v1.91.96.0 fix: honest install and self-upgrade on Capy (field wave A, items 1-5) (#3164)

* docs(designs): gstack field wave plan (2026-10-12) and the shared simulated Capy host fixture

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

* feat(doctor): --min-revision, a launch Bun found off PATH, planning-only pins SKIP

gstack-doctor --check gains --min-revision <v>|unknown: below it the revision
row FAILs with REVISION_BELOW_MINIMUM naming the Capy wrapper or
bin/gstack-upgrade; unknown says so and never claims the minimum. The runtime
and pins rows name a supported Bun found in $BUN_INSTALL/bin (not on PATH)
with the export/GSTACK_LAUNCH fix (gstack_bun_launch_dir, one helper in
bin/gstack-bun-version.sh). --for a planning-only workflow (autoplan, the plan
reviews, office-hours) reports a repo test-pin mismatch as SKIP pins
(planning-only; ...). New result codes UPGRADE_REFUSED, UPGRADE_FETCH_FAILED,
REVISION_BELOW_MINIMUM, CAPY_WRAPPER_STALE, INSTALL_UNVERIFIED with
troubleshooting anchors; REVISION_UNMET's fix names bin/gstack-upgrade.

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

* feat(install): install verdict and install admission at skill start

bin/gstack-install-verdict.sh (Bash) and lib/install-verdict.ts (TypeScript)
are the one reader of the install verdict gstack-capy-install writes to
<state root>/install-verdicts/<sha256(checkout realpath)>.json (checkout,
HEAD, workflow and required components, planning-only pins, trailer). The
source checkout and capy/support.env resolve through gstack_source_root /
sourceRoot, which follow an installed root's .source-path.

gstack-skill-start, after SESSION_KIND: an unattended session (any host)
refuses on a PATH Bun below the supported minimum; with GSTACK_CAPY=1 an
unattended or explicit spawned session also refuses without a passing
verdict for this checkout, HEAD and workflow (INSTALL_UNVERIFIED). A refusal
prints the INSTALL: row, an install-refused instruction block bound to its
SESSION_ID, GSTACK_RESULT ... status=refused run=- and exits 3. Ambient
spawned sessions warn; GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1 admits and says so.
capy/support.env declares GSTACK_MIN_REVISION and GSTACK_CAPY_MIN_WRAPPER.

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

* feat(capy-install): launch PATH, Bun reuse and CI pins, setup skip on HEAD, verdict, --check

The GSTACK_LAUNCH line carries PATH=<dir>:$PATH when the certified Bun is not
first on PATH, plus GSTACK_CAPY=1 and GSTACK_INSTALL_VERDICT, and
GSTACK_LAUNCH_PATH: <dir>; the doctor runs with that PATH. A supported Bun in
$BUN_INSTALL/bin is reused instead of downloaded again. Project pins are read
with bin/gstack-runtime-pins.ts (CI lanes included): when every exact pin is
gstack's verified version the archive is installed alongside a different PATH
Bun; any other exact pin is RUNTIME_PIN_CONFLICT. Both ./setup runs are
skipped when this HEAD was set up with the same hosts, model and browser flag
and the check passes (never after a fast-forward); a failed setup ends with
gstack: fail setup and is retried next run. --check certifies only;
GSTACK_CAPY_LOCK_HELD=1 accepts the bootstrapper's held lock; result anchors
come from the generated components table; REV_NOTE names bin/gstack-upgrade.

Intentional pin change: test/gstack-capy-install.test.ts --revision trailer
now names <root>/bin/gstack-upgrade (the old text named a command that never
existed).

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

* feat(upgrade): bin/gstack-upgrade, the unattended fast-forward every fix line names

--check fetches and prints current|behind <installed> -> <remote> (<n>
commits); the default fast-forwards to the remote default branch tip and
reinstalls (bin/gstack-capy-install on a Capy install, else ./setup
--refresh-registered), completing a pending reinstall on the next run. It
refuses (UPGRADE_REFUSED, exit 3, nothing changed) a dirty tracked byte, a
diverged commit, a pinned checkout, the incoming Bun floor and a held
.setup-lock; never stashes or resets; an unreachable remote is
UPGRADE_FETCH_FAILED. Fetches are receipted (fail-open). The unattended
skill-end UPGRADE_AVAILABLE line is followed by UPGRADE_COMMAND naming it.

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

* feat(capy): vendored Capy skill, frozen bootstrapper and full wrapper bin/gstack-capy-session

capy/skill/gstack/ is the Drive skill's source of truth. scripts/install.sh
is a frozen bootstrapper: it prints gstack-capy-skill: wrapper <n> (<path>),
clones or fetches under .gstack-capy-install.lock, reads the remote
capy/support.env (FETCH_HEAD), fast-forwards a clean unpinned checkout below
GSTACK_MIN_REVISION (refusing dirty, diverged or pinned checkouts with the
exact commands; GSTACK_CAPY_AUTO_UPGRADE=0 disables), and execs the
checkout's own bin/gstack-capy-session with GSTACK_CAPY_LOCK_HELD=1 so the
held lock is never taken twice. Offline it says the remote minimum is
unknown. A Drive copy older than GSTACK_CAPY_MIN_WRAPPER prints an owner
action (CAPY_WRAPPER_STALE). SKILL.md: check at session start, install
lazily before the first workflow, the GSTACK_LAUNCH line, the trailer rule,
the subagent first-report line, gstack-pregate sealed before any push, and
the autoplan/DRIVER.md pointer. The context-budget fixture gains the skill's
entry.

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

* docs: Capy install layers, lazy install, snapshot bake, forward-only recovery, raising the minimum

docs/capy-install.md describes the three layers (Drive bootstrapper, full
wrapper, installer), the lazy install, the GSTACK_LAUNCH line, install
admission, baking gstack into a Capy snapshot, and that recovery after an
interrupted fast-forward completes or refuses the pending install stages
(checking out an older commit is not a rollback). docs/CHANGELOG_STYLE.md
(the release doc; there is no docs/RELEASING.md) says when
GSTACK_MIN_REVISION may be raised.

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

* refactor(capy): the stale-copy owner action moves from the frozen bootstrapper to bin/gstack-capy-session

The checkout-owned full wrapper reads GSTACK_CAPY_MIN_WRAPPER through
gstack_support_env_get(gstack_source_root) and compares it with the
bootstrapper revision it was handed, so the rule can change without
recopying the Drive skill. The bootstrapper keeps only what a stale checkout
cannot do: clone, fetch, read the remote minimum, fast-forward, exec.

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

* v1.91.96.0: honest install and self-upgrade on Capy; supported minimum 1.91.96.0

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

* test: drop the helper-only Capy host fixture test (test-of-test ratchet); lane tests exercise the helper

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

* test: bound the new sync spawns in the install-verdict and wrapper tests (spawnSync tripwire)

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

* ci(paid-pr-profile): the vendored Capy skill is free-only; free-only files are not prompts needing paid coverage

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

* chore(harness): non-behavioral HARNESS_VERSION decision for the PR-profile free-only rule

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

* test(doctor): lane A runtime and pins cases are platform-neutral (bash paths; a lane-free .bun-version pin)

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

* docs(designs): field wave plan with amendments and the gate rev 2-3 review record (ARTIFACT_VALID, 3 gate revisions)

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

* fix(capy-install): follow a project's exact Bun pin above the minimum when gstack has its verified archive (adds Bun 1.4.3)

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

* docs: the installer follows a verified exact project Bun pin (capy-install, troubleshooting, changelog)

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

* fix(capy-install): the install reason names the project's pin and gstack's real minimum

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>

test/gstack-skill-start.test.ts

@@ -394,6 +394,7 @@ describe('gstack-skill-start behavior', () => {
       expect(out).not.toContain('UPGRADE_AVAILABLE');
       const endOut = end({ GSTACK_SESSION_KIND: 'unattended' });
       expect(endOut).toMatch(/^UPGRADE_AVAILABLE: 9\.9\.9; run \/gstack-upgrade$/m);
+      expect(endOut).toMatch(/^UPGRADE_COMMAND: \/.*\/bin\/gstack-upgrade$/m);
       expect(endOut).toMatch(/^ARTIFACTS_SYNC: skipped \(unattended session\)$/m);
       expect(fs.existsSync(log)).toBe(false);
       expect(fs.existsSync(path.join(gh, 'analytics', 'skill-usage.jsonl'))).toBe(false);
@@ -764,3 +765,110 @@ describe('gstack-skill-end', () => {
     expect(fs.existsSync(pending)).toBe(false);
   });
 });
+
+// Field wave lane A (item 2): an unattended or Capy-spawned workflow refuses
+// to start on an unsupported PATH Bun, and on a Capy machine (GSTACK_CAPY=1)
+// without a matching install verdict for this checkout, HEAD and workflow.
+describe('gstack-skill-start install admission', () => {
+  const { spawnSync } = require('child_process') as typeof import('child_process');
+  const { createHash } = require('crypto') as typeof import('crypto');
+  const { writeBunStub } = require('./helpers/capy-host') as typeof import('./helpers/capy-host');
+  const head = execFileSync('git', ['-C', ROOT, 'rev-parse', 'HEAD'], { encoding: 'utf-8' }).trim();
+  const real = fs.realpathSync(ROOT);
+  const scratch = () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-admit-'));
+    fs.writeFileSync(path.join(dir, 'config.yaml'), 'update_check: false\n');
+    return dir;
+  };
+  const stubDir = (version: string) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-bun-'));
+    writeBunStub(path.join(dir, 'bun'), version);
+    return dir;
+  };
+  const verdict = (gh: string, over: Record<string, unknown> = {}, file?: string) => {
+    const target = file ?? path.join(gh, 'install-verdicts', `${createHash('sha256').update(real).digest('hex')}.json`);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify({
+      schema_version: 1, checkout: real, head, for: 'autoplan',
+      required: ['claude', 'codex', 'patch', 'runtime', 'pins', 'state-root', 'privacy', 'cores', 'revision'],
+      pins_planning_only: false, ok: true, trailer: 'gstack: ok 1.91.95.0 for=autoplan', min_revision: '1.91.95.0', launch_path: '', time: '2026-10-12T00:00:00Z', ...over,
+    }, null, 1) + '\n');
+    return target;
+  };
+  const start = (gh: string, skill: string, env: Record<string, string>, bin = START) => spawnSync(bin, ['--skill', skill], {
+    timeout: 30_000, encoding: 'utf-8', cwd: tmpHome,
+    env: { PATH: process.env.PATH!, HOME: tmpHome, GSTACK_HOME: gh, ...env },
+  });
+
+  test('unattended with Bun 1.3.14 first on PATH: the runtime row with its fix, status=refused, exit 3; interactive keeps running', () => {
+    const gh = scratch();
+    const bun = stubDir('1.3.14');
+    const PATH = `${bun}${path.delimiter}${process.env.PATH}`;
+    const r = start(gh, 'autoplan', { GSTACK_SESSION_KIND: 'unattended', PATH });
+    expect(r.status, r.stdout + r.stderr).toBe(3);
+    expect(r.stdout).toMatch(/^SESSION_KIND: unattended$/m);
+    expect(r.stdout).toContain(`INSTALL: fail runtime — bun 1.3.14 at ${bun}/bun is below the supported minimum 1.4.2`);
+    expect(r.stdout).toContain('(RUNTIME_BELOW_MINIMUM)');
+    expect(r.stdout.trim().split('\n').at(-1)).toBe('GSTACK_RESULT: skill=autoplan status=refused run=-');
+    const human = start(gh, 'autoplan', { PATH });
+    expect(human.status).toBe(0);
+    expect(human.stdout).not.toContain('status=refused');
+    const openclaw = start(gh, 'autoplan', { OPENCLAW_SESSION: '1', PATH });
+    expect(openclaw.status).toBe(0);
+    expect(openclaw.stdout).toContain('INSTALL: warn runtime');
+    const overridden = start(gh, 'autoplan', { GSTACK_SESSION_KIND: 'unattended', PATH, GSTACK_ALLOW_UNSUPPORTED_RUNTIME: '1' });
+    expect(overridden.status).toBe(0);
+    expect(overridden.stdout).toContain('INSTALL_VERDICT: overridden (GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1)');
+  });
+
+  test('GSTACK_CAPY=1: a missing, failing, other-HEAD or narrower verdict refuses; a matching one admits; other unattended hosts need no verdict', () => {
+    const gh = scratch();
+    const capy = { GSTACK_SESSION_KIND: 'unattended', GSTACK_CAPY: '1' };
+    const missing = start(gh, 'autoplan', capy);
+    expect(missing.status, missing.stdout + missing.stderr).toBe(3);
+    expect(missing.stdout).toContain('INSTALL: fail verdict — no install verdict');
+    expect(missing.stdout).toContain('(INSTALL_UNVERIFIED)');
+    expect(start(gh, 'autoplan', { GSTACK_SESSION_KIND: 'unattended' }).status).toBe(0);
+
+    verdict(gh);
+    const ok = start(gh, 'autoplan', capy);
+    expect(ok.status, ok.stdout + ok.stderr).toBe(0);
+    expect(ok.stdout).toMatch(/^INSTALL_VERDICT: ok gstack: ok 1\.91\.95\.0 for=autoplan$/m);
+    const spawned = start(gh, 'autoplan', { GSTACK_SESSION_KIND: 'spawned', GSTACK_CAPY: '1' });
+    expect(spawned.status).toBe(0);
+
+    verdict(gh, { ok: false, trailer: 'gstack: fail runtime' });
+    const failed = start(gh, 'autoplan', capy);
+    expect(failed.status).toBe(3);
+    expect(failed.stdout).toContain('gstack: fail runtime');
+    verdict(gh, { head: '0'.repeat(40) });
+    const moved = start(gh, 'autoplan', capy);
+    expect(moved.status).toBe(3);
+    expect(moved.stdout).toContain('another HEAD');
+    verdict(gh, { pins_planning_only: true });
+    expect(start(gh, 'autoplan', capy).status).toBe(0);
+    const tests = start(gh, 'review', capy);
+    expect(tests.status).toBe(3);
+    expect(tests.stdout).toContain('planning-only');
+    verdict(gh);
+    const browser = start(gh, 'qa', capy);
+    expect(browser.status).toBe(3);
+    expect(browser.stdout).toContain('browse-bundle');
+
+    const elsewhere = verdict(gh, {}, path.join(gh, 'named.json'));
+    fs.rmSync(path.join(gh, 'install-verdicts'), { recursive: true, force: true });
+    expect(start(gh, 'autoplan', { ...capy, GSTACK_INSTALL_VERDICT: elsewhere }).status).toBe(0);
+  });
+
+  test('an installed runtime root follows its .source-path to the source checkout for the verdict and HEAD', () => {
+    const gh = scratch();
+    const runtime = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-runtime-'));
+    fs.symlinkSync(path.join(ROOT, 'bin'), path.join(runtime, 'bin'));
+    fs.writeFileSync(path.join(runtime, '.source-path'), `${ROOT}\n`);
+    fs.copyFileSync(path.join(ROOT, 'VERSION'), path.join(runtime, 'VERSION'));
+    verdict(gh);
+    const r = start(gh, 'autoplan', { GSTACK_SESSION_KIND: 'unattended', GSTACK_CAPY: '1' }, path.join(runtime, 'bin/gstack-skill-start'));
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain('INSTALL_VERDICT: ok');
+  });
+});