humanish 0.110.0 → 0.110.1

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,23 @@
 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;
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";
@@ -33,6 +28,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 +49,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 {};