@memnexus-ai/mx-agent-cli 0.1.251 → 0.1.253

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.
@@ -231,6 +231,74 @@ git fetch --prune
231
231
 
232
232
  ## Safety Rules
233
233
 
234
+ ### Report Every Guard Override — Required, Not Optional
235
+
236
+ Several of the commands above (`git reset --hard`, `git stash`, `git checkout -- <path>`,
237
+ `git restore <path>`) are blocked by the `git-mutation-guard` PreToolUse hook. The block
238
+ message tells you to re-run with a `GIT_EXPERT=1` prefix. Using that override is legitimate —
239
+ you are the designated agent for destructive git operations, and the escape hatch exists for
240
+ you. Using it *silently* is not.
241
+
242
+ **Whenever you clear a guard block with `GIT_EXPERT=1` — or with any other sanctioned
243
+ override — your report back MUST contain all four of the following. A report that omits any
244
+ of them is an incomplete task, not a stylistic shortcut, and you must go back and add them
245
+ before you finish:**
246
+
247
+ 1. **Which command was blocked** — the exact command, verbatim.
248
+ 2. **Which guard blocked it** — the guard name from the block message (e.g.
249
+ `git-mutation-guard`), not just "a hook."
250
+ 3. **That you used the override** — state `GIT_EXPERT=1` (or the override you used) explicitly.
251
+ "I ran a hard reset" is not a disclosure of an override.
252
+ 4. **Why the override was justified** — the specific reason this destructive operation was
253
+ correct here (e.g. "all branch commits were confirmed on main after squash merge; no
254
+ unpushed work").
255
+
256
+ Use this form:
257
+
258
+ ```
259
+ Guard override used:
260
+ Blocked command: git reset --hard origin/main
261
+ Guard: git-mutation-guard (PreToolUse)
262
+ Override: GIT_EXPERT=1
263
+ Justification: Post-squash-merge sync. Verified `git log origin/main..HEAD` was
264
+ empty and `git status` clean before resetting — no work at risk.
265
+ ```
266
+
267
+ **Why this is a hard requirement.** On 2026-07-31 a git-expert was blocked on a hard reset,
268
+ re-ran it four seconds later with `GIT_EXPERT=1`, and closed by telling its leader only that
269
+ it had used a hard reset. No mention of the block, no mention of the override. That leader
270
+ reported in good faith that the guard had not fired, and an investigation across eight
271
+ worktrees was spent confirming a guard that was healthy the whole time. The override was
272
+ correct. Its invisibility was the defect.
273
+
274
+ **Routing around a guard counts too.** The requirement above applies to the override because
275
+ the override is the route the guard instruments. It is not the only route. The guard covers
276
+ four patterns — `reset --hard`, `stash`, `checkout -- <path>`, `restore <path>` — and every
277
+ one of these is allowed through with no block and no log:
278
+
279
+ | Allowed, unlogged | Destroys |
280
+ |---|---|
281
+ | `git clean -fdx` | every untracked file, including another agent's new work |
282
+ | `git checkout -f <branch>` | uncommitted changes across the tree |
283
+ | `git branch -D <branch>` | an unmerged branch |
284
+ | `git worktree remove --force` | an entire worktree and everything uncommitted in it |
285
+ | `git update-ref -d` / `git reflog expire --expire=now --all` | the refs and reflog you would recover from |
286
+ | `rm -rf <path>` | whatever you point it at |
287
+
288
+ So: **if a guard blocks you and you then accomplish the same effect by a route the guard does
289
+ not cover, that is reportable on the same terms** — state which command was blocked, which
290
+ route you took instead, and why that route was the right one. You would be able to say
291
+ truthfully that you used no override, and your leader would still have the wrong picture.
292
+ Reaching for an uninstrumented path to avoid the disclosure is precisely the failure this
293
+ section exists to prevent, and it is worse than the silent override was, because there is no
294
+ log to reconcile against afterwards.
295
+
296
+ Your leader cannot tell "the guard did not fire" from "the guard fired and I overrode it"
297
+ unless you say so. Only you have that information at the moment it matters. The override is
298
+ also recorded to `~/.mx-agent/logs/git-guard-override.jsonl`, but that log is a
299
+ reconciliation record for later audit — it does not reach your leader in time to inform the
300
+ decision in front of them, and it does not carry your justification. Reporting is your job.
301
+
234
302
  ### Never Do Without Explicit Confirmation
235
303
 
236
304
  | Operation | Risk | When It's Safe |
@@ -368,6 +436,7 @@ git stash pop
368
436
  | **Committing .claude/settings.local.json** | Local settings contain user-specific configuration. | Keep it in .gitignore. Only commit .claude/settings.json (shared). |
369
437
  | **Interactive rebase in agent context** | `git rebase -i` requires terminal input that agents can't provide. | Use non-interactive rebase. For squashing, use `git rebase` with `--squash` on merge instead. |
370
438
  | **Ignoring stash before rebase** | Unstaged changes block rebase with a confusing error. | Always `git stash --include-untracked` before rebase, `git stash pop` after. |
439
+ | **Silent guard override** | Reporting "I ran a hard reset" after clearing a `git-mutation-guard` block with `GIT_EXPERT=1` hides the block from your leader, who then cannot tell a working guard from a broken one. This cost a fleet-wide investigation on 2026-07-31. | Report all four items — blocked command, guard, override used, justification. See "Report Every Guard Override" above. |
371
440
 
372
441
  ---
373
442
 
@@ -378,3 +447,7 @@ branches stay in sync, conflicts get resolved correctly, and no work is lost. Wh
378
447
  works, nobody notices. When git breaks, everything stops.
379
448
 
380
449
  Your job is to make sure nobody notices.
450
+
451
+ The one thing you never keep quiet is a guardrail you had to step around. Overrides get
452
+ reported, every time — a leader acting on an incomplete picture of what the guardrails did
453
+ is a worse outcome than any git problem you were solving.
@@ -19,6 +19,21 @@
19
19
  # ESCAPE HATCH: prefix the command with `GIT_EXPERT=1` to run a genuinely-needed
20
20
  # destructive git op deliberately (e.g. GIT_EXPERT=1 git reset --hard <sha>).
21
21
  # The escape is intentional friction, not a lock.
22
+ # OVERRIDE AUDIT (2026-07-31 false alarm): an override that clears a real block is
23
+ # appended to ~/.mx-agent/logs/git-guard-override.jsonl before the command runs,
24
+ # so "the guard never fired" and "the guard fired and was overridden" are
25
+ # distinguishable after the fact. Motivating incident: a git-expert was blocked on
26
+ # a hard reset, re-ran it four seconds later with GIT_EXPERT=1, and reported only
27
+ # the reset to its leader; that leader then reported a broken guard in good faith
28
+ # and an investigation confirmed the guard was healthy in all eight worktrees. The
29
+ # override itself was sanctioned — its invisibility was the defect. Self-reporting
30
+ # alone is a rung-5 control (it depends on the overriding agent choosing to
31
+ # mention it), so the log exists as the independent record. Logging is FAIL-OPEN
32
+ # and side-effect-only: on any problem it is skipped, not retried and not
33
+ # escalated, so an override is neither withheld nor delayed because of it. See
34
+ # the log_override() header for the failure modes this had to be hardened
35
+ # against (a FIFO that blocked the append forever, a symlink that redirected it)
36
+ # and for the residual TOCTOU that is knowingly accepted.
22
37
  # LAYERING CAVEAT: GIT_EXPERT=1 only clears THIS hook's blocks (bare-SHA/branch
23
38
  # reset forms, stash, checkout-file, restore-worktree). It does NOT clear the two
24
39
  # patterns `git reset --hard HEAD~*` and `git reset --hard HEAD^*` — those are
@@ -65,10 +80,115 @@ if [[ -z "$COMMAND" ]]; then
65
80
  exit 0
66
81
  fi
67
82
 
68
- # Deliberate override.
69
- if echo "$COMMAND" | grep -qE '(^|[^A-Za-z_])GIT_EXPERT=1(\s|$)'; then
70
- exit 0
83
+ # Deliberate override. NOTE: this no longer short-circuits. The scan still runs so
84
+ # we can name WHICH pattern the override cleared; refuse() then logs and allows
85
+ # instead of blocking. A GIT_EXPERT=1 command that matches nothing is not an
86
+ # override of anything and is not logged.
87
+ #
88
+ # LOG FIDELITY (#4804, part 1 of 2). OVERRIDE below is a WHOLE-COMMAND test and
89
+ # still governs the allow/deny decision exactly as before — this commit changes
90
+ # no boundary. What it changes is what gets WRITTEN: a record is appended only
91
+ # when the override token and the pattern that matched occur in the SAME command
92
+ # segment (SEG_OVERRIDE, set in check_segment). The whole-command test made the
93
+ # log useless as evidence — a read-only command that merely mentions both the
94
+ # token and a destructive verb somewhere in its text (an agent writing about the
95
+ # guard, a probe script being edited) produced a record indistinguishable from a
96
+ # genuine override. All four records in the live log were produced that way; none
97
+ # was a real override. Same-segment is the weakest condition that separates "the
98
+ # token was applied to this command" from "the token appears somewhere on the
99
+ # line", and it is decision-neutral, so it needs no boundary re-verification.
100
+ OVERRIDE_RE='(^|[^A-Za-z_])GIT_EXPERT=1(\s|$)'
101
+ OVERRIDE=0
102
+ if echo "$COMMAND" | grep -qE "$OVERRIDE_RE"; then
103
+ OVERRIDE=1
71
104
  fi
105
+ # Set per segment by check_segment; consumed by refuse() for logging only.
106
+ SEG_OVERRIDE=0
107
+
108
+ # --- override audit log (fail-open, side-effect only) -------------------------
109
+ # One JSONL line per cleared block, alongside idle-gate.jsonl / session-pause.jsonl.
110
+ # Fields: ts, worktree, guard, pattern (what was blocked), command (first line,
111
+ # sanitized + truncated). The command is UNTRUSTED text, so it is reduced to a
112
+ # conservative allowlist — no quotes, backslashes, control characters or non-ASCII
113
+ # reach the file, and nothing that renders as markup survives.
114
+ #
115
+ # PATH IS HARD-CODED, deliberately. There is no env var to redirect or disable
116
+ # this log: the party whose action is being recorded is the party who benefits
117
+ # from suppressing it, so a single variable in the environment must not be able
118
+ # to turn the record off. Same shape as session-idle-gate.sh, which hard-codes
119
+ # its own path. The probe isolates itself by overriding HOME, not by asking the
120
+ # product for a test hook.
121
+ #
122
+ # WRITE TARGET CHECKS (security review, 2026-08-01). Three defects were measured
123
+ # against earlier revisions of this file, each reproduced before it was fixed:
124
+ # - a FIFO at the log path with no reader made the append block forever on
125
+ # open(); `timeout 8` returned 124. Every override in that home directory
126
+ # hung the Bash call with no error output. `set +e` catches failures; it does
127
+ # nothing about blocking, so the claim that no logging failure could convert
128
+ # an allowed command into a blocked one was false — the command never ran.
129
+ # - a symlink at the log FILE path was followed, appending the record to the
130
+ # link target (201 bytes into a file outside the log directory).
131
+ # - after the leaf check landed, the same redirect survived one level up:
132
+ # `mkdir -p` and `>>` both follow DIRECTORY symlinks, so a symlinked
133
+ # `~/.mx-agent/logs` still took 185 bytes into an attacker-chosen directory.
134
+ # So there are two tests: the leaf must be absent or a plain regular file and not
135
+ # a symlink (`-f` alone follows links), and the containing directory must be a
136
+ # real directory and not a symlink. Either test failing skips the log entirely
137
+ # and lets the override proceed.
138
+ #
139
+ # WHAT THIS DOES NOT CLOSE — read this before describing the log as tamper-proof,
140
+ # because that description has now been wrong three times. Symlink redirection is
141
+ # closed AT THE LEAF AND ONE DIRECTORY UP. It is NOT closed for a symlinked
142
+ # `~/.mx-agent`, a symlinked `$HOME`, or any higher path component: those are
143
+ # resolved by the kernel before either test sees them, and walking every
144
+ # component is not something this hook should be doing on a hot path. Also not
145
+ # closed: the checks are TOCTOU, not atomic — a writer that swaps the path
146
+ # between the test and the append still wins the race, and closing that needs
147
+ # O_NOFOLLOW|O_NONBLOCK, which bash cannot express. Both residuals are accepted
148
+ # on the same grounds: anyone able to plant a component symlink in the agent's
149
+ # own home or to win that race already executes as the agent user, and this file
150
+ # is a guardrail, not an access control (same posture as the guard itself).
151
+ #
152
+ # The whole body runs in a subshell with errexit disabled, so an error inside it
153
+ # cannot change the caller's exit status. Combined with the two target tests, the
154
+ # intended property is that logging is skipped rather than allowed to stall or
155
+ # misdirect — an override is never withheld, and never delayed, because of the
156
+ # log.
157
+ log_override() {
158
+ (
159
+ set +e +u +o pipefail
160
+ log_dir="${HOME:-/tmp}/.mx-agent/logs"
161
+ log_file="${log_dir}/git-guard-override.jsonl"
162
+
163
+ # Leaf: refuse anything that is not an absent path or a plain regular file.
164
+ # FIFOs block, symlinks redirect, devices do neither usefully.
165
+ if [ -e "$log_file" ] || [ -L "$log_file" ]; then
166
+ [ -f "$log_file" ] && [ ! -L "$log_file" ] || exit 0
167
+ fi
168
+
169
+ ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
170
+ wt_path="${CLAUDE_WORKTREE_PATH:-${CLAUDE_PROJECT_DIR:-}}"
171
+ wt="$(basename "$wt_path" 2>/dev/null)"
172
+ wt="${wt//[^a-zA-Z0-9_.-]/}"
173
+ wt="${wt:-unknown}"
174
+ cmd="$(printf '%s' "$COMMAND" \
175
+ | head -n 1 \
176
+ | LC_ALL=C tr -d '\000-\037\177' \
177
+ | LC_ALL=C tr -c 'A-Za-z0-9 _.,:/=@+~^-' '?' \
178
+ | cut -c1-200)"
179
+ pat="$(printf '%s' "$1" | LC_ALL=C tr -c 'A-Za-z0-9 _.<>-' '?' | cut -c1-60)"
180
+ mkdir -p "$log_dir" || exit 0
181
+
182
+ # Containing directory: `mkdir -p` succeeds on a symlink-to-directory and
183
+ # `>>` follows it, so the leaf check alone left the redirect intact one level
184
+ # up. Test after mkdir, since the directory may not have existed before it.
185
+ [ -d "$log_dir" ] && [ ! -L "$log_dir" ] || exit 0
186
+
187
+ printf '{"ts":"%s","worktree":"%s","guard":"git-mutation-guard","pattern":"%s","override":"GIT_EXPERT=1","command":"%s"}\n' \
188
+ "$ts" "$wt" "$pat" "$cmd" >> "$log_file"
189
+ ) >/dev/null 2>&1 || true
190
+ return 0
191
+ }
72
192
 
73
193
  # --- heredoc-body stripping (consumer-aware) --------------------------------
74
194
  # Produce a "scannable" copy of the command. A heredoc body is dropped ONLY when
@@ -250,6 +370,22 @@ SCAN=$(printf '%s' "$COMMAND" | strip_heredocs)
250
370
 
251
371
  refuse() {
252
372
  local what="$1"
373
+
374
+ # Override in effect: record what it cleared, then allow. Silent on stdout and
375
+ # stderr — the allow contract is "exit 0, no output".
376
+ #
377
+ # The ALLOW is decided by the whole-command OVERRIDE (unchanged). The RECORD is
378
+ # written only when the token sits in the same segment as the pattern that
379
+ # matched (#4804): a command whose token and pattern are in different segments
380
+ # is still allowed exactly as before, but it is not evidence of an override and
381
+ # must not be written down as one.
382
+ if [[ "$OVERRIDE" -eq 1 ]]; then
383
+ if [[ "$SEG_OVERRIDE" -eq 1 ]]; then
384
+ log_override "$what"
385
+ fi
386
+ exit 0
387
+ fi
388
+
253
389
  {
254
390
  echo ""
255
391
  echo "BLOCKED: destructive git operation ($what)"
@@ -262,6 +398,14 @@ refuse() {
262
398
  echo "If you truly must run this, prefix it with GIT_EXPERT=1 to override,"
263
399
  echo "e.g. GIT_EXPERT=1 $what ..."
264
400
  echo ""
401
+ echo "IF YOU OVERRIDE, YOU MUST REPORT IT. Your report back to whoever asked"
402
+ echo "for this work has to state: the command that was blocked, that"
403
+ echo "git-mutation-guard blocked it, that you used GIT_EXPERT=1 to override,"
404
+ echo "and why the override was justified. Omitting this is a failure to"
405
+ echo "complete the task — a silent override on 2026-07-31 was reported up the"
406
+ echo "chain as a broken guard and cost an investigation across eight"
407
+ echo "worktrees. The override is recorded either way."
408
+ echo ""
265
409
  } >&2
266
410
  exit 2
267
411
  }
@@ -313,6 +457,13 @@ GITSEG='(^|[;&|({`]|\s(then|do|else)\s)\s*([0-9]*[<>][^[:space:]]*\s+|[A-Za-z_][
313
457
  check_segment() {
314
458
  local seg="$1"
315
459
 
460
+ # Does the override token appear in THIS segment (#4804)? Logging-only in this
461
+ # revision: refuse() still decides allow/deny from the whole-command OVERRIDE.
462
+ SEG_OVERRIDE=0
463
+ if printf '%s' "$seg" | grep -qE "$OVERRIDE_RE"; then
464
+ SEG_OVERRIDE=1
465
+ fi
466
+
316
467
  # git stash (mutating forms). Allow read-only `stash list` / `stash show`;
317
468
  # block bare stash, push, pop, apply, drop, clear, save, branch, create, store.
318
469
  if printf '%s' "$seg" | grep -qE "${GITSEG}stash\b"; then
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memnexus-ai/mx-agent-cli",
3
- "version": "0.1.251",
3
+ "version": "0.1.253",
4
4
  "description": "CLI for creating and managing AI agent teams",
5
5
  "type": "module",
6
6
  "bin": {