@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/types/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser half of the original-tab launch-cutover handoff, plus the
+ * boot-generation reload loop: polls carry the last-seen boot id, a stale id
+ * with no cutover in flight reloads the tab once, and a sustained disconnection
+ * (not a transient blip) raises a neutral overlay.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** No Cordis services are needed; this is a same-origin browser lifecycle observer. */
+export declare const inject: readonly string[];
+/** Deliberately discard query and fragment because either may hold credentials. */
+export declare function safeReturnPath(href: string, origin: string): string | undefined;
+export declare function fallbackCutoverId(hash: string): string | null;
+/** Install the polling/reload loop for this tab's lifetime. */
+export declare function apply(_ctx: ClientContext): () => void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,264 @@
+const ROUTE = '/_ankh-guard/browser-handoff';
+const CAPABILITY_KEY = 'ankh-guard.browser-handoff-capability.v1';
+const PENDING_KEY = 'ankh-guard.browser-handoff-pending.v1';
+const BOOT_ID_KEY = 'ankh-guard.browser-handoff-boot-id.v1';
+const FALLBACK_HASH_KEY = 'ankh-guard-handoff';
+const ACTIVE_RETRY_MS = 250;
+const ERROR_RETRY_MIN_MS = 1_000;
+const ERROR_RETRY_MAX_MS = 30_000;
+/** Sustained-failure threshold for the disconnected overlay; transient blips never show it. */
+const DISCONNECTED_OVERLAY_MS = 5_000;
+/** No Cordis services are needed; this is a same-origin browser lifecycle observer. */
+export const inject = [];
+function encodeBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+}
+function freshCapability() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return encodeBase64Url(bytes);
+}
+function capability() {
+    const existing = sessionStorage.getItem(CAPABILITY_KEY);
+    if (existing !== null && /^[A-Za-z0-9_-]{43}$/.test(existing))
+        return existing;
+    const created = freshCapability();
+    sessionStorage.setItem(CAPABILITY_KEY, created);
+    return created;
+}
+function readPending() {
+    try {
+        const value = JSON.parse(sessionStorage.getItem(PENDING_KEY) ?? 'null');
+        if (value?.version !== 1 || typeof value.cutoverId !== 'string'
+            || (value.channel !== 'original-tab' && value.channel !== 'fallback-tab')
+            || (value.authentication !== 'existing-cookie' && value.authentication !== 'launch-url'))
+            return null;
+        if (value.channel === 'original-tab' && typeof value.capability !== 'string')
+            return null;
+        if (value.returnPath !== undefined && !isSafeReturnPath(value.returnPath))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/** Deliberately discard query and fragment because either may hold credentials. */
+export function safeReturnPath(href, origin) {
+    try {
+        const url = new URL(href);
+        if (url.origin !== origin || url.pathname === '' || url.pathname.startsWith('//')
+            || url.pathname.includes('\\'))
+            return undefined;
+        return url.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSafeReturnPath(value) {
+    return typeof value === 'string' && value.startsWith('/') && !value.startsWith('//')
+        && !value.includes('\\') && !value.includes('?') && !value.includes('#');
+}
+function writePending(value) {
+    // Deliberately excludes launchUrl: bearer URLs never enter browser storage.
+    sessionStorage.setItem(PENDING_KEY, JSON.stringify(value));
+}
+export function fallbackCutoverId(hash) {
+    const params = new URLSearchParams(hash.startsWith('#') ? hash.slice(1) : hash);
+    const id = params.get(FALLBACK_HASH_KEY);
+    return id !== null && /^[A-Za-z0-9._-]{1,160}$/.test(id) ? id : null;
+}
+function consumeFallbackFragment() {
+    const cutoverId = fallbackCutoverId(location.hash);
+    if (cutoverId === null)
+        return null;
+    const url = new URL(location.href);
+    url.hash = '';
+    history.replaceState(history.state, '', url.href);
+    const pending = {
+        version: 1,
+        cutoverId,
+        channel: 'fallback-tab',
+        authentication: 'launch-url',
+    };
+    writePending(pending);
+    return pending;
+}
+function waitingOverlay(kind = 'restarting') {
+    const existing = document.getElementById('ankh-guard-browser-handoff');
+    if (existing !== null)
+        return existing;
+    const zh = navigator.language.toLowerCase().startsWith('zh');
+    const element = document.createElement('div');
+    element.id = 'ankh-guard-browser-handoff';
+    element.setAttribute('role', 'status');
+    element.setAttribute('aria-live', 'polite');
+    // 'disconnected' covers failures without a known restart in flight (a bare
+    // exit may never come back) — neutral copy, no auto-recovery promise.
+    element.textContent = kind === 'disconnected'
+        ? (zh ? '连接已断开,等待服务恢复。' : 'Connection lost; waiting for the service to recover.')
+        : (zh ? 'dsh 正在重启；此标签页会自动恢复。' : 'dsh is restarting; this tab will recover automatically.');
+    element.style.cssText = [
+        'position:fixed', 'inset:0', 'z-index:2147483647', 'display:grid', 'place-items:center',
+        'padding:24px', 'background:rgba(15,18,24,.92)', 'color:#fff',
+        'font:500 16px/1.5 system-ui,sans-serif', 'text-align:center',
+    ].join(';');
+    document.documentElement.append(element);
+    return element;
+}
+async function post(body) {
+    return fetch(ROUTE, {
+        method: 'POST',
+        credentials: 'same-origin',
+        cache: 'no-store',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+async function acknowledge(pending) {
+    const response = await post({
+        version: 1,
+        operation: 'ack',
+        cutoverId: pending.cutoverId,
+        channel: pending.channel,
+        authentication: pending.authentication,
+        ...(pending.capability !== undefined ? { capability: pending.capability } : {}),
+    });
+    return response.status === 204;
+}
+/** Install the polling/reload loop for this tab's lifetime. */
+export function apply(_ctx) {
+    let disposed = false;
+    let timer;
+    let pending = consumeFallbackFragment() ?? readPending();
+    let cap;
+    let errorRetryMs = ERROR_RETRY_MIN_MS;
+    let firstFailureAt;
+    // Fullscreen notice only for SUSTAINED disconnection (restart window, bare
+    // exit): transient network blips and the backoff cadence never trip it.
+    const noteDisconnected = () => {
+        firstFailureAt ??= Date.now();
+        if (Date.now() - firstFailureAt >= DISCONNECTED_OVERLAY_MS)
+            waitingOverlay('disconnected');
+    };
+    const schedule = (delayMs = 0) => {
+        if (!disposed)
+            timer = setTimeout(() => { void tick(); }, delayMs);
+    };
+    const tick = async () => {
+        if (disposed)
+            return;
+        try {
+            if (pending !== null) {
+                waitingOverlay();
+                if (await acknowledge(pending)) {
+                    const returnPath = pending.returnPath;
+                    const originalTab = pending.channel === 'original-tab';
+                    sessionStorage.removeItem(PENDING_KEY);
+                    sessionStorage.removeItem(CAPABILITY_KEY);
+                    document.getElementById('ankh-guard-browser-handoff')?.remove();
+                    pending = null;
+                    if (originalTab && returnPath !== undefined
+                        && safeReturnPath(location.href, location.origin) !== returnPath) {
+                        location.replace(returnPath);
+                        return;
+                    }
+                }
+                errorRetryMs = ERROR_RETRY_MIN_MS;
+                firstFailureAt = undefined;
+                schedule(ACTIVE_RETRY_MS);
+                return;
+            }
+            const tabCapability = cap ??= capability();
+            const knownBootId = sessionStorage.getItem(BOOT_ID_KEY);
+            const response = await post({
+                version: 1, operation: 'poll', capability: tabCapability,
+                ...(knownBootId === null ? {} : { knownBootId }),
+            });
+            if (!response.ok) {
+                noteDisconnected();
+                schedule(errorRetryMs);
+                errorRetryMs = Math.min(errorRetryMs * 2, ERROR_RETRY_MAX_MS);
+                return;
+            }
+            errorRetryMs = ERROR_RETRY_MIN_MS;
+            firstFailureAt = undefined;
+            const result = await response.json();
+            // Learn the serving boot id before acting on it — storing the successor's
+            // id ahead of the reload is what makes the generation check one-shot.
+            if (typeof result.bootId === 'string')
+                sessionStorage.setItem(BOOT_ID_KEY, result.bootId);
+            if (result.state === 'idle') {
+                document.getElementById('ankh-guard-browser-handoff')?.remove();
+                // The server holds idle polls, providing event-like wakeup without a
+                // permanent fixed-frequency request loop.
+                schedule();
+                return;
+            }
+            if (result.state === 'waiting')
+                waitingOverlay();
+            // Boot-generation reload (no cutoverId): the process this tab knew is
+            // gone. No registration/ack dance — the stored id already advanced.
+            if (result.state === 'ready' && result.action === 'reload' && typeof result.cutoverId !== 'string') {
+                location.reload();
+                return;
+            }
+            if (result.state !== 'ready' || typeof result.cutoverId !== 'string') {
+                schedule(ACTIVE_RETRY_MS);
+                return;
+            }
+            if (result.action === 'reload' && result.authentication === 'existing-cookie') {
+                const returnPath = safeReturnPath(location.href, location.origin);
+                const nextPending = {
+                    version: 1, cutoverId: result.cutoverId, channel: 'original-tab',
+                    authentication: 'existing-cookie', capability: tabCapability,
+                    ...(returnPath === undefined ? {} : { returnPath }),
+                };
+                pending = nextPending;
+                writePending(nextPending);
+                waitingOverlay();
+                location.reload();
+                return;
+            }
+            if (result.action === 'replace' && result.authentication === 'launch-url'
+                && typeof result.launchUrl === 'string') {
+                const launch = new URL(result.launchUrl);
+                if (launch.origin !== location.origin || launch.pathname !== '/' || launch.search === ''
+                    || launch.username !== '' || launch.password !== '' || launch.hash !== '') {
+                    schedule(ACTIVE_RETRY_MS);
+                    return;
+                }
+                const returnPath = safeReturnPath(location.href, location.origin);
+                const nextPending = {
+                    version: 1, cutoverId: result.cutoverId, channel: 'original-tab',
+                    authentication: 'launch-url', capability: tabCapability,
+                    ...(returnPath === undefined ? {} : { returnPath }),
+                };
+                pending = nextPending;
+                writePending(nextPending);
+                waitingOverlay();
+                // The bearer remains a local variable for the shortest possible time.
+                location.replace(launch.href);
+                return;
+            }
+        }
+        catch {
+            // The expected restart interval rejects fetches; keep the old page and retry.
+            noteDisconnected();
+            schedule(errorRetryMs);
+            errorRetryMs = Math.min(errorRetryMs * 2, ERROR_RETRY_MAX_MS);
+            return;
+        }
+        schedule(ACTIVE_RETRY_MS);
+    };
+    void tick();
+    return () => {
+        disposed = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+    };
+}

package/lib/types/deployment-proof.d.ts

@@ -0,0 +1,24 @@
+import { type LaunchSpec } from './launch-spec.ts';
+import { type ProvenDeployment, type VerifyResult } from './state.ts';
+export interface RestartAuthorization {
+    version: 1;
+    kind: 'fresh-credential' | 'proven-deployment';
+    revision: string;
+    evidenceSha256: string;
+}
+export interface RestartEvidenceResult extends VerifyResult {
+    authorization?: RestartAuthorization;
+}
+export declare function captureDeploymentFingerprint(spec: LaunchSpec): ProvenDeployment['fingerprint'];
+export declare function deploymentFingerprintSha256(fingerprint: ProvenDeployment['fingerprint']): string;
+export declare function verifyProvenDeployment(stateDir: string, spec: LaunchSpec): RestartEvidenceResult;
+/** Fresh evidence wins; an exact prior deployment is the same-launch fallback. */
+export declare function verifyRestartEvidence(stateDir: string, spec: LaunchSpec, maxAgeMinutes: number, now?: number): RestartEvidenceResult;
+/** Revalidate the exact evidence selected before the scheduled stop. */
+export declare function verifyRestartAuthorization(stateDir: string, spec: LaunchSpec, authorization: RestartAuthorization): RestartEvidenceResult;
+/**
+ * Promote a fresh credential after the boot's readiness/canary boundary. A
+ * proof-authorized pure restart retains the existing proof unchanged.
+ */
+export declare function proveCurrentDeployment(stateDir: string, spec: LaunchSpec, authorization: RestartAuthorization, now?: number): RestartEvidenceResult;
+//# sourceMappingURL=deployment-proof.d.ts.map

package/lib/types/deployment-proof.js

@@ -0,0 +1,314 @@
+/**
+ * Reusable evidence for a pure, same-launch restart.
+ *
+ * A green credential is deliberately short lived: it authorizes one stop
+ * close to the observed build/test run. Once that stop has completed
+ * readiness and canary, however, the exact deployed inputs are known-good.
+ * This module fingerprints those inputs so a later pure restart can reuse the
+ * expensive proof without turning "same git HEAD" into a weak proxy for
+ * "same deployment".
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync, } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { currentHead, isWorkingTreeClean } from "./git.js";
+import { commandSha256 } from "./launch-spec.js";
+import { loadState, setProvenDeployment, verifyCredential, } from "./state.js";
+const PROFILE_FILES = [
+    'cordis.patch.yml', 'cordis.yml', 'package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml',
+];
+const HOST_RUNTIME_FILES = [
+    'package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml',
+    'node_modules/.modules.yaml', 'node_modules/.pnpm-workspace-state-v1.json',
+];
+const SKIPPED_PACKAGE_DIRS = new Set(['.git', 'coverage', 'node_modules']);
+function hashChunk(hash, kind, logicalPath, value = '') {
+    hash.update(kind);
+    hash.update('\0');
+    hash.update(logicalPath);
+    hash.update('\0');
+    hash.update(value);
+    hash.update('\0');
+}
+/**
+ * Hash a runtime tree, following links so a linked package cannot drift
+ * outside the fingerprint. Real-directory de-duplication permits legal link
+ * cycles without recursion loops. Special/dangling/unreadable nodes fail
+ * closed.
+ */
+function hashRuntimePath(hash, absolutePath, logicalPath, seenDirectories, packageRoot = false) {
+    const info = lstatSync(absolutePath);
+    if (info.isSymbolicLink()) {
+        const targetText = readlinkSync(absolutePath);
+        hashChunk(hash, 'link', logicalPath, targetText);
+        let target;
+        try {
+            target = realpathSync(absolutePath);
+        }
+        catch (error) {
+            throw new Error(`deployment fingerprint refused dangling link ${logicalPath}: ${String(error)}`);
+        }
+        hashRuntimePath(hash, target, `${logicalPath}/@target`, seenDirectories, packageRoot);
+        return;
+    }
+    if (info.isFile()) {
+        hashChunk(hash, 'file', logicalPath, readFileSync(absolutePath));
+        return;
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`deployment fingerprint refused special file ${logicalPath}`);
+    }
+    const realDirectory = realpathSync(absolutePath);
+    if (seenDirectories.has(realDirectory)) {
+        hashChunk(hash, 'cycle', logicalPath);
+        return;
+    }
+    seenDirectories.add(realDirectory);
+    hashChunk(hash, 'dir', logicalPath);
+    for (const name of readdirSync(absolutePath).sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))) {
+        if (packageRoot && SKIPPED_PACKAGE_DIRS.has(name)) {
+            hashChunk(hash, 'excluded-dir', `${logicalPath}/${name}`);
+            continue;
+        }
+        hashRuntimePath(hash, join(absolutePath, name), `${logicalPath}/${name}`, seenDirectories, packageRoot);
+    }
+}
+function hashOptionalPath(hash, root, relativePath) {
+    const absolutePath = join(root, relativePath);
+    if (!existsSync(absolutePath)) {
+        hashChunk(hash, 'absent', relativePath);
+        return;
+    }
+    hashRuntimePath(hash, absolutePath, relativePath, new Set());
+}
+function dependencyInstallPath(profileDir, dependency) {
+    return join(profileDir, 'node_modules', ...dependency.split('/'));
+}
+function fileDependencyPath(profileDir, specifier) {
+    if (!specifier.startsWith('file:'))
+        return undefined;
+    const pathname = specifier.slice('file:'.length);
+    return isAbsolute(pathname) ? pathname : resolve(profileDir, pathname);
+}
+/** Hash profile inputs, installed direct packages, and file: source archives. */
+function profileRuntimeSha256(spec) {
+    const profileDir = join(spec.home, 'profiles', spec.profile);
+    const manifestPath = join(profileDir, 'package.json');
+    if (!existsSync(manifestPath))
+        throw new Error(`deployment fingerprint requires ${manifestPath}`);
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`deployment fingerprint could not parse profile package.json: ${String(error)}`);
+    }
+    const hash = createHash('sha256');
+    for (const file of PROFILE_FILES)
+        hashOptionalPath(hash, profileDir, file);
+    const dependencies = Object.entries(manifest.dependencies ?? {})
+        .sort(([left], [right]) => Buffer.from(left).compare(Buffer.from(right)));
+    for (const [name, source] of dependencies) {
+        const installed = dependencyInstallPath(profileDir, name);
+        if (!existsSync(installed))
+            throw new Error(`deployment fingerprint requires installed profile dependency ${name}`);
+        hashRuntimePath(hash, installed, `installed/${name}`, new Set(), true);
+        const archive = fileDependencyPath(profileDir, source);
+        if (archive !== undefined) {
+            if (!existsSync(archive))
+                throw new Error(`deployment fingerprint requires file dependency archive for ${name}`);
+            hashRuntimePath(hash, archive, `source-archive/${name}`, new Set());
+        }
+    }
+    return hash.digest('hex');
+}
+/**
+ * Hash the host install metadata and any explicitly bound built execution
+ * surface. Source surfaces are content-bound by the clean harness git tree.
+ */
+function hostRuntimeSha256(spec) {
+    const hash = createHash('sha256');
+    for (const file of HOST_RUNTIME_FILES)
+        hashOptionalPath(hash, spec.harnessRoot, file);
+    if (spec.preflight !== undefined) {
+        hashRuntimePath(hash, spec.preflight.runnerPath, 'preflight/runner', new Set());
+        hashRuntimePath(hash, spec.preflight.installAnchor, 'preflight/install-anchor', new Set());
+        if (spec.preflight.surface === 'built') {
+            hashRuntimePath(hash, dirname(spec.preflight.installAnchor), 'preflight/built-host-package', new Set(), true);
+        }
+    }
+    return hash.digest('hex');
+}
+function cleanRevision(root, role) {
+    const revision = currentHead(root);
+    if (revision === null)
+        throw new Error(`deployment fingerprint requires ${role} to be a git repository`);
+    if (!isWorkingTreeClean(root))
+        throw new Error(`deployment fingerprint requires a clean ${role}`);
+    return revision;
+}
+export function captureDeploymentFingerprint(spec) {
+    if (spec.preflight === undefined) {
+        throw new Error('deployment fingerprint requires an explicit source/built preflight execution binding');
+    }
+    if (spec.preflight.targetCommandSha256 !== commandSha256(spec.command)) {
+        throw new Error('deployment fingerprint refused a preflight binding for a different launch command');
+    }
+    if (fileSha256(spec.preflight.runnerPath) !== spec.preflight.runnerSha256) {
+        throw new Error('deployment fingerprint refused a changed preflight runner');
+    }
+    if (fileSha256(spec.preflight.installAnchor) !== spec.preflight.installAnchorSha256) {
+        throw new Error('deployment fingerprint refused a changed preflight install anchor');
+    }
+    const credentialRevision = cleanRevision(spec.credentialRepo, 'credential repository');
+    const harnessRevision = cleanRevision(spec.harnessRoot, 'harness root');
+    return {
+        version: 1,
+        credentialRevision,
+        harnessRevision,
+        launchSpecSha256: commandSha256(JSON.stringify(spec)),
+        profileSha256: profileRuntimeSha256(spec),
+        hostRuntimeSha256: hostRuntimeSha256(spec),
+    };
+}
+export function deploymentFingerprintSha256(fingerprint) {
+    return commandSha256(JSON.stringify(fingerprint));
+}
+function credentialCommandSha256(credential) {
+    return commandSha256(credential.command);
+}
+function fileSha256(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+function proofCredentialMatches(proof, credential) {
+    return credential !== undefined
+        && credential.revision === proof.credential.revision
+        && credential.recordedAt === proof.credential.recordedAt
+        && credential.scope === proof.credential.scope
+        && credentialCommandSha256(credential) === proof.credential.commandSha256;
+}
+export function verifyProvenDeployment(stateDir, spec) {
+    const state = loadState(stateDir);
+    const proof = state.provenDeployment;
+    if (proof === undefined)
+        return { ok: false, reason: 'no proven deployment recorded by a completed restart canary' };
+    if (!proofCredentialMatches(proof, state.credential)) {
+        return { ok: false, reason: 'proven deployment no longer matches the recorded build/test credential' };
+    }
+    let current;
+    try {
+        current = captureDeploymentFingerprint(spec);
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    const currentSha256 = deploymentFingerprintSha256(current);
+    if (currentSha256 !== proof.fingerprintSha256 || JSON.stringify(current) !== JSON.stringify(proof.fingerprint)) {
+        return {
+            ok: false,
+            reason: `proven deployment fingerprint changed (${proof.fingerprintSha256.slice(0, 16)} -> ${currentSha256.slice(0, 16)}) — rebuild, test, and record again`,
+        };
+    }
+    return {
+        ok: true,
+        reason: `proven deployment valid (${proof.credential.scope} @ ${proof.credential.revision}, fingerprint ${proof.fingerprintSha256.slice(0, 16)})`,
+        authorization: {
+            version: 1,
+            kind: 'proven-deployment',
+            revision: proof.credential.revision,
+            evidenceSha256: proof.fingerprintSha256,
+        },
+    };
+}
+/** Fresh evidence wins; an exact prior deployment is the same-launch fallback. */
+export function verifyRestartEvidence(stateDir, spec, maxAgeMinutes, now = Date.now()) {
+    const state = loadState(stateDir);
+    const credential = state.credential;
+    const fresh = verifyCredential(state, currentHead(spec.credentialRepo), now, maxAgeMinutes, isWorkingTreeClean(spec.credentialRepo));
+    if (fresh.ok && credential !== undefined) {
+        return {
+            ...fresh,
+            authorization: {
+                version: 1,
+                kind: 'fresh-credential',
+                revision: credential.revision,
+                evidenceSha256: credentialCommandSha256(credential),
+            },
+        };
+    }
+    const proven = verifyProvenDeployment(stateDir, spec);
+    if (proven.ok)
+        return proven;
+    return { ok: false, reason: `${fresh.reason}; pure-restart reuse unavailable: ${proven.reason}` };
+}
+/** Revalidate the exact evidence selected before the scheduled stop. */
+export function verifyRestartAuthorization(stateDir, spec, authorization) {
+    const state = loadState(stateDir);
+    if (authorization.kind === 'proven-deployment') {
+        const proven = verifyProvenDeployment(stateDir, spec);
+        if (!proven.ok || proven.authorization?.evidenceSha256 !== authorization.evidenceSha256) {
+            return { ok: false, reason: `scheduled proven-deployment authorization changed: ${proven.reason}` };
+        }
+        return proven;
+    }
+    const credential = state.credential;
+    if (credential === undefined
+        || credential.revision !== authorization.revision
+        || credentialCommandSha256(credential) !== authorization.evidenceSha256) {
+        return { ok: false, reason: 'scheduled credential authorization no longer matches durable state' };
+    }
+    if (currentHead(spec.credentialRepo) !== credential.revision || !isWorkingTreeClean(spec.credentialRepo)) {
+        return { ok: false, reason: 'scheduled credential authorization no longer matches a clean repository HEAD' };
+    }
+    return { ok: true, reason: `scheduled fresh credential still matches ${credential.revision}`, authorization };
+}
+/**
+ * Promote a fresh credential after the boot's readiness/canary boundary. A
+ * proof-authorized pure restart retains the existing proof unchanged.
+ */
+export function proveCurrentDeployment(stateDir, spec, authorization, now = Date.now()) {
+    const authorized = verifyRestartAuthorization(stateDir, spec, authorization);
+    if (!authorized.ok)
+        return authorized;
+    if (authorization.kind === 'proven-deployment') {
+        return { ...authorized, reason: `${authorized.reason}; existing deployment proof retained` };
+    }
+    const state = loadState(stateDir);
+    const credential = state.credential;
+    if (credential === undefined)
+        return { ok: false, reason: 'credential disappeared before deployment proof was recorded' };
+    let fingerprint;
+    try {
+        fingerprint = captureDeploymentFingerprint(spec);
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    if (fingerprint.credentialRevision !== credential.revision) {
+        return { ok: false, reason: 'deployment fingerprint revision differs from the credential revision' };
+    }
+    const fingerprintSha256 = deploymentFingerprintSha256(fingerprint);
+    const proof = {
+        version: 1,
+        provenAt: now,
+        credential: {
+            revision: credential.revision,
+            recordedAt: credential.recordedAt,
+            scope: credential.scope,
+            commandSha256: credentialCommandSha256(credential),
+        },
+        fingerprint,
+        fingerprintSha256,
+    };
+    setProvenDeployment(stateDir, proof, now);
+    return {
+        ok: true,
+        reason: `recorded proven deployment ${fingerprintSha256.slice(0, 16)} for ${credential.revision}`,
+        authorization: {
+            version: 1,
+            kind: 'proven-deployment',
+            revision: credential.revision,
+            evidenceSha256: fingerprintSha256,
+        },
+    };
+}

package/lib/types/exit-agent.js

@@ -15,6 +15,7 @@
 import { writeFileSync } from 'node:fs';
 import { isDirectInvocation } from "./defaults.js";
 import { findPidOnPort } from "./processes.js";
+import { registerCurrentTestProcess } from "./test-seam.js";
 /**
  * One exit attempt: SIGTERM the listener on {@link port} and record the
  * outcome. Extracted from the timer so tests can drive it directly.
@@ -49,5 +50,6 @@ export function exitAgentMain(env = process.env) {
 }
 // Direct invocation only: imported (tests, bundling) it must never fire.
 if (isDirectInvocation(import.meta.url)) {
+    registerCurrentTestProcess();
     exitAgentMain();
 }

package/lib/types/git.d.ts

@@ -5,18 +5,27 @@
  * @returns the full HEAD sha, or null.
  */
 export declare function currentHead(repoDir: string): string | null;
+/**
+ * Porcelain entries for every tracked or untracked working-tree change.
+ * `null` means git could not inspect the checkout; callers must fail closed.
+ */
+export declare function workingTreeChanges(repoDir: string): string[] | null;
+/** Whether the checkout has no staged, unstaged, or untracked changes. */
+export declare function isWorkingTreeClean(repoDir: string): boolean;
 /** Result of a checkpoint commit. */
 export type CheckpointCommitResult = {
     ok: true;
     sha: string;
     artifacts: string[];
+    createdCommit: boolean;
 } | {
     ok: false;
     error: string;
 };
 /**
- * Commit the whole working tree as a checkpoint snapshot (empty commits
- * allowed — a clean tree still records a rollback point).
+ * Record a clean HEAD directly, or commit the whole dirty working tree as an
+ * explicitly approved checkpoint snapshot. Dirty commits use a temporary git
+ * index: a hook/commit failure leaves the caller's real index untouched.
  * @param repoDir - repository directory.
  * @param message - checkpoint commit message.
  * @param artifactPattern - staged paths matching this are reported as
@@ -24,7 +33,7 @@ export type CheckpointCommitResult = {
  * SRC_ARTIFACT_PATTERN in defaults.ts; omit for none).
  * @returns the new HEAD sha, or a failure reason.
  */
-export declare function commitCheckpoint(repoDir: string, message: string, artifactPattern?: RegExp): CheckpointCommitResult;
+export declare function commitCheckpoint(repoDir: string, message: string, artifactPattern?: RegExp, includeDirty?: boolean): CheckpointCommitResult;
 /**
  * Roll the checkout back to a checkpoint commit WITHOUT losing work: the
  * discarded HEAD becomes a `guard-backup-*` branch, and uncommitted tracked