From a4c1fa1e73a98790ff7b68ab1cb5d25c32296076 Mon Sep 17 00:00:00 2001
From: Patrick Roza <contact@patrickroza.com>
Date: Mon, 3 Aug 2026 20:18:52 +0200
Subject: [PATCH 1/2] =?UTF-8?q?feat(agent):=20ship=20gate=20=E2=80=94=20ch?=
 =?UTF-8?q?ecks=20run=20at=20the=20push,=20not=20on=20request?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports the agent ship gate from macs-scanner, minus everything that does not
apply to a library monorepo.

`.githooks/pre-push` is a no-op for humans and for draft / no-PR pushes, and runs
the full gate on ready PRs. Drafts stay free so sharing early costs nothing.
Publishing is gated rather than forbidden: `pnpm pr:ready` is the explicit path
and plain `gh pr ready` reaches the same place, because `.tools/bin/gh` runs the
gate first and passes the command through when it is green. Nothing to remember,
and no way around it.

The gate is `pnpm check` -> `pnpm lint` -> `pnpm test`: exactly what ci.yml runs,
deliberately not a superset. There is no application to stand up and no browser
suite here, so the unit run is the whole gate — `pnpm -r --no-bail test:run` is
the closest analogue of the E2E stage the product repos gate on.

The validated HEAD SHA is cached under `.run/`, so a commit is validated once
however often it is pushed or published, and AGENTS.md now says plainly not to
hand-run these checks as routine verification. Repeatedly re-proving one commit
is the cost the gate exists to remove, not to add.

Two details carried over from what the other ports taught:

- The gate supplies its own PATH (node_modules/.bin). pnpm and the hook both
  provide it, so the dependency stays invisible until something runs the gate
  from a bare process — which the gh shim does — and it dies with "command not
  found".
- The hook scrubs git's local env vars before running, so nested git commands
  discover their own repository instead of inheriting the outer push's GIT_DIR.

Verified: the shim intercepts `gh pr ready`, runs the gate, and refuses on a
dirty worktree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .envrc                                |   6 +-
 .githooks/pre-push                    |  12 ++
 .gitignore                            |   4 +
 AGENTS.md                             |  48 ++++++--
 package.json                          |   3 +-
 scripts/agent-gh.mjs                  |  60 ++++++++++
 scripts/agent-pr-ready.mjs            |  65 +++++++++++
 scripts/agent-pre-push.mjs            | 161 ++++++++++++++++++++++++++
 scripts/install-git-hooks.mjs         |  62 ++++++++++
 scripts/lib/agent-env.mjs             |  26 +++++
 scripts/lib/agent-gh-policy.mjs       | 155 +++++++++++++++++++++++++
 scripts/lib/agent-pr-state.mjs        | 123 ++++++++++++++++++++
 scripts/lib/agent-ship-gate-cache.mjs | 121 +++++++++++++++++++
 13 files changed, 837 insertions(+), 9 deletions(-)
 create mode 100755 .githooks/pre-push
 create mode 100644 scripts/agent-gh.mjs
 create mode 100644 scripts/agent-pr-ready.mjs
 create mode 100644 scripts/agent-pre-push.mjs
 create mode 100644 scripts/install-git-hooks.mjs
 create mode 100644 scripts/lib/agent-env.mjs
 create mode 100644 scripts/lib/agent-gh-policy.mjs
 create mode 100644 scripts/lib/agent-pr-state.mjs
 create mode 100644 scripts/lib/agent-ship-gate-cache.mjs

diff --git a/.envrc b/.envrc
index 8392d159f2..03113d3dba 100644
--- a/.envrc
+++ b/.envrc
@@ -1 +1,5 @@
-use flake
\ No newline at end of file
+use flake
+
+# Repo `gh` policy shim: publishing runs the ship gate first (see AGENTS.md).
+# Installed by scripts/install-git-hooks.mjs; run `direnv allow` once after cloning.
+PATH_add .tools/bin
diff --git a/.githooks/pre-push b/.githooks/pre-push
new file mode 100755
index 0000000000..d2386cb765
--- /dev/null
+++ b/.githooks/pre-push
@@ -0,0 +1,12 @@
+# Agent-only ship gate (humans: no-op). See scripts/agent-pre-push.mjs.
+# Draft / no PR: free push. Ready PR: check + lint + test.
+# Publish: pnpm pr:ready, or raw `gh pr ready` — the shim runs the same gate first.
+#
+# Humans: SKIP_AGENT_PREPUSH=1 git push
+# Agents: never SKIP_AGENT_PREPUSH / never --no-verify
+# Nested Git commands must discover their own repositories, not inherit this
+# hook's GIT_DIR/GIT_WORK_TREE from the outer push.
+for name in $(git rev-parse --local-env-vars); do
+  unset "$name"
+done
+pnpm exec node scripts/agent-pre-push.mjs
diff --git a/.gitignore b/.gitignore
index 99d20f97aa..e98229014a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,3 +58,7 @@ run.sh
 
 # Generated publish staging directories
 packages/*/.publish/
+
+# agent gh shim (generated) + local ship-gate state
+.tools/
+.run/
diff --git a/AGENTS.md b/AGENTS.md
index a152daf982..61bcf99c55 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,11 +11,40 @@ This is the Effect App library repository, focusing on functional programming pa
 
 Always open a PR for agent work that changes the repo — do not leave finished work only on a local branch.
 
-- **Draft early**: open a draft PR as soon as there is a meaningful commit (or when starting multi-step work that will land), so review/CI can track progress while local validation is still in flight.
+- **Draft early**: open a draft PR as soon as there is a meaningful commit (or when starting multi-step work that will land), so review/CI can track progress while local validation is still in flight. Pushes to a draft are free — the gate does not run on them.
 - **Keep the PR current**: push commits as you go; update the PR body if scope shifts.
-- **Ready when done**: after mandatory validation (`pnpm lint-fix`, `pnpm check`, and relevant tests) passes, mark the PR ready for review (undraft / publish). Do not leave a finished, validated change as draft.
+- **Ready when done**: publish with `pnpm pr:ready`, or with plain `gh pr ready` — both run the ship gate first and undraft only if it passes. Do not hand-run the checks beforehand and do not leave a finished, validated change as draft.
 - **Base**: target `main` unless the work is explicitly stacked on another branch.
 
+### The gate runs the checks — you do not
+
+`.githooks/pre-push` is the agent ship gate. It is a **no-op for humans** and
+fires only for coding agents (`GROK_AGENT` / `T3_AGENT` / `AI_AGENT` / Claude /
+Cursor / Codex env markers).
+
+| Branch PR state         | Agent pre-push                    |
+| ----------------------- | --------------------------------- |
+| No open PR              | **skip** — free push              |
+| **Draft**               | **skip** — free push, share early |
+| **Ready** for review    | full ship gate                    |
+| `gh` / PR lookup failed | full ship gate (**fail closed**)  |
+
+The gate is `pnpm check` → `pnpm lint` → `pnpm test`, which is what CI runs and
+nothing more. This is a library monorepo — no application to stand up, no browser
+suite — so the unit run *is* the gate. It caches the validated HEAD SHA in
+`.run/agent-ship-gate.json`, so **one commit is validated once** however many
+times you push or publish it. Force a re-run with `AGENT_SHIP_GATE_FORCE=1`.
+
+**Do not hand-run `pnpm check` / `lint` / `test` as routine verification.**
+Validating the same commit repeatedly costs the same each time and proves nothing
+the first run did not. While iterating, narrow proof is the right tool — the one
+test you are fixing, or a typecheck of the package you touched. Whole-gate runs
+belong to the push.
+
+`.envrc` puts the `gh` shim on `PATH`; run **`direnv allow`** once after cloning
+(`command -v gh` should print `.tools/bin/gh`). Never `--no-verify`, and never set
+`SKIP_AGENT_PREPUSH` — that is the human escape hatch.
+
 ### Core Principles
 
 - **Zero Tolerance for Errors**: All automated checks must pass
@@ -48,13 +77,18 @@ Anti-patterns that mean you skipped the checklist:
 - Adding a sleep / retry to "give it time to work" instead of finding the missing wake signal.
 - Disabling a hook (`--no-verify`) or a check to make the diff land.
 
-### Mandatory Validation Steps
+### Validation
+
+The ship gate owns validation — see *The gate runs the checks — you do not*. It
+runs `pnpm check` → `pnpm lint` → `pnpm test` on publish and on pushes to a ready
+PR, once per commit.
 
-After **all** changes are made, run these from the **repo root**:
+`pnpm lint-fix` is the one thing worth running by hand, because it *writes*: it
+formats and auto-fixes across packages, and the gate only reports what it would
+have fixed. Run it when you are done editing, stage what it changes, then push.
 
-1. `pnpm lint-fix` — auto-formats and fixes lint issues across all packages; apply all resulting changes
-2. `pnpm check` — type-checks all packages (dependency changes in one package can break others); fix all reported errors
-   - If type checking continues to fail, run `pnpm clean` to clear caches, then re-run `pnpm check`
+If type checking fails in a way that makes no sense against the diff, `pnpm clean`
+clears the caches — stale incremental state produces phantom errors.
 
 <!-- - Always run tests after making changes: `pnpm test <test_file.ts>` -->
 <!-- - Build the project: `pnpm build`
diff --git a/package.json b/package.json
index 87518f7525..d5d5e9212f 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
     "lint": "pnpm -r lint",
     "circular:dist": "pnpm -r circular:dist",
     "test": "pnpm -r --no-bail test:run",
+    "pr:ready": "node scripts/agent-pr-ready.mjs",
     "testsuite": "pnpm -r --no-bail testsuite",
     "up-all": "pnpm --recursive update",
     "u": "pnpm run update && pnpm i && pnpm dedupe",
@@ -34,7 +35,7 @@
     "build": "cd packages/eslint-shared-config && pnpm build && cd ../.. && cd packages/cli && pnpm build && cd .. && pnpm build:tsc && cd vue-components && pnpm build",
     "rbuild": "pnpm clean && pnpm build",
     "nnm": "find . -name 'node_modules' -type d -prune -exec rm -rf '{}' + && pnpm i",
-    "prepare": "node -e \"const v=require('typescript/package.json').version;if(v.startsWith('6.')){require('child_process').execSync('effect-language-service patch',{stdio:'inherit'})}else{console.log('Skipping effect-language-service patch for TypeScript '+v)}\"",
+    "prepare": "node -e \"const v=require('typescript/package.json').version;if(v.startsWith('6.')){require('child_process').execSync('effect-language-service patch',{stdio:'inherit'})}else{console.log('Skipping effect-language-service patch for TypeScript '+v)}\" && node scripts/install-git-hooks.mjs",
     "subtree:effect": "node scripts/sync-effect-subtree.js"
   },
   "dependencies": {
diff --git a/scripts/agent-gh.mjs b/scripts/agent-gh.mjs
new file mode 100644
index 0000000000..1a726c951d
--- /dev/null
+++ b/scripts/agent-gh.mjs
@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Agent-facing `gh` policy shim.
+ *
+ * Installed at `.tools/bin/gh` by `scripts/install-git-hooks.mjs`.
+ * When coding-agent env markers are set and the command would publish a PR
+ * (`gh pr ready`, ready_for_review API), the ship gate runs first and the command
+ * then proceeds. Only a failing gate stops it — publishing is gated, not
+ * forbidden. `pnpm pr:ready` remains the explicit path; it sets AGENT_PR_SHIP=1
+ * so the gate runs once, not twice.
+ *
+ * Humans / non-agents: transparent pass-through to the next `gh` on PATH.
+ */
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+import { isCodingAgent } from "./lib/agent-env.mjs"
+import { findRealGh, requiresShipGate } from "./lib/agent-gh-policy.mjs"
+
+const selfPath = fileURLToPath(import.meta.url)
+const argv = process.argv.slice(2)
+
+let shipping = false
+
+if (isCodingAgent()) {
+  const gate = requiresShipGate(argv)
+  if (gate.required) {
+    console.error(`agent gh: ${gate.reason}`)
+    // Lazy: `gh` is on the hot path for ordinary commands and must not pay for
+    // the gate's dependencies just to run `gh pr view`.
+    const { runAgentShipGate } = await import("./agent-pre-push.mjs")
+    // Exits non-zero itself when a check fails, so a red gate stops the publish
+    // and a green one falls through to the real `gh` below.
+    await runAgentShipGate({ root: process.cwd() })
+    shipping = true
+  }
+}
+
+const realGh = findRealGh({ selfPath })
+if (!realGh) {
+  console.error("agent gh: could not resolve real `gh` binary (set AGENT_GH_REAL)")
+  process.exit(127)
+}
+
+// Avoid re-entering this shim if PATH still prefers us.
+const env = { ...process.env }
+const toolsBin = path.resolve(path.dirname(selfPath), "..", ".tools", "bin")
+const pathParts = (env["PATH"] ?? "").split(path.delimiter).filter(Boolean)
+env["PATH"] = pathParts.filter((p) => path.resolve(p) !== toolsBin).join(path.delimiter)
+env["AGENT_GH_REAL"] = realGh
+// The gate passed, so anything this command spawns is already cleared to ship.
+if (shipping) env["AGENT_PR_SHIP"] = "1"
+
+const result = spawnSync(realGh, argv, {
+  stdio: "inherit",
+  env,
+  shell: false
+})
+process.exit(result.status === null ? 1 : result.status)
diff --git a/scripts/agent-pr-ready.mjs b/scripts/agent-pr-ready.mjs
new file mode 100644
index 0000000000..17addb0914
--- /dev/null
+++ b/scripts/agent-pr-ready.mjs
@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Agent (and human) publish path: run the ship gate, then mark the PR ready.
+ *
+ *   pnpm pr:ready
+ *
+ * Agents must not call `gh pr ready` directly — the agent gh shim blocks it
+ * unless AGENT_PR_SHIP=1 (set only here for the undraft step).
+ */
+import { spawnSync } from "node:child_process"
+import process from "node:process"
+import { runAgentShipGate } from "./agent-pre-push.mjs"
+import { resolveOpenPrState } from "./lib/agent-pr-state.mjs"
+
+const root = process.cwd()
+const prState = resolveOpenPrState({ cwd: root })
+
+if (prState.mode === "none") {
+  console.error("agent pr:ready: no open PR for this branch — open a draft first (`gh pr create --draft`)")
+  process.exit(1)
+}
+
+if (prState.mode === "unknown") {
+  console.error(`agent pr:ready: cannot resolve PR state (${prState.detail ?? "gh failed"})`)
+  process.exit(1)
+}
+
+if (prState.mode === "ready") {
+  console.error(
+    `agent pr:ready: PR${
+      prState.pr?.number != null ? ` #${prState.pr.number}` : ""
+    } is already ready — running ship gate only`
+  )
+  await runAgentShipGate({ root })
+  process.exit(0)
+}
+
+// draft → gate then undraft
+console.error(
+  `agent pr:ready: ship gate then ready PR${prState.pr?.number != null ? ` #${prState.pr.number}` : ""}`
+)
+await runAgentShipGate({ root })
+
+const env = { ...process.env, AGENT_PR_SHIP: "1" }
+const readyArgs = prState.pr?.number != null
+  ? ["pr", "ready", String(prState.pr.number)]
+  : ["pr", "ready"]
+
+console.error("agent pr:ready: marking PR ready for review")
+const result = spawnSync("gh", readyArgs, {
+  stdio: "inherit",
+  cwd: root,
+  env,
+  shell: false
+})
+const status = result.status === null ? 1 : result.status
+if (status !== 0) {
+  console.error(`agent pr:ready: gh pr ready failed (exit ${status})`)
+  process.exit(status)
+}
+
+console.error(
+  "agent pr:ready: ok — PR is ready; CI re-runs with e2e enabled (ready_for_review; not draft mini baseline)"
+)
+process.exit(0)
diff --git a/scripts/agent-pre-push.mjs b/scripts/agent-pre-push.mjs
new file mode 100644
index 0000000000..0d73b93b5b
--- /dev/null
+++ b/scripts/agent-pre-push.mjs
@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Native git `pre-push` entry for coding agents only.
+ *
+ * Humans: no-op (exit 0) — self-responsible; not forced by the hook.
+ *
+ * Agents:
+ *   - Draft PR or no open PR: free push (open a draft early, push freely).
+ *   - Ready-for-review PR (or unknown PR state): ship gate below.
+ *   - Publishing runs the same gate whichever way it is reached: `pnpm pr:ready`
+ *     explicitly, or raw `gh pr ready`, which the shim gates rather than refuses.
+ *
+ * Ship gate — the JS quality path CI runs, and nothing else:
+ *   1. `pnpm check`  — tsgo --build ./tsconfig.all.json
+ *   2. `pnpm lint`
+ *   3. `pnpm test`   — pnpm -r --no-bail test:run
+ *
+ * This is a library monorepo: there is no application to stand up and no browser
+ * suite, so the unit run is the whole story. That keeps the gate honest about
+ * being the same thing CI runs (`ci.yml` runs `pnpm lint` and `pnpm test`)
+ * rather than a superset nobody else executes.
+ *
+ * Checks run **once**, at the right moment: the validated HEAD SHA is cached
+ * under `.run/`, so a commit is never re-validated because it was pushed twice.
+ * Agents should not hand-run these separately.
+ *
+ * Detection: GROK_AGENT / T3_AGENT / AI_AGENT / Claude / Cursor / Codex env.
+ * Humans only: SKIP_AGENT_PREPUSH=1 git push
+ * Agents must never set that flag or use git push --no-verify.
+ */
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+import { isCodingAgent } from "./lib/agent-env.mjs"
+import { resolveOpenPrState, shouldRunShipGateOnPush } from "./lib/agent-pr-state.mjs"
+import {
+  isShipGateForce,
+  isShipGateShaCached,
+  readHeadSha,
+  readShipGateCache,
+  writeShipGateCache
+} from "./lib/agent-ship-gate-cache.mjs"
+
+export { isCodingAgent }
+
+/**
+ * The gate shells out to workspace binaries that live in `node_modules/.bin`.
+ * pnpm and the hook both put that on PATH, so every caller happens to work and
+ * the dependency stays invisible — until something runs the gate from a bare
+ * process, where it dies with "command not found". Supply it explicitly so the
+ * gate does not depend on how it was invoked.
+ *
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} env
+ */
+const withRepoBin = (root, env) => {
+  const repoBin = path.join(root, "node_modules", ".bin")
+  const current = (env["PATH"] ?? "").split(path.delimiter).filter(Boolean)
+  if (current.some((entry) => path.resolve(entry) === repoBin)) return env
+  return { ...env, PATH: [repoBin, ...current].join(path.delimiter) }
+}
+
+const run = (label, args, opts = {}) => {
+  console.error(`agent ship-gate: ${label}`)
+  const result = spawnSync(args[0], args.slice(1), {
+    stdio: "inherit",
+    shell: true,
+    cwd: opts.cwd ?? process.cwd(),
+    env: opts.env ?? process.env
+  })
+  const status = result.status === null ? 1 : result.status
+  if (status !== 0) {
+    console.error(`agent ship-gate: failed: ${label} (exit ${status})`)
+    process.exit(status)
+  }
+}
+
+export const isWorktreeClean = (root = process.cwd(), opts = {}) => {
+  const runGit = opts.runGit
+    ?? ((args, runOpts) => spawnSync("git", args, { cwd: runOpts.cwd, encoding: "utf8", shell: false }))
+  const result = runGit(["status", "--porcelain=v1", "--untracked-files=normal"], { cwd: root })
+  return result.status === 0 && String(result.stdout ?? "").trim() === ""
+}
+
+/**
+ * Shared by pre-push (ready PRs) and `pnpm pr:ready`. Caches the validated HEAD
+ * SHA so push + publish never double-run for the same commit.
+ * Force: AGENT_SHIP_GATE_FORCE=1.
+ *
+ * @param {{ root?: string, force?: boolean, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {Promise<{ status: "cached" | "ok", sha: string | null }>}
+ */
+export const runAgentShipGate = async (opts = {}) => {
+  const root = opts.root ?? process.cwd()
+  const env = withRepoBin(root, opts.env ?? process.env)
+  const force = opts.force === true || isShipGateForce(env)
+  const headSha = readHeadSha(root)
+
+  if (!isWorktreeClean(root)) {
+    console.error("agent ship-gate: worktree is dirty — commit the changes, then push again")
+    process.exit(1)
+  }
+
+  if (!force && headSha && isShipGateShaCached(headSha, readShipGateCache(root))) {
+    console.error(
+      `agent ship-gate: skip — ${
+        headSha.slice(0, 12)
+      } already validated (cache .run/agent-ship-gate.json; force with AGENT_SHIP_GATE_FORCE=1)`
+    )
+    return { status: "cached", sha: headSha }
+  }
+
+  run("pnpm check", ["pnpm", "check"], { cwd: root, env })
+  run("pnpm lint", ["pnpm", "lint"], { cwd: root, env })
+  run("pnpm test", ["pnpm", "test"], { cwd: root, env })
+
+  if (!isWorktreeClean(root)) {
+    console.error("agent ship-gate: validation rewrote files — commit the changes, then push again")
+    process.exit(1)
+  }
+
+  if (headSha) {
+    try {
+      writeShipGateCache(root, headSha)
+      console.error(`agent ship-gate: cached ${headSha.slice(0, 12)} (.run/agent-ship-gate.json)`)
+    } catch (error) {
+      console.error(`agent ship-gate: could not write cache: ${error?.message ?? error}`)
+    }
+  }
+
+  console.error("agent ship-gate: ok")
+  return { status: "ok", sha: headSha }
+}
+
+const thisFile = fileURLToPath(import.meta.url)
+const invokedAs = process.argv[1] ? path.resolve(process.argv[1]) : ""
+
+if (invokedAs === thisFile) {
+  if (!isCodingAgent()) process.exit(0)
+
+  const root = process.cwd()
+  const prState = resolveOpenPrState({ cwd: root })
+
+  if (!shouldRunShipGateOnPush(prState.mode)) {
+    const why = prState.mode === "draft"
+      ? `draft PR${prState.pr?.number != null ? ` #${prState.pr.number}` : ""} — free push`
+      : "no open PR — free push (open a draft to share)"
+    console.error(`agent pre-push: skip ship gate (${why})`)
+    process.exit(0)
+  }
+
+  if (prState.mode === "unknown") {
+    console.error(
+      `agent pre-push: PR state unknown (${prState.detail ?? "gh failed"}) — fail closed, running ship gate`
+    )
+  }
+
+  await runAgentShipGate({ root })
+  process.exit(0)
+}
diff --git a/scripts/install-git-hooks.mjs b/scripts/install-git-hooks.mjs
new file mode 100644
index 0000000000..5cb6894e72
--- /dev/null
+++ b/scripts/install-git-hooks.mjs
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Points git at the repository's tracked hooks and generates the agent `gh`
+ * policy shim. Runs from `prepare`.
+ *
+ * The shim is generated rather than committed because it embeds this checkout's
+ * absolute path, which differs per clone and per worktree. `.envrc` puts the
+ * directory on PATH, so it applies only while you are inside the repository.
+ */
+import { execFileSync } from "node:child_process"
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+if (process.env["SKIP_PREPARE"]) {
+  console.log("install-git-hooks: SKIP_PREPARE set, skipping")
+  process.exit(0)
+}
+
+const installAgentGhShim = () => {
+  const toolsBin = path.join(root, ".tools", "bin")
+  mkdirSync(toolsBin, { recursive: true })
+  const shimPath = path.join(toolsBin, "gh")
+  writeFileSync(
+    shimPath,
+    `#!/usr/bin/env bash
+# Installed by scripts/install-git-hooks.mjs — agent gh policy shim.
+# Publishing a PR runs the ship gate first; only a failing gate stops it.
+set -euo pipefail
+exec node ${JSON.stringify(path.join(root, "scripts", "agent-gh.mjs"))} "$@"
+`,
+    { encoding: "utf8", mode: 0o755 }
+  )
+  try {
+    chmodSync(shimPath, 0o755)
+  } catch {
+    // best-effort on platforms without chmod
+  }
+}
+
+try {
+  installAgentGhShim()
+} catch (error) {
+  console.error(`install-git-hooks: could not install agent gh shim: ${error?.message ?? error}`)
+}
+
+try {
+  execFileSync("git", ["config", "core.hooksPath", ".githooks"], { cwd: root })
+} catch (error) {
+  const code = error?.code
+  const message = String(error?.message ?? error ?? "")
+  // Docker / tarball / no-git installs have nothing to configure. A real
+  // worktree failure should still fail prepare.
+  if (code === "ENOENT" || /not a git repository/iu.test(message) || /spawnSync git/iu.test(message)) {
+    console.log("install-git-hooks: no git repository, skipping hooks")
+    process.exit(0)
+  }
+  throw error
+}
diff --git a/scripts/lib/agent-env.mjs b/scripts/lib/agent-env.mjs
new file mode 100644
index 0000000000..e92e32dba6
--- /dev/null
+++ b/scripts/lib/agent-env.mjs
@@ -0,0 +1,26 @@
+/**
+ * Shared agent-env detection (pre-push, gh shim, pr:ready).
+ */
+import process from "node:process"
+
+const truthy = (v) => {
+  if (v == null || v === "") return false
+  const s = String(v).toLowerCase()
+  return s !== "0" && s !== "false" && s !== "no" && s !== "off"
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export const isCodingAgent = (env = process.env) => {
+  if (truthy(env["SKIP_AGENT_PREPUSH"])) return false
+  return (
+    truthy(env["GROK_AGENT"])
+    || truthy(env["T3_AGENT"])
+    || truthy(env["AI_AGENT"])
+    || truthy(env["CLAUDECODE"])
+    || truthy(env["CLAUDE_CODE"])
+    || truthy(env["CURSOR_AGENT"])
+    || truthy(env["CURSOR_TRACE_ID"])
+    || truthy(env["CODEX_CI"])
+    || truthy(env["CODEX_SANDBOX"])
+  )
+}
diff --git a/scripts/lib/agent-gh-policy.mjs b/scripts/lib/agent-gh-policy.mjs
new file mode 100644
index 0000000000..2e828e4328
--- /dev/null
+++ b/scripts/lib/agent-gh-policy.mjs
@@ -0,0 +1,155 @@
+/**
+ * Agent policy for `gh`: recognise the invocations that publish a pull request
+ * (undraft / ready-for-review side channels) so the shim can run the ship gate
+ * before letting them through. Publishing is gated, never refused — only a
+ * failing gate stops it. `pnpm pr:ready` sets AGENT_PR_SHIP=1 so its own undraft
+ * call does not re-run the gate it just passed.
+ */
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const truthy = (v) => {
+  if (v == null || v === "") return false
+  const s = String(v).toLowerCase()
+  return s !== "0" && s !== "false" && s !== "no" && s !== "off"
+}
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export const isAgentPrShipAllowed = (env = process.env) => truthy(env["AGENT_PR_SHIP"])
+
+/**
+ * Strip leading global `gh` flags so subcommands are at the front.
+ * @param {string[]} argv
+ */
+export const stripGhGlobalFlags = (argv) => {
+  const args = [...argv]
+  const skipValue = new Set([
+    "-R",
+    "--repo",
+    "-h",
+    "--hostname",
+    "-p",
+    "--path",
+    "--config-dir"
+  ])
+  while (args.length > 0) {
+    const a = args[0]
+    if (a === "--") {
+      args.shift()
+      break
+    }
+    if (!a.startsWith("-")) break
+    if (a.includes("=") && (a.startsWith("-R=") || a.startsWith("--repo=") || a.startsWith("--hostname="))) {
+      args.shift()
+      continue
+    }
+    if (skipValue.has(a)) {
+      args.shift()
+      if (args.length > 0) args.shift()
+      continue
+    }
+    // Unknown global flag with possible value — stop rather than mis-parse.
+    if (a.startsWith("-") && args.length > 1 && !args[1].startsWith("-") && !a.includes("=")) {
+      // boolean globals like --help stay; leave them for gh
+      break
+    }
+    args.shift()
+  }
+  return args
+}
+
+/**
+ * @param {string[]} argv  args after the gh binary name
+ * @param {NodeJS.ProcessEnv} [env]
+ * Does this `gh` invocation publish a pull request, and therefore have to pass
+ * the ship gate first?
+ *
+ * Refusing outright enforced the gate by making the agent remember a second
+ * command — forget it and you get an error, not a validated PR.
+ *
+ * @returns {{ required: boolean, reason?: string }}
+ */
+export const requiresShipGate = (argv, env = process.env) => {
+  if (isAgentPrShipAllowed(env)) return { required: false }
+
+  const args = stripGhGlobalFlags(argv)
+  if (args.length === 0) return { required: false }
+
+  // gh pr ready [number]
+  if (args[0] === "pr" && args[1] === "ready") {
+    return {
+      required: true,
+      reason: "`gh pr ready` publishes this PR — running the ship gate first"
+    }
+  }
+
+  // REST / GraphQL undraft side channels via `gh api`
+  if (args[0] === "api") {
+    const joined = args.join(" ")
+    if (/ready_for_review/i.test(joined) || /markPullRequestReadyForReview/i.test(joined)) {
+      return {
+        required: true,
+        reason: "this `gh api` call publishes a PR — running the ship gate first"
+      }
+    }
+  }
+
+  return { required: false }
+}
+
+/**
+ * Resolve the real `gh` binary, skipping this policy shim when it is on PATH.
+ * @param {{ env?: NodeJS.ProcessEnv, selfPath?: string }} [opts]
+ * @returns {string | null}
+ */
+export const findRealGh = (opts = {}) => {
+  const env = opts.env ?? process.env
+  if (env["AGENT_GH_REAL"] && fs.existsSync(env["AGENT_GH_REAL"])) {
+    return env["AGENT_GH_REAL"]
+  }
+
+  const selfPath = opts.selfPath
+    ? path.resolve(opts.selfPath)
+    : fileURLToPath(import.meta.url)
+
+  const pathEnv = env["PATH"] ?? ""
+  for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+    for (const name of ["gh", "gh.real"]) {
+      const candidate = path.join(dir, name)
+      try {
+        if (!fs.existsSync(candidate)) continue
+        const resolved = fs.realpathSync(candidate)
+        // Skip our shim (scripts/agent-gh.mjs launched via .tools/bin/gh).
+        if (resolved === selfPath) continue
+        if (resolved.endsWith(`${path.sep}agent-gh.mjs`)) continue
+        if (resolved.includes(`${path.sep}.tools${path.sep}bin${path.sep}gh`)) continue
+        // Prefer executables; on Windows skip the check.
+        try {
+          fs.accessSync(candidate, fs.constants.X_OK)
+        } catch {
+          continue
+        }
+        return candidate
+      } catch {
+        // try next
+      }
+    }
+  }
+
+  // Last resort: ask the shell (may return us — caller must detect loops).
+  const which = spawnSync("bash", ["-lc", "command -v gh"], {
+    encoding: "utf8",
+    env,
+    shell: false
+  })
+  if (which.status === 0) {
+    const p = which.stdout.trim()
+    if (p && !p.endsWith("agent-gh.mjs") && !p.includes(`${path.sep}.tools${path.sep}bin${path.sep}gh`)) {
+      return p
+    }
+  }
+  return null
+}
diff --git a/scripts/lib/agent-pr-state.mjs b/scripts/lib/agent-pr-state.mjs
new file mode 100644
index 0000000000..976934679e
--- /dev/null
+++ b/scripts/lib/agent-pr-state.mjs
@@ -0,0 +1,123 @@
+/**
+ * Resolve whether the current branch's open PR should enforce the agent ship gate.
+ *
+ * Modes:
+ *   none    — no open PR (or closed/merged): free agent push
+ *   draft   — open draft PR: free agent push (GitHub Diff UI)
+ *   ready   — open non-draft PR: ship gate on every agent push
+ *   unknown — gh missing / failed: fail closed (run the gate)
+ */
+import { spawnSync } from "node:child_process"
+import process from "node:process"
+
+/**
+ * @param {{ isDraft?: boolean, state?: string } | null | undefined} pr
+ * @returns {"none" | "draft" | "ready"}
+ */
+export const classifyPrPayload = (pr) => {
+  if (pr == null) return "none"
+  const state = String(pr.state ?? "").toUpperCase()
+  if (state === "CLOSED" || state === "MERGED") return "none"
+  if (pr.isDraft === true) return "draft"
+  return "ready"
+}
+
+/**
+ * @param {"none" | "draft" | "ready" | "unknown"} mode
+ * @returns {boolean}
+ */
+export const shouldRunShipGateOnPush = (mode) => mode === "ready" || mode === "unknown"
+
+/**
+ * @param {{
+ *   cwd?: string
+ *   env?: NodeJS.ProcessEnv
+ *   runGh?: (args: string[], opts: { cwd: string, env: NodeJS.ProcessEnv }) =>
+ *     { status: number | null, stdout: string, stderr: string }
+ * }} [opts]
+ * @returns {{ mode: "none" | "draft" | "ready" | "unknown", pr: { number?: number, url?: string, isDraft?: boolean, state?: string } | null, detail?: string }}
+ */
+/** Strip ANSI color codes so `gh --json` stays parseable when color is forced. */
+const stripAnsi = (text) => String(text).replace(/\u001b\[[0-9;]*m/g, "")
+
+/** Return the JSON object while ignoring shell integration noise around it. */
+const extractJsonObject = (text) => {
+  const cleaned = stripAnsi(text).trim()
+  const start = cleaned.indexOf("{")
+  const end = cleaned.lastIndexOf("}")
+  if (start === -1 || end === -1 || end < start) return cleaned
+  return cleaned.slice(start, end + 1)
+}
+
+export const resolveOpenPrState = (opts = {}) => {
+  const cwd = opts.cwd ?? process.cwd()
+  const env = { ...(opts.env ?? process.env) }
+  delete env.FORCE_COLOR
+  delete env.CLICOLOR_FORCE
+  env.NO_COLOR = "1"
+  env.CLICOLOR = "0"
+  env.GH_FORCE_TTY = "0"
+  env.TERM = "dumb"
+  const runGh = opts.runGh
+    ?? ((args, runOpts) => {
+      const result = spawnSync("gh", args, {
+        encoding: "utf8",
+        cwd: runOpts.cwd,
+        env: runOpts.env,
+        shell: false
+      })
+      return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        error: result.error
+      }
+    })
+
+  const result = runGh(
+    ["pr", "view", "--json", "number,url,isDraft,state"],
+    { cwd, env }
+  )
+
+  if (result.error && result.error.code === "ENOENT") {
+    return { mode: "unknown", pr: null, detail: "gh not found on PATH" }
+  }
+
+  const status = result.status === null ? 1 : result.status
+  const stderr = stripAnsi(result.stderr ?? "").trim()
+  const stdout = extractJsonObject(result.stdout ?? "")
+
+  // No PR for this branch — free push (open a draft when ready to share).
+  if (status !== 0) {
+    const combined = `${stderr}\n${stdout}`.toLowerCase()
+    if (
+      combined.includes("no pull requests found")
+      || combined.includes("could not resolve to a pullrequest")
+      || combined.includes("no pr found")
+      || combined.includes("not found")
+    ) {
+      return { mode: "none", pr: null, detail: stderr.trim() || "no open PR" }
+    }
+    return {
+      mode: "unknown",
+      pr: null,
+      detail: stderr.trim() || stdout || `gh pr view exited ${status}`
+    }
+  }
+
+  if (!stdout) {
+    return { mode: "unknown", pr: null, detail: "gh pr view returned empty JSON" }
+  }
+
+  try {
+    const pr = JSON.parse(stdout)
+    const mode = classifyPrPayload(pr)
+    return { mode, pr, detail: mode === "none" ? `PR ${pr.number} is ${pr.state}` : undefined }
+  } catch (error) {
+    return {
+      mode: "unknown",
+      pr: null,
+      detail: `failed to parse gh pr view JSON: ${error?.message ?? error}`
+    }
+  }
+}
diff --git a/scripts/lib/agent-ship-gate-cache.mjs b/scripts/lib/agent-ship-gate-cache.mjs
new file mode 100644
index 0000000000..a887044604
--- /dev/null
+++ b/scripts/lib/agent-ship-gate-cache.mjs
@@ -0,0 +1,121 @@
+/**
+ * Persist the last HEAD SHA that passed the agent ship gate.
+ * pre-push and `pnpm pr:ready` share this so the same commit is never double-paid.
+ *
+ * Path: `.run/agent-ship-gate.json` (under gitignored `.run/`).
+ */
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import process from "node:process"
+
+export const SHIP_GATE_CACHE_REL = path.join(".run", "agent-ship-gate.json")
+
+/** @param {string} [root] */
+export const shipGateCachePath = (root = process.cwd()) => path.join(root, SHIP_GATE_CACHE_REL)
+
+/**
+ * @param {string} [root]
+ * @param {{ runGit?: (args: string[], opts: { cwd: string }) => { status: number | null, stdout: string } }} [opts]
+ * @returns {string | null} full SHA or null
+ */
+export const readHeadSha = (root = process.cwd(), opts = {}) => {
+  const runGit = opts.runGit
+    ?? ((args, runOpts) => {
+      const result = spawnSync("git", args, {
+        encoding: "utf8",
+        cwd: runOpts.cwd,
+        shell: false
+      })
+      return { status: result.status, stdout: result.stdout ?? "" }
+    })
+  const result = runGit(["rev-parse", "HEAD"], { cwd: root })
+  if (result.status !== 0) return null
+  const sha = String(result.stdout).trim()
+  return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null
+}
+
+/**
+ * @param {string} [root]
+ * @param {{ readFileSync?: typeof fs.readFileSync }} [opts]
+ * @returns {{ sha?: string, validatedAt?: string, automatedSha?: string, automatedAt?: string } | null}
+ */
+export const readShipGateCache = (root = process.cwd(), opts = {}) => {
+  const readFileSync = opts.readFileSync ?? fs.readFileSync
+  const file = shipGateCachePath(root)
+  try {
+    const raw = readFileSync(file, "utf8")
+    const parsed = JSON.parse(raw)
+    const parsedSha = typeof parsed?.sha === "string" ? parsed.sha.trim().toLowerCase() : ""
+    const parsedAutomatedSha = typeof parsed?.automatedSha === "string"
+      ? parsed.automatedSha.trim().toLowerCase()
+      : ""
+    const sha = /^[0-9a-f]{40}$/i.test(parsedSha) ? parsedSha : undefined
+    const automatedSha = /^[0-9a-f]{40}$/i.test(parsedAutomatedSha) ? parsedAutomatedSha : sha
+    if (!sha && !automatedSha) return null
+    return {
+      sha,
+      validatedAt: typeof parsed.validatedAt === "string" ? parsed.validatedAt : undefined,
+      automatedSha,
+      automatedAt: typeof parsed.automatedAt === "string"
+        ? parsed.automatedAt
+        : typeof parsed.validatedAt === "string"
+        ? parsed.validatedAt
+        : undefined
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} sha
+ * @param {{ stage?: "automated" | "complete", writeFileSync?: typeof fs.writeFileSync, mkdirSync?: typeof fs.mkdirSync, now?: () => Date }} [opts]
+ */
+export const writeShipGateCache = (root, sha, opts = {}) => {
+  const writeFileSync = opts.writeFileSync ?? fs.writeFileSync
+  const mkdirSync = opts.mkdirSync ?? fs.mkdirSync
+  const now = opts.now ?? (() => new Date())
+  const normalized = String(sha).trim().toLowerCase()
+  if (!/^[0-9a-f]{40}$/i.test(normalized)) {
+    throw new Error(`writeShipGateCache: invalid sha ${sha}`)
+  }
+  const file = shipGateCachePath(root)
+  const at = now().toISOString()
+  const value = opts.stage === "automated"
+    ? { automatedSha: normalized, automatedAt: at }
+    : { sha: normalized, validatedAt: at, automatedSha: normalized, automatedAt: at }
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, "utf8")
+}
+
+/**
+ * @param {string | null | undefined} headSha
+ * @param {{ sha: string } | null | undefined} cache
+ */
+export const isShipGateShaCached = (headSha, cache) => {
+  if (!headSha || !cache?.sha) return false
+  return headSha.toLowerCase() === cache.sha.toLowerCase()
+}
+
+/**
+ * @param {string | null | undefined} headSha
+ * @param {{ automatedSha?: string, sha?: string } | null | undefined} cache
+ */
+export const isShipGateAutomationCached = (headSha, cache) => {
+  if (!headSha) return false
+  const cachedSha = cache?.automatedSha ?? cache?.sha
+  return Boolean(cachedSha && headSha.toLowerCase() === cachedSha.toLowerCase())
+}
+
+/**
+ * Force re-run even when SHA is cached.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export const isShipGateForce = (env = process.env) => {
+  const v = env["AGENT_SHIP_GATE_FORCE"]
+  if (v == null || v === "") return false
+  const s = String(v).toLowerCase()
+  return s !== "0" && s !== "false" && s !== "no" && s !== "off"
+}

From 067f3720e8642c0a0102a23cfb5c6b540724caf2 Mon Sep 17 00:00:00 2001
From: Patrick Roza <contact@patrickroza.com>
Date: Mon, 3 Aug 2026 20:24:12 +0200
Subject: [PATCH 2/2] fix(agent): run the pre-push gate without pnpm exec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pnpm exec` runs a dependency-status check before the command. When the lockfile
has moved — a rebase does it — pnpm decides node_modules must be purged and
reinstalled, then aborts because a git hook has no TTY:

    ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY

The push then fails with a pnpm error that says nothing about the gate, because
the gate never started. Invoke node directly instead; the gate already puts
node_modules/.bin on PATH itself, so pnpm was not providing anything still
needed.

Same class as the other headless failures this work surfaced: a tool changing
behaviour based on TTY or CI detection breaks in a hook, and does it
confusingly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .githooks/pre-push | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.githooks/pre-push b/.githooks/pre-push
index d2386cb765..8aa31a67d0 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -9,4 +9,8 @@
 for name in $(git rev-parse --local-env-vars); do
   unset "$name"
 done
-pnpm exec node scripts/agent-pre-push.mjs
+# Plain `node`, not `pnpm exec node`: pnpm runs a dependency-status check first
+# and will try to purge node_modules when the lockfile moved (a rebase does it),
+# which aborts without a TTY — the hook then fails with a pnpm error instead of
+# anything about the gate. The gate puts node_modules/.bin on PATH itself.
+node scripts/agent-pre-push.mjs