@memnexus-ai/mx-agent-cli 0.1.264 → 0.1.266

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 (48) hide show
  1. package/dist/__tests__/runtime-codex-adapter.test.js +18 -5
  2. package/dist/__tests__/runtime-codex-adapter.test.js.map +1 -1
  3. package/dist/__tests__/runtime-codex-config.test.js +133 -12
  4. package/dist/__tests__/runtime-codex-config.test.js.map +1 -1
  5. package/dist/__tests__/runtime-codex-guard-proof.test.d.ts +2 -0
  6. package/dist/__tests__/runtime-codex-guard-proof.test.d.ts.map +1 -0
  7. package/dist/__tests__/runtime-codex-guard-proof.test.js +747 -0
  8. package/dist/__tests__/runtime-codex-guard-proof.test.js.map +1 -0
  9. package/dist/__tests__/start-runtime-wiring.test.js +91 -2
  10. package/dist/__tests__/start-runtime-wiring.test.js.map +1 -1
  11. package/dist/agent-config/hooks/auto-capture-session-end.sh +82 -1
  12. package/dist/agent-config/hooks/ci-validate-hook.sh +77 -0
  13. package/dist/agent-config/hooks/coordination-midsession-drain.sh +79 -0
  14. package/dist/agent-config/hooks/delegation-audit.sh +79 -0
  15. package/dist/agent-config/hooks/deploy-verification-reminder.sh +79 -0
  16. package/dist/agent-config/hooks/gh-pr-edit-guard.sh +79 -0
  17. package/dist/agent-config/hooks/git-mutation-guard.sh +79 -0
  18. package/dist/agent-config/hooks/iteration-log-check.sh +79 -0
  19. package/dist/agent-config/hooks/memory-checkpoint-reminder.sh +79 -0
  20. package/dist/agent-config/hooks/mx-guard-hook.sh +77 -0
  21. package/dist/agent-config/hooks/named-memory-write-guard.sh +79 -0
  22. package/dist/agent-config/hooks/observability-sync.sh +77 -0
  23. package/dist/agent-config/hooks/session-idle-gate.sh +79 -0
  24. package/dist/agent-config/hooks/workflow-dispatch-guard.sh +77 -0
  25. package/dist/agent-config/hooks/worktree-guard.sh +79 -0
  26. package/dist/commands/codex-prove-guards.d.ts +62 -0
  27. package/dist/commands/codex-prove-guards.d.ts.map +1 -0
  28. package/dist/commands/codex-prove-guards.js +353 -0
  29. package/dist/commands/codex-prove-guards.js.map +1 -0
  30. package/dist/commands/start.d.ts.map +1 -1
  31. package/dist/commands/start.js +27 -1
  32. package/dist/commands/start.js.map +1 -1
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +33 -0
  35. package/dist/index.js.map +1 -1
  36. package/dist/lib/runtime/codex-adapter.d.ts +42 -2
  37. package/dist/lib/runtime/codex-adapter.d.ts.map +1 -1
  38. package/dist/lib/runtime/codex-adapter.js +81 -9
  39. package/dist/lib/runtime/codex-adapter.js.map +1 -1
  40. package/dist/lib/runtime/codex-config.d.ts +53 -4
  41. package/dist/lib/runtime/codex-config.d.ts.map +1 -1
  42. package/dist/lib/runtime/codex-config.js +164 -15
  43. package/dist/lib/runtime/codex-config.js.map +1 -1
  44. package/dist/lib/runtime/codex-guard-proof.d.ts +127 -0
  45. package/dist/lib/runtime/codex-guard-proof.d.ts.map +1 -0
  46. package/dist/lib/runtime/codex-guard-proof.js +372 -0
  47. package/dist/lib/runtime/codex-guard-proof.js.map +1 -0
  48. package/package.json +1 -1
@@ -10,6 +10,85 @@
10
10
  # Output: advisory message to stdout (when threshold met)
11
11
  # Exit: always 0 (never blocks)
12
12
 
13
+ MXHT_HOOK=delegation-audit MXHT_EVENT=Stop MXHT_TOOL=-
14
+ # >>> SHARED hook-timing probe v1
15
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
16
+ # separated from time spent waiting on the API when a session stalls mid-stream.
17
+ # Appends one line to a local, gitignored log. Read it with
18
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
19
+ #
20
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
21
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
22
+ # default. A diagnostic that can break the gate it observes is worse than no
23
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
24
+ # guard on the PreToolUse path at once. Every step below is guarded and every
25
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
26
+ #
27
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
28
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
29
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
30
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
31
+ MXHT_T0="${EPOCHREALTIME:-}"
32
+ _mxht_emit() {
33
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
34
+ MXHT_DONE=1
35
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
36
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
37
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
38
+ [ -n "$root" ] && [ -d "$root" ] || return 0
39
+ local dir="$root/.mx-hook-timing"
40
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
41
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
42
+ # strip both forms and subtract as plain integer microseconds.
43
+ local dur=-1
44
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
45
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
46
+ local stamp hour
47
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
48
+ printf -v hour '%(%H)T' -1
49
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
50
+ # is at most 24 files each holding one hour of this machine's hook calls. The
51
+ # first writer into a slot on a new day truncates it instead of appending —
52
+ # detected by reading the slot's first line, which is a builtin read (no stat,
53
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
54
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
55
+ local f="$dir/h$hour.log" first="" line
56
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
57
+ # Anything else is a silent no-op. Two concrete failures if this check is
58
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
59
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
60
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
61
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
62
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
63
+ # dangling symlink, so -L is needed to catch that case too).
64
+ if [ -e "$f" ] || [ -L "$f" ]; then
65
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
66
+ fi
67
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
68
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
69
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
70
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
71
+ # concurrent hooks cannot interleave partial lines.
72
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
73
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
74
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
75
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
76
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
77
+ else
78
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
79
+ fi
80
+ }
81
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
82
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
83
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
84
+ # final printf failing on an unwritable slot is the reachable case — replaces the
85
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
86
+ # harness reads as "error", not "block", so the command it meant to block runs.
87
+ # Pinned verbatim by hook-timing-parity.test.sh.
88
+ trap '_mxht_emit || :' EXIT
89
+ # <<< SHARED hook-timing probe v1
90
+
91
+
13
92
  # Fail-open: any error -> allow session to end normally
14
93
  trap 'exit 0' ERR
15
94
 
@@ -7,6 +7,85 @@
7
7
  # Output: reminder message to stdout when deploy pending and not verified
8
8
  # Exit: 2 when reminder is emitted, 0 otherwise
9
9
 
10
+ MXHT_HOOK=deploy-verification-reminder MXHT_EVENT=PostToolUse MXHT_TOOL=Bash
11
+ # >>> SHARED hook-timing probe v1
12
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
13
+ # separated from time spent waiting on the API when a session stalls mid-stream.
14
+ # Appends one line to a local, gitignored log. Read it with
15
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
16
+ #
17
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
18
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
19
+ # default. A diagnostic that can break the gate it observes is worse than no
20
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
21
+ # guard on the PreToolUse path at once. Every step below is guarded and every
22
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
23
+ #
24
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
25
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
26
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
27
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
28
+ MXHT_T0="${EPOCHREALTIME:-}"
29
+ _mxht_emit() {
30
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
31
+ MXHT_DONE=1
32
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
33
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
34
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
35
+ [ -n "$root" ] && [ -d "$root" ] || return 0
36
+ local dir="$root/.mx-hook-timing"
37
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
38
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
39
+ # strip both forms and subtract as plain integer microseconds.
40
+ local dur=-1
41
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
42
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
43
+ local stamp hour
44
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
45
+ printf -v hour '%(%H)T' -1
46
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
47
+ # is at most 24 files each holding one hour of this machine's hook calls. The
48
+ # first writer into a slot on a new day truncates it instead of appending —
49
+ # detected by reading the slot's first line, which is a builtin read (no stat,
50
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
51
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
52
+ local f="$dir/h$hour.log" first="" line
53
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
54
+ # Anything else is a silent no-op. Two concrete failures if this check is
55
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
56
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
57
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
58
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
59
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
60
+ # dangling symlink, so -L is needed to catch that case too).
61
+ if [ -e "$f" ] || [ -L "$f" ]; then
62
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
63
+ fi
64
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
65
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
66
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
67
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
68
+ # concurrent hooks cannot interleave partial lines.
69
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
70
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
71
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
72
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
73
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
74
+ else
75
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
76
+ fi
77
+ }
78
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
79
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
80
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
81
+ # final printf failing on an unwritable slot is the reachable case — replaces the
82
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
83
+ # harness reads as "error", not "block", so the command it meant to block runs.
84
+ # Pinned verbatim by hook-timing-parity.test.sh.
85
+ trap '_mxht_emit || :' EXIT
86
+ # <<< SHARED hook-timing probe v1
87
+
88
+
10
89
  # Fail-open: any error → exit 0 silently
11
90
  trap 'exit 0' ERR
12
91
  set -u
@@ -55,6 +55,85 @@
55
55
  # here is one confusing gh failure, not lost work, and matching the whole
56
56
  # command loosely instead of anchoring per segment is its own defect (#4804).
57
57
 
58
+ MXHT_HOOK=gh-pr-edit-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
59
+ # >>> SHARED hook-timing probe v1
60
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
61
+ # separated from time spent waiting on the API when a session stalls mid-stream.
62
+ # Appends one line to a local, gitignored log. Read it with
63
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
64
+ #
65
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
66
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
67
+ # default. A diagnostic that can break the gate it observes is worse than no
68
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
69
+ # guard on the PreToolUse path at once. Every step below is guarded and every
70
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
71
+ #
72
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
73
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
74
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
75
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
76
+ MXHT_T0="${EPOCHREALTIME:-}"
77
+ _mxht_emit() {
78
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
79
+ MXHT_DONE=1
80
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
81
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
82
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
83
+ [ -n "$root" ] && [ -d "$root" ] || return 0
84
+ local dir="$root/.mx-hook-timing"
85
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
86
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
87
+ # strip both forms and subtract as plain integer microseconds.
88
+ local dur=-1
89
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
90
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
91
+ local stamp hour
92
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
93
+ printf -v hour '%(%H)T' -1
94
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
95
+ # is at most 24 files each holding one hour of this machine's hook calls. The
96
+ # first writer into a slot on a new day truncates it instead of appending —
97
+ # detected by reading the slot's first line, which is a builtin read (no stat,
98
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
99
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
100
+ local f="$dir/h$hour.log" first="" line
101
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
102
+ # Anything else is a silent no-op. Two concrete failures if this check is
103
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
104
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
105
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
106
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
107
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
108
+ # dangling symlink, so -L is needed to catch that case too).
109
+ if [ -e "$f" ] || [ -L "$f" ]; then
110
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
111
+ fi
112
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
113
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
114
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
115
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
116
+ # concurrent hooks cannot interleave partial lines.
117
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
118
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
119
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
120
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
121
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
122
+ else
123
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
124
+ fi
125
+ }
126
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
127
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
128
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
129
+ # final printf failing on an unwritable slot is the reachable case — replaces the
130
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
131
+ # harness reads as "error", not "block", so the command it meant to block runs.
132
+ # Pinned verbatim by hook-timing-parity.test.sh.
133
+ trap '_mxht_emit || :' EXIT
134
+ # <<< SHARED hook-timing probe v1
135
+
136
+
58
137
  set -uo pipefail
59
138
 
60
139
  # Read stdin with the bash redirection builtin rather than `cat`. A hook whose
@@ -77,6 +77,85 @@
77
77
  # match. The guard deters accidental discards; it does not stop a determined
78
78
  # caller.
79
79
 
80
+ MXHT_HOOK=git-mutation-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
81
+ # >>> SHARED hook-timing probe v1
82
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
83
+ # separated from time spent waiting on the API when a session stalls mid-stream.
84
+ # Appends one line to a local, gitignored log. Read it with
85
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
86
+ #
87
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
88
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
89
+ # default. A diagnostic that can break the gate it observes is worse than no
90
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
91
+ # guard on the PreToolUse path at once. Every step below is guarded and every
92
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
93
+ #
94
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
95
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
96
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
97
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
98
+ MXHT_T0="${EPOCHREALTIME:-}"
99
+ _mxht_emit() {
100
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
101
+ MXHT_DONE=1
102
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
103
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
104
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
105
+ [ -n "$root" ] && [ -d "$root" ] || return 0
106
+ local dir="$root/.mx-hook-timing"
107
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
108
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
109
+ # strip both forms and subtract as plain integer microseconds.
110
+ local dur=-1
111
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
112
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
113
+ local stamp hour
114
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
115
+ printf -v hour '%(%H)T' -1
116
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
117
+ # is at most 24 files each holding one hour of this machine's hook calls. The
118
+ # first writer into a slot on a new day truncates it instead of appending —
119
+ # detected by reading the slot's first line, which is a builtin read (no stat,
120
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
121
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
122
+ local f="$dir/h$hour.log" first="" line
123
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
124
+ # Anything else is a silent no-op. Two concrete failures if this check is
125
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
126
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
127
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
128
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
129
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
130
+ # dangling symlink, so -L is needed to catch that case too).
131
+ if [ -e "$f" ] || [ -L "$f" ]; then
132
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
133
+ fi
134
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
135
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
136
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
137
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
138
+ # concurrent hooks cannot interleave partial lines.
139
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
140
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
141
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
142
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
143
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
144
+ else
145
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
146
+ fi
147
+ }
148
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
149
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
150
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
151
+ # final printf failing on an unwritable slot is the reachable case — replaces the
152
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
153
+ # harness reads as "error", not "block", so the command it meant to block runs.
154
+ # Pinned verbatim by hook-timing-parity.test.sh.
155
+ trap '_mxht_emit || :' EXIT
156
+ # <<< SHARED hook-timing probe v1
157
+
158
+
80
159
  set -euo pipefail
81
160
 
82
161
  INPUT=$(cat)
@@ -14,6 +14,85 @@
14
14
  # mechanism used by auto-capture-session-end.sh), reads the iteration log via
15
15
  # the mx CLI, and compares timestamps.
16
16
 
17
+ MXHT_HOOK=iteration-log-check MXHT_EVENT=Stop MXHT_TOOL=-
18
+ # >>> SHARED hook-timing probe v1
19
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
20
+ # separated from time spent waiting on the API when a session stalls mid-stream.
21
+ # Appends one line to a local, gitignored log. Read it with
22
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
23
+ #
24
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
25
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
26
+ # default. A diagnostic that can break the gate it observes is worse than no
27
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
28
+ # guard on the PreToolUse path at once. Every step below is guarded and every
29
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
30
+ #
31
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
32
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
33
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
34
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
35
+ MXHT_T0="${EPOCHREALTIME:-}"
36
+ _mxht_emit() {
37
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
38
+ MXHT_DONE=1
39
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
40
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
41
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
42
+ [ -n "$root" ] && [ -d "$root" ] || return 0
43
+ local dir="$root/.mx-hook-timing"
44
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
45
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
46
+ # strip both forms and subtract as plain integer microseconds.
47
+ local dur=-1
48
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
49
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
50
+ local stamp hour
51
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
52
+ printf -v hour '%(%H)T' -1
53
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
54
+ # is at most 24 files each holding one hour of this machine's hook calls. The
55
+ # first writer into a slot on a new day truncates it instead of appending —
56
+ # detected by reading the slot's first line, which is a builtin read (no stat,
57
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
58
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
59
+ local f="$dir/h$hour.log" first="" line
60
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
61
+ # Anything else is a silent no-op. Two concrete failures if this check is
62
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
63
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
64
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
65
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
66
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
67
+ # dangling symlink, so -L is needed to catch that case too).
68
+ if [ -e "$f" ] || [ -L "$f" ]; then
69
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
70
+ fi
71
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
72
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
73
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
74
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
75
+ # concurrent hooks cannot interleave partial lines.
76
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
77
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
78
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
79
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
80
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
81
+ else
82
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
83
+ fi
84
+ }
85
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
86
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
87
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
88
+ # final printf failing on an unwritable slot is the reachable case — replaces the
89
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
90
+ # harness reads as "error", not "block", so the command it meant to block runs.
91
+ # Pinned verbatim by hook-timing-parity.test.sh.
92
+ trap '_mxht_emit || :' EXIT
93
+ # <<< SHARED hook-timing probe v1
94
+
95
+
17
96
  # Fail-open: any unexpected error → exit 0 silently
18
97
  trap 'exit 0' ERR
19
98
  set -u
@@ -71,6 +71,85 @@
71
71
  # as capable, not as read-only, so a broken jq degrades to the demand rather than
72
72
  # turning the gate off (see PAYLOAD_OPAQUE below).
73
73
 
74
+ MXHT_HOOK=memory-checkpoint-reminder MXHT_EVENT=PreToolUse MXHT_TOOL=-
75
+ # >>> SHARED hook-timing probe v1
76
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
77
+ # separated from time spent waiting on the API when a session stalls mid-stream.
78
+ # Appends one line to a local, gitignored log. Read it with
79
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
80
+ #
81
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
82
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
83
+ # default. A diagnostic that can break the gate it observes is worse than no
84
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
85
+ # guard on the PreToolUse path at once. Every step below is guarded and every
86
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
87
+ #
88
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
89
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
90
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
91
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
92
+ MXHT_T0="${EPOCHREALTIME:-}"
93
+ _mxht_emit() {
94
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
95
+ MXHT_DONE=1
96
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
97
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
98
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
99
+ [ -n "$root" ] && [ -d "$root" ] || return 0
100
+ local dir="$root/.mx-hook-timing"
101
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
102
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
103
+ # strip both forms and subtract as plain integer microseconds.
104
+ local dur=-1
105
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
106
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
107
+ local stamp hour
108
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
109
+ printf -v hour '%(%H)T' -1
110
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
111
+ # is at most 24 files each holding one hour of this machine's hook calls. The
112
+ # first writer into a slot on a new day truncates it instead of appending —
113
+ # detected by reading the slot's first line, which is a builtin read (no stat,
114
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
115
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
116
+ local f="$dir/h$hour.log" first="" line
117
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
118
+ # Anything else is a silent no-op. Two concrete failures if this check is
119
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
120
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
121
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
122
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
123
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
124
+ # dangling symlink, so -L is needed to catch that case too).
125
+ if [ -e "$f" ] || [ -L "$f" ]; then
126
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
127
+ fi
128
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
129
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
130
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
131
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
132
+ # concurrent hooks cannot interleave partial lines.
133
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
134
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
135
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
136
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
137
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
138
+ else
139
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
140
+ fi
141
+ }
142
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
143
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
144
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
145
+ # final printf failing on an unwritable slot is the reachable case — replaces the
146
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
147
+ # harness reads as "error", not "block", so the command it meant to block runs.
148
+ # Pinned verbatim by hook-timing-parity.test.sh.
149
+ trap '_mxht_emit || :' EXIT
150
+ # <<< SHARED hook-timing probe v1
151
+
152
+
74
153
  # Fail-open: any error → exit 0 silently
75
154
  trap 'exit 0' ERR
76
155
  set -u
@@ -38,6 +38,83 @@
38
38
  # `git -C /treeA push && git -C /treeB push` pushed unlinted. Every push
39
39
  # segment is now resolved and every distinct toplevel linted.
40
40
 
41
+ MXHT_HOOK=mx-guard-hook MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
42
+ # >>> SHARED hook-timing probe v1
43
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
44
+ # separated from time spent waiting on the API when a session stalls mid-stream.
45
+ # Appends one line to a local, gitignored log. Read it with
46
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
47
+ #
48
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
49
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
50
+ # default. A diagnostic that can break the gate it observes is worse than no
51
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
52
+ # guard on the PreToolUse path at once. Every step below is guarded and every
53
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
54
+ #
55
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
56
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
57
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
58
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
59
+ MXHT_T0="${EPOCHREALTIME:-}"
60
+ _mxht_emit() {
61
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
62
+ MXHT_DONE=1
63
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
64
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
65
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
66
+ [ -n "$root" ] && [ -d "$root" ] || return 0
67
+ local dir="$root/.mx-hook-timing"
68
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
69
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
70
+ # strip both forms and subtract as plain integer microseconds.
71
+ local dur=-1
72
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
73
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
74
+ local stamp hour
75
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
76
+ printf -v hour '%(%H)T' -1
77
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
78
+ # is at most 24 files each holding one hour of this machine's hook calls. The
79
+ # first writer into a slot on a new day truncates it instead of appending —
80
+ # detected by reading the slot's first line, which is a builtin read (no stat,
81
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
82
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
83
+ local f="$dir/h$hour.log" first="" line
84
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
85
+ # Anything else is a silent no-op. Two concrete failures if this check is
86
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
87
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
88
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
89
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
90
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
91
+ # dangling symlink, so -L is needed to catch that case too).
92
+ if [ -e "$f" ] || [ -L "$f" ]; then
93
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
94
+ fi
95
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
96
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
97
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
98
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
99
+ # concurrent hooks cannot interleave partial lines.
100
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
101
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
102
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
103
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
104
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
105
+ else
106
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
107
+ fi
108
+ }
109
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
110
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
111
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
112
+ # final printf failing on an unwritable slot is the reachable case — replaces the
113
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
114
+ # harness reads as "error", not "block", so the command it meant to block runs.
115
+ # Pinned verbatim by hook-timing-parity.test.sh.
116
+ trap '_mxht_emit || :' EXIT
117
+ # <<< SHARED hook-timing probe v1
41
118
 
42
119
 
43
120
  # Read hook input from stdin