From 1aff74c4218560ea7403dd12b9766433fa5ef52a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 09:56:41 +0000
Subject: [PATCH 1/2] =?UTF-8?q?feat(hooks):=20guard=20the=20shared=20proce?=
 =?UTF-8?q?ss=20table=20=E2=80=94=20kill=20only=20a=20PID=20you=20recorded?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Worktree isolation gives each agent its own checkout, index and HEAD; it gives
it nothing over the process table, which is one table per container. A
name-matched kill reaches whatever a parallel agent is running under that name,
and it exits 0 either way — the agent that fired it observes nothing, the agent
whose run died cannot attribute it, and the loss is recorded as a flake.

The same shape as guard-shared-stash.sh, deliberately: hook + same-named
.selftest.sh + an OS_ALLOW_* escape + the Bash PreToolUse registration, with the
AGENTS.md line and the CLAUDE.md inline beside the stash rule they generalise.

Swept first, so the rule covers the class rather than one spelling: the tree
carries no pkill, no killall, no `xargs kill`, no `ps | grep | kill` and no
`fuser -k`. Every live kill site is PID-scoped — `kill "$SERVER_PID"`,
`kill $(lsof -ti tcp:PORT)`, `pgrep -s`/`pgrep -P` in publish-smoke.sh and
gen-sdui-manifest.sh — and the self-test pins all of them ALLOWED alongside the
blocked shapes, including the card's own specimen.

Neither ceiling moves: AGENTS.md 1067 -> 1068 (its one line of headroom) and
CLAUDE.md stays at 41, the stash section absorbing the second rule inside its
existing six lines. The mechanism, the class and the escape live in the hook
header, which carries no ceiling — the ratchet's own prescribed remedy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P58euzUXCVJNwmhuPC9DXY
---
 .claude/hooks/guard-process-kill.selftest.sh | 215 ++++++++++++
 .claude/hooks/guard-process-kill.sh          | 333 +++++++++++++++++++
 .claude/settings.json                        |   4 +
 AGENTS.md                                    |   1 +
 CLAUDE.md                                    |  12 +-
 5 files changed, 559 insertions(+), 6 deletions(-)
 create mode 100755 .claude/hooks/guard-process-kill.selftest.sh
 create mode 100755 .claude/hooks/guard-process-kill.sh

diff --git a/.claude/hooks/guard-process-kill.selftest.sh b/.claude/hooks/guard-process-kill.selftest.sh
new file mode 100755
index 0000000000..5889ec7c07
--- /dev/null
+++ b/.claude/hooks/guard-process-kill.selftest.sh
@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Self-test for guard-process-kill.sh — run it after touching that hook:
+#
+#   .claude/hooks/guard-process-kill.selftest.sh
+#
+# Feeds the hook the same JSON payload shape Claude Code delivers on PreToolUse and asserts
+# the block/allow verdict per command. Needs jq (to build payloads) and nothing else: no
+# install, no build, no network. Exit 0 = all cases hold.
+#
+# The harness is guard-shared-stash.selftest.sh's, one-for-one — same verdict(), expect(),
+# stderr_of(), says() and lacks() — because this guard is that guard's shape applied to the
+# other shared object. The case matrix is this guard's own, and it pins BOTH sides on
+# purpose: a guard for a class this wide is worth nothing if the PID-scoped teardown the
+# repo already prescribes comes back red.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+hook="$here/guard-process-kill.sh"
+pass=0
+fail=0
+
+command -v jq >/dev/null 2>&1 || { echo "selftest needs jq to build payloads" >&2; exit 1; }
+
+# verdict <command> [env assignments…] -> prints "block" or "allow"
+verdict() {
+  local cmd="$1"; shift
+  local payload out rc
+  payload="$(jq -nc --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  out="$(printf '%s' "$payload" | env "$@" "$hook" 2>/dev/null)"
+  rc=$?
+  case "$rc" in
+    0) printf 'allow' ;;
+    2) printf 'block' ;;
+    *) printf 'exit%s' "$rc" ;;
+  esac
+}
+
+expect() { # expect <block|allow> <command> [env…]
+  local want="$1" cmd="$2"; shift 2
+  local got; got="$(verdict "$cmd" "$@")"
+  if [ "$got" = "$want" ]; then
+    pass=$((pass + 1)); printf '  ok   %-5s  %s\n' "$got" "$cmd"
+  else
+    fail=$((fail + 1)); printf '  FAIL want=%s got=%s  %s\n' "$want" "$got" "$cmd"
+  fi
+}
+
+stderr_of() { # stderr_of <command> [env…] -> the refusal text an agent actually reads
+  local cmd="$1"; shift
+  local payload
+  payload="$(jq -nc --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  printf '%s' "$payload" | env "$@" "$hook" 2>&1 >/dev/null
+}
+
+says() { # says <needle> <label> <command> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) pass=$((pass + 1)); printf '  ok   says   %s\n' "$label" ;;
+    *) fail=$((fail + 1)); printf '  FAIL missing "%s"  %s\n' "$needle" "$label" ;;
+  esac
+}
+
+lacks() { # lacks <needle> <label> <command> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) fail=$((fail + 1)); printf '  FAIL still says "%s"  %s\n' "$needle" "$label" ;;
+    *) pass=$((pass + 1)); printf '  ok   lacks  %s\n' "$label" ;;
+  esac
+}
+
+echo "== the specimen this rule was filed for (objectstack#16182 / PR #16120) =="
+expect block "pkill -f 'dispatch-gates.mjs --self-test'"
+expect block 'pkill -f dispatch-gates.mjs'
+
+echo "== pkill selects by NAME with or without -f =="
+expect block 'pkill node'
+expect block 'pkill -9 vitest'
+expect block 'pkill -x esbuild'
+expect block 'pkill -u root node'
+expect block 'pkill --signal TERM node'
+expect block 'pkill -f "pnpm --filter @objectstack/spec test"'
+expect block '/usr/bin/pkill -f vitest'
+expect block 'OS_FOO=1 pkill -f vitest'
+
+echo "== killall is the spelling a pkill-only rule would go silent on =="
+expect block 'killall node'
+expect block 'killall -9 node'
+expect block 'killall -r "vitest.*"'
+expect block 'killall'
+
+echo "== reached through separators and command substitution =="
+expect block 'cd /home/user/objectstack && pkill -f vitest'
+expect block 'pnpm test; pkill -f vitest'
+expect block 'out=$(pkill -f vitest)'
+
+echo "== a pgrep NAME PATTERN feeding a kill is a pkill spelled out longhand =="
+expect block 'pgrep -f dispatch-gates.mjs | xargs kill'
+expect block 'kill $(pgrep -f vitest)'
+expect block 'kill -9 $(pgrep node)'
+expect block 'for p in $(pgrep -f vitest); do kill "$p"; done'
+expect block 'pgrep -lf node | awk "{print \$1}" | xargs kill -9'
+
+echo "== ps piped through grep into a kill is the hand-rolled spelling of the same thing =="
+expect block 'ps aux | grep vitest | awk "{print \$2}" | xargs kill'
+expect block 'ps -ef | grep node | xargs kill -9'
+
+echo "== PID-SCOPED kills are the POSITIVE form and must stay allowed =="
+expect allow 'kill "$SERVER_PID"'
+expect allow 'kill -0 "$SERVER_PID"'
+expect allow 'kill -9 12345'
+expect allow 'kill -- -"$PGID"'
+expect allow 'kill %1'
+expect allow 'cmd & pid=$!; kill "$pid"'
+
+echo "== the teardown AGENTS.md itself prescribes: the port is one YOU picked =="
+expect allow 'kill $(lsof -ti tcp:38421)'
+expect allow 'kill $(lsof -ti tcp:3000) 2>/dev/null'
+
+echo "== pgrep -P / -s select by a handle the caller owns — live in two tracked scripts =="
+# scripts/publish-smoke.sh kill_tree() and scripts/gen-sdui-manifest.sh sdui_live_pids().
+# A rule that reddened these would be routed around within the hour.
+expect allow 'for child in $(pgrep -P "$pid"); do kill "$child"; done'
+expect allow 'pgrep -s "$leader" | xargs kill'
+expect allow 'kill $(pgrep -P 4242)'
+expect allow 'pgrep -P "${frontier// /,}"'
+
+echo "== the same selectors on pkill, with NO pattern operand =="
+expect allow 'pkill -P "$pid"'
+expect allow 'pkill -s "$sid"'
+expect allow 'pkill -P4242'
+expect allow 'pkill --help'
+# …and adding a pattern to them is blocked again, which is what makes the pair meaningful.
+expect block 'pkill -P "$pid" node'
+expect block 'pkill -s "$sid" -f vitest'
+
+echo "== reads are reads: nothing dies, so nothing is blocked =="
+expect allow 'pgrep -f vitest'
+expect allow 'pgrep -lf node'
+expect allow 'ps aux | grep node'
+expect allow 'ps -o sid= -p "$LEADER" | tr -d " "'
+expect allow 'ps aux | grep -c vitest'
+
+echo "== unrelated commands are untouched =="
+expect allow 'pnpm --filter @objectstack/spec test'
+expect allow 'git status'
+expect allow 'node scripts/pm/dispatch-gates.mjs --self-test'
+expect allow 'rm -rf node_modules'
+
+echo "== writing ABOUT the ban must not trip the ban (objectstack#4890) =="
+expect allow 'grep -n "pkill -f" AGENTS.md'
+expect allow 'git grep -n "killall"'
+expect allow 'grep -rn "pgrep -f x | xargs kill" .claude/'
+expect allow 'echo "never run pkill -f against a shared container"'
+
+echo "== an UNQUOTED \\\" opens no quote, so the kill behind it is still seen (#11738) =="
+# Inherited from guard-shared-stash.sh's split_segments(): reading the escaped `\"` as
+# OPENING a region that never closes collapses the command into one harmless-headed segment
+# and lets the real kill ride through as an argument. The bare forms next door are the
+# controls that say the guard was reached at all.
+expect block 'echo \" ; pkill -f vitest'
+expect block 'echo \" && killall node'
+expect allow 'echo \" ; echo hello'
+expect allow 'echo \" ; git status'
+
+echo "== an escaped \\\" INSIDE a double-quoted word does NOT close it (#10406 half) =="
+# The other direction of the same rule: reading it as CLOSING splits where bash would not
+# and turns the tail of a pure READ into a segment judged on its own head word.
+expect allow 'grep -rn "he said \"pkill -f vitest\" once" .claude/'
+expect block 'echo "he said \"x\"" && pkill -f vitest'
+
+echo "== escape hatch =="
+expect allow 'pkill -f vitest' OS_ALLOW_PROCESS_KILL=1
+expect allow 'ps aux | grep node | xargs kill' OS_ALLOW_PROCESS_KILL=1
+
+echo "== the refusal leads with the POSITIVE form, and names where the hatch works =="
+# A rule that only says "not like this" gets routed into another spelling of the same
+# mistake, so the positive form is pinned as text an agent actually reads — not merely as
+# an intention in the header. And the hatch sentence must name the environment THIS HOOK
+# reads: a VAR=1 command prefix cannot reach it, and an instruction that does not work is
+# an invitation to route around the guard (#15971, the same repair the stash guard took).
+says 'Kill only a PID you recorded' 'the positive form' 'pkill -f vitest'
+says 'hook itself runs in' 'the hatch names the environment this hook reads' 'pkill -f vitest'
+lacks 're-run with' 'the refusal does not print an unusable prefix remedy' 'pkill -f vitest'
+
+echo "== payload with no command fails open =="
+if printf '%s' '{"tool_name":"Bash","tool_input":{}}' | "$hook" >/dev/null 2>&1; then
+  pass=$((pass + 1)); printf '  ok   allow  (empty tool_input)\n'
+else
+  fail=$((fail + 1)); printf '  FAIL empty tool_input should fail open\n'
+fi
+
+echo "== jq-less fallback still parses the command =="
+nojq="$(mktemp -d)"
+for b in bash env cat sed head grep; do
+  p="$(command -v "$b")" && ln -s "$p" "$nojq/$b"
+done
+printf '%s' '{"tool_name":"Bash","tool_input":{"command":"pkill -f vitest"}}' \
+  | PATH="$nojq" "$hook" >/dev/null 2>&1
+case "$?" in
+  0) got_nojq=allow ;;
+  2) got_nojq=block ;;
+  *) got_nojq="exit$?" ;;
+esac
+if [ "$got_nojq" = block ]; then
+  pass=$((pass + 1)); printf '  ok   block  (no jq on PATH)\n'
+else
+  fail=$((fail + 1)); printf '  FAIL no-jq fallback got=%s\n' "$got_nojq"
+fi
+rm -rf "$nojq"
+
+printf '\n%s passed, %s failed\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]
diff --git a/.claude/hooks/guard-process-kill.sh b/.claude/hooks/guard-process-kill.sh
new file mode 100755
index 0000000000..c59489dfa1
--- /dev/null
+++ b/.claude/hooks/guard-process-kill.sh
@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+# guard-process-kill.sh — PreToolUse guard: the PROCESS TABLE is SHARED by every agent in
+# this container. Blocks Bash commands that select processes BY NAME and kill them, and
+# lets every PID-scoped form through.
+#
+# Why: worktree isolation (AGENTS.md Prime Directive #11, enforced by guard-main-checkout*.sh)
+# gives each agent its own checkout, its own index and its own HEAD. It gives it NOTHING
+# here. There is ONE process table per container, so a name-matched kill reaches every
+# process in it regardless of which worktree spawned it — exactly the way refs/stash is one
+# stack for every worktree, which is why guard-shared-stash.sh exists and why this guard is
+# built in its shape rather than a new one.
+#
+# And it shares the property that makes the stash rule a RULE rather than advice: it reports
+# SUCCESS either way. `pkill -f foo` exits 0 when it matched *something*, so the agent that
+# fired it observes nothing at all, while the agent whose run was destroyed sees a killed
+# process and a truncated log with no signal connecting it to the neighbour that did it —
+# and re-runs, blaming a flake. The damage lands on someone ELSE's work: the one who caused
+# it cannot see it and the one who suffered it cannot attribute it, so this failure does not
+# get rarer with experience. It just gets recorded as flakiness.
+#
+# Provenance, objectstack#16182 (graded from a SELF-REPORT, not an audit catch): the
+# implementer on PR #16120 volunteered in its own delivery report, after the work was
+# already green, that it had run `pkill -f 'dispatch-gates.mjs --self-test'` to clear a
+# lingering self-test of its own. Four agents were live in that container at the time, and
+# `node scripts/pm/dispatch-gates.mjs --self-test` is a command essentially every
+# implementer in this fleet runs before pushing — a pattern kill on that string is a coin
+# flip against whoever else is mid-run. Nothing was lost that day (the process was its own
+# and had already exited) and no gate could have seen the near-miss.
+#
+# ## The rule, in its POSITIVE form — which is the half that has to be written down
+#
+#   KILL ONLY A PID YOU RECORDED.
+#
+# Record the pid when you start the thing (`cmd & pid=$!`, a pidfile, `lsof -ti tcp:PORT`
+# for the server you yourself started), then signal THAT pid. A rule that only says "not
+# like this" gets routed around into another spelling of the same mistake, which is why the
+# refusal text below leads with the positive form and why the class — not one binary — is
+# what this guard blocks.
+#
+# ## The class this blocks: selection by NAME, never selection by PID
+#
+#   pkill …            — a name/pattern matcher by construction, with or without -f
+#   killall …          — the same thing under another name (the spelling the ban would go
+#                        silent on if it named `pkill -f` alone)
+#   pgrep PATTERN piped into, or substituted into, a kill — including `| xargs kill`
+#   ps … | grep … in a command that also kills — the hand-rolled spelling of pgrep
+#
+# ## What is deliberately ALLOWED, because it is PID-scoped and this repo prescribes it
+#
+#   kill "$SERVER_PID" / kill -0 "$PID" / kill -- -"$PGID"     — a pid or a group you own
+#   kill $(lsof -ti tcp:38421)                                 — AGENTS.md's own dev-server
+#                                                                teardown: the port is one
+#                                                                you picked, not a name
+#   pgrep -P "$pid" / pgrep -s "$leader" — even piped into a kill: the selector is a parent
+#                                          or session handle the caller owns, and both are
+#                                          live in scripts/publish-smoke.sh and
+#                                          scripts/gen-sdui-manifest.sh
+#   pkill -P "$pid" / pkill -s "$sid"    — the same selectors on pkill, with NO pattern
+#                                          operand. Add a pattern and it is blocked again.
+#   pgrep -f foo / ps aux | grep node    — a READ. Nothing dies; look all you like.
+#
+# Deliberate exception (you know the match can only be yours): OS_ALLOW_PROCESS_KILL=1.
+#
+# Exit-code contract, mirroring guard-shared-stash.sh and guard-main-checkout.sh:
+# 0 = allow, 2 = block with the reason on stderr. Anything this cannot parse fails OPEN — a
+# guard that blocks work it does not understand gets disabled, and then it guards nothing.
+#
+# Known boundaries, stated so nobody has to rediscover them:
+#
+#   1. Like guard-shared-stash.sh, the check reads the FIRST WORD of each shell segment, so
+#      a wrapped invocation (bash -c '…', ssh host '…', a script file) is not caught. That
+#      is the deliberate trade: the target is the reflexive one-liner an agent reaches for
+#      mid-task, not a determined evader, and the escape hatch already exists for anyone who
+#      means it. Matching the string anywhere in the command would block every `grep pkill`
+#      run against this very file.
+#   2. The pgrep/ps coupling is WHOLE-COMMAND, not pipeline-precise: a name-pattern selector
+#      and a kill in one command line block each other even when they are unrelated
+#      (`kill "$PID" && pgrep -f node`). Pipeline-exact coupling needs separator bookkeeping
+#      this pass deliberately does not carry, and the over-block errs toward the rule with a
+#      one-variable way out — the direction this guard is willing to be wrong in.
+#
+# Self-test (no network, no build): .claude/hooks/guard-process-kill.selftest.sh
+
+set -uo pipefail
+
+[ "${OS_ALLOW_PROCESS_KILL:-}" = "1" ] && exit 0
+
+input="$(cat 2>/dev/null || true)"
+cmd=""
+if command -v jq >/dev/null 2>&1; then
+  cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+fi
+if [ -z "$cmd" ]; then
+  # jq-less fallback: lift the JSON string value honouring backslash escapes (so an
+  # embedded \" does not truncate the command), then unescape what matters for shell text.
+  cmd="$(printf '%s' "$input" \
+    | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(\(\\.\|[^"\\]\)*\)".*/\1/p' \
+    | head -1 \
+    | sed 's/\\n/ /g; s/\\t/ /g; s/\\"/"/g; s/\\\\/\\/g')"
+fi
+
+[ -n "$cmd" ] || exit 0
+
+# --- split the command into shell segments, honouring quotes ---------------------------
+# Copied case-for-case from guard-shared-stash.sh's split_segments(), including both of its
+# measured escape repairs, because the two guards face the identical parsing problem and a
+# divergence here would be a silent hole in one of them:
+#
+#   - a separator inside '…' or "…" does NOT split, so writing ABOUT the ban is never caught
+#     by the ban (objectstack#4890: the PR writing a rule must not trip it);
+#   - OUTSIDE quotes a backslash escapes the NEXT character, so an escaped `\"` opens no
+#     quoted region at all — reading it as opening one collapses the whole command into a
+#     single harmless-headed segment and lets the real kill ride through as an argument
+#     (#11738 on the stash guard, #11131 on guard-main-checkout-bash.sh);
+#   - INSIDE "…" the rule inverts: `\"` is a literal quote that leaves the region OPEN, and
+#     reading it as closing splits where bash would not, turning the tail of a pure READ
+#     into a segment judged on its own head word — a false BLOCK (#11804 / #10406).
+#
+# Both characters are kept verbatim: this pass only SPLITS, and the classifiers below
+# re-read the words afterwards.
+segments=()
+split_segments() {
+  local s="$1" seg="" q="" ch i n=${#1}
+  for ((i = 0; i < n; i++)); do
+    ch="${s:i:1}"
+    if [ -n "$q" ]; then
+      if [ "$q" = '"' ] && [ "$ch" = '\' ] && [ $((i + 1)) -lt "$n" ]; then
+        case "${s:i+1:1}" in
+          '"' | '\' | '$' | '`')
+            seg+="$ch" ; i=$((i + 1)) ; seg+="${s:i:1}" ; continue ;;
+        esac
+      fi
+      seg+="$ch"
+      [ "$ch" = "$q" ] && q=""
+      continue
+    fi
+    case "$ch" in
+      '\')
+        seg+="$ch"
+        if [ $((i + 1)) -lt "$n" ]; then i=$((i + 1)) ; seg+="${s:i:1}" ; fi
+        ;;
+      "'" | '"') q="$ch" ; seg+="$ch" ;;
+      ';' | '|' | '&' | '(' | ')' | '{' | '}' | $'\n') segments+=("$seg") ; seg="" ;;
+      *) seg+="$ch" ;;
+    esac
+  done
+  segments+=("$seg")
+}
+
+# --- words and effective head word of one segment ---------------------------------------
+# Sets W (the segment's words), HEAD_I (index of the command word) and HEAD (that word with
+# any leading path stripped, so /usr/bin/pkill reads as pkill). Returns 1 when the segment
+# carries no command word at all — an empty segment, or nothing but assignments.
+#
+# Leading FOO=bar assignments are skipped the way guard-shared-stash.sh skips them. The
+# keyword list is this guard's own addition and it is load-bearing: `for p in $(…); do kill
+# $p; done` splits so that the killing segment begins with `do`, and a pass that reads `do`
+# as the command word would not see the kill at all.
+W=()
+HEAD=""
+HEAD_I=0
+seg_words() {
+  W=()
+  read -r -a W <<<"$1"
+  HEAD=""
+  HEAD_I=0
+  local n=${#W[@]} i=0
+  while [ "$i" -lt "$n" ]; do
+    case "${W[$i]}" in
+      [A-Za-z_][A-Za-z0-9_]*=*) i=$((i + 1)) ;;
+      do | then | else | elif | time | exec | nohup | sudo | command | '!') i=$((i + 1)) ;;
+      *) break ;;
+    esac
+  done
+  [ "$i" -lt "$n" ] || return 1
+  HEAD_I=$i
+  HEAD="${W[$i]##*/}"
+  return 0
+}
+
+# --- pkill: block unless the selectors are PID-family and there is NO pattern operand ----
+# Fail-CLOSED once the command word is confidently pkill, exactly as guard-shared-stash.sh
+# is fail-closed once it has confidently identified `git stash`: an option this does not
+# recognise is blocked rather than waved through, because the unrecognised half of pkill's
+# option space is where -f, -x, -u and the signal flags live.
+check_pkill() {
+  local n=${#W[@]} i=$((HEAD_I + 1)) pidscoped=0
+  while [ "$i" -lt "$n" ]; do
+    case "${W[$i]}" in
+      --help | -h | --version | -V) return 0 ;;   # reading the manual is not killing
+      --) return 1 ;;                             # everything after it is a pattern
+      -P | --parent | -s | --session | -g | --pgroup | -t | --terminal)
+        pidscoped=1 ; i=$((i + 2)) ;;
+      -P* | -s* | -g* | -t* | --parent=* | --session=* | --pgroup=* | --terminal=*)
+        pidscoped=1 ; i=$((i + 1)) ;;
+      *) return 1 ;;                              # any other option, and every operand
+    esac
+  done
+  [ "$pidscoped" -eq 1 ] && return 0
+  return 1
+}
+
+# --- killall: every operand it takes is a NAME, so only its read-only options survive ----
+check_killall() {
+  local n=${#W[@]} i=$((HEAD_I + 1))
+  while [ "$i" -lt "$n" ]; do
+    case "${W[$i]}" in
+      --help | -h | --version | -V | -l | --list) return 0 ;;
+      *) return 1 ;;
+    esac
+  done
+  return 1
+}
+
+# --- does this segment select processes by NAME? (pgrep with a bare pattern operand) -----
+# Returns 0 = yes, this is a name-pattern selector. `pgrep -s "$leader"` and
+# `pgrep -P "$pid"` consume their argument and leave no operand behind, so they answer 1 —
+# which is what keeps scripts/publish-smoke.sh and scripts/gen-sdui-manifest.sh legal.
+is_name_selector() {
+  [ "$HEAD" = "pgrep" ] || return 1
+  local n=${#W[@]} i=$((HEAD_I + 1))
+  while [ "$i" -lt "$n" ]; do
+    case "${W[$i]}" in
+      --) i=$((i + 1)) ; [ "$i" -lt "$n" ] && return 0 ; return 1 ;;
+      -d | --delimiter | -P | --parent | -s | --session | -g | --pgroup | -t | --terminal \
+        | -u | --euid | -U | --uid | -G | --group | -F | --pidfile | --ns | --nslist)
+        i=$((i + 2)) ;;
+      -*) i=$((i + 1)) ;;
+      *) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# --- does this segment kill something? ---------------------------------------------------
+is_kill_sink() {
+  local j n=${#W[@]}
+  case "$HEAD" in
+    kill) return 0 ;;
+    xargs)
+      for ((j = HEAD_I + 1; j < n; j++)); do
+        case "${W[$j]##*/}" in kill | pkill | killall) return 0 ;; esac
+      done
+      ;;
+  esac
+  return 1
+}
+
+refuse() {
+  local what="$1" offending="$2"
+  cat >&2 <<EOF
+⛔ Blocked: this kills processes BY NAME, and the process table is ONE table shared by
+   every agent in this container.
+   $what
+   command: $offending
+
+Kill only a PID you recorded. Worktree isolation (AGENTS.md Prime Directive #11) gives you
+your own checkout, index and HEAD; it gives you nothing here, exactly as it gives you
+nothing over the shared stash stack. A name match reaches whatever a parallel agent happens
+to be running under that name right now — and it reports SUCCESS either way: you see exit
+0, they see a killed process and a truncated log with nothing tying it back to you, and
+they re-run and blame a flake. objectstack#16182 records the near-miss that filed this rule:
+\`pkill -f 'dispatch-gates.mjs --self-test'\` fired in a container holding four live agents,
+against a command every implementer here runs before pushing.
+
+Use instead — record the pid, then signal that pid:
+  cmd & pid=\$!            ; kill "\$pid"          # you started it, you have its pid
+  kill \$(lsof -ti tcp:38421)                      # the dev server on the port YOU picked
+  kill -- -"\$pgid"                                # a process group you own
+  for c in \$(pgrep -P "\$pid"); do kill "\$c"; done  # children of a pid you recorded
+
+Already allowed, no flag needed:
+  kill / kill -0 / kill -9 on a pid, a job spec or your own group
+  pgrep -P PID | pgrep -s SID | pkill -P PID | pkill -s SID     # no name pattern anywhere
+  pgrep -f PATTERN | ps aux | grep name                          # reads: nothing dies
+
+Deliberate exception (the match really can only be yours): set OS_ALLOW_PROCESS_KILL=1 in
+the environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command only,
+and this hook is not that command, so a prefix never reaches it.
+EOF
+  exit 2
+}
+
+split_segments "$cmd"
+
+saw_ps=0
+saw_grep=0
+saw_name_selector=0
+saw_kill_sink=0
+first_selector=""
+first_sink=""
+
+for seg in "${segments[@]}"; do
+  seg_words "$seg" || continue
+  trimmed="${seg#"${seg%%[![:space:]]*}"}"
+
+  case "$HEAD" in
+    pkill)
+      check_pkill && continue
+      refuse "pkill matches process NAMES, with or without -f." "$trimmed" ;;
+    killall)
+      check_killall && continue
+      refuse "killall matches process NAMES — the spelling a pkill-only rule goes silent on." \
+        "$trimmed" ;;
+    ps) saw_ps=1 ;;
+    grep | egrep | fgrep | rg)
+      saw_grep=1
+      [ -n "$first_selector" ] || first_selector="$trimmed" ;;
+  esac
+
+  if is_name_selector; then
+    saw_name_selector=1
+    [ -n "$first_selector" ] || first_selector="$trimmed"
+  fi
+  if is_kill_sink; then
+    saw_kill_sink=1
+    [ -n "$first_sink" ] || first_sink="$trimmed"
+  fi
+done
+
+if [ "$saw_kill_sink" -eq 1 ]; then
+  if [ "$saw_name_selector" -eq 1 ]; then
+    refuse "a pgrep NAME PATTERN feeding a kill is a pkill spelled out longhand." \
+      "$first_selector … $first_sink"
+  fi
+  if [ "$saw_ps" -eq 1 ] && [ "$saw_grep" -eq 1 ]; then
+    refuse "ps piped through grep into a kill is a pkill spelled out longhand." \
+      "$first_selector … $first_sink"
+  fi
+fi
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 7f5d01dcd5..eb0f372efd 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -77,6 +77,10 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-shared-stash.sh\""
           },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-process-kill.sh\""
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-governed-enqueue.sh\""
diff --git a/AGENTS.md b/AGENTS.md
index 0fc3ae3a25..caf2ac7379 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -525,6 +525,7 @@ Even inside your own worktree, operate defensively:
    killing it (or its port) breaks their in-flight work. Spin up your own instance on a
    random high port (`pnpm dev -- --fresh -p <random>`) and **shut it down yourself when
    the task is done** (`kill $(lsof -ti tcp:<port>)`). Don't leave orphan servers behind.
+   ⛔ One process table per container: **kill only a PID you recorded, never a name** (`guard-process-kill.sh`).
 9. **After pulling `main` into a long-lived worktree, refresh its build state before you
    trust a single test or gate.** A worktree open across several merges accumulates
    artefacts stale relative to the source, and every one of them fails **as if your change
diff --git a/CLAUDE.md b/CLAUDE.md
index b2f1d74a6e..c12cabe183 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,7 +1,7 @@
 # CLAUDE.md
 
 **[AGENTS.md](./AGENTS.md) is the source of truth for working in this repo — read it.**
-Its Prime Directives are binding: each of the four rules that must never be missed is
+Its Prime Directives are binding: each of the rules that must never be missed is
 inlined below as one sentence, its enforcing hook, and a pointer to the AGENTS.md heading.
 
 ## ⛔ Claim the issue before you write any code
@@ -24,12 +24,12 @@ Hooks in `.claude/hooks/`: `guard-main-checkout.sh` (Edit/Write/NotebookEdit) an
 `guard-main-checkout-bash.sh` (the same writes as Bash); override `OS_ALLOW_MAIN_EDITS=1`.
 Full rule: AGENTS.md → **Prime Directives**, directive 11.
 
-## ⛔ Never `git stash` — the stash stack is NOT covered by worktree isolation
+## ⛔ Never `git stash`, never kill by name — worktree isolation covers neither
 
-`refs/stash` lives in the common `.git` dir, so all worktrees share one LIFO stack: your
-`pop` takes another agent's entry and reports **success** — use a patch or a wip commit.
-Hook `guard-shared-stash.sh` enforces it (override `OS_ALLOW_STASH=1`; re-run its
-`.selftest.sh` if you change it). Full rule: AGENTS.md → **Multi-agent working discipline**.
+`refs/stash` lives in the common `.git` dir and the process table is one per container, neither isolated: your `pop`
+takes another agent's entry, a name-matched kill takes their run, and both report **success**. Use a patch or a wip
+commit; kill only a PID you recorded. Hooks `guard-shared-stash.sh` / `guard-process-kill.sh` (`OS_ALLOW_STASH=1`,
+`OS_ALLOW_PROCESS_KILL=1`; re-run each `.selftest.sh`). Full rule: AGENTS.md → **Multi-agent working discipline**.
 
 ## ⛔ Never edit `content/docs/releases/` in a code PR
 

From 089173a8a8ed0ae66c50fd9077df1ce8d1483bb2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 10:05:11 +0000
Subject: [PATCH 2/2] =?UTF-8?q?test(hooks):=20pin=20bare=20`pkill`=20?=
 =?UTF-8?q?=E2=80=94=20the=20ablation=20found=20the=20pidscoped=20gate=20u?=
 =?UTF-8?q?npinned?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second ablation leg: replacing check_pkill's `[ "$pidscoped" -eq 1 ] && return 0`
with an unconditional allow left the self-test green at 68/0. Bare `pkill` is
the only input that reaches that gate — every other spelling returns earlier —
so the branch had no case standing on it. It does now.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P58euzUXCVJNwmhuPC9DXY
---
 .claude/hooks/guard-process-kill.selftest.sh | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.claude/hooks/guard-process-kill.selftest.sh b/.claude/hooks/guard-process-kill.selftest.sh
index 5889ec7c07..42729cb262 100755
--- a/.claude/hooks/guard-process-kill.selftest.sh
+++ b/.claude/hooks/guard-process-kill.selftest.sh
@@ -84,6 +84,11 @@ expect block 'pkill --signal TERM node'
 expect block 'pkill -f "pnpm --filter @objectstack/spec test"'
 expect block '/usr/bin/pkill -f vitest'
 expect block 'OS_FOO=1 pkill -f vitest'
+# Bare `pkill` — its option loop completes with no PID-family selector, and it is the ONLY
+# input that reaches the pidscoped gate at the end of check_pkill. Without this row that gate
+# is unpinned: an ablation replacing it with an unconditional allow left this file green at
+# 68/0, which is how the hole was found rather than shipped.
+expect block 'pkill'
 
 echo "== killall is the spelling a pkill-only rule would go silent on =="
 expect block 'killall node'