@dalzoubi/dev-agents-sync 2.0.15 → 2.0.17

package/tests/hooks-cli-install.test.mjs

@@ -0,0 +1,1666 @@
+/**
+ * tests/hooks-cli-install.test.mjs
+ *
+ * Slice S4 — CLI installs hooks + lockfile + settings auto-wire.
+ * Spec: docs/specs/260616-agent-steering-and-hooks/
+ *
+ * These tests FAIL before the implement agent wires up the behavior and PASS after.
+ * They are behavior-anchored (§7): each criterion maps to at least one named test
+ * that would fail if the behavior broke.
+ *
+ * Behavior anchors:
+ *
+ *  H1. init/update write three hook scripts into .claude/hooks/ as executable,
+ *      shell-comment-marker-managed, lockfile-tracked files.
+ *  H2. Running update twice leaves hooks and settings byte-identical (idempotent).
+ *  H3. After install, deleting a .claude/hooks/*.sh makes check report drift (exit 1).
+ *  H4. After install, editing a .claude/hooks/*.sh makes check report drift (exit 1).
+ *  H5. Clean tree (hooks installed and unmodified) makes check exit 0.
+ *  H6. Settings merge is additive + idempotent: merging into a settings.json that
+ *      already has unrelated consumer settings + a consumer hook preserves them all
+ *      and adds the three tagged hook registrations; a second merge is a no-op.
+ *  H7. Injected settings entries are tagged so they can be identified and removed
+ *      without touching consumer-authored entries.
+ *  H8. --dry-run writes nothing (no hooks, no settings, no lockfile change) but
+ *      returns the plan; exit 0.
+ *  H9. --no-hooks-wiring installs hook scripts but does NOT modify settings.json.
+ * H10. Malformed settings.json causes update to fail loud with code ESETTINGS_PARSE
+ *      and leaves the file unmodified.
+ * H11. An existing lockfile WITHOUT a hooks section parses and update upgrades it
+ *      additively (no error, hooks section added).
+ * H12. CLI never logs the auth token (privacy invariant).
+ *
+ * Assumed src/settings.mjs interface (noted for the implement agent):
+ *
+ *   import { mergeHookSettings, removeHookSettings, HOOK_TAG } from '../src/settings.mjs';
+ *
+ *   mergeHookSettings(consumerCwd, hookScripts, opts?)
+ *     - consumerCwd: string — path to consumer repo root
+ *     - hookScripts: { event: string, matcher: string, command: string }[]
+ *         Each element describes one hook to wire in settings.json.
+ *         Example: [
+ *           { 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' },
+ *         ]
+ *     - opts.dryRun: boolean — when true, computes plan but writes nothing
+ *     Returns: { merged: boolean, dryRun: boolean } (or equivalent plan object in dry-run)
+ *     Throws: SettingsParseError with .code === 'ESETTINGS_PARSE' on malformed settings.json
+ *
+ *   HOOK_TAG: string — the tag value injected into managed hook entries so they are
+ *     identifiable and removable. Its exact shape is an implementation detail for the
+ *     implement agent; tests only require that:
+ *       (a) it is present as a property on each injected hook entry OR as a metadata
+ *           field elsewhere in the settings object, AND
+ *       (b) consumer-authored settings survive a merge unchanged (the tag is NOT present
+ *           on consumer entries).
+ *
+ * Lockfile hooks section (additive, §8):
+ *   Existing lockfiles without a `hooks` section parse and are upgraded. The lockfile
+ *   may store a list of managed hook paths so `check` can detect drift. The exact field
+ *   name is an implement-agent decision; tests only assert observable behavior.
+ *
+ * Three hook names (matching the .claude/hooks/ directory from S3):
+ *   - steering-injector.sh    — SessionStart
+ *   - managed-file-guard.sh   — PostToolUse
+ *   - uncommitted-check.sh    — Stop
+ *
+ * Shell-comment marker format (POSIX-sh): `# managed-by: dev-agents-sync vX.Y.Z`
+ *
+ * Test runner: `node --test packages/dev-agents-sync/tests/hooks-cli-install.test.mjs`
+ * No third-party dependencies. All tests use isolated tmp dirs.
+ */
+
+import { describe, it, before, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  statSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { runCheck } from '../src/commands/check.mjs';
+import { writeLockfile, readLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Module under test — settings.mjs does NOT EXIST yet (implement agent creates it).
+// The import WILL THROW on module-not-found, which is the expected RED failure for
+// the module-existence criterion. All describe blocks that use settings.mjs import
+// it locally inside the test to capture the per-test failure reason rather than
+// aborting the entire file.
+// ---------------------------------------------------------------------------
+
+// We use a lazy importer so individual tests can fail independently.
+let _settingsMod = null;
+async function importSettings() {
+  if (_settingsMod) return _settingsMod;
+  // Will throw ERR_MODULE_NOT_FOUND when settings.mjs doesn't exist — the
+  // expected failure mode during RED phase.
+  _settingsMod = await import('../src/settings.mjs');
+  return _settingsMod;
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+// ---------------------------------------------------------------------------
+// Fixture helpers — mirrors the pattern used by init.test.mjs / update.test.mjs
+// ---------------------------------------------------------------------------
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/**
+ * Builds a fixture FileMap from the release-v1.0.0 fixture directory.
+ * Extended with fake hook script entries so the fetcher returns them as
+ * part of the managed-file set.
+ */
+function buildFixtureFileMap(targets = ['claude']) {
+  const map = {};
+  for (const target of targets) {
+    const targetDir = path.join(FIXTURE_DIR, target);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, target);
+  }
+  // Inject hook script entries that look like what S3's build.mjs emits.
+  // These must be under the `claude` target prefix so they resolve into
+  // .claude/hooks/. The shell-comment marker is the canonical form for .sh files.
+  map['claude/hooks/steering-injector.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# SessionStart hook.\nexit 0\n';
+  map['claude/hooks/managed-file-guard.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# PostToolUse hook.\nexit 0\n';
+  map['claude/hooks/uncommitted-check.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# Stop hook.\nexit 0\n';
+  return map;
+}
+
+/** A fetcher that returns the fixture file map (including hook scripts). */
+function makeFixtureFetcher() {
+  return async (_repo, _tag, _token) => buildFixtureFileMap(['claude']);
+}
+
+/** A fetcher that returns the fixture file map but WITHOUT hook scripts (pre-S3 baseline). */
+function makeNoHooksFetcher() {
+  const map = {};
+  const targetDir = path.join(FIXTURE_DIR, 'claude');
+  if (existsSync(targetDir)) {
+    collectFiles(targetDir, targetDir, map, 'claude');
+  }
+  return async (_repo, _tag, _token) => ({ ...map });
+}
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+/** The three hook file names installed under .claude/hooks/. */
+const HOOK_FILES = [
+  'steering-injector.sh',
+  'managed-file-guard.sh',
+  'uncommitted-check.sh',
+];
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-hooks-test-'));
+}
+
+/**
+ * Seeds a minimal pre-initialized consumer repo (lockfile + one agent file).
+ * Optionally writes an existing lockfile without a hooks section (for back-compat).
+ */
+function setupInitializedRepo(consumerDir, opts = {}) {
+  const {
+    targets = ['claude'],
+    resolvedVersion = '1.0.0',
+    range = '^1',
+    omitHooksSection = false,
+  } = opts;
+
+  const lockfileData = {
+    source: 'github:dalzoubi/dev-agents',
+    range,
+    resolvedVersion,
+    targets,
+    lastUpdated: '2026-06-01T00:00:00Z',
+  };
+
+  // For back-compat test: write the lockfile as raw JSON without a `hooks` section.
+  if (omitHooksSection) {
+    const raw =
+      JSON.stringify(
+        {
+          $schema:
+            'https://raw.githubusercontent.com/dalzoubi/dev-agents/v1/schema/lockfile.schema.json',
+          source: lockfileData.source,
+          range: lockfileData.range,
+          resolvedVersion: lockfileData.resolvedVersion,
+          targets: lockfileData.targets,
+          lastUpdated: lockfileData.lastUpdated,
+          // no `hooks` key at all
+        },
+        null,
+        2,
+      ) + '\n';
+    writeFileSync(path.join(consumerDir, '.dev-agents-sync.json'), raw, 'utf8');
+  } else {
+    writeLockfile(consumerDir, lockfileData);
+  }
+
+  const agentsDir = path.join(consumerDir, '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  const fixtureContent = readFileSync(
+    path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'),
+    'utf8',
+  );
+  writeFileSync(path.join(agentsDir, 'define.md'), fixtureContent, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// H1 — init writes three hook scripts into .claude/hooks/
+//
+// Criterion: init/update write three hook scripts, executable, with the
+// shell-comment marker, recorded in the lockfile.
+// ---------------------------------------------------------------------------
+
+describe('S4 H1 — init installs hook scripts', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H1a: init creates .claude/hooks/steering-injector.sh', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude', 'hooks', 'steering-injector.sh')),
+      'init must write .claude/hooks/steering-injector.sh',
+    );
+  });
+
+  it('H1b: init creates .claude/hooks/managed-file-guard.sh', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude', 'hooks', 'managed-file-guard.sh')),
+      'init must write .claude/hooks/managed-file-guard.sh',
+    );
+  });
+
+  it('H1c: init creates .claude/hooks/uncommitted-check.sh', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude', 'hooks', 'uncommitted-check.sh')),
+      'init must write .claude/hooks/uncommitted-check.sh',
+    );
+  });
+
+  it('H1d: all installed hook scripts carry the shell-comment marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const content = readFileSync(path.join(hooksDir, file), 'utf8');
+      assert.ok(
+        /^#\s*managed-by:\s*dev-agents-sync\s+v[0-9]+\.[0-9]+\.[0-9]+/m.test(content),
+        `${file} must contain the shell-comment marker "# managed-by: dev-agents-sync vX.Y.Z"`,
+      );
+    }
+  });
+
+  it('H1e: all installed hook scripts are executable', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const absPath = path.join(hooksDir, file);
+      const st = statSync(absPath);
+      // On POSIX: mode & 0o111 checks owner+group+other execute bits.
+      assert.ok(
+        (st.mode & 0o111) !== 0,
+        `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
+      );
+    }
+  });
+
+  it('H1f: hook scripts are recorded in the lockfile after init', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // Read raw lockfile JSON so we catch any field name the implement agent uses.
+    const raw = readFileSync(path.join(consumerDir, '.dev-agents-sync.json'), 'utf8');
+
+    // At minimum, each hook file name must appear somewhere in the lockfile,
+    // since these are lockfile-tracked managed files.
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        raw.includes(file),
+        `lockfile must reference ${file} (it is a lockfile-tracked managed file)`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H1 (update variant) — update installs hook scripts on a pre-existing repo
+// ---------------------------------------------------------------------------
+
+describe('S4 H1 — update installs hook scripts', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H1g: update installs all three hook scripts when not previously installed', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        existsSync(path.join(hooksDir, file)),
+        `update must install .claude/hooks/${file}`,
+      );
+    }
+  });
+
+  it('H1h: update-installed hook scripts carry the shell-comment marker', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const content = readFileSync(path.join(hooksDir, file), 'utf8');
+      assert.ok(
+        /^#\s*managed-by:\s*dev-agents-sync\s+v[0-9]+\.[0-9]+\.[0-9]+/m.test(content),
+        `update-installed ${file} must carry the shell-comment marker`,
+      );
+    }
+  });
+
+  it('H1i: update-installed hook scripts are executable', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const st = statSync(path.join(hooksDir, file));
+      assert.ok(
+        (st.mode & 0o111) !== 0,
+        `update-installed ${file} must be executable`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H2 — idempotent update: running update twice leaves hooks + settings identical
+// ---------------------------------------------------------------------------
+
+describe('S4 H2 — idempotent update', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H2a: hook script content is byte-identical after a second update', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const updateOpts = {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    };
+
+    await runUpdate(consumerDir, updateOpts);
+
+    // Capture hook contents after first update.
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    const firstPass = {};
+    for (const file of HOOK_FILES) {
+      firstPass[file] = readFileSync(path.join(hooksDir, file), 'utf8');
+    }
+
+    await runUpdate(consumerDir, updateOpts);
+
+    // After second update, hook contents must be byte-identical.
+    for (const file of HOOK_FILES) {
+      const secondPass = readFileSync(path.join(hooksDir, file), 'utf8');
+      assert.equal(
+        secondPass,
+        firstPass[file],
+        `${file} must be byte-identical after a second update (idempotent)`,
+      );
+    }
+  });
+
+  it('H2b: settings.json has no duplicate hook entries after a second update', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const updateOpts = {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    };
+
+    await runUpdate(consumerDir, updateOpts);
+    await runUpdate(consumerDir, updateOpts);
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    assert.ok(existsSync(settingsPath), '.claude/settings.json must exist after update');
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const hooks = settings.hooks ?? {};
+
+    // Collect all hook commands across all event types.
+    const allCommands = [];
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+          for (const h of hookList) {
+            if (h.command) allCommands.push(h.command);
+          }
+        }
+      }
+    }
+
+    // Each hook script must appear at most once.
+    for (const file of HOOK_FILES) {
+      const occurrences = allCommands.filter((cmd) => cmd.includes(file)).length;
+      assert.ok(
+        occurrences <= 1,
+        `${file} hook command must appear at most once in settings.json after two updates (found: ${occurrences})`,
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H3/H4/H5 — check detects hook drift (exit 1); clean tree exits 0
+// ---------------------------------------------------------------------------
+
+describe('S4 H3 — check reports drift on deleted hook script (exit 1)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H3: deleting .claude/hooks/steering-injector.sh causes check to exit 1', async () => {
+    // Install hooks first.
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // Delete a hook script to simulate drift.
+    rmSync(path.join(consumerDir, '.claude', 'hooks', 'steering-injector.sh'));
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when a hook script has been deleted');
+  });
+
+  it('H3b: drift error names the deleted hook file path', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    rmSync(path.join(consumerDir, '.claude', 'hooks', 'steering-injector.sh'));
+
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message;
+    }
+
+    assert.ok(
+      errorMessage.includes('steering-injector.sh') || errorMessage.includes('hooks'),
+      `drift error must name the offending path; got: ${errorMessage}`,
+    );
+  });
+});
+
+describe('S4 H4 — check reports drift on edited hook script (exit 1)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H4: editing .claude/hooks/managed-file-guard.sh causes check to exit 1', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const guardPath = path.join(consumerDir, '.claude', 'hooks', 'managed-file-guard.sh');
+    writeFileSync(guardPath, readFileSync(guardPath, 'utf8') + '\n# extra line\n', 'utf8');
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when a hook script has been locally modified');
+  });
+});
+
+describe('S4 H5 — check exits 0 when hooks are installed and unmodified', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H5: check exits 0 on a clean tree after hook install', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(exitCode, 0, 'check must exit 0 when all managed files (including hooks) match');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H6 — settings merge: additive, idempotent, preserves consumer entries
+// ---------------------------------------------------------------------------
+
+describe('S4 H6 — settings merge is additive and idempotent', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H6a: mergeHookSettings adds three hook registrations to an empty settings.json', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(settingsPath, JSON.stringify({}, null, 2), 'utf8');
+
+    await mergeHookSettings(
+      consumerDir,
+      [
+        { 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' },
+      ],
+    );
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const hooks = settings.hooks ?? {};
+
+    // Each event must have at least one entry referencing the installed script.
+    const findCmd = (eventName, script) => {
+      const entries = hooks[eventName] ?? [];
+      return entries.some(
+        (e) =>
+          Array.isArray(e.hooks) &&
+          e.hooks.some((h) => typeof h.command === 'string' && h.command.includes(script)),
+      );
+    };
+
+    assert.ok(
+      findCmd('SessionStart', 'steering-injector.sh'),
+      'settings.json must contain a SessionStart hook for steering-injector.sh',
+    );
+    assert.ok(
+      findCmd('PostToolUse', 'managed-file-guard.sh'),
+      'settings.json must contain a PostToolUse hook for managed-file-guard.sh',
+    );
+    assert.ok(
+      findCmd('Stop', 'uncommitted-check.sh'),
+      'settings.json must contain a Stop hook for uncommitted-check.sh',
+    );
+  });
+
+  it('H6b: mergeHookSettings preserves all existing consumer settings', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(
+      settingsPath,
+      JSON.stringify(
+        {
+          env: { MY_API_KEY: 'value' },
+          permissions: { allow: ['Bash(git:*)'] },
+          hooks: {
+            PreToolUse: [
+              {
+                matcher: '.*',
+                hooks: [{ type: 'command', command: 'my-custom-hook.sh' }],
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    await mergeHookSettings(
+      consumerDir,
+      [
+        { 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' },
+      ],
+    );
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+
+    // Consumer settings must be preserved.
+    assert.deepEqual(settings.env, { MY_API_KEY: 'value' }, 'env must be preserved');
+    assert.deepEqual(
+      settings.permissions,
+      { allow: ['Bash(git:*)'] },
+      'permissions must be preserved',
+    );
+
+    // Consumer-authored PreToolUse hook must still be present.
+    const preToolUse = (settings.hooks ?? {}).PreToolUse ?? [];
+    const hasCustomHook = preToolUse.some(
+      (e) =>
+        Array.isArray(e.hooks) &&
+        e.hooks.some((h) => h.command === 'my-custom-hook.sh'),
+    );
+    assert.ok(
+      hasCustomHook,
+      'consumer-authored PreToolUse hook (my-custom-hook.sh) must be preserved after merge',
+    );
+  });
+
+  it('H6c: calling mergeHookSettings twice produces no duplicate hook entries', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(settingsPath, JSON.stringify({}, null, 2), 'utf8');
+
+    const hookSpec = [
+      { 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' },
+    ];
+
+    await mergeHookSettings(consumerDir, hookSpec);
+    await mergeHookSettings(consumerDir, hookSpec); // second call
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const hooks = settings.hooks ?? {};
+
+    const allCommands = [];
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+          for (const h of hookList) {
+            if (h.command) allCommands.push(h.command);
+          }
+        }
+      }
+    }
+
+    for (const file of HOOK_FILES) {
+      const count = allCommands.filter((cmd) => cmd.includes(file)).length;
+      assert.ok(
+        count <= 1,
+        `${file} must appear at most once in settings.json after two merges (found: ${count})`,
+      );
+    }
+  });
+
+  it('H6d: mergeHookSettings on a non-existent settings.json creates it', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    // No settings.json exists yet.
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    assert.ok(!existsSync(settingsPath), 'settings.json must not pre-exist for this test');
+
+    await mergeHookSettings(
+      consumerDir,
+      [
+        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+      ],
+    );
+
+    assert.ok(existsSync(settingsPath), 'mergeHookSettings must create settings.json when absent');
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    assert.ok(parsed.hooks, 'created settings.json must have a hooks section');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H7 — injected settings entries are tagged; consumer entries are not
+// ---------------------------------------------------------------------------
+
+describe('S4 H7 — injected hook entries are tagged (identifiable and removable)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H7a: injected hook entries can be identified as CLI-managed (tagged)', async () => {
+    const { mergeHookSettings, HOOK_TAG } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(settingsPath, JSON.stringify({}, null, 2), 'utf8');
+
+    await mergeHookSettings(consumerDir, [
+      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+    ]);
+
+    const raw = readFileSync(settingsPath, 'utf8');
+
+    // The HOOK_TAG must be a non-empty string constant exported from settings.mjs.
+    assert.ok(
+      typeof HOOK_TAG === 'string' && HOOK_TAG.length > 0,
+      'HOOK_TAG must be a non-empty string exported by settings.mjs',
+    );
+
+    // The tag value must appear in the serialized settings so entries are identifiable.
+    assert.ok(
+      raw.includes(HOOK_TAG),
+      `settings.json must contain the HOOK_TAG ("${HOOK_TAG}") on injected entries`,
+    );
+  });
+
+  it('H7b: consumer-authored hook entry does NOT carry the CLI tag after a merge', async () => {
+    const { mergeHookSettings, HOOK_TAG } = await importSettings();
+
+    const consumerHook = { type: 'command', command: 'my-consumer-hook.sh' };
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(
+      settingsPath,
+      JSON.stringify(
+        {
+          hooks: {
+            PreToolUse: [{ matcher: '.*', hooks: [consumerHook] }],
+          },
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    await mergeHookSettings(consumerDir, [
+      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+    ]);
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const preToolUseEntries = (settings.hooks?.PreToolUse ?? []);
+
+    for (const entry of preToolUseEntries) {
+      for (const h of entry.hooks ?? []) {
+        if (h.command === 'my-consumer-hook.sh') {
+          // This consumer-authored hook must NOT have the CLI's tag property.
+          // The exact property name is HOOK_TAG; assert it's absent on consumer entries.
+          assert.ok(
+            h[HOOK_TAG] === undefined && entry[HOOK_TAG] === undefined,
+            `consumer-authored hook must not carry the HOOK_TAG ("${HOOK_TAG}") after a merge`,
+          );
+        }
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H8 — --dry-run writes nothing, returns plan, exits 0
+// ---------------------------------------------------------------------------
+
+describe('S4 H8 — --dry-run writes nothing', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H8a: init --dry-run does not write any hook scripts', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        !existsSync(path.join(hooksDir, file)),
+        `init --dry-run must not write .claude/hooks/${file}`,
+      );
+    }
+  });
+
+  it('H8b: update --dry-run does not write any hook scripts', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        !existsSync(path.join(hooksDir, file)),
+        `update --dry-run must not write .claude/hooks/${file}`,
+      );
+    }
+  });
+
+  it('H8c: update --dry-run does not write or modify settings.json', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    // Pre-exist a settings.json with consumer content.
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const original = JSON.stringify({ env: { FOO: 'bar' } }, null, 2);
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, original, 'utf8');
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(
+      after,
+      original,
+      'update --dry-run must not modify settings.json',
+    );
+  });
+
+  it('H8d: update --dry-run does not modify the lockfile', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    const before = readFileSync(path.join(consumerDir, '.dev-agents-sync.json'), 'utf8');
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const after = readFileSync(path.join(consumerDir, '.dev-agents-sync.json'), 'utf8');
+    assert.equal(after, before, 'update --dry-run must not modify the lockfile');
+  });
+
+  it('H8e: update --dry-run returns a result describing the plan', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const result = await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    assert.ok(result, 'update --dry-run must return a result object');
+    assert.ok(
+      result.dryRun === true,
+      'dry-run result must carry dryRun: true',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H9 — --no-hooks-wiring installs scripts but skips settings merge
+// ---------------------------------------------------------------------------
+
+describe('S4 H9 — --no-hooks-wiring skips settings.json', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H9a: update --no-hooks-wiring installs hook scripts', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      noHooksWiring: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        existsSync(path.join(hooksDir, file)),
+        `update --no-hooks-wiring must still install .claude/hooks/${file}`,
+      );
+    }
+  });
+
+  it('H9b: update --no-hooks-wiring does not create or modify settings.json', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+
+    await runUpdate(consumerDir, {
+      noHooksWiring: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    // settings.json must NOT have been created (no pre-existing file).
+    assert.ok(
+      !existsSync(settingsPath),
+      'update --no-hooks-wiring must not create settings.json',
+    );
+  });
+
+  it('H9c: update --no-hooks-wiring leaves an existing settings.json unmodified', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const original = JSON.stringify({ env: { KEEP: 'me' } }, null, 2);
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, original, 'utf8');
+
+    await runUpdate(consumerDir, {
+      noHooksWiring: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(
+      after,
+      original,
+      'update --no-hooks-wiring must leave an existing settings.json byte-identical',
+    );
+  });
+
+  it('H9d: init --no-hooks-wiring installs hook scripts but skips settings.json', async () => {
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      noHooksWiring: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // Hook scripts must be installed.
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        existsSync(path.join(consumerDir, '.claude', 'hooks', file)),
+        `init --no-hooks-wiring must still install ${file}`,
+      );
+    }
+
+    // settings.json must NOT be created.
+    assert.ok(
+      !existsSync(settingsPath),
+      'init --no-hooks-wiring must not create settings.json',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H10 — malformed settings.json causes update to fail loud with ESETTINGS_PARSE
+// ---------------------------------------------------------------------------
+
+describe('S4 H10 — malformed settings.json triggers ESETTINGS_PARSE (no write)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H10a: update fails loud with ESETTINGS_PARSE when settings.json is invalid JSON', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, '{not: valid JSON}}', 'utf8');
+
+    let thrownError = null;
+    try {
+      await runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      });
+    } catch (err) {
+      thrownError = err;
+    }
+
+    assert.ok(thrownError !== null, 'update must throw when settings.json is malformed JSON');
+    assert.ok(
+      thrownError.code === 'ESETTINGS_PARSE' ||
+        (thrownError.message && /ESETTINGS_PARSE/i.test(thrownError.message)),
+      `error must carry code ESETTINGS_PARSE; got code=${thrownError?.code} message=${thrownError?.message}`,
+    );
+  });
+
+  it('H10b: malformed settings.json is left unmodified (no partial write)', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    const malformed = '{not: valid JSON}}';
+    writeFileSync(settingsPath, malformed, 'utf8');
+
+    try {
+      await runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      });
+    } catch {
+      // Expected — swallow the error for the preservation check.
+    }
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(
+      after,
+      malformed,
+      'malformed settings.json must remain unmodified after a failed update (no partial write)',
+    );
+  });
+
+  it('H10c: mergeHookSettings throws an error with code ESETTINGS_PARSE on malformed JSON', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, '{ "hooks": {bad json}', 'utf8');
+
+    let thrownError = null;
+    try {
+      await mergeHookSettings(consumerDir, [
+        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+      ]);
+    } catch (err) {
+      thrownError = err;
+    }
+
+    assert.ok(thrownError !== null, 'mergeHookSettings must throw on malformed settings.json');
+    assert.ok(
+      thrownError.code === 'ESETTINGS_PARSE',
+      `error must carry .code === 'ESETTINGS_PARSE'; got: ${thrownError?.code}`,
+    );
+  });
+
+  it('H10d: mergeHookSettings leaves malformed settings.json byte-identical (no partial write)', async () => {
+    const { mergeHookSettings } = await importSettings();
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    mkdirSync(path.dirname(settingsPath), { recursive: true });
+    const malformed = '{ "hooks": {bad json}';
+    writeFileSync(settingsPath, malformed, 'utf8');
+
+    try {
+      await mergeHookSettings(consumerDir, [
+        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+      ]);
+    } catch {
+      // expected
+    }
+
+    const after = readFileSync(settingsPath, 'utf8');
+    assert.equal(
+      after,
+      malformed,
+      'mergeHookSettings must leave malformed settings.json byte-identical (no partial write)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H11 — back-compat: existing lockfile without hooks section upgrades cleanly
+// ---------------------------------------------------------------------------
+
+describe('S4 H11 — back-compat: pre-hooks lockfile upgrades cleanly', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H11a: update against a lockfile without a hooks section does not throw', async () => {
+    // Write a lockfile that has no `hooks` field at all (pre-S4 format).
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0', omitHooksSection: true });
+
+    await assert.doesNotReject(
+      runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      }),
+      'update must not throw when the lockfile has no hooks section',
+    );
+  });
+
+  it('H11b: after upgrading a pre-hooks lockfile, hook scripts are installed', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0', omitHooksSection: true });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        existsSync(path.join(hooksDir, file)),
+        `update must install ${file} even when upgrading a pre-hooks lockfile`,
+      );
+    }
+  });
+
+  it('H11c: after upgrading, lockfile is rewritten with hooks information', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0', omitHooksSection: true });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const raw = readFileSync(path.join(consumerDir, '.dev-agents-sync.json'), 'utf8');
+
+    // After upgrade, the lockfile must reference the installed hooks.
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        raw.includes(file),
+        `upgraded lockfile must reference ${file}`,
+      );
+    }
+  });
+
+  it('H11d: pre-hooks lockfile still validates (additive upgrade — no required fields missing)', async () => {
+    // Verifies that readLockfile itself can parse the old format without crashing.
+    // The hooks section is not a required field (additive change, §8).
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0', omitHooksSection: true });
+
+    assert.doesNotThrow(
+      () => readLockfile(consumerDir),
+      'readLockfile must not throw on a lockfile that lacks a hooks section',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// L5 — fail-loud on wrong-shape `hooks` field (H1 remediation, §5/§12)
+//
+// A consumer settings.json whose `hooks` field (or an event value within it) has
+// the wrong INTERNAL shape must surface ESETTINGS_PARSE and leave the file
+// byte-identical — never silently spread a string/array into an index-keyed
+// object, never silently discard a non-array event value.
+// ---------------------------------------------------------------------------
+
+describe('S4 L5 — wrong-shape hooks field fails loud (ESETTINGS_PARSE, no write)', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  const HOOK_SPEC = [
+    { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+  ];
+
+  // Each case: a syntactically valid JSON object whose `hooks` sub-tree is the
+  // wrong shape. The original bug either corrupted (string/array → index-keyed
+  // object) or discarded (non-array event value) the consumer's data.
+  const cases = [
+    ['hooks is a string', { hooks: 'oops' }],
+    ['hooks is an array', { hooks: ['x'] }],
+    ['a hooks event value is a string', { hooks: { SessionStart: 'x' } }],
+  ];
+
+  for (const [label, settingsObj] of cases) {
+    it(`L5: mergeHookSettings throws ESETTINGS_PARSE when ${label}`, async () => {
+      const { mergeHookSettings } = await importSettings();
+
+      const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+      const original = JSON.stringify(settingsObj, null, 2);
+      writeFileSync(settingsPath, original, 'utf8');
+
+      let thrownError = null;
+      try {
+        await mergeHookSettings(consumerDir, HOOK_SPEC);
+      } catch (err) {
+        thrownError = err;
+      }
+
+      assert.ok(thrownError !== null, `mergeHookSettings must throw when ${label}`);
+      assert.equal(
+        thrownError.code,
+        'ESETTINGS_PARSE',
+        `error must carry code ESETTINGS_PARSE; got: ${thrownError?.code}`,
+      );
+
+      // The file must be byte-identical — no corruption, no partial write.
+      const after = readFileSync(settingsPath, 'utf8');
+      assert.equal(
+        after,
+        original,
+        `settings.json must be byte-identical after a failed merge when ${label}`,
+      );
+    });
+
+    it(`L5: update fails loud and writes nothing when ${label}`, async () => {
+      setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+      const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+      const original = JSON.stringify(settingsObj, null, 2);
+      writeFileSync(settingsPath, original, 'utf8');
+
+      let thrownError = null;
+      try {
+        await runUpdate(consumerDir, {
+          fetcher: makeFixtureFetcher(),
+          availableTags: ['v1.0.0', 'v1.2.0'],
+        });
+      } catch (err) {
+        thrownError = err;
+      }
+
+      assert.ok(thrownError !== null, `update must throw when ${label}`);
+      assert.ok(
+        thrownError.code === 'ESETTINGS_PARSE' ||
+          (thrownError.message && /ESETTINGS_PARSE/i.test(thrownError.message)),
+        `error must carry code ESETTINGS_PARSE; got code=${thrownError?.code} message=${thrownError?.message}`,
+      );
+
+      const after = readFileSync(settingsPath, 'utf8');
+      assert.equal(
+        after,
+        original,
+        `settings.json must be byte-identical after a failed update when ${label}`,
+      );
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// L4 — reversibility crux: a consumer hook on the SAME event as a managed one
+// survives merge + remove untouched (only tagged managed entries are removed).
+// ---------------------------------------------------------------------------
+
+describe('S4 L4 — consumer hook on a managed event survives merge then remove', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('L4: removeHookSettings keeps the consumer SessionStart hook and drops only managed ones', async () => {
+    const { mergeHookSettings, removeHookSettings, HOOK_TAG } = await importSettings();
+
+    // Consumer authored a hook on SessionStart — the SAME event the managed
+    // steering-injector registers on. This is the reversibility crux: removing
+    // managed entries must not collaterally remove the consumer's entry.
+    const consumerHook = { type: 'command', command: 'my-session-start.sh' };
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    writeFileSync(
+      settingsPath,
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [{ matcher: '.*', hooks: [consumerHook] }],
+          },
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    // Merge the managed registrations (steering-injector is also SessionStart).
+    await mergeHookSettings(consumerDir, [
+      { 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' },
+    ]);
+
+    // After merge: SessionStart has BOTH the consumer entry and the managed one.
+    {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const ss = settings.hooks.SessionStart;
+      const hasConsumer = ss.some((e) =>
+        (e.hooks ?? []).some((h) => h.command === 'my-session-start.sh'),
+      );
+      const hasManaged = ss.some((e) => e[HOOK_TAG] === true);
+      assert.ok(hasConsumer, 'consumer SessionStart hook must survive the merge');
+      assert.ok(hasManaged, 'a managed SessionStart entry must be added by the merge');
+    }
+
+    // Now remove managed entries.
+    await removeHookSettings(consumerDir);
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const ss = settings.hooks?.SessionStart ?? [];
+
+    // The consumer hook is intact and untagged.
+    const consumerEntries = ss.filter((e) =>
+      (e.hooks ?? []).some((h) => h.command === 'my-session-start.sh'),
+    );
+    assert.equal(consumerEntries.length, 1, 'consumer SessionStart hook must remain after remove');
+    for (const e of consumerEntries) {
+      assert.equal(e[HOOK_TAG], undefined, 'consumer entry must NOT carry the HOOK_TAG');
+      for (const h of e.hooks ?? []) {
+        assert.equal(h[HOOK_TAG], undefined, 'consumer hook must NOT carry the HOOK_TAG');
+      }
+    }
+
+    // No tagged managed entry remains on SessionStart.
+    const managedLeft = ss.filter((e) => e[HOOK_TAG] === true);
+    assert.equal(managedLeft.length, 0, 'all tagged managed SessionStart entries must be removed');
+
+    // The managed steering-injector command is gone entirely.
+    const stillManaged = ss.some((e) =>
+      (e.hooks ?? []).some(
+        (h) => typeof h.command === 'string' && h.command.includes('steering-injector.sh'),
+      ),
+    );
+    assert.ok(!stillManaged, 'managed steering-injector.sh registration must be removed');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// M2 — wire hooks on the up-to-date short-circuit (already-latest consumer)
+// ---------------------------------------------------------------------------
+
+describe('S4 M2 — up-to-date update still wires hooks already on disk', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('M2a: a consumer already on latest with hook scripts on disk but no settings gets them wired', async () => {
+    // Pin the consumer to the latest available tag so update short-circuits.
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    // Simulate hook scripts already present on disk (from a prior install) but
+    // settings.json never wired.
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    for (const file of HOOK_FILES) {
+      writeFileSync(
+        path.join(hooksDir, file),
+        `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.0\nexit 0\n`,
+        'utf8',
+      );
+    }
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    assert.ok(!existsSync(settingsPath), 'settings.json must not pre-exist for this test');
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    assert.ok(result.upToDate === true, 'update must report up-to-date (short-circuit taken)');
+    assert.ok(existsSync(settingsPath), 'settings.json must be wired even on the up-to-date path');
+
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const hooks = settings.hooks ?? {};
+    const allCommands = [];
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          for (const h of entry.hooks ?? []) {
+            if (h.command) allCommands.push(h.command);
+          }
+        }
+      }
+    }
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        allCommands.some((cmd) => cmd.includes(file)),
+        `up-to-date update must wire ${file} into settings.json`,
+      );
+    }
+  });
+
+  it('M2b: up-to-date wiring is idempotent (second run adds no duplicates)', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    for (const file of HOOK_FILES) {
+      writeFileSync(path.join(hooksDir, file), `#!/bin/sh\nexit 0\n`, 'utf8');
+    }
+
+    const opts = { fetcher: makeFixtureFetcher(), availableTags: ['v1.0.0'] };
+    await runUpdate(consumerDir, opts);
+    await runUpdate(consumerDir, opts);
+
+    const settings = JSON.parse(
+      readFileSync(path.join(consumerDir, '.claude', 'settings.json'), 'utf8'),
+    );
+    const hooks = settings.hooks ?? {};
+    const allCommands = [];
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          for (const h of entry.hooks ?? []) {
+            if (h.command) allCommands.push(h.command);
+          }
+        }
+      }
+    }
+    for (const file of HOOK_FILES) {
+      const count = allCommands.filter((cmd) => cmd.includes(file)).length;
+      assert.ok(count <= 1, `${file} must appear at most once after two up-to-date runs (found ${count})`);
+    }
+  });
+
+  it('M2c: up-to-date dry-run wires nothing', async () => {
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    for (const file of HOOK_FILES) {
+      writeFileSync(path.join(hooksDir, file), `#!/bin/sh\nexit 0\n`, 'utf8');
+    }
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0'],
+    });
+
+    assert.ok(!existsSync(settingsPath), 'up-to-date --dry-run must not create settings.json');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// H12 — privacy: CLI never logs the auth token
+// ---------------------------------------------------------------------------
+
+describe('S4 H12 — privacy: auth token never logged in hook install', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('H12a: update with a token never writes the token to any installed hook script', async () => {
+    const secretToken = 'ghp_SUPERSECRETTOKEN_S4_TEST';
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      token: secretToken,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const absPath = path.join(hooksDir, file);
+      if (!existsSync(absPath)) continue;
+      const content = readFileSync(absPath, 'utf8');
+      assert.ok(
+        !content.includes(secretToken),
+        `${file} must not contain the auth token (privacy invariant)`,
+      );
+    }
+  });
+
+  it('H12b: update with a token never writes the token to settings.json', async () => {
+    const secretToken = 'ghp_SUPERSECRETTOKEN_SETTINGS';
+    setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    await runUpdate(consumerDir, {
+      token: secretToken,
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+      const content = readFileSync(settingsPath, 'utf8');
+      assert.ok(
+        !content.includes(secretToken),
+        'settings.json must not contain the auth token (privacy invariant)',
+      );
+    }
+    // If settings.json was not created, the invariant is trivially satisfied.
+  });
+
+  it('H12c: init with a token never writes the token to the lockfile', async () => {
+    const secretToken = 'ghp_SUPERSECRETTOKEN_INIT';
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      token: secretToken,
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const raw = readFileSync(path.join(consumerDir, '.dev-agents-sync.json'), 'utf8');
+    assert.ok(
+      !raw.includes(secretToken),
+      'lockfile must not contain the auth token (privacy invariant)',
+    );
+  });
+});