session-orchestrator 5.2.0 → 5.4.0

package/hooks/pre-bash-staging-fence.mjs

@@ -22,23 +22,32 @@
  *     "host":        "string",
  *     "started_at":  "2026-05-23T21:30:00.000Z",
  *     "staged_paths": [
- *       { "command": "git add src/foo.ts", "timestamp": "2026-…" },
+ *       { "paths": ["src/foo.ts"], "command_hash": "a635c66ec7e7bf56",
+ *         "timestamp": "2026-…" },
  *       ...
  *     ]
  *   }
  *
- * The hook does NOT parse the `git add` argv into paths — argv parsing is
- * fragile (globs, pathspec magic, `-A`, `-u`, `--`). Instead it records the
- * raw command string; the commit-guard reconciles staged paths via
- * `git diff --cached --name-only` and cross-checks them against ALL sibling
- * fence files at commit time (where the staged set is unambiguous).
+ * The entry records the PATH OPERANDS, never the command text (#1404): a
+ * staging command can carry a secret (`GIT_TOKEN=… git add x`), and the raw
+ * string was persisted verbatim to disk — the same defect 8f15f77b removed
+ * from hooks/enforce-commands.mjs. Paths are what the only reader
+ * (hooks/wave-scope-commit-guard.mjs) actually needs; `command_hash` keeps
+ * the entry countable and groupable without the text.
+ *
+ * `paths: ["*"]` means "stages a set no operand names" (`git add -A`, `.`,
+ * `-u`) and overlaps EVERY staged path — the case the reader's old raw-text
+ * regex could not see at all, because `-A` contains no path to match.
  *
  * Decision flow (G1-G6 early-return ladder):
  *   G1  tool filter — Bash only
  *   G2  command must be a non-empty string
- *   G3  regex match /\bgit\s+add\b/ — only `git add` invocations
+ *   G3  cheap regex PRE-FILTER — skip the tokenizer for plainly unrelated
+ *       commands (see GIT_ADD_REGEX; it does not decide the question)
  *   G4  context gate — isWaveAgentContext(); exit 0 immediately for
  *       coordinator/manual commits (AC5 safe-default no-op)
+ *   G4b tokenize + extract path operands; exit 0 when no `git add` statement
+ *       resolves (a pre-filter false positive writes nothing)
  *   G5  derive agent_id, build fence dir + path
  *   G6  read-modify-write the fence file (append the staging-intent entry).
  *       Errors are warned + swallowed — the hook NEVER blocks the Bash call.
@@ -64,29 +73,303 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { stableHostname } from '../scripts/lib/host-identity.mjs';
-if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
 /**
- * Matches `git add ...` invocations with word boundaries on both sides so
- * `gitadd` and `git addremote` (hypothetical) do not match. Anchored to the
- * `git` token, so `echo "git add"` is not matched (echo ≠ verb position).
- *
- * We deliberately accept `git add` anywhere in the command string — operators
- * sometimes prefix env-vars (`GIT_COMMITTER_NAME=foo git add ...`) or chain
- * commands (`cd repo && git add ...`). False positives are tolerable here
- * (the hook only writes a log line, never blocks).
+ * Cheap PRE-FILTER for the staging-command gate (G3). It answers "is it worth
+ * loading the tokenizer for this command?", never "is this a staging
+ * command?" — since #1404 that verdict belongs to {@link extractStagedPaths},
+ * which resolves the verb and subcommand properly.
+ *
+ * `git` and `add` must sit in the same statement (the negated class stops at
+ * `;`, `&`, `|` and newline) within 120 characters of each other, so global
+ * flags between them are tolerated: `git -C sub add x` reaches the extractor,
+ * where `\bgit\s+add\b` used to drop it silently. `\badd\b` keeps
+ * `git addremote` out.
+ *
+ * False positives are cheap AND inert: `git commit -m "add x"` matches here,
+ * resolves to no `git add` statement, and writes nothing (G4b).
+ */
+const GIT_ADD_REGEX = /\bgit\b[^;&|\n]{0,120}\badd\b/;
+
+/**
+ * Recorded in place of a path list when the staging command names NO explicit
+ * path operand but stages a set we cannot enumerate — `git add -A`,
+ * `git add .`, `git add -u`, `git add --pathspec-from-file=<f>`. The reader
+ * (hooks/wave-scope-commit-guard.mjs) treats it as "overlaps every staged
+ * path". This is the case the previous raw-command regex silently MISSED:
+ * `-A` contains no path text, so `pathRegex(ours).test('git add -A')` was
+ * always false and the widest staging command of all fenced nothing.
  */
-const GIT_ADD_REGEX = /\bgit\s+add\b/;
+const ALL_PATHS_MARKER = '*';
+
+/** git GLOBAL flags (before the subcommand) that consume the NEXT token. */
+const GIT_GLOBAL_VALUE_FLAGS = new Set([
+  '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env',
+]);
+
+/** `git add` flags that consume the NEXT token as their value. */
+const GIT_ADD_VALUE_FLAGS = new Set(['--chmod']);
+
+/** `git add` long flags that stage a set no path operand names. */
+const GIT_ADD_ALL_FLAGS = new Set(['--all', '--no-ignore-removal', '--update']);
+
+/**
+ * Shells whose `-c <payload>` operand is a command line the shell EXECUTES, so
+ * a `git add` inside it stages this working copy for real.
+ *
+ * DELIBERATE DUPLICATE of `DASH_C_SHELLS` in scripts/lib/command-blocker.mjs —
+ * that module does not export it (nor its `dashCPayloads`), and #1404's own
+ * rule for this hook is to consume the tokenizer, not to edit it (5 other
+ * consumers). Change one, change both.
+ */
+const DASH_C_SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'su']);
+
+/**
+ * Payload recursion depth for {@link scanForStagedPaths}. ONE level: it covers
+ * `bash -c "git add x"` and `xargs -I{} sh -c "git add x"`, which is the whole
+ * measured regression class (2026-09-20), and keeps a hook that runs on EVERY
+ * Bash call from re-tokenizing an arbitrarily nested string.
+ *
+ * NAMED CEILING (BV-004): `bash -c "bash -c 'git add x'"` is not recorded.
+ * REVISIT TRIGGER: raise to 2 if a doubly-nested staging command is ever
+ * observed in a wave transcript.
+ */
+const MAX_PAYLOAD_DEPTH = 1;
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * sha256(command) truncated to 16 hex chars.
+ *
+ * DELIBERATE DUPLICATE of hooks/enforce-commands.mjs (itself a copy of
+ * hooks/pre-bash-destructive-guard.mjs) — see the 8f15f77b commit message:
+ * the three guards stay import-free of each other on purpose, so a shared
+ * helper is NOT introduced. The hash keeps a fence entry COUNTABLE and
+ * GROUPABLE without persisting command text that may carry a secret
+ * (`GIT_TOKEN=… git add x`) — issue #1404.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function hashCommand(command) {
+  return crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
+}
+
+/**
+ * Normalise a path token so writer and reader compare the same spelling.
+ *
+ * DELIBERATE DUPLICATE of the identically-named function in
+ * hooks/wave-scope-commit-guard.mjs — the reader is a husky pre-commit hook
+ * outside the Claude-Code hook import set, and the two must agree byte for
+ * byte. Change one, change both.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeStagedPath(raw) {
+  let p = String(raw).trim();
+  while (p.startsWith('./')) p = p.slice(2);
+  p = p.replace(/\/{2,}/g, '/');
+  while (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  return p;
+}
+
+/**
+ * Extract the PATH OPERANDS of every `git add` statement in a Bash command.
+ *
+ * Reuses the repo's own shell tokenizer (scripts/lib/command-blocker.mjs) —
+ * no second shell grammar is invented here. The import is LAZY: this hook
+ * runs on every Bash call of every session, and only a `git add` command
+ * (G3) ever reaches this function, so the tokenizer's module graph must not
+ * be paid for by the other 99% of calls.
+ *
+ * Handled: `git add -- a b`, quoted operands with spaces, `git -C <dir> add x`
+ * (relative `-C` is prefixed onto the operand), chained statements
+ * (`cd x && git add y` — each statement is its own segment), leading env
+ * assignments, and the enumerate-nothing flags that yield ALL_PATHS_MARKER.
+ *
+ * NAMED CEILINGS (BV-004):
+ *  - Operands are recorded as WRITTEN, relative to the invoking cwd. A
+ *    `cd subdir && git add foo.ts` records `foo.ts` while the staged path is
+ *    `subdir/foo.ts` → a miss. This is exactly the pre-#1404 behaviour (the
+ *    raw-command regex missed it too), not a new gap; revisit if a wave agent
+ *    is ever observed staging from a subdirectory.
+ *  - An ABSOLUTE operand (or an absolute `-C`) is recorded verbatim and will
+ *    not match a repo-relative staged path. Same ceiling, same trigger.
+ *  - A command the tokenizer resolves to no `git add` statement (`echo "git
+ *    add x"` — G3's documented, tolerated false positive) yields an EMPTY
+ *    list, never the marker: over-reporting here would turn a log line into a
+ *    blocked commit, which the hook's fail-safe posture forbids. This is also
+ *    why a blanket "pre-filter hit but nothing resolved → `paths: ['*']`"
+ *    floor was REJECTED at the 2026-09-20 fix: `git commit -m "add x"` matches
+ *    {@link GIT_ADD_REGEX}, and the marker overlaps EVERY staged path, so that
+ *    floor manufactures a collision for a command that stages nothing.
+ *  - A staging command a shell never executes locally is not recorded, and
+ *    should not be: `ssh host 'git add x'` stages a REMOTE index, and
+ *    `git submodule foreach "git add x"` stages the SUBMODULE's — neither can
+ *    collide with a sibling agent in this working copy.
+ *    REVISIT TRIGGER: if the commit-guard ever reconciles submodule indexes.
+ *
+ * @param {string} command
+ * @returns {Promise<{ recognised: boolean, paths: string[] }>}
+ */
+async function extractStagedPaths(command) {
+  let lib;
+  try {
+    lib = await import('../scripts/lib/command-blocker.mjs');
+  } catch {
+    return { recognised: false, paths: [] };
+  }
+
+  const paths = new Set();
+  const state = { recognised: false };
+  scanForStagedPaths(command, lib, paths, state, 0);
+  return { recognised: state.recognised, paths: [...paths] };
+}
+
+/**
+ * Collect the command lines a shell nested in this segment will EXECUTE.
+ *
+ * Two sources, unioned:
+ *  - wrapper payloads `resolveSegmentVerb` already reports (`env -S '…'`),
+ *    across both readings of an ambiguous dual parse (#1000);
+ *  - a `-c`-style operand following a {@link DASH_C_SHELLS} token ANYWHERE in
+ *    the segment, not only in resolved-verb position. The wider scan is what
+ *    covers `xargs -I{} sh -c "git add x"` and `find … -exec sh -c "…" \;`,
+ *    whose resolved verb is `xargs`/`find`; keying on the shell TOKEN instead
+ *    of the verb also keeps `grep -c <pattern>` out, because `grep` is not a
+ *    shell name.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} segment
+ * @param {{ payloads: string[], alt?: { payloads: string[] } }} resolved
+ * @returns {string[]} distinct payload strings
+ */
+function nestedShellPayloads(segment, resolved) {
+  const out = new Set();
+  for (const reading of [resolved, resolved.alt]) {
+    if (!reading) continue;
+    for (const p of reading.payloads) out.add(p);
+  }
+  for (let i = 0; i < segment.length - 1; i++) {
+    const tok = segment[i];
+    if (tok.quoted || !DASH_C_SHELLS.has(path.basename(tok.text))) continue;
+    for (let j = i + 1; j < segment.length - 1; j++) {
+      if (/^-[A-Za-z]*c$/.test(segment[j].text)) {
+        out.add(segment[j + 1].text);
+        break;
+      }
+    }
+  }
+  return [...out];
+}
+
+/**
+ * One tokenize + per-segment pass of {@link extractStagedPaths}, re-entered
+ * once per nested shell payload (bounded by {@link MAX_PAYLOAD_DEPTH}).
+ *
+ * Accumulates into the caller's `paths` set and `state.recognised` flag rather
+ * than returning, so a nested hit and a top-level hit compose:
+ * `git add a && bash -c "git add b"` records BOTH.
+ *
+ * @param {string} command
+ * @param {{ tokenizeCommand: Function, splitChainSegments: Function,
+ *           resolveSegmentVerb: Function }} lib
+ * @param {Set<string>} paths - OUT
+ * @param {{ recognised: boolean }} state - OUT
+ * @param {number} depth
+ * @returns {void}
+ */
+function scanForStagedPaths(command, lib, paths, state, depth) {
+  let segments;
+  try {
+    segments = lib.splitChainSegments(lib.tokenizeCommand(command));
+  } catch {
+    return;
+  }
+
+  for (const segment of segments) {
+    const resolved = lib.resolveSegmentVerb(segment);
+
+    // A staging command nested in `bash -c "…"` resolves to the verb `bash`,
+    // so the loop below never sees it. Before #1404 the raw-text regex matched
+    // it INSIDE the quotes and the reader's path regex found the collision;
+    // the tokenizer rewrite dropped the whole class silently (measured
+    // 2026-09-20: `bash -c "git add src/foo.ts"` → no fence file at all). The
+    // fence is cross-agent collision detection, so a miss is silent in BOTH
+    // directions — re-enter the same extraction on the payload.
+    if (depth < MAX_PAYLOAD_DEPTH) {
+      for (const payload of nestedShellPayloads(segment, resolved)) {
+        // The G3 pre-filter again, on the payload: same cheap question, same
+        // tolerated false positives, and it keeps an unrelated `-c` operand
+        // from paying for a second tokenize.
+        if (typeof payload === 'string' && GIT_ADD_REGEX.test(payload)) {
+          scanForStagedPaths(payload, lib, paths, state, depth + 1);
+        }
+      }
+    }
+
+    const { verb, index } = resolved;
+    if (verb !== 'git' || index < 0) continue;
+
+    let i = index + 1;
+    let chdir = null;
+
+    // git GLOBAL flags sit between `git` and the subcommand.
+    while (i < segment.length) {
+      const tok = segment[i];
+      if (tok.quoted || !tok.text.startsWith('-') || tok.text === '-') break;
+      if (GIT_GLOBAL_VALUE_FLAGS.has(tok.text)) {
+        if (tok.text === '-C' && i + 1 < segment.length) chdir = segment[i + 1].text;
+        i += 2;
+        continue;
+      }
+      i += 1; // boolean global flag, or attached `--git-dir=<p>`
+    }
+
+    if (i >= segment.length || segment[i].quoted || segment[i].text !== 'add') continue;
+    state.recognised = true;
+    i += 1;
+
+    let endOfFlags = false;
+    let stagesAll = false;
+
+    for (; i < segment.length; i++) {
+      const tok = segment[i];
+      const text = tok.text;
+
+      if (!endOfFlags && !tok.quoted && text.startsWith('-') && text !== '-') {
+        if (text === '--') { endOfFlags = true; continue; }
+        if (GIT_ADD_VALUE_FLAGS.has(text)) { i += 1; continue; }
+        if (text === '--pathspec-from-file' || text.startsWith('--pathspec-from-file=')) {
+          stagesAll = true;
+          if (text === '--pathspec-from-file') i += 1;
+          continue;
+        }
+        if (GIT_ADD_ALL_FLAGS.has(text)) { stagesAll = true; continue; }
+        // Short-flag cluster: `-A`, `-u`, `-An`, `-vu` all stage a set no
+        // operand names.
+        if (!text.startsWith('--') && /[Au]/.test(text.slice(1))) stagesAll = true;
+        continue;
+      }
+
+      if (text === '.' || text === './') { stagesAll = true; continue; }
+      const operand = chdir && !chdir.startsWith('/') ? `${chdir}/${text}` : text;
+      const normalised = normalizeStagedPath(operand);
+      if (normalised.length > 0) paths.add(normalised);
+    }
+
+    if (stagesAll) paths.add(ALL_PATHS_MARKER);
+  }
+}
+
 /**
  * Derive a per-agent identifier for the fence filename.
  *
@@ -136,10 +419,10 @@ function resolveProjectDir() {
  * #558 M1). The first call for a given agent_id creates the file with a
  * fresh body.
  *
- * @param {{ fenceFile: string, agentId: string, command: string }} args
+ * @param {{ fenceFile: string, agentId: string, command: string, paths: string[] }} args
  * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string }}
  */
-function appendIntent({ fenceFile, agentId, command }) {
+function appendIntent({ fenceFile, agentId, command, paths }) {
   const timestamp = new Date().toISOString();
 
   let body;
@@ -169,7 +452,14 @@ function appendIntent({ fenceFile, agentId, command }) {
     };
   }
 
-  body.staged_paths.push({ command: command.slice(0, 512), timestamp });
+  // #1404 — persist what the READER needs (path operands), never the command
+  // text: a staging command can carry a secret in a leading env assignment.
+  // The hash keeps the entry countable/groupable, mirroring enforce-commands.
+  body.staged_paths.push({
+    paths,
+    command_hash: hashCommand(command),
+    timestamp,
+  });
 
   return writeJsonAtomicSync(fenceFile, body, { tmpPrefix: '.fence.tmp' });
 }
@@ -189,12 +479,20 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
-  // G3 — regex gate. Non-`git add` commands pass through unconditionally.
+  // G3 — cheap regex PRE-FILTER. Commands that cannot possibly be a staging
+  // command pass through without loading the tokenizer.
   if (!GIT_ADD_REGEX.test(command)) return emitAllow();
 
   // G4 — context gate. Coordinator/manual commits are not fenced.
   if (!isWaveAgentContext()) return emitAllow();
 
+  // G4b — the PRECISE gate (#1404). The tokenizer, not the regex, decides
+  // whether this command really stages anything: a pre-filter hit with no
+  // resolvable `git add` statement (`git commit -m "add x"`) writes NO fence
+  // file, where the pre-#1404 hook logged its raw text.
+  const { recognised, paths } = await extractStagedPaths(command);
+  if (!recognised) return emitAllow();
+
   // G5 — derive paths.
   const projectDir = resolveProjectDir();
   const agentId = deriveAgentId();
@@ -206,7 +504,7 @@ async function main() {
   );
 
   // G6 — append intent. Never blocks the Bash call on failure.
-  const result = appendIntent({ fenceFile, agentId, command });
+  const result = appendIntent({ fenceFile, agentId, command, paths });
   if (!result.ok) {
     process.stderr.write(
       `⚠ pre-bash-staging-fence: failed to write fence file — ${result.error}\n`,
@@ -216,12 +514,18 @@ async function main() {
   return emitAllow();
 }
 
-// Top-level error handler — never let exit 1 leak. Fail-open on internal
-// errors to avoid blocking legitimate work (mirrors the destructive-guard
-// posture).
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-staging-fence: internal error — ${e?.message || e}\n`,
-  );
-  process.exit(0);
-});
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak. Fail-open on internal
+  // errors to avoid blocking legitimate work (mirrors the destructive-guard
+  // posture).
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-staging-fence: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}

package/hooks/pre-bash-templates-first.mjs

@@ -44,14 +44,10 @@ import { hasReadInSession } from './_lib/transcript-history.mjs';
 import { resolveHost, matchesBypass } from './_lib/vcs-create-matcher.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { existsSync, readdirSync, lstatSync } from 'node:fs';
 import path from 'node:path';
 
-// #519: opt-in via profile/env. Default profile "full" enables this hook;
-// minimal/off disable. SO_DISABLED_HOOKS=pre-bash-templates-first opts out
-// per session.
-if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
-
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -426,12 +422,21 @@ async function main() {
   });
 }
 
-// Top-level error handler — never let exit 1 leak. Same posture as
-// pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
-// blocking legitimate work.
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,
-  );
-  process.exit(0);
-});
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // #519: opt-in via profile/env. Default profile "full" enables this hook;
+  // minimal/off disable. SO_DISABLED_HOOKS=pre-bash-templates-first opts out
+  // per session.
+  if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak. Same posture as
+  // pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
+  // blocking legitimate work.
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}

package/hooks/pre-edit-sessions-ledger-guard.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * pre-edit-sessions-ledger-guard.mjs — PreToolUse `Edit|Write|MultiEdit` hook:
+ * denies a TOOL write into the sessions ledger
+ * (`.orchestrator/metrics/sessions.jsonl`, plus rotated `sessions.jsonl.<N>`).
+ *
+ * The sibling `pre-bash-sessions-ledger-guard.mjs` covers shell writes only; the
+ * Edit/Write/MultiEdit tools were a second, unguarded route to the same file
+ * (GitLab #1443 item 4). Editing the ledger in place skips the validating writer
+ * (`scripts/emit-session.mjs`) and can silently rewrite records that are already
+ * there — the ledger is append-only by contract.
+ *
+ * ## Fleet safety — allow is the default, deny is the exception
+ *
+ * This hook runs on EVERY Edit/Write/MultiEdit in every session on the host, so
+ * it denies exactly one thing and allows everything else, including every
+ * internal failure: empty or unparsable stdin, a missing `tool_input`, an
+ * unknown `tool_name`, an absent `file_path`, or a repo module that fails to
+ * load all exit 0 with no decision (the harness proceeds). Only a positively
+ * identified ledger path is denied.
+ *
+ * ## Path scope — narrower than the Bash guard, on purpose
+ *
+ * The Bash guard matches on BASENAME (`sessions.jsonl` in any directory), because
+ * a shell `cd .orchestrator/metrics && echo … >> sessions.jsonl` leaves only the
+ * basename to see. The Edit/Write tools always carry the full target path, so
+ * here the path must END in `.orchestrator/metrics/sessions.jsonl` (optionally
+ * `.<digits>` for a rotated archive). Tmp-dir fixtures outside a
+ * `.orchestrator/metrics/` directory, `sessions.jsonl.bak`, `learnings.jsonl` and
+ * `events.jsonl` all allow. The comparison is case-insensitive because the
+ * default macOS filesystem is: `Sessions.JSONL` there IS the ledger.
+ *
+ * Not covered (by design — a guard against the accident, not a containment
+ * boundary): a symlink that points at the ledger under another name, and the
+ * `NotebookEdit` tool (not in the matcher; it cannot target a `.jsonl` file
+ * meaningfully).
+ *
+ * Named limits (measured 2026-09-25, security review of #1443):
+ *
+ * - The TRACKED fixture `tests/fixtures/harness-audit/clean-repo/.orchestrator/
+ *   metrics/sessions.jsonl` matches the suffix and is DENIED (the Bash guard
+ *   denies it too, by basename). No `tests/fixtures/` exemption on purpose: a
+ *   path-prefix carve-out is a second hole, not a narrower guard. Editing that
+ *   fixture is intentional maintenance — run with
+ *   `SO_DISABLED_HOOKS=pre-edit-sessions-ledger-guard`.
+ * - A payload over 1 MB fails OPEN: `readStdin` (`scripts/lib/io.mjs`) rejects
+ *   past 1,048,576 bytes and the catch below allows. A whole-ledger `Write`
+ *   carries the file as `content`, so it bypasses the guard once the ledger
+ *   nears that size. Largest ledger on the reference host: 481,543 bytes
+ *   (`wc -c` over all 31 `.orchestrator/metrics/sessions.jsonl` under the
+ *   projects root). Revisit when any ledger passes ~900 KB.
+ * - The case-insensitive match can DENY a distinct file on a case-sensitive
+ *   filesystem (Linux): `.Orchestrator/METRICS/Sessions.JSONL` is not the
+ *   ledger there, but is refused. Fails closed; same override as above.
+ *
+ * ## Platforms
+ *
+ * Cursor and Pi reach this hook through their bridges
+ * (`scripts/lib/cursor-hook-bridge.mjs`, `scripts/lib/pi-hook-bridge.mjs`), which
+ * rewrite native tool names to `Edit`/`Write`/`MultiEdit` and populate
+ * `tool_input.file_path`. Codex is a documented gap in
+ * `scripts/lib/validate/check-hooks-symmetry.mjs` (no Claude tool-name vocabulary).
+ *
+ * ## Override
+ *
+ *   SO_DISABLED_HOOKS=pre-edit-sessions-ledger-guard   (session-level)
+ *   SO_HOOK_PROFILE=minimal|off
+ */
+
+import path from 'node:path';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
+
+/** This hook's name — the `SO_DISABLED_HOOKS` key. */
+const HOOK_NAME = 'pre-edit-sessions-ledger-guard';
+
+/** The tools this hook judges. Anything else allows. */
+const GUARDED_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+
+/**
+ * The ledger, or a rotated archive of it, at the END of a normalized path.
+ * Anchored on a separator (or the start) so `x.orchestrator/metrics/…` does not match.
+ */
+const LEDGER_PATH_RE = /(?:^|\/)\.orchestrator\/metrics\/sessions\.jsonl(?:\.\d+)?$/i;
+
+/**
+ * Upper bound on the echoed target in the deny reason. `emitDeny` clamps the
+ * whole reason, so an unbounded path on line 1 would push the writer/reader
+ * instructions off the end (same reasoning as the Bash guard's TARGET_ECHO_MAX).
+ */
+const TARGET_ECHO_MAX = 200;
+
+/**
+ * Does this `file_path` name the sessions ledger (or a rotated archive)?
+ *
+ * Backslashes are normalized first so a Windows-spelled path is not read as one
+ * long filename (mirrors the Bash guard's `refersToLedger`), then
+ * `path.posix.normalize` folds `..` and `//` so `metrics/../metrics/sessions.jsonl`
+ * cannot sidestep the suffix match.
+ *
+ * @param {unknown} filePath
+ * @returns {boolean}
+ */
+export function isLedgerPath(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return false;
+  const normalized = path.posix.normalize(filePath.replace(/\\/g, '/'));
+  return LEDGER_PATH_RE.test(normalized);
+}
+
+/**
+ * Read the payload and decide. Every non-ledger outcome returns without output
+ * (exit 0 = no decision = allow).
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  // Late-bound so a broken io.mjs lands in the fail-open catch below instead of
+  // an ESM link-time crash, and so the stdin reader is the repo's shared one.
+  const { readStdin, emitDeny } = await import('../scripts/lib/io.mjs');
+
+  let input;
+  try {
+    input = await readStdin();
+  } catch {
+    return; // unparsable / oversized / timed-out stdin → allow
+  }
+  if (!input || typeof input !== 'object') return;
+  if (!GUARDED_TOOLS.has(input.tool_name)) return;
+
+  const filePath = input.tool_input?.file_path;
+  if (!isLedgerPath(filePath)) return;
+
+  const shown = filePath.length > TARGET_ECHO_MAX ? `${filePath.slice(0, TARGET_ECHO_MAX)}…` : filePath;
+  emitDeny(
+    [
+      `${input.tool_name} on the sessions ledger blocked: '${shown}'`,
+      `The ledger is append-only through its validating writer:`,
+      `  node scripts/emit-session.mjs --entry '<json>'    (or pipe the JSON on stdin)`,
+      `Read or verify it without writing:`,
+      `  node scripts/check-sessions-integrity.mjs`,
+      `Editing the file in place skips schema validation and can rewrite existing records.`,
+      `Override (intentional maintenance only): run the session with`,
+      `SO_DISABLED_HOOKS=${HOOK_NAME}`,
+      `See: GitLab #1443, skills/session-end/session-metrics-write.md`,
+    ].join('\n'),
+  );
+}
+
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  if (!shouldRunHook(HOOK_NAME)) process.exit(0);
+
+  // Fail-OPEN on any internal error: exit 0 with no stdout is "no decision".
+  main()
+    .then(() => process.exit(0))
+    .catch((e) => {
+      process.stderr.write(`⚠ ${HOOK_NAME}: internal error — ${e?.message || e}\n`);
+      process.exit(0);
+    });
+}