@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

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

package/lib/types/git.js

@@ -4,6 +4,9 @@
  * are synchronous child-process invocations scoped to the repo directory.
  */
 import { execFileSync } from 'node:child_process';
+import { copyFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
 /**
  * The repository's current HEAD, or null when the directory is not inside a
  * git repository (or git itself is unavailable).
@@ -23,8 +26,27 @@ export function currentHead(repoDir) {
     }
 }
 /**
- * Commit the whole working tree as a checkpoint snapshot (empty commits
- * allowed — a clean tree still records a rollback point).
+ * Porcelain entries for every tracked or untracked working-tree change.
+ * `null` means git could not inspect the checkout; callers must fail closed.
+ */
+export function workingTreeChanges(repoDir) {
+    try {
+        const out = execFileSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], { cwd: repoDir, encoding: 'utf8', stdio: 'pipe' });
+        return out.split('\0').filter(entry => entry !== '');
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether the checkout has no staged, unstaged, or untracked changes. */
+export function isWorkingTreeClean(repoDir) {
+    const changes = workingTreeChanges(repoDir);
+    return changes !== null && changes.length === 0;
+}
+/**
+ * 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
@@ -32,22 +54,62 @@ export function currentHead(repoDir) {
  * SRC_ARTIFACT_PATTERN in defaults.ts; omit for none).
  * @returns the new HEAD sha, or a failure reason.
  */
-export function commitCheckpoint(repoDir, message, artifactPattern) {
+export function commitCheckpoint(repoDir, message, artifactPattern, includeDirty = false) {
+    let tempDir;
     try {
-        execFileSync('git', ['add', '-A'], { cwd: repoDir, stdio: 'pipe' });
-        const staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: repoDir, encoding: 'utf8' });
+        const changes = workingTreeChanges(repoDir);
+        if (changes === null)
+            return { ok: false, error: 'git checkpoint failed: working tree status is unavailable' };
+        if (changes.length > 0 && !includeDirty) {
+            const shown = changes.slice(0, 10).map(entry => `  ${entry}`).join('\n');
+            const more = changes.length > 10 ? `\n  … (${changes.length - 10} more)` : '';
+            return {
+                ok: false,
+                error: `checkpoint refused: working tree has ${changes.length} change(s); review them, then rerun with --include-dirty to commit the complete snapshot:\n${shown}${more}`,
+            };
+        }
+        const previousHead = currentHead(repoDir);
+        if (previousHead === null)
+            return { ok: false, error: 'git checkpoint failed: current HEAD is unavailable' };
+        if (changes.length === 0)
+            return { ok: true, sha: previousHead, artifacts: [], createdCommit: false };
+        const indexPathRaw = execFileSync('git', ['rev-parse', '--git-path', 'index'], { cwd: repoDir, encoding: 'utf8', stdio: 'pipe' }).trim();
+        const indexPath = resolve(repoDir, indexPathRaw);
+        tempDir = mkdtempSync(join(tmpdir(), 'ankh-guard-index-'));
+        const tempIndex = join(tempDir, 'index');
+        copyFileSync(indexPath, tempIndex);
+        const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
+        execFileSync('git', ['add', '-A'], { cwd: repoDir, env, stdio: 'pipe' });
+        const staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: repoDir, env, encoding: 'utf8' });
         const artifacts = artifactPattern === undefined
             ? []
             : staged.split('\n').filter(file => artifactPattern.test(file));
-        execFileSync('git', ['commit', '--allow-empty', '-m', message], { cwd: repoDir, stdio: 'pipe' });
+        execFileSync('git', ['commit', '-m', message], { cwd: repoDir, env, stdio: 'pipe' });
         const sha = currentHead(repoDir);
         if (sha === null)
             return { ok: false, error: 'checkpoint commit succeeded but HEAD became unreadable' };
-        return { ok: true, sha, artifacts };
+        try {
+            // The complete snapshot is now HEAD; make the real index match it. This
+            // is the successful-path equivalent of the old `git add -A && commit`,
+            // while the temporary index protected the failure path.
+            execFileSync('git', ['reset', '--mixed', 'HEAD'], { cwd: repoDir, stdio: 'pipe' });
+        }
+        catch (error) {
+            try {
+                execFileSync('git', ['update-ref', 'HEAD', previousHead, sha], { cwd: repoDir, stdio: 'pipe' });
+            }
+            catch { /* best effort */ }
+            return { ok: false, error: `checkpoint commit could not settle the real index: ${String(error)}` };
+        }
+        return { ok: true, sha, artifacts, createdCommit: true };
     }
     catch (error) {
         return { ok: false, error: `git checkpoint failed: ${String(error)}` };
     }
+    finally {
+        if (tempDir !== undefined)
+            rmSync(tempDir, { recursive: true, force: true });
+    }
 }
 /**
  * Roll the checkout back to a checkpoint commit WITHOUT losing work: the

package/lib/types/index.d.ts

@@ -18,7 +18,53 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type RestartRequest, type RestartRequestResult } from './restart-request.ts';
 import { type GuardState, type VerifyResult } from './state.ts';
+/**
+ * The slice of a persisted session the preset derivation reads. Structural
+ * rather than the rc host's `PresetBearingSession`: the 0.1.2 host deleted
+ * that type together with `resolveSessionPreset`.
+ */
+interface PersistedPresetSource {
+    header: {
+        agentPreset?: string | null;
+    };
+    events: readonly {
+        type: string;
+        data?: unknown;
+    }[];
+}
+/**
+ * The two preset-derivation surfaces a host may carry: the rc line exports
+ * `resolveSessionPreset`; the 0.1.2 line replaced it (and the
+ * `PresetBearingSession` type) with the `agentPresetProjectionDefinition`
+ * unit. Probed per call, never from a version string.
+ */
+export interface PresetDerivationSurface {
+    agentPresetProjectionDefinition?: {
+        init(header: {
+            agentPreset?: string | null;
+        }): string | null;
+        apply(state: string | null, event: {
+            type: string;
+            data?: unknown;
+        }): string | null;
+    };
+    resolveSessionPreset?: (session: PersistedPresetSource) => string | undefined;
+}
+/**
+ * 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 declare function deriveSessionPreset(host: PresetDerivationSurface, session: PersistedPresetSource): string | undefined;
 /** Plugin configuration. */
 export interface SelfRestartGuardConfig {
     /** Credential freshness window in minutes (default 10). */
@@ -75,6 +121,7 @@ export type CheckpointResult = {
     ok: true;
     sha: string;
     artifacts: string[];
+    createdCommit: boolean;
 } | {
     ok: false;
     error: string;
@@ -90,11 +137,13 @@ export interface SelfRestartGuard {
      */
     verify(): VerifyResult;
     /**
-     * Record a green credential for the current HEAD.
+     * Record an externally proven green credential for the current clean HEAD.
+     * This synchronous service is a trusted orchestrator seam; agent/CLI flows
+     * must use `record --run -- PROGRAM` so the guard observes the exit status.
      * @param scope - what passed, e.g. 'build+test'.
      * @param options - optional command that produced the green state.
      * @returns the persisted state including the new credential.
-     * @throws outside a git repository (no HEAD to bind to).
+     * @throws outside a git repository or while the checkout is dirty.
      */
     record(scope: string, options?: {
         command?: string;
@@ -110,7 +159,9 @@ export interface SelfRestartGuard {
      */
     status(): GuardState;
     /**
-     * Commit the whole tree as a pre-batch checkpoint and remember it.
+     * Remember the existing clean HEAD as a pre-batch checkpoint. Dirty trees
+     * are refused; the CLI's reviewed `--include-dirty` path is deliberately
+     * unavailable through this convenience service.
      * @param message - batch description; defaults to 'batch snapshot'.
      * @returns the checkpoint commit sha, or a failure reason.
      */
@@ -134,6 +185,17 @@ export interface SelfRestartGuard {
     canary(options?: {
         port?: number;
     }): Promise<CanaryResult>;
+    /**
+     * Trigger a guarded restart onto a new launch command (a UI-grade
+     * mode/profile switch). Dispatches on supervision: no live watchdog → the
+     * restart verb's stop→start→canary; supervised → reconfigure's transactional
+     * cutover (the only safe way to change the launch command under a live
+     * watchdog). The full gate chain applies — credential, composition
+     * preflight, marker/lock — and a refusal never stops the running instance.
+     * @param request - start: the successor launch command; profile: the dsh profile to preflight; initiator: the session id the restart report returns to (required — the UI caller knows the real session, never invent one).
+     * @returns the structured verdict; terminal hint text never crosses this seam.
+     */
+    requestRestart(request: RestartRequest): Promise<RestartRequestResult>;
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -150,4 +212,5 @@ export declare const inject: string[];
  * @param config - validated plugin config.
  */
 export declare function apply(ctx: Context, config: SelfRestartGuardConfig): void;
+export {};
 //# sourceMappingURL=index.d.ts.map