typeclaw 0.22.0 → 0.24.0

package/src/inspect/live.ts

@@ -10,8 +10,11 @@ export type StreamLiveOptions = {
   WebSocketImpl?: typeof WebSocket
   onSubscribed?: (live: boolean) => void
   onError?: (message: string) => void
+  connectTimeoutMs?: number
 }
 
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000
+
 export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<InspectEvent> {
   const WS = opts.WebSocketImpl ?? WebSocket
   const ws = new WS(opts.url)
@@ -63,9 +66,11 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
     }
   })
 
-  // Settle on open OR on any terminal condition (error/close/abort). Resolving
-  // false here is what unblocks the connect gate when esc aborts mid-connect —
-  // otherwise `await onOpen` would hang forever and freeze the inspect CLI.
+  // Settle on open OR on any terminal condition (error/close/abort/timeout).
+  // Resolving false on abort/close/timeout is what unblocks the connect gate —
+  // otherwise `await onOpen` would hang forever and freeze the inspect CLI. The
+  // timeout bounds Bun/websocket states that neither open nor error promptly.
+  let connectTimer: ReturnType<typeof setTimeout> | null = null
   const onOpen = new Promise<boolean>((resolve, reject) => {
     ws.addEventListener('open', () => resolve(true), { once: true })
     ws.addEventListener('error', () => reject(new Error('websocket connection failed')), { once: true })
@@ -74,6 +79,8 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
       if (opts.signal.aborted) resolve(false)
       else opts.signal.addEventListener('abort', () => resolve(false), { once: true })
     }
+    const timeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
+    connectTimer = setTimeout(() => reject(new Error('websocket connect timed out')), timeoutMs)
   })
   ws.addEventListener('close', () => {
     closed = true
@@ -109,7 +116,14 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
     opened = await onOpen
   } catch (err) {
     closed = true
+    try {
+      ws.close()
+    } catch {
+      /* ignore */
+    }
     throw err
+  } finally {
+    if (connectTimer !== null) clearTimeout(connectTimer)
   }
   if (!opened || closed || opts.signal?.aborted === true) return
 

package/src/inspect/loop.ts

@@ -1,20 +1,21 @@
 import { runInspect, type RunInspectOptions, type RunInspectResult } from './index'
 
-export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
-  newEscSignal: () => AbortSignal
-  // Runs after every runInspect attempt settles. The caller disarms the raw-mode
-  // ESC listener here so the live tail releases stdin before clack re-opens the
-  // picker: an ESC-aborted tail leaves the listener armed (raw mode on, 'data'
-  // handler attached), and handing clack that flowing stream freezes the picker
-  // on SSH/Bun pseudo-TTYs.
-  afterEscStream?: () => void
+export type TailController = {
+  signal: AbortSignal
+  intent: () => 'back' | 'exit' | null
+  dispose: () => void
+}
+
+export type RunInspectLoopOptions = Omit<RunInspectOptions, 'signal'> & {
+  // Builds a fresh interaction scope for ONE live-tail attempt: a new
+  // AbortController plus a temporary raw-mode listener. The loop disposes it
+  // before the picker re-opens so clack always owns a clean, non-raw stdin —
+  // this is what replaces the old pause/resume-same-controller model.
+  createTailScope: () => TailController
 }
 
 export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
   let sessionArg = opts.sessionIdOrPrefix
-  // Remember the last session the user picked from the interactive picker so
-  // an ESC-back-to-picker re-opens with that row pre-selected. The picker
-  // receives this through the `initialSessionId` hint on its second arg.
   let lastPickedId: string | undefined
   const wrappedSelectSession: typeof opts.selectSession = async (sessions, selectOpts) => {
     const hint = selectOpts?.initialSessionId ?? lastPickedId
@@ -24,18 +25,23 @@ export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunIn
   }
 
   while (true) {
-    const escSignal = opts.newEscSignal()
-    const callOpts: RunInspectOptions = { ...opts, escSignal, selectSession: wrappedSelectSession }
-    if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
-    else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
-
+    const scope = opts.createTailScope()
     let result: RunInspectResult
     try {
+      const callOpts: RunInspectOptions = {
+        ...opts,
+        selectSession: wrappedSelectSession,
+        signal: scope.signal,
+      }
+      if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
+      else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
       result = await runInspect(callOpts)
     } finally {
-      opts.afterEscStream?.()
+      scope.dispose()
     }
+
     if (!result.ok) return result
+    if (scope.intent() === 'exit') return result
     if (result.escToPicker !== true) return result
     sessionArg = undefined
   }

package/src/run/index.ts

@@ -4,6 +4,7 @@ import { createSession, createSessionWithDispose } from '@/agent'
 import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { requestContainerRestart } from '@/agent/restart'
+import { consumeRestartHandoff } from '@/agent/restart-handoff'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   awaitWithSubagentTimeout,
@@ -16,6 +17,7 @@ import {
   type SubagentRegistry,
   type SubagentShared,
 } from '@/agent/subagents'
+import { clearTodosForOrigin } from '@/agent/todo/continuation-wiring'
 import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import {
   createChannelManager,
@@ -282,14 +284,31 @@ export async function startAgent({
     // `typeclaw run` outside Docker), the handler reports that instead of the
     // command resolving as unknown, which would make the advertised contract
     // depend on the runtime environment.
-    onRestart: async (): Promise<string> => {
+    onRestart: async (ctx): Promise<string> => {
       if (containerName === undefined) {
         return 'Restart is unavailable: this agent is not running inside a typeclaw container.'
       }
-      // No originatingSessionId/stream/handoff: a channel-invoked restart must
-      // not write a resume hint or fire the "I'm back" broadcast that a TUI
-      // restart does (issue #291 scoping — only TUI origins resume).
-      const result = await requestContainerRestart({ containerName })
+      // When the /restart command resolved a live channel session, ctx carries
+      // its identity: pass stream + session id/file + channel handoffOrigin so
+      // the dying container appends the `typeclaw.restart-self` entry (via the
+      // broadcast) and writes a channel-origin handoff. On the next boot the
+      // channel resume path reopens that exact conversation. With no live
+      // session (cold channel / native slash), ctx is undefined and the
+      // container just bounces — the next inbound resumes pending todos.
+      const result = await requestContainerRestart({
+        containerName,
+        ...(ctx !== undefined
+          ? {
+              stream,
+              agentDir: cwd,
+              originatingSessionId: ctx.originatingSessionId,
+              ...(ctx.originatingSessionFile !== undefined
+                ? { originatingSessionFile: ctx.originatingSessionFile }
+                : {}),
+              handoffOrigin: ctx.handoffOrigin,
+            }
+          : {}),
+      })
       return result.ok ? 'Restart scheduled; the container will bounce shortly.' : `Restart denied: ${result.reason}`
     },
   })
@@ -434,6 +453,13 @@ export async function startAgent({
         // marker so the audit trail records "user edited cron.json".
         scheduledByOrigin: (job.scheduledByOrigin as SessionOrigin | undefined) ?? { kind: 'config-file' },
       }
+      // Cron todos are per-fire ephemeral by default: each scheduled run starts
+      // with a clean list so an incomplete item from a prior fire cannot
+      // resurrect indefinitely on every tick. (A future opt-in could carry them
+      // forward; until then, clearing is the safe default.)
+      await clearTodosForOrigin(cwd, cronOrigin).catch((err) =>
+        console.error(`[cron] ${job.id}: clear todos failed: ${err instanceof Error ? err.message : String(err)}`),
+      )
       const session = await createSession({
         reloadRegistry,
         sessionManager,
@@ -507,8 +533,37 @@ export async function startAgent({
   })
 
   reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
+
+  // Two-phase channel restart-resume around adapter startup, to close the race
+  // where an adapter starts receiving before the resume claims the handoff:
+  //   1. Claim the channel handoff and RESERVE the originating key BEFORE
+  //      channelManager.start(). The reservation installs a per-key gate, so an
+  //      inbound that arrives the instant an adapter connects coalesces onto the
+  //      resume instead of stale-rolling the mapping or creating a rival session.
+  //   2. start() the adapters (registers outbound callbacks the wake reply needs).
+  //   3. resume() the reservation: reopen the exact session and enqueue the wake
+  //      — skipped automatically if a real inbound already coalesced in (2)→(3).
+  // Claims ONLY channel handoffs; tui handoffs are left on disk (peek-then-delete
+  // never removes an unclaimed handoff) for the websocket open handler to claim.
+  // Best-effort throughout: any failure leaves the todo to resume on the next inbound.
+  let restartReservation: ReturnType<typeof channelManager.router.reserveRestartHandoff> = null
+  try {
+    const handoff = await consumeRestartHandoff(cwd, { accept: (h) => h.origin.kind === 'channel' })
+    if (handoff !== null) restartReservation = channelManager.router.reserveRestartHandoff(handoff)
+  } catch (err) {
+    console.warn(`[run] channel restart-resume reserve failed: ${err instanceof Error ? err.message : err}`)
+  }
+
   await channelManager.start()
 
+  if (restartReservation !== null) {
+    try {
+      await restartReservation.resume()
+    } catch (err) {
+      console.warn(`[run] channel restart-resume failed: ${err instanceof Error ? err.message : err}`)
+    }
+  }
+
   // Captured separately from setSpawnSubagent so both the plugin context and
   // the plugin-command runner can dispatch through the same path. The setter
   // returns void, so without this local binding we couldn't reuse the fn.

package/src/sandbox/build.ts

@@ -110,6 +110,7 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   }
 
   appendMasks(argv, policy)
+  appendWritable(argv, policy)
 
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
@@ -128,6 +129,15 @@ function appendMasks(argv: string[], policy: SandboxPolicy): void {
   }
 }
 
+function appendWritable(argv: string[], policy: SandboxPolicy): void {
+  for (const dir of policy.writable?.dirs ?? []) {
+    argv.push('--bind', dir, dir)
+  }
+  for (const file of policy.writable?.files ?? []) {
+    argv.push('--bind', file, file)
+  }
+}
+
 function appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/index.ts

@@ -1,6 +1,7 @@
 export { buildSandboxedCommand, type SandboxedCommand } from './build'
 export { ensureBwrapAvailable, _resetBwrapAvailabilityCacheForTests } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
+export { resolveWritableZones, subtractMasked, type WritableZones } from './writable-zones'
 export { formatCommand, shellQuote } from './quote'
 export { SandboxPolicyError, SandboxUnavailableError } from './errors'
 export {
@@ -12,4 +13,5 @@ export {
   type SandboxPolicy,
   type SandboxProcessPolicy,
   type SandboxProcStrategy,
+  type SandboxWritablePolicy,
 } from './policy'

package/src/sandbox/policy.ts

@@ -37,11 +37,21 @@ export type SandboxMaskPolicy = {
   files?: string[]
 }
 
+// Writable carve-outs re-exposed on top of a read-only project root AND its
+// masks. Rendered last so "last op wins" makes these the only RW paths: an RW
+// bind here overrides the broad --ro-bind parent, while anything not listed
+// stays read-only (EROFS) or masked.
+export type SandboxWritablePolicy = {
+  dirs?: string[]
+  files?: string[]
+}
+
 export type SandboxPolicy = {
   bwrapPath?: string
   cwd?: string
   mounts?: SandboxMount[]
   masks?: SandboxMaskPolicy
+  writable?: SandboxWritablePolicy
   network?: SandboxNetwork
   env?: SandboxEnvPolicy
   commandFilter?: SandboxCommandFilter

package/src/sandbox/writable-zones.ts

@@ -0,0 +1,78 @@
+import { lstat } from 'node:fs/promises'
+import path, { join } from 'node:path'
+
+export type WritableZones = {
+  dirs: string[]
+  files: string[]
+}
+
+// SECURITY: a blanket RW bind is coarser than the write/edit guards, so this set
+// is deliberately NARROWER than the write/edit allowlist — only genuinely
+// free-write scratch zones. `.agents/skills` and `packages` are excluded: the
+// former is validated (SKILL.md shape, name, frontmatter) by the skillAuthoring
+// guard and the latter holds executable plugin code; bash must not get blanket
+// RW to either. Skill authoring and package writes go through the guarded
+// write/edit tool only.
+const WRITABLE_DIRS = ['workspace', 'public', 'mounts'] as const
+
+// Bash may EDIT these when present; creating a MISSING root file goes through
+// write/edit (bwrap cannot RW-bind a non-existent source without pre-creating it).
+const WRITABLE_ROOT_FILES = [
+  'AGENTS.md',
+  'IDENTITY.md',
+  'SOUL.md',
+  'USER.md',
+  'cron.json',
+  'package.json',
+  'typeclaw.json',
+] as const
+
+// SECURITY: the symlink rejection is load-bearing. An RW bind follows symlinks,
+// so a `workspace -> /etc` symlink at a zone root would grant write access to an
+// outside path. (Symlinks INSIDE a real zone are already safe — the kernel
+// resolves them to the read-only parent mount.)
+export async function resolveWritableZones(agentDir: string): Promise<WritableZones> {
+  const dirs = await collectExisting(
+    WRITABLE_DIRS.map((d) => join(agentDir, d)),
+    'dir',
+  )
+  const files = await collectExisting(
+    WRITABLE_ROOT_FILES.map((f) => join(agentDir, f)),
+    'file',
+  )
+  return { dirs, files }
+}
+
+// SECURITY: a writable RW bind renders AFTER the masks and last-op-wins, so an
+// RW bind on a masked path would re-expose the real (hidden) directory. Drop any
+// writable zone that is, or is nested under, a masked path so the confidentiality
+// boundary survives — e.g. a guest's masked `workspace/` is never re-exposed RW.
+export function subtractMasked(writable: WritableZones, masked: { dirs: string[]; files: string[] }): WritableZones {
+  const maskedDirs = masked.dirs
+  const isMasked = (target: string): boolean =>
+    masked.files.includes(target) || maskedDirs.some((dir) => target === dir || isInside(dir, target))
+  return {
+    dirs: writable.dirs.filter((dir) => !isMasked(dir)),
+    files: writable.files.filter((file) => !isMasked(file)),
+  }
+}
+
+function isInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child)
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+}
+
+async function collectExisting(paths: string[], kind: 'dir' | 'file'): Promise<string[]> {
+  const checks = await Promise.all(paths.map((p) => isRealEntry(p, kind)))
+  return paths.filter((_, i) => checks[i])
+}
+
+async function isRealEntry(path: string, kind: 'dir' | 'file'): Promise<boolean> {
+  try {
+    const stats = await lstat(path)
+    if (stats.isSymbolicLink()) return false
+    return kind === 'dir' ? stats.isDirectory() : stats.isFile()
+  } catch {
+    return false
+  }
+}

package/src/server/index.ts

@@ -17,6 +17,14 @@ import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-hand
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
+import { TODO_CONTINUATION_SOURCE } from '@/agent/todo/continuation'
+import {
+  armRestartKickForOrigin,
+  extractTurnUsage,
+  recordTurnOutcome,
+  recordTurnStart,
+  runIdleContinuation,
+} from '@/agent/todo/continuation-wiring'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
 import type { McpManager } from '@/mcp'
@@ -155,6 +163,7 @@ type QueuedPrompt = {
   text: string
   delivery: PromptDelivery
   ts: number
+  source?: string
 }
 
 type SessionState = {
@@ -172,6 +181,7 @@ type SessionState = {
   // generation that ran session.start. A plugin reload mid-connection does
   // not re-target this session's lifecycle hooks.
   runtimeSnapshot: PluginRuntimeState | null
+  unsubTurnOutcome: Unsubscribe | null
   dispose: () => Promise<void>
 }
 
@@ -257,7 +267,7 @@ export function createServer({
       handoffPending = false
       return null
     }
-    handoffInFlight = consumeRestartHandoff(agentDir).catch(() => null)
+    handoffInFlight = consumeRestartHandoff(agentDir, { accept: (h) => h.origin.kind === 'tui' }).catch(() => null)
     const result = await handoffInFlight
     handoffPending = false
     handoffInFlight = null
@@ -497,6 +507,7 @@ export function createServer({
               unsubClaim: null,
               activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
+              unsubTurnOutcome: null,
               dispose,
             }
             sessionStates.set(ws, state)
@@ -505,12 +516,16 @@ export function createServer({
               await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
             }
 
+            if (agentDir !== undefined) {
+              state.unsubTurnOutcome = subscribeTurnOutcome(session, agentDir, origin, sessionFileId, logger)
+            }
+
             liveSessionRegistry?.register({ sessionId: sessionFileId, session })
             forwardSessionEvents(ws, session, logger, sessionFileId)
 
             if (stream) {
               state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-                enqueuePrompt(ws, state, msg, agentDir, logger),
+                enqueuePrompt(ws, state, msg, agentDir, logger, stream),
               )
 
               state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -543,6 +558,17 @@ export function createServer({
             // wired (state.unsubPrompts above) so the kick is enqueued, not
             // dropped on the floor.
             if (resumed !== null && stream) {
+              // Arm the one-shot restart-kick suppressor BEFORE publishing the
+              // kick: the kick owns the first post-restart turn ("I'm back"),
+              // so the first idle after it must not also fire a todo
+              // continuation. The flag is consumed by that first idle. Best-
+              // effort: a failure here only risks one redundant nudge, which
+              // the episode budget still bounds.
+              if (agentDir !== undefined) {
+                await armRestartKickForOrigin(agentDir, origin).catch((err) =>
+                  logger.error(`[server] ${sessionFileId}: arm restart-kick suppression failed: ${describeErr(err)}`),
+                )
+              }
               stream.publish({
                 target: { kind: 'session', sessionId: sessionFileId },
                 payload: { kind: 'prompt', text: ' ', delivery: 'queue' },
@@ -798,6 +824,7 @@ export function createServer({
             }
           } finally {
             if (state) {
+              state.unsubTurnOutcome?.()
               state.session.dispose()
               await state.dispose()
               liveSessionRegistry?.unregister(state.sessionFileId)
@@ -867,6 +894,31 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
   })
 }
 
+// Record each completed turn's stopReason for the todo-continuation guard.
+// Ordering-independent by design: this writes the outcome from `message_end`,
+// and the idle path only reads the stored outcome — it never assumes the
+// event arrived before idle fired. An unrecognized stopReason classifies as
+// 'unknown', which the idle path treats as not-safe-to-continue (fail closed).
+function subscribeTurnOutcome(
+  session: AgentSession,
+  agentDir: string,
+  origin: SessionOrigin,
+  sessionFileId: string,
+  logger: ServerLogger,
+): Unsubscribe {
+  return session.subscribe((event) => {
+    const usage = extractTurnUsage(event)
+    if (usage === null) return
+    void recordTurnOutcome({
+      agentDir,
+      origin,
+      turnId: sessionFileId,
+      stopReason: usage.stopReason,
+      ...(usage.tokens !== undefined ? { tokens: usage.tokens } : {}),
+    }).catch((err) => logger.error(`[server] ${sessionFileId}: todo outcome capture failed: ${describeErr(err)}`))
+  })
+}
+
 function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
   const detected = detectProviderError(message)
   if (detected === null) return
@@ -895,6 +947,7 @@ function enqueuePrompt(
   msg: StreamMessage,
   agentDir: string | undefined,
   logger: ServerLogger,
+  stream: Stream | undefined,
 ): void {
   const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
   if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
@@ -904,14 +957,16 @@ function enqueuePrompt(
       send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
     })
   }
+  const source = (msg.meta as { source?: unknown } | undefined)?.source
   state.drainQueue.push({
     streamMessageId: msg.id,
     text: payload.text,
     delivery,
     ts: msg.ts,
+    ...(typeof source === 'string' ? { source } : {}),
   })
   pushQueueState(ws, state)
-  void drain(ws, state, agentDir, logger)
+  void drain(ws, state, agentDir, logger, stream)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -948,7 +1003,13 @@ function makeTurnHookCallers(
   }
 }
 
-async function drain(ws: Ws, state: SessionState, agentDir: string | undefined, logger: ServerLogger): Promise<void> {
+async function drain(
+  ws: Ws,
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+  stream: Stream | undefined,
+): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
@@ -960,6 +1021,14 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
+      if (agentDir !== undefined) {
+        await recordTurnStart({
+          agentDir,
+          origin: state.origin,
+          isRealUserTurn: item.source !== TODO_CONTINUATION_SOURCE,
+        }).catch((err) => logger.error(`[server] ${state.sessionFileId}: todo turn-start failed: ${describeErr(err)}`))
+      }
+
       await fireTurnStart(item.text)
       try {
         await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
@@ -971,12 +1040,57 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       }
       await fireTurnEnd()
       await fireIdle()
+
+      // Idle-continuation runs INSIDE the loop and enqueues directly onto
+      // drainQueue (not via stream.publish). Publishing would re-enter drain()
+      // through the session subscriber while `state.draining` is still true, so
+      // the nested call would no-op and the continuation would stall until some
+      // unrelated event woke the loop again. Enqueuing here lets the same `while`
+      // consume it on the next iteration. Only fires when the queue is otherwise
+      // empty so a real user turn is never preempted by a continuation.
+      if (state.drainQueue.length === 0) {
+        await maybeContinueTodos(state, agentDir, logger)
+      }
     }
   } finally {
     state.draining = false
   }
 }
 
+// If incomplete todos remain and all guards pass, push a single continuation
+// prompt directly onto this session's drainQueue, tagged TODO_CONTINUATION_SOURCE
+// so the next drain iteration treats it as an injected (non-user) turn that does
+// not reset the episode budget. The enclosing drain loop consumes it; this never
+// calls drain() itself.
+async function maybeContinueTodos(
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+): Promise<void> {
+  if (agentDir === undefined) return
+  try {
+    await runIdleContinuation({
+      agentDir,
+      origin: state.origin,
+      deliver: (text) => {
+        state.drainQueue.push({
+          streamMessageId: `todo-continuation-${crypto.randomUUID()}` as StreamMessageId,
+          text,
+          delivery: 'queue',
+          ts: Date.now(),
+          source: TODO_CONTINUATION_SOURCE,
+        })
+      },
+    })
+  } catch (err) {
+    logger.error(`[server] ${state.sessionFileId}: todo continuation failed: ${describeErr(err)}`)
+  }
+}
+
+function describeErr(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 function pushQueueState(ws: Ws, state: SessionState): void {
   const pending: QueueStateItem[] = state.drainQueue.map((q) => ({
     id: q.streamMessageId,