@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/types/processes.js

@@ -5,17 +5,190 @@
  * caller goes through here.
  */
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+function executable(name, candidates) {
+    return candidates.find(candidate => existsSync(candidate)) ?? name;
+}
+// dsh tool sessions intentionally carry a narrow PATH on macOS. Never turn a
+// missing /usr/sbin entry into "no listener"; use the platform's canonical
+// absolute paths first and retain PATH lookup only as a portable fallback.
+const LSOF = executable('lsof', ['/usr/sbin/lsof', '/usr/bin/lsof']);
+const PS = executable('ps', ['/bin/ps', '/usr/bin/ps']);
+const PGREP = executable('pgrep', ['/usr/bin/pgrep', '/bin/pgrep']);
+const SYSCTL = executable('sysctl', ['/usr/sbin/sysctl', '/sbin/sysctl']);
+const PYTHON = executable('python3', ['/usr/bin/python3', '/opt/homebrew/bin/python3']);
+const DARWIN_START_TOKEN = [
+    'import ctypes,struct,sys',
+    'p=int(sys.argv[1])',
+    'b=ctypes.create_string_buffer(136)',
+    'n=ctypes.CDLL("/usr/lib/libproc.dylib").proc_pidinfo(p,3,0,b,136)',
+    'n == 136 or sys.exit(1)',
+    's,u=struct.unpack_from("QQ",b.raw,120)',
+    'print(f"darwin:{s}:{u}",end="")',
+].join(';');
+/** Every process listening on a TCP port. An empty list also covers unavailable lsof. */
+export function findPidsOnPort(port) {
+    try {
+        const out = execFileSync(LSOF, [`-tiTCP:${port}`, '-sTCP:LISTEN', '-P'], { encoding: 'utf8', stdio: 'pipe' }).trim();
+        return [...new Set(out.split('\n').map(Number).filter(pid => Number.isInteger(pid) && pid > 0))];
+    }
+    catch {
+        return [];
+    }
+}
+/** TCP listen ports owned directly by one PID, using the same absolute lsof resolution. */
+export function listeningPortsForPid(pid) {
+    try {
+        const out = execFileSync(LSOF, ['-nP', '-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN'], { encoding: 'utf8', stdio: 'pipe' });
+        return [...new Set([...out.matchAll(/:(\d+) \(LISTEN\)/g)].map(match => Number(match[1])).filter(Number.isInteger))];
+    }
+    catch {
+        return [];
+    }
+}
 /** The first process listening on a TCP port, or null when none is (via lsof). */
 export function findPidOnPort(port) {
+    return findPidsOnPort(port)[0]?.toString() ?? null;
+}
+/**
+ * Current identity for a live process, or null when it cannot be proved.
+ * Linux exposes a boot-scoped kernel start tick. Other POSIX hosts do not,
+ * so bind the start instant to the boot, uid, session, and settled command.
+ * This materially strengthens macOS ps(1)'s second-granularity lstart; all
+ * guard captures occur after the watchdog/child has reached its steady argv.
+ */
+export function processIdentity(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const status = execFileSync(PS, ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', stdio: 'pipe' }).trim();
+        if (status === '' || status.startsWith('Z'))
+            return null;
+        if (process.platform === 'darwin') {
+            try {
+                const nativeStart = execFileSync(PYTHON, ['-c', DARWIN_START_TOKEN, String(pid)], {
+                    encoding: 'utf8', stdio: 'pipe',
+                }).trim();
+                if (/^darwin:\d+:\d+$/.test(nativeStart))
+                    return { pid, startToken: nativeStart };
+            }
+            catch {
+                // Minimal macOS installations can lack python3; use the strengthened
+                // ps evidence below rather than silently dropping identity checks.
+            }
+        }
+        const procStat = `/proc/${pid}/stat`;
+        if (existsSync(procStat)) {
+            const stat = readFileSync(procStat, 'utf8');
+            const commandEnd = stat.lastIndexOf(')');
+            const fields = commandEnd < 0 ? [] : stat.slice(commandEnd + 1).trim().split(/\s+/);
+            const startTicks = fields[19];
+            if (startTicks === undefined || startTicks === '')
+                return null;
+            let bootId = 'unknown-boot';
+            try {
+                bootId = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() || bootId;
+            }
+            catch { /* optional */ }
+            return { pid, startToken: `linux:${bootId}:${startTicks}` };
+        }
+        const processEvidence = execFileSync(PS, ['-o', 'sess=', '-o', 'uid=', '-o', 'lstart=', '-o', 'command=', '-p', String(pid)], {
+            encoding: 'utf8', stdio: 'pipe',
+        }).trim();
+        if (processEvidence === '')
+            return null;
+        let bootEvidence = 'unknown-boot';
+        try {
+            bootEvidence = execFileSync(SYSCTL, ['-n', 'kern.boottime'], {
+                encoding: 'utf8', stdio: 'pipe',
+            }).trim() || bootEvidence;
+        }
+        catch {
+            // The start instant + uid/session remains a portable fallback.
+        }
+        const startToken = `posix:${createHash('sha256').update(bootEvidence).update('\0').update(processEvidence).digest('hex')}`;
+        return { pid, startToken };
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether the same, non-recycled process is still alive. */
+export function processIdentityMatches(identity) {
+    return processIdentity(identity.pid)?.startToken === identity.startToken;
+}
+function parentPid(pid) {
+    try {
+        const value = Number(execFileSync(PS, ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8', stdio: 'pipe' }).trim());
+        return Number.isInteger(value) && value > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The live POSIX process-group id for one PID, or null when unavailable. */
+export function processGroupId(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
     try {
-        const out = execFileSync('lsof', [`-tiTCP:${port}`, '-sTCP:LISTEN', '-P'], { encoding: 'utf8', stdio: 'pipe' }).trim();
-        const first = out.split('\n')[0];
-        return first !== undefined && first !== '' ? first : null;
+        const value = Number(execFileSync(PS, ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8', stdio: 'pipe' }).trim());
+        return Number.isInteger(value) && value > 0 ? value : null;
     }
     catch {
         return null;
     }
 }
+/** Whether candidate is root itself or a live descendant of root. */
+export function pidBelongsToTree(root, candidate) {
+    let cursor = candidate;
+    const seen = new Set();
+    while (cursor > 0 && !seen.has(cursor)) {
+        if (cursor === root)
+            return true;
+        seen.add(cursor);
+        const parent = parentPid(cursor);
+        if (parent === null)
+            return false;
+        cursor = parent;
+    }
+    return false;
+}
+/**
+ * Prove that exactly one port listener belongs to a supervisor and return the
+ * direct child root through which that supervisor owns it. This is captured
+ * before cutover; the successor must stop this identity, never an arbitrary
+ * process discovered later from the shared port.
+ */
+export function findOwnedListener(port, supervisorPid) {
+    const listeners = findPidsOnPort(port);
+    if (listeners.length !== 1)
+        return null;
+    const listenerPid = listeners[0];
+    if (listenerPid === undefined)
+        return null;
+    const listener = processIdentity(listenerPid);
+    if (listener === null)
+        return null;
+    let cursor = listenerPid;
+    let childRoot = null;
+    const seen = new Set();
+    while (cursor > 0 && !seen.has(cursor)) {
+        seen.add(cursor);
+        const parent = parentPid(cursor);
+        if (parent === supervisorPid) {
+            childRoot = cursor;
+            break;
+        }
+        if (parent === null)
+            return null;
+        cursor = parent;
+    }
+    if (childRoot === null)
+        return null;
+    const child = processIdentity(childRoot);
+    return child === null ? null : { child, listener };
+}
 /** POSIX single-quote one word for a shell command line. */
 function shellQuote(word) {
     return `'${word.replace(/'/g, "'\\''")}'`;
@@ -34,7 +207,7 @@ export function discoverLaunchCommand(pid) {
     let argv;
     let cwd;
     try {
-        argv = execFileSync('ps', ['-o', 'command=', '-p', pid], { encoding: 'utf8', stdio: 'pipe' }).trim();
+        argv = execFileSync(PS, ['-o', 'command=', '-p', pid], { encoding: 'utf8', stdio: 'pipe' }).trim();
         if (argv === '')
             return null;
     }
@@ -42,7 +215,7 @@ export function discoverLaunchCommand(pid) {
         throw new Error(`ps unavailable: ${String(error)}`);
     }
     try {
-        const out = execFileSync('lsof', ['-a', '-p', pid, '-d', 'cwd', '-Fn'], { encoding: 'utf8', stdio: 'pipe' });
+        const out = execFileSync(LSOF, ['-a', '-p', pid, '-d', 'cwd', '-Fn'], { encoding: 'utf8', stdio: 'pipe' });
         const match = /^n(.+)$/m.exec(out);
         if (match === null)
             return null;
@@ -54,7 +227,7 @@ export function discoverLaunchCommand(pid) {
     const TRANSIENT = new Set(['DSH_ANKH_RESTART_DRIVER', 'DSH_SESSION_ID', 'DSH_SESSION_JSONL', 'DSH_WEB_URL', 'DSH_SHELL']);
     const env = {};
     try {
-        const out = execFileSync('ps', ['eww', '-o', 'command', '-p', pid], { encoding: 'utf8', stdio: 'pipe' });
+        const out = execFileSync(PS, ['eww', '-o', 'command', '-p', pid], { encoding: 'utf8', stdio: 'pipe' });
         for (const token of out.split(/\s+/)) {
             const eq = token.indexOf('=');
             if (eq > 0 && token.slice(0, eq).startsWith('DSH_') && !TRANSIENT.has(token.slice(0, eq)))
@@ -76,10 +249,11 @@ export function discoverLaunchCommand(pid) {
  * setsid'd — so the sweep walks `pgrep -P` instead. `pgrep` missing or
  * returning nothing is fine: the pid itself still gets the signal.
  */
-export function killPidTree(pid, signal) {
+function signalFrozenTree(pid, signal) {
+    let safe = true;
     let children = [];
     try {
-        const out = execFileSync('pgrep', ['-P', String(pid)], { encoding: 'utf8', stdio: 'pipe' }).trim();
+        const out = execFileSync(PGREP, ['-P', String(pid)], { encoding: 'utf8', stdio: 'pipe' }).trim();
         children = out === '' ? [] : out.split('\n');
     }
     catch {
@@ -87,13 +261,65 @@ export function killPidTree(pid, signal) {
     }
     for (const raw of children) {
         const child = Number(raw);
-        if (Number.isInteger(child) && child > 0)
-            killPidTree(child, signal);
+        if (!Number.isInteger(child) || child <= 0)
+            continue;
+        try {
+            process.kill(child, 'SIGSTOP');
+        }
+        catch {
+            continue;
+        }
+        // pgrep and SIGSTOP are separate syscalls. Verify the frozen PID is still
+        // this frozen parent's child before recursively signalling it; if not,
+        // resume the unrelated process and refuse to claim a complete sweep.
+        if (parentPid(child) !== pid) {
+            safe = false;
+            try {
+                process.kill(child, 'SIGCONT');
+            }
+            catch { /* already gone */ }
+            continue;
+        }
+        safe = signalFrozenTree(child, signal) && safe;
     }
     try {
         process.kill(pid, signal);
+        if (signal !== 'SIGKILL')
+            process.kill(pid, 'SIGCONT');
     }
     catch {
         // already gone
     }
+    return safe;
+}
+/**
+ * Freeze, then revalidate, then signal an authorized process identity. A
+ * mismatch resumes the PID without delivering the requested signal.
+ */
+export function signalProcessIdentity(identity, signal) {
+    try {
+        process.kill(identity.pid, 'SIGSTOP');
+    }
+    catch {
+        return 'gone';
+    }
+    if (!processIdentityMatches(identity)) {
+        try {
+            process.kill(identity.pid, 'SIGCONT');
+        }
+        catch { /* already gone */ }
+        return 'mismatch';
+    }
+    return signalFrozenTree(identity.pid, signal) ? 'signalled' : 'mismatch';
+}
+export function killPidTree(pid, signal) {
+    try {
+        // Freeze before enumeration so a wrapper cannot exit and orphan its
+        // listener to PID 1 between pgrep and delivery of the requested signal.
+        process.kill(pid, 'SIGSTOP');
+    }
+    catch {
+        return; // already gone
+    }
+    signalFrozenTree(pid, signal);
 }

package/lib/types/restart-context.d.ts

@@ -10,6 +10,19 @@ export interface RestartRecord {
      * guard) — written on the respawn so the recovery is reported, not silent.
      */
     unexpected?: boolean;
+    /**
+     * The watchdog recovered repeated boot failures by restoring the last
+     * healthy profile composition (the newest plugin change was unmounted).
+     */
+    compositionRecovered?: boolean;
+    /** What the composition rollback changed (the unmounted rows), for the report. */
+    detail?: string;
+    /** Durable launch-configuration cutover outcome and receipt location. */
+    cutover?: {
+        id: string;
+        outcome: 'target-ready' | 'restored' | 'awaiting-user' | 'prepare-failed';
+        receipt: string;
+    };
     reportedAt?: number;
 }
 /**
@@ -126,6 +139,25 @@ export interface InstanceLaunch {
     /** Epoch milliseconds when recorded. */
     recordedAt: number;
 }
+/**
+ * Record a composition rollback recovery: repeated boot failures whose
+ * subject lived outside the checkout (a freshly installed plugin is the
+ * common case) were recovered by restoring the last healthy profile
+ * composition. The service is UP again minus the newest plugin change — the
+ * recovery must be reported, never silent.
+ *
+ * Pending-record policy: a pending record with real diagnostics (error /
+ * unexpected) is kept; a BARE exit outcome (exitAt/pid only) is merged over —
+ * the watchdog knows the boot actually failed and recovered, so its record is
+ * the truthful one, and it inherits the exit record's initiator so the report
+ * still reaches its owner.
+ * @param stateDir - state directory.
+ * @param now - epoch milliseconds of the recovery boot.
+ * @param detail - what changed in the rolled-back composition (e.g. the
+ * unmounted bundle rows), for the report text.
+ * @returns whether the record was written.
+ */
+export declare function writeCompositionRecovery(stateDir: string, now: number, detail?: string): boolean;
 /**
  * Persist the launch record (atomic). The instance-facing side of
  * {@link writeInstanceLaunch}: only an `instance`-sourced record may be
@@ -187,4 +219,22 @@ export declare function writeSkillRegistration(stateDir: string, record: SkillRe
  * @returns the record, or null.
  */
 export declare function readSkillRegistration(stateDir: string): SkillRegistrationRecord | null;
+/** Minimal log-event view this helper reads (the session-persistence event shape). */
+interface ParkedProbeEvent {
+    type: string;
+    seq?: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Whether the session's last turn ended PARKED on user input: interrupted
+ * while waiting on an open `ask_user_question` call, or on an approval
+ * (`approval/asked` with no `approval/decided` in the same turn / after the
+ * turn's start). A parked turn has no interrupted WORK — the card persists in
+ * the log and the user answers whenever — so the restart resume must leave
+ * such sessions alone (no resume, no continue injection, no replayed card).
+ * @param events - the session's durable events (crash-repair already applied).
+ * @returns whether the last interrupted turn was parked on user input.
+ */
+export declare function isParkedOnUserInput(events: readonly ParkedProbeEvent[]): boolean;
+export {};
 //# sourceMappingURL=restart-context.d.ts.map

package/lib/types/restart-context.js

@@ -50,6 +50,22 @@ export function restartContextText(record, canaryPending) {
     if (record.exitAt === undefined && record.error === undefined)
         return '';
     const time = record.exitAt !== undefined ? new Date(record.exitAt).toISOString() : '未知时间';
+    if (record.cutover !== undefined) {
+        if (record.cutover.outcome === 'target-ready') {
+            return `[ankh-guard] 服务于 ${time} 完成启动配置切换；新 supervisor 与 child 已接管，应用就绪证明（受保护宿主需要时包含认证交接）和金丝雀均通过。耐久回执：${record.cutover.receipt}。请读取回执中的 PID、配置摘要、认证、重试与恢复字段，并向用户生成最终报告。`;
+        }
+        if (record.cutover.outcome === 'restored') {
+            return `[ankh-guard] 服务于 ${time} 尝试切换启动配置失败，但已按重启前批准的策略恢复上一份完整启动配置并重新就绪。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告失败、重试和恢复结果。`;
+        }
+        if (record.cutover.outcome === 'awaiting-user') {
+            return `[ankh-guard] 服务于 ${time} 切换启动配置失败；批准的策略是停留等待用户，watchdog 未擅自重置仓库。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告当前等待点。`;
+        }
+        return `[ankh-guard] 启动配置切换在停止旧实例前失败，上一份启动配置仍有效。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告准备阶段失败。`;
+    }
+    if (record.compositionRecovered === true) {
+        const what = record.detail !== undefined ? `回滚内容：${record.detail}。` : '';
+        return `[ankh-guard] 服务于 ${time} 前后连续启动失败，watchdog 已自动回滚到上次健康的 profile 组合并恢复。${what}原组合已备份到 state 的 composition-backup-* 目录。建议用户修复或卸载相关插件后重新安装验证。请向用户简要回报本次自动恢复与上述建议。`;
+    }
     if (record.unexpected === true) {
         return `[ankh-guard] 服务最近发生过一次非计划退出（崩溃或被手动停止）：${time}，watchdog 已自动拉起实例。请向用户简要回报这次非计划重启。`;
     }
@@ -79,6 +95,19 @@ export function continueAndReportText(record, canaryPending) {
     if (record.exitAt === undefined && record.error === undefined)
         return '';
     const time = record.exitAt !== undefined ? new Date(record.exitAt).toISOString() : '未知时间';
+    if (record.cutover !== undefined) {
+        const outcome = record.cutover.outcome === 'target-ready'
+            ? '新启动配置的应用就绪证明（受保护宿主需要时包含认证交接）与金丝雀均已通过'
+            : record.cutover.outcome === 'restored'
+                ? '目标启动失败，上一份完整启动配置已恢复并重新就绪'
+                : record.cutover.outcome === 'awaiting-user'
+                    ? '目标启动失败，watchdog 正按批准策略等待用户'
+                    : '切换在停止旧实例前失败，上一份启动配置仍有效';
+        return `[ankh-guard] 服务于 ${time} 发生启动配置切换：${outcome}。你上次正在进行的回合被中断（日志已标记 interrupted）。耐久回执：${record.cutover.receipt}。请检查当前状态并继续未完成的任务，读取回执后向用户报告 supervisor/child PID、配置摘要、认证、重试与恢复结果。`;
+    }
+    if (record.compositionRecovered === true) {
+        return `[ankh-guard] 服务于 ${time} 前后连续启动失败，watchdog 已自动回滚到上次健康的 profile 组合并恢复（最近的插件变更已卸载）。你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务，并向用户简要回报本次自动恢复；若任务已不再适用，简要说明原因后停止。`;
+    }
     if (record.unexpected === true) {
         return `[ankh-guard] 服务于 ${time} 发生非计划退出（崩溃或被手动停止），watchdog 已自动拉起实例。你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务，并向用户简要回报这次非计划重启；若任务已不再适用，简要说明原因后停止。`;
     }
@@ -152,6 +181,37 @@ export function writeAdoptionRecord(stateDir, now, initiator) {
     })}\n`);
     return true;
 }
+/**
+ * Record a composition rollback recovery: repeated boot failures whose
+ * subject lived outside the checkout (a freshly installed plugin is the
+ * common case) were recovered by restoring the last healthy profile
+ * composition. The service is UP again minus the newest plugin change — the
+ * recovery must be reported, never silent.
+ *
+ * Pending-record policy: a pending record with real diagnostics (error /
+ * unexpected) is kept; a BARE exit outcome (exitAt/pid only) is merged over —
+ * the watchdog knows the boot actually failed and recovered, so its record is
+ * the truthful one, and it inherits the exit record's initiator so the report
+ * still reaches its owner.
+ * @param stateDir - state directory.
+ * @param now - epoch milliseconds of the recovery boot.
+ * @param detail - what changed in the rolled-back composition (e.g. the
+ * unmounted bundle rows), for the report text.
+ * @returns whether the record was written.
+ */
+export function writeCompositionRecovery(stateDir, now, detail) {
+    const pending = pendingRestartRecord(stateDir);
+    if (pending !== null && (pending.error !== undefined || pending.unexpected === true || pending.compositionRecovered === true))
+        return false;
+    mkdirSync(stateDir, { recursive: true });
+    atomicWrite(restartRecordFile(stateDir), `${JSON.stringify({
+        exitAt: now,
+        compositionRecovered: true,
+        ...(detail !== undefined && detail !== '' ? { detail } : {}),
+        ...(pending?.initiator !== undefined ? { initiator: pending.initiator } : {}),
+    })}\n`);
+    return true;
+}
 /**
  * Persist the launch record (atomic). The instance-facing side of
  * {@link writeInstanceLaunch}: only an `instance`-sourced record may be
@@ -287,3 +347,49 @@ export function readSkillRegistration(stateDir) {
         return null;
     }
 }
+/** The tool whose open call means the turn is parked waiting for the human. */
+const USER_INPUT_TOOL = 'ask_user_question';
+/**
+ * Whether the session's last turn ended PARKED on user input: interrupted
+ * while waiting on an open `ask_user_question` call, or on an approval
+ * (`approval/asked` with no `approval/decided` in the same turn / after the
+ * turn's start). A parked turn has no interrupted WORK — the card persists in
+ * the log and the user answers whenever — so the restart resume must leave
+ * such sessions alone (no resume, no continue injection, no replayed card).
+ * @param events - the session's durable events (crash-repair already applied).
+ * @returns whether the last interrupted turn was parked on user input.
+ */
+export function isParkedOnUserInput(events) {
+    let parkedTurn;
+    let parkedTurnStartSeq = -1;
+    for (const event of events) {
+        const reason = event.data['reason'];
+        if (event.type === 'turn/end' && reason?.kind === 'interrupted') {
+            parkedTurn = event.data['turn'];
+        }
+    }
+    if (parkedTurn === undefined)
+        return false;
+    for (const event of events) {
+        if (event.type === 'turn/start' && event.data['turn'] === parkedTurn) {
+            parkedTurnStartSeq = event.seq ?? -1;
+        }
+    }
+    let lastToolName;
+    let pendingApproval = false;
+    for (const event of events) {
+        // Approval events are not guaranteed to carry a turn — fall back to the
+        // turn's start sequence boundary.
+        const inTurn = event.data['turn'] === parkedTurn
+            || (parkedTurnStartSeq >= 0 && (event.seq ?? -1) >= parkedTurnStartSeq);
+        if (!inTurn)
+            continue;
+        if (event.type === 'tool/call')
+            lastToolName = event.data['name'];
+        if (event.type === 'approval/asked')
+            pendingApproval = true;
+        if (event.type === 'approval/decided')
+            pendingApproval = false;
+    }
+    return lastToolName === USER_INPUT_TOOL || pendingApproval;
+}

package/lib/types/restart-request.d.ts

@@ -0,0 +1,32 @@
+/** One guarded-restart request. */
+export interface RestartRequest {
+    /** The successor launch command (the target profile's `dsh web …` line). */
+    start: string;
+    /** The dsh profile the composition preflight dry-runs. */
+    profile: string;
+    /** The session id the restart report returns to — required, never invented. */
+    initiator: string;
+}
+/** The structured verdict; terminal hint text never crosses this seam. */
+export type RestartRequestResult = {
+    accepted: true;
+    via: 'restart' | 'reconfigure';
+    detail: string;
+} | {
+    accepted: false;
+    stage: string;
+    reason: string;
+    detail: string;
+};
+/**
+ * Validate and dispatch one restart request through the guard's own gate
+ * chain. A refusal never stops the running instance.
+ * @param request - the successor command, target profile, and owning session.
+ * @param context - the guard's resolved state dir and credential repo.
+ * @returns the structured verdict with bounded human detail for display.
+ */
+export declare function requestRestart(request: RestartRequest, context: {
+    stateDir: string;
+    repoDir: string;
+}): Promise<RestartRequestResult>;
+//# sourceMappingURL=restart-request.d.ts.map

package/lib/types/restart-request.js

@@ -0,0 +1,128 @@
+/**
+ * In-process guarded-restart trigger for UI-grade callers (the mode
+ * switcher's host half). Dispatches on supervision — no live watchdog: the
+ * `restart` verb's self-contained stop→start→canary; supervised:
+ * `reconfigure`'s transactional cutover, the only safe way to change the
+ * launch command under a live watchdog (its respawn would otherwise fight
+ * the new command). The trigger shells out to this package's own CLI, so
+ * the gate chain (credential → preflight → marker/lock) keeps exactly one
+ * behavior source and the detached driver keeps its proven lifetime rules;
+ * the structured verdict returns through DSH_ANKH_VERDICT_FILE, never
+ * scraped from the human stderr text.
+ *
+ * Never import the CLI module from the plugin graph: a runtime edge pulls
+ * cli.ts into a shared tsdown chunk, evicting its code from lib/cli.js so
+ * the direct-invocation guard never fires and the built CLI silently exits
+ * 0 on every call (observed 2026-09-09; type-only imports are erased and
+ * stay safe).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readInstanceLaunch } from "./restart-context.js";
+import { liveWatchdogPid } from "./state-files.js";
+/** Bounded human detail carried alongside the structured verdict, for display. */
+const DETAIL_CAP = 4096;
+/**
+ * argv (after process.execPath) that runs this package's CLI with the given
+ * args — the same source/built split as the CLI's own cliInvocation, resolved
+ * from this module's directory (src/ and lib/ keep their entries side by
+ * side). The two copies must not be unified through an import: see the module
+ * doc for what a runtime edge into the CLI module does to the built bundle.
+ */
+function cliEntryArgs(args) {
+    // Check the FILE path, not the directory: '…/src' has no trailing
+    // separator and never matches '/src/' — cliInvocation gets this right
+    // because it tests the module file itself.
+    const modulePath = fileURLToPath(import.meta.url);
+    const here = dirname(modulePath);
+    if (modulePath.includes(`${sep}src${sep}`)) {
+        const tsx = join(resolve(here, '../../../node_modules'), 'tsx', 'dist', 'esm', 'index.mjs');
+        if (existsSync(tsx))
+            return ['--import', tsx, join(here, 'cli.ts'), ...args];
+        return [join(here, 'cli.ts'), ...args];
+    }
+    return [join(here, 'cli.js'), ...args];
+}
+/** Read the caller-side verdict file, or null when the CLI never wrote one. */
+function readVerdict(file) {
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof value.stage === 'string' && typeof value.reason === 'string'
+            ? { stage: value.stage, reason: value.reason }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate and dispatch one restart request through the guard's own gate
+ * chain. A refusal never stops the running instance.
+ * @param request - the successor command, target profile, and owning session.
+ * @param context - the guard's resolved state dir and credential repo.
+ * @returns the structured verdict with bounded human detail for display.
+ */
+export async function requestRestart(request, context) {
+    if (request.start.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'start (the successor launch command) is required', detail: '' };
+    }
+    if (request.profile.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'profile (the dsh profile to preflight) is required', detail: '' };
+    }
+    if (request.initiator.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'initiator (the session id the restart report returns to) is required — never invent one', detail: '' };
+    }
+    const port = readInstanceLaunch(context.stateDir)?.port;
+    if (port === undefined) {
+        return { accepted: false, stage: 'usage', reason: "no instance launch record in the state dir — the guard does not know this instance's port", detail: '' };
+    }
+    const via = liveWatchdogPid(context.stateDir) === null ? 'restart' : 'reconfigure';
+    const argv = via === 'restart'
+        ? [
+            'restart', '--port', String(port), '--start', request.start, '--profile', request.profile,
+            '--initiator', request.initiator, '--state-dir', context.stateDir, '--repo', context.repoDir,
+        ]
+        : [
+            'reconfigure', '--start', request.start, '--profile', request.profile,
+            '--on-failure', 'restore-previous', '--initiator', request.initiator, '--state-dir', context.stateDir,
+        ];
+    const verdictDir = mkdtempSync(join(tmpdir(), 'ankh-restart-request-'));
+    const verdictFile = join(verdictDir, 'verdict.json');
+    // This instance's own supervision variables must not leak into the CLI's
+    // children: a WD_STATE_DIR would retarget every watchdog they spawn (the
+    // same scrub the restart verb applies to the instance it starts).
+    const env = { ...process.env, DSH_ANKH_VERDICT_FILE: verdictFile };
+    delete env.DSH_ANKH_RESTART_DRIVER;
+    for (const key of Object.keys(env)) {
+        if (key.startsWith('WD_'))
+            delete env[key];
+    }
+    try {
+        const { code, output } = await new Promise((resolvePromise, rejectPromise) => {
+            let captured = '';
+            const child = spawn(process.execPath, cliEntryArgs(argv), { stdio: ['ignore', 'pipe', 'pipe'], env });
+            const append = (chunk) => { if (captured.length < DETAIL_CAP)
+                captured += chunk.toString('utf8'); };
+            child.stdout.on('data', append);
+            child.stderr.on('data', append);
+            child.once('error', rejectPromise);
+            child.once('exit', exitCode => { resolvePromise({ code: exitCode, output: captured }); });
+        });
+        const detail = output.trim();
+        if (code === 0)
+            return { accepted: true, via, detail };
+        const verdict = readVerdict(verdictFile);
+        return {
+            accepted: false,
+            stage: verdict?.stage ?? 'unknown',
+            reason: verdict?.reason ?? detail.split('\n', 1)[0] ?? `guard CLI exited ${code ?? 'signal'}`,
+            detail,
+        };
+    }
+    finally {
+        rmSync(verdictDir, { recursive: true, force: true });
+    }
+}