@lannguyensi/harness 0.42.0 → 0.43.0

package/dist/runtime/bash-match-facts.js

@@ -0,0 +1,194 @@
+// Live facts about FULL_TEMPLATE's shipped `bash_match` policies (task
+// `074acf5d`, run `2026-07-28-manifest-facts-drift-guard`).
+//
+// WHY THIS MODULE EXISTS: two consecutive runs shipped/attempted a defect
+// of the exact same CLASS, one day and one file apart.
+//   - Run `432db3d3` (merged 2026-07-27), HIGH: `NON_GIT_HEAD_TOKENS`
+//     (`command-normalize.ts`) covered 4 of the 8 head tokens a shipped
+//     `bash_match` policy actually gates. Closed by
+//     `tests/runtime/bash-match-head-token-drift.test.ts`, but scoped to
+//     that one set in that one file.
+//   - Run `dbc6d303` (halted 2026-07-28), CRITICAL: a NEW module's
+//     `INERT_CONSUMER_HEADS` contained `harness` — itself the gated head
+//     token of `deny-kill-switch-bypass`. The prior day's guard
+//     structurally could not see it: it only ever compared ONE named set
+//     (`NON_GIT_HEAD_TOKENS`) against the manifest, never a set someone
+//     adds tomorrow.
+// This module answers, ONE call, read live (never hand-copied): "which
+// policies declare a `bash_match`, which head token(s) each anchors on,
+// which verbs, and is token X gated by ANY of them?" — the question both
+// incidents got wrong. `src/runtime/bash-match-registry.ts` builds the
+// generalised, EVERY-registered-set guard on top of the facts this module
+// produces.
+//
+// DESIGN: literal head-token extraction straight out of an arbitrary
+// regex string is fragile (alternations, nested groups, nothing
+// guarantees a token is even a bare word) — the same reasoning the
+// migrated guard's own header carried. A CURATED classification map is
+// used instead, but it is never trusted blind: `extractBashMatchFacts`
+// verifies it against the LIVE policies passed in (call it with
+// `parseManifest(parseYaml(FULL_TEMPLATE)).policies` to get the shipped
+// ground truth) and THROWS descriptively the moment the curated map and
+// the live manifest disagree — a policy added/removed/renamed, or a
+// classified token no longer present in its policy's live pattern. A
+// caller that gets a `BashMatchFacts` back without an exception is
+// holding verified-fresh facts, not a stale copy.
+//
+// LAYERING: this module takes policies as a plain parameter and does not
+// import `FULL_TEMPLATE` itself (that lives in `src/cli/init/templates.ts`,
+// the `cli` layer — `.dependency-cruiser.cjs`'s `runtime-no-upward-imports`
+// rule forbids `runtime/` importing `cli/`). The live wiring (parsing
+// FULL_TEMPLATE and calling this module) happens in test code, which the
+// boundary check does not scan.
+//
+// WHY src/runtime/, NOT tests/ (F8, fix round): this module and
+// `bash-match-registry.ts` are a single shared source of truth that TWO
+// independent test files (`bash-match-head-token-drift.test.ts`,
+// `bash-match-registry.test.ts`) import symmetrically — a module peer
+// test files both depend on belongs beside the engine code it inspects,
+// not inside the test tree that merely happens to hold its only callers
+// today.
+/**
+ * The curated ground truth, verified fresh against FULL_TEMPLATE's live
+ * policies by `extractBashMatchFacts` every time it runs — see the module
+ * header. Keyed by policy name.
+ *
+ * "documented-uncovered" tokens (fix round 2, finding F1 on the migrated
+ * guard — see `command-normalize.ts`'s "SHIPPED BUT NOT COVERED"
+ * paragraph for why each is genuinely out of reach today, not merely
+ * unimplemented): `env`, `unset`, `tee`, `cp`.
+ */
+const CURATED_BASH_MATCH_FACTS = {
+    "review-before-merge-bash": {
+        headTokens: [{ token: "gh", class: "non-git-set" }],
+        verbs: ["merge"],
+    },
+    "dogfood-before-release": {
+        headTokens: [
+            { token: "npm", class: "non-git-set" },
+            { token: "git", class: "git" },
+        ],
+        verbs: ["publish", "tag"],
+    },
+    "preflight-before-investigation": {
+        headTokens: [{ token: "git", class: "git" }],
+        verbs: ["status", "log", "diff", "branch"],
+    },
+    "review-subagent-before-pr-create-bash": {
+        headTokens: [{ token: "gh", class: "non-git-set" }],
+        verbs: ["create"],
+    },
+    "preflight-before-push": {
+        headTokens: [{ token: "git", class: "git" }],
+        verbs: ["push"],
+    },
+    "deny-kill-switch-bypass": {
+        headTokens: [{ token: "harness", class: "non-git-set" }],
+        verbs: ["pause", "resume", "gate", "disable", "enable"],
+    },
+    "deny-session-env-strip": {
+        headTokens: [
+            { token: "env", class: "documented-uncovered" },
+            { token: "unset", class: "documented-uncovered" },
+        ],
+        // Headless trigger alternatives (the bare `<SESSION_VAR>=` form) and
+        // multiple independent alternations make a flat verb list misleading
+        // rather than merely incomplete — left empty rather than overclaim.
+        verbs: [],
+    },
+    "deny-pause-sentinel-forgery": {
+        headTokens: [
+            { token: "tee", class: "documented-uncovered" },
+            { token: "cp", class: "documented-uncovered" },
+        ],
+        // No separate "verb" beyond the head tokens themselves here.
+        verbs: [],
+    },
+};
+/**
+ * `documented-uncovered` head tokens are collected from the curated map
+ * itself (single source of truth) rather than hand-copied a second time.
+ */
+function documentedUncoveredTokens() {
+    const out = new Set();
+    for (const fact of Object.values(CURATED_BASH_MATCH_FACTS)) {
+        for (const h of fact.headTokens) {
+            if (h.class === "documented-uncovered")
+                out.add(h.token);
+        }
+    }
+    return out;
+}
+/** Exposed for callers that need the full "genuinely not covered today" list (see `bash-match-registry.ts`). */
+export const DOCUMENTED_UNCOVERED_HEAD_TOKENS = documentedUncoveredTokens();
+/**
+ * Compute verified-fresh `BashMatchFacts` from a LIVE list of parsed
+ * policies. Call with `parseManifest(parseYaml(FULL_TEMPLATE)).policies`
+ * to get the shipped ground truth (never hand-copy the patterns).
+ *
+ * Throws descriptively — the caller should let this propagate as a
+ * failing test, not swallow it — when:
+ *   1. The exact SET of policy names carrying a `bash_match` trigger in
+ *      the live `policies` differs from the curated map's key set
+ *      (a policy was added, removed, or renamed).
+ *   2. A curated head token or verb is no longer present as a standalone
+ *      word (`\bTOKEN\b`) in its policy's live pattern (renamed/removed
+ *      within an otherwise still-existing policy).
+ */
+export function extractBashMatchFacts(policies) {
+    const live = policies.filter((p) => p.trigger.bash_match !== undefined);
+    const actualNames = [...live.map((p) => p.name)].sort();
+    const curatedNames = Object.keys(CURATED_BASH_MATCH_FACTS).sort();
+    if (JSON.stringify(actualNames) !== JSON.stringify(curatedNames)) {
+        throw new Error(`bash_match facts drift: the live policies declaring a bash_match trigger (${JSON.stringify(actualNames)}) no longer match CURATED_BASH_MATCH_FACTS's classified set (${JSON.stringify(curatedNames)}) in src/runtime/bash-match-facts.ts. A policy was added, removed, or renamed — update the curated map consciously.`);
+    }
+    const byName = new Map(live.map((p) => [p.name, p]));
+    const gatedHeadTokens = new Set();
+    const classification = new Map();
+    const policyFacts = [];
+    for (const policyName of curatedNames) {
+        const curated = CURATED_BASH_MATCH_FACTS[policyName];
+        const policy = byName.get(policyName);
+        const pattern = policy.trigger.bash_match;
+        for (const { token, class: cls } of curated.headTokens) {
+            assertStandaloneWord(pattern, token, policyName);
+            gatedHeadTokens.add(token);
+            classification.set(token, cls);
+        }
+        for (const verb of curated.verbs) {
+            assertStandaloneWord(pattern, verb, policyName);
+        }
+        policyFacts.push({
+            policyName,
+            pattern,
+            headTokens: curated.headTokens,
+            verbs: curated.verbs,
+        });
+    }
+    return {
+        policyNames: actualNames,
+        policies: policyFacts,
+        gatedHeadTokens,
+        classify: (token) => classification.get(token),
+    };
+}
+function assertStandaloneWord(pattern, word, policyName) {
+    const standaloneWordRe = new RegExp(`\\b${word}\\b`);
+    if (!standaloneWordRe.test(pattern)) {
+        throw new Error(`bash_match facts drift: policy "${policyName}"'s live bash_match pattern no longer contains the classified word "${word}" as a standalone word (pattern: ${pattern}). It was renamed or removed — update CURATED_BASH_MATCH_FACTS in src/runtime/bash-match-facts.ts.`);
+    }
+}
+/**
+ * "Is `token` gated by ANY shipped `bash_match` policy?" — the one-call
+ * question both incidents got wrong. Real caller (F8, fix round):
+ * `bash-match-registry.ts`'s `checkRegisteredSets` covers-purity check,
+ * which asks this once per declared `member` of every
+ * "covers-gated-head-tokens" registration. Takes only the `gatedHeadTokens`
+ * slice of `BashMatchFacts` (not the full shape) so a caller holding the
+ * same narrowed `Pick` `checkRegisteredSets` accepts can call this directly
+ * without widening its own parameter type.
+ */
+export function isHeadTokenGated(facts, token) {
+    return facts.gatedHeadTokens.has(token);
+}
+//# sourceMappingURL=bash-match-facts.js.map

package/dist/runtime/bash-match-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-match-facts.js","sourceRoot":"","sources":["../../src/runtime/bash-match-facts.ts"],"names":[],"mappings":"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"}

package/dist/runtime/bash-match-registry.d.ts

@@ -0,0 +1,75 @@
+import type { BashMatchFacts } from "./bash-match-facts.js";
+export type RegisteredSetIntent = "covers-gated-head-tokens" | "must-not-contain-gated-head-token";
+interface RegisteredHeadTokenSetCommon {
+    /** Stable identifier, used in failure messages and by the unregistered-set scan's cross-reference. */
+    readonly id: string;
+    /** File the set is actually declared in, for failure messages. */
+    readonly module: string;
+    /** Membership test — `Set.has` or `RegExp.test`, see the module header. */
+    readonly has: (token: string) => boolean;
+    readonly description: string;
+}
+/**
+ * A "covers-gated-head-tokens" registration — the set exists so the engine
+ * RECOGNISES these head tokens. `members` is NON-OPTIONAL (fix round 2,
+ * S1): the round-1 shape had this field OPTIONAL, and
+ * `checkRegisteredSets`'s covers-purity check (c) simply `continue`d past
+ * any registration that omitted it — a new module registered as
+ * "covers-gated-head-tokens" WITHOUT `members` measurably passed the full
+ * suite (167 files / 3980 tests) even with a gated head token laundered
+ * inside its `has()` predicate. Making `members` mandatory on this arm
+ * turns that escape into a TYPE ERROR: a covers registration that omits
+ * `members` now fails `tsc`, not merely a test. See `checkRegisteredSets`
+ * checks (c), (d), (e) below for the three independent things `members`
+ * (and `has()`) are cross-checked against.
+ */
+export interface CoversHeadTokenSet extends RegisteredHeadTokenSetCommon {
+    readonly intent: "covers-gated-head-tokens";
+    readonly members: readonly string[];
+}
+/**
+ * A "must-not-contain-gated-head-token" registration — the set exists for
+ * some OTHER purpose and must never contain a token the manifest itself
+ * gates (the dbc6d303 CRITICAL shape). `members` is optional here: no
+ * purity/redundancy/predicate-purity semantics apply to this arm — only
+ * `has()` is ever asked anything (check (a)).
+ */
+export interface MustNotContainHeadTokenSet extends RegisteredHeadTokenSetCommon {
+    readonly intent: "must-not-contain-gated-head-token";
+    readonly members?: readonly string[];
+}
+/**
+ * Discriminated union on `intent` (fix round 2, S1) — see
+ * `CoversHeadTokenSet`'s doc for why the split exists.
+ */
+export type RegisteredHeadTokenSet = CoversHeadTokenSet | MustNotContainHeadTokenSet;
+export declare const REGISTERED_HEAD_TOKEN_SETS: readonly RegisteredHeadTokenSet[];
+/**
+ * Which of the five independent checks flagged this violation (fix round
+ * 2): a fixture test asserting on one check's behaviour must not be
+ * silently polluted by another check's unrelated finding on the same
+ * (setId, token) pair — see `tests/runtime/bash-match-registry.test.ts`.
+ */
+export type RegistrationCheck = "must-not-contain" | "covers-completeness" | "covers-purity" | "covers-redundancy" | "covers-predicate-purity";
+export interface RegistrationViolation {
+    readonly setId: string;
+    readonly intent: RegisteredSetIntent;
+    readonly token: string;
+    readonly check: RegistrationCheck;
+    readonly reason: string;
+}
+/**
+ * Check every registered set against the live facts. Returns an EMPTY
+ * array when clean. `registrations` and `documentedUncovered` default to
+ * the real, shipped values (F5 fix-round correction: the
+ * `documentedUncovered` default previously silently fell back to an empty
+ * set, which raised 4 FALSE violations — tee, cp, env, unset — when called
+ * with only `facts`; pinned by
+ * `tests/runtime/bash-match-head-token-drift.test.ts`'s
+ * "checkRegisteredSets(liveFacts())" defaults test) but accept fixtures —
+ * see `tests/runtime/bash-match-registry.test.ts`'s regression tests for
+ * the historical incidents, which pass deliberately-broken fixtures to
+ * prove this function catches their exact shape.
+ */
+export declare function checkRegisteredSets(facts: Pick<BashMatchFacts, "gatedHeadTokens" | "classify">, registrations?: readonly RegisteredHeadTokenSet[], documentedUncovered?: ReadonlySet<string>): RegistrationViolation[];
+export {};

package/dist/runtime/bash-match-registry.js

@@ -0,0 +1,359 @@
+// Registration point for every engine-side constant set that mirrors
+// FULL_TEMPLATE's `bash_match` facts (task `074acf5d`, run
+// `2026-07-28-manifest-facts-drift-guard`).
+//
+// WHY A REGISTRY, NOT ONE HARD-CODED COMPARISON: the guard this replaces
+// (`tests/runtime/bash-match-head-token-drift.test.ts`, pre-migration)
+// checked exactly one named set (`NON_GIT_HEAD_TOKENS`) against the
+// manifest. That guard could not see run `dbc6d303`'s `INERT_CONSUMER_HEADS`
+// (a NEW module, CRITICAL: contained `harness`, the kill-switch's own
+// gated head token) at all — it simply never looked at any set but the
+// one it was told about. `REGISTERED_HEAD_TOKEN_SETS` below is the list
+// every such set must join; `checkRegisteredSets` walks the WHOLE list
+// against the live facts, so a set registered tomorrow is checked
+// automatically, and (paired with the unregistered-set scan in
+// `tests/runtime/bash-match-head-token-drift.test.ts`) a set that is
+// NOT registered is itself a finding.
+//
+// TWO INTENTS (minimum required — see the two historical incidents this
+// run exists to close):
+//   - "covers-gated-head-tokens": the set exists so the engine recognises
+//     these head tokens (`NON_GIT_HEAD_TOKENS`'s shape). Checked for
+//     COMPLETENESS: every head token the manifest actually gates (barring
+//     a consciously `documented-uncovered` token) must be covered by AT
+//     LEAST ONE registered set with this intent — the run `432db3d3` HIGH
+//     (a covers-set spanning only 4 of 8 gated tokens) as a standing
+//     regression class.
+//   - "must-not-contain-gated-head-token": the set exists for some OTHER
+//     purpose entirely and must NEVER contain a token the manifest itself
+//     gates — the run `dbc6d303` CRITICAL's shape (an "inert consumer"
+//     allowlist that accidentally absorbed the kill-switch's own gated
+//     head token). Checked by testing every LIVE gated head token against
+//     every such registered set's `has()`.
+//
+// FIX ROUND 2 (task `074acf5d`, second fix round, findings S1/S2/S4 —
+// see `.ai/runs/2026-07-28-manifest-facts-drift-guard/03-decisions.md`
+// D-002/D-004): review round 2 MEASURED that the round-1 guard's central
+// defence — a registration's self-declared `intent` — was still
+// escapable two ways, and that the guard reproduced its own defect class
+// inside itself. Three changes close what can be made STRUCTURALLY
+// impossible (D-002/D-003 deliberately draws the line here, not at every
+// enumerable escape — see the decisions file):
+//   (S1) `RegisteredHeadTokenSet` is now a DISCRIMINATED UNION on `intent`:
+//     the "covers-gated-head-tokens" arm's `members` is NON-OPTIONAL.
+//     Omitting `members` on a covers registration — the round-1 escape,
+//     "declare no members and check (c) below never runs" — is now a
+//     COMPILE ERROR, not a test failure. The "must-not-contain" arm keeps
+//     `members` optional (no purity semantics apply to it).
+//   (S2) check (d), COVERS-REDUNDANCY, below: NARROWS — does not close —
+//     the escape where a laundered set's declared `members` are all
+//     HONESTLY gated (so check (c) is satisfied) but the set's true
+//     purpose is something else. It works only for a gated token that some
+//     covers-set legitimately covers, and is STRUCTURALLY SILENT for the
+//     `documented-uncovered` subset. MEASURED (review round 3): a
+//     registration declaring `members: ["tee"]` — or any subset of
+//     `env`/`unset`/`tee`/`cp`, four of the eight live gated head tokens —
+//     passes checks (a) through (e) with an entirely honest, live-coupled
+//     `has()` and `members`, end to end on the real tree. That is the
+//     `dbc6d303` shape (an inert allowlist absorbing a gated head token)
+//     and this registry does not see it. Redesign filed as a follow-up;
+//     see the LIMITS paragraph at the end of this header.
+//   (S4) check (e), COVERS-PREDICATE-PURITY, below: closes the escape
+//     where a registration's `has()` PREDICATE accepts more than its
+//     declared `members` claim (measured: widening `GIT_TOKEN_RE` to also
+//     match "docker" while leaving `members: ["git"]` untouched left the
+//     full suite green) — this guard reproducing, inside itself, the exact
+//     "engine-side constant mirrors manifest content with no coupling"
+//     defect class it exists to eliminate elsewhere.
+// Each violation now carries a `check` field (see `RegistrationViolation`)
+// naming exactly which of the five checks fired, so a fixture test can
+// assert on ONE check's output without an unrelated check's finding on the
+// same (setId, token) pair silently changing what the array contains.
+//
+// COVERS-PURITY (fix round, F1+F2): a THIRD check, over a "covers"
+// registration's OWN declared `members` (see `RegisteredHeadTokenSet.members`
+// below), closes two escapes with one rule — every declared member must
+// itself be a live gated head token:
+//   (F1) the REVERSE direction, ENGINE->MANIFEST: the pre-migration guard
+//     asserted this (every member of `NON_GIT_HEAD_TOKENS` must be a token
+//     some shipped policy gates) and the migration to this registry
+//     silently dropped it — completeness-checking (b) only ever walks
+//     `facts.gatedHeadTokens` outward to registered sets, never a
+//     registered set's own members inward to the facts. An engine set
+//     gaining an ungated member (e.g. "docker" added to
+//     `NON_GIT_HEAD_TOKENS`) is real DEAD CODE at best and a sign the
+//     manifest and the engine have silently diverged at worst; either way
+//     it is a regression this registry exists to catch.
+//   (F2) MIS-DECLARED INTENT: a `must-not-contain-gated-head-token` set
+//     relabeled `covers-gated-head-tokens` to dodge check (a) — cheap,
+//     because `intent` is self-declared and was, before this check,
+//     cross-checked against nothing. A set that exists for any purpose
+//     OTHER than recognising gated head tokens (an inert-consumer
+//     allowlist, say) necessarily contains members that are not
+//     themselves gated head tokens, so it fails THIS check the moment it
+//     declares `members` — the decision rule is: pick the intent that
+//     describes the set's PURPOSE; a set whose purpose is anything other
+//     than recognising gated head tokens is
+//     "must-not-contain-gated-head-token", never "covers-gated-head-tokens".
+//
+// AXIS SCOPE (F6, fix round): this registry models the HEAD-TOKEN axis
+// only — which literal head token a `bash_match` anchors on. A shipped
+// policy's `bash_match` can equally anchor on a VERB with no head-token
+// significance of its own (`pause` in `deny-kill-switch-bypass`), checked
+// today only by `HARNESS_READ_ONLY_SUBS` in `read-only-bash.ts`, a set this
+// registry does not see and does not check. The VERB axis is explicitly
+// OUT OF SCOPE for this run: the exact same defect shape (an engine-side
+// allowlist silently absorbing a gated token) is unmodellable here today,
+// one axis over. Do not assume verb coverage exists because head-token
+// coverage does.
+//
+// WHY src/runtime/, NOT tests/ (F8, fix round): see `bash-match-facts.ts`'s
+// module header — the same reasoning applies here.
+//
+// LIMITS — READ THIS BEFORE TRUSTING A REGISTRATION. Three independent
+// adversarial review passes each found a way to register a set that this
+// registry accepts but should not. Two rounds of added checks narrowed the
+// family without closing it, so the checks were frozen here deliberately
+// and the registration SURFACE is being redesigned instead (follow-up
+// task; the shape under consideration is that a registration hands the
+// registry the constant itself rather than a self-description, so a stale
+// or lying mirror cannot be expressed at all). What this registry does NOT
+// catch today, each measured end to end, not theorised:
+//   1. A covers registration whose declared `members` are all
+//      `documented-uncovered` gated tokens (`env`, `unset`, `tee`, `cp` —
+//      four of eight). Passes every check with an honest, live-coupled
+//      registration. This is the `dbc6d303` CRITICAL shape.
+//   2. A `has()` predicate that does not reflect the constant its
+//      `id`/`module` names: a stale hand-copied snapshot, or `() => false`.
+//      Nothing couples the two. The `must-not-contain` arm has no
+//      predicate check at all, and that is the arm the CRITICAL shape
+//      lives in.
+//   3. `members` declaring coverage the predicate rejects (the two are
+//      each walked in one direction, never against each other), and an
+//      empty `members: []`, which typechecks.
+//   4. A registration naming a `module`/`id` that no exported constant
+//      matches.
+// What it DOES catch is the bar it was built for and still meets: both
+// historical incidents (`432db3d3`'s covers-completeness gap and
+// `dbc6d303`'s `harness` in an inert allowlist), plus an unregistered set
+// in the runtime layer. Treat it as a tripwire for the accidental case,
+// never as a boundary against a determined one.
+//
+// TODAY'S REAL REGISTRATIONS are both "covers" sets — `GIT_TOKEN_RE` and
+// `NON_GIT_HEAD_TOKENS`, both from `command-normalize.ts`, the two sets
+// the pre-migration guard already knew about. No real
+// "must-not-contain-gated-head-token" consumer exists in this tree today
+// (run `dbc6d303`'s own module is explicit non-goal / future work for
+// THIS run) — the intent is fully implemented and covered by the fixture
+// regression tests in `tests/runtime/bash-match-registry.test.ts`
+// (reproducing the CRITICAL's exact shape) and by a live mutation probe
+// against this file's own `REGISTERED_HEAD_TOKEN_SETS` array, not against
+// a second production consumer: temporarily registering a fixture
+// (`intent: "must-not-contain-gated-head-token"`, `has` containing
+// "harness") reddens exactly "every registered engine-side set is clean
+// against the live facts ..." and the F5 defaults test in
+// `tests/runtime/bash-match-head-token-drift.test.ts`, with the violation
+// naming the fixture's own `setId` and the offending token — the probe was
+// reverted immediately after.
+//
+// `has()` rather than an enumerable `ReadonlySet<string>` uniformly for
+// checks (a) and (b): the live gated-head-token vocabulary is small and
+// fully known from `BashMatchFacts.gatedHeadTokens` (never more than ~8
+// entries), so both checks only ever need to ask "does this registered set
+// answer YES for token X", which a `RegExp.test` (`GIT_TOKEN_RE`) and a
+// `Set.has` (`NON_GIT_HEAD_TOKENS`) can equally answer. Check (c)
+// (COVERS-PURITY, above) is different in kind — it asks "does this
+// registered set contain something the facts DON'T know about", which no
+// predicate over the ~8 known tokens can answer; that is why `members` is
+// a separate, enumerable field rather than folded into `has()` — NON-
+// OPTIONAL on the "covers-gated-head-tokens" arm as of fix round 2 (S1;
+// see `CoversHeadTokenSet`'s doc), optional on "must-not-contain", which
+// this field's checks never apply to.
+import { GIT_TOKEN_RE, NON_GIT_HEAD_TOKENS } from "./command-normalize.js";
+import { DOCUMENTED_UNCOVERED_HEAD_TOKENS, isHeadTokenGated } from "./bash-match-facts.js";
+export const REGISTERED_HEAD_TOKEN_SETS = [
+    {
+        id: "GIT_TOKEN_RE",
+        module: "src/runtime/command-normalize.ts",
+        intent: "covers-gated-head-tokens",
+        has: (token) => GIT_TOKEN_RE.test(token),
+        members: ["git"],
+        description: "canonicalizeSegment's git-basename recognizer (matches `git`, and any `\\S*/git` path-qualified spelling, by basename)",
+    },
+    {
+        id: "NON_GIT_HEAD_TOKENS",
+        module: "src/runtime/command-normalize.ts",
+        intent: "covers-gated-head-tokens",
+        has: (token) => NON_GIT_HEAD_TOKENS.has(token),
+        members: [...NON_GIT_HEAD_TOKENS],
+        description: "canonicalizeSegment's closed non-git head-token set (today: gh, npm, harness)",
+    },
+];
+/**
+ * Fixed, deliberately small vocabulary of plausible NON-gated head tokens
+ * (fix round 2, S4/D-004) — commands a reasonable engine-side set might
+ * plausibly mirror or accidentally absorb, but that no shipped
+ * `bash_match` policy gates today. Combined with the live
+ * `facts.gatedHeadTokens` (every token that IS gated, verified fresh —
+ * see `bash-match-facts.ts`) this gives check (e) below a concrete probe
+ * domain to test every registered "covers" predicate against, instead of
+ * trusting a registration's declared `members` to be an honest reflection
+ * of what its `has()` actually accepts.
+ */
+const PLAUSIBLE_NON_GATED_HEAD_TOKENS = [
+    "docker",
+    "kubectl",
+    "ls",
+    "cat",
+    "node",
+    "python",
+    "make",
+    "ssh",
+];
+/**
+ * Check every registered set against the live facts. Returns an EMPTY
+ * array when clean. `registrations` and `documentedUncovered` default to
+ * the real, shipped values (F5 fix-round correction: the
+ * `documentedUncovered` default previously silently fell back to an empty
+ * set, which raised 4 FALSE violations — tee, cp, env, unset — when called
+ * with only `facts`; pinned by
+ * `tests/runtime/bash-match-head-token-drift.test.ts`'s
+ * "checkRegisteredSets(liveFacts())" defaults test) but accept fixtures —
+ * see `tests/runtime/bash-match-registry.test.ts`'s regression tests for
+ * the historical incidents, which pass deliberately-broken fixtures to
+ * prove this function catches their exact shape.
+ */
+export function checkRegisteredSets(facts, registrations = REGISTERED_HEAD_TOKEN_SETS, documentedUncovered = DOCUMENTED_UNCOVERED_HEAD_TOKENS) {
+    const violations = [];
+    // (a) must-not-contain: no registered set with this intent may answer
+    // `true` for ANY live gated head token — the dbc6d303 CRITICAL shape.
+    for (const reg of registrations) {
+        if (reg.intent !== "must-not-contain-gated-head-token")
+            continue;
+        for (const token of facts.gatedHeadTokens) {
+            if (reg.has(token)) {
+                violations.push({
+                    setId: reg.id,
+                    intent: reg.intent,
+                    token,
+                    check: "must-not-contain",
+                    reason: `"${reg.id}" (${reg.module} — ${reg.description}) declares intent "must-not-contain-gated-head-token" but contains "${token}", which IS gated by a shipped bash_match policy`,
+                });
+            }
+        }
+    }
+    // (b) covers-completeness: every gated head token NOT consciously
+    // documented as uncovered must be answered `true` by at least one
+    // registered "covers" set — the 432db3d3 HIGH shape.
+    for (const token of facts.gatedHeadTokens) {
+        if (documentedUncovered.has(token))
+            continue;
+        const covered = registrations.some((reg) => reg.intent === "covers-gated-head-tokens" && reg.has(token));
+        if (!covered) {
+            const cls = facts.classify(token);
+            violations.push({
+                setId: "(none)",
+                intent: "covers-gated-head-tokens",
+                token,
+                check: "covers-completeness",
+                reason: `gated head token "${token}" (class: ${cls ?? "unknown"}) is not covered by ANY registered "covers-gated-head-tokens" set, and is not in the documented-uncovered list either`,
+            });
+        }
+    }
+    // (c) covers-purity (fix round, F1+F2): every member a "covers" set
+    // DECLARES (see RegisteredHeadTokenSet.members) must itself be a live
+    // gated head token. Closes two escapes with one check: (1) the reverse
+    // ENGINE->MANIFEST direction the pre-migration guard checked and the
+    // migration dropped (a covers set gaining a member — e.g. "docker" —
+    // that no shipped policy gates at all); (2) the mis-declared-intent
+    // laundering escape, where a `must-not-contain-gated-head-token` set is
+    // relabeled `covers-gated-head-tokens` to dodge check (a) — a set that
+    // exists for any purpose OTHER than recognising gated head tokens
+    // necessarily contains a member that fails this check. `members` is
+    // non-optional on this arm as of fix round 2 (S1) — every registration
+    // that reaches here has one to walk.
+    for (const reg of registrations) {
+        if (reg.intent !== "covers-gated-head-tokens")
+            continue;
+        for (const member of reg.members) {
+            if (!isHeadTokenGated(facts, member)) {
+                violations.push({
+                    setId: reg.id,
+                    intent: reg.intent,
+                    token: member,
+                    check: "covers-purity",
+                    reason: `"${reg.id}" (${reg.module} — ${reg.description}) declares intent "covers-gated-head-tokens" and lists "${member}" among its members, but "${member}" is not a live gated head token (no shipped bash_match policy gates it) — pick the intent that describes the set's PURPOSE: a set that exists for any purpose OTHER than recognising gated head tokens is "must-not-contain-gated-head-token", never "covers-gated-head-tokens"`,
+                });
+            }
+        }
+    }
+    // (d) covers-redundancy (fix round 2, S2): a gated head token answered
+    // `true` by MORE THAN ONE registered "covers-gated-head-tokens" set is a
+    // violation. Closes the escape check (c) cannot: a laundered set (its
+    // TRUE purpose is something other than recognising gated head tokens,
+    // relabeled "covers-gated-head-tokens" to dodge check (a)) whose
+    // declared `members` are HONESTLY all gated — e.g. `new
+    // Set(["harness"])` or `new Set(["harness", "gh"])` — passes check (c)
+    // cleanly (every declared member IS a live gated head token). The tell
+    // is redundancy: a gated head token legitimately has exactly ONE
+    // registered "covers" set responsible for it.
+    //
+    // SCOPE OF THIS CHECK, measured, not assumed (review round 3): the tell
+    // only exists for a token some covers-set ALREADY covers. For the four
+    // `documented-uncovered` tokens (`env`, `unset`, `tee`, `cp`) no
+    // covers-set covers them by definition, so `coveringSets.length` is 1
+    // and this check is structurally silent — while check (b) skips them and
+    // checks (c)/(e) pass because they ARE gated. A laundered set declaring
+    // only those tokens therefore passes everything. Do not read this check
+    // as a completeness proof; an earlier version of this comment did, and
+    // it was false for half the live vocabulary.
+    for (const token of facts.gatedHeadTokens) {
+        const coveringSets = registrations.filter((reg) => reg.intent === "covers-gated-head-tokens" && reg.has(token));
+        if (coveringSets.length > 1) {
+            for (const reg of coveringSets) {
+                const others = coveringSets.filter((r) => r.id !== reg.id).map((r) => r.id);
+                violations.push({
+                    setId: reg.id,
+                    intent: reg.intent,
+                    token,
+                    check: "covers-redundancy",
+                    reason: `"${reg.id}" (${reg.module} — ${reg.description}) declares intent "covers-gated-head-tokens" and answers true for "${token}", but "${token}" is ALSO covered by ${others.length} other registered covers-set(s) (${others.join(", ")}) — a gated head token must be covered by exactly one registered covers-set; redundant coverage is the signature of an intent-laundered set whose declared members happen to already be genuinely gated elsewhere`,
+                });
+            }
+        }
+    }
+    // (e) covers-predicate-purity (fix round 2, S4/D-004): unlike check (c),
+    // which only inspects a registration's DECLARED `members`, this probes
+    // the registration's ACTUAL `has()` predicate directly against a fixed
+    // vocabulary — every live gated head token plus
+    // `PLAUSIBLE_NON_GATED_HEAD_TOKENS` — and demands `has(token)` answer
+    // `true` ONLY for tokens that ARE live gated head tokens. Closes the
+    // exact defect class this run exists to eliminate, reproduced INSIDE
+    // this guard: a predicate-based registration (`GIT_TOKEN_RE.test`)
+    // paired with a hand-written `members` list that check (c) verifies but
+    // the predicate ITSELF is never re-checked against — measured (D-004):
+    // widening `GIT_TOKEN_RE` to also match "docker" while leaving
+    // `members: ["git"]` untouched left the full suite green before this
+    // check existed.
+    const probeVocabulary = new Set([
+        ...facts.gatedHeadTokens,
+        ...PLAUSIBLE_NON_GATED_HEAD_TOKENS,
+    ]);
+    for (const reg of registrations) {
+        if (reg.intent !== "covers-gated-head-tokens")
+            continue;
+        for (const token of probeVocabulary) {
+            if (reg.has(token) && !isHeadTokenGated(facts, token)) {
+                violations.push({
+                    setId: reg.id,
+                    intent: reg.intent,
+                    token,
+                    check: "covers-predicate-purity",
+                    reason: `"${reg.id}" (${reg.module} — ${reg.description}) declares intent "covers-gated-head-tokens" and its has() predicate answers true for "${token}", but "${token}" is not a live gated head token — the predicate accepts more than its declared members claim, reproducing this run's own defect class (an engine-side predicate mirroring manifest content with no coupling) inside the guard itself`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=bash-match-registry.js.map