@khorsheed/dsh-ankh-guard 0.2.0 → 0.3.0

package/lib/types/index.js

@@ -42,6 +42,24 @@ export function deriveSessionPreset(host, session) {
     }
     return host.resolveSessionPreset?.(session);
 }
+/** Probe the session-persistence service's cold-read face. */
+function probeColdReader(ctx) {
+    const service = ctx.get('sessionPersistence');
+    if (service === undefined || service === null)
+        return undefined;
+    return typeof service.open === 'function' ? service : undefined;
+}
+/** Read one persisted session's header and full log through a read handle. */
+async function readColdLog(persistence, id) {
+    const handle = await persistence.open(id, 'read');
+    try {
+        const cold = await handle.read(0);
+        return { meta: handle.header, events: cold.events };
+    }
+    finally {
+        await handle.close();
+    }
+}
 export const Config = z.object({
     maxAgeMinutes: z.natural().min(1).default(10),
     stateDir: z.string().default(''),
@@ -180,10 +198,10 @@ export function apply(ctx, config) {
             if (probe === undefined) {
                 probe = (async () => {
                     try {
-                        const persistence = ctx.get('sessionPersistence');
+                        const persistence = probeColdReader(ctx);
                         if (persistence === undefined)
                             return false;
-                        const { events } = await persistence.inspect(id);
+                        const { events } = await readColdLog(persistence, id);
                         return isParkedOnUserInput(events);
                     }
                     catch {
@@ -220,7 +238,19 @@ export function apply(ctx, config) {
                 return;
             const id = agent.id;
             const exitAt = pendingContinue.get(id);
-            const record = followupReport ? pendingRestartRecord(stateDir) : null;
+            let record = followupReport ? pendingRestartRecord(stateDir) : null;
+            // A bare PLANNED outcome with no initiating session (the restart was
+            // driven from outside the host — the operator's terminal already has
+            // the announcement) has no in-host owner: settle the record instead of
+            // waking whichever root session happens to mount first. Records
+            // carrying diagnostics someone must hear about — an unplanned
+            // recovery, a composition rollback, a failed restart — keep the
+            // first-created claim.
+            if (record !== null && record.initiator === undefined
+                && record.unexpected !== true && record.compositionRecovered !== true && record.error === undefined) {
+                acknowledgeRestartRecord(stateDir, record, Date.now());
+                record = null;
+            }
             const owesReport = record !== null && (record.initiator === undefined || id === record.initiator);
             if (exitAt !== undefined) {
                 void (async () => {
@@ -326,10 +356,13 @@ export function apply(ctx, config) {
                 agentOptions.model = selection.model;
             let setup;
             const presets = ctx.get('agentPresets');
-            const persistence = ctx.get('sessionPersistence');
+            const persistence = probeColdReader(ctx);
             if (presets !== undefined && persistence !== undefined) {
-                const inspected = await persistence.inspect(id);
-                const presetId = deriveSessionPreset(agentPresetsHost, { header: inspected.meta, events: inspected.events });
+                const inspected = await readColdLog(persistence, id);
+                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 }) };

package/lib/types/restart-context.js

@@ -2,12 +2,17 @@
  * Restart-record context injection and interrupted-session continuity. After
  * a scheduled restart, the FULL report waits for the initiating session's
  * root agent, whenever it resumes (session restore is lazy, so no other
- * session is ever woken for reporting); a record without an initiator is
- * claimed by the first root agent created. Separately, a snapshot written at
- * SIGTERM time (`interrupted-sessions.json`) records which root sessions had
- * a live turn when the process stopped, so the next restart boot can resume
- * those sessions and queue a "continue" turn. Pure logic reads the durable
- * files; the plugin wires them into `agent/created` and `agent.followup`.
+ * session is ever woken for reporting). A record without an initiator splits
+ * by kind: one carrying diagnostics someone must hear about (an unplanned
+ * recovery, a composition rollback, a failed restart) is claimed by the
+ * first root agent created, while a bare planned outcome — the restart was
+ * driven from outside the host and the operator's terminal already has the
+ * announcement — is settled without waking anyone. Separately, a snapshot
+ * written at SIGTERM time (`interrupted-sessions.json`) records which root
+ * sessions had a live turn when the process stopped, so the next restart
+ * boot can resume those sessions and queue a "continue" turn. Pure logic
+ * reads the durable files; the plugin wires them into `agent/created` and
+ * `agent.followup`.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { stateFile } from "./state-files.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khorsheed/dsh-ankh-guard",
   "description": "Hard gate for self-modification restarts: a green-build credential bound to the git HEAD, checked before any restart of the running instance",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -62,12 +62,12 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@types/node": "^22.0.0",
     "tsdown": "^0.22.2",
@@ -95,9 +95,9 @@
       "immediately": true
     },
     "compat": {
-      "minHost": "0.1.2-rc.1",
+      "minHost": "0.1.5-rc.1",
       "notes": "composition-preflight runs via the standalone preflight-runner and degrades to a notice when no live harness checkout resolves; original-tab browser handoff feature-probes optional WebServer/connection auth seams; reversible state quarantine was exercised in a live 0.1.1-rc.2 to 0.1.2-alpha.4 cutover",
-      "verifiedHost": "0.1.2-rc.1"
+      "verifiedHost": "0.1.5-rc.1"
     }
   }
 }

package/lib/processes-BjZgJjQr.js

@@ -1,344 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-//#region lib/types/processes.js
-/**
-* Process primitives shared by the guard CLI and the exit agent: locating the
-* listener on a port and killing a process tree. One owner — the watchdog's
-* bash side keeps its own copy (different runtime), but every TypeScript
-* caller goes through here.
-*/
-function executable(name, candidates) {
-	return candidates.find((candidate) => existsSync(candidate)) ?? name;
-}
-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. */
-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. */
-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). */
-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.
-*/
-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 {}
-		const procStat = `/proc/${pid}/stat`;
-		if (existsSync(procStat)) {
-			const stat = readFileSync(procStat, "utf8");
-			const commandEnd = stat.lastIndexOf(")");
-			const startTicks = (commandEnd < 0 ? [] : stat.slice(commandEnd + 1).trim().split(/\s+/))[19];
-			if (startTicks === void 0 || startTicks === "") return null;
-			let bootId = "unknown-boot";
-			try {
-				bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || bootId;
-			} catch {}
-			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 {}
-		return {
-			pid,
-			startToken: `posix:${createHash("sha256").update(bootEvidence).update("\0").update(processEvidence).digest("hex")}`
-		};
-	} catch {
-		return null;
-	}
-}
-/** Whether the same, non-recycled process is still alive. */
-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. */
-function processGroupId(pid) {
-	if (!Number.isInteger(pid) || pid <= 0) return null;
-	try {
-		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;
-	}
-}
-/**
-* 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.
-*/
-function findOwnedListener(port, supervisorPid) {
-	const listeners = findPidsOnPort(port);
-	if (listeners.length !== 1) return null;
-	const listenerPid = listeners[0];
-	if (listenerPid === void 0) return null;
-	const listener = processIdentity(listenerPid);
-	if (listener === null) return null;
-	let cursor = listenerPid;
-	let childRoot = null;
-	const seen = /* @__PURE__ */ 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, "'\\''")}'`;
-}
-/**
-* Discover how the process on a port was launched — its exact argv from
-* `ps -o command=`, its cwd from lsof, and its DSH_* environment from
-* `ps eww` — rendered as a shell command. This exists because the agent's
-* sandbox blocks ps entirely, so every fresh-machine agent fell into a
-* process-tree archaeology loop before its first restart; the CLI (running
-* unsandboxed) answers the same question mechanically and reliably. Returns
-* null when the process is gone or ps/lsof are unavailable.
-* @param pid - the listener's pid.
-*/
-function discoverLaunchCommand(pid) {
-	let argv;
-	let cwd;
-	try {
-		argv = execFileSync(PS, [
-			"-o",
-			"command=",
-			"-p",
-			pid
-		], {
-			encoding: "utf8",
-			stdio: "pipe"
-		}).trim();
-		if (argv === "") return null;
-	} catch (error) {
-		throw new Error(`ps unavailable: ${String(error)}`);
-	}
-	try {
-		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;
-		cwd = match[1] ?? "";
-	} catch (error) {
-		throw new Error(`lsof cwd unavailable: ${String(error)}`);
-	}
-	const TRANSIENT = /* @__PURE__ */ 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"
-		});
-		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))) env[token.slice(0, eq)] = token.slice(eq + 1);
-		}
-	} catch {}
-	const envPart = Object.entries(env).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
-	return `cd ${shellQuote(cwd)} && ${envPart !== "" ? `${envPart} ` : ""}${argv}`;
-}
-/**
-* Kill a pid AND its descendants, deepest first (best effort). The supervised
-* instance may have forked children; a plain signal on the pid alone would
-* orphan them (the EADDRINUSE race the watchdog's EADDRINUSE branch exists
-* for). The process-group model is NOT assumed — the instance is not
-* setsid'd — so the sweep walks `pgrep -P` instead. `pgrep` missing or
-* returning nothing is fine: the pid itself still gets the signal.
-*/
-function signalFrozenTree(pid, signal) {
-	let safe = true;
-	let children = [];
-	try {
-		const out = execFileSync(PGREP, ["-P", String(pid)], {
-			encoding: "utf8",
-			stdio: "pipe"
-		}).trim();
-		children = out === "" ? [] : out.split("\n");
-	} catch {}
-	for (const raw of children) {
-		const child = Number(raw);
-		if (!Number.isInteger(child) || child <= 0) continue;
-		try {
-			process.kill(child, "SIGSTOP");
-		} catch {
-			continue;
-		}
-		if (parentPid(child) !== pid) {
-			safe = false;
-			try {
-				process.kill(child, "SIGCONT");
-			} catch {}
-			continue;
-		}
-		safe = signalFrozenTree(child, signal) && safe;
-	}
-	try {
-		process.kill(pid, signal);
-		if (signal !== "SIGKILL") process.kill(pid, "SIGCONT");
-	} catch {}
-	return safe;
-}
-function killPidTree(pid, signal) {
-	try {
-		process.kill(pid, "SIGSTOP");
-	} catch {
-		return;
-	}
-	signalFrozenTree(pid, signal);
-}
-//#endregion
-export { listeningPortsForPid as a, processIdentityMatches as c, killPidTree as i, findOwnedListener as n, processGroupId as o, findPidOnPort as r, processIdentity as s, discoverLaunchCommand as t };