@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/cli/policy/intercept.js

@@ -7,10 +7,11 @@ import { openLedgerSession, } from "../../policies/index.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { intercept, recordPolicyDecisionOnSession, resolveGitContext, resolveKubeContext, } from "../../runtime/index.js";
+import { buildActionEnvelope, intercept, isBlockingDecision, recordPolicyDecisionOnSession, resolveEnvironment, resolveGitContext, resolveKubeContext, sanitizeEnvelopeReason, } from "../../runtime/index.js";
 import { resolveGeneratedDir, writePendingApproval } from "../../runtime/pending-approval.js";
 import { parseBashPrefix } from "../../runtime/bash-prefix-parse.js";
-import { MAX_NORMALIZE_LENGTH, normalizeCommand, } from "../../runtime/command-normalize.js";
+import { MAX_NORMALIZE_LENGTH, normalizeCommand, normalizeCommandAmpAware, normalizeCommandQuoteAware, segmentViewOf, } from "../../runtime/command-normalize.js";
+import { extractShellCommand, SHELL_ALIASES } from "../../runtime/tool-name-aliases.js";
 import { loadManifest } from "../loader.js";
 import { checkPauseFromLoader } from "../pause-check.js";
 async function readStdin(stream) {
@@ -51,7 +52,19 @@ function hookSuffix(hookName) {
  * policy name so concurrent fires (rare but possible) stay readable.
  */
 function formatDecisionDiagnostic(decision, hookName) {
-    const header = `harness policy intercept${hookSuffix(hookName)}: ${decision.policyName}: ${decision.outcome}${decision.outcome === "warn-degraded" ? " (ledger unreachable)" : ""}`;
+    // The deny-degraded suffix names the fail_open opt-out ON PURPOSE and
+    // ONLY here: stderr is the operator's surface. The agent-facing deny
+    // envelope deliberately omits it (see the deny-degraded branch in
+    // `runtime/intercept.ts` — a deny that includes its own disable recipe
+    // is not a gate).
+    // Both degraded arms are cause-neutral: the degraded family has five
+    // causes and only one of them is the ledger; the true cause follows
+    // on the block's own `reason:` line (review 2026-08-08, rounds 3+5).
+    const header = `harness policy intercept${hookSuffix(hookName)}: ${decision.policyName}: ${decision.outcome}${decision.outcome === "warn-degraded"
+        ? " (evidence could not be evaluated; non-blocking per warn tier or fail_open opt-out)"
+        : decision.outcome === "deny-degraded"
+            ? " (evidence could not be evaluated; failing closed per enforcement tier; operator opt-out: risk.degraded_fail_posture: fail_open)"
+            : ""}`;
     const lines = [header];
     lines.push(`  ledger_tag: ${decision.ledgerTag}`);
     if (decision.requiresEval !== undefined) {
@@ -92,11 +105,13 @@ function readBashCommand(input) {
     const cmd = input.command;
     return typeof cmd === "string" && cmd.length > 0 ? cmd : null;
 }
+// Derived from `SHELL_ALIASES` rather than hand-copying its members (fix
+// round 2): `tool-name-aliases.ts`'s own header warns against the copy,
+// and since fix round 1 the precompute-matches-matcher argument above
+// depends on this set and the alias expansion agreeing. Deriving it means
+// they cannot drift apart.
 function isCodexShellTool(toolName) {
-    return (toolName === "Bash" ||
-        toolName === "shell" ||
-        toolName === "exec_command" ||
-        toolName === "functions.exec_command");
+    return typeof toolName === "string" && SHELL_ALIASES.includes(toolName);
 }
 function extractPerCallCwd(input) {
     if (!input || typeof input !== "object" || Array.isArray(input))
@@ -138,6 +153,48 @@ function resolvePolicyCwd(event, codexCommandCwd) {
     }
     return process.cwd();
 }
+// Mirrors `ENV_PRECEDENCE` in `../../runtime/environment-resolver.ts`
+// (most-dangerous-first). Kept as a local, small, duplicate table
+// instead of importing that module's private const, so this file stays
+// a read-only consumer of `resolveEnvironment`'s public API rather than
+// reaching into its internals. `unknown` is deliberately ranked lowest:
+// resolving to no signal at all must never look like an "upgrade" over
+// a branch that DID fire a resolver.
+const ENV_RANK = {
+    production: 0,
+    staging: 1,
+    dev: 2,
+    local: 3,
+    unknown: 4,
+};
+/**
+ * Branch-switch, upgrade-only merge (task 341e024b): a leading `git
+ * switch <branch>` / `git checkout <branch>` names the branch the REST
+ * of the command actually runs against, the same way a leading `cd
+ * <path>` names a different working directory (see `resolverGit`'s own
+ * comment at the call site). Unlike that `cd` merge — which fully
+ * REPLACES the git context and can move the resolved environment in
+ * EITHER direction (G5, pre-existing, out of scope for this task) —
+ * this merge is deliberately asymmetric: it only ever pushes the
+ * resolved environment to something MORE dangerous, never less.
+ *
+ * Both the base git context and the switch-target candidate (same repo
+ * / sha, only `branch` differs) are run through the SAME
+ * `resolveEnvironment` call with IDENTICAL env / kube inputs, so any
+ * difference in the result is attributable to the branch alone. The
+ * more dangerous of the two (`ENV_RANK` order) wins; a switch AWAY from
+ * a production branch never downgrades — when the candidate resolves to
+ * something equally or less dangerous, `baseGit` is returned unchanged.
+ */
+function applyBranchSwitchUpgrade(event, manifest, cwd, baseGit, branchTarget, inputs, user, host, now) {
+    if (branchTarget === null || branchTarget === baseGit.branch)
+        return baseGit;
+    const candidateGit = { ...baseGit, branch: branchTarget };
+    const effectiveNow = now ?? new Date();
+    const baseResolution = resolveEnvironment(buildActionEnvelope(event, { cwd, git: baseGit, user, host, now: effectiveNow }), manifest.environments.resolvers, inputs);
+    const candidateResolution = resolveEnvironment(buildActionEnvelope(event, { cwd, git: candidateGit, user, host, now: effectiveNow }), manifest.environments.resolvers, inputs);
+    return ENV_RANK[candidateResolution.name] < ENV_RANK[baseResolution.name] ? candidateGit : baseGit;
+}
 /**
  * Real grounding-mcp-backed ledger client. Exported for testing: the
  * `record` adapter's failure-surfacing path is exercised against a
@@ -162,6 +219,38 @@ export function realLedgerClient(server, opts) {
     const stderr = opts.stderr ?? process.stderr;
     let session = null;
     const summaryCache = new Map();
+    // One fresh-session retry for audit writes per client instance,
+    // reserved for `deny-degraded` decisions (task f1aea826, AC4; review
+    // 2026-08-08 tightened both the reservation and the budget). The
+    // pooled session carries a session-wide timeout latch: a single slow
+    // QUERY (the very condition that produces a blocking `deny-degraded`)
+    // short-circuits every later call on the same session, including the
+    // audit write for that decision — so the one row that most needs to
+    // land was guaranteed to be lost. A fresh subprocess lands it whenever
+    // grounding-mcp itself is healthy (the measured 2026-08-06 case: only
+    // the artificial 1ms query budget latched; follow-up calls answered
+    // fine).
+    //
+    // Bounds, stated precisely because the record runs on the deny path
+    // BEFORE the envelope is emitted and any stall risks the outer
+    // hook-timeout-is-allow contract: the retry is (a) reserved for
+    // decisions whose outcome is `deny-degraded` — an allow/warn row
+    // failing first must not consume it — (b) taken at most once per
+    // client instance, and (c) run on a session whose OWN timeout is
+    // `auditRetryTimeoutMs(timeoutMs)` = max(250ms, timeoutMs/4). Its two
+    // calls (initialize + ledger_add) therefore add at most
+    // 2 * max(250ms, timeoutMs/4) on top of the query's timeoutMs — that
+    // is <=timeoutMs/2 (total <=1.5x) once timeoutMs >= 1s, while below
+    // 1s the 250ms floor dominates and the ADD is bounded at 500ms
+    // absolute (review 2026-08-08 round 2: at the audit's 1-100ms probe
+    // settings that is a multiple of the query budget, but a trivial
+    // absolute cost). The fresh session replaces the latched one, so
+    // later audit writes in the same invocation inherit the working
+    // transport (and its tighter budget). If the retry also fails, the
+    // loud-stderr contract stands (audit degradation never blocks,
+    // docs/okf matrix).
+    const retryTimeoutMs = auditRetryTimeoutMs(timeoutMs);
+    let recordRetryUsed = false;
     const getSession = () => (session ??= openLedgerSession({
         mcpCommand: command,
         ...(env && { mcpEnv: env }),
@@ -172,9 +261,12 @@ export function realLedgerClient(server, opts) {
             // Cache the Promise (not the value) so concurrent queries for the
             // same session dedupe onto one in-flight round-trip. A degraded
             // result is cached too — deliberately: a first-query timeout
-            // degrades ALL K policies to warn-degraded (fail-open, matching the
-            // documented ledger-unreachable contract) instead of retrying per
-            // policy, which would reintroduce the fan-out. Staleness: our own
+            // degrades ALL K policies off the one cached round-trip instead of
+            // retrying per policy, which would reintroduce the fan-out. (What
+            // a degraded evaluation MEANS is tier-dependent since task
+            // f1aea826: warn policies stay non-blocking `warn-degraded`,
+            // block/require_approval fail closed as `deny-degraded`.)
+            // Staleness: our own
             // `record` rows are filtered out by the evaluator by design; an
             // EXTERNAL writer landing evidence mid-loop would make a later
             // policy deny where a fresh query would allow — a fail-closed,
@@ -188,7 +280,24 @@ export function realLedgerClient(server, opts) {
             return cached;
         },
         async record(decision, sessionId) {
-            const result = await recordPolicyDecisionOnSession(getSession(), decision, sessionId);
+            let result = await recordPolicyDecisionOnSession(getSession(), decision, sessionId);
+            if (!result.ok &&
+                decision.outcome === "deny-degraded" &&
+                !recordRetryUsed) {
+                // Latched-session recovery (bounds documented at retryTimeoutMs
+                // above): drop the pooled session and retry ONCE over a fresh
+                // subprocess with the tighter retry budget. Queries are
+                // unaffected — their per-session summary promise is already
+                // cached by the time any record runs.
+                recordRetryUsed = true;
+                session?.dispose();
+                session = openLedgerSession({
+                    mcpCommand: command,
+                    ...(env && { mcpEnv: env }),
+                    timeoutMs: retryTimeoutMs,
+                });
+                result = await recordPolicyDecisionOnSession(session, decision, sessionId);
+            }
             // A failed audit-write must not block the tool — the decision is
             // still applied — but it must not be silent either: an unrecorded
             // decision is invisible to `harness audit` / `explain --trace`.
@@ -203,13 +312,178 @@ export function realLedgerClient(server, opts) {
         },
     };
 }
-function degradedLedgerClient(reason) {
+/**
+ * Per-call budget of the audit-retry session (task f1aea826, review
+ * round 2): a quarter of the ledger timeout with a 250ms floor (a fresh
+ * node subprocess must cold-start + initialize within it). Exported as a
+ * pure function so the FORMULA itself is pinned by a unit test — the
+ * round-1 finding this bounds was precisely that an unbounded retry
+ * reused the full budget, and nothing would go red if that regressed.
+ */
+export function auditRetryTimeoutMs(timeoutMs) {
+    return Math.max(250, Math.floor(timeoutMs / 4));
+}
+/**
+ * Recognise a hook `command` string as an invocation of `harness policy
+ * intercept`'s subcommand, regardless of how the leading interpreter /
+ * binary token is spelled: a bare `harness policy intercept`, a node-path
+ * form (`node /abs/path/dist/cli/index.js policy intercept`, e.g. a local
+ * dev build), an `npx` form (`npx harness policy intercept`), a leading
+ * inline env-var assignment (`FOO=bar harness policy intercept` — the
+ * same shape `understanding-before-execution.ts`'s `wrap()` helper
+ * prefixes pack-contributed commands with), or a trailing flag
+ * (`harness policy intercept --hook <name>`, the tag
+ * `generate-codex-config.ts#commandWithHookTag` appends).
+ *
+ * Every OTHER call site that needs to recognise this subcommand in this
+ * codebase today (`generate-settings.ts#hookTimeoutSeconds`,
+ * `generate-codex-config.ts#commandWithHookTag`) still compares
+ * `command.trim() === "harness policy intercept"` VERBATIM — deliberately
+ * left unchanged (task d20a7e0c scope: the hook-timeout projection
+ * contract those two own is out of scope). For THEM a missed match only
+ * changes a floor/flag on a command harness itself emits byte-for-byte,
+ * so the single canonical spelling is enough. This matcher exists for a
+ * caller (the validate/doctor hook-budget-vs-ledger-timeout guard, task
+ * d20a7e0c) where under-recognition is a false NEGATIVE on a security
+ * check against an OPERATOR-authored `manifest.hooks[]` entry, which is
+ * under no obligation to spell the command exactly the way harness's own
+ * generators do.
+ *
+ * Deliberately narrow, not a shell parser: matches the two literal words
+ * `policy` and `intercept` as adjacent, whitespace-separated tokens,
+ * preceded by start-of-string / whitespace / a path separator (so
+ * `mypolicy intercept` inside one longer token cannot match) and followed
+ * by whitespace, end-of-string, or a semicolon/quote character (`;`, `"`,
+ * `'`) immediately abutting the word — the shape a chained shell command
+ * (`harness policy intercept; echo done`) or an embedded `sh -c
+ * "harness policy intercept"` wrapper produces, where nothing whitespace
+ * separates `intercept` from the next token (review 2026-08-09, fix round
+ * 1, finding 3). The quote arm accepts more than it strictly should: a
+ * quote glued directly onto the word (`intercept'or'`) also matches, even
+ * though a shell concatenates that into a different, longer identifier
+ * (`interceptor`). This is a deliberate, harmless OVER-flag — at worst a
+ * spurious validate/doctor diagnostic on an exotic command, never a missed
+ * real hook — accepted because the same quote boundary is load-bearing for
+ * the legitimate `sh -c "...intercept"` wrapper above. Still not
+ * exhaustive: a trailing `)`, `|`, `&`, or
+ * backtick immediately abutting the word (e.g. `$(harness policy
+ * intercept)`) is a KNOWN, deliberately-unclosed gap — widening further
+ * risks matching inside an unrelated longer token with no whitespace
+ * boundary at all, and the shapes above already cover the realistic
+ * manifest-authoring patterns this matcher exists for. A false negative
+ * here degrades to the pre-existing verbatim behaviour (the hook is
+ * simply not classified as ledger-consulting, so the margin check has
+ * nothing to say about it) — not a runtime bypass; the dispatch this
+ * check advises about is unaffected either way.
+ */
+export function isPolicyInterceptCommand(command) {
+    return /(?:^|[\s/\\])policy\s+intercept(?:\s|$|[;"'])/.test(command);
+}
+/**
+ * Minimum `budget_ms` a blocking, ledger-consulting hook needs to clear
+ * the worst-case wall time `realLedgerClient` (below) can spend before it
+ * writes its own fail-closed decision — derived from that function's OWN
+ * two round-trip shapes, not a measured-then-eyeballed constant. Both
+ * halves are pinned against the real client in
+ * tests/e2e/policy-intercept.test.ts ("hook-budget-ledger-margin
+ * derivation (task d20a7e0c)").
+ *
+ * SCOPE, stated precisely (review 2026-08-09, fix round 1): this is the
+ * worst case on the PURE-TIMEOUT HANG SHAPE — the shape where the
+ * `query()` call that degrades does so by tripping `LedgerSession`'s own
+ * session-wide `timedOut` latch (src/policies/ledger-client.ts), which is
+ * what lets the retry sequence below start from an INSTANT first
+ * `record()` attempt. A query() that instead degrades via a NON-timeout
+ * path — `ledger_summary` coming back a genuine JSON-RPC error, an
+ * unparseable payload, or a payload missing the `entries` shape
+ * (`querySummary`'s non-timeout `degraded` branches in
+ * src/policies/ledger-client.ts) — never sets that latch, so it falls
+ * OUTSIDE this bound. See the KNOWN RESIDUAL paragraph at the end of this
+ * comment; do not read this function, or the `checkHookBudgetLedgerMargin`
+ * diagnostic it backs, as a blanket worst-case guarantee.
+ *
+ * `T` = the ledger's own per-call budget (`health.timeout_ms`, defaulted
+ * to 5000 exactly like `realLedgerClient` itself). `R` =
+ * `auditRetryTimeoutMs(T)`, the audit-retry session's own per-call budget.
+ *
+ *   1. query() — up to 2×T. `LedgerSession.querySummary`
+ *      (src/policies/ledger-client.ts) performs `ensureInitialized()`
+ *      (the `initialize` handshake, its own T-bounded wait) and, only
+ *      once THAT resolves, the actual `ledger_summary` `tools/call` (a
+ *      SEPARATE T-bounded wait). A ledger that is merely SLOW rather than
+ *      hard-down (the threat class docs/risk-gate.md and this file's own
+ *      `deny-degraded` diagnostics already name, distinct from an
+ *      instantly-refusing one) can answer `initialize` just under T and
+ *      still time out on the following `ledger_summary` — the case a
+ *      naive "1×T" assumption undercounts.
+ *
+ *   2. the deny-degraded audit retry — up to 3×R. On the pure-timeout
+ *      hang shape, the pooled session's `timedOut` latch (tripped by the
+ *      query()-side timeout itself) makes the FIRST `record()` attempt on
+ *      it instant (see `realLedgerClient`'s own doc comment above). The
+ *      ONE reserved retry then opens a FRESH session budgeted at R and
+ *      calls `recordPolicyDecisionOnSession` (src/runtime/ledger-
+ *      record.ts), which can spend up to three independent R-bounded
+ *      round-trips before it can report success or give up: the fresh
+ *      session's own `initialize` handshake, the first `ledger_add`
+ *      attempt at `type: "policy_decision"`, and — only reached when that
+ *      attempt comes back a genuine JSON-RPC error rather than a
+ *      transport timeout (an older/incompatible grounding-mcp rejecting
+ *      the newer type) — the legacy `type: "fact"` fallback `ledger_add`.
+ *
+ * query() must complete (or degrade) before any policy decision — and so
+ * any record() — is computed (`intercept()`'s per-policy loop in
+ * src/runtime/intercept.ts awaits `evaluateOnePolicy`, which calls
+ * `ledger.query`, before it calls `ledger.record`), and the retry only
+ * starts after the first record() attempt on the pooled session already
+ * failed, so the two stages are SEQUENTIAL within one hook invocation:
+ * worst case ON THE PURE-TIMEOUT HANG SHAPE = 2T + 3R.
+ *
+ * KNOWN RESIDUAL (review 2026-08-09, fix round 1): when `query()` instead
+ * degrades via one of the NON-timeout branches named in the SCOPE
+ * paragraph above, the pooled session's `timedOut` latch is never set, so
+ * `record()`'s own first attempt is a REAL round-trip too — up to T for
+ * the `type: "policy_decision"` `ledger_add` attempt, plus another up to
+ * T for the legacy `type: "fact"` fallback if that attempt is itself
+ * rejected non-timeout — BEFORE the 3R retry sequence even starts. Worst
+ * case on this "error-then-hang" shape is therefore up to 4T + 3R, not
+ * 2T + 3R: 23750ms at the shipped T=5000 default, against this
+ * function's 13750ms. This formula is DELIBERATELY NOT raised to
+ * 4T + 3R: doing so would fail `checkHookBudgetLedgerMargin` against the
+ * shipped, reviewer-confirmed-clean fresh-init budget of 15000ms
+ * (src/cli/init/templates.ts, task 7bf47554/#414 — out of scope here) at
+ * the same T=5000 default, since 15000 < 23750. The guard this function
+ * backs GUARANTEES delivery of the fail-closed verdict on the
+ * pure-timeout hang shape, but NOT on this error-then-hang shape.
+ * Unlike an earlier draft of this note, this residual is NOT confined to
+ * one runtime projection: Claude Code and Codex both convert `budget_ms`
+ * into the outer hook-kill seconds via the identical `hookTimeoutSeconds`
+ * helper (src/cli/apply/generate-settings.ts, shared by
+ * generate-codex-config.ts) since task 7bf47554/#414, so a manifest at
+ * the shipped defaults is equally exposed on both — this was checked
+ * against both generators' current source, not assumed.
+ */
+export function requiredHookBudgetMs(ledgerTimeoutMs) {
+    return 2 * ledgerTimeoutMs + 3 * auditRetryTimeoutMs(ledgerTimeoutMs);
+}
+function degradedLedgerClient(reason, stderr, hookName) {
     return {
         async query() {
             return { kind: "degraded", reason };
         },
-        async record() {
-            /* no-op when ledger is unavailable */
+        async record(decision) {
+            // No transport exists, so no audit row can ever land. Stay silent
+            // for non-blocking rows (a manifest without grounding-mcp would
+            // otherwise emit one line per policy per tool event), but a
+            // BLOCKING decision with no audit row must not also be invisible
+            // (review 2026-08-08: previously a deny-degraded produced neither
+            // a row nor an audit-write-failed line on this path). Blocking-ness
+            // is the runtime's own isBlockingDecision — round 2 caught a third
+            // hand-rolled copy of that predicate here.
+            if (isBlockingDecision(decision)) {
+                stderr.write(`harness policy intercept${hookSuffix(hookName)}: blocking decision for ` +
+                    `${decision.policyName} has NO audit row (${reason})\n`);
+            }
         },
     };
 }
@@ -271,7 +545,7 @@ export async function runInterceptCli(opts = {}) {
         const server = findGroundingMcp(manifest);
         ledger = server
             ? realLedgerClient(server, opts)
-            : degradedLedgerClient("grounding-mcp not declared in manifest");
+            : degradedLedgerClient("grounding-mcp not declared in manifest", stderr, opts.hookName);
     }
     // For the SESSION_ID builtin we keep the empty-string fallback rather
     // than routing through resolveSessionId (which lands on "default").
@@ -303,45 +577,180 @@ export async function runInterceptCli(opts = {}) {
     // literal `preflight:`. An explicit env var still wins: it is the
     // operator's deliberate override of the derived value.
     //
-    // Deliberately CWD-ONLY, not target-directory-aware: a command that
-    // explicitly names a different repository (`git -C <B>`, `env -C
-    // <B>`, a leading `cd <B> &&`) still resolves ${REPO}/${BRANCH} from
-    // the hook's own cwd, so a preflight recorded for repo A still
-    // authorises a command that explicitly reads repo B — unchanged from
-    // the shipped 0.42.0 behaviour. A per-command target-directory
-    // resolution was built and reviewed (run
-    // 2026-07-27-gate-target-repo-resolution) but removed before shipping:
-    // three consecutive review rounds each found a different way one
-    // global `targetDir` per event leaked into the wrong evaluation (Risk
-    // Gate risk declassification; a push-gate multi-invocation fail-open;
-    // a non-git gated verb sharing a chain with a targeted git call, first
-    // via `&&`, then still open via `|` / `||`). Each fix was partial
-    // because a single per-event `targetDir` cannot express "this
-    // invocation targets repo B, but the gated verb after it runs in the
-    // caller's cwd" — the correct fix attributes a target to the SEGMENT
-    // that satisfies a policy's own trigger, which needs the policy
-    // builtins to become per-policy, not per-event. The extraction itself
-    // (`command-normalize.ts`'s `targetDir`/`targetBase`) stays in the
-    // tree, fully tested, as the foundation for that redesign — tracked as
-    // follow-up task `98ad072f`.
+    // `cwdGitContext` below is the DEFAULT / FALLBACK builtins basis, not
+    // the only one used anymore (task `98ad072f`, T-003). A command that
+    // explicitly names a different repository (`git -C <B>`, `env -C <B>`,
+    // a leading `cd <B> &&`) still resolves `builtins.REPO`/`.BRANCH` (and
+    // `currentHeadSha`, below) from THIS cwd for the majority of policies —
+    // any policy whose `requires:` doesn't reference `${REPO}`/`${BRANCH}`/
+    // `at_head` stays exactly on this cwd-only path, as does any policy
+    // whose own trigger-satisfying segment names no foreign target. Only a
+    // MATCHED policy that (a) uses `${REPO}`/`${BRANCH}`/`at_head` and (b)
+    // whose own `bash_match`-satisfying segment names a different,
+    // resolvable git repository gets a per-policy override — resolved
+    // lazily, inside `intercept()`, from the `commandSegments` view threaded
+    // below, never from this `cwdGitContext`. A prior attempt (run
+    // `2026-07-27-gate-target-repo-resolution`) tried a single global
+    // `targetDir` per event instead and was removed before shipping: three
+    // consecutive review rounds each found a different way one event-wide
+    // target leaked into the wrong evaluation (Risk Gate risk
+    // declassification; a push-gate multi-invocation fail-open; a non-git
+    // gated verb sharing a chain with a targeted git call). This
+    // `cwdGitContext` variable, and the `builtins` object built from it
+    // below, remain exactly what they were before this task — the resolved
+    // fallback every policy without a foreign attribution still uses,
+    // including the Risk Gate's own `resolverGit` further down, which
+    // this task does not touch at all.
     const cwd = resolvePolicyCwd(event, opts.codexCommandCwd);
     const cwdGitContext = resolveGitContext(cwd);
-    // Computed once here (not per-policy) so `intercept()` below can
-    // thread the SAME `NormalizedCommand` into every `bash_match` trigger
-    // check instead of each one recomputing it.
-    const normalizedCommand = event.tool_name === "Bash"
-        ? (() => {
-            const cmd = readBashCommand(event.tool_input);
-            return cmd === null ? undefined : normalizeCommand(cmd);
-        })()
-        : undefined;
+    // Computed once here (not per-policy) so `intercept()` below can thread
+    // the SAME `NormalizedCommand` into every `bash_match` trigger check
+    // instead of each one recomputing it.
+    //
+    // Fix round 1, finding F4: derive this from `extractShellCommand(event)`
+    // — the SAME function `policyMatchesEvent`'s `bash_match` branch itself
+    // calls (`src/runtime/tool-name-aliases.ts`) — instead of the narrower
+    // `event.tool_name === "Bash"` + `readBashCommand(event.tool_input)` pair
+    // this used before, which only ever looked at `tool_input.command`. A
+    // Codex shell event (`tool_name: "shell"` / `"exec_command"` /
+    // `"functions.exec_command"`, which `expandToolNameAliases` maps onto
+    // `match: "Bash"` policies) commonly carries its command under
+    // `raw_input`/`input` rather than `tool_input`, or under a `cmd` key —
+    // `extractShellCommand` reads all of those, `readBashCommand` read none
+    // of them. Before this fix such an event still reached the `bash_match`
+    // branch (via alias expansion) but with no precomputed value, so
+    // `policyMatchesEvent`'s per-policy fallback ran BOTH normalisation
+    // passes once PER MATCHING POLICY instead of once per event.
+    // `isCodexShellTool` scopes the precompute to exactly the tool-name set
+    // `SHELL_ALIASES` expands (Bash plus the three Codex shell aliases), so
+    // this does not start normalising unrelated tool calls that merely
+    // happen to carry a `command`/`cmd`-named argument for some other
+    // purpose.
+    //
+    // Fix round 2: that set is NOT, as this comment previously claimed, the
+    // only way a `match: "Bash"` policy's `bash_match` branch can be
+    // reached. `trigger.match` is a SUBSTRING test over the expanded alias
+    // list, so `BashOutput` and `KillBash` — real Claude Code tool names —
+    // satisfy `match: "Bash"` too and do reach that branch (measured: both
+    // return `policyMatchesEvent === true`). They simply fall through to
+    // the per-policy fallback here, exactly as they did before this change,
+    // so nothing is gated differently; the precompute just does not
+    // de-duplicate for them.
+    //
+    // This also makes the precomputed value and the matcher's own value
+    // PROVABLY consistent for the common case: both are now the same
+    // `extractShellCommand(event)` call, so the latent
+    // `raw_input`/`input`/`cmd` divergence `InterceptOptions.normalizedCommand`'s
+    // own JSDoc warns about (nothing verifies the threaded value came from
+    // the event's real command) can no longer actually diverge for a
+    // `tool_name` in `SHELL_ALIASES` — the one production call site
+    // (`runInterceptCli`) derives both from the identical event via the
+    // identical function. It remains an unenforced INVARIANT, not a checked
+    // one: nothing stops a future second caller from threading a mismatched
+    // value in, and `event.tool_input`/`raw_input`/`input` could still
+    // change between the moment this is read and any later read of the same
+    // event object, however unlikely in practice.
+    //
+    // TWO behavioural differences, both checked (fix round 2 corrects the
+    // prior wording, which named only the first):
+    //
+    // 1. `readBashCommand` required a NON-EMPTY string; `extractShellCommand`
+    //    accepts an empty one. An empty command now becomes
+    //    `bashCommand = ""` instead of `null`, so `normalizedCommand`
+    //    becomes a defined `normalizeCommand("") = {normalized: "",
+    //    truncated: false, ...}` instead of staying `undefined` —
+    //    behaviourally identical either way (a pure function of the empty
+    //    string, now computed once instead of falling back per policy), and
+    //    `truncated` can never be `true` for an empty string, so the
+    //    `MAX_NORMALIZE_LENGTH` stderr line just below cannot fire from it.
+    //
+    // 2. That stderr line's SCOPE widened. Under the old ternary
+    //    `bashCommand` was unconditionally `null` for any non-`Bash`
+    //    `tool_name`, so `normalizedCommand` stayed `undefined` and the
+    //    guard could never fire for a Codex shell event, nor for a command
+    //    carried under `raw_input`/`input` or a `cmd` key. Measured at
+    //    HEAD: a `tool_name: "shell"` event with a 100,001-char
+    //    `raw_input.cmd` now emits the line. The direction is
+    //    safety-positive — a previously SILENT loss of normalised-form
+    //    coverage on those events is now reported — but it is a real change
+    //    in observable output, so it is named here rather than implied.
+    const bashCommand = isCodexShellTool(event.tool_name) ? extractShellCommand(event) : null;
+    const normalizedCommand = bashCommand === null ? undefined : normalizeCommand(bashCommand);
+    // Per-segment view for `intercept()`'s per-policy attribution (task
+    // `98ad072f`, T-003) — deferred behind a memoised thunk, mirroring
+    // `ampNormalizedCommandThunk` below (D-015 fix round, run
+    // 2026-08-02-per-repo-gate-scoping-redesign, correcting this comment's
+    // own prior claim). CORRECTED: this is NOT "the same class as
+    // `normalizeCommand`'s own eager call just above" — `segmentViewOf` runs
+    // its OWN full segmentation walk over `bashCommand` (`command-
+    // normalize.ts`'s `segmentAndCanonicalize`, a SEPARATE call from the one
+    // `normalizeCommand` just made on the SAME string), and computing it
+    // unconditionally, for every Bash event, regardless of whether any
+    // policy in the manifest even uses `${REPO}`/`${BRANCH}`/`at_head`, was
+    // measured as a real, avoidable second pass — +206% at
+    // `MAX_NORMALIZE_LENGTH` (2.73 → 8.36 ms; see `segmentViewOf`'s own doc
+    // comment in `command-normalize.ts`). Threading it as a self-memoising
+    // thunk instead — the exact shape `ampNormalizedCommandThunk` below
+    // already uses for the same reason — lets `intercept()`'s
+    // `usesPerRepoBuiltins` gate decide whether the walk happens at all: a
+    // manifest with none of those policies never calls `segmentViewOf`, and
+    // a manifest that DOES still only pays the cost once per event, on
+    // first use, not once per Bash event regardless of need.
+    let commandSegmentsCache;
+    const commandSegmentsThunk = bashCommand === null
+        ? undefined
+        : () => {
+            if (commandSegmentsCache === undefined) {
+                commandSegmentsCache = segmentViewOf(bashCommand);
+            }
+            return commandSegmentsCache;
+        };
+    // Memoised thunk for the ampersand-aware SECOND normalisation pass
+    // (task aabbad63). Unlike `normalizedCommand` above — eagerly computed
+    // once per Bash event, because `policyMatchesEvent`'s first two arms
+    // may need it on every raw-miss — the amp-aware pass is consulted only
+    // as a THIRD, additional arm, and only when a policy's regex has
+    // already missed BOTH the raw command and `normalizedCommand`; most
+    // events never reach it at all. Computing it eagerly here would pay
+    // its segmentation cost on the common path for every single Bash call
+    // inside the ~1000ms hook budget, whether or not any policy ends up
+    // needing it. Wrapping it in a lazily-evaluated, self-memoising thunk
+    // instead lets `policyMatchesEvent` call it from inside the manifest-
+    // wide `matching` loop below (once per policy that still hasn't
+    // matched) while the actual segmentation work happens AT MOST ONCE per
+    // event — the same "computed once per event, not once per policy"
+    // discipline `normalizedCommand` already has, just deferred until
+    // first use instead of forced up front.
+    let ampNormalizedCommandCache;
+    const ampNormalizedCommandThunk = bashCommand === null
+        ? undefined
+        : () => (ampNormalizedCommandCache ??= normalizeCommandAmpAware(bashCommand));
+    // Memoised thunk for the quote-aware THIRD normalisation pass (task
+    // cf3dff51) — the SAME shape as `ampNormalizedCommandThunk` immediately
+    // above, for the same reason: `policyMatchesEvent`'s fourth arm calls
+    // this only when a policy's regex has already missed the raw command,
+    // `normalizedCommand`, AND the amp-aware pass, so most events never
+    // reach it at all; computing it eagerly here would pay its
+    // segmentation cost on the common path for every Bash call regardless
+    // of whether any policy ends up needing it.
+    let quoteNormalizedCommandCache;
+    const quoteNormalizedCommandThunk = bashCommand === null
+        ? undefined
+        : () => (quoteNormalizedCommandCache ??= normalizeCommandQuoteAware(bashCommand));
     // Above `MAX_NORMALIZE_LENGTH`, `normalizeCommand` skips normalisation
     // entirely and `truncated` comes back `true`. Raw matching still
-    // applies regardless (`policyMatchesEvent`'s raw-OR-normalised
-    // construction), so an oversized command only loses the ADDITIONAL
-    // normalised-form coverage — but that skip must not be silent, so one
-    // stderr line reports it here, keeping the module itself pure and
-    // I/O-free.
+    // applies regardless (`policyMatchesEvent`'s raw-OR-normalised-OR-amp-
+    // normalised-OR-quote-normalised construction), so an oversized command
+    // only loses the ADDITIONAL normalised-form coverage — but that skip
+    // must not be silent, so one stderr line reports it here, keeping the
+    // module itself pure and I/O-free. This one line also covers the
+    // amp-aware SECOND pass (`normalizeCommandAmpAware`, task `aabbad63`,
+    // fix round 1 finding F6) and the quote-aware THIRD pass
+    // (`normalizeCommandQuoteAware`, task `cf3dff51`): both share the
+    // identical `MAX_NORMALIZE_LENGTH` bound over the identical
+    // `bashCommand`, so neither one's own `truncated` can ever disagree
+    // with `normalizedCommand`'s for this call — no separate stderr line
+    // names either pass's own skip, nor does one need to.
     if (normalizedCommand?.truncated === true) {
         stderr.write(`harness policy intercept${hookSuffix(opts.hookName)}: Bash command exceeds ${MAX_NORMALIZE_LENGTH} chars; normalised-form matching skipped for this call (raw match only)\n`);
     }
@@ -364,21 +773,23 @@ export async function runInterceptCli(opts = {}) {
                 namespace: opts.kubeNamespace ?? "",
             }
             : resolveKubeContext();
-        // Two POSIX Bash idioms (`VAR=value command`, `cd <path> && command`)
-        // were invisible to the resolver before: the env resolver read
-        // `process.env` and the branch resolver read `.git/HEAD` under the
-        // hook's starting cwd, so a prod signal smuggled through either
-        // idiom silently passed the gate. Parse the leading prefix once from
-        // the Bash command and merge the result into the resolver inputs
-        // only. ${CWD} always names the hook's own cwd; ${REPO}/${BRANCH}
-        // (`cwdGitContext` above, feeding `builtins`) are cwd-only too — see
-        // the comment above `cwdGitContext`'s declaration. The Risk Gate
-        // resolver's git base, `resolverGit` below, is its own independent
-        // narrow parse: it recognises only a leading `cd`, never `git -C` /
-        // `--work-tree` / `--git-dir` / `env -C`. Bottom line: `resolverGit`
-        // must never read anything other than `cwdGitContext`, or the
-        // leading-`cd` target within THIS same narrow parse — this feeds
-        // `when:`-clause risk classification, not ledger-tag namespacing.
+        // Three POSIX Bash idioms (`VAR=value command`, `cd <path> &&
+        // command`, and — since task 341e024b — `git switch|checkout
+        // <branch> && command`) were invisible to the resolver before: the
+        // env resolver read `process.env` and the branch resolver read
+        // `.git/HEAD` under the hook's starting cwd, so a prod signal
+        // smuggled through any of the three idioms silently passed the
+        // gate. Parse the leading prefix once from the Bash command and
+        // merge the result into the resolver inputs only. ${CWD} always
+        // names the hook's own cwd; ${REPO}/${BRANCH} (`cwdGitContext`
+        // above, feeding `builtins`) are cwd-only too — see the comment
+        // above `cwdGitContext`'s declaration. The Risk Gate resolver's git
+        // base, `resolverGit` below, is its own independent narrow parse: it
+        // recognises only a leading `cd`, never `git -C` / `--work-tree` /
+        // `--git-dir` / `env -C`. Bottom line: `resolverGit` must never read
+        // anything other than `cwdGitContext`, or the leading-`cd` target
+        // within THIS same narrow parse — this feeds `when:`-clause risk
+        // classification, not ledger-tag namespacing.
         //
         // G5 (review round 2, 2026-07-27): that leading-`cd` parse is itself
         // still a live declassification lever, PRE-EXISTING and NOT changed
@@ -395,7 +806,13 @@ export async function runInterceptCli(opts = {}) {
         // branch, as in the example above) — `resolverGit` trusts whichever
         // of the two the command happens to name, with no independent check
         // that the `cd` target is the repo the destructive command actually
-        // runs against.
+        // runs against. The `git switch`/`checkout` merge added below
+        // (`gitForRisk`, via `applyBranchSwitchUpgrade`) deliberately does
+        // NOT share this bidirectional-risk shape: it is a SEPARATE,
+        // upgrade-only step layered on top of `resolverGit`, not a change to
+        // `resolverGit` itself — a switch away from a production branch can
+        // never downgrade what `resolverGit` (cwd- or cd-based) already
+        // resolved.
         const bashPrefix = event.tool_name === "Bash"
             ? (() => {
                 const cmd = readBashCommand(event.tool_input);
@@ -421,11 +838,18 @@ export async function runInterceptCli(opts = {}) {
             // win over process.env (matches POSIX `VAR=value cmd` semantics).
             return { ...base, ...bashPrefix.inlineEnv };
         })();
+        const riskUser = safeOs(() => os.userInfo().username);
+        const riskHost = safeOs(() => os.hostname());
+        // A leading `git switch`/`checkout <branch>` (task 341e024b) is
+        // merged on top of `resolverGit` above — upgrade-only, see
+        // `applyBranchSwitchUpgrade`'s own doc comment for why this one is
+        // NOT a straight replacement the way the `cd` merge is.
+        const gitForRisk = applyBranchSwitchUpgrade(event, manifest, cwd, resolverGit, bashPrefix?.branchTarget ?? null, { env: resolverEnv, kubeContext: kube.context, kubeNamespace: kube.namespace }, riskUser, riskHost, opts.now);
         riskContext = {
-            git: resolverGit,
+            git: gitForRisk,
             cwd,
-            user: safeOs(() => os.userInfo().username),
-            host: safeOs(() => os.hostname()),
+            user: riskUser,
+            host: riskHost,
             env: resolverEnv,
             kubeContext: kube.context,
             kubeNamespace: kube.namespace,
@@ -444,6 +868,11 @@ export async function runInterceptCli(opts = {}) {
             ...(cwdGitContext.sha.length > 0 && { currentHeadSha: cwdGitContext.sha }),
             ...(riskContext && { riskContext }),
             ...(normalizedCommand && { normalizedCommand }),
+            ...(ampNormalizedCommandThunk && { ampNormalizedCommandThunk }),
+            ...(quoteNormalizedCommandThunk && { quoteNormalizedCommandThunk }),
+            ...(commandSegmentsThunk && { commandSegmentsThunk }),
+            ...(process.env.HARNESS_REPO !== undefined && { repoOverridden: true }),
+            ...(process.env.HARNESS_BRANCH !== undefined && { branchOverridden: true }),
         });
     }
     finally {
@@ -458,14 +887,18 @@ export async function runInterceptCli(opts = {}) {
     // the producer side knows the live session id (it just received it on
     // the hook event), but `harness approve risk` runs from the operator's
     // `!`-shell where `$CLAUDE_SESSION_ID` is unset, so it has to read the
-    // marker. `deny` decisions are deliberately not staged: `harness approve
-    // risk` cannot unblock a `deny`, and writing a marker the verb cannot
-    // act on would just lie about the recoverability of the block. The
-    // "first blocking decision" check (rather than `.some()`) matters when
-    // two `when:`-bearing policies fire on the same event: the runtime's
-    // `intercept()` picks the first blocking decision (`runtime/intercept.ts:511`),
-    // so a `deny`-first / `require_approval`-second order produces an
-    // unrecoverable block; we mustn't stage in that case either.
+    // marker. `deny` and `deny-degraded` decisions are deliberately not
+    // staged: `harness approve risk` cannot unblock either (a deny is a
+    // real verdict, a deny-degraded means the evidence source is
+    // unreadable, so no approval tag could even be read), and writing a
+    // marker the verb cannot act on would just lie about the
+    // recoverability of the block. The "first blocking decision" check
+    // (rather than `.some()`) matters when two `when:`-bearing policies
+    // fire on the same event: the runtime's `intercept()` picks the first
+    // blocking decision (its `isBlockingDecision`, imported here so the
+    // two surfaces cannot drift — review 2026-08-08), so a blocking-first
+    // / `require_approval`-second order produces an unrecoverable block;
+    // we mustn't stage in that case either.
     //
     // Best-effort: a staging-write failure must never escalate a gate block
     // into a thrown hook error. `resolveGeneratedDir` is skipped (along
@@ -473,8 +906,7 @@ export async function runInterceptCli(opts = {}) {
     // exercise the policy logic with injected manifests and no on-disk
     // path, and the test path is also the only place an empty
     // `eventSessionId` is interesting.
-    const firstBlocking = result.decisions.find((d) => (d.outcome === "deny" && d.enforcement === "block") ||
-        d.outcome === "require_approval");
+    const firstBlocking = result.decisions.find(isBlockingDecision);
     if (result.blockJson &&
         eventSessionId !== undefined &&
         eventSessionId.length > 0 &&
@@ -509,6 +941,33 @@ export async function runInterceptCli(opts = {}) {
     if (result.decisions.length === 0 && manifest.policies.length > 0) {
         stderr.write(formatNoMatchHint(event, manifest, opts.hookName));
     }
+    // Degraded-deny operator hint. Default-verbosity, ONE line per event:
+    // the envelope deliberately tells the agent only to involve the
+    // operator, and the full diagnostic (which names the fail_open
+    // opt-out) is verbose-only — without this line an operator whose
+    // fleet wedges on a degraded ledger has no default-verbosity pointer
+    // at all (review 2026-08-08, round 2). Two deliberate properties:
+    //   - It carries the decision's OWN reason (sanitised: it can embed
+    //     grounding-mcp subprocess output) instead of asserting a ledger
+    //     fault — deny-degraded has five causes and only one of them is
+    //     the ledger; a hardcoded "ledger unreadable" sent operators of
+    //     the other four down a false doctor-path (round 3, medium).
+    //   - It does NOT name the opt-out knob: hook stderr can be surfaced
+    //     to the model in some harness configurations, so the default
+    //     channel points at the operator docs and the verbose diagnostic
+    //     instead of carrying the disable recipe (deviation from round
+    //     2's suggested fix, recorded in the run's 03-decisions.md).
+    // Suppressed under --verbose, where formatDecisionDiagnostic already
+    // prints the same reason with more context.
+    const firstDegradedDeny = result.decisions.find((d) => d.outcome === "deny-degraded");
+    if (firstDegradedDeny && !verbose) {
+        stderr.write(`harness policy intercept${hookSuffix(opts.hookName)}: ${firstDegradedDeny.policyName}: ` +
+            `deny-degraded (evidence could not be evaluated: ` +
+            `${sanitizeEnvelopeReason(firstDegradedDeny.reason)}); failing closed. ` +
+            `Operator recovery: check the reason above, then harness doctor if it names ` +
+            `the ledger; details and the availability opt-out: docs/risk-gate.md ` +
+            `("Degraded mode") or rerun with HARNESS_POLICY_VERBOSE=1\n`);
+    }
     if (verbose) {
         for (const decision of result.decisions) {
             if (decision.outcome === "allow")