@saluzi/saluzi-edu 0.2.65 → 0.2.66

package/package.json

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

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

@@ -181,6 +181,60 @@ describe('Session Attach wait mode', () => {
     expect(await res.json()).toEqual({ assigned: false })
   })
 
+  test('assignment: disconnected env + authorized caller → reactivated, not 404', async () => {
+    // A wait-mode worker whose env the disconnect monitor flipped (laptop
+    // sleep during the 24h wait, pre-fix claim-wait, etc.) must recover on
+    // its next poll instead of dead-waiting on swallowed 404s — the CLI
+    // ignores assignment errors until its deadline.
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'mac1',
+      ownerUserId: owner.id,
+      sessionMode: 'attach',
+    })
+    storeUpdateEnvironment(env.id, { status: 'disconnected' })
+
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { ...ADMIN_KEY },
+    })
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ assigned: false })
+    expect(storeGetEnvironment(env.id)?.status).toBe('active')
+  })
+
+  test('assignment: disconnected env + stranger → 403, env NOT reactivated', async () => {
+    // Same invariant as the heartbeat test above: a 403 must not resurrect
+    // or keep alive an env the caller has no business touching.
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'mac1',
+      ownerUserId: owner.id,
+      sessionMode: 'attach',
+    })
+    storeUpdateEnvironment(env.id, { status: 'disconnected' })
+    const stranger = createUser(db)
+
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { Authorization: rctAuth(stranger.id) },
+    })
+    expect(res.status).toBe(403)
+    expect(storeGetEnvironment(env.id)?.status).toBe('disconnected')
+  })
+
+  test('assignment: deregistered env → 404 (terminal)', async () => {
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'mac1',
+      ownerUserId: owner.id,
+      sessionMode: 'attach',
+    })
+    storeUpdateEnvironment(env.id, { status: 'deregistered' })
+    const res = await app.request(`/v1/environments/${env.id}/assignment`, {
+      headers: { ...ADMIN_KEY },
+    })
+    expect(res.status).toBe(404)
+  })
+
   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

@@ -313,6 +313,43 @@ describe('POST /v1/sessions/:id/attach', () => {
     expect(body.error.type).toBe('environment_unowned')
   })
 
+  test('bare admin API key attaches to an unowned env (documented worker setup)', async () => {
+    // Self-hosted workers connect with SALUZI_BRIDGE_OAUTH_TOKEN=<RCS_API_KEYS>
+    // and no SALUZI_BRIDGE_USERNAME — the env they register is unowned until
+    // claimed, and the direct-attach path never prints a claim URL. A hard
+    // 409 here made `/rc --attach <id>` fail out of the box. Bare admin keys
+    // are trusted credentials (ensureAttachAccess already audited their
+    // session-manage bypass) — the bind is allowed.
+    const owner = createUser(db)
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'cli-worker',
+    })
+    const session = createSession({
+      environment_id: null,
+      title: 'Web session',
+      source: 'web',
+    })
+    storeBindSession(session.id, owner.id, 'user')
+
+    const res = await app.request(`/v1/sessions/${session.id}/attach`, {
+      method: 'POST',
+      headers: { ...JSON_HDRS, ...ADMIN_KEY },
+      body: JSON.stringify({ environment_id: env.id }),
+    })
+    expect(res.status).toBe(200)
+    const body = (await res.json()) as {
+      status: string
+      session_id: string
+      work_item_id: string
+      rebind: boolean
+    }
+    expect(body.status).toBe('attached')
+    expect(body.session_id).toBe(session.id)
+    expect(body.work_item_id).toMatch(/^work_/)
+    expect(body.rebind).toBe(true)
+  })
+
   test('archived session → 409 session_closed', async () => {
     const world = seedWorld(db)
     const { archiveSession } = await import('../services/session')

package/packages/remote-control-server/src/__tests__/low-priority-fixes.test.ts

@@ -10,8 +10,11 @@ import { Hono } from 'hono'
 import {
   storeReset,
   storeCreateSession,
+  storeCreateEnvironment,
   storeBindSession,
   storeListSessionsByOwnerUuid,
+  storeListSessionsByEnvironment,
+  storeGetActiveWorkItemBySession,
 } from '../store'
 import { initDatabase, resetDbSingleton } from '../db/sqlite'
 import { issueToken } from '../auth/token'
@@ -176,3 +179,95 @@ describe('M2: resolveOwnedWebSessionId removes redundant fallback', () => {
     expect(source).not.toMatch(/import\s*\{[^}]*storeIsSessionOwner[^}]*\}/)
   })
 })
+
+// =============================================================================
+// worker_at_capacity pre-validation: the repl-worker capacity check must run
+// BEFORE createSession. It used to run after, where the just-created session
+// (already bound to body.environment_id) always tripped it — every web session
+// creation on a repl worker env 409'd AND left a stray bound-but-never-
+// dispatched session behind on each retry.
+// =============================================================================
+describe('worker_at_capacity pre-validation (repl workers)', () => {
+  let app: Hono
+
+  beforeEach(() => {
+    freshDb()
+    storeReset()
+    app = createApp()
+  })
+
+  test('idle repl worker env → 200, session created AND work item dispatched', async () => {
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'cli-worker',
+      workerType: 'repl',
+    })
+    const res = await app.request('/web/sessions', {
+      method: 'POST',
+      headers: {
+        Authorization: userAuth('webuser'),
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ title: 'On Worker', environment_id: env.id }),
+    })
+    expect(res.status).toBe(200)
+    const body = (await res.json()) as { id: string; environment_id: string }
+    expect(body.environment_id).toBe(env.id)
+    // Pre-fix the 409 returned before createWorkItem — the CLI would poll a
+    // session that never received work.
+    const work = storeGetActiveWorkItemBySession(body.id)
+    expect(work).not.toBeNull()
+    expect(work?.environmentId).toBe(env.id)
+  })
+
+  test('repl env with an open session → 409 and NO stray session left behind', async () => {
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'cli-worker',
+      workerType: 'repl',
+    })
+    storeCreateSession({
+      environmentId: env.id,
+      title: 'Existing',
+      source: 'web',
+    })
+    const before = storeListSessionsByEnvironment(env.id).length
+
+    const res = await app.request('/web/sessions', {
+      method: 'POST',
+      headers: {
+        Authorization: userAuth('webuser'),
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ title: 'Overflow', environment_id: env.id }),
+    })
+    expect(res.status).toBe(409)
+    const body = (await res.json()) as { error: { type: string } }
+    expect(body.error.type).toBe('worker_at_capacity')
+    // Pre-fix the session record was created (and bound) before the 409.
+    expect(storeListSessionsByEnvironment(env.id).length).toBe(before)
+  })
+
+  test('non-repl (spawn) env skips the capacity check', async () => {
+    const env = storeCreateEnvironment({
+      secret: 'test-api-key',
+      machineName: 'spawn-worker',
+      workerType: 'claude_code',
+      maxSessions: 4,
+    })
+    storeCreateSession({
+      environmentId: env.id,
+      title: 'Existing',
+      source: 'web',
+    })
+    const res = await app.request('/web/sessions', {
+      method: 'POST',
+      headers: {
+        Authorization: userAuth('webuser'),
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ title: 'Second', environment_id: env.id }),
+    })
+    expect(res.status).toBe(200)
+  })
+})

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

@@ -10,6 +10,9 @@ import {
   storeCreateSession,
   storeCreateEnvironment,
   storeBindSession,
+  storeUpdateEnvironment,
+  storeGetEnvironment,
+  storeGetActiveWorkItemBySession,
 } from '../store'
 import {
   removeEventBus,
@@ -323,6 +326,72 @@ describe('V1 Session Routes', () => {
     expect(body.id).toMatch(/^session_/)
   })
 
+  test('POST /v1/sessions with environment_id refreshes env liveness (claim-wait retry loop)', async () => {
+    // An unowned env's claim-wait loop retries POST /v1/sessions every 5s
+    // (409 environment_unowned) for up to 24h — that retry IS the worker's
+    // only traffic. Without touching lastPollAt here the disconnect monitor
+    // flips the env after RCS_DISCONNECT_TIMEOUT, and when the claim finally
+    // lands the work item dispatch rejects the non-active env: a session
+    // that exists yet never receives work (the CLI polls 204s forever).
+    ensureUser('testuser')
+    const envRes = await app.request('/v1/environments/bridge', {
+      method: 'POST',
+      headers: {
+        ...AUTH_HEADERS,
+        'Content-Type': 'application/json',
+        'X-User-Id': 'testuser',
+      },
+      body: JSON.stringify({ machine_name: 'test' }),
+    })
+    const { environment_id } = await envRes.json()
+    // Age the heartbeat past the disconnect timeout, then simulate one
+    // claim-wait retry.
+    const stale = new Date(Date.now() - 10 * 60 * 1000)
+    storeUpdateEnvironment(environment_id, { lastPollAt: stale })
+    const before = storeGetEnvironment(environment_id)?.lastPollAt?.getTime()
+
+    const sessRes = await app.request('/v1/sessions', {
+      method: 'POST',
+      headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ environment_id }),
+    })
+    expect(sessRes.status).toBe(200)
+    const after = storeGetEnvironment(environment_id)?.lastPollAt?.getTime()
+    expect(after).not.toBe(before)
+    expect(after ?? 0).toBeGreaterThan(stale.getTime())
+  })
+
+  test('POST /v1/sessions reactivates a monitor-flipped env so the work item is created', async () => {
+    // Recovery path for envs already flipped to 'disconnected' (CLI waited
+    // out the timeout before these fixes, laptop sleep, etc.): the retry
+    // reactivates the env, so the session gets its work item instead of
+    // becoming a zombie the CLI polls forever.
+    ensureUser('testuser')
+    const envRes = await app.request('/v1/environments/bridge', {
+      method: 'POST',
+      headers: {
+        ...AUTH_HEADERS,
+        'Content-Type': 'application/json',
+        'X-User-Id': 'testuser',
+      },
+      body: JSON.stringify({ machine_name: 'test' }),
+    })
+    const { environment_id } = await envRes.json()
+    storeUpdateEnvironment(environment_id, { status: 'disconnected' })
+
+    const sessRes = await app.request('/v1/sessions', {
+      method: 'POST',
+      headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ environment_id }),
+    })
+    expect(sessRes.status).toBe(200)
+    const body = await sessRes.json()
+    expect(storeGetEnvironment(environment_id)?.status).toBe('active')
+    const work = storeGetActiveWorkItemBySession(body.id)
+    expect(work).not.toBeNull()
+    expect(work?.environmentId).toBe(environment_id)
+  })
+
   test('POST /v1/sessions with events — publishes initial events', async () => {
     const sessRes = await app.request('/v1/sessions', {
       method: 'POST',

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

@@ -4,7 +4,7 @@ import {
   registerEnvironment,
   deregisterEnvironment,
   reconnectEnvironment,
-  updatePollTime,
+  touchEnvironmentActivity,
 } from '../../services/environment'
 import { acceptCliHeaders, apiKeyAuth } from '../../auth/middleware'
 import {
@@ -291,7 +291,12 @@ app.post('/bridge', acceptCliHeaders, bridgeAuth, async c => {
 app.get('/:id/assignment', acceptCliHeaders, bridgeAuth, async c => {
   const envId = c.req.param('id')!
   const env = storeGetEnvironment(envId)
-  if (!env || env.status !== 'active') {
+  // 'disconnected' is NOT a 404 here: the ownership gate below authorizes the
+  // caller first, then touchEnvironmentActivity reactivates the env — a live
+  // wait-mode worker polling a monitor-flipped env recovers instead of
+  // dead-waiting on swallowed 404s for its 24h deadline. Deregistered is
+  // terminal.
+  if (!env || env.status === 'deregistered') {
     return c.json(
       { error: { type: 'not_found', message: 'Environment not found' } },
       404,
@@ -299,10 +304,11 @@ app.get('/:id/assignment', acceptCliHeaders, bridgeAuth, async c => {
   }
 
   // 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.
+  // as its liveness signal (touchEnvironmentActivity 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(
@@ -345,9 +351,11 @@ app.get('/:id/assignment', acceptCliHeaders, bridgeAuth, async c => {
   // 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
-  // disconnected after the idle timeout, assignment starts 404ing, and the
-  // CLI silently spins until its 24h deadline (P0-2).
-  updatePollTime(envId)
+  // disconnected after the idle timeout and the CLI silently spins until its
+  // 24h deadline (P0-2). touchEnvironmentActivity also reactivates an env the
+  // monitor already flipped (runs only after the gate — a 403 must not keep
+  // a dead env looking alive).
+  touchEnvironmentActivity(envId)
   const assigned = storeListSessionsByEnvironment(envId)
     .filter(s => !isSessionClosedStatus(s.status))
     .filter(s => s.source !== 'acp')

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

@@ -6,14 +6,14 @@ import {
   heartbeatWork,
 } from '../../services/work-dispatch'
 import { apiKeyAuth, acceptCliHeaders } from '../../auth/middleware'
-import { updatePollTime } from '../../services/environment'
+import { touchEnvironmentActivity } from '../../services/environment'
 
 const app = new Hono()
 
 /** GET /v1/environments/:id/work/poll — Long-poll for work */
 app.get('/:id/work/poll', acceptCliHeaders, apiKeyAuth, async c => {
   const envId = c.req.param('id')!
-  updatePollTime(envId)
+  touchEnvironmentActivity(envId)
   const result = await pollWork(envId)
   if (!result) {
     // Return 204 No Content so the client's axios parses it as null

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

@@ -13,6 +13,7 @@ import { createWorkItem } from '../../services/work-dispatch'
 import { publishSessionEvent } from '../../services/transport'
 import { loadPersistedEvents } from '../../services/event-persistence'
 import { getEventBus } from '../../transport/event-bus'
+import { touchEnvironmentActivity } from '../../services/environment'
 import { acceptCliHeaders, apiKeyAuth } from '../../auth/middleware'
 import {
   bridgeAuth,
@@ -157,6 +158,19 @@ app.post('/', acceptCliHeaders, apiKeyAuth, async c => {
   const body = await c.req.json()
   const username = c.get('userId')
 
+  // Worker liveness: this route is the claim-wait loop's only traffic (an
+  // unowned env retries POST /v1/sessions every 5s until the claim URL is
+  // opened, up to 24h). Without touching the env here the disconnect monitor
+  // flips it to 'disconnected' after RCS_DISCONNECT_TIMEOUT, and when the
+  // claim finally lands the session is created but createWorkItem rejects
+  // the non-active env — a session that exists yet never receives work, so
+  // the CLI polls 204s forever and never connects. Touch BEFORE the unowned
+  // 409 so the retry loop itself keeps the env alive; touchEnvironmentActivity
+  // also reactivates an env the monitor already flipped.
+  if (typeof body.environment_id === 'string' && body.environment_id) {
+    touchEnvironmentActivity(body.environment_id)
+  }
+
   // Resolve env ownership to bind session_owners.
   let envOwnerUserId: string | null = null
   let envTeamId: string | null = null
@@ -439,18 +453,34 @@ async function performAttach(
   // owns (the env it just registered). Admin may attach on behalf.
   const ownership = storeGetEnvironmentOwnership(envId)
   if (!ownership?.ownerUserId) {
-    return c.json(
-      {
-        error: {
-          type: 'environment_unowned',
-          message:
-            'Environment has no owner yet; claim it via the printed URL before attaching sessions',
+    // The documented self-hosted worker setup authenticates with a bare
+    // RCS_API_KEYS admin key (SALUZI_BRIDGE_OAUTH_TOKEN, no
+    // SALUZI_BRIDGE_USERNAME) — its env is unowned until claimed, so a hard
+    // 409 here made `/rc --attach <id>` fail out of the box with a claim URL
+    // the direct-attach path never prints. Bare admin keys are trusted
+    // credentials (ensureAttachAccess already audited their session-manage
+    // bypass) — allow the bind. Identity callers still get the claim-flow
+    // guidance (the wait-mode CLI prints the URL).
+    if (!caller.isApiAdmin || caller.hasIdentity) {
+      return c.json(
+        {
+          error: {
+            type: 'environment_unowned',
+            message:
+              'Environment has no owner yet; claim it via the printed URL before attaching sessions',
+          },
         },
-      },
-      409,
+        409,
+      )
+    }
+    log(
+      `[audit] Bare admin API key attached session ${sessionId} to unowned env ${envId}`,
     )
   }
-  if (!caller.isApiAdmin && ownership.ownerUserId !== caller.uuid) {
+  // Optional chain: the bare-admin fallthrough above leaves ownership
+  // possibly-null/unowned here — but isApiAdmin is true on that path, so the
+  // short-circuit keeps the semantics identical.
+  if (!caller.isApiAdmin && ownership?.ownerUserId !== caller.uuid) {
     return c.json(
       {
         error: {

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

@@ -96,6 +96,31 @@ app.post('/sessions', sessionAuth, async c => {
       const session = getSession(sessionId)
       return c.json(toWebSessionResponse(session!), 200)
     }
+
+    // In-process (replBridge) workers register with workerType='repl' and
+    // maxSessions=1 — they can only serve one session at a time. Reject
+    // multi-session creation with a helpful error guiding the user to
+    // `slz rc` (spawn mode). MUST run before createSession: the new session
+    // is created WITH body.environment_id, so checking after would always
+    // see the just-created session and 409 every request (leaving a stray
+    // bound-but-never-dispatched session behind on each retry).
+    if (env?.workerType === 'repl') {
+      const existing = storeListSessionsByEnvironment(env.id).filter(
+        s => !isSessionClosedStatus(s.status),
+      )
+      if (existing.length > 0) {
+        return c.json(
+          {
+            error: {
+              type: 'worker_at_capacity',
+              message:
+                '该 worker 为 in-process 模式（slz 默认），只支持单会话。请用 `slz rc` 启动 spawn 模式 worker 支持多会话。',
+            },
+          },
+          409,
+        )
+      }
+    }
   }
 
   const teamId = typeof body.team_id === 'string' ? body.team_id : null
@@ -120,28 +145,6 @@ app.post('/sessions', sessionAuth, async c => {
 
   // Dispatch work to environment if specified
   if (body.environment_id) {
-    // In-process (replBridge) workers register with workerType='repl' and
-    // maxSessions=1 — they can only serve one session at a time. Reject
-    // multi-session creation with a helpful error guiding the user to
-    // `slz rc` (spawn mode).
-    const env = storeGetEnvironment(body.environment_id)
-    if (env?.workerType === 'repl') {
-      const existing = storeListSessionsByEnvironment(env.id).filter(
-        s => !isSessionClosedStatus(s.status),
-      )
-      if (existing.length > 0) {
-        return c.json(
-          {
-            error: {
-              type: 'worker_at_capacity',
-              message:
-                '该 worker 为 in-process 模式（slz 默认），只支持单会话。请用 `slz rc` 启动 spawn 模式 worker 支持多会话。',
-            },
-          },
-          409,
-        )
-      }
-    }
     try {
       const spawnMode =
         body.spawn_mode === 'worktree' || body.spawn_mode === 'same-dir'

package/packages/remote-control-server/src/services/environment.ts

@@ -277,6 +277,31 @@ export function updatePollTime(envId: string) {
   storeUpdateEnvironment(envId, { lastPollAt: new Date() })
 }
 
+/**
+ * Worker-traffic liveness signal: refresh lastPollAt and, when the disconnect
+ * monitor had flipped the env to 'disconnected', reactivate it.
+ *
+ * The flip is based on a stale heartbeat — a worker actively hitting the env
+ * (work poll, assignment poll, session-creation retry during claim wait)
+ * proves it is alive. Without reactivation the CLI polls a zombie env
+ * forever: the work-poll route never 404s, so the client's env-lost recovery
+ * never fires, and any session created on the flipped env gets no work item
+ * (createWorkItem rejects non-active envs) — a session that exists but can
+ * never connect. 'deregistered' is terminal and stays dead.
+ */
+export function touchEnvironmentActivity(envId: string) {
+  const env = storeGetEnvironment(envId)
+  if (!env) return
+  if (env.status === 'disconnected') {
+    storeUpdateEnvironment(envId, { status: 'active', lastPollAt: new Date() })
+    log(
+      `[RCS] Environment ${envId} reactivated by worker traffic (was disconnected)`,
+    )
+  } else if (env.status === 'active') {
+    storeUpdateEnvironment(envId, { lastPollAt: new Date() })
+  }
+}
+
 export function listActiveEnvironments() {
   return storeListActiveEnvironments()
 }