@saluzi/saluzi-edu 0.2.64 → 0.2.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saluzi/saluzi-edu",
-  "version": "0.2.64",
+  "version": "0.2.65",
   "description": "Saluzi CLI - interactive AI coding assistant in the terminal",
   "license": "MIT",
   "type": "module",

package/packages/remote-control-server/src/__tests__/attach-code.test.ts

@@ -16,6 +16,7 @@ import {
   storeCreateEnvironment,
   storeIssueAttachCode,
   storeConsumeAttachCode,
+  storeAttachCodesSize,
 } from '../store'
 import { initDatabase, resetDbSingleton, getDb } from '../db/sqlite'
 import { issueSessionToken } from '../auth/session'
@@ -172,6 +173,17 @@ describe('attach codes', () => {
     expect(storeConsumeAttachCode(record.code)).toBeNull()
   })
 
+  test('unconsumed expired codes are swept on the next issue (memory hygiene)', () => {
+    expect(storeAttachCodesSize()).toBe(0)
+    // Expired immediately and never presented — consume() would never see it.
+    storeIssueAttachCode(sessionId, -1000)
+    expect(storeAttachCodesSize()).toBe(1)
+    // The next issue sweeps it instead of letting it accumulate forever.
+    const live = storeIssueAttachCode(sessionId)
+    expect(storeAttachCodesSize()).toBe(1)
+    expect(storeConsumeAttachCode(live.code)?.sessionId).toBe(sessionId)
+  })
+
   test('missing code or environment_id → 400', async () => {
     const res = await app.request('/v1/sessions/attach-code/exchange', {
       method: 'POST',

package/packages/remote-control-server/src/__tests__/attach-wait.test.ts

@@ -30,6 +30,7 @@ import { storeBindSession } from '../store'
  * - POST /v1/environments/bridge persists session_mode:'attach'.
  * - GET /v1/environments/:id/assignment returns the first open non-ACP
  *   session on the env (assigned:false until the Web UI binds one).
+ *   Gated on env ownership (admin bypasses; unowned envs stay open).
  * - GET /web/environments surfaces attach_waiting for waiting workers.
  */
 
@@ -124,6 +125,62 @@ describe('Session Attach wait mode', () => {
     expect(after ?? 0).toBeGreaterThan(stale.getTime())
   })
 
+  test('assignment: owned env + owner rct token → 200 (worker polls as itself)', async () => {
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'mac1',
+      ownerUserId: owner.id,
+      sessionMode: 'attach',
+    })
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { Authorization: rctAuth(owner.id) },
+    })
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ assigned: false })
+  })
+
+  test('assignment: owned env + stranger rct token → 403, heartbeat NOT refreshed', async () => {
+    // Assignment discloses the env's bound session AND is its liveness
+    // signal — neither may be driven by a third party.
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'mac1',
+      ownerUserId: owner.id,
+      sessionMode: 'attach',
+    })
+    const stale = new Date(Date.now() - 10 * 60 * 1000)
+    storeUpdateEnvironment(env.id, { lastPollAt: stale })
+
+    const stranger = createUser(db)
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { Authorization: rctAuth(stranger.id) },
+    })
+    expect(res.status).toBe(403)
+    const body = (await res.json()) as { error: { type: string } }
+    expect(body.error.type).toBe('forbidden')
+    // updatePollTime runs only AFTER the gate — a 403 must not keep a dead
+    // env looking alive.
+    expect(storeGetEnvironment(env.id)?.lastPollAt?.getTime()).toBe(
+      stale.getTime(),
+    )
+  })
+
+  test('assignment: unowned env (claim pending) + any auth → 200 assigned:false', async () => {
+    // Two-phase wait (claim → attach): while unowned there is nothing to
+    // disclose, so the poll stays open to any authenticated caller.
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'unclaimed',
+      sessionMode: 'attach',
+    })
+    const stranger = createUser(db)
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { Authorization: rctAuth(stranger.id) },
+    })
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ assigned: false })
+  })
+
   test('assignment: session bound to the env (web attach) → assigned with session id', async () => {
     const env = storeCreateEnvironment({
       secret: 'test-api-key',

package/packages/remote-control-server/src/__tests__/attach.test.ts

@@ -207,33 +207,62 @@ describe('POST /v1/sessions/:id/attach', () => {
     expect(body.idempotent).toBeUndefined()
   })
 
-  test('idempotent re-entry bypasses manage-rights check (doReconnect re-bind)', async () => {
-    // Wait-mode scenario: a team admin bound the session to the caller's env;
-    // the caller itself has no manage rights. The re-bind after env loss must
-    // still succeed via the same-env idempotent path.
+  test('idempotent re-entry bypasses manage-rights check for the env owner (doReconnect re-bind)', async () => {
+    // Wait-mode scenario: a team admin bound the session to the CLI worker's
+    // env; the worker itself has no manage rights on the session. The re-bind
+    // after env loss must still succeed via the same-env idempotent path —
+    // gated on env ownership (the worker owns its env), not session rights.
+    const world = seedWorld(db)
+    const cliOwner = createUser(db)
+    const cliEnv = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'cli-worker',
+      ownerUserId: cliOwner.id,
+    })
+    // The team-admin bind: the session is re-pointed to the CLI env with a
+    // live work item (bare admin API key performs the attach).
+    const first = await app.request(`/v1/sessions/${world.sessionId}/attach`, {
+      method: 'POST',
+      headers: { ...JSON_HDRS, ...ADMIN_KEY },
+      body: JSON.stringify({ environment_id: cliEnv.id }),
+    })
+    expect(first.status).toBe(200)
+    const { work_item_id } = (await first.json()) as { work_item_id: string }
+
+    // Re-entry as the CLI owner (no manage rights, owns the env) → 200 with
+    // the SAME work item.
+    const second = await app.request(`/v1/sessions/${world.sessionId}/attach`, {
+      method: 'POST',
+      headers: { ...JSON_HDRS, Authorization: rctAuth(cliOwner.id) },
+      body: JSON.stringify({ environment_id: cliEnv.id }),
+    })
+    expect(second.status).toBe(200)
+    const body = (await second.json()) as {
+      idempotent: boolean
+      work_item_id: string
+    }
+    expect(body.idempotent).toBe(true)
+    expect(body.work_item_id).toBe(work_item_id)
+  })
+
+  test('idempotent re-entry by a non-owner who knows session+env IDs → 403', async () => {
+    // The idempotent path echoes the work-item id; a random authenticated
+    // caller must not be able to probe bindings. Falls through to the full
+    // checks → manage-rights 403.
     const world = seedWorld(db)
-    const admin = createUser(db, 'admin')
-    // Attach once WITH rights (owner) so a work item exists on world.envId.
     const first = await app.request(`/v1/sessions/${world.sessionId}/attach`, {
       method: 'POST',
       headers: { ...JSON_HDRS, Authorization: rctAuth(world.owner.id) },
       body: JSON.stringify({ environment_id: world.envId }),
     })
     expect(first.status).toBe(200)
-    void admin
 
-    // Re-entry as the STRANGER (no manage rights) but same env → 200.
-    // Note: env ownership also matches the stranger? No — the env belongs to
-    // owner; but the idempotent check runs BEFORE both the access and env
-    // ownership checks, so the re-entry returns the existing binding.
     const second = await app.request(`/v1/sessions/${world.sessionId}/attach`, {
       method: 'POST',
       headers: { ...JSON_HDRS, Authorization: rctAuth(world.stranger.id) },
       body: JSON.stringify({ environment_id: world.envId }),
     })
-    expect(second.status).toBe(200)
-    const body = (await second.json()) as { idempotent: boolean }
-    expect(body.idempotent).toBe(true)
+    expect(second.status).toBe(403)
   })
 
   test("stranger's rct token → 403 (canManageSession, G9)", async () => {
@@ -411,6 +440,19 @@ describe('GET /v1/sessions/attachable', () => {
     const list = (await res.json()) as Array<{ id: string }>
     expect(list.some(s => s.id === world.sessionId)).toBe(true)
   })
+
+  test('admin API key + unresolvable X-Username → 403 (consistent with attach)', async () => {
+    // An explicit-but-unknown identity is a misconfiguration, not "see
+    // everything" — the listing must be exactly as strict as
+    // POST /:id/attach's ensureAttachAccess.
+    await seedWorld(db)
+    const res = await app.request('/v1/sessions/attachable', {
+      headers: { ...ADMIN_KEY, 'X-Username': 'no_such_user_xyz' },
+    })
+    expect(res.status).toBe(403)
+    const body = (await res.json()) as { error: { type: string } }
+    expect(body.error.type).toBe('forbidden')
+  })
 })
 
 describe('GET /v1/sessions/:id/events (bridge auth)', () => {
@@ -518,4 +560,21 @@ describe('storeRebindSessionEnvironment', () => {
     storeReset()
     expect(storeRebindSessionEnvironment('ses_missing', 'env_x')).toBe(false)
   })
+
+  test('rebinding to null clears the binding (dispatch-failure rollback)', () => {
+    const db = freshDb()
+    storeReset()
+    const world = seedWorld(db)
+    const web = createSession({
+      environment_id: null,
+      title: 'Web session',
+      source: 'web',
+    })
+    expect(storeRebindSessionEnvironment(web.id, world.envId)).toBe(true)
+    expect(storeRebindSessionEnvironment(web.id, null)).toBe(true)
+    const row = db
+      .query('SELECT environment_id FROM sessions WHERE id = $id')
+      .get({ $id: web.id }) as { environment_id: string | null }
+    expect(row.environment_id).toBeNull()
+  })
 })

package/packages/remote-control-server/src/auth/bridge-auth.ts

@@ -74,3 +74,47 @@ export function resolveUserIdUuid(
     .get({ $value: value }) as { id: string } | null
   return row?.id ?? null
 }
+
+/** Caller identity resolved for attach-family endpoints. */
+export type AttachCaller = {
+  /** Resolved users.id UUID — null for a bare admin API key. */
+  uuid: string | null
+  isApiAdmin: boolean
+  /** True when no identity at all was presented (bare admin API key). */
+  hasIdentity: boolean
+  /**
+   * True when the users-table lookup itself failed (DB unavailable). Routes
+   * must return 503 BEFORE treating uuid:null as an unresolvable identity —
+   * a DB outage must not masquerade as a 403.
+   */
+  dbUnavailable: boolean
+}
+
+/**
+ * Resolve the bridge caller identity for attach endpoints.
+ *
+ * bridgeAuth's userId may be a UUID (rct_* token), a username (in-memory
+ * token) or an arbitrary X-Username string (shared admin API key) — only
+ * users-table UUIDs can hold session management rights, so everything goes
+ * through resolveUserIdUuid (G9: the API layer must self-enforce
+ * canManageSession; the ingress WS accepting a global API key is not a
+ * boundary we may lean on).
+ */
+export function resolveAttachCaller(c: Context): AttachCaller {
+  const raw = c.get('userId') as string | undefined
+  const isApiAdmin = (c.get('isApiAdmin') as boolean | undefined) ?? false
+  if (!raw) {
+    return { uuid: null, isApiAdmin, hasIdentity: false, dbUnavailable: false }
+  }
+  try {
+    return {
+      uuid: resolveUserIdUuid(getDb(), raw),
+      isApiAdmin,
+      hasIdentity: true,
+      dbUnavailable: false,
+    }
+  } catch (err) {
+    console.error('[bridge] DB error resolving attach caller identity:', err)
+    return { uuid: null, isApiAdmin, hasIdentity: true, dbUnavailable: true }
+  }
+}

package/packages/remote-control-server/src/routes/v1/environments.ts

@@ -7,7 +7,11 @@ import {
   updatePollTime,
 } from '../../services/environment'
 import { acceptCliHeaders, apiKeyAuth } from '../../auth/middleware'
-import { bridgeAuth, resolveUserIdUuid } from '../../auth/bridge-auth'
+import {
+  bridgeAuth,
+  resolveAttachCaller,
+  resolveUserIdUuid,
+} from '../../auth/bridge-auth'
 import { getDb } from '../../db/sqlite'
 import { isSessionClosedStatus } from '../../services/session'
 import {
@@ -282,7 +286,8 @@ app.post('/bridge', acceptCliHeaders, bridgeAuth, async c => {
  *  waiting for the Web UI to bind a session (POST /v1/sessions/:id/attach).
  *  Returns the first open, non-ACP session on the environment, or
  *  assigned:false to keep waiting. Long-polling is unnecessary — the worker
- *  already runs a poll loop cadence for work items. */
+ *  already runs a poll loop cadence for work items.
+ *  Access: the env owner (the polling worker itself) or an admin. */
 app.get('/:id/assignment', acceptCliHeaders, bridgeAuth, async c => {
   const envId = c.req.param('id')!
   const env = storeGetEnvironment(envId)
@@ -292,6 +297,51 @@ app.get('/:id/assignment', acceptCliHeaders, bridgeAuth, async c => {
       404,
     )
   }
+
+  // Ownership gate: assignment discloses the env's bound session AND doubles
+  // as its liveness signal (updatePollTime below) — both are restricted to
+  // the env owner (the wait-mode worker polls under the same identity it
+  // registered with) and admins. Unowned envs (claim pending) stay open:
+  // nothing is bound yet, so there is nothing to disclose or keep alive.
+  const caller = resolveAttachCaller(c)
+  if (caller.dbUnavailable) {
+    return c.json(
+      {
+        error: {
+          type: 'database_unavailable',
+          message: 'Database unavailable',
+        },
+      },
+      503,
+    )
+  }
+  let ownerUserId: string | null = null
+  try {
+    ownerUserId = storeGetEnvironmentOwnership(envId)?.ownerUserId ?? null
+  } catch (err) {
+    console.error('[bridge] DB error during assignment ownership lookup:', err)
+    return c.json(
+      {
+        error: {
+          type: 'database_unavailable',
+          message: 'Database unavailable',
+        },
+      },
+      503,
+    )
+  }
+  if (ownerUserId && !caller.isApiAdmin && caller.uuid !== ownerUserId) {
+    return c.json(
+      {
+        error: {
+          type: 'forbidden',
+          message: 'Not allowed to poll this environment',
+        },
+      },
+      403,
+    )
+  }
+
   // The attach-wait worker has no work item in flight, so the work-poll
   // route never refreshes its heartbeat. This poll IS its liveness signal:
   // without touching lastPollAt the disconnect monitor flips the env to

package/packages/remote-control-server/src/routes/v1/sessions.ts

@@ -14,7 +14,11 @@ import { publishSessionEvent } from '../../services/transport'
 import { loadPersistedEvents } from '../../services/event-persistence'
 import { getEventBus } from '../../transport/event-bus'
 import { acceptCliHeaders, apiKeyAuth } from '../../auth/middleware'
-import { bridgeAuth, resolveUserIdUuid } from '../../auth/bridge-auth'
+import {
+  bridgeAuth,
+  resolveAttachCaller,
+  type AttachCaller,
+} from '../../auth/bridge-auth'
 import { getDb } from '../../db/sqlite'
 import {
   storeBindSession,
@@ -25,6 +29,7 @@ import {
   storeListSessions,
   storeListSessionsByEnvironment,
   storeRebindSessionEnvironment,
+  type SessionRecord,
 } from '../../store'
 
 const app = new Hono()
@@ -33,36 +38,17 @@ const app = new Hono()
 // Session Attach — bind an existing session to a CLI-registered environment
 // ---------------------------------------------------------------------------
 
-/** Caller identity resolved for attach endpoints. */
-type AttachCaller = {
-  /** Resolved users.id UUID — null for a bare admin API key. */
-  uuid: string | null
-  isApiAdmin: boolean
-  /** True when no identity at all was presented (bare admin API key). */
-  hasIdentity: boolean
-}
-
-/**
- * Resolve the bridge caller identity for attach endpoints.
- *
- * bridgeAuth's userId may be a UUID (rct_* token), a username (in-memory
- * token) or an arbitrary X-Username string (shared admin API key) — only
- * users-table UUIDs can hold session management rights, so everything goes
- * through resolveUserIdUuid (G9: the API layer must self-enforce
- * canManageSession; the ingress WS accepting a global API key is not a
- * boundary we may lean on).
- */
-function resolveAttachCaller(c: import('hono').Context): AttachCaller {
-  const raw = c.get('userId') as string | undefined
-  const isApiAdmin = (c.get('isApiAdmin') as boolean | undefined) ?? false
-  if (!raw) {
-    return { uuid: null, isApiAdmin, hasIdentity: false }
-  }
-  return {
-    uuid: resolveUserIdUuid(getDb(), raw),
-    isApiAdmin,
-    hasIdentity: true,
-  }
+/** 503 body shared by every attach-family route on a DB outage. */
+function dbUnavailable(c: import('hono').Context): Response {
+  return c.json(
+    {
+      error: {
+        type: 'database_unavailable',
+        message: 'Database unavailable',
+      },
+    },
+    503,
+  )
 }
 
 /**
@@ -150,15 +136,15 @@ function isSessionOccupied(
 }
 
 /** Shape returned by GET /attachable and consumed by the CLI picker. */
-function toAttachableEntry(session: ReturnType<typeof getSession>) {
+function toAttachableEntry(session: SessionRecord) {
   return {
-    id: session!.id,
-    title: session!.title,
-    status: session!.status,
-    source: session!.source,
-    environment_id: session!.environment_id ?? null,
-    updated_at: session!.updated_at,
-    busy: isSessionOccupied(session!.id, null),
+    id: session.id,
+    title: session.title,
+    status: session.status,
+    source: session.source,
+    environment_id: session.environmentId,
+    updated_at: session.updatedAt.getTime() / 1000,
+    busy: isSessionOccupied(session.id, null),
   }
 }
 
@@ -240,7 +226,14 @@ app.post('/', acceptCliHeaders, apiKeyAuth, async c => {
  *  worker. */
 app.get('/attachable', bridgeAuth, async c => {
   const caller = resolveAttachCaller(c)
-  if (caller.uuid === null && caller.hasIdentity && !caller.isApiAdmin) {
+  if (caller.dbUnavailable) {
+    return dbUnavailable(c)
+  }
+  // An explicit-but-unresolvable identity (e.g. admin API key +
+  // X-Username matching no user) is a misconfiguration, not "see
+  // everything": 403, mirroring POST /:id/attach's ensureAttachAccess —
+  // the listing previously was the laxer of the two.
+  if (caller.uuid === null && caller.hasIdentity) {
     return c.json(
       {
         error: {
@@ -258,16 +251,22 @@ app.get('/attachable', bridgeAuth, async c => {
     )
   }
 
-  const db = getDb()
-  const attachable = storeListSessions()
+  const uuid = caller.uuid
+  const open = storeListSessions()
     .filter(s => !isSessionClosedStatus(s.status))
     .filter(s => s.source !== 'acp')
-    .filter(
-      s => caller.uuid === null || canManageSession(s.id, caller.uuid, db),
-    )
-    .map(s => toAttachableEntry(getSession(s.id)))
+  // Bare admin API key (uuid null) sees all; an identity sees only what it
+  // can manage. getDb() is touched only when the filter actually runs.
+  let visible = open
+  if (uuid !== null) {
+    const db = getDb()
+    visible = open.filter(s => canManageSession(s.id, uuid, db))
+  }
 
-  return c.json(attachable, 200)
+  return c.json(
+    visible.map(s => toAttachableEntry(s)),
+    200,
+  )
 })
 
 /** POST /v1/sessions/:id/attach — Bind an existing session to a CLI
@@ -317,6 +316,9 @@ async function performAttach(
   },
 ): Promise<Response> {
   const { sessionId, envId, caller, skipAccessCheck } = opts
+  if (caller.dbUnavailable) {
+    return dbUnavailable(c)
+  }
   const session = getSession(sessionId)
   if (!session) {
     return c.json(
@@ -325,28 +327,49 @@ async function performAttach(
     )
   }
 
-  // Idempotent re-entry BEFORE authorization: a CLI retrying after a network
-  // blip re-presents the same session+env pair — returning the existing
-  // binding is not a new grant, so it must not depend on the caller still
-  // holding manage rights (e.g. a doReconnect re-bind where the bound
-  // session was assigned by a team admin, or an expired share). The check
-  // only matches an existing work item on the SAME environment — no state
-  // is created.
+  // Idempotent re-entry BEFORE session-manage authorization: a CLI retrying
+  // after a network blip re-presents the same session+env pair — returning
+  // the existing binding is not a new grant, so it must not depend on the
+  // caller still holding manage rights (e.g. a doReconnect re-bind where the
+  // bound session was assigned by a team admin, or an expired share). The
+  // check only matches an existing work item on the SAME environment — no
+  // state is created.
+  //
+  // Still gated on environment ownership (or admin): the CLI re-entering is
+  // the env's own worker, so ownership always holds for legitimate retries,
+  // while a random authenticated caller who merely knows session+env IDs
+  // must not be able to probe the binding (the response echoes the work
+  // item id). Non-owners fall through to the full checks below, which
+  // reject them.
   const activeItem = storeGetActiveWorkItemBySession(sessionId)
   if (activeItem && activeItem.environmentId === envId) {
-    log(
-      `[RCS] Attach idempotent re-entry: session=${sessionId} env=${envId} work=${activeItem.id}`,
-    )
-    return c.json(
-      {
-        status: 'attached',
-        session_id: sessionId,
-        work_item_id: activeItem.id,
-        rebind: false,
-        idempotent: true,
-      },
-      200,
-    )
+    let idempotentOwner = false
+    try {
+      const ownership = storeGetEnvironmentOwnership(envId)
+      idempotentOwner =
+        caller.isApiAdmin ||
+        (caller.uuid !== null && ownership?.ownerUserId === caller.uuid)
+    } catch (err) {
+      logError(
+        `[RCS] Ownership lookup failed during attach re-entry (session=${sessionId} env=${envId}): ${err}`,
+      )
+      return dbUnavailable(c)
+    }
+    if (idempotentOwner) {
+      log(
+        `[RCS] Attach idempotent re-entry: session=${sessionId} env=${envId} work=${activeItem.id}`,
+      )
+      return c.json(
+        {
+          status: 'attached',
+          session_id: sessionId,
+          work_item_id: activeItem.id,
+          rebind: false,
+          idempotent: true,
+        },
+        200,
+      )
+    }
   }
 
   // Authorization: identity-based attach requires manage rights (G9). The
@@ -482,9 +505,17 @@ async function performAttach(
     workItemId = await createWorkItem(envId, sessionId)
   } catch (err) {
     // Roll the rebind back so a failed dispatch doesn't leave the session
-    // pointing at an environment that never picked it up.
-    if (rebind && session.environment_id) {
-      storeRebindSessionEnvironment(sessionId, session.environment_id)
+    // pointing at an environment that never picked it up — including back to
+    // "no environment" when the session had none. A rollback failure must
+    // not mask the original dispatch error.
+    if (rebind) {
+      try {
+        storeRebindSessionEnvironment(sessionId, session.environment_id)
+      } catch (rollbackErr) {
+        logError(
+          `[RCS] Attach rollback failed for session ${sessionId}: ${rollbackErr}`,
+        )
+      }
     }
     return c.json(
       {
@@ -570,6 +601,9 @@ app.post('/attach-code/exchange', bridgeAuth, async c => {
  *  wrong layer (P0-1). */
 app.get('/:id/events', bridgeAuth, async c => {
   const caller = resolveAttachCaller(c)
+  if (caller.dbUnavailable) {
+    return dbUnavailable(c)
+  }
   const sessionId =
     resolveExistingSessionId(c.req.param('id')!) ?? c.req.param('id')!
   const session = getSession(sessionId)

package/packages/remote-control-server/src/store.ts

@@ -586,10 +586,13 @@ export function storeListSessionsByEnvironment(envId: string): SessionRecord[] {
  * storeUpdateSession's patch type intentionally excludes environment_id
  * because ownership-binding flows must never re-point a session as a side
  * effect. Attach is the one flow with an explicit re-bind contract.
+ *
+ * environmentId may be null — the rollback path (dispatch failure in
+ * performAttach) restores "no environment" when the session had none.
  */
 export function storeRebindSessionEnvironment(
   sessionId: string,
-  environmentId: string,
+  environmentId: string | null,
 ): boolean {
   const rec = sessions.get(sessionId)
   if (!rec) return false
@@ -1018,6 +1021,13 @@ export function storeIssueAttachCode(
   sessionId: string,
   ttlMs = 15 * 60 * 1000,
 ): AttachCodeRecord {
+  // Sweep expired codes: consume() only removes a code when it is actually
+  // presented, so unconsumed expired codes would otherwise accumulate for
+  // the process lifetime. Map deletion during iteration is safe.
+  const now = Date.now()
+  for (const [code, record] of attachCodes) {
+    if (record.expiresAt.getTime() <= now) attachCodes.delete(code)
+  }
   const code = `atc_${randomUUID().replace(/-/g, '')}`
   const record: AttachCodeRecord = {
     code,
@@ -1045,6 +1055,12 @@ export function storeResetAttachCodes() {
   attachCodes.clear()
 }
 
+/** Test helper — number of attach codes currently held (expired codes that
+ *  have not been swept yet still count). */
+export function storeAttachCodesSize(): number {
+  return attachCodes.size
+}
+
 // ---------- Reset (for tests) ----------
 
 export function storeReset() {