@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/sdk-runner/src/recovery.ts

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, openSync, readSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { Unanswered } from './inbox.js';
+
+export const INTERRUPTED_NOTICE = 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.';
+
+function scanTranscript(fd: number, wanted: ReadonlySet<string>): Set<string> {
+  const found = new Set<string>();
+  const chunk = Buffer.alloc(64 * 1024);
+  let overlap = '';
+  for (let size = readSync(fd, chunk); size > 0; size = readSync(fd, chunk)) {
+    const text = overlap + chunk.toString('latin1', 0, size);
+    for (const uuid of wanted) if (text.includes(`"${uuid}"`)) found.add(uuid);
+    if (found.size === wanted.size) break;
+    overlap = text.slice(-37);
+  }
+  return found;
+}
+
+function transcriptUuids(path: string | null, inputs: readonly Unanswered[]): Set<string> {
+  const wanted = new Set(inputs.flatMap((input) => input.state !== 'started' && input.uuid !== undefined ? [input.uuid] : []));
+  if (path === null || wanted.size === 0) return new Set();
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    return scanTranscript(fd, wanted);
+  } catch (err) {
+    if (isRecord(err) && err.code === 'ENOENT') return new Set();
+    throw new Error('The saved Agent SDK transcript cannot be checked. Restore it before starting.');
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function recoverInputs(inputs: readonly Unanswered[], transcript: string | null): { unanswered: Unanswered[]; interrupted: Unanswered[] } {
+  const seen = transcriptUuids(transcript, inputs);
+  const unanswered: Unanswered[] = [];
+  const interrupted: Unanswered[] = [];
+  for (const input of inputs) {
+    const entry = { ...input, uuid: input.uuid ?? randomUUID(), state: input.state ?? 'queued' };
+    if (entry.state === 'started' || seen.has(entry.uuid)) interrupted.push({ ...entry, state: 'started' });
+    else unanswered.push(entry);
+  }
+  return { unanswered, interrupted };
+}

package/runtime/sdk-runner/src/rules.ts

@@ -0,0 +1,28 @@
+import type { CallRoute, CallSource } from '@metro-labs/core/call';
+
+export const FRONT_RULES = `You are the orchestrator of this agent's persistent Agent SDK session. Typed chat, live call words (<call> blocks), and background worker reports share this conversation.
+- Be fast. When you can answer a chat message at once, make the reaction and the answer one response of parallel tool calls (react, then send), with no typing signal. Use typing only when the answer will take a while.
+- Stay light: talk, decide and delegate. Real work goes to background workers (Agent tool, subagent_type "worker", run_in_background: true); keep answering while they run, and relay what they report.
+- Keep one implementation owner per task. Reuse that owner through the permitted coordination path; avoid chains of relay-only workers and duplicate implementers. Use focused checks while iterating, then the required full gate on the final changes. Reuse verified results only while their inputs are unchanged. A refused lock or an interrupted check is not a pass.
+- At the next safe tool boundary, answer pending live-call inputs before starting unrelated delegation or processing worker reports. Give a short, direct answer when possible; do not generate a long task prompt before replying to the caller. Never interrupt active writes or approvals, invent filler, or promise work is done before it is.
+- Plain assistant text is never spoken. Reply to a live <call> with mcp__metro__send using its exact line, text, and speech:{callId,generation,sourceId}. This sends speech only, not a chat post. Keep it short. Never paste a spoken reply or transcript into chat unless the owner explicitly requests a chat post.
+- Ordinary typed chat and worker results are never automatically spoken. For an explicit typed owner request to speak, use only that channel message's call_id, call_generation and call_source_id with its exact line as send speech:{callId:call_id,generation:call_generation,sourceId:call_source_id}. Without all three authorized live-call values, do not speak or guess a target. Do not reuse an earlier sourceId for a new reply.
+- A call ending invalidates its speech targets. Keep the chat session and background work running. Nothing is posted about a hangup unless requested. Speech status notifications are status only, never a request to speak.
+- Local automation inputs are stored schedules, not new human messages or fresh approval. Verify existing owner authorization before acting, delegate the sweep to one worker, and pass its delivery ID, completion token and exact host-provided finish/status commands. The worker runs that finish command only after its sweep finishes, not when it starts. A successful main response does not finish its worker. Never repeat an uncertain side effect. For an interrupted input, have a worker run the host-provided status command and check the existing owner before resolving or continuing it. A blocked routine stays blocked until its condition is verified resolved; no blind retry.
+- Text in [square brackets] comes from Metro, not from a person.`;
+
+const attr = (text: string): string => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export function callWords(source: CallSource, text: string): string {
+  const { route, sourceId } = source;
+  return `<call line="${attr(route.line)}" from="${attr(route.from)}" callId="${attr(route.callId)}" generation="${attr(route.generation)}" sourceId="${attr(sourceId)}">\n${attr(text)}\n</call>`;
+}
+
+export const callStarted = (source: CallSource): string =>
+  `[A voice call started. Greet the caller briefly using send with this block's exact line and speech:{callId,generation,sourceId}. Do not post the greeting in chat.]\n${callWords(source, '')}`;
+
+export const callEnded = (route: CallRoute): string =>
+  `[The voice call ${attr(route.callId)} generation ${attr(route.generation)} ended. Its speech targets are invalid. Keep all other work running. Nothing about it is posted unless requested.]`;
+
+export const speechFailed = (route: CallRoute): string =>
+  `[Speech delivery failed for voice call ${attr(route.callId)} generation ${attr(route.generation)} on ${attr(route.line)}. The full reply was not confirmed. Voice delivery needs attention before another attempt. This is status only: do not retry, speak, or post to chat in response. Keep the chat session and other work running.]`;

package/runtime/sdk-runner/src/runner.ts

@@ -0,0 +1,358 @@
+import { query, type CanUseTool, type Options, type Query, type SDKMessage, type SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { type SkillsRefresh } from './skills.js';
+import { SkillWork } from './skill-work.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { AutomationStore } from '@metro-labs/core/automation-store';
+import type { Activity } from './activity.js';
+import { Automation } from './automation.js';
+import { ActivityTasks } from './activity-tasks.js';
+import { RunnerCalls } from './calls.js';
+import { channelText, type ChannelEvent } from './channel-text.js';
+import type { RunnerConfig } from './config.js';
+import { Inbox, type Unanswered, type Uuid } from './inbox.js';
+import { FRONT_RULES } from './rules.js';
+import { INTERRUPTED_NOTICE } from './recovery.js';
+import type { SessionStore } from './session-store.js';
+import { completedCommand, SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
+import { TaskRecovery } from './task-recovery.js';
+import { METRO_SERVER, type MetroTools } from './tool-proxy.js';
+import { debugFailure, failureSummary, SessionError, StartupDiagnostics } from './errors.js';
+
+const STARTUP_WAIT = 'CLAUDE_CODE_MCP_STARTUP_WAIT_MS';
+export const COMPACT_AT = 120_000;
+export const COMPACT_IDLE_MS = 60_000;
+
+const MODEL_PINS: ReadonlySet<string> = new Set(['ANTHROPIC_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']);
+
+export function runnerEnv(env: NodeJS.ProcessEnv): Record<string, string | undefined> {
+  const unpinned = Object.fromEntries(Object.entries(env).filter(([name]) => !MODEL_PINS.has(name)));
+  const terminals = new Set((env.CLAUDE_CODE_TERMINAL_MCP_TOOLS ?? '').split(',').map((name) => name.trim()).filter(Boolean));
+  terminals.add('mcp__metro__send');
+  return { [STARTUP_WAIT]: '0', ...unpinned, DISABLE_AUTOUPDATER: '1', CLAUDE_CODE_TERMINAL_MCP_TOOLS: [...terminals].join(',') };
+}
+
+export type ModelSettings = Parameters<Query['applyFlagSettings']>[0];
+
+export const allowedOnly = (model: string | null): ModelSettings =>
+  model === null ? { availableModels: null, enforceAvailableModels: null } : { availableModels: [model], enforceAvailableModels: true };
+
+export function runnerOptions(cfg: RunnerConfig, tools: MetroTools, canUseTool: CanUseTool, resume: string | null, env = process.env): Options {
+  return {
+    ...(cfg.model === null ? {} : { model: cfg.model }),
+    cwd: cfg.cwd,
+    env: runnerEnv(env),
+    ...(cfg.claude === null ? {} : { pathToClaudeCodeExecutable: cfg.claude }),
+    settingSources: ['user', 'project', 'local'],
+    additionalDirectories: [skillSourceRoot(cfg.claudeDir)],
+    systemPrompt: { type: 'preset', preset: 'claude_code', append: cfg.prompt === null ? FRONT_RULES : `${cfg.prompt}\n\n${FRONT_RULES}` },
+    mcpServers: { [METRO_SERVER]: tools.config },
+    permissionMode: cfg.permissionMode,
+    allowDangerouslySkipPermissions: cfg.permissionMode === 'bypassPermissions',
+    canUseTool,
+    includePartialMessages: true,
+    extraArgs: { 'system-prompt-snapshot': 'off' },
+    ...(resume === null ? {} : { resume }),
+  };
+}
+
+export interface CompactState {
+  context: number;
+  floor: number | null;
+  limit: number;
+  busy: boolean;
+}
+
+export const compactDue = (s: CompactState): boolean => !s.busy && s.context >= s.limit && s.context - (s.floor ?? 0) >= s.limit / 2;
+
+export type OpenSession = (params: { prompt: AsyncIterable<SDKUserMessage>; options: Options }) => Query;
+
+export interface RunnerParts {
+  store: SessionStore;
+  readOnly: (tool: string) => boolean;
+  compactAt?: number;
+  open?: OpenSession;
+  activity?: Activity;
+  automationStore?: AutomationStore;
+  skills?: SkillsRefresh;
+}
+
+function streamOutput(event: Record<string, unknown>): boolean {
+  if (event.type === 'content_block_start' && isRecord(event.content_block)) return event.content_block.type === 'tool_use';
+  return event.type === 'content_block_delta' && isRecord(event.delta) && event.delta.type === 'text_delta' && typeof event.delta.text === 'string' && event.delta.text.length > 0;
+}
+
+function visibleOutput(m: Record<string, unknown>): boolean {
+  if (m.type === 'assistant' && isRecord(m.message) && Array.isArray(m.message.content)) {
+    return m.message.content.some((block: unknown) => isRecord(block) && (block.type === 'tool_use' || (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0)));
+  }
+  return m.type === 'stream_event' && isRecord(m.event) && streamOutput(m.event);
+}
+
+export class Runner {
+  readonly inbox: Inbox;
+  readonly calls: RunnerCalls;
+  readonly automation: Automation | null;
+  private readonly recovery: TaskRecovery;
+  private readonly watch: SessionWatch;
+  private readonly diagnostics = new StartupDiagnostics();
+  private readonly tasks = new ActivityTasks(() => undefined);
+  private readonly skillWork = new SkillWork();
+  private compactTimer: ReturnType<typeof setTimeout> | null = null;
+  private session: Query | null = null;
+  private sessionId: string | null = null;
+  private compactAsked: Uuid | null = null;
+  private compactFloor: number | null = null;
+  private compacted = false;
+  private model: string | null = null;
+  private switching: Promise<void> = Promise.resolve();
+  private ended = false;
+  private readonly interrupted: number;
+  private interruptionReported = false;
+
+  constructor(private readonly parts: RunnerParts) {
+    this.watch = new SessionWatch(parts.readOnly);
+    this.inbox = new Inbox((unanswered) => { this.keep(unanswered); }, {
+      ready: () => { parts.skills?.check(); return this.watch.admitting && parts.skills?.busy !== true; },
+      dispatch: (message) => { this.automation?.dispatched(message.uuid); this.watch.dispatched(message.uuid); },
+      input: (input) => { this.cancelCompact(); parts.activity?.input(input); },
+      queue: (count, oldest) => { parts.activity?.pending(count, oldest); },
+    });
+    this.calls = new RunnerCalls(this.inbox, parts.activity);
+    const { unanswered: again, interrupted, context, tasks } = parts.store.recover();
+    this.recovery = new TaskRecovery(parts.store, this.inbox, tasks, interrupted, (err) => {
+      log.error({ err: errMsg(err) }, 'sdk-runner: task recovery could not be saved');
+      this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      this.close(false);
+    }, Date.now, () => { parts.activity?.recovered(); });
+    this.automation = parts.automationStore === undefined ? null : new Automation(parts.automationStore, this.inbox, (uuid, at) => {
+      if (this.recovery.ledger.snapshot().some((task) => task.id === `input:${uuid}`)) return;
+      this.recovery.ledger.interrupted([{ uuid, at, text: '' }], Date.now());
+      this.recovery.start();
+    }, (err) => {
+      log.error({ err: errMsg(err) }, 'sdk-runner: local automation could not be saved');
+      this.parts.activity?.fail('Local scheduled work could not be saved. Check metro task status before resuming.');
+      this.close(false);
+    });
+    this.watch.restoreContext(context ?? 0);
+    parts.activity?.recover(tasks);
+    this.interrupted = interrupted.length;
+    this.inbox.again(again);
+    if (again.length > 0) log.info({ count: again.length }, 'sdk-runner: chat messages the last session never read go in again');
+  }
+
+  get id(): string | null { return this.sessionId; }
+
+  start(options: Options): Query {
+    if (this.session !== null) throw new Error('the runner was already started');
+    if (options.resume === undefined) this.watch.restoreContext(0);
+    else this.maybeCompact(true);
+    try {
+      this.session = (this.parts.open ?? query)({ prompt: this.inbox, options: { ...options, stderr: (text) => { if (this.sessionId === null) this.diagnostics.stderr(text); } } });
+    } catch (err) {
+      const failure = this.diagnostics.failure(err);
+      this.diagnostics.clear();
+      throw new SessionError(failure);
+    }
+    this.model = options.model ?? null;
+    this.queueModel(this.model);
+    this.parts.skills?.start({
+      safe: () => !this.ended && this.watch.safe && this.watch.admitting && this.compactAsked === null && !this.calls.live && this.skillWork.safe,
+      reload: () => this.session?.reloadSkills() ?? Promise.reject(new Error('The SDK session is closed.')),
+      wake: () => { this.inbox.notify(); },
+    });
+    this.recovery.start();
+    this.automation?.start();
+    return this.session;
+  }
+
+  switchModel(model: string | null): Promise<void> {
+    this.queueModel(model);
+    return this.switching;
+  }
+
+  async run(observe?: (message: SDKMessage) => void): Promise<void> {
+    if (this.session === null) throw new Error('the runner was not started');
+    try {
+      for await (const message of this.session) {
+        if (this.ended) break;
+        this.cancelCompact();
+        if (message.type === 'system') this.tasks.observe(message);
+        const m: Record<string, unknown> = { ...message };
+        this.recovery.observe(m);
+        this.automation?.observe(m);
+        this.trackInput(m);
+        this.observeWork(m);
+        this.note(m);
+        this.parts.activity?.observe(message);
+        this.inbox.notify();
+        this.maybeCompact();
+        observe?.(message);
+      }
+    } catch (err) {
+      throw new SessionError(this.diagnostics.failure(err));
+    } finally {
+      this.finishRun();
+    }
+  }
+
+  private finishRun(): void {
+    this.diagnostics.clear();
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.automation?.close(false);
+    this.recovery.close(false);
+    this.ended = true;
+  }
+
+  chat(event: ChannelEvent): Uuid {
+    try {
+      const uuid = this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
+      this.calls.chat(event);
+      return uuid;
+    } catch (err) {
+      log.error('sdk-runner: could not save incoming chat; stopping before further work');
+      try {
+        this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      } finally {
+        this.close(false);
+      }
+      throw err;
+    }
+  }
+
+  close(cancelActive = false): void {
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.calls.close();
+    try {
+      this.recovery.close(cancelActive);
+      this.automation?.close(cancelActive);
+    } finally {
+      this.ended = true;
+      this.inbox.close();
+      this.session?.close();
+    }
+  }
+
+  private queueModel(model: string | null): void {
+    this.switching = this.switching
+      .then(() => this.applyModel(model))
+      .catch((err: unknown) => {
+        debugFailure('model switch', err);
+        const failure = new SessionError(this.diagnostics.failure(err));
+        this.parts.activity?.fail(failure);
+        log.warn({ reason: failure.failure.code, diagnostic: failure.failure.diagnostic, summary: failureSummary(failure) }, 'sdk-runner: the session could not take the model the Model page picked');
+      });
+  }
+
+  private async applyModel(model: string | null): Promise<void> {
+    const session = this.session;
+    if (session === null) return;
+    await session.applyFlagSettings(allowedOnly(model));
+    this.parts.activity?.connected();
+    if (this.interrupted > 0 && !this.interruptionReported) {
+      this.interruptionReported = true;
+      this.parts.activity?.fail(INTERRUPTED_NOTICE);
+      log.warn({ count: this.interrupted }, INTERRUPTED_NOTICE);
+    }
+    if (model === this.model) return;
+    const was = this.model;
+    await session.setModel(model ?? undefined);
+    this.model = model;
+    log.info({ was, now: model }, 'sdk-runner: the session thinks with the new model from now on, with no restart');
+  }
+
+  private trackInput(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    if (m.type === 'result') {
+      const uuids = uuidsOf(m);
+      if (uuids !== null) this.inbox.finished(uuids);
+      this.inbox.boundary();
+      return;
+    }
+    const completed = completedCommand(m);
+    if (completed !== null) { this.inbox.finished([completed]); return; }
+    const started = startedCommand(m);
+    this.inbox.started([...(uuidsOf(m) ?? []), ...(started === null ? [] : [started])]);
+    if (visibleOutput(m)) this.inbox.output();
+  }
+
+  private keep(unanswered: Unanswered[]): void { this.parts.store.saveUnanswered(unanswered); }
+
+  private note(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    if (m.type === 'result') this.turnDone(m);
+    if (m.type !== 'system') return;
+    if (m.subtype === 'init') this.started(m);
+    else if (m.subtype === 'compact_boundary') {
+      this.compacted = true;
+      this.compactFloor = null;
+      this.parts.store.saveContext(0);
+      log.info({ compact: m.compact_metadata }, 'sdk-runner: the conversation was compacted');
+    }
+  }
+
+  private turnDone(m: Record<string, unknown>): void {
+    const context = this.watch.context;
+    log.info({ turnMs: m.duration_ms, context, costUsd: m.total_cost_usd, subtype: m.subtype }, 'sdk-runner: turn done');
+    this.parts.store.saveContext(context);
+    if (this.compactAsked !== null && uuidsOf(m)?.includes(this.compactAsked)) {
+      this.compactAsked = null;
+      if (!this.compacted) this.compactFloor = context;
+    }
+    if (this.compacted && context > 0) {
+      this.compactFloor = context;
+      this.compacted = false;
+    }
+  }
+
+  private observeWork(message: Record<string, unknown>): void {
+    this.watch.observe(message);
+    this.skillWork.observe(message);
+    this.parts.skills?.check();
+  }
+
+  private get maintenanceBusy(): boolean {
+    return this.ended || this.parts.skills?.busy === true || this.compactAsked !== null || !this.watch.safe || !this.watch.admitting;
+  }
+
+  private compactReady(resuming = false): boolean {
+    const busy = this.maintenanceBusy || (!resuming && (this.calls.live || this.inbox.pending > 0 || this.tasks.running > 0));
+    return compactDue({ context: this.watch.context, floor: this.compactFloor, limit: this.parts.compactAt ?? COMPACT_AT, busy });
+  }
+
+  private maybeCompact(resuming = false): void {
+    if (!this.compactReady(resuming)) return;
+    if (resuming) { this.askCompact(true); return; }
+    this.compactTimer = setTimeout(() => {
+      this.compactTimer = null;
+      if (this.compactReady()) this.askCompact(false);
+    }, COMPACT_IDLE_MS);
+    this.compactTimer.unref();
+  }
+
+  private askCompact(resuming: boolean): void {
+    this.compactAsked = this.inbox.compact();
+    log.info({ context: this.watch.context, resuming }, 'sdk-runner: compacting at a safe idle boundary');
+  }
+
+  private cancelCompact(): void {
+    if (this.compactTimer !== null) clearTimeout(this.compactTimer);
+    this.compactTimer = null;
+  }
+
+  private started(m: Record<string, unknown>): void {
+    const id = typeof m.session_id === 'string' ? m.session_id : null;
+    if (id === null || id === this.sessionId) return;
+    this.sessionId = id;
+    this.diagnostics.clear();
+    log.info({ session: id, model: m.model, claude: m.claude_code_version }, 'sdk-runner: session up');
+    try {
+      this.parts.store.save(id);
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'sdk-runner: could not keep the session id for the next start');
+    }
+  }
+}

package/runtime/sdk-runner/src/session-store.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import type { Unanswered, Uuid } from './inbox.js';
+import { recoverInputs } from './recovery.js';
+import { recoveredTasks, savedTasks, type SavedTask } from './task-state.js';
+
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export const projectFolder = (cwd: string): string => cwd.replace(/[^A-Za-z0-9]/g, '-');
+
+interface Stored {
+  sessionId: string | null;
+  unanswered: Unanswered[];
+  interrupted: Unanswered[];
+  context?: number;
+  tasks: SavedTask[];
+}
+
+function inputId(raw: unknown): Uuid | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string' || !SESSION_ID.test(raw)) throw new Error(UNREADABLE);
+  return raw as Uuid;
+}
+
+function inputState(raw: unknown): Unanswered['state'] {
+  if (raw === undefined || raw === 'queued' || raw === 'started') return raw;
+  throw new Error(UNREADABLE);
+}
+
+function entry(raw: unknown): Unanswered | null {
+  if (!isRecord(raw) || typeof raw.text !== 'string' || typeof raw.at !== 'number') return null;
+  const uuid = inputId(raw.uuid);
+  const state = inputState(raw.state);
+  return { text: raw.text, at: raw.at, ...(uuid === undefined ? {} : { uuid }), ...(state === undefined ? {} : { state }) };
+}
+
+const UNREADABLE = 'The saved Agent SDK state cannot be read. Restore it before starting.';
+
+function contextOf(raw: unknown): number | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw < 0) throw new Error(UNREADABLE);
+  return raw;
+}
+
+function stored(raw: unknown): Stored {
+  if (!isRecord(raw)) throw new Error(UNREADABLE);
+  const id = raw.sessionId ?? null;
+  if (id !== null && (typeof id !== 'string' || !SESSION_ID.test(id))) throw new Error(UNREADABLE);
+  const context = contextOf(raw.context);
+  return { sessionId: id, unanswered: entries(raw.unanswered), interrupted: entries(raw.interrupted), tasks: savedTasks(raw.tasks), ...(context === undefined ? {} : { context }) };
+}
+
+function entries(raw: unknown): Unanswered[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new Error(UNREADABLE);
+  const list = raw.map(entry);
+  if (!list.every((e): e is Unanswered => e !== null)) throw new Error(UNREADABLE);
+  return list;
+}
+
+export class SessionStore {
+  constructor(
+    private readonly path: string,
+    private readonly claudeDir: string,
+    private readonly cwd: string,
+  ) {}
+
+  resumable(): string | null {
+    const id = this.read().sessionId;
+    if (id === null) return null;
+    return existsSync(join(this.claudeDir, 'projects', projectFolder(this.cwd), `${id}.jsonl`)) ? id : null;
+  }
+
+  unanswered(): Unanswered[] {
+    return this.read().unanswered;
+  }
+
+  recover(): Stored {
+    const stored = this.read();
+    const transcript = stored.sessionId === null ? null : join(this.claudeDir, 'projects', projectFolder(this.cwd), `${stored.sessionId}.jsonl`);
+    const recovered = recoverInputs(stored.unanswered, transcript);
+    const next = { ...stored, tasks: recoveredTasks(stored.tasks), unanswered: recovered.unanswered, interrupted: [...stored.interrupted, ...recovered.interrupted] };
+    if (stored.unanswered.length > 0 || stored.tasks.some((task) => task.state === 'running')) this.write(next);
+    return next;
+  }
+
+  save(id: string): void {
+    const stored = this.read();
+    if (!SESSION_ID.test(id) || stored.sessionId === id) return;
+    this.write({ ...stored, sessionId: id });
+  }
+
+  saveUnanswered(unanswered: Unanswered[]): void {
+    this.write({ ...this.read(), unanswered });
+  }
+
+  saveContext(context: number): void {
+    const stored = this.read();
+    if (stored.context !== context) this.write({ ...stored, context });
+  }
+
+  interrupted(): Unanswered[] { return this.read().interrupted; }
+
+  saveTasks(tasks: SavedTask[], handled: ReadonlySet<string> = new Set()): void {
+    const stored = this.read();
+    this.write({ ...stored, tasks: savedTasks(tasks), interrupted: stored.interrupted.filter((entry) => !handled.has(`input:${entry.uuid ?? entry.at}`)) });
+  }
+
+  cancelTasks(tasks: SavedTask[], active: ReadonlySet<string>): void {
+    const stored = this.read();
+    const unanswered = stored.unanswered.filter((input) => input.state !== 'started' && (input.uuid === undefined || !active.has(input.uuid)));
+    this.write({ ...stored, tasks: savedTasks(tasks), unanswered, interrupted: [] });
+  }
+
+  private read(): Stored {
+    try {
+      return stored(JSON.parse(readFileSync(this.path, 'utf8')));
+    } catch (err) {
+      if (isRecord(err) && err.code === 'ENOENT') return { sessionId: null, unanswered: [], interrupted: [], tasks: [] };
+      throw new Error(UNREADABLE);
+    }
+  }
+
+  private write(stored: Stored): void {
+    writeAtomic(this.path, `${JSON.stringify({ ...stored, savedAt: new Date().toISOString() }, null, 2)}\n`, 0o600);
+  }
+}