@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

package/lib/types/index.js

@@ -1,16 +1,65 @@
 import z from '@deepseek-ai/schemastery';
 import { connect } from 'node:net';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-import { resolveSessionPreset } from '@deepseek-ai/dsh-agent-presets';
-import { execFileSync } from 'node:child_process';
+// Namespace handle for runtime feature detection: the 0.1.2 host replaced
+// the `resolveSessionPreset` free function (and the `PresetBearingSession`
+// type) with the `agentPresetProjectionDefinition` unit, and a STATIC named
+// import of a removed export is a SyntaxError at module load — exactly the
+// failure this dual-host probing exists to survive. The derivation below
+// reads both surfaces through one structural cast.
+import * as agentPresetsHost from '@deepseek-ai/dsh-agent-presets';
 import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveRepoDir, resolveStateDir, SRC_ARTIFACT_PATTERN } from "./defaults.js";
-import { commitCheckpoint, currentHead, resetToCheckpoint } from "./git.js";
+import { commitCheckpoint, currentHead, isWorkingTreeClean, resetToCheckpoint } from "./git.js";
+import { listeningPortsForPid } from "./processes.js";
+import { cutoverBlocksWake } from "./launch-spec.js";
 import { stateFile } from "./state-files.js";
-import { acknowledgeRestartRecord, buildLaunchCommand, continueAndReportText, continueInterruptedText, interruptedSnapshotFile, writeInstanceLaunch, writeSkillRegistration, pendingRestartRecord, readInterruptedSnapshot, restartContextText, writeInterruptedSnapshot, } from "./restart-context.js";
+import { registerBrowserHandoff } from "./browser-handoff.js";
+import { requestRestart } from "./restart-request.js";
+import { acknowledgeRestartRecord, buildLaunchCommand, continueAndReportText, continueInterruptedText, interruptedSnapshotFile, isParkedOnUserInput, writeInstanceLaunch, writeSkillRegistration, pendingRestartRecord, readInterruptedSnapshot, restartContextText, writeInterruptedSnapshot, } from "./restart-context.js";
 import { clearCredential, loadState, recordCredential, setCheckpoint, verifyCredential, } from "./state.js";
+/**
+ * Which preset a session actually runs, newest selection winning. The rc host
+ * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
+ * replaced it with `agentPresetProjectionDefinition` (init from the header,
+ * fold `agent-preset/selected` events) — same semantics, so the derivation
+ * feature-detects either surface and never touches the version string. A host
+ * with neither yields undefined: the resume falls back to the deployment's
+ * default preset, the same outcome a preset-less session had before.
+ * @param host - the agent-presets module namespace, structurally probed.
+ * @param session - the session's header and event log.
+ * @returns the preset id, or `undefined` when the session names none.
+ */
+export function deriveSessionPreset(host, session) {
+    if (host.agentPresetProjectionDefinition !== undefined) {
+        const projection = host.agentPresetProjectionDefinition;
+        let state = projection.init(session.header);
+        for (const event of session.events)
+            state = projection.apply(state, event);
+        return state ?? undefined;
+    }
+    return host.resolveSessionPreset?.(session);
+}
+/** Probe the session-persistence service's cold-read face. */
+function probeColdReader(ctx) {
+    const service = ctx.get('sessionPersistence');
+    if (service === undefined || service === null)
+        return undefined;
+    return typeof service.open === 'function' ? service : undefined;
+}
+/** Read one persisted session's header and full log through a read handle. */
+async function readColdLog(persistence, id) {
+    const handle = await persistence.open(id, 'read');
+    try {
+        const cold = await handle.read(0);
+        return { meta: handle.header, events: cold.events };
+    }
+    finally {
+        await handle.close();
+    }
+}
 export const Config = z.object({
     maxAgeMinutes: z.natural().min(1).default(10),
     stateDir: z.string().default(''),
@@ -56,7 +105,13 @@ function registerRestartSkill(ctx, stateDir) {
             writeSkillRegistration(stateDir, { registered: false, reason: 'shipped SKILL.md malformed', at: Date.now() });
             return;
         }
-        ctx.effect(() => skills.register({ name, description, content, source: 'runtime' }));
+        ctx.effect(() => skills.register({
+            name,
+            description,
+            content,
+            source: 'runtime',
+            provider: 'ankh-guard',
+        }));
         writeSkillRegistration(stateDir, { registered: true, at: Date.now() });
     }
     catch (error) {
@@ -119,6 +174,7 @@ export function apply(ctx, config) {
     // (default-on!) with no warning — a misconfiguration failing silent.
     const followupReport = reportMode === 'followup';
     registerRestartSkill(ctx, stateDir);
+    registerBrowserHandoff(ctx, stateDir);
     if (followupReport || resumeInterrupted) {
         const pluginMessage = (text) => createUserMessage({
             content: [{ type: 'text', text }],
@@ -129,6 +185,33 @@ export function apply(ctx, config) {
         const pendingContinue = new Map();
         let disposed = false;
         ctx.effect(() => () => { disposed = true; });
+        // A turn parked on user input (an open ask_user_question call, or an
+        // undecided approval) is not interrupted WORK — the card persists in the
+        // log and the user answers whenever. Auto-continuing it replays the
+        // question and burns a turn for nothing (observed on prod 3080: sessions
+        // parked on question cards were woken on every restart of an upgrade
+        // day). The probe reads the session's repaired log tail; memoized per
+        // boot; a probe failure fails open to the pre-existing behavior.
+        const parkedMemo = new Map();
+        const checkParked = (id) => {
+            let probe = parkedMemo.get(id);
+            if (probe === undefined) {
+                probe = (async () => {
+                    try {
+                        const persistence = probeColdReader(ctx);
+                        if (persistence === undefined)
+                            return false;
+                        const { events } = await readColdLog(persistence, id);
+                        return isParkedOnUserInput(events);
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+                parkedMemo.set(id, probe);
+            }
+            return probe;
+        };
         const claim = (agent, record) => {
             const canaryPending = existsSync(stateFile(stateDir, 'restartRequested'));
             const text = restartContextText(record, canaryPending);
@@ -142,33 +225,77 @@ export function apply(ctx, config) {
         };
         // The single delivery path for every resume trigger (this plugin's pass,
         // the UI, the schedule system): an interrupted session gets exactly one
-        // "continue" injection; the restart's initiator gets the report — merged
-        // into one message when it is both. The map makes repeat calls no-ops.
+        // "continue" injection — unless its interrupted turn was parked on user
+        // input, in which case the card in the log is the continuation and no
+        // injection fires; the restart's initiator gets the report — merged into
+        // one message when it is both. The map makes repeat calls no-ops.
         const deliver = (agent) => {
+            // Transport can be up before the watchdog has exchanged the launch URL,
+            // handed it to the browser, or run the canary. Do not let that early
+            // mount wake a session; the release poll below retries live roots once
+            // the durable receipt reaches a terminal phase.
+            if (cutoverBlocksWake(stateDir))
+                return;
             const id = agent.id;
             const exitAt = pendingContinue.get(id);
-            const record = followupReport ? pendingRestartRecord(stateDir) : null;
-            if (exitAt !== undefined && record !== null
-                && (record.initiator === undefined || id === record.initiator)) {
-                // The initiator was itself interrupted by its own restart: one
-                // combined turn continues the work AND reports the outcome — two
-                // separate injections would run two near-duplicate turns.
-                const canaryPending = existsSync(stateFile(stateDir, 'restartRequested'));
-                const text = continueAndReportText(record, canaryPending);
-                if (text !== '') {
-                    agent.followup(pluginMessage(text));
-                    pendingContinue.delete(id);
-                    acknowledgeRestartRecord(stateDir, record, Date.now());
-                    return;
-                }
-                // A record with nothing to report yet (no exitAt/error) must not
-                // swallow the continue — fall through to the continue-only path.
+            let record = followupReport ? pendingRestartRecord(stateDir) : null;
+            // A bare PLANNED outcome with no initiating session (the restart was
+            // driven from outside the host — the operator's terminal already has
+            // the announcement) has no in-host owner: settle the record instead of
+            // waking whichever root session happens to mount first. Records
+            // carrying diagnostics someone must hear about — an unplanned
+            // recovery, a composition rollback, a failed restart — keep the
+            // first-created claim.
+            if (record !== null && record.initiator === undefined
+                && record.unexpected !== true && record.compositionRecovered !== true && record.error === undefined) {
+                acknowledgeRestartRecord(stateDir, record, Date.now());
+                record = null;
             }
+            const owesReport = record !== null && (record.initiator === undefined || id === record.initiator);
             if (exitAt !== undefined) {
-                agent.followup(pluginMessage(continueInterruptedText(exitAt)));
-                // Delete only after a successful injection: a throwing followup keeps
-                // the session eligible at its next creation (same rule as claim()).
-                pendingContinue.delete(id);
+                void (async () => {
+                    const parked = await checkParked(id);
+                    if (disposed || pendingContinue.get(id) !== exitAt)
+                        return;
+                    // Delete before injecting: two resume triggers racing the memoized
+                    // probe must not double-inject; a throwing followup re-arms the
+                    // session for its next creation (same rule as claim()).
+                    pendingContinue.delete(id);
+                    if (parked) {
+                        // Parked on user input: the card IS the continuation. An owed
+                        // report still lands (report-only text, not the merged one).
+                        if (owesReport && record !== null)
+                            claim(agent, record);
+                        return;
+                    }
+                    if (owesReport && record !== null) {
+                        // The initiator was itself interrupted by its own restart: one
+                        // combined turn continues the work AND reports the outcome — two
+                        // separate injections would run two near-duplicate turns.
+                        const canaryPending = existsSync(stateFile(stateDir, 'restartRequested'));
+                        const text = continueAndReportText(record, canaryPending);
+                        if (text !== '') {
+                            try {
+                                agent.followup(pluginMessage(text));
+                                acknowledgeRestartRecord(stateDir, record, Date.now());
+                                return;
+                            }
+                            catch {
+                                pendingContinue.set(id, exitAt);
+                                return;
+                            }
+                        }
+                        // A record with nothing to report yet (no exitAt/error) must not
+                        // swallow the continue — fall through to the continue-only path.
+                    }
+                    try {
+                        agent.followup(pluginMessage(continueInterruptedText(exitAt)));
+                    }
+                    catch {
+                        pendingContinue.set(id, exitAt);
+                    }
+                })();
+                return;
             }
             if (record === null)
                 return;
@@ -229,10 +356,13 @@ export function apply(ctx, config) {
                 agentOptions.model = selection.model;
             let setup;
             const presets = ctx.get('agentPresets');
-            const persistence = ctx.get('sessionPersistence');
+            const persistence = probeColdReader(ctx);
             if (presets !== undefined && persistence !== undefined) {
-                const inspected = await persistence.inspect(id);
-                const presetId = resolveSessionPreset({ header: inspected.meta, events: inspected.events });
+                const inspected = await readColdLog(persistence, id);
+                const presetId = deriveSessionPreset(agentPresetsHost, {
+                    header: inspected.meta,
+                    events: inspected.events,
+                });
                 setup = async (agentCtx) => { await presets.mount(agentCtx, (await presets.resolve(presetId)).id); };
             }
             return { resumeSessionId: id, agentOptions, ...(setup === undefined ? {} : { setup }) };
@@ -260,6 +390,11 @@ export function apply(ctx, config) {
         // happens through `deliver` below, from the `agent/created` listener or
         // the live branch here.
         const resumePass = async () => {
+            while (!disposed && cutoverBlocksWake(stateDir)) {
+                await new Promise(resolve => setTimeout(resolve, 250));
+            }
+            if (disposed)
+                return;
             const snapshot = readInterruptedSnapshot(stateDir);
             if (snapshot === null)
                 return;
@@ -269,6 +404,13 @@ export function apply(ctx, config) {
                 for (const id of [...new Set([...snapshot.resume, ...snapshot.interrupted])]) {
                     if (disposed)
                         return;
+                    // Parked on user input: the card in the log is the continuation —
+                    // do not recreate the agent at all (its creation would fire the
+                    // delivery path; deliver() also filters, belt and suspenders).
+                    if (await checkParked(id)) {
+                        pendingContinue.delete(id);
+                        continue;
+                    }
                     const live = ctx.agents.list().find(agent => agent.id === id);
                     if (live !== undefined) {
                         // Already live: its `agent/created` may have predated this plugin's
@@ -297,6 +439,19 @@ export function apply(ctx, config) {
             const timer = setTimeout(() => { void resumePass(); }, resumeDelayMs);
             ctx.effect(() => () => { clearTimeout(timer); });
         }
+        // The browser handoff can create an agent while the receipt still says
+        // canary-pending. agent/created is one-shot, so retry already-live roots
+        // after release; acknowledgement and pendingContinue preserve exact-once.
+        if (cutoverBlocksWake(stateDir)) {
+            const releaseTimer = setInterval(() => {
+                if (disposed || cutoverBlocksWake(stateDir))
+                    return;
+                clearInterval(releaseTimer);
+                for (const agent of ctx.agents.roots())
+                    deliver(agent);
+            }, 250);
+            ctx.effect(() => () => { clearInterval(releaseTimer); });
+        }
         ctx.on('agent/created', ({ agent }) => {
             if (!ctx.agents.roots().includes(agent))
                 return;
@@ -313,6 +468,8 @@ export function apply(ctx, config) {
             const record = pendingRestartRecord(stateDir);
             if (record === null)
                 return decision;
+            if (cutoverBlocksWake(stateDir))
+                return decision;
             const canaryPending = existsSync(stateFile(stateDir, 'restartRequested'));
             const text = restartContextText(record, canaryPending);
             if (text === '')
@@ -334,11 +491,13 @@ export function apply(ctx, config) {
         }, { prepend: true });
     }
     const service = {
-        verify: () => verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes),
+        verify: () => verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes, isWorkingTreeClean(repoDir)),
         record: (scope, options) => {
             const head = currentHead(repoDir);
             if (head === null)
                 throw new Error('ankh-guard: cannot record a credential outside a git repository');
+            if (!isWorkingTreeClean(repoDir))
+                throw new Error('ankh-guard: cannot record a credential while the working tree is dirty');
             return recordCredential(stateDir, { scope, revision: head, command: options?.command ?? '' }, Date.now());
         },
         clear: () => clearCredential(stateDir, Date.now()),
@@ -351,6 +510,7 @@ export function apply(ctx, config) {
             return result;
         },
         reset: sha => resetToCheckpoint(repoDir, sha),
+        requestRestart: request => requestRestart(request, { stateDir, repoDir }),
         canary: async (options) => {
             const checks = [];
             const verdict = service.verify();
@@ -378,16 +538,7 @@ export function apply(ctx, config) {
                 if (key.startsWith('DSH_') && value !== undefined)
                     env[key] = value;
             }
-            let port;
-            try {
-                const out = execFileSync('lsof', ['-a', '-p', String(process.pid), '-iTCP', '-sTCP:LISTEN', '-P'], { encoding: 'utf8', stdio: 'pipe' });
-                const match = /:(\d+) \(LISTEN\)/.exec(out);
-                if (match !== null)
-                    port = Number(match[1]);
-            }
-            catch {
-                // lsof unavailable or nothing listening yet — the record still helps.
-            }
+            const port = listeningPortsForPid(process.pid)[0];
             writeInstanceLaunch(stateDir, {
                 command: buildLaunchCommand(process.execPath, process.execArgv, process.argv.slice(1), process.cwd(), env),
                 source: 'instance',

package/lib/types/launch-spec.d.ts

@@ -0,0 +1,263 @@
+import type { TransitionReference } from './transition.ts';
+export type CutoverRecoveryPolicy = 'restore-previous' | 'wait-for-user';
+export type BrowserHandoffPolicy = 'required' | 'off';
+export type LaunchRole = 'target' | 'previous';
+export type CutoverControlAction = 'abort' | 'restore-previous';
+export type PreflightSurface = 'source' | 'built';
+/**
+ * Immutable execution binding for composition preflight. The runner and host
+ * installation are explicit because the guarded checkout and the successor's
+ * npm toolchain may be different module graphs.
+ */
+export interface LaunchPreflightSpec {
+    version: 1;
+    surface: PreflightSurface;
+    runnerExecutable: string;
+    runnerRuntimeArgs: string[];
+    runnerPath: string;
+    runnerSha256: string;
+    /** package.json used as createRequire()'s anchor for a built successor. */
+    installAnchor: string;
+    installAnchorSha256: string;
+    hostPackageVersion: string;
+    /** Full digest of the launch command this preflight contract approves. */
+    targetCommandSha256: string;
+    /** One-shot candidate command that validates the target CLI/argv contract. */
+    candidateProbeCommand?: string;
+    candidateProbeSha256?: string;
+    /** Guard binds and runs this caller assertion; it does not derive the probe. */
+    candidateProbeProvenance?: 'caller-supplied';
+}
+/** Everything needed to launch one supervised instance. The state directory is the transaction anchor. */
+export interface LaunchSpec {
+    version: 1;
+    command: string;
+    port: number;
+    home: string;
+    /** Repository whose HEAD is bound to the guard credential and rollback. */
+    credentialRepo: string;
+    /** dsh host checkout used by preflight and exported as DSH_HARNESS. */
+    harnessRoot: string;
+    profile: string;
+    /** Absent only on launch state written before execution binding existed. */
+    preflight?: LaunchPreflightSpec;
+}
+export interface StableLaunchState {
+    version: 1;
+    mode: 'stable';
+    active: LaunchSpec;
+}
+export interface CutoverLaunchState {
+    version: 1;
+    mode: 'cutover';
+    cutoverId: string;
+    selected: LaunchRole;
+    previous: LaunchSpec;
+    target: LaunchSpec;
+    /** Immutable, cutover-scoped filesystem transition prepared before takeover. */
+    transition?: TransitionReference;
+}
+export type LaunchState = StableLaunchState | CutoverLaunchState;
+export type CutoverPhase = 'prepared' | 'supervisor-starting' | 'supervisor-ready' | 'target-starting' | 'target-retrying' | 'restoring' | 'ready' | 'restored' | 'awaiting-user' | 'prepare-failed';
+export interface LaunchSpecSummary {
+    commandSha256: string;
+    port: number;
+    home: string;
+    credentialRepo: string;
+    harnessRoot: string;
+    profile: string;
+    preflight?: {
+        surface: PreflightSurface;
+        runnerExecutable: string;
+        runnerRuntimeArgs: string[];
+        runnerPath: string;
+        runnerSha256: string;
+        installAnchor: string;
+        installAnchorSha256: string;
+        hostPackageVersion: string;
+        targetCommandSha256: string;
+        candidateProbeSha256?: string;
+        candidateProbeProvenance?: 'caller-supplied';
+    };
+}
+export interface CutoverAttempt {
+    role: LaunchRole;
+    number: number;
+    childPid: number;
+    childStartToken?: string;
+    startedAt: number;
+    outcome?: 'failed' | 'ready';
+    detail?: string;
+}
+/** PID identity proof safe to persist in the redacted operational receipt. */
+export interface CutoverProcessOwnership {
+    childPid: number;
+    childStartToken: string;
+    listenerPid: number;
+    listenerStartToken: string;
+}
+export interface CutoverBrowserHandoff {
+    required: boolean;
+    status: 'pending' | 'acknowledged' | 'fallback-opened' | 'off' | 'failed' | 'not-required';
+    channel?: 'original-tab' | 'fallback-tab';
+    authentication?: 'existing-cookie' | 'launch-url';
+    authority?: string;
+    acknowledgedAt?: number;
+}
+export interface LaunchCutoverReceipt {
+    version: 1;
+    id: string;
+    phase: CutoverPhase;
+    preparedAt: number;
+    updatedAt: number;
+    initiator?: string;
+    previous: LaunchSpecSummary;
+    target: LaunchSpecSummary;
+    /** Redacted transition evidence; the plan paths live only in launch state. */
+    transition?: {
+        planSha256: string;
+        operationCount: number;
+        phase: 'pending' | 'applied' | 'rolled-back' | 'failed';
+        failureOperation?: 'apply' | 'rollback';
+        detail?: string;
+    };
+    supervisor: {
+        previousPid: number;
+        previousStartToken: string;
+        targetDriverPid?: number;
+        targetDriverStartToken?: string;
+        targetPid?: number;
+        targetStartToken?: string;
+        previousRetirement?: 'yielded' | 'identity-gone' | 'forced';
+    };
+    child: {
+        previousPid?: number;
+        targetPid?: number;
+        restoredPid?: number;
+    };
+    ownership: {
+        previous: CutoverProcessOwnership;
+        target?: CutoverProcessOwnership;
+        restored?: CutoverProcessOwnership;
+    };
+    readiness?: {
+        role: LaunchRole;
+        childPid: number;
+        listenerPid: number;
+        stableWindowMs: number;
+        retryCount: number;
+    };
+    authentication: {
+        transportStatus?: number;
+        launchUrlObserved?: boolean;
+        exchangeStatus?: number;
+        authenticatedStatus?: number;
+        /** Compatibility summary; detailed browser evidence lives in browserHandoff. */
+        browserHandoff: CutoverBrowserHandoff['status'];
+    };
+    /** Browser acknowledgement is independent of server transport/readiness/canary. */
+    browserHandoff: CutoverBrowserHandoff;
+    /** Candidate and composition checks completed before the previous host stopped. */
+    preflight?: {
+        surface: PreflightSurface;
+        runnerExecutable: string;
+        runnerRuntimeArgs: string[];
+        runnerPath: string;
+        runnerSha256: string;
+        installAnchor: string;
+        installAnchorSha256: string;
+        hostPackageVersion: string;
+        targetCommandSha256: string;
+        candidateProbeSha256: string;
+        candidateProbeProvenance: 'caller-supplied';
+        candidateProbe: 'pass';
+        composition: 'pass';
+    };
+    /** Target evidence is retained even if recovery later becomes terminal. */
+    targetValidation?: {
+        readiness?: LaunchCutoverReceipt['readiness'];
+        canary?: {
+            outcome: 'pass' | 'fail';
+            detail?: string;
+        };
+    };
+    canary?: {
+        outcome: 'pass' | 'fail';
+        detail?: string;
+    };
+    attempts: CutoverAttempt[];
+    failureCount: {
+        target: number;
+        previous: number;
+    };
+    recovery: {
+        policy: CutoverRecoveryPolicy;
+        result: 'pending' | 'not-needed' | 'restored' | 'waiting-for-user' | 'prepare-failed';
+        detail?: string;
+        validation?: {
+            readiness?: LaunchCutoverReceipt['readiness'];
+            canary?: {
+                outcome: 'pass' | 'fail' | 'skipped';
+                detail?: string;
+            };
+        };
+    };
+    events: Array<{
+        at: number;
+        kind: string;
+        detail?: string;
+    }>;
+}
+export interface CutoverControlRequest {
+    version: 1;
+    cutoverId: string;
+    action: CutoverControlAction;
+    requestedAt: number;
+}
+export declare function commandSha256(command: string): string;
+/** Read the selected launch state, or null for a deployment predating this protocol. */
+export declare function readLaunchState(stateDir: string): LaunchState | null;
+/** The exact spec a newly starting supervisor must honor. */
+export declare function selectedLaunchSpec(state: LaunchState): LaunchSpec;
+/** Persist an ordinary, non-transactional active spec. */
+export declare function writeStableLaunchSpec(stateDir: string, spec: LaunchSpec, ifAbsent?: boolean): boolean;
+export declare function summarizeLaunchSpec(spec: LaunchSpec): LaunchSpecSummary;
+/** Safe operator view: preserve topology and selection without printing commands. */
+export declare function summarizeLaunchState(state: LaunchState | null): unknown;
+/** Read the durable receipt, or null when absent/malformed. */
+export declare function readCutoverReceipt(stateDir: string): LaunchCutoverReceipt | null;
+/** Persist an operator control request for the current watchdog to consume. */
+export declare function writeCutoverControl(stateDir: string, cutoverId: string, action: CutoverControlAction, now: number): CutoverControlRequest;
+export declare function readCutoverControl(stateDir: string): CutoverControlRequest | null;
+export declare function clearCutoverControl(stateDir: string, cutoverId: string): void;
+/**
+ * Prepare one cutover. The receipt lands first; the single launch-state rename
+ * is the commit point selecting target. A crash before that rename leaves the
+ * previous stable state authoritative and the old supervisor untouched.
+ */
+export declare function prepareLaunchCutover(stateDir: string, input: {
+    id: string;
+    previous: LaunchSpec;
+    target: LaunchSpec;
+    recoveryPolicy: CutoverRecoveryPolicy;
+    browserHandoff: BrowserHandoffPolicy;
+    previousSupervisorPid: number;
+    previousSupervisorStartToken: string;
+    previousOwnership: CutoverProcessOwnership;
+    transition?: TransitionReference;
+    initiator?: string;
+    now: number;
+}): LaunchCutoverReceipt;
+/**
+ * Apply one watchdog event. Arguments are deliberately credential-free; the
+ * launch URL itself never crosses this boundary or lands in the receipt.
+ */
+export declare function recordCutoverEvent(stateDir: string, id: string, kind: string, args: readonly string[], now: number): LaunchCutoverReceipt;
+/** A restarted instance must not wake/report while the watchdog is still proving the cutover. */
+export declare function cutoverBlocksWake(stateDir: string): boolean;
+/** The active transaction's full specs plus its redacted policy receipt. */
+export declare function activeCutover(stateDir: string): {
+    state: CutoverLaunchState;
+    receipt: LaunchCutoverReceipt;
+} | null;
+//# sourceMappingURL=launch-spec.d.ts.map