@cairnkeep/cli 2.3.0 → 2.4.0

package/scripts/lib/capability-opencode-plugin-harness.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+
+const [pluginPath, repoPath, fixturePath, scenario = "contract"] = process.argv.slice(2);
+const sessionID = process.env.CAIRN_TEST_SESSION ?? "session-fixture";
+
+assert.ok(
+  pluginPath && repoPath && fixturePath,
+  "usage: capability-opencode-plugin-harness.mjs <plugin.ts> <repo> <fixture.json> [scenario]",
+);
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8"));
+const contract = fixture?.opencode;
+const pluginSource = readFileSync(pluginPath, "utf8");
+assert.match(pluginSource, /spawn\("node", \[COORDINATOR, operation\]/,
+  "OpenCode's Bun host must delegate the coordinator to Node");
+assert.doesNotMatch(pluginSource, /spawn\(process\.execPath/,
+  "OpenCode's process.execPath is the harness binary, not Node");
+assert.match(pluginSource, /state\.operations === 0\s*\? Promise\.resolve\(operation\(\)\)/,
+  "non-awaited OpenCode terminal callbacks must start coordinator I/O synchronously");
+assert.match(pluginSource, /spawnSync\("node", \[COORDINATOR, operation\]/,
+  "OpenCode terminal settlement needs a bounded synchronous Bun-host bridge");
+assert.match(pluginSource, /process\.versions as NodeJS\.ProcessVersions & \{ bun\?: string \}/,
+  "the synchronous terminal bridge must stay scoped to OpenCode's Bun host");
+assert.equal(contract?.version, "1.17.20", "fixture must pin OpenCode 1.17.20");
+assert.equal(
+  contract?.source?.commit,
+  "4473fc3c9055046183990a965d68df3db7ea6f62",
+  "fixture must pin the official v1.17.20 source commit",
+);
+assert.equal(contract?.hook?.name, "command.execute.before");
+assert.deepEqual(contract?.dispose, {
+  name: "dispose",
+  phase: "plugin-shutdown",
+  input_fields: [],
+  additional_properties: false,
+  source_file: "packages/plugin/src/index.ts",
+  source_commit: "4473fc3c9055046183990a965d68df3db7ea6f62",
+  purpose: "Release plugin-owned resources after the host stops using the plugin instance.",
+});
+assert.deepEqual(contract?.hook?.input?.required_fields, ["command", "sessionID", "arguments"]);
+assert.deepEqual(contract?.hook?.output?.required_fields, ["parts"]);
+assert.deepEqual(Object.keys(contract?.events ?? {}).sort(), [
+  "session.deleted",
+  "session.error",
+  "session.idle",
+  "session.status",
+]);
+assert.equal(contract?.lifecycle?.event_callback_is_awaited, false);
+
+function assertExactKeys(value, required, optional = []) {
+  assert.ok(value && typeof value === "object" && !Array.isArray(value));
+  const keys = Object.keys(value).sort();
+  const allowed = [...required, ...optional].sort();
+  for (const key of required) assert.ok(keys.includes(key), `missing required field: ${key}`);
+  for (const key of keys) assert.ok(allowed.includes(key), `unexpected fixture field: ${key}`);
+}
+
+assertExactKeys(
+  contract.hook.input.sample,
+  contract.hook.input.required_fields,
+  contract.hook.input.optional_fields,
+);
+assertExactKeys(
+  contract.hook.output.sample,
+  contract.hook.output.required_fields,
+  contract.hook.output.optional_fields,
+);
+for (const [name, eventContract] of Object.entries(contract.events)) {
+  assertExactKeys(
+    eventContract.sample,
+    eventContract.required_fields,
+    eventContract.optional_fields,
+  );
+  assertExactKeys(
+    eventContract.sample.properties,
+    eventContract.properties_required_fields,
+    eventContract.properties_optional_fields,
+  );
+  assert.equal(eventContract.sample.type, name);
+  if (name === "session.deleted") {
+    assertExactKeys(
+      eventContract.sample.properties.info,
+      eventContract.info_required_fields,
+      eventContract.info_optional_fields,
+    );
+    assertExactKeys(
+      eventContract.sample.properties.info.time,
+      eventContract.time_required_fields,
+      eventContract.time_optional_fields,
+    );
+  }
+}
+
+const module = await import(`${pathToFileURL(pluginPath).href}?test=${Date.now()}`);
+for (const [name, value] of Object.entries(module)) {
+  assert.equal(typeof value, "function", `OpenCode treats exported ${name} as a plugin entrypoint`);
+}
+assert.equal(typeof module.CapabilityCommandPlugin, "function");
+assert.deepEqual(module.CapabilityCommandPlugin.contract, {
+  version: contract.version,
+  sourceCommit: contract.source.commit,
+  admissionHook: contract.hook.name,
+  terminalEvents: contract.lifecycle,
+});
+
+const calls = [];
+const client = {
+  session: {
+    get: async ({ path }) => ({
+      data: {
+        id: path.id,
+        projectID: "project-fixture",
+        directory: repoPath,
+        title: "fixture",
+        version: contract.version,
+        time: { created: 1, updated: 2 },
+      },
+    }),
+  },
+};
+const plugin = await module.CapabilityCommandPlugin({
+  client,
+  project: {
+    id: "project-fixture",
+    worktree: scenario === "identity-mismatch" ? `${repoPath}-decoy` : repoPath,
+  },
+  directory: repoPath,
+  worktree: repoPath,
+  serverUrl: new URL("http://127.0.0.1:4096"),
+  $: undefined,
+  experimental_workspace: undefined,
+});
+
+assert.ok(plugin && typeof plugin === "object");
+assert.equal(typeof plugin[contract.hook.name], "function");
+assert.equal(typeof plugin.event, "function");
+
+async function commandBefore(targetSessionID = sessionID) {
+  const input = structuredClone(contract.hook.input.sample);
+  const output = structuredClone(contract.hook.output.sample);
+  input.sessionID = targetSessionID;
+  if (scenario === "malformed-admission") input.unexpected = "rejected";
+  try {
+    await plugin[contract.hook.name](input, output);
+    calls.push({ boundary: contract.hook.name, result: "allowed", parts: output.parts.length });
+  } catch (error) {
+    calls.push({
+      boundary: contract.hook.name,
+      result: "blocked",
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function deliver(eventName, targetSessionID = sessionID) {
+  const event = structuredClone(contract.events[eventName].sample);
+  if (eventName === "session.deleted") event.properties.info.id = targetSessionID;
+  else event.properties.sessionID = targetSessionID;
+  await plugin.event({ event });
+  calls.push({ boundary: "event", event: eventName });
+}
+
+async function disposePlugin() {
+  if (typeof plugin.dispose !== "function") {
+    calls.push({ boundary: contract.dispose.name, result: "missing" });
+    return false;
+  }
+  await plugin.dispose();
+  calls.push({ boundary: contract.dispose.name, result: "completed" });
+  return true;
+}
+
+function traceRows() {
+  const trace = process.env.CAIRN_BOUNDARY_TRACE;
+  if (!trace || !existsSync(trace)) return [];
+  const raw = readFileSync(trace, "utf8").trim();
+  return raw ? raw.split(/\n/).map(JSON.parse) : [];
+}
+
+async function waitForOperation(operation, count) {
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    if (traceRows().filter((row) => row.operation === operation).length >= count) return;
+    await delay(10);
+  }
+  throw new Error(`coordinator operation did not arrive: ${operation} #${count}`);
+}
+
+function releaseCoordinator() {
+  const release = process.env.CAIRN_TEST_RELEASE_FILE;
+  assert.ok(release, "CAIRN_TEST_RELEASE_FILE is required for ordering scenarios");
+  writeFileSync(release, "release\n");
+}
+
+const scenarios = new Set([
+  "contract",
+  "admission",
+  "success",
+  "status-success",
+  "error",
+  "abandonment",
+  "duplicate-success",
+  "duplicate-error",
+  "settled-then-delete",
+  "cwd-drift-success",
+  "malformed-admission",
+  "identity-mismatch",
+  "dispose-contract",
+  "dispose-unfinished",
+  "dispose-multiple",
+  "dispose-settled-success",
+  "dispose-settled-error",
+  "dispose-terminal-race",
+  "terminal-next-admission",
+  "dispose-master-off",
+]);
+assert.ok(scenarios.has(scenario), `unsupported scenario: ${scenario}`);
+
+if (!new Set(["contract", "dispose-contract", "dispose-multiple"]).has(scenario)) await commandBefore();
+if (scenario === "success") await deliver("session.idle");
+if (scenario === "status-success") await deliver("session.status");
+if (scenario === "error") await deliver("session.error");
+if (scenario === "abandonment") await deliver("session.deleted");
+if (scenario === "duplicate-success") {
+  await deliver("session.idle");
+  await deliver("session.status");
+  await deliver("session.idle");
+}
+if (scenario === "duplicate-error") {
+  await deliver("session.error");
+  await deliver("session.error");
+}
+if (scenario === "settled-then-delete") {
+  await deliver("session.idle");
+  await deliver("session.deleted");
+}
+if (scenario === "cwd-drift-success") {
+  process.chdir(`${repoPath}-decoy`);
+  await deliver("session.idle");
+}
+if (scenario === "dispose-contract") await disposePlugin();
+if (scenario === "dispose-unfinished" || scenario === "dispose-master-off") await disposePlugin();
+if (scenario === "dispose-multiple") {
+  await commandBefore(`${sessionID}-one`);
+  await commandBefore(`${sessionID}-two`);
+  await disposePlugin();
+}
+if (scenario === "dispose-settled-success") {
+  await deliver("session.idle");
+  await disposePlugin();
+}
+if (scenario === "dispose-settled-error") {
+  await deliver("session.error");
+  await disposePlugin();
+}
+if (scenario === "dispose-terminal-race") {
+  assert.equal(typeof plugin.dispose, "function", "native dispose hook is missing");
+  const terminal = deliver("session.idle");
+  await waitForOperation("harness-terminal", 1);
+  const disposal = plugin.dispose();
+  await delay(50);
+  releaseCoordinator();
+  await terminal;
+  await disposal;
+  calls.push({ boundary: contract.dispose.name, result: "completed" });
+}
+if (scenario === "terminal-next-admission") {
+  const terminal = deliver("session.error");
+  await waitForOperation("harness-terminal", 1);
+  const nextAdmission = commandBefore();
+  await delay(50);
+  assert.equal(traceRows().filter((row) => row.operation === "harness-before").length, 1,
+    "next same-session admission reached the coordinator before the accepted terminal finished");
+  releaseCoordinator();
+  await terminal;
+  await nextAdmission;
+}
+
+process.stdout.write(`${JSON.stringify({
+  fixture: {
+    version: contract.version,
+    commit: contract.source.commit,
+  },
+  dispose_present: typeof plugin.dispose === "function",
+  scenario,
+  calls,
+})}\n`);

package/scripts/lib/trajectory-opencode-plugin-harness.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const [pluginPath, repoPath, fixturePath] = process.argv.slice(2);
+assert.ok(pluginPath && repoPath && fixturePath, "usage: harness <plugin.ts> <repo> <fixture.json>");
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8"));
+const module = await import(`${pathToFileURL(pluginPath).href}?test=${Date.now()}`);
+assert.equal(typeof module.MemoryCapturePlugin, "function");
+
+const client = {
+    session: {
+        get: async () => ({ data: { id: fixture.session.id } }),
+        messages: async () => ({ data: fixture.messages }),
+    },
+};
+const plugin = await module.MemoryCapturePlugin({ client, directory: repoPath });
+assert.equal(typeof plugin.event, "function");
+await plugin.event({
+    event: {
+        type: "session.idle",
+        properties: { sessionID: fixture.session.id },
+    },
+});

package/scripts/lib/trajectory-pi-extension-harness.mjs

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const [extensionPath, repoPath, fixturePath] = process.argv.slice(2);
+assert.ok(extensionPath && repoPath && fixturePath, "usage: harness <extension.ts> <repo> <fixture.json>");
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8"));
+const module = await import(`${pathToFileURL(extensionPath).href}?test=${Date.now()}`);
+assert.equal(typeof module.default, "function");
+
+let shutdownHandler;
+const pi = {
+    on(event, handler) {
+        if (event === "session_shutdown") shutdownHandler = handler;
+    },
+};
+await module.default(pi);
+assert.equal(typeof shutdownHandler, "function");
+
+let sessionReads = 0;
+const sessionManager = {
+    getSessionId() {
+        sessionReads += 1;
+        return fixture.session.id;
+    },
+    getBranch() {
+        sessionReads += 1;
+        return fixture.session.entries;
+    },
+};
+
+await shutdownHandler(
+    { type: "session_shutdown", reason: "quit" },
+    { cwd: repoPath, sessionManager },
+);
+
+if (/^(?:1|true|yes|on)$/i.test(process.env.CAIRN_TRAJECTORY_CAPTURE ?? "")) {
+    assert.equal(sessionReads, 2, "enabled adapter must read the session ID and active branch exactly once");
+} else {
+    assert.equal(sessionReads, 0, "disabled adapter must not touch the SessionManager");
+}

package/scripts/memory-wiki-audit.sh

@@ -6,6 +6,7 @@
 #   2. open hard contradictions in CONTRADICTIONS.md
 #   3. orphan source pages not linked from index.md
 #   4. unreviewed memory candidates staged longer than STALE_DAYS
+#   5. optional closed-trajectory note distillation in a separate process
 #
 # Output: a consolidated markdown report on stdout (and optionally to REPORT_PATH).
 # Designed for a systemd timer or cron. Pure bash/grep — no model round-trip, so
@@ -19,6 +20,8 @@
 #   --report PATH      also write the report to this file
 set -euo pipefail
 
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
 PARA_ROOT="${HOME}/PARA"
 STALE_DAYS=30
 REPORT_PATH=""
@@ -41,6 +44,8 @@ hard_open_total=0
 orphan_total=0
 staged_stale_total=0
 sections=()
+note_distillation_enabled=0
+note_distillation_status=""
 
 # Find every project with a wiki.
 while IFS= read -r wiki_dir; do
@@ -118,6 +123,47 @@ while IFS= read -r wiki_dir; do
   fi
 done < <(find "$PARA_ROOT" -maxdepth 4 -type d -name wiki -path '*/.planning/wiki' 2>/dev/null)
 
+# Keep note taking outside every harness callback. The audit timer starts the
+# same public one-shot command an operator would run. Master-off retains the
+# compatibility flag; master-on consumes the central effective status. A note
+# failure is reported but never hides or changes wiki findings or their exit.
+note_distillation_eligible=0
+case "${CAIRN_CAPABILITY_CONTRACT:-}" in
+  1|true|TRUE|yes|YES|on|ON)
+    capability_status="$("$CAIRN_ROOT/bin/cairn" capabilities status --json 2>/dev/null || true)"
+    if printf '%s' "$capability_status" | node -e '
+      let input = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (chunk) => { input += chunk; });
+      process.stdin.on("end", () => {
+        try {
+          const status = JSON.parse(input);
+          const notes = status.capabilities?.find((row) => row.id === "notes.distill");
+          process.exit(notes?.enabled === true ? 0 : 1);
+        } catch {
+          process.exit(1);
+        }
+      });
+    '; then
+      note_distillation_eligible=1
+    fi
+    ;;
+  *)
+    case "${CAIRN_NOTE_DISTILLATION:-}" in
+      1|true|TRUE|yes|YES|on|ON) note_distillation_eligible=1 ;;
+    esac
+    ;;
+esac
+
+if (( note_distillation_eligible == 1 )); then
+  note_distillation_enabled=1
+  if "$CAIRN_ROOT/bin/cairn" notes distill --all-projects --para-root "$PARA_ROOT" --json >/dev/null 2>&1; then
+    note_distillation_status="completed"
+  else
+    note_distillation_status="failed (deterministic wiki findings remain valid)"
+  fi
+fi
+
 # Build report once, output to stdout (and REPORT_PATH if set).
 report_body="$(
   {
@@ -129,6 +175,9 @@ report_body="$(
     echo "- Open hard contradictions: $hard_open_total"
     echo "- Orphan source pages: $orphan_total"
     echo "- Unreviewed staged candidates: $staged_stale_total"
+    if (( note_distillation_enabled == 1 )); then
+      echo "- Note distillation: $note_distillation_status"
+    fi
     echo
     if (( ${#sections[@]} > 0 )); then
       echo "## Findings by project"

package/scripts/smoke-bash32.sh

@@ -30,6 +30,7 @@ SCRIPTS=(
   scripts/sync-claude-assets.sh
   scripts/sync-opencode-explore-assets.sh
   scripts/sync-opencode-wiki-assets.sh
+  scripts/sync-pi-assets.sh
 )
 
 fails=0
@@ -49,6 +50,14 @@ for s in "${SCRIPTS[@]}"; do
   fi
 done
 
+help_out=$("$RUNTIME" run --rm -v "$ROOT_DIR":/w:ro -w /w "$IMG" bash scripts/doctor.sh --help 2>&1) || true
+if grep -q 'typed metadata.*note transactions' <<<"$help_out"; then
+  echo "  [PASS] doctor help runs on bash 3.2"
+else
+  echo "  [FAIL] doctor help did not expose Phase 16 repair scope"
+  fails=$((fails + 1))
+fi
+
 if [[ $fails -eq 0 ]]; then
   echo "smoke-bash32: OK"
   exit 0

package/scripts/sync-claude-assets.sh

@@ -4,7 +4,7 @@ shopt -s nullglob
 
 usage() {
   cat <<'EOF'
-Usage: sync-claude-assets.sh [--check|--apply] [--live-root PATH]
+Usage: sync-claude-assets.sh [--check|--apply] [--capability-overlay] [--live-root PATH]
 
 Compare or sync the repo-managed Claude Code assets (commands, agents) and the
 security/wiki scaffold templates against the live Claude Code config tree.
@@ -12,12 +12,17 @@ security/wiki scaffold templates against the live Claude Code config tree.
 Options:
   --check            Verify that the live assets match the repo copy (default)
   --apply            Copy the repo-managed assets into the live Claude tree, then verify
+  --capability-overlay
+                     Select guarded commands and native capability hooks only when
+                     CAIRN_CAPABILITY_CONTRACT is also enabled
   --live-root PATH   Override the live Claude root (default: $CLAUDE_CONFIG_DIR or $HOME/.claude)
   -h, --help         Show this help text
 
 Notes:
   - Claude assets source of truth lives under ./claude/ (commands/, agents/).
   - Installs claude/commands/*.md -> <live>/commands/ and claude/agents/*.md -> <live>/agents/.
+  - --capability-overlay substitutes matching files from claude/capability-contract/
+    only with the master switch enabled; all other modes ignore that tree.
   - Also installs templates/{security,wiki}-*.template -> <live>/templates/ so the
     /security-audit and /wiki-* commands can scaffold from $HOME/.claude/templates/.
   - Renders claude/hooks/*.sh -> <live>/hooks/ (substituting @@INFRA_ROOT@@) and
@@ -32,17 +37,34 @@ CLAUDE_SOURCE="$ROOT_DIR/claude"
 TEMPLATE_SOURCE="$ROOT_DIR/templates"
 LIVE_ROOT="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 MODE="check"
+CAPABILITY_OVERLAY=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --check) MODE="check"; shift ;;
     --apply) MODE="apply"; shift ;;
+    --capability-overlay) CAPABILITY_OVERLAY=1; shift ;;
     --live-root) LIVE_ROOT="$2"; shift 2 ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; usage >&2; exit 2 ;;
   esac
 done
 
+capability_contract_enabled() {
+  local value="${CAIRN_CAPABILITY_CONTRACT:-}"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  case "$value" in
+    1|[Tt][Rr][Uu][Ee]|[Yy][Ee][Ss]|[Oo][Nn]) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+CAPABILITY_OVERLAY_ACTIVE=0
+if [[ "$CAPABILITY_OVERLAY" -eq 1 ]] && capability_contract_enabled; then
+  CAPABILITY_OVERLAY_ACTIVE=1
+fi
+
 if [[ ! -d "$CLAUDE_SOURCE" ]]; then
   echo "No repo-managed Claude assets found at $CLAUDE_SOURCE" >&2
   exit 1
@@ -54,9 +76,13 @@ DSTS=()
 
 # 1. claude/ tree -> <live>/...
 while IFS= read -r rel; do
-  SRCS+=("$CLAUDE_SOURCE/$rel")
+  src="$CLAUDE_SOURCE/$rel"
+  if [[ "$CAPABILITY_OVERLAY_ACTIVE" -eq 1 && -f "$CLAUDE_SOURCE/capability-contract/$rel" ]]; then
+    src="$CLAUDE_SOURCE/capability-contract/$rel"
+  fi
+  SRCS+=("$src")
   DSTS+=("$LIVE_ROOT/$rel")
-done < <(cd "$CLAUDE_SOURCE" && find . -type f -name '*.md' | sed 's|^\./||' | sort)
+done < <(cd "$CLAUDE_SOURCE" && find . -path './capability-contract' -prune -o -type f -name '*.md' -print | sed 's|^\./||' | sort)
 
 # 2. security/wiki scaffold templates -> <live>/templates/
 for tpl in "$TEMPLATE_SOURCE"/security-*.template "$TEMPLATE_SOURCE"/wiki-*.template; do
@@ -71,6 +97,8 @@ if ((${#SRCS[@]} == 0)); then
 fi
 
 status=0
+HOOK_LIVE_DIR="$LIVE_ROOT/hooks"
+SETTINGS_FILE="$LIVE_ROOT/settings.json"
 for i in "${!SRCS[@]}"; do
   src="${SRCS[$i]}"
   dst="${DSTS[$i]}"
@@ -89,12 +117,76 @@ for i in "${!SRCS[@]}"; do
   fi
 done
 
+# Capability hooks are intentionally outside claude/hooks so the legacy loop
+# above cannot discover, render, register, or execute them. They enter an
+# isolated root only through the effective overlay branch.
+if [[ "$CAPABILITY_OVERLAY_ACTIVE" -eq 1 ]]; then
+  for hook_src in "$CLAUDE_SOURCE"/capability-contract/hooks/*.sh; do
+    [[ -f "$hook_src" ]] || continue
+    hook_name="$(basename "$hook_src")"
+    hook_dst="$HOOK_LIVE_DIR/$hook_name"
+    hook_cmd="bash \"$hook_dst\""
+    case "$hook_name" in
+      capability-command-start.sh)
+        hook_event_specs='UserPromptExpansion:wiki-ingest|wiki-query|wiki-lint|graphify|security-audit'
+        ;;
+      capability-command-finish.sh)
+        hook_event_specs=$'Stop\nStopFailure\nCwdChanged\nSessionEnd'
+        ;;
+      *)
+        continue
+        ;;
+    esac
+
+    if [[ "$MODE" == "apply" ]]; then
+      mkdir -p "$HOOK_LIVE_DIR"
+      sed "s|@@INFRA_ROOT@@|$ROOT_DIR|g" "$hook_src" > "$hook_dst"
+      chmod +x "$hook_dst"
+      echo "installed: hooks/$hook_name"
+    fi
+
+    while IFS= read -r event_spec; do
+      [[ -n "$event_spec" ]] || continue
+      event="${event_spec%%:*}"
+      matcher="${event_spec#*:}"
+      [[ "$matcher" == "$event_spec" ]] && matcher=""
+      if [[ "$MODE" == "apply" ]]; then
+        node -e '
+const fs = require("fs");
+const [p, cmd, token, event, matcher] = process.argv.slice(1);
+let s = {};
+if (fs.existsSync(p)) {
+  try { s = JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch (e) { console.error("settings.json parse failed, leaving untouched"); process.exit(1); }
+}
+s.hooks = s.hooks || {};
+s.hooks[event] = Array.isArray(s.hooks[event]) ? s.hooks[event] : [];
+const already = s.hooks[event].some((entry) =>
+  Array.isArray(entry.hooks) && entry.hooks.some((h) => typeof h.command === "string" && h.command.includes(token)));
+if (already) { console.log(`ok: ${event} hook already registered`); process.exit(0); }
+if (fs.existsSync(p)) fs.copyFileSync(p, p + ".bak");
+const entry = matcher
+  ? { matcher, hooks: [{ type: "command", command: cmd }] }
+  : { hooks: [{ type: "command", command: cmd }] };
+s.hooks[event].push(entry);
+fs.writeFileSync(p, JSON.stringify(s, null, 2) + "\n");
+console.log(`registered: ${event} hook${matcher ? " (" + matcher + ")" : ""}`);
+' "$SETTINGS_FILE" "$hook_cmd" "$hook_dst" "$event" "$matcher" || status=1
+      else
+        if [[ -f "$hook_dst" ]] && grep -qF "$hook_name" "$SETTINGS_FILE" 2>/dev/null; then
+          echo "ok: hooks/$hook_name ($event)"
+        else
+          echo "DRIFT: hooks/$hook_name ($event)"
+          status=1
+        fi
+      fi
+    done <<< "$hook_event_specs"
+  done
+fi
+
 # Claude hooks: render @@INFRA_ROOT@@ and register each hook on its correct
 # event in <live>/settings.json. This is the one place that touches the global
 # user settings; it backs up first and matches by command so re-runs are no-ops.
-HOOK_LIVE_DIR="$LIVE_ROOT/hooks"
-SETTINGS_FILE="$LIVE_ROOT/settings.json"
-
 # Map hook filename -> "event[:matcher][@timeout]". matcher only for
 # PreToolUse-style events; an optional trailing "@timeout" (seconds) threads
 # an explicit per-hook timeout into the settings.json registration entry so
@@ -108,6 +200,7 @@ hook_event_for() {
   case "$1" in
     memory-wakeup.sh)           echo "SessionStart" ;;
     memory-capture.sh)          echo "SessionEnd" ;;
+    compaction-capture.sh) echo "PostCompact" ;;
     memory-recall.sh)           echo "PreToolUse:Edit|Write|MultiEdit" ;;
     context-explore-pretask.sh) echo "UserPromptSubmit@25" ;;
     *)                          echo "" ;;