humanish 0.110.1 → 0.110.3

package/dist/routes/terminal/route.d.ts

@@ -1,20 +1,10 @@
+import { type RefusedStudy } from "../../run/route-shell.js";
 import { type TerminalRefusal } from "./plan.js";
 import type { TerminalPlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
-import { type RunTerminalProductStudyOptions, type TerminalProductStudyResult, type TerminalRunInput } from "./types.js";
-/**
- * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
- * record the route has always returned, and otherwise runs the plan.
- */
-export declare function runTerminalProductStudy(options: RunTerminalProductStudyOptions): Promise<TerminalProductStudyResult>;
+import { type TerminalProductStudyResult, type TerminalRunInput } from "./types.js";
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
-export declare function terminalStudyRefusal(options: RunTerminalProductStudyOptions, refusal: TerminalRefusal): Promise<TerminalProductStudyResult>;
-/**
- * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
- * gets: whichever of its fail-closed exits the run takes, the run it started is closed, and only a
- * run that published its final bundle reaches automatic analysis.
- */
-export declare function runTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<TerminalProductStudyResult>;
+export declare function terminalStudyRefusal(options: TerminalRunInput & RefusedStudy, refusal: TerminalRefusal): Promise<TerminalProductStudyResult>;
 /**
  * runStudyWith's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
  * before any run scope opens, so the CLI can present their refusal before it loads a declared

package/dist/routes/terminal/route.js

@@ -11,10 +11,11 @@
 // The safety contract (`docs/history/goals/terminal-product-lane/goal.md`) is enforced by construction in
 // the files each item names, and checked by the verifier (verify/actor.ts
 // validateTerminalProductEvidence):
-//   1. Explicit key placement. openai-env (default) injects the raw runtime key command-scoped,
-//      never through Sandbox.create({envs}). Opt-in openai-egress sends it only in the host-side E2B
-//      header transform and passes an inert command placeholder. The proxy is spendable by every
-//      sandbox process from creation; this protects the raw key, not provider spending.
+//   1. Explicit key placement. openai-egress (default) sends the raw runtime key only in the
+//      host-side E2B header transform and passes an inert command placeholder. The proxy is
+//      spendable by every sandbox process from creation; this protects the raw key, not provider
+//      spending. Opt-in openai-env injects the raw key command-scoped, never through
+//      Sandbox.create({envs}).
 //      Enforced in credentials.ts and runtime-auth.ts.
 //   2. Fail-closed cap. The live key is never exercised without scenario.caps in force: maxUsd
 //      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).
@@ -43,31 +44,16 @@
 //      humanish never calls Sandbox.list to prove cleanup, so a shared operator key never reaches a
 //      sandbox it did not create. A live run that cannot prove teardown fails closed.
 //      Enforced in sandbox.ts.
-import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
 import path from "node:path";
-import { runScope } from "../../run/run.js";
-import { planTerminalStudy } from "./plan.js";
+import {} from "../../run/run.js";
+import { admitRoute, completeRefusalAnalysis, } from "../../run/route-shell.js";
+import {} from "./plan.js";
 import { runDryTerminalStudy } from "./dry-run.js";
 import { checkLiveTerminalMachine, runLiveTerminalSession } from "./session.js";
 import { terminalRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
-/**
- * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
- * record the route has always returned, and otherwise runs the plan.
- */
-export async function runTerminalProductStudy(options) {
-    const { config, dryRun, ...input } = options;
-    const planned = planTerminalStudy(config, {
-        dryRun,
-        hasCostProbe: input.deps?.costProbe !== undefined,
-    });
-    if (planned.ok)
-        return runTerminalPlan(planned.plan, input);
-    return terminalStudyRefusal(options, planned.refusal);
-}
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
 export function terminalStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
@@ -82,60 +68,35 @@ export function terminalStudyRefusal(options, refusal) {
         warnings: [],
         error: { code: refusal.code, message: refusal.message },
     };
-    // A refusal starts no run, so a declared or default analysis is recorded as skipped.
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
-}
-/**
- * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
- * gets: whichever of its fail-closed exits the run takes, the run it started is closed, and only a
- * run that published its final bundle reaches automatic analysis.
- */
-export async function runTerminalPlan(plan, input) {
-    const admission = await admitTerminalRun(plan, input);
-    return admission.ok ? runAdmittedTerminalRun(admission.admitted, input) : admission.result;
+    return completeRefusalAnalysis(refused, config, options);
 }
 /**
  * runStudyWith's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
  * before any run scope opens, so the CLI can present their refusal before it loads a declared
  * scorer, and returns the run that continues from them with that scorer.
  */
-export async function admitTerminalPlan(plan, input) {
-    const admission = await admitTerminalRun(plan, input);
-    if (!admission.ok)
-        return { ok: false, outcome: terminalOutcome(admission.result) };
-    return {
-        ok: true,
-        run: async (scorer) => terminalOutcome(await runAdmittedTerminalRun(admission.admitted, withLateScorer(input, scorer, terminalRouteScorer))),
-    };
-}
-function terminalOutcome(result) {
-    return { route: "terminal", result };
+export function admitTerminalPlan(plan, input) {
+    return admitRoute({
+        route: "terminal",
+        analysis: plan.analysis,
+        input,
+        admit: () => admitTerminalRun(plan, input),
+        withScorer: (base, scorer) => withLateScorer(base, scorer, terminalRouteScorer),
+        runInScope: runTerminalPlanInScope,
+    });
 }
-/**
- * A live plan's local checks, made outside any run scope. A refusal is the result runTerminalPlan
- * returns for it, with the analysis record of a run that never started.
- */
-async function admitTerminalRun(plan, input) {
+/** A live plan's local checks, made outside any run scope. */
+function admitTerminalRun(plan, input) {
     const warnings = [];
     if (plan.dryRun)
         return { ok: true, admitted: { plan, warnings } };
     const checked = checkLiveTerminalMachine(plan, input, warnings);
     if (checked.ok)
         return { ok: true, admitted: { plan, warnings, runtimeEnv: checked.runtimeEnv } };
-    const refused = terminalFailure(plan, input, warnings)(checked.code, checked.message);
-    return { ok: false, result: await completeTerminalAnalysis(plan, input, refused, undefined) };
-}
-/** Runs an admitted plan in its own run scope, then its automatic analysis. */
-async function runAdmittedTerminalRun(admitted, input) {
-    const { result, finished } = await runScope((scope) => runTerminalPlanInScope(admitted, input, scope));
-    return completeTerminalAnalysis(admitted.plan, input, result, finished);
-}
-function completeTerminalAnalysis(plan, input, result, finished) {
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
-        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
-        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
-    });
+    return {
+        ok: false,
+        result: terminalFailure(plan, input, warnings)(checked.code, checked.message),
+    };
 }
 /** The route's envelope for a run that stops before its bundle. */
 function terminalFailure(plan, input, warnings) {

package/dist/routes/terminal/runtime-auth.d.ts

@@ -1,4 +1,10 @@
+import type { StudyRuntimeAuth } from "../../study/types.js";
 import type { E2BNetworkOptions } from "../../substrates/e2b/sdk.js";
+/**
+ * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
+ * so the raw key stays in the host-side E2B request unless a study declares openai-env.
+ */
+export declare const DEFAULT_RUNTIME_AUTH: StudyRuntimeAuth;
 /** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
 export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
 /** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */

package/dist/routes/terminal/runtime-auth.js

@@ -1,3 +1,8 @@
+/**
+ * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
+ * so the raw key stays in the host-side E2B request unless a study declares openai-env.
+ */
+export const DEFAULT_RUNTIME_AUTH = "openai-egress";
 const OPENAI_EGRESS_HOST = "api.openai.com";
 /** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
 export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";

package/dist/routes/terminal/session.d.ts

@@ -13,9 +13,8 @@ export declare function checkLiveTerminalMachine(plan: LiveTerminalPlan, input:
     readonly message: string;
 };
 /**
- * The live in-sandbox agent session orchestrator (mirror of runCuaActorStudy's E2B branch). Enforces
- * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
- * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * The live in-sandbox agent session orchestrator. Enforces the 8-point safety contract by
+ * construction; fails closed before any sandbox/key/spend on any precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
  * the redacted terminal event stream + normalized transcript, the agent report, and the
  * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
  */

package/dist/routes/terminal/session.js

@@ -38,9 +38,8 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
     return { ok: true, runtimeEnv };
 }
 /**
- * The live in-sandbox agent session orchestrator (mirror of runCuaActorStudy's E2B branch). Enforces
- * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
- * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * The live in-sandbox agent session orchestrator. Enforces the 8-point safety contract by
+ * construction; fails closed before any sandbox/key/spend on any precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
  * the redacted terminal event stream + normalized transcript, the agent report, and the
  * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
  */

package/dist/routes/terminal/types.d.ts

@@ -6,7 +6,6 @@ import type { RunScope } from "../../run/run.js";
 import type { buildRuntimeAuth } from "./credentials.js";
 import type { TerminalPlan } from "../../study/plan-types.js";
 import type { StudyDeps } from "../../study/study-deps.js";
-import type { StudyConfig } from "../../study/types.js";
 import type { ObserverResult } from "../../observer/render.js";
 import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "../../run/bundle.js";
 import { type StudyResultIdentity } from "../../run/study-result.js";
@@ -97,15 +96,13 @@ export interface TerminalScorer {
      */
     deriveFeedback?: (ctx: TerminalProductScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
 }
-export interface RunTerminalProductStudyOptions {
+/** What a terminal run takes besides its plan. The plan carries the config, dry run and study. */
+export interface TerminalRunInput {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
     /** Reports the analysis window to onEvent; built by normalizeRunStudyOptions. */
     emit?: (event: StudyEvent) => void;
     cwd: string;
-    config: StudyConfig;
-    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
-    dryRun: boolean;
     open?: boolean;
     runId?: string;
     /**
@@ -312,8 +309,6 @@ export interface TerminalLedgers {
     /** The no-spend proof derived from `cost`. Never an independent assertion. */
     noSpendProof: NoSpendProof;
 }
-/** What a terminal run takes besides its plan. The plan carries the config, dry run and study. */
-export type TerminalRunInput = Omit<RunTerminalProductStudyOptions, "config" | "dryRun">;
 /** A live terminal plan: its caps are the fail-closed ones planTerminalStudy required. */
 export type LiveTerminalPlan = Extract<TerminalPlan, {
     readonly dryRun: false;

package/dist/run/dry-run.js

@@ -11,6 +11,7 @@ import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./
 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.
@@ -49,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();

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.
@@ -126,7 +127,7 @@ export const EXECUTION_FAILURE_KINDS = [
 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/reclaim.d.ts

@@ -18,6 +18,11 @@ export interface ReclaimResult {
     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";

package/dist/run/reclaim.js

@@ -11,12 +11,16 @@
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
 import { containedPathAbsent, readContainedRegularFile, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
-import { resolveRunPath } from "./locate.js";
+import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { RUN_STATUS_FILE } from "./status.js";
+import { isRecord } from "./type-guards.js";
 import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 import { sandboxOwnerTags, } from "./sandbox-creates.js";
 import { earlierOutcomes, GONE, RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, receiptWriter, rootState, searchTagSets, settledWithin, targetSet, } from "./reclaim-outcomes.js";
 import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { runIdOf } from "./paths.js";
+import { cli } from "../cli/invocation.js";
 export { RECLAIM_RECEIPT_ARTIFACT };
 export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
     return reclaimRun(cwd, runInput, () => resolveRunPath(cwd, runInput), hooks);
@@ -54,11 +58,14 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
             ...base,
             error: {
                 code: "HUMANISH_RECLAIM_RUN_NOT_FOUND",
-                message: `No run found for "${runInput}" (use \`humanish runs\` to list runs).`,
+                message: `No run found for "${runInput}" (use \`${cli("runs")}\` to list runs).`,
             },
         };
     }
     const runId = runIdOf(runPaths);
+    // The signal handler passes the creates it stopped and decides from what they reported.
+    if (hooks.creates === undefined && (await recordedDryRun(runPaths)))
+        return { ...base, ok: true, state: "clean", runId, reason: "dry-run" };
     const reclaimed = await reclaimRoot(runPaths, runId, hooks, warnings);
     if (reclaimed.kind === "module-unavailable")
         return {
@@ -85,6 +92,31 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
         createsInFlight,
     };
 }
+/**
+ * Whether the run records that it was a dry run: run.json and status.json, each one present, say
+ * `dry-run`. A run with neither record is not taken for one. A journal with any line in it, or an
+ * earlier reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a
+ * live one whatever its records say.
+ */
+async function recordedDryRun(runPaths) {
+    const modes = [];
+    for (const file of [RUN_BUNDLE_FILE, RUN_STATUS_FILE]) {
+        const record = await readRunJsonIfExists(runPaths, file);
+        if (isRecord(record))
+            modes.push(record.mode);
+    }
+    if (modes.length === 0 || modes.some((mode) => mode !== "dry-run"))
+        return false;
+    if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
+        const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+        if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
+            return false;
+    }
+    if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
+        return true;
+    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
+    return journal !== null && journal.toString("utf8").trim() === "";
+}
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/route-shell.d.ts

@@ -0,0 +1,60 @@
+import { type AnalysisInput } from "../analysis/automatic-completion.js";
+import type { AutomaticAnalysisDeps } from "../analysis/automatic.js";
+import type { AdmittedPlan, StudyResult } from "../run-study.js";
+import type { PlannedAnalysis } from "../study/plan-types.js";
+import type { LateScorer } from "../study/route-inputs.js";
+import type { StudyRoute } from "../study/routing.js";
+import type { StudyConfig } from "../study/types.js";
+import { type RunScope } from "./run.js";
+type ShellRoute = Exclude<StudyRoute, "preview">;
+/** A route's local checks: the refused result, or what its run continues from. */
+export type RouteAdmission<R extends ShellRoute, A> = {
+    readonly ok: false;
+    readonly result: StudyResult<R>;
+} | {
+    readonly ok: true;
+    readonly admitted: A;
+};
+/** A route's own parts of its run. Everything around them is admitRoute's. */
+export interface RouteShell<R extends ShellRoute, I extends AnalysisInput, A> {
+    readonly route: R;
+    /** The plan's automatic analysis, which both the refused result and the run complete. */
+    readonly analysis: PlannedAnalysis | undefined;
+    /** The route's input as the checks admitted it. */
+    readonly input: I;
+    /** The checks that need no scorer, made before any run scope opens. */
+    admit(): Promise<RouteAdmission<R, A>> | RouteAdmission<R, A>;
+    /** The run inside its run scope, with the input a late scorer joined. */
+    runInScope(admitted: A, input: I, scope: RunScope): Promise<StudyResult<R>>;
+    /** Layers a scorer the CLI loaded after the checks over the input. Scripted takes no scorer. */
+    readonly withScorer?: (input: I, scorer: LateScorer | undefined) => I;
+    /** Computer use's reason to skip analysis: a local VM study whose cleanup is unconfirmed. */
+    readonly analysisRefusal?: AutomaticAnalysisDeps["refusal"];
+    /**
+     * Computer use and shared world receive email. The run and its analysis share one scope for the
+     * secrets it registers. The other routes run outside any scope, where scrubbing changes nothing.
+     */
+    readonly commsSecrets?: boolean;
+}
+/**
+ * Runs a route's checks and returns the refusal they made or the route's run. A refusal carries the
+ * analysis record of a run that never started. The run opens its own run scope, so whichever exit
+ * it takes closes the run it started, and only a run that published its final bundle is analyzed.
+ */
+export declare function admitRoute<R extends ShellRoute, I extends AnalysisInput, A>(shell: RouteShell<R, I, A>): Promise<AdmittedPlan<R>>;
+/**
+ * A refused study's result with the analysis record a refusal gets: it starts no run, so a declared
+ * or default analysis is recorded as skipped.
+ */
+export declare function completeRefusalAnalysis<T extends {
+    cwd: string;
+    runId: string;
+    dryRun: boolean;
+}>(refused: T, config: StudyConfig, input: AnalysisInput): Promise<T>;
+/** What a refused study's envelope reads besides the route's input. */
+export interface RefusedStudy {
+    readonly config: StudyConfig;
+    /** The run's resolved dry run. */
+    readonly dryRun: boolean;
+}
+export {};

package/dist/run/route-shell.js

@@ -0,0 +1,51 @@
+// The shell the computer-use, scripted, terminal and shared-world routes share. A route supplies
+// its local checks and the body it runs inside the run scope. admitRoute completes the automatic
+// analysis of a refusal and of a run, and wraps the result as the route's outcome, so a change to
+// either is made here once. The preview route records no run and has no shell.
+import { completeAutomaticAnalysis } from "../analysis/automatic-completion.js";
+import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
+import { runScope } from "./run.js";
+import { withTransientCommsSecrets } from "./transient-comms-secrets.js";
+/**
+ * Runs a route's checks and returns the refusal they made or the route's run. A refusal carries the
+ * analysis record of a run that never started. The run opens its own run scope, so whichever exit
+ * it takes closes the run it started, and only a run that published its final bundle is analyzed.
+ */
+export async function admitRoute(shell) {
+    const complete = (input, result, finished) => completeAutomaticAnalysis(result, finished, shell.analysis?.config, input, {
+        ...(shell.analysis === undefined ? {} : { trigger: shell.analysis.trigger }),
+        preferLargerOutput: shell.analysis?.preferLargerOutput === true,
+        ...(shell.analysisRefusal === undefined ? {} : { refusal: shell.analysisRefusal }),
+    });
+    const admission = await shell.admit();
+    if (!admission.ok)
+        return {
+            ok: false,
+            outcome: routeOutcome(shell.route, await complete(shell.input, admission.result, undefined)),
+        };
+    const { admitted } = admission;
+    return {
+        ok: true,
+        run: async (scorer) => {
+            // The scorer joins the input only; whatever the checks admitted stays what the run uses.
+            const input = shell.withScorer?.(shell.input, scorer) ?? shell.input;
+            const run = async () => {
+                const { result, finished } = await runScope((scope) => shell.runInScope(admitted, input, scope));
+                return complete(input, result, finished);
+            };
+            return routeOutcome(shell.route, await (shell.commsSecrets ? withTransientCommsSecrets(run) : run()));
+        },
+    };
+}
+/**
+ * A refused study's result with the analysis record a refusal gets: it starts no run, so a declared
+ * or default analysis is recorded as skipped.
+ */
+export function completeRefusalAnalysis(refused, config, input) {
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, input, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+}
+/** A result as its route's outcome. StudyOutcome pairs each route with its result type. */
+function routeOutcome(route, result) {
+    return { route, result };
+}

package/dist/run/run-not-found.js

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { resolveRunsRoot } from "./paths.js";
+import { cli } from "../cli/invocation.js";
 /**
  * The message for a run that is not there: how to start one when the project has no runs, or how
  * to list them when it has. Only the runs directory's entry names are read.
@@ -10,6 +11,6 @@ export async function runNotFoundMessage(cwdInput, runInput) {
     const entries = await readdir(resolveRunsRoot(cwd)).catch(() => []);
     const hasRun = entries.some((name) => !name.startsWith(".") && !name.endsWith(".json"));
     return hasRun
-        ? `No run ${runInput}; humanish runs lists them.`
-        : `No runs in ${cwd} yet; start one with humanish run first-run.`;
+        ? `No run ${runInput}; ${cli("runs")} lists them.`
+        : `No runs in ${cwd} yet; start one with ${cli("run first-run")}.`;
 }

package/dist/run/run.d.ts

@@ -92,7 +92,12 @@ 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, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean);
+    /**
+     * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
+     * when asked, since the signal can arrive after the bundle was published.
+     */
+    get interrupted(): boolean;
     static isIssued(value: unknown): value is FinishedRun;
     /**
      * The run's ok and execution outcome as run.json records them: what the route passed to

package/dist/run/run.js

@@ -27,11 +27,12 @@ const issueKey = Symbol("FinishedRun");
 export class FinishedRun {
     #observer;
     #recordFailure;
+    #interrupted;
     #outcome;
     runId;
     /** The paths created by startRun and validated at the start of `finish`. */
     paths;
-    constructor(key, runId, paths, observer, outcome, recordFailure) {
+    constructor(key, runId, paths, observer, outcome, recordFailure, interrupted) {
         if (key !== issueKey)
             throw new Error("Only Run.finish issues a FinishedRun.");
         this.runId = runId;
@@ -39,6 +40,14 @@ export class FinishedRun {
         this.#observer = observer;
         this.#outcome = outcome;
         this.#recordFailure = recordFailure;
+        this.#interrupted = interrupted;
+    }
+    /**
+     * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
+     * when asked, since the signal can arrive after the bundle was published.
+     */
+    get interrupted() {
+        return this.#interrupted();
     }
     static isIssued(value) {
         return typeof value === "object" && value !== null && #observer in value;
@@ -167,7 +176,7 @@ function runPublisher(args) {
             await writeBundleFiles(bundle, finishedOutcome(current), (publicBundle) => runStatus.restate(runStatusOutcome(publicBundle))).catch(() => undefined);
             return current;
         }));
-        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure);
+        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, () => runStatus.interrupted);
     };
     const interrupt = async (signal) => {
         interrupted = { state: "interrupted", ok: false, signal, at: new Date(now()).toISOString() };

package/dist/run/sandbox-creates.js

@@ -1,7 +1,9 @@
 // The sandboxes this process is creating for each run directory, and the E2B tags that name the
-// directory. A receipt reaches sandbox-receipts.ndjson only after `Sandbox.create` resolves, and
-// on @e2b/desktop that is after desktop startup, seconds after E2B has created the sandbox. The
-// CLI's signal handler (src/cli/commands/run-signals.ts) uses this registry to cover that window:
+// 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.

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

@@ -23,12 +23,13 @@ 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. */