@mmnto/cli 2.0.0 → 2.2.0

package/dist/commands/gate-install.test.js

@@ -3,10 +3,10 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { knownGateEvents, TotemError } from '@mmnto/totem';
+import { knownGates, TotemError } from '@mmnto/totem';
 import { ejectCommand } from './eject.js';
-import { gateInstallCommand, resolveGateEvents } from './gate.js';
-import { commandInstallsGate, GATE_WRAPPER_REL, installGates } from './gate-install.js';
+import { gateInstallCommand } from './gate.js';
+import { commandInstallsGate, GATE_WRAPPER_REL, installGates, } from './gate-install.js';
 import { initCommand } from './init.js';
 import { CLAUDE_GATE_WRAPPER, TOTEM_FILE_END, TOTEM_FILE_MARKER } from './init-templates.js';
 import { resolveGitRootForHookPath, resolveHooksDir } from './install-hooks.js';
@@ -60,13 +60,41 @@ function preToolUseEntries(cwd) {
     const hooks = (parsed.hooks ?? {});
     return (hooks.PreToolUse ?? []);
 }
-/** Count Write|Edit PreToolUse entries whose command references a given gate. */
+/**
+ * The `{event, matcher}` pairs the caller resolves from the core registry and
+ * hands `installGates` (mmnto-ai/totem#2799). Spelled literally here rather than
+ * read from `knownGates()` so a registry change that silently moved a gate to a
+ * different matcher would FAIL these tests instead of following them.
+ */
+const FREEZE_CHECK = { event: 'freeze-check', matcher: 'Write|Edit' };
+const TRANSPORT_SHIELD = {
+    event: 'transport-shield',
+    matcher: 'Bash|PowerShell',
+};
+/**
+ * Every PreToolUse matcher an entry installing `event` currently appears under.
+ * Matcher-AGNOSTIC by construction: a gate that leaked into a second matcher
+ * shows up here as two members, which is the invariant the #2799 tests assert.
+ */
+function matchersFor(cwd, event) {
+    const found = [];
+    for (const e of preToolUseEntries(cwd)) {
+        if (!Array.isArray(e.hooks))
+            continue;
+        for (const h of e.hooks) {
+            const cmd = typeof h === 'string' ? h : (h?.command ?? '');
+            // Collision-safe exact --event match (tier-independent).
+            if (commandInstallsGate(cmd, event))
+                found.push(e.matcher ?? '');
+        }
+    }
+    return found;
+}
+/** Count PreToolUse entries (under ANY matcher) whose command references a given gate. */
 function gateEntryCount(cwd, event) {
-    return preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit' &&
-        Array.isArray(e.hooks) &&
+    return preToolUseEntries(cwd).filter((e) => Array.isArray(e.hooks) &&
         e.hooks.some((h) => {
             const cmd = typeof h === 'string' ? h : (h?.command ?? '');
-            // Collision-safe exact --event match (tier-independent).
             return commandInstallsGate(cmd, event);
         })).length;
 }
@@ -74,7 +102,7 @@ function gateEntryCount(cwd, event) {
 function gateCommandFor(cwd, event) {
     const cmds = [];
     for (const e of preToolUseEntries(cwd)) {
-        if (e.matcher !== 'Write|Edit' || !Array.isArray(e.hooks))
+        if (!Array.isArray(e.hooks))
             continue;
         for (const h of e.hooks) {
             const cmd = typeof h === 'string' ? h : (h?.command ?? '');
@@ -97,7 +125,7 @@ describe('installGates / gate install (settings merge)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('scaffolds the wrapper and merges one PreToolUse entry per gate', () => {
-        const results = installGates(cwd, ['freeze-check']);
+        const results = installGates(cwd, [FREEZE_CHECK]);
         // wrapper scaffold + one entry merge
         expect(results.some((r) => r.file === GATE_WRAPPER_REL && r.action === 'created')).toBe(true);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
@@ -108,7 +136,7 @@ describe('installGates / gate install (settings merge)', () => {
         const wrapperPath = path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs');
         fs.mkdirSync(path.dirname(wrapperPath), { recursive: true });
         fs.writeFileSync(wrapperPath, `${TOTEM_FILE_MARKER}\nstale\n${TOTEM_FILE_END}\n`, 'utf-8');
-        const results = installGates(cwd, ['freeze-check']);
+        const results = installGates(cwd, [FREEZE_CHECK]);
         // gate install now threads the end marker, so scaffoldFile drift-repairs the bounded
         // wrapper (`refreshed`) and gate-install maps that to `merged` (a write happened).
         expect(results.find((r) => r.file === GATE_WRAPPER_REL).action).toBe('merged');
@@ -116,9 +144,9 @@ describe('installGates / gate install (settings merge)', () => {
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
     });
     it('is idempotent: a second install of the same gate is a no-op', () => {
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         const before = JSON.stringify(readSettings(cwd));
-        const second = installGates(cwd, ['freeze-check']);
+        const second = installGates(cwd, [FREEZE_CHECK]);
         const entryResult = second.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('skipped');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
@@ -127,8 +155,8 @@ describe('installGates / gate install (settings merge)', () => {
     it('keys idempotency on the per-gate command substring (distinct gates → distinct entries)', () => {
         // freeze-check installed; a hypothetical future gate keyed on a different
         // --event substring produces a SECOND entry rather than colliding.
-        installGates(cwd, ['freeze-check']);
-        installGates(cwd, ['some-future-gate']);
+        installGates(cwd, [FREEZE_CHECK]);
+        installGates(cwd, [{ event: 'some-future-gate', matcher: 'Write|Edit' }]);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateEntryCount(cwd, 'some-future-gate')).toBe(1);
         // Two distinct Write|Edit gate entries under one matcher.
@@ -147,16 +175,110 @@ describe('installGates / gate install (settings merge)', () => {
                 PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'my-hook' }] }],
             },
         }));
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         const entries = preToolUseEntries(cwd);
         expect(entries.some((e) => e.matcher === 'Bash')).toBe(true);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
     });
-    it('gateInstallCommand --all installs every known gate', async () => {
+    it('gateInstallCommand --all installs every known gate under ITS registry matcher', async () => {
         await gateInstallCommand({ all: true });
-        for (const event of knownGateEvents()) {
+        for (const { event, matcher } of knownGates()) {
+            expect(gateEntryCount(cwd, event)).toBe(1);
+            // The installed matcher is the registry's, not a shared default.
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
+        }
+    });
+});
+// ─── Per-gate matchers (mmnto-ai/totem#2799) ───────────────────────────
+//
+// Before #2799 every gate entry was written under one hardcoded `Write|Edit`
+// matcher. The registry now carries each gate's own matcher, the caller
+// resolves it (`knownGates()`), and `installGates` writes THAT — so
+// `transport-shield` lands on `Bash|PowerShell` while `freeze-check` keeps the
+// byte-identical `Write|Edit` entry it has always written.
+describe('installGates per-gate matcher (mmnto-ai/totem#2799)', () => {
+    let cwd;
+    let originalCwd;
+    const STRICT_FREEZE_ENTRY = {
+        matcher: 'Write|Edit',
+        hooks: [
+            {
+                type: 'command',
+                command: 'node .claude/hooks/gate-wrapper.cjs --event freeze-check --strict',
+            },
+        ],
+    };
+    const STRICT_TRANSPORT_ENTRY = {
+        matcher: 'Bash|PowerShell',
+        hooks: [
+            {
+                type: 'command',
+                command: 'node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict',
+            },
+        ],
+    };
+    beforeEach(() => {
+        cwd = makeTmpDir();
+        originalCwd = process.cwd();
+        process.chdir(cwd);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    });
+    it('transport-shield writes exactly ONE entry under Bash|PowerShell with the baked command', () => {
+        installGates(cwd, [TRANSPORT_SHIELD]);
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'transport-shield')).toBe('node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict');
+        // The whole emitted entry, byte for byte.
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_TRANSPORT_ENTRY]);
+    });
+    it('freeze-check writes the SAME Write|Edit entry it wrote before #2799, byte for byte', () => {
+        installGates(cwd, [FREEZE_CHECK]);
+        // The full emitted JSON entry — the regression guard on the gate whose
+        // matcher did NOT change.
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY]);
+    });
+    it('both gates together write both entries, each under its own matcher', () => {
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY, STRICT_TRANSPORT_ENTRY]);
+        expect(matchersFor(cwd, 'freeze-check')).toEqual(['Write|Edit']);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+    });
+    it('re-running both gates at the same tier is a byte-level no-op', () => {
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        const settingsPath = path.join(cwd, '.claude', 'settings.json');
+        const before = fs.readFileSync(settingsPath, 'utf-8');
+        const second = installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        expect(second.find((r) => r.event === 'freeze-check')?.action).toBe('skipped');
+        expect(second.find((r) => r.event === 'transport-shield')?.action).toBe('skipped');
+        expect(fs.readFileSync(settingsPath, 'utf-8')).toBe(before);
+    });
+    it('a tier switch updates the transport-shield entry IN PLACE under its own matcher', () => {
+        installGates(cwd, [TRANSPORT_SHIELD], 'pilot');
+        expect(gateCommandFor(cwd, 'transport-shield')).toContain('--pilot');
+        const switched = installGates(cwd, [TRANSPORT_SHIELD], 'strict');
+        expect(switched.find((r) => r.event === 'transport-shield')?.action).toBe('updated');
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        const cmd = gateCommandFor(cwd, 'transport-shield');
+        expect(cmd).toContain('--strict');
+        expect(cmd).not.toContain('--pilot');
+    });
+    it('after any sequence of INSTALLER writes, no gate appears under two matchers (hand edits are not enforced)', () => {
+        // Interleave tiers and selections — the upsert must converge on exactly one
+        // entry per gate, always under that gate's registry matcher.
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
+        installGates(cwd, [TRANSPORT_SHIELD]);
+        installGates(cwd, [TRANSPORT_SHIELD], 'pilot');
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD], 'strict');
+        installGates(cwd, [TRANSPORT_SHIELD], 'strict');
+        for (const { event, matcher } of [FREEZE_CHECK, TRANSPORT_SHIELD]) {
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
             expect(gateEntryCount(cwd, event)).toBe(1);
         }
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY, STRICT_TRANSPORT_ENTRY]);
     });
 });
 // ─── FIX A: tier-AWARE upsert (update in place, never silent no-op/dup) ──
@@ -179,17 +301,17 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('default(strict) then re-install --strict → skipped, one entry, command keeps --strict', () => {
-        installGates(cwd, ['freeze-check']); // default tier === strict
-        const second = installGates(cwd, ['freeze-check'], 'strict');
+        installGates(cwd, [FREEZE_CHECK]); // default tier === strict
+        const second = installGates(cwd, [FREEZE_CHECK], 'strict');
         const entryResult = second.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('skipped');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--strict');
     });
     it('--pilot then --strict → updated, ONE entry, command flips to --strict (not --pilot)', () => {
-        installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--pilot');
-        const switched = installGates(cwd, ['freeze-check'], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'strict');
         const entryResult = switched.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('updated');
         // Exactly one entry — no duplicate created by the tier switch.
@@ -199,8 +321,8 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         expect(cmd).not.toContain('--pilot');
     });
     it('--strict then --pilot → updated back to --pilot, one entry', () => {
-        installGates(cwd, ['freeze-check'], 'strict');
-        const switched = installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'pilot');
         const entryResult = switched.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('updated');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
@@ -242,13 +364,13 @@ describe('installGates tier-aware upsert (FIX A)', () => {
                 return c === shieldCommand;
             }));
         // Install the gate at pilot → a distinct second Write|Edit entry.
-        installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--pilot');
         expect(hasShield()).toBe(true);
         expect(preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit').length).toBe(2);
         // Tier switch → updates ONLY the gate entry in place; PreWriteShield stays.
-        const switched = installGates(cwd, ['freeze-check'], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'strict');
         expect(switched.find((r) => r.event === 'freeze-check')?.action).toBe('updated');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         const cmd2 = gateCommandFor(cwd, 'freeze-check');
@@ -258,21 +380,9 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         expect(preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit').length).toBe(2);
     });
 });
-describe('resolveGateEvents (registry-driven validation)', () => {
-    it('--all enumerates knownGateEvents()', async () => {
-        expect(await resolveGateEvents({ all: true })).toEqual(knownGateEvents());
-    });
-    it('a known --<name> resolves to itself', async () => {
-        expect(await resolveGateEvents({ name: 'freeze-check' })).toEqual(['freeze-check']);
-    });
-    it('an unknown --<name> fails loud (never default-install)', async () => {
-        await expect(resolveGateEvents({ name: 'made-up-gate' })).rejects.toBeInstanceOf(TotemError);
-        await expect(resolveGateEvents({ name: 'made-up-gate' })).rejects.toThrow(/unknown gate/i);
-    });
-    it('no --all and no --<name> fails loud (no default-install)', async () => {
-        await expect(resolveGateEvents({})).rejects.toThrow(/no gate selected/i);
-    });
-});
+// `resolveGates` (the registry-driven `{event, matcher}` resolver that replaced
+// `resolveGateEvents` in mmnto-ai/totem#2799) is covered in gate.test.ts, beside
+// the other `./gate.js` command-seam tests.
 // ─── The parameterized wrapper's disposition → exit-code map ───────────
 //
 // We render the wrapper template to a temp dir and drive it via stdin with
@@ -291,27 +401,60 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
     afterEach(() => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
-    /** Install a stub local CLI that emits a controlled verdict / exit code. */
+    /** Where the stub CLI records the argv and stdin it was spawned with (absent ⇒ never spawned). */
+    const stubRecordPath = () => path.join(cwd, 'stub-record.json');
+    /** Install a stub local CLI that records its argv + stdin and emits a controlled verdict / exit code. */
     function writeStubCli(opts) {
         const distDir = path.join(cwd, 'node_modules', '@mmnto', 'cli', 'dist');
         fs.mkdirSync(distDir, { recursive: true });
         const verdictJson = opts.verdict === undefined ? '' : JSON.stringify(opts.verdict);
         const exitCode = opts.exit ?? 0;
         // CommonJS stub (the wrapper invokes via `node <path>`); .js is fine here
-        // because there is no package.json type:module in the temp dir.
+        // because there is no package.json type:module in the temp dir. The record
+        // is what lets a test assert BOTH that a spawn happened and exactly which
+        // `gate check --event … --payload -` the wrapper projected, argv AND the
+        // stdin the payload rides on (mmnto-ai/totem#2799); `JSON.stringify` on
+        // the path handles Windows separators without a hand-written escape.
         const stub = [
             '"use strict";',
+            'const fs = require("fs");',
             `const out = ${JSON.stringify(verdictJson)};`,
+            'let stdin = "";',
+            'try { stdin = fs.readFileSync(0, "utf-8"); } catch { stdin = ""; }',
+            `fs.writeFileSync(${JSON.stringify(stubRecordPath())}, JSON.stringify({ argv: process.argv.slice(2), stdin }));`,
             'if (out) process.stdout.write(out + "\\n");',
             `process.exit(${exitCode});`,
             '',
         ].join('\n');
         fs.writeFileSync(path.join(distDir, 'index.js'), stub);
     }
+    /** What the stub CLI was spawned with, or null when the wrapper never spawned it. */
+    function stubRecord() {
+        if (!fs.existsSync(stubRecordPath()))
+            return null;
+        return JSON.parse(fs.readFileSync(stubRecordPath(), 'utf-8'));
+    }
+    /** The argv the stub CLI was spawned with, or null when the wrapper never spawned it. */
+    function stubArgv() {
+        return stubRecord()?.argv ?? null;
+    }
+    /**
+     * The payload JSON the wrapper projected, parsed (throws if it never
+     * spawned). The payload rides on the child's stdin under `--payload -` —
+     * never argv, whose win32 limit a long Bash command would exceed.
+     */
+    function spawnedPayload() {
+        const record = stubRecord();
+        expect(record, 'the wrapper never spawned the CLI').not.toBeNull();
+        const at = record.argv.indexOf('--payload');
+        expect(at).toBeGreaterThan(-1);
+        expect(record.argv[at + 1]).toBe('-');
+        return JSON.parse(record.stdin);
+    }
     /** Run the rendered wrapper with the given envelope + baked extra args. */
-    function runWrapper(envelope, extraArgs = []) {
+    function runWrapper(envelope, extraArgs = [], event = 'freeze-check') {
         const wrapperPath = path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs');
-        const res = spawnSync(process.execPath, [wrapperPath, '--event', 'freeze-check', ...extraArgs], {
+        const res = spawnSync(process.execPath, [wrapperPath, '--event', event, ...extraArgs], {
             cwd,
             input: JSON.stringify(envelope),
             encoding: 'utf-8',
@@ -321,6 +464,7 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
     }
     const EDIT_NO_SUBSYSTEM = { tool_name: 'Edit', tool_input: { file_path: 'src/foo.ts' } };
     const DECLARED = { tool_name: 'Edit', tool_input: { subsystem: 'rule-compilation' } };
+    const ALLOW_VERDICT = { disposition: 'allow', reason: 'ok', provenance: {} };
     it('allow → exit 0 (silent)', () => {
         writeStubCli({ verdict: { disposition: 'allow', reason: 'ok', provenance: {} }, exit: 0 });
         const { status } = runWrapper(DECLARED);
@@ -417,6 +561,101 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         });
         expect(res.status).toBe(0);
     });
+    // ─── Per-event payload projection (mmnto-ai/totem#2799) ────────────────
+    //
+    // The wrapper is --event-parameterized but used to build ONE freeze-check-
+    // shaped payload for every event. It now branches on the baked --event AFTER
+    // the envelope parse and the non-object guard: each gate owns its own
+    // NOT-APPLICABLE test and its own payload, and an event it cannot project
+    // fails CLOSED. The stub CLI records its argv, so "did not spawn" is an
+    // assertion about the filesystem, not an inference from the exit code.
+    const BASH_CMD = { tool_name: 'Bash', tool_input: { command: 'git status' } };
+    const PWSH_CMD = { tool_name: 'PowerShell', tool_input: { command: 'Get-ChildItem' } };
+    it('transport-shield on a Write envelope → exit 0, never spawns', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Write', tool_input: { file_path: 'src/foo.ts' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Write envelope that DECLARES a subsystem still never spawns', () => {
+        // The falsifier for the projection swap: pre-#2799 the wrapper keyed
+        // applicability on `tool_input.subsystem` for EVERY event, so this envelope
+        // shelled out with a freeze-check-shaped `{subsystem}` payload under
+        // `--event transport-shield`. Applicability is now the gate's own.
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Write', tool_input: { subsystem: 'rule-compilation' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Bash envelope with no string command → exit 0, never spawns', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Bash', tool_input: { description: 'no command field' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Bash envelope with a command spawns {tool, command, platform}', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(BASH_CMD, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toEqual(['gate', 'check', '--event', 'transport-shield', '--payload', '-']);
+        expect(spawnedPayload()).toEqual({
+            tool: 'Bash',
+            command: 'git status',
+            platform: process.platform,
+        });
+    });
+    it('a Bash command past the win32 command-line limit still reaches the gate on stdin (P3-F6)', () => {
+        // 40,000 characters: past win32's 32,767-character argv cap, where an argv
+        // payload failed the spawn with ENAMETOOLONG and fell into the fail-closed
+        // arm with nothing broken. On stdin the verdict comes back and maps to exit 0.
+        // Discriminates the fold on the windows-latest CI leg only: linux (128 KB per
+        // argument) and darwin admit a 40 KB argv, so there the pre-fold wrapper also
+        // exits 0; the stdin record assertion below is what holds on every platform.
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        /** One command-line past win32's 32,767-character cap (CreateProcess), where argv transport fails. */
+        const PAST_WIN32_ARGV_CAP = 40_000;
+        const long = 'x'.repeat(PAST_WIN32_ARGV_CAP);
+        const { status, stderr } = runWrapper({ tool_name: 'Bash', tool_input: { command: long } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stderr).not.toContain('fail-closed');
+        expect(spawnedPayload()).toEqual({ tool: 'Bash', command: long, platform: process.platform });
+    });
+    it('transport-shield on a PowerShell envelope spawns the same shape with tool PowerShell', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(PWSH_CMD, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(spawnedPayload()).toEqual({
+            tool: 'PowerShell',
+            command: 'Get-ChildItem',
+            platform: process.platform,
+        });
+    });
+    it('freeze-check is UNCHANGED: no subsystem → exit 0 without spawning', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper(EDIT_NO_SUBSYSTEM);
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('freeze-check is UNCHANGED: a declared subsystem spawns the {subsystem} payload', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(DECLARED);
+        expect(status).toBe(0);
+        expect(stubArgv()).toEqual(['gate', 'check', '--event', 'freeze-check', '--payload', '-']);
+        expect(spawnedPayload()).toEqual({ subsystem: 'rule-compilation' });
+    });
+    it('an --event the wrapper cannot project → exit 2 fail-closed, never spawns', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status, stderr } = runWrapper(BASH_CMD, [], 'nope');
+        expect(status).toBe(2);
+        expect(stderr).toContain('no payload projection for event "nope"; failing closed.');
+        expect(stubArgv()).toBeNull();
+    });
+    it('an unprojectable --event fails closed even under --pilot (tier maps dispositions only)', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(BASH_CMD, ['--pilot'], 'nope');
+        expect(status).toBe(2);
+        expect(stubArgv()).toBeNull();
+    });
 });
 // ─── eject parity ──────────────────────────────────────────────────────
 describe('eject removes the gate entry (parity with install)', () => {
@@ -433,7 +672,7 @@ describe('eject removes the gate entry (parity with install)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('scrubs the gate PreToolUse entry and the wrapper script on eject', async () => {
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
         await ejectCommand({ force: true });
@@ -449,7 +688,7 @@ describe('eject removes the gate entry (parity with install)', () => {
         fs.writeFileSync(path.join(cwd, '.claude', 'settings.json'), JSON.stringify({
             hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'mine' }] }] },
         }));
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         await ejectCommand({ force: true });
         expect(fs.existsSync(path.join(cwd, '.claude', 'settings.json'))).toBe(true);
         const entries = preToolUseEntries(cwd);
@@ -475,12 +714,19 @@ describe('init --gates= routes through the shared installer', () => {
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
     });
-    it('init --gates=all installs every known gate', async () => {
+    it('init --gates=all installs every known gate under ITS registry matcher', async () => {
         await initCommand({ bare: true, gates: 'all' });
-        for (const event of knownGateEvents()) {
+        for (const { event, matcher } of knownGates()) {
             expect(gateEntryCount(cwd, event)).toBe(1);
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
         }
     });
+    it('init --gates=transport-shield installs it under Bash|PowerShell (the pair, not a default)', async () => {
+        await initCommand({ bare: true, gates: 'transport-shield' });
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'transport-shield')).toBe('node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict');
+    });
     it('init --gates= with an unknown member fails loud', async () => {
         await expect(initCommand({ bare: true, gates: 'made-up-gate' })).rejects.toThrow(/unknown gate/i);
     });