@memnexus-ai/mx-agent-cli 0.1.289 → 0.1.291

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.
@@ -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"
@@ -7,7 +7,7 @@
7
7
  "hooks": [
8
8
  {
9
9
  "type": "command",
10
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/memory-checkpoint-reminder.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
10
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/memory-checkpoint-reminder.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/memory-checkpoint-reminder.sh\"; printf \"[hook-wrapper] memory-checkpoint-reminder.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
11
11
  "timeout": 60
12
12
  }
13
13
  ]
@@ -17,37 +17,37 @@
17
17
  "hooks": [
18
18
  {
19
19
  "type": "command",
20
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/worktree-guard.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
20
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/worktree-guard.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/worktree-guard.sh\"; printf \"[hook-wrapper] worktree-guard.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
21
21
  "timeout": 60
22
22
  },
23
23
  {
24
24
  "type": "command",
25
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/mx-guard-hook.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
25
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/mx-guard-hook.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/mx-guard-hook.sh\"; printf \"[hook-wrapper] mx-guard-hook.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
26
26
  "timeout": 300
27
27
  },
28
28
  {
29
29
  "type": "command",
30
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/ci-validate-hook.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
30
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/ci-validate-hook.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/ci-validate-hook.sh\"; printf \"[hook-wrapper] ci-validate-hook.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
31
31
  "timeout": 3600
32
32
  },
33
33
  {
34
34
  "type": "command",
35
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/workflow-dispatch-guard.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
35
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/workflow-dispatch-guard.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/workflow-dispatch-guard.sh\"; printf \"[hook-wrapper] workflow-dispatch-guard.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
36
36
  "timeout": 60
37
37
  },
38
38
  {
39
39
  "type": "command",
40
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/git-mutation-guard.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
40
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/git-mutation-guard.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/git-mutation-guard.sh\"; printf \"[hook-wrapper] git-mutation-guard.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
41
41
  "timeout": 60
42
42
  },
43
43
  {
44
44
  "type": "command",
45
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/named-memory-write-guard.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
45
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/named-memory-write-guard.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/named-memory-write-guard.sh\"; printf \"[hook-wrapper] named-memory-write-guard.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
46
46
  "timeout": 60
47
47
  },
48
48
  {
49
49
  "type": "command",
50
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/gh-pr-edit-guard.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
50
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/gh-pr-edit-guard.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/gh-pr-edit-guard.sh\"; printf \"[hook-wrapper] gh-pr-edit-guard.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
51
51
  "timeout": 60
52
52
  }
53
53
  ]
@@ -59,7 +59,7 @@
59
59
  "hooks": [
60
60
  {
61
61
  "type": "command",
62
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/deploy-verification-reminder.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
62
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/deploy-verification-reminder.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/deploy-verification-reminder.sh\"; printf \"[hook-wrapper] deploy-verification-reminder.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
63
63
  "timeout": 60
64
64
  }
65
65
  ]
@@ -71,12 +71,12 @@
71
71
  "hooks": [
72
72
  {
73
73
  "type": "command",
74
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/auto-checkpoint.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
74
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/auto-checkpoint.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/auto-checkpoint.sh\"; printf \"[hook-wrapper] auto-checkpoint.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
75
75
  "timeout": 30
76
76
  },
77
77
  {
78
78
  "type": "command",
79
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/auto-capture-precompact.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
79
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/auto-capture-precompact.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/auto-capture-precompact.sh\"; printf \"[hook-wrapper] auto-capture-precompact.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
80
80
  "timeout": 30
81
81
  }
82
82
  ]
@@ -88,7 +88,7 @@
88
88
  "hooks": [
89
89
  {
90
90
  "type": "command",
91
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/reload-checkpoint.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
91
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/reload-checkpoint.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/reload-checkpoint.sh\"; printf \"[hook-wrapper] reload-checkpoint.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
92
92
  "timeout": 20
93
93
  }
94
94
  ]
@@ -98,12 +98,12 @@
98
98
  "hooks": [
99
99
  {
100
100
  "type": "command",
101
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/set-terminal-appearance.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
101
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/set-terminal-appearance.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/set-terminal-appearance.sh\"; printf \"[hook-wrapper] set-terminal-appearance.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
102
102
  "timeout": 5
103
103
  },
104
104
  {
105
105
  "type": "command",
106
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/coordination-brief.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
106
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/coordination-brief.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/coordination-brief.sh\"; printf \"[hook-wrapper] coordination-brief.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
107
107
  "timeout": 180
108
108
  }
109
109
  ]
@@ -114,32 +114,32 @@
114
114
  "hooks": [
115
115
  {
116
116
  "type": "command",
117
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/observability-sync.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
117
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/observability-sync.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/observability-sync.sh\"; printf \"[hook-wrapper] observability-sync.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
118
118
  "timeout": 30
119
119
  },
120
120
  {
121
121
  "type": "command",
122
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/auto-capture-session-end.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
122
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/auto-capture-session-end.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/auto-capture-session-end.sh\"; printf \"[hook-wrapper] auto-capture-session-end.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
123
123
  "timeout": 30
124
124
  },
125
125
  {
126
126
  "type": "command",
127
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/delegation-audit.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
127
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/delegation-audit.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/delegation-audit.sh\"; printf \"[hook-wrapper] delegation-audit.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
128
128
  "timeout": 15
129
129
  },
130
130
  {
131
131
  "type": "command",
132
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/iteration-log-check.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
132
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/iteration-log-check.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/iteration-log-check.sh\"; printf \"[hook-wrapper] iteration-log-check.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
133
133
  "timeout": 20
134
134
  },
135
135
  {
136
136
  "type": "command",
137
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/coordination-midsession-drain.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
137
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/coordination-midsession-drain.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/coordination-midsession-drain.sh\"; printf \"[hook-wrapper] coordination-midsession-drain.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
138
138
  "timeout": 30
139
139
  },
140
140
  {
141
141
  "type": "command",
142
- "command": "bash -c 'H=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/.claude/hooks/session-idle-gate.sh\"; [ -f \"$H\" ] && exec bash \"$H\" || exit 0'",
142
+ "command": "bash -c 'D=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}\"; H=\"$D/.claude/hooks/session-idle-gate.sh\"; [ -f \"$H\" ] && [ ! -L \"$H\" ] && exec bash \"$H\"; L=\"$D/mx-agent-system/agent-config/hooks/hook-launcher.sh\"; [ -f \"$L\" ] && exec bash \"$L\" \"$D\" \".claude/hooks/session-idle-gate.sh\"; printf \"[hook-wrapper] session-idle-gate.sh DID NOT RUN - this tool call was NOT checked by it. Restore: mx-agent start (issue #4853).\\n[hook-wrapper] It is registered in settings.json but missing under %s, and the hook launcher is missing too.\\n\" \"$D\" >&2; exit 1'",
143
143
  "timeout": 60
144
144
  }
145
145
  ]
@@ -28,4 +28,13 @@ export interface VerifyHooksOptions {
28
28
  path?: string;
29
29
  }
30
30
  export declare function runVerifyHooks(options?: VerifyHooksOptions): void;
31
+ /** Append-only record written by agent-config/hooks/hook-launcher.sh on a heal. */
32
+ export declare function healLogPath(): string;
33
+ export interface HealLogEntry {
34
+ timestamp: string;
35
+ worktree: string;
36
+ hook: string;
37
+ detail: string;
38
+ }
39
+ export declare function readHealLog(worktreePath: string): HealLogEntry[];
31
40
  //# sourceMappingURL=verify-hooks.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"verify-hooks.d.ts","sourceRoot":"","sources":["../../src/commands/verify-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AASH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAoCrE"}
1
+ {"version":3,"file":"verify-hooks.d.ts","sourceRoot":"","sources":["../../src/commands/verify-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAsCrE;AAED,mFAAmF;AACnF,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AA4CD,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,EAAE,CAYhE"}
@@ -22,7 +22,9 @@
22
22
  * restore every file). Non-blocking by design in the skill, which treats
23
23
  * a non-zero exit as fail-open.
24
24
  */
25
- import { resolve } from 'path';
25
+ import { closeSync, existsSync, openSync, readSync, statSync } from 'fs';
26
+ import { homedir } from 'os';
27
+ import { join, resolve } from 'path';
26
28
  import chalk from 'chalk';
27
29
  import { checkHookCompleteness } from '../lib/hook-completeness.js';
28
30
  import { verifyAndHealHooks } from '../lib/claude.js';
@@ -40,6 +42,7 @@ export function runVerifyHooks(options = {}) {
40
42
  catch {
41
43
  // No project root / config — defaults inside the lib apply.
42
44
  }
45
+ reportHealHistory(worktreePath);
43
46
  const result = checkHookCompleteness(worktreePath, { configSource: cfg.configSource });
44
47
  if (result.complete) {
45
48
  console.log(chalk.green('✓ Hook completeness: all expected guards registered and present.'));
@@ -62,6 +65,96 @@ export function runVerifyHooks(options = {}) {
62
65
  process.exitCode = 1;
63
66
  }
64
67
  }
68
+ /** Append-only record written by agent-config/hooks/hook-launcher.sh on a heal. */
69
+ export function healLogPath() {
70
+ return join(homedir(), '.mx-agent', 'hook-heal.log');
71
+ }
72
+ /**
73
+ * Parse the heal log, keeping only entries for `worktreePath`.
74
+ *
75
+ * Why this exists (#4853): when hook-launcher.sh restores a registered-but-missing
76
+ * hook it CANNOT announce that fact to the session — it must exit with the restored
77
+ * hook's own code, and Claude Code discards stderr from a hook that exits 0. A
78
+ * worktree whose guard keeps getting deleted would therefore self-repair forever
79
+ * and tell nobody. The launcher instead appends one line per heal to
80
+ * `~/.mx-agent/hook-heal.log` (outside `.claude/`, so regeneration does not prune
81
+ * it) and this command prints it. Never throws: a missing or malformed log is not
82
+ * an error, it is the normal case.
83
+ */
84
+ /** Bytes of the heal log this command will hold in memory. See readTail. */
85
+ const HEAL_LOG_TAIL_BYTES = 256 * 1024;
86
+ /**
87
+ * Read at most the last `maxBytes` of a file, dropping the leading partial line.
88
+ *
89
+ * The launcher rotates the log at 1 MB, but rotation is best-effort (it is
90
+ * skipped when the temp write fails, and the launcher may not run again for a
91
+ * while) so the reader must not assume a bound. The log grows one ~200-byte
92
+ * record per tool call in exactly the scenario this feature exists to detect —
93
+ * a guard being deleted repeatedly — so reading it whole would slow or exhaust
94
+ * memory precisely when the heal history is most worth reading.
95
+ */
96
+ function readTail(p, maxBytes) {
97
+ const fd = openSync(p, 'r');
98
+ try {
99
+ const size = statSync(p).size;
100
+ const start = size > maxBytes ? size - maxBytes : 0;
101
+ const buf = Buffer.alloc(Math.min(size, maxBytes));
102
+ if (buf.length === 0)
103
+ return '';
104
+ readSync(fd, buf, 0, buf.length, start);
105
+ const text = buf.toString('utf-8');
106
+ // A non-zero start almost certainly lands mid-record; that line is not a
107
+ // parseable entry, so drop it rather than emit a truncated timestamp.
108
+ return start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
109
+ }
110
+ finally {
111
+ closeSync(fd);
112
+ }
113
+ }
114
+ export function readHealLog(worktreePath) {
115
+ try {
116
+ const p = healLogPath();
117
+ if (!existsSync(p))
118
+ return [];
119
+ return readTail(p, HEAL_LOG_TAIL_BYTES)
120
+ .split('\n')
121
+ .map((line) => line.split('\t'))
122
+ .filter((f) => f.length >= 3 && f[1] === worktreePath)
123
+ .map((f) => ({ timestamp: f[0], worktree: f[1], hook: f[2], detail: f[3] ?? '' }));
124
+ }
125
+ catch {
126
+ return [];
127
+ }
128
+ }
129
+ /**
130
+ * Strip control characters from a log field before printing it.
131
+ *
132
+ * The launcher validates the hook name and strips control bytes from the paths
133
+ * it writes, so it never produces such a record. But the log is a plain file in
134
+ * $HOME: anyone who can write it can put ANSI escapes in a field, and chalk.dim
135
+ * does not strip them — the output of this command is read by agents.
136
+ */
137
+ function safeField(s) {
138
+ // eslint-disable-next-line no-control-regex
139
+ return s.replace(/[\x00-\x1f\x7f]/g, '?');
140
+ }
141
+ /** Print the heal history for this worktree. Silent when there is none. */
142
+ function reportHealHistory(worktreePath) {
143
+ const entries = readHealLog(worktreePath);
144
+ if (entries.length === 0)
145
+ return;
146
+ const byHook = new Map();
147
+ for (const e of entries)
148
+ byHook.set(e.hook, (byHook.get(e.hook) ?? 0) + 1);
149
+ console.log(chalk.yellow(`⚠ Hook auto-heal history: ${entries.length} registered hook${entries.length === 1 ? '' : 's'} ` +
150
+ `had to be restored at call time in this worktree. Something is removing them.`));
151
+ for (const [hook, count] of byHook) {
152
+ console.log(chalk.dim(` ${safeField(hook)} — restored ${count}x`));
153
+ }
154
+ const last = entries[entries.length - 1];
155
+ console.log(chalk.dim(` most recent: ${safeField(last.timestamp)} ${safeField(last.hook)} ${safeField(last.detail)}`));
156
+ console.log(chalk.dim(` log: ${healLogPath()}`));
157
+ }
65
158
  /** Human-readable problem lines for the three unhealthy categories. */
66
159
  function describeProblems(r) {
67
160
  const lines = [];
@@ -1 +1 @@
1
- {"version":3,"file":"verify-hooks.js","sourceRoot":"","sources":["../../src/commands/verify-hooks.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"verify-hooks.js","sourceRoot":"","sources":["../../src/commands/verify-hooks.ts"],"names":[],"mappings":"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"}