From f4f9e3cb47d6b1f39ef8ae33449122b8ff2afee7 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Tue, 28 Apr 2026 12:45:50 -0400
Subject: [PATCH 01/17] docs(claude): add programmatic-Claude lockdown rule +
 skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cascaded from socket-repo-template. CLAUDE.md gains one bullet
alongside the other security 🚨 rules; the skill at
.claude/skills/programmatic-claude-lockdown/SKILL.md holds the
four-flag table (`tools`/`allowedTools`/`disallowedTools`/
`permissionMode: 'dontAsk'`), both recipes (read-only and
Bash-needing), and the never-do list.

Reference impl: socket-lib/tools/prim/src/disambiguate.mts (SDK form);
socket-registry weekly-update.yml uses the Bash-needing CLI form.
---
 .../programmatic-claude-lockdown/SKILL.md     | 84 +++++++++++++++++++
 CLAUDE.md                                     |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 .claude/skills/programmatic-claude-lockdown/SKILL.md

diff --git a/.claude/skills/programmatic-claude-lockdown/SKILL.md b/.claude/skills/programmatic-claude-lockdown/SKILL.md
new file mode 100644
index 00000000..f2561013
--- /dev/null
+++ b/.claude/skills/programmatic-claude-lockdown/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: programmatic-claude-lockdown
+description: Reference for locking down programmatic Claude invocations (the `claude` CLI in workflows/scripts, the `@anthropic-ai/claude-agent-sdk` `query()` in code). Loads on demand when writing or reviewing any callsite that runs Claude programmatically. Source: https://code.claude.com/docs/en/agent-sdk/permissions.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Programmatic Claude lockdown
+
+**Rule:** every programmatic Claude callsite sets four flags. Skip any one and a future edit silently widens the surface.
+
+## The four flags
+
+| Layer | SDK option | CLI flag | What it does |
+|---|---|---|---|
+| Definition | `tools` | `--tools` | Base set the model is told about. Tools not listed are invisible — no `tool_use` block possible. |
+| Auto-approve | `allowedTools` | `--allowedTools` | Step 4. Listed tools run without invoking `canUseTool`. |
+| Deny | `disallowedTools` | `--disallowedTools` | Step 2. Wins even against `bypassPermissions`. Defense-in-depth. |
+| Mode | `permissionMode: 'dontAsk'` | `--permission-mode dontAsk` | Step 3. Unmatched tools denied without falling through to a missing `canUseTool`. |
+
+The official permission flow (1) hooks → (2) deny rules → (3) permission mode → (4) allow rules → (5) `canUseTool`. In `dontAsk` mode step 5 is skipped — denied. The doc states verbatim: *"`allowedTools` and `disallowedTools` ... control whether a tool call is approved, not whether the tool is available."* Availability is `tools`.
+
+## Recipe — read-only agent (audit, classify, summarize)
+
+```ts
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+query({
+  prompt: '...',
+  options: {
+    tools: ['Read', 'Grep', 'Glob'],
+    allowedTools: ['Read', 'Grep', 'Glob'],
+    disallowedTools: ['Agent', 'Bash', 'Edit', 'NotebookEdit', 'Task', 'WebFetch', 'WebSearch', 'Write'],
+    permissionMode: 'dontAsk',
+  },
+})
+```
+
+CLI form for workflow YAML / shell scripts:
+
+```yaml
+claude --print \
+  --tools "Read" "Grep" "Glob" \
+  --allowedTools "Read" "Grep" "Glob" \
+  --disallowedTools "Agent" "Bash" "Edit" "NotebookEdit" "Task" "WebFetch" "WebSearch" "Write" \
+  --permission-mode dontAsk \
+  --model "$MODEL" \
+  --max-turns 25 \
+  "<prompt>"
+```
+
+## Recipe — agent that needs Bash (e.g. `/updating`: pnpm + git + jq)
+
+Narrow `Bash(...)` patterns surgically. Block dangerous Bash patterns explicitly. Fleet rules: no `npx`/`pnpm dlx`/`yarn dlx`; no `curl`/`wget` exfil; no destructive `rm -rf`; no `sudo`. Build the deny list as shell vars so the npx/dlx denials can carry the `# zizmor:` exemption marker (the pre-commit `scanNpxDlx` hook treats those literal strings as the prohibited tools, not as exemptions, unless the line is tagged):
+
+```yaml
+DISALLOW_BASE='Agent Task NotebookEdit WebFetch WebSearch Bash(curl:*) Bash(wget:*) Bash(rm -rf*) Bash(sudo:*)'
+DISALLOW_PKG_EXEC='Bash(npx:*) Bash(pnpm dlx:*) Bash(yarn dlx:*)'  # zizmor: documentation-prohibition
+claude --print \
+  --tools "Bash" "Read" "Write" "Edit" "Glob" "Grep" \
+  --allowedTools "Bash(pnpm:*)" "Bash(git:*)" "Bash(jq:*)" "Read" "Write" "Edit" "Glob" "Grep" \
+  --disallowedTools $DISALLOW_BASE $DISALLOW_PKG_EXEC \
+  --permission-mode dontAsk \
+  --model "$MODEL" --max-turns 25 \
+  "<prompt>"
+```
+
+## Never
+
+- ❌ `permissionMode: 'default'` in headless contexts — falls through to a missing `canUseTool`. Behavior undefined.
+- ❌ `permissionMode: 'bypassPermissions'` / `allowDangerouslySkipPermissions: true`.
+- ❌ Omitting `tools` — SDK default is the full claude_code preset.
+- ❌ `Agent` / `Task` permitted — sub-agents inherit modes and can escape per-subagent restrictions when the parent is `bypassPermissions`/`acceptEdits`/`auto`.
+
+## Reference implementation
+
+`socket-lib/tools/prim/src/disambiguate.mts` — canonical SDK-form callsite. The file header documents each flag against the eval-flow step it enforces.
+
+`socket-lib/tools/prim/test/disambiguate.test.mts` — source-text guards that fail the build if `BASE_TOOLS` widens, if `tools: BASE_TOOLS` is unwired, if `permissionMode` drifts from `'dontAsk'`, or if `bypassPermissions` / `allowDangerouslySkipPermissions: true` ever appears. Mirror this pattern in any new callsite.
+
+## Existing fleet callsites
+
+- `socket-registry/.github/workflows/weekly-update.yml` — two `claude --print` invocations (run `/updating` skill, fix test failures). Bash recipe above.
+- `socket-lib/tools/prim/src/disambiguate.mts` — read-only recipe above (`query()` SDK form).
diff --git a/CLAUDE.md b/CLAUDE.md
index a59e46aa..793dbf85 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,6 +44,7 @@ The umbrella rule: never run a git command that mutates state belonging to a pat
 - **minimumReleaseAge**: NEVER add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding — the age threshold is a security control.
 - 🚨 **NEVER mention private repos or internal project names** in commits, PR titles/descriptions/comments, issues, release notes, or any public-surface text. Internal codenames, unreleased product names, internal tooling repo names not on the public org page, customer names, partner names — none belong in public surfaces. **Omit the reference entirely.** Don't substitute a placeholder ("an internal tool", "a downstream consumer", etc.) — the placeholder itself is a tell that something is being elided. Rewrite the sentence to not need the reference at all.
 - 🚨 **NEVER trigger Publish / Release / Provenance / Build-Release workflows** — no `gh workflow run`, `gh workflow dispatch`, or `gh api .../dispatches`. Workflow dispatches are irrevocable: Publish workflows push npm versions (unpublishable after 24h), Build/Release workflows pin GitHub releases by SHA, container workflows push immutable tags. Even build workflows with a `dry_run` input still treat the dispatch itself as the prod trigger. The user runs workflow_dispatch jobs manually after CI passes on the release commit + tag — Claude **never** dispatches them. If the user asks for a publish, tell them to run the command in their own terminal (or the GitHub Actions UI).
+- 🚨 **Programmatic Claude calls** (workflows, skills, scripts that invoke `claude` CLI or `@anthropic-ai/claude-agent-sdk`) MUST set all four lockdown flags: `--tools`/`tools`, `--allowedTools`/`allowedTools`, `--disallowedTools`/`disallowedTools`, and `--permission-mode dontAsk`/`permissionMode: 'dontAsk'`. NEVER `default` mode in headless contexts (falls through to a missing `canUseTool` → undefined behavior). NEVER `bypassPermissions`. See `.claude/skills/programmatic-claude-lockdown/SKILL.md` for the recipe + reference impl (`socket-lib/tools/prim/src/disambiguate.mts`).
 - File existence: ALWAYS `existsSync` from `node:fs`. NEVER `fs.access`, `fs.stat`-for-existence, or an async `fileExists` wrapper. Import form: `import { existsSync, promises as fs } from 'node:fs'`.
 - Null-prototype objects: ALWAYS use `{ __proto__: null, ...rest }` for config, return, and internal-state objects. Prevents prototype pollution and accidental inheritance. See `src/socket-sdk-class.ts` and `src/file-upload.ts` for examples.
 - Linear references: NEVER reference Linear issues (e.g. `SOC-123`, `ENG-456`, Linear URLs) in code, code comments, or PR titles/descriptions/review comments. Keep the codebase and PR history tool-agnostic — tracking lives in Linear.

From 14d0c83b75b2af6d29cc7902bb720e6d44c89d72 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Tue, 28 Apr 2026 13:03:26 -0400
Subject: [PATCH 02/17] =?UTF-8?q?chore(deps):=20bump=20pnpm=2011.0.0-rc.5?=
 =?UTF-8?q?=20=E2=86=92=2011.0.0=20(GA)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pnpm v11 is now stable: https://github.com/pnpm/pnpm/releases/tag/v11.0.0

- package.json: packageManager pin "pnpm@11.0.0-rc.5" → "pnpm@11.0.0";
  engines.pnpm ">=11.0.0-rc.0" → ">=11.0.0".
- external-tools.json: bump version + 6 platform sha256s (darwin
  arm64/x64, linux arm64/x64, win arm64/x64). Hashes computed locally
  from the v11.0.0 release tarballs.

pnpm-workspace.yaml already on the v11 idioms (allowBuilds,
pmOnFail, minimumReleaseAge); lockfile shape unchanged.
---
 external-tools.json | 14 +++++++-------
 package.json        |  4 ++--
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/external-tools.json b/external-tools.json
index 06ef8a73..a3c36c59 100644
--- a/external-tools.json
+++ b/external-tools.json
@@ -22,7 +22,7 @@
     },
     "pnpm": {
       "description": "pnpm — the fleet's package manager.",
-      "version": "11.0.0-rc.5",
+      "version": "11.0.0",
       "packageManager": "pnpm",
       "repository": "github:pnpm/pnpm",
       "release": "asset",
@@ -34,27 +34,27 @@
       "checksums": {
         "darwin-arm64": {
           "asset": "pnpm-darwin-arm64.tar.gz",
-          "sha256": "32a50710ccacfdcf14e6d5995d5368298eec913b0ce3903b9e09b6555f06f4e5"
+          "sha256": "3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b"
         },
         "darwin-x64": {
           "asset": "pnpm-darwin-x64.tar.gz",
-          "sha256": "71dca33f4275da6b43bf1eb40bdc4d876f59a116716eacbf01079c3d985ff85d"
+          "sha256": "1701748b75187f1333a9c616827943ff84ff46cc42becc156ff6864b9bd0f948"
         },
         "linux-arm64": {
           "asset": "pnpm-linux-arm64.tar.gz",
-          "sha256": "2dd04127ff10b1f9dd20bae248b779c77a8ec67e3afa35e7256e5f94abddd493"
+          "sha256": "1e6d87ebfd7ff169966ff5b3ad71b780b883c68d3e59987df1096dfd8853df75"
         },
         "linux-x64": {
           "asset": "pnpm-linux-x64.tar.gz",
-          "sha256": "7ebef4b616ba41fb0d54a207b36508fae3346723283a088b43fc1e038ee6fed0"
+          "sha256": "9b44acc77ada40fc41b665fde1d57367a5ebec31bd4b1b00598daed195da3e17"
         },
         "win-arm64": {
           "asset": "pnpm-win32-arm64.zip",
-          "sha256": "e4a39ad4c251db5e34b18b98561ef25bab5506ad65cad2fa3602af58d1972667"
+          "sha256": "0746be8e98ca183078d0747559f0cbbd30a13a53eb177f67474eb3c52dc21bc8"
         },
         "win-x64": {
           "asset": "pnpm-win32-x64.zip",
-          "sha256": "147485ae2f38c3d1ccf2f5db00d0244416bcd22b9114c02388e6a78f41538fc4"
+          "sha256": "581e222e622cd0cc4f0ac5f85dd0db76b65117e3b17507979d89e63fdc68edca"
         }
       }
     },
diff --git a/package.json b/package.json
index 586274d1..f27ff047 100644
--- a/package.json
+++ b/package.json
@@ -111,7 +111,7 @@
   },
   "engines": {
     "node": ">=18.20.8",
-    "pnpm": ">=11.0.0-rc.0"
+    "pnpm": ">=11.0.0"
   },
-  "packageManager": "pnpm@11.0.0-rc.5"
+  "packageManager": "pnpm@11.0.0"
 }

From dae9d496cd47fbec90f336c87389d55ca5aad2c3 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 29 Apr 2026 14:16:55 -0400
Subject: [PATCH 03/17] chore(ci): cascade socket-registry pin to eeb81520
 (pnpm 11.0.0 GA)

---
 .github/workflows/ci.yml            | 2 +-
 .github/workflows/generate.yml      | 6 +++---
 .github/workflows/provenance.yml    | 2 +-
 .github/workflows/weekly-update.yml | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b430cd4b..535697a0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,6 +21,6 @@ concurrency:
 jobs:
   ci:
     name: Run CI Pipeline
-    uses: SocketDev/socket-registry/.github/workflows/ci.yml@85a2fc0d33af6304246620365de3e7f053035a8d # main
+    uses: SocketDev/socket-registry/.github/workflows/ci.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
     with:
       test-script: 'pnpm run test --all --skip-build'
diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml
index b4534c3e..f26b4e8d 100644
--- a/.github/workflows/generate.yml
+++ b/.github/workflows/generate.yml
@@ -46,14 +46,14 @@ jobs:
           echo "Sleeping for $delay seconds..."
           sleep $delay
 
-      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@85a2fc0d33af6304246620365de3e7f053035a8d # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
 
       - name: Configure push credentials
         env:
           GH_TOKEN: ${{ github.token }}
         run: git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
 
-      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@85a2fc0d33af6304246620365de3e7f053035a8d # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
         with:
           gpg-private-key: ${{ secrets.BOT_GPG_PRIVATE_KEY }}
 
@@ -145,5 +145,5 @@ jobs:
           > \`\`\`
           EOF
 
-      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@85a2fc0d33af6304246620365de3e7f053035a8d # main
+      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
         if: always()
diff --git a/.github/workflows/provenance.yml b/.github/workflows/provenance.yml
index ecf5df13..7fd8db92 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -25,7 +25,7 @@ jobs:
     permissions:
       contents: write # To create GitHub releases
       id-token: write # For npm trusted publishing via OIDC
-    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@85a2fc0d33af6304246620365de3e7f053035a8d # main
+    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
     with:
       debug: ${{ inputs.debug }}
       dist-tag: ${{ inputs.dist-tag }}
diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml
index 1112eaed..2aa344ff 100644
--- a/.github/workflows/weekly-update.yml
+++ b/.github/workflows/weekly-update.yml
@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   weekly-update:
-    uses: SocketDev/socket-registry/.github/workflows/weekly-update.yml@85a2fc0d33af6304246620365de3e7f053035a8d # main
+    uses: SocketDev/socket-registry/.github/workflows/weekly-update.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
     with:
       test-setup-script: 'pnpm run build'
       test-script: 'pnpm test'

From a53d18e2553ff0bbfa3ee5ba4a2bfcd110e78528 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 29 Apr 2026 19:46:38 -0400
Subject: [PATCH 04/17] chore(ci): cascade socket-registry to 0fc1abfd (pnpm
 11.0.0 GA chain)

---
 .github/workflows/ci.yml            | 2 +-
 .github/workflows/generate.yml      | 6 +++---
 .github/workflows/provenance.yml    | 2 +-
 .github/workflows/weekly-update.yml | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 535697a0..69763f87 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,6 +21,6 @@ concurrency:
 jobs:
   ci:
     name: Run CI Pipeline
-    uses: SocketDev/socket-registry/.github/workflows/ci.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+    uses: SocketDev/socket-registry/.github/workflows/ci.yml@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
     with:
       test-script: 'pnpm run test --all --skip-build'
diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml
index f26b4e8d..8a6580ee 100644
--- a/.github/workflows/generate.yml
+++ b/.github/workflows/generate.yml
@@ -46,14 +46,14 @@ jobs:
           echo "Sleeping for $delay seconds..."
           sleep $delay
 
-      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-and-install@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
 
       - name: Configure push credentials
         env:
           GH_TOKEN: ${{ github.token }}
         run: git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
 
-      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+      - uses: SocketDev/socket-registry/.github/actions/setup-git-signing@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
         with:
           gpg-private-key: ${{ secrets.BOT_GPG_PRIVATE_KEY }}
 
@@ -145,5 +145,5 @@ jobs:
           > \`\`\`
           EOF
 
-      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+      - uses: SocketDev/socket-registry/.github/actions/cleanup-git-signing@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
         if: always()
diff --git a/.github/workflows/provenance.yml b/.github/workflows/provenance.yml
index 7fd8db92..9bd82b9d 100644
--- a/.github/workflows/provenance.yml
+++ b/.github/workflows/provenance.yml
@@ -25,7 +25,7 @@ jobs:
     permissions:
       contents: write # To create GitHub releases
       id-token: write # For npm trusted publishing via OIDC
-    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
     with:
       debug: ${{ inputs.debug }}
       dist-tag: ${{ inputs.dist-tag }}
diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml
index 2aa344ff..dc58ead3 100644
--- a/.github/workflows/weekly-update.yml
+++ b/.github/workflows/weekly-update.yml
@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   weekly-update:
-    uses: SocketDev/socket-registry/.github/workflows/weekly-update.yml@eeb81520395947c6c4ab701b4f7f690a2296b816 # main
+    uses: SocketDev/socket-registry/.github/workflows/weekly-update.yml@0fc1abfd5e9ae4396f9fb507371aeea75e2f412c # main
     with:
       test-setup-script: 'pnpm run build'
       test-script: 'pnpm test'

From 86a11e419da64e03f4551285fec26f8c4759bd29 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 30 Apr 2026 10:55:54 -0400
Subject: [PATCH 05/17] feat(.claude): add stale-process-sweeper Stop hook

Reaps orphan vitest/tsgo/type-coverage/esbuild workers at turn-end so
they don't pile up across turns and exhaust system memory. Only kills
processes whose parent has died (true orphans); leaves running
test/build trees alone.

- .claude/hooks/stale-process-sweeper/  (hook + tests + README)
- .claude/settings.json                  (Stop hook block)
- CLAUDE.md                              (Background Bash rule)

Sourced from socket-repo-template (canonical fleet hook).
---
 .claude/hooks/stale-process-sweeper/README.md |  74 ++++++
 .claude/hooks/stale-process-sweeper/index.mts | 214 ++++++++++++++++++
 .../hooks/stale-process-sweeper/package.json  |  12 +
 .../test/stale-process-sweeper.test.mts       |  84 +++++++
 .../hooks/stale-process-sweeper/tsconfig.json |  15 ++
 .claude/settings.json                         |  10 +
 CLAUDE.md                                     |   4 +
 7 files changed, 413 insertions(+)
 create mode 100644 .claude/hooks/stale-process-sweeper/README.md
 create mode 100644 .claude/hooks/stale-process-sweeper/index.mts
 create mode 100644 .claude/hooks/stale-process-sweeper/package.json
 create mode 100644 .claude/hooks/stale-process-sweeper/test/stale-process-sweeper.test.mts
 create mode 100644 .claude/hooks/stale-process-sweeper/tsconfig.json

diff --git a/.claude/hooks/stale-process-sweeper/README.md b/.claude/hooks/stale-process-sweeper/README.md
new file mode 100644
index 00000000..38d96674
--- /dev/null
+++ b/.claude/hooks/stale-process-sweeper/README.md
@@ -0,0 +1,74 @@
+# stale-process-sweeper
+
+Claude Code `Stop` hook that sweeps stale Node test/build worker
+processes at turn-end, before they pile up across turns and exhaust
+system memory.
+
+## Why
+
+Vitest's `forks` pool spawns one Node worker per CPU. When the parent
+runner exits abnormally — `Bash` timeout, `SIGINT` from the user,
+pre-commit hook crash — the workers stay alive holding 80–100 MB
+each. After a few interrupted runs the host has gigabytes of
+abandoned processes.
+
+The sweeper finds those processes (matched by command-line pattern)
+that have lost their parent, and sends them `SIGTERM`. A still-living
+parent means the worker is part of a real, in-progress run, and the
+sweeper leaves it alone.
+
+## What's swept
+
+| Pattern | Source |
+| --- | --- |
+| `vitest/dist/workers/(forks\|threads)` | Vitest worker pool |
+| `vitest/dist/(cli\|node).[mc]?js` | Orphaned Vitest parent runners |
+| `\btsgo\b` | TypeScript Go-based type checker |
+| `type-coverage/bin/type-coverage` | Type coverage tool |
+| `esbuild/(bin\|lib)/.*\bservice\b` | esbuild's daemon service |
+
+## What's not swept
+
+- Anything spawned by a still-living shell (PPID alive)
+- The Claude Code process itself or its parent terminal
+- Anything outside the pattern list
+
+## Wiring
+
+In `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/stale-process-sweeper/index.mts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+Silent on the happy path (no orphans found). When something is reaped:
+
+```
+[stale-process-sweeper] reaped 14 stale worker(s), ~1120MB freed:
+vitest-worker=29240(95MB), vitest-worker=33278(93MB), …
+```
+
+The line goes to stderr. Stop-hook output is shown to the user, not
+the model — useful diagnostic, doesn't pollute Claude's context.
+
+## Tests
+
+```bash
+cd .claude/hooks/stale-process-sweeper
+node --test test/*.test.mts
+```
diff --git a/.claude/hooks/stale-process-sweeper/index.mts b/.claude/hooks/stale-process-sweeper/index.mts
new file mode 100644
index 00000000..4e9923e5
--- /dev/null
+++ b/.claude/hooks/stale-process-sweeper/index.mts
@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// Claude Code Stop hook — stale-process-sweeper.
+//
+// Fires at turn-end. Finds Node test/build worker processes that the
+// session left behind (test runner crashed mid-run, hook timed out,
+// user interrupted `Bash`, etc.) and kills them so they don't pile up
+// across turns and exhaust system memory.
+//
+// What's swept:
+//   - vitest workers (`vitest/dist/workers/forks` and the threads pool)
+//   - vitest itself (orphan parent runners that survived a SIGINT)
+//   - tsgo / tsc type-check daemons
+//   - type-coverage workers
+//   - esbuild service processes
+//
+// What's NOT swept:
+//   - Anything spawned by a still-living shell (PPID alive)
+//   - Anything matching the user's editors / IDEs / terminals
+//   - The Claude Code process itself
+//
+// The hook is fast (one `ps` call + a few regex matches + a couple of
+// `kill -0` probes) and silent on the happy path. It only writes to
+// stderr when it actually killed something — that's a useful signal.
+//
+// Stop hooks receive JSON on stdin (we don't read it; the body
+// shape is irrelevant to our work) and exit code is advisory.
+
+import { spawnSync } from 'node:child_process'
+import process from 'node:process'
+
+// Process-name patterns that indicate a stale test/build worker.
+// Must be specific enough that real user processes (a normal `node`
+// invocation, an editor's language server) don't match.
+const STALE_PATTERNS: Array<{ name: string; rx: RegExp }> = [
+  // Vitest worker pools — both `forks` (process-per-worker) and the
+  // path the threads pool uses when isolation is requested. The
+  // canonical leak: Vitest spawns N workers, parent crashes/SIGINTs,
+  // workers stay alive holding 80–100MB each.
+  {
+    name: 'vitest-worker',
+    rx: /vitest\/dist\/workers\/(forks|threads)/,
+  },
+  // Vitest parent runner that survived its own children's exit.
+  // Matches `node ... vitest/dist/cli ... run` etc.
+  {
+    name: 'vitest-runner',
+    rx: /vitest\/dist\/(cli|node)\.[mc]?js/,
+  },
+  // tsgo / tsc daemons. `tsgo` is the new Go-based type checker;
+  // `tsc --watch` daemons can also linger.
+  {
+    name: 'tsgo',
+    rx: /\btsgo\b/,
+  },
+  // type-coverage runs as a separate process and sometimes outlives
+  // its CI step.
+  {
+    name: 'type-coverage',
+    rx: /type-coverage\/bin\/type-coverage/,
+  },
+  // esbuild's daemon service helper.
+  {
+    name: 'esbuild-service',
+    rx: /esbuild\/(bin|lib)\/.*\bservice\b/,
+  },
+]
+
+interface ProcRow {
+  pid: number
+  ppid: number
+  rss: number
+  command: string
+}
+
+function listProcesses(): ProcRow[] {
+  // -A: all processes, -o: custom format, no truncation. macOS + Linux
+  // both support this exact form. Windows isn't supported (Stop hook
+  // is unix-only in practice for socket-* repos).
+  const result = spawnSync(
+    'ps',
+    ['-A', '-o', 'pid=,ppid=,rss=,command='],
+    { encoding: 'utf8' },
+  )
+  if (result.status !== 0 || !result.stdout) {
+    return []
+  }
+  const rows: ProcRow[] = []
+  for (const line of result.stdout.split('\n')) {
+    if (!line.trim()) {
+      continue
+    }
+    // Split into [pid, ppid, rss, ...command]. `command` may contain
+    // arbitrary spaces, so re-join after the first three fields.
+    const parts = line.trim().split(/\s+/)
+    if (parts.length < 4) {
+      continue
+    }
+    const pid = Number.parseInt(parts[0]!, 10)
+    const ppid = Number.parseInt(parts[1]!, 10)
+    const rss = Number.parseInt(parts[2]!, 10)
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid)) {
+      continue
+    }
+    const command = parts.slice(3).join(' ')
+    rows.push({ pid, ppid, rss, command })
+  }
+  return rows
+}
+
+function isAlive(pid: number): boolean {
+  if (pid <= 1) {
+    // PID 0 / 1 are the kernel / init — if our parent is one of those,
+    // we're definitely an orphan, but `kill -0 1` would mislead.
+    return false
+  }
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function classify(row: ProcRow): string | undefined {
+  for (const { name, rx } of STALE_PATTERNS) {
+    if (rx.test(row.command)) {
+      return name
+    }
+  }
+  return undefined
+}
+
+function sweep(): { killed: Array<{ pid: number; name: string; rssMb: number }>; skipped: number } {
+  const rows = listProcesses()
+  const myPid = process.pid
+  const myPpid = process.ppid
+  const killed: Array<{ pid: number; name: string; rssMb: number }> = []
+  let skipped = 0
+
+  for (const row of rows) {
+    // Never touch ourselves or our parent (Claude Code).
+    if (row.pid === myPid || row.pid === myPpid) {
+      continue
+    }
+    const name = classify(row)
+    if (!name) {
+      continue
+    }
+    // Only sweep if the parent is gone (true orphan) or is PID 1
+    // (re-parented to init after the original parent exited). A live
+    // parent means the worker is part of a real, in-progress run we
+    // should not interrupt.
+    const orphan = row.ppid === 1 || !isAlive(row.ppid)
+    if (!orphan) {
+      skipped += 1
+      continue
+    }
+    try {
+      // SIGTERM first — give the worker a chance to flush. We don't
+      // wait for it; the next sweep (next turn) will SIGKILL anything
+      // that ignored SIGTERM. Keeping the hook fast matters more than
+      // squeezing every last byte.
+      process.kill(row.pid, 'SIGTERM')
+      killed.push({
+        pid: row.pid,
+        name,
+        rssMb: Math.round(row.rss / 1024),
+      })
+    } catch {
+      // Already gone, or we lack permission — nothing to do.
+    }
+  }
+  return { killed, skipped }
+}
+
+function main() {
+  // Drain stdin (Stop hook delivers a JSON payload). We don't need
+  // the body, but Node will keep the event loop alive if we don't
+  // consume it.
+  process.stdin.resume()
+  process.stdin.on('data', () => {})
+  process.stdin.on('end', runSweep)
+  // If stdin is already closed (some hook runners don't pipe input),
+  // run immediately.
+  if (process.stdin.readable === false) {
+    runSweep()
+  }
+}
+
+function runSweep() {
+  let result: { killed: Array<{ pid: number; name: string; rssMb: number }>; skipped: number }
+  try {
+    result = sweep()
+  } catch (e) {
+    // Hooks must never crash a Claude turn. Log and exit clean.
+    process.stderr.write(
+      `[stale-process-sweeper] unexpected error: ${(e as Error).message}\n`,
+    )
+    process.exit(0)
+  }
+  if (result.killed.length > 0) {
+    const totalMb = result.killed.reduce((sum, k) => sum + k.rssMb, 0)
+    const breakdown = result.killed
+      .map(k => `${k.name}=${k.pid}(${k.rssMb}MB)`)
+      .join(', ')
+    process.stderr.write(
+      `[stale-process-sweeper] reaped ${result.killed.length} stale ` +
+        `worker(s), ~${totalMb}MB freed: ${breakdown}\n`,
+    )
+  }
+  process.exit(0)
+}
+
+main()
diff --git a/.claude/hooks/stale-process-sweeper/package.json b/.claude/hooks/stale-process-sweeper/package.json
new file mode 100644
index 00000000..1a0f6de1
--- /dev/null
+++ b/.claude/hooks/stale-process-sweeper/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "hook-stale-process-sweeper",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  }
+}
diff --git a/.claude/hooks/stale-process-sweeper/test/stale-process-sweeper.test.mts b/.claude/hooks/stale-process-sweeper/test/stale-process-sweeper.test.mts
new file mode 100644
index 00000000..56ac3572
--- /dev/null
+++ b/.claude/hooks/stale-process-sweeper/test/stale-process-sweeper.test.mts
@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.resolve(__dirname, '..', 'index.mts')
+
+// Run the hook with an empty stdin payload (Stop hook delivers JSON,
+// but the body is unused). Captures stderr + exit code.
+function runHook(): Promise<{ code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [HOOK], {
+      stdio: ['pipe', 'ignore', 'pipe'],
+    })
+    let stderr = ''
+    child.stderr.on('data', d => {
+      stderr += d.toString()
+    })
+    child.on('error', reject)
+    child.on('exit', code => {
+      resolve({ code: code ?? -1, stderr })
+    })
+    // Stop hooks receive a JSON payload on stdin. Send an empty object
+    // so the hook's drain logic completes.
+    child.stdin.end('{}\n')
+  })
+}
+
+test('stale-process-sweeper: exits 0 when nothing to sweep', async () => {
+  const { code, stderr } = await runHook()
+  assert.equal(code, 0, `hook should exit 0; stderr=${stderr}`)
+  // On a clean host the hook should be silent.
+  assert.equal(
+    stderr,
+    '',
+    `hook should be silent when no orphans exist; got: ${stderr}`,
+  )
+})
+
+test('stale-process-sweeper: ignores live-parent test workers', async () => {
+  // Spawn a fake "vitest worker" whose parent is still alive. The
+  // sweeper must not touch it. We use a script path that matches the
+  // worker regex; the actual command runs `node -e 'setTimeout(...)'`
+  // long enough to outlive the hook invocation.
+  //
+  // Note: matching the regex `vitest/dist/workers/forks` requires a
+  // command line that contains that substring. We can't easily forge
+  // a real vitest binary, so we approximate by passing the path as an
+  // argv string — `ps -o command=` reflects argv, and the regex sees
+  // it.
+  const fakeWorker = spawn(
+    process.execPath,
+    [
+      '-e',
+      'setTimeout(() => {}, 5000)',
+      // This dummy arg is what `ps` will report; the sweeper's regex
+      // picks it up. The worker still has a live parent (this test
+      // process), so the sweeper should NOT kill it.
+      '/fake/vitest/dist/workers/forks.js',
+    ],
+    { stdio: 'ignore', detached: false },
+  )
+  // Give the OS a moment to register the child.
+  await new Promise(r => setTimeout(r, 100))
+  try {
+    const { code, stderr } = await runHook()
+    assert.equal(code, 0)
+    // Should NOT have reaped the fake worker — its parent (us) is
+    // alive. If the hook killed it, the message would mention it.
+    assert.ok(
+      !stderr.includes('reaped'),
+      `hook reaped a live-parent worker: ${stderr}`,
+    )
+    // Verify the worker is still alive.
+    assert.ok(
+      !fakeWorker.killed && fakeWorker.exitCode === null,
+      'fake worker should still be running',
+    )
+  } finally {
+    fakeWorker.kill('SIGKILL')
+  }
+})
diff --git a/.claude/hooks/stale-process-sweeper/tsconfig.json b/.claude/hooks/stale-process-sweeper/tsconfig.json
new file mode 100644
index 00000000..53c5c847
--- /dev/null
+++ b/.claude/hooks/stale-process-sweeper/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "esnext",
+    "verbatimModuleSyntax": true
+  }
+}
diff --git a/.claude/settings.json b/.claude/settings.json
index 894dcf15..5c6bd51f 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -35,6 +35,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/stale-process-sweeper/index.mts"
+          }
+        ]
+      }
     ]
   },
   "permissions": {
diff --git a/CLAUDE.md b/CLAUDE.md
index 793dbf85..b6e292fa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -104,6 +104,10 @@ When you encounter a legacy term during unrelated work, fix it inline — don't
 - **Leaky**: `Promise.race(pool)` inside a loop where `pool` persists across iterations (the classic concurrency-limiter bug) — also applies to `Promise.any` and long-lived arms like interrupt signals.
 - **Fix**: single-waiter "slot available" signal — each task's `.then` resolves a one-shot `promiseWithResolvers` that the loop awaits, then replaces. No persistent pool, nothing to stack.
 
+### Background Bash
+
+Never use `Bash(run_in_background: true)` for test/build commands (`vitest`, `pnpm test`, `pnpm build`, `tsgo`). Backgrounded runs you don't poll get abandoned and leak Node workers. Background mode is for dev servers and long migrations whose results you'll consume. If a run hangs, kill it: `pkill -f "vitest/dist/workers"`.
+
 ---
 
 ## EMOJI & OUTPUT STYLE

From 11082c6c55bcc7227504f24bbfb57bdb2d7404dc Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 30 Apr 2026 11:29:49 -0400
Subject: [PATCH 06/17] docs(claude): restructure CLAUDE.md to fleet-canonical
 + project-specific layout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Split CLAUDE.md into two clearly-delimited sections:

- `## 📚 Fleet Standards` — wrapped in BEGIN/END FLEET-CANONICAL markers,
  byte-identical across every socket-* repo (sync via socket-repo-template).
- `## 🏗️ SDK-Specific` — repo-owned content: Architecture, Commands,
  Configuration Files, SDK-Specific Patterns, Testing, CI Testing,
  Changelog Management, Debugging, SDK Notes.

Fleet block ~8.6 KB; verbose content moves to references:
- `docs/references/inclusive-language.md`
- `docs/references/sorting.md`
- `.claude/skills/promise-race-pitfall/SKILL.md`

CLAUDE.md 22.7 KB → 13.9 KB.

Joins this PR's programmatic-Claude lockdown additions; the new fleet
block already references the lockdown skill this PR adds.
---
 .claude/skills/promise-race-pitfall/SKILL.md |  57 +++++
 CLAUDE.md                                    | 255 ++++++-------------
 docs/references/inclusive-language.md        |  34 +++
 docs/references/sorting.md                   |  16 ++
 4 files changed, 189 insertions(+), 173 deletions(-)
 create mode 100644 .claude/skills/promise-race-pitfall/SKILL.md
 create mode 100644 docs/references/inclusive-language.md
 create mode 100644 docs/references/sorting.md

diff --git a/.claude/skills/promise-race-pitfall/SKILL.md b/.claude/skills/promise-race-pitfall/SKILL.md
new file mode 100644
index 00000000..d38f3c2a
--- /dev/null
+++ b/.claude/skills/promise-race-pitfall/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: promise-race-pitfall
+description: Reference for the `Promise.race` cross-iteration handler-leak bug. Loads on demand when writing or reviewing concurrency code that uses `Promise.race`, `Promise.any`, or hand-rolled concurrency limiters.
+---
+
+# Promise.race in loops — the handler-leak pitfall
+
+**Never re-race the same pool of promises across loop iterations.** Each call to `Promise.race([A, B, …])` attaches fresh `.then` handlers to every arm. A promise that survives N iterations accumulates N handler sets. See [nodejs/node#17469](https://github.com/nodejs/node/issues/17469) and [`@watchable/unpromise`](https://github.com/watchable/unpromise).
+
+## Patterns
+
+- **Safe** — both arms created per call:
+
+  ```ts
+  const value = await Promise.race([
+    fetchSomething(),
+    new Promise((_, r) => setTimeout(() => r(new Error('timeout')), 5000)),
+  ])
+  ```
+
+- **Leaky** — `pool` survives across iterations, accumulating handlers:
+
+  ```ts
+  while (queue.length) {
+    const winner = await Promise.race(pool)  // ← N handlers per arm by iteration N
+    pool = pool.filter(p => p !== winner)
+  }
+  ```
+
+  Same hazard for `Promise.any` and any long-lived arm such as an interrupt signal.
+
+## The fix
+
+Use a single-waiter "slot available" signal. Each task's `.then` resolves a one-shot `promiseWithResolvers` that the loop awaits, then replaces. No persistent pool, nothing to stack.
+
+```ts
+let signal = Promise.withResolvers<Task>()
+function startTask(task: Task) {
+  task.run().then(() => {
+    const prev = signal
+    signal = Promise.withResolvers<Task>()
+    prev.resolve(task)
+  })
+}
+while (queue.length) {
+  // launch up to N tasks
+  while (running < N && queue.length) startTask(queue.shift()!)
+  const finished = await signal.promise
+  running -= 1
+}
+```
+
+The arm being awaited is *always fresh*; nothing accumulates handlers.
+
+## Quick check
+
+Before merging concurrency code, ask: *does any arm of a `Promise.race`/`Promise.any` outlive the call?* If yes, refactor to the single-waiter signal.
diff --git a/CLAUDE.md b/CLAUDE.md
index b6e292fa..33343c12 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,155 +2,132 @@
 
 🚨 **MANDATORY**: Act as principal-level engineer with deep expertise in TypeScript, Node.js, and SDK development.
 
-## USER CONTEXT
+<!-- BEGIN FLEET-CANONICAL — sync via socket-repo-template/scripts/sync-scaffolding.mjs. Do not edit downstream. -->
 
-- Identify users by git credentials; use their actual name, never "the user"
-- Use "you/your" when speaking directly; use names when referencing contributions
+## 📚 Fleet Standards
 
-## 🚨 PARALLEL CLAUDE SESSIONS - WORKTREE REQUIRED
+### Identifying users
 
-**This repo may have multiple Claude sessions running concurrently against the same checkout, against parallel git worktrees, or against sibling clones.** Several common git operations are hostile to that and silently destroy or hijack the other session's work.
+Identify users by git credentials and use their actual name. Use "you/your" when speaking directly; use names when referencing contributions.
 
-- **FORBIDDEN in the primary checkout** (the one another Claude may be editing):
-  - `git stash` — shared stash store; another session can `pop` yours.
-  - `git add -A` / `git add .` — sweeps files belonging to other sessions.
-  - `git checkout <branch>` / `git switch <branch>` — yanks the working tree out from under another session.
-  - `git reset --hard` against a non-HEAD ref — discards another session's commits.
-- **REQUIRED for branch work**: spawn a worktree instead of switching branches in place. Each worktree has its own HEAD, so branch operations inside it are safe.
+### Parallel Claude sessions
 
-  ```bash
-  # From the primary checkout — does NOT touch the working tree here.
-  git worktree add -b <task-branch> ../<repo>-<task> main
-  cd ../<repo>-<task>
-  # edit, commit, push from here; the primary checkout is untouched.
-  cd -
-  git worktree remove ../<repo>-<task>
-  ```
+This repo may have multiple Claude sessions running concurrently against the same checkout, against parallel git worktrees, or against sibling clones. Several common git operations are hostile to that.
 
-- **REQUIRED for staging**: surgical `git add <specific-file> [<file>…]` with explicit paths. Never `-A` / `.`.
-- **If you need a quick WIP save**: commit on a new branch from inside a worktree, not a stash.
-- **NEVER revert files you didn't touch.** If `git status` shows files you didn't modify, those belong to another session, an upstream pull, or a hook side-effect — leave them alone. Specifically: do not run `git checkout -- <unrelated-path>` to "clean up" the diff before committing, and do not include unrelated paths in `git add`. Stage only the explicit files you edited.
+**Forbidden in the primary checkout:**
 
-The umbrella rule: never run a git command that mutates state belonging to a path other than the file you just edited.
+- `git stash` — shared store; another session can `pop` yours
+- `git add -A` / `git add .` — sweeps files from other sessions
+- `git checkout <branch>` / `git switch <branch>` — yanks the working tree out from under another session
+- `git reset --hard` against a non-HEAD ref — discards another session's commits
 
-## 📚 SHARED STANDARDS
+**Required for branch work:** spawn a worktree.
 
-- Commits: [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) `<type>(<scope>): <description>` — NO AI attribution
-- **Open PRs:** when adding commits to an OPEN PR, ALWAYS update the PR title and description to match the new scope. A title like `chore: foo` after you've added security-fix and docs commits to it is now a lie. Use `gh pr edit <num> --title "..." --body "..."` (or `--body-file`) and rewrite the body so it reflects every commit on the branch, grouped by theme. The reviewer should be able to read the PR description and know what's in it without scrolling commits.
-- Scripts: Prefer `pnpm run foo --flag` over `foo:bar` scripts
-- Dependencies: After `package.json` edits, run `pnpm install`
-- Backward Compatibility: 🚨 FORBIDDEN to maintain — actively remove when encountered
-- 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** — use `pnpm exec <package>` or `pnpm run <script>`. Add tools as pinned devDependencies first.
-- **minimumReleaseAge**: NEVER add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding — the age threshold is a security control.
-- 🚨 **NEVER mention private repos or internal project names** in commits, PR titles/descriptions/comments, issues, release notes, or any public-surface text. Internal codenames, unreleased product names, internal tooling repo names not on the public org page, customer names, partner names — none belong in public surfaces. **Omit the reference entirely.** Don't substitute a placeholder ("an internal tool", "a downstream consumer", etc.) — the placeholder itself is a tell that something is being elided. Rewrite the sentence to not need the reference at all.
-- 🚨 **NEVER trigger Publish / Release / Provenance / Build-Release workflows** — no `gh workflow run`, `gh workflow dispatch`, or `gh api .../dispatches`. Workflow dispatches are irrevocable: Publish workflows push npm versions (unpublishable after 24h), Build/Release workflows pin GitHub releases by SHA, container workflows push immutable tags. Even build workflows with a `dry_run` input still treat the dispatch itself as the prod trigger. The user runs workflow_dispatch jobs manually after CI passes on the release commit + tag — Claude **never** dispatches them. If the user asks for a publish, tell them to run the command in their own terminal (or the GitHub Actions UI).
-- 🚨 **Programmatic Claude calls** (workflows, skills, scripts that invoke `claude` CLI or `@anthropic-ai/claude-agent-sdk`) MUST set all four lockdown flags: `--tools`/`tools`, `--allowedTools`/`allowedTools`, `--disallowedTools`/`disallowedTools`, and `--permission-mode dontAsk`/`permissionMode: 'dontAsk'`. NEVER `default` mode in headless contexts (falls through to a missing `canUseTool` → undefined behavior). NEVER `bypassPermissions`. See `.claude/skills/programmatic-claude-lockdown/SKILL.md` for the recipe + reference impl (`socket-lib/tools/prim/src/disambiguate.mts`).
-- File existence: ALWAYS `existsSync` from `node:fs`. NEVER `fs.access`, `fs.stat`-for-existence, or an async `fileExists` wrapper. Import form: `import { existsSync, promises as fs } from 'node:fs'`.
-- Null-prototype objects: ALWAYS use `{ __proto__: null, ...rest }` for config, return, and internal-state objects. Prevents prototype pollution and accidental inheritance. See `src/socket-sdk-class.ts` and `src/file-upload.ts` for examples.
-- Linear references: NEVER reference Linear issues (e.g. `SOC-123`, `ENG-456`, Linear URLs) in code, code comments, or PR titles/descriptions/review comments. Keep the codebase and PR history tool-agnostic — tracking lives in Linear.
+```bash
+git worktree add -b <task-branch> ../<repo>-<task> main
+cd ../<repo>-<task>
+# edit / commit / push from here; primary checkout is untouched
+git worktree remove ../<repo>-<task>
+```
 
-### Sorting
+**Required for staging:** surgical `git add <specific-file>`. Never `-A` / `.`.
 
-Sort lists alphanumerically (literal byte order, ASCII before letters). Apply this to:
+**Never revert files you didn't touch.** If `git status` shows unfamiliar changes, leave them — they belong to another session, an upstream pull, or a hook side-effect.
 
-- **Config lists** — `permissions.allow` / `permissions.deny` in `.claude/settings.json`, `external-tools.json` checksum keys, allowlists in workflow YAML.
-- **Object key entries** — sort keys in plain JSON config + return-shape literals + internal-state objects. (Exception: `__proto__: null` always comes first, ahead of any data keys.)
-- **Import specifiers** — sort named imports inside a single statement: `import { encrypt, randomDataKey, wrapKey } from './crypto.mts'`. Imports that say `import type` follow the same rule. Statement _order_ is the project's existing convention (`node:` → external → local → types) — that's separate from specifier order _within_ a statement.
-- **Method / function source placement** — within a module, sort top-level functions alphabetically. Convention: private functions (lowercase / un-exported) sort first, exported functions second. The first-line `export` keyword is the divider.
-- **Array literals** — when the array is a config list, allowlist, or set-like collection. Position-bearing arrays (e.g. argv, anything where index matters semantically) keep their meaningful order.
+The umbrella rule: never run a git command that mutates state belonging to a path other than the file you just edited.
 
-When in doubt, sort. The cost of a sorted list that didn't need to be is approximately zero; the cost of an unsorted list that did need to be is a merge conflict.
+### Public-surface hygiene
 
-### Paths: One Path, One Reference
+🚨 The four rules below have hooks that re-print the rule on every public-surface `git` / `gh` command. The rules apply even when the hooks are not installed.
 
-**If a path appears in two places, that's a bug.** Every artifact (build output, cache directory, generated file, config location) lives at exactly one canonical location, and that location is defined in exactly one place — typically a `paths.mts` (or equivalent path helper) module. Everything else — other scripts, READMEs, Dockerfiles, workflows, tests — derives from that source. No hand-assembled `path.join(...)` strings outside the module that owns them.
+- **Real customer / company names** — never write one into a commit, PR, issue, comment, or release note. Replace with `Acme Inc` or rewrite the sentence to not need the reference. (No enumerated denylist exists — a denylist is itself a leak.)
+- **Private repos / internal project names** — never mention. Omit the reference entirely; don't substitute "an internal tool" — the placeholder is a tell.
+- **Linear refs** — never put `SOC-123`/`ENG-456`/Linear URLs in code, comments, or PR text. Linear lives in Linear.
+- **Publish / release / build-release workflows** — never `gh workflow run|dispatch` or `gh api …/dispatches`. Dispatches are irrevocable. The user runs them manually.
 
-- **Within a package**: every script imports its own path module. No script computes paths from raw segments.
-- **Across packages**: when package B consumes package A's artifact, B imports A's path module (or a typed helper exported from it) — never reconstructs the path from string segments. The classic failure: A adds a new path segment (e.g. inserts a `wasm/` directory), B's hand-built copy of the path drifts, builds break.
-- **Doc strings**: README "Output:" lines and `@fileoverview` comments describe the path; they don't _encode_ it for tools to parse. The doc is for humans only — and even there, it must match what the path module actually produces, verified by running the function.
-- **Workflows / Dockerfiles**: GitHub Actions YAML and Dockerfiles can't `import` TS, so they're allowed to reference the path string directly — but they MUST add a comment pointing at the canonical path module so the next person editing knows where the source of truth lives, and any path string must match the module byte-for-byte. If you find yourself writing the same path twice in one workflow, hoist it to a step output or a job-level env var; reference that everywhere downstream.
-- **Comments that re-state the path**: forbidden. A comment like `// Path mirrors getBuildPaths(): build/<mode>/<arch>/out/Final/...` is duplication wearing a comment costume. The import statement is the comment.
+### Commits & PRs
 
-When you spot duplication, the answer is never "update both" — the answer is "delete one and import the other." Fix the architecture, not the symptom.
+- Conventional Commits `<type>(<scope>): <description>` — NO AI attribution.
+- **When adding commits to an OPEN PR**, update the PR title and description to match the new scope. Use `gh pr edit <num> --title … --body …`. The reviewer should know what's in the PR without scrolling commits.
+- **Replying to Cursor Bugbot** — reply on the inline review-comment thread, not as a detached PR comment: `gh api repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies -X POST -f body=…`.
 
-### Inclusive Language
+### Programmatic Claude calls
 
-Use precise, neutral terms over historical metaphors that imply hierarchy or exclusion. The substitutes are not euphemisms — they're more _accurate_ (a list of allowed values genuinely is an "allowlist"; "whitelist" is a metaphor that hides what the list does).
+🚨 Workflows / skills / scripts that invoke `claude` CLI or `@anthropic-ai/claude-agent-sdk` MUST set all four lockdown flags: `tools`, `allowedTools`, `disallowedTools`, `permissionMode: 'dontAsk'`. Never `default` mode in headless contexts. Never `bypassPermissions`. See `.claude/skills/programmatic-claude-lockdown/SKILL.md`.
 
-| Replace                          | With                                                |
-| -------------------------------- | --------------------------------------------------- |
-| `whitelist` / `whitelisted`      | `allowlist` / `allowed` / `allowlisted`             |
-| `blacklist` / `blacklisted`      | `denylist` / `denied` / `blocklisted` / `blocked`   |
-| `master` (branch, process, copy) | `main` (branch); `primary` / `controller` (process) |
-| `slave`                          | `replica`, `worker`, `secondary`, `follower`        |
-| `grandfathered`                  | `legacy`, `pre-existing`, `exempted`                |
-| `sanity check`                   | `quick check`, `confidence check`, `smoke test`     |
-| `dummy` (placeholder)            | `placeholder`, `stub`                               |
+### Tooling
 
-Apply across **code** (identifiers, comments, string literals), **docs** (READMEs, CLAUDE.md, markdown), **config files** (YAML, JSON), **commit messages**, **PR titles/descriptions**, and **CI logs** you control.
+- **Package manager**: `pnpm`. Run scripts via `pnpm run foo --flag`, never `foo:bar`. After `package.json` edits, `pnpm install`.
+- 🚨 NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use `pnpm exec <package>` or `pnpm run <script>` # zizmor: documentation-prohibition
+- **`minimumReleaseAge`** — never add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding (security control).
+- **Backward compatibility** — FORBIDDEN to maintain. Actively remove when encountered.
 
-Two exceptions where the legacy term must remain (because changing it breaks something external):
+### Code style
 
-- **Third-party APIs / upstream code**: when interfacing with an external API field literally named `whitelist`, keep the field name; rename your local variable. E.g. `const allowedDomains = response.whitelist`.
-- **Vendored upstream sources**: don't rewrite vendored code (`vendor/**`, `upstream/**`, `**/fixtures/**`). Patch around it if needed.
+- **Comments** — default to none. Write one only when the WHY is non-obvious to a senior engineer.
+- **Completion** — never leave `TODO` / `FIXME` / `XXX` / shims / stubs / placeholders. Finish 100%. If too large for one pass, ask before cutting scope.
+- **`null` vs `undefined`** — use `undefined`. `null` is allowed only for `__proto__: null` or external API requirements.
+- **Object literals** — `{ __proto__: null, ... }` for config / return / internal-state.
+- **Imports** — no dynamic `await import()`. `node:fs` cherry-picks (`existsSync`, `promises as fs`); `path` / `os` / `url` / `crypto` use default imports. Exception: `fileURLToPath` from `node:url`.
+- **HTTP** — never `fetch()`. Use `httpJson` / `httpText` / `httpRequest` from `@socketsecurity/lib/http-request`.
+- **File existence** — `existsSync` from `node:fs`. Never `fs.access` / `fs.stat`-for-existence / async `fileExists` wrapper.
+- **File deletion** — route every delete through `safeDelete()` / `safeDeleteSync()` from `@socketsecurity/lib/fs`. Never `fs.rm` / `fs.unlink` / `fs.rmdir` / `rm -rf` directly — even for one known file.
+- **Edits** — Edit tool, never `sed` / `awk`.
+- **Inclusive language** — see [`docs/references/inclusive-language.md`](docs/references/inclusive-language.md) for the substitution table.
+- **Sorting** — sort lists alphanumerically; details in [`docs/references/sorting.md`](docs/references/sorting.md). When in doubt, sort.
+- **`Promise.race` / `Promise.any` in loops** — never re-race a pool that survives across iterations (the handlers stack). See `.claude/skills/promise-race-pitfall/SKILL.md`.
 
-When you encounter a legacy term during unrelated work, fix it inline — don't defer.
+### 1 path, 1 reference
 
-### Promise.race in loops
+A path is constructed exactly once. Everywhere else references the constructed value.
 
-**NEVER re-race the same pool of promises across loop iterations.** Each call to `Promise.race([A, B, ...])` attaches fresh `.then` handlers to every arm; a promise that survives N iterations accumulates N handler sets. See [nodejs/node#17469](https://github.com/nodejs/node/issues/17469) and `@watchable/unpromise`.
+- **Within a package**: every script imports its own `scripts/paths.mts`. No `path.join('build', mode, …)` outside that module.
+- **Across packages**: package B imports package A's `paths.mts` via the workspace `exports` field. Never `path.join(PKG, '..', '<sibling>', 'build', …)`.
+- **Workflows / Dockerfiles / shell** can't `import` TS — construct once, reference by output / `ENV` / variable.
 
-- **Safe**: `Promise.race([fresh1, fresh2])` where both arms are created per call (e.g. one-shot `withTimeout` wrappers).
-- **Leaky**: `Promise.race(pool)` inside a loop where `pool` persists across iterations (the classic concurrency-limiter bug) — also applies to `Promise.any` and long-lived arms like interrupt signals.
-- **Fix**: single-waiter "slot available" signal — each task's `.then` resolves a one-shot `promiseWithResolvers` that the loop awaits, then replaces. No persistent pool, nothing to stack.
+Three-level enforcement: `.claude/hooks/path-guard/` blocks at edit time; `scripts/check-paths.mts` is the whole-repo gate run by `pnpm check`; `/path-guard` is the audit-and-fix skill. Find the canonical owner and import from it.
 
 ### Background Bash
 
-Never use `Bash(run_in_background: true)` for test/build commands (`vitest`, `pnpm test`, `pnpm build`, `tsgo`). Backgrounded runs you don't poll get abandoned and leak Node workers. Background mode is for dev servers and long migrations whose results you'll consume. If a run hangs, kill it: `pkill -f "vitest/dist/workers"`.
+Never use `Bash(run_in_background: true)` for test / build commands (`vitest`, `pnpm test`, `pnpm build`, `tsgo`). Backgrounded runs you don't poll get abandoned and leak Node workers. Background mode is for dev servers and long migrations whose results you'll consume. If a run hangs, kill it: `pkill -f "vitest/dist/workers"`. The `.claude/hooks/stale-process-sweeper/` `Stop` hook reaps true orphans as a safety net.
 
----
+### Judgment & self-evaluation
 
-## EMOJI & OUTPUT STYLE
+- If the request is based on a misconception, say so before executing.
+- If you spot an adjacent bug, flag it: "I also noticed X — want me to fix it?"
+- Fix warnings (lint / type / build / runtime) when you see them — don't leave them for later.
+- **Default to perfectionist** when you have latitude. "Works now" ≠ "right."
+- Before calling done: perfectionist vs. pragmatist views. Default perfectionist absent a signal.
+- If a fix fails twice: stop, re-read top-down, state where the mental model was wrong, try something fundamentally different.
 
-**Terminal symbols** (from `@socketsecurity/lib/logger` LOG_SYMBOLS): ✓ (green), ✗ (red), ⚠ (yellow), ℹ (blue), → (cyan). Use logger methods, never manually apply colors.
+### Error messages
 
-```javascript
-import { getDefaultLogger } from '@socketsecurity/lib/logger'
-const logger = getDefaultLogger()
+An error message is UI. The reader should fix the problem from the message alone. Four ingredients in order:
 
-logger.success(msg) // Green ✓
-logger.fail(msg) // Red ✗
-logger.warn(msg) // Yellow ⚠
-logger.info(msg) // Blue ℹ
-logger.step(msg) // Cyan →
-```
-
-Emojis allowed sparingly: 📦 💡 🚀 🎉. Prefer text-based symbols for terminal compatibility.
-
----
+1. **What** — the rule, not the fallout (`must be lowercase`, not `invalid`).
+2. **Where** — exact file / line / key / field / flag.
+3. **Saw vs. wanted** — the bad value and the allowed shape or set.
+4. **Fix** — one imperative action (`rename the key to …`).
 
-### 1 path, 1 reference
+Use `isError` / `isErrnoException` / `errorMessage` / `errorStack` from `@socketsecurity/lib/errors` over hand-rolled checks. Use `joinAnd` / `joinOr` from `@socketsecurity/lib/arrays` for allowed-set lists. Full guidance in [`docs/references/error-messages.md`](docs/references/error-messages.md).
 
-**A path is _constructed_ exactly once. Everywhere else _references_ the constructed value.**
+### Token hygiene
 
-Referencing a single computed path many times is fine — that's the whole point of computing it once. What's banned is _re-constructing_ the same path in multiple places, because that's where drift is born.
+🚨 Never emit the raw value of any secret to tool output, commits, comments, or replies. The `.claude/hooks/token-guard/` `PreToolUse` hook blocks the deterministic patterns (literal token shapes, env dumps, `.env*` reads, unfiltered `curl -H "Authorization:"`, sensitive-name commands without redaction). When the hook blocks a command, rewrite — don't bypass.
 
-- **Within a package**: every script imports its own `scripts/paths.mts` (or `lib/paths.mts`). No `path.join('build', mode, ...)` outside that module.
-- **Across packages**: when package B consumes package A's output, B imports A's `paths.mts` via the workspace `exports` field. Never `path.join(PKG, '..', '<sibling>', 'build', ...)`.
-- **Workflows, Dockerfiles, shell scripts**: they can't `import` TS, so they construct the string once and reference it everywhere downstream. Workflows: a "Compute paths" step exposes `steps.paths.outputs.final_dir`; later steps read `${{ steps.paths.outputs.final_dir }}`. Dockerfiles/shell: assign once to a variable / `ENV`, reference by name thereafter. Each canonical construction carries a comment naming the source-of-truth `paths.mts`. **Re-building** the same path in a second step is the violation, not referring to the constructed value many times.
-- **Comments**: may describe path _structure_ with placeholders ("`<mode>/<arch>`") but should not encode a complete literal path string. The import statement IS the comment.
+Behavior the hook can't catch: redact `token` / `jwt` / `access_token` / `refresh_token` / `api_key` / `secret` / `password` / `authorization` fields when citing API responses. Show key *names* only when displaying `.env.local`. If a user pastes a secret, treat it as compromised and ask them to rotate.
 
-Code execution takes priority over docs: violations in `.mts`/`.cts`, Makefiles, Dockerfiles, workflow YAML, and shell scripts are blocking. README and doc-comment violations are advisory unless they contain a fully-qualified path with no parametric placeholders.
+Full hook spec in [`.claude/hooks/token-guard/README.md`](.claude/hooks/token-guard/README.md).
 
-**Three-level enforcement:**
+### Agents & skills
 
-- **Hook** — `.claude/hooks/path-guard/` blocks `Edit`/`Write` calls that would introduce a violation in a `.mts`/`.cts` file at edit time.
-- **Gate** — `scripts/check-paths.mts` runs in `pnpm check`. Fails the build on any violation that isn't allowlisted in `.github/paths-allowlist.yml`.
-- **Skill** — `/path-guard` audits the repo and fixes findings; `/path-guard check` reports only; `/path-guard install` drops the gate + hook + rule into a fresh repo.
+- `/security-scan` — AgentShield + zizmor audit
+- `/quality-scan` — quality analysis
+- Shared subskills in `.claude/skills/_shared/`
 
-The mantra is intentionally short so it sticks: **1 path, 1 reference**. When in doubt, find the canonical owner and import from it.
+<!-- END FLEET-CANONICAL -->
 
-## 🏗️ SDK-SPECIFIC
+## 🏗️ SDK-Specific
 
 ### Architecture
 
@@ -174,30 +151,6 @@ Features: TypeScript support, API client, package analysis, security scanning, o
 - **Check all**: `pnpm check`
 - **Coverage**: `pnpm run cover`
 
-## ERROR MESSAGES
-
-An error message is UI. The reader should be able to fix the problem from the message alone, without opening your source. Every message needs four ingredients, in order:
-
-1. **What** — the rule that was broken, not the fallout (`must be non-empty`, not `invalid`).
-2. **Where** — exact method, argument, field, or URL.
-3. **Saw vs. wanted** — the bad value and the allowed shape or set.
-4. **Fix** — one concrete action, imperative voice (`pass an org slug`, not `the org slug was missing`).
-
-SDK errors are **terse** — callers may `catch` and match on message text, so every word counts. One sentence covering all four is the norm: `throw new Error('orgSlug is required')`.
-
-Prefer the caught-value helpers from `@socketsecurity/lib/errors` (`isError`, `isErrnoException`, `errorMessage`, `errorStack`) over hand-rolled `instanceof Error` / `'code' in e` checks. For allowed-set / conflict lists, use `joinAnd` / `joinOr` from `@socketsecurity/lib/arrays`.
-
-See `docs/references/error-messages.md` for length tiers (validator / programmatic), the full rule list, worked examples, anti-patterns, and helper signatures.
-
-## Agents & Skills
-
-- `/security-scan` — AgentShield + zizmor security audit
-- `/quality-scan` — comprehensive code quality analysis
-- `/quality-loop` — scan and fix iteratively
-- Agents: `code-reviewer`, `security-reviewer`, `refactor-cleaner` (in `.claude/agents/`)
-- Shared subskills in `.claude/skills/_shared/`
-- Pipeline state tracked in `.claude/ops/queue.yaml`
-
 ### Configuration Files
 
 Configs live in `.config/`:
@@ -300,56 +253,12 @@ Also available: `setupTestEnvironment()` (nock only), `createTestClient()` (clie
 - Custom runner: `scripts/test.mts` with glob expansion
 - Memory: auto heap (CI 8GB, local 4GB)
 
-### Changelog Management
-
-🚨 MANDATORY for version bumps:
-
-- Check OpenAPI updates: `git diff v{prev}..HEAD -- types/`
-- Document user-facing changes: new endpoints, parameter changes, new enum values, breaking contracts
-- Focus on user impact, not internal infrastructure
-
 ### Debugging
 
 - CI uses published npm packages, not local
 - Package detection: use `existsSync()` not `fs.access()`
 - Test failures: check unused nock mocks and cleanup
 
-### Judgment Protocol
-
-- If the user's request is based on a misconception, say so before executing
-- If you spot a bug adjacent to what was asked, flag it: "I also noticed X — want me to fix it?"
-- You are a collaborator, not just an executor
-- When a warning (lint, type-check, build, runtime) surfaces in code you're already editing, fix it in the same change — don't leave it for later. For warnings in unrelated files, flag them instead of drive-by fixing.
-- **Default to perfectionist mindset**: when you have latitude to choose, pick the maximally correct option — no shortcuts, no cosmetic deferrals. Fix state that _looks_ stale even if not load-bearing. If pragmatism is the right call, the user will ask for it explicitly. "Works now" ≠ "right."
-
-### Self-Evaluation
-
-- Before calling done: present two views — perfectionist reject vs. pragmatist ship — and let the user decide. If the user gives no signal, default to perfectionist: do the fuller fix.
-- If a fix fails twice: stop, re-read top-down, state where the mental model was wrong, try something fundamentally different
-
-### Completion Protocol
-
-- **NEVER claim done at 80%** — finish 100% before reporting
-- Fix forward, don't revert; reverting requires explicit user approval
-- After EVERY code change: build, test, verify, commit — one atomic unit
-
-### File System as State
-
-Use `.claude/` (gitignored) for plans, intermediate analysis, logs, and cross-session context. Don't hold large analysis in context.
-
-### Self-Improvement
-
-- After ANY user correction: log the pattern so the mistake isn't repeated
-- Convert mistakes into strict rules
-- After fixing a bug: explain why it happened and what category it represents
-
-### Context & Edit Safety
-
-- After 10+ messages: re-read files before editing
-- Before/after every edit: re-read to confirm
-- Tool results over 50K chars are silently truncated — narrow scope and re-run if sparse
-- Tasks touching >5 files: use sub-agents with worktree isolation
-
 ### SDK Notes
 
 - Windows compatibility matters — test path handling
diff --git a/docs/references/inclusive-language.md b/docs/references/inclusive-language.md
new file mode 100644
index 00000000..0489c7f0
--- /dev/null
+++ b/docs/references/inclusive-language.md
@@ -0,0 +1,34 @@
+# Inclusive language reference
+
+The fleet uses precise, neutral terms over historical metaphors that imply hierarchy or exclusion. The substitutes are not euphemisms — they're more *accurate* (a list of allowed values genuinely is an "allowlist"; "whitelist" is a metaphor that hides what the list does).
+
+## Substitution table
+
+| Replace                                  | With                                                  |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `whitelist` / `whitelisted`              | `allowlist` / `allowed` / `allowlisted`               |
+| `blacklist` / `blacklisted`              | `denylist` / `denied` / `blocklisted` / `blocked`     |
+| `master` (branch, process, copy)         | `main` (branch); `primary` / `controller` (process)   |
+| `slave`                                  | `replica`, `worker`, `secondary`, `follower`          |
+| `grandfathered`                          | `legacy`, `pre-existing`, `exempted`                  |
+| `sanity check`                           | `quick check`, `confidence check`, `smoke test`       |
+| `dummy` (placeholder)                    | `placeholder`, `stub`                                 |
+
+## Where to apply
+
+- **Code**: identifiers, comments, string literals.
+- **Docs**: READMEs, CLAUDE.md, markdown.
+- **Config**: YAML, JSON.
+- **History**: commit messages, PR titles/descriptions.
+- **CI logs** you control.
+
+## Two narrow exceptions
+
+The legacy term must remain only when changing it would break something external:
+
+- **Third-party APIs / upstream code**: when interfacing with an external API field literally named `whitelist`, keep the field name; rename your local variable. Example: `const allowedDomains = response.whitelist`.
+- **Vendored upstream sources**: don't rewrite vendored code under `vendor/**`, `upstream/**`, or `**/fixtures/**`. Patch around it if needed.
+
+## When to fix
+
+When you encounter a legacy term during unrelated work, fix it inline — don't defer.
diff --git a/docs/references/sorting.md b/docs/references/sorting.md
new file mode 100644
index 00000000..b0e61801
--- /dev/null
+++ b/docs/references/sorting.md
@@ -0,0 +1,16 @@
+# Sorting reference
+
+Sort lists alphanumerically (literal byte order, ASCII before letters).
+
+## Where to sort
+
+- **Config lists** — `permissions.allow` / `permissions.deny` in `.claude/settings.json`, `external-tools.json` checksum keys, allowlists in workflow YAML.
+- **Object key entries** — keys in plain JSON config + return-shape literals + internal-state objects. (Exception: `__proto__: null` always comes first, ahead of any data keys.)
+- **Import specifiers** — sort named imports inside a single statement: `import { encrypt, randomDataKey, wrapKey } from './crypto.mts'`. `import type` follows the same rule. Statement *order* (`node:` → external → local → types) is separate from specifier order *within* a statement.
+- **Method / function placement** — within a module, sort top-level functions alphabetically. Convention: private functions (lowercase / un-exported) sort first, exported functions second. The `export` keyword is the divider.
+- **Array literals** — when the array is a config list, allowlist, or set-like collection. Position-bearing arrays (e.g. `argv`, anything where index matters semantically) keep their meaningful order.
+- **`Set` constructor arguments** — `new Set([...])` and `new SafeSet([...])` literals. The runtime is order-insensitive, so source order is alphanumeric. Same rationale as Array literals: predictable diffs, no merge conflicts on insertions.
+
+## Default
+
+When in doubt, sort. The cost of a sorted list that didn't need to be is approximately zero; the cost of an unsorted list that did need to be is a merge conflict.

From 6841175736fdcd29f229b0b8b663f3a5c0f2c325 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 30 Apr 2026 11:37:50 -0400
Subject: [PATCH 07/17] chore(oxfmt): enable JSDoc formatting

oxfmt 0.37+ formats JSDoc comments. Adopt the canonical `jsdoc` block
from socket-repo-template; it preserves the existing JSDoc style across
this repo (verified: zero diff under the new config).

Source of truth: socket-repo-template/template/.oxfmtrc.json. Future
updates flow through `scripts/sync-scaffolding.mjs --all --fix`.
---
 .oxfmtrc.json | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 9e6a8034..05832ea0 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -12,6 +12,19 @@
   "bracketSameLine": false,
   "bracketSpacing": true,
   "singleAttributePerLine": false,
+  "jsdoc": {
+    "addDefaultToDescription": false,
+    "bracketSpacing": false,
+    "capitalizeDescriptions": true,
+    "commentLineStrategy": "multiline",
+    "descriptionTag": false,
+    "descriptionWithDot": true,
+    "keepUnparsableExampleIndent": false,
+    "lineWrappingStyle": "greedy",
+    "preferCodeFences": false,
+    "separateReturnsFromParam": false,
+    "separateTagGroups": true
+  },
   "ignorePatterns": [
     "**/openapi.json",
     "**/.cache",

From d06f0a82d92b939250851d92dbd7f8d3569a966a Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 30 Apr 2026 12:51:23 -0400
Subject: [PATCH 08/17] chore(claude+hooks): sync fleet-canonical updates from
 socket-repo-template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `.git-hooks/_helpers.mts` + `pre-commit.mts` + `pre-push.mts` —
  rename suppression marker `# zizmor: …` → `# socket-hook: allow [<rule>]`
  (legacy form still recognized for one cycle); add doc-aware scan
  heuristic; emit `LineHit.suggested` rewrites alongside hits.
- `CLAUDE.md` — update fleet block npx-rule marker; oxfmt-normalized
  markdown emphasis.
- `docs/references/{inclusive-language,sorting}.md` — re-sync.
- `.claude/skills/path-guard/SKILL.md`, `.claude/agents/security-reviewer.md`
  — sync drift from template.
- `pnpm-lock.yaml` — regenerate after template sync.

Verified: `pnpm run check --all` clean; `pnpm test --all` 565/565 pass.
---
 .claude/agents/security-reviewer.md   |   2 +-
 .claude/skills/path-guard/SKILL.md    |   2 +-
 .git-hooks/_helpers.mts               | 154 ++++++++++++++++++++++++--
 .git-hooks/pre-commit.mts             |  34 +++++-
 .git-hooks/pre-push.mts               |  13 ++-
 CLAUDE.md                             |   4 +-
 docs/references/inclusive-language.md |  20 ++--
 docs/references/sorting.md            |   2 +-
 pnpm-lock.yaml                        |   2 +
 9 files changed, 204 insertions(+), 29 deletions(-)
 mode change 100644 => 100755 .git-hooks/_helpers.mts
 mode change 100644 => 100755 .git-hooks/pre-commit.mts
 mode change 100644 => 100755 .git-hooks/pre-push.mts

diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md
index 1d35eabd..97f399e9 100644
--- a/.claude/agents/security-reviewer.md
+++ b/.claude/agents/security-reviewer.md
@@ -1,6 +1,6 @@
 ---
 name: security-reviewer
-description: Reviews findings from AgentShield + zizmor against socket-sdk-js's CLAUDE.md security rules and grades the result A-F. Spawned by the security-scan skill after the static scans run.
+description: Reviews findings from AgentShield + zizmor against the project's CLAUDE.md security rules and grades the result A-F. Spawned by the security-scan skill after the static scans run.
 tools: Read, Grep, Glob, Bash(git:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Bash(ls:*), Bash(pnpm exec agentshield:*), Bash(zizmor:*), Bash(command -v:*), Bash(cat:*), Bash(head:*), Bash(tail:*)
 ---
 
diff --git a/.claude/skills/path-guard/SKILL.md b/.claude/skills/path-guard/SKILL.md
index 747ad02b..8ff21c2b 100644
--- a/.claude/skills/path-guard/SKILL.md
+++ b/.claude/skills/path-guard/SKILL.md
@@ -2,7 +2,7 @@
 name: path-guard
 description: Audit and fix path duplication in this Socket repo. Apply the strict "1 path, 1 reference" rule — every build/test/runtime/config path is constructed exactly once; everywhere else references the constructed value. Default mode finds and fixes; `check` mode reports only; `install` mode drops the gate + hook + rule into a fresh repo.
 user-invocable: true
-allowed-tools: Task, Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion
+allowed-tools: Task, Read, Edit, Write, Grep, Glob, AskUserQuestion, Bash(pnpm run check:*), Bash(node scripts/check-paths:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Bash(git:*)
 ---
 
 # path-guard
diff --git a/.git-hooks/_helpers.mts b/.git-hooks/_helpers.mts
old mode 100644
new mode 100755
index b8a29978..35a647a4
--- a/.git-hooks/_helpers.mts
+++ b/.git-hooks/_helpers.mts
@@ -96,10 +96,123 @@ const PERSONAL_PATH_RE =
 const PERSONAL_PATH_PLACEHOLDER_RE =
   /(\/Users\/<[^>]*>\/|\/home\/<[^>]*>\/|C:\\Users\\<[^>]*>\\|\/Users\/\$\{?[A-Z_]+\}?\/|\/home\/\$\{?[A-Z_]+\}?\/)/
 
-export type LineHit = { lineNumber: number; line: string }
+// Per-line opt-out marker for our pre-commit / pre-push scanners.
+//
+// Canonical form:    # socket-hook: allow
+// Targeted form:     # socket-hook: allow <rule>
+//
+// The targeted form names a specific rule (`personal-path`, `npx`,
+// `aws-key`, etc.) and is recommended for reviewers; the bare `allow`
+// form blanket-suppresses every scanner on that line. eslint-style
+// precedent.
+//
+// Legacy `# zizmor: ...` markers are still recognized for one cycle so
+// existing files don't have to be rewritten in the same change that
+// renames the marker.
+const SOCKET_HOOK_MARKER_RE = /#\s*socket-hook:\s*allow(?:\s+([\w-]+))?/
+const LEGACY_ZIZMOR_MARKER_RE = /#\s*zizmor:\s*[\w-]+/
+
+function lineIsSuppressed(line: string, rule?: string): boolean {
+  if (LEGACY_ZIZMOR_MARKER_RE.test(line)) {
+    return true
+  }
+  const m = line.match(SOCKET_HOOK_MARKER_RE)
+  if (!m) {
+    return false
+  }
+  // No rule named on the marker → blanket allow.
+  if (!m[1]) {
+    return true
+  }
+  // Marker named a specific rule → only suppress that rule.
+  return rule === undefined || m[1] === rule
+}
 
-// Returns lines that contain a real personal path (excludes lines
-// that are pure placeholders). Caller decides what to do with hits.
+// Heuristic context flags: lines that look like "this is a doc example"
+// rather than a real call leaked into runtime code.
+//   - Comment lines (start with `*`, `//`, `#`).
+//   - Lines that contain a JSDoc tag like @example / @param / @returns
+//     (multi-line JSDoc bodies use leading ` * ` which we already match).
+//   - Lines whose entire interesting content sits inside a backtick span
+//     (markdown / template-literal example).
+const COMMENT_LINE_RE = /^\s*(\*|\/\/|#)/
+const JSDOC_TAG_RE = /@(example|param|returns?|see|link)\b/
+
+function isInsideBackticks(line: string, needleRe: RegExp): boolean {
+  // Find every backtick-delimited span on the line and test if the
+  // pattern only appears within those spans. Conservative: if any
+  // hit is *outside* a span, treat the line as runtime code.
+  const spans: Array<[number, number]> = []
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '`') {
+      const end = line.indexOf('`', i + 1)
+      if (end < 0) {
+        break
+      }
+      spans.push([i, end])
+      i = end
+    }
+  }
+  if (spans.length === 0) {
+    return false
+  }
+  let m: RegExpExecArray | null
+  const re = new RegExp(needleRe.source, needleRe.flags.replace('g', '') + 'g')
+  while ((m = re.exec(line)) !== null) {
+    const start = m.index
+    const end = start + m[0].length
+    const inside = spans.some(([s, e]) => start > s && end <= e)
+    if (!inside) {
+      return false
+    }
+  }
+  return true
+}
+
+function looksLikeDocumentation(
+  line: string,
+  needleRe: RegExp,
+  rule?: string,
+): boolean {
+  if (lineIsSuppressed(line, rule)) {
+    return true
+  }
+  if (COMMENT_LINE_RE.test(line)) {
+    return true
+  }
+  if (JSDOC_TAG_RE.test(line)) {
+    return true
+  }
+  if (isInsideBackticks(line, needleRe)) {
+    return true
+  }
+  return false
+}
+
+export type LineHit = {
+  lineNumber: number
+  line: string
+  // Suggested rewrite when this flagged line is documentation-style and
+  // the scanner can offer a concrete fix. Undefined for runtime-code
+  // paths where the right answer depends on the surrounding code.
+  suggested?: string
+}
+
+// Build a suggested rewrite for a documentation-style personal path.
+// Replaces the matched real-path username segment with the canonical
+// placeholder form: `<user>` / `<USERNAME>` (matching the platform
+// convention of the surrounding path).
+function suggestPlaceholder(line: string): string {
+  return line
+    .replace(/\/Users\/[^/\s]+\//g, '/Users/<user>/')
+    .replace(/\/home\/[^/\s]+\//g, '/home/<user>/')
+    .replace(/C:\\Users\\[^\\]+\\/g, 'C:\\Users\\<USERNAME>\\')
+}
+
+// Returns lines that contain a real personal path (excludes lines that
+// are pure placeholders or look like documentation examples). Each hit
+// carries a `suggested` rewrite when the scanner can offer one — the
+// caller surfaces it to the user as the fix recipe.
 export const scanPersonalPaths = (text: string): LineHit[] => {
   const hits: LineHit[] = []
   const lines = text.split('\n')
@@ -109,8 +222,6 @@ export const scanPersonalPaths = (text: string): LineHit[] => {
       continue
     }
     if (PERSONAL_PATH_PLACEHOLDER_RE.test(line)) {
-      // Has placeholder — but might also have a real path on the
-      // same line. Strip placeholder forms and re-test.
       const stripped = line.replace(
         new RegExp(PERSONAL_PATH_PLACEHOLDER_RE, 'g'),
         '',
@@ -119,7 +230,14 @@ export const scanPersonalPaths = (text: string): LineHit[] => {
         continue
       }
     }
-    hits.push({ lineNumber: i + 1, line })
+    if (looksLikeDocumentation(line, PERSONAL_PATH_RE, 'personal-path')) {
+      continue
+    }
+    hits.push({
+      lineNumber: i + 1,
+      line,
+      suggested: suggestPlaceholder(line),
+    })
   }
   return hits
 }
@@ -186,14 +304,34 @@ export const scanPrivateKeys = (text: string): LineHit[] => {
 
 const NPX_DLX_RE = /\b(npx|pnpm dlx|yarn dlx)\b/
 
+// Suggest the canonical replacement for a runtime npx/dlx call.
+// Documentation contexts (comments, JSDoc) are exempt via
+// looksLikeDocumentation(); we only ever land here for code lines, where
+// the right swap is `pnpm exec` (since `pnpm` is the fleet's package
+// manager) or `pnpm run` for script entries.
+function suggestNpxReplacement(line: string): string {
+  return line
+    .replace(/\bpnpm dlx\b/g, 'pnpm exec')
+    .replace(/\byarn dlx\b/g, 'pnpm exec')
+    .replace(/\bnpx\b/g, 'pnpm exec')
+}
+
 export const scanNpxDlx = (text: string): LineHit[] => {
   const hits: LineHit[] = []
   const lines = text.split('\n')
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!
-    if (NPX_DLX_RE.test(line) && !line.includes('# zizmor:')) {
-      hits.push({ lineNumber: i + 1, line })
+    if (!NPX_DLX_RE.test(line)) {
+      continue
+    }
+    if (looksLikeDocumentation(line, NPX_DLX_RE, 'npx')) {
+      continue
     }
+    hits.push({
+      lineNumber: i + 1,
+      line,
+      suggested: suggestNpxReplacement(line),
+    })
   }
   return hits
 }
diff --git a/.git-hooks/pre-commit.mts b/.git-hooks/pre-commit.mts
old mode 100644
new mode 100755
index 61df1057..c42bfef0
--- a/.git-hooks/pre-commit.mts
+++ b/.git-hooks/pre-commit.mts
@@ -97,8 +97,18 @@ const main = (): number => {
     const hits = scanPersonalPaths(text)
     if (hits.length > 0) {
       out(red(`✗ ERROR: Hardcoded personal path found in: ${file}`))
-      hits.slice(0, 3).forEach(h => out(`${h.lineNumber}:${h.line.trim()}`))
-      out('Replace with relative paths or environment variables.')
+      for (const h of hits.slice(0, 3)) {
+        out(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          out(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      out(
+        'Replace with `<user>` / `<USERNAME>` placeholders, an env var ' +
+          '(`$HOME`, `${USER}`), or — for documentation lines that need ' +
+          'the literal username form — append the marker ' +
+          '`# zizmor: documentation-placeholder`.',
+      )
       errors++
     }
   }
@@ -159,7 +169,12 @@ const main = (): number => {
     if (
       file.includes('node_modules/') ||
       file.endsWith('pnpm-lock.yaml') ||
-      file.includes('.git-hooks/')
+      file.includes('.git-hooks/') ||
+      // CHANGELOG entries discuss npx ecosystem *behavior* (cache
+      // semantics, naming conventions) as historical documentation —
+      // they're not commands. Skip the npx/dlx scan for changelogs.
+      file === 'CHANGELOG.md' ||
+      file.endsWith('/CHANGELOG.md')
     ) {
       continue
     }
@@ -170,8 +185,17 @@ const main = (): number => {
     const hits = scanNpxDlx(text)
     if (hits.length > 0) {
       out(red(`✗ ERROR: npx/dlx usage found in: ${file}`))
-      hits.slice(0, 3).forEach(h => out(`${h.lineNumber}:${h.line.trim()}`))
-      out("Use 'pnpm exec <package>' or 'pnpm run <script>' instead.")
+      for (const h of hits.slice(0, 3)) {
+        out(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          out(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      out(
+        "Use 'pnpm exec <package>' or 'pnpm run <script>' instead. For " +
+          'documentation lines that need the literal `npx` form, append ' +
+          'the marker `# zizmor: documentation-prohibition`.',
+      )
       errors++
     }
   }
diff --git a/.git-hooks/pre-push.mts b/.git-hooks/pre-push.mts
old mode 100644
new mode 100755
index cc218a0d..0a9be2e3
--- a/.git-hooks/pre-push.mts
+++ b/.git-hooks/pre-push.mts
@@ -251,7 +251,18 @@ const scanFilesInRange = (range: string): number => {
     const pathHits = scanPersonalPaths(text)
     if (pathHits.length > 0) {
       out(red(`✗ BLOCKED: Hardcoded personal path found in: ${file}`))
-      pathHits.slice(0, 3).forEach(h => out(`${h.lineNumber}:${h.line.trim()}`))
+      for (const h of pathHits.slice(0, 3)) {
+        out(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          out(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      out(
+        'Replace with `<user>` / `<USERNAME>` placeholders, an env var ' +
+          '(`$HOME`, `${USER}`), or — for documentation lines that need ' +
+          'the literal username form — append the marker ' +
+          '`# zizmor: documentation-placeholder`.',
+      )
       errors++
     }
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 33343c12..5312f464 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -58,7 +58,7 @@ The umbrella rule: never run a git command that mutates state belonging to a pat
 ### Tooling
 
 - **Package manager**: `pnpm`. Run scripts via `pnpm run foo --flag`, never `foo:bar`. After `package.json` edits, `pnpm install`.
-- 🚨 NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use `pnpm exec <package>` or `pnpm run <script>` # zizmor: documentation-prohibition
+- 🚨 NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use `pnpm exec <package>` or `pnpm run <script>` # socket-hook: allow npx
 - **`minimumReleaseAge`** — never add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding (security control).
 - **Backward compatibility** — FORBIDDEN to maintain. Actively remove when encountered.
 
@@ -115,7 +115,7 @@ Use `isError` / `isErrnoException` / `errorMessage` / `errorStack` from `@socket
 
 🚨 Never emit the raw value of any secret to tool output, commits, comments, or replies. The `.claude/hooks/token-guard/` `PreToolUse` hook blocks the deterministic patterns (literal token shapes, env dumps, `.env*` reads, unfiltered `curl -H "Authorization:"`, sensitive-name commands without redaction). When the hook blocks a command, rewrite — don't bypass.
 
-Behavior the hook can't catch: redact `token` / `jwt` / `access_token` / `refresh_token` / `api_key` / `secret` / `password` / `authorization` fields when citing API responses. Show key *names* only when displaying `.env.local`. If a user pastes a secret, treat it as compromised and ask them to rotate.
+Behavior the hook can't catch: redact `token` / `jwt` / `access_token` / `refresh_token` / `api_key` / `secret` / `password` / `authorization` fields when citing API responses. Show key _names_ only when displaying `.env.local`. If a user pastes a secret, treat it as compromised and ask them to rotate.
 
 Full hook spec in [`.claude/hooks/token-guard/README.md`](.claude/hooks/token-guard/README.md).
 
diff --git a/docs/references/inclusive-language.md b/docs/references/inclusive-language.md
index 0489c7f0..b34fb85d 100644
--- a/docs/references/inclusive-language.md
+++ b/docs/references/inclusive-language.md
@@ -1,18 +1,18 @@
 # Inclusive language reference
 
-The fleet uses precise, neutral terms over historical metaphors that imply hierarchy or exclusion. The substitutes are not euphemisms — they're more *accurate* (a list of allowed values genuinely is an "allowlist"; "whitelist" is a metaphor that hides what the list does).
+The fleet uses precise, neutral terms over historical metaphors that imply hierarchy or exclusion. The substitutes are not euphemisms — they're more _accurate_ (a list of allowed values genuinely is an "allowlist"; "whitelist" is a metaphor that hides what the list does).
 
 ## Substitution table
 
-| Replace                                  | With                                                  |
-| ---------------------------------------- | ----------------------------------------------------- |
-| `whitelist` / `whitelisted`              | `allowlist` / `allowed` / `allowlisted`               |
-| `blacklist` / `blacklisted`              | `denylist` / `denied` / `blocklisted` / `blocked`     |
-| `master` (branch, process, copy)         | `main` (branch); `primary` / `controller` (process)   |
-| `slave`                                  | `replica`, `worker`, `secondary`, `follower`          |
-| `grandfathered`                          | `legacy`, `pre-existing`, `exempted`                  |
-| `sanity check`                           | `quick check`, `confidence check`, `smoke test`       |
-| `dummy` (placeholder)                    | `placeholder`, `stub`                                 |
+| Replace                          | With                                                |
+| -------------------------------- | --------------------------------------------------- |
+| `whitelist` / `whitelisted`      | `allowlist` / `allowed` / `allowlisted`             |
+| `blacklist` / `blacklisted`      | `denylist` / `denied` / `blocklisted` / `blocked`   |
+| `master` (branch, process, copy) | `main` (branch); `primary` / `controller` (process) |
+| `slave`                          | `replica`, `worker`, `secondary`, `follower`        |
+| `grandfathered`                  | `legacy`, `pre-existing`, `exempted`                |
+| `sanity check`                   | `quick check`, `confidence check`, `smoke test`     |
+| `dummy` (placeholder)            | `placeholder`, `stub`                               |
 
 ## Where to apply
 
diff --git a/docs/references/sorting.md b/docs/references/sorting.md
index b0e61801..f452f0a6 100644
--- a/docs/references/sorting.md
+++ b/docs/references/sorting.md
@@ -6,7 +6,7 @@ Sort lists alphanumerically (literal byte order, ASCII before letters).
 
 - **Config lists** — `permissions.allow` / `permissions.deny` in `.claude/settings.json`, `external-tools.json` checksum keys, allowlists in workflow YAML.
 - **Object key entries** — keys in plain JSON config + return-shape literals + internal-state objects. (Exception: `__proto__: null` always comes first, ahead of any data keys.)
-- **Import specifiers** — sort named imports inside a single statement: `import { encrypt, randomDataKey, wrapKey } from './crypto.mts'`. `import type` follows the same rule. Statement *order* (`node:` → external → local → types) is separate from specifier order *within* a statement.
+- **Import specifiers** — sort named imports inside a single statement: `import { encrypt, randomDataKey, wrapKey } from './crypto.mts'`. `import type` follows the same rule. Statement _order_ (`node:` → external → local → types) is separate from specifier order _within_ a statement.
 - **Method / function placement** — within a module, sort top-level functions alphabetically. Convention: private functions (lowercase / un-exported) sort first, exported functions second. The `export` keyword is the divider.
 - **Array literals** — when the array is a config list, allowlist, or set-like collection. Position-bearing arrays (e.g. `argv`, anything where index matters semantically) keep their meaningful order.
 - **`Set` constructor arguments** — `new Set([...])` and `new SafeSet([...])` literals. The runtime is order-insensitive, so source order is alphanumeric. Same rationale as Array literals: predictable diffs, no merge conflicts on insertions.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d33e9e50..66a01c32 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -190,6 +190,8 @@ importers:
         specifier: 24.9.2
         version: 24.9.2
 
+  .claude/hooks/stale-process-sweeper: {}
+
   .claude/hooks/token-guard: {}
 
 packages:

From 8a11559d74df48d40754e62b816d2621bf59ce18 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Thu, 30 Apr 2026 16:51:56 -0400
Subject: [PATCH 09/17] feat(.claude): add logger-guard +
 auth-rotation-reminder hooks

logger-guard (PreToolUse Edit|Write):
- Blocks direct stream writes (process.std{err,out}.write, console.*)
  in source files; suggests getDefaultLogger() rewrite per hit.
- Path-exempts hooks/, .git-hooks/, scripts/, tests, fixtures,
  external/ vendor/ upstream/.
- Honors `# socket-hook: allow [logger]` opt-out marker.

auth-rotation-reminder (Stop):
- Periodic auto-logout from npm/pnpm/yarn/gcloud/aws-sso/vault/docker/
  socket; gh stays logged-in by default.
- 1h throttle, ISO-8601 .claude/auth-rotation.snooze with auto-cleanup.
- Skip when CI or SOCKET_AUTH_ROTATION_DISABLED set.

pnpm-workspace.yaml: register catalog with @socketsecurity/lib +
@types/node so hook package.json deps resolve via `catalog:`.

Pre-commit/pre-push pick up scanLoggerLeaks for edits made outside
---
 .../hooks/auth-rotation-reminder/README.md    | 131 +++++++
 .../hooks/auth-rotation-reminder/index.mts    | 353 ++++++++++++++++++
 .../hooks/auth-rotation-reminder/package.json |  18 +
 .../hooks/auth-rotation-reminder/services.mts | 142 +++++++
 .../test/auth-rotation-reminder.test.mts      | 162 ++++++++
 .../auth-rotation-reminder/tsconfig.json      |  15 +
 .claude/hooks/logger-guard/README.md          |  54 +++
 .claude/hooks/logger-guard/index.mts          | 261 +++++++++++++
 .claude/hooks/logger-guard/package.json       |  15 +
 .../logger-guard/test/logger-guard.test.mts   | 171 +++++++++
 .claude/hooks/logger-guard/tsconfig.json      |  15 +
 .claude/settings.json                         |   8 +
 .git-hooks/_helpers.mts                       |  46 +++
 .git-hooks/pre-commit.mts                     |  52 ++-
 .git-hooks/pre-push.mts                       |  28 ++
 pnpm-lock.yaml                                |  25 ++
 pnpm-workspace.yaml                           |   7 +
 17 files changed, 1502 insertions(+), 1 deletion(-)
 create mode 100644 .claude/hooks/auth-rotation-reminder/README.md
 create mode 100644 .claude/hooks/auth-rotation-reminder/index.mts
 create mode 100644 .claude/hooks/auth-rotation-reminder/package.json
 create mode 100644 .claude/hooks/auth-rotation-reminder/services.mts
 create mode 100644 .claude/hooks/auth-rotation-reminder/test/auth-rotation-reminder.test.mts
 create mode 100644 .claude/hooks/auth-rotation-reminder/tsconfig.json
 create mode 100644 .claude/hooks/logger-guard/README.md
 create mode 100644 .claude/hooks/logger-guard/index.mts
 create mode 100644 .claude/hooks/logger-guard/package.json
 create mode 100644 .claude/hooks/logger-guard/test/logger-guard.test.mts
 create mode 100644 .claude/hooks/logger-guard/tsconfig.json

diff --git a/.claude/hooks/auth-rotation-reminder/README.md b/.claude/hooks/auth-rotation-reminder/README.md
new file mode 100644
index 00000000..fb278842
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/README.md
@@ -0,0 +1,131 @@
+# auth-rotation-reminder
+
+Claude Code `Stop` hook that periodically logs you out of authenticated
+CLIs (npm, pnpm, gcloud, vault, aws sso, docker, socket, …) so stale
+long-lived tokens don't sit in your dotfiles or keychain for days.
+
+## Why
+
+Long-lived auth tokens live in well-known locations: `~/.npmrc`,
+`~/.config/gh/hosts.yml`, `~/.config/gcloud/`, `~/.docker/config.json`.
+A compromised dev workstation has a wide blast radius on those files.
+Periodic auto-revocation tightens the window and forces explicit
+re-authentication, which is itself a small phishing-defense moment
+("did I really mean to publish?").
+
+## Defaults
+
+- **Interval**: 1 hour. Set `SOCKET_AUTH_ROTATION_INTERVAL_HOURS=4` to
+  loosen, `=0` to run on every Stop event.
+- **Mode**: auto-logout (the hook *acts*, not just warns).
+- **Default skip-list**: `gh` is skipped because Claude Code itself
+  uses `gh` for `gh pr edit` etc. — auto-revoking it would break the
+  agent.
+- **CI**: hook short-circuits when `CI` env var is set.
+
+## What's swept
+
+| id        | display name      | detect            | logout                         |
+| --------- | ----------------- | ----------------- | ------------------------------ |
+| npm       | npm               | `npm whoami`      | `npm logout`                   |
+| pnpm      | pnpm              | `pnpm whoami`     | `pnpm logout`                  |
+| yarn      | yarn              | `yarn --version`  | `yarn npm logout`              |
+| gcloud    | gcloud            | `gcloud auth list ... ACTIVE` | `gcloud auth revoke --all --quiet` |
+| aws-sso   | aws (sso)         | `aws sts get-caller-identity` | `aws sso logout` |
+| gh        | gh (GitHub CLI)   | `gh auth status`  | `gh auth logout --hostname github.com` |
+| vault     | vault             | `vault token lookup` | `vault token revoke -self` |
+| docker    | docker            | `docker info \| grep Username:` | `docker logout` |
+| socket    | socket            | `socket whoami`   | `socket logout`                |
+
+The hook never reads, prints, or compares any token value. Detection
+is exit-code only; logout commands' output is suppressed except for
+non-zero exit codes which surface as "logout failed" lines.
+
+## Snoozing
+
+Need to keep your auth alive for the next few hours (e.g. mid-publish)?
+Drop a `.snooze` file with an ISO 8601 expiry on line 1.
+
+```bash
+# Snooze for 4 hours, project-local
+date -ud "+4 hours" +"%Y-%m-%dT%H:%M:%SZ" > .claude/auth-rotation.snooze
+
+# Snooze globally for 8 hours (applies to every repo)
+mkdir -p ~/.claude/hooks/auth-rotation
+date -ud "+8 hours" +"%Y-%m-%dT%H:%M:%SZ" > ~/.claude/hooks/auth-rotation/snooze
+```
+
+The hook **automatically deletes the file** once the timestamp is
+reached. No manual cleanup needed.
+
+Snoozes that are malformed, empty, or unreadable are also auto-deleted
+on the next run — fail-safe so a corrupted file can't permanently
+disable rotation.
+
+`.claude/*.snooze` is gitignored; project-local snoozes never leak into
+commits.
+
+## Skip-list
+
+Permanently skip a service:
+
+```bash
+# Per-user: applies to every repo
+mkdir -p ~/.claude/hooks/auth-rotation
+echo gcloud >> ~/.claude/hooks/auth-rotation/services-skip
+
+# Per-repo: applies just to this checkout
+echo vault >> .claude/auth-rotation.services-skip
+```
+
+One id per line. Lines starting with `#` are comments. Service ids
+are stable — see the table above.
+
+## Disable temporarily
+
+```bash
+SOCKET_AUTH_ROTATION_DISABLED=1   # any non-empty value
+```
+
+For pairing sessions, demos, etc. The hook short-circuits before
+doing any work.
+
+## Wiring
+
+In `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/auth-rotation-reminder/index.mts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Tests
+
+```bash
+cd .claude/hooks/auth-rotation-reminder
+node --test test/*.test.mts
+```
+
+## Reusing the snooze convention
+
+Other hooks can adopt the same `.snooze` pattern. The convention is:
+
+- Filename: `.claude/<hook-id>.snooze` (project) or
+  `~/.claude/hooks/<hook-id>/snooze` (global).
+- Format: ISO 8601 expiry on line 1. Optional further lines ignored.
+- `.gitignore`: `.claude/*.snooze`.
+- Cleanup: hook auto-deletes expired files via `safeDelete`.
+- The `checkSnoozes` / `tryUnlink` helpers in `index.mts` are easy to
+  copy into a sibling hook.
diff --git a/.claude/hooks/auth-rotation-reminder/index.mts b/.claude/hooks/auth-rotation-reminder/index.mts
new file mode 100644
index 00000000..06e05356
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/index.mts
@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// Claude Code Stop hook — auth-rotation-reminder.
+//
+// Periodically logs you out of authenticated CLIs (npm, pnpm, gcloud,
+// vault, aws sso, docker, socket, …) so stale long-lived tokens don't
+// sit in dotfiles or keychains for days.
+//
+// Behavior on each Stop event:
+//
+//   1. Drain stdin (Stop hook delivers a JSON payload we don't need).
+//   2. Skip if running in CI (CI auth has its own lifecycle).
+//   3. Read both global + project-local `.snooze` files. Each carries
+//      an ISO 8601 expiry on line 1; if past, the file is auto-cleaned
+//      and the hook proceeds. If unexpired, the hook honors the snooze
+//      and exits silently.
+//   4. Throttle via a state file: if the last successful run was within
+//      the configured interval (default 1h), exit silently.
+//   5. For each service in services.mts:
+//        a. Skip if the binary is missing and `optional: true`.
+//        b. Run detectCmd. Skip if not authenticated.
+//        c. Run logoutCmd. Log to stderr via lib's logger.
+//   6. Update the state file's mtime.
+//
+// The hook NEVER reads, prints, or compares any token value. Detection
+// is exit-code only; logout commands' output is suppressed except for
+// non-zero exit codes which surface as "logout failed" lines.
+//
+// Snooze file format (ISO 8601 timestamp on line 1):
+//
+//   $ date -ud '+4 hours' +"%Y-%m-%dT%H:%M:%SZ" > .claude/auth-rotation.snooze
+//
+// Removed automatically once the timestamp is reached.
+//
+// Configuration env vars (all optional):
+//
+//   SOCKET_AUTH_ROTATION_INTERVAL_HOURS   default: 1
+//     How long between actual auth-rotation runs (state-file throttle).
+//     Set to 0 to run on every Stop event (verbose).
+//
+//   SOCKET_AUTH_ROTATION_DISABLED        default: unset
+//     If set to a truthy value, skip the hook entirely.
+
+import { spawnSync } from 'node:child_process'
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+import { safeDelete } from '@socketsecurity/lib/fs'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import { DEFAULT_SKIP_IDS, SERVICES } from './services.mts'
+import type { Service } from './services.mts'
+
+const logger = getDefaultLogger()
+const PREFIX = '[auth-rotation-reminder]'
+
+// ── Paths ───────────────────────────────────────────────────────────
+
+const STATE_DIR = path.join(homedir(), '.claude', 'hooks', 'auth-rotation')
+const STATE_FILE = path.join(STATE_DIR, 'last-run')
+const GLOBAL_SNOOZE = path.join(STATE_DIR, 'snooze')
+const GLOBAL_SKIP_LIST = path.join(STATE_DIR, 'services-skip')
+
+// Project-local files live at the repo root next to .claude/. Claude
+// Code spawns Stop hooks with the working directory set to the repo
+// root so process.cwd() is reliable here.
+const PROJECT_SNOOZE = path.join(
+  process.cwd(),
+  '.claude',
+  'auth-rotation.snooze',
+)
+const PROJECT_SKIP_LIST = path.join(
+  process.cwd(),
+  '.claude',
+  'auth-rotation.services-skip',
+)
+
+// ── Snooze handling ─────────────────────────────────────────────────
+
+interface SnoozeStatus {
+  active: boolean
+  cleaned: string[]
+}
+
+async function checkSnoozes(): Promise<SnoozeStatus> {
+  const status: SnoozeStatus = { active: false, cleaned: [] }
+  const cleanFile = async (file: string, reason: string): Promise<void> => {
+    try {
+      await safeDelete(file)
+      status.cleaned.push(file)
+    } catch (e) {
+      logger.error(
+        `${PREFIX} safeDelete(${path.basename(file)}) failed (${reason}): ${(e as Error).message}`,
+      )
+    }
+  }
+  for (const file of [GLOBAL_SNOOZE, PROJECT_SNOOZE]) {
+    if (!existsSync(file)) {
+      continue
+    }
+    let content = ''
+    try {
+      content = readFileSync(file, 'utf8').trim()
+    } catch {
+      await cleanFile(file, 'unreadable')
+      continue
+    }
+    // Empty content = legacy form, no expiry. Treat as expired now.
+    if (content.length === 0) {
+      await cleanFile(file, 'legacy (no expiry)')
+      continue
+    }
+    const firstLine = content.split('\n')[0]!.trim()
+    const expiry = Date.parse(firstLine)
+    if (Number.isNaN(expiry)) {
+      await cleanFile(file, 'malformed expiry')
+      continue
+    }
+    if (Date.now() >= expiry) {
+      await cleanFile(file, 'expired')
+      continue
+    }
+    // Unexpired snooze. Honor it.
+    status.active = true
+    return status
+  }
+  return status
+}
+
+// ── Skip-list ───────────────────────────────────────────────────────
+
+function loadSkipIds(): Set<string> {
+  const skipIds = new Set<string>(DEFAULT_SKIP_IDS)
+  for (const file of [GLOBAL_SKIP_LIST, PROJECT_SKIP_LIST]) {
+    if (!existsSync(file)) {
+      continue
+    }
+    try {
+      const content = readFileSync(file, 'utf8')
+      for (const raw of content.split('\n')) {
+        const trimmed = raw.trim()
+        if (trimmed && !trimmed.startsWith('#')) {
+          skipIds.add(trimmed)
+        }
+      }
+    } catch {
+      // Ignore unreadable skip-list — better to over-rotate than fail closed.
+    }
+  }
+  return skipIds
+}
+
+// ── Throttle ────────────────────────────────────────────────────────
+
+function intervalMs(): number {
+  const raw = process.env['SOCKET_AUTH_ROTATION_INTERVAL_HOURS']
+  const hours = raw === undefined ? 1 : Number.parseFloat(raw)
+  if (!Number.isFinite(hours) || hours < 0) {
+    return 60 * 60 * 1000
+  }
+  return Math.round(hours * 60 * 60 * 1000)
+}
+
+function withinThrottle(): boolean {
+  const interval = intervalMs()
+  if (interval === 0) {
+    return false
+  }
+  if (!existsSync(STATE_FILE)) {
+    return false
+  }
+  try {
+    const { mtimeMs } = statSync(STATE_FILE)
+    return Date.now() - mtimeMs < interval
+  } catch {
+    return false
+  }
+}
+
+function touchStateFile(): void {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true })
+    if (!existsSync(STATE_FILE)) {
+      writeFileSync(STATE_FILE, '')
+    }
+    const now = new Date()
+    utimesSync(STATE_FILE, now, now)
+  } catch {
+    // Throttle is best-effort. Loss = hook runs more often than configured;
+    // not worth surfacing.
+  }
+}
+
+// ── Service detection + logout ──────────────────────────────────────
+
+interface RotationResult {
+  loggedOut: string[]
+  failed: Array<{ service: string; reason: string }>
+  skippedMissing: string[]
+}
+
+function isOnPath(binary: string): boolean {
+  // `command -v` is portable across sh/bash/zsh and exits 0 if found.
+  const r = spawnSync('sh', ['-c', `command -v ${binary} >/dev/null 2>&1`], {
+    stdio: 'ignore',
+  })
+  return r.status === 0
+}
+
+function isAuthenticated(s: Service): boolean {
+  const r = spawnSync(s.detectCmd[0]!, s.detectCmd.slice(1) as string[], {
+    stdio: 'ignore',
+    timeout: 5000,
+  })
+  return r.status === 0
+}
+
+function runLogout(s: Service): { ok: boolean; reason?: string } {
+  const r = spawnSync(s.logoutCmd[0]!, s.logoutCmd.slice(1) as string[], {
+    stdio: 'ignore',
+    timeout: 10_000,
+  })
+  if (r.status === 0) {
+    return { ok: true }
+  }
+  if (r.error) {
+    return { ok: false, reason: r.error.message }
+  }
+  return { ok: false, reason: `exit code ${r.status}` }
+}
+
+function rotateAll(skipIds: Set<string>): RotationResult {
+  const result: RotationResult = {
+    loggedOut: [],
+    failed: [],
+    skippedMissing: [],
+  }
+  for (const service of SERVICES) {
+    if (skipIds.has(service.id)) {
+      continue
+    }
+    if (!isOnPath(service.detectCmd[0]!)) {
+      if (!service.optional) {
+        result.skippedMissing.push(service.name)
+      }
+      continue
+    }
+    if (!isAuthenticated(service)) {
+      continue
+    }
+    const out = runLogout(service)
+    if (out.ok) {
+      result.loggedOut.push(service.name)
+    } else {
+      result.failed.push({
+        service: service.name,
+        reason: out.reason ?? 'unknown',
+      })
+    }
+  }
+  return result
+}
+
+// ── Output ──────────────────────────────────────────────────────────
+
+function reportSnoozeCleaned(cleaned: string[]): void {
+  for (const file of cleaned) {
+    logger.error(`${PREFIX} cleared expired snooze: ${file}`)
+  }
+}
+
+function reportRotation(result: RotationResult): void {
+  const parts: string[] = []
+  if (result.loggedOut.length > 0) {
+    parts.push(
+      `logged out of ${result.loggedOut.length} CLI(s): ${result.loggedOut.join(', ')}`,
+    )
+  }
+  if (result.failed.length > 0) {
+    const failed = result.failed
+      .map(f => `${f.service} (${f.reason})`)
+      .join(', ')
+    parts.push(`logout failed: ${failed}`)
+  }
+  if (result.skippedMissing.length > 0) {
+    parts.push(`expected-but-missing: ${result.skippedMissing.join(', ')}`)
+  }
+  if (parts.length === 0) {
+    return
+  }
+  logger.error(`${PREFIX} ${parts.join('; ')}`)
+  logger.error(
+    `  Snooze for next 4h:  date -ud "+4 hours" +"%Y-%m-%dT%H:%M:%SZ" > .claude/auth-rotation.snooze`,
+  )
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+async function run(): Promise<void> {
+  if (process.env['CI']) {
+    return
+  }
+  if (process.env['SOCKET_AUTH_ROTATION_DISABLED']) {
+    return
+  }
+  const snooze = await checkSnoozes()
+  reportSnoozeCleaned(snooze.cleaned)
+  if (snooze.active) {
+    return
+  }
+  if (withinThrottle()) {
+    return
+  }
+  const skipIds = loadSkipIds()
+  const result = rotateAll(skipIds)
+  reportRotation(result)
+  touchStateFile()
+}
+
+function main(): void {
+  // Drain stdin so Node doesn't keep us alive waiting on the Stop hook's
+  // JSON payload (we don't read its contents).
+  process.stdin.resume()
+  process.stdin.on('data', () => {})
+  process.stdin.on('end', () => {
+    run()
+      .catch(e => {
+        logger.error(`${PREFIX} unexpected error: ${(e as Error).message}`)
+      })
+      .finally(() => {
+        process.exit(0)
+      })
+  })
+  if (process.stdin.readable === false) {
+    run()
+      .catch(e => {
+        logger.error(`${PREFIX} unexpected error: ${(e as Error).message}`)
+      })
+      .finally(() => {
+        process.exit(0)
+      })
+  }
+}
+
+main()
diff --git a/.claude/hooks/auth-rotation-reminder/package.json b/.claude/hooks/auth-rotation-reminder/package.json
new file mode 100644
index 00000000..38fa6a49
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "hook-auth-rotation-reminder",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "dependencies": {
+    "@socketsecurity/lib": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  }
+}
diff --git a/.claude/hooks/auth-rotation-reminder/services.mts b/.claude/hooks/auth-rotation-reminder/services.mts
new file mode 100644
index 00000000..f0168d09
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/services.mts
@@ -0,0 +1,142 @@
+// Service catalog for auth-rotation-reminder.
+//
+// Each entry tells the hook how to detect whether a CLI is currently
+// authenticated and how to log it out. `optional: true` means the hook
+// silently skips the service if the binary isn't on PATH (most are
+// optional — most devs have a subset of these installed).
+//
+// Detection commands MUST exit 0 when authenticated and non-zero when
+// not. Output goes to /dev/null; the hook reads only the exit code.
+//
+// Logout commands run unconditionally when the hook is in auto-logout
+// mode. They should be idempotent — re-running them on an already
+// logged-out CLI is fine.
+
+export interface Service {
+  // Stable id used in skip-list files and error messages. Never rename
+  // without a deprecation cycle — devs encode these in their personal
+  // `.skip` lists.
+  id: string
+  // Display name for output.
+  name: string
+  // Command + args that exit 0 if logged in, non-zero otherwise.
+  detectCmd: readonly string[]
+  // Command + args that performs the logout. Must be idempotent.
+  logoutCmd: readonly string[]
+  // Skip silently when the binary isn't on PATH. False means the
+  // hook reports "binary missing" as a finding (rare — only for
+  // first-class fleet CLIs we expect every dev to have).
+  optional: boolean
+  // Optional human-readable doc URL surfaced when the hook reports the
+  // logout. Empty when no canonical doc page exists.
+  docUrl?: string
+}
+
+// Default skip-list seeds. Devs can extend via the per-user
+// `~/.claude/hooks/auth-rotation/services-skip` (one id per line)
+// or per-repo `.claude/auth-rotation.services-skip` files.
+//
+// `gh` is seeded because Claude Code itself uses `gh` for `gh pr edit`
+// etc. — auto-revoking it mid-session would break the agent.
+export const DEFAULT_SKIP_IDS = ['gh'] as const
+
+export const SERVICES: readonly Service[] = [
+  {
+    id: 'npm',
+    name: 'npm',
+    detectCmd: ['npm', 'whoami'],
+    logoutCmd: ['npm', 'logout'],
+    optional: true,
+    docUrl: 'https://docs.npmjs.com/cli/v11/commands/npm-logout',
+  },
+  {
+    id: 'pnpm',
+    name: 'pnpm',
+    detectCmd: ['pnpm', 'whoami'],
+    logoutCmd: ['pnpm', 'logout'],
+    optional: false,
+    docUrl: 'https://pnpm.io/id/11.x/cli/logout',
+  },
+  {
+    id: 'yarn',
+    name: 'yarn',
+    // Yarn Berry's logout lives under `npm` namespace; Yarn Classic's
+    // is bare. We try Berry first (the modern default), fall back to
+    // Classic. Detection is the same: `npm whoami` from inside a
+    // yarn-managed registry. Yarn doesn't expose a portable whoami,
+    // so we approximate by checking for a yarn auth token in
+    // `~/.yarnrc.yml` via grep — too fragile to ship; use logout-only
+    // (idempotent: clears nothing if nothing's there).
+    detectCmd: ['yarn', '--version'],
+    logoutCmd: ['yarn', 'npm', 'logout'],
+    optional: true,
+  },
+  {
+    id: 'gcloud',
+    name: 'gcloud',
+    // `gcloud auth list` exits 0 always; we check whether any non-empty
+    // active account is reported. Wrap with sh -c to chain.
+    detectCmd: [
+      'sh',
+      '-c',
+      'gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>/dev/null | grep -q .',
+    ],
+    logoutCmd: ['gcloud', 'auth', 'revoke', '--all', '--quiet'],
+    optional: true,
+    docUrl: 'https://cloud.google.com/sdk/gcloud/reference/auth/revoke',
+  },
+  {
+    id: 'aws-sso',
+    name: 'aws (sso)',
+    // `aws sts get-caller-identity` succeeds when authenticated.
+    // sts is the universal probe across all AWS auth flavors.
+    detectCmd: ['aws', 'sts', 'get-caller-identity'],
+    // `aws sso logout` only clears SSO cache. For non-SSO creds, the
+    // dev would have to remove `~/.aws/credentials` themselves; we
+    // don't touch that file because it might hold long-lived keys
+    // intentionally. SSO-only is the conservative default.
+    logoutCmd: ['aws', 'sso', 'logout'],
+    optional: true,
+  },
+  {
+    id: 'gh',
+    name: 'gh (GitHub CLI)',
+    detectCmd: ['gh', 'auth', 'status'],
+    logoutCmd: ['gh', 'auth', 'logout', '--hostname', 'github.com'],
+    optional: true,
+    docUrl: 'https://cli.github.com/manual/gh_auth_logout',
+  },
+  {
+    id: 'vault',
+    name: 'vault',
+    detectCmd: ['vault', 'token', 'lookup'],
+    // `token revoke -self` revokes the active token; survives the
+    // logout safely (re-auth via `vault login` next session).
+    logoutCmd: ['vault', 'token', 'revoke', '-self'],
+    optional: true,
+  },
+  {
+    id: 'docker',
+    name: 'docker',
+    // No portable "am I logged in" — `docker info` returns mixed data.
+    // Approximate via `docker system info` filter.
+    detectCmd: [
+      'sh',
+      '-c',
+      'docker info 2>/dev/null | grep -q "^ Username:"',
+    ],
+    // Without a registry arg, `docker logout` clears the default index.
+    logoutCmd: ['docker', 'logout'],
+    optional: true,
+  },
+  {
+    id: 'socket',
+    name: 'socket',
+    // `socket whoami` (when present in the cli) is the canonical probe.
+    // The cli emits exit 0 when authenticated.
+    detectCmd: ['socket', 'whoami'],
+    // `socket logout` clears the local API token from settings.
+    logoutCmd: ['socket', 'logout'],
+    optional: true,
+  },
+] as const
diff --git a/.claude/hooks/auth-rotation-reminder/test/auth-rotation-reminder.test.mts b/.claude/hooks/auth-rotation-reminder/test/auth-rotation-reminder.test.mts
new file mode 100644
index 00000000..4582a1f9
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/test/auth-rotation-reminder.test.mts
@@ -0,0 +1,162 @@
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.resolve(__dirname, '..', 'index.mts')
+
+interface Env {
+  [key: string]: string
+}
+
+function runHook(opts: {
+  cwd?: string
+  env?: Env
+} = {}): Promise<{ code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [HOOK], {
+      cwd: opts.cwd ?? process.cwd(),
+      stdio: ['pipe', 'ignore', 'pipe'],
+      env: {
+        // Default to a sentinel CI value the hook short-circuits on,
+        // unless the caller overrides. Most tests want the early-exit
+        // path so they don't actually run logout commands.
+        ...process.env,
+        ...opts.env,
+      },
+    })
+    let stderr = ''
+    child.stderr.on('data', d => {
+      stderr += d.toString()
+    })
+    child.on('error', reject)
+    child.on('exit', code => {
+      resolve({ code: code ?? -1, stderr })
+    })
+    child.stdin.end('{}\n')
+  })
+}
+
+function makeRepo(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'auth-rotation-test-'))
+  mkdirSync(path.join(dir, '.claude'), { recursive: true })
+  return dir
+}
+
+test('exits 0 silently when CI env var is set', async () => {
+  const repo = makeRepo()
+  try {
+    const { code, stderr } = await runHook({
+      cwd: repo,
+      env: { CI: '1' },
+    })
+    assert.equal(code, 0)
+    assert.equal(stderr, '', `expected no output in CI; got: ${stderr}`)
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
+
+test('exits 0 silently when SOCKET_AUTH_ROTATION_DISABLED is set', async () => {
+  const repo = makeRepo()
+  try {
+    const { code, stderr } = await runHook({
+      cwd: repo,
+      env: {
+        CI: '',
+        SOCKET_AUTH_ROTATION_DISABLED: '1',
+      },
+    })
+    assert.equal(code, 0)
+    assert.equal(stderr, '')
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
+
+test('honors a project-local snooze with future expiry', async () => {
+  const repo = makeRepo()
+  try {
+    const expiry = new Date(Date.now() + 60 * 60 * 1000).toISOString()
+    writeFileSync(path.join(repo, '.claude', 'auth-rotation.snooze'), expiry)
+    const { code, stderr } = await runHook({
+      cwd: repo,
+      env: { CI: '' },
+    })
+    assert.equal(code, 0)
+    // Hook should NOT report cleanup of an unexpired snooze.
+    assert.ok(
+      !stderr.includes('cleared expired snooze'),
+      `hook cleared a fresh snooze: ${stderr}`,
+    )
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
+
+test('auto-cleans expired project-local snooze and proceeds', async () => {
+  const repo = makeRepo()
+  const snoozeFile = path.join(repo, '.claude', 'auth-rotation.snooze')
+  try {
+    const expiry = new Date(Date.now() - 60 * 60 * 1000).toISOString()
+    writeFileSync(snoozeFile, expiry)
+    const { code, stderr } = await runHook({
+      cwd: repo,
+      // Force CI so the hook short-circuits AFTER snooze handling
+      // (which is what we're testing).
+      env: { CI: '' },
+    })
+    assert.equal(code, 0)
+    // We can't easily assert on snooze cleanup messaging without
+    // also forcing the hook to do real auth detection. The strong
+    // assertion is that the file is gone afterward.
+    assert.ok(
+      !existsSync(snoozeFile),
+      'expired snooze file should have been deleted',
+    )
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
+
+test('auto-cleans malformed snooze content', async () => {
+  const repo = makeRepo()
+  const snoozeFile = path.join(repo, '.claude', 'auth-rotation.snooze')
+  try {
+    writeFileSync(snoozeFile, 'not-an-iso-timestamp\n')
+    const { code } = await runHook({
+      cwd: repo,
+      env: { CI: '' },
+    })
+    assert.equal(code, 0)
+    assert.ok(
+      !existsSync(snoozeFile),
+      'malformed snooze file should have been deleted',
+    )
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
+
+test('auto-cleans empty (legacy) snooze file', async () => {
+  const repo = makeRepo()
+  const snoozeFile = path.join(repo, '.claude', 'auth-rotation.snooze')
+  try {
+    writeFileSync(snoozeFile, '')
+    const { code } = await runHook({
+      cwd: repo,
+      env: { CI: '' },
+    })
+    assert.equal(code, 0)
+    assert.ok(
+      !existsSync(snoozeFile),
+      'empty (legacy) snooze file should have been deleted',
+    )
+  } finally {
+    rmSync(repo, { recursive: true, force: true })
+  }
+})
diff --git a/.claude/hooks/auth-rotation-reminder/tsconfig.json b/.claude/hooks/auth-rotation-reminder/tsconfig.json
new file mode 100644
index 00000000..53c5c847
--- /dev/null
+++ b/.claude/hooks/auth-rotation-reminder/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "esnext",
+    "verbatimModuleSyntax": true
+  }
+}
diff --git a/.claude/hooks/logger-guard/README.md b/.claude/hooks/logger-guard/README.md
new file mode 100644
index 00000000..55ba3ece
--- /dev/null
+++ b/.claude/hooks/logger-guard/README.md
@@ -0,0 +1,54 @@
+# logger-guard
+
+Claude Code `PreToolUse` hook that blocks `Edit`/`Write` tool calls
+introducing direct stream writes (`process.stderr.write`,
+`process.stdout.write`, `console.log/error/warn/info/debug`) into
+source files.
+
+## Why
+
+Source code uses `getDefaultLogger()` from `@socketsecurity/lib/logger`
+for all output. Direct stream writes bypass:
+
+- Color/theme handling
+- Indentation tracking
+- Stream redirection in tests
+- Counter increments used by spinners and progress bars
+
+so they produce inconsistent output that breaks layout-sensitive
+workflows (spinner clears, footer rendering).
+
+## Scope
+
+- Only fires on `Edit` / `Write` tools.
+- Only inspects files matching `*.{ts,mts,tsx,cts}` under repo
+  source. Hooks (`.claude/hooks/`), git-hooks (`.git-hooks/`), build
+  scripts (`scripts/`), tests, fixtures, and external/vendored code
+  are exempt.
+- Lines containing `# socket-hook: allow logger` are exempt
+  (canonical opt-out). The bare `# socket-hook: allow` form also
+  works.
+- Lines that look like documentation (`*` / `//` / `#` comments,
+  JSDoc tags, fully-backticked code spans) are exempt.
+
+## Suggested replacements
+
+| Direct call | Logger equivalent |
+| --- | --- |
+| `process.stderr.write(s)` | `logger.error(s)` |
+| `process.stdout.write(s)` | `logger.info(s)` |
+| `console.error(...)` | `logger.error(...)` |
+| `console.warn(...)` | `logger.warn(...)` |
+| `console.info(...)` | `logger.info(...)` |
+| `console.debug(...)` | `logger.debug(...)` |
+| `console.log(...)` | `logger.info(...)` |
+
+The hook surfaces the rewrite as a `Fix:` line per hit so the agent
+can apply it directly.
+
+## Tests
+
+```bash
+cd .claude/hooks/logger-guard
+node --test test/*.test.mts
+```
diff --git a/.claude/hooks/logger-guard/index.mts b/.claude/hooks/logger-guard/index.mts
new file mode 100644
index 00000000..f7ad0f85
--- /dev/null
+++ b/.claude/hooks/logger-guard/index.mts
@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — logger-guard.
+//
+// Blocks Edit/Write tool calls that would introduce direct calls to
+// `process.stderr.write`, `process.stdout.write`, `console.log`,
+// `console.error`, `console.warn`, `console.info`, or `console.debug`
+// in source files. Exit code 2 makes Claude Code refuse the tool call
+// so the diff never lands. The model sees the rejection reason on
+// stderr and retries using the lib's logger.
+//
+// Why this rule:
+//
+//   The fleet's source code uses `getDefaultLogger()` from
+//   `@socketsecurity/lib/logger` for every output. Direct stream writes
+//   bypass:
+//     - Color/theme handling
+//     - Indentation tracking
+//     - Stream redirection in tests
+//     - Counter increments used by spinners
+//   so they produce inconsistent output that breaks layout-sensitive
+//   workflows (spinner clears, footer rendering).
+//
+// Scope:
+//
+//   - Fires only on `Edit` and `Write` tool calls.
+//   - Only inspects files under `src/` with .ts/.mts/.tsx/.cts
+//     extensions. Hooks (.claude/hooks/), git-hooks (.git-hooks/),
+//     scripts (scripts/), tests, fixtures, and external/ vendored code
+//     are exempt — see EXEMPT_PATH_PATTERNS.
+//   - Lines marked `# socket-hook: allow logger` are exempt (canonical
+//     opt-out marker, same as path-guard / token-guard / npx-guard).
+//   - Lines that look like documentation (comment lines, JSDoc tags,
+//     fully backticked code spans) are exempt — handled by the shared
+//     `looksLikeDocumentation` heuristic in `_helpers.mts`.
+//
+// The hook fails OPEN on its own bugs (exit 0 + stderr log) so a bad
+// hook deploy can't brick the session.
+
+import process from 'node:process'
+
+// Files exempt from the rule. Comments explain why each is excluded.
+const EXEMPT_PATH_PATTERNS: RegExp[] = [
+  // Hook code itself runs early in the lifecycle and may need to log
+  // to stderr before the lib is fully resolvable. Treat hooks as
+  // "system code" with their own conventions.
+  /\.claude\/hooks\//,
+  // Git hooks (.git-hooks/_helpers.mts, pre-commit, etc.) run before
+  // workspace deps are guaranteed to be installed.
+  /\.git-hooks\//,
+  // Build scripts often produce direct stdout for human-readable
+  // build output (progress, summary). Migrate these case-by-case
+  // outside of this hook's scope.
+  /(^|\/)scripts\//,
+  // Test files commonly use console.* to capture / assert output.
+  /\.(test|spec)\.(m?[jt]s|tsx?|cts|mts)$/,
+  /(^|\/)tests?\//,
+  /(^|\/)fixtures\//,
+  // Vendored upstream sources — never modified for local conventions.
+  /(^|\/)external\//,
+  /(^|\/)vendor\//,
+  /(^|\/)upstream\//,
+  // The hook itself.
+  /\.claude\/hooks\/logger-guard\//,
+]
+
+const LOGGER_LEAK_RE =
+  /\b(process\.std(?:err|out)\.write|console\.(?:log|error|warn|info|debug))\s*\(/
+
+const COMMENT_LINE_RE = /^\s*(\*|\/\/|#)/
+const JSDOC_TAG_RE = /@(example|param|returns?|see|link)\b/
+const SOCKET_HOOK_MARKER_RE = /#\s*socket-hook:\s*allow(?:\s+([\w-]+))?/
+
+function isMarkerSuppressed(line: string): boolean {
+  const m = line.match(SOCKET_HOOK_MARKER_RE)
+  if (!m) {
+    return false
+  }
+  // No specific rule named → blanket allow. Targeted form must name
+  // 'logger' to suppress this scanner.
+  return !m[1] || m[1] === 'logger'
+}
+
+function isInsideBackticks(line: string): boolean {
+  // Find every backtick-delimited span on the line and test if every
+  // logger-leak match sits within one. Conservative: any match outside
+  // a backtick span fails the check.
+  const spans: Array<[number, number]> = []
+  for (let i = 0; i < line.length; i += 1) {
+    if (line[i] === '`') {
+      const end = line.indexOf('`', i + 1)
+      if (end < 0) {
+        break
+      }
+      spans.push([i, end])
+      i = end
+    }
+  }
+  if (spans.length === 0) {
+    return false
+  }
+  const re = new RegExp(LOGGER_LEAK_RE.source, 'g')
+  let m: RegExpExecArray | null
+  while ((m = re.exec(line)) !== null) {
+    const start = m.index
+    const end = start + m[0].length
+    const inside = spans.some(([s, e]) => start > s && end <= e)
+    if (!inside) {
+      return false
+    }
+  }
+  return true
+}
+
+function looksLikeDocumentation(line: string): boolean {
+  if (isMarkerSuppressed(line)) {
+    return true
+  }
+  if (COMMENT_LINE_RE.test(line)) {
+    return true
+  }
+  if (JSDOC_TAG_RE.test(line)) {
+    return true
+  }
+  if (isInsideBackticks(line)) {
+    return true
+  }
+  return false
+}
+
+function suggestReplacement(line: string): string {
+  return line
+    .replace(/\bprocess\.stderr\.write\s*\(/g, 'logger.error(')
+    .replace(/\bprocess\.stdout\.write\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.error\s*\(/g, 'logger.error(')
+    .replace(/\bconsole\.warn\s*\(/g, 'logger.warn(')
+    .replace(/\bconsole\.info\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.debug\s*\(/g, 'logger.debug(')
+    .replace(/\bconsole\.log\s*\(/g, 'logger.info(')
+}
+
+interface Hit {
+  lineNumber: number
+  line: string
+  suggested: string
+}
+
+function scan(source: string): Hit[] {
+  const hits: Hit[] = []
+  const lines = source.split('\n')
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!
+    if (!LOGGER_LEAK_RE.test(line)) {
+      continue
+    }
+    if (looksLikeDocumentation(line)) {
+      continue
+    }
+    hits.push({
+      lineNumber: i + 1,
+      line,
+      suggested: suggestReplacement(line),
+    })
+  }
+  return hits
+}
+
+function isInScope(filePath: string): boolean {
+  if (!filePath) {
+    return false
+  }
+  if (!/\.(m?ts|tsx|cts)$/.test(filePath)) {
+    return false
+  }
+  for (const re of EXEMPT_PATH_PATTERNS) {
+    if (re.test(filePath)) {
+      return false
+    }
+  }
+  return true
+}
+
+function readStdin(): Promise<string> {
+  return new Promise(resolve => {
+    let buf = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => (buf += chunk))
+    process.stdin.on('end', () => resolve(buf))
+  })
+}
+
+interface ToolInput {
+  tool_name?: string
+  tool_input?: {
+    file_path?: string
+    new_string?: string
+    content?: string
+  }
+}
+
+function emitBlock(filePath: string, hits: Hit[]): void {
+  // Hook itself logs to stderr (no lib import at module load — keep
+  // hooks self-contained for fast startup). The rule only applies to
+  // source code; this output is informational for the agent.
+  const out: string[] = []
+  out.push('')
+  out.push('[logger-guard] Blocked: direct stream write found')
+  out.push(
+    '  Use `getDefaultLogger()` from `@socketsecurity/lib/logger` instead.',
+  )
+  out.push(`  File:    ${filePath}`)
+  for (const h of hits.slice(0, 3)) {
+    out.push(`  Line ${h.lineNumber}: ${h.line.trim()}`)
+    out.push(`  Fix:           ${h.suggested.trim()}`)
+  }
+  if (hits.length > 3) {
+    out.push(`  …and ${hits.length - 3} more.`)
+  }
+  out.push(
+    '  Opt-out for one line (rare): append `// # socket-hook: allow logger`.',
+  )
+  out.push('')
+  process.stderr.write(out.join('\n'))
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin()
+  if (!raw) {
+    return
+  }
+  let payload: ToolInput
+  try {
+    payload = JSON.parse(raw) as ToolInput
+  } catch {
+    return
+  }
+  if (payload.tool_name !== 'Edit' && payload.tool_name !== 'Write') {
+    return
+  }
+  const filePath = payload.tool_input?.file_path ?? ''
+  if (!isInScope(filePath)) {
+    return
+  }
+  const source =
+    payload.tool_input?.new_string ?? payload.tool_input?.content ?? ''
+  if (!source) {
+    return
+  }
+  const hits = scan(source)
+  if (hits.length === 0) {
+    return
+  }
+  emitBlock(filePath, hits)
+  process.exitCode = 2
+}
+
+main().catch(e => {
+  // Fail open on hook bugs.
+  process.stderr.write(
+    `[logger-guard] hook error (continuing): ${(e as Error).message}\n`,
+  )
+})
diff --git a/.claude/hooks/logger-guard/package.json b/.claude/hooks/logger-guard/package.json
new file mode 100644
index 00000000..7bc46780
--- /dev/null
+++ b/.claude/hooks/logger-guard/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "hook-logger-guard",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  }
+}
diff --git a/.claude/hooks/logger-guard/test/logger-guard.test.mts b/.claude/hooks/logger-guard/test/logger-guard.test.mts
new file mode 100644
index 00000000..a509b365
--- /dev/null
+++ b/.claude/hooks/logger-guard/test/logger-guard.test.mts
@@ -0,0 +1,171 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.resolve(__dirname, '..', 'index.mts')
+
+interface Payload {
+  tool_name: 'Edit' | 'Write' | string
+  tool_input: {
+    file_path?: string
+    new_string?: string
+    content?: string
+  }
+}
+
+function runHook(payload: Payload): Promise<{ code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [HOOK], {
+      stdio: ['pipe', 'ignore', 'pipe'],
+    })
+    let stderr = ''
+    child.stderr.on('data', d => {
+      stderr += d.toString()
+    })
+    child.on('error', reject)
+    child.on('exit', code => {
+      resolve({ code: code ?? -1, stderr })
+    })
+    child.stdin.end(JSON.stringify(payload))
+  })
+}
+
+test('blocks console.log in src/ .ts files', async () => {
+  const { code, stderr } = await runHook({
+    tool_name: 'Write',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      content: 'export function foo() { console.log("hi") }',
+    },
+  })
+  assert.equal(code, 2, `expected exit 2; got ${code}; stderr=${stderr}`)
+  assert.ok(stderr.includes('logger-guard'))
+  assert.ok(stderr.includes('Fix:'))
+  assert.ok(stderr.includes('logger.info'))
+})
+
+test('blocks process.stderr.write in src/ .mts files', async () => {
+  const { code, stderr } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/utils/output.mts',
+      new_string: 'process.stderr.write("oops\\n")',
+    },
+  })
+  assert.equal(code, 2)
+  assert.ok(stderr.includes('logger.error('))
+})
+
+test('allows hooks themselves to use process.stderr.write', async () => {
+  const { code, stderr } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: '.claude/hooks/some-hook/index.mts',
+      new_string: 'process.stderr.write("ok\\n")',
+    },
+  })
+  assert.equal(code, 0, `expected exit 0; got ${code}; stderr=${stderr}`)
+})
+
+test('allows scripts/ to use console.log', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'scripts/build.mts',
+      new_string: 'console.log("build complete")',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('allows tests to use console.log', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/utils/foo.test.mts',
+      new_string: 'console.log("debug")',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('respects # socket-hook: allow logger marker', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      new_string:
+        'const x = 1; console.error("legacy") // # socket-hook: allow logger',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('respects bare # socket-hook: allow marker', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      new_string: 'console.warn("a") // # socket-hook: allow',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('does not flag JSDoc examples', async () => {
+  const { code } = await runHook({
+    tool_name: 'Write',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      content:
+        '/**\n * @example\n * console.log("usage")\n */\nexport const foo = 1',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('does not flag comment lines', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      new_string: '// previously: console.log("debug")',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('does not flag content fully inside a single backtick span', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      // Single-line markdown-style backtick span — the inner content
+      // is documentation, not real code.
+      new_string: 'const note = `use logger.info() not console.log()`',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+test('does not run on non-Edit/Write tools', async () => {
+  const { code } = await runHook({
+    tool_name: 'Bash',
+    tool_input: { content: 'console.log("nope")' },
+  })
+  assert.equal(code, 0)
+})
+
+test('does not run on .js files (out of scope)', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.js',
+      new_string: 'console.log("legacy")',
+    },
+  })
+  assert.equal(code, 0)
+})
diff --git a/.claude/hooks/logger-guard/tsconfig.json b/.claude/hooks/logger-guard/tsconfig.json
new file mode 100644
index 00000000..53c5c847
--- /dev/null
+++ b/.claude/hooks/logger-guard/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "esnext",
+    "verbatimModuleSyntax": true
+  }
+}
diff --git a/.claude/settings.json b/.claude/settings.json
index 5c6bd51f..cca69875 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -8,6 +8,10 @@
             "type": "command",
             "command": "node .claude/hooks/check-new-deps/index.mts"
           },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/logger-guard/index.mts"
+          },
           {
             "type": "command",
             "command": "node .claude/hooks/path-guard/index.mts"
@@ -39,6 +43,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/auth-rotation-reminder/index.mts"
+          },
           {
             "type": "command",
             "command": "node .claude/hooks/stale-process-sweeper/index.mts"
diff --git a/.git-hooks/_helpers.mts b/.git-hooks/_helpers.mts
index 35a647a4..1181e37e 100755
--- a/.git-hooks/_helpers.mts
+++ b/.git-hooks/_helpers.mts
@@ -336,6 +336,52 @@ export const scanNpxDlx = (text: string): LineHit[] => {
   return hits
 }
 
+// ── Logger leak scanner ────────────────────────────────────────────
+//
+// The fleet rule: source code uses `getDefaultLogger()` from
+// `@socketsecurity/lib/logger`. Direct calls to `process.stderr.write`,
+// `process.stdout.write`, `console.log`, `console.error`, `console.warn`,
+// `console.info`, `console.debug` are blocked. Doc-context lines are
+// exempt; lines carrying `# socket-hook: allow logger` are exempt too.
+
+const LOGGER_LEAK_RE =
+  /\b(process\.std(?:err|out)\.write|console\.(?:log|error|warn|info|debug))\s*\(/
+
+// Map each direct call to its lib-logger equivalent. process.stdout is
+// closer to logger.info; process.stderr / console.error → logger.error;
+// console.warn → logger.warn; console.info / console.log → logger.info;
+// console.debug → logger.debug.
+function suggestLoggerReplacement(line: string): string {
+  return line
+    .replace(/\bprocess\.stderr\.write\s*\(/g, 'logger.error(')
+    .replace(/\bprocess\.stdout\.write\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.error\s*\(/g, 'logger.error(')
+    .replace(/\bconsole\.warn\s*\(/g, 'logger.warn(')
+    .replace(/\bconsole\.info\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.debug\s*\(/g, 'logger.debug(')
+    .replace(/\bconsole\.log\s*\(/g, 'logger.info(')
+}
+
+export const scanLoggerLeaks = (text: string): LineHit[] => {
+  const hits: LineHit[] = []
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (!LOGGER_LEAK_RE.test(line)) {
+      continue
+    }
+    if (looksLikeDocumentation(line, LOGGER_LEAK_RE, 'logger')) {
+      continue
+    }
+    hits.push({
+      lineNumber: i + 1,
+      line,
+      suggested: suggestLoggerReplacement(line),
+    })
+  }
+  return hits
+}
+
 // ── AI attribution scanner ─────────────────────────────────────────
 
 const AI_ATTRIBUTION_RE =
diff --git a/.git-hooks/pre-commit.mts b/.git-hooks/pre-commit.mts
index c42bfef0..d4b885a4 100755
--- a/.git-hooks/pre-commit.mts
+++ b/.git-hooks/pre-commit.mts
@@ -20,6 +20,7 @@ import {
   readFileForScan,
   scanAwsKeys,
   scanGitHubTokens,
+  scanLoggerLeaks,
   scanNpxDlx,
   scanPersonalPaths,
   scanPrivateKeys,
@@ -194,7 +195,56 @@ const main = (): number => {
       out(
         "Use 'pnpm exec <package>' or 'pnpm run <script>' instead. For " +
           'documentation lines that need the literal `npx` form, append ' +
-          'the marker `# zizmor: documentation-prohibition`.',
+          'the marker `# socket-hook: allow npx`.',
+      )
+      errors++
+    }
+  }
+
+  // Direct stream writes (process.stderr.write, process.stdout.write,
+  // console.*) in source files. Source code uses getDefaultLogger()
+  // from @socketsecurity/lib/logger; the logger-guard PreToolUse hook
+  // catches these at edit time, this gate catches them at commit time
+  // for edits made outside Claude.
+  out('Checking for direct stream writes...')
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    // Apply the same exempt set as the logger-guard hook so the rule
+    // is consistent: hooks, git-hooks, scripts, vendored / external
+    // sources are allowed. The shouldSkipFile helper covers tests and
+    // fixtures already.
+    if (
+      file.startsWith('.claude/hooks/') ||
+      file.startsWith('.git-hooks/') ||
+      file.startsWith('scripts/') ||
+      file.includes('/external/') ||
+      file.includes('/vendor/') ||
+      file.includes('/upstream/')
+    ) {
+      continue
+    }
+    if (!/\.(m?ts|tsx|cts)$/.test(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanLoggerLeaks(text)
+    if (hits.length > 0) {
+      out(red(`✗ ERROR: direct stream write found in: ${file}`))
+      for (const h of hits.slice(0, 3)) {
+        out(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          out(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      out(
+        "Use `getDefaultLogger()` from `@socketsecurity/lib/logger`. " +
+          'For documentation lines that need the literal call, append ' +
+          'the marker `# socket-hook: allow logger`.',
       )
       errors++
     }
diff --git a/.git-hooks/pre-push.mts b/.git-hooks/pre-push.mts
index 0a9be2e3..ee173403 100755
--- a/.git-hooks/pre-push.mts
+++ b/.git-hooks/pre-push.mts
@@ -32,6 +32,7 @@ import {
   readFileForScan,
   scanAwsKeys,
   scanGitHubTokens,
+  scanLoggerLeaks,
   scanPersonalPaths,
   scanPrivateKeys,
   scanSocketApiKeys,
@@ -292,6 +293,33 @@ const scanFilesInRange = (range: string): number => {
       out(red(`✗ BLOCKED: Private key found in: ${file}`))
       errors++
     }
+
+    if (
+      !file.startsWith('.claude/hooks/') &&
+      !file.startsWith('.git-hooks/') &&
+      !file.startsWith('scripts/') &&
+      !file.includes('/external/') &&
+      !file.includes('/vendor/') &&
+      !file.includes('/upstream/') &&
+      /\.(m?ts|tsx|cts)$/.test(file)
+    ) {
+      const loggerHits = scanLoggerLeaks(text)
+      if (loggerHits.length > 0) {
+        out(red(`✗ BLOCKED: direct stream write found in: ${file}`))
+        for (const h of loggerHits.slice(0, 3)) {
+          out(`${h.lineNumber}: ${h.line.trim()}`)
+          if (h.suggested && h.suggested !== h.line) {
+            out(`     fix: ${h.suggested.trim()}`)
+          }
+        }
+        out(
+          'Use `getDefaultLogger()` from `@socketsecurity/lib/logger`. ' +
+            'For documentation lines that need the literal call, append ' +
+            'the marker `# socket-hook: allow logger`.',
+        )
+        errors++
+      }
+    }
   }
   return errors
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 66a01c32..6c8de19f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -52,6 +52,15 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+catalogs:
+  default:
+    '@socketsecurity/lib':
+      specifier: 5.25.1
+      version: 5.25.1
+    '@types/node':
+      specifier: 24.9.2
+      version: 24.9.2
+
 overrides:
   defu: '>=6.1.7'
   vite: 7.3.2
@@ -154,6 +163,16 @@ importers:
         specifier: 4.0.3
         version: 4.0.3(@types/node@24.9.2)(jiti@2.6.1)(yaml@2.8.3)
 
+  .claude/hooks/auth-rotation-reminder:
+    dependencies:
+      '@socketsecurity/lib':
+        specifier: 'catalog:'
+        version: 5.25.1(typescript@5.9.3)
+    devDependencies:
+      '@types/node':
+        specifier: 'catalog:'
+        version: 24.9.2
+
   .claude/hooks/check-new-deps:
     dependencies:
       '@socketregistry/packageurl-js':
@@ -170,6 +189,12 @@ importers:
         specifier: 24.9.2
         version: 24.9.2
 
+  .claude/hooks/logger-guard:
+    devDependencies:
+      '@types/node':
+        specifier: 'catalog:'
+        version: 24.9.2
+
   .claude/hooks/path-guard: {}
 
   .claude/hooks/private-name-guard:
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index b8a1c8ba..23750b22 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,13 @@
 loglevel: error
 trustPolicy: no-downgrade
 
+# Catalog: shared dependency versions referenced as "catalog:" in
+# package.json. Hooks under .claude/hooks/* declare their deps via
+# `catalog:` so they stay in lockstep with the root workspace.
+catalog:
+  '@socketsecurity/lib': 5.25.1
+  '@types/node': 24.9.2
+
 # Register .claude/hooks/* as workspace packages so taze (run via
 # `pnpm run update`) sees and bumps their package.json manifests
 # alongside the root. Keeps hook deps in lockstep with the main tree.

From a80ad15188f2be9a146991943b518d0673606680 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Fri, 1 May 2026 11:35:41 -0400
Subject: [PATCH 10/17] chore: enable blockExoticSubdeps + sync .mjs->.mts
 script refs + soak-window wording

- pnpm-workspace.yaml: add blockExoticSubdeps: true (fleet default).
  Direct git deps still allowed; transitive ones refused.
- Update sync-scaffolding script references from .mjs to .mts in
  hook READMEs, path-guard segments, _shared skill rules, CLAUDE.md
  fleet-canonical header, and xport-schema.mts file header.
- Adopt "soak window" terminology in security-reviewer + CLAUDE.md
  tooling block, matching how the rest of the fleet refers to pnpm's
  minimumReleaseAge field.
---
 .claude/agents/security-reviewer.md       | 2 +-
 .claude/hooks/path-guard/README.md        | 6 +++---
 .claude/hooks/path-guard/segments.mts     | 4 ++--
 .claude/hooks/token-guard/README.md       | 6 +++---
 .claude/skills/_shared/path-guard-rule.md | 4 ++--
 CLAUDE.md                                 | 4 ++--
 pnpm-workspace.yaml                       | 9 +++++++++
 scripts/xport-schema.mts                  | 2 +-
 8 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md
index 97f399e9..04d4b138 100644
--- a/.claude/agents/security-reviewer.md
+++ b/.claude/agents/security-reviewer.md
@@ -18,7 +18,7 @@ Apply these rules from CLAUDE.md exactly:
 
 1. **Secrets**: Hardcoded API keys, passwords, tokens, private keys in code or config
 2. **Injection**: Command injection via shell: true or string interpolation in spawn/exec. Path traversal in file operations.
-3. **Dependencies**: npx/dlx usage. Unpinned versions (^ or ~). Missing minimumReleaseAge bypass justification. # zizmor: documentation-checklist
+3. **Dependencies**: npx/dlx usage. Unpinned versions (^ or ~). Missing soak-window bypass justification (pnpm-workspace.yaml `minimumReleaseAgeExclude`). # zizmor: documentation-checklist
 4. **File operations**: fs.rm without safeDelete. process.chdir usage. fetch() usage (must use lib's httpRequest).
 5. **GitHub Actions**: Unpinned action versions (must use full SHA). Secrets outside env blocks. Template injection from untrusted inputs.
 6. **Error handling**: Sensitive data in error messages. Stack traces exposed to users.
diff --git a/.claude/hooks/path-guard/README.md b/.claude/hooks/path-guard/README.md
index 523a31b4..2dee9c19 100644
--- a/.claude/hooks/path-guard/README.md
+++ b/.claude/hooks/path-guard/README.md
@@ -1,6 +1,6 @@
 # path-guard
 
-Claude Code `PreToolUse` hook that refuses `Edit`/`Write` tool calls that would *construct* a multi-segment build/output path inline in a `.mts` or `.cts` file. Mandatory across the Socket fleet — every repo ships this file byte-for-byte via `scripts/sync-scaffolding.mjs`.
+Claude Code `PreToolUse` hook that refuses `Edit`/`Write` tool calls that would *construct* a multi-segment build/output path inline in a `.mts` or `.cts` file. Mandatory across the Socket fleet — every repo ships this file byte-for-byte via `scripts/sync-scaffolding.mts`.
 
 **Mantra: 1 path, 1 reference.**
 
@@ -57,10 +57,10 @@ Adding a new detection pattern: update `STAGE_SEGMENTS` (or `KNOWN_SIBLING_PACKA
 
 ## Updating across the fleet
 
-This file is in `IDENTICAL_FILES` in `scripts/sync-scaffolding.mjs` (in `socket-repo-template`). After editing, run from `socket-repo-template`:
+This file is in `IDENTICAL_FILES` in `scripts/sync-scaffolding.mts` (in `socket-repo-template`). After editing, run from `socket-repo-template`:
 
 ```bash
-node scripts/sync-scaffolding.mjs --all --fix
+node scripts/sync-scaffolding.mts --all --fix
 ```
 
 to propagate the change to every fleet repo.
diff --git a/.claude/hooks/path-guard/segments.mts b/.claude/hooks/path-guard/segments.mts
index 891d0b8b..e2e4f4b8 100644
--- a/.claude/hooks/path-guard/segments.mts
+++ b/.claude/hooks/path-guard/segments.mts
@@ -6,7 +6,7 @@
 // consumers import from here so they can never drift apart.
 //
 // Synced byte-identically across the Socket fleet via
-// socket-repo-template/scripts/sync-scaffolding.mjs (IDENTICAL_FILES).
+// socket-repo-template/scripts/sync-scaffolding.mts (IDENTICAL_FILES).
 // When adding a new stage/build-root/mode/sibling, edit this file in
 // the template and re-sync.
 
@@ -41,7 +41,7 @@ export const MODE_SEGMENTS = new Set(['dev', 'prod', 'shared'])
 // Socket fleet — the gate is byte-identical via sync-scaffolding, so
 // listing every fleet package keeps Rule B firing in any repo. When a
 // new package joins the workspace, add it here and propagate via
-// `node scripts/sync-scaffolding.mjs --all --fix` from
+// `node scripts/sync-scaffolding.mts --all --fix` from
 // socket-repo-template.
 export const KNOWN_SIBLING_PACKAGES = new Set([
   // socket-btm
diff --git a/.claude/hooks/token-guard/README.md b/.claude/hooks/token-guard/README.md
index 9cba28a5..3b1ae32a 100644
--- a/.claude/hooks/token-guard/README.md
+++ b/.claude/hooks/token-guard/README.md
@@ -1,6 +1,6 @@
 # token-guard
 
-Claude Code `PreToolUse` hook that refuses Bash tool calls that would leak secrets to tool output. Mandatory across the Socket fleet — every repo ships this file byte-for-byte via `scripts/sync-scaffolding.mjs`.
+Claude Code `PreToolUse` hook that refuses Bash tool calls that would leak secrets to tool output. Mandatory across the Socket fleet — every repo ships this file byte-for-byte via `scripts/sync-scaffolding.mts`.
 
 ## What it blocks
 
@@ -48,10 +48,10 @@ Adding new token-shape detections: update `LITERAL_TOKEN_PATTERNS` in `index.mts
 
 ## Updating across the fleet
 
-This file is in `IDENTICAL_FILES` in `scripts/sync-scaffolding.mjs`. After editing, run from `socket-repo-template`:
+This file is in `IDENTICAL_FILES` in `scripts/sync-scaffolding.mts`. After editing, run from `socket-repo-template`:
 
 ```bash
-node scripts/sync-scaffolding.mjs --all --fix
+node scripts/sync-scaffolding.mts --all --fix
 ```
 
 to propagate the change to every fleet repo.
diff --git a/.claude/skills/_shared/path-guard-rule.md b/.claude/skills/_shared/path-guard-rule.md
index fa42a32e..2447f8b7 100644
--- a/.claude/skills/_shared/path-guard-rule.md
+++ b/.claude/skills/_shared/path-guard-rule.md
@@ -1,7 +1,7 @@
 <!--
 Shared snippet — the canonical "1 path, 1 reference" rule text.
 Synced byte-identical across the Socket fleet via socket-repo-template's
-sync-scaffolding.mjs (SHARED_SKILL_FILES).
+sync-scaffolding.mts (SHARED_SKILL_FILES).
 
 This file is the source of truth for the rule's wording. Three artifacts
 embed (or paraphrase) it:
@@ -10,7 +10,7 @@ embed (or paraphrase) it:
   2. .claude/hooks/path-guard/README.md — what the hook blocks.
   3. .claude/skills/path-guard/SKILL.md — what the skill enforces.
 
-If the wording changes here, re-run `node scripts/sync-scaffolding.mjs
+If the wording changes here, re-run `node scripts/sync-scaffolding.mts
 --all --fix` from socket-repo-template to propagate.
 -->
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 5312f464..6b609fd0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,7 +2,7 @@
 
 🚨 **MANDATORY**: Act as principal-level engineer with deep expertise in TypeScript, Node.js, and SDK development.
 
-<!-- BEGIN FLEET-CANONICAL — sync via socket-repo-template/scripts/sync-scaffolding.mjs. Do not edit downstream. -->
+<!-- BEGIN FLEET-CANONICAL — sync via socket-repo-template/scripts/sync-scaffolding.mts. Do not edit downstream. -->
 
 ## 📚 Fleet Standards
 
@@ -59,7 +59,7 @@ The umbrella rule: never run a git command that mutates state belonging to a pat
 
 - **Package manager**: `pnpm`. Run scripts via `pnpm run foo --flag`, never `foo:bar`. After `package.json` edits, `pnpm install`.
 - 🚨 NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use `pnpm exec <package>` or `pnpm run <script>` # socket-hook: allow npx
-- **`minimumReleaseAge`** — never add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding (security control).
+- **Soak window** (pnpm-workspace.yaml `minimumReleaseAge`, default 7 days) — never add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding (security control).
 - **Backward compatibility** — FORBIDDEN to maintain. Actively remove when encountered.
 
 ### Code style
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 23750b22..5a73c388 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -45,6 +45,15 @@ minimumReleaseAgeExclude:
   - '@socketregistry/*'
   - '@socketsecurity/*'
 
+# Refuse transitive dependencies declared via git/tarball/local-tarball
+# specs — an npm package shouldn't be allowed to drag in a git URL we
+# don't control (bypasses npm registry validation, no provenance, no
+# soak window). Direct git deps are still allowed (the test suite at
+# pnpm/pkg-manager/core/test/install/blockExoticSubdeps.ts confirms
+# this). pnpm's current default is `false`; declared explicitly so a
+# future flip can't silently change install behavior.
+blockExoticSubdeps: true
+
 # Pin exact versions on `pnpm add`. Catalog and overrides should
 # also be exact pins (5.24.0, not ^5.24.0).
 saveExact: true
diff --git a/scripts/xport-schema.mts b/scripts/xport-schema.mts
index aa6c0d04..f063a0d6 100644
--- a/scripts/xport-schema.mts
+++ b/scripts/xport-schema.mts
@@ -10,7 +10,7 @@
  *     `@socketsecurity/lib/validation/validate-schema`
  *
  * Byte-identical across socket-tui / socket-btm / socket-sdxgen / ultrathink /
- * socket-registry / socket-repo-template via sync-scaffolding.mjs.
+ * socket-registry / socket-repo-template via sync-scaffolding.mts.
  */
 
 import { Type, type Static } from '@sinclair/typebox'

From bc385a0d8f529dd6a18c9bd54b046ca3715a3bcf Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Fri, 1 May 2026 12:45:35 -0400
Subject: [PATCH 11/17] chore(publish): pin publishConfig {access:public,
 provenance:true} on root manifest

Provenance attestation becomes a property of the package, not a
property of the workflow's --provenance flag. Survives any future
emergency-publish path that bypasses provenance.yml. access: public
also load-bears for first-publish of @scoped packages on a fresh
npm registry session.

Pre-existing iocraft test failures unrelated; --no-verify per
session-wide authorization.
---
 package.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/package.json b/package.json
index f27ff047..39aa1626 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,10 @@
   "description": "SDK for the Socket API client",
   "homepage": "https://github.com/SocketDev/socket-sdk-js",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "author": {
     "name": "Socket Inc",
     "email": "eng@socket.dev",

From 19f880975738d9f8f2dc3c9ee65119cdfa456f86 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Fri, 1 May 2026 12:47:51 -0400
Subject: [PATCH 12/17] refactor(publish): stage to os.tmpdir() before npm
 publish
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Working tree is never mutated during publish; the staged copy is
what `npm publish` runs against. Eliminates a class of "interrupted
publish leaves dirty git status" incidents:

- Run `pnpm publish:ci` against the live tree
- Operator hits Ctrl-C mid-publish (or the runner times out)
- Working tree was being modified in-place during publish; recovery
  is awkward, version-bump committed but tarball not pushed, etc.

After this change: tmpdir staging via fs.cp at the start of
publishPackage(); npm publish runs with cwd=staged; try/finally +
SIGINT/SIGTERM handlers feed safeDelete()/safeDeleteSync() so the
tmpdir is reaped on every exit path.

Locally validated: dry-run on fresh build produces identical npm
publish output, working tree stays clean throughout. The staged
copy filter excludes node_modules / dotfiles / pnpm-lock.yaml — npm
publish then enforces the package's `files` field on the staged
copy as it would on the working tree.

Pre-existing iocraft test failures unrelated; --no-verify per
session-wide authorization.
---
 scripts/publish.mts | 130 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 101 insertions(+), 29 deletions(-)

diff --git a/scripts/publish.mts b/scripts/publish.mts
index a4a880bd..8d0ccbf8 100644
--- a/scripts/publish.mts
+++ b/scripts/publish.mts
@@ -6,11 +6,13 @@
 
 import { spawn } from 'node:child_process'
 import { existsSync, promises as fs } from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
 import { parseArgs } from '@socketsecurity/lib/argv/parse'
+import { safeDelete, safeDeleteSync } from '@socketsecurity/lib/fs'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
 
 const logger = getDefaultLogger()
@@ -244,6 +246,41 @@ interface PublishOptions {
   tag?: string
 }
 
+/**
+ * Stage the publishable files into a fresh os.tmpdir() subdir and
+ * return its path. The staged copy is what `npm publish` is invoked
+ * against — the working tree is never mutated. Cleanup is the
+ * caller's responsibility (use `safeDelete()` in a finally block;
+ * SIGINT/SIGTERM handlers should `safeDeleteSync()`).
+ *
+ * The filter respects the package's `files` array implicitly by
+ * letting `npm publish` itself enforce inclusion — staging copies
+ * everything except node_modules/lockfile/dotfile noise. npm reads
+ * the staged package.json's `files` field for the actual publish
+ * manifest.
+ */
+async function stageForPublish(): Promise<string> {
+  const stageRoot = await fs.mkdtemp(
+    path.join(os.tmpdir(), `socket-sdk-publish-${process.pid}-`),
+  )
+  await fs.cp(rootPath, stageRoot, {
+    recursive: true,
+    dereference: true,
+    filter: src => {
+      const base = path.basename(src)
+      return (
+        base !== 'node_modules' &&
+        base !== '.git' &&
+        base !== '.gitignore' &&
+        base !== '.gitkeep' &&
+        !base.startsWith('.pnpm') &&
+        base !== 'pnpm-lock.yaml'
+      )
+    },
+  })
+  return stageRoot
+}
+
 /**
  * Publish a single package.
  */
@@ -267,42 +304,77 @@ async function publishPackage(options: PublishOptions = {}): Promise<boolean> {
   }
   log.done('Version check complete')
 
-  // Prepare publish args.
-  const publishArgs = ['publish', '--access', access, '--tag', tag]
-
-  // Add provenance attestation in CI only. `npm publish --provenance`
-  // requires the GitHub Actions OIDC id-token endpoint; running locally
-  // fails with "Provenance generation in GitHub Actions requires
-  // 'id-token: write' permission". Gated so local non-dry-run publishes
-  // (emergency cases) still work.
-  if (!dryRun && process.env['GITHUB_ACTIONS'] === 'true') {
-    publishArgs.push('--provenance')
+  // Stage to os.tmpdir() so the working tree never mutates during
+  // publish. If a hook (or the operator's signal) interrupts mid-
+  // publish, `git status` stays clean and the tmpdir is reaped on
+  // the next exit.
+  log.progress('Staging package contents')
+  const stageRoot = await stageForPublish()
+
+  // SIGINT/SIGTERM handlers reap the staging dir synchronously
+  // because the Node event loop unwinds before async work settles
+  // when terminating. Idempotent — multiple registrations are fine.
+  const cleanup = (): void => {
+    try {
+      safeDeleteSync(stageRoot)
+    } catch {
+      /* swallow during teardown */
+    }
   }
+  process.once('SIGINT', () => {
+    log.warn('SIGINT — cleaning up staging root')
+    cleanup()
+    process.exit(130)
+  })
+  process.once('SIGTERM', () => {
+    log.warn('SIGTERM — cleaning up staging root')
+    cleanup()
+    process.exit(143)
+  })
+  log.done(`Staged to ${stageRoot}`)
 
-  if (dryRun) {
-    publishArgs.push('--dry-run')
-  }
+  try {
+    // Prepare publish args.
+    const publishArgs = ['publish', '--access', access, '--tag', tag]
+
+    // Add provenance attestation in CI only. `npm publish
+    // --provenance` requires the GitHub Actions OIDC id-token
+    // endpoint; running locally fails with "Provenance generation in
+    // GitHub Actions requires 'id-token: write' permission". Gated
+    // so local non-dry-run publishes (emergency cases) still work.
+    if (!dryRun && process.env['GITHUB_ACTIONS'] === 'true') {
+      publishArgs.push('--provenance')
+    }
 
-  if (otp) {
-    publishArgs.push('--otp', otp)
-  }
+    if (dryRun) {
+      publishArgs.push('--dry-run')
+    }
 
-  // Publish.
-  log.progress(dryRun ? 'Running dry-run publish' : 'Publishing to npm')
-  const publishCode = await runCommand('npm', publishArgs)
+    if (otp) {
+      publishArgs.push('--otp', otp)
+    }
 
-  if (publishCode !== 0) {
-    log.failed('Publish failed')
-    return false
-  }
+    // Publish from the staged copy, not the working tree.
+    log.progress(dryRun ? 'Running dry-run publish' : 'Publishing to npm')
+    const publishCode = await runCommand('npm', publishArgs, {
+      cwd: stageRoot,
+    })
 
-  if (dryRun) {
-    log.done('Dry-run publish complete')
-  } else {
-    log.done(`Published ${packageName}@${version} to npm`)
-  }
+    if (publishCode !== 0) {
+      log.failed('Publish failed')
+      return false
+    }
 
-  return true
+    if (dryRun) {
+      log.done('Dry-run publish complete')
+    } else {
+      log.done(`Published ${packageName}@${version} to npm`)
+    }
+
+    return true
+  } finally {
+    await safeDelete(stageRoot)
+  }
 }
 
 interface PushTagOptions {

From f610428044bb497b167fbdf8c22c6e2a5c98e80a Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Fri, 1 May 2026 12:51:10 -0400
Subject: [PATCH 13/17] refactor(publish): use pnpm publish (not npm) +
 --ignore-scripts for staged copy

Switch the staged-publish from `npm publish` to `pnpm publish`,
matching the fleet's package manager. Adds two required flags:

- `--no-git-checks`: the staged tmpdir has no git history; pnpm's
  default would refuse to publish without one.
- `--ignore-scripts`: the prepublishOnly guard in source package.json
  exists to refuse direct `pnpm publish` runs from the working tree.
  The staged orchestrated publish already validated its inputs; the
  guard's purpose is moot here. Skipping it lets the staged copy
  stay byte-identical to source.

Locally validated: dry-run + force publishes through cleanly. The
prior implementation's `npm publish` invocation hit a wall on
prepublishOnly, which `pnpm publish --ignore-scripts` resolves.
---
 scripts/publish.mts | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/scripts/publish.mts b/scripts/publish.mts
index 8d0ccbf8..8c61e49f 100644
--- a/scripts/publish.mts
+++ b/scripts/publish.mts
@@ -335,9 +335,23 @@ async function publishPackage(options: PublishOptions = {}): Promise<boolean> {
 
   try {
     // Prepare publish args.
-    const publishArgs = ['publish', '--access', access, '--tag', tag]
-
-    // Add provenance attestation in CI only. `npm publish
+    const publishArgs = [
+      'publish',
+      '--access',
+      access,
+      '--tag',
+      tag,
+      // The staged tmpdir has no git history; --no-git-checks tells
+      // pnpm not to require a clean working tree there.
+      '--no-git-checks',
+      // The staged copy is what we're authorizing to ship; the
+      // prepublishOnly guard in package.json is meant to refuse
+      // *direct* `pnpm publish` runs from the working tree, not
+      // this orchestrated tmpdir publish.
+      '--ignore-scripts',
+    ]
+
+    // Add provenance attestation in CI only. `pnpm publish
     // --provenance` requires the GitHub Actions OIDC id-token
     // endpoint; running locally fails with "Provenance generation in
     // GitHub Actions requires 'id-token: write' permission". Gated
@@ -356,7 +370,7 @@ async function publishPackage(options: PublishOptions = {}): Promise<boolean> {
 
     // Publish from the staged copy, not the working tree.
     log.progress(dryRun ? 'Running dry-run publish' : 'Publishing to npm')
-    const publishCode = await runCommand('npm', publishArgs, {
+    const publishCode = await runCommand('pnpm', publishArgs, {
       cwd: stageRoot,
     })
 

From 4982fe4047faa4b4034c4dba326c2e68a0b9439e Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Fri, 1 May 2026 14:20:04 -0400
Subject: [PATCH 14/17] =?UTF-8?q?chore(deps):=20bump=20@socketsecurity/lib?=
 =?UTF-8?q?=205.25.1=20=E2=86=92=205.26.1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Picks up the v5.26.1 fixes (case-insensitive default + Windows
forward-slash normalization in `globs.glob` / `globSync` /
`getGlobMatcher`, narrow matchesGlob fast-path, .then→async/await
sweep). Sdk-js call sites don't touch any v5.26.1 BREAKING
surfaces (effects/{text-shimmer,ultra,types}, themes barrel,
releases/github barrel) — clean version bump.
---
 package.json   |  2 +-
 pnpm-lock.yaml | 17 +++++++++++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 39aa1626..55721e56 100644
--- a/package.json
+++ b/package.json
@@ -77,7 +77,7 @@
     "@babel/traverse": "7.26.4",
     "@babel/types": "7.26.3",
     "@oxlint/migrate": "1.52.0",
-    "@socketsecurity/lib": "5.25.1",
+    "@socketsecurity/lib": "5.26.1",
     "@sveltejs/acorn-typescript": "1.0.8",
     "@types/babel__traverse": "7.28.0",
     "@types/node": "24.9.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6c8de19f..e7e73631 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -91,8 +91,8 @@ importers:
         specifier: 0.34.49
         version: 0.34.49
       '@socketsecurity/lib':
-        specifier: 5.25.1
-        version: 5.25.1(typescript@5.9.3)
+        specifier: 5.26.1
+        version: 5.26.1(typescript@5.9.3)
       '@sveltejs/acorn-typescript':
         specifier: 1.0.8
         version: 1.0.8(acorn@8.15.0)
@@ -1300,6 +1300,15 @@ packages:
       typescript:
         optional: true
 
+  '@socketsecurity/lib@5.26.1':
+    resolution: {integrity: sha512-ppyhOC/vPBY0gZVRtzNpmf/8nodILERmNV8J62pzVo7GvAB9S1q0/k/vSF2tor2NJEDtim+m6N+J5qtQ0mR99A==}
+    engines: {node: '>=22', pnpm: '>=11.0.0-rc.0'}
+    peerDependencies:
+      typescript: '>=5.0.0'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   '@socketsecurity/sdk@4.0.1':
     resolution: {integrity: sha512-fe3DQp2dFwhc0G6Za36GIMSV+QaPAP5L96K3ZOtywt9nhbwxc9IQwqzdOVztdn5Rbez3t9EHU9Esj24/hWdP0g==}
     engines: {node: '>=18.20.8', pnpm: '>=11.0.0-rc.0'}
@@ -3028,6 +3037,10 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
+  '@socketsecurity/lib@5.26.1(typescript@5.9.3)':
+    optionalDependencies:
+      typescript: 5.9.3
+
   '@socketsecurity/sdk@4.0.1': {}
 
   '@standard-schema/spec@1.1.0': {}

From 8606972b7a90ee50a288c5d2993248f4373fb193 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 3 May 2026 19:00:11 -0400
Subject: [PATCH 15/17] chore: adopt socket-repo-template kind config + schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the per-repo socket-repo-template config + its schema:

- `.socket-repo-template.json` — declares this repo's kind
  (single-package) + schemaVersion. Read by socket-repo-template's
  sync-scaffolding kind-aware checker.
- `scripts/socket-repo-template-schema.mts` — TypeBox source of truth
  for the config shape.
- `scripts/socket-repo-template-emit-schema.mts` — emitter that
  regenerates the JSON Schema from the TypeBox source.
- `socket-repo-template-schema.json` — generated draft 2020-12 JSON
  Schema (referenced by `.socket-repo-template.json`'s `$schema` for
  editor autocompletion).

Synced byte-identical from socket-repo-template@5ad601c.
---
 .socket-repo-template.json                   |   6 +
 scripts/socket-repo-template-emit-schema.mts |  32 +++
 scripts/socket-repo-template-schema.mts      | 263 +++++++++++++++++++
 socket-repo-template-schema.json             | 167 ++++++++++++
 4 files changed, 468 insertions(+)
 create mode 100644 .socket-repo-template.json
 create mode 100644 scripts/socket-repo-template-emit-schema.mts
 create mode 100644 scripts/socket-repo-template-schema.mts
 create mode 100644 socket-repo-template-schema.json

diff --git a/.socket-repo-template.json b/.socket-repo-template.json
new file mode 100644
index 00000000..2668dabe
--- /dev/null
+++ b/.socket-repo-template.json
@@ -0,0 +1,6 @@
+{
+  "$schema": "./socket-repo-template-schema.json",
+  "schemaVersion": 1,
+  "repoName": "socket-sdk-js",
+  "kind": "single-package"
+}
diff --git a/scripts/socket-repo-template-emit-schema.mts b/scripts/socket-repo-template-emit-schema.mts
new file mode 100644
index 00000000..458a942c
--- /dev/null
+++ b/scripts/socket-repo-template-emit-schema.mts
@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Emit `socket-repo-template-schema.json` from the
+ * TypeBox source.
+ *
+ * Run via `pnpm run socket-repo-template:emit-schema` from a fleet
+ * repo (the worktree where TypeBox is installed). Mirrors the xport
+ * emit pattern.
+ */
+
+import { writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import { SocketRepoTemplateConfigSchema } from './socket-repo-template-schema.mts'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(__dirname, '..')
+const outPath = path.join(rootDir, 'socket-repo-template-schema.json')
+
+const enriched = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://github.com/SocketDev/socket-repo-template-schema.json',
+  title: 'socket-repo-template per-repo config',
+  ...SocketRepoTemplateConfigSchema,
+}
+
+writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8')
+logger.success(`wrote ${path.relative(rootDir, outPath)}`)
diff --git a/scripts/socket-repo-template-schema.mts b/scripts/socket-repo-template-schema.mts
new file mode 100644
index 00000000..6b544a6f
--- /dev/null
+++ b/scripts/socket-repo-template-schema.mts
@@ -0,0 +1,263 @@
+/**
+ * @fileoverview TypeBox schema for `.socket-repo-template.json` — the
+ * per-fleet-repo config consumed by `sync-scaffolding`.
+ *
+ * Each fleet repo (socket-lib, socket-cli, ultrathink, …) ships a
+ * `.socket-repo-template.json` at its root declaring its kind +
+ * any per-repo opt-ins. The runner reads it to decide which optional
+ * files the repo is expected to ship and which it must not ship.
+ *
+ * Source-of-truth flow:
+ *   - This TypeBox source → `Static<typeof SocketRepoTemplateConfigSchema>`
+ *     for typed reads in the runner.
+ *   - `socket-repo-template-emit-schema.mts` writes
+ *     `socket-repo-template-schema.json` (draft 2020-12) at the repo root.
+ *   - `.socket-repo-template.json` references the JSON Schema via its
+ *     `$schema` field for IDE autocompletion.
+ *
+ * Byte-identical across the fleet via sync-scaffolding's IDENTICAL_FILES.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+
+// ---------------------------------------------------------------------------
+// Kind enum.
+// ---------------------------------------------------------------------------
+
+const KindSchema = Type.Union(
+  [
+    Type.Literal('single-package'),
+    Type.Literal('mono-no-native'),
+    Type.Literal('consumer'),
+    Type.Literal('producer'),
+    Type.Literal('both'),
+    Type.Literal('lang-ports'),
+  ],
+  {
+    description:
+      'Fleet repo category. Determines which opt-in files the repo must ship and which it must not. See README.md "Fleet kinds" for the table.',
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Hooks block — git hook variant selection.
+// ---------------------------------------------------------------------------
+
+const HooksSchema = Type.Object(
+  {
+    enablePrePush: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true.',
+      }),
+    ),
+    enableCommitMsg: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true.',
+      }),
+    ),
+    enablePreCommit: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true.',
+      }),
+    ),
+    preCommitVariant: Type.Optional(
+      Type.Union([Type.Literal('lint-only'), Type.Literal('lint-test')], {
+        description:
+          '`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`.',
+      }),
+    ),
+  },
+  { description: 'Git-hook opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Scripts block — package.json script declarations.
+// ---------------------------------------------------------------------------
+
+const ScriptsSchema = Type.Object(
+  {
+    required: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies.',
+      }),
+    ),
+    optional: Type.Optional(
+      Type.Record(Type.String(), Type.Boolean(), {
+        description:
+          'Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out.',
+      }),
+    ),
+    bodyExempt: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only.',
+      }),
+    ),
+  },
+  { description: 'package.json script tracking overrides.' },
+)
+
+// ---------------------------------------------------------------------------
+// Lint block — oxlint profile selection.
+// ---------------------------------------------------------------------------
+
+const LintSchema = Type.Object(
+  {
+    profile: Type.Optional(
+      Type.Union([Type.Literal('standard'), Type.Literal('rich')], {
+        description:
+          '`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted.',
+      }),
+    ),
+  },
+  { description: 'oxlint profile.' },
+)
+
+// ---------------------------------------------------------------------------
+// Workflows block — GitHub Actions opt-ins.
+// ---------------------------------------------------------------------------
+
+const WorkflowsSchema = Type.Object(
+  {
+    ci: Type.Optional(
+      Type.Boolean({ description: 'Ship `.github/workflows/ci.yml`.' }),
+    ),
+    weeklyUpdate: Type.Optional(
+      Type.Boolean({
+        description: 'Ship `.github/workflows/weekly-update.yml`.',
+      }),
+    ),
+    provenance: Type.Optional(
+      Type.Boolean({
+        description:
+          'Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today.',
+      }),
+    ),
+    requirePinnedFullSha: Type.Optional(
+      Type.Boolean({
+        description:
+          'Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer.',
+      }),
+    ),
+  },
+  { description: 'CI workflow opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Claude block — opt-in agents/skills/commands.
+// ---------------------------------------------------------------------------
+
+const ClaudeSchema = Type.Object(
+  {
+    includeSecurityScanSkill: Type.Optional(
+      Type.Boolean({
+        description: 'Ship `.claude/skills/security-scan/SKILL.md`.',
+      }),
+    ),
+    includeSharedSkills: Type.Optional(
+      Type.Boolean({
+        description:
+          'Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build.',
+      }),
+    ),
+    includeUpdatingSkill: Type.Optional(
+      Type.Boolean({
+        description:
+          'Ship the dependency-update skill. Reserved — no consumer wired today.',
+      }),
+    ),
+  },
+  { description: 'Claude Code opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Workspace block — pnpm-workspace.yaml derived settings.
+// ---------------------------------------------------------------------------
+
+const WorkspaceSchema = Type.Object(
+  {
+    allowBuilds: Type.Optional(
+      Type.Record(Type.String(), Type.Boolean(), {
+        description:
+          'pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts.',
+      }),
+    ),
+    blockExoticSubdeps: Type.Optional(
+      Type.Boolean({
+        description:
+          'Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally.',
+      }),
+    ),
+    minimumReleaseAge: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        description:
+          'Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days).',
+      }),
+    ),
+    minimumReleaseAgeExclude: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here.',
+      }),
+    ),
+    resolutionMode: Type.Optional(
+      Type.Union([Type.Literal('highest'), Type.Literal('lowest-direct')], {
+        description: 'pnpm `resolutionMode`. Fleet default `highest`.',
+      }),
+    ),
+    trustPolicy: Type.Optional(
+      Type.Union([Type.Literal('no-downgrade'), Type.Literal('match-spec')], {
+        description: 'pnpm `trustPolicy`. Fleet default `no-downgrade`.',
+      }),
+    ),
+  },
+  {
+    description:
+      'pnpm-workspace.yaml setting hints. The runner reads from the YAML; this block exists for repos that prefer to declare intent in JSON.',
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Top-level config.
+// ---------------------------------------------------------------------------
+
+export const SocketRepoTemplateConfigSchema = Type.Object(
+  {
+    $schema: Type.Optional(
+      Type.String({
+        description:
+          'JSON Schema reference for editor autocompletion. Conventionally `./socket-repo-template-schema.json`.',
+      }),
+    ),
+    schemaVersion: Type.Literal(1, {
+      description:
+        'Schema version. Bump on breaking changes; readers gate on it.',
+    }),
+    repoName: Type.String({
+      pattern: '^[a-z0-9][a-z0-9-]*$',
+      description:
+        'Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for kind-independent exemptions like the oxlint `socket-lib` carve-out.',
+    }),
+    kind: KindSchema,
+    hooks: Type.Optional(HooksSchema),
+    scripts: Type.Optional(ScriptsSchema),
+    lint: Type.Optional(LintSchema),
+    workflows: Type.Optional(WorkflowsSchema),
+    claude: Type.Optional(ClaudeSchema),
+    workspace: Type.Optional(WorkspaceSchema),
+  },
+  {
+    description:
+      'Per-repo socket-repo-template config. Lives at the fleet repo root as `.socket-repo-template.json`.',
+  },
+)
+
+export type SocketRepoTemplateConfig = Static<
+  typeof SocketRepoTemplateConfigSchema
+>
+export type Kind = Static<typeof KindSchema>
diff --git a/socket-repo-template-schema.json b/socket-repo-template-schema.json
new file mode 100644
index 00000000..56a0b3c0
--- /dev/null
+++ b/socket-repo-template-schema.json
@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/SocketDev/socket-repo-template-schema.json",
+  "title": "socket-repo-template per-repo config",
+  "type": "object",
+  "description": "Per-repo socket-repo-template config. Lives at the fleet repo root as `.socket-repo-template.json`.",
+  "required": ["schemaVersion", "repoName", "kind"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor autocompletion. Conventionally `./socket-repo-template-schema.json`."
+    },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Schema version. Bump on breaking changes; readers gate on it."
+    },
+    "repoName": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for kind-independent exemptions like the oxlint `socket-lib` carve-out."
+    },
+    "kind": {
+      "description": "Fleet repo category. Determines which opt-in files the repo must ship and which it must not. See README.md \"Fleet kinds\" for the table.",
+      "enum": [
+        "single-package",
+        "mono-no-native",
+        "consumer",
+        "producer",
+        "both",
+        "lang-ports"
+      ]
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Git-hook opt-ins.",
+      "additionalProperties": false,
+      "properties": {
+        "enablePrePush": {
+          "type": "boolean",
+          "description": "Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true."
+        },
+        "enableCommitMsg": {
+          "type": "boolean",
+          "description": "Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true."
+        },
+        "enablePreCommit": {
+          "type": "boolean",
+          "description": "Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true."
+        },
+        "preCommitVariant": {
+          "enum": ["lint-only", "lint-test"],
+          "description": "`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`."
+        }
+      }
+    },
+    "scripts": {
+      "type": "object",
+      "description": "package.json script tracking overrides.",
+      "additionalProperties": false,
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies."
+        },
+        "optional": {
+          "type": "object",
+          "additionalProperties": { "type": "boolean" },
+          "description": "Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out."
+        },
+        "bodyExempt": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only."
+        }
+      }
+    },
+    "lint": {
+      "type": "object",
+      "description": "oxlint profile.",
+      "additionalProperties": false,
+      "properties": {
+        "profile": {
+          "enum": ["standard", "rich"],
+          "description": "`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted."
+        }
+      }
+    },
+    "workflows": {
+      "type": "object",
+      "description": "CI workflow opt-ins.",
+      "additionalProperties": false,
+      "properties": {
+        "ci": {
+          "type": "boolean",
+          "description": "Ship `.github/workflows/ci.yml`."
+        },
+        "weeklyUpdate": {
+          "type": "boolean",
+          "description": "Ship `.github/workflows/weekly-update.yml`."
+        },
+        "provenance": {
+          "type": "boolean",
+          "description": "Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today."
+        },
+        "requirePinnedFullSha": {
+          "type": "boolean",
+          "description": "Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer."
+        }
+      }
+    },
+    "claude": {
+      "type": "object",
+      "description": "Claude Code opt-ins.",
+      "additionalProperties": false,
+      "properties": {
+        "includeSecurityScanSkill": {
+          "type": "boolean",
+          "description": "Ship `.claude/skills/security-scan/SKILL.md`."
+        },
+        "includeSharedSkills": {
+          "type": "boolean",
+          "description": "Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build."
+        },
+        "includeUpdatingSkill": {
+          "type": "boolean",
+          "description": "Ship the dependency-update skill. Reserved — no consumer wired today."
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "description": "pnpm-workspace.yaml setting hints. The runner reads from the YAML; this block exists for repos that prefer to declare intent in JSON.",
+      "additionalProperties": false,
+      "properties": {
+        "allowBuilds": {
+          "type": "object",
+          "additionalProperties": { "type": "boolean" },
+          "description": "pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts."
+        },
+        "blockExoticSubdeps": {
+          "type": "boolean",
+          "description": "Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally."
+        },
+        "minimumReleaseAge": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days)."
+        },
+        "minimumReleaseAgeExclude": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here."
+        },
+        "resolutionMode": {
+          "enum": ["highest", "lowest-direct"],
+          "description": "pnpm `resolutionMode`. Fleet default `highest`."
+        },
+        "trustPolicy": {
+          "enum": ["no-downgrade", "match-spec"],
+          "description": "pnpm `trustPolicy`. Fleet default `no-downgrade`."
+        }
+      }
+    }
+  }
+}

From ba9a8189aea78d8304993f85b20024961745d873 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 3 May 2026 19:20:55 -0400
Subject: [PATCH 16/17] chore: sync emit-schema scripts from
 socket-repo-template@563fd6a

Both schema emitters (`scripts/xport-emit-schema.mts`,
`scripts/socket-repo-template-emit-schema.mts`) now `pnpm exec
oxfmt` their output so the emitted JSON Schema matches what
oxfmt produces. Without this, every fleet repo that re-emits
would flag the schema as drifted on `pnpm run check --all`.

Re-emitted `socket-repo-template-schema.json` through the
formatter. (`xport.schema.json` was already at the canonical
formatted shape.)
---
 scripts/socket-repo-template-emit-schema.mts |  12 ++
 scripts/xport-emit-schema.mts                |  12 ++
 socket-repo-template-schema.json             | 198 ++++++++++++-------
 3 files changed, 154 insertions(+), 68 deletions(-)

diff --git a/scripts/socket-repo-template-emit-schema.mts b/scripts/socket-repo-template-emit-schema.mts
index 458a942c..aefd3516 100644
--- a/scripts/socket-repo-template-emit-schema.mts
+++ b/scripts/socket-repo-template-emit-schema.mts
@@ -11,6 +11,7 @@ import { writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { spawn } from '@socketsecurity/lib/spawn'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
 
 import { SocketRepoTemplateConfigSchema } from './socket-repo-template-schema.mts'
@@ -29,4 +30,15 @@ const enriched = {
 }
 
 writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8')
+
+// Run oxfmt on the output so the file matches what oxfmt would
+// produce. Without this, `pnpm run check --all` (which runs oxfmt
+// over the tree) would flag the emitted schema as drifted on every
+// repo that re-emits it. The schema is in IDENTICAL_FILES, so the
+// formatted form is the byte-canonical form fleet-wide.
+await spawn('pnpm', ['exec', 'oxfmt', outPath], {
+  cwd: rootDir,
+  stdio: 'inherit',
+})
+
 logger.success(`wrote ${path.relative(rootDir, outPath)}`)
diff --git a/scripts/xport-emit-schema.mts b/scripts/xport-emit-schema.mts
index 5bc6a1e6..a0d4e93b 100644
--- a/scripts/xport-emit-schema.mts
+++ b/scripts/xport-emit-schema.mts
@@ -12,6 +12,7 @@ import { writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { spawn } from '@socketsecurity/lib/spawn'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
 
 import { XportManifestSchema } from './xport-schema.mts'
@@ -34,4 +35,15 @@ const enriched = {
 }
 
 writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8')
+
+// Run oxfmt on the output so the file matches what oxfmt would
+// produce. Without this, `pnpm run check --all` (which runs oxfmt
+// over the tree) would flag the emitted schema as drifted on every
+// repo that re-emits it. The schema is in IDENTICAL_FILES, so the
+// formatted form is the byte-canonical form fleet-wide.
+await spawn('pnpm', ['exec', 'oxfmt', outPath], {
+  cwd: rootDir,
+  stdio: 'inherit',
+})
+
 logger.success(`wrote ${path.relative(rootDir, outPath)}`)
diff --git a/socket-repo-template-schema.json b/socket-repo-template-schema.json
index 56a0b3c0..c26fdde5 100644
--- a/socket-repo-template-schema.json
+++ b/socket-repo-template-schema.json
@@ -2,164 +2,226 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/SocketDev/socket-repo-template-schema.json",
   "title": "socket-repo-template per-repo config",
-  "type": "object",
   "description": "Per-repo socket-repo-template config. Lives at the fleet repo root as `.socket-repo-template.json`.",
+  "type": "object",
   "required": ["schemaVersion", "repoName", "kind"],
-  "additionalProperties": false,
   "properties": {
     "$schema": {
-      "type": "string",
-      "description": "JSON Schema reference for editor autocompletion. Conventionally `./socket-repo-template-schema.json`."
+      "description": "JSON Schema reference for editor autocompletion. Conventionally `./socket-repo-template-schema.json`.",
+      "type": "string"
     },
     "schemaVersion": {
+      "description": "Schema version. Bump on breaking changes; readers gate on it.",
       "const": 1,
-      "description": "Schema version. Bump on breaking changes; readers gate on it."
+      "type": "number"
     },
     "repoName": {
-      "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for kind-independent exemptions like the oxlint `socket-lib` carve-out."
+      "description": "Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for kind-independent exemptions like the oxlint `socket-lib` carve-out.",
+      "type": "string"
     },
     "kind": {
       "description": "Fleet repo category. Determines which opt-in files the repo must ship and which it must not. See README.md \"Fleet kinds\" for the table.",
-      "enum": [
-        "single-package",
-        "mono-no-native",
-        "consumer",
-        "producer",
-        "both",
-        "lang-ports"
+      "anyOf": [
+        {
+          "const": "single-package",
+          "type": "string"
+        },
+        {
+          "const": "mono-no-native",
+          "type": "string"
+        },
+        {
+          "const": "consumer",
+          "type": "string"
+        },
+        {
+          "const": "producer",
+          "type": "string"
+        },
+        {
+          "const": "both",
+          "type": "string"
+        },
+        {
+          "const": "lang-ports",
+          "type": "string"
+        }
       ]
     },
     "hooks": {
-      "type": "object",
       "description": "Git-hook opt-ins.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "enablePrePush": {
-          "type": "boolean",
-          "description": "Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true."
+          "description": "Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true.",
+          "type": "boolean"
         },
         "enableCommitMsg": {
-          "type": "boolean",
-          "description": "Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true."
+          "description": "Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true.",
+          "type": "boolean"
         },
         "enablePreCommit": {
-          "type": "boolean",
-          "description": "Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true."
+          "description": "Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true.",
+          "type": "boolean"
         },
         "preCommitVariant": {
-          "enum": ["lint-only", "lint-test"],
-          "description": "`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`."
+          "description": "`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`.",
+          "anyOf": [
+            {
+              "const": "lint-only",
+              "type": "string"
+            },
+            {
+              "const": "lint-test",
+              "type": "string"
+            }
+          ]
         }
       }
     },
     "scripts": {
-      "type": "object",
       "description": "package.json script tracking overrides.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "required": {
+          "description": "Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies.",
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies."
+          "items": {
+            "type": "string"
+          }
         },
         "optional": {
+          "description": "Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out.",
           "type": "object",
-          "additionalProperties": { "type": "boolean" },
-          "description": "Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out."
+          "patternProperties": {
+            "^(.*)$": {
+              "type": "boolean"
+            }
+          }
         },
         "bodyExempt": {
+          "description": "Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only.",
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only."
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
     "lint": {
-      "type": "object",
       "description": "oxlint profile.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "profile": {
-          "enum": ["standard", "rich"],
-          "description": "`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted."
+          "description": "`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted.",
+          "anyOf": [
+            {
+              "const": "standard",
+              "type": "string"
+            },
+            {
+              "const": "rich",
+              "type": "string"
+            }
+          ]
         }
       }
     },
     "workflows": {
-      "type": "object",
       "description": "CI workflow opt-ins.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "ci": {
-          "type": "boolean",
-          "description": "Ship `.github/workflows/ci.yml`."
+          "description": "Ship `.github/workflows/ci.yml`.",
+          "type": "boolean"
         },
         "weeklyUpdate": {
-          "type": "boolean",
-          "description": "Ship `.github/workflows/weekly-update.yml`."
+          "description": "Ship `.github/workflows/weekly-update.yml`.",
+          "type": "boolean"
         },
         "provenance": {
-          "type": "boolean",
-          "description": "Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today."
+          "description": "Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today.",
+          "type": "boolean"
         },
         "requirePinnedFullSha": {
-          "type": "boolean",
-          "description": "Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer."
+          "description": "Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer.",
+          "type": "boolean"
         }
       }
     },
     "claude": {
-      "type": "object",
       "description": "Claude Code opt-ins.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "includeSecurityScanSkill": {
-          "type": "boolean",
-          "description": "Ship `.claude/skills/security-scan/SKILL.md`."
+          "description": "Ship `.claude/skills/security-scan/SKILL.md`.",
+          "type": "boolean"
         },
         "includeSharedSkills": {
-          "type": "boolean",
-          "description": "Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build."
+          "description": "Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build.",
+          "type": "boolean"
         },
         "includeUpdatingSkill": {
-          "type": "boolean",
-          "description": "Ship the dependency-update skill. Reserved — no consumer wired today."
+          "description": "Ship the dependency-update skill. Reserved — no consumer wired today.",
+          "type": "boolean"
         }
       }
     },
     "workspace": {
-      "type": "object",
       "description": "pnpm-workspace.yaml setting hints. The runner reads from the YAML; this block exists for repos that prefer to declare intent in JSON.",
-      "additionalProperties": false,
+      "type": "object",
       "properties": {
         "allowBuilds": {
+          "description": "pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts.",
           "type": "object",
-          "additionalProperties": { "type": "boolean" },
-          "description": "pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts."
+          "patternProperties": {
+            "^(.*)$": {
+              "type": "boolean"
+            }
+          }
         },
         "blockExoticSubdeps": {
-          "type": "boolean",
-          "description": "Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally."
+          "description": "Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally.",
+          "type": "boolean"
         },
         "minimumReleaseAge": {
-          "type": "integer",
           "minimum": 0,
-          "description": "Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days)."
+          "description": "Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days).",
+          "type": "integer"
         },
         "minimumReleaseAgeExclude": {
+          "description": "Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here.",
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here."
+          "items": {
+            "type": "string"
+          }
         },
         "resolutionMode": {
-          "enum": ["highest", "lowest-direct"],
-          "description": "pnpm `resolutionMode`. Fleet default `highest`."
+          "description": "pnpm `resolutionMode`. Fleet default `highest`.",
+          "anyOf": [
+            {
+              "const": "highest",
+              "type": "string"
+            },
+            {
+              "const": "lowest-direct",
+              "type": "string"
+            }
+          ]
         },
         "trustPolicy": {
-          "enum": ["no-downgrade", "match-spec"],
-          "description": "pnpm `trustPolicy`. Fleet default `no-downgrade`."
+          "description": "pnpm `trustPolicy`. Fleet default `no-downgrade`.",
+          "anyOf": [
+            {
+              "const": "no-downgrade",
+              "type": "string"
+            },
+            {
+              "const": "match-spec",
+              "type": "string"
+            }
+          ]
         }
       }
     }

From 161dc1cf701fec28d82da1d1c8234a666aacb670 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 3 May 2026 23:31:35 -0400
Subject: [PATCH 17/17] chore: sync power-state helper from
 socket-repo-template@c23dfef
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds `scripts/power-state.mts` — fleet-canonical AC-vs-battery
detection helper. Used by long-running build/test scripts to size
their timeouts adaptively (laptops on battery throttle CPU hard,
and a static timeout tuned for AC will kill an otherwise-healthy
run on battery).

Tries `node:smol-power` first (when running inside a node-smol
binary), falls back to per-platform paths on system Node:
- macOS:   `pmset -g batt`
- Linux:   `/sys/class/power_supply/<entry>/online` direct reads
           (no shellout, no D-Bus, no UPower)
- Windows: PowerShell `Win32_Battery.BatteryStatus`

Synced byte-identical from socket-repo-template via sync-scaffolding.
---
 scripts/power-state.mts | 165 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 scripts/power-state.mts

diff --git a/scripts/power-state.mts b/scripts/power-state.mts
new file mode 100644
index 00000000..2d327006
--- /dev/null
+++ b/scripts/power-state.mts
@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Detect whether the host is currently on AC power
+ * (vs battery). Used by long-running build/test scripts to size
+ * timeouts adaptively — laptops on battery throttle CPU hard
+ * (especially macOS), and a static timeout that fits AC will kill
+ * an otherwise-healthy run on battery.
+ *
+ * Two paths, in priority order:
+ *
+ *   1. `node:smol-power` — when running inside a node-smol binary
+ *      that ships the smol_power native binding (socket-btm's custom
+ *      Node distribution). Pure C++ syscalls, sub-millisecond.
+ *
+ *   2. Shellout fallback — system Node doesn't have node:smol-power.
+ *      Each platform has a different mechanism:
+ *        * macOS:   `pmset -g batt` parses "AC Power" / "Battery Power"
+ *        * Linux:   reads /sys/class/power_supply/<entry>/online
+ *                   (no shellout, just open/read syscalls)
+ *        * Windows: PowerShell `Get-CimInstance Win32_Battery`
+ *
+ * On detection failure we conservatively assume AC — the downstream
+ * timeout becomes the shorter / more aggressive value, which is
+ * appropriate for build servers and headless CI (those environments
+ * are expected to run at full speed).
+ *
+ * Returns a Promise so callers don't block the event loop on shellout
+ * paths.
+ *
+ * Byte-identical across the fleet via socket-repo-template's
+ * sync-scaffolding (IDENTICAL_FILES).
+ */
+
+import { existsSync, promises as fs } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { spawn } from '@socketsecurity/lib/spawn'
+
+// Probe for node:smol-power. Lives in socket-btm's node-smol binary.
+// Wrapped in try/catch so this file is safe to import on system Node
+// where the module doesn't exist.
+let _smolPower: { isOnAcPower: () => boolean } | undefined
+async function getSmolPower(): Promise<typeof _smolPower> {
+  if (_smolPower !== undefined) {
+    return _smolPower
+  }
+  try {
+    const mod = await import('node:smol-power')
+    _smolPower = mod
+    return _smolPower
+  } catch {
+    _smolPower = undefined
+    return undefined
+  }
+}
+
+async function detectMacOs(): Promise<boolean> {
+  try {
+    // `pmset -g batt` on macOS prints lines like
+    //   Now drawing from 'AC Power'
+    //   Now drawing from 'Battery Power'
+    // Match the AC variant; everything else (battery, unknown) is
+    // treated as not-AC.
+    const result = await spawn('pmset', ['-g', 'batt'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return /AC Power/.test(result.stdout || '')
+  } catch {
+    return true
+  }
+}
+
+async function detectLinux(): Promise<boolean> {
+  // Linux exposes power state under /sys/class/power_supply. Each
+  // AC adapter is its own dir (`AC`, `ADP1`, `AC0`, `ACAD`, …)
+  // with an `online` file holding "1" when power is connected.
+  // Containers and headless servers often have no power_supply
+  // tree at all — treat that as AC since those environments are
+  // expected to run at full speed.
+  const psDir = '/sys/class/power_supply'
+  if (!existsSync(psDir)) {
+    return true
+  }
+  try {
+    const entries = await fs.readdir(psDir)
+    for (const entry of entries) {
+      const onlineFile = path.join(psDir, entry, 'online')
+      if (!existsSync(onlineFile)) {
+        continue
+      }
+      try {
+        const value = await fs.readFile(onlineFile, 'utf8')
+        if (value.trim() === '1') {
+          return true
+        }
+      } catch {
+        // Unreadable entry — skip; another entry may report.
+      }
+    }
+  } catch {
+    // Directory enumeration failed — fall through to AC.
+    return true
+  }
+  return false
+}
+
+async function detectWindows(): Promise<boolean> {
+  try {
+    // Windows: query the battery status via PowerShell + CIM.
+    // `Win32_Battery.BatteryStatus`:
+    //   1 = Discharging        (battery)
+    //   2 = On AC, not charging or fully charged
+    //   3..5 = Various battery states
+    //   6 = AC + charging
+    // Desktops with no battery return an empty result; treat as AC.
+    const result = await spawn(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-Command',
+        '(Get-CimInstance -ClassName Win32_Battery).BatteryStatus',
+      ],
+      { stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+    const trimmed = (result.stdout || '').trim()
+    if (trimmed === '') {
+      return true
+    }
+    const status = Number.parseInt(trimmed, 10)
+    if (Number.isNaN(status)) {
+      return true
+    }
+    return status === 2 || status === 6
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Returns `true` if the host is on AC power. Conservative on
+ * detection failure (returns `true`) — callers using this for
+ * timeout sizing prefer a longer timeout to a too-short one.
+ *
+ * Prefers the native binding (`node:smol-power`) when running
+ * inside a node-smol binary; falls back to a per-platform path
+ * (shellout on macOS / Windows, direct sysfs reads on Linux) on
+ * system Node.
+ */
+export async function isOnAcPower(): Promise<boolean> {
+  const native = await getSmolPower()
+  if (native) {
+    return native.isOnAcPower()
+  }
+  if (process.platform === 'darwin') {
+    return await detectMacOs()
+  }
+  if (process.platform === 'linux') {
+    return await detectLinux()
+  }
+  if (process.platform === 'win32') {
+    return await detectWindows()
+  }
+  // Unsupported platform; conservative default.
+  return true
+}