@shardflux/sdk 0.6.2 → 0.8.0

package/dist/capture.js

@@ -0,0 +1,1326 @@
+/**
+ * Tool-call capture (docs/decisions/0006-tool-call-capture.md): tees every tool call of a customer's agent harness
+ * (its input and its full output) into the workspace filesystem, so the agent can compute on results in the VM and
+ * they are in snapshots and forks.
+ *
+ *   const capture = workspace.captureToolCalls();
+ *   const result = await capture.run(block, () => myTools[block.name](block.input));
+ *
+ * Invisible by construction: wrapped tools return the same value, the same promise object and the same thrown error;
+ * a synchronous tool stays synchronous; nothing capture does ever throws into the harness after setup. The only work on
+ * the call's path is taking a reference to its data: serialization runs in `setImmediate`, writes in the background.
+ *
+ * Write protocol: the output file first (atomic replace, key `cap:<run>:<seq>:o<part>`), then the index line, appended
+ * in batches (`cap:<run>:i:<batch>`) in `seq` order. A retry keeps its key while the outcome is unknown (network error:
+ * the write may have committed and is then replayed); after an error response it moves to `<key>:r<n>`, because the host
+ * replays a failed operation's error under its key (an append retried that way starts with a newline, so a torn line
+ * from the failed attempt stays a line of its own).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { cellPath } from "./cell.js";
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, JsonlCollector, asBytes, cutUtf8, dropped as droppedPlan, errorInfo, isUnreadable, padSeq, parseArguments, planOutput, sanitizeToolName, sha256Hex, toJsonSafe, } from "./capture-serialize.js";
+import { PROMPT_HINT, WORKSPACE_README, fillTemplate } from "./capture-text.js";
+import { createAdapters } from "./capture-adapters.js";
+/** A capture problem, reported to `onError` (never thrown into the harness). */
+export class CaptureError extends Error {
+    kind;
+    seq;
+    tool;
+    callId;
+    /** The workspace path of a failed write. */
+    path;
+    constructor(kind, message, extra = {}) {
+        super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+        this.name = 'CaptureError';
+        this.kind = kind;
+        this.seq = extra.seq;
+        this.tool = extra.tool;
+        this.callId = extra.callId;
+        this.path = extra.path;
+    }
+}
+/** Internal hooks the registry calls. */
+export const SETTLE = Symbol('shardflux.capture.settle');
+export const DISCARD = Symbol('shardflux.capture.discard');
+/**
+ * The captures of one client, by workspace id: Shardflux calls on the same client wait for writes recorded before them
+ * (read-your-writes), and delete/reset discard pending writes.
+ */
+export class CaptureRegistry {
+    #byWorkspace = new Map();
+    add(workspaceId, capture) {
+        let set = this.#byWorkspace.get(workspaceId);
+        if (!set)
+            this.#byWorkspace.set(workspaceId, (set = new Set()));
+        set.add(capture);
+    }
+    remove(workspaceId, capture) {
+        const set = this.#byWorkspace.get(workspaceId);
+        if (!set)
+            return;
+        set.delete(capture);
+        if (set.size === 0)
+            this.#byWorkspace.delete(workspaceId);
+    }
+    /**
+     * Waits for writes recorded before this call (not for later ones), each capture bounded by its settle timeout.
+     * Undefined when nothing is pending, so callers skip the await. Never rejects.
+     */
+    settle(workspaceId) {
+        const set = this.#byWorkspace.get(workspaceId);
+        if (!set)
+            return undefined;
+        const waits = [];
+        for (const c of set) {
+            try {
+                const w = c[SETTLE]();
+                if (w)
+                    waits.push(w);
+            }
+            catch {
+                // a barrier never fails the call it guards
+            }
+        }
+        return waits.length === 0 ? undefined : Promise.all(waits).then(() => undefined, () => undefined);
+    }
+    /** Drops pending writes of the workspace (delete: the captures also close; reset: the README is written again). */
+    discard(workspaceId, reason) {
+        const set = this.#byWorkspace.get(workspaceId);
+        if (!set)
+            return;
+        for (const c of [...set]) {
+            try {
+                c[DISCARD](reason);
+            }
+            catch {
+                // never fails the lifecycle call
+            }
+        }
+    }
+}
+const DEFAULT_DIR = '/home/user/tool-calls';
+const INDEX_BATCH_BYTES = 1024 * 1024;
+const DEDUP_IDS = 10_000;
+const SERIALIZE_BUDGET_MS = 4;
+/** Reserved per call for its index line before the line exists (the exact size replaces it). */
+const LINE_RESERVE = 1024;
+/** Error messages in a `queue_full` line are cut to this many characters. */
+const DEGRADED_MESSAGE_MAX = 4096;
+const EMPTY = new Uint8Array(0);
+const STATUSES = new Set(['ok', 'error', 'cancelled', 'incomplete', 'retry']);
+const encoder = new TextEncoder();
+/** `YYYYMMDDTHHMMSSmmmZ-xxxxxx`: sortable UTC start time plus 6 random base36 characters. */
+export function newRunId(now = new Date()) {
+    const ts = now.toISOString().replace(/[-:.]/g, '');
+    const rnd = crypto.getRandomValues(new Uint8Array(6));
+    let suffix = '';
+    for (const b of rnd)
+        suffix += (b % 36).toString(36);
+    return `${ts}-${suffix}`;
+}
+const isNativePromise = (v) => v instanceof Promise || Object.prototype.toString.call(v) === '[object Promise]';
+const tag = (v) => Object.prototype.toString.call(v);
+const isAsyncGeneratorObject = (v) => tag(v) === '[object AsyncGenerator]';
+const isGeneratorObject = (v) => tag(v) === '[object Generator]';
+const isAbortError = (e) => e instanceof Error && (e.name === 'AbortError' || e.code === 'ABORT_ERR');
+/** Timestamps an index line can carry: `started_at` has a 4-digit year (0000-01-01 to 9999-12-31, UTC). */
+const MIN_MS = -62_167_219_200_000;
+const MAX_MS = 253_402_300_799_999;
+/**
+ * Epoch milliseconds from a Date, a number or an ISO string; null when absent, invalid or out of range (epoch
+ * nanoseconds or seconds passed by mistake must not reach toISOString(), which throws for them).
+ */
+export function toMs(v) {
+    let ms;
+    try {
+        if (v instanceof Date)
+            ms = v.getTime();
+        else if (typeof v === 'number')
+            ms = v;
+        else if (typeof v === 'string')
+            ms = Date.parse(v);
+        else
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return Number.isFinite(ms) && ms >= MIN_MS && ms <= MAX_MS ? ms : null;
+}
+/** ISO 8601 with milliseconds and Z, or null; never throws. */
+function isoOf(ms) {
+    if (ms === null)
+        return null;
+    try {
+        return new Date(ms).toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+/** A non-negative integer duration, or null (NaN, Infinity, or past Number.MAX_SAFE_INTEGER). */
+function durationOf(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return null;
+    const d = Math.max(0, Math.round(v));
+    return d <= Number.MAX_SAFE_INTEGER ? d : null;
+}
+function matches(sel, tool, source) {
+    if (typeof sel === 'function')
+        return sel(tool, source);
+    if (sel instanceof RegExp) {
+        sel.lastIndex = 0;
+        return sel.test(tool);
+    }
+    return sel.includes(tool);
+}
+const activeCapture = new AsyncLocalStorage();
+/** Runs capture bookkeeping on the tool's path: whatever it throws stays here (`finish` reports its own failures). */
+function quiet(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // never into the harness
+    }
+}
+/**
+ * Wraps `fn` so each call is recorded into the capture active at call time (`capture.activate()`), and passes
+ * straight through when none is. For tools defined at import time in multi-tenant servers.
+ */
+export function captureTool(name, fn, opts = {}) {
+    const wrapped = function (...args) {
+        const capture = activeCapture.getStore();
+        if (!capture)
+            return fn.apply(this, args);
+        return capture.wrap(name, fn, opts).apply(this, args);
+    };
+    Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+    return wrapped;
+}
+export class ToolCallCapture {
+    /** `YYYYMMDDTHHMMSSmmmZ-xxxxxx`. */
+    runId;
+    /** The capture directory (`dir`). */
+    dir;
+    /** `<dir>/<runId>`: index.jsonl and the output files. */
+    runDir;
+    workspaceId;
+    #host;
+    #cell;
+    #sleep;
+    #opts;
+    #adapters;
+    #core;
+    #closed = false;
+    #closing;
+    #gen = 0;
+    #abort = new AbortController();
+    #seq = 0;
+    #settled = 0;
+    #nextCommit = 1;
+    #items = new Map();
+    #toSerialize = [];
+    #serializeScheduled = false;
+    #fileQueue = [];
+    #activeWrites = 0;
+    #batch = [];
+    #batchBytes = 0;
+    #batchTimer;
+    #committing = false;
+    #batchNo = 0;
+    #readmeDone = false;
+    #readmeGen = 0;
+    #pendingBytes = 0;
+    #waiters = [];
+    #seen = new Set();
+    #stats = { recorded: 0, written: 0, failed: 0, dropped: 0, skipped: 0, duplicates: 0, discarded: 0, retries: 0 };
+    constructor(host, opts = {}) {
+        const dir = (opts.dir ?? DEFAULT_DIR).replace(/\/+$/, '');
+        if (!dir.startsWith('/') || dir.length < 2 || dir.split('/').some((p) => p === '..'))
+            throw new TypeError(`capture dir must be an absolute workspace path, got ${JSON.stringify(opts.dir)}`);
+        const pos = (v, d, name, min = 1) => {
+            if (v === undefined)
+                return d;
+            if (!Number.isFinite(v) || v < min)
+                throw new TypeError(`${name} must be a number >= ${min}`);
+            return v;
+        };
+        this.#host = host;
+        this.#cell = host.cell;
+        this.#sleep = host.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref()));
+        this.workspaceId = host.workspaceId;
+        this.dir = dir;
+        this.runId = newRunId();
+        this.runDir = `${dir}/${this.runId}`;
+        this.#opts = {
+            include: opts.include,
+            exclude: opts.exclude,
+            transform: opts.transform,
+            maxOutputBytes: pos(opts.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, 'maxOutputBytes'),
+            maxInlineInputBytes: pos(opts.maxInlineInputBytes, 64 * 1024, 'maxInlineInputBytes', 0),
+            maxPendingBytes: pos(opts.maxPendingBytes, 128 * 1024 * 1024, 'maxPendingBytes', 0),
+            maxPendingCalls: Math.floor(pos(opts.maxPendingCalls, 10_000, 'maxPendingCalls')),
+            concurrency: Math.floor(pos(opts.concurrency, 4, 'concurrency')),
+            batchDelayMs: pos(opts.batchDelayMs, 50, 'batchDelayMs', 0),
+            retryWindowMs: pos(opts.retryWindowMs, 120_000, 'retryWindowMs', 0),
+            settleTimeoutMs: pos(opts.settleTimeoutMs, 30_000, 'settleTimeoutMs', 0),
+            metadata: opts.metadata,
+            onError: opts.onError,
+        };
+        this.#core = {
+            observe: (spec, fn, thisArg, args) => this.#observe(spec, fn, thisArg, args),
+            hook: (call) => this.#hook(call),
+            settle: () => this[SETTLE](),
+            flush: (timeoutMs) => this.flush(timeoutMs === undefined ? {} : { timeoutMs }),
+            accepts: (tool, source) => this.#accepts(tool, source),
+        };
+        host.registry.add(this.workspaceId, this);
+    }
+    // ---- public API ----------------------------------------------------------------------------------------------
+    /** Counters (a snapshot). */
+    get stats() {
+        return { ...this.#stats, pending: this.#seq - this.#settled, pendingBytes: this.#pendingBytes };
+    }
+    /** True after close() (or when the workspace was deleted): records are ignored. */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * Records one finished call. Synchronous and cheap (serialization happens later); never throws. Returns null when the
+     * capture is closed or the call id was already recorded.
+     */
+    record(call) {
+        try {
+            return this.#record(this.#normalize(call, call.source ?? 'manual'));
+        }
+        catch (e) {
+            this.#report(new CaptureError('serialize', `record failed: ${errorInfo(e).message}`, { cause: e }));
+            return null;
+        }
+    }
+    /**
+     * Runs `fn` (your tool) for a model's tool call and records it: Anthropic `tool_use {id, name, input}`, Responses
+     * `function_call {call_id, name, arguments}`, a Chat `tool_calls` item `{id, function: {name, arguments}}`, or
+     * `{name, input}`. Returns exactly what `fn` returns (the same promise object; a sync result stays sync).
+     */
+    run(call, fn) {
+        const tool = call.name ?? call.toolName ?? call.function?.name ?? 'tool';
+        // A Responses function_call has both: `id` is the item id (fc_…), `call_id` the id its output pairs on.
+        const callId = call.call_id ?? call.callId ?? call.toolCallId ?? call.id ?? null;
+        const input = call.input !== undefined ? call.input : call.args !== undefined ? call.args : parseArguments(call.arguments ?? call.function?.arguments);
+        return this.#observe({ tool, source: 'manual', input, callId }, fn, undefined, []);
+    }
+    /**
+     * Wraps a tool function: every call is recorded. The wrapper returns what `fn` returns (the same value, the same
+     * promise object, the same thrown error; sync stays sync). An async generator is passed through item by item and its
+     * items are stored as `.jsonl`.
+     */
+    wrap(name, fn, opts = {}) {
+        if (typeof fn !== 'function')
+            throw new TypeError('wrap() needs a function');
+        const observe = (spec, thisArg, args) => this.#observe(spec, fn, thisArg, args);
+        const wrapped = function (...args) {
+            let input;
+            let callId = null;
+            try {
+                input = opts.input ? opts.input(...args) : args.length === 1 ? args[0] : args;
+                callId = opts.callId?.(...args) ?? null;
+            }
+            catch {
+                input = args;
+            }
+            return observe({ tool: name, source: opts.source ?? 'wrap', input, callId, ...(opts.meta ? { meta: opts.meta } : {}) }, this, args);
+        };
+        Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+        Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+        return wrapped;
+    }
+    /**
+     * Wraps a collection of tools and returns a copy of the same shape (objects are copied with their prototype; the
+     * originals are not modified). Detects `execute` (AI SDK, Mastra, Shardflux workspaceTools), `run` (Anthropic tool
+     * runner), `invoke` (OpenAI Agents FunctionTool, LangChain tools) and plain functions in an object. Throws TypeError
+     * for any other shape.
+     */
+    tools(tools) {
+        return this.adapters.wrapAny(tools);
+    }
+    /** Runs `fn` with this capture active for `captureTool()` wrappers (AsyncLocalStorage). */
+    activate(fn) {
+        return activeCapture.run(this, fn);
+    }
+    /** The paragraph you can put in a system prompt so the agent knows where its tool calls are (never injected). */
+    promptHint() {
+        return fillTemplate(PROMPT_HINT, { dir: this.dir, run_dir: this.runDir }).trimEnd();
+    }
+    /**
+     * Waits until every call recorded before it is written (or has failed), at most `timeoutMs` (default
+     * settleTimeoutMs). Never rejects. Serverless: `waitUntil(capture.flush())`, or `await capture.flush()` before
+     * returning.
+     */
+    async flush(opts = {}) {
+        const complete = await this.#waitSettled(this.#seq, opts.timeoutMs ?? this.#opts.settleTimeoutMs);
+        return this.#result(complete);
+    }
+    /**
+     * Stops the capture: flushes what was recorded (bounded by `timeoutMs`), or drops it with `discard: true`, then
+     * ignores later records. Never rejects; calling it again returns the first close's result.
+     */
+    close(opts = {}) {
+        this.#closing ??= (async () => {
+            this.#closed = true;
+            let complete = true;
+            if (opts.discard)
+                this.#discardPending('discarded', 'close({ discard: true })');
+            else
+                complete = await this.#waitSettled(this.#seq, opts.timeoutMs ?? this.#opts.settleTimeoutMs);
+            if (!complete)
+                this.#discardPending('timeout', 'close timed out');
+            this.#host.registry.remove(this.workspaceId, this);
+            this.#cell.close();
+            return this.#result(complete);
+        })();
+        return this.#closing;
+    }
+    /** Framework adapters (created on first use). */
+    get adapters() {
+        return (this.#adapters ??= createAdapters(this.#core));
+    }
+    /** Vercel AI SDK: `tools: capture.aiSdk.tools(tools)` or `...capture.aiSdk.callbacks()`. */
+    get aiSdk() {
+        return this.adapters.aiSdk;
+    }
+    /** Mastra: `hooks: capture.mastra.hooks()` or `tools: capture.mastra.tools({...})`. */
+    get mastra() {
+        return this.adapters.mastra;
+    }
+    /** Anthropic SDK tool runner: `tools: capture.anthropic.tools([...])`. */
+    get anthropic() {
+        return this.adapters.anthropic;
+    }
+    /** OpenAI Agents JS: `capture.openaiAgents.attach(runner)` or `tools: capture.openaiAgents.tools([...])`. */
+    get openaiAgents() {
+        return this.adapters.openaiAgents;
+    }
+    /** Claude Agent SDK: `options.hooks = capture.claude.hooks(myHooks)`. */
+    get claude() {
+        return this.adapters.claude;
+    }
+    /** LangChain.js / LangGraph.js: `callbacks: [capture.langchain.handler()]`. */
+    get langchain() {
+        return this.adapters.langchain;
+    }
+    /** MCP client: `const release = capture.mcp.instrument(client, { server: 'github' })`. */
+    get mcp() {
+        return this.adapters.mcp;
+    }
+    // ---- registry hooks -------------------------------------------------------------------------------------------
+    /** Read-your-writes: waits for calls recorded so far (bounded, never rejects); undefined when nothing is pending. */
+    [SETTLE]() {
+        if (this.#settled >= this.#seq)
+            return undefined;
+        return this.#waitSettled(this.#seq, this.#opts.settleTimeoutMs);
+    }
+    /** delete: drops pending writes and closes; reset: drops pending writes, the README is written again. */
+    [DISCARD](reason) {
+        if (this.#seq > this.#settled)
+            this.#discardPending('discarded', `workspace ${reason}`);
+        if (reason === 'reset') {
+            this.#readmeDone = false;
+            this.#readmeGen += 1;
+            return;
+        }
+        this.#closed = true;
+        this.#host.registry.remove(this.workspaceId, this);
+        this.#cell.close();
+    }
+    // ---- recording ------------------------------------------------------------------------------------------------
+    #accepts(tool, source) {
+        try {
+            if (this.#opts.include && !matches(this.#opts.include, tool, source))
+                return false;
+            if (this.#opts.exclude && matches(this.#opts.exclude, tool, source))
+                return false;
+            return true;
+        }
+        catch {
+            return false; // a throwing selector fails closed
+        }
+    }
+    /** Hook-level record: filtered by include/exclude. */
+    #hook(call) {
+        if (this.#closed)
+            return null;
+        try {
+            const n = this.#normalize(call, call.source ?? 'manual');
+            if (!this.#accepts(n.tool, n.source))
+                return null;
+            return this.#record(n);
+        }
+        catch (e) {
+            this.#report(new CaptureError('serialize', `record failed: ${errorInfo(e).message}`, { cause: e }));
+            return null;
+        }
+    }
+    #normalize(call, source) {
+        const hasError = call.error !== undefined && call.error !== null;
+        const startedAtMs = toMs(call.startedAt);
+        const durationMs = durationOf(call.durationMs);
+        return {
+            tool: typeof call.tool === 'string' && call.tool.length > 0 ? call.tool : 'tool',
+            input: call.input,
+            output: call.output,
+            error: call.error,
+            hasError,
+            status: STATUSES.has(call.status) ? call.status : undefined,
+            callId: typeof call.callId === 'string' && call.callId.length > 0 ? call.callId.slice(0, 512) : null,
+            startedAtMs,
+            durationMs,
+            meta: call.meta,
+            source,
+        };
+    }
+    #record(call) {
+        if (this.#closed)
+            return null;
+        if (this.#seq - this.#settled >= this.#opts.maxPendingCalls) {
+            // The hard memory bound while the workspace does not take writes: the call is not kept at all.
+            this.#stats.dropped += 1;
+            this.#report(new CaptureError('queue_full', `${this.#opts.maxPendingCalls} calls are pending (maxPendingCalls); call ${call.tool} was not recorded`, { tool: call.tool, callId: call.callId }));
+            return null;
+        }
+        if (call.callId !== null) {
+            if (this.#seen.has(call.callId)) {
+                this.#stats.duplicates += 1;
+                return null;
+            }
+            this.#seen.add(call.callId);
+            if (this.#seen.size > DEDUP_IDS)
+                this.#seen.delete(this.#seen.values().next().value);
+        }
+        const seq = (this.#seq += 1);
+        this.#stats.recorded += 1;
+        const item = {
+            seq,
+            gen: this.#gen,
+            call,
+            state: 'serialize',
+            line: null,
+            reserved: 0,
+            plan: null,
+            inputPath: null,
+            inputValue: null,
+            inputTruncated: false,
+            inputDropped: null,
+            degraded: false,
+            lineReserve: 0,
+            filesLeft: 0,
+            outputFailed: null,
+            inputFailed: false,
+        };
+        this.#items.set(seq, item);
+        this.#toSerialize.push(item);
+        if (!this.#serializeScheduled) {
+            this.#serializeScheduled = true;
+            setImmediate(() => this.#serializeSome());
+        }
+        return { run: this.runId, seq, callId: call.callId };
+    }
+    /**
+     * Calls `fn` and records the call when it settles, returning exactly what `fn` returned. Everything capture does is
+     * guarded: only `fn`'s own exceptions reach the caller.
+     */
+    #observe(spec, fn, thisArg, args) {
+        const hookLevel = spec.hookLevel === true;
+        let active = !this.#closed;
+        if (active && hookLevel)
+            active = this.#accepts(spec.tool, spec.source);
+        if (!active)
+            return fn.apply(thisArg, args);
+        const startedAtMs = Date.now();
+        const t0 = performance.now();
+        const finish = (output, error, hasError, extra = {}) => {
+            try {
+                let out = output;
+                let err = hasError ? error : undefined;
+                let status = extra.status;
+                if (!hasError && spec.post) {
+                    const p = spec.post(output);
+                    out = p.output;
+                    if (p.error !== undefined)
+                        err = p.error;
+                    if (p.status)
+                        status = p.status;
+                }
+                const n = this.#normalize({ tool: spec.tool, input: spec.input, output: out, error: err, callId: spec.callId, startedAt: startedAtMs, durationMs: performance.now() - t0, ...(spec.meta ? { meta: spec.meta } : {}), ...(status ? { status } : {}) }, spec.source);
+                if (extra.jsonl)
+                    n.jsonl = extra.jsonl;
+                if (extra.note)
+                    n.note = extra.note;
+                this.#record(n);
+            }
+            catch (e) {
+                this.#report(new CaptureError('serialize', `record failed: ${errorInfo(e).message}`, { cause: e, tool: spec.tool }));
+            }
+        };
+        let result;
+        try {
+            result = fn.apply(thisArg, args);
+        }
+        catch (e) {
+            finish(undefined, e, true);
+            throw e;
+        }
+        try {
+            if (isNativePromise(result)) {
+                // Observing the rejection marks this promise handled: a caller that never awaits it gets no
+                // unhandledRejection for it (README "Limits"; no sound way to observe without handling in Node).
+                result.then((v) => {
+                    try {
+                        if (isAsyncGeneratorObject(v) || isGeneratorObject(v))
+                            finish(undefined, undefined, false, { note: 'stream_not_captured' });
+                        else
+                            finish(v, undefined, false);
+                    }
+                    catch {
+                        // finish reports its own failures
+                    }
+                }, (e) => {
+                    try {
+                        finish(undefined, e, true);
+                    }
+                    catch {
+                        // finish reports its own failures
+                    }
+                });
+                return result;
+            }
+            if (typeof result === 'object' && result !== null && typeof result.then === 'function') {
+                // A lazy thenable (e.g. a query builder) may run again on every then(): never call it.
+                finish(undefined, undefined, false, { note: 'thenable_not_captured' });
+                return result;
+            }
+            if (isAsyncGeneratorObject(result))
+                return this.#teeAsync(result, spec.final === true, finish);
+            if (isGeneratorObject(result))
+                return this.#teeSync(result, spec.final === true, finish);
+            finish(result, undefined, false);
+        }
+        catch (e) {
+            this.#report(new CaptureError('serialize', `record failed: ${errorInfo(e).message}`, { cause: e, tool: spec.tool }));
+        }
+        return result;
+    }
+    /** A pass-through async generator: the consumer sees the same results; items go to .jsonl (or the last one is the output). */
+    #teeAsync(src, final, finish) {
+        const collector = final ? null : new JsonlCollector(this.#opts.maxOutputBytes);
+        let last;
+        let done = false;
+        const end = (status, error) => {
+            if (done)
+                return;
+            done = true;
+            const extra = collector ? { jsonl: collector } : {};
+            if (error !== undefined)
+                finish(undefined, error, true, extra);
+            else
+                finish(final ? last : null, undefined, false, { status, ...extra });
+        };
+        const seen = (r) => {
+            if (r.done)
+                end('ok');
+            else if (collector)
+                collector.push(r.value);
+            else
+                last = r.value;
+        };
+        const pass = Object.create(Object.getPrototypeOf(src));
+        Object.defineProperties(pass, {
+            next: {
+                value: async (...a) => {
+                    let r;
+                    try {
+                        r = await src.next(...a);
+                    }
+                    catch (e) {
+                        end('error', e);
+                        throw e;
+                    }
+                    quiet(() => seen(r));
+                    return r;
+                },
+            },
+            return: {
+                value: async (v) => {
+                    let r;
+                    try {
+                        r = await src.return(v);
+                    }
+                    catch (e) {
+                        end('error', e);
+                        throw e;
+                    }
+                    quiet(() => end('incomplete'));
+                    return r;
+                },
+            },
+            throw: {
+                value: async (err) => {
+                    let r;
+                    try {
+                        r = await src.throw(err);
+                    }
+                    catch (e) {
+                        end('error', e);
+                        throw e;
+                    }
+                    quiet(() => seen(r));
+                    return r;
+                },
+            },
+            [Symbol.asyncIterator]: { value: () => pass },
+        });
+        return pass;
+    }
+    #teeSync(src, final, finish) {
+        const collector = final ? null : new JsonlCollector(this.#opts.maxOutputBytes);
+        let last;
+        let done = false;
+        const end = (status, error) => {
+            if (done)
+                return;
+            done = true;
+            const extra = collector ? { jsonl: collector } : {};
+            if (error !== undefined)
+                finish(undefined, error, true, extra);
+            else
+                finish(final ? last : null, undefined, false, { status, ...extra });
+        };
+        const seen = (r) => {
+            if (r.done)
+                end('ok');
+            else if (collector)
+                collector.push(r.value);
+            else
+                last = r.value;
+        };
+        const pass = Object.create(Object.getPrototypeOf(src));
+        const guard = (f, after) => {
+            let r;
+            try {
+                r = f();
+            }
+            catch (e) {
+                end('error', e);
+                throw e;
+            }
+            quiet(() => after(r));
+            return r;
+        };
+        Object.defineProperties(pass, {
+            next: { value: (...a) => guard(() => src.next(...a), seen) },
+            return: { value: (v) => guard(() => src.return(v), () => end('incomplete')) },
+            throw: { value: (err) => guard(() => src.throw(err), seen) },
+            [Symbol.iterator]: { value: () => pass },
+        });
+        return pass;
+    }
+    // ---- serialization (setImmediate) -----------------------------------------------------------------------------
+    /** Runs in setImmediate: nothing may escape it (an exception there would end the harness process). */
+    #serializeSome() {
+        this.#serializeScheduled = false;
+        const until = performance.now() + SERIALIZE_BUDGET_MS;
+        while (this.#toSerialize.length > 0) {
+            const item = this.#toSerialize.shift();
+            if (item.gen === this.#gen)
+                this.#guard(() => this.#prepare(item), item);
+            if (performance.now() >= until)
+                break;
+        }
+        if (this.#toSerialize.length > 0) {
+            this.#serializeScheduled = true;
+            setImmediate(() => this.#serializeSome());
+        }
+        this.#guard(() => this.#pumpWrites());
+        this.#guard(() => this.#pumpCommit());
+    }
+    /**
+     * Last line of defence on the background side: reports what `fn` threw, and makes sure an item it was working on
+     * still settles (with no line) so the index and every barrier move on.
+     */
+    #guard(fn, item) {
+        try {
+            fn();
+        }
+        catch (e) {
+            this.#report(new CaptureError('serialize', `capture internal error${item ? ` on call ${item.seq}` : ''}: ${errorInfo(e).message}`, { cause: e, ...(item ? { seq: item.seq } : {}) }));
+            if (item && item.state !== 'ready' && item.gen === this.#gen && this.#items.get(item.seq) === item) {
+                this.#stats.failed += 1;
+                item.state = 'ready';
+                item.line = null;
+                try {
+                    this.#pumpCommit();
+                }
+                catch {
+                    // reported above
+                }
+            }
+        }
+    }
+    #copyForTransform(call) {
+        const event = {
+            tool: call.tool,
+            callId: call.callId,
+            source: call.source,
+            status: this.#statusOf(call),
+            input: call.input,
+            // A generator's items are handed over as an array (the transform may redact them too).
+            output: call.jsonl ? call.jsonl.values() : call.output,
+            error: call.hasError ? errorInfo(call.error) : null,
+            startedAt: isoOf(call.startedAtMs),
+            durationMs: call.durationMs,
+            meta: { ...(this.#opts.metadata ?? {}), ...(call.meta ?? {}) },
+        };
+        try {
+            return structuredClone(event);
+        }
+        catch {
+            const bytes = asBytes(event.output);
+            return {
+                ...event,
+                input: toJsonSafe(event.input),
+                output: bytes ? bytes.slice() : toJsonSafe(event.output),
+                meta: toJsonSafe(event.meta) ?? {},
+            };
+        }
+    }
+    #statusOf(call) {
+        if (call.status)
+            return call.status;
+        if (call.hasError)
+            return isAbortError(call.error) ? 'cancelled' : 'error';
+        return 'ok';
+    }
+    /** Applies `transform` to a copy; null when the call is dropped (transform returned null or threw). */
+    #transform(item, call) {
+        const transform = this.#opts.transform;
+        if (!transform)
+            return call;
+        let ev;
+        let copy;
+        try {
+            copy = this.#copyForTransform(call);
+            ev = transform(copy);
+        }
+        catch (e) {
+            this.#stats.dropped += 1;
+            this.#report(new CaptureError('transform', `transform threw; call ${item.seq} (${call.tool}) was dropped: ${errorInfo(e).message}`, { seq: item.seq, tool: call.tool, callId: call.callId, cause: e }));
+            return null;
+        }
+        if (ev === null || ev === undefined) {
+            this.#stats.skipped += 1;
+            return null;
+        }
+        const out = {
+            ...call,
+            tool: typeof ev.tool === 'string' && ev.tool.length > 0 ? ev.tool : call.tool,
+            callId: typeof ev.callId === 'string' && ev.callId.length > 0 ? ev.callId.slice(0, 512) : ev.callId === null ? null : call.callId,
+            source: typeof ev.source === 'string' && ev.source.length > 0 ? ev.source : call.source,
+            status: STATUSES.has(ev.status) ? ev.status : call.status,
+            input: ev.input,
+            output: ev.output,
+            error: ev.error ?? undefined,
+            hasError: ev.error !== null && ev.error !== undefined,
+            startedAtMs: ev.startedAt === null ? null : (toMs(ev.startedAt) ?? call.startedAtMs),
+            durationMs: ev.durationMs === null ? null : typeof ev.durationMs === 'number' ? durationOf(ev.durationMs) : call.durationMs,
+            meta: typeof ev.meta === 'object' && ev.meta !== null ? ev.meta : {},
+            metaFinal: true,
+        };
+        delete out.jsonl;
+        if (call.jsonl && Array.isArray(ev.output)) {
+            // Items stay items: written as .jsonl again, after the transform.
+            const again = new JsonlCollector(this.#opts.maxOutputBytes);
+            for (const v of ev.output)
+                again.push(v);
+            if (call.jsonl.truncated)
+                again.truncated = true;
+            out.jsonl = again;
+        }
+        return out;
+    }
+    /** Transform, serialize, reserve, and queue the item's files (or its index line at once when there are none). */
+    #prepare(item) {
+        let call = item.call;
+        try {
+            if (isUnreadable(call.output))
+                call = { ...call, output: undefined, note: call.note ?? 'stream_not_captured' };
+            const transformed = this.#transform(item, call);
+            if (!transformed)
+                return this.#ready(item, null);
+            call = item.call = transformed;
+            const base = `${padSeq(item.seq)}-${sanitizeToolName(call.tool)}`;
+            let plan = call.jsonl ? call.jsonl.plan(base) : planOutput(call.output, base, this.#opts.maxOutputBytes);
+            if (call.note && !plan.note)
+                plan = { ...plan, note: call.note };
+            if (plan.dropped === 'too_large' || plan.dropped === 'serialize_failed') {
+                this.#stats.dropped += 1;
+                this.#report(new CaptureError(plan.dropped === 'too_large' ? 'too_large' : 'serialize', `output of call ${item.seq} (${call.tool}) not stored: ${plan.dropped}`, { seq: item.seq, tool: call.tool, callId: call.callId }));
+            }
+            // The input: inline up to maxInlineInputBytes, else its own file.
+            let inputValue = toJsonSafe(call.input);
+            if (inputValue === undefined)
+                inputValue = null;
+            let inputFile = null;
+            const inputText = JSON.stringify(inputValue);
+            // A string of n UTF-16 units is at most 3n UTF-8 bytes: only long ones need encoding to decide.
+            let inlineBytes = inputText.length;
+            if (inputText.length * 3 > this.#opts.maxInlineInputBytes) {
+                const bytes = encoder.encode(inputText);
+                inlineBytes = bytes.length;
+                if (bytes.length > this.#opts.maxInlineInputBytes) {
+                    const data = cutUtf8(bytes, this.#opts.maxOutputBytes);
+                    item.inputTruncated = data.length < bytes.length;
+                    inputFile = { path: `${base}.input.json`, data, contentType: 'application/json', sha256: sha256Hex(data) };
+                    inputValue = null;
+                    inlineBytes = 0;
+                }
+            }
+            // Everything this call holds until its line is appended counts: files, the inline input, the line itself.
+            const fileBytes = plan.files.reduce((n, f) => n + f.data.length, 0);
+            const inputBytes = inputFile ? inputFile.data.length : inlineBytes;
+            const room = this.#opts.maxPendingBytes - this.#pendingBytes - LINE_RESERVE;
+            if (fileBytes + inputBytes > room) {
+                const dropped = [];
+                if (fileBytes > 0) {
+                    plan = droppedPlan('queue_full', plan.note);
+                    dropped.push('output');
+                }
+                if (inputBytes > 0 && inputBytes > room) {
+                    inputFile = null;
+                    inputValue = null;
+                    item.inputDropped = 'queue_full';
+                    dropped.push('input');
+                }
+                if (dropped.length > 0) {
+                    item.degraded = true;
+                    this.#stats.dropped += 1;
+                    this.#report(new CaptureError('queue_full', `pending data over maxPendingBytes (${this.#opts.maxPendingBytes}); the ${dropped.join(' and ')} of call ${item.seq} (${call.tool}) dropped`, { seq: item.seq, tool: call.tool, callId: call.callId }));
+                }
+            }
+            item.plan = plan;
+            item.inputValue = inputValue;
+            item.state = 'files';
+            // Only what the line needs stays referenced: the tool's input and output objects are released.
+            item.call = { ...call, input: undefined, output: undefined };
+            delete item.call.jsonl;
+            const tasks = [];
+            if (inputFile) {
+                item.inputPath = inputFile.path;
+                tasks.push({ item, file: inputFile, key: `cap:${this.runId}:${item.seq}:in`, kind: 'input' });
+            }
+            plan.files.forEach((f, i) => {
+                const part = plan.files.length === 1 ? 'o0' : i === plan.files.length - 1 ? 'or' : `o${i + 1}`;
+                tasks.push({ item, file: f, key: `cap:${this.runId}:${item.seq}:${part}`, kind: 'output' });
+            });
+            item.lineReserve = LINE_RESERVE + (item.inputValue === null ? 0 : inlineBytes);
+            item.reserved = tasks.reduce((n, t) => n + t.file.data.length, 0) + item.lineReserve;
+            this.#pendingBytes += item.reserved;
+            item.filesLeft = tasks.length;
+            if (tasks.length === 0)
+                return this.#finishFiles(item);
+            this.#fileQueue.push(...tasks);
+        }
+        catch (e) {
+            this.#stats.dropped += 1;
+            this.#report(new CaptureError('serialize', `call ${item.seq} (${call.tool}) could not be serialized: ${errorInfo(e).message}`, { seq: item.seq, tool: call.tool, callId: call.callId, cause: e }));
+            item.plan = droppedPlan('serialize_failed');
+            item.inputValue = null;
+            item.state = 'files';
+            item.call = { ...item.call, input: undefined, output: undefined };
+            delete item.call.jsonl;
+            this.#finishFiles(item);
+        }
+    }
+    /**
+     * Builds the index line once every file of the item is written or has failed. Never throws: a line that cannot be
+     * built falls back to a minimal one, and failing that the call is counted as failed (it never wedges the index).
+     */
+    #finishFiles(item) {
+        if (item.outputFailed)
+            this.#stats.dropped += 1;
+        let line = null;
+        try {
+            line = this.#buildLine(item, false);
+        }
+        catch (e) {
+            try {
+                line = this.#buildLine(item, true);
+                this.#report(new CaptureError('serialize', `index line of call ${item.seq} built without meta: ${errorInfo(e).message}`, { seq: item.seq, cause: e }));
+            }
+            catch (e2) {
+                this.#stats.failed += 1;
+                this.#report(new CaptureError('serialize', `index line of call ${item.seq} could not be built: ${errorInfo(e2).message}`, { seq: item.seq, cause: e2 }));
+            }
+        }
+        this.#ready(item, line);
+    }
+    #buildLine(item, minimal) {
+        const call = item.call;
+        const plan = item.plan ?? droppedPlan('serialize_failed');
+        const failed = item.outputFailed;
+        const short = minimal || item.degraded;
+        let error = null;
+        if (call.hasError) {
+            const info = errorInfo(call.error);
+            error = { type: String(info.type).slice(0, 256), message: short ? String(info.message).slice(0, DEGRADED_MESSAGE_MAX) : String(info.message) };
+        }
+        const meta = short ? {} : call.metaFinal ? { ...(call.meta ?? {}) } : { ...(this.#opts.metadata ?? {}), ...(call.meta ?? {}) };
+        if (plan.note)
+            meta.note = plan.note;
+        if (item.inputTruncated)
+            meta.input_truncated = true;
+        if (item.inputDropped || item.inputFailed)
+            meta.input_dropped = item.inputDropped ?? 'write_failed';
+        const line = {
+            v: 1,
+            run: this.runId,
+            seq: item.seq,
+            call_id: typeof call.callId === 'string' ? call.callId : null,
+            tool: typeof call.tool === 'string' && call.tool.length > 0 ? call.tool : 'tool',
+            source: typeof call.source === 'string' && call.source.length > 0 ? call.source : 'manual',
+            status: this.#statusOf(call),
+            error,
+            started_at: minimal ? null : isoOf(call.startedAtMs),
+            duration_ms: minimal ? null : durationOf(call.durationMs),
+        };
+        if (item.inputPath && !item.inputFailed && !item.inputDropped)
+            line.input_path = item.inputPath;
+        else
+            line.input = item.inputFailed || item.inputDropped || minimal ? null : item.inputValue;
+        const stored = !failed && plan.outputPath !== null;
+        line.output_path = stored ? plan.outputPath : null;
+        line.content_type = stored ? plan.contentType : null;
+        line.bytes = stored ? plan.bytes : 0;
+        line.sha256 = stored ? plan.sha256 : null;
+        line.truncated = stored ? plan.truncated : false;
+        if (stored && plan.parts)
+            line.parts = plan.parts;
+        const drop = failed ?? plan.dropped ?? (item.inputDropped === 'queue_full' ? 'queue_full' : undefined);
+        if (drop)
+            line.dropped = drop;
+        const safeMeta = toJsonSafe(meta);
+        if (typeof safeMeta === 'object' && safeMeta !== null && !Array.isArray(safeMeta) && Object.keys(safeMeta).length > 0)
+            line.meta = safeMeta;
+        else if (Object.keys(meta).length > 0 && (typeof safeMeta !== 'object' || safeMeta === null || Array.isArray(safeMeta)))
+            line.meta = { value: safeMeta };
+        return `${JSON.stringify(line)}\n`;
+    }
+    #ready(item, line) {
+        item.line = line;
+        item.state = 'ready';
+        item.inputValue = null;
+        // The exact size of the line replaces what was reserved for it.
+        const n = line ? encoder.encode(line).length : 0;
+        item.reserved += n - item.lineReserve;
+        this.#pendingBytes += n - item.lineReserve;
+        item.lineReserve = 0;
+        this.#pumpCommit();
+    }
+    // ---- file writes ----------------------------------------------------------------------------------------------
+    #pumpWrites() {
+        while (this.#activeWrites < this.#opts.concurrency && this.#fileQueue.length > 0) {
+            const task = this.#fileQueue.shift();
+            if (task.item.gen !== this.#gen)
+                continue;
+            this.#activeWrites += 1;
+            const gen = this.#gen;
+            const done = (r) => {
+                if (gen !== this.#gen)
+                    return;
+                this.#activeWrites -= 1;
+                const item = task.item;
+                // The bytes are written (or given up on): release them now, not when the line is appended.
+                const size = task.file.data.length;
+                task.file.data = EMPTY;
+                item.reserved -= size;
+                this.#pendingBytes -= size;
+                if (!r.ok) {
+                    if (task.kind === 'input')
+                        item.inputFailed = true;
+                    else
+                        item.outputFailed ??= r.reason === 'too_large' ? 'too_large' : 'write_failed';
+                }
+                item.filesLeft -= 1;
+                if (item.filesLeft === 0)
+                    this.#finishFiles(item);
+                this.#pumpWrites();
+            };
+            void this.#put(`${this.runDir}/${task.file.path}`, task.file.data, task.key, false, gen)
+                .catch((e) => ({ ok: false, reason: 'permanent', error: e }))
+                .then(done)
+                .catch((e) => this.#report(new CaptureError('write', `capture write bookkeeping failed: ${errorInfo(e).message}`, { cause: e })));
+        }
+    }
+    /**
+     * One PUT /files with retries: network errors keep the key (the write may have committed: replayed); an error
+     * response moves to `<key>:r<n>` (the host replays a failed operation's error under its key) and an append then
+     * starts with a newline. 400/403/413/422 are final; 404/410 mean the workspace is gone.
+     */
+    async #put(path, data, key, append, gen) {
+        try {
+            return await this.#putWithRetries(path, data, key, append, gen);
+        }
+        catch (e) {
+            // Anything unexpected (an injected sleep that rejects, a broken signal): the write fails, capture goes on.
+            return this.#fail(path, e, 'permanent');
+        }
+    }
+    async #putWithRetries(path, data, key, append, gen) {
+        const deadline = Date.now() + this.#opts.retryWindowMs;
+        const url = cellPath('/v1/workspaces/{workspace_id}/files', { workspace_id: this.workspaceId });
+        let n = 0;
+        let delay = 250;
+        for (let attempt = 0;; attempt += 1) {
+            if (gen !== this.#gen || this.#abort.signal.aborted)
+                return { ok: false, reason: 'aborted' };
+            const k = n === 0 ? key : `${key}:r${n}`;
+            let body = data;
+            if (append && n > 0) {
+                body = new Uint8Array(data.length + 1);
+                body[0] = 0x0a;
+                body.set(data, 1);
+            }
+            const left = deadline - Date.now();
+            const signal = left > 0 ? AbortSignal.any([this.#abort.signal, AbortSignal.timeout(left)]) : this.#abort.signal;
+            try {
+                const res = await this.#cell.request('PUT', url, {
+                    query: { path, create_parents: true, ...(append ? { append: true } : {}) },
+                    body,
+                    contentType: 'application/octet-stream',
+                    idempotencyKey: k,
+                    signal,
+                });
+                await res.arrayBuffer().catch(() => undefined);
+                return { ok: true };
+            }
+            catch (e) {
+                if (gen !== this.#gen || this.#abort.signal.aborted)
+                    return { ok: false, reason: 'aborted' };
+                let definitive = false;
+                if (e instanceof ShardfluxApiError) {
+                    if (e.status === 404 || e.status === 410) {
+                        this.#gone(e);
+                        return { ok: false, reason: 'gone', error: e };
+                    }
+                    if (e.status === 413)
+                        return this.#fail(path, e, 'too_large');
+                    if (e.status === 400 || e.status === 401 || e.status === 403 || e.status === 422)
+                        return this.#fail(path, e, 'permanent');
+                    definitive = true;
+                }
+                else if (e instanceof ShardfluxProtocolError) {
+                    if (e.status === 404 || e.status === 410) {
+                        this.#gone(e);
+                        return { ok: false, reason: 'gone', error: e };
+                    }
+                    if (e.status === 400 || e.status === 403 || e.status === 413 || e.status === 422)
+                        return this.#fail(path, e, e.status === 413 ? 'too_large' : 'permanent');
+                    definitive = e.status > 0;
+                }
+                if (definitive)
+                    n += 1;
+                const hint = e instanceof ShardfluxApiError && e.retryAfterSeconds !== undefined ? e.retryAfterSeconds * 1000 : 0;
+                const wait = Math.min(5_000, Math.max(delay, hint));
+                if (Date.now() + wait >= deadline)
+                    return this.#fail(path, e, 'window');
+                this.#stats.retries += 1;
+                await this.#sleep(wait);
+                delay = Math.min(5_000, delay * 2);
+            }
+        }
+    }
+    #fail(path, error, reason) {
+        const why = reason === 'window' ? `still failing after retryWindowMs (${this.#opts.retryWindowMs} ms)` : reason === 'too_large' ? 'too large for the files API' : 'refused';
+        this.#report(new CaptureError('write', `write of ${path} ${why}: ${errorInfo(error).message}`, { path, cause: error }));
+        return { ok: false, reason, error };
+    }
+    #gone(error) {
+        if (this.#closed && this.#seq === this.#settled)
+            return;
+        this.#report(new CaptureError('gone', `the workspace is gone (${errorInfo(error).message}); the capture is closed`, { cause: error }));
+        this.#closed = true;
+        this.#host.registry.remove(this.workspaceId, this);
+        this.#discardPending(null, 'workspace gone');
+        this.#cell.close();
+    }
+    // ---- the index ------------------------------------------------------------------------------------------------
+    #pumpCommit() {
+        if (this.#committing)
+            return;
+        for (;;) {
+            const item = this.#items.get(this.#nextCommit);
+            if (!item || item.state !== 'ready' || item.gen !== this.#gen)
+                break;
+            if (item.line && this.#batchBytes > 0 && this.#batchBytes + item.line.length > INDEX_BATCH_BYTES)
+                break;
+            this.#batch.push(item);
+            if (item.line)
+                this.#batchBytes += item.line.length;
+            this.#nextCommit += 1;
+        }
+        if (this.#batch.length === 0)
+            return;
+        if (this.#batchBytes === 0) {
+            // Only calls without a line (dropped by transform): settled in order, nothing to write.
+            const last = this.#batch[this.#batch.length - 1];
+            this.#batch = [];
+            this.#settleThrough(last.seq);
+            return this.#pumpCommit();
+        }
+        const full = this.#items.get(this.#nextCommit)?.state === 'ready' && this.#batchBytes > 0;
+        if (full || this.#waiters.length > 0 || this.#opts.batchDelayMs === 0) {
+            void this.#commit();
+            return;
+        }
+        this.#batchTimer ??= setTimeout(() => {
+            this.#batchTimer = undefined;
+            this.#guard(() => void this.#commit());
+        }, this.#opts.batchDelayMs);
+    }
+    async #commit() {
+        if (this.#committing || this.#batch.length === 0)
+            return;
+        if (this.#batchTimer) {
+            clearTimeout(this.#batchTimer);
+            this.#batchTimer = undefined;
+        }
+        const gen = this.#gen;
+        const batch = this.#batch;
+        this.#batch = [];
+        this.#batchBytes = 0;
+        this.#committing = true;
+        try {
+            if (!this.#readmeDone) {
+                const readme = encoder.encode(fillTemplate(WORKSPACE_README, { dir: this.dir, run_dir: this.runDir }));
+                const r = await this.#put(`${this.dir}/README.md`, readme, `cap:${this.runId}:readme${this.#readmeGen > 0 ? `:${this.#readmeGen}` : ''}`, false, gen);
+                if (gen !== this.#gen)
+                    return;
+                this.#readmeDone = true; // written, or reported: never blocks the index
+                if (!r.ok && r.reason === 'gone')
+                    return;
+            }
+            const lines = batch.filter((i) => i.line).map((i) => i.line);
+            const data = encoder.encode(lines.join(''));
+            this.#batchNo += 1;
+            const r = await this.#put(`${this.runDir}/index.jsonl`, data, `cap:${this.runId}:i:${this.#batchNo}`, true, gen);
+            if (gen !== this.#gen)
+                return;
+            if (r.ok)
+                this.#stats.written += lines.length;
+            else if (r.reason !== 'gone' && r.reason !== 'aborted')
+                this.#stats.failed += lines.length;
+            this.#settleThrough(batch[batch.length - 1].seq);
+        }
+        catch (e) {
+            if (gen === this.#gen) {
+                this.#stats.failed += batch.filter((i) => i.line).length;
+                this.#report(new CaptureError('write', `index append failed: ${errorInfo(e).message}`, { cause: e }));
+                this.#settleThrough(batch[batch.length - 1].seq);
+            }
+        }
+        finally {
+            if (gen === this.#gen) {
+                this.#committing = false;
+                this.#pumpCommit();
+            }
+        }
+    }
+    #settleThrough(seq) {
+        for (let s = this.#settled + 1; s <= seq; s += 1) {
+            const item = this.#items.get(s);
+            if (item) {
+                this.#pendingBytes -= item.reserved;
+                this.#items.delete(s);
+            }
+        }
+        if (seq > this.#settled)
+            this.#settled = seq;
+        if (this.#waiters.length === 0)
+            return;
+        for (let i = this.#waiters.length - 1; i >= 0; i -= 1) {
+            const w = this.#waiters[i];
+            if (w.seq <= this.#settled) {
+                this.#waiters.splice(i, 1);
+                w.resolve();
+            }
+        }
+    }
+    /** Resolves true once every seq <= `seq` is settled, false at the timeout. Never rejects. */
+    #waitSettled(seq, timeoutMs) {
+        if (this.#settled >= seq)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const waiter = {
+                seq,
+                resolve: () => {
+                    clearTimeout(timer);
+                    resolve(true);
+                },
+            };
+            this.#waiters.push(waiter);
+            const timer = setTimeout(() => {
+                const i = this.#waiters.indexOf(waiter);
+                if (i >= 0)
+                    this.#waiters.splice(i, 1);
+                resolve(this.#settled >= seq);
+            }, Math.max(0, timeoutMs));
+            // Someone is waiting: append what is ready now instead of after the batch delay.
+            if (this.#batchTimer && !this.#committing)
+                this.#guard(() => void this.#commit());
+            else
+                this.#guard(() => this.#pumpCommit());
+        });
+    }
+    /** Drops every pending call (delete, reset, close with discard or after its timeout, workspace gone). */
+    #discardPending(kind, why) {
+        const pending = this.#seq - this.#settled;
+        this.#gen += 1;
+        this.#abort.abort(new DOMException('capture discarded', 'AbortError'));
+        this.#abort = new AbortController();
+        if (this.#batchTimer)
+            clearTimeout(this.#batchTimer);
+        this.#batchTimer = undefined;
+        this.#toSerialize = [];
+        this.#fileQueue = [];
+        this.#activeWrites = 0;
+        this.#batch = [];
+        this.#batchBytes = 0;
+        this.#committing = false;
+        if (kind === 'discarded')
+            this.#stats.discarded += pending;
+        else
+            this.#stats.failed += pending;
+        if (pending > 0 && kind)
+            this.#report(new CaptureError(kind, `${pending} pending call(s) dropped: ${why}`));
+        this.#nextCommit = this.#seq + 1;
+        this.#settleThrough(this.#seq);
+        this.#items.clear();
+        this.#pendingBytes = 0;
+    }
+    #result(complete) {
+        return { complete, written: this.#stats.written, failed: this.#stats.failed, dropped: this.#stats.dropped };
+    }
+    #report(e) {
+        const cb = this.#opts.onError;
+        if (!cb)
+            return;
+        try {
+            cb(e);
+        }
+        catch {
+            // the listener's problem
+        }
+    }
+}