humanish 0.106.0 → 0.107.0

package/dist/analysis/store-executions.js

@@ -3,7 +3,7 @@
 import path from "node:path";
 import { runIdOf } from "../run/paths.js";
 import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
-import { pathMissing, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, readBoundedFile } from "../run/evidence-files.js";
 import { ANALYSIS_MAX_BYTES, MAX_VERSIONS, ANALYSIS_DIRECTORY, ANALYSIS_EXECUTION_DIRECTORY, claimDirectory, directoryIds, existingRoot, safeId, } from "./store.js";
 import { hashAnalysisValue, analysisExecutionStartSchema, validateAnalysisArtifact, validateAnalysisExecutionReceipt, } from "./validation.js";
 /** receipt.json and start.json in an execution directory. */
@@ -17,14 +17,14 @@ const EXECUTION_BINDING_KEYS = [
     "promptVersion",
 ];
 /** Exact bounded receipt lookup for an already claimed execution, never a dispatch decision. */
-export async function readStudyAnalysisExecution(prepared, id) {
+export async function readAnalysisExecution(prepared, id) {
     if (!safeId(id))
         return null;
     try {
         const root = await existingRoot(prepared, ANALYSIS_EXECUTION_DIRECTORY);
         if (!root)
             return null;
-        const bytes = await readBoundedStudyFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
+        const bytes = await readBoundedFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
         if (!bytes)
             return null;
         const receipt = validateAnalysisExecutionReceipt(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
@@ -38,7 +38,7 @@ export async function readStudyAnalysisExecution(prepared, id) {
  * Publish accounting first. Unlike a usable report, this receipt does not claim
  * the source still matches; its digests name the exact input that was attempted.
  */
-export async function writeStudyAnalysisExecutionReceipt(prepared, value) {
+export async function writeAnalysisExecutionReceipt(prepared, value) {
     const receipt = executionReceipt(value, prepared);
     const root = await prepareContainedOutputDirectoryRoot(prepared, ANALYSIS_EXECUTION_DIRECTORY);
     const claimed = await claimDirectory(root, receipt.id);
@@ -68,7 +68,7 @@ function executionReceipt(value, prepared) {
     return receipt;
 }
 /** The returned closure owns one exact directory; persisted IDs never authorize overwriting it. */
-export async function beginStudyAnalysisExecution(prepared, context) {
+export async function beginAnalysisExecution(prepared, context) {
     const start = analysisExecutionStartSchema.parse({
         ...context,
         schema: "humanish.analysis-execution-start.v1",
@@ -92,7 +92,7 @@ export async function beginStudyAnalysisExecution(prepared, context) {
         await writeContainedOutputFile(claimed, "receipt.json", `${JSON.stringify(receipt, null, 2)}\n`);
     };
 }
-export async function listStudyAnalysisExecutions(prepared) {
+export async function listAnalysisExecutions(prepared) {
     const receipts = [];
     const warnings = [];
     try {
@@ -102,7 +102,7 @@ export async function listStudyAnalysisExecutions(prepared) {
         const inventory = await directoryIds(root, MAX_VERSIONS);
         warnings.push(...inventory.warnings);
         for (const id of inventory.ids) {
-            const bytes = await readBoundedStudyFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
+            const bytes = await readBoundedFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
             if (!bytes) {
                 if (!(await pathMissing(path.join(root.physicalPath, id, "receipt.json")).catch(() => false)))
                     warnings.push("ANALYSIS_RECEIPT_UNREADABLE");
@@ -128,7 +128,7 @@ export async function listStudyAnalysisExecutions(prepared) {
     return { receipts, warnings: [...new Set(warnings)] };
 }
 /** Accounting is independent of source freshness and findings validation. No evidence is opened. */
-export async function readStudyAnalysisAccountingRecords(prepared) {
+export async function readAnalysisAccountingRecords(prepared) {
     const records = new Map();
     const warnings = [];
     for (const directory of [ANALYSIS_EXECUTION_DIRECTORY, ANALYSIS_DIRECTORY]) {
@@ -145,7 +145,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     records.set(id, record);
                 }
                 if (directory === ANALYSIS_EXECUTION_DIRECTORY) {
-                    const startBytes = await readBoundedStudyFile(root, `${id}/start.json`, MAX_EXECUTION_RECORD_BYTES);
+                    const startBytes = await readBoundedFile(root, `${id}/start.json`, MAX_EXECUTION_RECORD_BYTES);
                     if (startBytes) {
                         try {
                             const start = analysisExecutionStartSchema.parse(JSON.parse(startBytes.toString("utf8")));
@@ -159,7 +159,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     }
                 }
                 const legacy = directory === ANALYSIS_DIRECTORY;
-                const bytes = await readBoundedStudyFile(root, `${id}/${legacy ? "analysis.json" : "receipt.json"}`, legacy ? ANALYSIS_MAX_BYTES : MAX_EXECUTION_RECORD_BYTES);
+                const bytes = await readBoundedFile(root, `${id}/${legacy ? "analysis.json" : "receipt.json"}`, legacy ? ANALYSIS_MAX_BYTES : MAX_EXECUTION_RECORD_BYTES);
                 if (!bytes)
                     continue;
                 try {
@@ -169,7 +169,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     // A historical report may have stale captures or invalid findings. Its strictly checked
                     // accounting metadata still records incurred usage; it never approves those findings.
                     const candidate = legacy
-                        ? Object.fromEntries(Object.keys(studyAnalysisExecutionReceiptKeys).map((key) => [key, raw[key]]))
+                        ? Object.fromEntries(Object.keys(analysisExecutionReceiptKeys).map((key) => [key, raw[key]]))
                         : raw;
                     if (legacy)
                         Object.assign(candidate, {
@@ -208,7 +208,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
     }
     return { records: [...records.values()], warnings: [...new Set(warnings)] };
 }
-const studyAnalysisExecutionReceiptKeys = {
+const analysisExecutionReceiptKeys = {
     id: true,
     runId: true,
     status: true,

package/dist/analysis/store.d.ts

@@ -18,14 +18,14 @@ export declare function assertAnalysisPublicationCapacity(prepared: PreparedRunA
 export declare function existingRoot(prepared: PreparedRunArtifactPaths, directory?: string): Promise<PreparedSelectedOutputDirectory | null>;
 export declare function claimDirectory(parent: PreparedSelectedOutputDirectory, id: string): Promise<PreparedSelectedOutputDirectory>;
 /** A claimed version is never reused, including after interruption before publication. */
-export declare function writeStudyAnalysis(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
+export declare function writeAnalysis(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
 export declare function directoryIds(root: PreparedSelectedOutputDirectory, limit: number, ignoreLegacyFiles?: boolean): Promise<{
     ids: string[];
     warnings: string[];
 }>;
 /** Read one exact result without reading automatic job state or unrelated history. */
-export declare function readStudyAnalysisVersion(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisListEntry | null>;
+export declare function readAnalysisVersion(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisListEntry | null>;
 /** Includes failed attempts; callers must not equate the newest attempt with usable findings. */
 export declare function listAnalyses(prepared: PreparedRunArtifactPaths): Promise<AnalysisListEntry[]>;
-export declare function loadStudyAnalysisRecord(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;
-export declare function appendStudyAnalysisCorrection(prepared: PreparedRunArtifactPaths, value: AnalysisCorrection): Promise<void>;
+export declare function loadAnalysisRecord(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;
+export declare function appendAnalysisCorrection(prepared: PreparedRunArtifactPaths, value: AnalysisCorrection): Promise<void>;

package/dist/analysis/store.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { physicalCwdOf, runIdOf, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "./evidence.js";
-import { pathMissing, isStudyEvidencePath, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, isEvidencePath, readBoundedFile } from "../run/evidence-files.js";
 import { hashAnalysisValue, validateAnalysisArtifact, validateAnalysisCorrection, } from "./validation.js";
 import { ANALYSIS_ID_PATTERN, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -61,9 +61,9 @@ export async function claimDirectory(parent, id) {
     return prepareContainedOutputDirectoryRoot(parent, id);
 }
 /** A claimed version is never reused, including after interruption before publication. */
-export async function writeStudyAnalysis(prepared, value) {
+export async function writeAnalysis(prepared, value) {
     const artifact = validateAnalysisArtifact(value);
-    const source = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    const source = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (!source)
         throw new Error("ANALYSIS_SOURCE_UNAVAILABLE");
     await validateAnalysisEvidence(prepared, artifact, source);
@@ -73,7 +73,7 @@ export async function writeStudyAnalysis(prepared, value) {
     const root = await prepareContainedOutputDirectoryRoot(prepared, ANALYSIS_DIRECTORY);
     const claimed = await claimDirectory(root, artifact.id);
     // Recheck source immediately before publishing the immutable record.
-    const current = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (!current?.equals(source))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     await writeContainedOutputFile(claimed, "analysis.json", bytes);
@@ -100,7 +100,7 @@ export async function directoryIds(root, limit, ignoreLegacyFiles = false) {
             if (entry.name.startsWith(".humanish-write-"))
                 continue;
             if (ignoreLegacyFiles &&
-                isStudyEvidencePath(entry.name) &&
+                isEvidencePath(entry.name) &&
                 !["analysis.json", "correction.json", "receipt.json"].includes(entry.name))
                 continue;
             warnings.push("ANALYSIS_UNSAFE_ENTRY_IGNORED");
@@ -118,7 +118,7 @@ export async function directoryIds(root, limit, ignoreLegacyFiles = false) {
 async function readVersion(prepared, root, id, source) {
     if (!safeId(id))
         return { id: "invalid", state: "invalid", analysis: null, warnings: ["ANALYSIS_ID_INVALID"] };
-    const bytes = await readBoundedStudyFile(root, `${id}/analysis.json`, ANALYSIS_MAX_BYTES);
+    const bytes = await readBoundedFile(root, `${id}/analysis.json`, ANALYSIS_MAX_BYTES);
     // A claimed directory without a published record is an interrupted write, not a report.
     if (bytes === null) {
         if (await pathMissing(path.join(root.physicalPath, id, "analysis.json")).catch(() => false))
@@ -159,14 +159,14 @@ async function readVersion(prepared, root, id, source) {
     return { id, state: "ready", analysis, warnings: [] };
 }
 /** Read one exact result without reading automatic job state or unrelated history. */
-export async function readStudyAnalysisVersion(prepared, id) {
+export async function readAnalysisVersion(prepared, id) {
     if (!safeId(id))
         return null;
     try {
         const root = await existingRoot(prepared);
         if (!root)
             return null;
-        return await readVersion(prepared, root, id, await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes));
+        return await readVersion(prepared, root, id, await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes));
     }
     catch {
         return null;
@@ -179,7 +179,7 @@ export async function listAnalyses(prepared) {
         if (!root)
             return [];
         const inventory = await directoryIds(root, MAX_VERSIONS, true);
-        const source = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+        const source = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
         const results = [];
         for (const id of inventory.ids) {
             const entry = await readVersion(prepared, root, id, source);
@@ -219,7 +219,7 @@ async function readCorrections(prepared, root, analysis) {
         const inventory = await directoryIds(bound, MAX_CORRECTIONS);
         warnings.push(...inventory.warnings);
         for (const id of inventory.ids) {
-            const bytes = await readBoundedStudyFile(root, `${analysis.id}/corrections/${id}/correction.json`, MAX_CORRECTION_BYTES);
+            const bytes = await readBoundedFile(root, `${analysis.id}/corrections/${id}/correction.json`, MAX_CORRECTION_BYTES);
             if (!bytes) {
                 // An unpublished claim directory is harmless; a present record that
                 // cannot be checked must not silently erase a prior review decision.
@@ -246,7 +246,7 @@ async function readCorrections(prepared, root, analysis) {
     corrections.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
     return { corrections, warnings };
 }
-export async function loadStudyAnalysisRecord(prepared, id) {
+export async function loadAnalysisRecord(prepared, id) {
     if (id !== undefined && !safeId(id))
         return empty("invalid", ["ANALYSIS_ID_INVALID"]);
     try {
@@ -290,9 +290,9 @@ function assertCorrectionBinding(analysis, correction) {
         Date.parse(correction.createdAt) < Date.parse(analysis.completedAt))
         throw new Error("ANALYSIS_CORRECTION_BINDING_INVALID");
 }
-export async function appendStudyAnalysisCorrection(prepared, value) {
+export async function appendAnalysisCorrection(prepared, value) {
     const correction = validateAnalysisCorrection(value);
-    const loaded = await loadStudyAnalysisRecord(prepared, correction.analysisId);
+    const loaded = await loadAnalysisRecord(prepared, correction.analysisId);
     if (loaded.state !== "ready" || !loaded.analysis)
         throw new Error("ANALYSIS_CORRECTION_SOURCE_UNAVAILABLE");
     assertCorrectionBinding(loaded.analysis, correction);

package/dist/cli/commands/analysis-signals.d.ts

@@ -2,6 +2,7 @@ import type { RunLabOptions } from "../../run-lab.js";
 import type { CliIo } from "../io.js";
 /**
  * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis, so actor signal behavior is unchanged.
+ * it. The listeners exist only during analysis; before it, the run's own handlers
+ * (run-signals.ts) hold the signals and hand them over here.
  */
 export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunLabOptions, "onEvent" | "analysisSignal">;

package/dist/cli/commands/analysis-signals.js

@@ -1,6 +1,8 @@
+import { handOverRunSignals } from "./run-signals.js";
 /**
  * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis, so actor signal behavior is unchanged.
+ * it. The listeners exist only during analysis; before it, the run's own handlers
+ * (run-signals.ts) hold the signals and hand them over here.
  */
 export function cliAnalysisOptions(io) {
     const controller = new AbortController();
@@ -13,6 +15,7 @@ export function cliAnalysisOptions(io) {
         onEvent: (event) => {
             if (event.type === "analysis-started") {
                 io.writeErr("Participants finished; preparing analysis…\n");
+                handOverRunSignals();
                 for (const signal of signals)
                     process.on(signal, cancel);
             }

package/dist/cli/commands/analyze.js

@@ -3,7 +3,7 @@ import { Command, Option } from "commander";
 import { forTerminal } from "../../routes/terminal/encoding.js";
 import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from "../../analysis/service.js";
 import { listAnalyses } from "../../analysis/store.js";
-import { listStudyAnalysisExecutions } from "../../analysis/store-executions.js";
+import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
 import { discoverCliKeys, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
 import { resolvePhysicalCwd } from "../../run/paths.js";
@@ -132,6 +132,8 @@ async function handleAnalyze(io, options, command) {
                 lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
             if (value.executionReceiptPath)
                 lines.push(`Execution receipt: ${value.executionReceiptPath}`);
+            if (value.rejectedOutputPath)
+                lines.push(`Rejected output, kept locally for diagnosis: ${value.rejectedOutputPath}`);
             if (value.usage) {
                 lines.push(`Recorded attempt usage${value.usage.usageComplete ? "" : " (incomplete)"}: ${value.usage.inputTokens ?? "unknown"} input tokens, ${value.usage.outputTokens ?? "unknown"} output tokens.`);
                 lines.push(`Estimated attempt cost: ${value.usage.estimatedCostUsd === null ? "unknown" : `$${value.usage.estimatedCostUsd}`}.`);
@@ -152,7 +154,7 @@ async function handleAnalyzeList(io, options, command) {
     const prepared = await resolveRunPath(await resolvePhysicalCwd(options.cwd), options.run).catch(() => null);
     const versions = prepared ? await listAnalyses(prepared) : [];
     const executions = prepared
-        ? await listStudyAnalysisExecutions(prepared)
+        ? await listAnalysisExecutions(prepared)
         : { receipts: [], warnings: [] };
     const result = {
         schema: "humanish.analysis-history.v1",

package/dist/cli/commands/comms.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { COMMS_PROVIDERS, saveCommsConnection } from "../../comms/connections.js";
+import { catchTokenRefusal } from "../../comms/external-evidence.js";
 import { readCommsSetup } from "../../comms/setup.js";
 import { checkCommsConnection, configureCommsLab } from "../../comms/setup.js";
 import { inspectCommsRecovery, recoverCommsReceiving } from "../../comms/receiving-recovery.js";
@@ -73,7 +74,7 @@ export function registerCommsCommands(parent, io) {
         .summary("Run the adopter-hosted email catch.")
         .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
         .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
-        .option("--token <value>", "Require this bearer token on GET /deliveries (recommended when reachable off-host).")
+        .option("--token <value>", "Require this bearer token, at least 16 characters, on GET /deliveries (recommended when reachable off-host).")
         .option("--smtp-port <port>", "Also capture SMTP mail on 127.0.0.1:<port>. Point your app's SMTP transport here.")
         .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
         .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous) => [...(previous ?? []), value])
@@ -178,6 +179,12 @@ async function handleCommsRecover(io, options, command) {
     }
 }
 async function handleCommsCatch(io, options) {
+    const tokenRefusal = catchTokenRefusal(options.token);
+    if (tokenRefusal !== undefined) {
+        io.writeErr(`--token: ${tokenRefusal} The token guards GET /deliveries, and runs scrub it from their warnings.\n`);
+        io.setExitCode(2);
+        return;
+    }
     const port = Number.parseInt(options.port, 10);
     if (!Number.isInteger(port) || port <= 0 || port > 65_534) {
         io.writeErr("--port must be an integer between 1 and 65534.\n");

package/dist/cli/commands/lab-route-computer-use.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface ComputerUseRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-computer-use.js

@@ -7,6 +7,7 @@ import { serveObserver } from "../../observer/render.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
 import { cliAnalysisOptions } from "./analysis-signals.js";
+import { onRunShutdown } from "./run-signals.js";
 import { parseLabCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
 import { formatCuaLabHuman } from "./lab-format.js";
@@ -29,6 +30,7 @@ export function computerUseRouteRun(args) {
         tunnel: undefined,
         exposeWarnings: [],
         publicTarget: undefined,
+        releaseShutdown: undefined,
     };
     return {
         options: cuaRunOptions(args, settings, prepared, live),
@@ -37,7 +39,12 @@ export function computerUseRouteRun(args) {
             if (outcome.route !== "computer-use") {
                 throw new Error(`Expected the computer-use route, got ${outcome.route}.`);
             }
-            await reportCuaRun(args, prepared, outcome.result, live);
+            try {
+                await reportCuaRun(args, prepared, outcome.result, live);
+            }
+            finally {
+                live.releaseShutdown?.();
+            }
         },
     };
 }
@@ -66,15 +73,15 @@ function resolveCuaSettings(args) {
         mode: args.mode,
         wantsMachine,
     });
-    const participantIds = parseParticipantIds(args.options.lanes);
+    const participantIds = parseParticipantIds(args.options.participants);
     if (participantIds.length > 0 && !args.options.rerunFailedFrom) {
-        args.io.writeErr("error: --lanes requires --rerun-failed-from.\n");
+        args.io.writeErr("error: --participants requires --rerun-failed-from.\n");
         args.io.setExitCode(2);
         return undefined;
     }
-    const count = parseLabCount(args.options.count ?? args.options.sims, args.config.actors[0]?.count ?? 1);
+    const count = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 1);
     if (count === null) {
-        args.io.writeErr("error: --count/--sims must be a positive integer.\n");
+        args.io.writeErr("error: --count must be a positive integer.\n");
         args.io.setExitCode(2);
         return undefined;
     }
@@ -122,7 +129,6 @@ function cuaRunOptions(args, settings, prepared, live) {
     return {
         ...cliAnalysisOptions(args.io),
         cwd: args.options.cwd,
-        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         // A followed watch opens the served Observer (or prints the phone target under --expose), so
         // its static render never opens. A non-follow watch opens what its plan says, once. Run mode
         // keeps the static open.
@@ -153,20 +159,24 @@ function cuaRunOptions(args, settings, prepared, live) {
             }),
     };
 }
+/** Closes the loopback server and any tunnel the watch attached. Safe to call twice. */
+async function closeLiveAttachment(io, live) {
+    const { server, tunnel } = live;
+    live.server = null;
+    live.tunnel = undefined;
+    await server?.close().catch((cleanupError) => {
+        io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+    });
+    await tunnel?.close().catch(() => undefined);
+}
 /**
  * Tears down the loopback server and any tunnel started inside onObserverReady, then reports a
  * tunnel startup failure or rethrows. The sandbox is created after onObserverReady returns, so a
  * tunnel failure cannot orphan one.
  */
 async function closeLiveAfterRunError(args, settings, live, error) {
-    await live.server?.close().catch((cleanupError) => {
-        args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
-    });
-    live.server = null;
-    if (live.tunnel) {
-        await live.tunnel.close().catch(() => undefined);
-        live.tunnel = undefined;
-    }
+    await closeLiveAttachment(args.io, live);
+    live.releaseShutdown?.();
     if (error instanceof ServeTunnelError) {
         refuseCua(args, settings.dryRun, error.code, error.message);
         return;
@@ -182,6 +192,8 @@ async function attachLiveObserver(io, settings, exposure, live, observer) {
             port: settings.port,
             exposed: exposure.exposed,
         });
+        // A signal that stops the run closes the server and any tunnel before the process exits.
+        live.releaseShutdown ??= onRunShutdown(() => closeLiveAttachment(io, live));
     }
     if (exposure.exposed) {
         const activeServer = live.server;

package/dist/cli/commands/lab-route-preview.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -8,12 +7,11 @@ interface PreviewRouteArgs {
     io: CliIo;
     lab: string;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }
 /**
- * The preview route's CLI setup: the sim count and Observer plan, its runLab options, and how it
+ * The preview route's CLI setup: the participant count and Observer plan, its runLab options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export declare function previewRouteRun(args: PreviewRouteArgs): RouteRun | undefined;

package/dist/cli/commands/lab-route-preview.js

@@ -2,11 +2,11 @@ import { Command } from "commander";
 import { formatRunHuman, parseLabCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
 /**
- * The preview route's CLI setup: the sim count and Observer plan, its runLab options, and how it
+ * The preview route's CLI setup: the participant count and Observer plan, its runLab options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export function previewRouteRun(args) {
-    const participantCount = parseLabCount(args.options.sims, args.config.actors[0]?.count ?? 4);
+    const participantCount = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 4);
     if (participantCount === null) {
         const result = {
             schema: "humanish.run-result.v1",
@@ -15,7 +15,7 @@ export function previewRouteRun(args) {
             warnings: [],
             error: {
                 code: "HUMANISH_INVALID_SIM_COUNT",
-                message: "--sims must be a positive integer.",
+                message: "--count must be a positive integer.",
             },
         };
         writeResult(args.command, args.io, result, formatRunHuman);
@@ -42,7 +42,6 @@ export function previewRouteRun(args) {
     return {
         options: {
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             count: participantCount,
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),

package/dist/cli/commands/lab-route-run.d.ts

@@ -1,8 +1,8 @@
-import { type LabOutcome, type RunLabOptions } from "../../run-lab.js";
+import { type InternalRunLabOptions, type LabOutcome } from "../../run-lab.js";
 import type { LabConfig } from "../../lab/types.js";
 import type { LoadedAdapterScorer } from "./lab-scorer.js";
 export interface RouteRun {
-    readonly options: RunLabOptions;
+    readonly options: InternalRunLabOptions;
     present(outcome: LabOutcome): Promise<void>;
     /** Handles an error runLab threw, and rethrows any it does not handle. */
     onRunError?(error: unknown): Promise<void>;
@@ -10,8 +10,10 @@ export interface RouteRun {
 /**
  * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
- * undefined, so a refused lab never imports the scorer's host code.
+ * undefined, so a refused lab never imports the scorer's host code. `afterRun` runs once runLab
+ * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
+ * Observer and tunnel).
  */
 export declare function runRoute(config: LabConfig, run: RouteRun, beforeRun?: () => Promise<{
     scorer?: LoadedAdapterScorer;
-} | undefined>): Promise<void>;
+} | undefined>, afterRun?: () => void): Promise<void>;

package/dist/cli/commands/lab-route-run.js

@@ -4,9 +4,11 @@ import { prepareLab } from "../../run-lab.js";
 /**
  * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
- * undefined, so a refused lab never imports the scorer's host code.
+ * undefined, so a refused lab never imports the scorer's host code. `afterRun` runs once runLab
+ * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
+ * Observer and tunnel).
  */
-export async function runRoute(config, run, beforeRun = () => Promise.resolve({})) {
+export async function runRoute(config, run, beforeRun = () => Promise.resolve({}), afterRun = () => undefined) {
     let outcome;
     try {
         const prepared = await prepareLab(config, run.options);
@@ -22,10 +24,12 @@ export async function runRoute(config, run, beforeRun = () => Promise.resolve({}
         }
     }
     catch (error) {
+        afterRun();
         if (run.onRunError === undefined)
             throw error;
         await run.onRunError(error);
         return;
     }
+    afterRun();
     await run.present(outcome);
 }

package/dist/cli/commands/lab-route-scripted.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface ScriptedRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-scripted.js

@@ -24,7 +24,6 @@ export function scriptedRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),

package/dist/cli/commands/lab-route-shared-world.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface SharedWorldRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-shared-world.js

@@ -63,7 +63,6 @@ export function sharedWorldRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: wantsFollow
                 ? false
                 : finishedPlan === undefined

package/dist/cli/commands/lab-route-terminal.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface TerminalRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-terminal.js

@@ -24,7 +24,6 @@ export function terminalRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),