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

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,11 +80,100 @@ if [[ -z "$COMMAND" ]]; then
65
80
  exit 0
66
81
  fi
67
82
 
68
- # Deliberate override.
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
+ OVERRIDE=0
69
88
  if echo "$COMMAND" | grep -qE '(^|[^A-Za-z_])GIT_EXPERT=1(\s|$)'; then
70
- exit 0
89
+ OVERRIDE=1
71
90
  fi
72
91
 
92
+ # --- override audit log (fail-open, side-effect only) -------------------------
93
+ # One JSONL line per cleared block, alongside idle-gate.jsonl / session-pause.jsonl.
94
+ # Fields: ts, worktree, guard, pattern (what was blocked), command (first line,
95
+ # sanitized + truncated). The command is UNTRUSTED text, so it is reduced to a
96
+ # conservative allowlist — no quotes, backslashes, control characters or non-ASCII
97
+ # reach the file, and nothing that renders as markup survives.
98
+ #
99
+ # PATH IS HARD-CODED, deliberately. There is no env var to redirect or disable
100
+ # this log: the party whose action is being recorded is the party who benefits
101
+ # from suppressing it, so a single variable in the environment must not be able
102
+ # to turn the record off. Same shape as session-idle-gate.sh, which hard-codes
103
+ # its own path. The probe isolates itself by overriding HOME, not by asking the
104
+ # product for a test hook.
105
+ #
106
+ # WRITE TARGET CHECKS (security review, 2026-08-01). Three defects were measured
107
+ # against earlier revisions of this file, each reproduced before it was fixed:
108
+ # - a FIFO at the log path with no reader made the append block forever on
109
+ # open(); `timeout 8` returned 124. Every override in that home directory
110
+ # hung the Bash call with no error output. `set +e` catches failures; it does
111
+ # nothing about blocking, so the claim that no logging failure could convert
112
+ # an allowed command into a blocked one was false — the command never ran.
113
+ # - a symlink at the log FILE path was followed, appending the record to the
114
+ # link target (201 bytes into a file outside the log directory).
115
+ # - after the leaf check landed, the same redirect survived one level up:
116
+ # `mkdir -p` and `>>` both follow DIRECTORY symlinks, so a symlinked
117
+ # `~/.mx-agent/logs` still took 185 bytes into an attacker-chosen directory.
118
+ # So there are two tests: the leaf must be absent or a plain regular file and not
119
+ # a symlink (`-f` alone follows links), and the containing directory must be a
120
+ # real directory and not a symlink. Either test failing skips the log entirely
121
+ # and lets the override proceed.
122
+ #
123
+ # WHAT THIS DOES NOT CLOSE — read this before describing the log as tamper-proof,
124
+ # because that description has now been wrong three times. Symlink redirection is
125
+ # closed AT THE LEAF AND ONE DIRECTORY UP. It is NOT closed for a symlinked
126
+ # `~/.mx-agent`, a symlinked `$HOME`, or any higher path component: those are
127
+ # resolved by the kernel before either test sees them, and walking every
128
+ # component is not something this hook should be doing on a hot path. Also not
129
+ # closed: the checks are TOCTOU, not atomic — a writer that swaps the path
130
+ # between the test and the append still wins the race, and closing that needs
131
+ # O_NOFOLLOW|O_NONBLOCK, which bash cannot express. Both residuals are accepted
132
+ # on the same grounds: anyone able to plant a component symlink in the agent's
133
+ # own home or to win that race already executes as the agent user, and this file
134
+ # is a guardrail, not an access control (same posture as the guard itself).
135
+ #
136
+ # The whole body runs in a subshell with errexit disabled, so an error inside it
137
+ # cannot change the caller's exit status. Combined with the two target tests, the
138
+ # intended property is that logging is skipped rather than allowed to stall or
139
+ # misdirect — an override is never withheld, and never delayed, because of the
140
+ # log.
141
+ log_override() {
142
+ (
143
+ set +e +u +o pipefail
144
+ log_dir="${HOME:-/tmp}/.mx-agent/logs"
145
+ log_file="${log_dir}/git-guard-override.jsonl"
146
+
147
+ # Leaf: refuse anything that is not an absent path or a plain regular file.
148
+ # FIFOs block, symlinks redirect, devices do neither usefully.
149
+ if [ -e "$log_file" ] || [ -L "$log_file" ]; then
150
+ [ -f "$log_file" ] && [ ! -L "$log_file" ] || exit 0
151
+ fi
152
+
153
+ ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
154
+ wt_path="${CLAUDE_WORKTREE_PATH:-${CLAUDE_PROJECT_DIR:-}}"
155
+ wt="$(basename "$wt_path" 2>/dev/null)"
156
+ wt="${wt//[^a-zA-Z0-9_.-]/}"
157
+ wt="${wt:-unknown}"
158
+ cmd="$(printf '%s' "$COMMAND" \
159
+ | head -n 1 \
160
+ | LC_ALL=C tr -d '\000-\037\177' \
161
+ | LC_ALL=C tr -c 'A-Za-z0-9 _.,:/=@+~^-' '?' \
162
+ | cut -c1-200)"
163
+ pat="$(printf '%s' "$1" | LC_ALL=C tr -c 'A-Za-z0-9 _.<>-' '?' | cut -c1-60)"
164
+ mkdir -p "$log_dir" || exit 0
165
+
166
+ # Containing directory: `mkdir -p` succeeds on a symlink-to-directory and
167
+ # `>>` follows it, so the leaf check alone left the redirect intact one level
168
+ # up. Test after mkdir, since the directory may not have existed before it.
169
+ [ -d "$log_dir" ] && [ ! -L "$log_dir" ] || exit 0
170
+
171
+ printf '{"ts":"%s","worktree":"%s","guard":"git-mutation-guard","pattern":"%s","override":"GIT_EXPERT=1","command":"%s"}\n' \
172
+ "$ts" "$wt" "$pat" "$cmd" >> "$log_file"
173
+ ) >/dev/null 2>&1 || true
174
+ return 0
175
+ }
176
+
73
177
  # --- heredoc-body stripping (consumer-aware) --------------------------------
74
178
  # Produce a "scannable" copy of the command. A heredoc body is dropped ONLY when
75
179
  # its consuming command is inert (cat/tee/redirect-to-file/non-shell language) —
@@ -250,6 +354,14 @@ SCAN=$(printf '%s' "$COMMAND" | strip_heredocs)
250
354
 
251
355
  refuse() {
252
356
  local what="$1"
357
+
358
+ # Override in effect: record what it cleared, then allow. Silent on stdout and
359
+ # stderr — the allow contract is "exit 0, no output".
360
+ if [[ "$OVERRIDE" -eq 1 ]]; then
361
+ log_override "$what"
362
+ exit 0
363
+ fi
364
+
253
365
  {
254
366
  echo ""
255
367
  echo "BLOCKED: destructive git operation ($what)"
@@ -262,6 +374,14 @@ refuse() {
262
374
  echo "If you truly must run this, prefix it with GIT_EXPERT=1 to override,"
263
375
  echo "e.g. GIT_EXPERT=1 $what ..."
264
376
  echo ""
377
+ echo "IF YOU OVERRIDE, YOU MUST REPORT IT. Your report back to whoever asked"
378
+ echo "for this work has to state: the command that was blocked, that"
379
+ echo "git-mutation-guard blocked it, that you used GIT_EXPERT=1 to override,"
380
+ echo "and why the override was justified. Omitting this is a failure to"
381
+ echo "complete the task — a silent override on 2026-07-31 was reported up the"
382
+ echo "chain as a broken guard and cost an investigation across eight"
383
+ echo "worktrees. The override is recorded either way."
384
+ echo ""
265
385
  } >&2
266
386
  exit 2
267
387
  }
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.252",
4
4
  "description": "CLI for creating and managing AI agent teams",
5
5
  "type": "module",
6
6
  "bin": {