@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.
- package/dist/__tests__/runtime-codex-adapter.test.js +18 -5
- package/dist/__tests__/runtime-codex-adapter.test.js.map +1 -1
- package/dist/__tests__/runtime-codex-config.test.js +133 -12
- package/dist/__tests__/runtime-codex-config.test.js.map +1 -1
- package/dist/__tests__/runtime-codex-guard-proof.test.d.ts +2 -0
- package/dist/__tests__/runtime-codex-guard-proof.test.d.ts.map +1 -0
- package/dist/__tests__/runtime-codex-guard-proof.test.js +747 -0
- package/dist/__tests__/runtime-codex-guard-proof.test.js.map +1 -0
- package/dist/__tests__/start-runtime-wiring.test.js +91 -2
- package/dist/__tests__/start-runtime-wiring.test.js.map +1 -1
- package/dist/agent-config/hooks/auto-capture-session-end.sh +82 -1
- package/dist/agent-config/hooks/ci-validate-hook.sh +77 -0
- package/dist/agent-config/hooks/coordination-midsession-drain.sh +79 -0
- package/dist/agent-config/hooks/delegation-audit.sh +79 -0
- package/dist/agent-config/hooks/deploy-verification-reminder.sh +79 -0
- package/dist/agent-config/hooks/gh-pr-edit-guard.sh +79 -0
- package/dist/agent-config/hooks/git-mutation-guard.sh +79 -0
- package/dist/agent-config/hooks/iteration-log-check.sh +79 -0
- package/dist/agent-config/hooks/memory-checkpoint-reminder.sh +79 -0
- package/dist/agent-config/hooks/mx-guard-hook.sh +77 -0
- package/dist/agent-config/hooks/named-memory-write-guard.sh +79 -0
- package/dist/agent-config/hooks/observability-sync.sh +77 -0
- package/dist/agent-config/hooks/session-idle-gate.sh +79 -0
- package/dist/agent-config/hooks/workflow-dispatch-guard.sh +77 -0
- package/dist/agent-config/hooks/worktree-guard.sh +79 -0
- package/dist/commands/codex-prove-guards.d.ts +62 -0
- package/dist/commands/codex-prove-guards.d.ts.map +1 -0
- package/dist/commands/codex-prove-guards.js +353 -0
- package/dist/commands/codex-prove-guards.js.map +1 -0
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +27 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +33 -0
- package/dist/index.js.map +1 -1
- package/dist/lib/runtime/codex-adapter.d.ts +42 -2
- package/dist/lib/runtime/codex-adapter.d.ts.map +1 -1
- package/dist/lib/runtime/codex-adapter.js +81 -9
- package/dist/lib/runtime/codex-adapter.js.map +1 -1
- package/dist/lib/runtime/codex-config.d.ts +53 -4
- package/dist/lib/runtime/codex-config.d.ts.map +1 -1
- package/dist/lib/runtime/codex-config.js +164 -15
- package/dist/lib/runtime/codex-config.js.map +1 -1
- package/dist/lib/runtime/codex-guard-proof.d.ts +127 -0
- package/dist/lib/runtime/codex-guard-proof.d.ts.map +1 -0
- package/dist/lib/runtime/codex-guard-proof.js +372 -0
- package/dist/lib/runtime/codex-guard-proof.js.map +1 -0
- package/package.json +1 -1
|
@@ -39,6 +39,85 @@
|
|
|
39
39
|
# refuse()->stderr+exit2, fail-open), iteration-log-check.sh (best-effort
|
|
40
40
|
# emit_telemetry with the MX_HOOK_TELEMETRY kill-switch and mx-on-PATH guard).
|
|
41
41
|
|
|
42
|
+
MXHT_HOOK=named-memory-write-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
|
|
43
|
+
# >>> SHARED hook-timing probe v1
|
|
44
|
+
# Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
|
|
45
|
+
# separated from time spent waiting on the API when a session stalls mid-stream.
|
|
46
|
+
# Appends one line to a local, gitignored log. Read it with
|
|
47
|
+
# mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
|
|
48
|
+
#
|
|
49
|
+
# FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
|
|
50
|
+
# fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
|
|
51
|
+
# default. A diagnostic that can break the gate it observes is worse than no
|
|
52
|
+
# diagnostic: an unwritable path or a full disk would otherwise take out every
|
|
53
|
+
# guard on the PreToolUse path at once. Every step below is guarded and every
|
|
54
|
+
# failure path is a silent no-op that leaves the hook's behaviour untouched.
|
|
55
|
+
#
|
|
56
|
+
# NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
|
|
57
|
+
# -T, one read, one append). No subprocess, no network, no JSON parsing, and the
|
|
58
|
+
# hook's stdin is never touched (the hook owns it). mkdir runs at most once per
|
|
59
|
+
# worktree. Kill switch: MX_HOOK_TIMING=0.
|
|
60
|
+
MXHT_T0="${EPOCHREALTIME:-}"
|
|
61
|
+
_mxht_emit() {
|
|
62
|
+
[ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
|
|
63
|
+
MXHT_DONE=1
|
|
64
|
+
[ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
|
|
65
|
+
[ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
|
|
66
|
+
local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
|
|
67
|
+
[ -n "$root" ] && [ -d "$root" ] || return 0
|
|
68
|
+
local dir="$root/.mx-hook-timing"
|
|
69
|
+
[ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
|
|
70
|
+
# EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
|
|
71
|
+
# strip both forms and subtract as plain integer microseconds.
|
|
72
|
+
local dur=-1
|
|
73
|
+
{ dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
|
|
74
|
+
[ "$dur" -ge 0 ] 2>/dev/null || return 0
|
|
75
|
+
local stamp hour
|
|
76
|
+
printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
|
|
77
|
+
printf -v hour '%(%H)T' -1
|
|
78
|
+
# BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
|
|
79
|
+
# is at most 24 files each holding one hour of this machine's hook calls. The
|
|
80
|
+
# first writer into a slot on a new day truncates it instead of appending —
|
|
81
|
+
# detected by reading the slot's first line, which is a builtin read (no stat,
|
|
82
|
+
# no rm, no find, no cron). Two writers can race that truncation and lose a
|
|
83
|
+
# line or two at an hour boundary; that is acceptable for a sampling diagnostic.
|
|
84
|
+
local f="$dir/h$hour.log" first="" line
|
|
85
|
+
# THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
|
|
86
|
+
# Anything else is a silent no-op. Two concrete failures if this check is
|
|
87
|
+
# dropped: a FIFO at the slot makes the `read` below block until the hook's
|
|
88
|
+
# settings.json timeout kills it, and a PreToolUse guard killed that way loses
|
|
89
|
+
# its exit 2 — the command it meant to block then runs; a symlink at the slot
|
|
90
|
+
# sends the day-rollover truncation onto the symlink's target. The `-e || -L`
|
|
91
|
+
# wrapper is what lets a not-yet-created slot through (-e is false for a
|
|
92
|
+
# dangling symlink, so -L is needed to catch that case too).
|
|
93
|
+
if [ -e "$f" ] || [ -L "$f" ]; then
|
|
94
|
+
[ -f "$f" ] && [ ! -L "$f" ] || return 0
|
|
95
|
+
fi
|
|
96
|
+
[ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
|
|
97
|
+
printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
|
|
98
|
+
"$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
|
|
99
|
+
# One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
|
|
100
|
+
# concurrent hooks cannot interleave partial lines.
|
|
101
|
+
# The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
|
|
102
|
+
# reported by the shell before an inner 2>/dev/null would be in effect, and a
|
|
103
|
+
# "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
|
|
104
|
+
if [ "${first%% *}" = "${stamp%% *}" ]; then
|
|
105
|
+
{ printf '%s' "$line" >>"$f"; } 2>/dev/null
|
|
106
|
+
else
|
|
107
|
+
{ printf '%s' "$line" >"$f"; } 2>/dev/null
|
|
108
|
+
fi
|
|
109
|
+
}
|
|
110
|
+
# `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
|
|
111
|
+
# this block is inlined into run under `set -e`, and the EXIT trap runs with
|
|
112
|
+
# errexit still in force. Without `|| :`, a non-zero return from the probe — the
|
|
113
|
+
# final printf failing on an unwritable slot is the reachable case — replaces the
|
|
114
|
+
# hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
|
|
115
|
+
# harness reads as "error", not "block", so the command it meant to block runs.
|
|
116
|
+
# Pinned verbatim by hook-timing-parity.test.sh.
|
|
117
|
+
trap '_mxht_emit || :' EXIT
|
|
118
|
+
# <<< SHARED hook-timing probe v1
|
|
119
|
+
|
|
120
|
+
|
|
42
121
|
set -euo pipefail
|
|
43
122
|
|
|
44
123
|
# ── Config ───────────────────────────────────────────────────────────────────
|
|
@@ -3,6 +3,83 @@
|
|
|
3
3
|
# Logs sync failures to the local startup JSONL so they are visible at next session start.
|
|
4
4
|
# FAIL-OPEN: always exits 0 regardless of sync outcome.
|
|
5
5
|
|
|
6
|
+
MXHT_HOOK=observability-sync MXHT_EVENT=Stop MXHT_TOOL=-
|
|
7
|
+
# >>> SHARED hook-timing probe v1
|
|
8
|
+
# Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
|
|
9
|
+
# separated from time spent waiting on the API when a session stalls mid-stream.
|
|
10
|
+
# Appends one line to a local, gitignored log. Read it with
|
|
11
|
+
# mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
|
|
12
|
+
#
|
|
13
|
+
# FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
|
|
14
|
+
# fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
|
|
15
|
+
# default. A diagnostic that can break the gate it observes is worse than no
|
|
16
|
+
# diagnostic: an unwritable path or a full disk would otherwise take out every
|
|
17
|
+
# guard on the PreToolUse path at once. Every step below is guarded and every
|
|
18
|
+
# failure path is a silent no-op that leaves the hook's behaviour untouched.
|
|
19
|
+
#
|
|
20
|
+
# NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
|
|
21
|
+
# -T, one read, one append). No subprocess, no network, no JSON parsing, and the
|
|
22
|
+
# hook's stdin is never touched (the hook owns it). mkdir runs at most once per
|
|
23
|
+
# worktree. Kill switch: MX_HOOK_TIMING=0.
|
|
24
|
+
MXHT_T0="${EPOCHREALTIME:-}"
|
|
25
|
+
_mxht_emit() {
|
|
26
|
+
[ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
|
|
27
|
+
MXHT_DONE=1
|
|
28
|
+
[ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
|
|
29
|
+
[ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
|
|
30
|
+
local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
|
|
31
|
+
[ -n "$root" ] && [ -d "$root" ] || return 0
|
|
32
|
+
local dir="$root/.mx-hook-timing"
|
|
33
|
+
[ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
|
|
34
|
+
# EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
|
|
35
|
+
# strip both forms and subtract as plain integer microseconds.
|
|
36
|
+
local dur=-1
|
|
37
|
+
{ dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
|
|
38
|
+
[ "$dur" -ge 0 ] 2>/dev/null || return 0
|
|
39
|
+
local stamp hour
|
|
40
|
+
printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
|
|
41
|
+
printf -v hour '%(%H)T' -1
|
|
42
|
+
# BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
|
|
43
|
+
# is at most 24 files each holding one hour of this machine's hook calls. The
|
|
44
|
+
# first writer into a slot on a new day truncates it instead of appending —
|
|
45
|
+
# detected by reading the slot's first line, which is a builtin read (no stat,
|
|
46
|
+
# no rm, no find, no cron). Two writers can race that truncation and lose a
|
|
47
|
+
# line or two at an hour boundary; that is acceptable for a sampling diagnostic.
|
|
48
|
+
local f="$dir/h$hour.log" first="" line
|
|
49
|
+
# THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
|
|
50
|
+
# Anything else is a silent no-op. Two concrete failures if this check is
|
|
51
|
+
# dropped: a FIFO at the slot makes the `read` below block until the hook's
|
|
52
|
+
# settings.json timeout kills it, and a PreToolUse guard killed that way loses
|
|
53
|
+
# its exit 2 — the command it meant to block then runs; a symlink at the slot
|
|
54
|
+
# sends the day-rollover truncation onto the symlink's target. The `-e || -L`
|
|
55
|
+
# wrapper is what lets a not-yet-created slot through (-e is false for a
|
|
56
|
+
# dangling symlink, so -L is needed to catch that case too).
|
|
57
|
+
if [ -e "$f" ] || [ -L "$f" ]; then
|
|
58
|
+
[ -f "$f" ] && [ ! -L "$f" ] || return 0
|
|
59
|
+
fi
|
|
60
|
+
[ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
|
|
61
|
+
printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
|
|
62
|
+
"$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
|
|
63
|
+
# One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
|
|
64
|
+
# concurrent hooks cannot interleave partial lines.
|
|
65
|
+
# The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
|
|
66
|
+
# reported by the shell before an inner 2>/dev/null would be in effect, and a
|
|
67
|
+
# "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
|
|
68
|
+
if [ "${first%% *}" = "${stamp%% *}" ]; then
|
|
69
|
+
{ printf '%s' "$line" >>"$f"; } 2>/dev/null
|
|
70
|
+
else
|
|
71
|
+
{ printf '%s' "$line" >"$f"; } 2>/dev/null
|
|
72
|
+
fi
|
|
73
|
+
}
|
|
74
|
+
# `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
|
|
75
|
+
# this block is inlined into run under `set -e`, and the EXIT trap runs with
|
|
76
|
+
# errexit still in force. Without `|| :`, a non-zero return from the probe — the
|
|
77
|
+
# final printf failing on an unwritable slot is the reachable case — replaces the
|
|
78
|
+
# hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
|
|
79
|
+
# harness reads as "error", not "block", so the command it meant to block runs.
|
|
80
|
+
# Pinned verbatim by hook-timing-parity.test.sh.
|
|
81
|
+
trap '_mxht_emit || :' EXIT
|
|
82
|
+
# <<< SHARED hook-timing probe v1
|
|
6
83
|
|
|
7
84
|
|
|
8
85
|
set -euo pipefail
|
|
@@ -46,6 +46,85 @@
|
|
|
46
46
|
# by the party it guards. Precedent: 6f934aaee removed the same affordance from
|
|
47
47
|
# the override audit log.
|
|
48
48
|
|
|
49
|
+
MXHT_HOOK=session-idle-gate MXHT_EVENT=Stop MXHT_TOOL=-
|
|
50
|
+
# >>> SHARED hook-timing probe v1
|
|
51
|
+
# Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
|
|
52
|
+
# separated from time spent waiting on the API when a session stalls mid-stream.
|
|
53
|
+
# Appends one line to a local, gitignored log. Read it with
|
|
54
|
+
# mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
|
|
55
|
+
#
|
|
56
|
+
# FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
|
|
57
|
+
# fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
|
|
58
|
+
# default. A diagnostic that can break the gate it observes is worse than no
|
|
59
|
+
# diagnostic: an unwritable path or a full disk would otherwise take out every
|
|
60
|
+
# guard on the PreToolUse path at once. Every step below is guarded and every
|
|
61
|
+
# failure path is a silent no-op that leaves the hook's behaviour untouched.
|
|
62
|
+
#
|
|
63
|
+
# NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
|
|
64
|
+
# -T, one read, one append). No subprocess, no network, no JSON parsing, and the
|
|
65
|
+
# hook's stdin is never touched (the hook owns it). mkdir runs at most once per
|
|
66
|
+
# worktree. Kill switch: MX_HOOK_TIMING=0.
|
|
67
|
+
MXHT_T0="${EPOCHREALTIME:-}"
|
|
68
|
+
_mxht_emit() {
|
|
69
|
+
[ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
|
|
70
|
+
MXHT_DONE=1
|
|
71
|
+
[ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
|
|
72
|
+
[ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
|
|
73
|
+
local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
|
|
74
|
+
[ -n "$root" ] && [ -d "$root" ] || return 0
|
|
75
|
+
local dir="$root/.mx-hook-timing"
|
|
76
|
+
[ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
|
|
77
|
+
# EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
|
|
78
|
+
# strip both forms and subtract as plain integer microseconds.
|
|
79
|
+
local dur=-1
|
|
80
|
+
{ dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
|
|
81
|
+
[ "$dur" -ge 0 ] 2>/dev/null || return 0
|
|
82
|
+
local stamp hour
|
|
83
|
+
printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
|
|
84
|
+
printf -v hour '%(%H)T' -1
|
|
85
|
+
# BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
|
|
86
|
+
# is at most 24 files each holding one hour of this machine's hook calls. The
|
|
87
|
+
# first writer into a slot on a new day truncates it instead of appending —
|
|
88
|
+
# detected by reading the slot's first line, which is a builtin read (no stat,
|
|
89
|
+
# no rm, no find, no cron). Two writers can race that truncation and lose a
|
|
90
|
+
# line or two at an hour boundary; that is acceptable for a sampling diagnostic.
|
|
91
|
+
local f="$dir/h$hour.log" first="" line
|
|
92
|
+
# THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
|
|
93
|
+
# Anything else is a silent no-op. Two concrete failures if this check is
|
|
94
|
+
# dropped: a FIFO at the slot makes the `read` below block until the hook's
|
|
95
|
+
# settings.json timeout kills it, and a PreToolUse guard killed that way loses
|
|
96
|
+
# its exit 2 — the command it meant to block then runs; a symlink at the slot
|
|
97
|
+
# sends the day-rollover truncation onto the symlink's target. The `-e || -L`
|
|
98
|
+
# wrapper is what lets a not-yet-created slot through (-e is false for a
|
|
99
|
+
# dangling symlink, so -L is needed to catch that case too).
|
|
100
|
+
if [ -e "$f" ] || [ -L "$f" ]; then
|
|
101
|
+
[ -f "$f" ] && [ ! -L "$f" ] || return 0
|
|
102
|
+
fi
|
|
103
|
+
[ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
|
|
104
|
+
printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
|
|
105
|
+
"$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
|
|
106
|
+
# One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
|
|
107
|
+
# concurrent hooks cannot interleave partial lines.
|
|
108
|
+
# The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
|
|
109
|
+
# reported by the shell before an inner 2>/dev/null would be in effect, and a
|
|
110
|
+
# "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
|
|
111
|
+
if [ "${first%% *}" = "${stamp%% *}" ]; then
|
|
112
|
+
{ printf '%s' "$line" >>"$f"; } 2>/dev/null
|
|
113
|
+
else
|
|
114
|
+
{ printf '%s' "$line" >"$f"; } 2>/dev/null
|
|
115
|
+
fi
|
|
116
|
+
}
|
|
117
|
+
# `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
|
|
118
|
+
# this block is inlined into run under `set -e`, and the EXIT trap runs with
|
|
119
|
+
# errexit still in force. Without `|| :`, a non-zero return from the probe — the
|
|
120
|
+
# final printf failing on an unwritable slot is the reachable case — replaces the
|
|
121
|
+
# hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
|
|
122
|
+
# harness reads as "error", not "block", so the command it meant to block runs.
|
|
123
|
+
# Pinned verbatim by hook-timing-parity.test.sh.
|
|
124
|
+
trap '_mxht_emit || :' EXIT
|
|
125
|
+
# <<< SHARED hook-timing probe v1
|
|
126
|
+
|
|
127
|
+
|
|
49
128
|
trap 'exit 0' ERR
|
|
50
129
|
set -u
|
|
51
130
|
|
|
@@ -21,6 +21,83 @@
|
|
|
21
21
|
# 0 = allow
|
|
22
22
|
# 2 = block (path filters explain why CI didn't trigger — dispatch not needed)
|
|
23
23
|
|
|
24
|
+
MXHT_HOOK=workflow-dispatch-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
|
|
25
|
+
# >>> SHARED hook-timing probe v1
|
|
26
|
+
# Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
|
|
27
|
+
# separated from time spent waiting on the API when a session stalls mid-stream.
|
|
28
|
+
# Appends one line to a local, gitignored log. Read it with
|
|
29
|
+
# mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
|
|
30
|
+
#
|
|
31
|
+
# FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
|
|
32
|
+
# fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
|
|
33
|
+
# default. A diagnostic that can break the gate it observes is worse than no
|
|
34
|
+
# diagnostic: an unwritable path or a full disk would otherwise take out every
|
|
35
|
+
# guard on the PreToolUse path at once. Every step below is guarded and every
|
|
36
|
+
# failure path is a silent no-op that leaves the hook's behaviour untouched.
|
|
37
|
+
#
|
|
38
|
+
# NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
|
|
39
|
+
# -T, one read, one append). No subprocess, no network, no JSON parsing, and the
|
|
40
|
+
# hook's stdin is never touched (the hook owns it). mkdir runs at most once per
|
|
41
|
+
# worktree. Kill switch: MX_HOOK_TIMING=0.
|
|
42
|
+
MXHT_T0="${EPOCHREALTIME:-}"
|
|
43
|
+
_mxht_emit() {
|
|
44
|
+
[ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
|
|
45
|
+
MXHT_DONE=1
|
|
46
|
+
[ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
|
|
47
|
+
[ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
|
|
48
|
+
local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
|
|
49
|
+
[ -n "$root" ] && [ -d "$root" ] || return 0
|
|
50
|
+
local dir="$root/.mx-hook-timing"
|
|
51
|
+
[ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
|
|
52
|
+
# EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
|
|
53
|
+
# strip both forms and subtract as plain integer microseconds.
|
|
54
|
+
local dur=-1
|
|
55
|
+
{ dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
|
|
56
|
+
[ "$dur" -ge 0 ] 2>/dev/null || return 0
|
|
57
|
+
local stamp hour
|
|
58
|
+
printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
|
|
59
|
+
printf -v hour '%(%H)T' -1
|
|
60
|
+
# BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
|
|
61
|
+
# is at most 24 files each holding one hour of this machine's hook calls. The
|
|
62
|
+
# first writer into a slot on a new day truncates it instead of appending —
|
|
63
|
+
# detected by reading the slot's first line, which is a builtin read (no stat,
|
|
64
|
+
# no rm, no find, no cron). Two writers can race that truncation and lose a
|
|
65
|
+
# line or two at an hour boundary; that is acceptable for a sampling diagnostic.
|
|
66
|
+
local f="$dir/h$hour.log" first="" line
|
|
67
|
+
# THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
|
|
68
|
+
# Anything else is a silent no-op. Two concrete failures if this check is
|
|
69
|
+
# dropped: a FIFO at the slot makes the `read` below block until the hook's
|
|
70
|
+
# settings.json timeout kills it, and a PreToolUse guard killed that way loses
|
|
71
|
+
# its exit 2 — the command it meant to block then runs; a symlink at the slot
|
|
72
|
+
# sends the day-rollover truncation onto the symlink's target. The `-e || -L`
|
|
73
|
+
# wrapper is what lets a not-yet-created slot through (-e is false for a
|
|
74
|
+
# dangling symlink, so -L is needed to catch that case too).
|
|
75
|
+
if [ -e "$f" ] || [ -L "$f" ]; then
|
|
76
|
+
[ -f "$f" ] && [ ! -L "$f" ] || return 0
|
|
77
|
+
fi
|
|
78
|
+
[ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
|
|
79
|
+
printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
|
|
80
|
+
"$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
|
|
81
|
+
# One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
|
|
82
|
+
# concurrent hooks cannot interleave partial lines.
|
|
83
|
+
# The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
|
|
84
|
+
# reported by the shell before an inner 2>/dev/null would be in effect, and a
|
|
85
|
+
# "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
|
|
86
|
+
if [ "${first%% *}" = "${stamp%% *}" ]; then
|
|
87
|
+
{ printf '%s' "$line" >>"$f"; } 2>/dev/null
|
|
88
|
+
else
|
|
89
|
+
{ printf '%s' "$line" >"$f"; } 2>/dev/null
|
|
90
|
+
fi
|
|
91
|
+
}
|
|
92
|
+
# `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
|
|
93
|
+
# this block is inlined into run under `set -e`, and the EXIT trap runs with
|
|
94
|
+
# errexit still in force. Without `|| :`, a non-zero return from the probe — the
|
|
95
|
+
# final printf failing on an unwritable slot is the reachable case — replaces the
|
|
96
|
+
# hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
|
|
97
|
+
# harness reads as "error", not "block", so the command it meant to block runs.
|
|
98
|
+
# Pinned verbatim by hook-timing-parity.test.sh.
|
|
99
|
+
trap '_mxht_emit || :' EXIT
|
|
100
|
+
# <<< SHARED hook-timing probe v1
|
|
24
101
|
|
|
25
102
|
|
|
26
103
|
# Fail-open: any unexpected error → allow the command through
|
|
@@ -35,6 +35,85 @@
|
|
|
35
35
|
# - CLAUDE_WORKTREE_PATH: Absolute path to worktree (e.g., /workspace/.worktrees/foo)
|
|
36
36
|
# - CLAUDE_WORKTREE_NAME: Worktree name (e.g., foo)
|
|
37
37
|
|
|
38
|
+
MXHT_HOOK=worktree-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
|
|
39
|
+
# >>> SHARED hook-timing probe v1
|
|
40
|
+
# Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
|
|
41
|
+
# separated from time spent waiting on the API when a session stalls mid-stream.
|
|
42
|
+
# Appends one line to a local, gitignored log. Read it with
|
|
43
|
+
# mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
|
|
44
|
+
#
|
|
45
|
+
# FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
|
|
46
|
+
# fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
|
|
47
|
+
# default. A diagnostic that can break the gate it observes is worse than no
|
|
48
|
+
# diagnostic: an unwritable path or a full disk would otherwise take out every
|
|
49
|
+
# guard on the PreToolUse path at once. Every step below is guarded and every
|
|
50
|
+
# failure path is a silent no-op that leaves the hook's behaviour untouched.
|
|
51
|
+
#
|
|
52
|
+
# NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
|
|
53
|
+
# -T, one read, one append). No subprocess, no network, no JSON parsing, and the
|
|
54
|
+
# hook's stdin is never touched (the hook owns it). mkdir runs at most once per
|
|
55
|
+
# worktree. Kill switch: MX_HOOK_TIMING=0.
|
|
56
|
+
MXHT_T0="${EPOCHREALTIME:-}"
|
|
57
|
+
_mxht_emit() {
|
|
58
|
+
[ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
|
|
59
|
+
MXHT_DONE=1
|
|
60
|
+
[ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
|
|
61
|
+
[ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
|
|
62
|
+
local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
|
|
63
|
+
[ -n "$root" ] && [ -d "$root" ] || return 0
|
|
64
|
+
local dir="$root/.mx-hook-timing"
|
|
65
|
+
[ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
|
|
66
|
+
# EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
|
|
67
|
+
# strip both forms and subtract as plain integer microseconds.
|
|
68
|
+
local dur=-1
|
|
69
|
+
{ dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
|
|
70
|
+
[ "$dur" -ge 0 ] 2>/dev/null || return 0
|
|
71
|
+
local stamp hour
|
|
72
|
+
printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
|
|
73
|
+
printf -v hour '%(%H)T' -1
|
|
74
|
+
# BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
|
|
75
|
+
# is at most 24 files each holding one hour of this machine's hook calls. The
|
|
76
|
+
# first writer into a slot on a new day truncates it instead of appending —
|
|
77
|
+
# detected by reading the slot's first line, which is a builtin read (no stat,
|
|
78
|
+
# no rm, no find, no cron). Two writers can race that truncation and lose a
|
|
79
|
+
# line or two at an hour boundary; that is acceptable for a sampling diagnostic.
|
|
80
|
+
local f="$dir/h$hour.log" first="" line
|
|
81
|
+
# THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
|
|
82
|
+
# Anything else is a silent no-op. Two concrete failures if this check is
|
|
83
|
+
# dropped: a FIFO at the slot makes the `read` below block until the hook's
|
|
84
|
+
# settings.json timeout kills it, and a PreToolUse guard killed that way loses
|
|
85
|
+
# its exit 2 — the command it meant to block then runs; a symlink at the slot
|
|
86
|
+
# sends the day-rollover truncation onto the symlink's target. The `-e || -L`
|
|
87
|
+
# wrapper is what lets a not-yet-created slot through (-e is false for a
|
|
88
|
+
# dangling symlink, so -L is needed to catch that case too).
|
|
89
|
+
if [ -e "$f" ] || [ -L "$f" ]; then
|
|
90
|
+
[ -f "$f" ] && [ ! -L "$f" ] || return 0
|
|
91
|
+
fi
|
|
92
|
+
[ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
|
|
93
|
+
printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
|
|
94
|
+
"$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
|
|
95
|
+
# One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
|
|
96
|
+
# concurrent hooks cannot interleave partial lines.
|
|
97
|
+
# The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
|
|
98
|
+
# reported by the shell before an inner 2>/dev/null would be in effect, and a
|
|
99
|
+
# "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
|
|
100
|
+
if [ "${first%% *}" = "${stamp%% *}" ]; then
|
|
101
|
+
{ printf '%s' "$line" >>"$f"; } 2>/dev/null
|
|
102
|
+
else
|
|
103
|
+
{ printf '%s' "$line" >"$f"; } 2>/dev/null
|
|
104
|
+
fi
|
|
105
|
+
}
|
|
106
|
+
# `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
|
|
107
|
+
# this block is inlined into run under `set -e`, and the EXIT trap runs with
|
|
108
|
+
# errexit still in force. Without `|| :`, a non-zero return from the probe — the
|
|
109
|
+
# final printf failing on an unwritable slot is the reachable case — replaces the
|
|
110
|
+
# hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
|
|
111
|
+
# harness reads as "error", not "block", so the command it meant to block runs.
|
|
112
|
+
# Pinned verbatim by hook-timing-parity.test.sh.
|
|
113
|
+
trap '_mxht_emit || :' EXIT
|
|
114
|
+
# <<< SHARED hook-timing probe v1
|
|
115
|
+
|
|
116
|
+
|
|
38
117
|
set -euo pipefail
|
|
39
118
|
|
|
40
119
|
# Read the tool input from stdin (JSON format)
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
export interface ProbeOutcome {
|
|
2
|
+
status: number | null;
|
|
3
|
+
stderr: string;
|
|
4
|
+
}
|
|
5
|
+
/** Runs one shipped hook command with `payload` on stdin. Injectable for tests. */
|
|
6
|
+
export type CommandRunner = (command: string, payload: string, env: NodeJS.ProcessEnv) => ProbeOutcome;
|
|
7
|
+
/** A PreToolUse Bash payload in the exact envelope codex-cli 0.145.0 delivers. */
|
|
8
|
+
export declare function bashPayload(command: string, cwd: string): string;
|
|
9
|
+
/** A PreToolUse spawn payload — the shape a real `spawn_agent` call produces. */
|
|
10
|
+
export declare function spawnPayload(cwd: string): string;
|
|
11
|
+
interface GuardProbeSpec {
|
|
12
|
+
guard: string;
|
|
13
|
+
script: string;
|
|
14
|
+
/** Command the guard must REFUSE. */
|
|
15
|
+
refused: string;
|
|
16
|
+
/** Text from the guard's OWN refusal that must appear in stderr (attribution). */
|
|
17
|
+
attribution: string;
|
|
18
|
+
/** Command the guard must ALLOW — the positive half. */
|
|
19
|
+
permitted: string;
|
|
20
|
+
/** Set when the probe substitutes a deterministic stand-in for a live dependency. */
|
|
21
|
+
stubbedDependency?: string;
|
|
22
|
+
}
|
|
23
|
+
export declare function guardProbeSpecs(): GuardProbeSpec[];
|
|
24
|
+
export interface ProveGuardsResult {
|
|
25
|
+
ok: boolean;
|
|
26
|
+
/** Human-readable lines, printed by the CLI entry point. */
|
|
27
|
+
lines: string[];
|
|
28
|
+
/** Guards observed refusing AND allowing. */
|
|
29
|
+
proven: string[];
|
|
30
|
+
/** Absolute path of the artifact, when one was written. */
|
|
31
|
+
artifactPath?: string;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Run the paired proof and, only on a complete set of observed refusals, write the
|
|
35
|
+
* artifact.
|
|
36
|
+
*
|
|
37
|
+
* ALL OR NOTHING. A guard that does not refuse means the run failed; nothing is
|
|
38
|
+
* written, and any existing artifact is left exactly as it was rather than being
|
|
39
|
+
* narrowed in place. A partial artifact would be a proof of one guard sitting where a
|
|
40
|
+
* reader looks for two, and the launch gate's "which guards" question is answered by
|
|
41
|
+
* the guard names in the file, not by the file's existence.
|
|
42
|
+
*/
|
|
43
|
+
export declare function proveCodexGuards(opts: {
|
|
44
|
+
worktreePath: string;
|
|
45
|
+
codexHome?: string;
|
|
46
|
+
/** ISO-8601 UTC stamp. Injected rather than read from a clock so runs are reproducible. */
|
|
47
|
+
now: string;
|
|
48
|
+
/** `codex --version` token. Injected for the same reason. */
|
|
49
|
+
codexVersion: string;
|
|
50
|
+
/** mx-agent build that is producing this proof. Defaults to the running CLI. */
|
|
51
|
+
cliVersion?: string;
|
|
52
|
+
runner?: CommandRunner;
|
|
53
|
+
/** Base environment for the probes. Defaults to the current process env. */
|
|
54
|
+
env?: NodeJS.ProcessEnv;
|
|
55
|
+
}): ProveGuardsResult;
|
|
56
|
+
export interface RunProveGuardsOptions {
|
|
57
|
+
path?: string;
|
|
58
|
+
}
|
|
59
|
+
/** CLI entry point. Exits non-zero when nothing was proven — a failed proof is not a pass. */
|
|
60
|
+
export declare function runCodexProveGuards(opts?: RunProveGuardsOptions): void;
|
|
61
|
+
export {};
|
|
62
|
+
//# sourceMappingURL=codex-prove-guards.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codex-prove-guards.d.ts","sourceRoot":"","sources":["../../src/commands/codex-prove-guards.ts"],"names":[],"mappings":"AA0EA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,YAAY,CAAC;AAYlB,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAahE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAahD;AAQD,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,eAAe,IAAI,cAAc,EAAE,CAwBlD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,iBAAiB,CAkNpB;AA8BD,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,qBAA0B,GAAG,IAAI,CAmB1E"}
|