@khorsheed/dsh-ankh-guard 0.3.2 → 0.4.1

package/lib/types/transition.js

@@ -499,12 +499,26 @@ function snapshotCopyError(source, error) {
     return new Error(`preflight snapshot could not safely copy ${source}: ${String(error)}`);
 }
 /**
- * Top-level home entries that never join a preflight snapshot: scratch is
- * ephemeral by definition, and copying it can push prepare+canary past the
- * credential's freshness window (observed: a 24 GB scratch expired the
- * credential mid-cutover, the target canary then failed and restored).
+ * Top-level home entries the preflight snapshot copies — the ALLOWLIST of
+ * inputs the launcher's boot actually reads: the profile trees, the home-level
+ * patch layer, settings, and the credential/identity stores. Everything else
+ * (plugin data: sessions, state, local-agent sub-homes, tarballs, scratch, …)
+ * is excluded BY DEFAULT, so a newly installed plugin's data directory can
+ * never silently join the copy — this list moves only when the HOST's boot
+ * starts reading a new home input, and a miss fails the dry-run loudly with
+ * the missing path rather than degrading into a slow copy. The denylist this
+ * replaced failed twice the other way: a 24 GB scratch tree expired the
+ * credential mid-cutover (canary failed, restored), and on 2026-09-27 the
+ * local-agent sub-home's absolute links dragged the host checkout's entire
+ * node_modules into a ~4 GB / 848 s prepare.
  */
-const SNAPSHOT_SKIPPED_TOP_LEVEL = new Set(['scratch']);
+export const SNAPSHOT_INCLUDED_TOP_LEVEL = [
+    'profiles',
+    'settings.yaml',
+    'cordis.patch.yml',
+    '.credentials.yaml',
+    '.anonymous-user-id',
+];
 function canonicalSnapshotSource(source) {
     try {
         return realpathSync(source);
@@ -558,7 +572,7 @@ function copySnapshotNode(source, destination, context) {
         });
         try {
             for (const name of readdirSync(canonical)) {
-                if (canonical === context.rootCanonical && SNAPSHOT_SKIPPED_TOP_LEVEL.has(name))
+                if (canonical === context.rootCanonical && !context.includeTopLevel.has(name))
                     continue;
                 copySnapshotNode(join(canonical, name), join(destination, name), context);
             }
@@ -574,6 +588,13 @@ function copySnapshotNode(source, destination, context) {
         copyFileSync(canonical, destination, constants.COPYFILE_FICLONE);
         chmodSync(destination, linkMetadata.mode & 0o7777);
         utimesSync(destination, linkMetadata.atime, linkMetadata.mtime);
+        context.copiedFiles++;
+        context.copiedBytes += linkMetadata.size;
+        context.onProgress?.({
+            files: context.copiedFiles,
+            bytes: context.copiedBytes,
+            skippedRuntimeEntries: context.skippedRuntimeEntries,
+        });
     }
     catch (error) {
         throw snapshotCopyError(source, error);
@@ -581,12 +602,19 @@ function copySnapshotNode(source, destination, context) {
 }
 /**
  * Preserve Node's ancestor node_modules lookup for an external package while
- * avoiding one copy per package link. Other external targets are materialized
- * individually and still deduplicated by canonical path.
+ * avoiding one copy per package link. The anchor is the package's OWN parent
+ * node_modules — the LAST node_modules segment in the resolved target: pnpm
+ * store links resolve to …/.pnpm/<name>@<version>/node_modules/<name>, where
+ * that parent already holds the package's dependency siblings, so the lookup
+ * survives at the tightest scope. Anchoring the FIRST segment instead dragged
+ * the whole multi-GB store root into the snapshot (observed 2026-09-27: 32
+ * profile links pulled in the host checkout's entire root node_modules).
+ * Other external targets are materialized individually and still deduplicated
+ * by canonical path.
  */
 function externalMaterializationAnchor(target) {
     const parsed = resolve(target).split(sep);
-    const nodeModulesIndex = parsed.indexOf('node_modules');
+    const nodeModulesIndex = parsed.lastIndexOf('node_modules');
     if (nodeModulesIndex >= 0) {
         const prefix = parsed.slice(0, nodeModulesIndex + 1).join(sep) || sep;
         return { source: prefix, destination: 'node_modules' };
@@ -665,17 +693,21 @@ function finalizeSnapshotDirectories(context) {
     }
 }
 /**
- * Clone a live home while retaining a contained package-link graph. Internal
- * links are rebuilt against copied nodes; external targets are deduplicated in
- * a snapshot-owned materialization area. No retained link resolves outside the
- * snapshot root, so writes through pnpm/Cordis links cannot reach live bytes.
- * Runtime entries without copyable content (sockets, FIFOs — and links to
- * them) are skipped and counted, never copied; the top-level scratch/ tree is
- * excluded for size. Device nodes still fail closed.
+ * Clone a live home's BOOT INPUTS while retaining a contained package-link
+ * graph. Only the allowlisted top-level entries are copied (see
+ * {@link SNAPSHOT_INCLUDED_TOP_LEVEL}) — plugin data directories are excluded
+ * by default, so the copy's size is bounded by what the composition's boot
+ * reads, not by whatever the home happens to hold. Internal links are rebuilt
+ * against copied nodes; external targets are deduplicated in a snapshot-owned
+ * materialization area. No retained link resolves outside the snapshot root,
+ * so writes through pnpm/Cordis links cannot reach live bytes. Runtime entries
+ * without copyable content (sockets, FIFOs — and links to them) are skipped
+ * and counted, never copied. Device nodes still fail closed.
  * @param sourceHome - Live dsh home to read.
- * @returns Isolated home, an idempotent cleanup callback, and the count of skipped runtime entries.
+ * @param options - Include-list override and progress callback.
+ * @returns Isolated home, an idempotent cleanup callback, and copy statistics.
  */
-export function createPreflightSnapshot(sourceHome) {
+export function createPreflightSnapshot(sourceHome, options = {}) {
     const root = mkdtempSync(join(tmpdir(), 'ankh-transition-preflight-'));
     const home = join(root, 'home');
     try {
@@ -684,31 +716,48 @@ export function createPreflightSnapshot(sourceHome) {
         const context = {
             externalRoot: join(root, 'materialized'),
             rootCanonical: source,
+            includeTopLevel: new Set(options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL),
             destinations: new Map(),
             pendingLinks: [],
             directories: [],
             skippedRuntimeEntries: 0,
+            copiedFiles: 0,
+            copiedBytes: 0,
+            ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
         };
         copySnapshotNode(source, home, context);
         resolveSnapshotLinks(context);
         assertSnapshotLinksContained(root, realpathSync(root));
         finalizeSnapshotDirectories(context);
-        return { home, root, skippedRuntimeEntries: context.skippedRuntimeEntries, cleanup: () => { rmSync(root, { recursive: true, force: true }); } };
+        return {
+            home,
+            root,
+            skippedRuntimeEntries: context.skippedRuntimeEntries,
+            copiedFiles: context.copiedFiles,
+            copiedBytes: context.copiedBytes,
+            cleanup: () => { rmSync(root, { recursive: true, force: true }); },
+        };
     }
     catch (error) {
         rmSync(root, { recursive: true, force: true });
         throw error;
     }
 }
-export function createTransitionPreflightSnapshot(plan) {
-    const snapshot = createPreflightSnapshot(plan.home);
+export function createTransitionPreflightSnapshot(plan, options = {}) {
+    // A transition rehearses the plan's exact operation paths, so their
+    // top-level roots join the copy even when they are not boot inputs.
+    const operationRoots = plan.operations.map(operation => operation.path.split(sep)[0]);
+    const snapshot = createPreflightSnapshot(plan.home, {
+        ...options,
+        includeTopLevel: [...new Set([...(options.includeTopLevel ?? SNAPSHOT_INCLUDED_TOP_LEVEL), ...operationRoots])],
+    });
     try {
         const stateDir = join(snapshot.root, 'guard-state');
         mkdirSync(stateDir, { recursive: true, mode: 0o700 });
         const rebound = { ...plan, home: snapshot.home };
         const reference = prepareTransition(rebound, snapshot.home, stateDir, 'preflight');
         applyTransition(reference, snapshot.home, stateDir, 'preflight');
-        return { home: snapshot.home, cleanup: snapshot.cleanup };
+        return snapshot;
     }
     catch (error) {
         snapshot.cleanup();

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.3.2",
+  "version": "0.4.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -44,14 +44,14 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-preset-registry": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent-preset-registry": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6 || ^0.2.0-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "peerDependenciesMeta": {
@@ -90,7 +90,7 @@
     },
     "compat": {
       "minHost": "0.1.5-rc.1",
-      "notes": "0.1.5-rc.1 full-line boot-verified 2026-09-25 (42 packages including capture) through the three compat layers: preset-registry dual-name probe, dual-shape typert codecs, and typert faces carrying zod@4; 0.1.7-rc.2 is the 3080 production-verified line; 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",
+      "notes": "0.1.5-rc.1 full-line boot-verified 2026-09-25 (42 packages including capture) through the three compat layers: preset-registry dual-name probe, dual-shape typert codecs, and typert faces carrying zod@4; 0.1.7-rc.2 is the 3080 production-verified line; 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; since 0.4.0 the preflight verdict also fails on any agent preset the registry marks broken — preset rows mount on standing scopes beside the profile tree, so a clean-booting profile whose presets cannot serve sessions (picker 加载失败, resume never-started) no longer passes the gate",
       "verifiedHost": "0.1.7-rc.2"
     }
   }

package/scripts/dsh-watchdog.sh

@@ -48,6 +48,11 @@
 #   WD_CUTOVER_ID=ID   durable launch-cutover receipt transaction
 #   WD_CUTOVER_POLICY= restore-previous or wait-for-user (approved pre-stop)
 #   WD_CUTOVER_DELAY_SECONDS=N grace after supervisor claim before old-child stop
+#   WD_CUTOVER_PARKED=1 hold the supervision claim while the receipt sits in
+#                      awaiting-user: never launch the rejected side, consume
+#                      abort/restore control markers, exit on watchdog-stop,
+#                      and release the claim when a --cutover-id resume flips
+#                      the receipt out of awaiting-user
 #   WD_PREVIOUS_CHILD_*=PID/start token authoritative old supervisor child root
 #   WD_PREVIOUS_LISTENER_*=PID/start token listener inside that old child tree
 #   WD_READY_STABILITY_SECONDS=N unchanged child/listener proof window (default 3)
@@ -61,7 +66,9 @@
 #   WD_TEST_BREAK=1    launch a command that always fails (give-up testing)
 #
 # Markers under the state directory (written by the app or the agent):
-#   restart-requested.json  -> intentional restart: respawn + canary + clear
+#   restart-requested.json  -> intentional restart: respawn + canary + clear;
+#                      an optional integer bootTimeoutMs field overrides
+#                      WD_BOOT_TIMEOUT for boots attempted while it is pending
 #   watchdog-stop           -> exit the watchdog without respawn
 set -u
 
@@ -219,6 +226,19 @@ cutover_control_action() {
   ' "$CONTROL_RESTORE_FILE" "$CONTROL_ABORT_FILE" "$CONTROL_FILE" "$CUTOVER_ID" 2>/dev/null
 }
 
+# The durable receipt's current phase, empty when unreadable. The parked hold
+# treats an unreadable receipt as still parked (hold, never flap): only a
+# cleanly read non-awaiting-user phase releases the claim.
+cutover_receipt_phase() {
+  node -e '
+    const fs = require("fs")
+    try {
+      const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"))
+      if (typeof value?.phase === "string") process.stdout.write(value.phase)
+    } catch {}
+  ' "$STATE_DIR/launch-cutover.json" 2>/dev/null
+}
+
 # The host owns the shape of its per-process launch URL. Discovery is generic:
 # the first HTTP URL printed by THIS attempt whose authority is exactly the
 # supervised loopback authority and whose query is non-empty. No parameter
@@ -1239,6 +1259,57 @@ if [ -n "${ANKH_GUARD_TEST_RUN_DIR:-}" ]; then wd_sleep 0.01; fi
 test_event_self "${ANKH_GUARD_TEST_PROCESS_ROLE:-watchdog}" keepalive-first-tick
 test_event_self "${ANKH_GUARD_TEST_PROCESS_ROLE:-watchdog}" ready
 
+# Parked awaiting-user hold (WD_CUTOVER_PARKED=1, spawned by a bare `supervise`
+# that found the receipt waiting for a user decision): the selected side was
+# explicitly rejected, so NOTHING is launched here. The hold keeps exactly one
+# live consumer for the operator control verbs — without it, a supervisor chain
+# that died mid-cutover wedges the transaction: abort-cutover/restore-previous
+# refuse with "no live watchdog", and a bare supervise used to exit 0.
+if [ "${WD_CUTOVER_PARKED:-0}" = "1" ]; then
+  wd_log "launch cutover $CUTOVER_ID is awaiting user action — holding the supervision claim WITHOUT launching the rejected $CUTOVER_ROLE side; settle: abort-cutover / restore-previous; exit: the watchdog-stop marker; resume the rejected side: supervise --cutover-id $CUTOVER_ID"
+  while true; do
+    # Same ownership discipline as the main loop: self-heal a deleted claim,
+    # yield to a different live owner.
+    if [ "$SUPERVISE" = "1" ]; then
+      if [ ! -f "$PIDFILE" ]; then (set -C; echo $$ > "$PIDFILE") 2>/dev/null || true; fi
+      pidowner=$(cat "$PIDFILE" 2>/dev/null)
+      if [ -n "$pidowner" ] && [ "$pidowner" != "$$" ] && kill -0 "$pidowner" 2>/dev/null; then
+        wd_log "pidfile now owned by live pid $pidowner — yielding the parked hold"
+        yielded=1
+        exit 75
+      fi
+    fi
+    # Deliberate stop: exit without respawn or settlement, exactly like the
+    # main loop's stop-marker path.
+    if [ -f "$STOP_MARKER" ]; then
+      wd_log "stop marker present — exiting the parked hold"
+      rm -f "$STOP_MARKER" "$PIDFILE"
+      exit 0
+    fi
+    # Operator control before the release check: a restore decision consumes
+    # the marker and breaks into the ordinary cutover resume path below, which
+    # boots the previous complete launch specification.
+    if handle_cutover_control; then
+      if [ "$control_result" = "restore" ]; then
+        wd_log "operator control selected the previous complete launch specification"
+        break
+      fi
+      wd_log "operator control consumed; cutover $CUTOVER_ID remains parked awaiting user action"
+      continue
+    fi
+    # A `supervise --cutover-id` resume records driver-started, flipping the
+    # receipt out of awaiting-user — this hold's release signal. Exit non-zero
+    # like a yield so an external supervisor (launchd/systemd) restarts its
+    # stable launcher, which then waits behind the resuming chain.
+    phase=$(cutover_receipt_phase)
+    if [ -n "$phase" ] && [ "$phase" != "awaiting-user" ]; then
+      wd_log "cutover $CUTOVER_ID left awaiting-user (phase $phase) — releasing the claim for the resuming supervisor"
+      exit 75
+    fi
+    wd_sleep 1
+  done
+fi
+
 write_cutover_restart_marker() {
   node -e '
     const fs = require("fs")
@@ -1252,6 +1323,21 @@ write_cutover_restart_marker() {
   ' "$RESTART_MARKER" "$CUTOVER_ID" "${WD_INITIATOR:-}"
 }
 
+# A scheduled exit may carry a one-boot readiness budget (schedule-exit
+# --boot-timeout-ms), recorded in the restart marker as whole milliseconds.
+# Validate before trusting: an unreadable or out-of-shape marker changes
+# nothing — the watchdog's own WD_BOOT_TIMEOUT stays in effect.
+restart_marker_boot_timeout() {
+  node -e '
+    const fs = require("fs")
+    try {
+      const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"))
+      const ms = value?.bootTimeoutMs
+      if (Number.isInteger(ms) && ms >= 1000) process.stdout.write(String(Math.ceil(ms / 1000)))
+    } catch {}
+  ' "$RESTART_MARKER" 2>/dev/null
+}
+
 consume_takeover_control() {
   if handle_cutover_control; then
     if [ "$control_result" = "wait" ]; then
@@ -1460,9 +1546,19 @@ while true; do
   current_listener_start=''
   # Boot window: transport-up is not enough. A protected root can answer 401;
   # ready_probe completes the process's announced launch-URL cookie exchange.
+  # The budget is the watchdog's own WD_BOOT_TIMEOUT unless the pending restart
+  # marker carries a one-boot override (schedule-exit --boot-timeout-ms).
+  attempt_boot_timeout=$BOOT_TIMEOUT
+  if [ -f "$RESTART_MARKER" ]; then
+    marker_boot_timeout=$(restart_marker_boot_timeout)
+    case "$marker_boot_timeout" in
+      ''|*[!0-9]*) ;;
+      *) attempt_boot_timeout=$marker_boot_timeout ;;
+    esac
+  fi
   up=0
-  readiness_failure_detail="readiness not proven within ${BOOT_TIMEOUT}s"
-  boot_limit=$(( $(date +%s) + BOOT_TIMEOUT ))
+  readiness_failure_detail="readiness not proven within ${attempt_boot_timeout}s"
+  boot_limit=$(( $(date +%s) + attempt_boot_timeout ))
   while [ "$(date +%s)" -lt "$boot_limit" ]; do
     if [ -n "$(cutover_control_action)" ]; then
       readiness_failure_detail="operator control interrupted readiness"
@@ -1499,8 +1595,15 @@ while true; do
     redact_launch_urls_in_output
     # Mirror the captured output into the watchdog log: with plain redirection
     # (see the launch site) the attempt log is the only place the failure was
-    # written, and the watchdog log is where an operator looks first.
-    sed 's/^/[instance] /' "$ATTEMPT_LOG" 2>/dev/null
+    # written, and the watchdog log is where an operator looks first. An EMPTY
+    # attempt log is itself the signal — "the instance never wrote a line" is
+    # what distinguished a dead-on-arrival boot from a noisy one in the
+    # 2026-09-30 launchd incident, and mirroring nothing hid it for an hour.
+    if [ -s "$ATTEMPT_LOG" ]; then
+      sed 's/^/[instance] /' "$ATTEMPT_LOG" 2>/dev/null
+    else
+      wd_log "attempt $current_attempt produced no output — the instance never wrote a line (captured log $ATTEMPT_LOG is empty)"
+    fi
 
     if [ -n "$CUTOVER_ID" ] && [ -n "$(cutover_control_action)" ]; then
       failures=$((failures + 1))