humanish 0.106.1 → 0.108.0

package/dist/cli/commands/observe.js

@@ -3,19 +3,21 @@ import { openTarget, renderObserver, serveObserver } from "../../observer/render
 import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { deprecationMessage, warnAndQueue } from "../deprecations.js";
+import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
-    parent
+    addLibraryOptions(parent
         .command("observe")
-        .description("Follow a run's saved evidence in Observer over loopback http://127.0.0.1.")
-        .summary("Follow a run's saved evidence over loopback http.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--open", "Open the observer in the default browser.")
+        .description("Open a saved run in the Observer, served on http://127.0.0.1; without --run, the latest. With --all, serve the run library, opening on --run when given.")
+        .summary("Open a saved run in the Observer.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION)
+        .option("--all", "Serve the whole run library, with optional tunnel-edge exposure.")
+        .addOption(freePortOption())
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--open", "Open the Observer in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
+        .option("--json", JSON_OPTION_DESCRIPTION))
         .addHelpText("after", [
         "",
         "Examples:",
@@ -23,62 +25,128 @@ export function registerObserveCommand(parent, io) {
         "  humanish observe --run latest",
         "  humanish observe --run <runId> --port 8732",
         "  humanish observe --no-open --json",
+        "  humanish observe --all",
+        "  humanish observe --all --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "  humanish observe --all --safe --expose --tunnel ngrok",
+        "  humanish observe --all --expose --public-url https://observer.example.com",
         "",
-        "The server binds 127.0.0.1 only and exposes just the run's bundle directory.",
-        "It stays attached until Ctrl-C; file:// security policy and live refresh are why",
-        "loopback http is preferred over opening the index.html path directly.",
+        "The server binds 127.0.0.1 only. One run exposes just that run's bundle directory; --all",
+        "serves the run library. It stays attached until Ctrl-C; file:// security policy and live",
+        "refresh are why loopback http is preferred over opening the index.html path directly.",
+        "",
+        "--safe, --expose, --tunnel, --tunnel-domain, --oauth, --allow-email, --allow-domain and",
+        "--public-url need --all. Exposure only ever happens through an authenticated edge (ngrok",
+        "--oauth google, or an operator --public-url you secure) forwarding to the loopback port;",
+        "the server carries no in-process auth. Live desktop stream URLs are never served; remote",
+        "viewers see persisted evidence only. --safe composes with any exposure.",
     ].join("\n"))
-        .action(async (options, command) => {
-        const port = parseObserverPort(options.port);
-        if (port === null) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: options.cwd,
-                warnings: [],
-                error: {
-                    code: "HUMANISH_INVALID_PORT",
-                    message: "--port must be an integer between 0 and 65535.",
-                },
-            };
-            writeResult(command, io, result, formatRunHuman);
-            io.setExitCode(2);
-            return;
-        }
-        const rendered = await renderObserver(options.cwd, options.run, { open: false });
-        if (!rendered.ok || !rendered.observerPath) {
-            writeResult(command, io, rendered, formatObserverHuman);
-            io.setExitCode(2);
-            return;
-        }
-        // Reuse the contained current-data projection, scoped to this run. A raw static
-        // server would miss runtime status and could replay stored iframe grants.
-        const wantsMachine = wantsJson(command);
-        const shouldOpen = options.open === false
-            ? false
-            : options.open === true
-                ? true
-                : !wantsMachine && process.stdout.isTTY === true;
-        const server = await serveObserver(rendered, { open: false, port, scope: "run" });
-        const openResult = shouldOpen
-            ? openTarget(server.url)
-            : { opened: false };
+        .action((options, command) => handleObserve(io, options, command));
+}
+/** The run library's flags, on `observe --all` and the hidden `serve` alias. */
+function addLibraryOptions(command) {
+    return command
+        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; other runs are not served at all.")
+        .option("--expose", "Share the library beyond this machine. Requires --oauth or --public-url, or --safe.")
+        .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
+        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
+        .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
+        "google",
+    ]))
+        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated)
+        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated)
+        .option("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.");
+}
+/** The library flags set on a one-run observe, as typed on the command line. */
+function libraryOnlyFlags(options) {
+    return [
+        options.safe === true ? ["--safe"] : [],
+        options.expose === true ? ["--expose"] : [],
+        options.tunnel === undefined ? [] : ["--tunnel"],
+        options.tunnelDomain === undefined ? [] : ["--tunnel-domain"],
+        options.oauth === undefined ? [] : ["--oauth"],
+        (options.allowEmail?.length ?? 0) === 0 ? [] : ["--allow-email"],
+        (options.allowDomain?.length ?? 0) === 0 ? [] : ["--allow-domain"],
+        options.publicUrl === undefined ? [] : ["--public-url"],
+    ].flat();
+}
+function refuseObserve(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `observe` shows one run (default latest); `observe --all` serves the run library. */
+async function handleObserve(io, options, command) {
+    if (options.all === true) {
+        await handleServe(io, options, command);
+        return;
+    }
+    const libraryOnly = libraryOnlyFlags(options);
+    if (libraryOnly.length > 0) {
+        refuseObserve(command, io, options.cwd, {
+            code: "HUMANISH_OBSERVE_OPTION_CONFLICT",
+            message: `${libraryOnly.join(", ")} ${libraryOnly.length === 1 ? "needs" : "need"} --all: humanish observe --all ${libraryOnly.join(" ")}.`,
+        });
+        return;
+    }
+    await observeRun(io, { ...options, run: options.run ?? "latest" }, command);
+}
+/** One run's Observer over loopback, until a signal stops it. */
+async function observeRun(io, options, command) {
+    const port = parseObserverPort(options.port);
+    if (port === null) {
         const result = {
-            ...rendered,
-            observerUrl: server.url,
-            serverUrl: server.url,
-            opened: openResult.opened,
-            ...(openResult.command ? { openCommand: openResult.command } : {}),
-            warnings: [
-                ...rendered.warnings,
-                "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
-                ...(openResult.warning ? [openResult.warning] : []),
-            ],
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: options.cwd,
+            warnings: [],
+            error: {
+                code: "HUMANISH_INVALID_PORT",
+                message: "--port must be an integer between 0 and 65535.",
+            },
         };
-        writeResult(command, io, result, formatObserverHuman);
-        io.setExitCode(0);
-        await serveObserveUntilSignal(io, server, { json: wantsMachine });
-    });
+        writeResult(command, io, result, formatRunHuman);
+        io.setExitCode(2);
+        return;
+    }
+    const rendered = await renderObserver(options.cwd, options.run, { open: false });
+    if (!rendered.ok || !rendered.observerPath) {
+        writeResult(command, io, rendered, formatObserverHuman);
+        io.setExitCode(2);
+        return;
+    }
+    // Reuse the contained current-data projection, scoped to this run. A raw static
+    // server would miss runtime status and could replay stored iframe grants.
+    const wantsMachine = wantsJson(command);
+    const shouldOpen = options.open === false
+        ? false
+        : options.open === true
+            ? true
+            : !wantsMachine && process.stdout.isTTY === true;
+    const server = await serveObserver(rendered, { open: false, port, scope: "run" });
+    const openResult = shouldOpen
+        ? openTarget(server.url)
+        : { opened: false };
+    const result = {
+        ...rendered,
+        observerUrl: server.url,
+        serverUrl: server.url,
+        opened: openResult.opened,
+        ...(openResult.command ? { openCommand: openResult.command } : {}),
+        warnings: [
+            ...rendered.warnings,
+            "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
+            ...(openResult.warning ? [openResult.warning] : []),
+        ],
+    };
+    writeResult(command, io, result, formatObserverHuman);
+    io.setExitCode(0);
+    await serveObserveUntilSignal(io, server, { json: wantsMachine });
 }
 async function serveObserveUntilSignal(io, server, options) {
     // Keep the JSON envelope on stdout clean: route attach/stop chatter to stderr
@@ -117,45 +185,19 @@ async function serveObserveUntilSignal(io, server, options) {
         }
     });
 }
+// Removed in 0.109.0: `serve` stays one minor as a hidden alias of `observe --all`.
 export function registerServeCommand(parent, io) {
-    parent
-        .command("serve")
-        .description("Serve the local run library over loopback http, with optional tunnel-edge authenticated exposure.")
-        .summary("Serve the run library; optional tunnel-edge exposure.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--run <id>", "Land on this run id (or latest) instead of the library index.")
-        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; everything else is absent (fail-closed).")
-        .option("--expose", "Declare exposure intent. Requires edge auth (--oauth or --public-url) OR --safe.")
-        .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
-        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
-        .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
-        "google",
-    ]))
-        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated, [])
-        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated, [])
-        .option("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.")
+    addLibraryOptions(parent
+        .command("serve", { hidden: true })
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .addOption(freePortOption())
+        .option("--run <id>", RUN_OPTION_DESCRIPTION)
         .option("--open", "Open the library in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
-        .addHelpText("after", [
-        "",
-        "Happy path:",
-        "  humanish serve",
-        "  humanish serve --expose --tunnel ngrok --oauth google --allow-email you@example.com",
-        "  humanish serve --safe --expose --tunnel ngrok",
-        "  humanish serve --expose --public-url https://observer.example.com",
-        "",
-        "Agent/CI path:",
-        "  humanish serve --json --no-open",
-        "",
-        "The server always binds 127.0.0.1; exposure only ever happens through an authenticated",
-        "edge (ngrok --oauth google, or an operator --public-url you secure) forwarding to the",
-        "loopback port. The server carries no in-process auth; the gate lives at the edge. Live",
-        "desktop stream URLs are never served here; remote viewers see persisted evidence only.",
-        "--safe composes with any exposure for defense in depth.",
-    ].join("\n"))
-        .action((options, command) => handleServe(io, options, command));
+        .option("--json", JSON_OPTION_DESCRIPTION)).action((options, command) => {
+        warnAndQueue(command, io, deprecationMessage("humanish serve", "humanish observe --all"));
+        return handleServe(io, options, command);
+    });
 }
 async function handleServe(io, options, command) {
     const fail = (code, message) => refuseServe(command, io, options, code, message);
@@ -171,8 +213,8 @@ async function handleServe(io, options, command) {
         ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
         ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
         ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
-        allowEmails: options.allowEmail,
-        allowDomains: options.allowDomain,
+        allowEmails: options.allowEmail ?? [],
+        allowDomains: options.allowDomain ?? [],
         ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
         safe: options.safe === true,
     });
@@ -257,7 +299,7 @@ async function reportServe(io, command, options, server, plan, edge) {
         ...serveExposureWarnings(server, options.safe === true, publicUrl),
     ];
     // Auto-open is suppressed under --expose so the public URL is not shoved into a local opener's
-    // argv unasked — the exposure target is a remote device anyway. Explicit --open still honors
+    // argv unasked; the exposure target is a remote device anyway. Explicit --open still honors
     // intent and opens the loopback library.
     const shouldOpen = options.open === false
         ? false
@@ -292,6 +334,7 @@ async function reportServe(io, command, options, server, plan, edge) {
             : {}),
         runsListed: server.runsListed,
         ...(server.shareReadyCount !== undefined ? { shareReadyCount: server.shareReadyCount } : {}),
+        ...(server.hiddenRuns !== undefined ? { hiddenRuns: server.hiddenRuns } : {}),
         ...(server.entryRunId ? { entryRunId: server.entryRunId } : {}),
         opened: openResult.opened,
         ...(openResult.command ? { openCommand: openResult.command } : {}),
@@ -309,20 +352,38 @@ async function reportServe(io, command, options, server, plan, edge) {
         },
     }, { json: wantsMachine });
 }
+/**
+ * The runs --safe left out, grouped by grade and reasons, and how to share one. A run held back
+ * only for raw screenshots can be exported as a copy with blurred screenshots; the read-results
+ * docs name that step.
+ */
+function hiddenRunLines(groups) {
+    const total = groups.reduce((sum, group) => sum + group.runs, 0);
+    if (total === 0)
+        return [];
+    const runs = (count) => `${count} run${count === 1 ? "" : "s"}`;
+    const lines = [`hidden: ${runs(total)} not share_ready`];
+    for (const group of groups) {
+        const reasons = group.reasons.length > 0 ? ` (${group.reasons.join(", ")})` : "";
+        lines.push(`  ${runs(group.runs)} ${group.status}${reasons}`);
+    }
+    if (groups.some((group) => group.reasons.join(",") === "RAW_SCREENSHOTS"))
+        lines.push("share: a run held back only for RAW_SCREENSHOTS can be copied with blurred screenshots: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish observe --all --safe --cwd <dir>`");
+    lines.push("why: `humanish verify --run <id>` explains each reason");
+    return lines;
+}
 function formatServeHuman(result) {
     if (!result.ok) {
-        return ([
-            "humanish serve failed",
-            ...(result.error ? [`error: ${result.error.code} ${result.error.message}`] : []),
-            ...result.warnings.map((warning) => `warning: ${warning}`),
-        ].join("\n") + "\n");
+        const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+        return { ...(warnings ? { stdout: warnings } : {}), error: result.error };
     }
     const modeSuffix = result.safe ? " (share_ready only)" : "";
     const lines = [
-        "humanish serve",
+        "humanish observe --all",
         `mode: ${result.mode}${modeSuffix}`,
         `library: ${result.url ?? ""}`,
         `runs: ${result.runsListed}`,
+        ...hiddenRunLines(result.hiddenRuns ?? []),
     ];
     if (result.publicUrl) {
         lines.push(`public: ${result.publicUrl}`);
@@ -332,7 +393,7 @@ function formatServeHuman(result) {
     }
     if (result.oauth) {
         const rules = [...result.oauth.allowEmails, ...result.oauth.allowDomains];
-        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule — any Google account)"}`);
+        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule: any Google account can sign in)"}`);
     }
     if (result.entryRunId) {
         lines.push(`entry: ${result.entryRunId}`);

package/dist/cli/commands/run-command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type CliIo, type LabCommandOptions as RunOptions } from "../io.js";
+/** The parsed flags of `run`, `watch` and the `lab run` alias. */
+export type { RunOptions };
+/** The flags a run takes, whichever command starts it. */
+export declare function addRunOptions(command: Command): Command;
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export declare function studyOnlyFlags(options: RunOptions): string[];
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export declare function handleRun(io: CliIo, named: string | undefined, options: RunOptions, command: Command): Promise<void>;

package/dist/cli/commands/run-command.js

@@ -0,0 +1,85 @@
+import { runDryRun } from "../../run/dry-run.js";
+import { runLabCommand } from "./lab-run.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
+/** The flags a run takes, whichever command starts it. */
+export function addRunOptions(command) {
+    return command
+        .option("--dry-run", "Do a dry run: a synthetic run with no browser, keys or provider spend.")
+        .option("--open", "Open the Observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .option("--detach", "Render/open once and exit without an attached watch server.")
+        .addOption(freePortOption())
+        .option("--count <count>", "Override the participant count of a preview or computer-use study, or of the synthetic run without a study.")
+        .option("--rerun-failed-from <run>", "Computer-use studies only: start a new run for the failed participants of a prior run.")
+        .option("--participants <ids>", "With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position.")
+        .option("--scorer <path>", "Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--json", JSON_OPTION_DESCRIPTION);
+}
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export function studyOnlyFlags(options) {
+    return [
+        options.scorer === undefined ? [] : ["--scorer"],
+        options.rerunFailedFrom === undefined ? [] : ["--rerun-failed-from"],
+        options.participants === undefined ? [] : ["--participants"],
+    ].flat();
+}
+function refuseRun(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export async function handleRun(io, named, options, command) {
+    // An empty argument, as from a script passing an unset variable, is the synthetic run.
+    const study = named === "" ? undefined : named;
+    const studyOnly = studyOnlyFlags(options);
+    if (study === undefined && studyOnly.length > 0) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_RUN_OPTION_CONFLICT",
+            message: `${studyOnly.join(", ")} ${studyOnly.length === 1 ? "needs" : "need"} a study: humanish run <study>.`,
+        });
+        return;
+    }
+    const loaded = await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+        // runLabCommand discovers keys for a live lab; the lab-less preview needs none.
+        discoverKeys: false,
+    });
+    if (!loaded)
+        return;
+    if (study !== undefined) {
+        await runLabCommand({ command, io, lab: study, mode: "run", options });
+        return;
+    }
+    const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);
+    if (participantCount === null) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+            message: "--count must be a positive integer.",
+        });
+        return;
+    }
+    const result = await runDryRun({
+        cwd: options.cwd,
+        ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(participantCount === undefined ? {} : { participantCount }),
+        // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
+        // produced it. A render failure is a warning on the result.
+        observer: { open: false },
+    });
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}

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

@@ -0,0 +1,30 @@
+import { type ReclaimHooks } from "../../run/reclaim.js";
+import type { RunInterruptSignal } from "../../run/status.js";
+import type { CliIo } from "../io.js";
+interface RunSignalTarget {
+    on(event: RunInterruptSignal, listener: () => void): unknown;
+    removeListener(event: RunInterruptSignal, listener: () => void): unknown;
+}
+/** Seams for tests; the CLI passes none. */
+export interface RunSignalOptions {
+    signalTarget?: RunSignalTarget;
+    exit?: (code: number) => void;
+    reclaim?: ReclaimHooks;
+    deadlineMs?: number;
+}
+/**
+ * Register work a committed shutdown finishes before it exits, such as closing watch's Observer
+ * server and tunnel. It runs within the same deadline as reclaim. The returned function removes it.
+ */
+export declare function onRunShutdown(cleanup: () => Promise<void>): () => void;
+/**
+ * Install the run's signal handling. `end` removes it. `release` removes it unless a shutdown has
+ * begun, which keeps its handlers so a second signal still exits at once.
+ */
+export declare function beginRunSignalPhase(io: Pick<CliIo, "writeErr">, options?: RunSignalOptions): {
+    end(): void;
+    release(): void;
+};
+/** Analysis is starting, and its own cancel handlers take the signals from here. */
+export declare function handOverRunSignals(): void;
+export {};

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

@@ -0,0 +1,146 @@
+// The run command's signal handling outside post-run analysis. The first interrupt, terminate or
+// hangup signal marks each unfinished run in this process interrupted, kills the E2B sandboxes
+// its create-time receipts name, runs the registered shutdown cleanups (watch's Observer server
+// and tunnel) and exits 128+n, all within one deadline; a second signal exits at once. Routes
+// take no abort signal, so the bundle is not finished, but the record ends at once and no
+// journaled sandbox waits for its timeout. Analysis has its own cancel handlers
+// (analysis-signals.ts) and takes over when it starts.
+import path from "node:path";
+import { activeRuns } from "../../run/active-runs.js";
+import { LATEST_RUN_ALIAS } from "../../run/locate.js";
+import { reclaimPinnedRunSandboxes, } from "../../run/reclaim.js";
+import { SANDBOX_RECEIPTS_ARTIFACT } from "../../run/sandbox-receipts.js";
+import { exitCodeForSignal } from "../observer-follow.js";
+/** How long the handler waits for interrupt, reclaim and cleanups before it exits anyway. */
+const INTERRUPT_RECLAIM_DEADLINE_MS = 10_000;
+/** Each kill's own request timeout, inside the deadline. */
+const KILL_REQUEST_TIMEOUT_MS = 8_000;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+let current;
+const shutdownCleanups = new Set();
+/**
+ * Register work a committed shutdown finishes before it exits, such as closing watch's Observer
+ * server and tunnel. It runs within the same deadline as reclaim. The returned function removes it.
+ */
+export function onRunShutdown(cleanup) {
+    shutdownCleanups.add(cleanup);
+    return () => {
+        shutdownCleanups.delete(cleanup);
+    };
+}
+/**
+ * Install the run's signal handling. `end` removes it. `release` removes it unless a shutdown has
+ * begun, which keeps its handlers so a second signal still exits at once.
+ */
+export function beginRunSignalPhase(io, options = {}) {
+    const target = options.signalTarget ?? process;
+    const exit = options.exit ??
+        ((code) => {
+            process.exit(code);
+        });
+    const handlers = new Map();
+    let stopping = false;
+    const end = () => {
+        for (const [signal, handler] of handlers)
+            target.removeListener(signal, handler);
+        handlers.clear();
+        if (current?.end === end)
+            current = undefined;
+    };
+    const release = () => {
+        if (!stopping)
+            end();
+    };
+    const onSignal = (signal) => {
+        if (stopping) {
+            exit(exitCodeForSignal(signal));
+            return;
+        }
+        stopping = true;
+        void stopActiveRuns(io, signal, options)
+            .catch(() => undefined)
+            .finally(() => exit(exitCodeForSignal(signal)));
+    };
+    current?.end();
+    for (const signal of SIGNALS) {
+        const handler = () => onSignal(signal);
+        handlers.set(signal, handler);
+        target.on(signal, handler);
+    }
+    current = { end, release };
+    return { end, release };
+}
+/** Analysis is starting, and its own cancel handlers take the signals from here. */
+export function handOverRunSignals() {
+    current?.release();
+}
+/**
+ * Interrupt, reclaim and the registered cleanups all run inside one deadline that starts before
+ * the first status write is awaited, so a stalled write or kill still ends in a bounded exit.
+ */
+async function stopActiveRuns(io, signal, options) {
+    const deadlineMs = options.deadlineMs ?? INTERRUPT_RECLAIM_DEADLINE_MS;
+    const runs = activeRuns();
+    // Absent: still pending at the deadline. Null: the run had finished, so there is nothing to say.
+    const reports = new Map();
+    const work = Promise.all([
+        ...runs.map(async (run) => {
+            // False when the run had already finished: its route released what it held.
+            if (!(await run.status.interrupt(signal))) {
+                reports.set(run, null);
+                return;
+            }
+            const reclaimed = await reclaimPinnedRunSandboxes(run.cwd, run.paths, {
+                requestTimeoutMs: KILL_REQUEST_TIMEOUT_MS,
+                ...options.reclaim,
+            }).catch(() => undefined);
+            reports.set(run, reclaimSummary(run, reclaimed));
+        }),
+        ...[...shutdownCleanups].map((cleanup) => cleanup().catch(() => undefined)),
+    ]);
+    const finished = await withDeadline(work, deadlineMs);
+    for (const run of runs) {
+        const report = reports.get(run);
+        if (report === null)
+            continue;
+        const text = report ??
+            (finished === "deadline"
+                ? `stopping did not finish within ${deadlineMs / 1000} s; ${recovery(run)}.`
+                : `reclaim failed; ${recovery(run)}.`);
+        try {
+            io.writeErr(`humanish: ${signal}: run ${run.runId} marked interrupted; ${text}\n`);
+        }
+        catch {
+            // A hung-up terminal cannot take the line; the status record and reclaim receipt hold it.
+        }
+    }
+}
+function withDeadline(work, ms) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("deadline"), ms);
+    });
+    return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+/**
+ * How to finish what the handler could not. A run whose id is the alias `latest` cannot be named
+ * to reclaim, which would resolve the newest run instead, so it gets its receipts path.
+ */
+function recovery(run) {
+    return run.runId === LATEST_RUN_ALIAS
+        ? `its id is \`${LATEST_RUN_ALIAS}\`, which \`humanish reclaim --run\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`
+        : `run \`humanish reclaim --run ${run.runId}\``;
+}
+function reclaimSummary(run, reclaimed) {
+    if (reclaimed === undefined)
+        return `reclaim failed; ${recovery(run)}.`;
+    if (reclaimed.error !== undefined)
+        return reclaimed.error.message;
+    if (reclaimed.outcomes.length === 0)
+        return "no sandbox receipts to reclaim.";
+    const counts = new Map();
+    for (const outcome of reclaimed.outcomes)
+        counts.set(outcome.state, (counts.get(outcome.state) ?? 0) + 1);
+    const tally = [...counts].map(([state, count]) => `${count} ${state}`).join(", ");
+    return reclaimed.ok ? `sandboxes: ${tally}.` : `sandboxes: ${tally}; ${recovery(run)} to retry.`;
+}