typeclaw 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 
 import {
   createAgentSession,
+  createCodingTools,
   DefaultResourceLoader,
   defineTool as definePiTool,
   SessionManager,
@@ -45,11 +46,13 @@ import {
   zodToToolParameters,
 } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
+import type { RestartHandoffOrigin } from './restart-handoff'
 import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
 import type { CreateSessionForSubagent, SubagentRegistry } from './subagents'
 import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
+import { attachToolNotFoundNudge } from './tool-not-found-nudge'
 import {
   createBudgetState,
   type ToolResultBudget,
@@ -68,6 +71,7 @@ import { createSpawnSubagentTool } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
 import { createSubagentCancelTool } from './tools/subagent-cancel'
 import { createSubagentOutputTool } from './tools/subagent-output'
+import { createTodoTools } from './tools/todo'
 import { webfetchTool } from './tools/webfetch'
 import { websearchTool } from './tools/websearch'
 
@@ -79,6 +83,13 @@ export { renderTurnRoleAnchor, renderTurnTimeAnchor } from './system-prompt'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createAgentSession>[0]>['tools']
 
+// pi's default active built-in tools when a session declares no `tools:` filter
+// (pi `createAgentSession` falls back to `defaultActiveToolNames`, which is the
+// name set of `codingTools`). Derived from pi's own `createCodingTools()` rather
+// than hardcoded so the list can't silently drift if pi adds/removes/renames a
+// default builtin; `default-pi-builtins match pi's coding tool set` pins it.
+const DEFAULT_PI_BUILTIN_TOOL_NAMES = createCodingTools(process.cwd()).map((t) => t.name)
+
 export type PluginSessionWiring = {
   registry: PluginRegistry
   hooks: HookBus
@@ -248,6 +259,13 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   const getOrigin: () => SessionOrigin | undefined =
     options.originRef !== undefined ? () => options.originRef!.current : () => options.origin
 
+  // Holds the session's signal-only abort once `createAgentSession` resolves.
+  // Tools are wrapped BEFORE the session exists, so the loop guard reaches the
+  // abort through this lazily-resolved getter. See `fireLoopAbort` in
+  // plugin-tools.ts for why aborting (not throwing) is what stops the loop.
+  const abortHolder: { abort?: () => void } = {}
+  const getAbort: () => (() => void) | undefined = () => abortHolder.abort
+
   // Subagent built-in tool refs are dual-routed (see BUILTIN_TOOL_DEFINITION
   // dual-map in plugin-tools.ts): pi-side coding tools go to `tools:` so they
   // become the strict base set, typeclaw-side web tools go to `customTools:`.
@@ -259,8 +277,8 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
     : { agentTools: [], toolDefinitions: [] }
   const pluginCustomTools = options.pluginSubagent
-    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin)
-    : wrapRegistryTools(options.plugins, getOrigin)
+    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin, getAbort)
+    : wrapRegistryTools(options.plugins, getOrigin, getAbort)
 
   // Per-run budget state for the tool-result byte ceiling. Allocated once per
   // session creation and threaded into every wrapped tool so they share the
@@ -276,7 +294,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
   const effectiveTools =
     options.tools ?? (options.pluginSubagent ? (resolvedSubagentBuiltins.agentTools as AgentSessionTools) : undefined)
-  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin)
+  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin, getAbort)
   const tools =
     sessionBudget && sessionBudgetState && hookWrappedTools
       ? (hookWrappedTools.map((t) =>
@@ -348,6 +366,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               permissions: options.permissions,
               reloadRoles: options.reloadRoles,
             }),
+            ...buildTodoTools(options.plugins?.agentDir, getOrigin),
           ]
   // Hook coverage for pi's builtin coding tools (read/bash/edit/write/grep/
   // find/ls) — pi 0.67.3 ignores `tools:` for implementation, so the only
@@ -361,10 +380,11 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           sessionId: options.plugins.sessionId,
           hooks: options.plugins.hooks,
           getOrigin,
+          getAbort,
           ...(options.permissions ? { permissions: options.permissions } : {}),
         })
       : []
-  const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin)
+  const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin, getAbort)
   const customToolsPreBudget = [...wrappedCustomSystemTools, ...pluginCustomTools, ...builtinPiToolOverrides]
   const customTools =
     sessionBudget && sessionBudgetState
@@ -385,25 +405,41 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     ...(thinkingLevel ? { thinkingLevel } : {}),
   })
 
+  abortHolder.abort = () => {
+    if (session.agent.signal?.aborted !== true) session.agent.abort()
+  }
+
+  // The names the session actually exposes to the model: pi's active base set
+  // (the caller's `tools:` filter, or pi's default builtins when unset) union
+  // the typeclaw/plugin custom tools. Deliberately EXCLUDES
+  // `builtinPiToolOverrides` — those replace builtin implementations by name,
+  // they are not additional callable names. This is the single source of truth
+  // for both the active-set re-narrowing below and the tool-not-found nudge
+  // vocabulary, so the two never drift (a divergence would make the nudge miss
+  // real tools or suggest tools the session deliberately did not expose).
+  const intendedActiveToolNames = [
+    ...new Set([
+      ...(tools !== undefined ? tools.map((t) => t.name) : DEFAULT_PI_BUILTIN_TOOL_NAMES),
+      ...[...wrappedCustomSystemTools, ...pluginCustomTools].map((t) => t.name),
+    ]),
+  ]
+
   // Re-narrow the active tool set after `createAgentSession`. pi 0.67.3's
   // `_refreshToolRegistry` runs with `includeAllExtensionTools: true` and
   // pushes every customTool name into the active set, which would widen
   // a subagent's declared `[edit]` to all 7 builtin overrides plus every
-  // typeclaw custom tool. The intended active set is the names the caller
-  // would have gotten WITHOUT the builtin overrides: pi's `initialActiveToolNames`
-  // (derived from `tools:`) union the names from typeclaw/plugin customTools.
-  // `builtinPiToolOverrides` are implementation overrides, never additions.
+  // typeclaw custom tool.
   if (builtinPiToolOverrides.length > 0) {
-    const baseActiveNames = tools !== undefined ? tools.map((t) => t.name) : ['read', 'bash', 'edit', 'write']
-    const customToolActiveNames = [...wrappedCustomSystemTools, ...pluginCustomTools].map((t) => t.name)
-    const intendedActive = [...new Set([...baseActiveNames, ...customToolActiveNames])]
-    session.setActiveToolsByName(intendedActive)
+    session.setActiveToolsByName(intendedActiveToolNames)
   }
 
   const unsubRestart = subscribeRestartNotice(options.stream, sessionManager)
 
+  const unsubToolNudge = attachToolNotFoundNudge(session, intendedActiveToolNames)
+
   const dispose = async () => {
     unsubRestart?.()
+    unsubToolNudge()
     if (materializedSkills) await materializedSkills.dispose()
   }
   return { session, dispose }
@@ -411,22 +447,39 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
 // Decides whether the restart tool should write the cross-restart handoff
 // file (`<agentDir>/.typeclaw/restart-pending.json`) and supplies the agentDir
-// + session file path it needs to do so. Returns an empty object — meaning
-// "no handoff" — for any session whose origin is not TUI, so a channel-
-// originated or cron-originated `restart` call cannot accidentally produce an
-// "I'm back" greeting in the next container's first TUI session. See
-// issue #291's scoping concerns. Also returns empty when the session is not
-// persisted to disk (in-memory sessions have no file the next container could
-// reopen).
+// + session file path + origin metadata it needs to do so. Returns an empty
+// object — meaning "no handoff" — for cron/subagent/system origins (no
+// attended session the next boot could resume) and for in-memory sessions
+// (no file to reopen).
+//
+// TUI and channel origins both resume: a TUI restart reattaches to the
+// reconnecting client (websocket open handler), a channel restart reopens the
+// originating chat session on the channel router's boot path. The `origin`
+// discriminator in the handoff is what routes the next boot to the correct
+// subsystem.
 export function buildRestartHandoffWiring(
   options: { origin?: SessionOrigin; plugins?: { agentDir: string } },
   sessionManager: SessionManager,
-): { agentDir?: string; originatingSessionFile?: string } {
-  if (options.origin?.kind !== 'tui') return {}
+): { agentDir?: string; originatingSessionFile?: string; handoffOrigin?: RestartHandoffOrigin } {
+  const origin = options.origin
+  if (origin === undefined) return {}
+  const handoffOrigin = restartHandoffOriginFor(origin)
+  if (handoffOrigin === null) return {}
   const agentDir = options.plugins?.agentDir
   const sessionFile = sessionManager.getSessionFile()
   if (agentDir === undefined || sessionFile === undefined) return {}
-  return { agentDir, originatingSessionFile: sessionFile }
+  return { agentDir, originatingSessionFile: sessionFile, handoffOrigin }
+}
+
+function restartHandoffOriginFor(origin: SessionOrigin): RestartHandoffOrigin | null {
+  if (origin.kind === 'tui') return { kind: 'tui' }
+  if (origin.kind === 'channel') {
+    return {
+      kind: 'channel',
+      key: { adapter: origin.adapter, workspace: origin.workspace, chat: origin.chat, thread: origin.thread },
+    }
+  }
+  return null
 }
 
 // Subscribes the given session to the in-process broadcast that the `restart`
@@ -662,9 +715,18 @@ export function buildRoleGrantTools(opts: {
   ]
 }
 
+export function buildTodoTools(
+  agentDir: string | undefined,
+  getOrigin: () => SessionOrigin | undefined,
+): ToolDefinition[] {
+  if (agentDir === undefined) return []
+  return createTodoTools({ agentDir, getOrigin })
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!plugins) return []
   return plugins.registry.tools.map((t: PluginRegisteredTool) =>
@@ -676,6 +738,7 @@ function wrapRegistryTools(
       logger: t.logger,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -684,6 +747,7 @@ function wrapSystemAgentTools(
   tools: AgentSessionTools | undefined,
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): AgentSessionTools | undefined {
   if (!tools || !hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
@@ -692,6 +756,7 @@ function wrapSystemAgentTools(
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -700,6 +765,7 @@ function wrapSystemTools(
   tools: ToolDefinition[],
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
@@ -708,6 +774,7 @@ function wrapSystemTools(
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -721,6 +788,7 @@ function wrapSubagentCustomTools(
   selection: PluginSubagentSelection,
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!selection.customTools || !plugins) return []
   const logger = makePluginLogger(selection.pluginName)
@@ -733,6 +801,7 @@ function wrapSubagentCustomTools(
       logger,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }

package/src/agent/plugin-tools.ts

@@ -33,7 +33,13 @@ import type {
   ToolContext,
   ToolResult,
 } from '@/plugin'
-import { buildSandboxedCommand, ensureBwrapAvailable, resolveHiddenPaths } from '@/sandbox'
+import {
+  buildSandboxedCommand,
+  ensureBwrapAvailable,
+  resolveHiddenPaths,
+  resolveWritableZones,
+  subtractMasked,
+} from '@/sandbox'
 
 import { createLoopGuard, type LoopGuard } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
@@ -163,6 +169,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 +180,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 +239,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 +299,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 +362,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 +440,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({
@@ -499,12 +514,21 @@ async function applyBashSandbox(
   if (dirs.length === 0 && files.length === 0) return
 
   await ensureBwrapAvailable()
+  // 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
+  // RW. Anything else under agentDir (.git/, node_modules/, agentDir root) is
+  // EROFS, so bash cannot sidestep the non-workspace-write guard. 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 })
   // 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 }],
     masks: { dirs, files },
+    writable,
     network: 'inherit',
     cwd: agentDir,
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
@@ -525,6 +549,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/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>`
   )
 }