humanish 0.110.2 → 0.110.3

package/dist/routes/terminal/route.js

@@ -44,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;
@@ -83,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/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/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.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/status.d.ts

@@ -80,6 +80,8 @@ export interface RunStatusHandle {
      *  `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>;
+    /** True from the moment `interrupt` accepts a signal, before its write lands. */
+    readonly interrupted: boolean;
 }
 export interface BeginRunStatusOptions {
     runId: string;

package/dist/run/status.js

@@ -69,6 +69,7 @@ export function beginRunStatus(runPaths, options) {
         updatedAt: startedAt,
     };
     let finished = false;
+    let interrupted = false;
     let finishedRecord;
     let writing = Promise.resolve();
     const write = (record) => {
@@ -119,11 +120,15 @@ export function beginRunStatus(runPaths, options) {
                 return false;
             }
             finished = true;
+            interrupted = true;
             clearInterval(timer);
             const completedAt = iso();
             await write({ ...base, state: "interrupted", updatedAt: completedAt, completedAt, signal });
             return true;
         },
+        get interrupted() {
+            return interrupted;
+        },
     };
     return handle;
 }

package/dist/study/composition-rules.js

@@ -51,7 +51,7 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorStudy with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
+// planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";

package/dist/study/init-templates.d.ts

@@ -24,5 +24,5 @@ export declare const humanishScripts: Record<string, string>;
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId): StarterFile[];
+export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId, command?: string): StarterFile[];
 export {};

package/dist/study/init-templates.js

@@ -34,6 +34,44 @@ defaults:
 `,
     };
 }
+/**
+ * The `humanish/README.md` init writes. Its commands start with `command`, the invocation init
+ * chose for this install (src/cli/invocation.ts), as in the section init writes to `AGENTS.md`.
+ */
+function readmeFile(command) {
+    return {
+        path: "humanish/README.md",
+        plane: "source",
+        contents: `# humanish
+
+This directory holds the committed definitions of this app's humanish studies: study files,
+personas and scenarios.
+
+Keep this directory public-safe:
+
+- synthetic personas only;
+- synthetic fixtures only;
+- env var names only, never values;
+- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
+
+Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
+
+Studies:
+
+- committed reusable studies live in humanish/studies/*.yaml;
+- private or machine-local studies live in ignored .humanish/studies/*.yaml or
+  .humanish/local/studies/*.yaml;
+- run a study with \`${command} run <study>\`, or \`${command} watch <study>\` to stay attached;
+- files under humanish/labs/ move there with \`${command} migrate\`.
+
+Format standard:
+
+- human-authored humanish source uses .yaml;
+- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
+- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
+`,
+    };
+}
 /**
  * The flagship live study. A ChatGPT-account Codex participant has no API-dollar price, so preflight
  * refuses a dollar cap on it (HUMANISH_COMPUTER_USE_UNPRICED_CAP); that variant is bounded by the
@@ -113,38 +151,7 @@ defaults:
     };
 }
 export const starterFiles = [
-    {
-        path: "humanish/README.md",
-        plane: "source",
-        contents: `# humanish
-
-This directory holds the committed definitions of this app's humanish studies: study files,
-personas and scenarios.
-
-Keep this directory public-safe:
-
-- synthetic personas only;
-- synthetic fixtures only;
-- env var names only, never values;
-- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
-
-Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
-
-Studies:
-
-- committed reusable studies live in humanish/studies/*.yaml;
-- private or machine-local studies live in ignored .humanish/studies/*.yaml or
-  .humanish/local/studies/*.yaml;
-- run a study with \`humanish run <study>\`, or \`humanish watch <study>\` to stay attached;
-- files under humanish/labs/ move there with \`humanish migrate\`.
-
-Format standard:
-
-- human-authored humanish source uses .yaml;
-- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
-- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
-`,
-    },
+    readmeFile("humanish"),
     {
         path: "humanish/personas/synthetic-new-user.yaml",
         plane: "source",
@@ -317,10 +324,12 @@ export const humanishScripts = {
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent) {
+export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent, command = "humanish") {
     return starterFiles.map((file) => file.path === "humanish/studies/local-browser.yaml"
         ? localBrowserStudy(localBrowser)
         : file.path === "humanish/studies/try-live.yaml"
             ? tryLiveStudy(actor, localAgent)
-            : file);
+            : file.path === "humanish/README.md"
+                ? readmeFile(command)
+                : file);
 }

package/dist/study/init.js

@@ -47,7 +47,7 @@ export async function runInit(options) {
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
     await planAgentsFile(preparedProjectRoot, cwd, plan, humanishCommand());
     const starterActor = starterActorFor(machine);
-    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
+    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine), machine.humanish), options.localBrowser !== undefined, plan);
     await planRuntimeDirectories(preparedProjectRoot, cwd, plan);
     const gitignorePlan = await planGitignore(preparedProjectRoot, cwd);
     plan.changes.push(gitignorePlan.change);

package/dist/study/parse/subject.js

@@ -176,7 +176,7 @@ function parseServedApp(raw, subject) {
         return stateResult;
     }
     if (stateResult.value) {
-        // Semantic validation is shared with the engine (runCuaActorStudy re-enforces it for
+        // Semantic validation is shared with the engine (planComputerUseStudy re-enforces it for
         // configs that arrive through the library API without the parser).
         const reason = subjectStateInvalidReason(stateResult.value, subject.env);
         if (reason) {

package/docs/architecture/actor-contract.md

@@ -17,7 +17,7 @@ capture-vs-publish rule in
 
 `codex-exec` is a real dispatch key for terminal-product studies, but the exported
 descriptor `runSession` is a fail-closed compatibility entry. Live execution is
-owned by `runTerminalProductStudy`, which coordinates sandbox creation,
+owned by `runLiveTerminalSession` (`src/routes/terminal/session.ts`), which coordinates sandbox creation,
 command-scoped runtime auth, evidence, caps, and by-id cleanup.
 
 The `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and the

package/docs/architecture/external-public-shared-world.md

@@ -64,7 +64,7 @@ public `runComputerUseLoop` refuses them. The actor passes them through
 `runComputerUseLoopWithTaps`. A library caller wraps the executor's `observe` (for `url` and
 `screenshot`) or the provider's `nextTurn` (for `reasoning` and `message`).
 
-Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
+Flow, a host-first barrier inside the shared-world route's fan-out:
 
 1. **Designated host.** Exactly one roster entry carries `host: true` (validated). Its mission = create
    the shared lobby; its browser opens `subject.appUrl`.

package/docs/architecture/terminal-product-route.md

@@ -24,19 +24,19 @@ fail-closed cross-validation, and forward-declared warnings.
 
 ## The composition
 
-| Axis                              | Value                                                                                                                                                       |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subject.source`                  | `terminal-product`                                                                                                                                          |
-| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                    |
-| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                        |
-| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                               |
-| `execution.runtimeAuth`           | `openai-egress` (default) or opt-in `openai-env`; names-only durable evidence                                                                               |
-| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                     |
-| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                          |
-| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused: no adopter cost source exists until issue 347 lands                    |
-| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                                |
-| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                       |
-| route                             | `terminal` → `runTerminalProductStudy` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
+| Axis                              | Value                                                                                                                                                 |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subject.source`                  | `terminal-product`                                                                                                                                    |
+| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                              |
+| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                  |
+| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                         |
+| `execution.runtimeAuth`           | `openai-egress` (default) or opt-in `openai-env`; names-only durable evidence                                                                         |
+| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                               |
+| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                    |
+| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused: no adopter cost source exists until issue 347 lands              |
+| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                          |
+| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                 |
+| route                             | `terminal` → `admitTerminalPlan` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
 
 Routing is `routeOf` (`src/study/plan.ts`). It sends every `terminal-product` subject to
 this route, even with an unregistered actor, so this route refuses the actor.

package/docs/contracts/study-analysis.md

@@ -321,10 +321,13 @@ The states without findings:
 
 - `running`: the automatic analysis is queued or running. `next` is `review` again.
 - `skipped`: the automatic analysis was skipped or refused, for example without
-  `OPENAI_API_KEY`. `next` is `analyze --max-cost 3`.
+  `OPENAI_API_KEY`, or the run's study file sets `review.analysis: false`
+  (`AUTOMATIC_ANALYSIS_DISABLED`, read from the file when the view is built). `next` is
+  `analyze --max-cost 3`, which runs an analysis anyway.
 - `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`
   reruns it with the same analyst, `--provider codex` for the Codex account analyst.
-- `none`: no analysis ran for this live run, for example with `review.analysis: false`.
+- `none`: no analysis ran for this live run and nothing records why, for example a run that
+  started from a library call, or one whose study file has moved or changed id.
 - `dry_run`: a dry run has no participant evidence to analyze.
 - `unavailable`: the run or its analysis records could not be read or checked, or the analysis
   text matched a sensitive-text pattern (`ANALYSIS_SENSITIVE_TEXT_QUARANTINED`), which the

package/docs/product/automatic-analysis.md

@@ -127,7 +127,7 @@ outcomes and the deterministic review verdict are never rewritten by analysis.
 | `AUTOMATIC_ANALYSIS_SOURCE_CHANGED`           | `failed`                  | The run directory changed after the run published its bundle          |
 | `AUTOMATIC_ANALYSIS_KEY_MISSING`              | `skipped`                 | No OpenAI API key                                                     |
 | `AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE`  | `skipped`                 | A default analysis found no participant evidence                      |
-| `AUTOMATIC_ANALYSIS_ACTOR_CANCELLED`          | `skipped`                 | The harness cancelled the participants                                |
+| `AUTOMATIC_ANALYSIS_ACTOR_CANCELLED`          | `skipped`                 | The harness cancelled the participants, or a signal stopped the run   |
 | `AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED`      | `skipped`                 | A local VM study could not confirm its cleanup; the command exits 2   |
 | `AUTOMATIC_ANALYSIS_ALREADY_REQUESTED`        | `skipped`                 | Another request already claimed this run's analysis                   |
 | `AUTOMATIC_ANALYSIS_BUSY`                     | `skipped`                 | Another analysis is running                                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.110.2",
+  "version": "0.110.3",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",