humanish 0.110.0 → 0.110.2

package/dist/run/run.d.ts

@@ -1,8 +1,7 @@
 import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
-import type { ExecutionOutcome } from "./judge.js";
+import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
-import { type RunStatusHandle } from "./status.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
     /** Project directory, in the form the route resolved it. */
@@ -22,6 +21,19 @@ interface StartRunOptions {
     /** Clock for `createdAt` and the latest pointer. */
     now?: (() => number) | undefined;
 }
+/** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
+interface RecordedOutcome {
+    ok: boolean;
+    execution: ExecutionOutcome;
+}
+/** What a route hands Run.finish about how its run ended, before the Observer renders. */
+export interface FinishOutcome extends RecordedOutcome {
+    /**
+     * The route's entry in OUTCOME_POLICIES. FinishedRun.renderObserver records an Observer that
+     * did not render under it, as a failure or a warning.
+     */
+    policy: OutcomePolicy;
+}
 interface Run {
     readonly runId: string;
     readonly createdAt: string;
@@ -41,14 +53,16 @@ interface Run {
      */
     writeSnapshot(bundle: RunBundle): Promise<void>;
     /**
-     * The one final publication: run.json, then the status outcome, then review.json, review.md,
-     * events.ndjson, observer/observer-data.json, and last the latest pointer. The status goes
-     * after run.json so the index never gets ahead of the evidence, and the pointer goes last so
-     * `latest` never selects a run whose projections are incomplete. Rejects before writing on a
-     * second call, after the scope closed, or when the bundle names another run or mode. A
-     * rejection partway leaves the files written so far and issues no FinishedRun.
+     * The one final publication: run.json with `outcome` set from `outcome`, then the status
+     * outcome copied from it, then review.json, review.md, events.ndjson,
+     * observer/observer-data.json, and last the latest pointer. The status goes after run.json so
+     * the index never gets ahead of the evidence, and the pointer goes last so `latest` never
+     * selects a run whose projections are incomplete. Every projection reads the outcome, so none
+     * shows a pass for a run whose ok is false. Rejects before writing on a second call, after the
+     * scope closed, or when the bundle names another run or mode. A rejection partway leaves the
+     * files written so far and issues no FinishedRun.
      */
-    finish(bundle: RunBundle): Promise<FinishedRun>;
+    finish(bundle: RunBundle, outcome: FinishOutcome): Promise<FinishedRun>;
 }
 export interface RunScope {
     /**
@@ -78,18 +92,20 @@ export declare class FinishedRun {
     readonly runId: string;
     /** The paths created by startRun and validated at the start of `finish`. */
     readonly paths: PreparedRunArtifactPaths;
-    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, status: RunStatusHandle);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>);
     static isIssued(value: unknown): value is FinishedRun;
-    /** Render the Observer for exactly these paths, never a directory re-resolved by name. */
-    renderObserver(): Promise<ObserverResult>;
     /**
-     * Record the result's ok and execution outcome in status.json. A route calls it once, after the
-     * Observer render, with the values its result returns, so the two agree.
+     * The run's ok and execution outcome as run.json records them: what the route passed to
+     * finish, plus an Observer that did not render. A route's result reads them from here.
+     */
+    get outcome(): RecordedOutcome;
+    /**
+     * Render the Observer for exactly these paths, never a directory re-resolved by name. An
+     * Observer that did not render is an `evidence` failure: it is added to run.json's outcome and
+     * status.json under the route's policy before this resolves. No page exists then that could
+     * show the run without it. A render that throws records nothing and rejects.
      */
-    recordOutcome(result: {
-        ok: boolean;
-        execution: ExecutionOutcome;
-    }): Promise<void>;
+    renderObserver(): Promise<ObserverResult>;
 }
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,

package/dist/run/run.js

@@ -2,15 +2,17 @@
 // token that lets the Observer and automatic analysis read it. Routes build bundles and write
 // their own evidence files; this module owns when the run starts, how it is published, and how it
 // is closed on every exit.
+import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
 import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD } from "./bundle.js";
+import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
-import { beginRunStatus, runStatusOutcome } from "./status.js";
+import { beginRunStatus, runStatusOutcome, } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -24,38 +26,66 @@ const issueKey = Symbol("FinishedRun");
  */
 export class FinishedRun {
     #observer;
-    #status;
+    #recordFailure;
+    #outcome;
     runId;
     /** The paths created by startRun and validated at the start of `finish`. */
     paths;
-    constructor(key, runId, paths, observer, status) {
+    constructor(key, runId, paths, observer, outcome, recordFailure) {
         if (key !== issueKey)
             throw new Error("Only Run.finish issues a FinishedRun.");
         this.runId = runId;
         this.paths = paths;
         this.#observer = observer;
-        this.#status = status;
+        this.#outcome = outcome;
+        this.#recordFailure = recordFailure;
     }
     static isIssued(value) {
         return typeof value === "object" && value !== null && #observer in value;
     }
-    /** Render the Observer for exactly these paths, never a directory re-resolved by name. */
-    renderObserver() {
-        const target = this.#observer;
-        if (target === undefined) {
-            return Promise.reject(new RunLifecycleError("This run was started without an Observer."));
-        }
-        return target.render(target.cwd, this.runId, { open: target.open, expectedRun: this.paths });
+    /**
+     * The run's ok and execution outcome as run.json records them: what the route passed to
+     * finish, plus an Observer that did not render. A route's result reads them from here.
+     */
+    get outcome() {
+        return this.#outcome;
     }
     /**
-     * Record the result's ok and execution outcome in status.json. A route calls it once, after the
-     * Observer render, with the values its result returns, so the two agree.
+     * Render the Observer for exactly these paths, never a directory re-resolved by name. An
+     * Observer that did not render is an `evidence` failure: it is added to run.json's outcome and
+     * status.json under the route's policy before this resolves. No page exists then that could
+     * show the run without it. A render that throws records nothing and rejects.
      */
-    recordOutcome(result) {
-        return this.#status.settle(result);
+    async renderObserver() {
+        const target = this.#observer;
+        if (target === undefined)
+            throw new RunLifecycleError("This run was started without an Observer.");
+        const observer = await target.render(target.cwd, this.runId, {
+            open: target.open,
+            expectedRun: this.paths,
+        });
+        if (!observer.ok) {
+            this.#outcome = await this.#recordFailure({
+                kind: "evidence",
+                message: observer.error?.message ?? "The Observer did not render.",
+            });
+        }
+        return observer;
     }
 }
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** An execution outcome as run.json records it, each message through the shape redaction. */
+function redactedExecution(execution) {
+    const redacted = (failure) => ({
+        kind: failure.kind,
+        message: redactText(failure.message),
+    });
+    return {
+        succeeded: execution.succeeded,
+        failures: execution.failures.map(redacted),
+        ...(execution.warnings === undefined ? {} : { warnings: execution.warnings.map(redacted) }),
+    };
+}
 /** Where FinishedRun renders the Observer, when the run was started with one. */
 function observerTarget(options) {
     return options.observer === undefined
@@ -66,6 +96,99 @@ function observerTarget(options) {
             render: options.observer.render ?? renderObserver,
         };
 }
+function runPublisher(args) {
+    const { options, runId, paths, runStatus, now, admit } = args;
+    const observer = observerTarget(options);
+    let pointerWritten = false;
+    // The bundle of the last write asked for, and the outcome every later write carries once a
+    // signal stopped the run, so no write after the interrupt can drop it.
+    let lastBundle;
+    let interrupted;
+    // One chain serializes every write. A rejection reaches only the caller of that write; the
+    // chain itself continues, so a failed snapshot never blocks the final publication.
+    let tail = Promise.resolve();
+    const enqueue = (write) => {
+        const written = tail.then(write);
+        tail = written.then(() => undefined, () => undefined);
+        return written;
+    };
+    const writePointer = async () => {
+        const pointer = {
+            schema: "humanish.latest-run.v1",
+            runId,
+            path: paths.relativeRunRoot,
+            updatedAt: new Date(now()).toISOString(),
+        };
+        await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+        pointerWritten = true;
+    };
+    /** run.json with its outcome, then `afterBundle`, then the review and projections. */
+    const writeBundleFiles = async (bundle, outcome, afterBundle) => {
+        await validatePreparedRunArtifactPaths(paths);
+        // The run owns `outcome`: a bundle read back from disk keeps none of its own.
+        const { outcome: _previous, ...evidence } = bundle;
+        const recorded = interrupted ?? outcome;
+        const publicBundle = await withPublicSandboxIds(paths, {
+            ...evidence,
+            cwd: PUBLIC_TARGET_CWD,
+            ...(recorded === undefined ? {} : { outcome: recorded }),
+        });
+        await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
+        await afterBundle(publicBundle);
+        await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
+        await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle), "utf8");
+        const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
+        await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
+        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle)), "utf8");
+    };
+    const snapshot = async (bundle) => {
+        await writeBundleFiles(bundle, undefined, async () => { });
+        if (!pointerWritten)
+            await writePointer();
+    };
+    const finishedOutcome = (outcome) => ({
+        state: "finished",
+        ok: outcome.ok,
+        execution: redactedExecution(outcome.execution),
+    });
+    const publish = async (bundle, outcome) => {
+        await writeBundleFiles(bundle, finishedOutcome(outcome), (publicBundle) => runStatus.finish(runStatusOutcome(publicBundle)));
+        await scrubRunSandboxIds(paths);
+        await writePointer();
+        let current = { ok: outcome.ok, execution: outcome.execution };
+        // An Observer that did not render, judged under the route's policy and written to run.json
+        // and status.json, so the two agree with the result the route returns. A run directory that
+        // can no longer be written (replaced, or a disk error) keeps the files it has, and the
+        // result still carries the failure.
+        const recordFailure = (failure) => admit(enqueue(async () => {
+            const { failures, warnings = [] } = current.execution;
+            const execution = judgeExecution([...failures, ...warnings, failure], outcome.policy);
+            current = { ok: current.ok && execution.succeeded, execution };
+            await writeBundleFiles(bundle, finishedOutcome(current), (publicBundle) => runStatus.restate(runStatusOutcome(publicBundle))).catch(() => undefined);
+            return current;
+        }));
+        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure);
+    };
+    const interrupt = async (signal) => {
+        interrupted = { state: "interrupted", ok: false, signal, at: new Date(now()).toISOString() };
+        const written = lastBundle;
+        if (written === undefined)
+            return;
+        // A failed write leaves status.json as the record of the interrupt.
+        await enqueue(() => writeBundleFiles(written, undefined, async () => { })).catch(() => undefined);
+    };
+    return {
+        snapshot(bundle) {
+            lastBundle = bundle;
+            return enqueue(() => snapshot(bundle));
+        },
+        publish(bundle, outcome) {
+            lastBundle = bundle;
+            return enqueue(() => publish(bundle, outcome));
+        },
+        interrupt,
+    };
+}
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
  * so the scope and its run admit no further calls, even through references `fn` leaked into
@@ -100,65 +223,40 @@ export async function runScope(fn) {
             if (!created.ok)
                 return created;
             // beginRunStatus reads only the mode and the study provenance from the run's options.
-            status = beginRunStatus(created.paths, { ...options, runId });
+            const runStatus = beginRunStatus(created.paths, { ...options, runId });
+            status = runStatus;
+            let interruptBundle;
             // Registered before the first write lands: a signal while it is still settling reaches
-            // the handle, whose interrupt queues behind that write.
-            unregister = registerActiveRun({ cwd: options.cwd, runId, paths: created.paths, status });
-            await status.started;
-            return { ok: true, run: openRun(options, runId, created.paths, status) };
+            // the handle, whose interrupt queues behind that write. The interrupt lands in
+            // status.json first, then in run.json once the run has written one.
+            unregister = registerActiveRun({
+                cwd: options.cwd,
+                runId,
+                paths: created.paths,
+                status: {
+                    async interrupt(signal) {
+                        const recorded = await runStatus.interrupt(signal);
+                        if (recorded)
+                            await interruptBundle?.(signal);
+                        return recorded;
+                    },
+                },
+            });
+            await runStatus.started;
+            const run = openRun(options, runId, created.paths, runStatus);
+            interruptBundle = run.interrupt;
+            return { ok: true, run: run.run };
         })());
     };
     const openRun = (options, runId, paths, runStatus) => {
         const now = options.now ?? Date.now;
         const createdAt = new Date(now()).toISOString();
-        const observer = observerTarget(options);
+        const publisher = runPublisher({ options, runId, paths, runStatus, now, admit });
         let finishCalled = false;
-        let pointerWritten = false;
-        // One chain serializes every write. A rejection reaches only the caller of that write; the
-        // chain itself continues, so a failed snapshot never blocks the final publication.
-        let tail = Promise.resolve();
-        const enqueue = (write) => {
-            const written = tail.then(write);
-            tail = written.then(() => undefined, () => undefined);
-            return written;
-        };
         const checkIdentity = (bundle) => bundle.runId !== runId || bundle.mode !== options.mode
             ? "The bundle names another run or mode than this run."
             : undefined;
-        const writePointer = async () => {
-            const pointer = {
-                schema: "humanish.latest-run.v1",
-                runId,
-                path: paths.relativeRunRoot,
-                updatedAt: new Date(now()).toISOString(),
-            };
-            await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
-            pointerWritten = true;
-        };
-        /** run.json, then `afterBundle`, then the review and projections. */
-        const writeBundleFiles = async (bundle, afterBundle) => {
-            await validatePreparedRunArtifactPaths(paths);
-            const publicBundle = await withPublicSandboxIds(paths, { ...bundle, cwd: PUBLIC_TARGET_CWD });
-            await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
-            await afterBundle(publicBundle);
-            await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
-            await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle), "utf8");
-            const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
-            await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
-            await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle)), "utf8");
-        };
-        const snapshot = async (bundle) => {
-            await writeBundleFiles(bundle, async () => { });
-            if (!pointerWritten)
-                await writePointer();
-        };
-        const publish = async (bundle) => {
-            await writeBundleFiles(bundle, (publicBundle) => runStatus.finish(runStatusOutcome(publicBundle)));
-            await scrubRunSandboxIds(paths);
-            await writePointer();
-            return new FinishedRun(issueKey, runId, paths, observer, runStatus);
-        };
-        return {
+        const run = {
             runId,
             createdAt,
             mode: options.mode,
@@ -172,9 +270,9 @@ export async function runScope(fn) {
                 const mismatch = checkIdentity(bundle);
                 if (mismatch !== undefined)
                     return refuse(mismatch);
-                return admit(enqueue(() => snapshot(bundle)));
+                return admit(publisher.snapshot(bundle));
             },
-            finish(bundle) {
+            finish(bundle, outcome) {
                 if (closed)
                     return refuse("The run scope has closed.");
                 if (finishCalled)
@@ -183,12 +281,13 @@ export async function runScope(fn) {
                 if (mismatch !== undefined)
                     return refuse(mismatch);
                 finishCalled = true;
-                return admit(enqueue(() => publish(bundle)).then((issued) => {
+                return admit(publisher.publish(bundle, outcome).then((issued) => {
                     finished = issued;
                     return issued;
                 }));
             },
         };
+        return { run, interrupt: publisher.interrupt };
     };
     let outcome;
     try {

package/dist/run/sandbox-creates.d.ts

@@ -0,0 +1,59 @@
+import type { PreparedOutputRoot } from "./contained-output.js";
+import type { SandboxOwnerTags } from "./sandbox-receipts.js";
+/** Refuses a sandbox create for a run directory whose process is stopping. */
+export declare class SandboxCreateRefusedError extends Error {
+    constructor();
+}
+/** One sandbox a create in this process reported, and what its route did with it. */
+export interface CreatedSandbox {
+    sandboxId: string;
+    /** The participant or subject label the receipt also records. */
+    participantId: string;
+    /** True once the route's own release confirmed the sandbox gone. */
+    released: boolean;
+}
+/**
+ * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
+ * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
+ * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
+ * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
+ * route already sets.
+ */
+export declare function sandboxOwnerTags(root: PreparedOutputRoot): SandboxOwnerTags;
+/** A create in progress; the acquire step in src/substrates/e2b/sandbox.ts holds one per create. */
+export interface SandboxCreateTicket {
+    /** Whether the directory's process has started stopping; checked before each attempt. */
+    stopping(): boolean;
+    /** The provider reported a sandbox id for this create. Safe to call twice with one id. */
+    created(sandboxId: string): void;
+    /** The route's release confirmed this sandbox gone. */
+    released(sandboxId: string): void;
+    /** The create resolved or threw, and its receipt write, if any, has finished. */
+    settled(): void;
+}
+/** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
+export declare function beginSandboxCreate(root: PreparedOutputRoot, participantId: string): SandboxCreateTicket;
+/**
+ * Run `write` once per directory and return its promise to every caller. Creates that start
+ * together then resume in the order they called, so the order they reach the provider does not
+ * depend on which file append finishes first. A write that reports failure is forgotten, so the
+ * next create tries again.
+ */
+export declare function recordSandboxOwnerOnce(root: PreparedOutputRoot, write: () => Promise<boolean>): Promise<void>;
+/** What the signal handler holds after stopping a directory's creates. */
+export interface StoppedSandboxCreates {
+    /**
+     * Calls `listener` at once for every sandbox a create has reported so far, then for each one an
+     * in-flight create reports later, until the returned function is called.
+     */
+    watch(listener: (sandbox: CreatedSandbox) => void): () => void;
+    /** Resolves once every create that was in flight at the stop has settled. */
+    settled: Promise<void>;
+    /** How many of those creates have not settled yet. */
+    inFlight(): number;
+}
+/**
+ * Stop `root`'s creates: any create that starts from now on is refused. Called synchronously when
+ * the signal arrives, before anything is awaited, so no create can slip in after it.
+ */
+export declare function stopSandboxCreates(root: PreparedOutputRoot): StoppedSandboxCreates;

package/dist/run/sandbox-creates.js

@@ -0,0 +1,140 @@
+// The sandboxes this process is creating for each run directory, and the E2B tags that name the
+// directory. E2B creates a sandbox before its id reaches this process: on @e2b/desktop the startup
+// guard reports the id, and its receipt is written, only once the SDK has the handle, and a
+// create from an SDK without the guard reports it when `Sandbox.create` resolves, after desktop
+// startup. The CLI's signal handler (src/cli/commands/run-signals.ts) uses this registry to cover
+// the window before a receipt lands:
+// it stops new creates, kills every id a create has reported, and kills each in-flight create's
+// sandbox as soon as its id arrives. The tags let `humanish reclaim` find a sandbox whose id
+// never reached this process at all.
+import { createHash } from "node:crypto";
+import path from "node:path";
+/** Refuses a sandbox create for a run directory whose process is stopping. */
+export class SandboxCreateRefusedError extends Error {
+    constructor() {
+        super("The run is stopping, so no further sandbox is created.");
+        this.name = "SandboxCreateRefusedError";
+    }
+}
+const directories = new Map();
+// A process runs one study at a time; the cap only bounds a long-lived library caller, and only
+// idle entries count against it.
+const MAX_REMEMBERED_DIRECTORIES = 64;
+function identityOf(root) {
+    return "physicalRunRoot" in root
+        ? { where: root.physicalRunRoot, identity: root.runRootIdentity }
+        : { where: root.physicalPath, identity: root.identity };
+}
+function directoryKey(root) {
+    const { where, identity } = identityOf(root);
+    return `${where}\0${identity.dev}:${identity.ino}:${identity.birthtimeNs}`;
+}
+function directoryFor(root) {
+    const key = directoryKey(root);
+    const existing = directories.get(key);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        stopping: false,
+        created: new Map(),
+        inFlight: new Set(),
+        listeners: new Set(),
+    };
+    directories.set(key, created);
+    // Only an idle entry is forgotten: a stopping one keeps refusing creates, and one with a create
+    // in flight or a sandbox its route has not released is still needed by the signal handler.
+    for (const [oldest, entry] of directories) {
+        if (directories.size <= MAX_REMEMBERED_DIRECTORIES)
+            break;
+        if (entry === created || !idle(entry))
+            continue;
+        directories.delete(oldest);
+    }
+    return created;
+}
+function idle(entry) {
+    return (!entry.stopping &&
+        entry.inFlight.size === 0 &&
+        [...entry.created.values()].every((sandbox) => sandbox.released));
+}
+/**
+ * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
+ * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
+ * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
+ * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
+ * route already sets.
+ */
+export function sandboxOwnerTags(root) {
+    const { where, identity } = identityOf(root);
+    const runKey = createHash("sha256")
+        .update(`${identity.ino}:${identity.birthtimeNs}`)
+        .digest("hex")
+        .slice(0, 16);
+    return { tool: "humanish", runId: path.basename(where), runKey };
+}
+/** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
+export function beginSandboxCreate(root, participantId) {
+    const directory = directoryFor(root);
+    if (directory.stopping)
+        throw new SandboxCreateRefusedError();
+    let settle;
+    const done = new Promise((resolve) => {
+        settle = resolve;
+    });
+    directory.inFlight.add(done);
+    return {
+        stopping: () => directory.stopping,
+        created(sandboxId) {
+            if (directory.created.has(sandboxId))
+                return;
+            const sandbox = { sandboxId, participantId, released: false };
+            directory.created.set(sandboxId, sandbox);
+            for (const listener of directory.listeners)
+                listener(sandbox);
+        },
+        released(sandboxId) {
+            const sandbox = directory.created.get(sandboxId);
+            if (sandbox !== undefined)
+                sandbox.released = true;
+        },
+        settled() {
+            directory.inFlight.delete(done);
+            settle();
+        },
+    };
+}
+/**
+ * Run `write` once per directory and return its promise to every caller. Creates that start
+ * together then resume in the order they called, so the order they reach the provider does not
+ * depend on which file append finishes first. A write that reports failure is forgotten, so the
+ * next create tries again.
+ */
+export function recordSandboxOwnerOnce(root, write) {
+    const directory = directoryFor(root);
+    const pending = (directory.ownerLine ??= write().then((written) => {
+        if (!written && directory.ownerLine === pending)
+            delete directory.ownerLine;
+    }));
+    return pending;
+}
+/**
+ * Stop `root`'s creates: any create that starts from now on is refused. Called synchronously when
+ * the signal arrives, before anything is awaited, so no create can slip in after it.
+ */
+export function stopSandboxCreates(root) {
+    const directory = directoryFor(root);
+    directory.stopping = true;
+    const pending = [...directory.inFlight];
+    return {
+        watch(listener) {
+            for (const sandbox of directory.created.values())
+                listener(sandbox);
+            directory.listeners.add(listener);
+            return () => {
+                directory.listeners.delete(listener);
+            };
+        },
+        settled: Promise.all(pending).then(() => undefined),
+        inFlight: () => pending.filter((create) => directory.inFlight.has(create)).length,
+    };
+}

package/dist/run/sandbox-receipts.d.ts

@@ -23,11 +23,26 @@ export interface ParsedSandboxReceipt extends Omit<SandboxReceipt, "provider"> {
 /** The ids this process has receipted for `root`, whether or not the journal write landed. */
 export declare function appendedSandboxIds(root: PreparedOutputRoot): string[];
 /**
- * Append one receipt. Best-effort by design: the receipt exists to protect the run, so a failed
- * receipt write must never fail the participant. The only cost of a miss is that `reclaim` cannot see
- * this id and the TTL backstop covers it instead. Containment is the same prepare step every
- * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
+ * Append one receipt; false when the write failed. Best-effort by design: the receipt exists to
+ * protect the run, so a failed receipt write must never fail the participant. The only cost of a
+ * miss is that `reclaim` cannot see this id and the TTL backstop covers it instead. Containment is
+ * the same prepare step every artifact write uses; append (not atomic-replace) keeps racing
+ * participants' receipts intact.
  */
-export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<void>;
+export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<boolean>;
+/** Append one owner line; false when the write failed, which never fails the create. */
+export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags): Promise<boolean>;
+/** The owner tags every sandbox carries; sandboxOwnerTags in src/run/sandbox-creates.ts. */
+export type SandboxOwnerTags = {
+    tool: "humanish";
+    runId: string;
+    runKey: string;
+};
+/**
+ * The owner tag sets a journal's owner lines record for the run named `runId`. Only a complete
+ * tuple counts: provider e2b, `tool: humanish`, this run's id and a well-formed key, and nothing
+ * else. A partial or foreign line would widen reclaim's search past this run, so it is skipped.
+ */
+export declare function parseSandboxOwners(text: string, runId: string): SandboxOwnerTags[];
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
 export declare function parseSandboxReceipts(text: string): ParsedSandboxReceipt[];