@jevitate/cli 0.1.0 → 0.3.0

package/dist/source-cli.js

@@ -0,0 +1,284 @@
+import { existsSync } from "node:fs";
+import { ParamValidationError } from "@jevitate/journey";
+import { ok, fail } from "./envelope.js";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { UnknownJourneyError, JourneyRequiresAuthError } from "./journey-api.js";
+import { withSiteGate } from "./site-gate-cli.js";
+import { withEngine } from "./engine.js";
+import { addSource, listSources, pullSource, updateSource, removeSource, trustJourney } from "./source-api.js";
+import { runSourceJourney, realResolvedJourneyRunner } from "./source-run-api.js";
+import { UnknownSourceError, EmbeddedSecretError, UndeclaredOriginError, UndeclaredTouError, HashMismatchError, UntrustedRiskyJourneyError, SourceValidationError, } from "@jevitate/sources";
+import { resolveDbPath, resolveSourceApiDeps, resolveApprovedBy, withBrowserLaunchFlags, browserOption, withEmulationFlags, emulationFromFlags, collectParam, emitJson, writeRawResult, } from "./cli-shared.js";
+/** Registers `jevitate source`: `add|list|pull|update|remove|trust|run`. */
+export function registerSourceCommands(program, deps) {
+    // #18 — manage distributed Journey sources (add/list/pull/update/remove/
+    // trust). Trust is an explicit user act, content-hash-bound; add/pull/update
+    // never trust anything implicitly.
+    const source = program.command("source").description("manage distributed Journey sources (git-backed collections of Journeys)");
+    source
+        .command("add <name> <gitUrl>")
+        .option("--accept-tou", "acknowledge the source's declared Terms of Use (required before its Journeys can run)")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name, gitUrl) {
+        const { acceptTou, json } = this.opts();
+        try {
+            const apiDeps = resolveSourceApiDeps(deps);
+            const result = await addSource(apiDeps, {
+                name,
+                gitUrl,
+                acceptTou: acceptTou ?? false,
+                ackedBy: resolveApprovedBy(deps),
+            });
+            const envelope = ok(result);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                const out = program.configureOutput().writeOut;
+                out?.(`added '${name}' pinned at ${result.pinnedCommit}\n`);
+                out?.(`Terms of Use for ${result.touSurface.gitUrl}:\n`);
+                for (const site of result.touSurface.sites)
+                    out?.(`  ${site.origin}\t${site.touBasis}\n`);
+                out?.(result.touAccepted ? "ToU acknowledged.\n" : "ToU NOT acknowledged — re-run with --accept-tou before running this source's Journeys.\n");
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof SourceValidationError) {
+                emitJson(program, fail("E_SOURCE_INVALID_MANIFEST", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_ADD", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+    source
+        .command("list")
+        .option("--json", "emit a JSON envelope")
+        .action(async function () {
+        const { json } = this.opts();
+        try {
+            const listing = await listSources(resolveSourceApiDeps(deps));
+            const envelope = ok(listing);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                const out = program.configureOutput().writeOut;
+                if (listing.length === 0) {
+                    out?.("no sources yet — add one with `jevitate source add <name> <gitUrl>`\n");
+                }
+                else {
+                    for (const s of listing) {
+                        out?.(`${s.name}\t${s.gitUrl}\t${s.pinnedCommit}\ttrusted=[${s.trustedJourneys.join(", ")}]\n`);
+                    }
+                }
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            emitJson(program, fail("E_SOURCE_LIST", String(err instanceof Error ? err.message : err)));
+        }
+    });
+    source
+        .command("pull <name>")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name) {
+        const { json } = this.opts();
+        try {
+            const result = await pullSource(resolveSourceApiDeps(deps), name);
+            const envelope = ok(result);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                program.configureOutput().writeOut?.(`pulled '${name}' (pin unchanged at ${result.pinnedCommit}; run 'source update' to advance)\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof UnknownSourceError) {
+                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_PULL", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+    source
+        .command("update <name>")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name) {
+        const { json } = this.opts();
+        try {
+            const result = await updateSource(resolveSourceApiDeps(deps), name);
+            const envelope = ok(result);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                program.configureOutput().writeOut?.(`updated '${name}' -> pinned at ${result.pinnedCommit}\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof UnknownSourceError) {
+                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_UPDATE", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+    source
+        .command("remove <name>")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name) {
+        const { json } = this.opts();
+        try {
+            const result = await removeSource(resolveSourceApiDeps(deps), name);
+            const envelope = ok(result);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                program.configureOutput().writeOut?.(`removed '${name}'\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof UnknownSourceError) {
+                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_REMOVE", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+    source
+        .command("trust <name> <journeyId>")
+        .description("explicitly trust one Journey in a source, bound to its current content hash")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name, journeyId) {
+        const { json } = this.opts();
+        try {
+            const result = await trustJourney(resolveSourceApiDeps(deps), {
+                sourceName: name,
+                journeyId,
+                approvedBy: resolveApprovedBy(deps),
+            });
+            // Never emit the Journey's content — only the address + bound hash.
+            const view = { sourceId: result.sourceId, journeyId: result.journeyId, contentHash: result.contentHash, approvedBy: result.approvedBy, approvedAtIso: result.approvedAtIso };
+            const envelope = ok(view);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                program.configureOutput().writeOut?.(`trusted '${name}/${journeyId}' at ${result.contentHash}\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof UnknownSourceError) {
+                emitJson(program, fail("E_SOURCE_UNKNOWN", err.message));
+            }
+            else if (err instanceof UnknownJourneyError) {
+                emitJson(program, fail("E_SOURCE_UNKNOWN_JOURNEY", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_TRUST", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+    // #26 — run a Journey that lives in a trusted remote source, THROUGH the
+    // existing run-gate (`@jevitate/sources`' `resolveForRun`). RULING: this is a
+    // `source run` subcommand (not `journey run --from-source`) because the whole
+    // trust boundary is source-scoped — the `<source>/<id>` address, the
+    // per-source manifest/ToU-ack/trust records all live under `source`. `journey
+    // run` stays the LOCAL FsJourneyStore path; keeping remote runs here keeps the
+    // two trust boundaries visibly separate. The run NEVER bypasses a gate: every
+    // refusal below is a typed error thrown by `resolveForRun` BEFORE any browser.
+    withBrowserLaunchFlags(withEmulationFlags(source.command("run <name> <journeyId>")))
+        .description("run a Journey from a trusted remote source through the run-gate")
+        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
+        .option("--storage-state <file>", "Playwright storageState JSON to start the session authenticated (#118: required when the journey declares metadata.requiresAuth); must exist")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (name, journeyId) {
+        const { param, storageState, json, ...emulationFlags } = this.opts();
+        if (storageState !== undefined && !existsSync(storageState)) {
+            emitJson(program, fail("E_SOURCE_RUN_ARGS", `storage state not found: ${storageState}`));
+            return;
+        }
+        let sourceRunEmulation;
+        try {
+            sourceRunEmulation = emulationFromFlags(emulationFlags);
+        }
+        catch (err) {
+            emitJson(program, fail("E_SOURCE_RUN_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        try {
+            const apiDeps = {
+                ...resolveSourceApiDeps(deps),
+                runJourney: deps.sources?.runJourney ?? realResolvedJourneyRunner,
+            };
+            const result = withEngine(await withSiteGate(resolveDbPath(deps), (siteGate) => runSourceJourney(apiDeps, {
+                ...(siteGate === undefined ? {} : { siteGate }),
+                sourceName: name,
+                journeyId,
+                params: param,
+                ...(sourceRunEmulation === undefined ? {} : { emulation: sourceRunEmulation }),
+                ...(storageState !== undefined ? { storageState } : {}),
+                ...browserOption(this.opts()),
+            })));
+            const envelope = ok(result);
+            if (json) {
+                emitJson(program, envelope);
+                if (result.outcome === "quarantined")
+                    process.exitCode = 1;
+            }
+            else {
+                writeRawResult(program, result);
+                process.exitCode = result.outcome === "quarantined" ? 1 : 0;
+            }
+        }
+        catch (err) {
+            // Each run-gate refusal maps to a distinct E_SOURCE_RUN* code so a
+            // caller can tell WHY the run was refused without string-matching.
+            if (err instanceof SiteGateRefusedError) {
+                emitJson(program, fail(err.code, err.message));
+            }
+            else if (err instanceof UnknownSourceError) {
+                emitJson(program, fail("E_SOURCE_RUN_UNKNOWN", err.message));
+            }
+            else if (err instanceof HashMismatchError) {
+                emitJson(program, fail("E_SOURCE_RUN_HASH_MISMATCH", err.message));
+            }
+            else if (err instanceof UntrustedRiskyJourneyError) {
+                emitJson(program, fail("E_SOURCE_RUN_UNTRUSTED", err.message));
+            }
+            else if (err instanceof UndeclaredOriginError) {
+                emitJson(program, fail("E_SOURCE_RUN_ORIGIN", err.message));
+            }
+            else if (err instanceof UndeclaredTouError) {
+                emitJson(program, fail("E_SOURCE_RUN_TOU", err.message));
+            }
+            else if (err instanceof EmbeddedSecretError) {
+                emitJson(program, fail("E_SOURCE_RUN_SECRET", err.message));
+            }
+            else if (err instanceof SourceValidationError) {
+                emitJson(program, fail("E_SOURCE_RUN_INVALID_MANIFEST", err.message));
+            }
+            else if (err instanceof ParamValidationError) {
+                emitJson(program, fail("E_INVALID_PARAMS", err.message));
+            }
+            else if (err instanceof JourneyRequiresAuthError) {
+                emitJson(program, fail("E_JOURNEY_REQUIRES_AUTH", err.message));
+            }
+            else {
+                emitJson(program, fail("E_SOURCE_RUN", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+}
+//# sourceMappingURL=source-cli.js.map

package/dist/source-cli.js.map

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

package/dist/source-run-api.d.ts

@@ -1,4 +1,6 @@
+import type { SiteGateDeps } from "@jevitate/runtime";
 import { type RunPolicy } from "@jevitate/domain";
+import { type BrowserLaunchOptions, type EmulationSpec } from "@jevitate/playwright";
 import { type JourneyRunResult } from "@jevitate/runtime";
 import { type SharedJourneyFile } from "@jevitate/sources";
 import type { SourceApiDeps } from "./source-api.js";
@@ -9,7 +11,19 @@ import type { SourceApiDeps } from "./source-api.js";
  * function. Injected as a fake in tests so unit tests never launch a real
  * browser; production wires `realResolvedJourneyRunner`.
  */
-export type RunResolvedJourney = (file: SharedJourneyFile, params: Record<string, string>, policy: RunPolicy) => Promise<JourneyRunResult>;
+export type RunResolvedJourney = (file: SharedJourneyFile, params: Record<string, string>, policy: RunPolicy, 
+/**
+ * Playwright storageState JSON to seed the session from (CLI `--storage-state`, #118) — the
+ * deterministic authenticated pre-step. Contains live session cookies: handed only to the
+ * browser, never logged, never sent to a model.
+ */
+storageState?: string, 
+/** Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`). */
+emulation?: EmulationSpec, 
+/** Chromium launch options (CLI `--browser-executable` / `--browser-channel` / `--browser-arg`). */
+browser?: BrowserLaunchOptions, 
+/** The site-policy gate (`jevitate site policy set`): pacing, throttles, budgets, quiet hours. */
+siteGate?: SiteGateDeps) => Promise<JourneyRunResult>;
 /**
  * The real, Playwright-backed runner for a gated source Journey. Mirrors
  * `journey-api.ts`'s `runJourneyProgrammatically` exactly:
@@ -40,6 +54,18 @@ export interface RunSourceJourneyRequest {
     params: Record<string, string>;
     /** Defaults to `safeRunPolicy()` (Slice 1 fail-closed secret mode). */
     policy?: RunPolicy;
+    /**
+     * Playwright storageState JSON to seed the session from (CLI `--storage-state`, #118) — the
+     * deterministic authenticated pre-step. Contains live session cookies: handed only to the
+     * browser, never logged, never sent to a model.
+     */
+    storageState?: string;
+    /** Per-mission viewport/device emulation (#149, CLI `--viewport <W>x<H>` / `--device "<name>"`). */
+    emulation?: EmulationSpec;
+    /** Chromium launch options (CLI `--browser-*`). */
+    browser?: BrowserLaunchOptions;
+    /** The site-policy gate (`jevitate site policy set`); absent = no site policy. */
+    siteGate?: SiteGateDeps;
 }
 /**
  * Runs a Journey that lives in a trusted remote source — the ONE programmatic

package/dist/source-run-api.js

@@ -1,13 +1,13 @@
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { deriveParamSchema, validateParams } from "@jevitate/journey";
+import { gateJourney } from "./site-gate-cli.js";
 import { safeRunPolicy } from "@jevitate/domain";
 import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { sessionLaunchOptions } from "./browser-run-options.js";
 import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
 import { RecordingInterpreter } from "@jevitate/interpreter";
 import { JourneyRunner } from "@jevitate/runtime";
 import { FederatedJourneyRegistry, GitSourceManager, RemoteSource, UnknownSourceError, loadManifest, readLock, resolveForRun, } from "@jevitate/sources";
+import { JourneyRequiresAuthError } from "./journey-api.js";
 /**
  * The real, Playwright-backed runner for a gated source Journey. Mirrors
  * `journey-api.ts`'s `runJourneyProgrammatically` exactly:
@@ -20,27 +20,38 @@ import { FederatedJourneyRegistry, GitSourceManager, RemoteSource, UnknownSource
  * A `SharedJourneyFile` IS a `Journey` (+ `declaredOrigins`), so it runs
  * through the standard `JourneyRunner` unchanged.
  */
-export const realResolvedJourneyRunner = async (file, params, policy) => {
+export const realResolvedJourneyRunner = async (file, params, policy, storageState, emulation, browser, siteGate) => {
+    // #118: a Journey that declares it needs auth refuses BEFORE any browser launch when no
+    // storageState was given — a clear, typed failure instead of a deep `replay-target-not-found`.
+    if (file.metadata.requiresAuth === true && storageState === undefined) {
+        throw new JourneyRequiresAuthError(`journey '${file.metadata.id}' requires auth (metadata.requiresAuth) — run with --storage-state <file>`);
+    }
     validateParams(deriveParamSchema(file.recording), params);
     // The browser allowlist is the Journey's authorized origin set — the base
     // site plus every gate-approved declared origin.
     const allowedOrigins = [...new Set([file.recording.site, ...file.declaredOrigins])];
-    const profileDir = await mkdtemp(join(tmpdir(), "jevitate-source-run-"));
+    // The site policy for the Journey's origin, decided before the browser opens.
+    const gate = await gateJourney(siteGate, file.recording, { enforceLimits: true });
     const port = new PlaywrightBrowserPort();
     const session = await port.open({
-        profileDir,
-        headless: true,
+        ...sessionLaunchOptions(browser),
         allowedOrigins,
         baseUrl: file.recording.site,
+        ...emulation,
+        ...(storageState !== undefined ? { storageState } : {}),
     });
     try {
-        const actor = CastActor.named("source-runner").whoCan(new BrowseTheWeb(session, allowedOrigins));
+        const actor = CastActor.named("source-runner").whoCan(new BrowseTheWeb(session, allowedOrigins), ...gate.abilities);
         const runner = new JourneyRunner(actor, new RecordingInterpreter());
-        return await runner.run({ journey: file, params, policy });
+        try {
+            return await runner.run({ journey: file, params, policy });
+        }
+        finally {
+            await gate.done();
+        }
     }
     finally {
         await session.close();
-        await rm(profileDir, { recursive: true, force: true });
     }
 };
 /** Resolves a registered source's recorded pin, or throws `UnknownSourceError`
@@ -86,6 +97,6 @@ export async function runSourceJourney(deps, req) {
     // ready-to-run file only when every gate passes.
     const file = await resolveForRun(gateDeps, `${req.sourceName}/${req.journeyId}`);
     const run = deps.runJourney ?? realResolvedJourneyRunner;
-    return run(file, req.params, req.policy ?? safeRunPolicy());
+    return run(file, req.params, req.policy ?? safeRunPolicy(), req.storageState, req.emulation, req.browser, req.siteGate);
 }
 //# sourceMappingURL=source-run-api.js.map

package/dist/source-run-api.js.map

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

package/dist/storage-state-snapshot.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `--save-storage-state` must survive a crash or a kill signal (#159), not just a clean exit: a
+ * rotating refresh token means the OLD `--storage-state` file is already stale by the time a run
+ * ends — losing the write on a crash/SIGTERM starts the next mission logged out.
+ *
+ * The crashed-run case is solved in each mission's own `finally` (a thrown error still reaches it —
+ * see `persistStorageState` in `explore-api.ts`/`ux-api.ts`). The KILLED case cannot: `kill-signal.ts`
+ * writes its partial result and exits SYNCHRONOUSLY, in the same turn the signal arrives (deliberately
+ * — see its own doc comment), and capturing Playwright's `storageState()` is async. There is no way to
+ * `await` it there without reopening the exact race that module exists to close.
+ *
+ * The fix: keep a cheap, best-effort, in-memory snapshot that is refreshed after every SETTLED step —
+ * so by the time a signal lands, `snapshot()` already holds a recent one, and the kill switch can
+ * write it with a plain synchronous `writeFileSync`.
+ *
+ * Never overwrites a good session with a lost/logged-out one: a refresh is skipped whenever the
+ * CURRENT page looks login-like (`isLoginLikeUrl`, the same #82 pattern `seedRedirectReason` uses) —
+ * so the snapshot held at that moment is the last one taken while the session still looked good, and
+ * that is what both the kill switch and the mission's own `finally` fallback end up writing. Nothing
+ * here is ever logged; the snapshot text is the same storageState JSON `--save-storage-state` writes.
+ */
+export declare class StorageStateSnapshotter {
+    #private;
+    private readonly session;
+    /** `false` when `--save-storage-state` was not given: every call below is then a no-op that
+     *  never touches the browser (a run without the flag pays nothing). */
+    private readonly enabled;
+    constructor(session: {
+        captureStorageState?(): Promise<string>;
+    }, 
+    /** `false` when `--save-storage-state` was not given: every call below is then a no-op that
+     *  never touches the browser (a run without the flag pays nothing). */
+    enabled: boolean);
+    /**
+     * Call after each settled step, with the page's CURRENT url. Fire-and-forget: never awaited by the
+     * mission loop (the capture cost must never slow down the run), never throws, and coalesces — a
+     * capture already in flight is left to finish rather than started twice.
+     */
+    noteSettledStep(currentUrl: string | undefined): void;
+    /** The last known-good snapshot, or `undefined` if none was ever safely captured. */
+    snapshot(): string | undefined;
+}
+/**
+ * The kill switch's synchronous write (#159): called from `onKillSignal` for each armed mission that
+ * declared a `--save-storage-state` path and has a snapshot to write. Mode 0600 (owner read/write
+ * only — the file holds live session cookies); a failed write is swallowed the same way every other
+ * best-effort step in the kill path is (a full disk must never keep the OTHER armed missions from
+ * being flushed, nor keep the process from exiting).
+ */
+export declare function writeKillSnapshot(path: string, json: string): void;

package/dist/storage-state-snapshot.js

@@ -0,0 +1,87 @@
+import { writeFileSync } from "node:fs";
+import { sessionFileInProjectRefusal } from "./project-dir.js";
+import { isLoginLikeUrl } from "@jevitate/explore";
+/**
+ * `--save-storage-state` must survive a crash or a kill signal (#159), not just a clean exit: a
+ * rotating refresh token means the OLD `--storage-state` file is already stale by the time a run
+ * ends — losing the write on a crash/SIGTERM starts the next mission logged out.
+ *
+ * The crashed-run case is solved in each mission's own `finally` (a thrown error still reaches it —
+ * see `persistStorageState` in `explore-api.ts`/`ux-api.ts`). The KILLED case cannot: `kill-signal.ts`
+ * writes its partial result and exits SYNCHRONOUSLY, in the same turn the signal arrives (deliberately
+ * — see its own doc comment), and capturing Playwright's `storageState()` is async. There is no way to
+ * `await` it there without reopening the exact race that module exists to close.
+ *
+ * The fix: keep a cheap, best-effort, in-memory snapshot that is refreshed after every SETTLED step —
+ * so by the time a signal lands, `snapshot()` already holds a recent one, and the kill switch can
+ * write it with a plain synchronous `writeFileSync`.
+ *
+ * Never overwrites a good session with a lost/logged-out one: a refresh is skipped whenever the
+ * CURRENT page looks login-like (`isLoginLikeUrl`, the same #82 pattern `seedRedirectReason` uses) —
+ * so the snapshot held at that moment is the last one taken while the session still looked good, and
+ * that is what both the kill switch and the mission's own `finally` fallback end up writing. Nothing
+ * here is ever logged; the snapshot text is the same storageState JSON `--save-storage-state` writes.
+ */
+export class StorageStateSnapshotter {
+    session;
+    enabled;
+    #last;
+    #pending = false;
+    constructor(session, 
+    /** `false` when `--save-storage-state` was not given: every call below is then a no-op that
+     *  never touches the browser (a run without the flag pays nothing). */
+    enabled) {
+        this.session = session;
+        this.enabled = enabled;
+    }
+    /**
+     * Call after each settled step, with the page's CURRENT url. Fire-and-forget: never awaited by the
+     * mission loop (the capture cost must never slow down the run), never throws, and coalesces — a
+     * capture already in flight is left to finish rather than started twice.
+     */
+    noteSettledStep(currentUrl) {
+        if (!this.enabled || this.#pending || this.session.captureStorageState === undefined)
+            return;
+        if (currentUrl !== undefined && isLoginLikeUrl(currentUrl))
+            return;
+        this.#pending = true;
+        this.session
+            .captureStorageState()
+            .then((json) => {
+            this.#last = json;
+        })
+            .catch(() => {
+            // Best-effort: a failed capture just leaves the previous (still good) snapshot in place.
+        })
+            .finally(() => {
+            this.#pending = false;
+        });
+    }
+    /** The last known-good snapshot, or `undefined` if none was ever safely captured. */
+    snapshot() {
+        return this.#last;
+    }
+}
+/**
+ * The kill switch's synchronous write (#159): called from `onKillSignal` for each armed mission that
+ * declared a `--save-storage-state` path and has a snapshot to write. Mode 0600 (owner read/write
+ * only — the file holds live session cookies); a failed write is swallowed the same way every other
+ * best-effort step in the kill path is (a full disk must never keep the OTHER armed missions from
+ * being flushed, nor keep the process from exiting).
+ */
+export function writeKillSnapshot(path, json) {
+    // #195: never into a repo's .jevitate/ — refused loudly (stderr), the write skipped; the kill path
+    // must still flush the other missions and exit, so it does not throw.
+    const refusal = sessionFileInProjectRefusal(path, "save-storage-state");
+    if (refusal !== undefined) {
+        process.stderr.write(`jevitate: storage state not written: ${refusal}\n`);
+        return;
+    }
+    try {
+        writeFileSync(path, json, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Best-effort, like every other write in the kill path.
+    }
+}
+//# sourceMappingURL=storage-state-snapshot.js.map

package/dist/storage-state-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-state-snapshot.js","sourceRoot":"","sources":["../src/storage-state-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,uBAAuB;IAKf;IAGA;IAPnB,KAAK,CAAqB;IAC1B,QAAQ,GAAG,KAAK,CAAC;IAEjB,YACmB,OAAoD;IACrE;2EACuE;IACtD,OAAgB;QAHhB,YAAO,GAAP,OAAO,CAA6C;QAGpD,YAAO,GAAP,OAAO,CAAS;IAChC,CAAC;IAEJ;;;;OAIG;IACH,eAAe,CAAC,UAA8B;QAC5C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS;YAAE,OAAO;QAC7F,IAAI,UAAU,KAAK,SAAS,IAAI,cAAc,CAAC,UAAU,CAAC;YAAE,OAAO;QACnE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,OAAO;aACT,mBAAmB,EAAE;aACrB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,yFAAyF;QAC3F,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC,CAAC,CAAC;IACP,CAAC;IAED,qFAAqF;IACrF,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAY;IAC1D,mGAAmG;IACnG,sEAAsE;IACtE,MAAM,OAAO,GAAG,2BAA2B,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IACxE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,OAAO,IAAI,CAAC,CAAC;QAC1E,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC"}