chore(wheelhouse): cascade template@f34d0e85

Auto-applied by socket-wheelhouse sync-scaffolding into socket-cli.
11 file(s) touched:
  - .claude/hooks/fleet/_shared/payload.mts
  - .claude/hooks/fleet/no-premature-commit-kill-guard/README.md
  - .claude/hooks/fleet/no-premature-commit-kill-guard/index.mts
  - .claude/hooks/fleet/no-premature-commit-kill-guard/package.json
  - .claude/hooks/fleet/no-premature-commit-kill-guard/test/index.test.mts
  - .claude/hooks/fleet/no-premature-commit-kill-guard/tsconfig.json
  - .claude/settings.json
  - CLAUDE.md
  - docs/agents.md/fleet/hook-registry.md
  - pnpm-workspace.yaml
  - scripts/fleet/check/soak-excludes-have-dates.mts

Author: jdalton

.claude/hooks/fleet/_shared/payload.mts

@@ -61,6 +61,10 @@ export interface ToolInput {
   readonly old_string?: unknown | undefined
   // Bash
   readonly command?: unknown | undefined
+  // Bash: true when the call requested `run_in_background`. Hooks that gate
+  // backgrounding (a backgrounded git commit hides its bounded pre-commit's
+  // completion) read it. Optional + unknown so a shape surprise can't crash.
+  readonly run_in_background?: unknown | undefined
 }
 
 /**

.claude/hooks/fleet/no-premature-commit-kill-guard/README.md

@@ -0,0 +1,38 @@
+# no-premature-commit-kill-guard
+
+PreToolUse Bash hook. Blocks two anti-patterns that share one root cause:
+
+1. **Backgrounding a `git commit`** (or `rebase` / `merge` / `cherry-pick`) via `run_in_background: true`.
+2. **`pkill` / `kill` / `killall` of a `git commit` or `vitest`** process.
+
+## Why
+
+A `git commit` (and the other three, which also fire the pre-commit chain) runs the staged-test reminder. That reminder is **bounded to ~60s** (`STAGED_TEST_TIMEOUT_MS` in `.git-hooks/_shared/helpers.mts`) but still takes real time on a non-trivial staged set. A commit that is "still running" before that bound elapses is **not a hang**.
+
+The failure loop this guard breaks:
+
+- Backgrounding the commit hides the bounded run's completion. The operator checks too early, sees it "still going", and concludes it hung.
+- Then a `pkill` / `kill` of the git-commit (or the vitest it spawned) tears down a mid-pre-commit run. That leaves a stale `.git/index.lock` (index corruption — the next git op fails with "Another git process seems to be running") and leaks vitest worker processes that pile up across attempts.
+
+Running the commit in the **foreground** and waiting for the bounded pre-commit avoids the whole loop. CI / the merge gate run the full suite regardless, so nothing is lost by letting the local bounded reminder finish.
+
+## Detection
+
+AST-parsed via `_shared/shell-command.mts` (`findInvocation` / `commandsFor`), never a raw regex on the line:
+
+- `run_in_background === true` **and** the command invokes `git commit` / `git rebase` / `git merge` / `git cherry-pick`.
+- a `pkill` / `kill` / `killall` whose args reference a `git commit` or `vitest` target. A `kill <pid>` of an unrelated process is not matched (no git/vitest token).
+
+## Bypass
+
+`Allow background-git bypass` typed verbatim in a recent user turn — for the rare genuinely-long migration commit you will babysit out of band, or to reap a confirmed-dead leaked vitest after the commit has already exited.
+
+## Failing open
+
+Parse / payload errors exit 0. A guard bug must not block unrelated Bash.
+
+## Related
+
+- `.git-hooks/_shared/helpers.mts` — `runStagedTestsReminder` + the `STAGED_TEST_TIMEOUT_MS` bound this guard relies on.
+- `stale-process-sweeper/` — reaps genuine orphan workers at turn end.
+- CLAUDE.md → "Background Bash".

.claude/hooks/fleet/no-premature-commit-kill-guard/index.mts

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — no-premature-commit-kill-guard.
+//
+// Two Bash anti-patterns, one root cause: a `git commit` (and rebase/merge/
+// cherry-pick, which also fire the pre-commit chain) runs the staged-test
+// reminder, which is BOUNDED to ~60s (STAGED_TEST_TIMEOUT_MS) but still takes
+// real time. A commit that is "still running" before that elapses is NOT a
+// hang.
+//
+//   1. Backgrounding it (`run_in_background: true`) hides the bounded run's
+//      completion, so the operator checks too early, sees it "still going",
+//      and concludes it hung.
+//   2. Then `pkill`/`kill` of the git-commit (or the vitest it spawned) tears
+//      down a mid-pre-commit run — which corrupts the index (a half-written
+//      `.git/index.lock`) and leaks vitest worker processes.
+//
+// Both are blocked here so the loop can't start: run commits in the FOREGROUND
+// and WAIT for the bounded pre-commit; never kill one mid-flight.
+//
+// Detection (AST-parsed via _shared/shell-command.mts, never raw regex on the
+// line):
+//   - run_in_background === true AND the command invokes
+//     `git <commit|rebase|merge|cherry-pick>`.
+//   - a `pkill`/`kill`/`killall` whose args reference a `git commit` or
+//     `vitest` target.
+//
+// Bypass: `Allow background-git bypass` typed verbatim in a recent user turn
+// (e.g. a genuinely long migration commit you'll babysit out-of-band, or
+// reaping a confirmed-dead leaked vitest).
+//
+// Fails open on parse / payload errors.
+
+import process from 'node:process'
+
+import { commandsFor, findInvocation } from '../_shared/shell-command.mts'
+import { bypassPhrasePresent, readStdin } from '../_shared/transcript.mts'
+
+const BYPASS_PHRASE = 'Allow background-git bypass'
+
+const GIT_PRE_COMMIT_SUBCOMMANDS = [
+  'commit',
+  'rebase',
+  'merge',
+  'cherry-pick',
+]
+
+interface Payload {
+  tool_name?: unknown | undefined
+  tool_input?:
+    | { command?: unknown | undefined; run_in_background?: unknown | undefined }
+    | undefined
+  transcript_path?: unknown | undefined
+}
+
+// True when the command invokes a git subcommand that triggers the pre-commit
+// chain (and thus the bounded staged-test reminder).
+export function invokesPreCommitGit(command: string): string | undefined {
+  for (let i = 0, { length } = GIT_PRE_COMMIT_SUBCOMMANDS; i < length; i += 1) {
+    const sub = GIT_PRE_COMMIT_SUBCOMMANDS[i]!
+    if (findInvocation(command, { binary: 'git', subcommand: sub })) {
+      return `git ${sub}`
+    }
+  }
+  return undefined
+}
+
+// True when the command is a process-kill (`pkill`/`kill`/`killall`) whose
+// args target a `git commit` or a `vitest` run — the premature-teardown shape.
+// `kill <pid>` of an unrelated process is NOT matched (no git/vitest token).
+export function killsCommitOrVitest(command: string): string | undefined {
+  for (const bin of ['pkill', 'killall', 'kill']) {
+    const cmds = commandsFor(command, bin)
+    for (let i = 0, { length } = cmds; i < length; i += 1) {
+      const joined = cmds[i]!.args.join(' ')
+      if (/\bvitest\b/.test(joined)) {
+        return `${bin} … vitest`
+      }
+      if (/git\s+commit\b/.test(joined)) {
+        return `${bin} … git commit`
+      }
+    }
+  }
+  return undefined
+}
+
+function emitBackgroundBlock(label: string): void {
+  process.stderr.write(
+    [
+      `[no-premature-commit-kill-guard] Blocked: backgrounding \`${label}\`.`,
+      '',
+      `  A ${label} fires the pre-commit chain, whose staged-test reminder is`,
+      '  BOUNDED to ~60s (STAGED_TEST_TIMEOUT_MS) but still takes real time. Run',
+      '  in the FOREGROUND and wait — a still-running commit is not a hang.',
+      '  Backgrounding hides its completion and invites a premature kill that',
+      '  corrupts the index + leaks vitest workers.',
+      '',
+      `  Bypass (rare; you'll babysit it): type "${BYPASS_PHRASE}".`,
+    ].join('\n') + '\n',
+  )
+}
+
+function emitKillBlock(label: string): void {
+  process.stderr.write(
+    [
+      `[no-premature-commit-kill-guard] Blocked: \`${label}\`.`,
+      '',
+      '  Killing a git-commit or its vitest mid-pre-commit corrupts the index',
+      '  (stale .git/index.lock) and leaks vitest worker processes. The',
+      '  pre-commit staged-test reminder is bounded to ~60s — WAIT for it.',
+      '',
+      '  If a run is genuinely dead (confirmed, not just slow), reap the orphan',
+      '  with `pkill -f "vitest/dist/workers"` after the commit has exited, or',
+      `  type "${BYPASS_PHRASE}" to allow this kill.`,
+    ].join('\n') + '\n',
+  )
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin()
+  let payload: Payload
+  try {
+    payload = JSON.parse(raw) as Payload
+  } catch {
+    process.exit(0)
+  }
+
+  if (payload.tool_name !== 'Bash') {
+    process.exit(0)
+  }
+
+  const command =
+    typeof payload.tool_input?.command === 'string'
+      ? payload.tool_input.command
+      : ''
+  if (!command.trim()) {
+    process.exit(0)
+  }
+
+  const backgrounded = payload.tool_input?.run_in_background === true
+  const bgGit = backgrounded ? invokesPreCommitGit(command) : undefined
+  const killTarget = killsCommitOrVitest(command)
+
+  if (!bgGit && !killTarget) {
+    process.exit(0)
+  }
+
+  const transcriptPath =
+    typeof payload.transcript_path === 'string'
+      ? payload.transcript_path
+      : undefined
+  if (transcriptPath && bypassPhrasePresent(transcriptPath, [BYPASS_PHRASE], 3)) {
+    process.exit(0)
+  }
+
+  if (bgGit) {
+    emitBackgroundBlock(bgGit)
+  } else if (killTarget) {
+    emitKillBlock(killTarget)
+  }
+  process.exit(2)
+}
+
+void main()

.claude/hooks/fleet/no-premature-commit-kill-guard/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hook-no-premature-commit-kill-guard",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  },
+  "devDependencies": {
+    "@socketsecurity/lib-stable": "catalog:",
+    "@types/node": "catalog:"
+  }
+}

.claude/hooks/fleet/no-premature-commit-kill-guard/test/index.test.mts

@@ -0,0 +1,139 @@
+// prefer-async-spawn: sync-semantics-required — a node:test spec drives the
+// hook subprocess and asserts on its exit + stderr inline; spawnSync (from the
+// lib, not node:child_process) is the right fit. encoding is set at runtime so
+// stdout/stderr come back as strings.
+import { spawnSync } from '@socketsecurity/lib-stable/process/spawn/child'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { invokesPreCommitGit, killsCommitOrVitest } from '../index.mts'
+
+const HOOK = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'index.mts',
+)
+
+function writeTranscript(userText: string): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'no-premature-kill-tx-'))
+  const file = path.join(dir, 'transcript.jsonl')
+  writeFileSync(
+    file,
+    JSON.stringify({
+      type: 'user',
+      message: { role: 'user', content: userText },
+    }) + '\n',
+  )
+  return file
+}
+
+function run(
+  command: string,
+  opts?: { background?: boolean; transcriptPath?: string },
+): { code: number; stderr: string } {
+  const r = spawnSync('node', [HOOK], {
+    encoding: 'utf8',
+    input: JSON.stringify({
+      tool_name: 'Bash',
+      tool_input: { command, run_in_background: opts?.background ?? false },
+      transcript_path: opts?.transcriptPath,
+    }),
+  })
+  return { code: typeof r.status === 'number' ? r.status : -1, stderr: String(r.stderr ?? '') }
+}
+
+// --- pure helpers ---
+
+test('invokesPreCommitGit: git commit / rebase / merge / cherry-pick', () => {
+  assert.equal(invokesPreCommitGit('git commit -m "x"'), 'git commit')
+  assert.equal(invokesPreCommitGit('git rebase origin/main'), 'git rebase')
+  assert.equal(invokesPreCommitGit('git merge feat'), 'git merge')
+  assert.equal(invokesPreCommitGit('git cherry-pick abc123'), 'git cherry-pick')
+})
+
+test('invokesPreCommitGit: non-pre-commit git is undefined', () => {
+  assert.equal(invokesPreCommitGit('git status'), undefined)
+  assert.equal(invokesPreCommitGit('git push origin main'), undefined)
+  assert.equal(invokesPreCommitGit('node build.mts'), undefined)
+})
+
+test('killsCommitOrVitest: pkill/kill of vitest or git commit', () => {
+  assert.ok(killsCommitOrVitest('pkill -f vitest'))
+  assert.ok(killsCommitOrVitest('pkill -9 -f "vitest/dist/workers"'))
+  assert.ok(killsCommitOrVitest("pkill -f 'git commit'"))
+  assert.ok(killsCommitOrVitest('killall vitest'))
+})
+
+test('killsCommitOrVitest: unrelated kill is undefined', () => {
+  assert.equal(killsCommitOrVitest('kill 12345'), undefined)
+  assert.equal(killsCommitOrVitest('pkill -f my-dev-server'), undefined)
+  assert.equal(killsCommitOrVitest('git status'), undefined)
+})
+
+// --- end-to-end (spawned hook) ---
+
+test('blocks backgrounding a git commit', () => {
+  const { code, stderr } = run('git commit -m "wip"', { background: true })
+  assert.equal(code, 2)
+  assert.match(stderr, /no-premature-commit-kill-guard/)
+  assert.match(stderr, /FOREGROUND/)
+})
+
+test('blocks backgrounding a git rebase', () => {
+  const { code } = run('git rebase origin/main', { background: true })
+  assert.equal(code, 2)
+})
+
+test('allows a FOREGROUND git commit', () => {
+  const { code } = run('git commit -m "wip"', { background: false })
+  assert.equal(code, 0)
+})
+
+test('allows backgrounding a non-git command (dev server)', () => {
+  const { code } = run('node dev-server.mts', { background: true })
+  assert.equal(code, 0)
+})
+
+test('blocks pkill of vitest', () => {
+  const { code, stderr } = run('pkill -f vitest')
+  assert.equal(code, 2)
+  assert.match(stderr, /corrupts the index/)
+})
+
+test('blocks pkill of a git commit', () => {
+  const { code } = run("pkill -f 'git commit'")
+  assert.equal(code, 2)
+})
+
+test('allows kill of an unrelated pid', () => {
+  const { code } = run('kill 4242')
+  assert.equal(code, 0)
+})
+
+test('bypass phrase allows backgrounding the git commit', () => {
+  const { code } = run('git commit -m "long migration"', {
+    background: true,
+    transcriptPath: writeTranscript('Allow background-git bypass'),
+  })
+  assert.equal(code, 0)
+})
+
+test('non-Bash tool passes through', () => {
+  const r = spawnSync('node', [HOOK], {
+    encoding: 'utf8',
+    input: JSON.stringify({
+      tool_name: 'Read',
+      tool_input: { file_path: 'foo.ts' },
+    }),
+  })
+  assert.equal(r.status, 0)
+})
+
+test('malformed payload fails open', () => {
+  const r = spawnSync('node', [HOOK], { encoding: 'utf8', input: 'not-json' })
+  assert.equal(r.status, 0)
+})

.claude/hooks/fleet/no-premature-commit-kill-guard/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "esnext",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  }
+}

.claude/settings.json

@@ -347,6 +347,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fleet/no-pm-exec-guard/index.mts"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fleet/no-premature-commit-kill-guard/index.mts"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fleet/no-tsx-guard/index.mts"