switchroom 0.14.90 → 0.14.92

package/telegram-plugin/gateway/cron-session.ts

@@ -0,0 +1,45 @@
+/**
+ * Cheap-cron session identity — docs/rfcs/cheap-cron-sessions.md §3.3.
+ *
+ * Rather than rekey the gateway's hardened single-bridge machinery
+ * (agentIndex / pendingInboundBuffer / handleRegister, each carrying
+ * subtle race fixes), a Tier-1 cron fire is routed to a SECOND bridge
+ * that registers under a DERIVED identity `<agent>-cron`. To the IPC
+ * layer it is "just another agent", so routing, buffering, disconnect,
+ * and heartbeat all work unchanged. The gateway gates its SINGLETON
+ * status machinery (shadow bridge-state, boot card, currentTurn /
+ * progress card / silence-poke) off the cron identity — which IS the
+ * §2.4 "cron session is status-silent" requirement, so it is one change,
+ * not two.
+ *
+ * The cron session's bridge sets SWITCHROOM_AGENT_NAME=`<agent>-cron`;
+ * the scheduler emits `meta.session='cron'` and the gateway derives the
+ * target via `cronIdentity()`. Pure string fns — pinned in cron-session.test.ts.
+ */
+
+/** Suffix that distinguishes a cron-session bridge from the main agent bridge. */
+export const CRON_IDENTITY_SUFFIX = "-cron";
+
+/** Derive the cron-session bridge identity for an agent. */
+export function cronIdentity(agent: string): string {
+  return `${agent}${CRON_IDENTITY_SUFFIX}`;
+}
+
+/** True iff `name` is a cron-session bridge identity (not a main agent bridge). */
+export function isCronIdentity(name: string | null | undefined): boolean {
+  return typeof name === "string" && name.endsWith(CRON_IDENTITY_SUFFIX);
+}
+
+/** The real agent name behind a (possibly cron) identity. */
+export function baseAgent(name: string): string {
+  return isCronIdentity(name) ? name.slice(0, -CRON_IDENTITY_SUFFIX.length) : name;
+}
+
+/**
+ * Resolve the IPC routing target for an inject_inbound. When the fire
+ * carries `meta.session='cron'` it goes to the derived cron bridge; every
+ * other fire (and all of today's callers) goes to the agent unchanged.
+ */
+export function resolveInjectTarget(agentName: string, meta: Record<string, string> | undefined): string {
+  return meta?.session === "cron" ? cronIdentity(agentName) : agentName;
+}

package/telegram-plugin/gateway/gateway.ts

@@ -287,6 +287,7 @@ import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
+import { isCronIdentity, resolveInjectTarget } from './cron-session.js'
 import {
   ObligationLedger,
   buildObligationRepresentInbound,
@@ -471,6 +472,10 @@ import {
 } from './resume-inbound-builder.js'
 import { applySubagentsSchema, getSubagentByJsonlId } from '../registry/subagents-schema.js'
 import { resolveWorkerFeedDispatch, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
+import {
+  resolveSubagentStatusSurface,
+  isOrphanSubagentStatusEnabled,
+} from './subagent-status-surface.js'
 import { formatIdleFooter } from '../idle-footer.js'
 import { resolveCallingSubagent } from './resolve-calling-subagent.js'
 
@@ -5470,6 +5475,19 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientRegistered(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge registered — agent=${client.agentName}\n`)
+    // Cheap-cron (§2.4/§3.3): a `<agent>-cron` bridge is the Tier-1 cheap
+    // session. It is STATUS-SILENT — it must NOT drive the gateway's
+    // singleton machinery (shadow bridge-state, warmup, boot card, which all
+    // track the MAIN agent's liveness). Drain any buffered cron fire to it
+    // (so a fire that triggered a lazy spawn lands), then return early.
+    if (isCronIdentity(client.agentName)) {
+      client.send({ type: 'status', status: 'agent_connected' })
+      const pending = pendingInboundBuffer.drain(client.agentName ?? '')
+      for (const m of pending) {
+        try { client.send(m) } catch { /* cron fire drop — best-effort, like today's cron */ }
+      }
+      return
+    }
     // Phase 2b shadow: ONLY emit bridgeUp for the REAL bridge sidecar
     // (with an agent name). Anonymous IPC clients (recall.py, mcp
     // handshakes, etc.) connect briefly without a name and would
@@ -5648,6 +5666,17 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onClientDisconnected(client: IpcClient) {
+    // Cheap-cron §2.4: a `<agent>-cron` bridge is the status-silent cron
+    // session. Its disconnect (e.g. B3 lazy idle-teardown) must NOT touch
+    // the MAIN agent's singleton state — emitting bridgeDown (the shadow
+    // state is unkeyed) or flushOnAgentDisconnect (flushes the main agent's
+    // active reactions / disposes its progress driver mid-turn) would be the
+    // "premature 👍" bug for the main session. Symmetric to the cron gate in
+    // onClientRegistered / onSessionEvent / onPtyPartial.
+    if (isCronIdentity(client.agentName)) {
+      process.stderr.write(`telegram gateway: cron-session bridge disconnected — agent=${client.agentName}\n`)
+      return
+    }
     // ONLY log "bridge disconnected" + emit bridgeDown for the REAL
     // bridge sidecar (matching the bridgeUp gate above). Anonymous IPC
     // clients — e.g. recall.py's one-shot legacy update_placeholder
@@ -5718,7 +5747,13 @@ const ipcServer: IpcServer = createIpcServer({
     }
   },
 
-  onSessionEvent(_client: IpcClient, msg: SessionEventForward) {
+  onSessionEvent(client: IpcClient, msg: SessionEventForward) {
+    // Cheap-cron §2.4: the cron session is status-silent — its session
+    // events must not drive the main agent's progress card, transcript
+    // tail, currentTurn, or silence-poke. Its reply still flows (onToolCall
+    // is not gated). currentTurn was never set for a cron fire (onInjectInbound
+    // skips markClaudeBusy), so the card machinery has nothing to attach to.
+    if (isCronIdentity(client.agentName)) return
     // Track the session-tail's attached file for the proactive-
     // compaction occupancy read (see maybeProactiveCompact).
     if (msg.activeFile) lastSessionActiveFile = msg.activeFile
@@ -5950,7 +5985,10 @@ const ipcServer: IpcServer = createIpcServer({
    * `handlePtyPartial` does its own buffering for the
    * partial-before-enqueue race.
    */
-  onPtyPartial(_client: IpcClient, msg: PtyPartialForward) {
+  onPtyPartial(client: IpcClient, msg: PtyPartialForward) {
+    // Cheap-cron §2.4: cron session is status-silent — no visible reply
+    // stream from its PTY tail (it would edit a card the main session owns).
+    if (isCronIdentity(client.agentName)) return
     handlePtyPartial(msg.text)
   },
 
@@ -6287,16 +6325,28 @@ const ipcServer: IpcServer = createIpcServer({
     const source = typeof msg.inbound.meta?.source === 'string'
       ? msg.inbound.meta.source
       : 'unknown'
-    const delivered = ipcServer.sendToAgent(msg.agentName, msg.inbound)
-    if (delivered) markClaudeBusyForInbound(msg.inbound)
+    // Cheap-cron (docs/rfcs/cheap-cron-sessions.md §3.3): a Tier-1 fire
+    // carries meta.session='cron' → route to the derived `<agent>-cron`
+    // bridge (a 2nd interactive Sonnet session in the same container).
+    // Every other fire (and all of today's callers) routes to the agent
+    // unchanged. Route+buffer share the same target so a fire that lands
+    // mid cron-session-spawn buffers under the cron identity and drains to
+    // it on register.
+    const target = resolveInjectTarget(msg.agentName, msg.inbound.meta)
+    const toCron = target !== msg.agentName
+    const delivered = ipcServer.sendToAgent(target, msg.inbound)
+    // Status-silent (§2.4): a cron fire must NOT set the MAIN agent's
+    // currentTurn (progress card / silence-poke). The cron session is
+    // fire-and-forget; its reply is its only Telegram surface.
+    if (delivered && !toCron) markClaudeBusyForInbound(msg.inbound)
     process.stderr.write(
-      `telegram gateway: inject_inbound agent=${msg.agentName} source=${source} prompt_key=${promptKey} delivered=${delivered}\n`,
+      `telegram gateway: inject_inbound agent=${msg.agentName} target=${target} source=${source} prompt_key=${promptKey} delivered=${delivered}\n`,
     )
     // #1150: same buffer-on-failure pattern as vault_grant_approved.
     // Cron fires use this path too — if a cron-driven wake-up lands
     // mid bridge-reconnect, buffer it for the next register.
     if (!delivered) {
-      pendingInboundBuffer.push(msg.agentName, msg.inbound)
+      pendingInboundBuffer.push(target, msg.inbound)
     }
   },
 
@@ -20410,6 +20460,11 @@ void (async () => {
             // compose draft, so no answer-stream contention). The kill-switch
             // disables only the nesting; the parent's own feed is unaffected.
             const foregroundNestingEnabled = process.env.SWITCHROOM_FOREGROUND_SUBAGENT_NESTING !== '0'
+            // Orphaned-foreground status (2026-06-09): a FOREGROUND sub-agent
+            // with no live parent turn to nest into (dispatched outside a turn,
+            // or the turn ended while it kept running — extended autonomous
+            // work) is surfaced via the worker feed instead of vanishing.
+            const orphanStatusEnabled = isOrphanSubagentStatusEnabled(process.env.SWITCHROOM_ORPHAN_SUBAGENT_STATUS)
             const workerActivityFeed = createWorkerActivityFeed({
               bot: {
                 sendMessage: async (cid, text, sendOpts) => {
@@ -20609,6 +20664,29 @@ void (async () => {
                         }
                       }
                     }
+                    return
+                  }
+                  // Not nested → an orphaned foreground sub-agent that was
+                  // surfaced via the worker feed (no live turn to nest into):
+                  // finalize its message (no-op if none was posted). A
+                  // foreground result returns inline as the Task tool result, so
+                  // there is no handback to deliver — return after.
+                  if (
+                    resolveSubagentStatusSurface({
+                      isBackground: false,
+                      liveTurnPresent: false,
+                      workerFeedEnabled,
+                      orphanStatusEnabled,
+                    }) === 'worker-feed'
+                  ) {
+                    void workerActivityFeed.finish(agentId, {
+                      description: dispatch.feedDescription,
+                      lastTool: null,
+                      toolCount,
+                      latestSummary: resultText,
+                      elapsedMs: durationMs,
+                      state: outcome === 'failed' ? 'failed' : 'done',
+                    })
                   }
                   return
                 }
@@ -20738,8 +20816,39 @@ void (async () => {
                   // activity draft rather than a separate worker message. Pure
                   // jsonl-tail → render (no model call), inside the
                   // subscription-honest boundary.
+                  //
+                  // But a foreground sub-agent with NO live turn to nest into
+                  // (dispatched outside a turn, or the turn ended while it kept
+                  // running — extended autonomous work) has nowhere to nest, and
+                  // pre-fix it silently returned here → invisible. Route through
+                  // the proven decision: an orphaned foreground sub-agent goes to
+                  // the worker feed (owner-DM fallback), not into the void.
+                  const surface = resolveSubagentStatusSurface({
+                    isBackground: false,
+                    liveTurnPresent: currentTurn != null,
+                    workerFeedEnabled,
+                    orphanStatusEnabled,
+                  })
+                  if (surface === 'worker-feed') {
+                    const origin = resolveSubagentOriginChat(agentId)
+                    void workerActivityFeed.update(
+                      agentId,
+                      origin?.chatId || fleetChatId || (loadAccess().allowFrom[0] ?? ''),
+                      {
+                        description: dispatch.feedDescription,
+                        lastTool,
+                        toolCount,
+                        latestSummary,
+                        elapsedMs,
+                        state: 'running',
+                      },
+                      origin?.threadId,
+                    )
+                    return
+                  }
+                  if (surface !== 'nest') return // 'skip' — orphan-status off
                   const turn = currentTurn
-                  if (turn == null) return
+                  if (turn == null) return // defensive: 'nest' implies a live turn
                   // Render regardless of `replyCalled` — a foreground Task
                   // blocks the parent, so any reply seen while it runs is an
                   // interim ack, never the final answer. Gating on replyCalled

package/telegram-plugin/gateway/subagent-status-surface.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest'
+import {
+  resolveSubagentStatusSurface,
+  isOrphanSubagentStatusEnabled,
+  type SubagentStatusSurface,
+  type SubagentStatusSurfaceInput,
+} from './subagent-status-surface.js'
+
+// ── Human-readable map ──────────────────────────────────────────────────────
+describe('resolveSubagentStatusSurface', () => {
+  const base: SubagentStatusSurfaceInput = {
+    isBackground: false,
+    liveTurnPresent: true,
+    workerFeedEnabled: true,
+    orphanStatusEnabled: true,
+  }
+  it('foreground + live turn → nest (unchanged default)', () => {
+    expect(resolveSubagentStatusSurface(base)).toBe('nest')
+  })
+  it('THE fix: orphaned foreground (no live turn) → worker-feed', () => {
+    expect(resolveSubagentStatusSurface({ ...base, liveTurnPresent: false })).toBe('worker-feed')
+  })
+  it('kill switch: orphaned foreground with orphanStatus OFF → skip (pre-fix invisible)', () => {
+    expect(
+      resolveSubagentStatusSurface({ ...base, liveTurnPresent: false, orphanStatusEnabled: false }),
+    ).toBe('skip')
+  })
+  it('orphaned foreground but feed OFF → skip (nothing to surface through)', () => {
+    expect(
+      resolveSubagentStatusSurface({ ...base, liveTurnPresent: false, workerFeedEnabled: false }),
+    ).toBe('skip')
+  })
+  it('background + feed on → worker-feed', () => {
+    expect(resolveSubagentStatusSurface({ ...base, isBackground: true, liveTurnPresent: false })).toBe('worker-feed')
+  })
+  it('background + feed off → legacy-relay', () => {
+    expect(
+      resolveSubagentStatusSurface({ ...base, isBackground: true, workerFeedEnabled: false }),
+    ).toBe('legacy-relay')
+  })
+})
+
+describe('isOrphanSubagentStatusEnabled — default ON, =0 kill switch', () => {
+  it('undefined / "1" / "" → on; "0" → off', () => {
+    expect(isOrphanSubagentStatusEnabled(undefined)).toBe(true)
+    expect(isOrphanSubagentStatusEnabled('1')).toBe(true)
+    expect(isOrphanSubagentStatusEnabled('')).toBe(true)
+    expect(isOrphanSubagentStatusEnabled('0')).toBe(false)
+  })
+})
+
+// ── TOTAL-ENUMERATION DETERMINISM PROOF ─────────────────────────────────────
+// 4 booleans = 16 reachable inputs. Enumerate all, assert totality, determinism,
+// the documented table (independent spec), and the load-bearing invariants.
+// (operator standard feedback_prove_finite_fsm_not_sample.)
+function allInputs(): SubagentStatusSurfaceInput[] {
+  const rows: SubagentStatusSurfaceInput[] = []
+  for (const isBackground of [false, true])
+    for (const liveTurnPresent of [false, true])
+      for (const workerFeedEnabled of [false, true])
+        for (const orphanStatusEnabled of [false, true])
+          rows.push({ isBackground, liveTurnPresent, workerFeedEnabled, orphanStatusEnabled })
+  return rows
+}
+
+// Independent spec encoding (kept separate from the impl).
+function spec(i: SubagentStatusSurfaceInput): SubagentStatusSurface {
+  if (i.isBackground) return i.workerFeedEnabled ? 'worker-feed' : 'legacy-relay'
+  if (i.liveTurnPresent) return 'nest'
+  if (!i.orphanStatusEnabled) return 'skip'
+  return i.workerFeedEnabled ? 'worker-feed' : 'skip'
+}
+
+describe('resolveSubagentStatusSurface — total enumeration (16 inputs)', () => {
+  const ROWS = allInputs()
+
+  it('exactly 16 reachable inputs (2^4)', () => {
+    expect(ROWS.length).toBe(16)
+  })
+  it('TOTAL + DETERMINISTIC: every input returns one of the four surfaces, idempotently', () => {
+    const surfaces = new Set<SubagentStatusSurface>(['nest', 'worker-feed', 'legacy-relay', 'skip'])
+    for (const i of ROWS) {
+      const a = resolveSubagentStatusSurface(i)
+      expect(surfaces.has(a)).toBe(true)
+      expect(resolveSubagentStatusSurface({ ...i })).toBe(a)
+    }
+  })
+  it('PRECEDENCE: matches the documented spec on all 16 inputs', () => {
+    for (const i of ROWS) expect(resolveSubagentStatusSurface(i)).toBe(spec(i))
+  })
+
+  it('INV-ORPHAN-VISIBLE: an orphaned foreground sub-agent is NEVER skip when orphanStatus + feed are on', () => {
+    for (const i of ROWS) {
+      if (!i.isBackground && !i.liveTurnPresent && i.orphanStatusEnabled && i.workerFeedEnabled) {
+        expect(resolveSubagentStatusSurface(i)).toBe('worker-feed')
+      }
+    }
+  })
+  it('INV-KILL-SWITCH: orphanStatus OFF ⇒ an orphaned foreground sub-agent is exactly the pre-fix behaviour (skip)', () => {
+    for (const i of ROWS) {
+      if (!i.isBackground && !i.liveTurnPresent && !i.orphanStatusEnabled) {
+        expect(resolveSubagentStatusSurface(i)).toBe('skip')
+      }
+    }
+  })
+  it('INV-NEST-UNCHANGED: a foreground sub-agent with a live turn is ALWAYS nest, independent of the other flags', () => {
+    for (const i of ROWS) {
+      if (!i.isBackground && i.liveTurnPresent) expect(resolveSubagentStatusSurface(i)).toBe('nest')
+    }
+  })
+  it('INV-BACKGROUND-UNCHANGED: background routing depends ONLY on the feed flag, never on liveTurn/orphanStatus', () => {
+    for (const i of ROWS) {
+      if (i.isBackground) {
+        expect(resolveSubagentStatusSurface(i)).toBe(i.workerFeedEnabled ? 'worker-feed' : 'legacy-relay')
+      }
+    }
+  })
+})

package/telegram-plugin/gateway/subagent-status-surface.ts

@@ -0,0 +1,69 @@
+/**
+ * Where does a sub-agent's live status go?
+ *
+ * A sub-agent's progress is surfaced on one of four "surfaces". This pure
+ * decision picks which, so the routing is provable by total enumeration rather
+ * than buried in the gateway's imperative branches.
+ *
+ *   - `nest`         — a FOREGROUND sub-agent running inside a LIVE parent turn:
+ *                      its narrative nests under the parent's activity draft
+ *                      (the progress card). The default, unchanged.
+ *   - `worker-feed`  — a BACKGROUND worker (the `🛠 Worker` edit-in-place
+ *                      message), OR a FOREGROUND sub-agent that has NO live
+ *                      parent turn to nest into (dispatched outside a turn, or
+ *                      the turn ended while it kept running). The latter is the
+ *                      2026-06-09 fix: extended autonomous work was invisible
+ *                      because foreground status was turn-scoped and a sub-agent
+ *                      with no turn silently returned. It now reuses the worker
+ *                      feed (with the same owner-DM fallback background workers
+ *                      already use), so post-turn work is always visible.
+ *   - `legacy-relay` — a BACKGROUND worker when the worker feed is OFF: fall
+ *                      back to the legacy "still working" injected-inbound relay.
+ *   - `skip`         — nothing to surface (kill-switch off for an orphaned
+ *                      foreground, or no feed to surface it through).
+ *
+ * Determinism: the input space is 4 booleans = 16 rows, enumerated and proven
+ * in subagent-status-surface.test.ts (operator standard
+ * feedback_prove_finite_fsm_not_sample). The load-bearing invariant: an
+ * orphaned foreground sub-agent (no live turn) is `worker-feed`, never `skip`,
+ * whenever the orphan-status flag and the feed are both on.
+ */
+
+export type SubagentStatusSurface = 'nest' | 'worker-feed' | 'legacy-relay' | 'skip'
+
+export interface SubagentStatusSurfaceInput {
+  /** run_in_background dispatch (registry `subagents.background`). */
+  isBackground: boolean
+  /**
+   * A LIVE parent turn exists to nest this (foreground) sub-agent into.
+   * onProgress: `currentTurn != null`. onFinish: `currentTurn != null && it was
+   * actually nested` (so a foreground sub-agent that was surfaced via the worker
+   * feed — never nested — finalizes through the feed, not a turn collapse).
+   * Ignored for background sub-agents.
+   */
+  liveTurnPresent: boolean
+  /** SWITCHROOM_WORKER_ACTIVITY_FEED on. */
+  workerFeedEnabled: boolean
+  /** SWITCHROOM_ORPHAN_SUBAGENT_STATUS on — surface no-parent-turn foreground
+   *  sub-agents via the worker feed. Off = pre-fix behaviour (invisible). */
+  orphanStatusEnabled: boolean
+}
+
+export function resolveSubagentStatusSurface(
+  input: SubagentStatusSurfaceInput,
+): SubagentStatusSurface {
+  if (!input.isBackground) {
+    // Foreground sub-agent.
+    if (input.liveTurnPresent) return 'nest'
+    // Orphaned foreground: no live turn to nest into — the invisible case.
+    if (!input.orphanStatusEnabled) return 'skip' // kill switch: pre-fix behaviour
+    return input.workerFeedEnabled ? 'worker-feed' : 'skip' // surfacing needs the feed
+  }
+  // Background worker.
+  return input.workerFeedEnabled ? 'worker-feed' : 'legacy-relay'
+}
+
+/** SWITCHROOM_ORPHAN_SUBAGENT_STATUS — default ON; `=0` restores pre-fix (invisible) behaviour. */
+export function isOrphanSubagentStatusEnabled(envVal: string | undefined): boolean {
+  return envVal !== '0'
+}

package/telegram-plugin/tests/cron-session.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest'
+import {
+  CRON_IDENTITY_SUFFIX,
+  baseAgent,
+  cronIdentity,
+  isCronIdentity,
+  resolveInjectTarget,
+} from '../gateway/cron-session.js'
+
+describe('cron-session identity helpers', () => {
+  it('derives and detects the cron identity', () => {
+    expect(cronIdentity('clerk')).toBe(`clerk${CRON_IDENTITY_SUFFIX}`)
+    expect(isCronIdentity('clerk-cron')).toBe(true)
+    expect(isCronIdentity('clerk')).toBe(false)
+    expect(isCronIdentity(null)).toBe(false)
+    expect(isCronIdentity(undefined)).toBe(false)
+  })
+
+  it('round-trips base agent', () => {
+    expect(baseAgent(cronIdentity('marko'))).toBe('marko')
+    expect(baseAgent('marko')).toBe('marko')
+  })
+
+  it('resolveInjectTarget routes only meta.session=cron to the cron bridge', () => {
+    expect(resolveInjectTarget('clerk', { session: 'cron', source: 'cron' })).toBe('clerk-cron')
+    expect(resolveInjectTarget('clerk', { session: 'main', source: 'cron' })).toBe('clerk')
+    expect(resolveInjectTarget('clerk', { source: 'cron' })).toBe('clerk')
+    expect(resolveInjectTarget('clerk', undefined)).toBe('clerk')
+    // back-compat: every legacy caller (no session) is unchanged.
+    expect(resolveInjectTarget('clerk', { source: 'telegram' })).toBe('clerk')
+  })
+})