@event4u/agent-config 9.16.0 → 9.18.0

package/src/scripts/_cli/handoff_sessions.ts

@@ -0,0 +1,435 @@
+/**
+ * Session enumeration for `agent-config handoff` (road-to-agent-handoff-
+ * resume Phase 1). Pure library — no CLI entry, no prompts, no writes.
+ *
+ * Sources, merged newest-first into one list:
+ *   - `chat-history`     — the cross-host JSONL log (primary; works for
+ *     every hook-capable host). Reuses `chat_history.list_sessions()`.
+ *   - `claude-transcript` — native Claude Code transcripts under
+ *     `~/.claude/projects/<slug>/*.jsonl` (fallback for sessions the log
+ *     missed; slug = cwd with `/` and `.` mapped to `-`).
+ *   - `codex-session`    — `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+ *     (Codex's ONLY source — a bundle host without hooks never writes
+ *     chat-history). Format verified 2026-08-04 against the live store:
+ *     line 0 is `{type:'session_meta', payload:{id, timestamp, cwd,
+ *     git:{branch}}}`; user prompts arrive as `event_msg` records with
+ *     `payload:{type:'user_message', message}` (fixture:
+ *     tests/scripts/fixtures/handoff/codex-session.jsonl).
+ *
+ * De-dup: native-store sessions whose platform id maps (via
+ * `derive_session_tag`) to a chat-history bucket are dropped — the
+ * chat-history entry wins.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
+
+export const DEFAULT_CAP = 15;
+const SUMMARY_SNIPPET_CHARS = 120;
+
+export type HandoffSource = 'chat-history' | 'claude-transcript' | 'codex-session';
+
+export interface HandoffSession {
+    id: string;
+    source: HandoffSource;
+    startedAt: string | null;
+    endedAt: string | null;
+    branch?: string;
+    entryCount: number;
+    summary: string;
+    /** Absolute transcript path — set for the native-store sources. */
+    transcriptPath?: string;
+}
+
+export interface ListOptions {
+    /** Repo root the sessions must belong to. Default: process.cwd(). */
+    cwd?: string;
+    /** Chat-history JSONL override (else AGENT_CHAT_HISTORY_FILE / default). */
+    chatHistoryPath?: string | null;
+    /** Claude Code projects root. Default: ~/.claude/projects. */
+    claudeProjectsRoot?: string;
+    /** Codex sessions root. Default: ~/.codex/sessions. */
+    codexSessionsRoot?: string;
+    /** Max sessions per source AND in the merged result. Default 15. */
+    cap?: number;
+}
+
+/** Mirrors the Claude Code project-dir naming: `/` and `.` → `-`. */
+export function encode_project_path(cwd: string): string {
+    return cwd.replace(/[/.]/g, '-');
+}
+
+function _snippet(text: string, max: number = SUMMARY_SNIPPET_CHARS): string {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length <= max ? oneLine : oneLine.slice(0, max - 1) + '…';
+}
+
+/** first-prompt → last-prompt summary (Step 3 contract). */
+function _summarize(first: string | null, last: string | null): string {
+    const a = first ? _snippet(first) : '';
+    const b = last ? _snippet(last) : '';
+    if (a && b && a !== b) return `${a} → ${b}`;
+    return a || b || '(no user prompts)';
+}
+
+function _read_lines(file: string): string[] {
+    try {
+        return fs.readFileSync(file, 'utf-8').split('\n');
+    } catch {
+        return [];
+    }
+}
+
+function _parse_json(line: string): Record<string, unknown> | null {
+    const trimmed = line.trim();
+    if (!trimmed) return null;
+    try {
+        const parsed = JSON.parse(trimmed) as unknown;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed as Record<string, unknown>;
+        }
+    } catch {
+        // fail-open — skip malformed lines
+    }
+    return null;
+}
+
+// ---------------------------------------------------------------------
+// chat-history (primary)
+// ---------------------------------------------------------------------
+
+const CHAT_HISTORY_REL = path.join('agents', 'runtime', '.agent-chat-history');
+
+/** Explicit option > AGENT_CHAT_HISTORY_FILE env > repo-root-relative default. */
+function _chat_history_path(opts: ListOptions): string {
+    if (opts.chatHistoryPath) return opts.chatHistoryPath;
+    return (
+        process.env.AGENT_CHAT_HISTORY_FILE ||
+        path.join(opts.cwd ?? process.cwd(), CHAT_HISTORY_REL)
+    );
+}
+
+/**
+ * Real-prompt summaries per session: hosts log system/task notifications as
+ * `t:'user'` entries, so the raw bucket summary can read like
+ * `<task-notification>…` — filtered here (council review 2026-08-04,
+ * claude-sonnet-4-5 + gpt-4o: picker noise is a UX defect; the log itself
+ * stays unfiltered).
+ */
+function _chat_history_summaries(histPath: string): Map<string, { first: string | null; last: string | null }> {
+    const bySession = new Map<string, { first: string | null; last: string | null }>();
+    let entries: Array<Record<string, unknown>>;
+    try {
+        entries = read_entries({ path: histPath, last: null });
+    } catch {
+        return bySession;
+    }
+    for (const e of entries) {
+        if (e.t !== 'user' || typeof e.text !== 'string') continue;
+        const text = e.text.trim();
+        if (!text || text.startsWith('<') || text.startsWith('Caveat:')) continue;
+        const sid = String(e.s ?? '<legacy>');
+        const slot = bySession.get(sid) ?? { first: null, last: null };
+        if (!slot.first) slot.first = text;
+        slot.last = text;
+        bySession.set(sid, slot);
+    }
+    return bySession;
+}
+
+function _chat_history_sessions(opts: ListOptions): HandoffSession[] {
+    const histPath = _chat_history_path(opts);
+    let buckets: Array<Record<string, unknown>>;
+    try {
+        buckets = list_sessions({ path: histPath, summary: true });
+    } catch {
+        return [];
+    }
+    const summaries = _chat_history_summaries(histPath);
+    return buckets
+        .filter((b) => Number(b.count ?? 0) > 0)
+        .map((b) => {
+            const id = String(b.id ?? '');
+            const prompts = summaries.get(id);
+            const summary = prompts
+                ? _summarize(prompts.first, prompts.last)
+                : '(no user prompts)';
+            return {
+                id,
+                source: 'chat-history' as const,
+                startedAt: b.first_ts ? String(b.first_ts) : null,
+                endedAt: b.last_ts ? String(b.last_ts) : null,
+                entryCount: Number(b.count ?? 0),
+                summary,
+            };
+        });
+}
+
+// ---------------------------------------------------------------------
+// claude-transcript (native fallback)
+// ---------------------------------------------------------------------
+
+interface TranscriptScan {
+    entryCount: number;
+    firstTs: string | null;
+    lastTs: string | null;
+    branch: string | null;
+    firstPrompt: string | null;
+    lastPrompt: string | null;
+}
+
+/** A real prompt has string content; tool_results arrive as block lists. */
+function _cc_prompt_text(rec: Record<string, unknown>): string | null {
+    if (rec.type !== 'user' || rec.isSidechain === true) return null;
+    const msg = rec.message;
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return null;
+    const content = (msg as Record<string, unknown>).content;
+    if (typeof content !== 'string') return null;
+    const trimmed = content.trim();
+    // skip host-injected meta blocks (caveats, command wrappers)
+    if (!trimmed || trimmed.startsWith('<') || trimmed.startsWith('Caveat:')) return null;
+    return trimmed;
+}
+
+function _scan_claude_transcript(file: string): TranscriptScan {
+    const scan: TranscriptScan = {
+        entryCount: 0,
+        firstTs: null,
+        lastTs: null,
+        branch: null,
+        firstPrompt: null,
+        lastPrompt: null,
+    };
+    for (const line of _read_lines(file)) {
+        const rec = _parse_json(line);
+        if (!rec) continue;
+        scan.entryCount += 1;
+        const ts = typeof rec.timestamp === 'string' ? rec.timestamp : null;
+        if (ts) {
+            if (!scan.firstTs) scan.firstTs = ts;
+            scan.lastTs = ts;
+        }
+        if (!scan.branch && typeof rec.gitBranch === 'string' && rec.gitBranch) {
+            scan.branch = rec.gitBranch;
+        }
+        const prompt = _cc_prompt_text(rec);
+        if (prompt) {
+            if (!scan.firstPrompt) scan.firstPrompt = prompt;
+            scan.lastPrompt = prompt;
+        }
+    }
+    return scan;
+}
+
+function _claude_transcript_sessions(opts: ListOptions, cap: number): HandoffSession[] {
+    const root = opts.claudeProjectsRoot ?? path.join(os.homedir(), '.claude', 'projects');
+    const cwd = opts.cwd ?? process.cwd();
+    const projectDir = path.join(root, encode_project_path(cwd));
+    let names: string[];
+    try {
+        names = fs.readdirSync(projectDir).filter((n) => n.endsWith('.jsonl'));
+    } catch {
+        return [];
+    }
+    const files = names
+        .map((n) => {
+            const full = path.join(projectDir, n);
+            try {
+                return { full, id: path.basename(n, '.jsonl'), mtime: fs.statSync(full).mtimeMs };
+            } catch {
+                return null;
+            }
+        })
+        .filter((f): f is { full: string; id: string; mtime: number } => f !== null)
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, cap);
+
+    const sessions: HandoffSession[] = [];
+    for (const f of files) {
+        const scan = _scan_claude_transcript(f.full);
+        if (scan.entryCount === 0) continue;
+        sessions.push({
+            id: f.id,
+            source: 'claude-transcript',
+            startedAt: scan.firstTs,
+            endedAt: scan.lastTs,
+            ...(scan.branch ? { branch: scan.branch } : {}),
+            entryCount: scan.entryCount,
+            summary: _summarize(scan.firstPrompt, scan.lastPrompt),
+            transcriptPath: f.full,
+        });
+    }
+    return sessions;
+}
+
+// ---------------------------------------------------------------------
+// codex-session (native adapter — Codex's only source)
+// ---------------------------------------------------------------------
+
+interface CodexMeta {
+    id: string;
+    timestamp: string | null;
+    cwd: string;
+    branch: string | null;
+}
+
+function _codex_meta(file: string): CodexMeta | null {
+    let firstLine = '';
+    try {
+        // metadata is always line 0 — never read the whole file here
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(8192);
+            const n = fs.readSync(fd, buf, 0, buf.length, 0);
+            firstLine = buf.toString('utf-8', 0, n).split('\n')[0] ?? '';
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+    const rec = _parse_json(firstLine);
+    if (!rec || rec.type !== 'session_meta') return null;
+    const payload = rec.payload;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+    const p = payload as Record<string, unknown>;
+    const git =
+        p.git && typeof p.git === 'object' && !Array.isArray(p.git)
+            ? (p.git as Record<string, unknown>)
+            : {};
+    return {
+        id: String(p.id ?? ''),
+        timestamp: typeof p.timestamp === 'string' ? p.timestamp : null,
+        cwd: String(p.cwd ?? ''),
+        branch: typeof git.branch === 'string' && git.branch ? git.branch : null,
+    };
+}
+
+function _codex_files(root: string): string[] {
+    const out: string[] = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) stack.push(full);
+            else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(full);
+        }
+    }
+    // rollout filenames embed the timestamp — lexicographic basename sort
+    // is chronological; newest first
+    return out.sort((a, b) => (path.basename(a) < path.basename(b) ? 1 : -1));
+}
+
+interface CodexScan {
+    entryCount: number;
+    lastTs: string | null;
+    firstPrompt: string | null;
+    lastPrompt: string | null;
+}
+
+function _codex_prompt_text(rec: Record<string, unknown>): string | null {
+    if (rec.type !== 'event_msg') return null;
+    const p = rec.payload;
+    if (!p || typeof p !== 'object' || Array.isArray(p)) return null;
+    const payload = p as Record<string, unknown>;
+    if (payload.type !== 'user_message') return null;
+    const msg = typeof payload.message === 'string' ? payload.message.trim() : '';
+    if (!msg || msg.startsWith('<')) return null; // skip injected meta blocks
+    return msg;
+}
+
+function _scan_codex_session(file: string): CodexScan {
+    const scan: CodexScan = { entryCount: 0, lastTs: null, firstPrompt: null, lastPrompt: null };
+    for (const line of _read_lines(file)) {
+        const rec = _parse_json(line);
+        if (!rec) continue;
+        scan.entryCount += 1;
+        if (typeof rec.timestamp === 'string') scan.lastTs = rec.timestamp;
+        const prompt = _codex_prompt_text(rec);
+        if (prompt) {
+            if (!scan.firstPrompt) scan.firstPrompt = prompt;
+            scan.lastPrompt = prompt;
+        }
+    }
+    return scan;
+}
+
+function _matches_repo(sessionCwd: string, repoCwd: string): boolean {
+    const norm = (p: string): string => path.resolve(p).replace(/\/+$/, '');
+    const a = norm(sessionCwd);
+    const b = norm(repoCwd);
+    return a === b || a.startsWith(b + path.sep);
+}
+
+function _codex_sessions(opts: ListOptions, cap: number): HandoffSession[] {
+    const root = opts.codexSessionsRoot ?? path.join(os.homedir(), '.codex', 'sessions');
+    const cwd = opts.cwd ?? process.cwd();
+    const matching: Array<{ file: string; meta: CodexMeta }> = [];
+    for (const file of _codex_files(root)) {
+        if (matching.length >= cap) break;
+        const meta = _codex_meta(file); // line-0 read only — cheap per file
+        if (!meta || !meta.id) continue;
+        if (!_matches_repo(meta.cwd, cwd)) continue;
+        matching.push({ file, meta });
+    }
+    const sessions: HandoffSession[] = [];
+    for (const { file, meta } of matching) {
+        const scan = _scan_codex_session(file);
+        if (scan.entryCount === 0) continue;
+        sessions.push({
+            id: meta.id,
+            source: 'codex-session',
+            startedAt: meta.timestamp,
+            endedAt: scan.lastTs ?? meta.timestamp,
+            ...(meta.branch ? { branch: meta.branch } : {}),
+            entryCount: scan.entryCount,
+            summary: _summarize(scan.firstPrompt, scan.lastPrompt),
+            transcriptPath: file,
+        });
+    }
+    return sessions;
+}
+
+// ---------------------------------------------------------------------
+// merge
+// ---------------------------------------------------------------------
+
+function _sort_key(s: HandoffSession): string {
+    return s.endedAt ?? s.startedAt ?? '';
+}
+
+/**
+ * Unified newest-first session list. Native-store sessions whose platform
+ * id maps to an existing chat-history bucket are dropped (chat-history is
+ * the primary source).
+ */
+export function list_handoff_sessions(opts: ListOptions = {}): HandoffSession[] {
+    const cap = opts.cap ?? DEFAULT_CAP;
+    const primary = _chat_history_sessions(opts);
+    const knownTags = new Set(primary.map((s) => s.id));
+
+    const native = [
+        ..._claude_transcript_sessions(opts, cap),
+        ..._codex_sessions(opts, cap),
+    ].filter((s) => {
+        try {
+            return !knownTags.has(derive_session_tag(s.id));
+        } catch {
+            return true;
+        }
+    });
+
+    return [...primary, ...native]
+        .sort((a, b) => (_sort_key(a) < _sort_key(b) ? 1 : _sort_key(a) > _sort_key(b) ? -1 : 0))
+        .slice(0, cap);
+}

package/src/scripts/_dispatch.bash

@@ -208,6 +208,15 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              router + projection freshness, host bridge status.
                              Flags: --platform <p>, --workspace <path>, --json, --strict,
                              --no-freshness
+  route:explain              Deterministic rule-routing trace for one prompt: matched
+                             triggers, tier, injected-vs-pointer disposition, budget
+                             consumption, rejected candidates. Trigger-match level only
+                             (what the host invokes is not measured).
+                             Flags: --files a,b, --profile full|balanced, --json
+  route:audit                Replay the router matcher over the last N user prompts of
+                             the chat-history log; renders matched rules per prompt.
+                             Trigger-match level only; read-only, no LLM call.
+                             Flags: --last N, --record (opt-in recorder), --weekly, --json
   hooks:replay               Replay a fixture through the universal dispatcher with
                              AGENT_CONFIG_REPLAY=1 (no writes under agents/runtime/state/).
                              Usage: hooks:replay --platform <name> --event <event>
@@ -257,6 +266,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
   analyze-session            Read-only post-session report from on-disk runtime state
+  handoff                    Pick a recent session, generate a handoff, seed a fresh session
 EOF
   fi
 
@@ -1170,6 +1180,18 @@ cmd_versions() {
 
 # `agent-config explain <config|rule|route>` — print the decision chain
 # behind a configuration or routing outcome. Read-only diagnostic; never
+# Router-matcher replay over recent chat-history prompts (read-only).
+# See scripts/_cli/cmd_route_audit.ts.
+cmd_route_audit() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_route_audit.ts" "$@"
+}
+
+# Deterministic rule-routing trace (trigger-match measurement level only).
+# See scripts/_cli/cmd_route_explain.ts.
+cmd_route_explain() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_route_explain.ts" "$@"
+}
+
 # edits state. See scripts/_cli/cmd_explain.ts.
 cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
@@ -1182,6 +1204,13 @@ cmd_analyze_session() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_analyze_session.ts" "$@"
 }
 
+# `agent-config handoff` — pick a recent session, generate a deterministic
+# handoff into agents/runtime/state/handoff-context.md, optionally --launch a
+# fresh host session. See scripts/_cli/cmd_handoff.ts.
+cmd_handoff() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_handoff.ts" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -1227,6 +1256,8 @@ main() {
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
     routing:doctor)          cmd_routing_doctor "$@" ;;
+    route:explain)           cmd_route_explain "$@" ;;
+    route:audit)             cmd_route_audit "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;
     reach:doctor)            cmd_reach_doctor "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
@@ -1255,6 +1286,7 @@ main() {
     versions)                cmd_versions "$@" ;;
     explain)                 cmd_explain "$@" ;;
     analyze-session)         cmd_analyze_session "$@" ;;
+    handoff)                 cmd_handoff "$@" ;;
     help|--help|-h|"")
       # Optional `--tier=0|1|all` filter (default 0).
       local tier_arg="0"

package/src/scripts/_lib/agent_src.ts

@@ -179,6 +179,27 @@ function _iterdirSorted(p: string): string[] {
 function _rglobSorted(root: string, pattern: string): string[] {
     const out: string[] = [];
     const suffix = pattern === '*' ? null : pattern.slice(1); // drop leading '*'
+    // Symlink confinement: every symlink (leaf or directory) must resolve
+    // inside the walk root, or it is ignored. A visited-realpath set bounds
+    // symlink cycles, and a broken symlink (realpath throws) is skipped
+    // explicitly. Without this, a directory symlink planted under a source
+    // root walks arbitrary paths outside the package and a cycle recurses
+    // until stack exhaustion (release-truth Phase 3).
+    let rootReal: string;
+    try {
+        rootReal = fs.realpathSync(root);
+    } catch {
+        return out;
+    }
+    const _confined = (p: string): string | null => {
+        try {
+            const real = fs.realpathSync(p);
+            return real === rootReal || _isUnder(real, rootReal) ? real : null;
+        } catch {
+            return null; // broken symlink → handled explicitly as "not yielded"
+        }
+    };
+    const visited = new Set<string>([rootReal]);
     const walk = (dir: string): void => {
         let entries: fs.Dirent[];
         try {
@@ -189,14 +210,21 @@ function _rglobSorted(root: string, pattern: string): string[] {
         for (const ent of entries) {
             const full = path.join(dir, ent.name);
             const matches = suffix === null ? true : ent.name.endsWith(suffix);
-            if (matches) {
+            if (matches && (!ent.isSymbolicLink() || _confined(full) !== null)) {
                 out.push(full);
             }
             // Recurse into directories. `isDirectory()` on a Dirent does not
-            // follow symlinks; pathlib.rglob follows directory symlinks. Use a
-            // stat-based dir check to match Python's traversal, but guard
-            // against unreadable entries.
-            if (ent.isDirectory() || (ent.isSymbolicLink() && _isDir(full))) {
+            // follow symlinks; pathlib.rglob follows directory symlinks. Follow
+            // a directory symlink only when its target stays inside the walk
+            // root and has not been visited yet (cycle guard).
+            if (ent.isDirectory()) {
+                walk(full);
+            } else if (ent.isSymbolicLink() && _isDir(full)) {
+                const real = _confined(full);
+                if (real === null || visited.has(real)) {
+                    continue;
+                }
+                visited.add(real);
                 walk(full);
             }
         }
@@ -432,7 +460,9 @@ export function artefact_roots(): string[] {
  *
  * Walks `_root_specs` (the leaf view). Deterministic order; deduplicated on
  * logical path so a file present in two roots during the move window is
- * yielded once. Symlinks and non-files are skipped. Mirrors `iter_artefacts`.
+ * yielded once. Non-files are skipped; symlinks are followed only when they
+ * resolve inside their walk root (external targets, broken links, and cycles
+ * are ignored). Mirrors `iter_artefacts`.
  */
 export function* iter_artefacts(suffix = '.md'): Generator<string> {
     const seen: Set<string> = new Set();

package/src/scripts/_lib/git_env.ts

@@ -0,0 +1,40 @@
+/**
+ * Environment for child `git` invocations that must resolve from their `cwd`.
+ *
+ * Git hooks export `GIT_DIR` (and often `GIT_INDEX_FILE`), and every child
+ * process inherits them. An inherited `GIT_DIR` **overrides** repository
+ * discovery, so `execFileSync('git', […], { cwd })` silently operates against
+ * the hook's repository instead of `cwd`. In a linked worktree the two differ,
+ * and the symptom is not an error but wrong data: `git log -- <path>` returns
+ * nothing, which the Gate R1 grandfather clause reads as "no pre-activation
+ * baseline" and reports as `missing_register` on every grandfathered roadmap.
+ *
+ * That made the pre-push enforcement layer fire spuriously while CI — which
+ * runs the same gate WITHOUT `GIT_DIR` — stayed green: the worst shape for a
+ * gate, since the failure looks like a content problem and the authoritative
+ * layer disagrees with the local one.
+ *
+ * Every gate in this family therefore runs git through this env: the variables
+ * that redirect discovery are removed, so `cwd` is the only thing that decides.
+ */
+
+/** Git env vars that override repository discovery and must not be inherited. */
+export const GIT_DISCOVERY_VARS: readonly string[] = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_COMMON_DIR',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+];
+
+/** `process.env` minus the discovery-overriding variables. */
+export function gitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...base };
+    for (const key of GIT_DISCOVERY_VARS) {
+        delete env[key];
+    }
+    return env;
+}

package/src/scripts/_lib/md_table.ts

@@ -0,0 +1,27 @@
+/**
+ * Markdown table-row splitting, escape-aware.
+ *
+ * Both plan-governance validators parse pipe tables whose cells legitimately
+ * contain an escaped pipe: the Risk-Register contract example writes
+ * `product \| implementation`, and findings text routinely describes unions or
+ * flags (`text\|json`). Splitting on every `|` shifts every later cell by one,
+ * so `Risk type` becomes `product \` and a findings row's `Status` becomes a
+ * fragment of its own Finding text — a spurious block with no fix except
+ * rewording the prose.
+ *
+ * One definition, imported by both validators: the same defect appearing twice
+ * is what made this a shared helper rather than a local function.
+ */
+
+/** Split on unescaped `|` only, drop the outer delimiters, unescape, trim. */
+export function splitMarkdownRow(line: string): string[] {
+    let inner = line.trim();
+    if (inner.startsWith('|')) {
+        inner = inner.slice(1);
+    }
+    // A trailing pipe is a delimiter only when it is not itself escaped.
+    if (inner.endsWith('|') && !inner.endsWith('\\|')) {
+        inner = inner.slice(0, -1);
+    }
+    return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}

package/src/scripts/_lib/planning_settings.ts

@@ -0,0 +1,43 @@
+/**
+ * Gate-R2 settings escape hatch, shared by the validator and the dispatcher.
+ *
+ * It lives here rather than in either script because BOTH R2 enforcement layers
+ * must honour it: `check_completion_review` (the gate) and
+ * `dispatch_r2_reviewer --verify` / `--verify-current` (the manifest
+ * re-derivation CI step). A reader that only the gate consulted left the second,
+ * blocking layer firing with the gate nominally switched off. `check_*` already
+ * imports the scope hash from `dispatch_*`, so putting the predicate in either
+ * one would make the import cycle back on itself.
+ *
+ * Fail-open by design: an unreadable or unparseable settings file, or a missing
+ * key, leaves the gate ACTIVE (`=== false` is the only disabling value).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+function planningFlagIsFalse(settingsDir: string, key: string): boolean {
+    const settingsPath = path.join(settingsDir, '.agent-settings.yml');
+    let raw: string;
+    try {
+        raw = fs.readFileSync(settingsPath, 'utf-8');
+    } catch {
+        return false;
+    }
+    try {
+        const parsed = parseYaml(raw) as unknown;
+        if (parsed === null || typeof parsed !== 'object') return false;
+        const planning = (parsed as Record<string, unknown>)['planning'];
+        if (planning === null || typeof planning !== 'object') return false;
+        return (planning as Record<string, unknown>)[key] === false;
+    } catch {
+        return false;
+    }
+}
+
+/** `planning.completion_review === false` in `<dir>/.agent-settings.yml`. */
+export function completionReviewDisabled(settingsDir: string): boolean {
+    return planningFlagIsFalse(settingsDir, 'completion_review');
+}