#15321 Record that cloud_vm_sessions.attachment_count is cumulative

Problem

cloud_vm_sessions.attachment_count reads like the number of clients attached to a session right now. It is not. upsertVmSession inserts it at 1 and then only ever adds to it:

attachmentCount: sql`${cloudVmSessions.attachmentCount} + ${input.attachmentCount ?? 1}`,

Nothing decrements on detach, so the value never returns to zero. It is a lifetime attach counter.

The value is published verbatim as attachmentCount by GET /api/vm/[id]/sessions and decoded straight into VMCloudSession.attachmentCount on the app side. Nothing renders it today, so there is no user-visible bug to fix. The risk is the next reader: a Cloud sidebar or machine list that shows "attachments" would report a machine as having twelve people on it after one person attached twelve times, and that mistake would look correct in review because the field name says what the renderer assumed.

Change

Comments at the three places the value is defined, passed and published, saying it is cumulative and must not be presented as a live viewer count. No behavior change, no schema change, no migration.

Verification

Comments only, so there is nothing to execute that could change. Disclosing what I did not run: web/ has no installed dependencies in this checkout, so I did not run bun x tsc --noEmit or bun run lint:complexity locally; CI covers both, and a comment cannot affect either.

I also did not add a test locking the cumulative semantics. The nearest coverage is in web/tests/vm-workflows.test.ts, which asserts attachmentCount: 1 after a single attach and so would still pass if the + became a plain assignment. A lock test would need a second attach against the DB-backed harness, and there is no local Postgres here to get a red-then-green result from. Worth a follow-up by someone who can run that suite locally.

Changelog

none

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Documents that cloud_vm_sessions.attachment_count is a lifetime attach counter, not a live client count. upsertVmSession inserts it at 1 and only ever adds to it, and there is no detach writer in web/, so the value never returns to zero.

Adds comments at the four places the value is defined, passed, and published (including the Swift socket re-export), clarifying that the insert branch stores the value verbatim while the conflict branch adds to it, and warning readers not to render it as a live viewer count. No behavior change.

Summary by CodeRabbit

• Documentation
  • Clarified that the session attachment count tracks cumulative attachments, not currently connected clients, and should be read alongside the last attachment time.
  • Documented that each session update adds to the running count, defaulting to one attachment.