Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

53.7 KB
Raw Blame
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join, posix } from 'node:path';
import { type DriveContext, type Harness, type HostTool, type ReplayPolicy, Restart, type SessionState, type Submission, Unavailable } from 'harness-world';
import {
  BuiltinCalls,
  CLAUDE_ROUTES,
  type GatewayCap,
  gatewayCredential,
  type GatewayHandler,
  gatewayHandler,
  gatewayUrl,
  isBrandedMachine,
  journalLedger,
  ModelSteps,
  NativeJournal,
  openTurn,
  placeSubmissions,
  type ProviderTool,
  recoveryNote,
  restartEvent,
  replayBy,
  type SessionMachine,
  type SessionProcess,
  settleAbandonedModelSteps,
  toolBridge,
  waitForSubmissions,
  zodShapeFromJsonSchema,
} from 'harness-world-process';
import { durableEnv, nativeModelId } from './env.ts';
import { uuidFrom } from './ids.ts';
import { MessageQueue } from './inbox.ts';
import { sandboxSpawn } from './spawn.ts';
import { JournalSessionStore } from './store.ts';
import { MCP_SERVER, TranscriptBuilder, type TurnEnd } from './transcript.ts';
import { assertAgentSdkVersion, CLAUDE_VM_EXECUTABLE } from './versions.ts';

/**
 * Claude Code on harness-world: a kernel `Harness` that drives the Claude
 * Agent SDK's `query()` in the drive (in the Function), with the `claude` CLI
 * as its child **in the session's Vercel Sandbox VM** (docs/workspaces.md
 * §5.6 "Claude Code"), never on the machine that drives the session.
 *
 * Every drive (one queue delivery):
 *
 * 1. returns at once when there is nothing to do (no open turn, nothing
 *    pending): an idle wake attaches no VM;
 * 2. attaches the session's VM through the sandbox tier (`sandbox.attach`:
 *    the `sandbox.attach` fact, the relay armed with the drive's fence) and
 *    refuses any machine the session factory didn't make (`isBrandedMachine`:
 *    `Unavailable('sandbox_required')`);
 * 3. starts `query()` with streaming input: a resume of the session the log
 *    holds (the SDK `load()`s the transcript from the journal; `sandboxSpawn`
 *    uploads only its `projects/**` into the VM), or a new session whose id
 *    is derived from the run;
 * 4. mirrors every transcript line the CLI writes into the journal (the
 *    SDK's `sessionStore`, flushed eagerly; `sandboxSpawn` maps the VM's
 *    paths to the Function's, on the trusted side);
 * 5. if the last turn never ended, opens with the recovery note; places each
 *    submission, then sends it (steers go in mid-turn, at priority `next`);
 *    serves the app's tools (an in-process MCP server, in the Function) and
 *    records each built-in call through the hooks;
 * 6. writes the normalized transcript and live events, and at each turn's
 *    end a `turn` entry and a flush;
 * 7. closes the input, lets the CLI exit, and kills what is left of the
 *    session's processes in the VM (the VM and the Drive stay).
 *
 * **The model.** The CLI's base URL is the VM's model port, its key the
 * attach's model key (`SessionMachine.modelKey`); every request it sends is
 * relayed to this drive's `gatewayHandler` (Claude's fixed table, the body
 * policy, the model allowlist, the budget, the credential), so the VM never
 * holds a credential (decision 6). The spend is kept in the session's
 * journal (`journalLedger`); a request past `sandbox({ budget })`'s turn or
 * session cap ends the turn at once with an `Unavailable` naming the cap.
 *
 * **Tools.** Tool-less by default: the app's `HostTool`s (`tools`) are the
 * CLI's only tools (`tools: []`), and the system prompt says so. With
 * `builtins`, Claude Code's own tools are on in the VM, on `/workspace` (the
 * session's Drive): `true` is the pinned allowlist `CLAUDE_BUILTINS`, a list
 * names them, the `claude_code` preset brings the CLI's whole set; the
 * ones whose state the transcript does not carry (`CLAUDE_BUILTINS_OFF`) are
 * always off. Each call is recorded through the hooks (`PreToolUse` commits
 * the intent before the call runs, after the assistant entry that made it is
 * in the log; `PostToolUse` / `PostToolUseFailure` the outcome, after the
 * Drive's writes are flushed for a mutating call), so after a crash the
 * recovery note says which calls completed and which were interrupted ("may
 * have half-run"); nothing reruns one. Bash's timeout is clamped to what is
 * left of the invocation, so a command never outlives it: one the clamp ends
 * is recorded as out of time, never left open. Claude Code runs its commands
 * under its own sandbox (bubblewrap, checked by a self-test in the VM before
 * the spawn): writes only to `/workspace` and the temp and home dirs, no read
 * of the CLI's state (`/var/lib/dh/s`), the model key unset in their
 * environment, a pid namespace that hides the CLI's own environ and keeps
 * them from tracing it, and no way to the model port. Where it can't start,
 * the drive fails the turn with an `Unavailable` (`unsandboxedCommands`
 * opts out).
 *
 * **A lost CLI.** When the CLI exits mid-turn (the link to the VM dropped, so
 * the relay killed it, or the VM killed it), the drive is rebuilt from the
 * log in the same delivery (`Restart`): it re-attaches and resumes the turn
 * with the recovery note, a few times per delivery while time is left.
 */

/** The SDK functions the harness calls (the module `@anthropic-ai/claude-agent-sdk`, a peer dependency). */
export type ClaudeAgentSdk = Pick<typeof import('@anthropic-ai/claude-agent-sdk'), 'query' | 'createSdkMcpServer' | 'tool'>;
type QueryOptions = NonNullable<Parameters<ClaudeAgentSdk['query']>[0]['options']>;
type UserMessage = import('@anthropic-ai/claude-agent-sdk').SDKUserMessage;

/** The VM's network, as `sandbox({ network })` says it (durable-harness's `SandboxNetwork`). */
export type ClaudeSandboxNetwork = 'allow-all' | 'deny-all' | { readonly allow: readonly string[] };

/**
 * The session's sandbox, as a kernel harness gets it from the sandbox tier
 * (harness-world-sandbox's `kernelSandbox` over the session factory, with the
 * descriptor's fields; durable-harness builds it from `sandbox()`).
 */
export interface ClaudeSandbox {
  /** Attach the session's VM for this drive (the `sandbox.attach` fact): the branded machine, with `/model` serving `model`. */
  attach(ctx: DriveContext, request: { model?: GatewayHandler; deadline?: number }): Promise<SessionMachine>;
  /**
   * The notes the machine carried (a lost Drive) reached the model in a turn
   * that committed: don't show them again. `key` is what they described
   * (`SessionMachine.notesKey`): a loss recorded since is kept.
   */
  acknowledge?(ctx: DriveContext, key?: string): Promise<void>;
  /** `sandbox({ env })`: non-secret variables for the CLI (checked there, and again at every spawn). */
  readonly env?: Readonly<Record<string, string>>;
  /** `sandbox({ network })`: what the CLI's own sandbox lets commands reach, and whether provider-hosted tools may run. */
  readonly network: ClaudeSandboxNetwork;
  /** `sandbox({ budget })`'s dollar caps (`Infinity` turns one off). */
  readonly budget: { readonly turnUsd: number; readonly sessionUsd: number };
  /** `sandbox({ commandTimeoutMs })`: the longest a Bash command may run. */
  readonly commandTimeoutMs?: number;
  /**
   * The writer of the Drive's manifest for one drive (`hw.sandbox-files`,
   * harness-world-sandbox's `DriveFiles`): told of each mutating built-in as
   * it ends, and asked to catch up once attached and for a snapshot after
   * each turn. Without it the session has no manifest (the Files panel has
   * nothing to show).
   */
  files?(ctx: DriveContext, machine: SessionMachine): ClaudeDriveFiles;
}

/** The Drive manifest's writer for one drive (`ClaudeSandbox.files`): harness-world-sandbox's `DriveFiles`, structurally. */
export interface ClaudeDriveFiles {
  /** A mutating built-in ended: a live event, and the paths it named for the next snapshot. */
  changed(call: { tool: string; callId: string; paths?: readonly string[] }): void;
  /** List first if an earlier invocation ended before its snapshot. Best effort. */
  catchUp(): Promise<void>;
  /** After a turn: list the Drive, if a call may have changed it. Best effort, bounded. */
  snapshot(): Promise<void>;
}

/** `builtins`: off, the pinned allowlist, a list of names, or the CLI's whole preset. */
export type ClaudeBuiltins = boolean | readonly string[] | { readonly type: 'preset'; readonly preset: 'claude_code' };

export interface ClaudeCodeHarnessOptions {
  /**
   * The session's sandbox (required: Claude Code runs only in the session's
   * Vercel Sandbox VM). Without one, or when it hands back a machine the
   * session factory didn't make, a drive fails the turn with
   * `Unavailable('sandbox_required')` (docs/workspaces.md §6 rule 1).
   */
  sandbox?: ClaudeSandbox;
  /**
   * The app's tools, served to Claude Code as an in-process MCP server
   * (`mcp__hands__<name>`) in the Function: each call is a kernel effect
   * keyed by its `tool_use` id, with the tool's own replay policy. Default
   * none.
   */
  tools?: HostTool[];
  /**
   * Claude Code's own tools, in the VM, on `/workspace`. Default false
   * (tool-less: `tools` are the CLI's only tools). `true`: the pinned
   * allowlist `CLAUDE_BUILTINS`; a list: those names; `{ type: 'preset',
   * preset: 'claude_code' }`: the CLI's whole set. `CLAUDE_BUILTINS_OFF` is
   * off whatever this says.
   */
  builtins?: ClaudeBuiltins;
  /** More built-ins to turn off (tool names, added to `CLAUDE_BUILTINS_OFF`). */
  disallowedTools?: string[];
  /**
   * A built-in's replay policy: what the recovery note says about a call a
   * crash interrupted ("safe to repeat", or "may have taken effect"), and
   * whether its outcome waits for the Drive's writes to be flushed (every
   * policy but `safe`). Nothing reruns a built-in either way. Default
   * `claudeBuiltinReplay` (reads safe).
   */
  builtinReplay?: Record<string, ReplayPolicy> | ((name: string) => ReplayPolicy);
  /** Provider-hosted tools the model may use (`web_search`, `web_fetch`); default none; refused with `network: 'deny-all'`. */
  providerTools?: readonly ProviderTool[];
  /**
   * The model, a native Anthropic id (`claude-sonnet-4-5`) or a Gateway one
   * (`anthropic/claude-sonnet-4.5`, passed as its native id: `nativeModelId`).
   * Default `claude-sonnet-4-5`.
   */
  model?: string;
  /** The model of the CLI's small background calls (`nativeModelId` too). Default `model`. */
  smallModel?: string;
  /** Appended to Claude Code's own system prompt (the `claude_code` preset). */
  instructions?: string;
  /** The AI Gateway credential, read per model request, in the Function. Default `gatewayCredential`. */
  credential?: () => Promise<string>;
  /** The Gateway's base URL. Default `gatewayUrl()`. */
  gatewayUrl?: string;
  /** The CLI's path in the VM. Default `CLAUDE_VM_EXECUTABLE` (the base image's pinned build). Tests on the stand-in VM pass the host build. */
  executable?: string;
  /** The kernel name (its sessions' runs are `workflow//durable-harness@<version>//<name>`). Default `claude-code`. */
  name?: string;
  /** The Agent SDK module. Default: `import('@anthropic-ai/claude-agent-sdk')` on the first drive, after its version is checked against the pin. */
  sdk?: ClaudeAgentSdk;
  /** How long a `never` tool waits for its call to reach the log before it is refused. Default 10 s. */
  barrierMs?: number;
  /**
   * Hold mirrored transcript lines this long so they share journal batches
   * (fewer events per turn). A barrier or a turn's end sends them at once.
   * Default 150 ms.
   */
  coalesceMs?: number;
  /** Keep the child this long after a turn, for a follow-up to skip the resume. Default 0. */
  idleMs?: number;
  /** `query()`'s `maxTurns` (model round trips per turn). */
  maxTurns?: number;
  /**
   * Run the CLI's commands without Claude Code's own sandbox where bubblewrap
   * doesn't work in the VM (with `builtins` on). Default false: such a drive
   * fails the turn with an `Unavailable`. Without that sandbox a command runs
   * beside the CLI as the same user: it can read the CLI's environment (the
   * model key) and trace the CLI or take its socket (the VM's kernel has no
   * Yama ptrace restriction, P0.16), so the model port's key and peer check no
   * longer tell the CLI's calls from the model's (the key is then only a
   * correlation id), and nothing hides the CLI's config dir. The VM stays the
   * boundary. For the stand-in VM's tests, and images without user namespaces.
   */
  unsandboxedCommands?: boolean;
  /** Called with the child's stderr tail when it exits mid-turn, the gateway's refusals, and SDK diagnostics. */
  log?: (message: string, fields?: Record<string, unknown>) => void;
}

/** The default model. */
export const DEFAULT_MODEL = 'claude-sonnet-4-5';

/** What the harness appends to the system prompt about the tools, before `instructions`, with the built-ins off and the app's tools there. */
export const TOOLS_NOTE = `Your only tools are this app's, the mcp__${MCP_SERVER}__ tools; you have no shell, file, search or web tools of your own.`;

/** `TOOLS_NOTE` for a session with no tools at all (built-ins off, no `tools`). */
export const NO_TOOLS_NOTE = 'You have no tools in this session: no shell, file, search or web tools. Answer from the conversation.';

/** With the built-ins on (docs/workspaces.md §5.6 "Workspace note"): what `/workspace` is. */
export const DRIVE_NOTE =
  'Your working directory, /workspace, is this session\'s own disk: files there are durable (they stay for later turns, on any machine) but not transactional: a command that a crash interrupted may have half-run, so check before you repeat one. Commands end with this turn: nothing keeps running in the background.';

/**
 * Built-ins that stay off whatever `builtins` says: their state lives in the
 * CLI process or its local files, which the transcript the log carries does
 * not hold (cron jobs, scheduled wakeups, worktrees, agent teams and their
 * messages, background shells, workflows, the task list, P0.17: 2.1.296
 * keeps it in the config dir), or they wait for a user who is not there
 * (questions, plan mode).
 */
export const CLAUDE_BUILTINS_OFF = [
  'CronCreate',
  'CronDelete',
  'CronList',
  'ScheduleWakeup',
  'EnterWorktree',
  'ExitWorktree',
  'ListAgents',
  'SendMessage',
  'TaskCreate',
  'TaskGet',
  'TaskList',
  'TaskUpdate',
  'TaskStop',
  'TodoWrite',
  'Workflow',
  'ReportFindings',
  'Monitor',
  'BashOutput',
  'KillShell',
  'AskUserQuestion',
  'EnterPlanMode',
  'ExitPlanMode',
  // Subagents (the `claude_code` preset): their sidechains' resume across VMs is not proven yet (§11.4 R7).
  'Task',
  'Agent',
];

/**
 * `builtins: true`: the pinned allowlist, the tools Claude Code 2.1.296 has
 * (its `system/init` list, checked by a test) that act on `/workspace` and
 * whose state is in the transcript. The design's Glob, Grep and TodoWrite are
 * not tools of this CLI (it searches through Bash, and its task list is off,
 * P0.17); WebSearch is provider-hosted (`providerTools`).
 */
export const CLAUDE_BUILTINS = ['Bash', 'Read', 'Edit', 'Write', 'NotebookEdit', 'WebFetch'] as const;

/** Built-ins that only read: "safe to repeat" after a crash, and no flush before their outcome. Everything else: "may have taken effect". */
export const CLAUDE_SAFE_BUILTINS = ['Read', 'Glob', 'Grep', 'LS', 'NotebookRead', 'WebFetch', 'WebSearch', 'ToolSearch', 'Skill'];

/** The default `builtinReplay`. */
export const claudeBuiltinReplay = replayBy(CLAUDE_SAFE_BUILTINS);

/** What a Bash command keeps of the invocation for its outcome to be recorded and the drive to end (the kernel's end-of-drive margin is 15 s). */
const BASH_MARGIN_MS = 20_000;
/** The shortest clamped Bash timeout worth running: past it, the call is refused before it runs. */
const BASH_MIN_MS = 1_000;
/** The invocation assumed when the kernel gives no deadline (a hand-written context): a Vercel Function's default maximum duration, the shortest likely one. */
const ASSUMED_INVOCATION_MS = 300_000;
/** How often one delivery rebuilds a drive whose CLI exited mid-turn (the kernel fails the session at 8). */
const CLI_RESTARTS = 3;
/** What a rebuilt drive needs of the invocation to be worth starting: else the delivery fails, and the queue redelivers. */
const RESTART_MIN_LEFT_MS = 60_000;
/** Where the built-in file tools may not write (they run in the CLI, outside Claude's sandbox): the repo's and Claude's config on the Drive. */
const PROTECTED_DIRS = ['.git', '.claude'];
/** The file tools' path inputs. */
const FILE_TOOLS: Readonly<Record<string, string>> = { Write: 'file_path', Edit: 'file_path', MultiEdit: 'file_path', NotebookEdit: 'notebook_path' };
/** What the model hears beside a call whose writes the Drive didn't confirm. */
const NOT_FLUSHED_NOTE = "The session's disk didn't confirm this call's writes: they may not have reached it. Check the files before relying on them.";

/** The `builtins` option, resolved: the `tools` option for `query()` (undefined: the preset, all of them). */
export function builtinTools(builtins: ClaudeBuiltins | undefined): string[] | undefined {
  if (builtins === undefined || builtins === false) return [];
  if (builtins === true) return [...CLAUDE_BUILTINS];
  if (Array.isArray(builtins)) {
    if (!builtins.every((b) => typeof b === 'string' && /^[A-Za-z][A-Za-z0-9_]*$/.test(b))) throw new TypeError('harness-world-claude-code: builtins takes tool names (Bash, Read, ...)');
    return [...builtins];
  }
  const preset = builtins as { type?: unknown; preset?: unknown };
  if (preset.type === 'preset' && preset.preset === 'claude_code') return undefined;
  throw new TypeError("harness-world-claude-code: builtins takes true, a list of tool names, or { type: 'preset', preset: 'claude_code' }");
}

/** The Claude Code sandbox settings for the VM (§5.5 "Claude Code runs under its own sandbox"; P0.10, P0.16). */
export function claudeSandboxSettings(machine: Pick<SessionMachine, 'root' | 'dirs'>, network: ClaudeSandboxNetwork): NonNullable<QueryOptions['sandbox']> {
  const { dirs } = machine;
  const open = [dirs.tmp, dirs.home, dirs.cache];
  return {
    enabled: true,
    failIfUnavailable: true,
    allowUnsandboxedCommands: false,
    filesystem: { allowWrite: [machine.root, ...open], denyRead: [dirname(dirs.config)], allowRead: open },
    credentials: { envVars: [{ name: 'ANTHROPIC_AUTH_TOKEN', mode: 'deny' }] },
    network: {
      ...(network === 'allow-all' ? { allowedDomains: ['*'] } : network === 'deny-all' ? { allowedDomains: [], strictAllowlist: true } : { allowedDomains: [...network.allow], strictAllowlist: true }),
      // The model port is the CLI's alone: never through the sandbox's proxy (the loopback names and literals it takes;
      // a public name that resolves to loopback still gets past, and then meets the port's key).
      deniedDomains: [...LOOPBACK_NAMES],
    },
  } as NonNullable<QueryOptions['sandbox']>;
}

/** Loopback, as names and literals a command could hand the sandbox's proxy for the model port. */
export const LOOPBACK_NAMES = ['localhost', 'localhost.', '127.0.0.1', '127.1', '0.0.0.0', '0', '2130706433', '::1', '[::1]', '::ffff:127.0.0.1', '[::ffff:127.0.0.1]', '::', '[::]'];

/** The bwrap self-test (P0.10): what Claude Code's sandbox needs of the VM, as the unprivileged user. */
const BWRAP_SELF_TEST = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--unshare-pid', '--unshare-net', '--die-with-parent', 'true'];

/** Whether bubblewrap works in the VM as the agent (a fresh `/proc` in a pid namespace, no network): Claude Code's sandbox can start. */
async function bwrapWorks(machine: SessionMachine, signal: AbortSignal): Promise<boolean> {
  try {
    const proc = await machine.spawn({ command: 'bwrap', args: BWRAP_SELF_TEST, signal });
    const timer = setTimeout(() => proc.kill('SIGKILL'), 10_000);
    const exit = await proc.exited;
    clearTimeout(timer);
    return exit.code === 0;
  } catch {
    return false;
  }
}

export function claudeCodeHarness(options: ClaudeCodeHarnessOptions = {}): Harness {
  const tools = options.tools ?? [];
  const allowed = builtinTools(options.builtins);
  const builtinsOn = allowed === undefined || allowed.length > 0;
  const model = nativeModelId(options.model ?? DEFAULT_MODEL);
  const smallModel = options.smallModel ? nativeModelId(options.smallModel) : undefined;
  const barrierMs = options.barrierMs ?? 10_000;
  const executable = options.executable ?? CLAUDE_VM_EXECUTABLE;
  const replay = typeof options.builtinReplay === 'function' ? options.builtinReplay : options.builtinReplay ? (name: string) => (options.builtinReplay as Record<string, ReplayPolicy>)[name] ?? claudeBuiltinReplay(name) : claudeBuiltinReplay;
  const providerTools = options.providerTools ?? [];
  const log = options.log ?? (() => {});
  let sdk: Promise<ClaudeAgentSdk> | undefined;
  const loadSdk = (): Promise<ClaudeAgentSdk> => {
    if (!sdk) {
      // The installed SDK must be the pinned one (pnpm only warns on a peer mismatch); a failed load is tried again on the next drive.
      const loading: Promise<ClaudeAgentSdk> = options.sdk
        ? Promise.resolve(options.sdk)
        : Promise.resolve().then(() => {
            assertAgentSdkVersion();
            return import('@anthropic-ai/claude-agent-sdk');
          });
      sdk = loading;
      loading.catch(() => (sdk = undefined));
    }
    return sdk;
  };

  return {
    name: options.name ?? 'claude-code',
    // Each model request reaches Agent Runs from the Gateway proxy (`ModelSteps.request`).
    modelCalls: 'self',
    async drive(ctx: DriveContext) {
      // Nothing to do (an idle wake, a chaos arming): no VM. A model step a
      // crash left open after its turn ended is closed (no request will retry it).
      if (!recoveryNote(ctx.state()) && ctx.pending().length === 0) {
        await settleAbandonedModelSteps(ctx);
        return;
      }
      const sandbox = options.sandbox;
      if (!sandbox) throw sandboxRequired();
      const [{ query, createSdkMcpServer, tool }, { z }] = await Promise.all([loadSdk(), import('zod')]);
      const journal = new NativeJournal(ctx);
      const records = await journal.read();
      const store = new JournalSessionStore(journal, { records, coalesceMs: options.coalesceMs ?? 150 });
      // The handler reads the credential per request, in the drive's async
      // context: on a Vercel Function the OIDC token comes from the request
      // that started the drive.
      const inDrive = AsyncLocalStorage.snapshot();
      const credential = options.credential ?? gatewayCredential;
      // The handler also sees each model request start and end: the drive's
      // model steps, written around a "Crash during: model" drill.
      const steps = new ModelSteps(ctx, options.log ? { log: options.log } : {});
      const ledger = journalLedger(journal, { records });
      if (ctx.deadline === undefined) log('claude-code: the kernel gave no deadline; assuming a 300 s invocation', {});
      const deadline = ctx.deadline ?? Date.now() + ASSUMED_INVOCATION_MS;
      const handler = gatewayHandler({
        routes: CLAUDE_ROUTES,
        models: { model, ...(smallModel ? { smallModel } : {}) },
        budget: sandbox.budget,
        ledger,
        providerTools,
        network: sandbox.network === 'allow-all' || sandbox.network === 'deny-all' ? sandbox.network : 'custom',
        credential: () => inDrive(credential),
        target: options.gatewayUrl ?? gatewayUrl(),
        track: steps.request,
        onCap: (cap) => {
          if (cap !== 'concurrency') ctx.halt?.(spendCapped(cap));
        },
        // Without the app's own log, the handler's default: a refused model call is a warning in the Function's logs, not silence.
        ...(options.log ? { log: (message: string, fields?: Record<string, unknown>) => log(`claude-code gateway: ${message}`, fields) } : {}),
      });

      const abort = new AbortController();
      const stop = () => abort.abort(ctx.signal.reason);
      ctx.signal.addEventListener('abort', stop, { once: true });
      /** What the attach handed back (closed when the drive ends, branded or not), and the Function's side of the CLI's config dir. */
      let held: SessionMachine | undefined;
      let configDir: string | undefined;
      try {
        const machine = (held = await sandbox.attach(ctx, { model: handler, deadline }));
        if (!isBrandedMachine(machine)) throw sandboxRequired();

        // The Function's side of the CLI's config dir: empty, 0700, this drive's.
        // The SDK's resume copies nothing from it (no credentials, no settings),
        // and the mirror's paths are mapped to it.
        configDir = await mkdtemp(join(tmpdir(), 'dh-claude-'));
        let proc: SessionProcess | undefined;
        // What the model must hear once (a lost Drive), in the drive's first message, and what it described (to acknowledge exactly that).
        let notes = machine.notes.length ? machine.notes.join('\n\n') : undefined;
        let noteSent = false;
        // The Drive's manifest: what the Files panel shows, kept in the log so it reads with no VM.
        const driveFiles = sandbox.files?.(ctx, machine);

        // Claude Code's own sandbox (P0.10): bubblewrap must work in the VM. A failed self-test is tried once more (a slow relay, a timeout).
        const ownSandbox = builtinsOn && ((await bwrapWorks(machine, ctx.signal)) || (await bwrapWorks(machine, ctx.signal)));
        if (builtinsOn && !ownSandbox) {
          if (ctx.signal.aborted) throw ctx.signal.reason;
          if (!options.unsandboxedCommands) throw noCommandSandbox();
          log("claude-code: bubblewrap doesn't work in this VM: the CLI's commands run without its sandbox (unsandboxedCommands; the VM is the boundary, the model key only a correlation id)");
        }

        /**
         * Tool calls the MCP server is running. The drive never returns with
         * one in flight: if the CLI dies mid-call, the call still runs to its
         * outcome in this process, and that outcome lands before the next
         * delivery reads the log.
         */
        const calls = new Set<Promise<unknown>>();
        const input = new MessageQueue<UserMessage>();
        /** User messages sent and not yet consumed by a turn (by `uuid`). */
        const outstanding = new Set<string>();
        const transcript = new TranscriptBuilder({ message: (e) => store.message(e), live: (e) => ctx.live(e) });
        const bridge = toolBridge(ctx, tools, {
          // A `never` tool runs only once the assistant entry that asked for it is in the log.
          beforeNever: ({ callId }) => store.barrier(callId, barrierMs),
        });
        // The built-ins: each call an intent before it runs, its outcome after (the hooks below).
        const builtins = new BuiltinCalls(ctx, { replay, beforeNever: ({ callId }) => store.barrier(callId, barrierMs), live: true });
        /** Bash calls whose timeout the invocation clamped: their outcome, if it timed out, says so. */
        const clamped = new Map<string, number>();
        const bridged = (name: string) => name.startsWith(`mcp__${MCP_SERVER}__`);
        const server = createSdkMcpServer({
          name: MCP_SERVER,
          version: '1.0.0',
          tools: bridge.tools.map((t) =>
            tool(t.name, t.description, zodShapeFromJsonSchema(t.inputSchema, z), async (args, extra) => {
              const callId = (extra as { _meta?: Record<string, unknown> } | undefined)?._meta?.['claudecode/toolUseId'];
              if (typeof callId !== 'string') return errorResult(`${t.name} was not run: the call carries no tool_use id`);
              await transcript.beforeCall(callId, t.name);
              const running = t.call(args, callId);
              calls.add(running);
              try {
                const result = await running;
                return { content: [{ type: 'text' as const, text: result.text }], ...(result.isError ? { isError: true } : {}) };
              } catch (err) {
                // The barrier timed out (nothing ran), or the drive stopped (the bridge halted it).
                return errorResult(`${t.name} was not run: ${(err as Error)?.message ?? String(err)}`);
              } finally {
                calls.delete(running);
              }
            })
          ),
        });

        const allow = (updatedInput?: Record<string, unknown>) => ({ hookSpecificOutput: { hookEventName: 'PreToolUse' as const, permissionDecision: 'allow' as const, ...(updatedInput ? { updatedInput } : {}) } });
        const deny = (reason: string) => ({ hookSpecificOutput: { hookEventName: 'PreToolUse' as const, permissionDecision: 'deny' as const, permissionDecisionReason: reason } });
        /**
         * A mutating call's writes reach the Drive before its outcome is
         * recorded (a timed-out Bash may have written). Returns why the flush
         * failed, if it did: that outcome is then committed as failed, saying
         * its writes may not be on the Drive (never as a plain success).
         */
        /** A mutating built-in ended: the Drive's manifest hears of it (a live event, and the file it named). */
        const changed = (name: string, callId: string, input: unknown) => {
          if (replay(name) === 'safe' || !driveFiles) return;
          const field = FILE_TOOLS[name];
          const path = field ? (input as Record<string, unknown> | undefined)?.[field] : undefined;
          driveFiles.changed({ tool: name, callId, ...(typeof path === 'string' ? { paths: [path] } : {}) });
        };
        const flushed = async (name: string): Promise<string | undefined> => {
          if (replay(name) === 'safe') return undefined;
          try {
            await machine.fsync();
            return undefined;
          } catch (err) {
            const why = String((err as Error)?.message ?? err).slice(0, 200);
            log('claude-code: the Drive flush after a built-in failed', { name, error: why });
            return why;
          }
        };
        const hooks: QueryOptions['hooks'] = {
          // Every built-in call commits its intent before it runs. Fails
          // closed: a hook that throws lets the tool run, so every error here
          // is a deny.
          PreToolUse: [
            {
              hooks: [
                async (hook) => {
                  try {
                    if (hook.hook_event_name !== 'PreToolUse' || bridged(hook.tool_name)) return {};
                    if (ctx.signal.aborted) return deny('the session stopped');
                    let updated: Record<string, unknown> | undefined;
                    const field = FILE_TOOLS[hook.tool_name];
                    if (field) {
                      const target = (hook.tool_input as Record<string, unknown> | undefined)?.[field];
                      if (typeof target === 'string' && protectedPath(machine.root, target)) return deny(`Not run: ${PROTECTED_DIRS.join(' and ')} on /workspace are not written by the file tools in this session.`);
                    }
                    if (hook.tool_name === 'Bash') {
                      const bash = (hook.tool_input ?? {}) as Record<string, unknown>;
                      if (bash.run_in_background === true) return deny('Not run: commands can\'t run in the background in this session (they end with the turn). Run it in the foreground.');
                      const left = deadline - Date.now() - BASH_MARGIN_MS;
                      if (left < BASH_MIN_MS) return deny('Not run: this invocation of the session is out of time. Say so, and the next turn can run it.');
                      const asked = typeof bash.timeout === 'number' && bash.timeout > 0 ? bash.timeout : (sandbox.commandTimeoutMs ? Math.min(120_000, sandbox.commandTimeoutMs) : 120_000);
                      const timeout = Math.floor(Math.min(asked, left, sandbox.commandTimeoutMs ?? Infinity));
                      // Only a clamped call's input changes (what the log records is what ran).
                      if (timeout < asked) {
                        clamped.set(hook.tool_use_id, timeout);
                        updated = { ...bash, timeout };
                      }
                    }
                    await transcript.beforeCall(hook.tool_use_id, hook.tool_name);
                    const start = await builtins.begin({ callId: hook.tool_use_id, name: hook.tool_name, input: updated ?? hook.tool_input });
                    if (start.run) return allow(updated);
                    // The log already has this call's outcome (it ran before a crash): never again.
                    return deny(`Not run again: this call already ran in this session. Its recorded result: ${start.result.text}`);
                  } catch (err) {
                    return deny(`Not run: ${(err as Error)?.message ?? String(err)}`);
                  }
                },
              ],
            },
          ],
          PostToolUse: [
            {
              hooks: [
                async (hook) => {
                  if (hook.hook_event_name !== 'PostToolUse' || bridged(hook.tool_name)) return {};
                  const unflushed = await flushed(hook.tool_name);
                  const limit = clamped.get(hook.tool_use_id);
                  const timedOut = limit !== undefined && (hook.tool_response as { interrupted?: unknown } | undefined)?.interrupted === true;
                  let text = toolResponseText(hook.tool_response);
                  if (timedOut) text = outOfTime(limit, text);
                  if (unflushed !== undefined) text = notFlushed(unflushed, text);
                  await builtins.end(hook.tool_use_id, { name: hook.tool_name, input: hook.tool_input, text, ...(timedOut || unflushed !== undefined ? { isError: true } : {}) }).catch(() => {});
                  changed(hook.tool_name, hook.tool_use_id, hook.tool_input);
                  return unflushed === undefined ? {} : { hookSpecificOutput: { hookEventName: 'PostToolUse' as const, additionalContext: NOT_FLUSHED_NOTE } };
                },
              ],
            },
          ],
          PostToolUseFailure: [
            {
              hooks: [
                async (hook) => {
                  if (hook.hook_event_name !== 'PostToolUseFailure' || bridged(hook.tool_name)) return {};
                  const unflushed = await flushed(hook.tool_name);
                  const limit = clamped.get(hook.tool_use_id);
                  const timedOut = limit !== undefined && /timed? ?out|timeout/i.test(hook.error);
                  let text = timedOut ? outOfTime(limit, hook.error) : hook.error;
                  if (unflushed !== undefined) text = notFlushed(unflushed, text);
                  await builtins.end(hook.tool_use_id, { name: hook.tool_name, input: hook.tool_input, text, isError: true }).catch(() => {});
                  changed(hook.tool_name, hook.tool_use_id, hook.tool_input);
                  return unflushed === undefined ? {} : { hookSpecificOutput: { hookEventName: 'PostToolUseFailure' as const, additionalContext: NOT_FLUSHED_NOTE } };
                },
              ],
            },
          ],
        };

        // The CLI's environment in the VM (the SDK gets it with the Function's config dir; `sandboxSpawn` swaps the VM's back in).
        const vmEnv = durableEnv({
          home: machine.dirs.home,
          configDir: machine.dirs.config,
          tmpDir: machine.dirs.tmp,
          cacheDir: machine.dirs.cache,
          baseUrl: machine.modelUrl,
          token: machine.modelKey,
          model,
          ...(smallModel ? { smallModel } : {}),
          ...(sandbox.commandTimeoutMs ? { bashTimeoutMs: sandbox.commandTimeoutMs } : {}),
          ...(sandbox.env ? { extra: sandbox.env } : {}),
        });
        const sdkEnv = { ...vmEnv, CLAUDE_CONFIG_DIR: configDir };
        const disallowed = [...CLAUDE_BUILTINS_OFF, ...(providerTools.includes('web_search') ? [] : ['WebSearch']), ...(options.disallowedTools ?? [])];
        const sessionId = uuidFrom(ctx.runId);
        const queryOptions: QueryOptions = {
          model,
          cwd: machine.root,
          env: sdkEnv,
          // Built-ins on: the allowed ones (less those whose state the log does not carry), each let through by
          // the PreToolUse hook once its intent is in the log. Off: the bridged tools are the only ones. Either
          // way nothing is asked of a user, and nothing else is permitted.
          ...(allowed !== undefined ? { tools: allowed } : {}),
          disallowedTools: disallowed,
          ...(builtinsOn ? { hooks } : {}),
          ...(ownSandbox ? { sandbox: claudeSandboxSettings(machine, sandbox.network) } : {}),
          ...(bridge.tools.length ? { mcpServers: { [MCP_SERVER]: server } } : {}),
          allowedTools: bridge.tools.map((t) => `mcp__${MCP_SERVER}__${t.name}`),
          permissionMode: 'dontAsk',
          strictMcpConfig: true,
          // No user, project or local settings (and so no CLAUDE.md): a model-planted .claude/ on the Drive is ignored.
          settingSources: [],
          persistSession: true,
          sessionStore: store,
          sessionStoreFlush: 'eager',
          includePartialMessages: true,
          systemPrompt: {
            type: 'preset',
            preset: 'claude_code',
            append: [builtinsOn ? DRIVE_NOTE : bridge.tools.length ? TOOLS_NOTE : NO_TOOLS_NOTE, options.instructions].filter(Boolean).join('\n\n'),
            snapshot: true,
          },
          ...(store.hasSession ? { resume: sessionId } : { sessionId }),
          ...(options.maxTurns ? { maxTurns: options.maxTurns } : {}),
          pathToClaudeCodeExecutable: executable,
          spawnClaudeCodeProcess: sandboxSpawn({
            machine,
            executable,
            env: sdkEnv,
            signal: ctx.signal,
            onError: (err) => ctx.halt?.(err),
            onSpawn: (p) => (proc = p),
            onUnmapped: (why) => ctx.halt?.(mirrorUnmapped(why)),
            // Its commands in their own pid namespace (its sandbox), or none at all: the model port then admits the CLI. Without its
            // sandbox (`unsandboxedCommands`) it doesn't, on a real VM: a command could read the key from its environ.
            isolatedCommands: ownSandbox || !builtinsOn,
          }),
          abortController: abort,
        };
        const q = query({ prompt: input, options: queryOptions });
        const messages = q[Symbol.asyncIterator]();

        const send = async (text: string, placed: Submission[], how: { synthetic?: string; priority?: 'next' | 'later' } = {}) => {
          // The drive's first message says, once, what the sandbox told it (a lost Drive).
          if (notes) {
            if (!how.synthetic) store.message({ type: 'message', role: 'user', text: notes, synthetic: 'environment' });
            text = `${notes}\n\n${text}`;
            notes = undefined;
            noteSent = true;
          }
          if (how.synthetic) {
            // In the log before the submissions it carries are placed.
            store.message({ type: 'message', role: 'user', text, synthetic: how.synthetic });
            await store.flush();
          }
          // Place before send: a withdraw that wins never reaches the CLI.
          await placeSubmissions(ctx, placed);
          // The message's id is derived from the first submission it carries
          // (the key of its placement), so a recovery can find it in the
          // transcript (`lostPrompts`).
          const first = placed[0]?.id;
          // A new turn's spend is keyed by its first submission; a steer joins the turn it steers, and a recovery note keeps the key of the turn it resumes (set before).
          if (first && how.priority !== 'next' && !how.synthetic) ledger.turn(first);
          const uuid = !first ? randomUUID() : how.synthetic ? uuidFrom(`note:${first}`) : uuidFrom(first);
          outstanding.add(uuid);
          input.push({
            type: 'user',
            message: { role: 'user', content: text },
            parent_tool_use_id: null,
            uuid: uuid as UserMessage['uuid'],
            ...(how.priority ? { priority: how.priority } : {}),
          });
        };

        /**
         * The CLI exited mid-turn, not because the drive stopped: the link to
         * the VM dropped (the relay killed it), or the VM killed it. Rebuild
         * the drive from the log in this delivery (`Restart`: it re-attaches,
         * and the turn resumes with the recovery note) while time is left;
         * past that, the delivery fails and the queue redelivers.
         */
        const cliExited = (why: string): Error => {
          const tail = proc ? proc.stderrTail().slice(-500) : '';
          const message = `claude exited mid-turn: ${why}${machine.signal.aborted ? ' (the link to the VM was lost)' : ''}${tail ? ` (${tail})` : ''}`;
          if (ctx.attempt < CLI_RESTARTS && deadline - Date.now() > RESTART_MIN_LEFT_MS) {
            log('claude-code: the CLI exited mid-turn; the drive is rebuilt from the log', { why: why.slice(0, 200), linkLost: machine.signal.aborted, attempt: ctx.attempt });
            return new Restart(message);
          }
          return new Error(message);
        };

        /** Read messages until a turn ends. */
        const nextTurnEnd = async (): Promise<TurnEnd> => {
          for (;;) {
            let r: IteratorResult<unknown>;
            try {
              r = await messages.next();
            } catch (err) {
              if (ctx.signal.aborted) throw ctx.signal.reason;
              throw cliExited(String((err as Error)?.message ?? err));
            }
            if (ctx.signal.aborted) throw ctx.signal.reason;
            if (r.done) throw cliExited('its output ended');
            const m = r.value as { type: string; subtype?: string; error?: unknown };
            // The SDK dropped a mirror batch (the session store refused it three times): as an unmapped frame, the turn ends and the session is kept.
            if (m.type === 'system' && m.subtype === 'mirror_error') {
              log('claude-code: the SDK dropped a mirror batch', { error: String(m.error ?? '').slice(0, 200) });
              ctx.halt?.(mirrorUnmapped('a batch the Agent SDK could not keep in the log'));
              throw ctx.signal.reason ?? mirrorUnmapped('a batch the Agent SDK could not keep in the log');
            }
            const end = transcript.observe(m);
            if (end) return end;
          }
        };

        /** Steers that arrive while a turn runs go in at once, at priority `next`; the rest wait for the turn to end. */
        const steering = () => {
          const done = new AbortController();
          const stopped = AbortSignal.any([done.signal, ctx.signal]);
          const running = (async () => {
            for (;;) {
              for (const s of ctx.pending().filter((p) => p.kind === 'steer')) {
                if (stopped.aborted) return;
                await send(s.text ?? '', [s], { priority: 'next' });
              }
              // A hint wakes it at once; without hints the inbox is polled.
              await nap(ctx, ctx.onHint ? 5000 : 1000, stopped);
              if (stopped.aborted) return;
              await ctx.refresh();
            }
          })().catch((err) => {
            // A withdraw won a placement race (`Restart`), or a write failed: rebuild from the log.
            if (!ctx.signal.aborted) ctx.halt?.(err);
          });
          return async () => {
            done.abort();
            await running;
          };
        };

        const runTurn = async () => {
          const stopSteering = steering();
          try {
            for (;;) {
              const end = await nextTurnEnd();
              transcript.endTurn(end);
              // A failed turn (a refused or failed model call) says so on the live stream too, not only in the log.
              if (end.status === 'failed') ctx.live({ type: 'error', message: end.error ?? 'the turn failed' });
              if (end.consumed) for (const u of end.consumed) outstanding.delete(u);
              else outstanding.clear();
              if (end.queued > 0 || outstanding.size > 0) continue;
              await stopSteering();
              // A steer placed while the turn was ending starts another turn.
              if (outstanding.size === 0) break;
            }
          } finally {
            await stopSteering();
          }
          // The CLI writes its end-of-turn lines (last-prompt, mode, cost) right
          // after the result: let them ride in the turn's last batch.
          await new Promise((r) => setTimeout(r, 30));
          await store.flush();
          // The note reached the model in a turn that committed: a later attach doesn't show it again (unless the Drive was lost again since).
          if (noteSent) {
            noteSent = false;
            await sandbox.acknowledge?.(ctx, machine.notesKey);
          }
          ctx.live({ type: 'idle' });
          // The Drive as the turn left it, for the Files panel (best effort: bounded by the invocation's time left).
          await driveFiles?.snapshot();
        };

        try {
          // A turn a crash cut off: resume it with what the log knows. Quote
          // its prompts if the transcript never got one of them. Its spend
          // stays keyed as the turn it resumes, so the turn cap holds across
          // redeliveries.
          // An earlier invocation that ended before its snapshot: the manifest catches up first.
          await driveFiles?.catchUp();
          const open = openTurn(ctx.state());
          const note = recoveryNote(ctx.state(), { prompts: !!open && lostPrompts(ctx.state(), open.placed, store).length > 0 });
          if (note) {
            if (open) ledger.turn(open.placed[0] ?? `open:${open.since}`);
            // The CLI answers again from the interrupted step: what a reader saw of its reply is replaced by what the log kept.
            ctx.live(restartEvent(note.turn));
            await send(note.text, note.pending, { synthetic: 'recovery' });
            await runTurn();
          }
          // The inbox, one submission per turn.
          for (;;) {
            await ctx.refresh();
            let [s] = ctx.pending();
            if (!s && options.idleMs) [s] = await waitForSubmissions(ctx, { signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(options.idleMs)]) });
            if (!s) break;
            await send(s.text ?? '', [s]);
            await runTurn();
          }
          // A model step a crash left open that no request of this drive made again: closed.
          await steps.settleAbandoned();
          // Let the CLI exit (stdin closed) and the SDK deliver its last mirror frames.
          input.end();
          await drain(messages, 10_000);
          await store.flush();
        } finally {
          // A call still running (the CLI exited mid-call) finishes first; a
          // stopped drive's calls stop with it (their signal), given a moment.
          if (calls.size) await settled([...calls], ctx.signal, 5000);
          // A built-in the CLI never reported (it died mid-call): interrupted,
          // "may or may not have taken effect". A stopped drive's are left to
          // the kernel, which resolves them the same way.
          if (builtins.size) await builtins.interruptAll();
          if (!input.closed) input.end();
          q.close();
          const p = proc as SessionProcess | undefined;
          if (p?.alive()) await Promise.race([p.exited, new Promise((r) => setTimeout(r, 2000))]);
        }
      } finally {
        ctx.signal.removeEventListener('abort', stop);
        // A drive that ends unstopped (the CLI exited mid-turn, a Restart): its spend records and the mirror lines still in the coalesce
        // window reach the log before the rebuilt drive reads it (bounded: a failing journal has halted the drive anyway).
        if (!ctx.signal.aborted) await Promise.race([Promise.allSettled([store.flush(), journal.flush()]), new Promise((r) => setTimeout(r, 2000).unref())]);
        // Nothing the model started outlives the drive: the session's processes in the VM are killed (the VM and the Drive stay).
        if (held) await held.close().catch(() => {});
        // No model step outlives the drive.
        await steps.close();
        if (configDir) await rm(configDir, { recursive: true, force: true }).catch(() => {});
      }
    },
  };
}

/** The refusal by provenance (docs/workspaces.md §6 rule 1). */
function sandboxRequired(): Unavailable {
  return new Unavailable('Claude Code runs only in a Vercel Sandbox: pass workspace: sandbox()', {
    code: 'sandbox_required',
    hint: "durable-harness's claudeCode() and claudeCodeHarness() attach the session's sandbox by default; a hand-built harness needs the sandbox tier's machine.",
  });
}

/** Claude Code's sandbox can't start in the VM (with the built-ins on, and no `unsandboxedCommands`). */
function noCommandSandbox(): Unavailable {
  return new Unavailable("Claude Code's own sandbox (bubblewrap) doesn't start in this session's VM, so its commands would run beside the CLI, where they can read its model key: this turn ends", {
    hint: 'Boot from the base (prepareSandboxBase) or an image built by the same recipe (bubblewrap, socat, a mountable /proc); the next turn tries again.',
  });
}

/** A built-in's outcome when the Drive didn't confirm its writes (§5.6 "FSYNC"): a failure, never a plain success. */
function notFlushed(why: string, output: string): string {
  return `${NOT_FLUSHED_NOTE} (the flush failed: ${why})\n${output}`;
}

/** Whether a file tool's path is under one of `PROTECTED_DIRS` of the workspace (relative paths are the workspace's). */
export function protectedPath(root: string, path: string): boolean {
  const abs = posix.resolve(root, path);
  return PROTECTED_DIRS.some((d) => {
    const base = posix.join(root, d);
    return abs === base || abs.startsWith(`${base}/`);
  });
}

/** A spend cap the model calls reached: the turn ends, saying which (§5.5 step 6). */
function spendCapped(cap: Exclude<GatewayCap, 'concurrency'>): Unavailable {
  return new Unavailable(`The turn stopped: the ${cap === 'turnUsd' ? "turn's" : "session's"} model spend reached its cap (sandbox({ budget: { ${cap} } })).`, {
    hint: `Raise sandbox({ budget: { ${cap} } }) to let the session spend more.`,
  });
}

/** The mirror guard (§5.6 "Mirror"): the turn ends, the session is kept. */
function mirrorUnmapped(why: string): Unavailable {
  return new Unavailable(`harness-world-claude-code: mirror_unmapped: the CLI's transcript mirror sent ${why}, so the transcript can't be kept in the log; this turn ends and the session is kept`, {
    hint: 'This is a VM or CLI fault, not a model one: check the deployment pins the CLI the image carries; the next turn tries again.',
  });
}

/** A Bash call the invocation's clamp ended (§5.6 "Deadlines"): a definite outcome, never an open intent. */
function outOfTime(limitMs: number, output: string): string {
  return `Ran out of time in this invocation of the session (its timeout was cut to ${Math.round(limitMs / 1000)} s); partial effects may exist. Output so far:\n${output}`;
}

/**
 * The prompts among `placed` that never reached the transcript: neither the
 * message sent for them (its `uuid` is derived from the first submission of
 * their placement, `place:<id>`) nor a recovery note that carried them is in
 * it. The crash came between the placement and the CLI's write.
 */
export function lostPrompts(state: SessionState, placed: string[], store: Pick<JournalSessionStore, 'hasUser'>): string[] {
  const said = new Set(state.submissions.filter((s) => s.kind === 'prompt' || s.kind === 'steer' || s.kind === 'followUp').map((s) => s.id));
  return placed.filter((id) => {
    if (!said.has(id)) return false;
    const placement = state.effectOrder.find((e) => e.name === 'place' && e.key.startsWith('place:') && e.placed.includes(id));
    const first = placement ? placement.key.slice('place:'.length) : id;
    return !store.hasUser(uuidFrom(first)) && !store.hasUser(uuidFrom(`note:${first}`));
  });
}

/** Wait `ms`, or until a hint says the log moved, or until `signal` aborts. */
function nap(ctx: DriveContext, ms: number, signal: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal.aborted) return resolve();
    const timer = setTimeout(done, ms);
    const off = ctx.onHint?.(() => done());
    signal.addEventListener('abort', done, { once: true });
    function done() {
      clearTimeout(timer);
      off?.();
      signal.removeEventListener('abort', done);
      resolve();
    }
  });
}

/** Every promise settled, or `graceMs` after `signal` aborted, whichever is first. */
function settled(promises: Promise<unknown>[], signal: AbortSignal, graceMs: number): Promise<void> {
  return new Promise<void>((resolve) => {
    let timer: ReturnType<typeof setTimeout> | undefined;
    const onAbort = () => (timer = setTimeout(done, graceMs));
    function done() {
      clearTimeout(timer);
      signal.removeEventListener('abort', onAbort);
      resolve();
    }
    void Promise.allSettled(promises).then(done);
    if (signal.aborted) onAbort();
    else signal.addEventListener('abort', onAbort, { once: true });
  });
}

/** A built-in's result as text: Bash's output, an edit's patch, a read file's content, else the JSON. */
export function toolResponseText(response: unknown): string {
  if (typeof response === 'string') return response;
  const r = response as Record<string, any> | null | undefined;
  if (r && typeof r === 'object') {
    if (typeof r.stdout === 'string' || typeof r.stderr === 'string') return [r.stdout, r.stderr].filter(Boolean).join('\n') || '(no output)';
    if (r.type === 'text' && typeof r.file?.content === 'string') return r.file.content;
  }
  return JSON.stringify(response) ?? String(response);
}

function errorResult(text: string) {
  return { content: [{ type: 'text' as const, text }], isError: true };
}

/** Read the iterator to its end (or until `ms` passed). */
async function drain(it: AsyncIterator<unknown>, ms: number): Promise<void> {
  const deadline = Date.now() + ms;
  for (;;) {
    const left = deadline - Date.now();
    if (left <= 0) return;
    const r = await Promise.race([it.next().catch(() => ({ done: true as const, value: undefined })), new Promise<'timeout'>((ok) => setTimeout(() => ok('timeout'), left))]);
    if (r === 'timeout' || r.done) return;
  }
}