typeclaw 0.23.0 → 0.25.0

package/src/agent/plugin-tools.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { join } from 'node:path'
 
 import type { AgentTool } from '@mariozechner/pi-agent-core'
 import {
@@ -33,13 +34,22 @@ import type {
   ToolContext,
   ToolResult,
 } from '@/plugin'
-import { buildSandboxedCommand, ensureBwrapAvailable, resolveHiddenPaths } from '@/sandbox'
+import {
+  buildSandboxedCommand,
+  ensureBwrapAvailable,
+  ensureSessionTmpDir,
+  mapVirtualTmpPath,
+  resolveHiddenPaths,
+  resolveProtectedZones,
+  resolveWritableZones,
+  subtractMasked,
+} from '@/sandbox'
 
 import { createLoopGuard, type LoopGuard } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
-import { webfetchTool } from './tools/webfetch'
-import { websearchTool } from './tools/websearch'
+import { webFetchTool } from './tools/webfetch'
+import { webSearchTool } from './tools/websearch'
 
 // Process-wide loop guard. State is keyed by sessionId so concurrent sessions
 // don't interfere; the guard's own LRU bound keeps it from growing without
@@ -106,7 +116,7 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
 // name-filter path); the wrapped customTools just replace the implementation
 // underneath so subagent and channel sessions share the same hook coverage.
 type PiAgentToolName = 'read' | 'bash' | 'edit' | 'write' | 'grep' | 'find' | 'ls'
-type TypeclawToolName = 'websearch' | 'webfetch'
+type TypeclawToolName = 'web_search' | 'web_fetch'
 
 const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
   read: piReadTool,
@@ -119,8 +129,8 @@ const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
 }
 
 const TYPECLAW_TOOL_DEFINITION_MAP: Record<TypeclawToolName, ToolDefinition<any, any, any>> = {
-  websearch: websearchTool,
-  webfetch: webfetchTool,
+  web_search: webSearchTool,
+  web_fetch: webFetchTool,
 }
 
 function isPiAgentToolName(name: string): name is PiAgentToolName {
@@ -163,6 +173,10 @@ export type WrapToolOptions = {
   // origin mutates per turn surface the current-turn `lastInboundAuthorId`
   // to `tool.before`. Sessions with a fixed origin can pass `() => origin`.
   getOrigin?: () => SessionOrigin | undefined
+  // Resolves the current turn's abort handle. Resolved lazily (not at wrap
+  // time) because tools are wrapped BEFORE `createAgentSession` returns the
+  // session whose `agent.abort` this points at. See `fireLoopAbort`.
+  getAbort?: () => (() => void) | undefined
 }
 
 export type WrapSystemToolOptions = {
@@ -170,6 +184,7 @@ export type WrapSystemToolOptions = {
   sessionId: string
   hooks: HookBus
   getOrigin?: () => SessionOrigin | undefined
+  getAbort?: () => (() => void) | undefined
   // When present, the bash builtin is rewritten through the per-tool bwrap
   // sandbox with role-derived path masks. Absent (or no masks for the role)
   // runs bash unchanged — preserving today's behavior for trusted+ and for
@@ -228,6 +243,7 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
 
       const loopDecision = sharedLoopGuard.check(opts.sessionId, opts.toolName, before.args)
       if (loopDecision.kind === 'block') {
+        fireLoopAbort(opts.getAbort)
         return errorResult(loopDecision.message)
       }
 
@@ -287,6 +303,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       }
       const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
       if (loopDecision.kind === 'block') {
+        fireLoopAbort(opts.getAbort)
         throw new Error(loopDecision.message)
       }
       const guardResult = await runFinalWriteGuards({
@@ -349,6 +366,7 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       }
       const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
       if (loopDecision.kind === 'block') {
+        fireLoopAbort(opts.getAbort)
         throw new Error(loopDecision.message)
       }
       const guardResult = await runFinalWriteGuards({
@@ -426,6 +444,7 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
       const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
       if (loopDecision.kind === 'block') {
+        fireLoopAbort(opts.getAbort)
         throw new Error(loopDecision.message)
       }
       const guardResult = await runFinalWriteGuards({
@@ -443,7 +462,11 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       stripGuardAcknowledgements(mutableArgs)
 
       if (tool.name === 'bash' && opts.permissions !== undefined) {
-        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, bashEnvOverlay)
+        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId, bashEnvOverlay)
+      }
+
+      if (TMP_REDIRECT_TOOLS.has(tool.name) && opts.permissions !== undefined) {
+        await applyTmpPathRedirect(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId)
       }
 
       const result = await bashEnvStore.run(bashEnvOverlay, () =>
@@ -490,6 +513,7 @@ async function applyBashSandbox(
   permissions: PermissionService,
   origin: SessionOrigin | undefined,
   agentDir: string,
+  sessionId: string,
   envOverlay: BashEnvOverlay | undefined,
 ): Promise<void> {
   const command = mutableArgs.command
@@ -499,12 +523,46 @@ async function applyBashSandbox(
   if (dirs.length === 0 && files.length === 0) return
 
   await ensureBwrapAvailable()
+  // Per-session /tmp: bind this session's scratch dir over the default
+  // --tmpfs /tmp so writes survive across the role's sandboxed bash calls AND
+  // match what the write/edit wrapper redirected a /tmp path to. The bind is
+  // emitted via policy.mounts (after the hardcoded --tmpfs /tmp), so last-op-
+  // wins makes it the live /tmp. Unsandboxed roles (empty masks, returned
+  // above) keep sharing the real container /tmp between write and bash.
+  const sessionTmp = await ensureSessionTmpDir(sessionId)
+  // Write-confined jail for low-trust roles: bind the whole project read-only,
+  // hide private/secret paths, then re-expose only the free-write scratch zones
+  // (workspace + root allowlist + .git) RW. The WORKING TREE outside those zones
+  // (node_modules/, agentDir root, non-allowlisted tracked files) stays EROFS, so
+  // bash cannot sidestep the non-workspace-write guard — and `git checkout` of a
+  // protected worktree path fails at the kernel. .git is RW so members can
+  // commit; .git/hooks + .git/config (and any writable core.hooksPath target)
+  // are re-protected RO (protected, rendered after writable, ensured to exist so
+  // an absent path can't be created+executed) so a hook-plant / core.hooksPath
+  // never becomes code execution in the unsandboxed runtime git ops. Trusted/owner never reach here
+  // (their masks are empty) and keep full unsandboxed access. subtractMasked
+  // drops any writable zone masked for this role so an RW bind never re-exposes a
+  // hidden path (e.g. a guest's masked workspace/).
+  const writable = subtractMasked(await resolveWritableZones(agentDir), { dirs, files })
+  // subtractMasked again on the protected set: a protected RO bind renders after
+  // the masks (last-op-wins), so an unfiltered protected path nested under a
+  // masked dir (e.g. a guest's workspace/ when core.hooksPath=workspace/hooks)
+  // would re-expose the hidden real dir. A masked path is already non-writable
+  // for this role, so it needs no protection anyway.
+  const protectedZones = writable.dirs.includes(join(agentDir, '.git'))
+    ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
+    : { dirs: [], files: [] }
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
   const { commandString } = buildSandboxedCommand(command, {
-    mounts: [{ type: 'bind', source: agentDir, dest: agentDir }],
+    mounts: [
+      { type: 'ro-bind', source: agentDir, dest: agentDir },
+      { type: 'bind', source: sessionTmp, dest: '/tmp' },
+    ],
     masks: { dirs, files },
+    writable,
+    protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
@@ -512,11 +570,55 @@ async function applyBashSandbox(
   mutableArgs.command = commandString
 }
 
+// The builtin file tools that take a single filesystem `path` arg. For a
+// sandboxed role they all run UNSANDBOXED in the main process (only bash is
+// bwrap-wrapped), so each must apply the same /tmp -> session-dir mapping that
+// applyBashSandbox binds for bash — otherwise a `read` of /tmp/foo hits the
+// real container /tmp while sandboxed bash wrote the session backing dir.
+const TMP_REDIRECT_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'find', 'ls'])
+
+// Sandboxed roles read /tmp through bwrap's per-session bind (applyBashSandbox),
+// but the path-based file tools run unsandboxed against the real container /tmp.
+// Without this redirect a guest/member that touches /tmp/foo through bash (bound
+// to the session dir) and through a file tool (real /tmp) would see two
+// different files. Rewriting the file tool's on-disk path to the same session
+// backing dir makes every layer resolve /tmp/foo to one file. Unsandboxed roles
+// (empty masks) are left untouched: their bash already shares the real /tmp.
+async function applyTmpPathRedirect(
+  mutableArgs: Record<string, unknown>,
+  permissions: PermissionService,
+  origin: SessionOrigin | undefined,
+  agentDir: string,
+  sessionId: string,
+): Promise<void> {
+  const rawPath = mutableArgs.path
+  if (typeof rawPath !== 'string') return
+
+  const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
+  if (dirs.length === 0 && files.length === 0) return
+
+  const backing = mapVirtualTmpPath(agentDir, sessionId, rawPath)
+  if (backing === undefined) return
+
+  await ensureSessionTmpDir(sessionId)
+  mutableArgs.path = backing
+}
+
 function appendLoopWarning(result: ToolResult, message: string): ToolResult {
   const content: ContentPart[] = [...(result.content as ContentPart[]), { type: 'text', text: message }]
   return { content, details: result.details }
 }
 
+// Clears one tool's loop-guard residue for a session on the process-wide shared
+// guard. The completion-reminder bridges (channel router + TUI server) call this
+// for `subagent_output` when a backgrounded subagent finishes, so the next fetch
+// the reminder asks for isn't blocked by the window the agent's premature polling
+// poisoned. Exposed as a narrow function rather than the guard itself so callers
+// can't reach `check`/`forget` and widen the blast radius.
+export function forgetSharedLoopGuardTool(sessionId: string, tool: string): void {
+  sharedLoopGuard.forgetTool(sessionId, tool)
+}
+
 // Test-only seam: swaps the shared loop guard for a fresh instance so tests
 // that reuse sessionIds across cases don't see cross-test streak counts.
 // Production code never calls this; the guard's LRU bound handles
@@ -525,6 +627,18 @@ export function __resetSharedLoopGuardForTests(): void {
   sharedLoopGuard = createLoopGuard()
 }
 
+// A loop-guard `block` verdict returned/thrown from a tool's execute() is
+// caught by pi-agent-core and surfaced to the model as an `isError` result,
+// which the model simply retries — the loop never ends. Aborting the run's
+// AbortSignal is the only thing that actually stops the in-flight turn (the
+// next assistant stream sees the aborted signal and ends with stopReason
+// 'aborted'). We use the signal-only `agent.abort`, never `session.abort`,
+// which would deadlock awaiting the very run this tool call belongs to. See
+// the matching pattern in src/channels/router.ts (policy-denied send cap).
+function fireLoopAbort(getAbort: (() => (() => void) | undefined) | undefined): void {
+  getAbort?.()?.()
+}
+
 function errorResult(message: string) {
   return {
     content: [{ type: 'text' as const, text: message }],

package/src/agent/restart/index.ts

@@ -1,6 +1,6 @@
 import { basename } from 'node:path'
 
-import { writeRestartHandoff } from '@/agent/restart-handoff'
+import { type RestartHandoffOrigin, writeRestartHandoff } from '@/agent/restart-handoff'
 import { send, sendHttp } from '@/hostd/client'
 import { containerSocketPath } from '@/hostd/paths'
 import type { Stream } from '@/stream'
@@ -30,6 +30,11 @@ export type RequestContainerRestartOptions = {
   agentDir?: string
   originatingSessionId?: string
   originatingSessionFile?: string
+  // Origin metadata persisted into the handoff so the next boot routes the
+  // resume to the right subsystem (tui → websocket open; channel → router
+  // startup). Required alongside agentDir + originatingSessionFile for the
+  // handoff to be written; omitting it skips the handoff entirely.
+  handoffOrigin?: RestartHandoffOrigin
   restartedAt?: string
 }
 
@@ -48,6 +53,7 @@ export async function requestContainerRestart({
   agentDir,
   originatingSessionId,
   originatingSessionFile,
+  handoffOrigin,
   restartedAt,
 }: RequestContainerRestartOptions): Promise<RequestContainerRestartResult> {
   const request = { kind: 'restart' as const, containerName, build: build === true }
@@ -84,13 +90,19 @@ export async function requestContainerRestart({
   // only; a missing one just cold-starts the rebooted container without the
   // "I'm back" greeting. writeRestartHandoff swallows its own errors today, but
   // guard here too so this contract survives the writer being changed later.
-  if (agentDir !== undefined && originatingSessionId !== undefined && originatingSessionFile !== undefined) {
+  if (
+    agentDir !== undefined &&
+    originatingSessionId !== undefined &&
+    originatingSessionFile !== undefined &&
+    handoffOrigin !== undefined
+  ) {
     try {
       await writeRestartHandoff(agentDir, {
-        schemaVersion: 1,
+        schemaVersion: 2,
         restartedAt: restartTimestamp,
         originatingSessionId,
         originatingSessionFile: basename(originatingSessionFile),
+        origin: handoffOrigin,
       })
     } catch {
       // intentional swallow — see the post-ACK rationale above

package/src/agent/restart-handoff/index.ts

@@ -1,17 +1,40 @@
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
+import type { AdapterId } from '@/channels/schema'
+
 import { restartHandoffPath } from './paths'
 
 export { restartHandoffPath } from './paths'
 
 export const RESTART_HANDOFF_TTL_MS = 60_000
 
+// The channel coordinates needed to reopen and wake the originating session
+// on the channel side after a restart. Mirrors ChannelKey (src/channels/types)
+// but is duplicated here so the handoff module does not depend on the channel
+// subsystem's full type surface — only the four routing coordinates travel in
+// the handoff file.
+export type RestartHandoffChannelKey = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
+// Discriminates which subsystem owns resuming the originating session on boot.
+// A TUI handoff is claimed by the websocket `open` handler (it needs a
+// reconnecting client); a channel handoff is claimed by channel startup (the
+// router reopens the session and wakes it without any client). Splitting the
+// claim by kind is what stops the first TUI reconnect from deleting a
+// channel-origin handoff before channel boot can see it.
+export type RestartHandoffOrigin = { kind: 'tui' } | { kind: 'channel'; key: RestartHandoffChannelKey }
+
 export type RestartHandoff = {
-  schemaVersion: 1
+  schemaVersion: 2
   restartedAt: string
   originatingSessionId: string
   originatingSessionFile: string
+  origin: RestartHandoffOrigin
 }
 
 // Atomic write via `.tmp` + rename so a crash mid-write never leaves the
@@ -38,13 +61,21 @@ export async function writeRestartHandoff(agentDir: string, handoff: RestartHand
 // Otherwise a stale file would linger until the NEXT restart wrote a fresh
 // one, and the boot consumer would re-read the stale entry every time.
 //
+// `accept` lets a caller claim only the handoffs it owns: the TUI path passes
+// a tui-only predicate, channel boot passes a channel-only predicate. When the
+// predicate REJECTS an otherwise-valid handoff, the file is restored so the
+// rightful owner can still claim it (best-effort; a restore failure degrades
+// to the same cold-start as a missing handoff). When `accept` is omitted, any
+// valid handoff is consumed (preserves the original single-consumer behavior
+// for callers that do not need kind-aware claiming).
+//
 // Returns the parsed handoff iff the file existed, was valid JSON of the
-// expected shape, and was within `ttlMs` of `now`. Otherwise returns null.
-// `now` and `ttlMs` are injectable so tests can drive the recency gate
-// without sleeping.
+// expected shape, was within `ttlMs` of `now`, and (if `accept` is given)
+// passed the predicate. Otherwise returns null. `now` and `ttlMs` are
+// injectable so tests can drive the recency gate without sleeping.
 export async function consumeRestartHandoff(
   agentDir: string,
-  options: { now?: number; ttlMs?: number } = {},
+  options: { now?: number; ttlMs?: number; accept?: (handoff: RestartHandoff) => boolean } = {},
 ): Promise<RestartHandoff | null> {
   const path = restartHandoffPath(agentDir)
   const now = options.now ?? Date.now()
@@ -57,14 +88,35 @@ export async function consumeRestartHandoff(
     return null
   }
 
-  await rm(path, { force: true }).catch(() => undefined)
-
   const handoff = parseHandoff(raw)
-  if (handoff === null) return null
+
+  // Peek before delete: a handoff we will NOT claim (malformed, expired, or
+  // rejected by `accept`) is left untouched on disk so the rightful consumer
+  // can still find it. The previous delete-then-restore opened a window where
+  // a concurrent rightful consumer saw no file; never deleting an unclaimed
+  // handoff closes that window entirely.
+  if (handoff === null) {
+    await rm(path, { force: true }).catch(() => undefined)
+    return null
+  }
 
   const restartedAtMs = Date.parse(handoff.restartedAt)
-  if (Number.isNaN(restartedAtMs)) return null
-  if (now - restartedAtMs > ttlMs) return null
+  if (Number.isNaN(restartedAtMs) || now - restartedAtMs > ttlMs) {
+    await rm(path, { force: true }).catch(() => undefined)
+    return null
+  }
+
+  if (options.accept !== undefined && !options.accept(handoff)) return null
+
+  // Claim by deleting. A non-forced unlink distinguishes "we removed it" from
+  // "it was already gone": if another consumer of the same kind claimed it
+  // first, the unlink throws ENOENT and we return null, so the handoff is
+  // honored exactly once even under concurrent same-kind consumers.
+  try {
+    await rm(path)
+  } catch {
+    return null
+  }
 
   return handoff
 }
@@ -78,14 +130,60 @@ function parseHandoff(raw: string): RestartHandoff | null {
   }
   if (parsed === null || typeof parsed !== 'object') return null
   const obj = parsed as Record<string, unknown>
-  if (obj.schemaVersion !== 1) return null
+
   if (typeof obj.restartedAt !== 'string') return null
   if (typeof obj.originatingSessionId !== 'string' || obj.originatingSessionId === '') return null
   if (typeof obj.originatingSessionFile !== 'string' || obj.originatingSessionFile === '') return null
+
+  // v1 handoffs predate the origin discriminator and were only ever written by
+  // TUI sessions (channel/cron origins wrote no handoff). Read them forward as
+  // a tui origin so an in-flight restart that straddles an upgrade still
+  // produces the "I'm back" turn.
+  if (obj.schemaVersion === 1) {
+    return {
+      schemaVersion: 2,
+      restartedAt: obj.restartedAt,
+      originatingSessionId: obj.originatingSessionId,
+      originatingSessionFile: obj.originatingSessionFile,
+      origin: { kind: 'tui' },
+    }
+  }
+
+  if (obj.schemaVersion !== 2) return null
+  const origin = parseOrigin(obj.origin)
+  if (origin === null) return null
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     restartedAt: obj.restartedAt,
     originatingSessionId: obj.originatingSessionId,
     originatingSessionFile: obj.originatingSessionFile,
+    origin,
+  }
+}
+
+function parseOrigin(raw: unknown): RestartHandoffOrigin | null {
+  if (raw === null || typeof raw !== 'object') return null
+  const obj = raw as Record<string, unknown>
+  if (obj.kind === 'tui') return { kind: 'tui' }
+  if (obj.kind === 'channel') {
+    const key = parseChannelKey(obj.key)
+    if (key === null) return null
+    return { kind: 'channel', key }
+  }
+  return null
+}
+
+function parseChannelKey(raw: unknown): RestartHandoffChannelKey | null {
+  if (raw === null || typeof raw !== 'object') return null
+  const obj = raw as Record<string, unknown>
+  if (typeof obj.adapter !== 'string' || obj.adapter === '') return null
+  if (typeof obj.workspace !== 'string') return null
+  if (typeof obj.chat !== 'string') return null
+  if (obj.thread !== null && typeof obj.thread !== 'string') return null
+  return {
+    adapter: obj.adapter as AdapterId,
+    workspace: obj.workspace,
+    chat: obj.chat,
+    thread: obj.thread,
   }
 }

package/src/agent/session-origin.ts

@@ -69,6 +69,36 @@ export type SessionOrigin =
       triggeredBy?: SessionOrigin
     }
 
+// Hard ceiling on the subagent delegation chain. Bounds chain LENGTH, not
+// fan-out breadth: the deepest reachable chain is main (depth 0) →
+// operator/reviewer (depth 1) → nested worker (depth 2). `spawn_subagent`
+// refuses to spawn from a session already at this depth.
+export const MAX_SUBAGENT_DEPTH = 2
+
+// Counts subagent links from the root by walking the `spawnedByOrigin`
+// ancestry. A non-subagent (or undefined) origin is depth 0; each nested
+// subagent origin adds one. Fails CLOSED on ambiguous ancestry: if a subagent
+// origin has no `spawnedByOrigin` (the serialized path in
+// parseSpawnedByOriginJson drops it), the true depth is unknowable, so we
+// return MAX_SUBAGENT_DEPTH rather than assume it sits at the root — a
+// truncated grandchild must not read as a child and earn an extra spawn. A
+// cyclic chain is bounded by the same cap.
+export function subagentDepth(origin: SessionOrigin | undefined): number {
+  let depth = 0
+  let current: SessionOrigin | undefined = origin
+  while (current !== undefined && current.kind === 'subagent') {
+    depth += 1
+    if (current.spawnedByOrigin === undefined) {
+      return MAX_SUBAGENT_DEPTH
+    }
+    if (depth >= MAX_SUBAGENT_DEPTH) {
+      return depth
+    }
+    current = current.spawnedByOrigin
+  }
+  return depth
+}
+
 export const PARTICIPANTS_TOP_K = 10
 export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 

package/src/agent/subagent-completion-reminder.ts

@@ -43,7 +43,9 @@ export function renderSubagentCompletionReminder(args: CompletionReminderArgs):
   return (
     `<system-reminder>\n` +
     `Subagent \`${args.subagent}\` (${args.taskId}) FAILED after ${durationStr}: ${err}. ` +
-    `Use subagent_output to inspect.${channelTail}\n` +
+    `Use subagent_output to inspect. If this work was tracked in your todo list, ` +
+    `keep the item pending (or add a recovery item) via todo_write so it is not ` +
+    `dropped.${channelTail}\n` +
     `</system-reminder>`
   )
 }
@@ -57,6 +59,13 @@ export function formatReminderDuration(ms: number): string {
   return `${min}m${sec}s`
 }
 
+export type SubagentCompletedChannelKey = {
+  adapter: string
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
 export type SubagentCompletedPayload = {
   taskId: string
   subagent: string
@@ -64,6 +73,11 @@ export type SubagentCompletedPayload = {
   ok: boolean
   durationMs: number
   error?: string
+  // Present when the parent was a channel session. Lets the router fall back
+  // to the live successor session for the same channel key when the parent
+  // rolled over (SESSION_FRESHNESS_TTL_MS) or was idle-evicted while the
+  // subagent ran — otherwise the completion is silently dropped.
+  channelKey?: SubagentCompletedChannelKey
 }
 
 // Type guard for the `subagent.completed` broadcast payload. Subscribers
@@ -80,9 +94,11 @@ export function parseSubagentCompletedPayload(payload: unknown): SubagentComplet
     ok?: unknown
     durationMs?: unknown
     error?: unknown
+    channelKey?: unknown
   }
   if (p.kind !== 'subagent.completed') return null
   if (typeof p.parentSessionId !== 'string') return null
+  const channelKey = parseChannelKey(p.channelKey)
   return {
     taskId: typeof p.taskId === 'string' ? p.taskId : '<unknown>',
     subagent: typeof p.subagent === 'string' ? p.subagent : 'subagent',
@@ -90,5 +106,14 @@ export function parseSubagentCompletedPayload(payload: unknown): SubagentComplet
     ok: p.ok === true,
     durationMs: typeof p.durationMs === 'number' ? p.durationMs : 0,
     ...(typeof p.error === 'string' ? { error: p.error } : {}),
+    ...(channelKey !== null ? { channelKey } : {}),
   }
 }
+
+function parseChannelKey(value: unknown): SubagentCompletedChannelKey | null {
+  if (value === null || typeof value !== 'object') return null
+  const k = value as { adapter?: unknown; workspace?: unknown; chat?: unknown; thread?: unknown }
+  if (typeof k.adapter !== 'string' || typeof k.workspace !== 'string' || typeof k.chat !== 'string') return null
+  if (k.thread !== null && typeof k.thread !== 'string') return null
+  return { adapter: k.adapter, workspace: k.workspace, chat: k.chat, thread: k.thread }
+}