humanish 0.110.0 → 0.110.2

package/dist/run/display.js

@@ -0,0 +1,106 @@
+// How a run reads wherever a surface says whether it passed: the TUI, the Observer and its run
+// library, `humanish runs`, `humanish stats` and review.md. Each of them calls runDisplay with the
+// same facts, so a run whose own ok is false shows as a pass on none of them, and two surfaces
+// cannot disagree about one run.
+import { classifyRunStatus, isRunStatusRecord } from "./status.js";
+const LABELS = {
+    running: "running",
+    interrupted: "interrupted",
+    passed: "passed",
+    failed: "failed",
+    blocked: "blocked",
+    timed_out: "timed out",
+    no_verdict: "no verdict",
+    dry_run: "dry run",
+    unknown: "unknown",
+};
+const TONES = {
+    running: "live",
+    interrupted: "warn",
+    passed: "pass",
+    failed: "fail",
+    blocked: "warn",
+    timed_out: "warn",
+    no_verdict: "warn",
+    dry_run: "neutral",
+    unknown: "neutral",
+};
+function shown(state, reason) {
+    return {
+        state,
+        label: LABELS[state],
+        tone: TONES[state],
+        ...(reason === undefined ? {} : { reason }),
+    };
+}
+/**
+ * A run's state. A live or interrupted run is that, whatever its last flush said. A finished run
+ * shows its participants' blocked, timed-out or failed verdict; otherwise a run whose ok is false
+ * is failed, even with a pass verdict, because its execution failed. Only then does a pass verdict
+ * show as passed.
+ */
+export function runDisplay(facts) {
+    if (facts.liveness === "running")
+        return shown("running");
+    if (facts.liveness === "interrupted")
+        return shown("interrupted");
+    const reason = facts.ok === false && facts.failure !== undefined
+        ? `${facts.failure.kind}: ${facts.failure.message}`
+        : undefined;
+    if (facts.verdict === "blocked")
+        return shown("blocked", reason);
+    if (facts.verdict === "timed_out")
+        return shown("timed_out", reason);
+    if (facts.verdict === "fail" || facts.ok === false)
+        return shown("failed", reason);
+    if (facts.verdict === "pass")
+        return shown("passed");
+    if (facts.verdict === "contract_proof_only")
+        return shown(facts.mode === "dry-run" ? "dry_run" : "no_verdict");
+    return shown("unknown");
+}
+/** A state in words: "passed", "timed out", "no verdict". */
+export function runDisplayLabel(state) {
+    return LABELS[state];
+}
+/** A display as one line of text: the label, then why the run failed when it says. */
+function runDisplayLine(display) {
+    return display.reason === undefined ? display.label : `${display.label}: ${display.reason}`;
+}
+/**
+ * The facts for a run from its bundle. run.json's `outcome` decides when it has one. A bundle
+ * without one is in progress, or was recorded before the field existed: its status record, when
+ * given and naming the run, then says whether the run is alive and, for the older run, holds its ok.
+ * With no record, a bundle whose simulations are still running is live.
+ */
+export function bundleDisplayFacts(bundle, status, nowMs = Date.now()) {
+    const base = { mode: bundle.mode, verdict: bundle.review?.verdict };
+    const outcome = bundle.outcome;
+    if (outcome?.state === "interrupted")
+        return { ...base, liveness: "interrupted" };
+    if (outcome?.state === "finished")
+        return {
+            ...base,
+            liveness: "finished",
+            ok: outcome.ok,
+            failure: outcome.execution.failures[0],
+        };
+    if (isRunStatusRecord(status) && status.runId === bundle.runId)
+        return {
+            ...base,
+            liveness: classifyRunStatus(status, nowMs),
+            ...(typeof status.outcome?.ok === "boolean" ? { ok: status.outcome.ok } : {}),
+            ...(status.outcome?.execution?.failures[0] === undefined
+                ? {}
+                : { failure: status.outcome.execution.failures[0] }),
+        };
+    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
+    return { ...base, liveness: inProgress ? "running" : "finished" };
+}
+/**
+ * How review.md says the run ended: the display of the bundle it is rendered from, so a run whose
+ * execution failed never reads as a pass beside its participants' verdict.
+ */
+export function reviewOutcome(bundle) {
+    return runDisplayLine(runDisplay(bundleDisplayFacts(bundle)));
+}

package/dist/run/dry-run.js

@@ -10,6 +10,8 @@ import { participantEvent, participantIdsOf, participantRecord, participantStrea
 import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./project.js";
 import { loadDryRunInputs } from "./dry-run-inputs.js";
 import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk, verdictText, } from "./judge.js";
+import { reviewOutcome } from "./display.js";
+import { cli } from "../cli/invocation.js";
 /**
  * The preview route's run. The run scope closes the run it started on every exit, including
  * the fail-closed ones. It renders an Observer only when `options.observer` asks for one.
@@ -48,7 +50,7 @@ async function runDryRunInScope(options, scope) {
     if (!options.dryRun) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_LIVE_RUN_UNIMPLEMENTED",
-            message: "humanish run needs a study. List studies with humanish study list, or run humanish run --dry-run for a sample bundle.",
+            message: `humanish run needs a study. List studies with ${cli("study list")}, or run ${cli("run --dry-run")} for a sample bundle.`,
         });
     }
     const createdAt = new Date().toISOString();
@@ -123,16 +125,17 @@ async function runDryRunInScope(options, scope) {
         review: createReviewSummary(judgment.verdict),
         feedbackCandidates: [],
     };
-    const finished = await run.finish(bundle);
-    const observer = options.observer === undefined ? undefined : await renderPreviewObserver(finished, warnings);
     // The preview's policy keeps an Observer that did not render a warning: the bundle is still
     // evidence, and `export` can render it later.
     const policy = OUTCOME_POLICIES.preview;
-    const execution = judgeExecution(observer === undefined || observer.ok
-        ? []
-        : [{ kind: "evidence", message: observer.error?.message ?? "render failed" }], policy);
-    const ok = resultOk({ judgment, execution, scorerFailures: [], policy });
-    await finished.recordOutcome({ ok, execution });
+    const execution = judgeExecution([], policy);
+    const finished = await run.finish(bundle, {
+        ok: resultOk({ judgment, execution, scorerFailures: [], policy }),
+        execution,
+        policy,
+    });
+    const observer = options.observer === undefined ? undefined : await renderPreviewObserver(finished, warnings);
+    const { ok } = finished.outcome;
     return {
         schema: "humanish.run-result.v1",
         ok,
@@ -175,6 +178,8 @@ Mode: ${bundle.mode}
 
 Verdict: ${verdictText(bundle.review.verdict, bundle.mode)}
 
+Outcome: ${reviewOutcome(bundle)}
+
 ${bundle.review.summary}
 
 ## Public-Safety

package/dist/run/judge.d.ts

@@ -91,8 +91,9 @@ export interface Judgment {
 }
 /** The judgment for a verdict: a run passes when its verdict is pass, and a dry run passes. */
 export declare function judgmentOf(verdict: Verdict, dryRun: boolean): Judgment;
-/** What kind of execution failure a run recorded. */
-type ExecutionFailureKind = "harness" | "provider-cleanup" | "provider-policy" | "sandbox-cleanup" | "evidence" | "cap" | "run";
+/** The kinds of execution failure a run records. */
+export declare const EXECUTION_FAILURE_KINDS: readonly ["harness", "provider-cleanup", "provider-policy", "sandbox-cleanup", "evidence", "cap", "run"];
+type ExecutionFailureKind = (typeof EXECUTION_FAILURE_KINDS)[number];
 /** One way the run failed as an execution. The message is scrubbed; status.json shows it. */
 export interface ExecutionFailure {
     kind: ExecutionFailureKind;

package/dist/run/judge.js

@@ -12,6 +12,7 @@
 //   4. foldScorerFailures, which every route with a scorer applies before the run finishes;
 //   5. the outcome: judgeExecution applies the route's policy to its execution failures, and
 //      resultOk gives the result's ok.
+import { cli } from "../cli/invocation.js";
 /**
  * The participant said it reached the goal having taken no action and said nothing, and no stop
  * condition ended the session. It most likely saw a blank or loading screen, so it is not a pass.
@@ -108,6 +109,16 @@ export function verdictForStatus(status) {
 export function judgmentOf(verdict, dryRun) {
     return { verdict, passed: dryRun || verdict === "pass" };
 }
+/** The kinds of execution failure a run records. */
+export const EXECUTION_FAILURE_KINDS = [
+    "harness",
+    "provider-cleanup",
+    "provider-policy",
+    "sandbox-cleanup",
+    "evidence",
+    "cap",
+    "run",
+];
 /**
  * The execution failure for one sandbox whose release is unconfirmed. `warning` is the route's
  * release warning, already scrubbed. `recovery` says how to release it by hand; without one,
@@ -116,7 +127,7 @@ export function judgmentOf(verdict, dryRun) {
 export function sandboxCleanupFailure(owner, warning, runId, recovery) {
     return {
         kind: "sandbox-cleanup",
-        message: `${owner}: ${warning ?? "Sandbox release is unconfirmed."} ${recovery ?? `Reclaim it by recorded id with \`humanish reclaim --run ${runId}\`.`}`,
+        message: `${owner}: ${warning ?? "Sandbox release is unconfirmed."} ${recovery ?? `Reclaim it by recorded id with \`${cli(`reclaim --run ${runId}`)}\`.`}`,
     };
 }
 /** Each route's outcome policy, in one place. */

package/dist/run/local-only-files.d.ts

@@ -0,0 +1,13 @@
+/** Each local-only file, relative to the run directory, with why a shared copy omits it. */
+export declare const LOCAL_ONLY_RUN_FILES: ReadonlyMap<string, string>;
+/**
+ * Whether a run-relative posix path names a local-only file. Case is ignored, so a request that
+ * spells the name differently cannot reach the file on a case-insensitive filesystem.
+ */
+export declare function isLocalOnlyRunFile(relativePath: string): boolean;
+/**
+ * Whether `filePath` is one of the local-only files of the run at `runRoot` under another
+ * spelling: the same device and inode. A case-insensitive filesystem also folds Unicode, so a name
+ * check alone cannot rule every spelling out.
+ */
+export declare function isLocalOnlyRunFileIdentity(runRoot: string, filePath: string): Promise<boolean>;

package/dist/run/local-only-files.js

@@ -0,0 +1,35 @@
+// Run files that mean something only on the machine that recorded the run. sandbox-receipts.ndjson
+// holds the raw sandbox ids reclaim kills by, and status.json holds the recording process's pid.
+// Bundle export leaves both out of a shared copy, and the Observer servers never hand them out.
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { SANDBOX_RECEIPTS_ARTIFACT } from "./sandbox-receipts.js";
+import { RUN_STATUS_FILE } from "./status.js";
+/** Each local-only file, relative to the run directory, with why a shared copy omits it. */
+export const LOCAL_ONLY_RUN_FILES = new Map([
+    [RUN_STATUS_FILE, "local process status is not a new attempt"],
+    [SANDBOX_RECEIPTS_ARTIFACT, "operational journal does not confer a derivative resource lease"],
+]);
+/**
+ * Whether a run-relative posix path names a local-only file. Case is ignored, so a request that
+ * spells the name differently cannot reach the file on a case-insensitive filesystem.
+ */
+export function isLocalOnlyRunFile(relativePath) {
+    return LOCAL_ONLY_RUN_FILES.has(relativePath.toLowerCase());
+}
+/**
+ * Whether `filePath` is one of the local-only files of the run at `runRoot` under another
+ * spelling: the same device and inode. A case-insensitive filesystem also folds Unicode, so a name
+ * check alone cannot rule every spelling out.
+ */
+export async function isLocalOnlyRunFileIdentity(runRoot, filePath) {
+    const requested = await lstat(filePath, { bigint: true }).catch(() => null);
+    if (requested === null)
+        return false;
+    for (const name of LOCAL_ONLY_RUN_FILES.keys()) {
+        const local = await lstat(path.join(runRoot, name), { bigint: true }).catch(() => null);
+        if (local !== null && local.dev === requested.dev && local.ino === requested.ino)
+            return true;
+    }
+    return false;
+}

package/dist/run/pricing.js

@@ -101,7 +101,7 @@ const DESKTOP_RESOURCE_RATE = {
  * since an npm install cannot edit this file.
  */
 export function unpricedCapMessage(model) {
-    return `execution.caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${Object.keys(MODEL_RATES).sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
+    return `caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${Object.keys(MODEL_RATES).sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
 }
 export const DESKTOP_RATE = {
     usdPerMinute: 0.00888,

package/dist/run/projection.d.ts

@@ -99,8 +99,6 @@ export declare function listWindow(args: {
     start: number;
     end: number;
 };
-/** The label for a run's state, in the register the surfaces share. */
-export declare function livenessLabel(entry: Pick<RunIndexEntry, "liveness" | "verdict">): string;
 /** A study as the study list shows it: what is declared, joined to what actually happened. */
 export interface StudyRow {
     /**

package/dist/run/projection.js

@@ -228,17 +228,6 @@ export function listWindow(args) {
     start = Math.max(0, Math.min(start, total - viewport));
     return { start, end: start + viewport };
 }
-/** The label for a run's state, in the register the surfaces share. */
-export function livenessLabel(entry) {
-    switch (entry.liveness) {
-        case "running":
-            return "running";
-        case "interrupted":
-            return "interrupted";
-        default:
-            return entry.verdict ?? "finished";
-    }
-}
 /** The addressable handle for a manifest: its filename without directory or extension. */
 function studyNameFromPath(manifestPath) {
     const base = manifestPath.split("/").pop() ?? manifestPath;

package/dist/run/reclaim-outcomes.d.ts

@@ -0,0 +1,89 @@
+import { type E2BTagSearch } from "../substrates/e2b/sandbox.js";
+import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
+export declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
+export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
+/**
+ * killed = kill(id) confirmed; already-gone = the server no longer knows the id (TTL or a prior
+ * cleanup got it), or the run's route released it before the signal; kill-failed = the attempt
+ * errored (the TTL backstop still applies); unsupported-provider = the receipt names a provider
+ * this version cannot reach, so nothing was attempted; pending = the kill had not answered when
+ * the receipt was written. `--check` writes running, already-gone or check-failed instead.
+ */
+export type ReclaimOutcomeState = "killed" | "already-gone" | "kill-failed" | "unsupported-provider" | "pending" | "running" | "check-failed";
+export interface ReclaimOutcome {
+    /** "[redacted-sandbox-id]"; the raw id is only in the run's sandbox-receipts.ndjson. */
+    sandboxId: string;
+    /** The id's digest, which matches its receipt. */
+    sandboxIdDigest: string;
+    laneId: string;
+    /** How reclaim learned of the sandbox: its receipt, a create in this process whose receipt had
+     *  not landed, or E2B's list of sandboxes tagged with this run. */
+    source: "receipt" | "create" | "tag";
+    state: ReclaimOutcomeState;
+    detail?: string;
+}
+/** E2B's list of sandboxes carrying the run's owner tags. */
+export interface ReclaimTagSearch {
+    /** not-run: the search did not start, because an earlier step failed or the run was stopping. */
+    status: E2BTagSearch["status"] | "not-run";
+    /** Tagged sandboxes no receipt or create named. */
+    found: number;
+    detail?: string;
+}
+/**
+ * clean: every sandbox found is confirmed gone, and the tag search finished with no create still
+ * in flight. unconfirmed: a kill did not confirm. running (`--check` only): a sandbox still
+ * exists. unknown: nothing failed, but reclaim could not search E2B or a create was still in
+ * flight, so a sandbox it never saw may still run.
+ */
+export type ReclaimState = "clean" | "unconfirmed" | "running" | "unknown";
+/** One sandbox reclaim acts on, keyed by provider and raw id. */
+export interface Target {
+    provider: string;
+    rawId: string;
+    outcome: ReclaimOutcome;
+}
+/**
+ * The sandboxes one reclaim acts on, each once by provider and raw id. The receipt naming every
+ * sandbox found, each pending, lands before that sandbox's kill starts, so an exit during the
+ * kills leaves a record of each one not yet confirmed gone.
+ */
+export declare function targetSet(options: {
+    e2b: E2BDesktopModule | undefined;
+    check: boolean;
+    requestTimeoutMs: number;
+    earlier: ReclaimOutcome[];
+    persist: ReturnType<typeof receiptWriter>;
+}): {
+    snapshot: (carried?: ReclaimOutcome[]) => ReclaimOutcome[];
+    /** Add one sandbox; false when it was already in the set. */
+    add(provider: string, rawId: string, participant: string, source: ReclaimOutcome["source"], released?: boolean): boolean;
+    /** Write the receipt naming every sandbox found so far, then start their kills. */
+    start(): Promise<void>;
+    /** Wait for every kill, including ones added while waiting. */
+    drain(): Promise<void>;
+    finish(outcomes: readonly ReclaimOutcome[], state: ReclaimState): Promise<void>;
+};
+/** Search E2B by each distinct tag set; done only when every search finished. */
+export declare function searchTagSets(e2b: E2BDesktopModule | undefined, tagSets: readonly Record<string, string>[], options: {
+    requestTimeoutMs: number;
+    unavailable: string;
+}): Promise<E2BTagSearch>;
+export declare const GONE: Set<ReclaimOutcomeState>;
+/**
+ * The outcomes an earlier reclaim of this directory recorded, by digest. A receipt written before
+ * 0.110 names raw ids, which are digested; an unreadable or foreign receipt carries nothing.
+ */
+export declare function earlierOutcomes(root: PreparedOutputRoot, label: string): Promise<ReclaimOutcome[]>;
+export declare function rootState(outcomes: readonly ReclaimOutcome[], check: boolean, searched: boolean): ReclaimState;
+/** Resolves when `settled` does, or after `ms` if given, whichever is first. */
+export declare function settledWithin(settled: Promise<void>, ms: number | undefined): Promise<void>;
+/**
+ * Writes reclaim-receipt.json in order, one write at a time, each with the latest outcomes. A
+ * check writes nothing. A failed write adds one warning and leaves the result unchanged.
+ */
+export declare function receiptWriter(root: PreparedOutputRoot, runId: string, receiptCount: number, check: boolean, warnings: string[]): {
+    /** Queue one write with these outcomes; resolves once it has landed or failed. */
+    write(outcomes: readonly ReclaimOutcome[], state: ReclaimState): Promise<void>;
+};

package/dist/run/reclaim-outcomes.js

@@ -0,0 +1,213 @@
+// What one reclaim found and did, sandbox by sandbox: the outcome vocabulary of
+// reclaim-receipt.json, the set of sandboxes a reclaim acts on (each once, with its pending record
+// written before its kill starts), the tag search across the tag sets a run recorded, and the
+// receipt writer. src/run/reclaim.ts decides what to find; this module records what happened.
+import { REDACTED_SANDBOX_ID, redactText, sandboxIdDigest, toErrorMessage, } from "../evidence/redaction.js";
+import { destroyE2BSandbox, findE2BSandboxesByTags, inspectE2BSandbox, } from "../substrates/e2b/sandbox.js";
+import { readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { scrubSandboxIds } from "./sandbox-ids.js";
+import { isRecord } from "./type-guards.js";
+export const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
+export const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
+/**
+ * The sandboxes one reclaim acts on, each once by provider and raw id. The receipt naming every
+ * sandbox found, each pending, lands before that sandbox's kill starts, so an exit during the
+ * kills leaves a record of each one not yet confirmed gone.
+ */
+export function targetSet(options) {
+    const { e2b, check, requestTimeoutMs, earlier, persist } = options;
+    const targets = new Map();
+    const work = [];
+    const queued = [];
+    let started = false;
+    const snapshot = (carried = earlier) => {
+        const current = [...targets.values()].map((target) => target.outcome);
+        const seen = new Set(current.map((outcome) => outcome.sandboxIdDigest));
+        return [...current, ...carried.filter((outcome) => !seen.has(outcome.sandboxIdDigest))];
+    };
+    const act = (target) => actOn(e2b, target, { check, requestTimeoutMs }).then((settled) => {
+        target.outcome = settled;
+        void persist.write(snapshot(), "unknown");
+    });
+    return {
+        snapshot,
+        /** Add one sandbox; false when it was already in the set. */
+        add(provider, rawId, participant, source, released = false) {
+            const key = JSON.stringify([provider, rawId]);
+            if (targets.has(key))
+                return false;
+            const pending = outcomeFor(sandboxIdDigest(rawId), participant, source);
+            const target = {
+                provider,
+                rawId,
+                outcome: released
+                    ? { ...pending, state: "already-gone", detail: "its route released it before the stop" }
+                    : pending,
+            };
+            targets.set(key, target);
+            if (released)
+                return true;
+            if (started)
+                work.push(persist.write(snapshot(), "unknown").then(() => act(target)));
+            else
+                queued.push(target);
+            return true;
+        },
+        /** Write the receipt naming every sandbox found so far, then start their kills. */
+        async start() {
+            let size;
+            do {
+                size = targets.size;
+                await persist.write(snapshot(), "unknown");
+            } while (targets.size !== size);
+            started = true;
+            for (const target of queued)
+                work.push(act(target));
+        },
+        /** Wait for every kill, including ones added while waiting. */
+        async drain() {
+            let count;
+            do {
+                count = work.length;
+                await Promise.all(work);
+            } while (work.length !== count);
+        },
+        async finish(outcomes, state) {
+            await persist.write(outcomes, state);
+        },
+    };
+}
+/** Search E2B by each distinct tag set; done only when every search finished. */
+export async function searchTagSets(e2b, tagSets, options) {
+    if (e2b === undefined)
+        return { status: "unavailable", sandboxes: [], detail: options.unavailable };
+    const distinct = new Map(tagSets.map((tags) => [
+        JSON.stringify(Object.entries(tags).sort(([a], [b]) => a.localeCompare(b))),
+        tags,
+    ]));
+    const searches = await Promise.all([...distinct.values()].map((tags) => findE2BSandboxesByTags(e2b, tags, { requestTimeoutMs: options.requestTimeoutMs })));
+    const unfinished = searches.find((search) => search.status !== "done");
+    const sandboxes = new Map(searches.flatMap((search) => search.sandboxes).map((listed) => [listed.sandboxId, listed]));
+    return {
+        status: unfinished?.status ?? "done",
+        sandboxes: [...sandboxes.values()],
+        ...(unfinished?.detail === undefined ? {} : { detail: unfinished.detail }),
+    };
+}
+/** Kill (or look up) one sandbox, and say what happened in reclaim's vocabulary. */
+async function actOn(e2b, target, options) {
+    const { outcome, provider, rawId } = target;
+    if (provider !== "e2b" || e2b === undefined)
+        return {
+            ...outcome,
+            state: "unsupported-provider",
+            detail: `provider ${JSON.stringify(provider)} is not supported by this humanish version; nothing was attempted, and that provider's own timeout is the backstop`,
+        };
+    const attempt = options.check
+        ? await inspectE2BSandbox(e2b, rawId, options)
+        : await destroyE2BSandbox(e2b, rawId, options);
+    const { detail: _previous, ...rest } = outcome;
+    // A provider error that quotes the id is scrubbed; the raw id stays in sandbox-receipts.ndjson.
+    return "detail" in attempt
+        ? { ...rest, state: attempt.state, detail: scrubSandboxIds(attempt.detail, [rawId]) }
+        : { ...rest, state: attempt.state };
+}
+export const GONE = new Set(["killed", "already-gone"]);
+const OUTCOME_STATES = new Set([
+    "killed",
+    "already-gone",
+    "kill-failed",
+    "unsupported-provider",
+    "pending",
+]);
+/**
+ * The outcomes an earlier reclaim of this directory recorded, by digest. A receipt written before
+ * 0.110 names raw ids, which are digested; an unreadable or foreign receipt carries nothing.
+ */
+export async function earlierOutcomes(root, label) {
+    let parsed;
+    try {
+        const bytes = await readContainedRegularFile(root, RECLAIM_RECEIPT_ARTIFACT);
+        if (bytes === null)
+            return [];
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed) || parsed.runId !== label || !Array.isArray(parsed.outcomes))
+        return [];
+    const carried = [];
+    for (const entry of parsed.outcomes) {
+        if (!isRecord(entry))
+            continue;
+        const text = (key) => typeof entry[key] === "string" ? entry[key] : undefined;
+        const state = text("state");
+        const raw = text("sandboxId");
+        const digest = text("sandboxIdDigest") ??
+            (raw === undefined || raw === REDACTED_SANDBOX_ID ? undefined : sandboxIdDigest(raw));
+        if (digest === undefined || state === undefined || !OUTCOME_STATES.has(state))
+            continue;
+        const source = text("source");
+        const detail = text("detail");
+        carried.push({
+            ...outcomeFor(digest, text("laneId") ?? "unknown", source === "create" || source === "tag" ? source : "receipt"),
+            state: state,
+            ...(detail === undefined ? {} : { detail }),
+        });
+    }
+    return carried;
+}
+/** A pending outcome, naming the sandbox by digest only. */
+function outcomeFor(digest, participant, source) {
+    return {
+        sandboxId: REDACTED_SANDBOX_ID,
+        sandboxIdDigest: digest,
+        laneId: participant,
+        source,
+        state: "pending",
+    };
+}
+export function rootState(outcomes, check, searched) {
+    if (check && outcomes.some((outcome) => outcome.state === "running"))
+        return "running";
+    const gone = outcomes.every((outcome) => GONE.has(outcome.state));
+    if (!gone)
+        return check ? "unknown" : "unconfirmed";
+    return searched ? "clean" : "unknown";
+}
+/** Resolves when `settled` does, or after `ms` if given, whichever is first. */
+export async function settledWithin(settled, ms) {
+    if (ms === undefined)
+        return settled;
+    let timer;
+    await Promise.race([
+        settled,
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+/**
+ * Writes reclaim-receipt.json in order, one write at a time, each with the latest outcomes. A
+ * check writes nothing. A failed write adds one warning and leaves the result unchanged.
+ */
+export function receiptWriter(root, runId, receiptCount, check, warnings) {
+    let chain = Promise.resolve();
+    let failed = false;
+    return {
+        /** Queue one write with these outcomes; resolves once it has landed or failed. */
+        write(outcomes, state) {
+            if (check)
+                return chain;
+            const text = `${JSON.stringify({ schema: RECLAIM_RESULT_SCHEMA, at: new Date().toISOString(), runId, state, receiptCount, outcomes }, null, 2)}\n`;
+            chain = chain.then(() => writeContainedOutputFile(root, RECLAIM_RECEIPT_ARTIFACT, text, "utf8").catch((error) => {
+                if (failed)
+                    return;
+                failed = true;
+                warnings.push(`Reclaim ran but its receipt could not be written: ${redactText(toErrorMessage(error))}`);
+            }));
+            return chain;
+        },
+    };
+}

package/dist/run/reclaim.d.ts

@@ -1,28 +1,28 @@
 import { type E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type StoppedSandboxCreates } from "./sandbox-creates.js";
+import { RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, type ReclaimOutcome, type ReclaimState, type ReclaimTagSearch } from "./reclaim-outcomes.js";
 import { type PreparedRunArtifactPaths } from "./paths.js";
-declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
-export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
-interface ReclaimOutcome {
-    /** "[redacted-sandbox-id]"; the raw id is only in the run's sandbox-receipts.ndjson. */
-    sandboxId: string;
-    /** The id's digest, which matches its receipt. */
-    sandboxIdDigest: string;
-    laneId: string;
-    /** killed = kill(id) confirmed; already-gone = the server no longer knows the id (TTL or a
-     *  prior cleanup got it); kill-failed = the attempt errored (the TTL backstop still applies);
-     *  unsupported-provider = the receipt names a provider this version cannot reach, so nothing
-     *  was attempted. */
-    state: "killed" | "already-gone" | "kill-failed" | "unsupported-provider";
-    detail?: string;
-}
+export { RECLAIM_RECEIPT_ARTIFACT };
 export interface ReclaimResult {
     schema: typeof RECLAIM_RESULT_SCHEMA;
+    /** True only when `state` is clean. */
     ok: boolean;
+    state: ReclaimState;
+    /** `check` kills nothing and writes nothing. */
+    mode: "kill" | "check";
     cwd: string;
     runId: string;
-    /** Receipts found in the run's journal (0 = nothing was created, or the run predates receipts). */
+    /** Receipts found in the run's journal (0 = nothing journaled, or the run predates receipts). */
     receiptCount: number;
     outcomes: ReclaimOutcome[];
+    tagSearch: ReclaimTagSearch;
+    /** Creates that had not returned when reclaim finished; only the signal handler sees any. */
+    createsInFlight: number;
+    /**
+     * Why there was nothing to look for: `dry-run` when run.json or status.json records the run as
+     * a dry run, which creates no sandboxes. Reclaim then contacts E2B for nothing.
+     */
+    reason?: "dry-run";
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";
@@ -33,6 +33,13 @@ export interface ReclaimHooks {
     /** Tests inject a fake @e2b/desktop module; default loads the real one. */
     loadModule?: () => Promise<E2BDesktopModule>;
     requestTimeoutMs?: number;
+    /** Ask E2B whether each sandbox still exists, and kill nothing. */
+    check?: boolean;
+    /** The signal handler's view of this run's creates: the ids they reported, and those still
+     *  in flight, whose sandboxes are killed as their ids arrive. */
+    creates?: StoppedSandboxCreates;
+    /** How long to wait for in-flight creates before the tag search runs anyway. */
+    createsWaitMs?: number;
 }
 export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks?: ReclaimHooks): Promise<ReclaimResult>;
 /**
@@ -47,4 +54,3 @@ export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: Prepare
  * be running is left alone with the reason (see preflightReclaimDecision).
  */
 export declare function reclaimPreflightSandboxes(cwd: string, hooks?: ReclaimHooks): Promise<ReclaimResult>;
-export {};