session-orchestrator 5.3.0 → 5.5.0

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.3.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.5.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -53,6 +53,11 @@
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/config-protection.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-edit-sessions-ledger-guard.mjs\"",
+            "timeout": 5
           }
         ]
       },

package/hooks/on-session-start.mjs

@@ -38,6 +38,7 @@ import path from 'node:path';
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
+import { readNavigatorLease } from '../scripts/lib/fleet-protocol.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
@@ -98,6 +99,38 @@ const bannerLines = [];
  */
 let pendingAdditionalContext = null;
 
+/** Byte budget of the navigator line (#1462, PRD 4.5 row "Bannerzeile B6"). */
+const NAVIGATOR_BANNER_MAX_BYTES = 120;
+
+/**
+ * Render the one-line navigator status (#1462, fleet protocol v1). The verdict
+ * comes from `readNavigatorLease()`: only a VALID lease is "aktiv"; a missing or
+ * expired one is "nicht nachweisbar" (ADR-004: absence is no proof of a free
+ * seat), an unreadable one says so instead of guessing. A long id is cut from
+ * the label — never from the fixed text — so the whole line stays ≤ 120 bytes.
+ * Same wording on every harness (Codex runs this hook too).
+ */
+export function navigatorBannerLine(verdict) {
+  if (verdict?.state === 'active') {
+    const lease = verdict.lease ?? {};
+    const prefix = '🧭 Navigator aktiv: ';
+    const suffix = ', Check-in nach ~/.config/navigator/checkin/';
+    const room = NAVIGATOR_BANNER_MAX_BYTES - Buffer.byteLength(prefix + suffix, 'utf8');
+    // Defence in depth: the lease reader already refuses control bytes in these
+    // two fields; a newline / ANSI / bidi byte must still never reach systemMessage.
+    let shown = String(lease.adresse ?? lease.session_id ?? 'unknown')
+      .replace(/[\p{Cc}\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu, '?');
+    if (Buffer.byteLength(shown, 'utf8') > room) {
+      const chars = [...shown];
+      while (chars.length > 0 && Buffer.byteLength(`${chars.join('')}…`, 'utf8') > room) chars.pop();
+      shown = `${chars.join('')}…`;
+    }
+    return `${prefix}${shown}${suffix}`;
+  }
+  if (verdict?.state === 'unreadable') return '🧭 Navigator: Lease unlesbar, Status nicht nachweisbar';
+  return '🧭 Navigator: keiner nachweisbar (keine gültige Lease)';
+}
+
 /**
  * Queue one or more banner lines for the single end-of-hook flush.
  * @param {string|null|undefined} line — multi-line strings are pushed verbatim
@@ -762,6 +795,13 @@ async function main() {
   // Resolve current branch; fall back to "unknown" when detached HEAD or no git.
   const branch = (await gitOutput(['branch', '--show-current'], projectRoot)) ?? 'unknown';
 
+  // #1443 — the commit this session started on, the fallback source for
+  // `session_start_ref` (STATE.md's `session-start-ref` had no writer). Kept
+  // only when it is a full object name; no repo, an unborn HEAD or a missing
+  // git leaves it null and the payload key is OMITTED, never fabricated.
+  const rawHeadSha = await gitOutput(['rev-parse', 'HEAD'], projectRoot);
+  const headSha = rawHeadSha && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(rawHeadSha) ? rawHeadSha : null;
+
   // v3.1.0 env-aware banner (opt-out via enable-host-banner: false in Session Config).
   // The ask-via-tool nudge rides the same opt-out flag — both are coordinator
   // reminders shown at session start; users who silence one expect silence.
@@ -987,6 +1027,18 @@ async function main() {
     pushBanner('   (registry view: repo/branch/wave. Liveness (busy/idle) is model-side — not available in this hook.)');
   }
 
+  // #1462 — Navigator line (fleet protocol v1). Exactly one line, read from the
+  // lease file only (`~/.config/navigator/leases/navigator.json`, override
+  // NAVIGATOR_CONFIG_DIR); registry `role` and ListAgents are hints, never proof.
+  // Gated like the peer lines above: no host banner → no navigator line. A read
+  // failure must never block the hook — the helper is fail-closed itself, the
+  // try/catch only guards against the unexpected.
+  if (bannerData) {
+    try {
+      pushBanner(navigatorBannerLine(await readNavigatorLease()));
+    } catch { /* swallow — hook must remain non-blocking */ }
+  }
+
   // Epic #583 W3-P3 — Mechanical peer-detection banner (independent of the
   // v3.1.0 registry-driven detectPeers() output). discoverActiveSessions()
   // reads every worktree's session.lock and the host registry; this is the
@@ -1046,8 +1098,10 @@ async function main() {
 
   // Phase 4 measurement probes — the mechanical caller (#1128).
   //
-  // `skills/session-start/SKILL.md` § Phase 4 names 19 probes with module paths
-  // and entry functions. Measured 2026-08-23 at `4f6404e`, not one of them had
+  // `skills/session-start/SKILL.md` § Phase 4 names 20 probes with module paths
+  // and entry functions (2026-10-02; the `PROBES` registry in
+  // `scripts/lib/session-start-probes.mjs` is the count's source of truth).
+  // Measured 2026-08-23 at `4f6404e` (a smaller family then), not one of them had
   // a caller anywhere in hooks/, npm scripts, .gitlab-ci.yml or .husky/ — the
   // only caller was the prose itself, and across 336 recorded session starts
   // there was no event proving any of them had ever run. Built, documented,
@@ -1126,6 +1180,7 @@ async function main() {
     // makes the supersession rate measurable instead of inferred (HR-105).
     peers_superseded: mechanicalPeersSuperseded,
   };
+  if (headSha) payload.head_sha = headSha;
 
   // #1091 — record the native SessionStart source so "does the same raw
   // session_id repeat under source=resume?" becomes answerable from

package/hooks/on-stop.mjs

@@ -27,11 +27,12 @@
  *                  "duration_ms":<int>,"duration_source":"meta-birthtime","status":"done"}
  *                (#1190 — every key after `event` is OPTIONAL and OMITTED when the
  *                 measurement could not be made; `agent` too. See docs/events-schema.md.)
+ *   Both records also carry `"reaper_trigger":"<reason>"` whenever `reaper.enabled`
+ *   is true — the orphan-reaper trigger outcome of this fire (#1489, see
+ *   `reaperTriggerField`); omitted when the reaper is disabled.
  */
 
 import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { performance } from 'node:perf_hooks';
 import {
   promises as fs,
   existsSync,
@@ -39,19 +40,23 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { detectPlatform, getProjectDir } from '../scripts/lib/platform.mjs';
+import { detectPlatform, getProjectDir, resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { findOwnScopeFile } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
-import { _parseReaper } from '../scripts/lib/config/reaper.mjs';
+import { maybeTriggerOrphanScan } from '../scripts/lib/orphan-reaper/trigger.mjs';
 
 // ---------------------------------------------------------------------------
 // stdin reading (inline — no io.mjs because Stop hooks exit 0 always, never deny)
@@ -211,25 +216,26 @@ async function gitInfo(projectRoot) {
 // ---------------------------------------------------------------------------
 
 /**
- * Try to read the wave number from .claude/wave-scope.json (or .codex / .cursor / .pi).
- * Returns 0 if no scope file is found or the file cannot be parsed.
- * @param {string} projectRoot
+ * Read the wave number from THIS session's wave-scope manifest at the session
+ * root — the same root and the same `.pi` > `.cursor` > `.codex` > `.claude`
+ * precedence the scope guards use (#1504 point 4). A peer's manifest in the
+ * same working copy is skipped; a peer-only result is "no own wave" → 0.
+ * Returns 0 too when the manifest is absent or cannot be parsed.
+ *
+ * @param {string} sessionRoot  `resolveSessionRoot(input.cwd)`
+ * @param {object|null} input   the hook payload (its `session_id` is ours)
  * @returns {Promise<number>}
  */
-async function readWaveNumber(projectRoot) {
-  const dirs = ['.pi', '.claude', '.codex', '.cursor'];
-  for (const dir of dirs) {
-    const scopePath = path.join(projectRoot, dir, 'wave-scope.json');
-    try {
-      const raw = await fs.readFile(scopePath, 'utf8');
-      const obj = JSON.parse(raw);
-      const wave = typeof obj.wave === 'number' ? obj.wave : 0;
-      return wave;
-    } catch {
-      // file missing or unparseable — try next
-    }
+async function readWaveNumber(sessionRoot, input) {
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+  const { path: scopePath } = findOwnScopeFile(sessionRoot, ownIds, classifyManifestSession);
+  if (scopePath === null) return 0;
+  try {
+    const obj = JSON.parse(await fs.readFile(scopePath, 'utf8'));
+    return typeof obj?.wave === 'number' ? obj.wave : 0;
+  } catch {
+    return 0; // unreadable or unparseable — no wave known
   }
-  return 0;
 }
 
 // ---------------------------------------------------------------------------
@@ -363,14 +369,40 @@ function resolveStopDuration(input, projectRoot) {
   }
 }
 
+/**
+ * The orphan-reaper trigger outcome as an optional record key (#1489).
+ *
+ * `reaper_trigger` carries the reason `maybeTriggerOrphanScan()` returned for
+ * THIS hook fire — `throttled` | `spawned` | `spawned-unthrottled` | `error` —
+ * on the record this hook emits anyway, so no new record type and no per-fire
+ * event exist (HR-101). `spawned-unthrottled` is the case it is here for: a
+ * throttle marker the trigger cannot stamp (a planted link or directory, a
+ * read-only tmp dir) makes every fire spawn a scan, and until now that outcome
+ * was discarded in `main()` — a defeated throttle nothing recorded (HR-105).
+ * Recording the healthy reasons too gives that count its denominator: the
+ * share of armed fires that ran unthrottled, from events.jsonl alone (HR-106).
+ *
+ * OMITTED when the reaper is disabled (the default): that is configuration,
+ * not a measurement, and stamping it would touch every record on every host.
+ *
+ * @param {{reason?: unknown}|null|undefined} trigger
+ * @returns {{reaper_trigger?: string}}
+ */
+function reaperTriggerField(trigger) {
+  const reason = trigger?.reason;
+  if (typeof reason !== 'string' || reason === 'disabled') return {};
+  return { reaper_trigger: reason };
+}
+
 /**
  * Handle a Stop event. Reads wave from scope file + git info, appends JSONL.
  * @param {object|null} input
+ * @param {{reason?: string}|null} [reaperTrigger]  `maybeTriggerOrphanScan()` result.
  */
-async function handleStop(input) {
+async function handleStop(input, reaperTrigger = null) {
   const projectRoot = getProjectDir();
 
-  const wave = await readWaveNumber(projectRoot);
+  const wave = await readWaveNumber(resolveSessionRoot(input?.cwd), input);
   const { commit, branch } = await gitInfo(projectRoot);
 
   const { sessionId, semanticSessionId } = await resolveSessionId(input, projectRoot);
@@ -483,6 +515,7 @@ async function handleStop(input) {
     ...(branch !== null ? { branch } : {}),
     ...(commit !== null ? { commit } : {}),
     ...duration,
+    ...reaperTriggerField(reaperTrigger),
   };
 
   try {
@@ -500,9 +533,10 @@ async function handleStop(input) {
  * coordinator turn. Currently always returns null (no inline warning from this
  * handler) — the slot is reserved for future SubagentStop feedback.
  * @param {object|null} input
+ * @param {{reason?: string}|null} [reaperTrigger]  `maybeTriggerOrphanScan()` result.
  * @returns {Promise<string|null>} additionalContext or null
  */
-async function handleSubagentStop(input) {
+async function handleSubagentStop(input, reaperTrigger = null) {
   /** @type {Record<string, unknown>} */
   const payload = {};
 
@@ -633,8 +667,12 @@ async function handleSubagentStop(input) {
   // #1183 — a malformed record throws EventValidationError BEFORE any side
   // effect (scripts/lib/events.mjs); this hook must never abort on that, so
   // the emit is wrapped rather than left to propagate.
+  // A fresh object via spread (like the Stop record above), never
+  // Object.assign onto a parsed payload: spread defines keys, so no `__proto__`
+  // key can reach the prototype setter (CWE-1321, semgrep
+  // prototype-pollution-object-assign).
   try {
-    await emitEvent('orchestrator.agent.stopped', payload);
+    await emitEvent('orchestrator.agent.stopped', { ...payload, ...reaperTriggerField(reaperTrigger) });
   } catch { /* telemetry never blocks the hook (#1183) */ }
   return null;
 }
@@ -775,145 +813,6 @@ function readStatusFromTranscriptTail(transcriptPath) {
 // main
 // ---------------------------------------------------------------------------
 
-// ---------------------------------------------------------------------------
-// orphan-reaper trigger (#1432 B4)
-// ---------------------------------------------------------------------------
-//
-// DUPLICATED VERBATIM between the two trigger hooks —
-// hooks/post-tool-batch-wave-signal.mjs <-> hooks/on-stop.mjs. Deliberate, with
-// a named revisit trigger (BV-004): they are the only two trigger points the
-// PRD declares, and a shared `hooks/_lib/reaper-trigger.mjs` would be a third
-// file in the hook import graph. SIZE, measured 2026-09-22 by diffing the two
-// blocks: 138 identical lines — this note said "~40 lines of glue" until then,
-// which is what made the duplicate look cheaper than it is. Extract it the
-// moment a THIRD hook needs the trigger, or the moment the copies must differ.
-
-/**
- * Filesystem path of the scan CLI, spawned as a PLAIN argv call.
- *
- * It used to be a `file://` URL handed to `node --input-type=module -e
- * <program>`, because `scripts/lib/orphan-reaper.mjs` had no entry guard. It
- * has one now (`parseReaperCliArgs` + the `isMainModule` tail), so the child's
- * contract lives in that module instead of as source text duplicated here —
- * and nothing this hook builds is a program any more: every variable part is
- * an argv value, which cannot become code whatever the checkout path contains.
- *
- * `fileURLToPath`, not `new URL(...).pathname`: the latter leaves a
- * percent-encoded path for any checkout directory containing a space.
- */
-const ORPHAN_REAPER_SCRIPT = fileURLToPath(
-  new URL('../scripts/lib/orphan-reaper.mjs', import.meta.url),
-);
-
-/**
- * Read the `reaper:` block from the project's Session Config host file.
- * Sync + inline, mirroring `hooks/loop-guard.mjs` `loadConfig()` — a hot hook
- * path must not import the full config orchestrator. A missing or unreadable
- * file yields the parser defaults, i.e. DISABLED.
- *
- * @param {string} projectDir
- * @returns {ReturnType<typeof _parseReaper>}
- */
-function loadReaperConfig(projectDir) {
-  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
-    try {
-      return _parseReaper(readFileSync(path.join(projectDir, name), 'utf8'));
-    } catch {
-      // missing or unreadable — try the next candidate
-    }
-  }
-  return _parseReaper('');
-}
-
-/**
- * Trigger the orphan scan, throttled and NON-BLOCKING (PRD FA4).
- *
- * The hook itself does exactly two pieces of I/O — one config read and one
- * `stat` of the throttle marker — and then hands the work to a DETACHED,
- * unref'd child. The scan is never run inline: one `ps` round-trip out of Node
- * was measured at ~47 ms over 287 KB of output, which alone would blow the
- * 50 ms `reaper.max-hook-latency-ms` budget this hook has to stay inside.
- *
- * The marker is stamped BEFORE the spawn, so a spawn that fails still consumes
- * the throttle window — otherwise a broken spawn would be retried on every
- * single tool batch.
- *
- * `reaper.max-hook-latency-ms` is the ceiling on the work above — measured here
- * with `performance.now()` and reported as ONE stderr WARN line when exceeded.
- * A WARN and not an event: this fires from a `PostToolBatch`-class hook, and a
- * per-fire telemetry record is exactly the always-on signal
- * `.claude/rules/host-resources.md` HR-101 calls a broken instrument. The
- * measurement covers preparation only — the scan itself runs detached, which is
- * the whole reason the budget can be held.
- *
- * Never throws: any failure degrades silently (PRD FA4 "lautlos degradieren").
- *
- * @param {object} [opts]
- * @param {string} [opts.projectDir]  Repo root; defaults to `getProjectDir()`.
- * @param {number} [opts.now]         Injected clock (ms).
- * @param {Function} [opts.spawnFn]   Injected `spawn` (tests).
- * @param {Function} [opts.statFn]    Injected `statSync` (tests).
- * @param {Function} [opts.writeFn]   Injected marker writer (tests).
- * @param {() => number} [opts.clockFn]  Injected monotonic clock for the latency
- *   budget (tests); defaults to `performance.now`.
- * @returns {Promise<{spawned: boolean, reason: string}>}
- */
-export async function maybeTriggerOrphanScan({
-  projectDir,
-  now,
-  spawnFn = spawn,
-  statFn,
-  writeFn,
-  clockFn = () => performance.now(),
-} = {}) {
-  const startedAt = clockFn();
-  /** One WARN line when the preparation overran `reaper.max-hook-latency-ms`. */
-  const checkLatency = (budgetMs) => {
-    const elapsed = clockFn() - startedAt;
-    if (Number.isFinite(budgetMs) && budgetMs > 0 && elapsed > budgetMs) {
-      process.stderr.write(
-        `orphan-reaper trigger: hook latency ${elapsed.toFixed(1)} ms exceeded `
-        + `reaper.max-hook-latency-ms (${budgetMs} ms)\n`,
-      );
-    }
-  };
-  try {
-    const root = typeof projectDir === 'string' && projectDir ? projectDir : getProjectDir();
-    const cfg = loadReaperConfig(root);
-    // Cheapest gate first: disabled means no stat, no spawn, no module load.
-    if (cfg.enabled !== true) return { spawned: false, reason: 'disabled' };
-
-    const reaper = await import('../scripts/lib/orphan-reaper.mjs');
-    const markerPath = reaper.scanMarkerPath(root);
-    const nowMs = typeof now === 'number' ? now : Date.now();
-
-    if (!reaper.shouldScanNow(markerPath, nowMs, cfg['min-scan-interval-seconds'], { statFn })) {
-      checkLatency(cfg['max-hook-latency-ms']);
-      return { spawned: false, reason: 'throttled' };
-    }
-    reaper.touchScanMarker(markerPath, { writeFn });
-
-    const child = spawnFn(
-      process.execPath,
-      [
-        ORPHAN_REAPER_SCRIPT,
-        '--repo-root', root,
-        '--mode', cfg.mode,
-        '--min-age-seconds', String(cfg['min-age-seconds']),
-        '--kill-grace-ms', String(cfg['kill-grace-ms']),
-        '--verify-wait-ms', String(cfg['verify-wait-ms']),
-        '--false-alarm-window', String(cfg['false-alarm-window']),
-      ],
-      { detached: true, stdio: 'ignore' },
-    );
-    if (child && typeof child.unref === 'function') child.unref();
-    checkLatency(cfg['max-hook-latency-ms']);
-    return { spawned: true, reason: 'spawned' };
-  } catch {
-    return { spawned: false, reason: 'error' };
-  }
-}
-
 async function main() {
   const input = await readStdinJson();
   const eventType = discriminate(input);
@@ -924,11 +823,14 @@ async function main() {
   // hook, which triggers last) because both branches below may throw — a
   // `handleStop` failure must not silently disarm the watchdog. The cost is one
   // config read plus one stat, bounded by `reaper.max-hook-latency-ms` (50 ms),
-  // and the scan itself runs in a detached child.
-  await maybeTriggerOrphanScan();
+  // and the scan itself runs in a detached child. Its outcome rides on the
+  // record either branch emits anyway (`reaper_trigger`, see reaperTriggerField).
+  // Rooted at the SESSION root (#1492 point 2): the gate ledger the scan reads
+  // lives in the tree the gate ran in — an entered worktree, not the launch dir.
+  const reaperTrigger = await maybeTriggerOrphanScan({ projectDir: resolveSessionRoot(input?.cwd) });
 
   if (eventType === 'subagent_stop') {
-    const additionalContext = await handleSubagentStop(input);
+    const additionalContext = await handleSubagentStop(input, reaperTrigger);
     // v2.1.163+: emit hookSpecificOutput for SubagentStop path.
     // If handleSubagentStop returns a non-empty context string, feed it back
     // to the coordinator turn. Currently returns null (no inline warning from
@@ -949,7 +851,7 @@ async function main() {
     // SubagentStop is intentionally outside this block — it must never emit
     // terminalSequence.
     try {
-      await handleStop(input);
+      await handleStop(input, reaperTrigger);
     } finally {
       // terminalSequence is only meaningful for Stop (session-level) events.
       process.stdout.write(buildTerminalSequenceJson(detectPlatform()));