@memnexus-ai/mx-agent-cli 0.1.290 → 0.1.292

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/__tests__/config-fidelity-unreadable-fixture.d.ts +32 -0
  2. package/dist/__tests__/config-fidelity-unreadable-fixture.d.ts.map +1 -0
  3. package/dist/__tests__/config-fidelity-unreadable-fixture.js +37 -0
  4. package/dist/__tests__/config-fidelity-unreadable-fixture.js.map +1 -0
  5. package/dist/__tests__/config-fidelity.test.d.ts +16 -0
  6. package/dist/__tests__/config-fidelity.test.d.ts.map +1 -0
  7. package/dist/__tests__/config-fidelity.test.js +2546 -0
  8. package/dist/__tests__/config-fidelity.test.js.map +1 -0
  9. package/dist/__tests__/doctor-config-fidelity.test.d.ts +19 -0
  10. package/dist/__tests__/doctor-config-fidelity.test.d.ts.map +1 -0
  11. package/dist/__tests__/doctor-config-fidelity.test.js +324 -0
  12. package/dist/__tests__/doctor-config-fidelity.test.js.map +1 -0
  13. package/dist/__tests__/verify-hooks-heal-log.test.d.ts +11 -0
  14. package/dist/__tests__/verify-hooks-heal-log.test.d.ts.map +1 -0
  15. package/dist/__tests__/verify-hooks-heal-log.test.js +172 -0
  16. package/dist/__tests__/verify-hooks-heal-log.test.js.map +1 -0
  17. package/dist/agent-config/hooks/HOOK-TIMEOUTS.md +47 -0
  18. package/dist/agent-config/hooks/hook-launcher.sh +305 -0
  19. package/dist/agent-config/settings.json +20 -20
  20. package/dist/commands/doctor.d.ts +46 -7
  21. package/dist/commands/doctor.d.ts.map +1 -1
  22. package/dist/commands/doctor.js +81 -9
  23. package/dist/commands/doctor.js.map +1 -1
  24. package/dist/commands/start.d.ts.map +1 -1
  25. package/dist/commands/start.js +56 -0
  26. package/dist/commands/start.js.map +1 -1
  27. package/dist/commands/verify-hooks.d.ts +9 -0
  28. package/dist/commands/verify-hooks.d.ts.map +1 -1
  29. package/dist/commands/verify-hooks.js +94 -1
  30. package/dist/commands/verify-hooks.js.map +1 -1
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +33 -9
  33. package/dist/index.js.map +1 -1
  34. package/dist/lib/config-fidelity.d.ts +500 -0
  35. package/dist/lib/config-fidelity.d.ts.map +1 -0
  36. package/dist/lib/config-fidelity.js +1713 -0
  37. package/dist/lib/config-fidelity.js.map +1 -0
  38. package/package.json +1 -1
  39. package/scripts/generate-claude.mjs +12 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"doctor-config-fidelity.test.js","sourceRoot":"","sources":["../../src/__tests__/doctor-config-fidelity.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Tests for the heal-log surfacing in `mx-agent verify-hooks` (#4853).
3
+ *
4
+ * hook-launcher.sh restores a registered-but-missing hook at call time and CANNOT
5
+ * announce that in-session: it has to exit with the restored hook's own code, and
6
+ * Claude Code discards stderr from a hook that exits 0. The durable log is the
7
+ * only channel the heal has, so "verify-hooks reads it" is the property that makes
8
+ * the heal visible to a human at all.
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=verify-hooks-heal-log.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"verify-hooks-heal-log.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/verify-hooks-heal-log.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Tests for the heal-log surfacing in `mx-agent verify-hooks` (#4853).
3
+ *
4
+ * hook-launcher.sh restores a registered-but-missing hook at call time and CANNOT
5
+ * announce that in-session: it has to exit with the restored hook's own code, and
6
+ * Claude Code discards stderr from a hook that exits 0. The durable log is the
7
+ * only channel the heal has, so "verify-hooks reads it" is the property that makes
8
+ * the heal visible to a human at all.
9
+ */
10
+ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
11
+ import { mkdirSync, rmSync, writeFileSync } from 'fs';
12
+ import { join } from 'path';
13
+ import { tmpdir } from 'os';
14
+ let home;
15
+ let origHome;
16
+ beforeEach(() => {
17
+ home = join(tmpdir(), `mx-heallog-${Date.now()}-${Math.random().toString(36).slice(2)}`);
18
+ mkdirSync(join(home, '.mx-agent'), { recursive: true });
19
+ origHome = process.env.HOME;
20
+ process.env.HOME = home;
21
+ vi.resetModules();
22
+ });
23
+ afterEach(() => {
24
+ if (origHome === undefined)
25
+ delete process.env.HOME;
26
+ else
27
+ process.env.HOME = origHome;
28
+ rmSync(home, { recursive: true, force: true });
29
+ });
30
+ async function load() {
31
+ return import('../commands/verify-hooks.js');
32
+ }
33
+ function writeLog(lines) {
34
+ writeFileSync(join(home, '.mx-agent', 'hook-heal.log'), lines.join('\n') + '\n');
35
+ }
36
+ describe('readHealLog', () => {
37
+ it('returns nothing when no log exists', async () => {
38
+ const { readHealLog } = await load();
39
+ expect(readHealLog('/some/worktree')).toEqual([]);
40
+ });
41
+ it('parses entries and keeps only this worktree', async () => {
42
+ writeLog([
43
+ '2026-08-10T12:00:00Z\t/wt/a\tworktree-guard.sh\trestored-from=/cache/worktree-guard.sh',
44
+ '2026-08-10T12:05:00Z\t/wt/b\tgit-mutation-guard.sh\trestored-from=/wt/b/src',
45
+ '2026-08-10T12:09:00Z\t/wt/a\tworktree-guard.sh\trestored-from=/cache/worktree-guard.sh',
46
+ ]);
47
+ const { readHealLog } = await load();
48
+ const entries = readHealLog('/wt/a');
49
+ expect(entries).toHaveLength(2);
50
+ expect(entries[0].hook).toBe('worktree-guard.sh');
51
+ expect(entries[1].timestamp).toBe('2026-08-10T12:09:00Z');
52
+ expect(entries[1].detail).toContain('restored-from=');
53
+ });
54
+ it('never throws on a malformed log', async () => {
55
+ writeLog(['', 'not-a-tsv-line', '\t\t', 'a\tb']);
56
+ const { readHealLog } = await load();
57
+ expect(() => readHealLog('/wt/a')).not.toThrow();
58
+ expect(readHealLog('b')).toEqual([]);
59
+ });
60
+ it('reads only the tail of a large log, and the newest records are what it keeps', async () => {
61
+ // The launcher rotates at 1 MB, but rotation is best-effort. The state this
62
+ // feature exists to detect — a guard being deleted on every tool call —
63
+ // grows the log without bound, so the reader must not load it whole: it
64
+ // would be slowest and hungriest exactly when the history matters most.
65
+ const filler = 'x'.repeat(400);
66
+ const lines = [];
67
+ for (let i = 0; i < 20000; i++) {
68
+ lines.push(`2026-08-10T12:00:00Z\t/wt/a\thook-${i}.sh\trestored-from=${filler}`);
69
+ }
70
+ writeLog(lines); // ~8.6 MB
71
+ const { readHealLog } = await load();
72
+ const entries = readHealLog('/wt/a');
73
+ // 256 KB tail over ~450-byte records: bounded well below the 20000 written.
74
+ expect(entries.length).toBeGreaterThan(0);
75
+ expect(entries.length).toBeLessThan(2000);
76
+ // The tail it keeps is the RECENT end — the last record must be the last written.
77
+ expect(entries[entries.length - 1].hook).toBe('hook-19999.sh');
78
+ // ...and the first kept record must be a whole one, not the partial line the
79
+ // byte-offset read starts in the middle of.
80
+ expect(entries[0].timestamp).toBe('2026-08-10T12:00:00Z');
81
+ });
82
+ it('does not read a log larger than the tail window into memory', async () => {
83
+ const big = 'y'.repeat(1024);
84
+ const lines = [];
85
+ for (let i = 0; i < 5000; i++)
86
+ lines.push(`2026-08-10T12:00:00Z\t/wt/a\th.sh\t${big}`);
87
+ writeLog(lines); // ~5 MB
88
+ const { readHealLog } = await load();
89
+ const entries = readHealLog('/wt/a');
90
+ const bytesHeld = entries.reduce((n, e) => n + e.detail.length, 0);
91
+ expect(bytesHeld).toBeLessThanOrEqual(256 * 1024);
92
+ });
93
+ });
94
+ describe('runVerifyHooks heal-history reporting', () => {
95
+ it('prints the heal history, the per-hook count, and the log path', async () => {
96
+ const wt = join(home, 'wt');
97
+ mkdirSync(join(wt, '.claude', 'hooks'), { recursive: true });
98
+ writeFileSync(join(wt, '.claude', 'settings.json'), JSON.stringify({ hooks: {} }, null, 2) + '\n');
99
+ writeLog([
100
+ `2026-08-10T12:00:00Z\t${wt}\tworktree-guard.sh\trestored-from=${home}/.mx-agent/permission-cache/hooks/worktree-guard.sh`,
101
+ `2026-08-10T12:09:00Z\t${wt}\tworktree-guard.sh\trestored-from=${home}/.mx-agent/permission-cache/hooks/worktree-guard.sh`,
102
+ ]);
103
+ const out = [];
104
+ const spy = vi.spyOn(console, 'log').mockImplementation((...a) => {
105
+ out.push(a.join(' '));
106
+ });
107
+ try {
108
+ const { runVerifyHooks } = await load();
109
+ runVerifyHooks({ path: wt });
110
+ }
111
+ finally {
112
+ spy.mockRestore();
113
+ process.exitCode = 0; // an incomplete fixture sets it; do not fail the suite
114
+ }
115
+ const text = out.join('\n');
116
+ expect(text).toContain('auto-heal history');
117
+ expect(text).toContain('worktree-guard.sh');
118
+ expect(text).toContain('restored 2x');
119
+ expect(text).toContain('hook-heal.log');
120
+ });
121
+ it('strips control characters from log fields before printing them', async () => {
122
+ // The launcher never writes such a record (it validates the hook name and
123
+ // strips control bytes from the paths). But the log is a plain file in
124
+ // $HOME: anyone who can write it can put ANSI escapes into output that
125
+ // agents read, and chalk.dim does not strip them.
126
+ const wt = join(home, 'wt3');
127
+ mkdirSync(join(wt, '.claude', 'hooks'), { recursive: true });
128
+ writeFileSync(join(wt, '.claude', 'settings.json'), JSON.stringify({ hooks: {} }, null, 2) + '\n');
129
+ const ESC = String.fromCharCode(27);
130
+ writeLog([
131
+ `2026-08-10T12:00:00Z\t${wt}\tevil${ESC}[2Kguard.sh\trestored-from=${ESC}[31mALL-CLEAR`,
132
+ ]);
133
+ const out = [];
134
+ const spy = vi.spyOn(console, 'log').mockImplementation((...a) => {
135
+ out.push(a.join(' '));
136
+ });
137
+ try {
138
+ const { runVerifyHooks } = await load();
139
+ runVerifyHooks({ path: wt });
140
+ }
141
+ finally {
142
+ spy.mockRestore();
143
+ process.exitCode = 0;
144
+ }
145
+ const text = out.join('\n');
146
+ expect(text).toContain('auto-heal history');
147
+ // No raw escape or bell survives into agent-visible output...
148
+ expect(text).not.toContain(ESC);
149
+ // ...and the record is still reported, with the bytes replaced.
150
+ expect(text).toContain("evil?[2Kguard.sh");
151
+ });
152
+ it('says nothing about healing when the log has no entry for this worktree', async () => {
153
+ const wt = join(home, 'wt2');
154
+ mkdirSync(join(wt, '.claude', 'hooks'), { recursive: true });
155
+ writeFileSync(join(wt, '.claude', 'settings.json'), JSON.stringify({ hooks: {} }, null, 2) + '\n');
156
+ writeLog([`2026-08-10T12:00:00Z\t/other/worktree\tworktree-guard.sh\trestored-from=x`]);
157
+ const out = [];
158
+ const spy = vi.spyOn(console, 'log').mockImplementation((...a) => {
159
+ out.push(a.join(' '));
160
+ });
161
+ try {
162
+ const { runVerifyHooks } = await load();
163
+ runVerifyHooks({ path: wt });
164
+ }
165
+ finally {
166
+ spy.mockRestore();
167
+ process.exitCode = 0; // an incomplete fixture sets it; do not fail the suite
168
+ }
169
+ expect(out.join('\n')).not.toContain('auto-heal history');
170
+ });
171
+ });
172
+ //# sourceMappingURL=verify-hooks-heal-log.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"verify-hooks-heal-log.test.js","sourceRoot":"","sources":["../../src/__tests__/verify-hooks-heal-log.test.ts"],"names":[],"mappings":"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"}
@@ -69,6 +69,53 @@ hook must announce the failure on stderr, name what is unknown, and say what to
69
69
  run to find out. Silence is the defect, not the timeout. See
70
70
  `coordination-brief.sh` and `coordination-midsession-drain.sh` for the wording.
71
71
 
72
+ ## The registration wrapper: a missing hook is announced, not silent (#4853)
73
+
74
+ Every registration in `settings.json` has the shape
75
+
76
+ ```sh
77
+ bash -c 'D="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}";
78
+ H="$D/.claude/hooks/<name>.sh"; [ -f "$H" ] && [ ! -L "$H" ] && exec bash "$H";
79
+ L="$D/mx-agent-system/agent-config/hooks/hook-launcher.sh";
80
+ [ -f "$L" ] && exec bash "$L" "$D" ".claude/hooks/<name>.sh";
81
+ printf "[hook-wrapper] <name>.sh DID NOT RUN - ..." >&2; exit 1'
82
+ ```
83
+
84
+ `.claude/hooks/` is untracked and only refreshes on `mx-agent start`, so a
85
+ registered hook can be absent on disk. Until 2026-08-10 the wrapper ended in
86
+ `|| exit 0`: the call was permitted and nothing said so, which made an unguarded
87
+ worktree indistinguishable from a guarded one — rule 2 above, violated by the
88
+ wrapper itself. Two of twelve worktrees on this machine were in that state.
89
+
90
+ The product owner chose **fail open with auto-heal** over fail closed, because
91
+ the wrapper is shared by guards and advisory hooks and a missing reminder must
92
+ not brick a session. So: the first clause is the fast path (now also refusing a
93
+ symlink at the hook slot, which `exec` would otherwise follow); if the hook is
94
+ missing, `hook-launcher.sh` restores it atomically — from the integrity-checked
95
+ `~/.mx-agent/permission-cache/` when that verifies, otherwise from this
96
+ directory — and runs it; if restore is impossible, the call is allowed and the
97
+ failure is announced by name.
98
+
99
+ **Announcing costs an exit code, and only the first line survives.** Claude Code
100
+ DISCARDS stderr from a hook that exits 0 — it reaches the debug log and nothing
101
+ else. So the fail-open branch exits **1**: a non-blocking error, which still
102
+ permits the action (the PO's decision) but puts a hook-error notice carrying the
103
+ **first line** of stderr in the transcript. Every announcement here is written so
104
+ line 1 alone says which hook did not run, that the call was unchecked, and the
105
+ remedy; lines 2+ are debug-log detail. `exit 2` was not an option — it blocks.
106
+
107
+ The heal branch cannot use that mechanism: it must exit with the restored hook's
108
+ own code, and exiting 1 instead would suppress that hook's stdout (for a
109
+ `SessionStart` hook that is injected context, and `coordination-brief.sh` drains
110
+ a queue, so its output cannot be reconstructed). The heal is therefore recorded
111
+ in `~/.mx-agent/hook-heal.log` and printed by `mx-agent verify-hooks`. Its stderr
112
+ line reaches the debug log only; do not write a comment or a message claiming
113
+ otherwise.
114
+
115
+ Timeout implications: the restore is a same-directory copy plus a `rename(2)`,
116
+ so it costs microseconds and fits inside every value in the table below,
117
+ including the 5s on `set-terminal-appearance`. It never runs on the normal path.
118
+
72
119
  ## Current assignment
73
120
 
74
121
  | Hook | Event | Tier | Timeout |
@@ -0,0 +1,305 @@
1
+ #!/usr/bin/env bash
2
+ # hook-launcher.sh — SLOW-PATH fallback for a REGISTERED-BUT-MISSING hook (#4853).
3
+ #
4
+ # WHAT #4853 IS. Every hook in agent-config/settings.json is registered as
5
+ #
6
+ # bash -c 'D="${CLAUDE_PROJECT_DIR:-...}"; H="$D/.claude/hooks/<name>.sh";
7
+ # [ -f "$H" ] && exec bash "$H" || exit 0'
8
+ #
9
+ # `.claude/hooks/` is an untracked, per-worktree materialization that only
10
+ # refreshes on `mx-agent start`. When the file is absent the wrapper takes
11
+ # `exit 0` — ALLOW — and says nothing. An unguarded worktree is then
12
+ # indistinguishable from a guarded one. Two of the twelve worktrees on this
13
+ # machine were in exactly that state on 2026-08-10 with no worktree-guard.sh at
14
+ # all. The defect is NOT that it allows; it is that it allows SILENTLY.
15
+ #
16
+ # THE DECISION (product owner, in session, 2026-08-10): FAIL OPEN WITH
17
+ # AUTO-HEAL, not fail closed. A missing ADVISORY hook must not brick a session,
18
+ # and the wrapper is shared by guards and advisory hooks alike, so the fix is
19
+ # uniform: restore the hook and run it; if that is impossible, allow the call
20
+ # but ANNOUNCE it, naming the hook and the reason.
21
+ #
22
+ # HOW AN ANNOUNCEMENT ACTUALLY REACHES ANYONE — read before editing a message.
23
+ # Claude Code DISCARDS stderr from a hook that exits 0: it goes to the debug log
24
+ # and is never shown in the transcript, so the model never sees it. Three exit
25
+ # codes matter here:
26
+ # exit 0 — stderr discarded. Useless for announcing anything.
27
+ # exit 1 — NON-BLOCKING error. The action still proceeds (which is the PO's
28
+ # fail-open decision, unchanged), and the transcript shows a
29
+ # hook-error notice carrying the FIRST LINE of stderr.
30
+ # exit 2 — BLOCKS the action. Not ours to choose: the PO chose fail open.
31
+ # So every fail-open announce below exits 1, and every announce message is
32
+ # written so that LINE 1 ALONE carries the whole point — what did not run, that
33
+ # the call was not checked, and what to do about it. Lines 2+ are detail for the
34
+ # debug log and for the test suite; they are NOT displayed. The same constraint
35
+ # is recorded across the guard hooks under KI-HOOK-STDERR-VISIBILITY
36
+ # (memory-checkpoint-reminder.sh:735,761, git-mutation-guard.sh:9,
37
+ # mx-guard-hook.sh:155, workflow-dispatch-guard.sh:255, gh-pr-edit-guard.sh:10,
38
+ # named-memory-write-guard.sh:10, ci-validate-hook.sh:300).
39
+ #
40
+ # WHERE THIS RUNS. Only on the failure branch. The registration keeps its own
41
+ # inline `[ -f "$H" ] && [ ! -L "$H" ] && exec bash "$H"` fast path, so a
42
+ # worktree with intact hooks does what it did before this file existed — same
43
+ # exec, no extra process. This script is reached only when the hook file is
44
+ # already missing, which is a state that must not be fast, it must be fixed.
45
+ #
46
+ # WHY A SHARED SCRIPT. Twenty registrations carry the wrapper. Duplicating
47
+ # restore-and-announce logic as escaped shell inside twenty JSON strings is
48
+ # unreviewable and drifts. The standing argument against shared hook code
49
+ # (hook-timing-parity.test.sh: "a defect in one shared file would take out every
50
+ # gate at once") is answered by the fallback ordering above — if this file is
51
+ # missing, broken, or unreadable, every registration still runs its own inline
52
+ # fast path and behaves exactly as it did before. This script can only ever make
53
+ # an ALREADY-FAILING invocation better or equally bad, never a working one worse.
54
+ #
55
+ # ARGUMENTS
56
+ # $1 project root (the registration already resolved it; may be empty)
57
+ # $2 worktree-relative hook path, always `.claude/hooks/<name>.sh`
58
+ #
59
+ # EXIT CODES
60
+ # 1 fail open — the hook did not run and could not be restored. Non-blocking;
61
+ # the action proceeds. 1 rather than 0 so the announcement is displayed.
62
+ # * otherwise, whatever the restored hook exits with (including 2 = block).
63
+
64
+ set -u
65
+
66
+ ROOT="${1:-}"
67
+ REL="${2:-}"
68
+ NAME="${REL##*/}"
69
+
70
+ # ── Fail-open announce ──────────────────────────────────────────────────────
71
+ # LINE 1 IS THE ONLY LINE ANYONE SEES (see the exit-code note above). It must
72
+ # stand alone: what did not run, that this call was unchecked, what to do.
73
+ fail_open() {
74
+ printf '%s\n' \
75
+ "[hook-launcher] ${NAME:-<unnamed hook>} DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853)." \
76
+ "[hook-launcher] Registered in .claude/settings.json but missing from ${ROOT:-<unresolved-root>}/.claude/hooks/, and auto-restore failed: $1" \
77
+ "[hook-launcher] No further call will be checked by it until it is restored. mx-agent verify-hooks lists every affected hook." \
78
+ >&2
79
+ exit 1
80
+ }
81
+
82
+ # ── Shape checks on the registration argument ───────────────────────────────
83
+ # The argument comes from a generated settings.json, so this is defence in
84
+ # depth, not validation of untrusted input. It exists so that a malformed
85
+ # registration degrades to a loud fail-open instead of joining a path.
86
+ case "$REL" in
87
+ *..*) fail_open "the registration passed a traversing hook reference (${REL})" ;;
88
+ .claude/hooks/*.sh) ;;
89
+ *) fail_open "the registration passed an unrecognised hook reference (${REL:-<empty>})" ;;
90
+ esac
91
+ case "$NAME" in
92
+ '' | *[!A-Za-z0-9._-]*) fail_open "the registration passed an unsafe hook name (${NAME:-<empty>})" ;;
93
+ esac
94
+
95
+ if [ -z "$ROOT" ] || [ ! -d "$ROOT" ]; then
96
+ fail_open "the project root could not be resolved (CLAUDE_PROJECT_DIR unset and git rev-parse failed)"
97
+ fi
98
+
99
+ # ── Restore source selection: integrity-checked cache first ─────────────────
100
+ # generate-claude.mjs states the invariant for its own degrade path
101
+ # (generate-claude.mjs:467): "The boot degrade path must NOT trust the working
102
+ # tree." This launcher is a degrade path too, so it follows the same order:
103
+ #
104
+ # 1. ~/.mx-agent/permission-cache/hooks/<name> — the last-known-good permission
105
+ # layer captured on the most recent ORIGIN-PINNED generation
106
+ # (refreshPermissionCache, generate-claude.mjs:488-551). Trusted only after
107
+ # recomputing the sha256 recorded in hash.txt over the whole layer, byte for
108
+ # byte the way the generator computes it (settings\0 + settings.json bytes,
109
+ # then each hook sorted by name as \0hook\0<name>\0<bytes>). This is an
110
+ # INTEGRITY check, not an authenticity check — identical posture to
111
+ # restorePermissionCacheToDest (generate-claude.mjs:564-607).
112
+ # 2. the working tree's agent-config/hooks/ — a MATERIALLY WEAKER claim: those
113
+ # bytes are whatever is checked out right now. Used only when there is no
114
+ # usable cache, because the alternative is not restoring at all.
115
+ #
116
+ # Which one was used is stated in the heal announcement and in the heal log. Do
117
+ # not collapse the two into one message: "restored from the origin-pinned cache"
118
+ # and "restored from the working tree" are different assurances.
119
+
120
+ # Working-tree candidate: the directory this script was found in. NOTE: that is
121
+ # the path the registration hardcoded, not a path this script can discover — a
122
+ # project whose configSource differs never reaches this file at all (see
123
+ # SHOULD-FIX-2 in the #4853 review; the registration path is not templated
124
+ # today, so auto-heal is a no-op outside this repo and the inline clause-3
125
+ # announcement is what fires there).
126
+ WT_DIR="$(cd -- "$(dirname -- "$0")" 2>/dev/null && pwd)" || WT_DIR=""
127
+
128
+ # Recompute the generator's layer hash over a permission-cache directory.
129
+ # Prints the hex digest, or nothing if the layer cannot be read.
130
+ #
131
+ # THIS IS THE SECOND IMPLEMENTATION OF ONE HASH. The first is
132
+ # hashPermissionLayer + readPermissionLayer in generate-claude.mjs (:493-525).
133
+ # Any disagreement between them is silent and permanent: the digests differ on
134
+ # every call, the cache is refused on every heal forever, and the launcher
135
+ # quietly demotes itself to the UNVERIFIED working tree while the announcement
136
+ # says "no cache was available" — true, but only because a bug rejected one.
137
+ # The two must agree on all four of: which entries are included, their order,
138
+ # the framing bytes, and the file bytes. Every rule below has a named
139
+ # counterpart in the generator, and hook-launcher.test.sh case 13 drives the
140
+ # generator's own writer against this function to prove they still match.
141
+ layer_hash() {
142
+ # C collation for both the glob expansion below and sha256sum, so the hook
143
+ # order matches the generator's byte-wise sort. LOAD-BEARING: the hooks dir
144
+ # contains uppercase names, and glob collation under en_US.utf8 does not
145
+ # match JS code-unit order. Do not remove.
146
+ local LC_ALL=C
147
+ local d="$1" f n out _dg
148
+ [ -f "$d/settings.json" ] || return 1
149
+ # INCLUSION RULE: the generator enumerates with readdirSync, which RETURNS
150
+ # dot-prefixed names; a bash glob does NOT match them unless dotglob is set.
151
+ # Without this line a single `.gitkeep`/`.editorconfig`/`.shellcheckrc` in the
152
+ # hooks source is hashed by the generator and skipped here — see the header.
153
+ # Saved and restored because dotglob is a shell-wide option.
154
+ _dg="$(shopt -p dotglob)"
155
+ shopt -s dotglob
156
+ out="$(
157
+ {
158
+ printf 'settings\0'
159
+ cat -- "$d/settings.json" || exit 1
160
+ for f in "$d"/hooks/*; do
161
+ [ -f "$f" ] || continue
162
+ [ -L "$f" ] && continue # generator's listDir counts a symlink as not-a-file
163
+ n="${f##*/}"
164
+ printf '\0hook\0%s\0' "$n"
165
+ cat -- "$f" || exit 1
166
+ done
167
+ } | LC_ALL=C sha256sum 2>/dev/null | cut -d' ' -f1
168
+ )"
169
+ eval "$_dg"
170
+ [ -n "$out" ] || return 1
171
+ printf '%s\n' "$out"
172
+ }
173
+
174
+ CACHE_DIR="${HOME:-}/.mx-agent/permission-cache"
175
+ SRC=""
176
+ SRC_LABEL=""
177
+ CACHE_SKIP_REASON="no cache at $CACHE_DIR"
178
+ if [ -n "${HOME:-}" ] && [ -f "$CACHE_DIR/hooks/$NAME" ] && [ ! -L "$CACHE_DIR/hooks/$NAME" ]; then
179
+ if [ -f "$CACHE_DIR/hash.txt" ]; then
180
+ RECORDED="$(tr -d '[:space:]' < "$CACHE_DIR/hash.txt" 2>/dev/null)"
181
+ ACTUAL="$(layer_hash "$CACHE_DIR")"
182
+ if [ -n "$ACTUAL" ] && [ "$ACTUAL" = "$RECORDED" ]; then
183
+ SRC="$CACHE_DIR/hooks/$NAME"
184
+ SRC_LABEL="the integrity-checked origin-pinned cache ($CACHE_DIR)"
185
+ else
186
+ CACHE_SKIP_REASON="the cache at $CACHE_DIR failed its sha256 integrity check"
187
+ fi
188
+ else
189
+ CACHE_SKIP_REASON="the cache at $CACHE_DIR has no hash.txt (fail closed on an unverifiable cache)"
190
+ fi
191
+ fi
192
+
193
+ if [ -z "$SRC" ]; then
194
+ [ -n "$WT_DIR" ] || fail_open "$CACHE_SKIP_REASON, and the agent-config hooks directory could not be resolved from $0"
195
+ # Regular file only, never a symlink. This mirrors the generator's fail-closed
196
+ # symlink ban (PO directive 2026-07-20): a link here would let whatever it
197
+ # points at run as the guard.
198
+ if [ ! -f "$WT_DIR/$NAME" ] || [ -L "$WT_DIR/$NAME" ]; then
199
+ fail_open "$CACHE_SKIP_REASON, and no usable restore source at $WT_DIR/$NAME (absent, or a symlink, which is banned)"
200
+ fi
201
+ SRC="$WT_DIR/$NAME"
202
+ SRC_LABEL="the WORKING TREE ($WT_DIR) - UNVERIFIED bytes, no cache was available"
203
+ fi
204
+
205
+ # ── Destination ─────────────────────────────────────────────────────────────
206
+ # `mkdir -p` FOLLOWS a symlink, so check the whole managed path, not just the
207
+ # final component: a `.claude` symlink would redirect the restore (and every
208
+ # later hook read) outside the worktree.
209
+ if [ -L "$ROOT/.claude" ]; then
210
+ fail_open "$ROOT/.claude is a symlink, which is banned for the managed config dir"
211
+ fi
212
+ DEST_DIR="$ROOT/.claude/hooks"
213
+ DEST="$DEST_DIR/$NAME"
214
+
215
+ mkdir -p -- "$DEST_DIR" 2>/dev/null
216
+ if [ ! -d "$DEST_DIR" ] || [ -L "$DEST_DIR" ]; then
217
+ fail_open "$DEST_DIR is not a usable directory (absent, unwritable, or a symlink)"
218
+ fi
219
+
220
+ # ── Atomic restore: temp file in the SAME directory, chmod, then rename ─────
221
+ # Never unlink-then-write. A concurrent hook invocation must see either the old
222
+ # state (absent) or the complete new file, never a partial or zero-byte script.
223
+ # `mv` within one directory is rename(2), which is atomic; a same-directory temp
224
+ # guarantees we stay on one filesystem so it cannot degrade to copy+unlink.
225
+ # Concurrent restores of the same hook are safe: each writes its own temp and
226
+ # renames identical bytes into place. rename(2) also REPLACES a symlink sitting
227
+ # at $DEST rather than writing through it.
228
+ TMP="$(mktemp -- "$DEST_DIR/.$NAME.XXXXXX" 2>/dev/null)" || TMP=""
229
+ [ -n "$TMP" ] || fail_open "could not create a temp file in $DEST_DIR (read-only filesystem?)"
230
+ trap 'rm -f -- "$TMP" 2>/dev/null' EXIT
231
+
232
+ cat -- "$SRC" > "$TMP" 2>/dev/null || fail_open "copying $SRC into $DEST_DIR failed"
233
+ chmod 0755 -- "$TMP" 2>/dev/null || fail_open "chmod 0755 on the restored copy of $NAME failed"
234
+ mv -f -- "$TMP" "$DEST" 2>/dev/null || fail_open "the atomic rename of $NAME into $DEST_DIR failed"
235
+ trap - EXIT
236
+
237
+ if [ ! -f "$DEST" ]; then
238
+ fail_open "$NAME was not present at $DEST after the rename reported success"
239
+ fi
240
+
241
+ # ── Record the heal DURABLY, because the stderr note below is not visible ───
242
+ # A worktree that silently repairs itself tells nobody that something keeps
243
+ # deleting its guard. We cannot make the heal notice visible the way fail_open
244
+ # does: this path must exit with the RESTORED HOOK'S own code (0 for an advisory
245
+ # hook, 2 for a block), and on exit 0 Claude Code discards stderr. Exiting 1
246
+ # instead would suppress the hook's own stdout — for SessionStart hooks that is
247
+ # the injected context, and coordination-brief.sh DRAINS a queue, so its output
248
+ # cannot be reconstructed. Losing a coordination message to make a notice
249
+ # visible is a bad trade.
250
+ # So the heal goes to an append-only log outside the worktree (survives
251
+ # `.claude/` regeneration, which prunes anything it does not manage), and
252
+ # `mx-agent verify-hooks` reads and prints it. The stderr lines below are for
253
+ # the debug log and nothing else - that is the whole of their reach.
254
+ HEAL_LOG="${HOME:-}/.mx-agent/hook-heal.log"
255
+ # A symlink here is refused, not followed. `>>` writes THROUGH a link, so a
256
+ # pre-planted one appends attacker-chosen records into any file this session can
257
+ # write. Every other path in this file is symlink-checked ($SRC, the cache hook,
258
+ # $DEST_DIR, $ROOT/.claude, the hook slot); this one was the omission.
259
+ [ -L "$HEAL_LOG" ] && HEAL_LOG=""
260
+ if [ -n "${HOME:-}" ] && [ -n "$HEAL_LOG" ]; then
261
+ # 0700/0600 to match the permission cache next door. The contents are
262
+ # low-sensitivity (worktree paths, hook names) but they tell a co-tenant which
263
+ # worktrees keep losing which guards.
264
+ # shellcheck disable=SC2174 # -m applying only to the deepest component is
265
+ # what is wanted: $HOME already exists and is not this hook's to re-permission.
266
+ mkdir -p -m 0700 -- "${HOME}/.mx-agent" 2>/dev/null
267
+ # Cap the log. The failure this feature exists to DETECT — something is
268
+ # deleting a guard repeatedly — writes one record per tool call, unbounded,
269
+ # across every worktree sharing $HOME. Rotate before the reader has to hold it
270
+ # all in memory, keeping the tail (the recent heals are the diagnostic).
271
+ # 2000 records is ~400 KB at the ~200-byte records this script writes, well
272
+ # under the 1 MB trigger: rotation must leave the file SMALL, or every
273
+ # subsequent heal rotates again and pays the copy.
274
+ LOG_BYTES="$(wc -c < "$HEAL_LOG" 2>/dev/null)" || LOG_BYTES=0
275
+ case "$LOG_BYTES" in ''|*[!0-9]*) LOG_BYTES=0 ;; esac
276
+ if [ "$LOG_BYTES" -gt 1048576 ]; then
277
+ ROT="$(mktemp -- "${HOME}/.mx-agent/.hook-heal.XXXXXX" 2>/dev/null)" || ROT=""
278
+ if [ -n "$ROT" ]; then
279
+ if tail -n 2000 -- "$HEAL_LOG" > "$ROT" 2>/dev/null; then
280
+ chmod 0600 -- "$ROT" 2>/dev/null
281
+ mv -f -- "$ROT" "$HEAL_LOG" 2>/dev/null || rm -f -- "$ROT" 2>/dev/null
282
+ else
283
+ rm -f -- "$ROT" 2>/dev/null
284
+ fi
285
+ fi
286
+ fi
287
+ # $NAME is validated above; $ROOT is not, and a project path containing a tab
288
+ # or newline would corrupt the record and make verify-hooks' field-2 filter
289
+ # drop or misattribute entries. Not attacker-relevant — it makes the
290
+ # diagnostic quietly wrong.
291
+ SAFE_ROOT="${ROOT//[[:cntrl:]]/?}"
292
+ SAFE_SRC="${SRC//[[:cntrl:]]/?}"
293
+ # Single short write to an O_APPEND fd: atomic against concurrent launchers.
294
+ printf '%s\t%s\t%s\t%s\n' \
295
+ "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)" "$SAFE_ROOT" "$NAME" "restored-from=$SAFE_SRC" \
296
+ >> "$HEAL_LOG" 2>/dev/null || true
297
+ chmod 0600 -- "$HEAL_LOG" 2>/dev/null
298
+ fi
299
+
300
+ printf '%s\n' \
301
+ "[hook-launcher] AUTO-HEALED: $NAME was registered but MISSING from $DEST_DIR; it has been restored and is running now. Source: $SRC_LABEL." \
302
+ "[hook-launcher] Something removed it. Logged to ${HEAL_LOG:-<heal log refused: it is a symlink>}; run mx-agent verify-hooks to see the heal history." \
303
+ >&2
304
+
305
+ exec bash "$DEST"