@dalzoubi/dev-agents-sync 2.0.25 → 2.0.26

package/tests/hook-retirement.test.mjs

@@ -0,0 +1,684 @@
+/**
+ * tests/hook-retirement.test.mjs
+ *
+ * Slice S1 (retire-rules-injector-hook) — CLI de-registration migration tests.
+ * Spec: docs/specs/260724-opus5-native-overlap/ ("Hook de-registration
+ * (prerequisite for S1)"). Plan: docs/specs/260724-opus5-native-overlap/plan.md
+ * ("Hook de-registration (S1, CLI)").
+ *
+ * These tests are written RED-first. `RETIRED_HOOK_SCRIPTS` does not exist in
+ * src/settings.mjs yet, and `computeMerge`/`mergeHookSettings` is purely
+ * additive today — it has no prune branch. They FAIL now and go GREEN once
+ * the implement agent adds the append-only `RETIRED_HOOK_SCRIPTS` list and
+ * extends the merge into a merge-then-prune pass, per plan.md.
+ *
+ * Behavior-anchored (§7): each criterion below maps to a named test that
+ * would fail if the behavior broke.
+ *
+ *  P1. A settings.json carrying the marker-managed (HOOK_TAG-tagged)
+ *      SessionStart -> rules-injector.sh entry has that entry pruned by
+ *      mergeHookSettings.
+ *  P2. A consumer-authored (untagged) entry for the SAME retired command
+ *      survives the prune untouched, byte-for-byte, even when a tagged
+ *      managed entry for that same command sits alongside it on the same
+ *      event. This is the reversibility crux — the prune must never touch
+ *      unmanaged or consumer-owned state.
+ *  P3. A consumer with no such entry anywhere sees literally no change:
+ *      the file stays byte-identical and the merge reports no change.
+ *  P4. Pruning is idempotent — running the merge twice against the same
+ *      fixture leaves the settings identical after the first and second
+ *      calls, and the second call reports nothing left to prune.
+ *  P5. --dry-run reports the prune (via the merge result) but writes
+ *      nothing — the file on disk stays byte-identical.
+ *  P6. The other three managed hooks (steering-injector.sh,
+ *      managed-file-guard.sh, uncommitted-check.sh) — on three DIFFERENT
+ *      events — are untouched by the prune: same tag, same matcher, same
+ *      command, before and after.
+ *
+ * ASSUMED src/settings.mjs INTERFACE (for the implement agent to match; this
+ * is the intended public surface per plan.md's "Hook de-registration (S1, CLI)"
+ * section, not yet implemented):
+ *
+ *   export const RETIRED_HOOK_SCRIPTS: { event: string, matcher: string, command: string }[]
+ *     Append-only. Its first entry targets `.claude/hooks/rules-injector.sh`.
+ *
+ *   mergeHookSettings(consumerCwd, hookScripts, opts?)
+ *     Existing additive-merge contract is UNCHANGED and extended, not
+ *     replaced: it still appends any hookScripts entry that is absent. NEW:
+ *     after the additive pass, it also PRUNES any settings entry that (a)
+ *     carries HOOK_TAG === true AND (b) has a hooks[].command matching a
+ *     command in RETIRED_HOOK_SCRIPTS — regardless of which event bucket it
+ *     lives under, and regardless of whether that command also appears in
+ *     the `hookScripts` argument. Untagged (consumer-authored) entries are
+ *     NEVER pruned, even when their command matches a retired one.
+ *     Returns { merged, dryRun, settingsPath, prunedRetired }:
+ *       prunedRetired: string[] — the retired commands actually removed by
+ *       this call. Always an array (empty when nothing was pruned), present
+ *       on every call including no-op ones, so a caller/test can tell "no
+ *       retired entries existed" apart from "retirement isn't supported."
+ *       `merged` is true if EITHER the additive merge OR the prune changed
+ *       the settings object.
+ *
+ * `RETIRED_HOOK_SCRIPTS` is imported dynamically (not via a static named
+ * import) so a still-missing export surfaces as a readable assertion failure
+ * ("RETIRED_HOOK_SCRIPTS must be a non-empty array...") rather than a
+ * module-load SyntaxError that would abort every test in this file with an
+ * opaque failure unrelated to the specific behavior under test.
+ *
+ * Test runner: `node --test packages/dev-agents-sync/tests/hook-retirement.test.mjs`
+ * No third-party dependencies. All tests use isolated tmp dirs.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { mergeHookSettings, HOOK_TAG } from '../src/settings.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Lazy import of RETIRED_HOOK_SCRIPTS — see the file header for why this is
+// dynamic rather than a static named import.
+// ---------------------------------------------------------------------------
+
+let _settingsMod = null;
+async function importSettings() {
+  if (_settingsMod) return _settingsMod;
+  _settingsMod = await import('../src/settings.mjs');
+  return _settingsMod;
+}
+
+const RETIRED_COMMAND = '.claude/hooks/rules-injector.sh';
+
+/**
+ * The intended POST-S1 caller-supplied hookScripts list — i.e. what a fixed
+ * DEFAULT_HOOK_SCRIPTS should look like once rules-injector.sh is removed
+ * from it. Hardcoded here (rather than imported from DEFAULT_HOOK_SCRIPTS)
+ * so these tests exercise the prune mechanism in isolation and do not
+ * silently start passing/failing as a side effect of a later, unrelated
+ * edit to DEFAULT_HOOK_SCRIPTS itself.
+ */
+const FUTURE_HOOK_SCRIPTS = [
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+  { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
+  { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+];
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-hook-retirement-test-'));
+}
+
+function settingsPathFor(consumerDir) {
+  return path.join(consumerDir, '.claude', 'settings.json');
+}
+
+function writeSettings(consumerDir, obj) {
+  mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+  writeFileSync(settingsPathFor(consumerDir), JSON.stringify(obj, null, 2), 'utf8');
+}
+
+function readSettingsRaw(consumerDir) {
+  return readFileSync(settingsPathFor(consumerDir), 'utf8');
+}
+
+function readSettingsJson(consumerDir) {
+  return JSON.parse(readSettingsRaw(consumerDir));
+}
+
+/** A CLI-managed (tagged) entry, mirroring settings.mjs's buildManagedEntry shape. */
+function taggedEntry(matcher, command) {
+  return { [HOOK_TAG]: true, matcher, hooks: [{ type: 'command', command }] };
+}
+
+/** A consumer-authored (untagged) entry for the same shape. */
+function consumerEntry(matcher, command) {
+  return { matcher, hooks: [{ type: 'command', command }] };
+}
+
+// ---------------------------------------------------------------------------
+// T0 — RETIRED_HOOK_SCRIPTS export exists and targets rules-injector.sh
+//
+// A dedicated, isolated assertion so a still-missing export fails with a
+// direct, readable message rather than surfacing only as a downstream
+// assertion mismatch in P1-P6.
+// ---------------------------------------------------------------------------
+
+describe('S1 T0 — RETIRED_HOOK_SCRIPTS export', () => {
+  it('T0a: RETIRED_HOOK_SCRIPTS is exported as a non-empty array', async () => {
+    const { RETIRED_HOOK_SCRIPTS } = await importSettings();
+    assert.ok(
+      Array.isArray(RETIRED_HOOK_SCRIPTS) && RETIRED_HOOK_SCRIPTS.length > 0,
+      `settings.mjs must export a non-empty RETIRED_HOOK_SCRIPTS array; got: ${JSON.stringify(RETIRED_HOOK_SCRIPTS)}`,
+    );
+  });
+
+  it('T0b: RETIRED_HOOK_SCRIPTS has an entry whose command targets .claude/hooks/rules-injector.sh', async () => {
+    const { RETIRED_HOOK_SCRIPTS } = await importSettings();
+    const list = Array.isArray(RETIRED_HOOK_SCRIPTS) ? RETIRED_HOOK_SCRIPTS : [];
+    const entry = list.find((h) => h && h.command === RETIRED_COMMAND);
+    assert.ok(
+      entry,
+      `RETIRED_HOOK_SCRIPTS must contain an entry with command "${RETIRED_COMMAND}" ` +
+      `(rules-injector.sh is the first retired hook per plan.md); ` +
+      `got commands: ${list.map((h) => h?.command).join(', ') || '(none)'}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P1 — Managed retired entry is pruned
+// ---------------------------------------------------------------------------
+
+describe('S1 P1 — mergeHookSettings prunes a managed (tagged) retired entry', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P1a: the tagged SessionStart entry for rules-injector.sh is removed', async () => {
+    writeSettings(consumerDir, {
+      hooks: { SessionStart: [taggedEntry('.*', RETIRED_COMMAND)] },
+    });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const stillPresent = sessionStart.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+    assert.ok(
+      !stillPresent,
+      `the managed rules-injector.sh SessionStart entry must be pruned; ` +
+      `got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+
+  it('P1b: result.prunedRetired reports the removed command', async () => {
+    writeSettings(consumerDir, {
+      hooks: { SessionStart: [taggedEntry('.*', RETIRED_COMMAND)] },
+    });
+
+    const result = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    assert.ok(
+      Array.isArray(result.prunedRetired),
+      `mergeHookSettings result must carry a prunedRetired array; got: ${JSON.stringify(result)}`,
+    );
+    assert.ok(
+      result.prunedRetired.includes(RETIRED_COMMAND),
+      `result.prunedRetired must include "${RETIRED_COMMAND}"; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+  });
+
+  it('P1c: result.merged is true when a retired entry was pruned', async () => {
+    writeSettings(consumerDir, {
+      hooks: { SessionStart: [taggedEntry('.*', RETIRED_COMMAND)] },
+    });
+
+    const result = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    assert.equal(
+      result.merged,
+      true,
+      'mergeHookSettings must report merged: true when a retired entry was pruned',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P2 — Unmanaged / consumer-authored entry is NOT pruned (the most important
+// test in the set: it protects consumer-owned settings.json state).
+// ---------------------------------------------------------------------------
+
+describe('S1 P2 — an unmanaged entry for the retired command survives untouched', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P2: a consumer-authored entry pointing at the retired command is preserved byte-for-byte, even alongside a managed one on the same event', async () => {
+    // Deliberately place BOTH a tagged (managed) entry and an untagged
+    // (consumer-authored) entry for the SAME command on the SAME event —
+    // the exact scenario a naive "delete anything matching this command"
+    // prune would get wrong.
+    const consumerOwned = consumerEntry('.*', RETIRED_COMMAND);
+    writeSettings(consumerDir, {
+      hooks: {
+        SessionStart: [taggedEntry('.*', RETIRED_COMMAND), consumerOwned],
+      },
+    });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const matching = sessionStart.filter(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+
+    // Exactly one survivor: the consumer's, and it must be untagged and
+    // byte-identical in shape to what was written.
+    assert.equal(
+      matching.length,
+      1,
+      `exactly one entry for ${RETIRED_COMMAND} must survive (the consumer's); ` +
+      `got ${matching.length}: ${JSON.stringify(matching)}`,
+    );
+    assert.equal(
+      matching[0][HOOK_TAG],
+      undefined,
+      'the surviving entry must be the untagged consumer-authored one, not the managed one',
+    );
+    assert.deepEqual(
+      matching[0],
+      consumerOwned,
+      'the consumer-authored entry must be byte-identical (untouched) after the prune',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P3 — Absent entry is a no-op
+// ---------------------------------------------------------------------------
+
+describe('S1 P3 — no retired entry present means no change', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P3: a consumer already fully wired with the three survivors and no retired entry sees a byte-identical file and merged: false', async () => {
+    // Already fully wired to the FUTURE (post-retirement) hook set, with no
+    // rules-injector.sh entry anywhere — the additive pass has nothing to
+    // add, and the prune pass has nothing to remove.
+    writeSettings(consumerDir, {
+      hooks: {
+        SessionStart: [taggedEntry('.*', '.claude/hooks/steering-injector.sh')],
+        PostToolUse: [taggedEntry('.*', '.claude/hooks/managed-file-guard.sh')],
+        Stop: [taggedEntry('.*', '.claude/hooks/uncommitted-check.sh')],
+      },
+    });
+    const before = readSettingsRaw(consumerDir);
+
+    const result = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const after = readSettingsRaw(consumerDir);
+    assert.equal(after, before, 'settings.json must be byte-identical when there is nothing to merge or prune');
+    assert.equal(result.merged, false, 'result.merged must be false on a true no-op');
+    assert.ok(
+      Array.isArray(result.prunedRetired) && result.prunedRetired.length === 0,
+      `result.prunedRetired must be an empty array when nothing was pruned; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P4 — Prune is idempotent
+// ---------------------------------------------------------------------------
+
+describe('S1 P4 — repeated merges are idempotent', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P4: a second merge after the prune reports no further change and leaves the file identical', async () => {
+    writeSettings(consumerDir, {
+      hooks: { SessionStart: [taggedEntry('.*', RETIRED_COMMAND)] },
+    });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+    const afterFirst = readSettingsRaw(consumerDir);
+
+    const secondResult = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+    const afterSecond = readSettingsRaw(consumerDir);
+
+    assert.equal(
+      afterSecond,
+      afterFirst,
+      'settings.json must be byte-identical after a second merge (idempotent, §9)',
+    );
+    assert.equal(secondResult.merged, false, 'the second merge must report merged: false');
+    assert.ok(
+      Array.isArray(secondResult.prunedRetired) && secondResult.prunedRetired.length === 0,
+      `the second merge must report an empty prunedRetired (nothing left to prune); got: ${JSON.stringify(secondResult.prunedRetired)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P5 — --dry-run reports without writing
+// ---------------------------------------------------------------------------
+
+describe('S1 P5 — --dry-run reports the prune but writes nothing', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P5: dry-run reports merged: true and the pruned command, but the file on disk stays byte-identical', async () => {
+    writeSettings(consumerDir, {
+      hooks: { SessionStart: [taggedEntry('.*', RETIRED_COMMAND)] },
+    });
+    const before = readSettingsRaw(consumerDir);
+
+    const result = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS, { dryRun: true });
+
+    assert.equal(result.dryRun, true, 'result.dryRun must be true');
+    assert.equal(result.merged, true, 'dry-run must still report that a change (the prune) would occur');
+    assert.ok(
+      Array.isArray(result.prunedRetired) && result.prunedRetired.includes(RETIRED_COMMAND),
+      `dry-run result.prunedRetired must report "${RETIRED_COMMAND}" would be pruned; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+
+    const after = readSettingsRaw(consumerDir);
+    assert.equal(after, before, '--dry-run must not write anything — the file must stay byte-identical');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// S1 cycle 2 RED — deliver-validate findings H1 (major) and M4 (minor).
+//
+// H1: pruneRetiredEntries (settings.mjs:163-185, the `continue` at :172) drops
+// the ENTIRE managed entry when ANY command in entry.hooks[] matches a
+// retired command. The CLI's own buildManagedEntry always emits one command
+// per entry, so the CLI itself never produces a multi-command entry — but a
+// multi-command hooks[] array is idiomatic Claude Code settings shape, and a
+// consumer hand-adding their own command into the CLI's already-tagged entry
+// produces exactly this shape. That consumer command is then deleted
+// permanently (it is unmanaged, so nothing re-adds it), violating the
+// invariant stated at settings.mjs:10-12 ("remove our own registrations for
+// RETIRED_HOOK_SCRIPTS, never anyone else's"): the prune is entry-granular
+// today; the invariant it claims to uphold is command-granular.
+//
+// Intended fix (not yet implemented): filter entry.hooks down to its
+// non-retired commands, keep the entry with the filtered array, and remove
+// the entry only when hooks empties.
+//
+// M4: the implementation comment at settings.mjs:158-161 claims the prune
+// scans every event bucket (not just SessionStart) specifically so a
+// pre-retirement CLI's registration under a different event is still caught.
+// Nothing pinned that claim, and nothing pinned that odd entry shapes (no
+// hooks[] key, non-string command) don't crash the prune.
+// ---------------------------------------------------------------------------
+
+describe('S1 H1 — prune is hook-granular, not entry-granular (a consumer command sharing a tagged entry must survive)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  const CONSUMER_COMMAND = '.claude/hooks/consumer-owned-check.sh';
+
+  it('H1a: a tagged entry whose hooks[] holds both the retired command and a consumer-added command survives the prune, with only the retired command removed', async () => {
+    const mixedEntry = {
+      [HOOK_TAG]: true,
+      matcher: '.*',
+      hooks: [
+        { type: 'command', command: RETIRED_COMMAND },
+        { type: 'command', command: CONSUMER_COMMAND },
+      ],
+    };
+    writeSettings(consumerDir, { hooks: { SessionStart: [mixedEntry] } });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const survivor = sessionStart.find((e) => e[HOOK_TAG] === true);
+    assert.ok(
+      survivor,
+      `the tagged entry must survive the prune (only its retired command should be removed, ` +
+      `not the whole entry — the prune must be hook-granular); got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+    const commands = (survivor?.hooks ?? []).map((h) => h.command);
+    assert.ok(
+      !commands.includes(RETIRED_COMMAND),
+      `the retired command must be gone from the surviving entry; got commands: ${JSON.stringify(commands)}`,
+    );
+    assert.ok(
+      commands.includes(CONSUMER_COMMAND),
+      `the consumer-added command sharing the entry must be intact after the prune (it is not ` +
+      `ours to delete); got commands: ${JSON.stringify(commands)}`,
+    );
+  });
+
+  it('H1b: a tagged entry whose hooks[] holds ONLY the retired command is removed entirely, without suppressing an unrelated append into the same bucket (must not regress)', async () => {
+    // NOTE: FUTURE_HOOK_SCRIPTS registers steering-injector.sh under
+    // SessionStart too — the SAME bucket as pureRetiredEntry. A correct merge
+    // both drops the fully-retired entry AND appends the legitimate
+    // steering-injector.sh entry, so the bucket is NOT empty afterward — it
+    // holds exactly the surviving append. Asserting `sessionStart.length ===
+    // 0` here would be unsatisfiable by ANY correct implementation (current
+    // or hook-granular-fixed alike), since it conflates "the retired entry is
+    // gone" with "nothing else may land in this bucket." Assert the actual
+    // guard instead: no entry carrying the retired command survives, and the
+    // concurrent append is untouched (proving the prune did not over-reach).
+    const pureRetiredEntry = taggedEntry('.*', RETIRED_COMMAND);
+    writeSettings(consumerDir, { hooks: { SessionStart: [pureRetiredEntry] } });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const retiredStillPresent = sessionStart.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+    assert.ok(
+      !retiredStillPresent,
+      `no entry carrying the retired command must survive once its hooks[] would empty entirely; ` +
+      `got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+
+    const steeringRegistered = sessionStart.some(
+      (e) =>
+        Array.isArray(e.hooks) &&
+        e.hooks.some((h) => h.command === '.claude/hooks/steering-injector.sh'),
+    );
+    assert.ok(
+      steeringRegistered,
+      `the concurrent steering-injector.sh append into the same SessionStart bucket must still ` +
+      `succeed — the prune must not suppress an unrelated append; got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+
+  it('H1c: pruning a mixed entry does not un-register a surviving managed hook that shared the same entry', async () => {
+    // Second-order effect: appendMissingEntries runs FIRST and sees the
+    // shipped command (steering-injector.sh) already present inside the
+    // mixed entry, so it never re-adds it as a separate entry. If the prune
+    // then drops the WHOLE entry (today's entry-granular behavior), the
+    // surviving managed hook vanishes with nothing left to re-register it —
+    // an un-registration deliver-validate flagged as a real regression risk,
+    // not just a data-loss risk.
+    const SURVIVING_COMMAND = '.claude/hooks/steering-injector.sh';
+    const mixedEntry = {
+      [HOOK_TAG]: true,
+      matcher: '.*',
+      hooks: [
+        { type: 'command', command: RETIRED_COMMAND },
+        { type: 'command', command: SURVIVING_COMMAND },
+      ],
+    };
+    writeSettings(consumerDir, { hooks: { SessionStart: [mixedEntry] } });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const stillRegistered = sessionStart.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === SURVIVING_COMMAND),
+    );
+    assert.ok(
+      stillRegistered,
+      `steering-injector.sh must still be registered under SessionStart after a prune touches a ` +
+      `mixed entry it shared with the retired command; got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+});
+
+describe('S1 M4 — cross-bucket prune claim and odd entry shapes', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('M4a: a retired command registered under a non-SessionStart bucket (PostToolUse) is still pruned', async () => {
+    writeSettings(consumerDir, { hooks: { PostToolUse: [taggedEntry('.*', RETIRED_COMMAND)] } });
+
+    const result = await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+    const postToolUse = settings.hooks?.PostToolUse ?? [];
+    const stillPresent = postToolUse.some(
+      (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === RETIRED_COMMAND),
+    );
+    assert.ok(
+      !stillPresent,
+      `a retired command registered under PostToolUse (not SessionStart) must still be pruned by ` +
+      `the all-bucket scan settings.mjs:158-161 claims exists; got hooks.PostToolUse: ${JSON.stringify(postToolUse)}`,
+    );
+    assert.ok(
+      result.prunedRetired.includes(RETIRED_COMMAND),
+      `result.prunedRetired must report the command pruned from the non-SessionStart bucket; got: ${JSON.stringify(result.prunedRetired)}`,
+    );
+  });
+
+  it('M4b: a tagged entry with no hooks[] key does not crash the prune and is left untouched', async () => {
+    const noHooksEntry = { [HOOK_TAG]: true, matcher: '.*' };
+    writeSettings(consumerDir, { hooks: { SessionStart: [noHooksEntry] } });
+
+    assert.doesNotThrow(
+      () => mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS),
+      'mergeHookSettings must not throw on a tagged entry missing the hooks[] key',
+    );
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const survivor = sessionStart.find((e) => e[HOOK_TAG] === true && !('hooks' in e));
+    assert.deepEqual(
+      survivor,
+      noHooksEntry,
+      `the no-hooks[]-key tagged entry must survive the prune untouched; got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+
+  it('M4c: a tagged entry with a non-string command does not crash the prune and is left untouched', async () => {
+    const weirdEntry = {
+      [HOOK_TAG]: true,
+      matcher: '.*',
+      hooks: [{ type: 'command', command: 12345 }],
+    };
+    writeSettings(consumerDir, { hooks: { SessionStart: [weirdEntry] } });
+
+    assert.doesNotThrow(
+      () => mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS),
+      'mergeHookSettings must not throw on a tagged entry whose command is not a string',
+    );
+
+    const settings = readSettingsJson(consumerDir);
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    const survivor = sessionStart.find(
+      (e) => e[HOOK_TAG] === true && Array.isArray(e.hooks) && e.hooks.some((h) => h.command === 12345),
+    );
+    assert.deepEqual(
+      survivor,
+      weirdEntry,
+      `the non-string-command tagged entry must survive the prune untouched; got hooks.SessionStart: ${JSON.stringify(sessionStart)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// P6 — Other managed hooks are untouched
+// ---------------------------------------------------------------------------
+
+describe('S1 P6 — the other three managed hooks survive the prune unchanged', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('P6: steering-injector.sh, managed-file-guard.sh, and uncommitted-check.sh entries are byte-identical after the prune', async () => {
+    const steering = taggedEntry('.*', '.claude/hooks/steering-injector.sh');
+    const guard = taggedEntry('.*', '.claude/hooks/managed-file-guard.sh');
+    const uncommitted = taggedEntry('.*', '.claude/hooks/uncommitted-check.sh');
+    const retired = taggedEntry('.*', RETIRED_COMMAND);
+
+    writeSettings(consumerDir, {
+      hooks: {
+        SessionStart: [steering, retired],
+        PostToolUse: [guard],
+        Stop: [uncommitted],
+      },
+    });
+
+    await mergeHookSettings(consumerDir, FUTURE_HOOK_SCRIPTS);
+
+    const settings = readSettingsJson(consumerDir);
+
+    // The retired entry is gone; the survivor on the same event is untouched.
+    const sessionStart = settings.hooks?.SessionStart ?? [];
+    assert.equal(
+      sessionStart.length,
+      1,
+      `SessionStart must retain only the steering-injector.sh entry after prune; got: ${JSON.stringify(sessionStart)}`,
+    );
+    assert.deepEqual(sessionStart[0], steering, 'steering-injector.sh entry must be byte-identical after the prune');
+
+    assert.deepEqual(
+      settings.hooks?.PostToolUse,
+      [guard],
+      'managed-file-guard.sh (PostToolUse) must be untouched by the prune',
+    );
+    assert.deepEqual(
+      settings.hooks?.Stop,
+      [uncommitted],
+      'uncommitted-check.sh (Stop) must be untouched by the prune',
+    );
+  });
+});