@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/types/browser-handoff.js

@@ -0,0 +1,489 @@
+/**
+ * Browser handoff bridge for launch cutovers.
+ *
+ * Old authenticated pages register random per-tab capabilities while the
+ * previous process is still the proven listener. Only SHA-256 digests are
+ * durable. After the successor proves one stable listener and passes canary,
+ * every registered tab may ask the final process for either a plain reload
+ * (its cookie is still valid) or that process's authenticated URL. The URL
+ * exists only in the response object and the browser's location.replace call:
+ * it never enters a state file, receipt, or log.
+ *
+ * Alongside the cutover channel, a boot-generation channel covers ordinary
+ * restarts (unsupervised `restart`/`schedule-exit`, watchdog crash respawns):
+ * the serving process's own pid + start token is its boot id, a polling tab
+ * carries the boot id it last saw, and a stale id with no active cutover
+ * means the process it knew is gone — answer ready/reload. A cutover receipt
+ * always wins over the generation check: during a cutover the old tab's known
+ * id is already stale, and the receipt protocol owns the pacing.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { activeCutover, readCutoverReceipt } from "./launch-spec.js";
+import { processIdentity, processIdentityMatches } from "./processes.js";
+import { stateFile } from "./state-files.js";
+export const BROWSER_HANDOFF_ROUTE = '/_ankh-guard/browser-handoff';
+const CAPABILITY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const MAX_BODY_BYTES = 4096;
+const MAX_REGISTRATIONS = 64;
+const DEFAULT_LONG_POLL_MS = 25_000;
+const DEFAULT_LONG_POLL_INTERVAL_MS = 200;
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCapability(value) {
+    return typeof value === 'string' && CAPABILITY_PATTERN.test(value);
+}
+function capabilitySha256(capability) {
+    return createHash('sha256').update(capability).digest('hex');
+}
+function parseMessage(value) {
+    if (!isObject(value) || value.version !== 1)
+        return null;
+    if (value.operation === 'poll' && isCapability(value.capability)) {
+        // Opaque to the server; length-capped so a poll cannot carry bulk data.
+        const knownBootId = typeof value.knownBootId === 'string' && value.knownBootId.length <= 256
+            ? value.knownBootId
+            : undefined;
+        return { version: 1, operation: 'poll', capability: value.capability, ...(knownBootId === undefined ? {} : { knownBootId }) };
+    }
+    if (value.operation !== 'ack' || typeof value.cutoverId !== 'string' || value.cutoverId === '')
+        return null;
+    if (value.channel !== 'original-tab' && value.channel !== 'fallback-tab')
+        return null;
+    if (value.authentication !== 'existing-cookie' && value.authentication !== 'launch-url')
+        return null;
+    if (value.channel === 'original-tab' && !isCapability(value.capability))
+        return null;
+    return {
+        version: 1,
+        operation: 'ack',
+        cutoverId: value.cutoverId,
+        channel: value.channel,
+        authentication: value.authentication,
+        ...(typeof value.capability === 'string' ? { capability: value.capability } : {}),
+    };
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function createJsonOnce(file, value) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    try {
+        // Publishing a complete hard link is both atomic for readers and
+        // first-writer-wins across competing tabs/processes.
+        linkSync(tmp, file);
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
+function writeJsonAtomic(file, value) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    try {
+        renameSync(tmp, file);
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* rename already consumed the temporary file */ }
+    }
+}
+function validRegistration(value) {
+    return isObject(value) && typeof value.authority === 'string' && value.authority !== ''
+        && typeof value.capabilitySha256 === 'string' && /^[a-f0-9]{64}$/.test(value.capabilitySha256)
+        && typeof value.armedAt === 'number' && Number.isFinite(value.armedAt)
+        && (value.acknowledgedAt === undefined
+            || (typeof value.acknowledgedAt === 'number' && Number.isFinite(value.acknowledgedAt)));
+}
+export function readBrowserHandoffRequest(stateDir) {
+    const request = readJson(stateFile(stateDir, 'browserHandoffRequest'));
+    if (request?.version !== 2 || typeof request.cutoverId !== 'string'
+        || !Array.isArray(request.registrations) || request.registrations.length === 0
+        || request.registrations.length > MAX_REGISTRATIONS
+        || !request.registrations.every(validRegistration))
+        return null;
+    return request;
+}
+function registerBrowserTab(stateDir, cutoverId, registration) {
+    const existing = readBrowserHandoffRequest(stateDir);
+    const registrations = existing?.cutoverId === cutoverId ? [...existing.registrations] : [];
+    if (!registrations.some(item => item.authority === registration.authority
+        && item.capabilitySha256 === registration.capabilitySha256)) {
+        if (registrations.length >= MAX_REGISTRATIONS)
+            return null;
+        registrations.push(registration);
+    }
+    const request = { version: 2, cutoverId, registrations };
+    writeJsonAtomic(stateFile(stateDir, 'browserHandoffRequest'), request);
+    return request;
+}
+function registrationMatches(request, cutoverId, authority, digest) {
+    return request?.cutoverId === cutoverId && request.registrations.some(item => (item.authority === authority && item.capabilitySha256 === digest));
+}
+function matchingRegistration(request, cutoverId, authority, digest) {
+    if (request?.cutoverId !== cutoverId)
+        return undefined;
+    return request.registrations.find(item => (item.authority === authority && item.capabilitySha256 === digest));
+}
+function acknowledgeBrowserTab(stateDir, cutoverId, authority, digest, acknowledgedAt) {
+    const request = readBrowserHandoffRequest(stateDir);
+    const registration = matchingRegistration(request, cutoverId, authority, digest);
+    if (request === null || registration === undefined)
+        return false;
+    registration.acknowledgedAt = acknowledgedAt;
+    writeJsonAtomic(stateFile(stateDir, 'browserHandoffRequest'), request);
+    return true;
+}
+export function readBrowserHandoffAcknowledgement(stateDir) {
+    const ack = readJson(stateFile(stateDir, 'browserHandoffAck'));
+    if (ack?.version !== 1 || typeof ack.cutoverId !== 'string'
+        || (ack.role !== 'target' && ack.role !== 'previous')
+        || typeof ack.authority !== 'string' || ack.authority === ''
+        || !Number.isInteger(ack.listenerPid) || (ack.listenerPid ?? 0) <= 0
+        || typeof ack.listenerStartToken !== 'string' || ack.listenerStartToken === ''
+        || (ack.channel !== 'original-tab' && ack.channel !== 'fallback-tab')
+        || (ack.authentication !== 'existing-cookie' && ack.authentication !== 'launch-url')
+        || typeof ack.acknowledgedAt !== 'number')
+        return null;
+    return ack;
+}
+function authorityOf(req) {
+    const host = req.headers.host;
+    const origin = req.headers.origin;
+    if (typeof host !== 'string' || typeof origin !== 'string')
+        return null;
+    try {
+        const parsed = new URL(origin);
+        if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.host !== host || parsed.origin !== origin)
+            return null;
+        return { authority: parsed.host, origin: parsed.origin };
+    }
+    catch {
+        return null;
+    }
+}
+function ownershipMatches(ownership, pid, identityMatches) {
+    return ownership !== undefined && ownership.listenerPid === pid
+        && identityMatches({ pid, startToken: ownership.listenerStartToken });
+}
+function json(res, status, body) {
+    res.writeHead(status, {
+        'cache-control': 'no-store',
+        'content-type': 'application/json; charset=utf-8',
+        'referrer-policy': 'no-referrer',
+        'x-content-type-options': 'nosniff',
+    });
+    res.end(`${JSON.stringify(body)}\n`);
+}
+async function bodyOf(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('body too large');
+        chunks.push(bytes);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+function currentReadyOwnership(stateDir, pid, identityMatches) {
+    const receipt = readCutoverReceipt(stateDir);
+    if (receipt === null || receipt.phase === 'awaiting-user' || receipt.readiness?.retryCount !== 0)
+        return null;
+    const role = receipt.readiness.role;
+    const ownership = role === 'target' ? receipt.ownership.target : receipt.ownership.restored;
+    const canarySettled = role === 'target'
+        ? receipt.targetValidation?.canary?.outcome === 'pass'
+        : receipt.recovery.validation?.canary !== undefined;
+    if (!ownershipMatches(ownership, pid, identityMatches)
+        || !canarySettled
+        || receipt.readiness.listenerPid !== ownership.listenerPid
+        || receipt.readiness.childPid !== ownership.childPid)
+        return null;
+    return {
+        cutoverId: receipt.id,
+        role,
+        ownership,
+        protected: receipt.authentication.launchUrlObserved === true,
+    };
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function waitForPollState(ready, waitMs, intervalMs) {
+    if (ready() || waitMs <= 0)
+        return;
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+        await delay(Math.min(intervalMs, Math.max(1, deadline - Date.now())));
+        if (ready())
+            return;
+    }
+}
+function authenticationState(connection, req) {
+    if (connection?.requestRejection === undefined)
+        return 'legacy-public';
+    const rejection = connection.requestRejection(req);
+    if (rejection === undefined)
+        return 'authenticated';
+    return rejection === 403 ? 'forbidden' : 'unauthenticated';
+}
+/** Create the exact HTTP handler; dependencies are injectable for deterministic protocol tests. */
+export function createBrowserHandoffHandler(dependencies) {
+    const pid = dependencies.pid ?? process.pid;
+    const now = dependencies.now ?? Date.now;
+    const identityMatches = dependencies.identityMatches ?? processIdentityMatches;
+    const identityProvider = dependencies.identityProvider ?? processIdentity;
+    const longPollMs = dependencies.longPollMs ?? DEFAULT_LONG_POLL_MS;
+    const longPollIntervalMs = dependencies.longPollIntervalMs ?? DEFAULT_LONG_POLL_INTERVAL_MS;
+    // Cached: a process's boot id never changes over its lifetime, and the
+    // platform lookup (ps/python3) must not run per held poll.
+    let bootIdCache;
+    const thisBootId = () => {
+        if (bootIdCache === undefined) {
+            const identity = identityProvider(pid);
+            bootIdCache = identity === null ? null : `${String(identity.pid)}:${identity.startToken}`;
+        }
+        return bootIdCache ?? undefined;
+    };
+    return async (req, res) => {
+        const connection = dependencies.connectionProvider?.() ?? dependencies.connection;
+        if (req.method !== 'POST' || req.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json') {
+            json(res, 404, { state: 'unavailable' });
+            return;
+        }
+        const requestAuthority = authorityOf(req);
+        if (requestAuthority === null) {
+            json(res, 403, { state: 'forbidden' });
+            return;
+        }
+        let message;
+        try {
+            message = parseMessage(await bodyOf(req));
+        }
+        catch {
+            message = null;
+        }
+        if (message === null) {
+            json(res, 400, { state: 'invalid' });
+            return;
+        }
+        if (message.operation === 'poll') {
+            const digest = capabilitySha256(message.capability);
+            // The serving process's boot id rides every poll response so a tab can
+            // learn it. Computed once: a process's identity never changes while it
+            // lives. Unavailable identity (ps blocked) disables the generation
+            // channel — polls degrade to the pre-generation flow, like an old client.
+            const bootId = thisBootId();
+            const respond = (status, body) => {
+                json(res, status, bootId === undefined ? body : { ...body, bootId });
+            };
+            // Boot-generation channel: a stale known id with NO active cutover means
+            // the process this tab knew is gone (ordinary restart or crash respawn).
+            // Short-circuits before the held-poll wait — this process's boot id
+            // cannot change under it. During a cutover the receipt protocol owns the
+            // pacing: the old tab's known id is already stale, and answering here
+            // would race the registration/ack dance.
+            if (bootId !== undefined && message.knownBootId !== undefined && message.knownBootId !== bootId
+                && activeCutover(dependencies.stateDir) === null) {
+                respond(200, { state: 'ready', action: 'reload', authentication: 'existing-cookie' });
+                return;
+            }
+            const pollHasState = () => {
+                const active = activeCutover(dependencies.stateDir);
+                if (active !== null) {
+                    if (active.receipt.phase === 'awaiting-user'
+                        || active.receipt.browserHandoff.status === 'off')
+                        return true;
+                    if (ownershipMatches(active.receipt.ownership.previous, pid, identityMatches)) {
+                        return !registrationMatches(readBrowserHandoffRequest(dependencies.stateDir), active.receipt.id, requestAuthority.authority, digest);
+                    }
+                    return currentReadyOwnership(dependencies.stateDir, pid, identityMatches) !== null;
+                }
+                const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+                const registration = readBrowserHandoffRequest(dependencies.stateDir);
+                return ready !== null && matchingRegistration(registration, ready.cutoverId, requestAuthority.authority, digest)?.acknowledgedAt === undefined;
+            };
+            await waitForPollState(pollHasState, longPollMs, longPollIntervalMs);
+            const active = activeCutover(dependencies.stateDir);
+            const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+            const registration = readBrowserHandoffRequest(dependencies.stateDir);
+            const registered = ready === null ? undefined : matchingRegistration(registration, ready.cutoverId, requestAuthority.authority, digest);
+            if (registered?.acknowledgedAt !== undefined
+                || (active === null && (ready === null || registered === undefined))
+                || active?.receipt.phase === 'awaiting-user'
+                || active?.receipt.browserHandoff.status === 'off') {
+                respond(200, { state: 'idle' });
+                return;
+            }
+            const previous = active?.receipt.ownership.previous;
+            if (active !== null && ownershipMatches(previous, pid, identityMatches)) {
+                const oldAuthentication = authenticationState(connection, req);
+                if (oldAuthentication === 'unauthenticated' || oldAuthentication === 'forbidden') {
+                    json(res, 401, { state: 'unauthorized' });
+                    return;
+                }
+                const registration = {
+                    authority: requestAuthority.authority,
+                    capabilitySha256: digest,
+                    armedAt: now(),
+                };
+                const selected = registerBrowserTab(dependencies.stateDir, active.receipt.id, registration);
+                respond(200, registrationMatches(selected, active.receipt.id, requestAuthority.authority, digest)
+                    ? { state: 'waiting', cutoverId: active.receipt.id }
+                    : { state: 'standby', cutoverId: active.receipt.id });
+                return;
+            }
+            if (ready === null || (active !== null && ready.cutoverId !== active.receipt.id)
+                || !registrationMatches(registration, ready?.cutoverId ?? '', requestAuthority.authority, digest)) {
+                respond(200, active === null
+                    ? { state: 'idle' }
+                    : { state: 'waiting', cutoverId: active.receipt.id });
+                return;
+            }
+            // A protected listener may expose the route before its optional
+            // connection service settles. Do not misclassify that startup window as
+            // a public/valid-cookie host and strand the original tab on a bare 401.
+            if (ready.protected && connection?.requestRejection === undefined) {
+                respond(200, { state: 'waiting', cutoverId: ready.cutoverId });
+                return;
+            }
+            const cookieState = authenticationState(connection, req);
+            if (cookieState === 'forbidden') {
+                json(res, 403, { state: 'forbidden' });
+                return;
+            }
+            if (cookieState !== 'unauthenticated') {
+                respond(200, {
+                    state: 'ready', action: 'reload', cutoverId: ready.cutoverId,
+                    role: ready.role, authentication: 'existing-cookie',
+                });
+                return;
+            }
+            if (connection?.authenticatedUrl === undefined) {
+                respond(200, { state: 'waiting', cutoverId: ready.cutoverId });
+                return;
+            }
+            let launchUrl;
+            try {
+                launchUrl = connection.authenticatedUrl(requestAuthority.origin);
+            }
+            catch {
+                json(res, 500, { state: 'unavailable' });
+                return;
+            }
+            let safe = false;
+            try {
+                const parsed = new URL(launchUrl);
+                safe = parsed.origin === requestAuthority.origin && parsed.pathname === '/'
+                    && parsed.username === '' && parsed.password === '' && parsed.search !== '' && parsed.hash === '';
+            }
+            catch { /* unsafe provider output */ }
+            if (!safe) {
+                json(res, 500, { state: 'unavailable' });
+                return;
+            }
+            respond(200, {
+                state: 'ready', action: 'replace', cutoverId: ready.cutoverId,
+                role: ready.role, authentication: 'launch-url', launchUrl,
+            });
+            return;
+        }
+        const receipt = readCutoverReceipt(dependencies.stateDir);
+        if (receipt === null || receipt.id !== message.cutoverId) {
+            json(res, 409, { state: 'stale' });
+            return;
+        }
+        const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+        if (ready === null || ready.cutoverId !== message.cutoverId) {
+            json(res, 409, { state: 'waiting' });
+            return;
+        }
+        if (ready.protected && connection?.requestRejection === undefined) {
+            json(res, 409, { state: 'waiting' });
+            return;
+        }
+        const ackAuthentication = authenticationState(connection, req);
+        if (ackAuthentication === 'unauthenticated' || ackAuthentication === 'forbidden') {
+            json(res, ackAuthentication === 'forbidden' ? 403 : 401, {
+                state: ackAuthentication === 'forbidden' ? 'forbidden' : 'unauthorized',
+            });
+            return;
+        }
+        const acknowledgedAt = now();
+        if (message.channel === 'original-tab') {
+            const registration = readBrowserHandoffRequest(dependencies.stateDir);
+            if (message.capability === undefined || !registrationMatches(registration, message.cutoverId, requestAuthority.authority, capabilitySha256(message.capability))) {
+                json(res, 403, { state: 'forbidden' });
+                return;
+            }
+            if (!acknowledgeBrowserTab(dependencies.stateDir, message.cutoverId, requestAuthority.authority, capabilitySha256(message.capability), acknowledgedAt)) {
+                json(res, 409, { state: 'conflict' });
+                return;
+            }
+        }
+        const acknowledgement = {
+            version: 1,
+            cutoverId: message.cutoverId,
+            role: ready.role,
+            authority: requestAuthority.authority,
+            listenerPid: ready.ownership.listenerPid,
+            listenerStartToken: ready.ownership.listenerStartToken,
+            channel: message.channel,
+            authentication: message.authentication,
+            acknowledgedAt,
+        };
+        const ackFile = stateFile(dependencies.stateDir, 'browserHandoffAck');
+        if (!createJsonOnce(ackFile, acknowledgement)) {
+            const existing = readBrowserHandoffAcknowledgement(dependencies.stateDir);
+            if (existing?.cutoverId !== acknowledgement.cutoverId
+                || existing.listenerPid !== acknowledgement.listenerPid
+                || existing.listenerStartToken !== acknowledgement.listenerStartToken) {
+                json(res, 409, { state: 'conflict' });
+                return;
+            }
+        }
+        res.writeHead(204, { 'cache-control': 'no-store' });
+        res.end();
+    };
+}
+/** Register the optional Web-profile bridge; headless/TUI compositions simply never activate it. */
+export function registerBrowserHandoff(ctx, stateDir) {
+    ctx.inject(['webServer'], (webCtx) => {
+        const webServer = webCtx.get('webServer');
+        if (webServer === undefined)
+            return;
+        const handler = createBrowserHandoffHandler({
+            stateDir,
+            connectionProvider: () => webCtx.get('connection'),
+        });
+        webCtx.effect(() => webServer.register({ kind: 'exact', path: BROWSER_HANDOFF_ROUTE, handler }), 'ankh-guard: browser handoff route');
+    });
+}

package/lib/types/cli.d.ts

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
+import { type BrowserHandoffPolicy, type CutoverRecoveryPolicy, type LaunchPreflightSpec, type PreflightSurface } from './launch-spec.ts';
 /** Parsed CLI options; empty stateDir/repoDir mean "use defaults". */
 interface CliOptions {
     stateDir: string;
     repoDir: string;
+    harnessRoot: string;
     home: string;
     maxAgeMinutes: number;
     port: number | undefined;
     command: string | undefined;
+    run: boolean;
+    runArgv: string[] | undefined;
     message: string | undefined;
+    detail: string | undefined;
     start: string | undefined;
     pid: string | undefined;
     timeoutMs: number | undefined;
     delayMs: number | undefined;
     stopTimeoutMs: number | undefined;
+    supervisorYieldTimeoutMs: number | undefined;
     log: string | undefined;
     foreground: boolean;
     rollback: boolean;
@@ -21,6 +27,18 @@ interface CliOptions {
     initiator: string | undefined;
     profile: string | undefined;
     preflightTimeoutMs: number | undefined;
+    preflightSurface: PreflightSurface | undefined;
+    preflightRunner: string | undefined;
+    preflightInstallAnchor: string | undefined;
+    candidateProbeCommand: string | undefined;
+    onFailure: CutoverRecoveryPolicy | undefined;
+    browserHandoff: BrowserHandoffPolicy;
+    ifAbsent: boolean;
+    trustCommand: boolean;
+    includeDirty: boolean;
+    takeoverFrom: number | undefined;
+    cutoverId: string | undefined;
+    transitionFile: string | undefined;
 }
 /** stdout/stderr sink (injected so tests capture output). */
 export interface CliIo {
@@ -63,10 +81,11 @@ export declare const preflightInternals: {
 };
 /**
  * The harness checkout the live instance boots from (and the preflight
- * runner resolves the official published packages from): the `--repo` target
- * when given, else `DSH_HARNESS`, else the conventional default.
+ * runner resolves the official published packages from): the
+ * `--harness-root` target when given, else `DSH_HARNESS`, else the
+ * conventional default. Credential repositories never enter this resolver.
  */
-export declare function resolveHarnessRoot(optionRepoDir: string | undefined, env?: Record<string, string | undefined>): string;
+export declare function resolveHarnessRoot(optionHarnessRoot: string | undefined, env?: Record<string, string | undefined>): string;
 /**
  * The standalone preflight runner command (see preflight-runner.ts): executed
  * with the harness's own tsx so its dynamic imports resolve against the live
@@ -97,9 +116,10 @@ export interface PreflightOutcome {
  * @param profile - the dsh profile to dry-run.
  * @param timeoutMs - bound on the whole subprocess run; a timeout kills it.
  * @param harnessRoot - harness checkout for the runner (default: DSH_HARNESS / ~/code/deepseek-harness).
+ * @param home - dsh home the dry-run must read instead of ambient process state.
  * @returns the classified outcome.
  */
-export declare function runPreflightCheck(profile: string, timeoutMs: number, harnessRoot?: string): Promise<PreflightOutcome>;
+export declare function runPreflightCheck(profile: string, timeoutMs: number, harnessRoot?: string, home?: string, binding?: LaunchPreflightSpec): Promise<PreflightOutcome>;
 /**
  * The home the supervised instance boots with (the watchdog exports it as
  * DSH_HOME): the explicit flag first, then the environment — the same
@@ -108,6 +128,16 @@ export declare function runPreflightCheck(profile: string, timeoutMs: number, ha
  * loud rather than boot the instance on a home guessed from the state dir.
  */
 export declare function resolveWdHome(optionHome: string, env?: Record<string, string | undefined>): string | undefined;
+/**
+ * A machine-readable refusal verdict: which gate denied, plus a one-line
+ * reason. In-process callers (the selfRestartGuard.requestRestart service
+ * seam) read it back from the verdict file named by DSH_ANKH_VERDICT_FILE
+ * instead of scraping the human stderr text.
+ */
+export interface CliRefusal {
+    stage: string;
+    reason: string;
+}
 /**
  * Run one CLI invocation against the guard state.
  * @param argv - arguments after the subcommand name.