From c03f185d15b40404dcccfcf7c01404616fd69352 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 01:19:25 -0800
Subject: [PATCH 1/5] v1.92.21.0 ci: blobless clones on the PR and train path,
 fail-loud history reads (GSTA-203 PR 5) (#3713)

* ci: blobless clones on the PR and train path, fail-loud history reads (GSTA-203 PR 5)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* changelog: GSTA-203 PR 5 fragment

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: tree-only merge-base diff in the Version Gate; ls-tree --full-tree in both history readers

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* ci: keep the route and backstop policy reads inline (git and jq only); docs follow

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: base CHANGELOG read in readFragments fails loudly; history readers try git show first

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: HISTORY_READ_FAILED from gstack-restamp and ship-queue land

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 .github/docker/Dockerfile.ci              |  15 ++
 .github/scripts/history-read.sh           |  48 ++++
 .github/workflows/evals-main-backstop.yml |  12 +-
 .github/workflows/evals.yml               |  23 +-
 .github/workflows/free-tests.yml          |   4 +-
 .github/workflows/version-gate.yml        |  11 +-
 CHANGELOG.md                              |   9 +
 VERSION                                   |   2 +-
 agents-digest/gstack-AGENTS.md            |   2 +-
 docs/troubleshooting.md                   |  28 +++
 lib/changelog-fragments.ts                |   5 +-
 lib/history-read.ts                       |  43 ++++
 lib/version-gate-train.ts                 |  22 +-
 package.json                              |   2 +-
 test/ci-history-read.test.ts              | 285 ++++++++++++++++++++++
 test/evals-train-workflow.test.ts         |   8 +-
 16 files changed, 498 insertions(+), 21 deletions(-)
 create mode 100755 .github/scripts/history-read.sh
 create mode 100644 lib/history-read.ts
 create mode 100644 test/ci-history-read.test.ts

diff --git a/.github/docker/Dockerfile.ci b/.github/docker/Dockerfile.ci
index efe5aca83..841291cca 100644
--- a/.github/docker/Dockerfile.ci
+++ b/.github/docker/Dockerfile.ci
@@ -60,6 +60,21 @@ RUN curl --retry 5 --retry-delay 5 --retry-connrefused -fsSL \
     && rm -rf /var/lib/apt/lists/* \
     && git --no-lazy-fetch --version
 
+# Partial clone: the eval jobs check out with `filter: blob:none` and read
+# older files through on-demand blob fetches (.github/scripts/history-read.sh).
+# Prove this Git makes a blobless clone and fetches a missing blob, so the image
+# fails here instead of in a slice's history read.
+RUN set -e; d=$(mktemp -d); \
+    git init -q -b main "$d/src"; echo one > "$d/src/f"; git -C "$d/src" add f; \
+    git -C "$d/src" -c user.name=ci -c user.email=ci@localhost commit -qm one; \
+    echo two > "$d/src/f"; git -C "$d/src" -c user.name=ci -c user.email=ci@localhost commit -qam two; \
+    git -C "$d/src" config uploadpack.allowFilter true; \
+    git clone -q --filter=blob:none --no-local "file://$d/src" "$d/clone"; \
+    test "$(git -C "$d/clone" config remote.origin.promisor)" = true; \
+    if GIT_NO_LAZY_FETCH=1 git -C "$d/clone" cat-file -e HEAD~1:f 2>/dev/null; then echo "blob present: not a partial clone" >&2; exit 1; fi; \
+    test "$(git -C "$d/clone" show HEAD~1:f)" = one; \
+    rm -rf "$d"; echo "partial clone: ok ($(git --version))"
+
 RUN python3 -m venv /tmp/gstack-ci-venv \
     && /tmp/gstack-ci-venv/bin/python -m pip --version \
     && rm -rf /tmp/gstack-ci-venv
diff --git a/.github/scripts/history-read.sh b/.github/scripts/history-read.sh
new file mode 100755
index 000000000..cb3c094d1
--- /dev/null
+++ b/.github/scripts/history-read.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Read one file at a commit in a CI checkout that may be a blobless clone
+# (actions/checkout `filter: blob:none`), where git fetches an old file's
+# contents on demand and that fetch can fail. lib/history-read.ts is the
+# TypeScript twin.
+#
+# Usage: history-read.sh <ref> <path> [--absent <text>]
+#
+# A read that `git show` answers is the file. When it fails, existence comes
+# from the ref's tree (`git ls-tree --full-tree`, local data only): a path the
+# tree does not list is absent, so this prints <text> (default: nothing) and
+# exits 0. A listed path is retried, 3 tries in all in a partial clone (only a
+# fetch can recover) and none otherwise, waiting HISTORY_READ_BACKOFF_SECONDS
+# (default 2) times the attempt between tries. Anything else (a ref that does
+# not resolve, a fetch that keeps failing) exits 1 with HISTORY_READ_FAILED
+# naming the ref, the path and the git version, and never reads as absent.
+# docs/troubleshooting.md#history-read-failed
+set -euo pipefail
+
+if [ "$#" -ne 2 ] && { [ "$#" -ne 4 ] || [ "$3" != --absent ]; }; then
+  echo "usage: history-read.sh <ref> <path> [--absent <text>]" >&2
+  exit 2
+fi
+ref=$1 file=$2 absent=${4:-}
+out=$(mktemp) err=$(mktemp)
+trap 'rm -f "$out" "$err"' EXIT
+
+fail() {
+  echo "::error::cannot read ${file} at ${ref}. $1 ($(git --version)). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)" >&2
+  exit 1
+}
+
+if git show "${ref}:${file}" >"$out" 2>"$err"; then cat "$out"; exit 0; fi
+listed=$(git ls-tree --full-tree "$ref" -- "$file" 2>"$err") || fail "git ls-tree failed: $(head -n 1 "$err")"
+if [ -z "$listed" ]; then
+  printf '%s' "$absent"
+  exit 0
+fi
+
+tries=1
+if git config --get-regexp '^(remote\..+\.promisor|extensions\.partialclone)$' | grep -qvi ' false$'; then tries=3; fi
+try=1
+while [ "$try" -lt "$tries" ]; do
+  sleep "$(( try * ${HISTORY_READ_BACKOFF_SECONDS:-2} ))"
+  if git show "${ref}:${file}" >"$out" 2>"$err"; then cat "$out"; exit 0; fi
+  try=$(( try + 1 ))
+done
+fail "git show failed ${tries} time(s): $(head -n 1 "$err")"
diff --git a/.github/workflows/evals-main-backstop.yml b/.github/workflows/evals-main-backstop.yml
index 2826bf353..2c3f30303 100644
--- a/.github/workflows/evals-main-backstop.yml
+++ b/.github/workflows/evals-main-backstop.yml
@@ -49,7 +49,17 @@ jobs:
       - name: Read the train policy (main)
         id: policy
         run: |
-          train=$(git show "${GITHUB_SHA}:.gstack/ship-policy.json" 2>/dev/null | jq -c 'if (.train | type) == "object" then .train else null end' 2>/dev/null || true)
+          ref="$GITHUB_SHA" file=.gstack/ship-policy.json policy=null
+          read_failed() { echo "::error::cannot read ${file} at ${ref}. $1 ($(git --version)). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)" >&2; exit 1; }
+          listed=$(git ls-tree --full-tree "$ref" -- "$file") || read_failed "git ls-tree failed"
+          if [ -n "$listed" ]; then
+            for try in 1 2 3; do
+              policy=$(git show "${ref}:${file}") && break
+              if [ "$try" = 3 ]; then read_failed "git show failed 3 times"; fi
+              sleep $((try * 2))
+            done
+          fi
+          train=$(jq -c 'if (.train | type) == "object" then .train else null end' <<<"$policy") || { echo "::error::${GITHUB_SHA}:.gstack/ship-policy.json is not valid JSON; fix the policy file" >&2; exit 1; }
           if [ -z "$train" ] || [ "$train" = null ]; then
             echo "train=false" >> "$GITHUB_OUTPUT"
             echo "- Backstop inert: main's .gstack/ship-policy.json declares no train block; per-PR gates cover main" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/evals.yml b/.github/workflows/evals.yml
index e7b81e55b..fd5ed557c 100644
--- a/.github/workflows/evals.yml
+++ b/.github/workflows/evals.yml
@@ -179,6 +179,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
@@ -193,9 +194,19 @@ jobs:
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
         run: |
           base="${BASE_SHA:-origin/${DEFAULT_BRANCH}}"
-          train=$(git show "${base}:.gstack/ship-policy.json" 2>/dev/null | jq -c 'if (.train | type) == "object" then .train else null end' 2>/dev/null || true)
-          artifact=$(jq -r '.record_artifact // ""' <<<"${train:-null}" 2>/dev/null || true)
-          check=$(jq -r '.full_gate_check // ""' <<<"${train:-null}" 2>/dev/null || true)
+          ref="$base" file=.gstack/ship-policy.json policy=null
+          read_failed() { echo "::error::cannot read ${file} at ${ref}. $1 ($(git --version)). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)" >&2; exit 1; }
+          listed=$(git ls-tree --full-tree "$ref" -- "$file") || read_failed "git ls-tree failed"
+          if [ -n "$listed" ]; then
+            for try in 1 2 3; do
+              policy=$(git show "${ref}:${file}") && break
+              if [ "$try" = 3 ]; then read_failed "git show failed 3 times"; fi
+              sleep $((try * 2))
+            done
+          fi
+          train=$(jq -c 'if (.train | type) == "object" then .train else null end' <<<"$policy") || { echo "::error::${base}:.gstack/ship-policy.json is not valid JSON; fix the policy file" >&2; exit 1; }
+          artifact=$(jq -r '.record_artifact // ""' <<<"${train:-null}")
+          check=$(jq -r '.full_gate_check // ""' <<<"${train:-null}")
           if [ -z "$train" ] || [ "$train" = null ]; then
             echo "train=false" >> "$GITHUB_OUTPUT"
             echo "- Train policy: none at ${base}; this run routes as before" >> "$GITHUB_STEP_SUMMARY"
@@ -470,6 +481,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
@@ -528,6 +540,7 @@ jobs:
           # Preserve full history for merge-base diff selection. Moving the
           # planner off the eval image must not change its selection inputs.
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
@@ -670,6 +683,7 @@ jobs:
           # shards on the lane's first live run ("ambiguous argument
           # 'main...HEAD'"). The manifest still governs WHICH shards run.
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - name: Fix bun temp
@@ -903,6 +917,7 @@ jobs:
         with:
           ref: ${{ inputs.screen_merge_sha }}
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - name: Fix bun temp
@@ -1029,6 +1044,7 @@ jobs:
         with:
           ref: ${{ fromJSON(needs.route.outputs.bisect_refs)[matrix.slice] }}
           fetch-depth: 0
+          filter: blob:none
           persist-credentials: false
 
       - name: Verify the prefix checkout
@@ -1173,6 +1189,7 @@ jobs:
           # history of its prefix commits T1..Tk for the train record.
           ref: ${{ inputs.screen_merge_sha }}
           fetch-depth: ${{ needs.plan-slices.outputs.mode == 'train' && '0' || '1' }}
+          filter: blob:none
           persist-credentials: false
 
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
diff --git a/.github/workflows/free-tests.yml b/.github/workflows/free-tests.yml
index 569b858fe..4af58829f 100644
--- a/.github/workflows/free-tests.yml
+++ b/.github/workflows/free-tests.yml
@@ -65,8 +65,10 @@ jobs:
         with:
           persist-credentials: false
           # Full history: the seed ratchet compares the allowlist with its
-          # merge-base copy, which a depth-1 checkout cannot read.
+          # merge-base copy, which a depth-1 checkout cannot read. Blobless:
+          # that copy is fetched on demand, and a failed read fails the ratchet.
           fetch-depth: 0
+          filter: blob:none
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
         with:
           bun-version: 1.4.2
diff --git a/.github/workflows/version-gate.yml b/.github/workflows/version-gate.yml
index 1be24d4e6..b64ec092a 100644
--- a/.github/workflows/version-gate.yml
+++ b/.github/workflows/version-gate.yml
@@ -23,6 +23,9 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
+          # Blobless: full history with file contents fetched on demand; the
+          # reads below fail loudly when a fetch fails (.github/scripts/history-read.sh).
+          filter: blob:none
           ref: ${{ github.event.pull_request.head.sha }}
           # The head's release_tool runs inside the gate (lib/version-gate-train.ts);
           # no token may sit in the checkout it stages. The base fetch below is public.
@@ -49,8 +52,12 @@ jobs:
           set -euo pipefail
           PR_VERSION=$(cat VERSION | tr -d '[:space:]')
           BASE_REF="${{ github.event.pull_request.base.ref }}"
-          git fetch origin "$BASE_REF" --quiet || true
-          BASE_VERSION=$(git show "origin/$BASE_REF:VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0.0")
+          for try in 1 2 3; do
+            git fetch origin "$BASE_REF" --quiet && break
+            if [ "$try" = 3 ]; then echo "::error::git fetch origin $BASE_REF failed 3 times ($(git --version)). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)"; exit 1; fi
+            sleep $((try * 2))
+          done
+          BASE_VERSION=$(bash .version-gate/.github/scripts/history-read.sh "origin/$BASE_REF" VERSION --absent 0.0.0.0 | tr -d '[:space:]')
           {
             echo "pr_version=$PR_VERSION"
             echo "base_version=$BASE_VERSION"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 19e50d361..4af548dec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.92.21.0] - 2026-11-01
+
+**The PR and train path check out blobless clones, and the history reads they gate on fail loudly instead of reading a failed fetch as "absent" (GSTA-203 PR 5).** Free Tests' plan job, the Version Gate and E2E Evals' route, screen summary, planner, slices, reruns, bisect and report checked out every file of every commit (about 232 MB) to read a handful of old files. They now check out with `filter: blob:none` (about 17 MB), and git fetches an old file's contents the first time something reads it.
+
+### Changed
+- **Blobless checkouts** (`filter: blob:none`) in `free-tests.yml` (free-plan), `version-gate.yml` and `evals.yml` (route, screen-summary, plan-slices, eval-slices, eval-rerun, train-bisect, slices-report). The release, CSO, periodic, marathon, sweep and recorder workflows and the main backstop keep full clones. `test/ci-history-read.test.ts` names each with its reason and fails on any other full-history checkout without the filter, printing the file and line to fix.
+- **History reads fail loudly.** The train-policy reads in the route and backstop jobs stay inline (git and jq only, so no repository code decides whether a PR push starts paid work). The Version Gate's base `VERSION` read goes through `.github/scripts/history-read.sh` from the gate's merge-commit checkout, and its train classification through the TypeScript twin, `lib/history-read.ts`, which also lists the merge base's changed files without rename detection so that diff needs no file contents. Each one checks existence with `git ls-tree`, reads with `git show` (3 tries in a partial clone) and fails with `HISTORY_READ_FAILED` naming the ref, the path and the git version (docs/troubleshooting.md#history-read-failed). A file that is really absent keeps its old meaning. A ship policy that is not valid JSON now fails the route and backstop jobs instead of reading as "no train". The Version Gate goes red when `git fetch origin <base>` fails 3 times instead of carrying on. `gstack-restamp` and `gstack-ship-queue land` read the base branch's CHANGELOG the same way, so a read that fails stops them with `HISTORY_READ_FAILED` instead of treating the base as having no released sections.
+- **The eval image asserts partial clone support.** `.github/docker/Dockerfile.ci` makes a blobless clone and fetches a missing blob at build time, so an image whose git cannot do that fails to build.
+
 ## [1.92.20.0] - 2026-11-01
 
 **`/retro global` now sees Kimi Code, OMP and Antigravity sessions (#2917, #1977).** `gstack-global-discover` scanned only Claude Code, Codex and Gemini. A week spent in other agent CLIs went uncounted, and nothing showed a zero to notice.
diff --git a/VERSION b/VERSION
index dbf7a7040..702e3354d 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.92.20.0
+1.92.21.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index 45e74e9c0..ba555e925 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.92.20.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.92.21.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 3a5da3378..225c66bda 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -2896,6 +2896,34 @@ fetching it cannot create that ref, so pass a branch that exists on `origin`
 (`git branch -r --list 'origin/*'` lists them). `gstack-pregate` says so in
 its fix instead of suggesting the fetch.
 
+<a id="history-read-failed"></a>
+### `cannot read <path> at <ref>. <cause> (git version <v>). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)`
+
+**Meaning.** A CI job or a local release tool read a file at an older commit
+and git could not produce it. The PR and train path jobs (Free Tests' plan, the Version Gate,
+and E2E Evals' route, screen summary, planner, slices, reruns, bisect and
+report) check out blobless clones (`filter: blob:none`): every commit and
+tree is there, but an older file's contents are fetched from GitHub the first
+time something reads them. When that fetch fails three times (a GitHub outage,
+a network drop), or the ref does not resolve at all, the read fails here
+instead of counting as "the file is absent". A file the commit really does not
+have still reads as absent, as before. No ship policy at the base means no
+train, and no VERSION means `0.0.0.0`. The route and backstop policy reads (inline
+in their workflows), `.github/scripts/history-read.sh` (the Version Gate's base
+`VERSION`) and `lib/history-read.ts` (the Version Gate's train classification)
+print this line. The Version Gate prints the same code when
+`git fetch origin <base>` fails three times. `gstack-restamp` and
+`gstack-ship-queue land` print it too when they cannot read the base branch's
+CHANGELOG, which they check fragments against (`lib/changelog-fragments.ts`
+reads it through `lib/history-read.ts`); outside a partial clone they do not
+retry.
+
+**Fix.** Rerun the failed job once GitHub is reachable. If it fails the same
+way on a healthy network, check that the ref exists on `origin` and that the
+runner's git supports partial clone (`git --version` 2.22 or newer; the eval
+image asserts it at build time in `.github/docker/Dockerfile.ci`). For a local
+tool, run `git fetch origin <base>` and rerun it.
+
 <a id="policy-invalid"></a>
 ### `POLICY_INVALID`
 
diff --git a/lib/changelog-fragments.ts b/lib/changelog-fragments.ts
index 3f5404cf8..3d21af17b 100644
--- a/lib/changelog-fragments.ts
+++ b/lib/changelog-fragments.ts
@@ -9,6 +9,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { headingVersion, parseChangelog } from './changelog-check';
+import { readHistoryFile } from './history-read';
 import type { Bump } from './version-source';
 
 export const FRAGMENT_README = 'README.md';
@@ -75,8 +76,8 @@ export function readFragments(cwd: string, treeish: string | null, dir: string,
     return out;
   };
   const excluded = new Map((exclude ? list(exclude) : []).map(e => [e.path, e.sha]));
-  const shown = exclude && changelog ? git(cwd, ['show', `${exclude}:${changelog}`]) : null;
-  const released = shown?.ok ? parseChangelog(shown.out.replace(/\r\n/g, '\n')).sections.filter(s => !s.unreleased).map(s => s.lines) : [];
+  const shown = exclude && changelog ? readHistoryFile(cwd, exclude, changelog) : null;
+  const released = shown !== null ? parseChangelog(shown.replace(/\r\n/g, '\n')).sections.filter(s => !s.unreleased).map(s => s.lines) : [];
   const isReleased = (body: string) => {
     const want = body.split('\n');
     return released.some(lines => lines.some((_, i) => want.every((w, k) => lines[i + k] === w)));
diff --git a/lib/history-read.ts b/lib/history-read.ts
new file mode 100644
index 000000000..f1fb39f9f
--- /dev/null
+++ b/lib/history-read.ts
@@ -0,0 +1,43 @@
+/**
+ * Read one file at a commit when the checkout may be a blobless clone
+ * (`filter: blob:none`), where git fetches an old file's contents on demand
+ * and that fetch can fail. The TypeScript twin of
+ * .github/scripts/history-read.sh. A read that `git show` answers is the
+ * file. When it fails, existence comes from the ref's tree (`git ls-tree
+ * --full-tree`, local data only): a path the tree does not list is absent, and
+ * a listed one is retried, 3 tries in all in a partial clone (only a fetch can
+ * recover) and none otherwise, waiting HISTORY_READ_BACKOFF_SECONDS (default 2)
+ * times the attempt between tries. Every other failure throws
+ * HISTORY_READ_FAILED instead of reading as absent
+ * (docs/troubleshooting.md#history-read-failed).
+ */
+import { spawnSync } from 'node:child_process';
+
+export const HISTORY_READ_TRIES = 3;
+
+export class HistoryReadError extends Error {
+  readonly code = 'HISTORY_READ_FAILED';
+}
+
+/** The file's text at `ref`, or null when the ref's tree does not list it. */
+export function readHistoryFile(repoRoot: string, ref: string, file: string): string | null {
+  const git = (args: string[]) => spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024 });
+  const fail = (cause: string) => {
+    const version = git(['--version']).stdout?.trim() || 'git version unknown';
+    return new HistoryReadError(`cannot read ${file} at ${ref}. ${cause} (${version}). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)`);
+  };
+  const firstLine = (r: ReturnType<typeof git>) => (r.stderr ?? '').split('\n')[0] || r.error?.message || `exit ${r.status}`;
+  let shown = git(['show', `${ref}:${file}`]);
+  if (shown.status === 0) return shown.stdout;
+  const listed = git(['ls-tree', '--full-tree', ref, '--', file]);
+  if (listed.status !== 0) throw fail(`git ls-tree failed: ${firstLine(listed)}`);
+  if (!listed.stdout.trim()) return null;
+  const promisors = (git(['config', '--get-regexp', '^(remote\\..+\\.promisor|extensions\\.partialclone)$']).stdout ?? '').split('\n');
+  const tries = promisors.some(line => line && !/ false$/i.test(line)) ? HISTORY_READ_TRIES : 1;
+  for (let attempt = 1; attempt < tries; attempt++) {
+    Bun.sleepSync(attempt * 1000 * Number(process.env.HISTORY_READ_BACKOFF_SECONDS ?? 2));
+    shown = git(['show', `${ref}:${file}`]);
+    if (shown.status === 0) return shown.stdout;
+  }
+  throw fail(`git show failed ${tries === 1 ? 'once (not a partial clone, so no retry)' : `${tries} times`}: ${firstLine(shown)}`);
+}
diff --git a/lib/version-gate-train.ts b/lib/version-gate-train.ts
index 0a95371dc..818f18730 100644
--- a/lib/version-gate-train.ts
+++ b/lib/version-gate-train.ts
@@ -13,6 +13,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { parseChangelog } from './changelog-check';
 import { effectiveBump, readFragments } from './changelog-fragments';
+import { HistoryReadError, readHistoryFile } from './history-read';
 import { matchesAny } from './ship-policy';
 
 export type TrainHead =
@@ -90,19 +91,27 @@ export function regeneratedAtBase(o: { repoRoot: string; head: string; baseVersi
   }
 }
 
+/** A history read that fails (not an absent file) classifies the head invalid with HISTORY_READ_FAILED. */
 export function classifyTrainHead(o: { repoRoot: string; baseRef: string; head: string; author?: string }): TrainHead {
+  try { return classify(o); } catch (e) { if (e instanceof HistoryReadError) return { kind: 'invalid', reason: e.message }; throw e; }
+}
+
+function classify(o: { repoRoot: string; baseRef: string; head: string; author?: string }): TrainHead {
   const base = `origin/${o.baseRef.replace(/^origin\//, '')}`;
-  const show = (rev: string, file: string) => git(o.repoRoot, ['show', `${rev}:${file}`]);
+  const show = (rev: string, file: string) => readHistoryFile(o.repoRoot, rev, file);
+  const policyText = show(base, '.gstack/ship-policy.json');
   let policy: any = null;
-  try { policy = JSON.parse(show(base, '.gstack/ship-policy.json') ?? 'null'); } catch { policy = null; }
+  try { policy = JSON.parse(policyText ?? 'null'); } catch { policy = null; }
   const fragDir: string | null = typeof policy?.changelog_fragments?.dir === 'string' ? policy.changelog_fragments.dir : null;
   if (!policy || ((typeof policy.train !== 'object' || policy.train === null) && !fragDir && policy.bump !== 'never')) return { kind: 'off' };
   const mergeBase = git(o.repoRoot, ['merge-base', base, o.head])?.trim();
   if (!mergeBase) return { kind: 'invalid', reason: `no merge base between ${base} and ${o.head}` };
 
-  const npmVersion = (rev: string) => { try { return JSON.parse(show(rev, 'package.json') ?? '{}').version ?? null; } catch { return null; } };
+  const npmVersion = (rev: string) => { const text = show(rev, 'package.json'); try { return JSON.parse(text ?? '{}').version ?? null; } catch { return null; } };
   if (policy.bump === 'never') return show(mergeBase, 'VERSION') === show(o.head, 'VERSION') && npmVersion(mergeBase) === npmVersion(o.head) ? { kind: 'unstamped', entry: 'kept' } : { kind: 'off' };
-  const changed = (git(o.repoRoot, ['diff', '--name-only', mergeBase, o.head]) ?? '').split('\n').filter(Boolean);
+  const diff = git(o.repoRoot, ['diff', '--no-renames', '--name-only', mergeBase, o.head]);
+  if (diff === null) return { kind: 'invalid', reason: `cannot list the files ${o.head} changes since its merge base ${mergeBase.slice(0, 12)}. Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)` };
+  const changed = diff.split('\n').filter(Boolean);
   const releaseOutputs: string[] = Array.isArray(policy.release_outputs) ? policy.release_outputs : [];
   // touched: what marks the head as stamped (the labels only feed the length check below)
   const touched: string[] = changed.filter(f => f === 'VERSION');
@@ -128,10 +137,7 @@ export function classifyTrainHead(o: { repoRoot: string; baseRef: string; head:
   }
 
   const file = typeof policy.changelog === 'string' ? policy.changelog : 'CHANGELOG.md';
-  const exists = (rev: string) => git(o.repoRoot, ['cat-file', '-e', `${rev}:${file}`]) !== null;
-  const read = (rev: string) => (exists(rev) ? show(rev, file) : '');
-  const [beforeText, afterText] = [read(mergeBase), read(o.head)];
-  if (beforeText === null || afterText === null) return { kind: 'invalid', reason: `cannot read ${file} at ${beforeText === null ? `the merge base ${mergeBase.slice(0, 12)}` : o.head}` };
+  const [beforeText, afterText] = [show(mergeBase, file) ?? '', show(o.head, file) ?? ''];
   const before = parseChangelog(beforeText);
   const after = parseChangelog(afterText);
   const unreleased = after.sections.filter(s => s.unreleased);
diff --git a/package.json b/package.json
index 3d7d98fac..e4022f3c6 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.92.20",
+  "version": "1.92.21",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/test/ci-history-read.test.ts b/test/ci-history-read.test.ts
new file mode 100644
index 000000000..b29465802
--- /dev/null
+++ b/test/ci-history-read.test.ts
@@ -0,0 +1,285 @@
+/**
+ * Blobless checkouts on the PR and train path (GSTA-203 PR 5).
+ *
+ * A `filter: blob:none` checkout keeps every commit and tree but fetches an
+ * older file's contents on demand, and that fetch can fail. Every history read
+ * those jobs gate on must tell "absent" (the ref's tree does not list the path)
+ * from "could not read" (a failed fetch, an unknown ref): the first keeps its
+ * old meaning, the second fails with HISTORY_READ_FAILED. The fixtures here
+ * are real blobless clones whose promisor remote is then made unreachable.
+ *
+ * The checkout-mode pin keeps every full-history checkout blobless except in
+ * the workflows FULL_CLONE_WORKFLOWS names, each with its reason.
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { readFragments } from '../lib/changelog-fragments';
+import { HistoryReadError, readHistoryFile } from '../lib/history-read';
+import { classifyTrainHead } from '../lib/version-gate-train';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const HELPER = path.join(ROOT, '.github', 'scripts', 'history-read.sh');
+const WORKFLOWS = path.join(ROOT, '.github', 'workflows');
+const SCRATCH = fs.mkdtempSync(path.join(os.tmpdir(), 'ci-history-read-'));
+const savedBackoff = process.env.HISTORY_READ_BACKOFF_SECONDS;
+process.env.HISTORY_READ_BACKOFF_SECONDS = '0';
+afterAll(() => {
+  if (savedBackoff === undefined) delete process.env.HISTORY_READ_BACKOFF_SECONDS;
+  else process.env.HISTORY_READ_BACKOFF_SECONDS = savedBackoff;
+  fs.rmSync(SCRATCH, { recursive: true, force: true });
+});
+
+/** Workflows that keep full clones, by file name, each with its reason. */
+const FULL_CLONE_WORKFLOWS: Record<string, string> = {
+  'weekly-release.yml': 'release: cuts and tags from main; off the PR and train path and not yet dispatched once blobless',
+  'cso-runtime-promote.yml': 'CSO image promotion; off the PR and train path and not yet dispatched once blobless',
+  'cso-runtime-qualification.yml': 'CSO runtime qualification; off the PR and train path and not yet dispatched once blobless',
+  'evals-periodic.yml': 'periodic evals; off the PR and train path and not yet dispatched once blobless',
+  'evals-marathon.yml': 'marathon evals; off the PR and train path and not yet dispatched once blobless',
+  'eval-sweep.yml': 'eval sweep; off the PR and train path and not yet dispatched once blobless',
+  'free-durations-record.yml': 'duration recorder; off the PR and train path and not yet dispatched once blobless',
+  'evals-main-backstop.yml': 'reads every train note blob (554 notes on refs/notes/gstack-trains at 5ba425a); a blobless clone fetches each on demand at about 0.58 s apiece, minutes more than the 10 s a blobless checkout saves on a job off the PR path',
+};
+
+/** The PR and train path jobs that check out blobless full history, by workflow. */
+const BLOBLESS_JOBS: Record<string, string[]> = {
+  'free-tests.yml': ['free-plan'],
+  'version-gate.yml': ['check'],
+  'evals.yml': ['route', 'screen-summary', 'plan-slices', 'eval-slices', 'eval-rerun', 'train-bisect', 'slices-report'],
+};
+
+const GIT_ID = ['-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.com', '-c', 'commit.gpgsign=false'];
+function git(cwd: string, ...args: string[]) {
+  return spawnSync('git', [...GIT_ID, ...args], { cwd, encoding: 'utf8', timeout: 30_000 });
+}
+function ok(cwd: string, ...args: string[]): string {
+  const r = git(cwd, ...args);
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+interface Fixture { clone: string; one: string; two: string; cut: () => void }
+/**
+ * A source repository with commits one and two, and a blobless clone of it
+ * checked out at one, so two's changed files are missing until fetched. `cut`
+ * points the clone's promisor remote at a path that does not exist.
+ */
+function fixture(name: string, one: Record<string, string>, two: Record<string, string | null>): Fixture {
+  const dir = path.join(SCRATCH, name);
+  const src = path.join(dir, 'src');
+  fs.mkdirSync(src, { recursive: true });
+  ok(src, 'init', '-q', '-b', 'main');
+  const write = (files: Record<string, string | null>) => {
+    for (const [rel, text] of Object.entries(files)) {
+      const target = path.join(src, rel);
+      if (text === null) { fs.rmSync(target, { force: true }); continue; }
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, text);
+    }
+    ok(src, 'add', '-A');
+  };
+  write(one);
+  ok(src, 'commit', '-q', '-m', 'one');
+  write(two);
+  ok(src, 'commit', '-q', '-m', 'two');
+  ok(src, 'config', 'uploadpack.allowFilter', 'true');
+  const clone = path.join(dir, 'clone');
+  ok(dir, 'clone', '-q', '--filter=blob:none', '--no-local', '--no-checkout', `file://${src}`, clone);
+  ok(clone, 'checkout', '-q', 'origin/main~1');
+  return { clone, one: ok(clone, 'rev-parse', 'HEAD'), two: ok(clone, 'rev-parse', 'origin/main'), cut: () => { ok(clone, 'remote', 'set-url', 'origin', `file://${dir}/gone`); } };
+}
+
+const TRAIN = { gate_workflow: 'evals.yml', free_workflow: 'free-tests.yml', full_gate_check: 'gstack/full-gate', record_artifact: 'gstack-train-record', max_size: 5, fill_hours: 3, screen_selection: 'none', trial_reservation_usd: 1.5 };
+const POLICY = '.gstack/ship-policy.json';
+const ONE = { VERSION: '1.0.0.0\n', [POLICY]: JSON.stringify({ bump: 'patch' }), 'README.md': 'one\n' };
+
+function helper(cwd: string, ...args: string[]) {
+  return spawnSync('bash', [HELPER, ...args], { cwd, encoding: 'utf8', timeout: 60_000, env: { PATH: process.env.PATH ?? '', HOME: cwd, HISTORY_READ_BACKOFF_SECONDS: '0' } });
+}
+const missing = (fx: Fixture, rev: string, rel: string) => spawnSync('git', ['cat-file', '-e', `${rev}:${rel}`], { cwd: fx.clone, timeout: 30_000, env: { ...process.env, GIT_NO_LAZY_FETCH: '1' } }).status !== 0;
+
+describe('history-read.sh and lib/history-read.ts on a blobless clone', () => {
+  test('a listed file is read, its blob fetched on demand', () => {
+    const fx = fixture('read', ONE, { VERSION: '1.0.0.1\n' });
+    expect(missing(fx, fx.two, 'VERSION')).toBe(true);
+    const r = helper(fx.clone, fx.two, 'VERSION');
+    expect(r.stderr).toBe('');
+    expect([r.status, r.stdout]).toEqual([0, '1.0.0.1\n']);
+    expect(readHistoryFile(fx.clone, fx.one, 'VERSION')).toBe('1.0.0.0\n');
+    const sub = path.join(fx.clone, 'sub');
+    fs.mkdirSync(sub);
+    expect(helper(sub, fx.one, POLICY)).toMatchObject({ status: 0, stdout: JSON.stringify({ bump: 'patch' }) });
+    expect(readHistoryFile(sub, fx.one, POLICY)).toBe(JSON.stringify({ bump: 'patch' }));
+  });
+
+  test('a path the tree does not list is absent even with the remote gone', () => {
+    const fx = fixture('absent', ONE, { [POLICY]: null });
+    fx.cut();
+    expect(helper(fx.clone, fx.two, POLICY, '--absent', 'null')).toMatchObject({ status: 0, stdout: 'null' });
+    expect(helper(fx.clone, fx.two, POLICY)).toMatchObject({ status: 0, stdout: '' });
+    expect(readHistoryFile(fx.clone, fx.two, POLICY)).toBeNull();
+  });
+
+  test('a blob that cannot be fetched fails after 3 tries with HISTORY_READ_FAILED, never as absent', () => {
+    const fx = fixture('unreachable', ONE, { [POLICY]: JSON.stringify({ bump: 'patch', train: TRAIN }) });
+    fx.cut();
+    const r = helper(fx.clone, fx.two, POLICY, '--absent', 'null');
+    expect(r.status).toBe(1);
+    expect(r.stdout).toBe('');
+    for (const part of [`::error::cannot read ${POLICY} at ${fx.two}.`, 'git show failed 3 time(s)', '(git version ', 'docs/troubleshooting.md#history-read-failed', '(HISTORY_READ_FAILED)']) expect(r.stderr).toContain(part);
+    let thrown: unknown;
+    try { readHistoryFile(fx.clone, fx.two, POLICY); } catch (e) { thrown = e; }
+    expect(thrown).toBeInstanceOf(HistoryReadError);
+    expect((thrown as HistoryReadError).code).toBe('HISTORY_READ_FAILED');
+    for (const part of [`cannot read ${POLICY} at ${fx.two}.`, 'git show failed 3 times', '(git version ', '#history-read-failed', '(HISTORY_READ_FAILED)']) expect((thrown as Error).message).toContain(part);
+    expect(fs.readFileSync(path.join(ROOT, 'docs', 'troubleshooting.md'), 'utf8')).toContain('<a id="history-read-failed"></a>');
+  });
+
+  test('a ref that does not resolve fails instead of reading as absent', () => {
+    const fx = fixture('bad-ref', ONE, { VERSION: '1.0.0.1\n' });
+    const r = helper(fx.clone, 'no-such-ref', 'VERSION', '--absent', '0.0.0.0');
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('cannot read VERSION at no-such-ref. git ls-tree failed');
+    expect(() => readHistoryFile(fx.clone, 'no-such-ref', 'VERSION')).toThrow('(HISTORY_READ_FAILED)');
+    expect(helper(fx.clone, 'only-one-arg').status).toBe(2);
+  });
+
+  test('the Version Gate classifies a head whose base policy cannot be fetched as invalid; an absent base policy stays off', () => {
+    const unreadable = fixture('gate-unreadable', ONE, { [POLICY]: JSON.stringify({ bump: 'patch', train: TRAIN }) });
+    unreadable.cut();
+    const kind = classifyTrainHead({ repoRoot: unreadable.clone, baseRef: 'main', head: unreadable.one });
+    expect(kind.kind).toBe('invalid');
+    expect(kind.kind === 'invalid' && kind.reason).toContain(`cannot read ${POLICY} at origin/main.`);
+    expect(kind.kind === 'invalid' && kind.reason).toContain('(HISTORY_READ_FAILED)');
+    const absent = fixture('gate-absent', ONE, { [POLICY]: null });
+    absent.cut();
+    expect(classifyTrainHead({ repoRoot: absent.clone, baseRef: 'main', head: absent.one })).toEqual({ kind: 'off' });
+  });
+
+  test('the fragment reader fails loudly when the base CHANGELOG cannot be fetched, and treats an absent one as nothing released', () => {
+    const fx = fixture('fragments', { ...ONE, 'CHANGELOG.md': '# Changelog\n\n## [1.0.0.0]\n\n- one\n', 'changelog.d/pr.md': '- the PR entry\n' }, { 'CHANGELOG.md': '# Changelog\n\n## [1.0.0.1]\n\n- two\n\n## [1.0.0.0]\n\n- one\n' });
+    fx.cut();
+    expect(() => readFragments(fx.clone, fx.one, 'changelog.d', fx.two, 'CHANGELOG.md', 'skip')).toThrow(HistoryReadError);
+    expect(readFragments(fx.clone, fx.one, 'changelog.d', fx.two, 'NO-CHANGELOG.md', 'skip').errors).toEqual([]);
+  });
+});
+
+type Step = { name?: string; uses?: string; run?: string; with?: Record<string, unknown> };
+type Workflow = { jobs: Record<string, { steps?: Step[] }> };
+const workflow = (file: string) => Bun.YAML.parse(fs.readFileSync(path.join(WORKFLOWS, file), 'utf8')) as Workflow;
+const stepOf = (file: string, job: string, name: string) => workflow(file).jobs[job]!.steps!.find(st => st.name === name)!;
+
+describe.skipIf(!Bun.which('jq') || !Bun.which('bash'))('the workflow steps that read history fail loudly', () => {
+  function runStep(script: string, fx: Fixture, env: Record<string, string>, helperAt = '.github/scripts') {
+    fs.mkdirSync(path.join(fx.clone, helperAt), { recursive: true });
+    fs.copyFileSync(HELPER, path.join(fx.clone, helperAt, 'history-read.sh'));
+    const bin = path.join(fx.clone, '.stub-bin');
+    fs.mkdirSync(bin, { recursive: true });
+    fs.writeFileSync(path.join(bin, 'sleep'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+    const out = path.join(fx.clone, '.github-output');
+    fs.writeFileSync(out, '');
+    const r = spawnSync('bash', ['-e', '-c', script], { cwd: fx.clone, encoding: 'utf8', timeout: 60_000,
+      env: { PATH: `${bin}:${process.env.PATH ?? ''}`, HOME: fx.clone, HISTORY_READ_BACKOFF_SECONDS: '0', GITHUB_OUTPUT: out, GITHUB_STEP_SUMMARY: path.join(fx.clone, '.summary'), ...env } });
+    const outputs = Object.fromEntries(fs.readFileSync(out, 'utf8').split('\n').filter(Boolean).map(line => [line.slice(0, line.indexOf('=')), line.slice(line.indexOf('=') + 1)]));
+    return { status: r.status, log: r.stdout + r.stderr, outputs };
+  }
+  const policySteps = [
+    { file: 'evals.yml', job: 'route', name: 'Read the train policy (base revision)', env: (fx: Fixture) => ({ BASE_SHA: fx.two, DEFAULT_BRANCH: 'main' }) },
+    { file: 'evals-main-backstop.yml', job: 'backstop', name: 'Read the train policy (main)', env: (fx: Fixture) => ({ GITHUB_SHA: fx.two }) },
+  ];
+
+  for (const { file, job, name, env } of policySteps) {
+    test(`${file} ${job}: an unfetchable policy fails, a malformed one fails, an absent one routes as before`, () => {
+      const script = stepOf(file, job, name).run!;
+      expect(script, 'the policy read runs no repository code: git and jq only').not.toMatch(/\.github\/scripts|\bbun\b/);
+      expect(script).not.toContain('|| true');
+      expect(script).not.toContain('2>/dev/null');
+
+      const trained = { [POLICY]: JSON.stringify({ bump: 'patch', train: TRAIN }) };
+      const reachable = fixture(`${job}-reachable`, ONE, trained);
+      expect(runStep(script, reachable, env(reachable))).toMatchObject({ status: 0, outputs: { train: 'true' } });
+      const unreadable = fixture(`${job}-unreadable`, ONE, trained);
+      unreadable.cut();
+      const failed = runStep(script, unreadable, env(unreadable));
+      expect(failed.status).not.toBe(0);
+      expect(failed.log).toContain('(HISTORY_READ_FAILED)');
+      expect(failed.outputs).toEqual({});
+
+      const malformed = fixture(`${job}-malformed`, ONE, { [POLICY]: '{not json' });
+      const bad = runStep(script, malformed, env(malformed));
+      expect(bad.status).not.toBe(0);
+      expect(bad.log).toContain(`${malformed.two}:${POLICY} is not valid JSON`);
+
+      const absent = fixture(`${job}-absent`, ONE, { [POLICY]: null });
+      absent.cut();
+      expect(runStep(script, absent, env(absent))).toMatchObject({ status: 0, outputs: { train: 'false' } });
+    });
+  }
+
+  test('version-gate.yml Read versions: the base VERSION is read, an absent one is 0.0.0.0, a failed fetch fails', () => {
+    const script = stepOf('version-gate.yml', 'check', 'Read versions').run!
+      .replace('${{ github.event.pull_request.base.ref }}', 'main');
+    expect(script).not.toContain('|| true');
+    expect(script).not.toContain('2>/dev/null');
+
+    const bumped = fixture('gate-bumped', ONE, { VERSION: '1.0.0.1\n' });
+    expect(runStep(script, bumped, {}, '.version-gate/.github/scripts')).toMatchObject({ status: 0, outputs: { pr_version: '1.0.0.0', base_version: '1.0.0.1', base_ref: 'main' } });
+
+    const unversioned = fixture('gate-unversioned', ONE, { VERSION: null });
+    expect(runStep(script, unversioned, {}, '.version-gate/.github/scripts').outputs.base_version).toBe('0.0.0.0');
+
+    bumped.cut();
+    const failed = runStep(script, bumped, {}, '.version-gate/.github/scripts');
+    expect(failed.status).not.toBe(0);
+    expect(failed.log).toContain('git fetch origin main failed 3 times');
+    expect(failed.log).toContain('(HISTORY_READ_FAILED)');
+  });
+});
+
+describe('checkout mode on the PR and train path', () => {
+  const files = fs.readdirSync(WORKFLOWS).filter(f => /\.ya?ml$/.test(f)).sort();
+
+  test('every full-history checkout is blobless unless its workflow keeps full clones for a named reason', () => {
+    const problems: string[] = [];
+    const fullHistory = new Set<string>();
+    for (const file of files) {
+      const text = fs.readFileSync(path.join(WORKFLOWS, file), 'utf8');
+      const checkoutLines = text.split('\n').flatMap((line, i) => (/^\s*(-\s+)?uses:\s*actions\/checkout@/.test(line) ? [i + 1] : []));
+      const steps = Object.entries((Bun.YAML.parse(text) as Workflow).jobs ?? {}).flatMap(([job, j]) => (j.steps ?? []).filter(st => st.uses?.startsWith('actions/checkout@')).map(st => ({ job, st })));
+      expect(steps.length, file).toBe(checkoutLines.length);
+      steps.forEach(({ job, st }, i) => {
+        const depth = st.with?.['fetch-depth'];
+        if (!(depth === 0 || depth === '0' || (typeof depth === 'string' && depth.includes("'0'")))) return;
+        fullHistory.add(file);
+        const at = `.github/workflows/${file}:${checkoutLines[i]}`;
+        if (FULL_CLONE_WORKFLOWS[file]) {
+          if (st.with?.filter !== undefined) problems.push(`${at}: job ${job} sets filter but ${file} is in FULL_CLONE_WORKFLOWS; remove one or the other`);
+          return;
+        }
+        if (st.with?.filter !== 'blob:none') problems.push(`${at}: job ${job} checks out full history without a blobless filter. Add \`filter: blob:none\` under its \`with:\`, or name ${file} in FULL_CLONE_WORKFLOWS (test/ci-history-read.test.ts) with the reason it needs every blob.`);
+      });
+    }
+    expect(problems).toEqual([]);
+    for (const [file, reason] of Object.entries(FULL_CLONE_WORKFLOWS)) {
+      expect(reason.length, file).toBeGreaterThan(20);
+      expect(fullHistory.has(file), `${file} has no full-history checkout left; drop it from FULL_CLONE_WORKFLOWS`).toBe(true);
+    }
+  });
+
+  test('the PR and train path jobs check out blobless full history', () => {
+    for (const [file, jobs] of Object.entries(BLOBLESS_JOBS)) {
+      for (const job of jobs) {
+        const checkout = workflow(file).jobs[job]!.steps!.find(st => st.uses?.startsWith('actions/checkout@'))!;
+        expect(checkout.with?.filter, `${file} ${job}`).toBe('blob:none');
+      }
+    }
+  });
+
+  test('the eval image asserts its Git makes a blobless clone and fetches a missing blob', () => {
+    const dockerfile = fs.readFileSync(path.join(ROOT, '.github', 'docker', 'Dockerfile.ci'), 'utf8');
+    for (const part of ['git clone -q --filter=blob:none --no-local', 'config remote.origin.promisor)" = true', 'GIT_NO_LAZY_FETCH=1 git -C "$d/clone" cat-file -e HEAD~1:f', 'show HEAD~1:f)" = one']) expect(dockerfile).toContain(part);
+  });
+});
diff --git a/test/evals-train-workflow.test.ts b/test/evals-train-workflow.test.ts
index cf3c8b71e..4e098f78e 100644
--- a/test/evals-train-workflow.test.ts
+++ b/test/evals-train-workflow.test.ts
@@ -392,7 +392,7 @@ describe.skipIf(!Bun.which('jq') || !Bun.which('bash'))('the route job reads the
   const block = { gate_workflow: 'evals.yml', free_workflow: 'free-tests.yml', full_gate_check: 'gstack/full-gate', record_artifact: 'gstack-train-record', max_size: 5, fill_hours: 3, screen_selection: 'none', trial_reservation_usd: 1.5 };
 
   test('no policy, no train block, or an invalid one: train=false, and a PR push routes pr', () => {
-    for (const policy of [undefined, { bump: 'patch' }, { bump: 'patch', train: null }, { train: { ...block, record_artifact: 'bad name!' } }, '{not json']) {
+    for (const policy of [undefined, { bump: 'patch' }, { bump: 'patch', train: null }, { train: { ...block, record_artifact: 'bad name!' } }]) {
       const fx = fixture(policy);
       const out = run(policyStep.run!, fx.dir, { BASE_SHA: fx.base, DEFAULT_BRANCH: 'main' });
       expect(out, JSON.stringify(policy)).toEqual({ train: 'false' });
@@ -401,6 +401,12 @@ describe.skipIf(!Bun.which('jq') || !Bun.which('bash'))('the route job reads the
     }
   });
 
+  test('a policy that is not JSON fails the route instead of routing as before (GSTA-203 H1)', () => {
+    const fx = fixture('{not json');
+    expect(() => run(policyStep.run!, fx.dir, { BASE_SHA: fx.base, DEFAULT_BRANCH: 'main' })).toThrow('.gstack/ship-policy.json is not valid JSON');
+    fs.rmSync(fx.dir, { recursive: true, force: true });
+  });
+
   test('a train block names the record artifact and check, and a PR push routes pr-summary', () => {
     const fx = fixture({ bump: 'patch', train: block });
     const out = run(policyStep.run!, fx.dir, { BASE_SHA: fx.base, DEFAULT_BRANCH: 'main' });

From e4e4e42967c3bde658ec3a42df62f37e69ca0f1a Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 01:35:42 -0800
Subject: [PATCH 2/5] v1.92.22.0 feat: Gemini CLI host, and older installs drop
 the dev toolchain (#3778)

* setup: explicit contributor marker; move pre-v1.91.231.0 installs to production deps (#3447)

./setup used node_modules/typescript as its contributor signal, so every
install made before v1.91.231.0 (a full bun install) kept ~520 MB of test and
eval packages forever. The contributor is now the clone bin/dev-setup marks
with git config gstack.contributor true, or GSTACK_CONTRIBUTOR=1. An unmarked
clone with the dev toolchain moves node_modules aside under a checkout lock,
installs production-only, verifies every dependency, and drops the backup; any
failure puts the full install back with SETUP_DEPS_MIGRATE_FAILED. CI and a
clone whose git config cannot be read never migrate. Bun cache entries for the
pinned Agent SDK are removed only when no other project links to them.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* hosts: add Gemini CLI as an experimental host (#1247)

./setup --host gemini (alias gemini-cli; --host auto when gemini is on PATH)
installs gstack-<skill> directories into ~/.gemini/skills, which Gemini CLI
0.66.0 lists with gemini skills list, plus the ~/.gemini/skills/gstack runtime
root. Renders go to .gemini-cli/ (gitignored) with name+description
frontmatter whose names match their directories, CLAUDE.md rewritten to
GEMINI.md, and a tool glossary for Gemini CLI's names (and Antigravity's, which
can read the same folder). gstack-uninstall removes only gstack-managed entries
there, so the user's own skills stay. Docs: ADDING_A_HOST.md verified facts,
hosts.md, uninstall.md, README.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (leave Bun's shared cache alone)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* changelog: Gemini CLI host and contributor marker (#1247, #3447)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: host lists name Copilot, Antigravity and Gemini CLI

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: the plan-mode re-render guard count includes the Gemini CLI host

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: troubleshooting's runtime-root guard host list names Gemini CLI

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 .gitignore                                 |   3 +
 CHANGELOG.md                               |  14 +
 CLAUDE.md                                  |   2 +-
 CONTRIBUTING.md                            |   8 +-
 README.md                                  |   3 +-
 VERSION                                    |   2 +-
 agents-digest/gstack-AGENTS.md             |   2 +-
 bin/dev-setup                              |   9 +-
 bin/gstack-doctor-components.sh            |   1 +
 bin/gstack-host-renders.sh                 |   2 +-
 bin/gstack-install-registry.sh             |   3 +-
 bin/gstack-team-init                       |   4 +-
 bin/gstack-uninstall                       |  18 ++
 docs/ADDING_A_HOST.md                      |  62 ++++-
 docs/PROJECT_STRUCTURE.md                  |   1 +
 docs/hosts.md                              |   8 +
 docs/troubleshooting.md                    |  23 +-
 docs/uninstall.md                          |   1 +
 hosts/gemini.ts                            |  59 +++++
 hosts/index.ts                             |   7 +-
 lib/result-codes.ts                        |   5 +
 package.json                               |   2 +-
 setup                                      | 239 +++++++++++++++--
 test/fixtures/skill-md-size-allowlist.json |   5 +
 test/gen-skill-docs.test.ts                |   2 +-
 test/host-config.test.ts                   |  56 +++-
 test/host-conformance.test.ts              |   5 +-
 test/host-renders-prune.test.ts            |   4 +-
 test/plan-mode-preamble-render.test.ts     |   2 +-
 test/runtime-root-assets.test.ts           |   1 +
 test/setup-install-registry.test.ts        |  93 ++++++-
 test/setup-production-deps.test.ts         | 294 ++++++++++++++++++++-
 test/setup-runtime-root-guard.test.ts      |   4 +-
 test/uninstall.test.ts                     |  40 +++
 34 files changed, 910 insertions(+), 74 deletions(-)
 create mode 100644 hosts/gemini.ts

diff --git a/.gitignore b/.gitignore
index 6a3ae8915..b042b9ded 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
 .env
 node_modules/
+node_modules.gstack-migrate/
+node_modules.gstack-migrate.lock/
 dist/
 browse/dist/
 design/dist/
@@ -40,6 +42,7 @@ lib/cso/images/gstack-cso-preparation
 .cursor/
 .copilot/
 .agy/
+.gemini-cli/
 .openclaw/
 .hermes/
 .gbrain/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4af548dec..6b891029a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.92.22.0] - 2026-11-01
+
+**gstack installs into Gemini CLI, and installs made before v1.91.231.0 finally drop the test and eval packages they never needed.** `./setup --host gemini` puts every gstack skill in `~/.gemini/skills`, where Gemini CLI 0.66.0 lists them (#1247). Separately, `./setup` used to treat any checkout that had TypeScript installed as a contributor's, so every install made before v1.91.231.0 (which ran a full `bun install`) kept about 510 MB of dev packages in `node_modules` forever (#3447).
+
+### Added
+- **Gemini CLI host** (experimental): `./setup --host gemini` (alias `gemini-cli`; `--host auto` picks it only when `gemini` is on PATH) links `gstack-<skill>` directories into `~/.gemini/skills` plus the `~/.gemini/skills/gstack` runtime root. The render goes to `.gemini-cli/` with frontmatter names that match their directories, `CLAUDE.md` read as `GEMINI.md`, and a tool glossary for Gemini CLI's tool names and for Antigravity CLI, which can read the same folder. Ask for a skill by name (`gstack-office-hours`); Gemini CLI loads it with `activate_skill`. `gstack-uninstall` removes only gstack-managed entries there, so your own skills stay. `--local --host gemini` is refused with a note that Gemini CLI loads workspace skills only in trusted folders. docs/ADDING_A_HOST.md lists the verified facts.
+- **An explicit contributor marker**: `bin/dev-setup` runs `git config gstack.contributor true`, and `GSTACK_CONTRIBUTOR=1` marks a single run. A marked clone keeps the full install on every `./setup`.
+
+### Changed
+- **An unmarked clone that still has the dev toolchain moves to production dependencies once.** setup takes a lock in the checkout, moves `node_modules` aside, installs production dependencies, checks every runtime package resolves, then deletes the old copy. If the install fails, the full `node_modules` goes back and setup prints `SETUP_DEPS_MIGRATE_FAILED` with the cause; nothing is removed and the next `./setup` tries again. CI, and a checkout whose git config cannot be read, never migrate. On a real install `node_modules` went from 1079 MB to 569 MB. Bun's shared package cache is left alone, because other projects can read it through symlinks.
+
+### Tests
+- test/setup-production-deps.test.ts: the marker (git config, env, CI, unreadable git config), the one-time migration and its no-op rerun, restore on a failed or unverified install, recovery of an interrupted move, the lock, an untouched Bun cache, and a real-Bun fixture for a marked and an unmarked clone. test/uninstall.test.ts: Gemini CLI entries removed, the user's own kept. Host config, conformance, install-registry, render-prune and runtime-root tests cover the new host.
+
 ## [1.92.21.0] - 2026-11-01
 
 **The PR and train path check out blobless clones, and the history reads they gate on fail loudly instead of reading a failed fetch as "absent" (GSTA-203 PR 5).** Free Tests' plan job, the Version Gate and E2E Evals' route, screen summary, planner, slices, reruns, bisect and report checked out every file of every commit (about 232 MB) to read a handful of old files. They now check out with `filter: blob:none` (about 17 MB), and git fetches an old file's contents the first time something reads it.
diff --git a/CLAUDE.md b/CLAUDE.md
index d425dc6e7..f2a630b7b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,7 +129,7 @@ and commit both; never edit the generated file
 (`test/design-checklist-sync.test.ts` fails on drift).
 
 Generation uses each host's `defaultModel` (`claude` for most hosts, `gpt`
-for Codex, `gemini` for Antigravity's `agy`) unless `--model` is explicit. Codex installs additionally read the
+for Codex, `gemini` for Antigravity's `agy` and Gemini CLI) unless `--model` is explicit. Codex installs additionally read the
 top-level model from `${CODEX_HOME:-~/.codex}/config.toml`; rerun
 `./setup --host codex` after changing that model. Note: `bun run build` and a
 bare `gen:skill-docs --host codex` render the host default (gpt) — if your
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 715592905..6132d56ac 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ bun install                    # install dependencies
 bin/dev-setup                  # activate dev mode
 ```
 
-`./setup` on its own installs production dependencies only. `bun install` (and `bin/dev-setup`, which runs it) adds the dev toolchain the tests and evals need: the Claude Agent SDK, TypeScript and Prettier. Once they are installed, a later `./setup` runs the full install too, so they stay at `bun.lock`'s versions.
+`./setup` on its own installs production dependencies only. `bin/dev-setup` adds the dev toolchain the tests and evals need (the Claude Agent SDK, TypeScript and Prettier) and marks the clone as a contributor's with `git config gstack.contributor true`. In a marked clone a later `./setup` runs the full install too, so the toolchain stays at `bun.lock`'s versions. In an unmarked clone `./setup` moves back to production dependencies, which is how installs made before v1.91.231.0 drop the toolchain they never needed. If you ran plain `bun install` instead of `bin/dev-setup`, run `git config gstack.contributor true` once, or set `GSTACK_CONTRIBUTOR=1` for a single run.
 
 > **Full clone vs shallow.** The README's user-facing install uses `--depth 1` for speed. As a contributor, use a full clone (no `--depth` flag) — you'll need history for `git log`, `git blame`, `git bisect`, and reviewing PRs against earlier versions. If you already have a `--depth 1` clone from following the README, promote it to a full clone with `git fetch --unshallow`.
 
@@ -736,11 +736,11 @@ worth the review overhead.
 
 ## Multi-host development
 
-gstack generates SKILL.md files for 10 hosts from one set of `.tmpl` templates.
+gstack generates SKILL.md files for 13 hosts from one set of `.tmpl` templates.
 Each host is a typed config in `hosts/*.ts`. The generator reads these configs
 to produce host-appropriate output (different frontmatter, paths, tool names).
 
-**Supported hosts:** Claude (primary), Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes, GBrain.
+**Supported hosts:** Claude (primary), Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes, GBrain, Copilot, Antigravity, Gemini CLI.
 
 ### Generating for all hosts
 
@@ -749,7 +749,7 @@ to produce host-appropriate output (different frontmatter, paths, tool names).
 bun run gen:skill-docs                    # Claude (default)
 bun run gen:skill-docs --host codex       # Codex
 bun run gen:skill-docs --host opencode    # OpenCode
-bun run gen:skill-docs --host all         # All 10 hosts
+bun run gen:skill-docs --host all         # All 13 hosts
 
 # Or use build, which does all hosts + compiles binaries
 bun run build
diff --git a/README.md b/README.md
index c10f1ae0f..011832a81 100644
--- a/README.md
+++ b/README.md
@@ -77,12 +77,13 @@ installs and passes the conformance tests but has no certification run yet;
 | Kiro | experimental | `--host kiro` → `~/.kiro/skills/gstack-*/` | ask for `gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host kiro` |
 | GitHub Copilot CLI | experimental | `--host copilot` → `~/.copilot/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host copilot` |
 | Antigravity CLI | experimental | `--host agy` (or `--host antigravity`) → `~/.gemini/antigravity-cli/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host agy` |
+| Gemini CLI | experimental | `--host gemini` (or `--host gemini-cli`) → `~/.gemini/skills/gstack-*/` | ask for `gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host gemini` |
 | Slate | instruction-only | `--host slate` (points at the Claude install; Slate reads `.claude/skills`) | `/office-hours` via the Claude install | advisory, not blocked | — | `./setup --host claude` |
 | OpenClaw | experimental | `--host openclaw` (five task skills and one `gstack` router skill in OpenClaw's skills folder; automatic when setup runs inside OpenClaw; ACP route in [docs/OPENCLAW.md](docs/OPENCLAW.md)) | ask for the task; the agent opens the matching task skill or the `gstack` router | advisory, not blocked | — | `./setup --host openclaw` |
 | Hermes | experimental | `--host hermes` (every skill in `$HERMES_HOME/skills/gstack`; automatic when setup runs inside Hermes) | ask for the task, or `/gstack-review` | advisory, not blocked | — | `./setup --host hermes` |
 | GBrain (mod) | instruction-only | `--host gbrain` (brain-aware variants ship from the GBrain repo) | — | advisory, not blocked | — | — |
 
-Per-host notes (agent harnesses, Copilot, Antigravity, OpenClaw and ClawHub, the Codex behavioral profile and model tiers, outside-review providers, the design binary's models) are in [docs/hosts.md](docs/hosts.md). Any rules-reading agent (Zed, Amp, Jules) can use the 2KB [agents digest](agents-digest/gstack-AGENTS.md) with no install. Adding a host: [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md).
+Per-host notes (agent harnesses, Copilot, Antigravity, Gemini CLI, OpenClaw and ClawHub, the Codex behavioral profile and model tiers, outside-review providers, the design binary's models) are in [docs/hosts.md](docs/hosts.md). Any rules-reading agent (Zed, Amp, Jules) can use the 2KB [agents digest](agents-digest/gstack-AGENTS.md) with no install. Adding a host: [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md).
 
 ## See it work
 
diff --git a/VERSION b/VERSION
index 702e3354d..893844ff7 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.92.21.0
+1.92.22.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index ba555e925..cee2c4bf1 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.92.21.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.92.22.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/bin/dev-setup b/bin/dev-setup
index f77026715..9a8f6f6f6 100755
--- a/bin/dev-setup
+++ b/bin/dev-setup
@@ -22,9 +22,12 @@ if [ ! -f "$REPO_ROOT/.env" ]; then
   fi
 fi
 
-# 2. Install dependencies, devDependencies included. Always run: a checkout
-# first installed by ./setup has production dependencies only, and an
-# up-to-date install is a no-op.
+# 2. Install dependencies, devDependencies included, and mark this clone as a
+# contributor's (#3447) so ./setup keeps the dev toolchain instead of moving it
+# to the production-only install. Always run: a checkout first installed by
+# ./setup has production dependencies only, and an up-to-date install is a no-op.
+git -C "$REPO_ROOT" config --local gstack.contributor true 2>/dev/null \
+  || echo "Warning: could not set git config gstack.contributor in $REPO_ROOT; export GSTACK_CONTRIBUTOR=1 before ./setup to keep the dev toolchain." >&2
 echo "Installing dependencies..."
 (cd "$REPO_ROOT" && bun install)
 
diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh
index ef78dec8f..e592bae08 100644
--- a/bin/gstack-doctor-components.sh
+++ b/bin/gstack-doctor-components.sh
@@ -141,6 +141,7 @@ gstack_result_anchor() {
     BROWSER_UNAVAILABLE) printf '%s' 'browser-ensure-failed' ;;
     INSTALL_PREFLIGHT_FAILED) printf '%s' 'capy-install-preflight-failed' ;;
     SETUP_PS1_EMPTY_ARGUMENT) printf '%s' 'setup-ps1-empty-argument' ;;
+    SETUP_DEPS_MIGRATE_FAILED) printf '%s' 'setup-deps-migrate-failed' ;;
     POLICY_SOURCE_UNAVAILABLE) printf '%s' 'policy-source-unavailable' ;;
     POLICY_INVALID) printf '%s' 'policy-invalid' ;;
     POLICY_CONTAINMENT) printf '%s' 'policy-containment' ;;
diff --git a/bin/gstack-host-renders.sh b/bin/gstack-host-renders.sh
index 83e667c87..b0295a6fb 100644
--- a/bin/gstack-host-renders.sh
+++ b/bin/gstack-host-renders.sh
@@ -24,7 +24,7 @@
 # host:render-dir for every host whose render lives in its own checkout dir.
 # Claude renders into the tracked tree. test/host-renders.test.ts keeps this
 # equal to hostSubdir in hosts/*.ts.
-GSTACK_HOST_RENDER_DIRS="codex:.agents kiro:.kiro factory:.factory opencode:.opencode cursor:.cursor copilot:.copilot agy:.agy slate:.slate openclaw:.openclaw hermes:.hermes gbrain:.gbrain"
+GSTACK_HOST_RENDER_DIRS="codex:.agents kiro:.kiro factory:.factory opencode:.opencode cursor:.cursor copilot:.copilot agy:.agy gemini:.gemini-cli slate:.slate openclaw:.openclaw hermes:.hermes gbrain:.gbrain"
 
 gstack_render_hosts_file() { printf '%s/.gstack-installed-hosts\n' "$1"; }
 
diff --git a/bin/gstack-install-registry.sh b/bin/gstack-install-registry.sh
index 0fe5e9e91..27ed91c57 100644
--- a/bin/gstack-install-registry.sh
+++ b/bin/gstack-install-registry.sh
@@ -184,7 +184,7 @@ gstack_install_render_for() {
 gstack_host_tier() {
   case "$1" in
     claude) echo full ;;
-    codex|kiro|factory|opencode|cursor|copilot|agy|openclaw|hermes) echo experimental ;;
+    codex|kiro|factory|opencode|cursor|copilot|agy|gemini|openclaw|hermes) echo experimental ;;
     slate|gbrain) echo instruction-only ;;
     *) echo unknown ;;
   esac
@@ -256,6 +256,7 @@ gstack_install_known_roots() {
   printf 'cursor\tglobal\t%s\t%s\n' "$HOME/.cursor/skills" "$HOME/.cursor/skills/gstack"
   printf 'copilot\tglobal\t%s\t%s\n' "$HOME/.copilot/skills" "$HOME/.copilot/skills/gstack"
   printf 'agy\tglobal\t%s\t%s\n' "$HOME/.gemini/antigravity-cli/skills" "$HOME/.gemini/antigravity-cli/skills/gstack"
+  printf 'gemini\tglobal\t%s\t%s\n' "$HOME/.gemini/skills" "$HOME/.gemini/skills/gstack"
   proj="$(git rev-parse --show-toplevel 2>/dev/null || true)"
   if [ -n "$proj" ] && [ "$proj" != "$HOME" ]; then
     printf 'claude\tproject\t%s\t%s\n' "$proj/.claude/skills" "$proj/.claude/skills/gstack"
diff --git a/bin/gstack-team-init b/bin/gstack-team-init
index d284ad04c..f27cfe7dd 100755
--- a/bin/gstack-team-init
+++ b/bin/gstack-team-init
@@ -82,7 +82,7 @@ else
 
 ```bash
 _GS=""
-for _D in "${GSTACK_ROOT:-}" "$HOME/.claude/skills/gstack" "$HOME/.codex/skills/gstack" "$HOME/.factory/skills/gstack" "$HOME/.kiro/skills/gstack" "$HOME/.config/opencode/skills/gstack" "$HOME/.slate/skills/gstack" "$HOME/.cursor/skills/gstack" "$HOME/.openclaw/skills/gstack" "$HOME/.hermes/skills/gstack" "$HOME/.gbrain/skills/gstack" "$HOME/.copilot/skills/gstack" "$HOME/.gemini/antigravity-cli/skills/gstack" "$HOME/.gstack/repos/gstack"; do
+for _D in "${GSTACK_ROOT:-}" "$HOME/.claude/skills/gstack" "$HOME/.codex/skills/gstack" "$HOME/.factory/skills/gstack" "$HOME/.kiro/skills/gstack" "$HOME/.config/opencode/skills/gstack" "$HOME/.slate/skills/gstack" "$HOME/.cursor/skills/gstack" "$HOME/.openclaw/skills/gstack" "$HOME/.hermes/skills/gstack" "$HOME/.gbrain/skills/gstack" "$HOME/.copilot/skills/gstack" "$HOME/.gemini/antigravity-cli/skills/gstack" "$HOME/.gemini/skills/gstack" "$HOME/.gstack/repos/gstack"; do
   [ -z "$_GS" ] && [ -n "$_D" ] && [ -d "$_D/bin" ] && _GS="$_D"
 done
 [ -n "$_GS" ] && echo "GSTACK_OK: $_GS" || echo "GSTACK_MISSING"
@@ -153,7 +153,7 @@ const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 const roots = [process.env.GSTACK_ROOT || ''].concat([
   '.claude/skills/gstack', '.codex/skills/gstack', '.factory/skills/gstack', '.kiro/skills/gstack',
   '.config/opencode/skills/gstack', '.slate/skills/gstack', '.cursor/skills/gstack', '.openclaw/skills/gstack',
-  '.hermes/skills/gstack', '.gbrain/skills/gstack', '.copilot/skills/gstack', '.gemini/antigravity-cli/skills/gstack', '.gstack/repos/gstack',
+  '.hermes/skills/gstack', '.gbrain/skills/gstack', '.copilot/skills/gstack', '.gemini/antigravity-cli/skills/gstack', '.gemini/skills/gstack', '.gstack/repos/gstack',
 ].map((rel) => path.join(home, rel)));
 const gstackRoot = roots.find((root) => {
   try { return root !== '' && fs.statSync(path.join(root, 'bin')).isDirectory(); } catch { return false; }
diff --git a/bin/gstack-uninstall b/bin/gstack-uninstall
index 5bbc12222..c88a53568 100755
--- a/bin/gstack-uninstall
+++ b/bin/gstack-uninstall
@@ -24,6 +24,7 @@
 #   ~/.config/opencode/skills/gstack* — OpenCode skill install + per-skill symlinks
 #   ~/.copilot/skills/gstack*     — GitHub Copilot CLI skill install + per-skill symlinks
 #   ~/.gemini/antigravity-cli/skills/gstack* — Antigravity CLI skill install + per-skill symlinks
+#   ~/.gemini/skills/gstack*      — Gemini CLI skill install + per-skill symlinks (gstack-managed only)
 #   harness registrations         — every file gstack-harness wrote into OpenClaw,
 #                                   Hermes, a Dot or another harness (from its
 #                                   ledger; edited files move to a backup), and
@@ -141,6 +142,7 @@ if [ "$FORCE" -eq 0 ]; then
   [ -d "$HOME/.config/opencode/skills" ] && echo "  ~/.config/opencode/skills/gstack*"
   [ -d "$HOME/.copilot/skills" ] && echo "  ~/.copilot/skills/gstack*"
   [ -d "$HOME/.gemini/antigravity-cli/skills" ] && echo "  ~/.gemini/antigravity-cli/skills/gstack*"
+  [ -d "$HOME/.gemini/skills" ] && echo "  ~/.gemini/skills/gstack*"
   [ "$KEEP_STATE" -eq 0 ] && [ -d "$STATE_DIR" ] && echo "  $STATE_DIR"
   [ -n "$_LEAVE_ROOT" ] && echo "  (kept) $_LEAVE_ROOT: state root selected by $RESOLVED_VAR; left in place"
 
@@ -546,6 +548,22 @@ if [ -d "$ANTIGRAVITY_SKILLS" ]; then
   done
 fi
 
+# ─── Remove Gemini CLI skills ───────────────────────────────
+# Same provenance gate. ~/.gemini/skills also holds the user's own skills, so
+# only gstack-managed gstack* entries go.
+GEMINI_SKILLS="$HOME/.gemini/skills"
+if [ -d "$GEMINI_SKILLS" ]; then
+  for _ITEM in "$GEMINI_SKILLS"/gstack*; do
+    [ -e "$_ITEM" ] || [ -L "$_ITEM" ] || continue
+    if _cursor_item_is_gstack_managed "$_ITEM"; then
+      rm -rf "$_ITEM"
+      REMOVED+=("gemini/$(basename "$_ITEM")")
+    else
+      _SKIPPED_DIRS+=("$_ITEM")
+    fi
+  done
+fi
+
 # ─── Reconcile the install registry ─────────────────────────
 # A registry that survives (--keep-state, or a state root selected by an env
 # var and left in place) must forget the installs removed above, or the next
diff --git a/docs/ADDING_A_HOST.md b/docs/ADDING_A_HOST.md
index 07e12b395..f58fffe83 100644
--- a/docs/ADDING_A_HOST.md
+++ b/docs/ADDING_A_HOST.md
@@ -2,7 +2,7 @@
 
 gstack uses a declarative host config system. Each supported AI coding agent
 (Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes,
-GBrain, Copilot, Antigravity) is defined as a typed TypeScript config object built by the
+GBrain, Copilot, Antigravity, Gemini CLI) is defined as a typed TypeScript config object built by the
 `defineHost()` factory. Rendering a new host means creating one file and
 re-exporting it: the generator, tests, and validation pick it up. Installing
 it is not free: setup still has one install arm per installable host (see
@@ -76,13 +76,13 @@ Inventory of every setup side effect, by phase (line numbers are approximate):
 |---|---|---|
 | Build | `browse/dist`, `design/dist`, `make-pdf/dist`, `bin/gstack-cso-*` in the source checkout | source |
 | Hosts record | `.gstack-installed-hosts` in the source checkout: every host setup installed from it, additive (#1694) | source |
-| Generation | renders for the recorded hosts only (`.agents/`, `.kiro/`, `.factory/`, `.opencode/`, `.cursor/`, `.copilot/`, `.agy/`) in the source checkout; `gstack-patch-names` rewrites Claude `name:` fields in place | source |
+| Generation | renders for the recorded hosts only (`.agents/`, `.kiro/`, `.factory/`, `.opencode/`, `.cursor/`, `.copilot/`, `.agy/`, `.gemini-cli/`) in the source checkout; `gstack-patch-names` rewrites Claude `name:` fields in place | source |
 | Render prune | renders of hosts the record does not name: links into the checkout removed, generated files moved to `$GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/`, other files kept | source / state root |
 | Chromium | Playwright cache (`~/.cache/ms-playwright`), lock under the state root | machine |
 | Config | `skill_prefix`, `timeline_stop_hook`, team-mode keys in `$GSTACK_STATE_ROOT/config.yaml` | state root |
 | Claude arm | `~/.claude/skills/gstack` link, one dir per skill with a `SKILL.md` link, alias copies | selected host |
 | Codex arm | `${CODEX_HOME:-~/.codex}/skills/gstack` runtime root, `gstack-*` links into `.agents/skills`, `.agents/skills/gstack` sidecar | selected host |
-| Kiro, Factory, OpenCode, Cursor, Copilot, Antigravity arms | the host's `skills/gstack` runtime root (built beside the live one and swapped in) and `gstack-*` links | selected host |
+| Kiro, Factory, OpenCode, Cursor, Copilot, Antigravity, Gemini CLI arms | the host's `skills/gstack` runtime root (built beside the live one and swapped in) and `gstack-*` links | selected host |
 | OpenCode commands | `~/.config/opencode/commands/gstack-*.md` with a managed marker (#2629); user command files are never touched | selected host |
 | Registry | one row per activated install in `installs.tsv` | state root |
 | Migrations | whatever each `v*.sh` repairs; marker in the state root | state root |
@@ -245,12 +245,15 @@ which Google's docs do not state, so the rendered text names no number.
 
 **Shared `~/.gemini`.** Antigravity CLI and Gemini CLI both live under
 `~/.gemini`. Gemini CLI reads `~/.gemini/skills` (and `~/.agents/skills`);
-Antigravity CLI reads `~/.gemini/antigravity-cli/skills`. Setup writes only
-gstack entries in the latter, uninstall removes only gstack-managed entries
-there, and `--host auto` selects Antigravity only for `agy` on `PATH` or an
-existing `~/.gemini/antigravity-cli`, never for a bare `~/.gemini`.
-`test/setup-install-registry.test.ts` holds both directions. Gemini CLI as a
-host is not supported. Two overlaps remain: workspace `.agents/skills` is also
+Antigravity CLI reads `~/.gemini/antigravity-cli/skills`, and Google's
+migration table lists `~/.gemini/skills` as an Antigravity global path too.
+Each host's arm writes only gstack entries in its own directory, uninstall
+removes only gstack-managed entries in each, and `--host auto` selects
+Antigravity only for `agy` on `PATH` or an existing
+`~/.gemini/antigravity-cli`, and Gemini CLI only for `gemini` on `PATH`,
+never either for a bare `~/.gemini`. `test/setup-install-registry.test.ts`
+holds every direction, including both hosts installed together. Gemini CLI is
+its own host ("Gemini CLI" below). Two overlaps remain: workspace `.agents/skills` is also
 where a project-local Codex install puts its Codex-flavored `gstack-*`
 skills, which Antigravity will list in that repo, and the Antigravity 2.0 app
 and IDE read `~/.gemini/config/skills`, which this host does not install
@@ -277,6 +280,46 @@ root's extra markdown files (`ETHOS.md`, `review/*.md`) as skills, the
 partial-read behavior of `view_file` on long skills, `ask_question` option
 handling, and an upgrade from an existing install.
 
+## Gemini CLI (#1247)
+
+Shipped as `experimental` (`hosts/gemini.ts`, `./setup --host gemini`, alias
+`--host gemini-cli`). Verified against Gemini CLI 0.66.0 (its bundled
+`docs/cli/skills.md` and `SkillManager.discoverSkills`) on 2026-10-31:
+
+| Fact | Value | Source |
+|---|---|---|
+| User skills | `~/.gemini/skills/<skill>/SKILL.md`, and the `~/.agents/skills` alias, which wins inside the user tier | [Agent Skills](https://geminicli.com/docs/cli/skills/), `packages/core/src/skills/skillManager.ts` |
+| Workspace skills | `.gemini/skills` and the `.agents/skills` alias, loaded only in a trusted folder (`/trust`) | same |
+| Precedence | built-in < extension < user < workspace; same name: the higher tier wins | same |
+| Discovery | `<dir>/<name>/SKILL.md`, one level deep; symlinked skill dirs are followed; the name comes from frontmatter `name` | same |
+| Invocation | the model calls `activate_skill` after you approve; `/skills list` and `gemini skills list` show them | same |
+| Tool names | `run_shell_command`, `read_file`, `read_many_files`, `write_file`, `replace`, `grep_search`, `glob`, `list_directory`, `ask_user`, `invoke_agent`, `activate_skill`, `enter_plan_mode`, `exit_plan_mode`, `write_todos`, `web_fetch`, `google_web_search` | 0.66.0 bundle |
+| Context file | `GEMINI.md` | 0.66.0 bundle |
+
+What the host does: skills in `~/.gemini/skills/gstack-*`, runtime root
+`~/.gemini/skills/gstack` with `.source-path` for `/gstack-upgrade`, `name:`
+equal to the `gstack-<skill>` directory, frontmatter limited to `name` and
+`description` (1024-character limit), the Gemini model overlay, and a
+one-paragraph tool glossary ahead of the preamble's STATUS rules. The glossary
+also names Antigravity's `run_command`, `view_file` and `ask_question`,
+because an Antigravity CLI that reads `~/.gemini/skills` sees these skills.
+The render directory is `.gemini-cli/` (gitignored), not `.gemini/`, so this
+repo's own trusted workspace never lists render output as skills. `--local`
+is refused: it installs only Claude, and Gemini CLI reads workspace skills only
+in trusted folders.
+
+Overlaps: inside a trusted repo, a project-local Codex install's `.agents/skills`
+(Codex-flavored `gstack-*` skills) is the workspace tier, which outranks
+`~/.gemini/skills`, so Gemini CLI uses those there. gstack never writes
+`~/.agents/skills`: that alias is shared with other tools and outranks
+`~/.gemini/skills`. Antigravity's own install stays in
+`~/.gemini/antigravity-cli/skills`.
+
+Unverified without a Gemini API key on the build machines (why it is not
+`full`): a live model run of any skill, `ask_user` option handling, and
+plan mode with gstack's plan-review skills. Discovery is verified:
+`gemini skills list` after `./setup --host gemini` lists the `gstack-*` skills.
+
 ## Instruction-only hosts and agent harnesses
 
 Slate and GBrain have no install arm. OpenClaw and Hermes are harness hosts:
@@ -313,6 +356,7 @@ hosts/
 ├── gbrain.ts        # GBrain
 ├── copilot.ts       # GitHub Copilot CLI
 ├── agy.ts           # Google Antigravity CLI
+├── gemini.ts        # Google Gemini CLI
 └── index.ts         # Registry: imports all, derives Host type
 ```
 
diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md
index cc71ce742..58532d09d 100644
--- a/docs/PROJECT_STRUCTURE.md
+++ b/docs/PROJECT_STRUCTURE.md
@@ -20,6 +20,7 @@ gstack/
 │   ├── codex.ts, factory.ts, kiro.ts  # Existing hosts
 │   ├── opencode.ts, slate.ts, cursor.ts, openclaw.ts  # IDE hosts
 │   ├── hermes.ts, gbrain.ts  # Agent runtime hosts
+│   ├── copilot.ts, agy.ts, gemini.ts  # GitHub Copilot CLI, Antigravity CLI, Gemini CLI
 │   └── index.ts     # Registry: exports all, derives Host type
 ├── scripts/         # Build + DX tooling
 │   ├── gen-skill-docs.ts  # Template → SKILL.md generator (config-driven)
diff --git a/docs/hosts.md b/docs/hosts.md
index 161e669a8..30eacb14c 100644
--- a/docs/hosts.md
+++ b/docs/hosts.md
@@ -137,6 +137,14 @@ Antigravity only when `agy` is on `PATH` or `~/.gemini/antigravity-cli` exists,
 never for a Gemini-CLI-only `~/.gemini`. The Antigravity 2.0 app and IDE read
 `~/.gemini/config/skills`, which this host does not install.
 
+Gemini CLI loads gstack skills itself when a task matches (`activate_skill`,
+after you approve); ask for `gstack-office-hours`, or list them with
+`/skills list`. Setup writes only `~/.gemini/skills/gstack*` and never
+`~/.agents/skills`, and `--host auto` selects Gemini CLI only when `gemini` is on
+`PATH`. Inside a repo with a project-local Codex install, Gemini CLI uses the
+Codex skills in `.agents/skills` (the workspace tier wins), and workspace skills
+load only in trusted folders (`/trust`).
+
 Outside reviews require the selected CLI to be installed and authenticated: Claude Code when using gstack in Codex, or Codex on other harnesses. External harnesses discover these commands as `/gstack-claude-code` and `/gstack-codex`; each harness omits its own wrapper. Explicit provider requests keep that provider. The existing `codex_reviews` setting controls automatic outside reviews where supported, regardless of the provider selected.
 
 `/claude` has been renamed to `/claude-code`. Re-run `./setup --host <name>` to migrate managed installations, including other harnesses sharing the checkout. Setup preserves the previous installation if replacement generation or installation fails and prints repair instructions.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 225c66bda..654641b76 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1239,8 +1239,8 @@ git -C ~/.claude/skills/gstack update-ref -d 'refs/gstack/rescue/<oid>'
 <a id="setup-runtime-root-contains-checkout"></a>
 ### `gstack setup: refusing to replace <root> for <host>: this runtime directory contains the source checkout setup runs from (<checkout>), so replacing it would delete the checkout. Nothing was changed.`
 
-**Meaning.** Setup installs Codex, Factory, OpenCode, Cursor, Copilot and
-Antigravity by building a runtime root (such as `~/.cursor/skills/gstack`) and
+**Meaning.** Setup installs Codex, Factory, OpenCode, Cursor, Copilot,
+Antigravity and Gemini CLI by building a runtime root (such as `~/.cursor/skills/gstack`) and
 swapping it in for the old one, and Kiro by writing into `~/.kiro/skills/gstack`.
 Your gstack checkout lives at that root or inside it, so the swap would delete
 the checkout (#3084), and Kiro would link the checkout into itself. Setup refuses before
@@ -2206,6 +2206,25 @@ anything.
 
 ---
 
+<a id="setup-deps-migrate-failed"></a>
+### `gstack: WARN kept the full dependency install (SETUP_DEPS_MIGRATE_FAILED; ...): <cause>`
+
+**Meaning.** Your install was made before v1.91.231.0, so it still carries the
+test and eval packages (about 520 MB, mostly the Claude Agent SDK). setup moved
+`node_modules` aside to install production dependencies only, that install
+failed, and setup put the full `node_modules` back. Nothing was removed, and
+gstack keeps working on the full install.
+
+**Fix.** Fix the cause the warning names (no network, a proxy, a full disk),
+then run `./setup` again. Developing gstack in this checkout? Mark it, and
+setup keeps the dev packages from then on:
+
+```bash
+git config gstack.contributor true
+```
+
+---
+
 <a id="chromium-install-exit-127"></a>
 ### `Chromium bootstrap: chromium-install — <bun> x playwright install chromium exited 127 (command not found); install Bun from bun.sh (winget Bun ships no bunx), or skip with ./setup --no-browser (Git Bash) or .\setup.ps1 --no-browser (PowerShell)`
 
diff --git a/docs/uninstall.md b/docs/uninstall.md
index a0309dd7a..8428c44d1 100644
--- a/docs/uninstall.md
+++ b/docs/uninstall.md
@@ -54,6 +54,7 @@ rm -rf "${HERMES_HOME:-$HOME/.hermes}/skills/gstack" 2>/dev/null
 rm -rf ~/.cursor/skills/gstack* 2>/dev/null
 rm -rf ~/.config/opencode/skills/gstack* 2>/dev/null
 rm -rf ~/.gemini/antigravity-cli/skills/gstack* 2>/dev/null
+rm -rf ~/.gemini/skills/gstack* 2>/dev/null
 
 # 6. Remove temp files
 rm -f /tmp/gstack-* 2>/dev/null
diff --git a/hosts/gemini.ts b/hosts/gemini.ts
new file mode 100644
index 000000000..a9f5417ae
--- /dev/null
+++ b/hosts/gemini.ts
@@ -0,0 +1,59 @@
+import { defineHost, GBRAIN_RESOLVERS, preambleToolGlossary } from './define-host';
+
+// Google Gemini CLI (#1247). Paths: user skills in ~/.gemini/skills, workspace
+// skills in .gemini/skills (trusted folders only), found at <dir>/<name>/SKILL.md
+// and indexed by frontmatter name (geminicli.com/docs/cli/skills). Tool names:
+// Gemini CLI 0.66.0. Google's migration table lists ~/.gemini/skills as an
+// Antigravity CLI global path too, so the glossary maps agy's names as well.
+// Verified facts in docs/ADDING_A_HOST.md "Gemini CLI".
+const GEMINI_TOOL_GLOSSARY = '**Gemini CLI tool names:** `AskUserQuestion` means your `ask_user` tool; there is no `mcp__*__AskUserQuestion` variant. The Bash tool means `run_shell_command`, the Read tool `read_file`, the Write tool `write_file`, the Edit tool `replace`, Grep `grep_search`, Glob `glob`, the Agent tool `invoke_agent`, and `ExitPlanMode` means `exit_plan_mode`. The Skill tool means `activate_skill`, or reading the skill\'s SKILL.md with `read_file`. In Antigravity CLI, which can read these skills too, use `run_command`, `view_file` and `ask_question` instead.';
+
+const gemini = defineHost({
+  name: 'gemini',
+  displayName: 'Gemini CLI',
+  cliAliases: ['gemini-cli'],
+  defaultModel: 'gemini',
+  tier: 'experimental',
+  capabilities: { toolExecution: true, questions: 'native', planMode: true, delegation: true, browser: true, safetyHooks: 'advisory' },
+
+  globalRoot: '.gemini/skills/gstack',
+  localSkillRoot: '.gemini/skills/gstack',
+  // Render output only: .gemini is Gemini CLI's own workspace directory, so a
+  // render there would be listed as workspace skills in this repo.
+  hostSubdir: '.gemini-cli',
+
+  // Gemini CLI indexes skills by frontmatter name, so names match their
+  // gstack-<skill> directories. 1024 is the Agent Skills description limit.
+  frontmatter: {
+    mode: 'allowlist',
+    keepFields: ['name', 'description'],
+    descriptionLimit: 1024,
+    descriptionLimitBehavior: 'error',
+    nameMatchesDirectory: true,
+  },
+
+  // Literal ~/.gemini/skills paths (the agy model); .source-path (written by
+  // setup) lets /gstack-upgrade find the checkout behind the runtime root.
+  pathRewrites: [
+    { from: 'if [ -d "$HOME/.claude/skills/gstack/.git" ]', to: 'if [ -d "$(cat "$HOME/.gemini/skills/gstack/.source-path" 2>/dev/null)/.git" ]' },
+    { from: 'INSTALL_DIR="$HOME/.claude/skills/gstack"', to: 'INSTALL_DIR="$(cat "$HOME/.gemini/skills/gstack/.source-path")"' },
+    { from: '$HOME/.claude/skills/gstack', to: '$HOME/.gemini/skills/gstack' },
+    { from: '~/.claude/skills/gstack', to: '~/.gemini/skills/gstack' },
+    { from: '.claude/skills/gstack', to: '.gemini/skills/gstack' },
+    { from: '.claude/skills/review', to: '.gemini/skills/gstack/review' },
+    { from: '.claude/skills', to: '.gemini/skills' },
+    { from: 'CLAUDE.md', to: 'GEMINI.md' },
+  ],
+  toolRewrites: preambleToolGlossary(GEMINI_TOOL_GLOSSARY),
+
+  suppressedResolvers: ['REVIEW_ARMY', ...GBRAIN_RESOLVERS],
+
+  runtimeRoot: {
+    globalSymlinks: ['bin', 'lib', 'browse/dist', 'browse/bin', 'design/dist', 'make-pdf/dist', 'freeze/bin', 'careful/bin', 'gstack-upgrade', 'ETHOS.md'],
+    globalFiles: {
+      'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'],
+    },
+  },
+});
+
+export default gemini;
diff --git a/hosts/index.ts b/hosts/index.ts
index 9477f76f3..f7064fecd 100644
--- a/hosts/index.ts
+++ b/hosts/index.ts
@@ -18,9 +18,10 @@ import hermes from './hermes';
 import gbrain from './gbrain';
 import copilot from './copilot';
 import agy from './agy';
+import gemini from './gemini';
 
 /** All registered host configs. Add new hosts here. */
-export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, copilot, agy];
+export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, copilot, agy, gemini];
 
 /** Map from host name to config. */
 export const HOST_CONFIG_MAP: Record<string, HostConfig> = Object.fromEntries(
@@ -44,7 +45,7 @@ export function getHostConfig(name: string): HostConfig {
 
 /**
  * Resolve a host name from a CLI argument, handling aliases.
- * e.g., 'agents' → 'codex', 'droid' → 'factory', 'antigravity' → 'agy'
+ * e.g., 'agents' → 'codex', 'droid' → 'factory', 'antigravity' → 'agy', 'gemini-cli' → 'gemini'
  */
 export function resolveHostArg(arg: string): string {
   // Direct name match
@@ -67,4 +68,4 @@ export function getExternalHosts(): HostConfig[] {
 }
 
 // Re-export individual configs for direct import
-export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, copilot, agy };
+export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, copilot, agy, gemini };
diff --git a/lib/result-codes.ts b/lib/result-codes.ts
index 599370c10..2dece5f82 100644
--- a/lib/result-codes.ts
+++ b/lib/result-codes.ts
@@ -166,6 +166,11 @@ export const RESULT_CODES = {
     summary: 'an argument given to .\\setup.ps1 is an empty string, which its Git Bash hand-off cannot carry, so nothing ran',
     fix: 'drop the empty argument or give it a value, then run .\\setup.ps1 again',
   },
+  SETUP_DEPS_MIGRATE_FAILED: {
+    anchor: 'setup-deps-migrate-failed',
+    summary: 'setup tried to move an install made before v1.91.231.0 to production-only dependencies, the production install failed, and setup put the full install back',
+    fix: 'read the cause on the warning line (offline, proxy, disk full), fix it, then re-run ./setup; the full install keeps working meanwhile',
+  },
   // C-stamp (plan C1, C2, C3, C5, C7): ship policy, restamp, tree receipt, ship receipt.
   POLICY_SOURCE_UNAVAILABLE: {
     anchor: 'policy-source-unavailable',
diff --git a/package.json b/package.json
index e4022f3c6..4ccb22127 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.92.21",
+  "version": "1.92.22",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/setup b/setup
index ce2a5cccc..2ae82558e 100755
--- a/setup
+++ b/setup
@@ -23,7 +23,7 @@ Usage: ./setup [options]
 Options:
   --host <name>     Install for one host. Default: claude. Hosts by tier:
                       full:             claude
-                      experimental:     codex, kiro, factory, opencode, cursor, copilot, agy, openclaw, hermes
+                      experimental:     codex, kiro, factory, opencode, cursor, copilot, agy, gemini, openclaw, hermes
                       instruction-only: slate, gbrain
                       auto:             every installed agent that setup detects
                     An explicit --host never changes another host's install.
@@ -212,7 +212,7 @@ _setup_unknown_option() {
 }
 while [ $# -gt 0 ]; do
   case "$1" in
-    --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, copilot, agy, slate, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; HOST_FLAG_SET=1; shift 2 ;;
+    --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, copilot, agy, gemini, slate, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; HOST_FLAG_SET=1; shift 2 ;;
     --host=*) HOST="${1#--host=}"; HOST_FLAG_SET=1; shift ;;
     --model) [ -z "$2" ] && echo "Missing value for --model" >&2 && exit 1; MODEL_OVERRIDE="$2"; MODEL_OVERRIDE_SET=1; shift 2 ;;
     --model=*) MODEL_OVERRIDE="${1#--model=}"; MODEL_OVERRIDE_SET=1; shift ;;
@@ -239,8 +239,9 @@ while [ $# -gt 0 ]; do
 done
 
 [ "$HOST" = "antigravity" ] && HOST="agy"  # Antigravity CLI is named after its binary
+[ "$HOST" = "gemini-cli" ] && HOST="gemini"
 case "$HOST" in
-  claude|codex|kiro|factory|opencode|cursor|copilot|agy|openclaw|hermes|auto) ;;
+  claude|codex|kiro|factory|opencode|cursor|copilot|agy|gemini|openclaw|hermes|auto) ;;
   slate)
     echo ""
     echo "Slate is not yet a first-class install target (docs/designs/SLATE_HOST.md —"
@@ -265,7 +266,7 @@ case "$HOST" in
     echo ""
     exit 0 ;;
   *)
-    echo "Unknown --host value: $HOST — nothing was installed or changed. Expected one of: claude (default), codex, kiro, factory, opencode, cursor, copilot, agy (alias antigravity), slate, openclaw, hermes, gbrain, or auto. Tiers: ./setup --help" >&2; exit 1 ;;
+    echo "Unknown --host value: $HOST — nothing was installed or changed. Expected one of: claude (default), codex, kiro, factory, opencode, cursor, copilot, agy (alias antigravity), gemini (alias gemini-cli), slate, openclaw, hermes, gbrain, or auto. Tiers: ./setup --help" >&2; exit 1 ;;
 esac
 
 # Bun versions come from one sourced file (floor and tested; E1).
@@ -550,6 +551,8 @@ COPILOT_SKILLS="$HOME/.copilot/skills"
 COPILOT_GSTACK="$COPILOT_SKILLS/gstack"
 AGY_SKILLS="$HOME/.gemini/antigravity-cli/skills"
 AGY_GSTACK="$AGY_SKILLS/gstack"
+GEMINI_SKILLS="$HOME/.gemini/skills"
+GEMINI_GSTACK="$GEMINI_SKILLS/gstack"
 
 SKILLS_BASENAME="$(basename "$INSTALL_SKILLS_DIR")"
 SKILLS_PARENT_BASENAME="$(basename "$(dirname "$INSTALL_SKILLS_DIR")")"
@@ -1362,8 +1365,9 @@ _remove_disabled_host_entry() {
 if [ "$LOCAL_INSTALL" -eq 1 ]; then
   echo "Warning: --local is deprecated. Use global install + --team instead." >&2
   echo "  See: https://github.com/garrytan/gstack#team-mode" >&2
-  if [ "$HOST" = "codex" ] || [ "$HOST" = "copilot" ]; then
+  if [ "$HOST" = "codex" ] || [ "$HOST" = "copilot" ] || [ "$HOST" = "gemini" ]; then
     echo "Error: --local is only supported for Claude Code (not $HOST)." >&2
+    [ "$HOST" = "gemini" ] && echo "  Gemini CLI loads workspace skills (.gemini/skills) only in trusted folders (/trust); ./setup --host gemini installs to ~/.gemini/skills." >&2
     exit 1
   fi
   INSTALL_SKILLS_DIR="$(pwd)/.claude/skills"
@@ -1381,6 +1385,7 @@ INSTALL_OPENCODE=0
 INSTALL_CURSOR=0
 INSTALL_COPILOT=0
 INSTALL_AGY=0
+INSTALL_GEMINI=0
 INSTALL_HARNESS=""
 if [ "$HOST" = "auto" ]; then
   command -v claude >/dev/null 2>&1 && INSTALL_CLAUDE=1
@@ -1398,8 +1403,10 @@ if [ "$HOST" = "auto" ]; then
   # Gemini CLI's and never selects Antigravity.
   command -v agy >/dev/null 2>&1 && INSTALL_AGY=1
   [ -d "$HOME/.gemini/antigravity-cli" ] && INSTALL_AGY=1
+  # ~/.gemini also holds Antigravity's config, so only the binary selects Gemini CLI.
+  command -v gemini >/dev/null 2>&1 && INSTALL_GEMINI=1
   # If none found, default to claude
-  if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_COPILOT" -eq 0 ] && [ "$INSTALL_AGY" -eq 0 ]; then
+  if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_COPILOT" -eq 0 ] && [ "$INSTALL_AGY" -eq 0 ] && [ "$INSTALL_GEMINI" -eq 0 ]; then
     INSTALL_CLAUDE=1
   fi
 elif [ "$HOST" = "claude" ]; then
@@ -1418,6 +1425,8 @@ elif [ "$HOST" = "copilot" ]; then
   INSTALL_COPILOT=1
 elif [ "$HOST" = "agy" ]; then
   INSTALL_AGY=1
+elif [ "$HOST" = "gemini" ]; then
+  INSTALL_GEMINI=1
 elif [ "$HOST" = "openclaw" ] || [ "$HOST" = "hermes" ]; then
   INSTALL_HARNESS="$HOST"
 fi
@@ -1425,8 +1434,8 @@ fi
 # A host that passes --host validation but sets no INSTALL_* flag would
 # silently configure nothing and exit 0 (the #2361 slate failure class).
 # Fail loudly if a future host lands in the accept-list without a dispatch arm.
-if [ "$HOST" != "auto" ] && [ -z "$INSTALL_HARNESS" ] && [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_COPILOT" -eq 0 ] && [ "$INSTALL_AGY" -eq 0 ]; then
-  echo "Error: no install arm exists for host '$HOST' — it passed --host validation but sets no INSTALL_* flag, so setup would configure nothing and exit 0. This is a setup bug. Valid install targets: claude, codex, kiro, factory, opencode, cursor, copilot, agy, openclaw, hermes (informational: slate, gbrain)." >&2
+if [ "$HOST" != "auto" ] && [ -z "$INSTALL_HARNESS" ] && [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_COPILOT" -eq 0 ] && [ "$INSTALL_AGY" -eq 0 ] && [ "$INSTALL_GEMINI" -eq 0 ]; then
+  echo "Error: no install arm exists for host '$HOST' — it passed --host validation but sets no INSTALL_* flag, so setup would configure nothing and exit 0. This is a setup bug. Valid install targets: claude, codex, kiro, factory, opencode, cursor, copilot, agy, gemini, openclaw, hermes (informational: slate, gbrain)." >&2
   exit 1
 fi
 
@@ -1450,7 +1459,8 @@ fi
 # contains, this checkout (#3084). _activate_runtime_root checks again; Kiro
 # writes into its root in place, so it is refused here too.
 for _rr in "$INSTALL_KIRO kiro $KIRO_SKILLS/gstack" "$INSTALL_FACTORY factory $FACTORY_GSTACK" "$INSTALL_OPENCODE opencode $OPENCODE_GSTACK" \
-  "$INSTALL_CURSOR cursor $CURSOR_GSTACK" "$INSTALL_COPILOT copilot $COPILOT_GSTACK" "$INSTALL_AGY agy $AGY_GSTACK"; do
+  "$INSTALL_CURSOR cursor $CURSOR_GSTACK" "$INSTALL_COPILOT copilot $COPILOT_GSTACK" "$INSTALL_AGY agy $AGY_GSTACK" \
+  "$INSTALL_GEMINI gemini $GEMINI_GSTACK"; do
   [ "${_rr%% *}" -eq 1 ] || continue
   _rr=${_rr#* }
   _runtime_root_refused "${_rr%% *}" "${_rr#* }" && exit 1
@@ -1682,18 +1692,112 @@ bun_cmd() {
   "$BUN_CMD" "$@"
 }
 
+# Who is a contributor is explicit (#3447): `git config gstack.contributor true`
+# in the checkout (bin/dev-setup writes it) or GSTACK_CONTRIBUTOR=1. A git error
+# (safe.directory, permissions) is "unknown", never "user", so it never prunes.
+# CI keeps whatever its own `bun install` put there.
+_deps_role() {
+  [ "${GSTACK_CONTRIBUTOR:-}" = "1" ] && { echo contributor; return; }
+  local value rc=0
+  value="$(git -C "$PWD" config --bool --get gstack.contributor 2>/dev/null)" || rc=$?
+  if [ "$rc" -eq 0 ]; then
+    [ "$value" = "true" ] && echo contributor || echo user
+    return
+  fi
+  [ "$rc" -ne 1 ] && { echo unknown; return; }
+  [ -n "${CI:-}" ] && { echo ci; return; }
+  echo user
+}
+
+_deps_has_dev() {
+  [ -d node_modules/typescript ] || [ -d node_modules/@anthropic-ai/claude-agent-sdk ]
+}
+
+# Every package.json "dependencies" entry resolves in node_modules.
+_deps_verified() {
+  [ -d node_modules ] || return 1
+  local name
+  for name in $(awk '/^  "dependencies": \{/{f=1;next} f&&/^  \}/{exit} f{gsub(/[",:]/," ");print $1}' package.json); do
+    [ -f "node_modules/$name/package.json" ] || return 1
+  done
+}
+
+# Checkout-local migration lock: a live holder means skip; a dead or missing
+# holder (killed setup) is reclaimed.
+_deps_lock() {
+  local lock="node_modules.gstack-migrate.lock" holder
+  if ! mkdir "$lock" 2>/dev/null; then
+    holder="$(cat "$lock/pid" 2>/dev/null || true)"
+    case "$holder" in
+      ''|*[!0-9]*|0) [ -z "$(find "$lock" -maxdepth 0 -mmin +5 2>/dev/null)" ] && [ -z "$holder" ] && return 1 ;;
+      *) kill -0 "$holder" 2>/dev/null && return 1 ;;
+    esac
+    rm -rf "$lock"
+    mkdir "$lock" 2>/dev/null || return 1
+  fi
+  echo "$$" > "$lock/pid"
+}
+
+_deps_unlock() { rm -rf node_modules.gstack-migrate.lock; }
+
+# A backup left by an interrupted migration: keep whichever copy is usable.
+_deps_recover() {
+  [ -d node_modules.gstack-migrate ] || return 0
+  if _deps_verified; then
+    rm -rf node_modules.gstack-migrate
+  else
+    rm -rf node_modules && mv node_modules.gstack-migrate node_modules
+  fi
+}
+
+# Installs made before v1.91.231.0 carry the dev toolchain. Locks, recovers, and
+# moves node_modules aside; succeeds only when it moved, so the caller installs
+# production-only and calls _deps_migration_finish.
+_deps_migration_start() {
+  [ -d node_modules.gstack-migrate ] || _deps_has_dev || return 1
+  _deps_lock || return 1
+  _deps_recover
+  if _deps_has_dev; then
+    _DEPS_BEFORE_KB="$(du -sk node_modules 2>/dev/null | cut -f1)"
+    mv node_modules node_modules.gstack-migrate && return 0
+  fi
+  _deps_unlock
+  return 1
+}
+
+_deps_migration_finish() {
+  local rc="$1" out="$2" after
+  if [ "$rc" -eq 0 ]; then
+    rm -rf node_modules.gstack-migrate
+    after="$(du -sk node_modules 2>/dev/null | cut -f1)"
+    _deps_unlock
+    echo "gstack: moved this install to production dependencies: node_modules $(( ${_DEPS_BEFORE_KB:-0} / 1024 )) MB -> $(( ${after:-0} / 1024 )) MB. Developing gstack in this checkout? Run: git config gstack.contributor true, then ./setup again."
+    return 0
+  fi
+  rm -rf node_modules
+  mv node_modules.gstack-migrate node_modules
+  _deps_unlock
+  echo "gstack: WARN kept the full dependency install (SETUP_DEPS_MIGRATE_FAILED; https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#setup-deps-migrate-failed): $(printf '%s\n' "$out" | tail -1 | cut -c1-200). Nothing was removed; the next ./setup tries again." >&2
+  return 1
+}
+
 # Users get production dependencies only. devDependencies are the test and eval
 # toolchain (the Claude Agent SDK's native binaries alone are ~440 MB on Linux), and
 # nothing setup, the build or an installed skill runs needs them. Bun never
-# prunes packages that are already installed, so a contributor's full
-# `bun install` (CONTRIBUTING.md, bin/dev-setup, CI) survives a later ./setup.
+# prunes packages that are already installed, so a user install that predates
+# v1.91.231.0 migrates once (_deps_migration_start), while a contributor (or a
+# checkout of unknown role, or CI) that has the dev toolchain gets the full
+# install, which keeps its dev packages at bun.lock's versions.
 # Bun's --production implies a frozen lockfile, so when bun.lock is out of date
 # (a fork or a local edit) refresh it first, then install production-only again.
-# A checkout that already has the dev toolchain (node_modules/typescript) is a
-# contributor's: a production install would leave its dev packages at old
-# versions after bun.lock moves, so it gets the full install instead.
 install_runtime_deps() {
-  if [ -d node_modules/typescript ]; then
+  local role out rc=0
+  role="$(_deps_role)"
+  if [ "$role" = "user" ] && _deps_migration_start; then
+    out="$( { bun_cmd install --production --frozen-lockfile || { bun_cmd install --lockfile-only && bun_cmd install --production --frozen-lockfile; }; } 2>&1 )" && _deps_verified || rc=$?
+    _deps_migration_finish "$rc" "$out" && return 0
+  fi
+  if [ "$role" = "contributor" ] || _deps_has_dev; then
     bun_cmd install --frozen-lockfile 2>/dev/null || bun_cmd install
     return
   fi
@@ -1849,6 +1953,7 @@ _RENDER_HOSTS_SELECTED=""
 [ "$INSTALL_CURSOR" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED cursor"
 [ "$INSTALL_COPILOT" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED copilot"
 [ "$INSTALL_AGY" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED agy"
+[ "$INSTALL_GEMINI" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED gemini"
 # shellcheck disable=SC2086 # the host list splits on purpose
 if ! gstack_render_hosts_add "$SOURCE_GSTACK_DIR" $_RENDER_HOSTS_SELECTED; then
   echo "  warning: could not write $(gstack_render_hosts_file "$SOURCE_GSTACK_DIR"); this build renders every host and nothing is pruned" >&2
@@ -2126,6 +2231,16 @@ if [ "$INSTALL_AGY" -eq 1 ] && { [ "$NEEDS_BUILD" -eq 0 ] || [ -n "$_PLAN_MODE_A
   )
 fi
 
+# 1h. Generate .gemini-cli/ Gemini CLI skill docs
+if [ "$INSTALL_GEMINI" -eq 1 ] && { [ "$NEEDS_BUILD" -eq 0 ] || [ -n "$_PLAN_MODE_ARG" ]; }; then
+  log "Generating .gemini-cli/ skill docs..."
+  (
+    cd "$SOURCE_GSTACK_DIR"
+    install_runtime_deps
+    bun_cmd run gen:skill-docs --host gemini ${_DISABLED_CSV:+"--disabled-skills=$_DISABLED_CSV"} ${_PLAN_MODE_ARG:+"$_PLAN_MODE_ARG"}
+  )
+fi
+
 # 2. Ensure Playwright's Chromium is available
 _PLAYWRIGHT_PLATFORM_OVERRIDE=""
 _PLAYWRIGHT_UNSUPPORTED_ARCH=""
@@ -3448,6 +3563,81 @@ link_agy_skill_dirs() {
   fi
 }
 
+# ─── Helper: ~/.gemini/skills/gstack runtime root ──────────────────────────
+# Same shape as the Antigravity root. ~/.gemini/skills is Gemini CLI's user
+# skills directory, shared with the user's own skills: setup writes only gstack
+# entries there. Built through _activate_runtime_root.
+create_gemini_runtime_root() {
+  local gstack_dir="$1"
+  local gemini_gstack="$2"
+  local gemini_dir="$gstack_dir/.gemini-cli/skills"
+  local asset f
+
+  mkdir -p "$gemini_gstack" "$gemini_gstack/browse" "$gemini_gstack/gstack-upgrade" "$gemini_gstack/review"
+  if [ -f "$gemini_dir/gstack/SKILL.md" ]; then
+    _copy_skill_md "$gemini_dir/gstack/SKILL.md" "$gemini_gstack/SKILL.md"
+  fi
+  for asset in bin lib browse/dist browse/bin; do
+    if [ -d "$gstack_dir/$asset" ]; then
+      _link_or_copy "$gstack_dir/$asset" "$gemini_gstack/$asset"
+    fi
+  done
+  _link_runtime_dists "$gstack_dir" "$gemini_gstack"
+  if [ -f "$gemini_dir/gstack-upgrade/SKILL.md" ]; then
+    _copy_skill_md "$gemini_dir/gstack-upgrade/SKILL.md" "$gemini_gstack/gstack-upgrade/SKILL.md"
+  fi
+  _copy_runtime_skill_refs "$gemini_dir" "$gemini_gstack"
+  if [ -f "$gstack_dir/ETHOS.md" ]; then
+    _link_or_copy "$gstack_dir/ETHOS.md" "$gemini_gstack/ETHOS.md"
+  fi
+  if [ -f "$gstack_dir/supabase/config.sh" ]; then
+    mkdir -p "$gemini_gstack/supabase"
+    _link_or_copy "$gstack_dir/supabase/config.sh" "$gemini_gstack/supabase/config.sh"
+  fi
+}
+
+# Frontmatter names already equal the gstack-<skill> directories
+# (nameMatchesDirectory), so no name patching. Fails when nothing was linked.
+link_gemini_skill_dirs() {
+  local gstack_dir="$1"
+  local skills_dir="$2"
+  local gemini_dir="$gstack_dir/.gemini-cli/skills"
+  local linked=()
+
+  if [ ! -d "$gemini_dir" ]; then
+    echo "  Generating .gemini-cli/ skill docs..."
+    ( cd "$gstack_dir" && bun_cmd run gen:skill-docs --host gemini ${_DISABLED_CSV:+"--disabled-skills=$_DISABLED_CSV"} ${_PLAN_MODE_ARG:+"$_PLAN_MODE_ARG"} )
+  fi
+  if [ ! -d "$gemini_dir" ]; then
+    echo "  warning: .gemini-cli/skills/ generation failed — run 'bun run gen:skill-docs --host gemini' manually" >&2
+    return 1
+  fi
+
+  for skill_dir in "$gemini_dir"/gstack*/; do
+    if [ -f "$skill_dir/SKILL.md" ]; then
+      skill_name="$(basename "$skill_dir")"
+      [ "$skill_name" = "gstack" ] && continue
+      case "${_DISABLED_SKILLS:- }" in *" ${skill_name#gstack-} "*) _remove_disabled_host_entry "$skills_dir/$skill_name"; continue ;; esac
+      target="$skills_dir/$skill_name"
+      if [ "$IS_WINDOWS" -eq 1 ] || [ -L "$target" ] || [ ! -e "$target" ]; then
+        if _owned_for_windows_refresh "$target"; then
+          _link_or_copy "$skill_dir" "$target"
+          linked+=("$skill_name")
+        else
+          echo "  left in place (existing dir not gstack-managed — no generated banner): $target" >&2
+        fi
+      fi
+    fi
+  done
+  if [ ${#linked[@]} -gt 0 ]; then
+    echo "  linked skills: ${linked[*]}"
+  fi
+  if ! ls "$skills_dir"/gstack-*/SKILL.md >/dev/null 2>&1; then
+    echo "  error: no gstack skills are installed in $skills_dir" >&2
+    return 1
+  fi
+}
+
 # 4. Install for Claude (default)
 # _claude_scope SKILLS_DIR — "global" for the user's Claude skills dir, else
 # "project <root>".
@@ -3868,6 +4058,25 @@ if [ "$INSTALL_AGY" -eq 1 ]; then
   fi
 fi
 
+# 6g. Install for Gemini CLI
+if [ "$INSTALL_GEMINI" -eq 1 ]; then
+  if _sidecar_root_user_owned "$GEMINI_GSTACK"; then
+    echo "  left in place (existing dir not gstack-managed — no generated banner): $GEMINI_GSTACK" >&2
+    _setup_row gemini global "$GEMINI_SKILLS" - "$SETUP_VERSION" skipped "left alone: $GEMINI_GSTACK is not gstack-managed (no generated banner)"
+  else
+    _setup_arm_begin gemini global "$GEMINI_SKILLS"
+    mkdir -p "$GEMINI_SKILLS"
+    _prune_stale_generated "$SOURCE_GSTACK_DIR" "$SOURCE_GSTACK_DIR/.gemini-cli/skills" "$GEMINI_SKILLS"
+    link_gemini_skill_dirs "$SOURCE_GSTACK_DIR" "$GEMINI_SKILLS"
+    _activate_runtime_root create_gemini_runtime_root "$SOURCE_GSTACK_DIR" "$GEMINI_GSTACK"
+    _setup_arm_publish gemini global - "$GEMINI_SKILLS" "$GEMINI_GSTACK" -
+    echo "gstack ready (gemini)."
+    echo "  browse: $BROWSE_BIN"
+    _browser_hint
+    echo "  gemini skills: $GEMINI_SKILLS (ask for gstack-<skill>; Gemini CLI activates it with activate_skill)"
+  fi
+fi
+
 # 7. Create .agents/ sidecar symlinks for the real Codex skill target.
 # The root Codex skill ends up pointing at $SOURCE_GSTACK_DIR/.agents/skills/gstack,
 # so the runtime assets must live there for both global and repo-local installs.
diff --git a/test/fixtures/skill-md-size-allowlist.json b/test/fixtures/skill-md-size-allowlist.json
index 5f6c8c08b..45435e0a9 100644
--- a/test/fixtures/skill-md-size-allowlist.json
+++ b/test/fixtures/skill-md-size-allowlist.json
@@ -29,6 +29,11 @@
     "factory/gstack-review": 125920,
     "gbrain/gstack-autoplan": 108748,
     "gbrain/gstack-plan-eng-review": 124972,
+    "gemini/gstack-autoplan": 108899,
+    "gemini/gstack-plan-design-review": 109210,
+    "gemini/gstack-plan-devex-review": 114248,
+    "gemini/gstack-plan-eng-review": 143588,
+    "gemini/gstack-review": 103679,
     "hermes/gstack-autoplan": 108751,
     "hermes/gstack-plan-eng-review": 125008,
     "kiro/gstack-autoplan": 108115,
diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts
index 7a52ba393..b6296dc27 100644
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -3693,7 +3693,7 @@ describe('setup script validation', () => {
     expect(setupContent).toContain('--host');
     // #2361: slate moved OUT of the install accept-list (it was accepted but
     // never dispatched — a silent exit-0 no-op) into an informational arm.
-    expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|copilot|agy|openclaw|hermes|auto');
+    expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|copilot|agy|gemini|openclaw|hermes|auto');
     expect(setupContent).toMatch(/^ {2}slate\)/m);
   });
 
diff --git a/test/host-config.test.ts b/test/host-config.test.ts
index a7155b8bb..e05ef8ed6 100644
--- a/test/host-config.test.ts
+++ b/test/host-config.test.ts
@@ -24,6 +24,7 @@ import {
   cursor,
   openclaw,
   agy,
+  gemini,
 } from '../hosts/index';
 import { HOST_PATHS } from '../scripts/resolvers/types';
 import { RESOLVERS } from '../scripts/resolvers';
@@ -37,8 +38,8 @@ const RESOLVER_NAMES = new Set(Object.keys(RESOLVERS));
 // ─── hosts/index.ts ─────────────────────────────────────────
 
 describe('hosts/index.ts', () => {
-  test('ALL_HOST_CONFIGS has 12 hosts', () => {
-    expect(ALL_HOST_CONFIGS.length).toBe(12);
+  test('ALL_HOST_CONFIGS has 13 hosts', () => {
+    expect(ALL_HOST_CONFIGS.length).toBe(13);
   });
 
   test('ALL_HOST_NAMES matches config names', () => {
@@ -61,6 +62,7 @@ describe('hosts/index.ts', () => {
     expect(cursor.name).toBe('cursor');
     expect(openclaw.name).toBe('openclaw');
     expect(agy.name).toBe('agy');
+    expect(gemini.name).toBe('gemini');
   });
 
   test('getHostConfig returns correct config', () => {
@@ -83,6 +85,7 @@ describe('hosts/index.ts', () => {
     expect(resolveHostArg('agents')).toBe('codex');
     expect(resolveHostArg('droid')).toBe('factory');
     expect(resolveHostArg('antigravity')).toBe('agy');
+    expect(resolveHostArg('gemini-cli')).toBe('gemini');
   });
 
   test('resolveHostArg throws on unknown alias', () => {
@@ -514,10 +517,11 @@ describe('golden-file regression', () => {
 // ─── Individual host config correctness ─────────────────────
 
 describe('host config correctness', () => {
-  test('Codex renders the GPT overlay, Antigravity the Gemini overlay, every other host the Claude overlay', () => {
+  test('Codex renders the GPT overlay, Antigravity and Gemini CLI the Gemini overlay, every other host the Claude overlay', () => {
     expect(codex.defaultModel).toBe('gpt');
     expect(agy.defaultModel).toBe('gemini');
-    for (const host of ALL_HOST_CONFIGS.filter(h => h.name !== 'codex' && h.name !== 'agy')) {
+    expect(gemini.defaultModel).toBe('gemini');
+    for (const host of ALL_HOST_CONFIGS.filter(h => !['codex', 'agy', 'gemini'].includes(h.name))) {
       expect(host.defaultModel).toBe('claude');
     }
   });
@@ -811,6 +815,50 @@ describe('Antigravity CLI host render', () => {
   });
 });
 
+describe('Gemini CLI host render', () => {
+  const OUT = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-gemini-'));
+  beforeAll(() => {
+    const r = Bun.spawnSync(['bun', 'run', 'scripts/gen-skill-docs.ts', '--host', 'gemini', '--out-dir', OUT], { cwd: ROOT, timeout: 120_000 });
+    if (r.exitCode !== 0) throw new Error(r.stderr.toString());
+  });
+  afterAll(() => fs.rmSync(OUT, { recursive: true, force: true }));
+  const dir = path.join(OUT, '.gemini-cli', 'skills');
+  const read = (skill: string) => fs.readFileSync(path.join(dir, skill, 'SKILL.md'), 'utf8');
+
+  test('paths name the Gemini CLI install, never Claude, Codex or Antigravity skill dirs', () => {
+    for (const skill of ['gstack-review', 'gstack-ship', 'gstack-careful', 'gstack-upgrade']) {
+      const md = readSkillStartup(path.join(dir, skill, 'SKILL.md'));
+      expect(md).not.toContain('~/.claude/skills/gstack');
+      expect(md).not.toContain('$HOME/.claude/skills/gstack');
+      expect(md).not.toContain('.codex/skills');
+      expect(md).not.toContain('antigravity-cli/skills');
+    }
+    expect(read('gstack-review')).toContain('_r=~/.gemini/skills/gstack');
+    expect(read('gstack-upgrade')).toContain('$HOME/.gemini/skills/gstack/.source-path');
+    expect(read('gstack-upgrade')).toContain('./setup --host gemini --refresh-registered');
+  });
+
+  test('the tool-name glossary names Gemini CLI 0.66.0 tools and Antigravity\'s, ahead of the preamble STATUS rules', () => {
+    const md = read('gstack-review');
+    const glossary = md.indexOf('**Gemini CLI tool names:**');
+    expect(glossary).toBeGreaterThan(-1);
+    expect(glossary).toBeLessThan(md.indexOf('Read the echoed `KEY: value` STATUS lines'));
+    const line = md.slice(glossary, md.indexOf('\n', glossary));
+    expectTokens(line, ['`ask_user`', '`run_shell_command`', '`read_file`', '`write_file`', '`replace`', '`grep_search`', '`glob`', '`invoke_agent`', '`exit_plan_mode`', '`activate_skill`']);
+    expectTokens(line, ['Antigravity', '`run_command`', '`view_file`', '`ask_question`']);
+  });
+
+  test('frontmatter keeps only name and description, and every name equals its directory', () => {
+    const names = fs.readdirSync(dir).filter(d => fs.existsSync(path.join(dir, d, 'SKILL.md')));
+    expect(names.length).toBeGreaterThan(20);
+    for (const name of names) {
+      const fm = read(name).split('\n---\n')[0];
+      expect(fm.match(/^name:\s*(\S+)/m)![1]).toBe(name);
+      expect(fm.split('\n').filter(l => /^[a-z-]+:/.test(l)).map(l => l.split(':')[0])).toEqual(['name', 'description']);
+    }
+  });
+});
+
 describe('host renders name the host\'s own tools and identities (#2626, #2015, #2825, #2338)', () => {
   const OUT = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-host-tools-'));
   beforeAll(() => {
diff --git a/test/host-conformance.test.ts b/test/host-conformance.test.ts
index ca136f179..56d6bb725 100644
--- a/test/host-conformance.test.ts
+++ b/test/host-conformance.test.ts
@@ -31,9 +31,10 @@ const DISCOVERY: Record<string, string> = {
   cursor: '.cursor/skills',
   copilot: '.copilot/skills',
   agy: '.gemini/antigravity-cli/skills',
+  gemini: '.gemini/skills',
 };
-/** Every directory any host (or a shared agents layout) reads; .gemini/skills is Gemini CLI's. */
-const ALL_DISCOVERY_DIRS = [...Object.values(DISCOVERY), '.agents/skills', '.copilot/skills', '.hermes/skills', '.gemini/skills'];
+/** Every directory any host (or a shared agents layout) reads. */
+const ALL_DISCOVERY_DIRS = [...Object.values(DISCOVERY), '.agents/skills', '.hermes/skills'];
 
 /** Harness hosts (install.registration 'harness') register through gstack-harness: test/harness-register.test.ts certifies them. */
 const installable = ALL_HOST_CONFIGS.filter(c => c.tier !== 'instruction-only' && c.install.registration !== 'harness').map(c => c.name);
diff --git a/test/host-renders-prune.test.ts b/test/host-renders-prune.test.ts
index 436e2c2d5..0cbe6995b 100644
--- a/test/host-renders-prune.test.ts
+++ b/test/host-renders-prune.test.ts
@@ -17,7 +17,7 @@ import { runGeneration } from '../scripts/gen-skill-docs';
 import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, put, runSetup, type Fixture } from './helpers/install-fixture';
 
 const ROOT = path.resolve(import.meta.dir, '..');
-const OTHER_DIRS = ['.agents', '.factory', '.kiro', '.opencode', '.cursor', '.copilot', '.agy', '.slate', '.openclaw', '.hermes', '.gbrain'];
+const OTHER_DIRS = ['.agents', '.factory', '.kiro', '.opencode', '.cursor', '.copilot', '.agy', '.gemini-cli', '.slate', '.openclaw', '.hermes', '.gbrain'];
 
 afterEach(cleanupFixtures);
 afterAll(cleanupSeed);
@@ -68,7 +68,7 @@ describe.skipIf(process.platform === 'win32')('setup prunes unrecorded host rend
     expect(fs.existsSync(path.join(f.dir, 'outside'))).toBe(true);
     expect(fs.existsSync(path.join(src, '.cursor/skills/gstack/bin'))).toBe(false);
     expect(fs.existsSync(path.join(src, 'bin/gstack-config'))).toBe(true);
-    for (const dir of ['.agents', '.opencode', '.copilot', '.agy', '.slate', '.openclaw', '.hermes', '.gbrain']) expect(fs.existsSync(path.join(src, dir)), dir).toBe(false);
+    for (const dir of ['.agents', '.opencode', '.copilot', '.agy', '.gemini-cli', '.slate', '.openclaw', '.hermes', '.gbrain']) expect(fs.existsSync(path.join(src, dir)), dir).toBe(false);
 
     expect(r.stdout).toContain('kept .factory/notes.md: not proven generated (no gstack banner or byte match)');
     expect(r.stdout).toContain('kept .kiro/skills/my-skill/SKILL.md: not proven generated');
diff --git a/test/plan-mode-preamble-render.test.ts b/test/plan-mode-preamble-render.test.ts
index 24bedde3f..60d10c400 100644
--- a/test/plan-mode-preamble-render.test.ts
+++ b/test/plan-mode-preamble-render.test.ts
@@ -49,7 +49,7 @@ describe('every installed-skill render carries the plan-mode arg', () => {
   test('setup: a build (which renders without the arg) does not skip the host re-renders when the key is off', () => {
     const setup = fs.readFileSync(path.join(ROOT, 'setup'), 'utf8');
     const guards = setup.split('\n').filter(line => /^if \[ "\$INSTALL_[A-Z]+" -eq 1 \] && .*NEEDS_BUILD/.test(line));
-    expect(guards.length).toBe(5);
+    expect(guards.length).toBe(6);
     for (const line of guards) expect(line, line).toContain('{ [ "$NEEDS_BUILD" -eq 0 ] || [ -n "$_PLAN_MODE_ARG" ]; }');
   });
 
diff --git a/test/runtime-root-assets.test.ts b/test/runtime-root-assets.test.ts
index 31d3bea91..d18eed0be 100644
--- a/test/runtime-root-assets.test.ts
+++ b/test/runtime-root-assets.test.ts
@@ -37,6 +37,7 @@ const ROOT_BUILDERS: Record<string, string> = {
   cursor: 'create_cursor_runtime_root',
   copilot: 'create_copilot_runtime_root',
   agy: 'create_agy_runtime_root',
+  gemini: 'create_gemini_runtime_root',
 };
 
 // Deferred, with the reason recorded in TODOS.md: /ship's measure loop runs
diff --git a/test/setup-install-registry.test.ts b/test/setup-install-registry.test.ts
index d4dada624..09d8bdfea 100644
--- a/test/setup-install-registry.test.ts
+++ b/test/setup-install-registry.test.ts
@@ -191,20 +191,25 @@ describe.skipIf(process.platform === 'win32')('Antigravity CLI shares ~/.gemini
     skill: readFileSync(join(home, '.gemini/skills/my-skill/SKILL.md'), 'utf8'),
   });
 
-  test.skipIf(Bun.which('agy') !== null)('auto-detect ignores a Gemini-CLI-only ~/.gemini and selects agy by its own config dir', () => {
+  // A machine with gemini or agy installed must not change what auto selects.
+  const pinnedPath = (f: { commands: string }) => ({
+    PATH: [f.commands, ...(process.env.PATH ?? '').split(':').filter(d => d && !['gemini', 'agy'].some(bin => existsSync(join(d, bin))))].join(':'),
+  });
+
+  test('auto-detect ignores a Gemini-CLI-only ~/.gemini and selects agy by its own config dir', () => {
     const f = makeFixture();
     const src = makeSource(f, join(f.home, 'gstack'));
     put(join(f.home, '.gemini/settings.json'), '{"theme":"mine"}\n');
     put(join(f.home, '.gemini/skills/my-skill/SKILL.md'), '---\nname: my-skill\ndescription: mine\n---\n');
     const before = geminiCliFiles(f.home);
 
-    const geminiOnly = runSetup(f, join(src, 'setup'), ['--host', 'auto']);
+    const geminiOnly = runSetup(f, join(src, 'setup'), ['--host', 'auto'], { env: pinnedPath(f) });
     expect(geminiOnly.status, geminiOnly.stdout + geminiOnly.stderr).toBe(0);
     expect(existsSync(join(f.home, '.gemini/antigravity-cli'))).toBe(false);
     expect(registryRows(f).map(row => row[0])).not.toContain('agy');
 
     mkdirSync(join(f.home, '.gemini/antigravity-cli'), { recursive: true });
-    const withAgy = runSetup(f, join(src, 'setup'), ['--host', 'auto']);
+    const withAgy = runSetup(f, join(src, 'setup'), ['--host', 'auto'], { env: pinnedPath(f) });
     expect(withAgy.status, withAgy.stdout + withAgy.stderr).toBe(0);
     expect(existsSync(join(f.home, '.gemini/antigravity-cli/skills/gstack-review/SKILL.md'))).toBe(true);
     expect(registryRows(f).map(row => row[0])).toContain('agy');
@@ -236,6 +241,88 @@ describe.skipIf(process.platform === 'win32')('Antigravity CLI shares ~/.gemini
     expect(geminiCliFiles(f.home)).toEqual(before);
     expect(registryRows(f)).toEqual([]);
   }, 120_000);
+
+  test('auto selects Gemini CLI only for gemini on PATH, never for a bare ~/.gemini', () => {
+    const f = makeFixture();
+    const src = makeSource(f, join(f.home, 'gstack'));
+    put(join(f.home, '.gemini/settings.json'), '{"theme":"mine"}\n');
+    put(join(f.home, '.gemini/skills/my-skill/SKILL.md'), '---\nname: my-skill\ndescription: mine\n---\n');
+    const before = geminiCliFiles(f.home);
+
+    const bare = runSetup(f, join(src, 'setup'), ['--host', 'auto'], { env: pinnedPath(f) });
+    expect(bare.status, bare.stdout + bare.stderr).toBe(0);
+    expect(registryRows(f).map(row => row[0])).not.toContain('gemini');
+    expect(readdirSync(join(f.home, '.gemini/skills'))).toEqual(['my-skill']);
+
+    put(join(f.commands, 'gemini'), '#!/bin/sh\nexit 0\n', 0o755);
+    const onPath = runSetup(f, join(src, 'setup'), ['--host', 'auto'], { env: pinnedPath(f) });
+    expect(onPath.status, onPath.stdout + onPath.stderr).toBe(0);
+    expect(registryRows(f).filter(row => row[0] === 'gemini').map(row => row[3])).toEqual([join(f.home, '.gemini/skills')]);
+    expect(existsSync(join(f.home, '.gemini/skills/gstack-review/SKILL.md'))).toBe(true);
+    expect(existsSync(join(f.home, '.gemini/antigravity-cli'))).toBe(false);
+    expect(geminiCliFiles(f.home)).toEqual(before);
+  }, 120_000);
+
+  test('--host gemini-cli (alias) writes only gstack entries in ~/.gemini/skills; uninstall removes only those', () => {
+    const f = makeFixture();
+    const src = makeSource(f, join(f.home, 'gstack'));
+    put(join(f.home, '.gemini/settings.json'), '{"theme":"mine"}\n');
+    put(join(f.home, '.gemini/skills/my-skill/SKILL.md'), '---\nname: my-skill\ndescription: mine\n---\n');
+    put(join(f.home, '.gemini/skills/gstack-notes/SKILL.md'), '---\nname: gstack-notes\ndescription: my notes\n---\n');
+    put(join(f.home, '.gemini/antigravity-cli/settings.json'), '{"agentMode":"plan"}\n');
+    const before = { ...geminiCliFiles(f.home), notes: readFileSync(join(f.home, '.gemini/skills/gstack-notes/SKILL.md'), 'utf8') };
+    const agyBefore = tree(join(f.home, '.gemini/antigravity-cli'));
+
+    const r = runSetup(f, join(src, 'setup'), ['--host', 'gemini-cli']);
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain('gstack ready (gemini)');
+    expect(registryRows(f).map(row => [row[0], row[3]])).toEqual([['gemini', join(f.home, '.gemini/skills')]]);
+    expect(readFileSync(join(f.home, '.gemini/skills/gstack/.source-path'), 'utf8').trim()).toBe(src);
+    expect(readFileSync(join(src, '.gstack-installed-hosts'), 'utf8').split('\n')).toContain('gemini');
+    expect(existsSync(join(src, '.gemini-cli/skills/gstack-review/SKILL.md'))).toBe(true);
+    const entries = readdirSync(join(f.home, '.gemini/skills'));
+    expect(entries.filter(n => !n.startsWith('gstack'))).toEqual(['my-skill']);
+    expect(entries).toContain('gstack-review');
+    expect({ ...geminiCliFiles(f.home), notes: readFileSync(join(f.home, '.gemini/skills/gstack-notes/SKILL.md'), 'utf8') }).toEqual(before);
+    expect(tree(join(f.home, '.gemini/antigravity-cli'))).toEqual(agyBefore);
+
+    const un = spawnSync('bash', [join(src, 'bin/gstack-uninstall'), '--force', '--keep-state'], { cwd: f.home, env: f.env, encoding: 'utf8', timeout: 30_000 });
+    expect(un.status, un.stderr).toBe(0);
+    expect(readdirSync(join(f.home, '.gemini/skills')).sort()).toEqual(['gstack-notes', 'my-skill']);
+    expect({ ...geminiCliFiles(f.home), notes: readFileSync(join(f.home, '.gemini/skills/gstack-notes/SKILL.md'), 'utf8') }).toEqual(before);
+    expect(tree(join(f.home, '.gemini/antigravity-cli'))).toEqual(agyBefore);
+    expect(registryRows(f)).toEqual([]);
+  }, 120_000);
+
+  test('--local --host gemini is refused with the trusted-folder note and writes no skills', () => {
+    const f = makeFixture();
+    const src = makeSource(f, join(f.home, 'gstack'));
+    const r = runSetup(f, join(src, 'setup'), ['--local', '--host', 'gemini']);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('Error: --local is only supported for Claude Code (not gemini).');
+    expect(r.stderr).toContain('Gemini CLI loads workspace skills (.gemini/skills) only in trusted folders (/trust)');
+    expect(existsSync(join(f.home, '.gemini'))).toBe(false);
+    expect(existsSync(join(f.home, '.claude/skills'))).toBe(false);
+    expect(r.stdout).not.toContain('gstack ready');
+  }, 60_000);
+
+  test('gemini and agy installed together: each arm writes only its own directory', () => {
+    const f = makeFixture();
+    const src = makeSource(f, join(f.home, 'gstack'));
+    expect(runSetup(f, join(src, 'setup'), ['--host', 'gemini']).status).toBe(0);
+    const geminiTree = tree(join(f.home, '.gemini/skills'));
+    const agy = runSetup(f, join(src, 'setup'), ['--host', 'agy']);
+    expect(agy.status, agy.stdout + agy.stderr).toBe(0);
+    expect(tree(join(f.home, '.gemini/skills'))).toEqual(geminiTree);
+    const agyTree = tree(join(f.home, '.gemini/antigravity-cli'));
+    const again = runSetup(f, join(src, 'setup'), ['--host', 'gemini']);
+    expect(again.status, again.stdout + again.stderr).toBe(0);
+    expect(tree(join(f.home, '.gemini/antigravity-cli'))).toEqual(agyTree);
+    expect(registryRows(f).map(row => [row[0], row[3]]).sort()).toEqual([
+      ['agy', join(f.home, '.gemini/antigravity-cli/skills')], ['gemini', join(f.home, '.gemini/skills')]]);
+    expect(readFileSync(join(f.home, '.gemini/skills/gstack-review/SKILL.md'), 'utf8')).toContain('**Gemini CLI tool names:**');
+    expect(readFileSync(join(f.home, '.gemini/antigravity-cli/skills/gstack-review/SKILL.md'), 'utf8')).toContain('**Antigravity tool names:**');
+  }, 180_000);
 });
 
 describe('install registry helper', () => {
diff --git a/test/setup-production-deps.test.ts b/test/setup-production-deps.test.ts
index 9664d568f..5289b4e13 100644
--- a/test/setup-production-deps.test.ts
+++ b/test/setup-production-deps.test.ts
@@ -40,6 +40,23 @@ function sliceFunction(source: string, name: string): string {
   return source.slice(start + 1, end + 3);
 }
 
+/** install_runtime_deps and the helpers it calls, sliced out of setup in definition order. */
+function depsFunctions(setup: string): string {
+  const names = ['bun_cmd', '_deps_role', '_deps_has_dev', '_deps_verified', '_deps_lock', '_deps_unlock', '_deps_recover',
+    '_deps_migration_start', '_deps_migration_finish', 'install_runtime_deps'];
+  return names.map((n) => (n === '_deps_unlock' ? setup.split('\n').find((l) => l.startsWith('_deps_unlock() {'))! + '\n' : sliceFunction(setup, n))).join('\n');
+}
+
+/** A git repository marked as a contributor's checkout (what bin/dev-setup writes). */
+function markContributor(dir: string): void {
+  gitInit(dir);
+  spawnSync('git', ['-C', dir, 'config', '--local', 'gstack.contributor', 'true'], { timeout: 10_000 });
+}
+
+function gitInit(dir: string): void {
+  spawnSync('git', ['init', '-q', dir], { timeout: 10_000 });
+}
+
 /**
  * A bun that records each argv line. Like Bun, a --frozen-lockfile install fails
  * ($FROZEN_RC) until `install --lockfile-only` has refreshed the lockfile; any other
@@ -56,7 +73,7 @@ function stubBun(base: string): { bun: string; calls: () => string[] } {
 describe.skipIf(process.platform === 'win32')('setup installs production dependencies only', () => {
   const setup = read('setup');
   const script = (bun: string, call: string) =>
-    `set -e\nBUN_CMD=${JSON.stringify(bun)}\n${sliceFunction(setup, 'bun_cmd')}\n${sliceFunction(setup, 'install_runtime_deps')}\n${call}\n`;
+    `set -e\nBUN_CMD=${JSON.stringify(bun)}\n${depsFunctions(setup)}\n${call}\n`;
 
   test('install_runtime_deps passes --production with the frozen lockfile, and refreshes a stale lockfile before installing production-only again', () => {
     const base = tempBase();
@@ -81,17 +98,20 @@ describe.skipIf(process.platform === 'win32')('setup installs production depende
     expect(stub3.calls()).toEqual(['install --production --frozen-lockfile', 'install --lockfile-only']);
   });
 
-  // Value: protects=a contributor checkout (dev toolchain present) keeps its dev packages at bun.lock's versions after ./setup;
+  // Value: protects=a contributor checkout (marked, dev toolchain present) keeps its dev packages at bun.lock's versions after ./setup;
   //   fails_when=setup runs the production install there, which Bun reports as "no changes" and leaves old dev versions;
   //   why_new=every other row starts without node_modules; seam=none; no_claim=Bun's own update behavior (stub bun)
-  test('a checkout with the dev toolchain gets the full frozen install, falling back to a plain install', () => {
+  // #3447: the contributor is the checkout marked with git config gstack.contributor, not any checkout that has typescript.
+  test('a marked contributor checkout gets the full frozen install, falling back to a plain install', () => {
     const base = tempBase();
+    markContributor(base);
     fs.mkdirSync(path.join(base, 'node_modules', 'typescript'), { recursive: true });
     const { bun, calls } = stubBun(base);
     expect(runBashScript(script(bun, 'install_runtime_deps'), { cwd: base, env: { ...process.env, FROZEN_RC: '0' } }).status).toBe(0);
     expect(calls()).toEqual(['install --frozen-lockfile']);
 
     const base2 = tempBase();
+    markContributor(base2);
     fs.mkdirSync(path.join(base2, 'node_modules', 'typescript'), { recursive: true });
     const stub2 = stubBun(base2);
     expect(runBashScript(script(stub2.bun, 'install_runtime_deps'), { cwd: base2, env: { ...process.env, FROZEN_RC: '1' } }).status).toBe(0);
@@ -103,6 +123,7 @@ describe.skipIf(process.platform === 'win32')('setup installs production depende
     //   why_new=both rows above succeed, and the failure row in the test above runs the production branch; seam=none;
     //   no_claim=setup's own subshell wiring around the call (stub bun)
     const base3 = tempBase();
+    markContributor(base3);
     fs.mkdirSync(path.join(base3, 'node_modules', 'typescript'), { recursive: true });
     const stub3 = stubBun(base3);
     const failed = runBashScript(script(stub3.bun, 'install_runtime_deps\necho AFTER'), { cwd: base3, env: { ...process.env, FROZEN_RC: '1', FALLBACK_RC: '4' } });
@@ -150,6 +171,25 @@ describe.skipIf(process.platform === 'win32')('setup installs production depende
     const r = runBashScript(`set -e\nREPO_ROOT=${JSON.stringify(base)}\nbun() { ${JSON.stringify(bun)} "$@"; }\n${block}`);
     expect(r.status).toBe(0);
     expect(calls()).toEqual(['install']);
+    // #3447: outside git the marker cannot be written; dev-setup says how to mark the run instead and still installs.
+    expect(r.stderr).toContain('GSTACK_CONTRIBUTOR=1');
+  });
+
+  // Value: protects=a contributor's clone keeps its dev toolchain on every later ./setup;
+  //   fails_when=bin/dev-setup stops writing the marker install_runtime_deps reads; why_new=#3447 adds the marker; seam=none; no_claim=none
+  test('bin/dev-setup marks the clone as a contributor checkout', () => {
+    const devSetup = read('bin/dev-setup');
+    const start = devSetup.indexOf('# 2. Install dependencies');
+    const block = devSetup.slice(start, devSetup.indexOf('# 3.', start));
+    const base = tempBase();
+    gitInit(base);
+    const { bun } = stubBun(base);
+    const r = runBashScript(`set -e\nREPO_ROOT=${JSON.stringify(base)}\nbun() { ${JSON.stringify(bun)} "$@"; }\n${block}`, { env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' } });
+    expect(r.status, r.stderr).toBe(0);
+    const marker = spawnSync('git', ['-C', base, 'config', '--bool', '--get', 'gstack.contributor'], { encoding: 'utf-8', timeout: 10_000 });
+    expect(marker.stdout.trim()).toBe('true');
+    const role = runBashScript(`${sliceFunction(read('setup'), '_deps_role')}\n_deps_role\n`, { cwd: base, env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' } });
+    expect(role.stdout.trim()).toBe('contributor');
   });
 });
 
@@ -174,7 +214,7 @@ describe.skipIf(process.platform === 'win32')('install_runtime_deps with the rea
     const env = { ...isolatedBunEnv(base), BUN_INSTALL_CACHE_DIR: path.join(base, 'cache') };
     const setup = read('setup');
     const run = (call: string) => runBashScript(
-      `set -e\nBUN_CMD=${JSON.stringify(process.execPath)}\n${sliceFunction(setup, 'bun_cmd')}\n${sliceFunction(setup, 'install_runtime_deps')}\n${call}\n`,
+      `set -e\nBUN_CMD=${JSON.stringify(process.execPath)}\n${depsFunctions(setup)}\n${call}\n`,
       { cwd: project, env, timeout: 90_000 });
     const has = (name: string) => fs.existsSync(path.join(project, 'node_modules', name, 'package.json'));
 
@@ -214,7 +254,7 @@ describe.skipIf(process.platform === 'win32')('install_runtime_deps with the rea
     const env = { ...isolatedBunEnv(base), BUN_INSTALL_CACHE_DIR: path.join(base, 'cache') };
     const setup = read('setup');
     const run = (call: string) => runBashScript(
-      `set -e\nBUN_CMD=${JSON.stringify(process.execPath)}\n${sliceFunction(setup, 'bun_cmd')}\n${sliceFunction(setup, 'install_runtime_deps')}\n${call}\n`,
+      `set -e\nBUN_CMD=${JSON.stringify(process.execPath)}\n${depsFunctions(setup)}\n${call}\n`,
       { cwd: project, env, timeout: 90_000 });
     const has = (name: string) => fs.existsSync(path.join(project, 'node_modules', name, 'package.json'));
 
@@ -229,6 +269,230 @@ describe.skipIf(process.platform === 'win32')('install_runtime_deps with the rea
   });
 });
 
+// #3447: installs made before v1.91.231.0 ran a full bun install, so they carry the dev
+// toolchain, and the old rule ("node_modules/typescript means contributor") kept them on it
+// forever. The contributor is now the checkout marked with git config gstack.contributor
+// (bin/dev-setup) or GSTACK_CONTRIBUTOR=1; every other checkout with dev packages migrates once.
+describe.skipIf(process.platform === 'win32')('install_runtime_deps moves older installs to production dependencies', () => {
+  const setup = read('setup');
+  const SDK = '@anthropic-ai/claude-agent-sdk';
+
+  /** A user checkout as an install made before v1.91.231.0 leaves it: a git clone with the full dev toolchain. */
+  function oldInstall(opts: { git?: boolean } = {}): string {
+    const base = tempBase();
+    if (opts.git !== false) gitInit(base);
+    fs.writeFileSync(path.join(base, 'package.json'), JSON.stringify({ name: 'fixture', dependencies: { 'runtime-pkg': '1.0.0' } }, null, 2) + '\n');
+    fs.writeFileSync(path.join(base, 'bun.lock'), `{\n  "packages": {\n    "${SDK}": ["${SDK}@0.2.141", "", {}],\n  }\n}\n`);
+    for (const dir of ['typescript', SDK, 'runtime-pkg']) {
+      fs.mkdirSync(path.join(base, 'node_modules', dir), { recursive: true });
+      fs.writeFileSync(path.join(base, 'node_modules', dir, 'package.json'), '{}');
+    }
+    return base;
+  }
+
+  /**
+   * A bun for the migration rows: records argv; a --production install recreates node_modules with
+   * runtime-pkg unless PROD_RC is nonzero (or PROD_SKIP_DEPS=1 leaves it out); `pm cache` prints
+   * $CACHE_DIR; any other install exits 0.
+   */
+  function migrateBun(base: string): { bun: string; calls: () => string[] } {
+    const log = path.join(base, '.calls');
+    const bun = path.join(base, '.bun-stub');
+    fs.writeFileSync(bun, `#!/usr/bin/env bash
+echo "$*" >> ${JSON.stringify(log)}
+case "$*" in
+  "pm cache") echo "\${CACHE_DIR:-}"; exit 0 ;;
+  *--production*)
+    [ "\${PROD_RC:-0}" -ne 0 ] && { echo "error: network down" >&2; exit "\${PROD_RC}"; }
+    mkdir -p node_modules
+    [ "\${PROD_SKIP_DEPS:-0}" = 1 ] || { mkdir -p node_modules/runtime-pkg && echo '{}' > node_modules/runtime-pkg/package.json; }
+    exit 0 ;;
+esac
+exit 0
+`, { mode: 0o755 });
+    return { bun, calls: () => (fs.existsSync(log) ? fs.readFileSync(log, 'utf-8').trim().split('\n').filter((l) => l !== 'pm cache') : []) };
+  }
+
+  const run = (base: string, bun: string, env: Record<string, string> = {}) => {
+    const clean = Object.fromEntries(Object.entries(process.env).filter(([k]) => k !== 'CI' && k !== 'GSTACK_CONTRIBUTOR'));
+    return runBashScript(`set -e\nBUN_CMD=${JSON.stringify(bun)}\n${depsFunctions(setup)}\ninstall_runtime_deps\n`,
+      { cwd: base, env: { ...clean, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', ...env } });
+  };
+  const has = (base: string, dir: string) => fs.existsSync(path.join(base, 'node_modules', dir));
+  const leftovers = (base: string) => ['node_modules.gstack-migrate', 'node_modules.gstack-migrate.lock'].filter((p) => fs.existsSync(path.join(base, p)));
+
+  // Value: protects=an install made before v1.91.231.0 drops its ~520 MB of dev packages on the next ./setup;
+  //   fails_when=setup keeps treating node_modules/typescript as a contributor marker (the pre-#3447 rule);
+  //   why_new=no row ran an unmarked checkout that already has the dev toolchain; seam=none; no_claim=real Bun (stub bun)
+  test('an unmarked checkout with the dev toolchain migrates to the production install once', () => {
+    const base = oldInstall();
+    const { bun, calls } = migrateBun(base);
+    const r = run(base, bun);
+    expect(r.status, r.stderr).toBe(0);
+    expect(calls()).toEqual(['install --production --frozen-lockfile']);
+    expect([has(base, 'typescript'), has(base, SDK), has(base, 'runtime-pkg')]).toEqual([false, false, true]);
+    expect(leftovers(base)).toEqual([]);
+    expect(r.stdout).toContain('gstack: moved this install to production dependencies');
+    expect(r.stdout).toContain('git config gstack.contributor true, then ./setup again');
+
+    const again = run(base, bun);
+    expect(again.status, again.stderr).toBe(0);
+    expect(again.stdout).not.toContain('moved this install');
+    expect(calls()).toEqual(['install --production --frozen-lockfile', 'install --production --frozen-lockfile']);
+  });
+
+  test('a contributor, a CI run and a checkout whose role git cannot read keep the dev toolchain', () => {
+    const marked = oldInstall();
+    spawnSync('git', ['-C', marked, 'config', '--local', 'gstack.contributor', 'true'], { timeout: 10_000 });
+    const envOnly = oldInstall();
+    const ci = oldInstall();
+    const unreadable = oldInstall();
+    const fakeGit = path.join(unreadable, '.fake-bin');
+    fs.mkdirSync(fakeGit);
+    fs.writeFileSync(path.join(fakeGit, 'git'), '#!/usr/bin/env bash\necho "fatal: detected dubious ownership" >&2\nexit 128\n', { mode: 0o755 });
+    for (const [base, env] of [[marked, {}], [envOnly, { GSTACK_CONTRIBUTOR: '1' }], [ci, { CI: 'true' }], [unreadable, { PATH: `${fakeGit}:${process.env.PATH}` }]] as const) {
+      const { bun, calls } = migrateBun(base);
+      const r = run(base, bun, env);
+      expect(r.status, r.stderr).toBe(0);
+      expect(calls()).toEqual(['install --frozen-lockfile']);
+      expect([has(base, 'typescript'), has(base, SDK)]).toEqual([true, true]);
+      expect(leftovers(base)).toEqual([]);
+    }
+    const marker = spawnSync('git', ['-C', marked, 'config', '--bool', 'gstack.contributor', 'false'], { timeout: 10_000 });
+    expect(marker.status).toBe(0);
+    const { bun } = migrateBun(marked);
+    expect(run(marked, bun).status).toBe(0);
+    expect(has(marked, 'typescript')).toBe(false);
+  });
+
+  test('a fresh CI checkout still gets the production install', () => {
+    const base = tempBase();
+    gitInit(base);
+    fs.writeFileSync(path.join(base, 'package.json'), JSON.stringify({ name: 'fixture', dependencies: { 'runtime-pkg': '1.0.0' } }, null, 2) + '\n');
+    const { bun, calls } = migrateBun(base);
+    expect(run(base, bun, { CI: 'true' }).status).toBe(0);
+    expect(calls()).toEqual(['install --production --frozen-lockfile']);
+  });
+
+  // Value: protects=an offline upgrade never leaves a user without node_modules;
+  //   fails_when=the migration deletes the old node_modules before the production install is proven, or swallows the failure;
+  //   why_new=the success row cannot fail the install; seam=none; no_claim=real network failures (stub bun)
+  test('a failed or unverified production install puts the full install back and says why', () => {
+    for (const env of [{ PROD_RC: '7' }, { PROD_SKIP_DEPS: '1' }] as Record<string, string>[]) {
+      const base = oldInstall();
+      const { bun, calls } = migrateBun(base);
+      const r = run(base, bun, env);
+      expect(r.status, r.stderr).toBe(0);
+      expect([has(base, 'typescript'), has(base, SDK), has(base, 'runtime-pkg')]).toEqual([true, true, true]);
+      expect(leftovers(base)).toEqual([]);
+      expect(r.stderr).toContain('SETUP_DEPS_MIGRATE_FAILED');
+      expect(r.stderr).toContain('Nothing was removed');
+      expect(calls().at(-1)).toBe('install --frozen-lockfile');
+    }
+    const offline = oldInstall();
+    expect(run(offline, migrateBun(offline).bun, { PROD_RC: '7' }).stderr).toContain('error: network down');
+  });
+
+  test('a backup left by an interrupted migration is recovered on the next run', () => {
+    const moved = oldInstall();
+    fs.renameSync(path.join(moved, 'node_modules'), path.join(moved, 'node_modules.gstack-migrate'));
+    const stub = migrateBun(moved);
+    expect(run(moved, stub.bun).status).toBe(0);
+    expect([has(moved, 'typescript'), has(moved, 'runtime-pkg')]).toEqual([false, true]);
+    expect(leftovers(moved)).toEqual([]);
+
+    const finished = oldInstall();
+    fs.renameSync(path.join(finished, 'node_modules'), path.join(finished, 'node_modules.gstack-migrate'));
+    fs.mkdirSync(path.join(finished, 'node_modules', 'runtime-pkg'), { recursive: true });
+    fs.writeFileSync(path.join(finished, 'node_modules', 'runtime-pkg', 'package.json'), '{}');
+    expect(run(finished, migrateBun(finished).bun).status).toBe(0);
+    expect(has(finished, 'typescript')).toBe(false);
+    expect(leftovers(finished)).toEqual([]);
+  });
+
+  test('a live migration lock skips the migration; a dead holder is reclaimed', () => {
+    const busy = oldInstall();
+    fs.mkdirSync(path.join(busy, 'node_modules.gstack-migrate.lock'));
+    fs.writeFileSync(path.join(busy, 'node_modules.gstack-migrate.lock', 'pid'), String(process.pid));
+    const b = migrateBun(busy);
+    expect(run(busy, b.bun).status).toBe(0);
+    expect(b.calls()).toEqual(['install --frozen-lockfile']);
+    expect(has(busy, 'typescript')).toBe(true);
+
+    const stale = oldInstall();
+    fs.mkdirSync(path.join(stale, 'node_modules.gstack-migrate.lock'));
+    fs.writeFileSync(path.join(stale, 'node_modules.gstack-migrate.lock', 'pid'), '2147483646');
+    expect(run(stale, migrateBun(stale).bun).status).toBe(0);
+    expect(has(stale, 'typescript')).toBe(false);
+    expect(leftovers(stale)).toEqual([]);
+  });
+
+  // Value: protects=another project's install that reads the Agent SDK out of Bun's shared cache (Bun's symlink
+  //   backend links each file there with no extra hardlink) keeps working after a gstack migration;
+  //   fails_when=the migration deletes Bun cache entries; why_new=a review reproduced a symlink-backend consumer
+  //   losing its package.json when cache entries with no extra hardlinks were deleted; seam=none; no_claim=Bun's cache layout
+  test('the migration never touches Bun\'s shared cache', () => {
+    const base = oldInstall();
+    const cache = path.join(base, '.cache');
+    const entry = path.join(cache, '@anthropic-ai', 'claude-agent-sdk-linux-x64@0.2.141@@@1');
+    fs.mkdirSync(entry, { recursive: true });
+    fs.writeFileSync(path.join(entry, 'cli.js'), 'x');
+    const consumer = path.join(base, '.symlink-project', 'node_modules', 'sdk');
+    fs.mkdirSync(consumer, { recursive: true });
+    fs.symlinkSync(path.join(entry, 'cli.js'), path.join(consumer, 'cli.js'));
+    const { bun, calls } = migrateBun(base);
+    const r = run(base, bun, { CACHE_DIR: cache });
+    expect(r.status, r.stderr).toBe(0);
+    expect(has(base, 'typescript')).toBe(false);
+    expect(calls()).toEqual(['install --production --frozen-lockfile']);
+    expect(fs.readFileSync(path.join(consumer, 'cli.js'), 'utf-8')).toBe('x');
+  });
+
+  test('a checkout outside git with the dev toolchain is a user install', () => {
+    const base = oldInstall({ git: false });
+    expect(run(base, migrateBun(base).bun).status).toBe(0);
+    expect(has(base, 'typescript')).toBe(false);
+  });
+});
+
+// Value: protects=with the real Bun, an older full install loses its dev packages and a marked contributor keeps them;
+//   fails_when=the production install after the move resolves differently from a fresh one, or the marker read breaks;
+//   why_new=the migration rows stub bun; seam=none; no_claim=registry packages (local file: packages; offline)
+describe.skipIf(process.platform === 'win32')('the migration with the real Bun', () => {
+  test('an unmarked full install loses its dev packages; a marked one keeps them across two runs', () => {
+    for (const marked of [false, true]) {
+      const base = tempBase();
+      const project = path.join(base, 'project');
+      for (const name of ['runtime-pkg', 'typescript']) {
+        fs.mkdirSync(path.join(project, 'pkgs', name), { recursive: true });
+        fs.writeFileSync(path.join(project, 'pkgs', name, 'package.json'), JSON.stringify({ name, version: '1.0.0' }));
+      }
+      fs.writeFileSync(path.join(project, 'package.json'), JSON.stringify({
+        name: 'migrate-fixture', version: '0.0.0',
+        dependencies: { 'runtime-pkg': 'file:./pkgs/runtime-pkg' },
+        devDependencies: { typescript: 'file:./pkgs/typescript' },
+      }, null, 2) + '\n');
+      gitInit(project);
+      if (marked) spawnSync('git', ['-C', project, 'config', '--local', 'gstack.contributor', 'true'], { timeout: 10_000 });
+      const env = { ...isolatedBunEnv(base), BUN_INSTALL_CACHE_DIR: path.join(base, 'cache'), GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' };
+      delete (env as Record<string, string | undefined>).CI;
+      delete (env as Record<string, string | undefined>).GSTACK_CONTRIBUTOR;
+      const setup = read('setup');
+      const runIt = (call: string) => runBashScript(`set -e\nBUN_CMD=${JSON.stringify(process.execPath)}\n${depsFunctions(setup)}\n${call}\n`, { cwd: project, env, timeout: 90_000 });
+      const has = (name: string) => fs.existsSync(path.join(project, 'node_modules', name, 'package.json'));
+      const full = runIt('bun_cmd install');
+      expect(full.status, full.stderr).toBe(0);
+      expect(has('typescript')).toBe(true);
+      for (let i = 0; i < 2; i++) {
+        const r = runIt('install_runtime_deps');
+        expect(r.status, r.stderr).toBe(0);
+        expect([has('runtime-pkg'), has('typescript')]).toEqual([true, marked]);
+      }
+      expect(fs.existsSync(path.join(project, 'node_modules.gstack-migrate'))).toBe(false);
+    }
+  });
+});
+
 /** Bare package names a source file loads (import/require/dynamic import), type-only imports excluded. */
 function importedPackages(text: string): string[] {
   const out = new Set<string>();
@@ -339,14 +603,14 @@ describe('setup and runtime need only production dependencies', () => {
   });
 
   // Generated by /ship Step 7 coverage audit (GSTA-97).
-  // Value: protects=a production-only install never creates the dev-toolchain marker install_runtime_deps reads, so a user's next ./setup stays production-only;
+  // Value: protects=a production-only install never creates a dev-toolchain package _deps_has_dev reads, so a user's next ./setup stays production-only;
   //   fails_when=a production dependency, or a package it pulls in (required peers included), starts depending on the marker package, so every repeat ./setup goes full;
   //   why_new=the real-Bun rows use local fixture packages, and nothing walks the repo's own bun.lock production closure;
   //   seam=none; no_claim=Bun's actual hoisting or platform filtering (a static, name-based walk of bun.lock that counts every candidate entry)
-  test('the production closure in bun.lock never installs the dev-toolchain marker setup checks', () => {
-    const marker = sliceFunction(read('setup'), 'install_runtime_deps').match(/\[ -d node_modules\/([^\s\]]+) \]/)?.[1];
-    expect(marker).toBeDefined();
-    expect(PKG.devDependencies).toHaveProperty([marker!]);
+  test('the production closure in bun.lock never installs the dev-toolchain packages setup checks', () => {
+    const markers = [...sliceFunction(read('setup'), '_deps_has_dev').matchAll(/\[ -d node_modules\/([^\s\]]+) \]/g)].map((m) => m[1]);
+    expect(markers).toEqual(['typescript', '@anthropic-ai/claude-agent-sdk']);
+    for (const marker of markers) expect(PKG.devDependencies).toHaveProperty([marker]);
     type Lock = { workspaces: Record<string, { dependencies?: Record<string, string> }>; packages: Record<string, unknown[]> };
     const closure = (lock: Lock): Set<string> => {
       const seen = new Set<string>();
@@ -369,14 +633,16 @@ describe('setup and runtime need only production dependencies', () => {
     const lock: Lock = JSON.parse(read('bun.lock').replace(/,(\s*[}\]])/g, '$1'));
     const production = closure(lock);
     expect(production.has('playwright-core')).toBe(true);
-    expect(production.has(marker!)).toBe(false);
-    // Negative controls: a required peer on the marker is caught, through a nested entry too; an optional peer is not.
+    for (const marker of markers) expect(production.has(marker), marker).toBe(false);
+    // Negative controls: a required peer on a marker is caught, through a nested entry too; an optional peer is not.
     const synthetic = (meta: Record<string, unknown>): Lock => ({
       workspaces: { '': { dependencies: { a: '1' } } },
       packages: { a: ['a@1', '', { dependencies: { b: '1' } }, 'sha'], b: ['b@1', '', {}, 'sha'], 'a/b': ['b@2', '', meta, 'sha'] },
     });
-    expect(closure(synthetic({ peerDependencies: { [marker!]: '*' } })).has(marker!)).toBe(true);
-    expect(closure(synthetic({ peerDependencies: { [marker!]: '*' }, optionalPeers: [marker!] })).has(marker!)).toBe(false);
+    for (const marker of markers) {
+      expect(closure(synthetic({ peerDependencies: { [marker]: '*' } })).has(marker)).toBe(true);
+      expect(closure(synthetic({ peerDependencies: { [marker]: '*' }, optionalPeers: [marker] })).has(marker)).toBe(false);
+    }
   });
 
   test('the dev toolchain stays out of the user install', () => {
diff --git a/test/setup-runtime-root-guard.test.ts b/test/setup-runtime-root-guard.test.ts
index 600d64a4e..a291b0afc 100644
--- a/test/setup-runtime-root-guard.test.ts
+++ b/test/setup-runtime-root-guard.test.ts
@@ -55,7 +55,7 @@ describe.skipIf(process.platform === 'win32')('setup never replaces a runtime ro
 
   test('a checkout nested inside a host runtime root is refused for every arm that writes a root', () => {
     for (const [host, root] of [['kiro', '.kiro/skills/gstack'], ['factory', '.factory/skills/gstack'], ['opencode', '.config/opencode/skills/gstack'],
-      ['copilot', '.copilot/skills/gstack'], ['agy', '.gemini/antigravity-cli/skills/gstack']] as const) {
+      ['copilot', '.copilot/skills/gstack'], ['agy', '.gemini/antigravity-cli/skills/gstack'], ['gemini', '.gemini/skills/gstack']] as const) {
       const f = makeFixture();
       const src = makeSource(f, join(f.home, root, 'checkout'));
       const before = tree(join(f.home, root));
@@ -72,7 +72,7 @@ describe.skipIf(process.platform === 'win32')('setup never replaces a runtime ro
     const fn = setup.slice(setup.indexOf('_activate_runtime_root() {'));
     expect(fn.slice(0, fn.indexOf('\n}\n'))).toMatch(/_runtime_root_refused "\$\{_SETUP_ARM%%\t\*\}" "\$root" && return 1/);
     const arms = [...setup.matchAll(/_activate_runtime_root create_(\w+)_runtime_root/g)].map(m => m[1]);
-    expect([...new Set(arms)].sort()).toEqual(['agy', 'codex', 'copilot', 'cursor', 'factory', 'opencode']);
+    expect([...new Set(arms)].sort()).toEqual(['agy', 'codex', 'copilot', 'cursor', 'factory', 'gemini', 'opencode']);
   });
 
   test('control: the canonical ~/.claude/skills/gstack install and a repeat ./setup succeed', () => {
diff --git a/test/uninstall.test.ts b/test/uninstall.test.ts
index 83d5e3926..2afaa641b 100644
--- a/test/uninstall.test.ts
+++ b/test/uninstall.test.ts
@@ -204,6 +204,46 @@ describe('gstack-uninstall', () => {
       expect(fs.existsSync(path.join(mockGitRoot, '.cursor', 'rules', 'keep.md'))).toBe(true);
     });
 
+    // Value: protects=uninstall clears gstack's Gemini CLI skills from ~/.gemini/skills, a folder the user's own skills share;
+    //   fails_when=the Gemini block is dropped, or loses the provenance gate and sweeps a user's gstack-prefixed skill;
+    //   why_new=#1247 adds the Gemini CLI host; seam=none; no_claim=Gemini CLI itself (temp HOME fixture)
+    test('--force removes Gemini CLI gstack skills and leaves the user\'s own', () => {
+      const banner = '<!-- AUTO-GENERATED from SKILL.md.tmpl - DO NOT EDIT DIRECTLY -->\n# x\n';
+      const skills = path.join(mockHome, '.gemini', 'skills');
+      const render = path.join(tmpDir, 'render', 'gstack-review');
+      fs.mkdirSync(render, { recursive: true });
+      fs.writeFileSync(path.join(render, 'SKILL.md'), banner);
+      fs.mkdirSync(path.join(skills, 'gstack'), { recursive: true });
+      fs.writeFileSync(path.join(skills, 'gstack', 'SKILL.md'), banner);
+      fs.symlinkSync(render, path.join(skills, 'gstack-review'));
+      for (const [name, body] of [['gstack-my-notes', '# mine\n'], ['frontend-design', 'keep']]) {
+        fs.mkdirSync(path.join(skills, name), { recursive: true });
+        fs.writeFileSync(path.join(skills, name, 'SKILL.md'), body);
+      }
+      fs.writeFileSync(path.join(mockHome, '.gemini', 'settings.json'), '{}');
+
+      const result = spawnSync('bash', [UNINSTALL, '--force'], {
+        stdio: 'pipe',
+        timeout: 30_000,
+        env: {
+          ...process.env,
+          HOME: mockHome,
+          GSTACK_DIR: path.join(mockHome, '.claude', 'skills', 'gstack'),
+          GSTACK_STATE_DIR: path.join(mockHome, '.gstack'),
+        },
+        cwd: mockGitRoot,
+      });
+
+      expect(result.status).toBe(0);
+      expect(fs.existsSync(path.join(skills, 'gstack'))).toBe(false);
+      expect(fs.existsSync(path.join(skills, 'gstack-review'))).toBe(false);
+      expect(fs.existsSync(path.join(render, 'SKILL.md'))).toBe(true);
+      expect(fs.existsSync(path.join(skills, 'gstack-my-notes', 'SKILL.md'))).toBe(true);
+      expect(fs.existsSync(path.join(skills, 'frontend-design', 'SKILL.md'))).toBe(true);
+      expect(fs.existsSync(path.join(mockHome, '.gemini', 'settings.json'))).toBe(true);
+      expect(result.stderr.toString()).toContain('gstack-my-notes');
+    });
+
     test("a user's own gstack-prefixed Cursor dir (no banner) survives and is listed", () => {
       // S5: the bare gstack* glob must not sweep a dir that merely starts
       // with "gstack" — provenance comes from the generated banner, and a

From b15492a148e2744d24b0ca4da5ba290fb109c340 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 01:52:31 -0800
Subject: [PATCH 3/5] v1.92.23.0 feat(harness): opt-in start hook for OpenClaw
 and Hermes, so agents run a skill's start command (GST-718) (#3786)

* feat(harness): opt-in start hook for OpenClaw and Hermes (GST-718)

gstack-harness register openclaw|hermes --start-hook (or GSTACK_HARNESS_START_HOOK,
or gstack-config harness_start_hook) adds a gstack-start plugin that puts a
one-line note on every user turn to run a gstack skill's start command as
written. Activation goes through each harness's own CLI and is read back;
a run that turns it on and ends inactive exits 4. Off by default.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): retry an inactive start hook without failing refresh, and never re-enable a user disable (GST-718)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): an env or config start-hook opt-in with an unsafe plugin folder turns the hook off instead of failing refresh (GST-718)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): normalize the hook profile, retry an interrupted activation, re-enable after kept edits

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): a non-folder or empty plugin path is never taken as kept edits

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): teardown keeps kept copies and refuses symlinked plugin paths; a failed opt-out can rerun; a saved hook survives OPENCLAW_CONFIG_PATH

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): any saved plugin root is checked for symlinks before an opt-out deletes through it

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(harness): tolerant JSON read-back, short read-back timeout, retry an interrupted explicit activation, symlink checks on every hook opt-out and folder cleanup

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(harness): start hook unchecked state and uninstall notes

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 CHANGELOG.md                           |   4 +
 VERSION                                |   2 +-
 agents-digest/gstack-AGENTS.md         |   2 +-
 bin/gstack-config                      |  17 +-
 bin/gstack-harness                     |  32 +-
 bin/gstack-harness-ledger.sh           |  61 ++-
 docs/OPENCLAW.md                       |   5 +
 docs/hosts.md                          |  26 ++
 docs/troubleshooting.md                |  20 +
 docs/uninstall.md                      |   9 +-
 lib/harness-register.ts                |  98 ++++-
 lib/harness-start-hook.ts              | 183 +++++++++
 package.json                           |   2 +-
 setup                                  |  13 +-
 test/fixtures/module-size-ratchet.json |   1 +
 test/harness-start-hook.test.ts        | 514 +++++++++++++++++++++++++
 16 files changed, 955 insertions(+), 34 deletions(-)
 create mode 100644 lib/harness-start-hook.ts
 create mode 100644 test/harness-start-hook.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b891029a..4b27a46ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.92.23.0] - 2026-11-01
+
+- **OpenClaw and Hermes: opt-in start hook.** `gstack-harness register openclaw|hermes --start-hook` (or `gstack-config set harness_start_hook on`, or `GSTACK_HARNESS_START_HOOK=1`) adds a `gstack-start` plugin that puts a one-line note on every user turn telling the agent to run a gstack skill's start command as written. Agents in these harnesses read gstack's skills but ran that command on 1 of 29 chances. gstack turns the plugin on through each harness's own CLI, checks that it is active, and exits 4 when it is not. It is off by default, the choice is saved across upgrades, a plugin you disable in the harness stays off, and `--no-start-hook`, unregister and uninstall take it out. See docs/hosts.md#start-hook.
+
 ## [1.92.22.0] - 2026-11-01
 
 **gstack installs into Gemini CLI, and installs made before v1.91.231.0 finally drop the test and eval packages they never needed.** `./setup --host gemini` puts every gstack skill in `~/.gemini/skills`, where Gemini CLI 0.66.0 lists them (#1247). Separately, `./setup` used to treat any checkout that had TypeScript installed as a contributor's, so every install made before v1.91.231.0 (which ran a full `bun install`) kept about 510 MB of dev packages in `node_modules` forever (#3447).
diff --git a/VERSION b/VERSION
index 893844ff7..ee815512e 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.92.22.0
+1.92.23.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index cee2c4bf1..aacc58cd9 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.92.22.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.92.23.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/bin/gstack-config b/bin/gstack-config
index 8992806e2..fce1672af 100755
--- a/bin/gstack-config
+++ b/bin/gstack-config
@@ -208,6 +208,14 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
 #                           #   the same model; every reviewer keeps full.
 # Docs: docs/model-policy.md
 #
+# harness_start_hook:       # on | off. on: ./setup and gstack-harness add the
+#                           #   gstack-start plugin to OpenClaw and Hermes registrations
+#                           #   (a one-line note on every turn to run the start
+#                           #   command of a skill; edits openclaw.json or config.yaml via the
+#                           #   harness CLI). off: takes it out. Absent = each
+#                           #   registration keeps its saved choice (default off).
+#                           #   GSTACK_HARNESS_START_HOOK=1|0 overrides it. Docs: docs/hosts.md
+#
 # ─── Advanced ────────────────────────────────────────────────────────
 # codex_reviews: enabled    # Outside review (Codex or Claude Code by harness): sends
 #                           #   the review prompt and repository content to that model.
@@ -368,6 +376,7 @@ lookup_default() {
     agent_model) echo "" ;; # empty = host (agents keep their own model); gstack-models resolve --role agent
     codex_effort) echo "" ;; # empty = each gate's own effort; /codex --effort, then GSTACK_CODEX_EFFORT, win (gstack-codex-probe run-with-timeout --effort)
     review_effort_tiers) echo "on" ;; # on | off — gstack-review-plan effort tiers (docs/model-policy.md#reasoning-effort)
+    harness_start_hook) echo "" ;; # on | off — empty = each harness registration keeps its saved choice (docs/hosts.md#start-hook)
     ship_greptile_early) echo "true" ;; # true | false — /ship's early Greptile PR
     pr_wait_gating_bots) echo "greptile,macroscope" ;; # review bots gstack-pr-wait --until ready waits for
     pr_wait_advisory_bots) echo "coderabbit" ;; # review bots gstack-pr-wait reports but never waits for
@@ -833,6 +842,10 @@ $_gstack_legacy_root"
       echo "Error: review_effort_tiers '$VALUE' not recognized. Valid values: on, off. Existing value left unchanged." >&2
       exit 1
     fi
+    if [ "$KEY" = "harness_start_hook" ] && [ "$VALUE" != "on" ] && [ "$VALUE" != "off" ]; then
+      echo "Error: harness_start_hook '$VALUE' not recognized. Valid values: on, off. Existing value left unchanged. fix: gstack-config unset harness_start_hook keeps each registration's saved choice (docs/hosts.md#start-hook)" >&2
+      exit 1
+    fi
     if [ "$KEY" = "codex_effort" ]; then
       case "$VALUE" in
         minimal|low|medium|high|xhigh|max|ultra) ;;
@@ -1100,7 +1113,7 @@ $_gstack_legacy_root"
                ship_measure_judge_outputs ship_measure_ask_per_trial_usd ship_measure_budget_usd \
                ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
                plan_review_tier implementation_tier model_frontier_claude model_frontier_openai \
-               model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model; do
+               model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model harness_start_hook; do
       gstack_config_select "$KEY"
       VALUE="$_gstack_cfg_value"
       SOURCE="default"
@@ -1125,7 +1138,7 @@ $_gstack_legacy_root"
                ship_measure_judge_outputs ship_measure_ask_per_trial_usd ship_measure_budget_usd \
                ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
                plan_review_tier implementation_tier model_frontier_claude model_frontier_openai \
-               model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model; do
+               model_smart_claude model_smart_openai codex_effort review_effort_tiers agent_model harness_start_hook; do
       printf '  %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
     done
     ;;
diff --git a/bin/gstack-harness b/bin/gstack-harness
index 5bd39f320..a80024b9f 100755
--- a/bin/gstack-harness
+++ b/bin/gstack-harness
@@ -8,10 +8,16 @@
  *
  * Usage:
  *   gstack-harness detect [--json]
- *   gstack-harness register <target> [--skills router|hybrid|all] [--skills-dir <dir>] [--context <file>] [--print] [--yes] [--no-registry]
+ *   gstack-harness register <target> [--skills router|hybrid|all] [--skills-dir <dir>] [--context <file>] [--start-hook|--no-start-hook] [--print] [--yes] [--no-registry]
  *     --context <file> writes gstack's marked routing block into that file only
  *     (opt-in: setup, upgrades and refresh never add one, and a block you
  *     delete stays deleted); it prints the file and its scope before writing
+ *     --start-hook (OpenClaw, Hermes; opt-in) adds the gstack-start plugin, which
+ *     puts a one-line note on every user turn to run a gstack skill's start
+ *     command, and turns it on through the harness's own commands (this edits
+ *     openclaw.json or Hermes's config.yaml); --no-start-hook takes it out. The
+ *     choice is saved; GSTACK_HARNESS_START_HOOK=1|0 or gstack-config
+ *     harness_start_hook on|off make it too. Exit 4: skills registered, hook not active
  *   gstack-harness unregister <target|registration id> [--remote]
  *   gstack-harness status [--json] [--no-check]
  *   gstack-harness refresh
@@ -46,11 +52,18 @@ function receiptLines(r: RegisterResult): string[] {
     'gstack-harness: ' + t.displayName + ': ' + r.skills + ' gstack skills ' + how + ' at ' + r.dest + ' (' + r.status + (r.written ? ', ' + r.written + ' files written' : '') + ')',
     ...(r.router ? ['  router: ' + r.router + ' (register with --skills all to list every skill natively)'] : []),
     ...r.kept.map(k => '  kept your edit: ' + k),
+    ...(r.hook ? ['  start hook: ' + r.hook.state + (r.hook.state === 'active' ? ' (new sessions get the note; a running gateway picks it up when it reloads)' : '') + (r.hook.detail ? ' - ' + r.hook.detail : '') + (r.hook.fix ? '; ' + r.hook.fix : '')] : []),
     '  ledger: ' + r.ledger,
     '  remove: ' + self + ' unregister ' + r.id,
   ];
 }
 const receipt = (r: RegisterResult) => console.log(receiptLines(r).join('\n'));
+/** A start hook this run turned on, or was asked for, that did not end up active: exit 4 after the receipt. */
+function hookFailed(r: RegisterResult): number {
+  if (!r.hook?.required || r.hook.state === 'active') return 0;
+  console.error(new HarnessError('HARNESS_HOOK_INACTIVE', TARGETS[r.target].displayName + ' start hook is ' + r.hook.state + (r.hook.detail ? ': ' + r.hook.detail : '') + (r.hook.fix ? '. Turn it on: ' + r.hook.fix : '')).report());
+  return 4;
+}
 
 function usage(code: number): never {
   const text = fs.readFileSync(process.argv[1], 'utf8').split('\n').slice(1).filter(l => l.startsWith(' *')).map(l => l.slice(3)).join('\n');
@@ -73,6 +86,7 @@ async function main(): Promise<number> {
       const mode = flag('--skills') as SkillsMode | undefined;
       const skillsDir = flag('--skills-dir'); const context = flag('--context');
       const print = bool('--print'); const yes = bool('--yes'); const noRegistry = bool('--no-registry');
+      const startHook = bool('--start-hook') ? true : bool('--no-start-hook') ? false : undefined;
       const t = getTarget(argv.shift() ?? '');
       if (print) { console.log(printPayload(checkout)); return 0; }
       if (t.name === 'qm') {
@@ -88,10 +102,10 @@ async function main(): Promise<number> {
         return 3;
       }
       if (context) (json ? console.error : console.log)('gstack-harness: context block: ' + path.resolve(context) + ' (' + contextScope(t, context, env, home) + ' scope)');
-      const r = register({ ...base, target: t, mode, skillsDir, context, registry: !noRegistry });
+      const r = register({ ...base, target: t, mode, skillsDir, context, registry: !noRegistry, startHook });
       if (json) console.log(JSON.stringify({ ...r, receipt: receiptLines(r).map(l => l.trim()).join('; ') }));
       else receipt(r);
-      return 0;
+      return hookFailed(r);
     }
     case 'unregister': {
       const remote = bool('--remote');
@@ -113,23 +127,25 @@ async function main(): Promise<number> {
       const extra = (['muse', 'grok'] as TargetName[]).filter(n => TARGETS[n].present(env, home)).map(n => ({ target: n, ...(check ? harnessSees(TARGETS[n], '', env, ['review', 'gstack-review'], true) : { visible: 'unknown' as const }) }));
       if (json) { console.log(JSON.stringify({ registrations: rows, detected: extra })); return 0; }
       if (!rows.length && !extra.length) console.log('gstack-harness: no harness registrations on this machine');
-      for (const r of rows) console.log(r.target + '\t' + r.mode + '\t' + r.dest + '\t' + r.files + ' files\t' + (r.stale ? 'stale (' + r.version + '; refresh: ' + self + ' refresh)' : r.version) + '\tvisible to harness: ' + r.visible + (r.checked ? ' (' + r.checked + ')' : '') + (r.missing?.length ? ' missing: ' + r.missing.slice(0, 5).join(', ') : '') + '\t' + r.id);
+      for (const r of rows) console.log(r.target + '\t' + r.mode + '\t' + r.dest + '\t' + r.files + ' files\t' + (r.stale ? 'stale (' + r.version + '; refresh: ' + self + ' refresh)' : r.version) + '\tvisible to harness: ' + r.visible + (r.checked ? ' (' + r.checked + ')' : '') + (r.missing?.length ? ' missing: ' + r.missing.slice(0, 5).join(', ') : '') + '\t' + r.id
+        + (r.hook ? '\n  start hook: ' + r.hook.state + (r.hook.detail ? ' - ' + r.hook.detail : '') + (r.hook.state !== 'active' && r.hook.fix ? '; ' + r.hook.fix : '') : ''));
       for (const x of extra) console.log(x.target + '\tdetect\t~/.claude/skills\t' + (x.visible === 'yes' ? 'discovered (Claude-rendered, unverified)' : 'unverified') + (x.checked ? ' (' + x.checked + ')' : ''));
       return 0;
     }
     case 'refresh': {
-      for (const r of refresh(base)) if (r.status !== 'unchanged') receipt(r);
-      return 0;
+      let code = 0;
+      for (const r of refresh(base)) { if (r.status !== 'unchanged' || r.hook?.required || r.hook?.retried || r.hook?.detail) receipt(r); code ||= hookFailed(r); }
+      return code;
     }
     case 'auto': {
       const d = detect(env, home);
       let failed = 0;
       const done = new Set<string>();
       for (const n of d.inside.filter(n => TARGETS[n].mechanism === 'skill-folder')) {
-        try { const r = register({ ...base, target: TARGETS[n], registry: true }); done.add(r.id); receipt(r); }
+        try { const r = register({ ...base, target: TARGETS[n], registry: true }); done.add(r.id); receipt(r); hookFailed(r); }
         catch (e) { if (e instanceof HarnessError) { console.error(e.report()); failed = 1; } else throw e; }
       }
-      try { for (const r of refresh(base, done)) if (r.status !== 'unchanged') receipt(r); }
+      try { for (const r of refresh(base, done)) { if (r.status !== 'unchanged' || r.hook?.required || r.hook?.retried || r.hook?.detail) receipt(r); hookFailed(r); } }
       catch (e) { if (e instanceof HarnessError) { console.error(e.report()); failed = 1; } else throw e; }
       for (const n of d.present.filter(n => !d.inside.includes(n) && TARGETS[n].mechanism === 'skill-folder' && !listLedgers(stateRoot).some(l => l.ledger.meta.target === n))) {
         console.log('gstack-harness: ' + TARGETS[n].displayName + ' is installed here; to give it gstack skills: ' + self + ' register ' + n);
diff --git a/bin/gstack-harness-ledger.sh b/bin/gstack-harness-ledger.sh
index 210e85326..6d24acb4b 100644
--- a/bin/gstack-harness-ledger.sh
+++ b/bin/gstack-harness-ledger.sh
@@ -20,12 +20,25 @@
 # (ledgers without the row: when only whitespace is left). Folders gstack
 # created are removed only when empty. A QM pack is never touched here: detaching it from
 # the org is `gstack-harness unregister qm --remote`.
+#
+# A registration with the start hook on (meta start_hook on) owns a second root, the
+# gstack-start plugin folder in the harness profile (meta hook_root). Before its files go,
+# gstack_harness_hook_release turns the plugin off through the harness's own CLI
+# (lib/harness-start-hook.ts), the same step `register --no-start-hook` runs.
 
 _gstack_harness_sha() {
   if command -v sha256sum >/dev/null 2>&1; then sha256sum ${1:+"$1"} | cut -d' ' -f1
   else shasum -a 256 ${1:+"$1"} | cut -d' ' -f1; fi
 }
 
+# True when $1 is below $2 and nothing between them is a symlink ($2 itself may be one).
+_gstack_harness_below() {
+  local p="$1" top="$2"
+  [ -n "$top" ] || return 1
+  case "$p" in "$top"/*) ;; *) return 1 ;; esac
+  while [ "$p" != "$top" ]; do [ -L "$p" ] && return 1; p="$(dirname "$p")"; done
+}
+
 # True when $1 is below $2 and no path from $2 down to $1 is a symlink.
 _gstack_harness_owned() {
   local p="$1" dest="$2"
@@ -57,16 +70,53 @@ _gstack_harness_cut_block() {
   rm -f "$tmp"
 }
 
+# Turns a registration's start hook off in its harness, from the ledger: OpenClaw drops
+# plugins.entries.gstack-start; Hermes removes the plugin and its config entries when its
+# folder holds exactly the files gstack wrote, unedited, and is reached without a symlink
+# below the profile; otherwise it only disables it so an edit or a kept copy survives. The harness runs with PATH, HOME and the profile only. Without the harness on
+# PATH it prints the command to run instead.
+gstack_harness_hook_release() {
+  local ledger="$1" kind a b target="" on="" profile="" root="" edited=0 to="" sub cmd n=0 safe=1 total
+  [ -f "$ledger" ] || return 0
+  while IFS=$'\t' read -r kind a b; do
+    case "$kind" in
+      meta) case "$a" in target) target="$b" ;; start_hook) on="$b" ;; hook_profile) profile="$b" ;; hook_root) root="$b" ;; esac ;;
+      file) if [ -n "$root" ]; then case "$b" in "$root"/*) if [ -f "$b" ]; then n=$((n + 1)); [ "$(_gstack_harness_sha "$b")" != "$a" ] && edited=1; fi ;; esac; fi ;;
+    esac
+  done < "$ledger"
+  { [ "$on" = on ] && [ -n "$profile" ] && [ -n "$root" ]; } || return 0
+  if [ -d "$root" ]; then
+    _gstack_harness_below "$root" "$profile" || { safe=0; edited=1; }
+    total="$(find "$root" -type f ! -path "$root/__pycache__/*" 2>/dev/null | wc -l | tr -d ' ')"
+    [ "${total:-0}" -gt "$n" ] && edited=1
+  fi
+  command -v timeout >/dev/null 2>&1 && to="timeout 60"
+  case "$target" in
+    openclaw) cmd="config unset plugins.entries.gstack-start"
+      if command -v openclaw >/dev/null 2>&1 && env -i PATH="$PATH" HOME="$HOME" OPENCLAW_STATE_DIR="$profile" $to openclaw $cmd </dev/null >/dev/null 2>&1; then :
+      else echo "  start hook: turn it off in OpenClaw yourself: OPENCLAW_STATE_DIR=\"$profile\" openclaw $cmd"; fi ;;
+    hermes) sub=remove; [ "$edited" = 1 ] && sub=disable
+      if command -v hermes >/dev/null 2>&1 && env -i PATH="$PATH" HOME="$HOME" HERMES_HOME="$profile" $to hermes plugins "$sub" gstack-start </dev/null >/dev/null 2>&1; then :
+      else echo "  start hook: turn it off in Hermes yourself: HERMES_HOME=\"$profile\" hermes plugins disable gstack-start"; fi ;;
+  esac
+  if [ "$safe" = 1 ] && [ -d "$root/__pycache__" ] && _gstack_harness_owned "$root/__pycache__" "$root"; then
+    rm -f "$root"/__pycache__/*.pyc
+    rmdir "$root/__pycache__" 2>/dev/null
+  fi
+  return 0
+}
+
 gstack_harness_unregister_ledger() {
-  local ledger="$1" stamp kind a b target="" dest="" pack="" pad="" padpath=""
+  local ledger="$1" stamp kind a b target="" dest="" pack="" pad="" padpath="" hroot="" hprof=""
   : "${GSTACK_STATE_ROOT:?gstack-harness-ledger: GSTACK_STATE_ROOT is not set}"
   [ -f "$ledger" ] || return 0
   stamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
+  gstack_harness_hook_release "$ledger"
   while IFS=$'\t' read -r kind a b; do
     case "$kind" in
-      meta) case "$a" in target) target="$b" ;; dest) dest="$b" ;; qm_pack) pack="$b" ;; esac ;;
+      meta) case "$a" in target) target="$b" ;; dest) dest="$b" ;; qm_pack) pack="$b" ;; hook_root) hroot="$b" ;; hook_profile) hprof="$b" ;; esac ;;
       file)
-        { [ -f "$b" ] && _gstack_harness_owned "$b" "$dest"; } || continue
+        { [ -f "$b" ] && { _gstack_harness_owned "$b" "$dest" || { _gstack_harness_owned "$b" "$hroot" && _gstack_harness_below "$hroot" "$hprof"; }; }; } || continue
         if [ "$(_gstack_harness_sha "$b")" = "$a" ]; then rm -f "$b"
         else mv "$b" "$b.edited-$stamp" && echo "  kept your edit: $b.edited-$stamp"; fi ;;
       blockpad) pad="$a"; padpath="$b" ;;
@@ -75,7 +125,10 @@ gstack_harness_unregister_ledger() {
   done < "$ledger"
   while IFS=$'\t' read -r kind a b; do
     [ "$kind" = dir ] && [ -d "$b" ] && [ ! -L "$b" ] || continue
-    case "$b" in "$dest"/*) _gstack_harness_owned "$b" "$dest" || continue ;; esac
+    case "$b" in
+      "$dest"/*) _gstack_harness_owned "$b" "$dest" || continue ;;
+      *) if [ -n "$hprof" ]; then case "$b" in "$hprof"/*) _gstack_harness_below "$b" "$hprof" || continue ;; esac; fi ;;
+    esac
     rmdir "$b" 2>/dev/null
   done < "$ledger"
   case "$target" in
diff --git a/docs/OPENCLAW.md b/docs/OPENCLAW.md
index e73bab35a..b3fe8af55 100644
--- a/docs/OPENCLAW.md
+++ b/docs/OPENCLAW.md
@@ -195,6 +195,11 @@ registered as a short entry that tells the agent to read the skill's full
 `SKILL.md` in `gstack/skills/`, a plain copy of every skill that OpenClaw
 reads in pages (`.gstack-skills/` under `--skills all`).
 Install, verify and remove: [hosts.md](hosts.md#agent-harnesses).
+Agents in OpenClaw read gstack's skills but rarely run their start command, so
+there is an opt-in [start hook](hosts.md#start-hook): `gstack-harness register
+openclaw --start-hook` adds a `gstack-start` plugin that puts a one-line note on
+every user turn, and grants it the conversation access OpenClaw requires for
+`before_prompt_build` through `openclaw config set`.
 
 The ACP artifacts in `openclaw/` are generated by `bun run gen:skill-docs --host openclaw`.
 
diff --git a/docs/hosts.md b/docs/hosts.md
index 30eacb14c..3482674db 100644
--- a/docs/hosts.md
+++ b/docs/hosts.md
@@ -24,6 +24,8 @@ neither does `./setup --local`.
 
 **What it writes.** Copies in the harness's own skills folder, never edits to
 `openclaw.json`, Hermes's `config.yaml` or any context file you did not name.
+The one exception is the [start hook](#start-hook), which you turn on yourself:
+it adds a plugin and enables it through the harness's own commands.
 A context block is opt-in: `gstack-harness register openclaw|hermes|generic
 --context <file>` writes the marked block into that file only, after printing
 the file and its scope (`profile` inside the harness's own home, else
@@ -67,6 +69,30 @@ characters, the part of a description Hermes's skills index shows.
 | Grok Bot, any chat-only skill library | nothing on disk | `gstack-harness register generic --print`, then paste the router and block into the app | ask it for a gstack skill | delete the pasted text |
 | any other harness | the router in an Agent Skills folder you name, and/or a 600-byte routing block between `<!-- gstack:begin harness-routing -->` markers in a context file you name | `gstack-harness register generic --skills-dir <dir>` and/or `--context <file>`; `gstack-harness manifest generic` prints every skill as JSON | the harness's own skill list | `gstack-harness unregister generic` |
 
+<a id="start-hook"></a>
+### Start hook (OpenClaw and Hermes, opt-in)
+
+Every gstack skill starts with a command in its Preamble (`gstack-skill-start`) that sets up the session: whether it runs unattended, questions, consent, upgrade checks. In OpenClaw and Hermes, agents read gstack's skills but almost never run that command (1 start in 29 chances, HARN-18). The start hook is a small `gstack-start` plugin that puts one note of about 210 characters on every user turn, telling the agent to run that command first, exactly as written, with no pipe.
+
+It is off unless you turn it on, because turning it on changes the harness's own settings:
+
+| | OpenClaw | Hermes |
+|---|---|---|
+| Plugin folder | `${OPENCLAW_STATE_DIR:-~/.openclaw}/extensions/gstack-start` (index.js, openclaw.plugin.json, package.json, note.txt) | `${HERMES_HOME:-~/.hermes}/plugins/gstack-start` (plugin.yaml, __init__.py, note.txt) |
+| Hook | `before_prompt_build`, returning the note as `prependContext` | `pre_llm_call`, returning the note as `context` |
+| Settings it changes, through the harness's own CLI | `openclaw config set plugins.entries.gstack-start.hooks.allowConversationAccess true` and `...enabled true` in `openclaw.json`. OpenClaw runs `before_prompt_build` from a plugin it did not bundle only with that grant, which also lets the plugin's hooks see conversation content (the plugin reads only its own note.txt) | `hermes plugins enable gstack-start` adds it to `plugins.enabled` in `config.yaml` (and creates `config.yaml` when there is none) |
+| Check | `openclaw plugins inspect gstack-start --runtime --json` lists `before_prompt_build` under `typedHooks` | `hermes plugins list` shows `gstack-start` enabled |
+
+**Turn it on.** `gstack-harness register openclaw --start-hook` (or `hermes`), or `gstack-config set harness_start_hook on` followed by `./setup`, or `GSTACK_HARNESS_START_HOOK=1 ./setup --host openclaw`. The first of these that is set decides: the `--start-hook`/`--no-start-hook` flag, then `GSTACK_HARNESS_START_HOOK` (`1`/`on` or `0`/`off`), then `harness_start_hook`, then the choice saved in the registration's ledger. Whatever decides, the choice is saved, so refresh and upgrades keep it. The hook goes only into the harness profile's own plugin folder; a registration with a custom `--skills-dir`, or OpenClaw run with `OPENCLAW_CONFIG_PATH` pointing at another config, gets no hook (`HARNESS_HOOK_UNSUPPORTED` when you ask for one). A hook you already turned on stays on when a later run happens to have `OPENCLAW_CONFIG_PATH` set.
+
+**Check it.** The receipt and `gstack-harness status` show `start hook: active` (configured for new sessions; a running OpenClaw gateway or Hermes gateway picks it up when it reloads or restarts), `written` (files in place but not active, with the reason and the command that fixes it), `disabled` (you turned it off in the harness), `unchecked` (a run that left a hook already on alone, or `status --no-check`; `gstack-harness status` checks it) or `off`. When the run that turns the hook on (or `--start-hook`) leaves it inactive, `gstack-harness register` and `./setup --host` exit 4 after registering the skills (`HARNESS_HOOK_INACTIVE`). Later refreshes and upgrades try once more each time, without failing, until the hook is active or you disable the plugin in the harness.
+
+**Turn it off.** `gstack-harness register openclaw --no-start-hook` (or `hermes`), or `gstack-config set harness_start_hook off` followed by `./setup`. Either turns the plugin off through the harness's CLI and removes its folder. You can also switch it off in the harness (`openclaw config set plugins.entries.gstack-start.enabled false`, `hermes plugins disable gstack-start`); gstack then leaves it off and never turns it back on unless you pass `--start-hook` again. `gstack-harness unregister` and `gstack-uninstall` remove it with the rest (Hermes only disables it when its folder holds an edited file or a kept `.edited-*` copy, so your edit survives), and print the harness command to run when the harness CLI is not on `PATH`.
+
+**What it costs.** The note is about 50 tokens and lands on every user turn, and each copy stays in the session's history, so a long session pays more (mostly cache reads). HARN-18's panel measures the added cost per trial. OpenClaw also logs that it cannot verify where the plugin came from, because gstack writes it instead of installing it from npm or ClawHub.
+
+**One owner.** A `gstack-start` folder this registration did not write stops the hook (`HARNESS_HOOK_OWNED_ELSEWHERE`): turn it off from the gstack install that wrote it, or move it aside.
+
 OpenClaw's ACP route below is unchanged: native registration gives OpenClaw's
 own agent gstack's skills; ACP spawns Claude Code with the full install.
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 654641b76..c5cdb50ef 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -6019,6 +6019,26 @@ The router's description (at most 300 bytes) and the context block (at most 600
 
 There is no ledger for that harness or id under `$GSTACK_STATE_ROOT/harness`. `gstack-harness status` lists every registration on this machine with its id.
 
+<a id="harness-hook-unsupported"></a>
+### `gstack-harness: <harness> has no start hook` / `the start hook goes into the <harness> profile <dir>, and this registration uses another skills folder` (HARNESS_HOOK_UNSUPPORTED)
+
+The [start hook](hosts.md#start-hook) exists for OpenClaw and Hermes only, and it goes into the harness profile's own plugin folder, the one the harness scans. A registration with `--skills-dir` somewhere else has no profile gstack can trust, and with `OPENCLAW_CONFIG_PATH` set OpenClaw reads a config outside the profile, where gstack's settings change would not land, so `--start-hook` is refused and nothing is written. Register without `--skills-dir` (set `OPENCLAW_STATE_DIR` or `HERMES_HOME` to pick the profile), or drop `--start-hook`. When the choice comes from `GSTACK_HARNESS_START_HOOK` or `harness_start_hook` instead of the flag, such a registration just gets no hook, and its receipt says so.
+
+<a id="harness-hook-choice-invalid"></a>
+### `gstack-harness: GSTACK_HARNESS_START_HOOK="<value>" is not on or off` (HARNESS_HOOK_CHOICE_INVALID)
+
+The start hook switch takes `on` or `off` (`GSTACK_HARNESS_START_HOOK` also takes `1` or `0`). Nothing was registered. Fix the value, or unset it so each registration keeps its saved choice.
+
+<a id="harness-hook-owned-elsewhere"></a>
+### `gstack-harness: a gstack-start plugin already exists at <dir> and this registration did not write it` (HARNESS_HOOK_OWNED_ELSEWHERE)
+
+Each harness profile has one start hook, owned by the gstack registration that wrote it, so that removing one install can never take another install's hook away. This folder is not in this registration's ledger: another gstack checkout or state root wrote it, or someone made it by hand. Nothing was written. Run `gstack-harness register <harness> --no-start-hook` from the gstack install that wrote it (its `gstack-harness status` shows the hook), or move the folder aside, then register again.
+
+<a id="harness-hook-inactive"></a>
+### `gstack-harness: <harness> start hook is written: <why>. Turn it on: <command>` (HARNESS_HOOK_INACTIVE, exit 4)
+
+The skills are registered and the start hook's files are in place, but the hook is not active in the harness. gstack turns the hook on through the harness's own CLI and then reads it back, so this means the CLI was not on `PATH`, one of its commands failed or timed out (the message quotes its last output), or the harness's settings block the plugin: OpenClaw's `plugins.allow` set without `gstack-start`, `gstack-start` in `plugins.deny`, or `hooks.allowPromptInjection: false`. gstack never edits your allow or deny lists. Run the printed command, then `gstack-harness status`; `--start-hook` again retries the whole step. `./setup --host` exits 4 for the same reason. Refreshes and upgrades retry on their own without failing, and stop once you disable the plugin in the harness.
+
 <a id="harness-qm-credentials"></a>
 ### `gstack-harness: no QM admin credential in the environment` / `... needs --yes` (HARNESS_QM_CREDENTIALS)
 
diff --git a/docs/uninstall.md b/docs/uninstall.md
index 8428c44d1..c0d044329 100644
--- a/docs/uninstall.md
+++ b/docs/uninstall.md
@@ -8,7 +8,7 @@ If gstack is installed on your machine:
 ~/.claude/skills/gstack/bin/gstack-uninstall
 ```
 
-This handles skills, symlinks, harness registrations (the files `gstack-harness` wrote into OpenClaw, Hermes, a Dot or another harness, from their ledgers), global state (`~/.gstack/`), project-local state, browse daemons, and temp files. Use `--keep-state` to preserve config and analytics. Use `--force` to skip confirmation.
+This handles skills, symlinks, harness registrations (the files `gstack-harness` wrote into OpenClaw, Hermes, a Dot or another harness, from their ledgers, plus the opt-in [start hook](hosts.md#start-hook), which it turns off through the harness's own CLI), global state (`~/.gstack/`), project-local state, browse daemons, and temp files. Use `--keep-state` to preserve config and analytics. Use `--force` to skip confirmation.
 
 ## Option 2: Manual removal (no local repo)
 
@@ -72,6 +72,13 @@ hook, the AskUserQuestion PreToolUse/PostToolUse hooks, and the Stop hooks
 (session timeline, plus verify-gate if you opted in). Left in place, they error
 on every matching event once the install directory is gone.
 
+If you turned on the OpenClaw or Hermes [start hook](hosts.md#start-hook),
+manual removal also leaves its `gstack-start` plugin turned on. Turn it off
+with `openclaw config unset plugins.entries.gstack-start` or `hermes plugins
+disable gstack-start`, then delete
+`${OPENCLAW_STATE_DIR:-~/.openclaw}/extensions/gstack-start` or
+`${HERMES_HOME:-~/.hermes}/plugins/gstack-start`.
+
 ## Clean up CLAUDE.md
 
 The uninstall script does not edit CLAUDE.md. In each project where gstack was added, remove the `## gstack` and `## Skill routing` sections.
diff --git a/lib/harness-register.ts b/lib/harness-register.ts
index 8ac054d77..9b00b665f 100644
--- a/lib/harness-register.ts
+++ b/lib/harness-register.ts
@@ -22,6 +22,7 @@ import { spawnSync } from 'node:child_process';
 import { bunIsolationArgs } from './bun-isolation';
 import { runBashSync } from './script-invocation';
 import { frontmatterList, routerLine } from './skill-triggers';
+import { activateHook, assertHookRoot, hookChoice, hookFiles, hookProfile, hookRoot, inspectHook, isHookTarget, profileSkills, type HookResult } from './harness-start-hook';
 
 export type SkillsMode = 'router' | 'hybrid' | 'all';
 export type TargetName = 'openclaw' | 'hermes' | 'dots' | 'generic' | 'qm' | 'muse' | 'grok';
@@ -134,6 +135,10 @@ export const HARNESS_CODES = {
   HARNESS_RENDER_FAILED: { anchor: 'harness-render-failed', fix: 'run bun install in the gstack checkout, then register again; the render output above names the failing skill' },
   HARNESS_BUDGET_EXCEEDED: { anchor: 'harness-budget-exceeded', fix: 'this is a gstack bug: report it with the byte count printed above' },
   HARNESS_NOT_REGISTERED: { anchor: 'harness-not-registered', fix: 'run gstack-harness status to see the registrations on this machine' },
+  HARNESS_HOOK_UNSUPPORTED: { anchor: 'harness-hook-unsupported', fix: 'the start hook is for OpenClaw and Hermes registered in their own profile: drop --skills-dir (set OPENCLAW_STATE_DIR or HERMES_HOME to pick the profile), or drop --start-hook' },
+  HARNESS_HOOK_CHOICE_INVALID: { anchor: 'harness-hook-choice-invalid', fix: 'set it to on or off (GSTACK_HARNESS_START_HOOK also takes 1 or 0), or unset it' },
+  HARNESS_HOOK_OWNED_ELSEWHERE: { anchor: 'harness-hook-owned-elsewhere', fix: 'if another gstack install wrote it, run that install\'s gstack-harness register <harness> --no-start-hook; otherwise move the folder aside, then register again' },
+  HARNESS_HOOK_INACTIVE: { anchor: 'harness-hook-inactive', fix: 'run the command printed above, then gstack-harness status; the skills themselves are registered' },
   HARNESS_QM_CREDENTIALS: { anchor: 'harness-qm-credentials', fix: 'set GSTACK_QM_URL and either GSTACK_QM_ADMIN_TOKEN, or GSTACK_QM_SIGNING_SECRET with GSTACK_QM_ADMIN_ACTOR, then rerun with --yes' },
   HARNESS_QM_API: { anchor: 'harness-qm-api', fix: 'check that the QM core URL is reachable and the credential is an org admin; gstack-harness status shows whether a pack was left half-registered' },
   HARNESS_QM_PACK_TOO_LARGE: { anchor: 'harness-qm-pack-too-large', fix: 'QM registration is not available yet; give a QM agent gstack with gstack-harness register generic --print pasted into its instructions' },
@@ -342,10 +347,14 @@ export interface RegisterOptions {
   version: string;
   /** Publish an installs.tsv row for host targets (setup's own arm publishes it instead). */
   registry?: boolean;
+  /** --start-hook (true) or --no-start-hook (false); otherwise GSTACK_HARNESS_START_HOOK, gstack-config harness_start_hook, then the ledger decide (lib/harness-start-hook.ts). */
+  startHook?: boolean;
 }
 export interface RegisterResult {
   id: string; target: TargetName; dest: string; mode: SkillsMode;
   status: 'installed' | 'updated' | 'unchanged'; written: number; skills: number; router: string | null; ledger: string; kept: string[];
+  /** The start hook, for OpenClaw and Hermes; required: this run turned it on or was asked to, so anything but active is a failure. */
+  hook?: HookResult & { required?: boolean; retried?: boolean };
 }
 
 const PLAIN = /^[^\t\n\r]+$/;
@@ -424,9 +433,10 @@ function keepEdit(file: string, stamp: string): string {
   return to;
 }
 
-/** Refuses a path outside dest, or one reached through a symlink below dest. */
-function assertOwnedPath(dest: string, p: string): void {
-  if (!p.startsWith(dest + path.sep)) throw new HarnessError('HARNESS_UNSAFE_DESTINATION', p + ' is outside ' + dest);
+/** Refuses a path outside every owned root (the destination, and the start hook's folder), or one reached through a symlink below its root. */
+function assertOwnedPath(roots: string[], p: string): void {
+  const dest = roots.find(r => r && p.startsWith(r + path.sep));
+  if (!dest) throw new HarnessError('HARNESS_UNSAFE_DESTINATION', p + ' is outside ' + roots.filter(Boolean).join(' and '));
   for (let d = p; d !== dest; d = path.dirname(d)) {
     let st: fs.Stats;
     try { st = fs.lstatSync(d); } catch { continue; }
@@ -515,6 +525,56 @@ function shellRegistry(opts: RegisterOptions, fn: string, args: string[]): boole
   return sourcedBash(opts.checkout, 'gstack-install-registry.sh', fn, args, opts.stateRoot, opts.env).status === 0;
 }
 
+interface HookPlan { on: boolean; prevOn: boolean; explicit: boolean; retry: boolean; profile: string; root: string; files: Map<string, Buffer>; note?: string }
+
+/** The start hook for this run: whether it is on, where it goes, and its files (null for targets without a hook). */
+function hookPlan(opts: RegisterOptions, dest: string, prev: Ledger | null): HookPlan | null {
+  const t = opts.target;
+  if (!isHookTarget(t.name)) {
+    if (opts.startHook) throw new HarnessError('HARNESS_HOOK_UNSUPPORTED', t.displayName + ' has no start hook');
+    return null;
+  }
+  const choice = hookChoice(opts.startHook, opts.env, opts.stateRoot, prev?.meta.start_hook);
+  if ('invalid' in choice) throw new HarnessError('HARNESS_HOOK_CHOICE_INVALID', choice.invalid + ' is not on or off');
+  const prevOn = prev?.meta.start_hook === 'on' && !!prev.meta.hook_root && !!prev.meta.hook_profile;
+  const profile = prevOn ? prev!.meta.hook_profile : hookProfile(t.name, opts.env, opts.home);
+  const root = hookRoot(t.name, profile);
+  const plan = { on: choice.on, prevOn, explicit: choice.source === 'flag', retry: prevOn && prev!.meta.hook_active === 'no', profile, root, files: new Map<string, Buffer>() };
+  const saved = prev?.meta.hook_root && prev.meta.hook_profile ? { profile: prev.meta.hook_profile, root: prev.meta.hook_root } : null;
+  const name = t.name;
+  const off = (p: HookPlan) => { if (saved) assertHookRoot(name, saved.profile, saved.root, saved.root, (code, msg) => { throw new HarnessError(code, msg); }); return p; };
+  if (!choice.on) return off(plan);
+  const why = dest !== profileSkills(t.name, profile) ? 'this registration uses another skills folder (' + dest + ')'
+    : t.name === 'openclaw' && opts.env.OPENCLAW_CONFIG_PATH ? 'OPENCLAW_CONFIG_PATH points OpenClaw at a config outside that profile' : '';
+  if (why && (plan.explicit || !prevOn)) {
+    if (plan.explicit) throw new HarnessError('HARNESS_HOOK_UNSUPPORTED', 'the start hook goes into the ' + t.displayName + ' profile ' + profile + ', and ' + why);
+    return off({ ...plan, on: false, note: 'off: ' + why + ' (' + choice.source + ' asked for the hook)' });
+  }
+  try {
+    assertHookRoot(t.name, profile, root, prevOn ? prev!.meta.hook_root : undefined, (code, msg) => { throw new HarnessError(code, msg); });
+  } catch (e) {
+    if (plan.explicit || prevOn || !(e instanceof HarnessError)) throw e;
+    return off({ ...plan, on: false, note: 'off: ' + e.message + ' (' + choice.source + ' asked for the hook; ' + HARNESS_CODES[e.code].fix + ')' });
+  }
+  return { ...plan, files: hookFiles(t.name, root) };
+}
+
+/** Turns the hook on after its files are written (when this run turns it on, was asked to, or the last try did not end active), and reads it back. */
+function finishHook(opts: RegisterOptions, hook: HookPlan | null, released: string): RegisterResult['hook'] {
+  if (!hook) return undefined;
+  if (!hook.on) return { state: 'off', ...(hook.note ? { detail: hook.note } : {}), ...(released ? { fix: released } : {}) };
+  const t = opts.target.name as 'openclaw' | 'hermes';
+  const required = !hook.prevOn || hook.explicit;
+  if (!required && !hook.retry) return { state: 'unchecked', profile: hook.profile, root: hook.root, fix: 'gstack-harness status shows whether it is active' };
+  if (!required) {
+    const now = inspectHook(t, hook.profile, opts.env, opts.home);
+    if (now.state === 'active' || now.state === 'disabled') return { ...now, profile: hook.profile, root: hook.root, retried: true };
+  }
+  const failed = activateHook(t, hook.profile, opts.env, opts.home);
+  const r = inspectHook(t, hook.profile, opts.env, opts.home);
+  return { ...r, ...(failed && r.state !== 'active' && !r.detail?.startsWith(failed) ? { detail: failed + (r.detail ? '; ' + r.detail : '') } : {}), profile: hook.profile, root: hook.root, required, retried: !required };
+}
+
 export function register(opts: RegisterOptions): RegisterResult {
   const t = opts.target;
   if (t.mechanism === 'verify-only' || t.mechanism === 'skill-pack-api') throw new HarnessError('HARNESS_UNKNOWN_TARGET', t.name + ' is not registered through files (use status for ' + t.name + ', or lib/harness-qm.ts for qm)');
@@ -530,12 +590,13 @@ export function register(opts: RegisterOptions): RegisterResult {
   if (explicit) { assertSafeDest(explicit, opts); assertContextFile(t, explicit); }
   const lfile = ledgerPath(opts.stateRoot, id);
   const prev = readLedger(lfile);
+  const hook = hookPlan(opts, dest, prev);
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-harness-'));
   try {
     const { files, router, visible, direct, skills } = planPayload(opts, dest, mode, scratch);
     const prevFiles = new Map((prev?.files ?? []).map(f => [f.path, f.sha]));
     const topOf = (p: string) => path.join(dest, path.relative(dest, p).split(path.sep)[0]);
-    const owned = new Set([...prevFiles.keys()].map(topOf));
+    const owned = new Set([...prevFiles.keys()].filter(p => p.startsWith(dest + path.sep)).map(topOf));
     for (const top of new Set([...files.keys()].map(topOf))) {
       let st: fs.Stats;
       try { st = fs.lstatSync(top); } catch { continue; }
@@ -549,7 +610,8 @@ export function register(opts: RegisterOptions): RegisterResult {
       const other = frontmatterField(fs.readFileSync(md, 'utf8'), 'name');
       if (visible.includes(other)) throw new HarnessError('HARNESS_UNOWNED_ENTRY', 'a skill named ' + other + ' already exists at ' + path.join(dest, e) + ' and gstack did not write it');
     }
-    for (const p of new Set([...files.keys(), ...prevFiles.keys()])) assertOwnedPath(dest, p);
+    for (const [p, b] of hook?.files ?? []) files.set(p, b);
+    for (const p of new Set([...files.keys(), ...prevFiles.keys()])) assertOwnedPath([dest, prev?.meta.hook_root ?? '', hook?.on ? hook.root : ''], p);
     const want = [...files].map(([p, b]) => ({ path: p, sha: sha256(b) }));
     const context = opts.context ? path.resolve(opts.context) : prev?.meta.context ?? '';
     const block = contextBlock(router, direct);
@@ -573,18 +635,21 @@ export function register(opts: RegisterOptions): RegisterResult {
     const same = prev && prev.meta.mode === mode && prev.meta.names === visible.join(',') && prev.files.length === want.length
       && (prev.meta.context ?? '') === context && prev.blocks.length === blocks.length
       && blocks.every(b => prev.blocks.some(p => p.path === b.path && p.sha === b.sha && p.pad === b.pad))
-      && want.every(w => prevFiles.get(w.path) === w.sha && onDiskSha(w.path) === w.sha);
+      && want.every(w => prevFiles.get(w.path) === w.sha && onDiskSha(w.path) === w.sha)
+      && (!hook || (prev.meta.start_hook ?? 'off') === (hook.on ? 'on' : 'off'));
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const kept: string[] = [];
     let written = 0;
+    const released = hook?.prevOn && !hook.on ? sourcedBash(opts.checkout, 'gstack-harness-ledger.sh', 'gstack_harness_hook_release', [lfile], opts.stateRoot, opts.env).stdout.trim() : '';
     if (!same) {
       const dirs = new Set(prev?.dirs ?? []);
       for (const p of files.keys()) for (let d = path.dirname(p); !fs.existsSync(d) && path.dirname(d) !== d; d = path.dirname(d)) dirs.add(d);
-      const record = (recorded: typeof want) => writeLedger(lfile, {
-        meta: { id, target: t.name, dest, mode, checkout: opts.checkout, version: opts.version, names: visible.join(','), ...(router ? { router } : {}), ...(context ? { context } : {}) },
+      const record = (recorded: typeof want, final: boolean) => writeLedger(lfile, {
+        meta: { id, target: t.name, dest, mode, checkout: opts.checkout, version: opts.version, names: visible.join(','), ...(router ? { router } : {}), ...(context ? { context } : {}),
+          ...(hook ? { start_hook: hook.on ? 'on' : 'off' } : {}), ...(hook?.on ? { hook_profile: hook.profile, hook_root: hook.root, ...(!hook.prevOn || hook.explicit ? { hook_active: 'no' } : prev?.meta.hook_active ? { hook_active: prev.meta.hook_active } : {}) } : !final && prev?.meta.hook_root ? { hook_profile: prev.meta.hook_profile, hook_root: prev.meta.hook_root } : {}) },
         files: recorded, dirs: [...dirs].sort((a, b) => b.length - a.length), blocks,
       });
-      record([...want, ...(prev?.files ?? []).filter(f => !files.has(f.path))]);
+      record([...want, ...(prev?.files ?? []).filter(f => !files.has(f.path))], false);
       for (const [p, sha] of prevFiles) {
         if (files.has(p)) continue;
         const disk = onDiskSha(p);
@@ -603,7 +668,7 @@ export function register(opts: RegisterOptions): RegisterResult {
         fs.renameSync(p + '.gstack-new', p);
         written++;
       }
-      record(want);
+      record(want, true);
     }
     for (const [file, text] of blockWrites) {
       if (text === (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null)) continue;
@@ -611,7 +676,12 @@ export function register(opts: RegisterOptions): RegisterResult {
       fs.writeFileSync(file, text);
     }
     if (opts.registry && t.render === 'host') shellRegistry(opts, 'gstack_install_registry_upsert', [t.name, 'global', '-', dest, opts.checkout, opts.checkout, opts.version, '-', '-']);
-    return { id, target: t.name, dest, mode, status: !prev ? 'installed' : same ? 'unchanged' : 'updated', written, skills, router, ledger: lfile, kept };
+    if (same && hook?.on && hook.explicit && prev.meta.hook_active !== 'no') writeLedger(lfile, { ...prev, meta: { ...prev.meta, hook_active: 'no' } });
+    const hookResult = finishHook(opts, hook, released);
+    const active = hookResult?.required || hookResult?.retried ? ({ active: 'yes', disabled: 'disabled' } as Record<string, string>)[hookResult.state] ?? 'no' : '';
+    const saved = active ? readLedger(lfile) : null;
+    if (saved && saved.meta.hook_active !== active) writeLedger(lfile, { ...saved, meta: { ...saved.meta, hook_active: active } });
+    return { id, target: t.name, dest, mode, status: !prev ? 'installed' : same ? 'unchanged' : 'updated', written, skills, router, ledger: lfile, kept, ...(hookResult ? { hook: hookResult } : {}) };
   } finally {
     fs.rmSync(scratch, { recursive: true, force: true });
   }
@@ -647,7 +717,7 @@ export function refresh(base: Omit<RegisterOptions, 'target'>, skip: Set<string>
     }));
 }
 
-export interface StatusRow { id: string; target: string; dest: string; mode: string; files: number; version: string; stale: boolean; visible: 'yes' | 'no' | 'unknown'; checked?: string; missing?: string[] }
+export interface StatusRow { id: string; target: string; dest: string; mode: string; files: number; version: string; stale: boolean; visible: 'yes' | 'no' | 'unknown'; checked?: string; missing?: string[]; hook?: HookResult }
 
 /** Runs the harness's own skill list: 'yes' when every name shows (or, with any, at least one). */
 export function harnessSees(t: Target, dest: string, env: Env, names: string[], any = false): { visible: 'yes' | 'no' | 'unknown'; checked?: string; missing?: string[] } {
@@ -664,6 +734,8 @@ export function status(stateRoot: string, version: string, env: Env, check = tru
   return listLedgers(stateRoot).map(({ ledger: l }) => {
     const t = (TARGETS as Record<string, Target>)[l.meta.target];
     const seen = check && t ? harnessSees(t, l.meta.dest, env, (l.meta.names ?? '').split(',').filter(Boolean)) : { visible: 'unknown' as const };
-    return { id: l.meta.id, target: l.meta.target, dest: l.meta.dest, mode: l.meta.mode, files: l.files.length, version: l.meta.version, stale: l.meta.version !== version, ...seen };
+    const on = l.meta.start_hook === 'on' && isHookTarget(l.meta.target) && !!l.meta.hook_profile;
+    const hook = on ? (check ? inspectHook(l.meta.target as 'openclaw' | 'hermes', l.meta.hook_profile, env, os.homedir()) : { state: 'unchecked' as const }) : undefined;
+    return { id: l.meta.id, target: l.meta.target, dest: l.meta.dest, mode: l.meta.mode, files: l.files.length, version: l.meta.version, stale: l.meta.version !== version, ...seen, ...(hook ? { hook } : {}) };
   });
 }
diff --git a/lib/harness-start-hook.ts b/lib/harness-start-hook.ts
new file mode 100644
index 000000000..7594d6865
--- /dev/null
+++ b/lib/harness-start-hook.ts
@@ -0,0 +1,183 @@
+/**
+ * The gstack-start hook (GST-718): an opt-in plugin that puts one short note on every user turn in OpenClaw
+ * (before_prompt_build) and Hermes (pre_llm_call), telling the agent to run a gstack skill's start command as
+ * written. Skill listings were followed on 1 of 29 chances (HARN-18); a per-turn note 97-100% (HARN-15).
+ *
+ * Off unless the user asks: `--start-hook`, GSTACK_HARNESS_START_HOOK or `gstack-config set harness_start_hook on`.
+ * Turning it on writes a fixed plugin into the harness profile (never under a custom --skills-dir) and changes the
+ * harness's settings only through its own commands: OpenClaw needs plugins.entries.gstack-start.hooks.
+ * allowConversationAccess before a non-bundled plugin's before_prompt_build runs (2026.10.6 hook-policy-decisions:6);
+ * Hermes loads a user plugin only once `hermes plugins enable` lists it. Activation runs only when the choice goes
+ * from off to on, so a plugin the user disabled in the harness is never turned back on. Turning it off and
+ * unregistering run gstack_harness_hook_release in bin/gstack-harness-ledger.sh, the same code gstack-uninstall runs.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readConfigKey } from './state-root';
+
+export const HOOK_ID = 'gstack-start';
+export const START_NOTE_MAX = 300;
+/** Names the helper every rendered preamble runs (test/harness-start-hook.test.ts checks both). */
+export const START_NOTE = 'gstack: if you use a gstack skill this turn, first run the gstack-skill-start command in its Preamble section exactly as written, with no pipe, head, || true or ; echo. Read its output, then follow the skill.';
+
+export type HookTarget = 'openclaw' | 'hermes';
+export type HookState = 'active' | 'written' | 'disabled' | 'unchecked' | 'off';
+export interface HookResult { state: HookState; fix?: string; detail?: string; profile?: string; root?: string }
+type Env = Record<string, string | undefined>;
+
+const MANAGED = "Managed by gstack-harness: it rewrites this file. Turn the hook off: gstack-harness register %s --no-start-hook";
+const SPECS = {
+  openclaw: {
+    profileVar: 'OPENCLAW_STATE_DIR', home: '.openclaw', sub: 'extensions', skills: ['skills'],
+    activate: [['config', 'set', 'plugins.entries.' + HOOK_ID + '.hooks.allowConversationAccess', 'true'], ['config', 'set', 'plugins.entries.' + HOOK_ID + '.enabled', 'true']],
+    files: (): Record<string, string> => ({
+      'index.js': [
+        '// ' + MANAGED.replace('%s', 'openclaw'),
+        "import { readFileSync } from 'node:fs';",
+        "const NOTE = new URL('./note.txt', import.meta.url);",
+        'export default {',
+        "  id: '" + HOOK_ID + "',",
+        "  name: 'gstack start hook',",
+        '  description: "Puts gstack\'s start-command note on each user turn (managed by gstack-harness).",',
+        '  register(api) {',
+        "    api.on('before_prompt_build', () => {",
+        "      let note = '';",
+        "      try { note = readFileSync(NOTE, 'utf8').trim(); } catch {}",
+        '      return note ? { prependContext: note } : undefined;',
+        '    });',
+        '  },',
+        '};',
+        '',
+      ].join('\n'),
+      'openclaw.plugin.json': JSON.stringify({ id: HOOK_ID, name: 'gstack start hook', description: "Puts gstack's start-command note on each user turn (managed by gstack-harness).", configSchema: { type: 'object', additionalProperties: false } }, null, 2) + '\n',
+      'package.json': JSON.stringify({ name: HOOK_ID, version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] } }, null, 2) + '\n',
+    }),
+  },
+  hermes: {
+    profileVar: 'HERMES_HOME', home: '.hermes', sub: 'plugins', skills: ['skills', 'gstack'],
+    activate: [['plugins', 'enable', HOOK_ID]],
+    files: (): Record<string, string> => ({
+      'plugin.yaml': ['# ' + MANAGED.replace('%s', 'hermes'), 'name: ' + HOOK_ID, 'version: 1.0.0', "description: Puts gstack's start-command note on each user turn (managed by gstack-harness).", ''].join('\n'),
+      '__init__.py': [
+        '# ' + MANAGED.replace('%s', 'hermes'),
+        'from pathlib import Path',
+        '',
+        '_NOTE = Path(__file__).with_name("note.txt")',
+        '',
+        '',
+        'def _context(**_kwargs):',
+        '    try:',
+        '        note = _NOTE.read_text(encoding="utf-8").strip()',
+        '    except OSError:',
+        '        return None',
+        '    return {"context": note} if note else None',
+        '',
+        '',
+        'def register(ctx):',
+        '    ctx.register_hook("pre_llm_call", _context)',
+        '',
+      ].join('\n'),
+    }),
+  },
+} as const;
+
+export const isHookTarget = (t: string): t is HookTarget => t === 'openclaw' || t === 'hermes';
+export function hookProfile(t: HookTarget, env: Env, home: string): string {
+  const v = env[SPECS[t].profileVar];
+  return v && path.isAbsolute(v) ? path.resolve(v) : v || path.join(home, SPECS[t].home);
+}
+export const hookRoot = (t: HookTarget, profile: string) => path.join(profile, SPECS[t].sub, HOOK_ID);
+/** The skills folder a registration must use for the hook to go into that profile. */
+export const profileSkills = (t: HookTarget, profile: string) => path.join(profile, ...SPECS[t].skills);
+const activateCommands = (t: HookTarget, profile: string) => SPECS[t].activate.map(a => SPECS[t].profileVar + '=' + JSON.stringify(profile) + ' ' + t + ' ' + a.join(' ')).join(' && ');
+
+/** The plugin's files (absolute path -> bytes): fixed code plus note.txt, which the code reads at each turn. */
+export function hookFiles(t: HookTarget, root: string): Map<string, Buffer> {
+  const out = new Map<string, Buffer>();
+  for (const [name, text] of Object.entries({ ...SPECS[t].files(), 'note.txt': START_NOTE + '\n' })) out.set(path.join(root, name), Buffer.from(text));
+  return out;
+}
+
+/** The user's choice and where it came from: --start-hook/--no-start-hook, then the env var, then gstack-config, then the ledger. */
+export function hookChoice(flag: boolean | undefined, env: Env, stateRoot: string, recorded: string | undefined): { on: boolean; source: 'flag' | 'env' | 'config' | 'ledger' } | { invalid: string } {
+  if (flag !== undefined) return { on: flag, source: 'flag' };
+  const parse = (v: string | null | undefined) => v == null || v === '' ? null : /^(1|on|true|yes)$/i.test(v) ? true : /^(0|off|false|no)$/i.test(v) ? false : undefined;
+  const fromEnv = parse(env.GSTACK_HARNESS_START_HOOK);
+  if (fromEnv === undefined) return { invalid: 'GSTACK_HARNESS_START_HOOK=' + JSON.stringify(env.GSTACK_HARNESS_START_HOOK) };
+  if (fromEnv !== null) return { on: fromEnv, source: 'env' };
+  const stored = readConfigKey('harness_start_hook', { ...env, GSTACK_STATE_ROOT: stateRoot } as NodeJS.ProcessEnv);
+  const fromConfig = parse(stored);
+  if (fromConfig === undefined) return { invalid: 'gstack-config harness_start_hook=' + JSON.stringify(stored) };
+  if (fromConfig !== null) return { on: fromConfig, source: 'config' };
+  return { on: recorded === 'on', source: 'ledger' };
+}
+
+/** Runs the harness's own CLI for one profile: argv only, stdin closed, a timeout, and no environment beyond PATH, HOME and the profile. */
+export function runHarness(t: HookTarget, profile: string, args: readonly string[], env: Env, home: string, timeout = 120_000) {
+  const r = spawnSync(t, args, { env: { PATH: env.PATH ?? '', HOME: home, [SPECS[t].profileVar]: profile }, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout });
+  const out = ((r.stdout ?? '') + (r.stderr ?? '')).trim();
+  return { ok: r.status === 0, stdout: r.stdout ?? '', why: r.error ? String((r.error as NodeJS.ErrnoException).code ?? r.error.message) : r.status === 0 ? '' : 'exit ' + r.status + (out ? ': ' + out.split('\n').slice(-2).join(' | ').slice(0, 300) : '') };
+}
+const onPath = (bin: string, env: Env) => (env.PATH ?? '').split(path.delimiter).some(d => d && fs.existsSync(path.join(d, bin)));
+
+/** Turns the plugin on in the harness. Returns the first failure, or ''. */
+export function activateHook(t: HookTarget, profile: string, env: Env, home: string): string {
+  if (!onPath(t, env)) return t + ' is not on PATH';
+  for (const a of SPECS[t].activate) {
+    const r = runHarness(t, profile, a, env, home, 60_000);
+    if (!r.ok) return t + ' ' + a.join(' ') + ' failed (' + r.why + ')';
+  }
+  return '';
+}
+
+function parseJson(s: string): any {
+  for (const m of s.matchAll(/^[ \t]*[[{]/gm)) { try { return JSON.parse(s.slice(m.index)); } catch {} }
+  return null;
+}
+
+/** Reads the hook back from the harness: active (configured for new sessions), disabled by the user, or written (with the fix). */
+const READ_TIMEOUT = 15_000;
+
+export function inspectHook(t: HookTarget, profile: string, env: Env, home: string): HookResult {
+  const fix = activateCommands(t, profile);
+  if (!onPath(t, env)) return { state: 'written', detail: t + ' is not on PATH, so gstack could not turn the plugin on or check it', fix };
+  if (t === 'hermes') {
+    const r = runHarness(t, profile, ['plugins', 'list', '--json'], env, home, READ_TIMEOUT);
+    const row = (parseJson(r.stdout) ?? []).find?.((p: any) => p?.name === HOOK_ID);
+    if (row?.status === 'enabled') return { state: 'active' };
+    if (row?.status === 'disabled') return { state: 'disabled', detail: 'turned off in Hermes (plugins.disabled); gstack leaves it off', fix: activateCommands(t, profile) };
+    return { state: 'written', detail: row ? 'Hermes lists it as ' + row.status : 'hermes plugins list does not show ' + HOOK_ID + (r.why ? ' (' + r.why + ')' : ''), fix };
+  }
+  const cfg = parseJson(runHarness(t, profile, ['config', 'get', 'plugins', '--json'], env, home, READ_TIMEOUT).stdout) ?? {};
+  const entry = cfg.entries?.[HOOK_ID] ?? {};
+  if (entry.enabled === false) return { state: 'disabled', detail: 'turned off in openclaw.json (plugins.entries.' + HOOK_ID + '.enabled false); gstack leaves it off', fix };
+  if (Array.isArray(cfg.deny) && cfg.deny.includes(HOOK_ID)) return { state: 'written', detail: 'plugins.deny lists ' + HOOK_ID, fix: 'remove ' + HOOK_ID + ' from plugins.deny in openclaw.json' };
+  if (Array.isArray(cfg.allow) && cfg.allow.length && !cfg.allow.includes(HOOK_ID)) return { state: 'written', detail: 'plugins.allow is set and does not list ' + HOOK_ID, fix: 'OPENCLAW_STATE_DIR=' + JSON.stringify(profile) + " openclaw config set plugins.allow '" + JSON.stringify([...cfg.allow, HOOK_ID]) + "'" };
+  if (entry.hooks?.allowPromptInjection === false) return { state: 'written', detail: 'plugins.entries.' + HOOK_ID + '.hooks.allowPromptInjection is false', fix };
+  const r = runHarness(t, profile, ['plugins', 'inspect', HOOK_ID, '--runtime', '--json'], env, home, READ_TIMEOUT);
+  const d = parseJson(r.stdout);
+  if (d?.plugin?.status === 'loaded' && d.plugin.enabled && (d.typedHooks ?? []).some((h: any) => h?.name === 'before_prompt_build')) return { state: 'active' };
+  const why = d?.plugin ? 'status ' + d.plugin.status + (d.plugin.enabled ? '' : ', not enabled') + ((d.typedHooks ?? []).length ? '' : ', before_prompt_build not registered') : 'openclaw plugins inspect failed' + (r.why ? ' (' + r.why + ')' : '');
+  return { state: 'written', detail: why, fix };
+}
+
+/** True when a plugin folder holds nothing but the .edited-<stamp> copies gstack kept when it turned the hook off. */
+function onlyKeptEdits(root: string): boolean {
+  let entries: fs.Dirent[];
+  try { entries = fs.readdirSync(root, { recursive: true, withFileTypes: true }); } catch { return false; }
+  const files = entries.filter(e => !e.isDirectory());
+  return files.length > 0 && files.every(e => e.isFile() && /\.edited-[0-9T-]+Z$/.test(e.name));
+}
+
+/** Checks the plugin folder before anything is written: under the profile, no symlink from the profile down, and not someone else's. */
+export function assertHookRoot(t: HookTarget, profile: string, root: string, recordedRoot: string | undefined, fail: (code: 'HARNESS_UNSAFE_DESTINATION' | 'HARNESS_HOOK_OWNED_ELSEWHERE', msg: string) => never): void {
+  if (!path.isAbsolute(profile) || /[\t\n\r]/.test(profile)) fail('HARNESS_UNSAFE_DESTINATION', 'the ' + t + ' profile ' + profile + ' is not a plain absolute path');
+  const top = path.resolve(profile);
+  for (let d = root; d !== top && d !== path.dirname(d); d = path.dirname(d)) {
+    let st: fs.Stats;
+    try { st = fs.lstatSync(d); } catch { continue; }
+    if (st.isSymbolicLink()) fail('HARNESS_UNSAFE_DESTINATION', d + ' is a symlink');
+  }
+  if (fs.existsSync(root) && recordedRoot !== root && !onlyKeptEdits(root)) fail('HARNESS_HOOK_OWNED_ELSEWHERE', 'a ' + HOOK_ID + ' plugin already exists at ' + root + ' and this registration did not write it');
+}
diff --git a/package.json b/package.json
index 4ccb22127..aee1fd8cb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.92.22",
+  "version": "1.92.23",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/setup b/setup
index 2ae82558e..f4d247792 100755
--- a/setup
+++ b/setup
@@ -519,7 +519,8 @@ $_RF_TARGETS
 EOF
   grep -q '	failed	' "$_RF_SUMMARY" && _RF_FAILED=1
   if [ "$HARNESS_AUTO" -eq 1 ] && [ -d "$GSTACK_STATE_ROOT/harness" ]; then
-    bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$SOURCE_GSTACK_DIR/bin/gstack-harness" refresh || _RF_FAILED=1
+    # Exit 4: every registration refreshed; a start hook this run turned on is not active (printed above).
+    bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$SOURCE_GSTACK_DIR/bin/gstack-harness" refresh || [ "$?" -eq 4 ] || _RF_FAILED=1
   fi
   echo ""
   if [ "$_RF_FAILED" -eq 1 ]; then
@@ -2442,11 +2443,16 @@ mkdir -p "$HOME/.gstack/projects"
 # OpenClaw and Hermes: gstack-harness copies this checkout's render for the
 # harness into the harness's own skills folder, records every file in a ledger
 # (bin/gstack-uninstall removes exactly those) and never edits harness config
-# (lib/harness-register.ts). Nothing else in this run applies to them.
+# unless the user opted into the start hook (GSTACK_HARNESS_START_HOOK or
+# gstack-config harness_start_hook; lib/harness-start-hook.ts). Exit 4 from
+# register means the skills are registered and the start hook is not active.
+# Nothing else in this run applies to them.
 _gstack_harness() { bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" "$SOURCE_GSTACK_DIR/bin/gstack-harness" "$@"; }
 if [ -n "$INSTALL_HARNESS" ]; then
   _setup_arm_begin "$INSTALL_HARNESS" global "$INSTALL_HARNESS"
-  if ! _HARNESS_JSON="$(_gstack_harness register "$INSTALL_HARNESS" --json --no-registry)"; then
+  _HARNESS_RC=0
+  _HARNESS_JSON="$(_gstack_harness register "$INSTALL_HARNESS" --json --no-registry)" || _HARNESS_RC=$?
+  if [ "$_HARNESS_RC" -ne 0 ] && [ "$_HARNESS_RC" -ne 4 ]; then
     _SETUP_REFUSED="gstack-harness could not register $INSTALL_HARNESS (reason above); nothing was changed for it"
     exit 1
   fi
@@ -2454,6 +2460,7 @@ if [ -n "$INSTALL_HARNESS" ]; then
   _setup_arm_publish "$INSTALL_HARNESS" global - "$_HARNESS_DEST" "$SOURCE_GSTACK_DIR" - -
   log "$(printf '%s\n' "$_HARNESS_JSON" | sed -n 's/.*"receipt":"\([^"]*\)".*/\1/p')"
   _setup_print_summary
+  [ "$_HARNESS_RC" -eq 4 ] && exit 4
   printf '%s' "$_SETUP_ROWS" | _setup_ready_line
   exit 0
 fi
diff --git a/test/fixtures/module-size-ratchet.json b/test/fixtures/module-size-ratchet.json
index a97ff0ccd..ad2cf1081 100644
--- a/test/fixtures/module-size-ratchet.json
+++ b/test/fixtures/module-size-ratchet.json
@@ -6,6 +6,7 @@
     { "file": "scripts/modules-cli.ts", "movedFrom": "(new: bin/gstack-modules CLI, GSTA-140)" },
     { "file": "lib/harness-register.ts", "movedFrom": "(new: gstack-harness registrar, GSTA-135)" },
     { "file": "lib/harness-qm.ts", "movedFrom": "(new: gstack-harness QM skill-pack target, GSTA-135)" },
+    { "file": "lib/harness-start-hook.ts", "movedFrom": "(new: gstack-harness start hook for OpenClaw and Hermes, GST-718)" },
     { "file": "lib/design-lint/render.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint.mjs)" },
     { "file": "lib/design-lint/render-probe.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint-render.mjs)" },
     { "file": "lib/design-lint/render-probe-space.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint-render.mjs)" },
diff --git a/test/harness-start-hook.test.ts b/test/harness-start-hook.test.ts
new file mode 100644
index 000000000..a226c2c6c
--- /dev/null
+++ b/test/harness-start-hook.test.ts
@@ -0,0 +1,514 @@
+/**
+ * The gstack-start hook (GST-718): opt-in OpenClaw and Hermes plugins that put gstack's start note on every user
+ * turn. Harness CLIs are fake /bin/sh scripts on PATH that record their argv and environment and keep the
+ * plugin state in the profile, so these cases run no harness and spend nothing.
+ */
+import { afterAll, afterEach, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { TARGETS, readLedger, register, status, unregister, type RegisterOptions } from '../lib/harness-register';
+import { HOOK_ID, START_NOTE, START_NOTE_MAX, hookChoice, hookFiles, inspectHook } from '../lib/harness-start-hook';
+import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, registryRows, runSetup } from './helpers/install-fixture';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const VERSION = fs.readFileSync(path.join(ROOT, 'VERSION'), 'utf8').trim();
+const temps: string[] = [];
+const tmp = () => { const d = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-hook-test-'))); temps.push(d); return d; };
+afterEach(() => { cleanupFixtures(); for (const d of temps.splice(0)) fs.rmSync(d, { recursive: true, force: true }); });
+afterAll(cleanupSeed);
+
+const FAKE_OPENCLAW = String.raw`#!/bin/sh
+d="$OPENCLAW_STATE_DIR"; c="$d/fake-config"
+printf '%s|secret=%s|home=%s|cfg=%s\n' "$*" "$ANTHROPIC_API_KEY" "$HOME" "$OPENCLAW_CONFIG_PATH" >> "$d/fake-calls"
+[ -f "$d/fake-fail" ] && { echo "config write refused" >&2; exit 3; }
+[ -f "$d/fake-kill" ] && { rm -f "$d/fake-kill"; kill -9 "$PPID"; sleep 5; }
+[ -f "$d/fake-noisy" ] && echo "[plugins] gstack-start: cannot verify where this plugin came from"
+[ -f "$d/fake-hang" ] && [ "$1" = plugins ] && exec sleep 40
+touch "$c"
+acc=false; grep -q '^plugins.entries.gstack-start.hooks.allowConversationAccess=true$' "$c" && acc=true
+en=$(grep '^plugins.entries.gstack-start.enabled=' "$c" | tail -1 | cut -d= -f2); enj=null; [ -n "$en" ] && enj=$en
+case "$1 $2" in
+  "config set") echo "$3=$4" >> "$c" ;;
+  "config unset") grep -v "^$3" "$c" > "$c.t"; mv "$c.t" "$c" ;;
+  "config get") api=""; grep -q '^plugins.entries.gstack-start.hooks.allowPromptInjection=false$' "$c" && api=',"allowPromptInjection":false'
+    printf '{"allow":%s,"deny":%s,"entries":{"gstack-start":{"enabled":%s,"hooks":{"allowConversationAccess":%s%s}}}}\n' "$(cat "$d/fake-allow" 2>/dev/null || echo null)" "$(cat "$d/fake-deny" 2>/dev/null || echo null)" "$enj" "$acc" "$api" ;;
+  "plugins inspect")
+    hooks=""; [ -d "$d/extensions/gstack-start" ] && [ "$acc" = true ] && [ "$en" != false ] && hooks='{"name":"before_prompt_build"}'
+    printf '{"plugin":{"status":"loaded","enabled":%s},"typedHooks":[%s]}\n' "$([ "$en" = false ] && echo false || echo true)" "$hooks" ;;
+esac
+`;
+const FAKE_HERMES = String.raw`#!/bin/sh
+d="$HERMES_HOME"
+printf '%s|secret=%s|home=%s\n' "$*" "$ANTHROPIC_API_KEY" "$HOME" >> "$d/fake-calls"
+case "$1 $2" in
+  "plugins enable") echo enabled > "$d/fake-state" ;;
+  "plugins disable") echo disabled > "$d/fake-state" ;;
+  "plugins remove") rm -rf "$d/plugins/$3" "$d/fake-state" ;;
+  "plugins list") if [ -d "$d/plugins/gstack-start" ]; then printf '[{"name":"gstack-start","status":"%s"}]\n' "$(cat "$d/fake-state" 2>/dev/null || echo 'not enabled')"; else echo '[]'; fi ;;
+esac
+`;
+
+/** A temp home, state root and profile, with fake openclaw and hermes CLIs first on PATH. */
+function rig(target: 'openclaw' | 'hermes', extra: { noCli?: boolean; env?: Record<string, string> } = {}) {
+  const d = tmp();
+  const bin = path.join(d, 'bin');
+  fs.mkdirSync(bin);
+  fs.writeFileSync(path.join(bin, 'openclaw'), FAKE_OPENCLAW, { mode: 0o755 });
+  fs.writeFileSync(path.join(bin, 'hermes'), FAKE_HERMES, { mode: 0o755 });
+  const profile = path.join(d, target === 'openclaw' ? 'oc' : 'he');
+  fs.mkdirSync(profile, { recursive: true });
+  const env = { PATH: (extra.noCli ? '' : bin + path.delimiter) + '/usr/bin:/bin', ANTHROPIC_API_KEY: 'sekret', [target === 'openclaw' ? 'OPENCLAW_STATE_DIR' : 'HERMES_HOME']: profile, ...extra.env };
+  const o = (more: Partial<RegisterOptions> = {}): RegisterOptions => ({ target: TARGETS[target], checkout: ROOT, stateRoot: path.join(d, 'state'), env, home: path.join(d, 'home'), version: VERSION, ...more });
+  const root = path.join(profile, target === 'openclaw' ? 'extensions' : 'plugins', HOOK_ID);
+  const calls = () => fs.existsSync(path.join(profile, 'fake-calls')) ? fs.readFileSync(path.join(profile, 'fake-calls'), 'utf8').trim().split('\n') : [];
+  return { d, bin, profile, env, o, root, calls };
+}
+
+describe('start hook: the note and the plugin files', () => {
+  test('the note fits its budget and names the helper every rendered preamble runs', () => {
+    expect(START_NOTE.length).toBeLessThanOrEqual(START_NOTE_MAX);
+    expect(START_NOTE).toContain('gstack-skill-start');
+    const review = fs.readFileSync(path.join(ROOT, 'review', 'SKILL.md'), 'utf8');
+    expect(review).toContain('## Preamble');
+    expect(review).toMatch(/bin\/gstack-skill-start --skill "review"/);
+  });
+
+  test('plugin code is fixed text: no install path in it, and it reads note.txt from its own folder', () => {
+    for (const t of ['openclaw', 'hermes'] as const) {
+      const a = hookFiles(t, '/one/place/' + HOOK_ID); const b = hookFiles(t, '/an\'other "place"/' + HOOK_ID);
+      expect([...a.values()].map(String)).toEqual([...b.values()].map(String));
+      for (const [p, bytes] of a) if (!p.endsWith('note.txt')) expect(String(bytes)).not.toContain('/one/place');
+      expect(String(a.get('/one/place/' + HOOK_ID + '/note.txt'))).toBe(START_NOTE + '\n');
+    }
+  });
+
+  test('the OpenClaw plugin returns the note as prependContext, and nothing when note.txt is gone', async () => {
+    const d = tmp();
+    for (const [p, b] of hookFiles('openclaw', d)) fs.writeFileSync(p, b);
+    const load = async () => {
+      let handler: (() => unknown) | undefined;
+      const mod = await import(path.join(d, 'index.js') + '?' + Math.random());
+      mod.default.register({ on: (name: string, fn: () => unknown) => { expect(name).toBe('before_prompt_build'); handler = fn; } });
+      return handler!();
+    };
+    expect(await load()).toEqual({ prependContext: START_NOTE });
+    fs.rmSync(path.join(d, 'note.txt'));
+    expect(await load()).toBeUndefined();
+  });
+
+  test('the Hermes plugin registers pre_llm_call and returns the note as context, and nothing when note.txt is gone', () => {
+    const d = tmp();
+    const pkg = path.join(d, 'gstack_start');
+    fs.mkdirSync(pkg);
+    for (const [p, b] of hookFiles('hermes', pkg)) fs.writeFileSync(p, b);
+    const probe = 'import sys, json\nsys.path.insert(0, sys.argv[1])\nimport gstack_start as m\nseen = []\nclass Ctx:\n    def register_hook(self, name, fn): seen.append((name, fn))\nm.register(Ctx())\nprint(json.dumps([seen[0][0], seen[0][1](session_id="s", user_message="hi")]))\n';
+    const run = () => spawnSync('python3', ['-B', '-c', probe, d], { encoding: 'utf8', timeout: 30_000 });
+    let r = run();
+    expect(r.status, r.stderr).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual(['pre_llm_call', { context: START_NOTE }]);
+    fs.rmSync(path.join(pkg, 'note.txt'));
+    r = run();
+    expect(JSON.parse(r.stdout)).toEqual(['pre_llm_call', null]);
+  });
+});
+
+describe('start hook: who decides', () => {
+  test('flag, then GSTACK_HARNESS_START_HOOK, then gstack-config harness_start_hook, then the ledger', () => {
+    const d = tmp();
+    const state = path.join(d, 'state');
+    fs.mkdirSync(state);
+    expect(hookChoice(undefined, {}, state, undefined)).toEqual({ on: false, source: 'ledger' });
+    expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: true, source: 'ledger' });
+    fs.writeFileSync(path.join(state, 'config.yaml'), 'harness_start_hook: off\n');
+    expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: false, source: 'config' });
+    expect(hookChoice(undefined, { GSTACK_HARNESS_START_HOOK: '1' }, state, undefined)).toEqual({ on: true, source: 'env' });
+    expect(hookChoice(false, { GSTACK_HARNESS_START_HOOK: 'on' }, state, 'on')).toEqual({ on: false, source: 'flag' });
+    expect(hookChoice(undefined, { GSTACK_HARNESS_START_HOOK: 'maybe' }, state, undefined)).toEqual({ invalid: 'GSTACK_HARNESS_START_HOOK="maybe"' });
+    fs.writeFileSync(path.join(state, 'config.yaml'), 'harness_start_hook: sometimes\n');
+    expect(hookChoice(undefined, {}, state, undefined)).toEqual({ invalid: 'gstack-config harness_start_hook="sometimes"' });
+  });
+
+  test('gstack-config takes harness_start_hook on or off and refuses anything else', () => {
+    const d = tmp();
+    const cfg = (...args: string[]) => spawnSync(path.join(ROOT, 'bin', 'gstack-config'), args, { env: { PATH: process.env.PATH, HOME: path.join(d, 'home'), GSTACK_STATE_ROOT: path.join(d, 'state') }, encoding: 'utf8', timeout: 30_000 });
+    expect(cfg('set', 'harness_start_hook', 'on').status).toBe(0);
+    expect(cfg('get', 'harness_start_hook').stdout.trim()).toBe('on');
+    const bad = cfg('set', 'harness_start_hook', 'yes');
+    expect(bad.status).toBe(1);
+    expect(bad.stderr).toContain("harness_start_hook 'yes' not recognized");
+    expect(cfg('get', 'harness_start_hook').stdout.trim()).toBe('on');
+  });
+
+  test('an invalid choice and a hook for a target or folder without one stop before anything is written', () => {
+    const r = rig('openclaw', { env: { GSTACK_HARNESS_START_HOOK: 'maybe' } });
+    expect(() => register(r.o())).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_CHOICE_INVALID' }));
+    const s = rig('openclaw');
+    expect(() => register(s.o({ skillsDir: path.join(s.d, 'custom', 'skills'), startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' }));
+    expect(() => register({ ...s.o({ startHook: true }), target: TARGETS.dots, skillsDir: path.join(s.d, 'dots') })).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' }));
+    expect(() => register({ ...s.o({ startHook: true }), env: { ...s.env, OPENCLAW_CONFIG_PATH: '/elsewhere/openclaw.json' } })).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' }));
+    for (const x of [r, s]) { expect(fs.existsSync(path.join(x.profile, 'skills'))).toBe(false); expect(x.calls()).toEqual([]); }
+    expect(fs.existsSync(path.join(s.d, 'custom'))).toBe(false);
+  });
+
+  test('a plugin folder gstack did not write, or a symlink on the way to it, stops an explicit --start-hook with nothing written, and turns an env or config opt-in into hook off', () => {
+    const r = rig('openclaw');
+    fs.mkdirSync(r.root, { recursive: true });
+    fs.writeFileSync(path.join(r.root, 'index.js'), 'mine');
+    expect(() => register(r.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_OWNED_ELSEWHERE' }));
+    expect(fs.readFileSync(path.join(r.root, 'index.js'), 'utf8')).toBe('mine');
+    const s = rig('hermes');
+    fs.mkdirSync(path.join(s.d, 'elsewhere'));
+    fs.symlinkSync(path.join(s.d, 'elsewhere'), path.join(s.profile, 'plugins'));
+    expect(() => register(s.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' }));
+    expect(fs.readdirSync(path.join(s.d, 'elsewhere'))).toEqual([]);
+    const viaEnv = register({ ...s.o(), env: { ...s.env, GSTACK_HARNESS_START_HOOK: '1' } });
+    expect(viaEnv.hook?.state).toBe('off');
+    expect(viaEnv.hook?.detail).toContain('is a symlink (env asked for the hook');
+    expect(fs.existsSync(path.join(s.profile, 'skills', 'gstack'))).toBe(true);
+    expect(fs.readdirSync(path.join(s.d, 'elsewhere'))).toEqual([]);
+    expect(r.calls().concat(s.calls())).toEqual([]);
+  });
+
+  test('a file, an empty folder or a folder with any non-kept file at the plugin path is still owned elsewhere', () => {
+    for (const make of [(root: string) => fs.writeFileSync(root, 'x'), (root: string) => fs.mkdirSync(path.join(root, 'sub'), { recursive: true }),
+      (root: string) => { fs.mkdirSync(root, { recursive: true }); fs.writeFileSync(path.join(root, 'note.txt.edited-2026-11-01T06-31-18-911Z'), 'kept'); fs.writeFileSync(path.join(root, 'plugin.yaml'), 'mine'); }]) {
+      const r = rig('hermes');
+      fs.mkdirSync(path.dirname(r.root), { recursive: true });
+      make(r.root);
+      expect(() => register(r.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_OWNED_ELSEWHERE' }));
+      expect(register({ ...r.o(), env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1' } }).hook?.state).toBe('off');
+    }
+  }, 300_000);
+
+  test('a profile path with a trailing slash under a symlinked parent still takes the hook and is saved without the slash', () => {
+    const r = rig('hermes');
+    const link = path.join(tmp(), 'ln');
+    fs.symlinkSync(r.d, link);
+    const res = register({ ...r.o({ startHook: true }), env: { ...r.env, HERMES_HOME: path.join(link, 'he') + '/' } });
+    expect(res.hook?.state).toBe('active');
+    expect(readLedger(res.ledger)!.meta.hook_profile).toBe(path.join(link, 'he'));
+    expect(fs.existsSync(path.join(r.root, 'plugin.yaml'))).toBe(true);
+  }, 120_000);
+});
+
+describe('start hook: OpenClaw lifecycle (fake CLI)', () => {
+  test('default registration adds no plugin and runs no harness command', () => {
+    const r = rig('openclaw');
+    const res = register(r.o());
+    expect(res.hook).toEqual({ state: 'off' });
+    expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false);
+    expect(r.calls()).toEqual([]);
+    expect(readLedger(res.ledger)!.files.every(f => f.path.startsWith(path.join(r.profile, 'skills') + path.sep))).toBe(true);
+  }, 120_000);
+
+  test('on, refreshed, disabled by the user, then off: activation runs once, a user disable sticks, opt-out cleans up', () => {
+    const r = rig('openclaw');
+    const on = register(r.o({ startHook: true }));
+    expect(on.hook).toMatchObject({ state: 'active', required: true, profile: r.profile, root: r.root });
+    expect(fs.readdirSync(r.root).sort()).toEqual(['index.js', 'note.txt', 'openclaw.plugin.json', 'package.json']);
+    const meta = readLedger(on.ledger)!.meta;
+    expect([meta.start_hook, meta.hook_profile, meta.hook_root]).toEqual(['on', r.profile, r.root]);
+    const argv = r.calls().map(l => l.split('|')[0]);
+    expect(argv).toEqual([
+      'config set plugins.entries.gstack-start.hooks.allowConversationAccess true',
+      'config set plugins.entries.gstack-start.enabled true',
+      'config get plugins --json',
+      'plugins inspect gstack-start --runtime --json',
+    ]);
+    for (const l of r.calls()) expect(l).toContain('|secret=|home=' + path.join(r.d, 'home') + '|cfg=');
+
+    const again = register(r.o());
+    expect(again.status).toBe('unchanged');
+    expect(again.hook?.state).toBe('unchecked');
+    expect(r.calls()).toHaveLength(4);
+
+    fs.appendFileSync(path.join(r.profile, 'fake-config'), 'plugins.entries.gstack-start.enabled=false\n');
+    register(r.o());
+    expect(r.calls().filter(l => l.startsWith('config set'))).toHaveLength(2);
+    expect(status(r.o().stateRoot, VERSION, r.env).find(s => s.target === 'openclaw')?.hook?.state).toBe('disabled');
+
+    const off = register(r.o({ startHook: false }));
+    expect(off.hook?.state).toBe('off');
+    expect(r.calls().some(l => l.startsWith('config unset plugins.entries.gstack-start|'))).toBe(true);
+    expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false);
+    const after = readLedger(off.ledger)!.meta;
+    expect(after.start_hook).toBe('off');
+    expect(after.hook_root).toBeUndefined();
+  }, 300_000);
+
+  test('a failed or blocked activation reports written with the fix; the CLI exits 4 after registering the skills', () => {
+    const r = rig('openclaw');
+    fs.writeFileSync(path.join(r.profile, 'fake-allow'), '["anthropic"]');
+    const res = register(r.o({ startHook: true }));
+    expect(res.hook).toMatchObject({ state: 'written', required: true, detail: 'plugins.allow is set and does not list gstack-start' });
+    expect(res.hook?.fix).toContain('openclaw config set plugins.allow \'["anthropic","gstack-start"]\'');
+
+    const s = rig('openclaw');
+    fs.writeFileSync(path.join(s.profile, 'fake-fail'), '');
+    const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw', '--start-hook'],
+      { env: { ...s.env, PATH: s.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(s.d, 'home'), GSTACK_STATE_ROOT: path.join(s.d, 'state') }, encoding: 'utf8', timeout: 240_000 });
+    expect(cli.status, cli.stderr).toBe(4);
+    expect(cli.stdout).toContain('start hook: written');
+    expect(cli.stderr).toContain('config write refused');
+    expect(cli.stderr).toContain('(HARNESS_HOOK_INACTIVE; docs/troubleshooting.md#harness-hook-inactive)');
+    expect(fs.existsSync(path.join(s.profile, 'skills', 'gstack', 'SKILL.md'))).toBe(true);
+  }, 300_000);
+
+  test('a run killed during activation leaves the hook marked not active, so the next plain register activates it', () => {
+    const r = rig('openclaw');
+    fs.writeFileSync(path.join(r.profile, 'fake-kill'), '');
+    const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw'],
+      { env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1', PATH: r.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 240_000 });
+    expect(cli.signal, cli.stderr).toBe('SIGKILL');
+    const dir = path.join(r.d, 'state', 'harness');
+    const lfile = fs.readdirSync(dir).find(f => f.endsWith('.ledger'));
+    expect(readLedger(path.join(dir, lfile!))!.meta).toMatchObject({ start_hook: 'on', hook_active: 'no' });
+    const next = register(r.o());
+    expect(next.hook).toMatchObject({ state: 'active', retried: true });
+    expect(readLedger(next.ledger)!.meta.hook_active).toBe('yes');
+  }, 300_000);
+
+  test('off with an edited plugin file keeps the edit, and the same registration can turn the hook back on', () => {
+    const r = rig('openclaw');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    fs.writeFileSync(path.join(r.root, 'note.txt'), 'my note\n');
+    const off = register(r.o({ startHook: false }));
+    expect(off.kept).toHaveLength(1);
+    expect(off.kept[0]).toMatch(/note\.txt\.edited-/);
+    const on = register(r.o({ startHook: true }));
+    expect(on.hook?.state).toBe('active');
+    expect(fs.readFileSync(path.join(r.root, 'note.txt'), 'utf8')).toBe(START_NOTE + '\n');
+    expect(fs.readFileSync(off.kept[0], 'utf8')).toBe('my note\n');
+  }, 300_000);
+
+  test('an explicit --start-hook on an unchanged registration killed during activation is retried by the next run', () => {
+    const r = rig('openclaw');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    fs.writeFileSync(path.join(r.profile, 'fake-kill'), '');
+    const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw', '--start-hook'],
+      { env: { ...r.env, PATH: r.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 240_000 });
+    expect(cli.signal, cli.stderr).toBe('SIGKILL');
+    const dir = path.join(r.d, 'state', 'harness');
+    expect(readLedger(path.join(dir, fs.readdirSync(dir).find(f => f.endsWith('.ledger'))!))!.meta.hook_active).toBe('no');
+    expect(register(r.o()).hook).toMatchObject({ state: 'active', retried: true });
+  }, 300_000);
+
+  test('a log line in brackets before the harness JSON still reads back as active', () => {
+    const r = rig('openclaw');
+    fs.writeFileSync(path.join(r.profile, 'fake-noisy'), '');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    expect(inspectHook('openclaw', r.profile, r.env, path.join(r.d, 'home')).state).toBe('active');
+  }, 120_000);
+
+  test('a hung harness read-back gives up after a short timeout', () => {
+    const r = rig('openclaw');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    fs.writeFileSync(path.join(r.profile, 'fake-hang'), '');
+    const t0 = Date.now();
+    expect(inspectHook('openclaw', r.profile, r.env, path.join(r.d, 'home')).state).toBe('written');
+    expect(Date.now() - t0).toBeLessThan(35_000);
+  }, 120_000);
+
+  test('without the harness on PATH the hook is written, not active, and names the commands to run', () => {
+    const r = rig('openclaw', { noCli: true });
+    const res = register(r.o({ startHook: true }));
+    expect(res.hook).toMatchObject({ state: 'written', detail: 'openclaw is not on PATH, so gstack could not turn the plugin on or check it' });
+    expect(res.hook?.fix).toBe('OPENCLAW_STATE_DIR=' + JSON.stringify(r.profile) + ' openclaw config set plugins.entries.gstack-start.hooks.allowConversationAccess true && OPENCLAW_STATE_DIR=' + JSON.stringify(r.profile) + ' openclaw config set plugins.entries.gstack-start.enabled true');
+  }, 120_000);
+});
+
+describe('start hook: read back and retry (fake CLI)', () => {
+  test('OpenClaw deny lists and allowPromptInjection false read back as written; a Hermes disable reads back as disabled', () => {
+    const r = rig('openclaw');
+    fs.mkdirSync(r.root, { recursive: true });
+    const cfg = (line: string) => fs.appendFileSync(path.join(r.profile, 'fake-config'), line + '\n');
+    cfg('plugins.entries.gstack-start.hooks.allowConversationAccess=true');
+    expect(inspectHook('openclaw', r.profile, r.env, r.d).state).toBe('active');
+    fs.writeFileSync(path.join(r.profile, 'fake-deny'), '["gstack-start"]');
+    expect(inspectHook('openclaw', r.profile, r.env, r.d)).toMatchObject({ state: 'written', detail: 'plugins.deny lists gstack-start' });
+    fs.rmSync(path.join(r.profile, 'fake-deny'));
+    cfg('plugins.entries.gstack-start.hooks.allowPromptInjection=false');
+    expect(inspectHook('openclaw', r.profile, r.env, r.d)).toMatchObject({ state: 'written', detail: 'plugins.entries.gstack-start.hooks.allowPromptInjection is false' });
+    const h = rig('hermes');
+    fs.mkdirSync(h.root, { recursive: true });
+    fs.writeFileSync(path.join(h.profile, 'fake-state'), 'disabled');
+    expect(inspectHook('hermes', h.profile, h.env, h.d)).toMatchObject({ state: 'disabled' });
+  });
+
+  test('after a failed opt-in, refresh retries without failing, and stops for good once the user disables the plugin', () => {
+    const r = rig('openclaw');
+    fs.writeFileSync(path.join(r.profile, 'fake-allow'), '["anthropic"]');
+    expect(register(r.o({ startHook: true })).hook).toMatchObject({ state: 'written', required: true });
+    expect(readLedger(register(r.o()).ledger)!.meta.hook_active).toBe('no');
+    const retry = register(r.o());
+    expect(retry.hook).toMatchObject({ state: 'written', required: false, retried: true });
+    fs.rmSync(path.join(r.profile, 'fake-allow'));
+    const fixed = register(r.o());
+    expect(fixed.hook).toMatchObject({ state: 'active', retried: true });
+    expect(readLedger(fixed.ledger)!.meta.hook_active).toBe('yes');
+    const sets = r.calls().filter(l => l.startsWith('config set')).length;
+    expect(register(r.o()).hook?.state).toBe('unchecked');
+    expect(r.calls().filter(l => l.startsWith('config set')).length).toBe(sets);
+
+    const s = rig('openclaw');
+    fs.writeFileSync(path.join(s.profile, 'fake-fail'), '');
+    expect(register(s.o({ startHook: true })).hook?.state).toBe('written');
+    fs.rmSync(path.join(s.profile, 'fake-fail'));
+    fs.appendFileSync(path.join(s.profile, 'fake-config'), 'plugins.entries.gstack-start.enabled=false\n');
+    const before = s.calls().filter(l => l.startsWith('config set')).length;
+    const left = register(s.o());
+    expect(left.hook).toMatchObject({ state: 'disabled', retried: true });
+    expect(readLedger(left.ledger)!.meta.hook_active).toBe('disabled');
+    register(s.o());
+    expect(s.calls().filter(l => l.startsWith('config set')).length).toBe(before);
+    expect(fs.readFileSync(path.join(s.profile, 'fake-config'), 'utf8')).toContain('enabled=false');
+  }, 300_000);
+});
+
+describe('start hook: Hermes lifecycle and the saved choice (fake CLI)', () => {
+  test('a one-run env opt-in is saved; config off then refresh turns it off; unregister removes the plugin through Hermes', () => {
+    const r = rig('hermes', { env: { GSTACK_HARNESS_START_HOOK: '1' } });
+    const on = register(r.o());
+    expect(on.hook?.state).toBe('active');
+    expect(r.calls().map(l => l.split('|')[0])).toEqual(['plugins enable gstack-start', 'plugins list --json']);
+
+    const env = { ...r.env }; delete (env as Record<string, string | undefined>).GSTACK_HARNESS_START_HOOK;
+    const kept = register({ ...r.o(), env });
+    expect(kept.hook?.state).toBe('unchecked');
+    expect(fs.existsSync(path.join(r.root, '__init__.py'))).toBe(true);
+
+    fs.writeFileSync(path.join(r.o().stateRoot, 'config.yaml'), 'harness_start_hook: off\n');
+    const off = register({ ...r.o(), env });
+    expect(off.hook?.state).toBe('off');
+    expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins remove gstack-start');
+    expect(fs.existsSync(path.join(r.profile, 'plugins'))).toBe(false);
+
+    fs.writeFileSync(path.join(r.o().stateRoot, 'config.yaml'), 'harness_start_hook: on\n');
+    const back = register({ ...r.o(), env });
+    expect(back.hook?.state).toBe('active');
+    fs.mkdirSync(path.join(r.root, '__pycache__'));
+    fs.writeFileSync(path.join(r.root, '__pycache__', '__init__.cpython-312.pyc'), 'x');
+    unregister(r.o().stateRoot, ROOT, 'hermes', env);
+    expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins remove gstack-start');
+    expect(fs.existsSync(path.join(r.profile, 'plugins'))).toBe(false);
+  }, 300_000);
+
+  test('bash-only uninstall: an edited plugin file is kept and Hermes only disables it; without Hermes on PATH it prints the command', () => {
+    const r = rig('hermes');
+    register(r.o({ startHook: true }));
+    fs.appendFileSync(path.join(r.root, 'note.txt'), 'my edit\n');
+    const ledgerSh = path.join(ROOT, 'bin', 'gstack-harness-ledger.sh');
+    const run = (PATH: string) => spawnSync('bash', ['-c', '. "$0" && gstack_harness_unregister_all', ledgerSh], { env: { PATH, HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 60_000 });
+    const res = run(r.bin + path.delimiter + '/usr/bin:/bin');
+    expect(res.status, res.stderr).toBe(0);
+    expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins disable gstack-start');
+    expect(fs.readdirSync(r.root).filter(f => f.startsWith('note.txt.edited-'))).toHaveLength(1);
+    expect(fs.existsSync(path.join(r.root, 'plugin.yaml'))).toBe(false);
+
+    const s = rig('hermes');
+    register(s.o({ startHook: true }));
+    const t = spawnSync('bash', ['-c', '. "$0" && gstack_harness_unregister_all', ledgerSh], { env: { PATH: '/usr/bin:/bin', HOME: path.join(s.d, 'home'), GSTACK_STATE_ROOT: path.join(s.d, 'state') }, encoding: 'utf8', timeout: 60_000 });
+    expect(t.status).toBe(0);
+    expect(t.stdout).toContain('start hook: turn it off in Hermes yourself: HERMES_HOME="' + s.profile + '" hermes plugins disable gstack-start');
+    expect(fs.existsSync(path.join(s.profile, 'plugins'))).toBe(false);
+  }, 300_000);
+});
+
+describe('start hook: teardown keeps what gstack did not write (fake CLI)', () => {
+  test('a kept copy of an edited Hermes plugin file survives unregister: Hermes only disables the plugin', () => {
+    const r = rig('hermes');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    fs.writeFileSync(path.join(r.root, 'note.txt'), 'my note\n');
+    const again = register(r.o());
+    expect(again.kept).toHaveLength(1);
+    unregister(r.o().stateRoot, ROOT, 'hermes', r.env);
+    expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins disable gstack-start');
+    expect(fs.readFileSync(again.kept[0], 'utf8')).toBe('my note\n');
+  }, 300_000);
+
+  test('a plugins folder swapped for a symlink after registration: off refuses, unregister deletes nothing through it', () => {
+    const r = rig('hermes');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    const elsewhere = path.join(r.d, 'elsewhere');
+    fs.renameSync(path.join(r.profile, 'plugins'), elsewhere);
+    fs.symlinkSync(elsewhere, path.join(r.profile, 'plugins'));
+    fs.writeFileSync(path.join(elsewhere, HOOK_ID, 'important.txt'), 'keep');
+    expect(() => register(r.o({ startHook: false }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' }));
+    unregister(r.o().stateRoot, ROOT, 'hermes', r.env);
+    expect(r.calls().some(l => l.startsWith('plugins remove'))).toBe(false);
+    expect(fs.readdirSync(path.join(elsewhere, HOOK_ID)).sort()).toEqual(['__init__.py', 'important.txt', 'note.txt', 'plugin.yaml']);
+  }, 300_000);
+
+  test.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('an opt-out that fails to delete the plugin files can be run again', () => {
+    const r = rig('openclaw');
+    const on = register(r.o({ startHook: true }));
+    expect(on.hook?.state).toBe('active');
+    fs.chmodSync(r.root, 0o555);
+    try {
+      expect(() => register(r.o({ startHook: false }))).toThrow(/EACCES/);
+      expect(readLedger(on.ledger)!.meta.hook_root).toBe(r.root);
+    } finally { fs.chmodSync(r.root, 0o755); }
+    const ext = path.join(r.profile, 'extensions'), moved = path.join(r.d, 'moved');
+    fs.renameSync(ext, moved);
+    fs.symlinkSync(moved, ext);
+    expect(() => register(r.o({ startHook: false }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' }));
+    expect(() => register({ ...r.o(), env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1' } })).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' }));
+    expect(fs.existsSync(path.join(moved, HOOK_ID, 'index.js'))).toBe(true);
+    fs.unlinkSync(ext);
+    fs.renameSync(moved, ext);
+    const off = register(r.o({ startHook: false }));
+    expect(off.hook?.state).toBe('off');
+    expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false);
+    expect(readLedger(off.ledger)!.meta.hook_root).toBeUndefined();
+  }, 300_000);
+
+  test('unregister leaves an empty plugin folder alone when the folder above it was swapped for a symlink', () => {
+    const r = rig('openclaw');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    const ext = path.join(r.profile, 'extensions'), elsewhere = path.join(r.d, 'elsewhere');
+    fs.renameSync(ext, path.join(r.d, 'old'));
+    fs.mkdirSync(path.join(elsewhere, HOOK_ID), { recursive: true });
+    fs.symlinkSync(elsewhere, ext);
+    unregister(r.o().stateRoot, ROOT, 'openclaw', r.env);
+    expect(fs.existsSync(path.join(elsewhere, HOOK_ID))).toBe(true);
+  }, 300_000);
+
+  test('a saved opt-in survives one run from a shell that sets OPENCLAW_CONFIG_PATH', () => {
+    const r = rig('openclaw');
+    expect(register(r.o({ startHook: true })).hook?.state).toBe('active');
+    const res = register({ ...r.o(), env: { ...r.env, OPENCLAW_CONFIG_PATH: '/elsewhere/openclaw.json' } });
+    expect(res.hook?.state).not.toBe('off');
+    expect(r.calls().some(l => l.startsWith('config unset'))).toBe(false);
+    expect(fs.existsSync(path.join(r.root, 'index.js'))).toBe(true);
+    expect(readLedger(res.ledger)!.meta.start_hook).toBe('on');
+  }, 300_000);
+});
+
+describe.skipIf(process.platform === 'win32')('start hook through ./setup --host', () => {
+  test('exits 4 with the skills registered when the hook does not turn on, and the next run retries it', () => {
+    const f = makeFixture();
+    const src = makeSource(f, path.join(f.dir, 'gstack'));
+    const bin = path.join(f.dir, 'fakebin');
+    fs.mkdirSync(bin);
+    fs.writeFileSync(path.join(bin, 'openclaw'), FAKE_OPENCLAW, { mode: 0o755 });
+    const profile = path.join(f.home, '.openclaw');
+    fs.mkdirSync(profile, { recursive: true });
+    fs.writeFileSync(path.join(profile, 'fake-fail'), '');
+    const PATH = bin + path.delimiter + f.env.PATH;
+    const first = runSetup(f, path.join(src, 'setup'), ['--host', 'openclaw'], { env: { PATH, GSTACK_HARNESS_START_HOOK: '1' } });
+    expect(first.status, first.stdout + first.stderr).toBe(4);
+    expect(first.stdout).toContain('start hook: written');
+    expect(first.stderr).toContain('(HARNESS_HOOK_INACTIVE; docs/troubleshooting.md#harness-hook-inactive)');
+    expect(fs.existsSync(path.join(profile, 'skills', 'gstack', 'SKILL.md'))).toBe(true);
+    expect(registryRows(f).map(row => row[0])).toEqual(['openclaw']);
+    const refreshed = runSetup(f, path.join(src, 'setup'), ['--refresh-registered'], { env: { PATH } });
+    expect(refreshed.status, refreshed.stdout + refreshed.stderr).toBe(0);
+    expect(refreshed.stdout + refreshed.stderr).toContain('start hook: written');
+    fs.rmSync(path.join(profile, 'fake-fail'));
+    const second = runSetup(f, path.join(src, 'setup'), ['--host', 'openclaw'], { env: { PATH } });
+    expect(second.status, second.stdout + second.stderr).toBe(0);
+    expect(second.stdout).toContain('start hook: active');
+  }, 180_000);
+});

From a2ce5bd8880e4ddab77e9656ff2a776082f31972 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 02:13:55 -0800
Subject: [PATCH 4/5] v1.92.24.0 fix(ship): finish accepts an owner-accepted
 documentation exception (GST-713) (#3776)

* fix(ship): base merges, adjacent base edits, test-only and audit-requested fixes no longer force a second review loop (GST-407, GST-384, GST-391)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* ship driver: trim two phrases for headroom with #3662

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* ship driver: keep the Next steps heading phrase the handoff check reads; trim elsewhere

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: regenerate ship goldens

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes

comparePath returns same only when every hunk sits where the base change puts it (patch-ids ignore positions) and treats a file-mode change as changed; the scoped-review packet says when a fence is truncated; --docs-result must be the posted audit's result; the --context-reviewed record goes beside the packet, outside the worktree. Negative controls for each.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pass-2 review fixes

A test edit routes as tests= only when it adds lines with no gate tag; a removed or changed line or an unreadable test diff goes through the full loop. Diffs skip textconv. A hunkless patch (binary, empty, mode-only) is same when its patch-id matches. Without --reviewed-base test files route as before. finish's packet path and attempt's state directory have fallbacks.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: Step 11 review fixes; a version-only stamp_files edit after review is release metadata (GBRA-251)

gateEditedPaths reads removed lines only inside hunks; carry refuses when a path listing fails; docs freshness stops on a failed listing; attempt counts an unreadable state file. releasePaths includes stamp_files paths whose edit is a version swap under stamp_patterns.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: no test edit skips review; guard packet writes; exclusive attempt state

A test-only edit with no gate tag gets the scoped fix-check of its test hunks instead of a lanes-only rerun. Packet write failures print a STOP or RECEIPT_CARRY_REFUSED. attempt's allowance uses an exclusive create.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: attempt prints gstack's install command; carry checks the product diff outside context paths

The attempt STOP no longer echoes the audit child's fix text. A scoped-review carry now requires the product patch-id without the context paths to match at both heads.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: oversized packets take the full loop; exact --docs-requested match; name-only test globs only in test dirs

A scoped-review packet section over 200 lines sends that path to the full loop instead of a truncated packet. The docs-result path match is exact. test_*.py, *Test.java and similar count as test code only under a test directory.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(unattended): carry's scoped-review refusal and what it keeps

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: carry's scoped-review route in ship-policy, review-policy and troubleshooting (docs-a-1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(windows): curate ship-rereview-triggers out of the Windows lane like ship-release (run 41193336209)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: restore bin/gstack-ship-receipt after the main merge

The merge commit b10e2db wrote a truncated copy of the file. This is the
three-way merge of both sides with the refused() union: main's codes plus
RECEIPT_CARRY_SCOPED_REVIEW.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): finish runs after an owner-accepted Step 14.5 documentation exception (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(ship): the exception match and every snapshot --exception refusal are covered (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): the exception snapshot uses the receipt's docs parser; finish also matches scope and stops on a corrupt docs-audit record (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: DOCS_AUDIT_BLOCKED names the --exception snapshot finish needs (GST-713)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* chore(changelog): drop #3684's fragment, already stamped into CHANGELOG.md on main

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 CHANGELOG.md                                  |   4 +
 VERSION                                       |   2 +-
 agents-digest/gstack-AGENTS.md                |   2 +-
 bin/gstack-docs-candidate                     |  25 +++-
 docs/troubleshooting.md                       |   5 +-
 lib/ship-release.ts                           |  24 +++-
 package.json                                  |   2 +-
 ship/sections/documentation.md                |   4 +-
 ship/sections/documentation.md.tmpl           |   4 +-
 test/ship-release-docs-exception.test.ts      | 119 ++++++++++++++++++
 .../ship/gst-713-docs-exception-finish.json   |   4 +
 11 files changed, 184 insertions(+), 11 deletions(-)
 create mode 100644 test/ship-release-docs-exception.test.ts
 create mode 100644 test/size-ledger/ship/gst-713-docs-exception-finish.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b27a46ad..d86a59838 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.92.24.0] - 2026-11-01
+
+- `/ship` can finish after the owner accepts a Step 14.5 documentation risk. `gstack-docs-candidate snapshot --exception .gstack/tmp/docs-audit.json` writes the post-audit snapshot from the blocked record, naming who accepted it, the date, how and the base SHA, and `gstack-ship-release finish` prints that exception on its `DOCS:` line. Finish still stops on a blocked audit with no accepted exception, and on an exception snapshot whose docs-audit record no longer carries it (GST-713).
+
 ## [1.92.23.0] - 2026-11-01
 
 - **OpenClaw and Hermes: opt-in start hook.** `gstack-harness register openclaw|hermes --start-hook` (or `gstack-config set harness_start_hook on`, or `GSTACK_HARNESS_START_HOOK=1`) adds a `gstack-start` plugin that puts a one-line note on every user turn telling the agent to run a gstack skill's start command as written. Agents in these harnesses read gstack's skills but ran that command on 1 of 29 chances. gstack turns the plugin on through each harness's own CLI, checks that it is active, and exits 4 when it is not. It is off by default, the choice is saved across upgrades, a plugin you disable in the harness stays off, and `--no-start-hook`, unregister and uninstall take it out. See docs/hosts.md#start-hook.
diff --git a/VERSION b/VERSION
index ee815512e..0718912ee 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.92.23.0
+1.92.24.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index aacc58cd9..3b982c202 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.92.23.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.92.24.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/bin/gstack-docs-candidate b/bin/gstack-docs-candidate
index a5728877f..517541019 100755
--- a/bin/gstack-docs-candidate
+++ b/bin/gstack-docs-candidate
@@ -4,7 +4,7 @@
  *
  * Usage (run inside the repository):
  *   gstack-docs-candidate snapshot --out <candidate.json> --audit-id <id> --mode edit|read-only
- *                                  --base <rev> [--select <path>]... [--docs <path>]...
+ *                                  --base <rev> [--select <path>]... [--docs <path>]... [--exception <docs-audit.json>]
  *   gstack-docs-candidate compare <candidate.json>
  *   gstack-docs-candidate attempt <child-output> --state <attempts.json>
  *   gstack-docs-candidate [snapshot|compare] --help
@@ -16,6 +16,9 @@
  * selected paths are the committed, staged, unstaged and untracked paths.
  * --docs takes files or directories (directories expand to their tracked and
  * untracked files). It prints a short summary; the JSON file is the record.
+ * --exception names the blocked .gstack/tmp/docs-audit.json an owner accepted
+ * (Step 14.5 Blocked recovery): the record then carries that exception, so
+ * Step 16 can tell an accepted risk from a skipped audit.
  *
  * compare re-reads the same state and prints one JSON object: whether HEAD or
  * the index changed, which recorded paths' content changed or disappeared, and
@@ -32,6 +35,7 @@
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { parseReceiptDocs, type ReceiptDocs } from '../lib/ship-receipt-docs';
 
 function git(args: string[]): string {
   const r = spawnSync('git', args, { encoding: 'utf8', env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' }, maxBuffer: 256 * 1024 * 1024 });
@@ -90,10 +94,20 @@ function one(args: string[], name: string): string {
   return values[0]!;
 }
 
-const USAGE = `usage: gstack-docs-candidate snapshot --out <candidate.json> --audit-id <id> --mode edit|read-only --base <rev> [--select <path>]... [--docs <path>]...
+const USAGE = `usage: gstack-docs-candidate snapshot --out <candidate.json> --audit-id <id> --mode edit|read-only --base <rev> [--select <path>]... [--docs <path>]... [--exception <docs-audit.json>]
        gstack-docs-candidate compare <candidate.json>
        gstack-docs-candidate attempt <child-output> --state <attempts.json>`;
 
+/** The owner's accepted Step 14.5 exception from the blocked .gstack/tmp/docs-audit.json record, read by the receipt's own parser; throws when the record is not blocked or names no complete exception. */
+function acceptedException(file: string): NonNullable<ReceiptDocs['exception']> & { scope: string } {
+  let audit: unknown;
+  try { audit = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { throw new Error(`--exception ${file} is not readable JSON: ${(error as Error).message}`); }
+  const parsed = parseReceiptDocs(audit);
+  const problem = !parsed.ok ? parsed.message : parsed.docs.status !== 'blocked' ? `its status is ${parsed.docs.status}, not blocked` : !parsed.docs.exception ? 'it names no accepted exception' : null;
+  if (problem || !parsed.ok || !parsed.docs.exception) throw new Error(`--exception ${file}: ${problem}. Only an owner-accepted documentation risk writes this snapshot (ship/sections/documentation.md, Blocked recovery step 3)`);
+  return { ...parsed.docs.exception, scope: parsed.docs.scope };
+}
+
 /** Each field compare needs that the record lacks or types wrongly; empty for a valid record. */
 function recordProblems(record: any): string[] {
   if (!record || typeof record !== 'object' || Array.isArray(record)) return ['not a JSON object'];
@@ -113,7 +127,7 @@ function main(argv: string[]): void {
     return;
   }
   if (command === 'snapshot') {
-    const known = new Set(['--out', '--audit-id', '--mode', '--base', '--select', '--docs']);
+    const known = new Set(['--out', '--audit-id', '--mode', '--base', '--select', '--docs', '--exception']);
     for (let i = 0; i < args.length; i += 2) if (!known.has(args[i]!)) throw new Error(`unknown argument: ${args[i]}`);
     const out = path.resolve(one(args, '--out'));
     const top = fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim());
@@ -121,6 +135,8 @@ function main(argv: string[]): void {
     const mode = one(args, '--mode');
     if (mode !== 'edit' && mode !== 'read-only') throw new Error('--mode must be edit or read-only');
     const base = git(['rev-parse', '--verify', one(args, '--base') + '^{commit}']).trim();
+    const exceptionFile = flag(args, '--exception')[0];
+    const exception = exceptionFile === undefined ? undefined : acceptedException(exceptionFile);
     process.chdir(top);
     const now = state(base);
     const listed = nul(git(['ls-files', '-z', '--cached', '--others', '--exclude-standard']));
@@ -128,10 +144,11 @@ function main(argv: string[]): void {
       : [...new Set([...now.committed, ...now.staged, ...now.unstaged, ...now.untracked])].sort();
     const docs = expand(listed, flag(args, '--docs'));
     const tracked = [...new Set([...selected, ...docs, ...now.staged, ...now.unstaged, ...now.untracked])].sort();
-    const record = { schema_version: 1, audit_id: one(args, '--audit-id'), mode, base, ...now, selected, docs, hashes: hashes(tracked) };
+    const record = { schema_version: 1, audit_id: one(args, '--audit-id'), mode, base, ...now, selected, docs, hashes: hashes(tracked), ...(exception ? { exception } : {}) };
     fs.writeFileSync(out, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
     console.log(`CANDIDATE: ${out}`);
     console.log(`base=${base} head=${now.head} branch=${now.branch || '(detached)'} mode=${mode}`);
+    if (exception) console.log(`EXCEPTION: accepted by ${exception.accepted_by} ${exception.date} via ${exception.via}`);
     console.log(`committed=${now.committed.length} staged=${now.staged.length} unstaged=${now.unstaged.length} untracked=${now.untracked.length} selected=${selected.length} docs=${docs.length} hashed=${tracked.length}`);
     for (const [label, list] of [['committed', now.committed], ['staged', now.staged], ['unstaged', now.unstaged], ['untracked', now.untracked], ['docs', docs]] as const) {
       if (list.length) console.log(`${label}: ${list.map(p => JSON.stringify(p)).join(' ')}`);
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index c5cdb50ef..2fb72daf8 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -5661,7 +5661,10 @@ over` line names (or raise its cap on the base branch). When the owner accepts
 the named risk instead, record it as `docs.exception: { accepted_by, date, via,
 reason }` and carry the `Documentation exception: accepted by <owner> <date> via
 <ref>: <reason>` line in the PR body's `## Documentation` section, word for word
-([ship-policy.md](ship-policy.md#ship-receipt)).
+([ship-policy.md](ship-policy.md#ship-receipt)). Then save the post-audit snapshot with
+`gstack-docs-candidate snapshot --exception .gstack/tmp/docs-audit.json`;
+`gstack-ship-release finish` stops on a blocked audit whose snapshot lacks the
+exception.
 <a id="gstack-pr-wait"></a>
 ## gstack-pr-wait
 
diff --git a/lib/ship-release.ts b/lib/ship-release.ts
index b8509cd04..b6e517d91 100644
--- a/lib/ship-release.ts
+++ b/lib/ship-release.ts
@@ -13,6 +13,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { classifyPath } from './review-depth';
 import { comparePath, contextPacket, gateEditedPaths, isTestCode, PACKET_SECTION_CAP, readScopedReview, touchedPaths, type PatchSides } from './ship-patch';
+import { parseReceiptDocs, type ReceiptDocs } from './ship-receipt-docs';
 import { resolveStateRoot } from './state-root';
 import { bumpVersion, cmpVersion, fmtVersion, parseVersion, versionWidth, type Bump } from './version-source';
 import { bin, evidenceExempt, firstLine, flagReader, fragmentPath, gh, git, hostedOrigin, laneLine, lanes, releasePaths, Report, runLanes, sh, shipPolicy, short, stampedFiles } from './ship-bin-common';
@@ -223,6 +224,26 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly
   try { stale = JSON.parse(cmp.stdout).content_changed; } catch { stale = null; }
   if (stale === null) { r.stop(`gstack-docs-candidate compare failed: ${firstLine(cmp.stderr)}; documentation freshness is unknown (stage 3)`); return false; }
   const record = JSON.parse(fs.readFileSync(postFile, 'utf8'));
+  const auditFile = path.join(cwd, '.gstack/tmp/docs-audit.json');
+  let docsAudit: ReceiptDocs | null = null;
+  if (fs.existsSync(auditFile)) {
+    let raw: unknown;
+    try { raw = JSON.parse(fs.readFileSync(auditFile, 'utf8')); } catch { raw = undefined; }
+    const parsed = parseReceiptDocs(raw);
+    if (!parsed.ok) { r.stop(`.gstack/tmp/docs-audit.json: ${parsed.message}; documentation status is unknown (stage 3)`); return false; }
+    docsAudit = parsed.docs;
+  }
+  const accepted = docsAudit?.exception;
+  if (accepted || record.exception) {
+    const same = !!accepted && !!record.exception && docsAudit!.status === 'blocked' && record.exception.scope === docsAudit!.scope
+      && (['accepted_by', 'date', 'via', 'reason'] as const).every(k => record.exception[k] === accepted[k]);
+    if (!same) {
+      r.stop(accepted
+        ? `the Step 14.5 audit is blocked and ${postFile} names no matching owner-accepted exception: snapshot with --exception .gstack/tmp/docs-audit.json (documentation.md Blocked recovery step 3)`
+        : `${postFile} names a documentation exception but .gstack/tmp/docs-audit.json is not the blocked record carrying it: rerun Step 14.5`);
+      return false;
+    }
+  }
   const baseRef = `origin/${base.replace(/^origin\//, '')}`;
   const nul = (out: string) => out.split('\0').filter(Boolean);
   const auditBase = git(cwd, ['merge-base', baseRef, record.head]).stdout.trim();
@@ -252,7 +273,8 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly
   if (carried.requested.length && bin(cwd, 'gstack-ship-receipt', ['docs-caps', '--base', base], 60_000).status !== 0) { r.stop('a --docs-requested fix breaks a doc cap (gstack-ship-receipt docs-caps): trim the file, then rerun finish'); return false; }
   const left = stale.filter(p => !carried.tests.includes(p) && !carried.base.includes(p) && !carried.requested.includes(p));
   const note = left.length || stale.length === 0 ? '' : ` (carried: tests=${carried.tests.length} base=${carried.base.length} requested=${carried.requested.length})`;
-  r.add(`DOCS: ${left.length ? `stale (${short(left)})` : `fresh against the Step 14.5 post-audit snapshot${note}`}`);
+  const exception = record.exception ? ` (blocked; documentation exception accepted by ${record.exception.accepted_by} ${record.exception.date} via ${record.exception.via})` : '';
+  r.add(`DOCS: ${left.length ? `stale (${short(left)})` : `fresh against the Step 14.5 post-audit snapshot${note}${exception}`}`);
   if (left.length) { r.stop('documentation inputs changed since the accepted audit: use stage 3 recovery (the remaining re-audit, a fix the audit\'s result asked for via --docs-requested <path> --docs-result <audit-id>-result.json, or a named risk); never refresh hashes'); return false; }
   return true;
 }
diff --git a/package.json b/package.json
index aee1fd8cb..fb5050636 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.92.23",
+  "version": "1.92.24",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/ship/sections/documentation.md b/ship/sections/documentation.md
index 0c967b862..70dea163c 100644
--- a/ship/sections/documentation.md
+++ b/ship/sections/documentation.md
@@ -137,4 +137,6 @@ auto-commit or push unexpected child commits.
    `.gstack/tmp/docs-audit.json` as `{"status":"blocked","scope":"<scope>","exception":{"accepted_by":"<owner>","date":"<YYYY-MM-DD>","via":"<their reply or review reference>","reason":"<their words, one line>"}}`;
    the PR body's Documentation section repeats it word for word, and
    `gstack-ship-receipt write --docs` refuses a blocked record without one
-   (`DOCS_AUDIT_BLOCKED`). An unattended run has no owner to accept: it stops here.
+   (`DOCS_AUDIT_BLOCKED`). Then save Step 16's post snapshot from it: the Prepare
+   `snapshot` with `--out <audit-id>-post.json --exception .gstack/tmp/docs-audit.json`;
+   finish refuses a blocked audit whose post snapshot lacks it. An unattended run has no owner to accept: it stops here.
diff --git a/ship/sections/documentation.md.tmpl b/ship/sections/documentation.md.tmpl
index 781f262d3..eb77f9f03 100644
--- a/ship/sections/documentation.md.tmpl
+++ b/ship/sections/documentation.md.tmpl
@@ -135,4 +135,6 @@ auto-commit or push unexpected child commits.
    `.gstack/tmp/docs-audit.json` as `{"status":"blocked","scope":"<scope>","exception":{"accepted_by":"<owner>","date":"<YYYY-MM-DD>","via":"<their reply or review reference>","reason":"<their words, one line>"}}`;
    the PR body's Documentation section repeats it word for word, and
    `gstack-ship-receipt write --docs` refuses a blocked record without one
-   (`DOCS_AUDIT_BLOCKED`). An unattended run has no owner to accept: it stops here.
+   (`DOCS_AUDIT_BLOCKED`). Then save Step 16's post snapshot from it: the Prepare
+   `snapshot` with `--out <audit-id>-post.json --exception .gstack/tmp/docs-audit.json`;
+   finish refuses a blocked audit whose post snapshot lacks it. An unattended run has no owner to accept: it stops here.
diff --git a/test/ship-release-docs-exception.test.ts b/test/ship-release-docs-exception.test.ts
new file mode 100644
index 000000000..90142901e
--- /dev/null
+++ b/test/ship-release-docs-exception.test.ts
@@ -0,0 +1,119 @@
+/**
+ * gstack-ship-release finish after an owner-accepted Step 14.5 documentation exception (GST-713, GEVA-84): the audit
+ * reader was skipped, so no post-audit snapshot existed and finish refused for want of a gstack-docs-candidate record.
+ * The accepted exception now writes that record (gstack-docs-candidate snapshot --exception), and finish accepts it only
+ * when it matches the blocked docs-audit.json the owner's answer was written into.
+ */
+import { afterEach, describe, expect, setDefaultTimeout, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { lineOf, shipFixture, type ShipFx } from './helpers/ship-bin-fixture';
+
+setDefaultTimeout(120_000);
+const RELEASE = path.join(import.meta.dir, '..', 'bin', 'gstack-ship-release');
+const CANDIDATE = path.join(import.meta.dir, '..', 'bin', 'gstack-docs-candidate');
+const WTREE = path.join(import.meta.dir, '..', 'bin', 'gstack-wtree');
+const fixtures: ShipFx[] = [];
+afterEach(() => { while (fixtures.length) fixtures.pop()!.cleanup(); });
+const LANE = 'tests=printf " 3 pass\\n 0 fail\\nRan 3 tests across 1 file. [5.00ms]\\n"';
+const EXCEPTION = { accepted_by: 'Garry', date: '2026-10-31', via: 'GStack Minder relay', reason: 'ship with the docs audit skipped' };
+
+/** A branch at Step 16 whose Step 14.5 audit is blocked: the run's .gstack/tmp exclude and docs-audit.json, the reviewed tree. */
+function blockedAudit(audit: object): { f: ShipFx; reviewed: string } {
+  const f = shipFixture(); fixtures.push(f);
+  fs.appendFileSync(path.join(f.work, '.git', 'info', 'exclude'), '/.gstack/tmp/\n');
+  f.write({ '.gstack/tmp/docs-audit.json': JSON.stringify(audit) + '\n' });
+  const reviewed = f.run(WTREE, []).stdout.trim();
+  expect(f.run(RELEASE, ['version', '--base', 'main', '--bump', 'micro']).status).toBe(0);
+  return { f, reviewed };
+}
+const snapshot = (f: ShipFx, extra: string[] = []) => {
+  const out = path.join(f.root, 'post.json');
+  return { out, r: f.run(CANDIDATE, ['snapshot', '--out', out, '--audit-id', 'a1', '--mode', 'edit', '--base', 'main', '--docs', 'README.md', ...extra]) };
+};
+
+describe('finish after an accepted documentation exception (GST-713)', () => {
+  // Value: protects=an owner-accepted Step 14.5 risk lets finish run, and the record names who accepted it and the base;
+  //   fails_when=finish needs a docs-candidate record only the skipped reader writes, so an accepted exception can never finish;
+  //   why_new=GEVA-84 hit it on gstack-evals#102; seam=gstack-docs-candidate snapshot --exception; no_claim=the PR body's exception line
+  test('the exception snapshot names the owner and base, and finish passes with the exception on its DOCS line', () => {
+    const { f, reviewed } = blockedAudit({ status: 'blocked', scope: 'README.md', exception: EXCEPTION });
+    const s = snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']);
+    expect(s.r.status, s.r.stderr).toBe(0);
+    expect(s.r.stdout).toContain('EXCEPTION: accepted by Garry 2026-10-31 via GStack Minder relay');
+    const record = JSON.parse(fs.readFileSync(s.out, 'utf8'));
+    expect([record.schema_version, record.base, record.exception]).toEqual([1, f.git('rev-parse', 'main').stdout.trim(), { ...EXCEPTION, scope: 'README.md' }]);
+    const ok = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', s.out, '--lane', LANE]);
+    expect(lineOf(ok.stdout, 'DOCS')).toBe('DOCS: fresh against the Step 14.5 post-audit snapshot (blocked; documentation exception accepted by Garry 2026-10-31 via GStack Minder relay)');
+    expect([ok.status, ok.stdout.split('\n').find(l => l.startsWith('STOP:'))]).toEqual([0, undefined]);
+  });
+
+  // Value: protects=finish never passes a blocked audit nobody accepted; fails_when=a blocked record with no exception, or a plain
+  //   snapshot taken over a blocked audit, gets past stage 3; seam=gstack-docs-candidate snapshot, finish stage 3; no_claim=who may accept
+  test('no accepted exception: the exception snapshot refuses, and a plain snapshot over a blocked audit stops finish', () => {
+    const { f, reviewed } = blockedAudit({ status: 'blocked', scope: 'README.md' });
+    const refused = snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']);
+    expect(refused.r.status).not.toBe(0);
+    expect(refused.r.stderr).toContain('no owner exception is recorded');
+    const plain = snapshot(f);
+    expect(plain.r.status).toBe(0);
+    const stop = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', plain.out, '--lane', LANE]);
+    expect(stop.status).toBe(3);
+    expect(stop.stdout).toContain('STOP: .gstack/tmp/docs-audit.json: the documentation audit is blocked (README.md) and no owner exception is recorded');
+  });
+
+  // Value: protects=an exception record cannot be reused after the docs-audit record changes; fails_when=finish trusts the snapshot's
+  //   exception without the blocked docs-audit.json carrying the same one; seam=finish stage 3; no_claim=receipt docs field
+  test('an exception snapshot whose docs-audit.json no longer carries it stops finish', () => {
+    const { f, reviewed } = blockedAudit({ status: 'blocked', scope: 'README.md', exception: EXCEPTION });
+    const s = snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']);
+    expect(s.r.status).toBe(0);
+    f.write({ '.gstack/tmp/docs-audit.json': JSON.stringify({ status: 'current', scope: 'README.md' }) + '\n' });
+    const stop = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', s.out, '--lane', LANE]);
+    expect(stop.status).toBe(3);
+    expect(stop.stdout).toContain('names a documentation exception but .gstack/tmp/docs-audit.json is not the blocked record carrying it');
+  });
+
+  // Value: protects=finish matches the snapshot's exception to the blocked record field by field; fails_when=any blocked record
+  //   with any exception passes, so another owner's or an edited answer finishes; seam=finish stage 3; no_claim=receipt docs field
+  test('a blocked audit carrying a different exception than the snapshot stops finish', () => {
+    const { f, reviewed } = blockedAudit({ status: 'blocked', scope: 'README.md', exception: EXCEPTION });
+    expect(snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']).r.status).toBe(0);
+    f.write({ '.gstack/tmp/docs-audit.json': JSON.stringify({ status: 'blocked', scope: 'README.md', exception: { ...EXCEPTION, accepted_by: 'Someone else' } }) + '\n' });
+    const stop = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', path.join(f.root, 'post.json'), '--lane', LANE]);
+    expect(stop.status).toBe(3);
+    expect(stop.stdout).toContain('names no matching owner-accepted exception');
+  });
+
+  // Value: protects=finish stops on a docs-audit.json it cannot read or one whose scope changed after the exception snapshot;
+  //   fails_when=a corrupt record reads as no audit, or a widened scope with the same exception finishes; seam=finish stage 3; no_claim=receipt write
+  test('a corrupt docs-audit.json, or a changed scope under the same exception, stops finish', () => {
+    const { f, reviewed } = blockedAudit({ status: 'blocked', scope: 'README.md', exception: EXCEPTION });
+    expect(snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']).r.status).toBe(0);
+    const post = path.join(f.root, 'post.json');
+    f.write({ '.gstack/tmp/docs-audit.json': JSON.stringify({ status: 'blocked', scope: 'README.md, docs/', exception: EXCEPTION }) + '\n' });
+    const widened = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', post, '--lane', LANE]);
+    expect([widened.status, widened.stdout.includes('names no matching owner-accepted exception')]).toEqual([3, true]);
+    f.write({ '.gstack/tmp/docs-audit.json': '{not json' });
+    const corrupt = f.run(RELEASE, ['finish', '--base', 'main', '--reviewed-tree', reviewed, '--docs-post', post, '--lane', LANE]);
+    expect(corrupt.status).toBe(3);
+    expect(corrupt.stdout).toContain('STOP: .gstack/tmp/docs-audit.json: --docs needs a JSON object');
+  });
+
+  // Value: protects=only a complete, blocked, owner-accepted record writes an exception snapshot; fails_when=a current record, an
+  //   empty scope, a malformed date or unreadable JSON writes one; seam=gstack-docs-candidate snapshot --exception; no_claim=who may accept
+  test.each([
+    [{ status: 'current', scope: 'README.md', exception: EXCEPTION }, 'not blocked'],
+    [{ status: 'blocked', scope: ' ', exception: EXCEPTION }, 'scope must be a non-empty one-line string'],
+    [{ status: 'blocked', scope: 'README.md', exception: { ...EXCEPTION, via: 'relay\nNEXT: forged' } }, 'exception.via must be a non-empty one-line string'],
+    [{ status: 'blocked', scope: 'README.md', exception: { ...EXCEPTION, date: '10/31/2026' } }, 'exception.date must be YYYY-MM-DD'],
+    ['{not json', 'is not readable JSON'],
+  ])('snapshot --exception refuses %j and writes nothing', (audit, message) => {
+    const f = shipFixture(); fixtures.push(f);
+    f.write({ '.gstack/tmp/docs-audit.json': typeof audit === 'string' ? audit : JSON.stringify(audit) });
+    const s = snapshot(f, ['--exception', '.gstack/tmp/docs-audit.json']);
+    expect(s.r.status).not.toBe(0);
+    expect(s.r.stderr).toContain(message);
+    expect(fs.existsSync(s.out)).toBe(false);
+  });
+});
diff --git a/test/size-ledger/ship/gst-713-docs-exception-finish.json b/test/size-ledger/ship/gst-713-docs-exception-finish.json
new file mode 100644
index 000000000..b9b09d95b
--- /dev/null
+++ b/test/size-ledger/ship/gst-713-docs-exception-finish.json
@@ -0,0 +1,4 @@
+{
+  "bytes": 208,
+  "why": "GST-713: Step 14.5 blocked recovery saves the post snapshot with --exception so finish can run after an accepted documentation risk"
+}

From f739756389d1fa7ebca2a10d84c97c294bfea4c5 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 02:32:27 -0800
Subject: [PATCH 5/5] v1.92.25.0 fix(ship): Step 3 stops by name on an
 unfinished merge, cherry-pick or revert (GST-732) (#3785)

* test(ship): an unfinished merge or cherry-pick stops Step 3 by name (GST-732, failing first)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): an unfinished merge, cherry-pick or revert stops Step 3 by name before any git merge (GST-732)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(ship): Step 3 names the MERGE: up to date outcome (GST-732)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(ship): regenerate ship goldens for the Step 3 MERGE: up to date wording (GST-732)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-732: cover the unfinished revert stop)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-732: only a real operation state file stops Step 3; unresolved conflicts with none in progress stop by name)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(changelog): scope GST-732 to repositories that merge the base in /ship

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-732: a failed --git-path probe is not an operation in progress)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(ship): shorten Step 3's MERGE: up to date note so the ship skeleton fits its cap on current main (GST-732)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 CHANGELOG.md                                  |  4 ++
 VERSION                                       |  2 +-
 agents-digest/gstack-AGENTS.md                |  2 +-
 lib/ship-preflight.ts                         | 19 ++++++--
 package.json                                  |  2 +-
 ship/SKILL.md                                 |  2 +-
 ship/SKILL.md.tmpl                            |  2 +-
 test/fixtures/golden/agy-ship-SKILL.md        |  2 +-
 test/fixtures/golden/claude-ship-SKILL.md     |  2 +-
 test/fixtures/golden/codex-ship-SKILL.md      |  2 +-
 test/fixtures/golden/factory-ship-SKILL.md    |  2 +-
 test/ship-preflight-base-ancestor.test.ts     | 47 ++++++++++++++-----
 .../ship/gst-732-preflight-unfinished-op.json |  4 ++
 13 files changed, 69 insertions(+), 23 deletions(-)
 create mode 100644 test/size-ledger/ship/gst-732-preflight-unfinished-op.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d86a59838..56e4c4786 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.92.25.0] - 2026-11-01
+
+- In a repository that merges the base during `/ship` (any `queue_mode` but `stamp-at-merge`), Step 3 now stops by name when an earlier merge, cherry-pick or revert is still unfinished (`STOP: an unfinished cherry-pick is in progress (CHERRY_PICK_HEAD): …`), with any conflicted files listed, and runs no `git merge`. Conflicted files left with no operation in progress, as after a conflicted `git stash pop`, stop with those files named instead of a merge message. Before, both fell through to `git merge`, so on a machine whose shared-tree guard refuses `git merge`, the guard's refusal was the only message (GST-732). A branch or tag named `MERGE_HEAD`, `CHERRY_PICK_HEAD` or `REVERT_HEAD` is not mistaken for one. The ship skill's Step 3 now names the `MERGE: up to date` outcome.
+
 ## [1.92.24.0] - 2026-11-01
 
 - `/ship` can finish after the owner accepts a Step 14.5 documentation risk. `gstack-docs-candidate snapshot --exception .gstack/tmp/docs-audit.json` writes the post-audit snapshot from the blocked record, naming who accepted it, the date, how and the base SHA, and `gstack-ship-release finish` prints that exception on its `DOCS:` line. Finish still stops on a blocked audit with no accepted exception, and on an exception snapshot whose docs-audit record no longer carries it (GST-713).
diff --git a/VERSION b/VERSION
index 0718912ee..798807a15 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.92.24.0
+1.92.25.0
diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md
index 3b982c202..c5c0f56f7 100644
--- a/agents-digest/gstack-AGENTS.md
+++ b/agents-digest/gstack-AGENTS.md
@@ -1,4 +1,4 @@
-# gstack digest v1.92.24.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.92.25.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,
diff --git a/lib/ship-preflight.ts b/lib/ship-preflight.ts
index 487dc0a74..dd1f51d5e 100644
--- a/lib/ship-preflight.ts
+++ b/lib/ship-preflight.ts
@@ -67,9 +67,22 @@ const forkPoint = (cwd: string, base: string) => git(cwd, ['merge-base', `origin
 
 function merge(cwd: string, base: string, r: Report): boolean {
   const policy = shipPolicy(cwd, base);
-  if (policy?.queue_mode === 'stamp-at-merge') r.add('MERGE: skipped (queue_mode stamp-at-merge: the slot stamp merges the base; docs/ship-policy.md#ship-before-ready)');
-  else if (!git(cwd, ['ls-files', '-u']).stdout.trim() && ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD'].every(ref => git(cwd, ['rev-parse', '-q', '--verify', ref]).status !== 0)
-    && git(cwd, ['merge-base', '--is-ancestor', `origin/${base}`, 'HEAD']).status === 0) r.add('MERGE: up to date');
+  const stampAtMerge = policy?.queue_mode === 'stamp-at-merge';
+  const pending = stampAtMerge ? undefined : ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD'].find(ref => {
+    const p = git(cwd, ['rev-parse', '--git-path', ref]);
+    return p.status === 0 && !!p.stdout.trim() && fs.existsSync(path.resolve(cwd, p.stdout.trim()));
+  });
+  const unmerged = stampAtMerge ? [] : git(cwd, ['diff', '--name-only', '--diff-filter=U']).stdout.split('\n').filter(Boolean);
+  if (pending) {
+    r.stop(`an unfinished ${pending.replace(/_HEAD$/, '').toLowerCase().replace('_', '-')} is in progress (${pending}${unmerged.length ? `, conflicts in ${short(unmerged, 8)}` : ''}): resolve and commit it, or abort it, then rerun (Step 3)`);
+    return false;
+  }
+  if (unmerged.length) {
+    r.stop(`unresolved conflicts in ${short(unmerged, 8)} with no merge, cherry-pick or revert in progress: resolve them (git add) or restore the files, then rerun (Step 3)`);
+    return false;
+  }
+  if (stampAtMerge) r.add('MERGE: skipped (queue_mode stamp-at-merge: the slot stamp merges the base; docs/ship-policy.md#ship-before-ready)');
+  else if (git(cwd, ['merge-base', '--is-ancestor', `origin/${base}`, 'HEAD']).status === 0) r.add('MERGE: up to date');
   else {
     const before = git(cwd, ['rev-parse', 'HEAD']).stdout.trim();
     const m = git(cwd, ['merge', `origin/${base}`, '--no-edit'], 300_000);
diff --git a/package.json b/package.json
index fb5050636..61d7434c0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.92.24",
+  "version": "1.92.25",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/ship/SKILL.md b/ship/SKILL.md
index 76c60c15c..32de83e7d 100644
--- a/ship/SKILL.md
+++ b/ship/SKILL.md
@@ -455,7 +455,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl
index f1dbb34ae..4b9491940 100644
--- a/ship/SKILL.md.tmpl
+++ b/ship/SKILL.md.tmpl
@@ -185,7 +185,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/test/fixtures/golden/agy-ship-SKILL.md b/test/fixtures/golden/agy-ship-SKILL.md
index df7239269..b3aa51ef4 100644
--- a/test/fixtures/golden/agy-ship-SKILL.md
+++ b/test/fixtures/golden/agy-ship-SKILL.md
@@ -455,7 +455,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/test/fixtures/golden/claude-ship-SKILL.md b/test/fixtures/golden/claude-ship-SKILL.md
index 76c60c15c..32de83e7d 100644
--- a/test/fixtures/golden/claude-ship-SKILL.md
+++ b/test/fixtures/golden/claude-ship-SKILL.md
@@ -455,7 +455,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md
index 4fdb09da6..e3b16338d 100644
--- a/test/fixtures/golden/codex-ship-SKILL.md
+++ b/test/fixtures/golden/codex-ship-SKILL.md
@@ -454,7 +454,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md
index bc3b84109..148a7b6fb 100644
--- a/test/fixtures/golden/factory-ship-SKILL.md
+++ b/test/fixtures/golden/factory-ship-SKILL.md
@@ -456,7 +456,7 @@ not web services already deployed.
 
 ## Step 3: Merge the base branch (BEFORE tests)
 
-The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `skipped` under stamp-at-merge).
+The preflight merges the fetched base (`git merge`) so tests and reviews cover the integrated code (`MERGE:`; `up to date` if nothing new; `skipped` under stamp-at-merge).
 
 **Merge conflicts:** `MERGE:` names them. Auto-resolve simple ones (VERSION, schema.rb, CHANGELOG ordering). For complex or ambiguous conflicts, **STOP**, show the conflicting choices, use AskUserQuestion for the resolution, and wait for the answer before editing or continuing; then commit and rerun the preflight.
 
diff --git a/test/ship-preflight-base-ancestor.test.ts b/test/ship-preflight-base-ancestor.test.ts
index 1e7fdd3c5..8920c63e9 100644
--- a/test/ship-preflight-base-ancestor.test.ts
+++ b/test/ship-preflight-base-ancestor.test.ts
@@ -44,20 +44,45 @@ describe('preflight merge when the base is already in HEAD (GST-691)', () => {
     expect(r.stdout).toContain('STOP: git merge origin/main failed: shared-tree guard: git merge is not allowed in this checkout');
   });
 
-  // Value: protects=an unfinished merge of another branch still stops at Step 3 with its conflicted files named, though the base is in HEAD;
-  //   fails_when=the ancestor shortcut reports up to date over an index with unmerged paths and the run tests conflict markers;
-  //   why_new=GST-691 /ship adversarial finding 1; seam=git ls-files -u; no_claim=how the agent resolves it
-  test('an unfinished merge with the base already in HEAD still stops, conflicted or resolved and staged', () => {
-    const { f } = guarded();
+  // Value: protects=an unfinished merge, cherry-pick or revert stops at Step 3 with its name and conflicted files, though the base is in HEAD, and no git merge runs;
+  //   fails_when=the ancestor shortcut reports up to date over one, or the stop is a guard's refusal that names no cause;
+  //   why_new=GST-691 /ship adversarial findings; seam=MERGE_HEAD/CHERRY_PICK_HEAD/REVERT_HEAD; no_claim=how the agent resolves it
+  test('an unfinished merge, cherry-pick or revert with the base already in HEAD stops and names it, conflicted or resolved', () => {
+    const { f, merges } = guarded();
     f.git('checkout', '-q', '-b', 'other', 'main'); f.write({ 'src/a.ts': 'export const a = 5;\n' }); f.commit('other edits a');
     f.git('checkout', '-q', 'feat'); f.write({ 'src/a.ts': 'export const a = 6;\n' }); f.commit('feat edits a');
     expect(f.git('merge', '--no-edit', 'other').status).not.toBe(0);
-    const r = f.run(PREFLIGHT, ['--base', 'main']);
-    expect([r.status, lineOf(r.stdout, 'MERGE')]).toEqual([3, '']);
-    expect(r.stdout).toMatch(/STOP: merge conflicts in src\/a\.ts/);
+    const conflicted = f.run(PREFLIGHT, ['--base', 'main']);
+    expect([conflicted.status, lineOf(conflicted.stdout, 'MERGE')]).toEqual([3, '']);
+    expect(conflicted.stdout).toContain('STOP: an unfinished merge is in progress (MERGE_HEAD, conflicts in src/a.ts)');
     f.write({ 'src/a.ts': 'export const a = 7;\n' }); f.git('add', 'src/a.ts');
-    const staged = f.run(PREFLIGHT, ['--base', 'main']);
-    expect([staged.status, lineOf(staged.stdout, 'MERGE')]).toEqual([3, '']);
-    expect(staged.stdout).toContain('STOP: git merge origin/main failed:');
+    expect(f.run(PREFLIGHT, ['--base', 'main']).stdout).toContain('STOP: an unfinished merge is in progress (MERGE_HEAD):');
+    f.git('merge', '--abort');
+    expect(f.git('cherry-pick', 'other').status).not.toBe(0);
+    f.write({ 'src/a.ts': 'export const a = 8;\n' }); f.git('add', 'src/a.ts');
+    expect(f.run(PREFLIGHT, ['--base', 'main']).stdout).toContain('STOP: an unfinished cherry-pick is in progress (CHERRY_PICK_HEAD):');
+    f.git('cherry-pick', '--abort');
+    f.write({ 'src/a.ts': 'export const a = 9;\n' }); f.commit('feat edits a again');
+    expect(f.git('revert', '--no-edit', 'HEAD~1').status).not.toBe(0);
+    f.write({ 'src/a.ts': 'export const a = 10;\n' }); f.git('add', 'src/a.ts');
+    expect(f.run(PREFLIGHT, ['--base', 'main']).stdout).toContain('STOP: an unfinished revert is in progress (REVERT_HEAD):');
+    expect(merges()).toEqual([]);
+  });
+
+  // Value: protects=only a real in-progress operation stops Step 3, and unresolved index entries with none in progress stop with their files named before any git merge;
+  //   fails_when=a branch or tag named like MERGE_HEAD/CHERRY_PICK_HEAD/REVERT_HEAD gives a stop no abort can clear, or a conflicted stash pop reaches git merge and gets a merge-specific stop;
+  //   why_new=GST-732 /ship adversarial findings 2 and 4; seam=git rev-parse --git-path, git diff --diff-filter=U; no_claim=git am or sequencer state
+  test('a ref named REVERT_HEAD is not an unfinished revert, and a conflicted stash pop stops with its files named', () => {
+    const { f, merges } = guarded();
+    f.git('branch', 'REVERT_HEAD'); f.git('tag', 'CHERRY_PICK_HEAD');
+    const named = f.run(PREFLIGHT, ['--base', 'main']);
+    expect([named.status, lineOf(named.stdout, 'MERGE')]).toEqual([0, 'MERGE: up to date']);
+    f.write({ 'src/a.ts': 'export const a = 6;\n' }); f.git('stash');
+    f.write({ 'src/a.ts': 'export const a = 7;\n' }); f.commit('feat edits a');
+    expect(f.git('stash', 'pop').status).not.toBe(0);
+    const r = f.run(PREFLIGHT, ['--base', 'main']);
+    expect(r.status).toBe(3);
+    expect(r.stdout).toContain('STOP: unresolved conflicts in src/a.ts with no merge, cherry-pick or revert in progress');
+    expect(merges()).toEqual([]);
   });
 });
diff --git a/test/size-ledger/ship/gst-732-preflight-unfinished-op.json b/test/size-ledger/ship/gst-732-preflight-unfinished-op.json
new file mode 100644
index 000000000..94358e552
--- /dev/null
+++ b/test/size-ledger/ship/gst-732-preflight-unfinished-op.json
@@ -0,0 +1,4 @@
+{
+  "bytes": 29,
+  "why": "GST-732: Step 3 names the MERGE: up to date outcome"
+}