humanish 0.110.0 → 0.110.2

package/dist/run/sandbox-receipts.js

@@ -1,6 +1,8 @@
-// Every created sandbox id is journaled to the run dir the moment create returns, before any work
-// happens in it. The participant loop lives in the caller's local process, so a sleeping laptop, crash or
-// kill loses every in-memory id; this append-only file keeps them for `humanish reclaim`.
+// Every created sandbox id is journaled to the run dir as soon as it reaches this process: when the
+// desktop startup guard reports it, or when create returns, before any work happens in it. The
+// participant loop lives in the caller's local process, so a sleeping laptop, crash or kill loses
+// every in-memory id; this append-only file keeps them for `humanish reclaim`, and tells verify and
+// the sweep which ids to look for.
 import { appendFile } from "node:fs/promises";
 import { prepareContainedOutputFile } from "./contained-output.js";
 export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
@@ -22,10 +24,11 @@ export function appendedSandboxIds(root) {
     return [...(appended.get(rootKey(root)) ?? [])];
 }
 /**
- * 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 async function appendSandboxReceipt(root, receipt) {
     const key = rootKey(root);
@@ -40,11 +43,57 @@ export async function appendSandboxReceipt(root, receipt) {
     try {
         const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
         await appendFile(filePath, `${JSON.stringify(receipt)}\n`, "utf8");
+        return true;
     }
     catch {
         // Swallowed on purpose; see the contract above.
+        return false;
     }
 }
+/** Append one owner line; false when the write failed, which never fails the create. */
+export async function appendSandboxOwner(root, owner) {
+    try {
+        const line = { at: new Date().toISOString(), provider: "e2b", owner };
+        const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
+        // The leading newline ends a line an earlier append left torn, so this record parses.
+        await appendFile(filePath, `\n${JSON.stringify(line)}\n`, "utf8");
+        return true;
+    }
+    catch {
+        // Never fails the create. Without the line, reclaim reports the run's sandboxes as unknown,
+        // never clean, so the next create tries again.
+        return false;
+    }
+}
+const RUN_KEY = /^[0-9a-f]{16}$/;
+/**
+ * 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 function parseSandboxOwners(text, runId) {
+    const owners = new Map();
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            const owner = parsed.owner;
+            if (parsed.provider !== "e2b" || owner === null || typeof owner !== "object")
+                continue;
+            if (Object.keys(owner).length !== 3 || owner.tool !== "humanish" || owner.runId !== runId)
+                continue;
+            if (typeof owner.runKey !== "string" || !RUN_KEY.test(owner.runKey))
+                continue;
+            owners.set(owner.runKey, { tool: "humanish", runId, runKey: owner.runKey });
+        }
+        catch {
+            // A torn line: skip it.
+        }
+    }
+    return [...owners.values()];
+}
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
 export function parseSandboxReceipts(text) {
     const receipts = [];

package/dist/run/stats.d.ts

@@ -1,3 +1,4 @@
+import { type RunDisplayState } from "./display.js";
 import { type CostTotals, type CostRow } from "./costs.js";
 declare const STATS_SCHEMA = "humanish.stats.v2";
 interface StatsParticipants {
@@ -13,6 +14,7 @@ interface StatsStudyRow {
     dryRun: number;
     /** Runs whose bundle carries a verdict; the denominator for passRate. */
     judged: number;
+    /** Runs that show as passed (runDisplay in src/run/display.ts): a pass verdict and an ok run. */
     passed: number;
     /** passed / judged, absent when judged is 0. */
     passRate?: number;
@@ -52,7 +54,10 @@ export interface StatsResult {
         estimatedSpendUsd: number;
         unpricedRuns: number;
         participants: StatsParticipants;
+        /** The participants' verdicts. `outcomes` says how many runs passed. */
         verdicts: Record<string, number>;
+        /** Runs by the state every surface shows them in (runDisplay in src/run/display.ts). */
+        outcomes: Partial<Record<RunDisplayState, number>>;
         costs: CostTotals;
     };
     studies: StatsStudyRow[];

package/dist/run/stats.js

@@ -2,6 +2,7 @@
 // numbers under the per-run rules: an estimate is labelled an estimate, a run whose cost is unknown
 // counts as unknown and never as zero, and every rate has a denominator next to it.
 import path from "node:path";
+import { runDisplay, runDisplayLabel } from "./display.js";
 import { readRunIndex } from "./run-index.js";
 import { addCostTotals, emptyCostTotals, readCostTotals, } from "./costs.js";
 import { round6 } from "./pricing.js";
@@ -68,7 +69,7 @@ function addToStudyRow(studies, entry, runUsd, costs) {
         row.dryRun += 1;
     if (entry.verdict !== undefined) {
         row.judged += 1;
-        if (entry.verdict === "pass")
+        if (runDisplay(entry).state === "passed")
             row.passed += 1;
     }
     if (entry.mode === "live" && entry.durationMs !== undefined)
@@ -157,6 +158,7 @@ export async function computeStats(cwdInput, options = {}) {
         unpricedRuns: 0,
         participants: emptyParticipants(),
         verdicts: {},
+        outcomes: {},
         costs: emptyCostTotals(),
     };
     const studies = new Map();
@@ -181,6 +183,8 @@ export async function computeStats(cwdInput, options = {}) {
         addParticipants(totals.participants, entry);
         if (entry.verdict !== undefined)
             totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
+        const { state } = runDisplay(entry);
+        totals.outcomes[state] = (totals.outcomes[state] ?? 0) + 1;
         addToStudyRow(studies, entry, runUsd, accounting.costs);
         addToDayRow(days, entry, runUsd, accounting.costs);
     }
@@ -239,7 +243,7 @@ function runCountLines(t) {
     const running = t.running > 0 ? ` (${t.running} still running)` : "";
     return [`live runs: ${t.live}${running}`, ...(t.dryRun > 0 ? [`dry runs: ${t.dryRun}`] : [])];
 }
-/** Spend, analysis, participants and verdicts across the selected live runs. */
+/** Spend, analysis, participants and outcomes across the selected live runs. */
 function totalsLines(t) {
     const c = t.costs;
     const incomplete = c.incompleteRunEstimates > 0
@@ -248,7 +252,7 @@ function totalsLines(t) {
     const unpriced = c.analysisUnpricedAttempts > 0 || c.analysisUnresolvedAttempts > 0
         ? `; ${c.analysisUnpricedAttempts} unpriced, ${c.analysisUnresolvedAttempts} unresolved`
         : "";
-    const verdicts = Object.entries(t.verdicts).map(([verdict, count]) => `${verdict} ${count}`);
+    const outcomes = Object.entries(t.outcomes).map(([state, count]) => `${runDisplayLabel(state)} ${count}`);
     return [
         `known estimated spend: ${knownMoney(c.estimatedTotalUsd)}`,
         `participants and desktops: ${knownMoney(c.runEstimatedUsd)}${incomplete}`,
@@ -265,7 +269,7 @@ function totalsLines(t) {
                 `participants: ${t.participants.reachedGoal} of ${t.participants.total} reached the goal, ${t.participants.reportedFriction} reported friction`,
             ]
             : []),
-        ...(verdicts.length > 0 ? [`verdicts: ${verdicts.join(", ")}`] : []),
+        ...(outcomes.length > 0 ? [`outcomes: ${outcomes.join(", ")}`] : []),
     ];
 }
 function dayLine(row) {

package/dist/run/status.d.ts

@@ -20,9 +20,9 @@ export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 interface RunStatusOutcome {
     /** `review.verdict` verbatim. */
     verdict?: string;
-    /** True when the run's own envelope reported success: the result's ok, recorded after finish. */
+    /** run.json's `outcome.ok`: the route result's ok. */
     ok?: boolean;
-    /** Whether the run worked as an execution, apart from its verdict; recorded after finish. */
+    /** run.json's `outcome.execution`: whether the run worked as an execution, apart from its verdict. */
     execution?: ExecutionOutcome;
     /** `review.participants` counts, when the run recorded any. */
     participants?: {
@@ -72,14 +72,11 @@ export interface RunStatusHandle {
     /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
      *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
-    /** After finish, add the result's ok and execution outcome to the finished record, so status.json
-     *  and the result agree. Before finish it does nothing. */
-    settle(result: {
-        ok: boolean;
-        execution: ExecutionOutcome;
-    }): Promise<void>;
+    /** After finish, replace the finished record's outcome with one read from a rewritten run.json,
+     *  so the two agree. Before finish, and after an interrupt, it does nothing. */
+    restate(outcome: RunStatusOutcome): Promise<void>;
     /** The process is being stopped by `signal`: state `interrupted`, `completedAt` and the signal.
-     *  It stops the cadence and makes a later finish or settle a no-op, so the route cannot write
+     *  It stops the cadence and makes a later finish or restate a no-op, so the route cannot write
      *  `running` or `finished` over it. When the run had finished it writes nothing, waits for the
      *  writes already queued and resolves false. */
     interrupt(signal: RunInterruptSignal): Promise<boolean>;

package/dist/run/status.js

@@ -4,15 +4,14 @@
 //
 // run.json remains the evidence of record. This file is a derived index and liveness record:
 // `verify` never gates on it, nothing here is a claim about what a participant did, and when the
-// two disagree run.json wins and this file can be rebuilt from it.
+// two disagree run.json wins. A finished record copies run.json's outcome, so it can be rebuilt
+// from it; a record written before run.json carried an outcome holds the only copy of the run's ok.
 //
 // Public safety: it holds only the run id, the study id/path/origin (the strings `humanish study list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
 import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
-import { redactText } from "../evidence/redaction.js";
-import { readRunSandboxIds, scrubSandboxIds } from "./sandbox-ids.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
 /** The file, relative to the run directory. */
 export const RUN_STATUS_FILE = "status.json";
@@ -46,6 +45,9 @@ export function runStatusOutcome(bundle) {
         ...(typeof bundle.cost?.fullyEstimated === "boolean"
             ? { estimatedCostComplete: bundle.cost.fullyEstimated }
             : {}),
+        ...(bundle.outcome?.state === "finished"
+            ? { ok: bundle.outcome.ok, execution: bundle.outcome.execution }
+            : {}),
     };
 }
 /**
@@ -103,28 +105,10 @@ export function beginRunStatus(runPaths, options) {
             };
             await write(finishedRecord);
         },
-        async settle(result) {
+        async restate(outcome) {
             if (finishedRecord === undefined)
                 return;
-            // The record is public-safe by construction, so each message passes the shape redaction
-            // again even though the routes scrubbed it. A route settles with its own result, so an SDK
-            // error here can still name a sandbox; the receipts give the ids to replace.
-            const ids = await readRunSandboxIds(runPaths);
-            const redacted = (failure) => ({
-                kind: failure.kind,
-                message: scrubSandboxIds(redactText(failure.message), ids),
-            });
-            const execution = {
-                succeeded: result.execution.succeeded,
-                failures: result.execution.failures.map(redacted),
-                ...(result.execution.warnings === undefined
-                    ? {}
-                    : { warnings: result.execution.warnings.map(redacted) }),
-            };
-            finishedRecord = {
-                ...finishedRecord,
-                outcome: { ...finishedRecord.outcome, ok: result.ok, execution },
-            };
+            finishedRecord = { ...finishedRecord, outcome };
             await write(finishedRecord);
         },
         async interrupt(signal) {

package/dist/run/stored-runs.d.ts

@@ -1,18 +1,7 @@
-import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
-import { type ReviewSummary, type RunBundle } from "./bundle.js";
-import { type CleanupAdapterResult, type CleanupResult } from "./results.js";
+import { type ReviewSummary } from "./bundle.js";
+import { type RunDisplay } from "./display.js";
 import { type VerifyResult } from "../verify/verify.js";
 declare const RUNS_SCHEMA = "humanish.runs-result.v1";
-export interface RunCleanupHooks {
-    /** @deprecated Ignored. Stored provider ids are not authority to load or mutate a provider. */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    cleanupAdapterResources?: (ctx: {
-        cwd: string;
-        runDir: string;
-        bundle: RunBundle;
-    }) => Promise<CleanupAdapterResult[]>;
-    now?: () => Date;
-}
 export interface RunsResult {
     schema: typeof RUNS_SCHEMA;
     ok: boolean;
@@ -22,6 +11,8 @@ export interface RunsResult {
         createdAt: string | null;
         mode: string | null;
         path: string;
+        /** How the run reads (runDisplay in src/run/display.ts); absent when it has no readable run.json. */
+        display?: RunDisplay;
     }>;
     latest: string | null;
     error?: {
@@ -29,10 +20,10 @@ export interface RunsResult {
         message: string;
     };
 }
-export declare function cleanupRun(cwdInput: string, runInput: string, hooks?: RunCleanupHooks): Promise<CleanupResult>;
 export declare function listRuns(cwdInput: string): Promise<RunsResult>;
 export declare function readReview(cwdInput: string, runInput: string): Promise<VerifyResult | (ReviewSummary & {
     path: string;
     runId: string;
+    display?: RunDisplay;
 })>;
 export {};

package/dist/run/stored-runs.js

@@ -1,157 +1,17 @@
-import { REDACTED_SANDBOX_ID, sandboxIdDigest } from "../evidence/redaction.js";
 import { lstat, readdir } from "node:fs/promises";
-import { runNotFoundMessage } from "./run-not-found.js";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
-import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, validatePreparedRunArtifactPaths, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputFile, readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
-import { CLEANUP_SCHEMA, } from "./results.js";
-import { isReviewSummary, isRunBundle } from "./bundle-shape.js";
+import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, } from "./contained-output.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
+import { bundleDisplayFacts, runDisplay } from "./display.js";
+import { RUN_STATUS_FILE } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 import { invalidRunStorageVerifyResult, verifyResolvedRun, } from "../verify/verify.js";
 const RUNS_SCHEMA = "humanish.runs-result.v1";
-/** A cleanup result that refused before inspecting any resource. */
-function cleanupRefusal(cwd, runInput, checkedAt, error, bundlePath) {
-    return {
-        schema: CLEANUP_SCHEMA,
-        ok: false,
-        cwd,
-        run: runInput,
-        ...(bundlePath === undefined ? {} : { bundlePath }),
-        checkedAt,
-        summary: { resources: 0, killed: 0, alreadyClean: 0, failed: 0, skipped: 0 },
-        resources: [],
-        adapterResults: [],
-        warnings: [],
-        error,
-    };
-}
-/** What the recorded evidence says about one provider resource; nothing is killed from here. */
-function recordedResourceResult(resource) {
-    // Named by digest: a run recorded before 0.110 holds the raw id here, which is digested.
-    const raw = resource.id === REDACTED_SANDBOX_ID ? undefined : resource.id;
-    const idDigest = resource.idDigest ?? (raw === undefined ? undefined : sandboxIdDigest(raw));
-    const base = {
-        provider: resource.provider,
-        kind: resource.kind,
-        id: REDACTED_SANDBOX_ID,
-        ...(idDigest === undefined ? {} : { idDigest }),
-    };
-    if (resource.provider !== "e2b-desktop" || resource.kind !== "sandbox") {
-        return {
-            ...base,
-            status: "skipped",
-            message: "cleanup only supports e2b-desktop sandbox resources",
-        };
-    }
-    if (resource.status === "killed" || resource.cleanup?.killed === true) {
-        return {
-            ...base,
-            status: "already_clean",
-            message: "resource was already recorded as killed",
-        };
-    }
-    return {
-        ...base,
-        status: "failed",
-        message: "automatic provider cleanup requires a verified resource lease",
-    };
-}
-export async function cleanupRun(cwdInput, runInput, hooks = {}) {
-    const cwd = path.resolve(cwdInput);
-    const checkedAt = (hooks.now ?? (() => new Date()))().toISOString();
-    let resolved;
-    try {
-        resolved = await resolveRunPath(cwd, runInput);
-    }
-    catch {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_INVALID_RUN_BUNDLE",
-            message: "Run storage failed containment validation.",
-        });
-    }
-    if (!resolved) {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_RUN_NOT_FOUND",
-            message: await runNotFoundMessage(cwd, runInput),
-        });
-    }
-    const runPaths = resolved;
-    const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const cleanupPath = path.join(runPaths.absoluteRunRoot, "cleanup.json");
-    await prepareContainedOutputFile(runPaths, "cleanup.json");
-    const bundleBytes = await readContainedRegularFile(runPaths, RUN_BUNDLE_FILE);
-    let bundle = null;
-    if (bundleBytes) {
-        try {
-            bundle = JSON.parse(bundleBytes.toString("utf8"));
-        }
-        catch {
-            bundle = null;
-        }
-    }
-    if (!isRunBundle(bundle)) {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_INVALID_RUN_BUNDLE",
-            message: "Run bundle failed cleanup shape validation.",
-        }, path.relative(cwd, bundlePath));
-    }
-    const warnings = [];
-    const providerResources = bundle.providerResources ?? [];
-    const resources = providerResources.map(recordedResourceResult);
-    let adapterResults = [];
-    if (hooks.cleanupAdapterResources) {
-        try {
-            adapterResults = await hooks.cleanupAdapterResources({
-                cwd,
-                runDir: runPaths.physicalRunRoot,
-                bundle,
-            });
-        }
-        catch (error) {
-            adapterResults = [
-                {
-                    id: "adapter-cleanup",
-                    ok: false,
-                    message: error instanceof Error ? error.message : String(error),
-                },
-            ];
-        }
-        await validatePreparedRunArtifactPaths(runPaths);
-    }
-    if (providerResources.length === 0 && adapterResults.length === 0) {
-        warnings.push("Run bundle recorded no provider resource evidence; nothing to inspect.");
-    }
-    const summary = {
-        resources: resources.length,
-        killed: 0,
-        alreadyClean: resources.filter((resource) => resource.status === "already_clean").length,
-        failed: resources.filter((resource) => resource.status === "failed").length +
-            adapterResults.filter((result) => !result.ok).length,
-        skipped: resources.filter((resource) => resource.status === "skipped").length,
-    };
-    const ok = summary.failed === 0;
-    const result = {
-        schema: CLEANUP_SCHEMA,
-        ok,
-        cwd: PUBLIC_TARGET_CWD,
-        run: runInput,
-        runId: bundle.runId,
-        bundlePath: path.relative(cwd, bundlePath),
-        cleanupPath: path.relative(cwd, cleanupPath),
-        checkedAt,
-        summary,
-        resources,
-        adapterResults,
-        warnings,
-    };
-    await validatePreparedRunArtifactPaths(runPaths);
-    await writeContainedOutputFile(runPaths, "cleanup.json", `${JSON.stringify(result, null, 2)}\n`, "utf8");
-    return result;
-}
 export async function listRuns(cwdInput) {
     const cwd = path.resolve(cwdInput);
     const runsRootPath = resolveRunsRoot(cwd);
@@ -216,6 +76,7 @@ export async function listRuns(cwdInput) {
             createdAt: isRecord(bundle) && typeof bundle.createdAt === "string" ? bundle.createdAt : null,
             mode: isRecord(bundle) && typeof bundle.mode === "string" ? bundle.mode : null,
             path: path.join(RUNS_RELATIVE_ROOT, entryName),
+            ...(await listedRunDisplay(entryRunPaths, bundle)),
         });
     }
     if (runsRoot) {
@@ -234,6 +95,29 @@ export async function listRuns(cwdInput) {
         latest: latest?.runId ?? null,
     };
 }
+/**
+ * A listed run's display, from its run.json and, for a bundle without an outcome, its status
+ * record. Like the listing's other fields it reads the file without verifying it; a run.json
+ * that is not an object naming a run gets none.
+ */
+async function listedRunDisplay(runPaths, bundle) {
+    if (!isRecord(bundle) || typeof bundle.runId !== "string")
+        return {};
+    const outcome = isRunOutcome(bundle.outcome) ? bundle.outcome : undefined;
+    const status = outcome === undefined ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE) : undefined;
+    const facts = bundleDisplayFacts({
+        runId: bundle.runId,
+        ...(typeof bundle.mode === "string" ? { mode: bundle.mode } : {}),
+        ...(isRecord(bundle.review) && typeof bundle.review.verdict === "string"
+            ? { review: { verdict: bundle.review.verdict } }
+            : {}),
+        ...(Array.isArray(bundle.simulations)
+            ? { simulations: bundle.simulations.filter(isRecord) }
+            : {}),
+        ...(outcome === undefined ? {} : { outcome }),
+    }, status);
+    return { display: runDisplay(facts) };
+}
 function runsUnavailableResult(cwd, error) {
     return {
         schema: RUNS_SCHEMA,
@@ -279,5 +163,6 @@ export async function readReview(cwdInput, runInput) {
         ...projected,
         path: path.relative(cwd, path.join(runPaths.absoluteRunRoot, "review.json")),
         runId: path.basename(runPaths.absoluteRunRoot),
+        ...(runPaths ? await listedRunDisplay(runPaths, bundle) : {}),
     };
 }

package/dist/run/streams.d.ts

@@ -171,8 +171,9 @@ export interface RunStream {
     /**
      * The judge's status for this participant (`judgedStatus` in src/run/judge.ts). It differs from
      * the trace status when a goal_satisfied session reported a blocker or never engaged. Computer-use
-     * fan-out writes it for a finished live participant; rerun selection reads it. Absent elsewhere,
-     * and in bundles written before it existed.
+     * and shared-world runs write it for a participant whose session finished; rerun selection and
+     * the Observer read it. Absent on the terminal and scripted routes, whose judge has no blocker
+     * rule, and in bundles written before it existed.
      */
     judgedStatus?: ActorStatus;
     transport: "snapshot" | "polling" | "sse" | "pty" | "app-server";

package/dist/study/agents-section.d.ts

@@ -0,0 +1,21 @@
+export type AgentsSectionReplacement = 
+/** The file has no humanish section. */
+{
+    kind: "absent";
+}
+/** A start marker with no end marker, in text no release wrote: possibly hand-edited. */
+ | {
+    kind: "unknown";
+}
+/** The file with humanish's section replaced; equal to the input when it was already current. */
+ | {
+    kind: "replaced";
+    contents: string;
+};
+/**
+ * `existing` with humanish's section replaced by `section` (as `agentsSection()` returns it, with
+ * its leading blank line). The replaced range runs from the start of the heading line that holds
+ * the start marker to the end of the end marker's line, or, without an end marker, through the
+ * text of the release that wrote it.
+ */
+export declare function replaceAgentsSection(existing: string, section: string): AgentsSectionReplacement;

package/dist/study/agents-section.js

@@ -0,0 +1,86 @@
+// Finds humanish's own section in a project's `AGENTS.md` so init can replace it on a rerun and
+// leave every other byte alone. Releases up to 0.110.1 wrote the section with a start marker and
+// no end marker, so for those the section's extent is known only by matching a text init wrote.
+import { createHash } from "node:crypto";
+import { AGENTS_SECTION_END_MARKER, AGENTS_SECTION_MARKER } from "../cli/first-run-path.js";
+/**
+ * Each section text a release wrote before the end marker existed, from its `## humanish` heading
+ * to its final newline: the UTF-16 length and the sha256 of its UTF-8 bytes. Comparing digests
+ * keeps the retired command and key names those versions taught out of the source.
+ */
+const SECTIONS_WITHOUT_END_MARKER = [
+    {
+        releases: "0.59.0 to 0.80.0",
+        length: 1171,
+        sha256: "3739c98204cc5b2df603238398bffc5c4a491782a3ab72475b0ad9d967698a11",
+    },
+    {
+        releases: "0.81.0 to 0.93.1",
+        length: 1191,
+        sha256: "169d646f329f35af1b5e51eb02cd0454a717cf29a447a230f3aa2d5a7354729c",
+    },
+    {
+        releases: "0.94.0 to 0.99.1",
+        length: 1214,
+        sha256: "68f987769893f041ab78e0b1cb4cd8db14a438511f15b58f9eaa412ea002b51f",
+    },
+    {
+        releases: "0.100.0 to 0.105.0",
+        length: 1548,
+        sha256: "f60c37003d21b1d8280d002f203130c60bc3c23454b018b3207407faa01cb76f",
+    },
+    {
+        releases: "0.106.0 to 0.107.0",
+        length: 1686,
+        sha256: "c2cd9d831e17021ad4477f300dbea13df1613bec8f30ebbabfabcd749b73f7f7",
+    },
+    {
+        releases: "0.108.0",
+        length: 1679,
+        sha256: "6352ec71d7c5073b2bf4993293753944eaf7cfd21169a311f42d9f52bdacfead",
+    },
+    {
+        releases: "0.109.0 to 0.110.0",
+        length: 1681,
+        sha256: "2559a93463cf50225aadf6753e84dd6e32b25aa3afdf8066e90d19c5d88d0ef0",
+    },
+    {
+        releases: "0.110.1",
+        length: 2014,
+        sha256: "9fb4cb94400c7447ab0fece861339e50de8e9be99797cf0763d7502be0fe668d",
+    },
+];
+/**
+ * `existing` with humanish's section replaced by `section` (as `agentsSection()` returns it, with
+ * its leading blank line). The replaced range runs from the start of the heading line that holds
+ * the start marker to the end of the end marker's line, or, without an end marker, through the
+ * text of the release that wrote it.
+ */
+export function replaceAgentsSection(existing, section) {
+    const marker = existing.indexOf(AGENTS_SECTION_MARKER);
+    if (marker < 0)
+        return { kind: "absent" };
+    const start = existing.lastIndexOf("\n", marker) + 1;
+    const replacement = section.replace(/^\n/, "");
+    const endMarker = existing.indexOf(AGENTS_SECTION_END_MARKER, marker);
+    if (endMarker >= 0) {
+        const lineEnd = existing.indexOf("\n", endMarker);
+        const end = lineEnd < 0 ? existing.length : lineEnd + 1;
+        return {
+            kind: "replaced",
+            contents: existing.slice(0, start) + replacement + existing.slice(end),
+        };
+    }
+    for (const known of SECTIONS_WITHOUT_END_MARKER) {
+        const candidate = existing.slice(start, start + known.length);
+        if (candidate.length !== known.length)
+            continue;
+        if (createHash("sha256").update(candidate).digest("hex") !== known.sha256)
+            continue;
+        return {
+            kind: "replaced",
+            contents: existing.slice(0, start) + replacement + existing.slice(start + known.length),
+        };
+    }
+    return { kind: "unknown" };
+}

package/dist/study/doctor.d.ts

@@ -1,7 +1,7 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import type { StudyConfig } from "./types.js";
 import type { PlanResult } from "./plan-types.js";
-import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
+import { type DetectedLocalAgent } from "../actors/local-agent/cli.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { DoctorCheckDraft } from "../cli/doctor.js";
 import { type CodexInstallation } from "../actors/codex/codex-admission.js";