patch(perf): local hot-fix wrapper bin-session-end-gated.cjs (gates #460 SessionEnd storm)

[LiuShiyuMath]

What this issue tracks

I applied a local-only hot-fix on @LiuShiyuMath's dev machine to mitigate the SessionEnd hook storm documented in #460 (loadavg 162 on 8-core M1 with 8 concurrent full-rescan pipelines).

This issue captures the diff applied to disk so the maintainer can decide whether to fold the same gate into packages/cli/src/bin-session-end.ts directly, or take a different approach (per-cwd lock check + global semaphore — see #460 fix scope).

The hot-fix is not in the TeamBrain repo. It lives in two user-level files:

1. ~/.teamagent/hooks/bin-session-end-gated.cjs — new 30-line gating wrapper
2. ~/.claude/settings.json — hooks.SessionEnd[0].hooks[0].command rewired to call the wrapper instead of the real hook

Gating policy implemented

Two layers, both stdlib-only (no deps, no DB):

1. Per-cwd dedupe (60 s window) — for the same cwd, if a SessionEnd was already kicked off in the last 60 s, drop the new fire. Uses /tmp/teamagent-session-end-gate/<sha256(cwd)[0..16]>.gate mtime as the canary.
2. Global concurrency cap (≤ 2 active) — across all cwds, at most 2 full-rescan pipelines may run concurrently. Counts gate files whose mtime is within the TTL window.

When dropped, the wrapper logs to /tmp/teamagent-session-end-gate.log (one line per drop, ISO timestamp + reason + cwd) and exits 0, so session close is never blocked.

When not dropped, the wrapper writes the gate file, then spawn execs ~/.teamagent/hooks/bin-session-end.cjs with the same stdin payload pipe-forwarded. Real hook's detached child still runs runFullRescanPipeline exactly as before — gate is purely a spawn-time admission control.

Patches applied

Patch 1 — new file ~/.teamagent/hooks/bin-session-end-gated.cjs

#!/usr/bin/env node
/**
 * TeamBrain bug #460 hot-fix wrapper (local-only, not in repo).
 *
 * Gates SessionEnd hook spawns to at most 1 concurrent rescan per cwd within
 * 60 s, plus a global cap of 2 concurrent rescans across all cwds. Drops the
 * fire (exit 0) when either gate is held, so Claude Code's session close is
 * never blocked.
 */
const fs = require("node:fs");
const crypto = require("node:crypto");
const path = require("node:path");
const { spawn } = require("node:child_process");

const LOCK_DIR = "/tmp/teamagent-session-end-gate";
const CWD_LOCK_TTL_MS = 60_000;
const GLOBAL_CAP = 2;
const REAL_HOOK = "/Users/m1/.teamagent/hooks/bin-session-end.cjs";

// ... 80-line gate logic, full source in https://github.com/libz-renlab-ai/TeamBrain/issues/461 (this issue)

Full source mirrored verbatim from the local file (4017 bytes) — see the Full source code block at the bottom of this issue.

Patch 2 — ~/.claude/settings.json SessionEnd hook

 "SessionEnd": [
   {
     "hooks": [
       {
         "type": "command",
-        "command": "bash -c '[ -f \"$1\" ] || exit 0; exec node \"$1\"' _ /Users/m1/.teamagent/hooks/bin-session-end.cjs",
+        "command": "bash -c '[ -f \"$1\" ] || exit 0; exec node \"$1\"' _ /Users/m1/.teamagent/hooks/bin-session-end-gated.cjs",
         "timeout": 30
       }
     ]
   }
 ]

settings.json was backed up before edit to ~/.claude/settings.json.bak-<unix-ts> so rollback is mv away.

Why this is a hot-fix, not a real fix

• Hash function differs from upstream code. Upstream cwdLockKey in packages/cli/src/bin-stop.ts:281 uses node:crypto sha256 too, but encodes / truncates differently. The gate doesn't collide with the upstream STOP_PIPELINE_LOCKS_DIR, so both can coexist without races, but my gate file is not the same file the upstream code writes.
• Lock TTL is wall-clock based, not handshake-based. If a real rescan runs > 60 s, a concurrent fire could slip through. Real fix should use the upstream lock with PID + started_at JSON (already implemented at bin-stop.ts:304+).
• Global cap of 2 is hardcoded. Should be configurable via env var.
• Wrapper duplicates the foreground-spawn responsibility of bin-session-end.ts:133 instead of folding the gate into that file. The proper fix is to edit bin-session-end.ts directly per bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460's scope.
• No regression test on the gate itself (the wrapper isn't in the repo's test surface).
• Manual install only. teamagent init will overwrite ~/.teamagent/hooks/bin-session-end.cjs cleanly but won't redeploy the wrapper or repair ~/.claude/settings.json. Anyone else who hits the same storm has to follow the install steps below.

Install / rollback recipe

Install (already done on @LiuShiyuMath's machine):

# 1. Drop the wrapper
cat > ~/.teamagent/hooks/bin-session-end-gated.cjs <<'EOF_WRAPPER'
# ... (see full source at bottom)
EOF_WRAPPER
chmod +x ~/.teamagent/hooks/bin-session-end-gated.cjs

# 2. Patch settings.json
cp ~/.claude/settings.json ~/.claude/settings.json.bak-$(date +%s)
jq '.hooks.SessionEnd[0].hooks[0].command = "bash -c '"'"'[ -f \"$1\" ] || exit 0; exec node \"$1\"'"'"' _ /Users/m1/.teamagent/hooks/bin-session-end-gated.cjs"' \
  ~/.claude/settings.json > ~/.claude/settings.json.new && mv ~/.claude/settings.json.new ~/.claude/settings.json

Rollback:

ls -t ~/.claude/settings.json.bak-* | head -1 | xargs -I {} cp {} ~/.claude/settings.json
rm ~/.teamagent/hooks/bin-session-end-gated.cjs

Verification

After installing the wrapper:

• Storm reproducer (N SessionEnds within 100 ms) should yield ≤ GLOBAL_CAP (2) live bin-session-end.cjs detached children, not N.
• tail -f /tmp/teamagent-session-end-gate.log shows drop reasons (per-cwd lock held, global cap 2/2 held) instead of fires going through.
• sysctl -n vm.loadavg should stabilize at < ncpu × 2 on the same hardware.

(Live verification on the user's machine is captured in the Slack DM thread; loadavg 1-min figure will settle 60-90 s after install.)

Asks for the maintainer

1. Decide whether to fold the gate logic into packages/cli/src/bin-session-end.ts (bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460's proper fix scope: gate the spawn on the existing STOP_PIPELINE_LOCKS_DIR/<cwdLockKey>.stop-pipeline.lock with stale handling already at bin-stop.ts:304+, plus a configurable global semaphore).
2. Add a regression test packages/cli/src/__tests__/bin-session-end.concurrency.test.ts per bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460's scope item.
3. Decide what to do with the wrapper: ship a polished version under packages/cli/scripts/ so other users hitting bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460 can install it without copy-pasting from an issue, OR delete the wrapper once the proper fix lands.

Full wrapper source (verbatim copy of ~/.teamagent/hooks/bin-session-end-gated.cjs)

#!/usr/bin/env node
/**
 * TeamBrain bug #460 hot-fix wrapper (local-only, not in repo).
 *
 * Gates SessionEnd hook spawns to at most 1 concurrent rescan per cwd within
 * 60 s, plus a global cap of 2 concurrent rescans across all cwds. Drops the
 * fire (exit 0) when either gate is held, so Claude Code's session close is
 * never blocked.
 *
 * Original (ungated): bash -c '[ -f "$1" ] || exit 0; exec node "$1"' _
 *   /Users/m1/.teamagent/hooks/bin-session-end.cjs
 * Gated: this script wraps that exec.
 *
 * Why this exists: bin-session-end.cjs always spawns a detached child running
 * runFullRescanPipeline. N SessionEnds within 100 ms → N concurrent full
 * rescans, each 17-36% CPU on a fresh ~8 MB tsup-bundle parse. See issue #460.
 *
 * Remove when issue #460 lands a proper fix in packages/cli/src/bin-session-end.ts.
 */

const fs = require("node:fs");
const crypto = require("node:crypto");
const path = require("node:path");
const { spawn } = require("node:child_process");

const LOCK_DIR = "/tmp/teamagent-session-end-gate";
const CWD_LOCK_TTL_MS = 60_000;
const GLOBAL_CAP = 2;
const REAL_HOOK = "/Users/m1/.teamagent/hooks/bin-session-end.cjs";

function safeMkdir(p) {
  try { fs.mkdirSync(p, { recursive: true, mode: 0o755 }); } catch {}
}
function readMtimeMs(p) {
  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
}
function readPayload() {
  let raw = "";
  try { raw = fs.readFileSync(0, "utf-8"); } catch {}
  return raw;
}
function extractCwd(raw) {
  try {
    const obj = JSON.parse(raw);
    if (obj && typeof obj.cwd === "string" && obj.cwd) return obj.cwd;
  } catch {}
  return process.cwd();
}
function cwdHash(cwd) {
  return crypto.createHash("sha256").update(cwd).digest("hex").slice(0, 16);
}
function countActiveGlobal() {
  try {
    const now = Date.now();
    return fs.readdirSync(LOCK_DIR)
      .filter((f) => f.endsWith(".gate"))
      .filter((f) => now - readMtimeMs(path.join(LOCK_DIR, f)) < CWD_LOCK_TTL_MS)
      .length;
  } catch { return 0; }
}
function dropSilently(reason) {
  try {
    fs.appendFileSync("/tmp/teamagent-session-end-gate.log",
      `${new Date().toISOString()} drop ${reason}\n`, { mode: 0o644 });
  } catch {}
  process.exit(0);
}
function main() {
  safeMkdir(LOCK_DIR);
  const raw = readPayload();
  const cwd = extractCwd(raw);
  const h = cwdHash(cwd);
  const gateFile = path.join(LOCK_DIR, `${h}.gate`);
  const lastMs = readMtimeMs(gateFile);
  if (lastMs > 0 && Date.now() - lastMs < CWD_LOCK_TTL_MS) {
    dropSilently(`per-cwd lock held cwd=${cwd}`); return;
  }
  const active = countActiveGlobal();
  if (active >= GLOBAL_CAP) {
    dropSilently(`global cap ${active}/${GLOBAL_CAP} held cwd=${cwd}`); return;
  }
  try { fs.writeFileSync(gateFile, `${Date.now()}\n${cwd}\n`, { mode: 0o644 }); } catch {}
  if (!fs.existsSync(REAL_HOOK)) { process.exit(0); }
  const child = spawn(process.execPath, [REAL_HOOK], {
    stdio: ["pipe", "inherit", "inherit"], env: process.env,
  });
  child.stdin.write(raw); child.stdin.end();
  child.on("error", () => process.exit(0));
  child.on("exit", (code) => process.exit(typeof code === "number" ? code : 0));
}
main();

Related

• #459 — upstream bg-spare worker leak (compounds with bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460 on the same machine)
• #460 — the real bug this hot-fix mitigates
• docs/debugging/toohot-many-bg-spare-workers.md — needs an entry for "session-end storm" as a 4th trigger of the same scheduler-overload pathology
• docs/adr/0013-inner-loop-on-ci.md — 3rd variant of the same pathology, vitest fork burst

---

Filed via /investigate (continuation) on 2026-05-14.

[LiuShiyuMath]

Update — wrapper rewritten to coincide with upstream pipelineLockPath

After filing this issue I revised ~/.teamagent/hooks/bin-session-end-gated.cjs to use the exact lockfile scheme from packages/cli/src/bin-stop.ts:270-340:

• Hash: sha1(cwd).digest("hex").slice(0, 16) (was sha256 in v1 — now matches cwdLockKey)
• Path: <TEAMAGENT_HOME ?? os.homedir()>/.teamagent/locks/<hash>.stop-pipeline.lock (matches pipelineLockPath)
• JSON content: { pid: number, started_at: ISO string } (matches writePipelineLock)
• Stale policy: LOCK_MAX_AGE_MS = 30 * 60 * 1000, LOCK_FUTURE_SKEW_MS = 60 * 1000, plus process.kill(pid, 0) liveness check — matches STOP_PIPELINE_LOCK_MAX_AGE_MS, STOP_PIPELINE_LOCK_FUTURE_SKEW_MS, and the stale-handling pattern at bin-stop.ts:316-340
• Spawn: detached: true + child.unref() + lock the child's pid — matches bin-session-end.ts:133 foreground contract

Forward-compatibility property (the limitation I'd flagged in v1):

When the proper in-source fix lands per #460's scope and uses pipelineLockPath(cwd) from bin-stop.ts, the wrapper and upstream will coordinate via the same lockfile. No double-fire race, no parallel hash families. The wrapper becomes a no-op safety net that the maintainer can delete with a one-line mv rollback.

Live verification (selftest)

$ TMP_CWD=/tmp/teamagent-gate-selftest-68507
$ echo $PAYLOAD | node ~/.teamagent/hooks/bin-session-end-gated.cjs   # fire 1
$ cat ~/.teamagent/locks/a3abfb2e51783e09.stop-pipeline.lock
{"pid":68530,"started_at":"2026-05-14T03:55:12.390Z"}
$ echo $PAYLOAD | node ~/.teamagent/hooks/bin-session-end-gated.cjs   # fire 2
$ tail -1 /tmp/teamagent-session-end-gate.log
2026-05-14T03:55:12.919Z drop per-cwd lock held by pid=68530 started=2026-05-14T03:55:12.390Z cwd=/tmp/teamagent-gate-selftest-68507

Hash of /tmp/teamagent-gate-selftest-68507 matches what cwdLockKey would produce. Lock JSON shape is the one upstream would read.

Updated full wrapper source

#!/usr/bin/env node
const fs = require("node:fs");
const os = require("node:os");
const crypto = require("node:crypto");
const path = require("node:path");
const { spawn } = require("node:child_process");

const LOCK_MAX_AGE_MS = 30 * 60 * 1000;
const LOCK_FUTURE_SKEW_MS = 60 * 1000;
const GLOBAL_CAP = 2;
const REAL_HOOK = "/Users/m1/.teamagent/hooks/bin-session-end.cjs";

function teamagentHomeDir() { return process.env.TEAMAGENT_HOME || os.homedir(); }
function locksDir() { return path.join(teamagentHomeDir(), ".teamagent", "locks"); }
function cwdLockKey(cwd) { return crypto.createHash("sha1").update(cwd).digest("hex").slice(0, 16); }
function pipelineLockPath(cwd) { return path.join(locksDir(), `${cwdLockKey(cwd)}.stop-pipeline.lock`); }

function readPayload() { try { return fs.readFileSync(0, "utf-8"); } catch { return ""; } }
function extractCwd(raw) {
  try { const o = JSON.parse(raw); if (o && typeof o.cwd === "string" && o.cwd) return o.cwd; } catch {}
  return process.cwd();
}
function pidAlive(pid) {
  if (!Number.isFinite(pid) || pid <= 0) return false;
  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
}
function readLiveLock(lockPath) {
  let raw; try { raw = fs.readFileSync(lockPath, "utf-8"); } catch { return null; }
  let p; try { p = JSON.parse(raw); } catch { return null; }
  if (typeof p.pid !== "number" || p.pid <= 0) return null;
  if (typeof p.started_at !== "string") return null;
  const s = Date.parse(p.started_at); if (!Number.isFinite(s)) return null;
  const now = Date.now();
  if (s > now + LOCK_FUTURE_SKEW_MS) return null;
  if (now - s > LOCK_MAX_AGE_MS) return null;
  if (!pidAlive(p.pid)) return null;
  return { pid: p.pid, started_at: p.started_at };
}
function countActiveGlobal() {
  try {
    return fs.readdirSync(locksDir())
      .filter((f) => f.endsWith(".stop-pipeline.lock"))
      .filter((f) => readLiveLock(path.join(locksDir(), f)))
      .length;
  } catch { return 0; }
}
function writeLock(lockPath, pid) {
  try { fs.mkdirSync(path.dirname(lockPath), { recursive: true });
    fs.writeFileSync(lockPath, JSON.stringify({ pid, started_at: new Date().toISOString() }), "utf-8"); } catch {}
}
function removeLock(lockPath) { try { if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath); } catch {} }
function dropSilently(reason) {
  try { fs.appendFileSync("/tmp/teamagent-session-end-gate.log",
    `${new Date().toISOString()} drop ${reason}\n`, { mode: 0o644 }); } catch {}
  process.exit(0);
}
async function main() {
  const raw = readPayload();
  const cwd = extractCwd(raw);
  const lockPath = pipelineLockPath(cwd);
  const live = readLiveLock(lockPath);
  if (live) { dropSilently(`per-cwd lock held by pid=${live.pid} started=${live.started_at} cwd=${cwd}`); return; }
  const active = countActiveGlobal();
  if (active >= GLOBAL_CAP) { dropSilently(`global cap ${active}/${GLOBAL_CAP} held cwd=${cwd}`); return; }
  if (!fs.existsSync(REAL_HOOK)) { process.exit(0); }
  const child = spawn(process.execPath, [REAL_HOOK], {
    detached: true, stdio: ["pipe", "ignore", "ignore"], env: process.env, windowsHide: true,
  });
  writeLock(lockPath, child.pid);
  child.stdin.write(raw); child.stdin.end();
  child.on("error", () => { removeLock(lockPath); process.exit(0); });
  child.unref();
  process.exit(0);
}
main();

Remaining real (not theoretical) limitations

1. Global cap is hardcoded at 2. Should be env-configurable. Cheap follow-up.
2. No regression test — the wrapper isn't in the repo's test surface.
3. Lock cleanup on child exit: the detached real hook completes and we don't clear our lock — we rely on the 30 min stale-age policy. Matches upstream's "best-effort lock" stance but means a crashed pipeline keeps the gate engaged for up to 30 min.
4. Other open Claude Code sessions loaded ~/.claude/settings.json before my patch; whether they pick up the wrapper depends on Claude Code's hook reload behavior. New sessions will use the wrapper.

These are real follow-ups, not blockers — the gate is live and dropping fires as evidenced above.

[LiuShiyuMath]

Update — v3: found and fixed a TOCTOU race in the v2 gate

Re-triggering the storm to verify the v2 gate exposed a real bug in it: a time-of-check-to-time-of-use race.

How v2 failed

v2 did check-then-write: readLiveLock() → if free → writeLock(). Under a true simultaneous burst (12 node procs starting within the same few ms), all ~8 fast ones read the lock state as "free" before any of them finished writing. Only the late stragglers saw the lock and dropped.

Storm test against v2: 12 fires → 8 heavy rescans spawned (expected ≤2). The earlier "2 children" result only held because real SessionEnd events stagger by milliseconds as sessions close — a synthetic simultaneous burst broke it. The gate was not actually robust.

v3 fix — atomic exclusive-create

v3 replaces check-then-write with fs.writeFileSync(lockPath, payload, { flag: "wx" }) — wx is atomic exclusive create, the kernel guarantees exactly one winner. Both gates use it:

1. Per-cwd lock — atomic wx-create of the upstream-format <sha1(cwd)[0:16]>.stop-pipeline.lock. This is load-bearing: the bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460 storm was 8 fires from the same cwd, so an atomic per-cwd lock alone collapses it to 1.
2. Global slot semaphore — GLOBAL_CAP atomic slot files .gate-slot-<i>. Each fire wx-creates a free slot; none free → drop.

Stale reclaim on EEXIST: if the existing lock's pid is dead or started_at > 30 min old, unlink + retry the wx once (matches upstream STOP_PIPELINE_LOCK_MAX_AGE_MS).

Lifecycle: claim-then-spawn-then-rebind. wx-create with the gate's own pid (millisecond-scale placeholder, gate is alive during the claim), spawn the child, then plain-overwrite the lock with the child's pid. When the heavy rescan child exits, its pid dies → lock reads stale → next fire reclaims it. pid-liveness IS the release.

v3 storm test — passes

Tested post-reboot (the reboot itself cleared the leaked process table; load was already back to 3/4/6 — the gate files survived since they live in ~/.teamagent/hooks/, not /tmp):

STORM A: 8 fires, SAME cwd (literal #460 shape)
  → peak 1 concurrent heavy rescan   (7 dropped: "per-cwd lock held")

STORM B: 10 fires, ALL DISTINCT cwds (stresses global cap)
  → peak 2 concurrent heavy rescans  (8 dropped: "global cap 2/2 held")

18 fires total → 15 dropped, 3 allowed (1 + 2)
loadavg during test: 3.27 → 3.17  (did not budge)

Pre-gate baseline for the same 18-fire burst: 18 concurrent full-rescan pipelines = the loadavg-162-204 condition.

Updated full source

The v3 bin-session-end-gated.cjs is 8696 bytes (was 6371). Installed at all three local paths:

• ~/.teamagent/hooks/bin-session-end.cjs — v3 gate (path old cached sessions call directly)
• ~/.teamagent/hooks/bin-session-end-gated.cjs — v3 gate (path ~/.claude/settings.json points at)
• ~/.teamagent/hooks/bin-session-end-real.cjs — the original 7.94 MB hook, unchanged, exec'd by the gate

bin-session-end-gated.cjs v3 (full source)

#!/usr/bin/env node
/**
 * TeamBrain bug #460 hot-fix wrapper (local-only, not in repo). v3 — atomic locks.
 *
 * Gates SessionEnd hook spawns so a burst of N simultaneous session-ends can
 * never fan out into N concurrent full-rescan pipelines (the #460 storm that
 * drove an 8-core M1 to loadavg 162-204).
 *
 * Two gates, BOTH using atomic exclusive-create (fs flag "wx") as the mutex —
 * no time-of-check-to-time-of-use race:
 *
 *   1. Per-cwd lock — at most ONE rescan per cwd. Path + hash + JSON shape
 *      exactly match upstream STOP_PIPELINE_LOCKS_DIR (bin-stop.ts:270-340):
 *        <TEAMAGENT_HOME or $HOME>/.teamagent/locks/<sha1(cwd)[0:16]>.stop-pipeline.lock
 *      content: { pid, started_at }.  This is the load-bearing gate — the #460
 *      storm was 8 fires from the SAME cwd, so an atomic per-cwd lock alone
 *      collapses it to 1.
 *
 *   2. Global slot semaphore — at most GLOBAL_CAP rescans across ALL cwds.
 *      GLOBAL_CAP atomic slot files <locksDir>/.gate-slot-<i>. Each fire tries
 *      to wx-create a free slot; if none free, drop.
 *
 * Stale reclaim: a lock/slot whose pid is dead, or whose started_at is >30 min
 * old (or >60 s in the future = clock skew), is stale — unlink + retry the
 * wx-create once. Matches upstream STOP_PIPELINE_LOCK_MAX_AGE_MS / SKEW.
 *
 * Lifecycle: the lock/slot stores the spawned CHILD's pid. When the heavy
 * rescan child exits, its pid dies → the lock/slot reads as stale → the next
 * fire reclaims it. No explicit release needed; pid-liveness IS the release.
 *
 * Why claim-then-spawn-then-rewrite: wx-create needs a value before the child
 * pid exists. So: (a) wx-create with the gate's OWN pid as a millisecond-scale
 * placeholder (gate is alive during the claim, so a concurrent fire correctly
 * sees "held"); (b) spawn child; (c) plain-overwrite the lock with child.pid.
 * If spawn fails, unlink. If the wx-create lost the race, drop without spawning.
 *
 * Drops are logged to /tmp/teamagent-session-end-gate.log (cosmetic; cleared
 * on reboot — the real lock state lives in ~/.teamagent/locks/, which persists).
 *
 * Coupling: the per-cwd lock path/hash/JSON exactly match upstream, so when
 * #460's in-source fix folds the gate into packages/cli/src/bin-session-end.ts
 * using the same pipelineLockPath(cwd), this wrapper and upstream coordinate
 * via the same file. Remove this wrapper when that lands.
 *
 * Wired in two places so both old and new Claude Code sessions are gated:
 *   - bin-session-end.cjs       — the filename old (pre-patch) cached sessions
 *                                 still call directly; this file replaces the
 *                                 original 7.94 MB hook there.
 *   - bin-session-end-gated.cjs — the filename ~/.claude/settings.json points
 *                                 at for sessions started after the patch.
 * Both are byte-identical copies of this gate. The original real hook is at
 * bin-session-end-real.cjs and is exec'd by REAL_HOOK below.
 */

const fs = require("node:fs");
const os = require("node:os");
const crypto = require("node:crypto");
const path = require("node:path");
const { spawn } = require("node:child_process");

const LOCK_MAX_AGE_MS = 30 * 60 * 1000;   // matches STOP_PIPELINE_LOCK_MAX_AGE_MS
const LOCK_FUTURE_SKEW_MS = 60 * 1000;    // matches STOP_PIPELINE_LOCK_FUTURE_SKEW_MS
const GLOBAL_CAP = 2;
const REAL_HOOK = "/Users/m1/.teamagent/hooks/bin-session-end-real.cjs";
const GATE_LOG = "/tmp/teamagent-session-end-gate.log";

function teamagentHomeDir() {
  return process.env.TEAMAGENT_HOME || os.homedir();
}
function locksDir() {
  return path.join(teamagentHomeDir(), ".teamagent", "locks");
}
function cwdLockKey(cwd) {
  return crypto.createHash("sha1").update(cwd).digest("hex").slice(0, 16);
}
function pipelineLockPath(cwd) {
  return path.join(locksDir(), `${cwdLockKey(cwd)}.stop-pipeline.lock`);
}
function slotPath(i) {
  return path.join(locksDir(), `.gate-slot-${i}`);
}

function readPayload() {
  try { return fs.readFileSync(0, "utf-8"); } catch { return ""; }
}
function extractCwd(raw) {
  try {
    const obj = JSON.parse(raw);
    if (obj && typeof obj.cwd === "string" && obj.cwd) return obj.cwd;
  } catch { /* fall through */ }
  return process.cwd();
}

function pidAlive(pid) {
  if (!Number.isFinite(pid) || pid <= 0) return false;
  try { process.kill(pid, 0); return true; }
  catch (e) { return e && e.code === "EPERM"; }  // EPERM = exists, not ours
}

/** A lock/slot file is stale if absent, malformed, dead-pid, too old, or future-skewed. */
function isStale(lockPath) {
  let raw;
  try { raw = fs.readFileSync(lockPath, "utf-8"); } catch { return true; }
  let p;
  try { p = JSON.parse(raw); } catch { return true; }
  if (typeof p.pid !== "number" || p.pid <= 0) return true;
  if (typeof p.started_at !== "string") return true;
  const started = Date.parse(p.started_at);
  if (!Number.isFinite(started)) return true;
  const now = Date.now();
  if (started > now + LOCK_FUTURE_SKEW_MS) return true;  // clock skew
  if (now - started > LOCK_MAX_AGE_MS) return true;       // > 30 min
  if (!pidAlive(p.pid)) return true;                      // dead owner
  return false;
}

/**
 * Atomically claim a lock file. Returns true if WE now hold it, false if it's
 * held live by someone else. Uses wx (exclusive create) — the kernel guarantees
 * exactly one winner under a simultaneous burst, eliminating the TOCTOU race.
 */
function tryClaim(lockPath) {
  const payload = JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() });
  try {
    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
    fs.writeFileSync(lockPath, payload, { flag: "wx" });  // atomic exclusive create
    return true;
  } catch (e) {
    if (!e || e.code !== "EEXIST") return false;          // unexpected IO error → be safe, drop
    // File exists. If it's stale, reclaim it once.
    if (isStale(lockPath)) {
      try { fs.unlinkSync(lockPath); } catch { /* someone else may have just removed it */ }
      try {
        fs.writeFileSync(lockPath, payload, { flag: "wx" });
        return true;
      } catch { return false; }   // lost the reclaim race
    }
    return false;                  // held live by someone else
  }
}

/** Rewrite a lock we already own with the real child pid (plain write, we own it). */
function rebindLock(lockPath, childPid) {
  try {
    fs.writeFileSync(
      lockPath,
      JSON.stringify({ pid: childPid, started_at: new Date().toISOString() }),
      "utf-8",
    );
  } catch { /* best-effort */ }
}
function release(lockPath) {
  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
}

/** Grab one of GLOBAL_CAP atomic slots. Returns the slot path, or null if all full. */
function acquireGlobalSlot() {
  for (let i = 0; i < GLOBAL_CAP; i++) {
    const sp = slotPath(i);
    if (tryClaim(sp)) return sp;
  }
  return null;
}

function dropSilently(reason) {
  try {
    fs.appendFileSync(GATE_LOG, `${new Date().toISOString()} drop ${reason}\n`, { mode: 0o644 });
  } catch { /* ignore */ }
  process.exit(0);
}

function main() {
  const raw = readPayload();
  const cwd = extractCwd(raw);
  const lockPath = pipelineLockPath(cwd);

  // Gate 1 — per-cwd. Atomic. This alone collapses the #460 same-cwd storm.
  if (!tryClaim(lockPath)) {
    dropSilently(`per-cwd lock held cwd=${cwd}`);
    return;
  }

  // Gate 2 — global slot semaphore. Atomic. Caps distinct-cwd bursts.
  const slot = acquireGlobalSlot();
  if (!slot) {
    release(lockPath);   // give the per-cwd lock back so this cwd isn't blocked 30 min
    dropSilently(`global cap ${GLOBAL_CAP}/${GLOBAL_CAP} held cwd=${cwd}`);
    return;
  }

  // Won both gates. Spawn the real hook detached so session close is not blocked.
  if (!fs.existsSync(REAL_HOOK)) {
    release(lockPath); release(slot);
    process.exit(0);
  }
  let child;
  try {
    child = spawn(process.execPath, [REAL_HOOK], {
      detached: true,
      stdio: ["pipe", "ignore", "ignore"],
      env: process.env,
      windowsHide: true,
    });
  } catch {
    release(lockPath); release(slot);
    process.exit(0);
  }
  // Rebind both lock files to the CHILD's pid: when the heavy rescan child
  // exits, its pid dies → both files read as stale → the next fire reclaims
  // them. pid-liveness IS the release; no explicit cleanup path needed.
  rebindLock(lockPath, child.pid);
  rebindLock(slot, child.pid);
  child.on("error", () => { release(lockPath); release(slot); process.exit(0); });
  try { child.stdin.write(raw); child.stdin.end(); } catch { /* child may have errored */ }
  child.unref();
  process.exit(0);
}

main();

Remaining real follow-ups (unchanged from before, still not blockers)

1. GLOBAL_CAP hardcoded at 2 — should be env-configurable.
2. No regression test in the repo's test surface — the concurrency test bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460 lists would cover exactly the TOCTOU case v2 failed.
3. /tmp/teamagent-session-end-gate.log is cosmetic and cleared on reboot — the real lock state in ~/.teamagent/locks/ persists, which is correct, but means drop-history doesn't survive reboot.
4. The proper fix is still to fold this into packages/cli/src/bin-session-end.ts per bug(perf): SessionEnd hook spawns N concurrent full-rescan pipelines — load 162 on 8-core M1 #460's scope — this wrapper is a hot-fix, not the destination.

The TOCTOU lesson is the main thing for the in-source fix: whatever gates the spawn must use an atomic primitive (wx create, mkdir, or a real advisory lock), not check-then-write — because bin-session-end.ts:133's whole problem is that N fires arrive simultaneously.

[LiuShiyuMath]

非技术版过热诊断说明（解释本 issue 的 hot-fix 闸门「装了什么红绿灯」）已发布在 #460 的评论里：#460 (comment) —— 同时记录了一个探查代码时的新发现：bin-pre-compact.ts:97 有和 bin-session-end.ts:133 完全相同的缺锁 bug，本 hot-fix gate 目前只覆盖 session-end，pre-compact 仍是裸的，in-source 正式修法需同时覆盖两条路径。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。

[github-actions]

⚠️ FIXEDFLOW (warn-only): 24 小时内未加 grill-ready label。当前为 7 天软提醒期；切到 enforce 后会自动 close。详见 docs/FIXEDFLOW.md。