@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

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

package/lib/types/index.js

@@ -1,16 +1,47 @@
 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);
+}
 export const Config = z.object({
     maxAgeMinutes: z.natural().min(1).default(10),
     stateDir: z.string().default(''),
@@ -56,7 +87,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 }));
+        ctx.effect(() => skills.register({
+            name,
+            description,
+            content,
+            source: 'runtime',
+            provider: 'ankh-guard',
+        }));
         writeSkillRegistration(stateDir, { registered: true, at: Date.now() });
     }
     catch (error) {
@@ -119,6 +156,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 +167,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 = ctx.get('sessionPersistence');
+                        if (persistence === undefined)
+                            return false;
+                        const { events } = await persistence.inspect(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 +207,65 @@ 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.
-            }
+            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;
@@ -232,7 +329,7 @@ export function apply(ctx, config) {
             const persistence = ctx.get('sessionPersistence');
             if (presets !== undefined && persistence !== undefined) {
                 const inspected = await persistence.inspect(id);
-                const presetId = resolveSessionPreset({ header: inspected.meta, events: inspected.events });
+                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 +357,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 +371,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 +406,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 +435,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 +458,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 +477,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 +505,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',