@jevitate/cli 0.1.0 → 0.2.0

package/dist/kill-signal.d.ts

@@ -0,0 +1,193 @@
+import type { UsageCounts, UsageLedger } from "@jevitate/ai-core";
+import type { TranscriptEntry } from "@jevitate/explore";
+import { type HostHealthSummary, type ResultStrategy } from "@jevitate/domain";
+import { type EngineInfo } from "./engine.js";
+/**
+ * Crash-safe termination (#94). `jevitate explore`/`explore --strategy usability` runs are commonly
+ * wrapped in an external timeout (`timeout -s TERM 900 jevitate explore ...`, the dogfooding
+ * harness's own convention) or killed by an operator. Before this module, SIGTERM/SIGINT killed the
+ * process outright — sometimes leaving NOTHING on disk to audit (no `.result.json`, even though the
+ * `MissionJournal` had already flushed every step's transcript/Recording as the run progressed).
+ *
+ * A single process-level handler is installed lazily, once, the first time any mission arms it
+ * (`armMissionKillSwitch`). On SIGTERM/SIGINT it writes a partial typed result — `outcome:
+ * "inconclusive"`, `reason: "interrupted by SIG… after N steps"` — built from whatever the journal
+ * already flushed, starts closing the shared browser pool, then exits with the conventional code
+ * (130 SIGINT / 143 SIGTERM) — all SYNCHRONOUSLY, in the same turn the signal arrives, without
+ * awaiting the browser close. Playwright installs its OWN SIGTERM/SIGINT handler on the browsers it
+ * launched; the instant that fires, any in-flight page operation starts rejecting, and the killed
+ * mission's own error handling can turn that into a normal (non-killed) result and call
+ * `process.exit` on its own terms — an `await` here, even a fast one, is enough of a window for
+ * that race to be won by the mission instead of by this handler. Writing synchronously
+ * (`writeFileSync`, already the case) and exiting before yielding the event loop makes this
+ * deterministic. Idempotent: a second signal (the wrapper/operator escalating) force-exits
+ * immediately.
+ *
+ * Several missions can be armed at once — one process may run many browser contexts on the shared
+ * pool (a daemon, a long-lived MCP server, a watch-mode queue drain). A signal flushes a partial
+ * result for EVERY armed mission, each with its own steps/usage, and tells each one's own scoped
+ * listener (`runWithMissionKillListener`) — never another mission's. Only then does the process exit,
+ * once. A mission's own outcome never exits the process: that is `process.exitCode`, set by the CLI
+ * command after the mission returns.
+ */
+export interface KillableMission {
+    /**
+     * #220: the strategy running (the unified result schema's `strategy`) and the scope it was
+     * authorized for (`target`) — so a killed run's partial result carries the same common fields as
+     * every other result. Optional only for library/test callers that arm a bare mission.
+     */
+    readonly strategy?: ResultStrategy;
+    readonly target?: {
+        readonly seedUrl: string;
+        readonly allowlist: readonly string[];
+        readonly storageStatePath?: string;
+    };
+    /**
+     * The mission's identity path — the same path handed to `MissionJournal` (a Recording path, or a
+     * report path for the usability strategy; the journal treats both identically).
+     * `transcriptPathFor`/`resultPathFor` are derived from it.
+     */
+    readonly recordingPath: string;
+    /**
+     * Where the journal flushes the transcript, when it is NOT `transcriptPathFor(recordingPath)` — a
+     * usability run keys its transcript off its report (`usability-<stamp>.transcript.json`), not off
+     * its Recording (`usability-<stamp>.recording.json`) (#120).
+     */
+    readonly transcriptPath?: string;
+    /**
+     * The live step list (the journal's last flushed entries) — read in preference to the file, so a
+     * killed run reports every step it took even when the file lags or lives elsewhere (#120).
+     */
+    readonly transcript?: () => readonly TranscriptEntry[] | undefined;
+    /**
+     * #245: the run's `--record-video` folder. A killed run lists the files already there as
+     * `videoPaths` — best effort: the signal cannot await a context close, so the last video may be
+     * truncated (the shared pool's close is started, not awaited).
+     */
+    readonly videoDir?: string;
+    /** The run's host-health summary so far (#203): a killed run's result carries it like every other result. */
+    readonly hostHealth?: () => HostHealthSummary | undefined;
+    /** The run's usage tracker: the tokens already spent are part of the killed run's result (#120). */
+    readonly usage?: {
+        snapshot(): UsageCounts;
+        calls?(): ReturnType<UsageLedger["calls"]>;
+    };
+    /**
+     * Whatever partial report the mission has so far (e.g. a usability run's observed screens and
+     * screenshots). Read synchronously on the signal; absent/throwing means no partial report.
+     */
+    readonly partialReport?: () => Record<string, unknown> | undefined;
+    /**
+     * `--save-storage-state` (#159): where to write the storageState JSON on a kill, and the mission's
+     * own `StorageStateSnapshotter.snapshot` — the last one captured while the session still looked
+     * authenticated (see `storage-state-snapshot.ts`). Read synchronously on the signal, like every
+     * other field here; `snapshot()` returning `undefined` (no safe capture yet) means nothing is
+     * written — an armed mission with no `--save-storage-state` omits this field entirely.
+     */
+    readonly storageState?: {
+        readonly path: string;
+        readonly snapshot: () => string | undefined;
+    };
+}
+/**
+ * What a killed run prints to stdout before exiting (#120): the `--json` envelope, the human summary
+ * (a non-`--json` explore, #210), or nothing (a caller that owns stdout, e.g. the MCP server, or a
+ * library use). Set by the CLI command that armed the mission.
+ */
+export type KillSwitchOutput = "envelope" | "human" | "none";
+declare const SIGNAL_EXIT_CODE: {
+    readonly SIGINT: 130;
+    readonly SIGTERM: 143;
+};
+export type KillSignal = keyof typeof SIGNAL_EXIT_CODE;
+/** The seams a test fakes: nothing here touches the real process/filesystem/browser pool. */
+export interface KillSwitchDeps {
+    readonly exit: (code: number) => void;
+    readonly closeBrowsers: () => Promise<void>;
+    readonly writeResult: (recordingPath: string, missionOutcome: string, exitCode: number, result: unknown, usage?: UsageLedger) => string;
+    readonly readTranscript: (transcriptPath: string) => {
+        steps: number;
+        transcript: readonly TranscriptEntry[];
+    };
+    readonly onSignal: (signal: KillSignal, handler: () => void) => void;
+    /** This build's identity, stamped on the killed run's result like every other result (#112). */
+    readonly engine?: () => EngineInfo;
+    /** SYNCHRONOUS stdout write — the process exits in the same turn, so nothing may be buffered. */
+    readonly writeStdout?: (text: string) => void;
+    /**
+     * `--save-storage-state` on a kill (#159): writes `json` to `path` SYNCHRONOUSLY, mode 0600.
+     * Defaults to `writeKillSnapshot` (a real `writeFileSync`); tests inject a fake here the same way
+     * they fake `writeResult`, instead of touching the real filesystem.
+     */
+    readonly writeStorageStateSnapshot?: (path: string, json: string) => void;
+}
+type KilledListener = (killed: {
+    resultPath: string;
+    exitCode: number;
+}) => void;
+/** One mission a signal killed: its partial result and where it was written (when the write succeeded). */
+export interface KilledMission {
+    readonly partial: Record<string, unknown>;
+    readonly resultPath?: string;
+}
+/**
+ * #220: an orchestrator that owns stdout for the whole command (a `--repeat`/`--persona` multi-run)
+ * reports a kill ITSELF: told the signal and every killed mission's partial result, it writes its
+ * own partial aggregate SYNCHRONOUSLY and returns what to print — instead of each run's own envelope.
+ */
+export type KillSummary = (killed: {
+    signal: KillSignal;
+    exitCode: number;
+    missions: readonly KilledMission[];
+}) => string | undefined;
+/**
+ * Installs the process-level SIGTERM/SIGINT handler with no mission armed yet. The CLI entry point
+ * (`bin.ts`) calls this ONCE, before `buildProgram`/`parseAsync` — i.e. before ANY browser can have
+ * launched. This matters: Playwright installs its OWN SIGTERM/SIGINT handler on the browser it
+ * launches (to avoid orphaning the Chromium subprocess), and Node invokes same-signal listeners in
+ * REGISTRATION ORDER — so registering ours first guarantees this module's write-then-exit always
+ * runs (and completes: writing is synchronous, and `deps.exit` is called with nothing awaited
+ * in between) before Playwright's handler can tear down the browser and let an in-flight mission's
+ * own error handling race it to `process.exit` with a different result/code. A command that never
+ * arms a mission (`jevitate journey list`, etc.) still benefits: Ctrl-C exits with the conventional
+ * code instead of Node's default. Idempotent — a redundant call (or `armMissionKillSwitch` calling
+ * it again as a safety net) is a no-op.
+ */
+export declare function installMissionKillSwitch(deps?: KillSwitchDeps): void;
+/**
+ * Arms the kill switch around a running mission: installs the process-level handler (as a safety
+ * net — the CLI entry point should already have via `installMissionKillSwitch`) and registers
+ * `mission` as the one to report on a kill signal. The caller's `finally` MUST call the returned
+ * disarm function, synchronously, before any `await` — the mission itself has (or is about to have)
+ * written its own typed result by then, so the process-level handler must stop treating a later,
+ * unrelated signal as belonging to this mission.
+ */
+export declare function armMissionKillSwitch(mission: KillableMission, deps?: KillSwitchDeps): () => void;
+/**
+ * Runs `fn` so that any mission armed inside it (at any await depth) reports a kill to `listener` —
+ * and ONLY that mission does. This is how a runner that owns one mission among several running
+ * concurrently in the process (e.g. a queue-drain item) learns where ITS result went, never another's.
+ */
+export declare function runWithMissionKillListener<T>(listener: KilledListener, fn: () => Promise<T>): Promise<T>;
+/** How many missions are armed right now (diagnostics and tests). */
+export declare function armedMissionCount(): number;
+/**
+ * What a killed run prints to stdout (#120). The CLI command that runs a mission sets it from its
+ * own flags (`--json` → the envelope) before arming; the default prints nothing.
+ */
+export declare function setKillSwitchOutput(mode: KillSwitchOutput): void;
+/**
+ * #220: installs the kill summary of an orchestrator that owns the command's stdout (a multi-run):
+ * on SIGTERM/SIGINT it replaces the per-mission output. Returns the function that removes it.
+ */
+export declare function setKillSummary(fn: KillSummary): () => void;
+/**
+ * Registers a process-wide SYNCHRONOUS listener told where EVERY killed mission's partial result was
+ * written, just before the process exits. A runner that owns one specific mission should use
+ * `runWithMissionKillListener` instead, so it never records another mission's result. Returns the
+ * unregister function.
+ */
+export declare function onMissionKilled(listener: KilledListener): () => void;
+/** Test seam: resets all module state (a real run never needs this — one process, one exit). */
+export declare function __resetKillSwitchForTests(): void;
+export {};

package/dist/kill-signal.js

@@ -0,0 +1,284 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readFileSync, writeSync } from "node:fs";
+import { MISSION_RESULT_SCHEMA_VERSION } from "@jevitate/domain";
+import { closeSharedBrowserPool } from "@jevitate/playwright";
+import { currentEngineInfo } from "./engine.js";
+import { ok } from "./envelope.js";
+import { formatMissionHuman } from "./cli-output.js";
+import { resultPathFor, writeMissionResult } from "./mission-journal.js";
+import { transcriptPathFor } from "./transcript-file.js";
+import { writeKillSnapshot } from "./storage-state-snapshot.js";
+import { listVideos } from "./browser-run-options.js";
+const SIGNAL_EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+/** Reads whatever the journal has already flushed; a run killed before its first step is 0 steps. */
+function readTranscriptFile(transcriptPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(transcriptPath, "utf8"));
+        if (Array.isArray(parsed))
+            return { steps: parsed.length, transcript: parsed };
+    }
+    catch {
+        // Not on disk yet (killed before the first step flushed) — an honest 0-step report, not a crash.
+    }
+    return { steps: 0, transcript: [] };
+}
+const realDeps = {
+    exit: (code) => process.exit(code),
+    closeBrowsers: closeSharedBrowserPool,
+    writeResult: writeMissionResult,
+    readTranscript: readTranscriptFile,
+    onSignal: (signal, handler) => {
+        process.on(signal, handler);
+    },
+    engine: currentEngineInfo,
+    writeStdout: (text) => {
+        writeSync(1, text);
+    },
+    writeStorageStateSnapshot: writeKillSnapshot,
+};
+let installed = false;
+/** Every armed mission, in arming order, with the kill listener scoped to the context that ran it. */
+const armed = new Map();
+let terminating = false;
+let output = "none";
+let summary;
+/** Process-wide listeners: told about every killed mission. */
+const killedListeners = new Set();
+/** The listener for missions armed inside `runWithMissionKillListener` (e.g. one queue-drain item). */
+const scopedListener = new AsyncLocalStorage();
+/** A getter that throws (or a missing one) yields `undefined` — a flush must never block the exit. */
+function safely(read) {
+    if (read === undefined)
+        return undefined;
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The killed run's partial typed result: every field a finished run's result would carry that exists yet. */
+function partialResult(mission, signal, code, deps) {
+    const transcriptPath = mission.transcriptPath ?? transcriptPathFor(mission.recordingPath);
+    // The live step list wins over the file (it is never behind it); the file is the fallback for a
+    // mission armed without a live reference.
+    const live = safely(mission.transcript);
+    const flushed = live === undefined ? deps.readTranscript(transcriptPath) : undefined;
+    const transcript = live ?? flushed?.transcript ?? [];
+    const steps = live === undefined ? (flushed?.steps ?? 0) : live.length;
+    const engine = safely(deps.engine);
+    const usage = safely(() => mission.usage?.snapshot());
+    const report = safely(mission.partialReport);
+    const hostHealth = safely(mission.hostHealth);
+    const videoDir = mission.videoDir;
+    const videoPaths = videoDir === undefined ? undefined : safely(() => listVideos(videoDir));
+    return {
+        // #220: the unified result schema's common fields (a kill is always the canonical `inconclusive`).
+        schemaVersion: MISSION_RESULT_SCHEMA_VERSION,
+        ...(mission.strategy === undefined ? {} : { strategy: mission.strategy }),
+        outcome: "inconclusive",
+        missionOutcome: "inconclusive",
+        // #217: a goal run's own ending travels as `goalOutcome` (a kill is the shared `inconclusive`).
+        ...(mission.strategy === "goal" ? { goalOutcome: "inconclusive" } : {}),
+        reason: `interrupted by ${signal} after ${steps} step${steps === 1 ? "" : "s"}`,
+        stop: "terminated",
+        signal,
+        steps,
+        exitCode: code,
+        defects: [],
+        hangs: [],
+        recordingPaths: [mission.recordingPath],
+        recordingPath: mission.recordingPath,
+        ...(videoPaths === undefined ? {} : { videoPaths }),
+        transcriptPath,
+        resultPath: resultPathFor(mission.recordingPath),
+        ...(mission.target === undefined ? {} : { target: { ...mission.target, allowlist: [...mission.target.allowlist] } }),
+        transcript,
+        ...(engine === undefined ? {} : { engine }),
+        ...(usage === undefined ? {} : { usage }),
+        ...(report === undefined ? {} : { partialReport: report }),
+        ...(hostHealth === undefined ? {} : { hostHealth }),
+    };
+}
+/**
+ * Synchronous by design (never `await`s before `deps.exit`): a killed mission's OWN in-flight
+ * `runExploration`/`runUsabilityMission`/etc. call is still running concurrently, and Playwright
+ * closes ITS launched browser on the same signal independently — the instant that happens, any
+ * pending page operation starts rejecting, and the mission's own error handling can turn that into
+ * a normal (non-killed) `crashed` result and call `process.exit` on its OWN terms. Racing that with
+ * an `await` here (even a fast one) is enough for the mission's own completion to win — so this
+ * writes the partial result (already synchronous: `writeFileSync`) and calls `deps.exit` in the
+ * SAME synchronous turn, before anything else gets a chance to run. Browser teardown is started but
+ * deliberately not awaited; a close that doesn't finish in time is left to the OS / Playwright's own
+ * process-group cleanup on the same signal.
+ */
+function onKillSignal(signal, deps) {
+    const code = SIGNAL_EXIT_CODE[signal];
+    if (terminating) {
+        // Escalation (a second signal, or the mission's own completion racing ahead): stop being
+        // graceful and exit right now.
+        deps.exit(code);
+        return;
+    }
+    terminating = true;
+    const killed = [];
+    for (const [mission, scoped] of [...armed]) {
+        let partial;
+        let resultPath;
+        try {
+            partial = partialResult(mission, signal, code, deps);
+            // #163: a killed run's per-call usage sidecar too (the calls it made before the signal).
+            const u = mission.usage;
+            const ledger = u?.calls === undefined ? undefined : { snapshot: () => u.snapshot(), calls: () => u.calls?.() ?? [] };
+            resultPath = deps.writeResult(mission.recordingPath, "inconclusive", code, partial, ledger);
+        }
+        catch {
+            // Best-effort: a failed flush must never keep the process from honoring the signal — nor keep
+            // the OTHER armed missions from being flushed.
+        }
+        // #159: `--save-storage-state` on a killed run — synchronous by construction (no `await`
+        // possible here, see this function's own doc comment): writes whatever the mission's
+        // `StorageStateSnapshotter` already holds (the last snapshot taken while the session still
+        // looked authenticated). Nothing is written when the mission has no `--save-storage-state`, or
+        // no safe snapshot was captured yet (e.g. killed before the first settled step).
+        try {
+            const snap = mission.storageState?.snapshot();
+            if (snap !== undefined)
+                (deps.writeStorageStateSnapshot ?? writeKillSnapshot)(mission.storageState.path, snap);
+        }
+        catch {
+            // Best-effort, like the flush above.
+        }
+        // Whoever ran THIS mission (e.g. its queue-drain item, #117) records where its result went —
+        // synchronously; process-wide listeners hear about every mission.
+        if (resultPath !== undefined) {
+            for (const listener of [...(scoped === undefined ? [] : [scoped]), ...killedListeners]) {
+                try {
+                    listener({ resultPath, exitCode: code });
+                }
+                catch {
+                    // Best-effort, like the flush.
+                }
+            }
+        }
+        if (partial !== undefined)
+            killed.push({ partial, ...(resultPath === undefined ? {} : { resultPath }) });
+        // A `--json` caller gets its envelope even from a killed run (#120) — one line per mission,
+        // written synchronously, before the exit below. An orchestrator's summary (#220) replaces them.
+        if (summary === undefined && partial !== undefined && output !== "none" && deps.writeStdout !== undefined) {
+            try {
+                deps.writeStdout(output === "envelope" ? `${JSON.stringify(ok(partial))}\n` : formatMissionHuman(partial));
+            }
+            catch {
+                // Best-effort, like the flush: stdout may already be gone (a closed pipe).
+            }
+        }
+    }
+    armed.clear();
+    // #220: the orchestrator's own partial aggregate — even when no mission was armed (killed between
+    // two runs of a multi-run) — written and printed synchronously, like everything above.
+    if (summary !== undefined) {
+        try {
+            const text = summary({ signal, exitCode: code, missions: killed });
+            if (text !== undefined && deps.writeStdout !== undefined)
+                deps.writeStdout(text);
+        }
+        catch {
+            // Best-effort, like the flush: a failed summary must never keep the process from exiting.
+        }
+    }
+    deps.closeBrowsers().catch(() => {
+        // Best-effort: a failed teardown must never keep the process from having honored the signal.
+    });
+    deps.exit(code);
+}
+function install(deps) {
+    if (installed)
+        return;
+    installed = true;
+    deps.onSignal("SIGTERM", () => onKillSignal("SIGTERM", deps));
+    deps.onSignal("SIGINT", () => onKillSignal("SIGINT", deps));
+}
+/**
+ * Installs the process-level SIGTERM/SIGINT handler with no mission armed yet. The CLI entry point
+ * (`bin.ts`) calls this ONCE, before `buildProgram`/`parseAsync` — i.e. before ANY browser can have
+ * launched. This matters: Playwright installs its OWN SIGTERM/SIGINT handler on the browser it
+ * launches (to avoid orphaning the Chromium subprocess), and Node invokes same-signal listeners in
+ * REGISTRATION ORDER — so registering ours first guarantees this module's write-then-exit always
+ * runs (and completes: writing is synchronous, and `deps.exit` is called with nothing awaited
+ * in between) before Playwright's handler can tear down the browser and let an in-flight mission's
+ * own error handling race it to `process.exit` with a different result/code. A command that never
+ * arms a mission (`jevitate journey list`, etc.) still benefits: Ctrl-C exits with the conventional
+ * code instead of Node's default. Idempotent — a redundant call (or `armMissionKillSwitch` calling
+ * it again as a safety net) is a no-op.
+ */
+export function installMissionKillSwitch(deps = realDeps) {
+    install(deps);
+}
+/**
+ * Arms the kill switch around a running mission: installs the process-level handler (as a safety
+ * net — the CLI entry point should already have via `installMissionKillSwitch`) and registers
+ * `mission` as the one to report on a kill signal. The caller's `finally` MUST call the returned
+ * disarm function, synchronously, before any `await` — the mission itself has (or is about to have)
+ * written its own typed result by then, so the process-level handler must stop treating a later,
+ * unrelated signal as belonging to this mission.
+ */
+export function armMissionKillSwitch(mission, deps = realDeps) {
+    install(deps);
+    armed.set(mission, scopedListener.getStore());
+    return () => {
+        armed.delete(mission);
+    };
+}
+/**
+ * Runs `fn` so that any mission armed inside it (at any await depth) reports a kill to `listener` —
+ * and ONLY that mission does. This is how a runner that owns one mission among several running
+ * concurrently in the process (e.g. a queue-drain item) learns where ITS result went, never another's.
+ */
+export function runWithMissionKillListener(listener, fn) {
+    return scopedListener.run(listener, fn);
+}
+/** How many missions are armed right now (diagnostics and tests). */
+export function armedMissionCount() {
+    return armed.size;
+}
+/**
+ * What a killed run prints to stdout (#120). The CLI command that runs a mission sets it from its
+ * own flags (`--json` → the envelope) before arming; the default prints nothing.
+ */
+export function setKillSwitchOutput(mode) {
+    output = mode;
+}
+/**
+ * #220: installs the kill summary of an orchestrator that owns the command's stdout (a multi-run):
+ * on SIGTERM/SIGINT it replaces the per-mission output. Returns the function that removes it.
+ */
+export function setKillSummary(fn) {
+    summary = fn;
+    return () => {
+        if (summary === fn)
+            summary = undefined;
+    };
+}
+/**
+ * Registers a process-wide SYNCHRONOUS listener told where EVERY killed mission's partial result was
+ * written, just before the process exits. A runner that owns one specific mission should use
+ * `runWithMissionKillListener` instead, so it never records another mission's result. Returns the
+ * unregister function.
+ */
+export function onMissionKilled(listener) {
+    killedListeners.add(listener);
+    return () => {
+        killedListeners.delete(listener);
+    };
+}
+/** Test seam: resets all module state (a real run never needs this — one process, one exit). */
+export function __resetKillSwitchForTests() {
+    installed = false;
+    armed.clear();
+    terminating = false;
+    output = "none";
+    summary = undefined;
+    killedListeners.clear();
+}
+//# sourceMappingURL=kill-signal.js.map

package/dist/kill-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-signal.js","sourceRoot":"","sources":["../src/kill-signal.ts"],"names":[],"mappings":"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"}

package/dist/launch-armed.d.ts

@@ -0,0 +1,37 @@
+import type { HostHealthSampler } from "@jevitate/explore";
+import type { HostHealthSummary } from "@jevitate/domain";
+import { type KillableMission } from "./kill-signal.js";
+import { StorageStateSnapshotter } from "./storage-state-snapshot.js";
+/**
+ * #226: what an armed mission's kill-switch hooks read before the host sampler and the browser exist:
+ * `undefined` until the launch finished, the live values after.
+ */
+export interface ArmedHooks {
+    readonly hostHealth: () => HostHealthSummary | undefined;
+    readonly snapshot: () => string | undefined;
+}
+export interface LaunchArmedOptions<S> {
+    /** The mission the kill switch reports on — built from `hooks`, never from the (not yet open) session. */
+    readonly mission: (hooks: ArmedHooks) => KillableMission;
+    /** Test seam (#203): the run's host-health sampler. Default: this host's. */
+    readonly hostHealth?: HostHealthSampler;
+    /** `--save-storage-state` was given: the snapshotter captures after settled steps. */
+    readonly saveStorageState: boolean;
+    /** Opens the run's browser session. */
+    readonly open: () => Promise<S>;
+}
+/**
+ * THE way a mission runner launches its browser (#226): the kill switch is armed FIRST — before the
+ * host sampler and the browser launch (Chromium can take seconds to start on a loaded host) — so a
+ * SIGTERM/SIGINT at any point from here writes and prints the partial result instead of exiting
+ * 143/130 with nothing. A failed launch stops the sampler and disarms the switch before rethrowing
+ * (the command reports that error itself).
+ */
+export declare function launchArmed<S extends {
+    captureStorageState?(): Promise<string>;
+}>(opts: LaunchArmedOptions<S>): Promise<{
+    disarmKillSwitch: () => void;
+    health: HostHealthSampler;
+    session: S;
+    snapshotter: StorageStateSnapshotter;
+}>;

package/dist/launch-armed.js

@@ -0,0 +1,31 @@
+import { startHostHealth } from "./host-health-run.js";
+import { armMissionKillSwitch } from "./kill-signal.js";
+import { StorageStateSnapshotter } from "./storage-state-snapshot.js";
+/**
+ * THE way a mission runner launches its browser (#226): the kill switch is armed FIRST — before the
+ * host sampler and the browser launch (Chromium can take seconds to start on a loaded host) — so a
+ * SIGTERM/SIGINT at any point from here writes and prints the partial result instead of exiting
+ * 143/130 with nothing. A failed launch stops the sampler and disarms the switch before rethrowing
+ * (the command reports that error itself).
+ */
+export async function launchArmed(opts) {
+    let health;
+    let snapshotter;
+    const disarmKillSwitch = armMissionKillSwitch(opts.mission({ hostHealth: () => health?.summary(), snapshot: () => snapshotter?.snapshot() }));
+    let started;
+    try {
+        started = await startHostHealth(opts.hostHealth);
+        const session = await opts.open();
+        // #159: refreshed after each settled step; the kill switch writes whatever this holds synchronously.
+        const snap = new StorageStateSnapshotter(session, opts.saveStorageState);
+        health = started;
+        snapshotter = snap;
+        return { disarmKillSwitch, health: started, session, snapshotter: snap };
+    }
+    catch (e) {
+        started?.stop();
+        disarmKillSwitch();
+        throw e;
+    }
+}
+//# sourceMappingURL=launch-armed.js.map

package/dist/launch-armed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-armed.js","sourceRoot":"","sources":["../src/launch-armed.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAwB,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAsBtE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAA2B;IAE3B,IAAI,MAAqC,CAAC;IAC1C,IAAI,WAAgD,CAAC;IACrD,MAAM,gBAAgB,GAAG,oBAAoB,CAC3C,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE,CAAC,CAC/F,CAAC;IACF,IAAI,OAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClC,qGAAqG;QACrG,MAAM,IAAI,GAAG,IAAI,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACzE,MAAM,GAAG,OAAO,CAAC;QACjB,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,CAAC;QAChB,gBAAgB,EAAE,CAAC;QACnB,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}