typeclaw 0.23.0 → 0.24.0

package/src/agent/subagents.ts

@@ -325,6 +325,20 @@ export type StartSubagentOptions = InvokeSubagentOptions & {
 // The two promises share a single underlying invokeSubagent invocation;
 // `completion` settles after dispose, so the session reference exposed via
 // `handle.abort` becomes a no-op once `completion` resolves.
+//
+// `timeoutMs` enforcement: the `spawn_subagent` tool drives its background
+// `subagent.completed` broadcast off this `completion` promise, so an
+// unbounded `invokeSubagent` (a wedged `session.prompt` that never settles)
+// would leave `completion` pending forever and the parent never woken. When
+// the subagent declares `timeoutMs`, we race the work against a ceiling and
+// settle `completion` with `ok: false` on expiry — which fires the FAILED
+// broadcast so the parent learns the spawn died instead of hanging silently.
+// This mirrors `awaitWithSubagentTimeout` on the SubagentConsumer path; here
+// the timeout resolves (rather than rejects) because `completion` already maps
+// failures to `{ ok: false }`. Cancellation is best-effort: pi's
+// `session.prompt` takes no AbortSignal, so we call the session `abort` handle
+// (which the handle resolution captured) to tear down what we can; the LLM
+// stream may keep running until the OS reaps it.
 export function startSubagent(name: string, options: StartSubagentOptions): StartSubagentResult {
   let resolveHandle: (h: SubagentHandle) => void
   let rejectHandle: (err: Error) => void
@@ -334,11 +348,13 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
   })
   let handleSettled = false
   let finalMessage: string | undefined
+  let abortSession: (() => Promise<void>) | undefined
 
-  const completion = invokeSubagent(name, {
+  const work = invokeSubagent(name, {
     ...options,
     onSessionCreated: (event) => {
       handleSettled = true
+      abortSession = event.abort
       resolveHandle({ taskId: options.taskId, sessionId: event.sessionId, abort: event.abort })
       if (options.onSession !== undefined) {
         options.onSession(event)
@@ -357,9 +373,36 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
       return { ok: false as const, error }
     })
 
+  const timeoutMs = options.registry[name]?.timeoutMs
+  const completion = timeoutMs === undefined ? work : raceSubagentCompletion(work, name, options.taskId, timeoutMs)
+
+  void completion.then(() => {
+    if (timeoutMs !== undefined) void abortSession?.()
+  })
+
   return { handle, completion }
 }
 
+type SubagentCompletion = { ok: true; finalMessage?: string } | { ok: false; error: string }
+
+function raceSubagentCompletion(
+  work: Promise<SubagentCompletion>,
+  name: string,
+  taskId: string,
+  timeoutMs: number,
+): Promise<SubagentCompletion> {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<SubagentCompletion>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ ok: false, error: new SubagentTimeoutError(name, taskId, timeoutMs).message }),
+      timeoutMs,
+    )
+  })
+  return Promise.race([work, timeout]).finally(() => {
+    if (timer !== null) clearTimeout(timer)
+  })
+}
+
 function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg: string) => void): void {
   try {
     session.subscribe((event: unknown) => {

package/src/agent/system-prompt.ts

@@ -42,6 +42,10 @@ When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it
 
 When the user gives you work, start doing it in the same turn — a real action, not a plan or a promise-to-act. Commentary-only turns are incomplete when the next action is clear. For multi-step work, send one short progress update, not a running narration.
 
+## Tracking your work
+
+For any multi-step or long-running task, maintain a todo list with \`todo_write\` and mark items complete as you finish them. This is not bookkeeping for its own sake: if this session is interrupted — a restart, a crash, or simply a later turn — the runtime uses the remaining incomplete items to resume the work instead of silently dropping it. Write the list when you start the work, update statuses as you go, and call \`todo_clear\` when everything is genuinely done. A single-step request needs no todo list.
+
 ## Tool-call style
 
 Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.

package/src/agent/todo/continuation-policy.ts

@@ -0,0 +1,242 @@
+import { createHash } from 'node:crypto'
+
+import { incompleteTodos, type Todo } from './store'
+
+export const DEFAULT_MAX_AUTO_TURNS = 3
+export const DEFAULT_MAX_CUMULATIVE_TOKENS = 25_000
+export const DEFAULT_MAX_WALL_CLOCK_MS = 30 * 60_000
+export const DEFAULT_STAGNATION_LIMIT = 2
+
+export type ContinuationLimits = {
+  maxAutoTurns: number
+  maxCumulativeTokens: number
+  maxWallClockMs: number
+  stagnationLimit: number
+}
+
+export const DEFAULT_CONTINUATION_LIMITS: ContinuationLimits = {
+  maxAutoTurns: DEFAULT_MAX_AUTO_TURNS,
+  maxCumulativeTokens: DEFAULT_MAX_CUMULATIVE_TOKENS,
+  maxWallClockMs: DEFAULT_MAX_WALL_CLOCK_MS,
+  stagnationLimit: DEFAULT_STAGNATION_LIMIT,
+}
+
+// A continuation episode is the unit a budget applies to. It opens when the
+// first auto-nudge fires after a real user turn (or restart recovery) and
+// resets only on the next REAL user prompt — never on the runtime's own
+// injected prompts. Persisting it lets the budgets survive a restart so a
+// crash-loop cannot reset the ceiling.
+export type ContinuationEpisode = {
+  episodeId: string
+  startedAt: number
+  autoTurnCount: number
+  cumulativeTokens: number
+  failureCount: number
+  stagnationCount: number
+  lastIncompleteHash: string | null
+}
+
+// The outcome of the most recently completed turn, recorded from the
+// `message_end` subscription (authoritative) or a prompt `finally` fallback.
+// `stopReason: 'unknown'` is the fail-closed value: an idle that sees it does
+// not auto-inject.
+export type TurnOutcome = {
+  turnId: string
+  stopReason: 'stop' | 'aborted' | 'error' | 'unknown'
+  endedAt: number
+  // Total tokens the just-completed turn consumed (from the assistant
+  // message's usage). Accumulated into the episode's cumulativeTokens so the
+  // token ceiling reflects real spend. Optional for older state files and for
+  // turns whose usage was unavailable; missing counts as 0.
+  tokens?: number
+}
+
+export type ContinuationState = {
+  episode: ContinuationEpisode | null
+  lastTurnOutcome: TurnOutcome | null
+  // One-shot suppressor: the restart kick prompt owns the first post-restart
+  // idle, so the first idle after a restart consumes this and skips exactly
+  // one injection.
+  suppressNextIdleNudgeReason: 'restart-kick' | null
+  // Durable user-abort suppressor (policy D1). Set when a turn ends via
+  // explicit user abort; cleared only by the next real user turn. While set,
+  // no auto-continuation fires regardless of episode budget.
+  autoResumeBlockedUntilRealUserTurn: boolean
+}
+
+export function emptyContinuationState(): ContinuationState {
+  return {
+    episode: null,
+    lastTurnOutcome: null,
+    suppressNextIdleNudgeReason: null,
+    autoResumeBlockedUntilRealUserTurn: false,
+  }
+}
+
+const STOP_REASONS = new Set<TurnOutcome['stopReason']>(['stop', 'aborted', 'error', 'unknown'])
+
+// Validate a persisted state object field-by-field and fail closed: any field
+// that does not match the expected shape is dropped to its empty value rather
+// than trusted. A partially-written file or a newer/older schema must never
+// surface a malformed `episode` whose `undefined`/`NaN` counters would compare
+// false against the ceilings and so bypass the token-burst guard. A malformed
+// episode collapses to `null` (a fresh episode opens on the next decision); a
+// malformed outcome collapses to `null` (the idle path then fails closed, not
+// auto-injecting).
+export function parseContinuationState(value: unknown): ContinuationState {
+  if (typeof value !== 'object' || value === null) return emptyContinuationState()
+  const v = value as Record<string, unknown>
+  return {
+    episode: parseEpisode(v.episode),
+    lastTurnOutcome: parseOutcome(v.lastTurnOutcome),
+    suppressNextIdleNudgeReason: v.suppressNextIdleNudgeReason === 'restart-kick' ? 'restart-kick' : null,
+    autoResumeBlockedUntilRealUserTurn: v.autoResumeBlockedUntilRealUserTurn === true,
+  }
+}
+
+function parseEpisode(value: unknown): ContinuationEpisode | null {
+  if (typeof value !== 'object' || value === null) return null
+  const e = value as Record<string, unknown>
+  if (typeof e.episodeId !== 'string') return null
+  if (!isFiniteNumber(e.startedAt)) return null
+  if (!isFiniteNumber(e.autoTurnCount)) return null
+  if (!isFiniteNumber(e.cumulativeTokens)) return null
+  if (!isFiniteNumber(e.failureCount)) return null
+  if (!isFiniteNumber(e.stagnationCount)) return null
+  if (e.lastIncompleteHash !== null && typeof e.lastIncompleteHash !== 'string') return null
+  return {
+    episodeId: e.episodeId,
+    startedAt: e.startedAt,
+    autoTurnCount: e.autoTurnCount,
+    cumulativeTokens: e.cumulativeTokens,
+    failureCount: e.failureCount,
+    stagnationCount: e.stagnationCount,
+    lastIncompleteHash: e.lastIncompleteHash,
+  }
+}
+
+function parseOutcome(value: unknown): TurnOutcome | null {
+  if (typeof value !== 'object' || value === null) return null
+  const o = value as Record<string, unknown>
+  if (typeof o.turnId !== 'string') return null
+  if (typeof o.stopReason !== 'string' || !STOP_REASONS.has(o.stopReason as TurnOutcome['stopReason'])) return null
+  if (!isFiniteNumber(o.endedAt)) return null
+  return {
+    turnId: o.turnId,
+    stopReason: o.stopReason as TurnOutcome['stopReason'],
+    endedAt: o.endedAt,
+    ...(isFiniteNumber(o.tokens) ? { tokens: o.tokens } : {}),
+  }
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+// Canonical hash of the INCOMPLETE todos only. Normalization (sort by id or
+// normalized text, collapse whitespace, include status) makes the hash stable
+// under reordering and cosmetic edits so it is a usable stagnation heuristic.
+// It is deliberately NOT used as proof of progress — see hasRealProgress.
+export function hashIncomplete(todos: readonly Todo[]): string {
+  const incomplete = incompleteTodos(todos)
+  const canonical = incomplete
+    .map((t) => ({
+      id: t.id ?? '',
+      status: t.status,
+      content: t.content.trim().replace(/\s+/g, ' '),
+    }))
+    .sort((a, b) => {
+      const ka = a.id !== '' ? a.id : a.content
+      const kb = b.id !== '' ? b.id : b.content
+      return ka < kb ? -1 : ka > kb ? 1 : 0
+    })
+  return createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+}
+
+// "Real progress" is stricter than "the hash changed": the incomplete set must
+// shrink. Text churn (reword/reorder/split) does not count, which is what
+// closes the fake-progress loophole. Only a drop in the number of incomplete
+// items resets the stagnation counter.
+export function hasRealProgress(prev: readonly Todo[], next: readonly Todo[]): boolean {
+  return incompleteTodos(next).length < incompleteTodos(prev).length
+}
+
+export type ContinuationDecision =
+  | { kind: 'inject'; episode: ContinuationEpisode }
+  | { kind: 'skip'; reason: ContinuationSkipReason }
+
+export type ContinuationSkipReason =
+  | 'no-incomplete-todos'
+  | 'restart-kick-suppressed'
+  | 'user-abort-blocked'
+  | 'turn-not-safe'
+  | 'max-auto-turns'
+  | 'max-tokens'
+  | 'max-wall-clock'
+  | 'stagnation'
+
+// Pure decision: given the current persisted state, the current todos, the
+// last turn outcome, a fresh episode-id factory, and `now`, decide whether to
+// inject a continuation and return the episode to persist. The caller is
+// responsible for persisting `episode` from an `inject` result before actually
+// injecting. Fails closed on every ambiguity.
+export function decideContinuation(args: {
+  state: ContinuationState
+  todos: readonly Todo[]
+  limits: ContinuationLimits
+  now: number
+  newEpisodeId: () => string
+}): ContinuationDecision {
+  const { state, todos, limits, now } = args
+
+  if (incompleteTodos(todos).length === 0) return { kind: 'skip', reason: 'no-incomplete-todos' }
+
+  if (state.suppressNextIdleNudgeReason === 'restart-kick') {
+    return { kind: 'skip', reason: 'restart-kick-suppressed' }
+  }
+
+  if (state.autoResumeBlockedUntilRealUserTurn) return { kind: 'skip', reason: 'user-abort-blocked' }
+
+  const outcome = state.lastTurnOutcome
+  if (outcome === null || outcome.stopReason === 'unknown' || outcome.stopReason === 'aborted') {
+    return { kind: 'skip', reason: 'turn-not-safe' }
+  }
+
+  const hash = hashIncomplete(todos)
+  const base: ContinuationEpisode = state.episode ?? {
+    episodeId: args.newEpisodeId(),
+    startedAt: now,
+    autoTurnCount: 0,
+    cumulativeTokens: 0,
+    failureCount: 0,
+    stagnationCount: 0,
+    lastIncompleteHash: null,
+  }
+
+  // Fold the just-completed turn's token spend into the episode BEFORE checking
+  // the ceiling, so the budget reflects what the previous auto-turn actually
+  // cost. `lastTurnOutcome.tokens` is the spend of the turn that drove this
+  // idle; missing usage counts as 0.
+  const episode: ContinuationEpisode = {
+    ...base,
+    cumulativeTokens: base.cumulativeTokens + (outcome.tokens ?? 0),
+  }
+
+  if (episode.autoTurnCount >= limits.maxAutoTurns) return { kind: 'skip', reason: 'max-auto-turns' }
+  if (episode.cumulativeTokens >= limits.maxCumulativeTokens) return { kind: 'skip', reason: 'max-tokens' }
+  if (now - episode.startedAt >= limits.maxWallClockMs) return { kind: 'skip', reason: 'max-wall-clock' }
+
+  const stagnated = episode.lastIncompleteHash === hash
+  const stagnationCount = stagnated ? episode.stagnationCount + 1 : episode.stagnationCount
+  if (stagnationCount >= limits.stagnationLimit) return { kind: 'skip', reason: 'stagnation' }
+
+  return {
+    kind: 'inject',
+    episode: {
+      ...episode,
+      autoTurnCount: episode.autoTurnCount + 1,
+      stagnationCount,
+      lastIncompleteHash: hash,
+    },
+  }
+}

package/src/agent/todo/continuation-state.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import {
+  type ContinuationState,
+  emptyContinuationState,
+  parseContinuationState,
+  type TurnOutcome,
+} from './continuation-policy'
+import type { TodoScope } from './scope'
+import { todoDir } from './store'
+
+type StateFile = {
+  version: 1
+  state: ContinuationState
+}
+
+export function continuationStatePath(agentDir: string, scope: TodoScope): string {
+  return join(todoDir(agentDir), '.state', `${scope.key}.json`)
+}
+
+export async function readContinuationState(agentDir: string, scope: TodoScope): Promise<ContinuationState> {
+  const path = continuationStatePath(agentDir, scope)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (err) {
+    if (isEnoent(err)) return emptyContinuationState()
+    throw err
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<StateFile>
+    return parseContinuationState(parsed.state)
+  } catch {
+    return emptyContinuationState()
+  }
+}
+
+export async function writeContinuationState(
+  agentDir: string,
+  scope: TodoScope,
+  state: ContinuationState,
+): Promise<void> {
+  const path = continuationStatePath(agentDir, scope)
+  const payload: StateFile = { version: 1, state }
+  await mkdir(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+  await rename(tmp, path)
+}
+
+// A real user turn ends any active continuation episode and clears both
+// suppressors. This is the ONLY thing that resets the episode budget — the
+// runtime's own injected continuation prompts must not. Callers pass `false`
+// for injected prompts so the episode budget keeps counting down.
+export function onTurnStart(state: ContinuationState, isRealUserTurn: boolean): ContinuationState {
+  if (!isRealUserTurn) return state
+  return {
+    ...state,
+    episode: null,
+    autoResumeBlockedUntilRealUserTurn: false,
+    suppressNextIdleNudgeReason: null,
+  }
+}
+
+// Record the most recently completed turn's outcome. Explicit user abort also
+// arms the durable suppressor so no auto-continuation fires until a real user
+// turn clears it (policy D1).
+export function onTurnOutcome(state: ContinuationState, outcome: TurnOutcome): ContinuationState {
+  const next: ContinuationState = { ...state, lastTurnOutcome: outcome }
+  if (outcome.stopReason === 'aborted') next.autoResumeBlockedUntilRealUserTurn = true
+  return next
+}
+
+export function armRestartKickSuppression(state: ContinuationState): ContinuationState {
+  return { ...state, suppressNextIdleNudgeReason: 'restart-kick' }
+}
+
+export function consumeRestartKickSuppression(state: ContinuationState): ContinuationState {
+  if (state.suppressNextIdleNudgeReason === null) return state
+  return { ...state, suppressNextIdleNudgeReason: null }
+}
+
+function isEnoent(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT'
+}

package/src/agent/todo/continuation-wiring.ts

@@ -0,0 +1,113 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+import { maybeInjectContinuation } from './continuation'
+import { type TurnOutcome } from './continuation-policy'
+import {
+  armRestartKickSuppression,
+  onTurnOutcome,
+  onTurnStart,
+  readContinuationState,
+  writeContinuationState,
+} from './continuation-state'
+import { resolveTodoScope } from './scope'
+import { writeTodos } from './store'
+
+// Map a pi `message_end` event's stopReason onto the TurnOutcome stopReason
+// space. Anything we don't recognize collapses to 'unknown' so the idle path
+// fails closed (no auto-injection on an outcome we can't classify).
+export function classifyStopReason(raw: unknown): TurnOutcome['stopReason'] {
+  if (raw === 'stop' || raw === 'aborted' || raw === 'error') return raw
+  return 'unknown'
+}
+
+// Extract the stopReason and token usage from a pi `message_end` event.
+// Returns null for any event that is not an assistant message_end. `tokens`
+// comes from the assistant message's `usage.totalTokens`; it is undefined when
+// the provider did not report usage.
+export function extractTurnUsage(event: unknown): { stopReason: TurnOutcome['stopReason']; tokens?: number } | null {
+  if (typeof event !== 'object' || event === null) return null
+  const e = event as { type?: unknown; message?: unknown }
+  if (e.type !== 'message_end') return null
+  const message = e.message as { role?: unknown; stopReason?: unknown; usage?: unknown } | undefined
+  if (message?.role !== 'assistant') return null
+  const usage = message.usage as { totalTokens?: unknown } | undefined
+  const total = usage?.totalTokens
+  const tokens = typeof total === 'number' && Number.isFinite(total) ? total : undefined
+  return { stopReason: classifyStopReason(message.stopReason), ...(tokens !== undefined ? { tokens } : {}) }
+}
+
+export function extractStopReason(event: unknown): TurnOutcome['stopReason'] | null {
+  return extractTurnUsage(event)?.stopReason ?? null
+}
+
+// Persist the just-completed turn's outcome for a scope. No-op for origins
+// without a todo scope (subagent/system). Safe to call from a subscription
+// callback; it swallows nothing — callers wrap as they see fit.
+export async function recordTurnOutcome(args: {
+  agentDir: string
+  origin: SessionOrigin
+  turnId: string
+  stopReason: TurnOutcome['stopReason']
+  tokens?: number
+  now?: number
+}): Promise<void> {
+  const scope = resolveTodoScope(args.origin)
+  if (scope === null) return
+  const state = await readContinuationState(args.agentDir, scope)
+  const outcome: TurnOutcome = {
+    turnId: args.turnId,
+    stopReason: args.stopReason,
+    endedAt: args.now ?? Date.now(),
+    ...(args.tokens !== undefined ? { tokens: args.tokens } : {}),
+  }
+  await writeContinuationState(args.agentDir, scope, onTurnOutcome(state, outcome))
+}
+
+// Reset the continuation episode at the start of a REAL user turn. Injected
+// continuation turns pass isRealUserTurn=false so the episode budget keeps
+// counting down. No-op for scopeless origins.
+export async function recordTurnStart(args: {
+  agentDir: string
+  origin: SessionOrigin
+  isRealUserTurn: boolean
+}): Promise<void> {
+  const scope = resolveTodoScope(args.origin)
+  if (scope === null) return
+  const state = await readContinuationState(args.agentDir, scope)
+  const next = onTurnStart(state, args.isRealUserTurn)
+  if (next !== state) await writeContinuationState(args.agentDir, scope, next)
+}
+
+// Arm the one-shot restart-kick suppressor for an origin's scope, so the first
+// idle after a restart skips exactly one continuation injection (the restart
+// kick prompt owns that turn). No-op for scopeless origins.
+export async function armRestartKickForOrigin(agentDir: string, origin: SessionOrigin): Promise<void> {
+  const scope = resolveTodoScope(origin)
+  if (scope === null) return
+  const state = await readContinuationState(agentDir, scope)
+  await writeContinuationState(agentDir, scope, armRestartKickSuppression(state))
+}
+
+// Empty the todo list for an origin's scope. No-op for scopeless origins.
+export async function clearTodosForOrigin(agentDir: string, origin: SessionOrigin): Promise<void> {
+  const scope = resolveTodoScope(origin)
+  if (scope === null) return
+  await writeTodos(agentDir, scope, [])
+}
+
+export type DeliverContinuation = (text: string) => void
+
+// Idle-path entry: decide whether to nudge and, if so, deliver via the
+// origin-appropriate mechanism the caller supplies. Returns true if a nudge
+// was delivered. The decide-and-persist step happens inside
+// maybeInjectContinuation; delivery is the only side effect the caller owns.
+export async function runIdleContinuation(args: {
+  agentDir: string
+  origin: SessionOrigin
+  deliver: DeliverContinuation
+}): Promise<boolean> {
+  const result = await maybeInjectContinuation({ agentDir: args.agentDir, origin: args.origin })
+  if (result.kind !== 'injected') return false
+  args.deliver(result.text)
+  return true
+}

package/src/agent/todo/continuation.ts

@@ -0,0 +1,71 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+import { type ContinuationLimits, DEFAULT_CONTINUATION_LIMITS, decideContinuation } from './continuation-policy'
+import { consumeRestartKickSuppression, readContinuationState, writeContinuationState } from './continuation-state'
+import { resolveTodoScope, type TodoScope } from './scope'
+import { readTodos } from './store'
+
+export const TODO_CONTINUATION_SOURCE = 'todo-continuation'
+
+export const CONTINUATION_PROMPT = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Incomplete todo items remain in your list. Continue working on the next',
+  'pending item now, without asking for permission. Mark each item complete (or',
+  'cancelled) as you finish it by calling `todo_write` with the updated list. If',
+  'you believe all the work is already done, do not just assert it — re-examine',
+  'each remaining item skeptically, verify the work actually landed, and update',
+  'the list accordingly. When everything is genuinely complete, call',
+  '`todo_clear`. Do not acknowledge or reply to this notice; just continue the',
+  'work.',
+  '',
+  '---',
+  '',
+].join('\n')
+
+export type ContinuationInjectResult =
+  | { kind: 'injected'; scope: TodoScope; text: string }
+  | { kind: 'skipped'; reason: string }
+
+export type MaybeInjectContinuationArgs = {
+  agentDir: string
+  origin: SessionOrigin | undefined
+  now?: number
+  limits?: ContinuationLimits
+  newEpisodeId?: () => string
+}
+
+// Decide-and-persist entry point called from the idle path of each origin's
+// drain loop. On `injected`, the caller is responsible for actually delivering
+// `text` into the session (TUI: stream.publish; channel: pendingSystemReminders
+// + drain). The episode mutation is persisted BEFORE returning so a crash
+// between persist and deliver can only UNDER-count (fail-safe: a missed
+// delivery costs one wasted budget slot, never an unbounded loop).
+//
+// The restart-kick one-shot is consumed here even on skip, so the first
+// post-restart idle always burns the suppressor exactly once.
+export async function maybeInjectContinuation(args: MaybeInjectContinuationArgs): Promise<ContinuationInjectResult> {
+  if (args.origin === undefined) return { kind: 'skipped', reason: 'no-origin' }
+  const scope = resolveTodoScope(args.origin)
+  if (scope === null) return { kind: 'skipped', reason: 'no-scope' }
+
+  const now = args.now ?? Date.now()
+  const limits = args.limits ?? DEFAULT_CONTINUATION_LIMITS
+  const newEpisodeId = args.newEpisodeId ?? (() => crypto.randomUUID())
+
+  const todos = await readTodos(args.agentDir, scope)
+  const state = await readContinuationState(args.agentDir, scope)
+
+  const decision = decideContinuation({ state, todos, limits, now, newEpisodeId })
+
+  if (decision.kind === 'skip') {
+    if (state.suppressNextIdleNudgeReason !== null) {
+      await writeContinuationState(args.agentDir, scope, consumeRestartKickSuppression(state))
+    }
+    return { kind: 'skipped', reason: decision.reason }
+  }
+
+  await writeContinuationState(args.agentDir, scope, { ...state, episode: decision.episode })
+  return { kind: 'injected', scope, text: CONTINUATION_PROMPT }
+}

package/src/agent/todo/scope.ts

@@ -0,0 +1,77 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+// A todo scope is the durable identity a todo list hangs off. It is
+// deliberately NOT the raw sessionId: sessionIds churn across TUI reconnects
+// and every cron fire, and a channel session can roll to a fresh sessionId on
+// stale-rollover (see src/channels/router.ts SESSION_FRESHNESS_TTL_MS). Keying
+// on origin identity instead lets a todo list survive those transitions so
+// interrupted work can be resumed.
+//
+// `key` is a filesystem-safe relative path segment (no leading slash, no `..`).
+// `kind` mirrors the originating `SessionOrigin['kind']` so the continuation
+// injector can enforce that a nudge only fires into a live session whose origin
+// matches the scope (the eligible-session invariant).
+export type TodoScope = {
+  kind: 'tui' | 'channel' | 'cron'
+  key: string
+}
+
+// Resolve the durable todo scope for a session origin, or `null` when the
+// origin owns no todo list.
+//
+// - tui      → singleton `tui`. There is no stable per-operator identity (the
+//              sessionId churns on every reconnect and the restart handoff is
+//              once-per-boot), so TUI is modeled as one global workstream per
+//              agent. Concurrent TUI attaches therefore share a scope; this is
+//              an accepted, documented limitation.
+// - channel  → keyed by the adapter/workspace/chat/thread tuple, matching how
+//              channels/sessions.json already identifies a conversation. This
+//              survives both container restart and stale-rollover.
+// - cron     → keyed by jobId. The sessionId is useless here (fresh every
+//              fire); the job is the durable identity.
+// - subagent → null. Subagents do not own continuation; their parent does.
+// - system   → null. Runtime infrastructure (memory/backup) is not
+//              user-delegated work and must never auto-continue.
+export function resolveTodoScope(origin: SessionOrigin): TodoScope | null {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui', key: 'tui' }
+    case 'channel':
+      return { kind: 'channel', key: channelScopeKey(origin) }
+    case 'cron':
+      return { kind: 'cron', key: `cron/${encodeComponent(origin.jobId)}` }
+    case 'subagent':
+    case 'system':
+      return null
+    default: {
+      const _exhaustive: never = origin
+      void _exhaustive
+      return null
+    }
+  }
+}
+
+function channelScopeKey(origin: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
+  const parts = [
+    encodeComponent(origin.adapter),
+    encodeComponent(origin.workspace),
+    encodeComponent(origin.chat),
+    encodeComponent(origin.thread),
+  ]
+  return `channel/${parts.join(':')}`
+}
+
+// Encode one scope component injectively. Every component is emitted as a
+// discriminant prefix plus its `encodeURIComponent` form:
+//   - null          → `n`        (the channel-root / no-thread case)
+//   - any string s  → `s<encoded>`
+// The prefix makes the three cases pairwise distinguishable that lossy schemes
+// confused: a null thread vs a literal "n" string, an empty string vs a
+// literal "_empty" string, and any value vs another whose unsafe chars happen
+// to map together. `encodeURIComponent` is itself injective and never emits
+// `/` or `:`, so the joined key is both a single filesystem-safe path segment
+// and a collision-free identity for the conversation whose todo file it names.
+function encodeComponent(value: string | null): string {
+  if (value === null) return 'n'
+  return `s${encodeURIComponent(value)}`
+}