typeclaw 0.10.0 → 0.11.1

package/src/init/validate-api-key.ts

@@ -60,6 +60,23 @@ export async function validateApiKey(
       return { kind: 'skipped', reason: 'network-error', detail: 'unexpected response shape' }
     }
     if (res.status === 401 || res.status === 403) {
+      // Fireworks issues two key classes that probe the same /v1/models
+      // endpoint differently:
+      //   * Standard keys (fw_...)  → 200 with the models list
+      //   * Fire Pass keys (fpk_...) → 403 with {"error":{"code":"FORBIDDEN",
+      //     "message":"Fire Pass API keys are not authorized for this route."}}
+      // The 403 *proves* authentication succeeded — the route is just out of
+      // scope for the key. Fire Pass keys do work at chat-completions, which
+      // is exactly the surface typeclaw needs (the only Fireworks model wired
+      // here is the Fire Pass router `kimi-k2p6-turbo`). Treating that 403
+      // as `rejected` is the bug; recognize the marker and accept the key.
+      // Genuinely bad keys still come back as 401 UNAUTHORIZED, untouched.
+      if (providerId === 'fireworks' && res.status === 403) {
+        const body = await readCapped(res, MAX_BODY_BYTES)
+        if (body !== null && isFireworksFirePassForbidden(body)) {
+          return { kind: 'ok' }
+        }
+      }
       return { kind: 'rejected', status: res.status }
     }
     return { kind: 'skipped', reason: 'network-error', detail: `HTTP ${res.status}` }
@@ -74,6 +91,20 @@ export async function validateApiKey(
 
 const MAX_BODY_BYTES = 4096
 
+function isFireworksFirePassForbidden(body: string): boolean {
+  try {
+    const parsed = JSON.parse(body) as { error?: { code?: unknown; message?: unknown } }
+    const err = parsed.error
+    if (!err || typeof err !== 'object') return false
+    if (err.code === 'FORBIDDEN' && typeof err.message === 'string' && err.message.includes('Fire Pass')) {
+      return true
+    }
+    return false
+  } catch {
+    return false
+  }
+}
+
 async function isModelsListShape(res: Response): Promise<boolean> {
   const text = await readCapped(res, MAX_BODY_BYTES)
   if (text === null) return false

package/src/inspect/index.ts

@@ -37,7 +37,11 @@ export type RunInspectOptions = {
   liveHint?: string
 }
 
-export type SelectSession = (sessions: SessionSummary[]) => Promise<SessionSummary | null>
+export type SelectSessionOptions = {
+  initialSessionId?: string
+}
+
+export type SelectSession = (sessions: SessionSummary[], opts?: SelectSessionOptions) => Promise<SessionSummary | null>
 
 export type LiveSourceFactory = (opts: {
   sessionId: string

package/src/inspect/loop.ts

@@ -6,9 +6,20 @@ export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
 
 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
+    const picked = await opts.selectSession(sessions, hint !== undefined ? { initialSessionId: hint } : {})
+    if (picked !== null) lastPickedId = picked.sessionId
+    return picked
+  }
+
   while (true) {
     const escSignal = opts.newEscSignal()
-    const callOpts: RunInspectOptions = { ...opts, escSignal }
+    const callOpts: RunInspectOptions = { ...opts, escSignal, selectSession: wrappedSelectSession }
     if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
     else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
 

package/src/inspect/replay.ts

@@ -66,7 +66,7 @@ function* eventsFromEntry(
   if (!isMessageEntry(entry)) return
   const message = entry.message
   const role = message.role
-  const ts = numberOr(readField(message, 'timestamp'), 0)
+  const ts = entryTimestampMs(entry, message)
   if (role === 'user') {
     const text = readTextContent(message.content)
     if (text !== null) yield { cat: 'user', ts, text }
@@ -219,6 +219,20 @@ function readUsage(value: unknown): {
   }
 }
 
+function entryTimestampMs(
+  entry: { type: 'message'; message: { role: string; [k: string]: unknown } },
+  message: { role: string; [k: string]: unknown },
+): number {
+  return timestampMs(readField(entry, 'timestamp')) ?? timestampMs(readField(message, 'timestamp')) ?? 0
+}
+
+function timestampMs(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value !== 'string' || value === '') return null
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
 function* readThinkingEvents(content: unknown, ts: number): Iterable<InspectEvent> {
   if (!Array.isArray(content)) return
   for (const block of content) {

package/src/run/codex-fetch-observer.ts

@@ -0,0 +1,377 @@
+export type CodexFetchObserverLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+}
+
+export type CodexFetchObserverOptions = {
+  logger?: CodexFetchObserverLogger
+  codexHost?: string
+  now?: () => number
+  // Override the default pre-headers (TTFB) deadline applied to the outer
+  // fetch(). When the codex backend silently holds a request without sending
+  // response headers, this is the timer that releases the request so
+  // `pi-coding-agent`'s `_isRetryableError` can retry. Default: 15_000 ms.
+  //
+  // Healthy Codex turns return response headers within ~1s (observed
+  // production p50: ~860ms). The first SSE event (`response.created`) is
+  // emitted before any model work begins and arrives within ~50ms of
+  // headers. Pathological-but-healthy upper bounds: TLS handshake on a cold
+  // connection (~2s), prompt-prefill on a cache miss with large input
+  // (~3s), Cloudflare PoP routing slowness (~2s) — sum ~7s. 15s is ~2x
+  // that, so anything past it is almost certainly the silent-hang failure
+  // mode rather than a real request making progress. False-positive cost
+  // is one retry (~5s extra); false-negative cost is the full Bun socket
+  // deadline (~268s). Aggressive wins.
+  ttfbMs?: number
+  // Override the sliding inter-chunk idle deadline applied to the SSE body
+  // reader. Resets on every chunk; if no bytes arrive within this window the
+  // body stream errors. Default: 300_000 ms, matches `openai/codex`'s Rust CLI
+  // `DEFAULT_STREAM_IDLE_TIMEOUT_MS`. Set to 0 to disable just this timer.
+  idleMs?: number
+  // Schedule fn for tests. Receives (delayMs, callback) and returns a handle
+  // the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
+  scheduler?: TimeoutScheduler
+}
+
+export type TimeoutScheduler = {
+  set: (delayMs: number, cb: () => void) => unknown
+  clear: (handle: unknown) => void
+}
+
+const DEFAULT_CODEX_HOST = 'chatgpt.com'
+const CODEX_PATH_FRAGMENT = '/codex/responses'
+const ENV_DISABLE_OBSERVER = 'TYPECLAW_CODEX_FETCH_OBSERVER'
+const ENV_DISABLE_TIMEOUTS = 'TYPECLAW_CODEX_TIMEOUTS'
+const ENV_TTFB_MS = 'TYPECLAW_CODEX_TTFB_MS'
+const ENV_IDLE_MS = 'TYPECLAW_CODEX_IDLE_MS'
+const DEFAULT_TTFB_MS = 15_000
+const DEFAULT_IDLE_MS = 300_000
+const LOG_PREFIX = '[codex-fetch]'
+
+const defaultScheduler: TimeoutScheduler = {
+  set: (delayMs, cb) => setTimeout(cb, delayMs),
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+const consoleLogger: CodexFetchObserverLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+}
+
+type InstallState = {
+  originalFetch: typeof fetch
+  uninstall: () => void
+}
+
+let installed: InstallState | null = null
+
+// Returns true when the request is for the Codex Responses endpoint and we
+// should attach phase-timing instrumentation. Method check matches the
+// pi-ai provider (only POST hits codex/responses); GETs to the same host
+// (auth probes, etc.) are deliberately ignored.
+function shouldObserve(input: RequestInfo | URL, init: RequestInit | undefined, codexHost: string): boolean {
+  const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
+  if (method !== 'POST') return false
+  let urlString: string
+  if (typeof input === 'string') urlString = input
+  else if (input instanceof URL) urlString = input.toString()
+  else urlString = input.url
+  let parsed: URL
+  try {
+    parsed = new URL(urlString)
+  } catch {
+    return false
+  }
+  if (parsed.hostname !== codexHost) return false
+  return parsed.pathname.includes(CODEX_PATH_FRAGMENT)
+}
+
+function quote(value: string | null): string {
+  if (value === null) return 'null'
+  return `"${value.replace(/"/g, '\\"')}"`
+}
+
+function formatLine(fields: {
+  status: number | null
+  headersMs: number | null
+  firstByteMs: number | null
+  totalMs: number
+  bodyBytes: number
+  retryAfter: string | null
+  requestId: string | null
+  error: string | null
+  cause: string | null
+}): string {
+  return [
+    LOG_PREFIX,
+    `status=${fields.status === null ? 'null' : fields.status}`,
+    `headers_ms=${fields.headersMs === null ? 'null' : fields.headersMs}`,
+    `first_byte_ms=${fields.firstByteMs === null ? 'null' : fields.firstByteMs}`,
+    `total_ms=${fields.totalMs}`,
+    `body_bytes=${fields.bodyBytes}`,
+    `retry_after=${fields.retryAfter === null ? 'null' : fields.retryAfter}`,
+    `request_id=${fields.requestId === null ? 'null' : fields.requestId}`,
+    `error=${quote(fields.error)}`,
+    `cause=${fields.cause === null ? 'null' : fields.cause}`,
+  ].join(' ')
+}
+
+function readEnvMs(name: string, fallback: number): number {
+  const raw = process.env[name]
+  if (raw === undefined || raw === '') return fallback
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback
+  return parsed
+}
+
+type BodyTapConfig = {
+  idleMs: number
+  scheduler: TimeoutScheduler
+}
+
+function attachBodyTimingTap(
+  response: Response,
+  start: number,
+  headersMs: number,
+  status: number,
+  retryAfter: string | null,
+  requestId: string | null,
+  now: () => number,
+  logger: CodexFetchObserverLogger,
+  config: BodyTapConfig,
+): Response {
+  if (response.body === null) {
+    logger.info(
+      formatLine({
+        status,
+        headersMs,
+        firstByteMs: null,
+        totalMs: now() - start,
+        bodyBytes: 0,
+        retryAfter,
+        requestId,
+        error: null,
+        cause: null,
+      }),
+    )
+    return response
+  }
+
+  let firstByteMs: number | null = null
+  let bodyBytes = 0
+  let settled = false
+  let cause: string | null = null
+
+  const settle = (error: string | null) => {
+    if (settled) return
+    settled = true
+    logger.info(
+      formatLine({
+        status,
+        headersMs,
+        firstByteMs,
+        totalMs: now() - start,
+        bodyBytes,
+        retryAfter,
+        requestId,
+        error,
+        cause,
+      }),
+    )
+  }
+
+  const tap = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      if (firstByteMs === null) firstByteMs = now() - start
+      bodyBytes += chunk.byteLength
+      controller.enqueue(chunk)
+    },
+    flush() {
+      settle(null)
+    },
+  })
+
+  const piped = response.body.pipeThrough(tap, { preventCancel: false })
+
+  const idleController = config.idleMs > 0 ? new AbortController() : null
+  let idleHandle: unknown = null
+  const armIdleTimer = () => {
+    if (idleController === null) return
+    if (idleHandle !== null) config.scheduler.clear(idleHandle)
+    idleHandle = config.scheduler.set(config.idleMs, () => {
+      cause = 'idle_timeout'
+      idleController.abort(new Error(`Codex SSE body idle for ${config.idleMs}ms (typeclaw observer timeout)`))
+    })
+  }
+  const disarmIdleTimer = () => {
+    if (idleHandle !== null) {
+      config.scheduler.clear(idleHandle)
+      idleHandle = null
+    }
+  }
+
+  // The idle abort listener is installed exactly once for the lifetime of the
+  // stream and removed in `finally`. Earlier shapes constructed a fresh
+  // `Promise.race` listener per chunk; if `reader.read()` won the race, the
+  // listener was never removed and closures accumulated on the signal across a
+  // long stream. Keeping one shared abort promise bounds the listener count to
+  // 1 regardless of chunk count.
+  const observerBody = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const reader = piped.getReader()
+      armIdleTimer()
+      let abortFired = false
+      let onAbort: (() => void) | null = null
+      const abortPromise = idleController
+        ? new Promise<never>((_, reject) => {
+            onAbort = () => {
+              abortFired = true
+              reject(idleController.signal.reason ?? new Error('idle timeout'))
+            }
+            if (idleController.signal.aborted) onAbort()
+            else idleController.signal.addEventListener('abort', onAbort, { once: true })
+          })
+        : null
+      // Swallow the shared rejection if no race ever observes it (clean stream
+      // end before any timeout). Without this, an aborted-after-close path
+      // could surface as an unhandled rejection on the runtime.
+      abortPromise?.catch(() => {})
+      try {
+        while (true) {
+          const readPromise = reader.read()
+          const result = abortPromise ? await Promise.race([readPromise, abortPromise]) : await readPromise
+          if (abortFired) {
+            reader.cancel(idleController!.signal.reason).catch(() => {})
+            throw idleController!.signal.reason
+          }
+          const { done, value } = result
+          if (done) {
+            disarmIdleTimer()
+            controller.close()
+            return
+          }
+          armIdleTimer()
+          controller.enqueue(value)
+        }
+      } catch (err) {
+        disarmIdleTimer()
+        const message = err instanceof Error ? err.message : String(err)
+        settle(message)
+        controller.error(err)
+      } finally {
+        if (onAbort !== null && idleController !== null && !idleController.signal.aborted) {
+          idleController.signal.removeEventListener('abort', onAbort)
+        }
+        reader.releaseLock()
+      }
+    },
+    cancel(reason) {
+      disarmIdleTimer()
+      const message = reason === undefined ? 'cancelled' : reason instanceof Error ? reason.message : String(reason)
+      settle(message)
+    },
+  })
+
+  return new Response(observerBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  })
+}
+
+export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}): () => void {
+  if (process.env[ENV_DISABLE_OBSERVER] === 'off') {
+    return () => {}
+  }
+  const logger = opts.logger ?? consoleLogger
+  if (installed !== null) {
+    logger.warn(`${LOG_PREFIX} install called but observer already installed; ignoring`)
+    return installed.uninstall
+  }
+
+  const codexHost = opts.codexHost ?? DEFAULT_CODEX_HOST
+  const now = opts.now ?? Date.now
+  const scheduler = opts.scheduler ?? defaultScheduler
+  const timeoutsEnabled = process.env[ENV_DISABLE_TIMEOUTS] !== 'off'
+  const ttfbMs = timeoutsEnabled ? (opts.ttfbMs ?? readEnvMs(ENV_TTFB_MS, DEFAULT_TTFB_MS)) : 0
+  const idleMs = timeoutsEnabled ? (opts.idleMs ?? readEnvMs(ENV_IDLE_MS, DEFAULT_IDLE_MS)) : 0
+  const originalFetch = globalThis.fetch
+
+  const wrappedImpl = async (
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response> => {
+    if (!shouldObserve(input, init, codexHost)) {
+      return originalFetch(input, init)
+    }
+    const start = now()
+
+    let ttfbCause: 'ttfb_timeout' | null = null
+    let ttfbHandle: unknown = null
+    let initWithSignal: RequestInit | undefined = init
+    if (ttfbMs > 0) {
+      const ttfbController = new AbortController()
+      ttfbHandle = scheduler.set(ttfbMs, () => {
+        ttfbCause = 'ttfb_timeout'
+        ttfbController.abort(
+          new Error(`Codex fetch timed out before response headers after ${ttfbMs}ms (typeclaw observer timeout)`),
+        )
+      })
+      const signal = init?.signal ? AbortSignal.any([init.signal, ttfbController.signal]) : ttfbController.signal
+      initWithSignal = { ...init, signal }
+    }
+
+    let response: Response
+    try {
+      response = await originalFetch(input, initWithSignal)
+    } catch (err) {
+      if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
+      const isTtfbAbort = ttfbCause === 'ttfb_timeout'
+      const surfacedError = isTtfbAbort
+        ? new Error(`Codex fetch timed out before response headers after ${ttfbMs}ms (typeclaw observer timeout)`)
+        : err
+      const message = surfacedError instanceof Error ? surfacedError.message : String(surfacedError)
+      logger.info(
+        formatLine({
+          status: null,
+          headersMs: null,
+          firstByteMs: null,
+          totalMs: now() - start,
+          bodyBytes: 0,
+          retryAfter: null,
+          requestId: null,
+          error: message,
+          cause: ttfbCause,
+        }),
+      )
+      throw surfacedError
+    }
+    if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
+    const headersMs = now() - start
+    const retryAfter = response.headers.get('retry-after')
+    const requestId = response.headers.get('x-request-id')
+    return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
+      idleMs,
+      scheduler,
+    })
+  }
+
+  // Preserve any static methods Bun attaches to `globalThis.fetch` (e.g.
+  // `preconnect`) so the wrapper is a drop-in replacement.
+  const wrapped = Object.assign(wrappedImpl, {
+    preconnect: (originalFetch as { preconnect?: (url: string) => void }).preconnect ?? (() => {}),
+  }) as typeof fetch
+
+  globalThis.fetch = wrapped
+
+  const uninstall = () => {
+    if (installed === null) return
+    if (globalThis.fetch === wrapped) {
+      globalThis.fetch = originalFetch
+    }
+    installed = null
+  }
+
+  installed = { originalFetch, uninstall }
+  return uninstall
+}

package/src/run/index.ts

@@ -59,11 +59,12 @@ import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } fr
 
 import { BUNDLED_PLUGINS } from './bundled-plugins'
 import { buildChannelSessionFactory } from './channel-session-factory'
+import { installCodexFetchObserver } from './codex-fetch-observer'
 import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
 
 type BunServer = ReturnType<Server['start']>
 
-export type TuiFactory = (options: TuiOptions) => { run: () => Promise<void> }
+export type TuiFactory = (options: TuiOptions) => { run: () => Promise<unknown> }
 
 export type LoadCronFn = (agentDir: string, options?: { subagents?: SubagentRegistry }) => Promise<LoadCronResult>
 export type SchedulerFactory = (options: { cwd: string; file: CronFile; onFire: (job: CronJob) => void }) => Scheduler
@@ -86,7 +87,7 @@ export type StartAgentOptions = {
 
 export type StartAgentResult = {
   server: BunServer
-  tuiPromise: Promise<void> | null
+  tuiPromise: Promise<unknown> | null
   scheduler: Scheduler | null
   cronConsumer: CronConsumer | null
   subagentConsumer: SubagentConsumer
@@ -113,6 +114,14 @@ export async function startAgent({
 }: StartAgentOptions): Promise<StartAgentResult> {
   const reloadRegistry = new ReloadRegistry()
 
+  // Wrap globalThis.fetch BEFORE any plugin/session/manager construction so
+  // every Codex Responses call from anywhere in the container is observed.
+  // Logs one `[codex-fetch]` line per matched request with phase timings;
+  // never aborts, never retries — purely passive instrumentation while we
+  // investigate the recurring multi-minute Codex stalls (see issue #394).
+  // Opt out with TYPECLAW_CODEX_FETCH_OBSERVER=off.
+  const uninstallCodexFetchObserver = installCodexFetchObserver()
+
   // The host CLI sets TYPECLAW_CONTAINER_NAME when it `docker run`s us. When
   // running outside a typeclaw container (tests, ad-hoc `bun run typeclaw run`
   // outside docker), the env var is absent and the `restart` tool is omitted —
@@ -329,6 +338,7 @@ export async function startAgent({
             signal: abortController.signal,
             runtimeVersion: runtimeVersionOpt.runtimeVersion,
             containerName: containerNameOpt.containerName,
+            sessionFactory,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -542,6 +552,7 @@ export async function startAgent({
       runtimeVersion: CLI_VERSION,
       containerName,
       outbound,
+      sessionFactory,
     })
 
   const server = createServer({
@@ -585,6 +596,7 @@ export async function startAgent({
     subagentCompletionBridge.stop()
     await tunnelManager.stop()
     await channelManager.stop()
+    uninstallCodexFetchObserver()
   }
 
   if (!attachTui) {

package/src/server/command-runner.ts

@@ -1,4 +1,9 @@
-import { createSessionWithDispose, type SessionOrigin } from '@/agent'
+import {
+  createSessionWithDispose,
+  type CreateSessionOptions,
+  type CreateSessionResult,
+  type SessionOrigin,
+} from '@/agent'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -11,6 +16,7 @@ import type {
   SpawnSubagentOptions,
 } from '@/plugin'
 import type { PluginRuntime } from '@/run/plugin-runtime'
+import type { SessionFactory } from '@/sessions'
 
 export type CommandSpawnSubagent = (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 
@@ -29,6 +35,14 @@ export type CommandRunnerOptions = {
   runtimeVersion: string | undefined
   containerName: string | undefined
   outbound: CommandOutbound
+  // Hands a persisted SessionManager to every prompt session spawned from a
+  // plugin command's `ctx.prompt`. Required so the session writes its JSONL
+  // (and therefore its `message.usage`) under sessions/, which is what
+  // `typeclaw usage` and the `bundled-plugins/backup` plugin scan. Without
+  // this every plugin-command LLM call would fall through to
+  // `SessionManager.inMemory()` and never persist usage — see
+  // `runPromptForCommand` below.
+  sessionFactory: SessionFactory
 }
 
 type CommandHandle = {
@@ -166,6 +180,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               containerName: opts.containerName,
               permissions: opts.permissions,
               signal: abortController.signal,
+              sessionFactory: opts.sessionFactory,
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -331,6 +346,8 @@ function writeLine(stream: WritableStream<Uint8Array>, line: string): void {
   void writer.write(new TextEncoder().encode(`${line}\n`)).then(() => writer.releaseLock())
 }
 
+export type CreateSessionForCommand = (options: CreateSessionOptions) => Promise<CreateSessionResult>
+
 export async function runPromptForCommand(args: {
   text: string
   origin: SessionOrigin
@@ -340,6 +357,16 @@ export async function runPromptForCommand(args: {
   containerName: string | undefined
   permissions: PermissionService
   signal: AbortSignal
+  // Persisted-session source. Each call gets a fresh SessionManager so the
+  // resulting JSONL is its own file under sessions/ — the same shape the
+  // cron `prompt` path uses in src/run/index.ts. Passing in-memory here
+  // regresses `typeclaw usage` (see CommandRunnerOptions.sessionFactory).
+  sessionFactory: SessionFactory
+  // Test seam for the agent-session boundary. Production passes the real
+  // `createSessionWithDispose`; tests inject a fake to verify wiring
+  // (specifically: the sessionManager handed off must be persisted, not
+  // in-memory) without booting the full session stack.
+  _createSession?: CreateSessionForCommand
 }): Promise<string> {
   // Mirrors src/agent/multimodal/look-at.ts: spawn a session, prompt, capture
   // the final assistant text, dispose. Unlike look-at we want the FULL agent
@@ -349,9 +376,11 @@ export async function runPromptForCommand(args: {
   // loader (no `systemPromptOverride`).
   const snapshot = args.runtime.get()
   const sessionId = resolveSessionIdForOrigin(args.origin)
-  const { session, dispose } = await createSessionWithDispose({
+  const create = args._createSession ?? createSessionWithDispose
+  const { session, dispose } = await create({
     origin: args.origin,
     permissions: args.permissions,
+    sessionManager: args.sessionFactory.createPersisted(),
     plugins: {
       registry: snapshot.registry,
       hooks: snapshot.hooks,