Merge main 1ccab0d8 into gsta258-l4-ready-receipts (rule 19 grant)

test/review-packets-removed.test.ts takes main's version (#3903 moved the
review pins to test/fixtures/review-pins/). This branch's two pin entries
become pin files with GSTA-202's recipe: a new
replays/GST-508+GST-464+GST-967+GSTA-258-L4.json and the
files/ship/sections/review-army.md.json repin to 22c37a64.

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

lib/ci-carry.ts

@@ -14,7 +14,9 @@
  *   max age, the run's own tree.json naming HEAD's tree);
  *   every run executed tests;
  *   with an inventory command, the runs' tree.json files cover every file it
- *   prints (a lane carries only what CI provably ran);
+ *   prints (a lane carries only what CI provably ran); with named jobs instead
+ *   (a lane with no test files, GST-1189), each of those jobs succeeded in the
+ *   run's newest attempt, read by verifyRun like the profile's own jobs;
  *   every run still stands after the inventory ran (runChanged).
  *
  * Anything else returns a refusal with a reason code, and the caller runs the
@@ -25,12 +27,18 @@
  * bounded by a timeout, and returns green, red with the failing jobs, still
  * running, or none.
  */
-import { runChanged, runReceiptFields, uncoveredFiles, verifyRun, type ApiRun, type RunDeps, type RunEvidence, type RunProfile, type RunSource } from './run-evidence';
+import { normalPath, runChanged, runInventory, runReceiptFields, uncoveredFiles, verifyRun, type ApiRun, type RunDeps, type RunEvidence, type RunProfile, type RunSource } from './run-evidence';
 
 export type CarryRefusal = 'dirty_tree' | 'no_profile' | 'no_run' | 'no_verified_run' | 'tree_mismatch' | 'no_tests'
-  | 'inventory_failed' | 'inventory_empty' | 'inventory_uncovered' | 'run_changed' | 'tree_changed' | 'api_error';
+  | 'inventory_failed' | 'inventory_empty' | 'inventory_uncovered' | 'inventory_skipped' | 'run_changed' | 'tree_changed' | 'api_error';
 export type CarryRefused = { ok: false; reason: CarryRefusal; detail: string };
-export type CarryVerdict = { ok: true; runs: RunEvidence[]; tests: number; receipt: string } | CarryRefused;
+/**
+ * `tests` never claims a whole run's count for a narrow lane: with an inventory it is the number of the lane's inventory files
+ * the runs' tree.json covers (`unit: 'files'`; tree.json has no per-file test counts yet), with named jobs `n/a`, and only
+ * without either (the whole run carried) the runs' test count. `remainder`: inventory files every run skipped entirely
+ * (tree.json `skipped_files`), which the caller must run here with the lane's per_file runner before the lane counts.
+ */
+export type CarryVerdict = { ok: true; runs: RunEvidence[]; tests: number | 'n/a'; unit?: 'files'; notOwed?: string; remainder?: string[]; receipt: string } | CarryRefused;
 
 /** How many of HEAD's runs per workflow are tried, newest first. */
 const CANDIDATES = 10;
@@ -38,12 +46,13 @@ const no = (reason: CarryRefusal, detail: string): CarryRefused => ({ ok: false,
 const newestFirst = (a: ApiRun, b: ApiRun) => (b.created_at ?? '').localeCompare(a.created_at ?? '') || b.id - a.id;
 
 /** The newest run of `profile` on `head` that verifies; a refusal lists each candidate's reason, newest first. */
-function newestVerified(src: RunSource, name: string, profile: RunProfile, head: string): { ok: true; evidence: RunEvidence } | CarryRefused {
+function newestVerified(src: RunSource, name: string, profile: RunProfile, head: string, jobs: string[]): { ok: true; evidence: RunEvidence } | CarryRefused {
+  if (jobs.length) profile = { ...profile, jobs: [...new Set([...profile.jobs, ...jobs])] };
   const listed = src.deps.runsForHead(profile.workflow, head).filter(r => profile.events.includes(r.event)).sort(newestFirst).slice(0, CANDIDATES);
   if (!listed.length) return no('no_run', `no ${profile.workflow} run (${profile.events.join(', ')}) on ${head.slice(0, 12)} yet`);
   const refusals: string[] = [];
   for (const run of listed) {
-    const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: [head], now: src.now });
+    const v = verifyRun(src.deps, { repo: src.repo, runRef: String(run.id), profileName: name, profile, vetoHeads: [head], now: src.now, unchanged: src.unchanged });
     if (v.ok) return v;
     refusals.push(`run ${run.id}: ${v.reason}`);
   }
@@ -52,9 +61,13 @@ function newestVerified(src: RunSource, name: string, profile: RunProfile, head:
 
 /**
  * The CI evidence for HEAD's tree under `profiles` (one verified run each), or why there is none. `wtree` reads the
- * working-tree fingerprint (before the lookup and after it); `inventory` lists the files the runs must cover.
+ * working-tree fingerprint (before the lookup and after it); `inventory` lists the files the runs must cover, or `jobs`
+ * names the jobs that must have succeeded in each run's newest attempt (a lane with no test files; no test count needed).
  */
-export function findCarry(src: RunSource, o: { profiles: string[]; head: string; tree: string; wtree: () => string | null; inventory?: () => string[] | { error: string } }): CarryVerdict {
+export function findCarry(src: RunSource, o: { profiles: string[]; head: string; tree: string; wtree: () => string | null; inventory?: () => string[] | { error: string }; jobs?: string[]; perFile?: boolean }): CarryVerdict {
+  const jobs = o.jobs ?? [];
+  let covered: number | undefined;
+  let remainder: string[] = [];
   const before = o.wtree();
   if (before !== o.tree) return no('dirty_tree', `the working tree (${before ? before.slice(0, 12) : 'fingerprint unavailable'}) is not HEAD's committed tree ${o.tree.slice(0, 12)}; only a clean, committed tree carries`);
   if (!o.profiles.length) return no('no_profile', 'no run profile is named');
@@ -63,20 +76,24 @@ export function findCarry(src: RunSource, o: { profiles: string[]; head: string;
     for (const name of o.profiles) {
       const profile = src.profiles[name];
       if (!profile) return no('no_profile', `${name} is not a run_profiles name on the base branch`);
-      const v = newestVerified(src, name, profile, o.head);
+      const v = newestVerified(src, name, profile, o.head, jobs);
       if (!v.ok) return v;
       runs.push(v.evidence);
     }
     const other = runs.find(e => e.tree !== o.tree);
     if (other) return no('tree_mismatch', `run ${other.run_id} tested tree ${other.tree.slice(0, 12)}, not ${o.tree.slice(0, 12)}`);
-    const empty = runs.find(e => !e.files.length || e.tests === 0);
+    const empty = jobs.length ? undefined : runs.find(e => !e.files.length || e.tests === 0);
     if (empty) return no('no_tests', `run ${empty.run_id}'s tree.json ${empty.files.length ? 'records 0 tests' : 'lists no test files'}`);
     if (o.inventory) {
       const listed = o.inventory();
       if ('error' in listed) return no('inventory_failed', listed.error);
       if (!listed.length) return no('inventory_empty', 'the inventory command printed no files');
-      const missing = uncoveredFiles(listed, runs);
-      if (missing.length) return no('inventory_uncovered', `${missing.length} of ${listed.length} inventory file(s) are in no run's tree.json: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}`);
+      const absent = uncoveredFiles(listed, runs, 'covered');
+      const some = (fs: string[]) => `${fs.slice(0, 5).join(', ')}${fs.length > 5 ? ', …' : ''}`;
+      if (absent.length) return no('inventory_uncovered', `${absent.length} of ${listed.length} inventory file(s) are in no run's tree.json: ${some(absent)}`);
+      remainder = uncoveredFiles(listed, runs, 'uncovered');
+      if (remainder.length && !o.perFile) return no('inventory_skipped', `${remainder.length} of ${listed.length} inventory file(s) skipped every test in CI and the lane declares no per_file runner: ${some(remainder)}`);
+      covered = new Set(listed.map(normalPath)).size - remainder.length;
     }
     for (const e of runs) {
       const changed = runChanged(src.deps, e.run_id, e.run_attempt);
@@ -87,6 +104,13 @@ export function findCarry(src: RunSource, o: { profiles: string[]; head: string;
   }
   const after = o.wtree();
   if (after !== o.tree) return no('tree_changed', `the working tree changed while the runs were verified (now ${after ? after.slice(0, 12) : 'unreadable'})`);
+  if (jobs.length) {
+    const gates = [...new Set(o.profiles.map(n => src.profiles[n]?.skippable?.gate).filter(Boolean))];
+    const allSkipped = runs.every(e => jobs.every(j => e.skipped_jobs?.includes(j)));
+    const notOwed = allSkipped ? `CI skipped at this tree (gate job ${gates.join(', ')}, workflow unchanged)` : undefined;
+    return { ok: true, runs, tests: 'n/a', ...(notOwed ? { notOwed } : {}), receipt: `ci-carry tree=${o.tree.slice(0, 12)} jobs=${jobs.join(',')}${notOwed ? ` not_owed=${gates.join(',')}` : ''} ${runReceiptFields(runs, src.now)}` };
+  }
+  if (covered !== undefined) return { ok: true, runs, tests: covered, unit: 'files', ...(remainder.length ? { remainder } : {}), receipt: `ci-carry tree=${o.tree.slice(0, 12)} files=${covered}${remainder.length ? ` skipped_here=${remainder.length}` : ''} ${runReceiptFields(runs, src.now)}` };
   const tests = runs.reduce((n, e) => n + (e.tests ?? e.files.length), 0);
   return { ok: true, runs, tests, receipt: `ci-carry tree=${o.tree.slice(0, 12)} tests=${tests} ${runReceiptFields(runs, src.now)}` };
 }
@@ -109,24 +133,75 @@ export async function waitForRun(deps: RunDeps, o: { workflow: string; events: s
   }
 }
 
-/** `ship_lanes_from` (base branch only): exact lane command → the profiles whose runs carry it and the command listing its test files. */
-export interface ShipLaneMapping { profiles: string[]; inventory: string }
+/**
+ * `ship_lanes_from` (base branch only): exact lane command → the profiles whose runs carry it and either the command listing
+ * its test files (`inventory`) or the CI jobs that run it (`jobs`, for a lane with no test files such as a typecheck; GST-1189).
+ */
+export interface ShipLaneMapping { profiles: string[]; inventory?: string; jobs?: string[]; aliases?: string[]; per_file?: string }
+
+/**
+ * The `ship_lanes_from` entry for an exact lane command: the entry it keys, else the entry that declares it in `aliases`
+ * (GST-1190: the same lane run under another exact spelling, such as an env prefix). Never normalized: an alias is a
+ * second exact command the base's owner declared, not a pattern.
+ */
+export function laneMapping(from: Record<string, ShipLaneMapping>, command: string): ShipLaneMapping | undefined {
+  if (Object.prototype.hasOwnProperty.call(from, command)) return from[command];
+  return Object.values(from).find(m => m.aliases?.includes(command));
+}
+
+/** findCarry's coverage rule for one mapping: its inventory (a pin-file command run in `cwd`, with a per_file runner or not) or its named jobs. */
+export const mappingCoverage = (m: ShipLaneMapping, cwd: string): { inventory?: () => string[] | { error: string }; jobs?: string[]; perFile?: boolean } =>
+  m.jobs ? { jobs: m.jobs } : { inventory: () => runInventory(m.inventory!, cwd), perFile: !!m.per_file };
+
+/**
+ * What `gstack-evidence record-ci` reported, read from its own last record line onward (the per_file remainder's output comes
+ * first, so a test printing look-alike lines cannot change the reading): the carried runs, count, unit and remainder, any
+ * not-owed reason, or the last CARRY_NONE reason.
+ */
+export function recordCiResult(stderr: string): { runs?: string; tests?: string; files?: boolean; notOwed?: string; here?: string; none?: string } {
+  const lines = stderr.split('\n');
+  const at = lines.findLastIndex(x => x.startsWith('gstack-evidence: recorded label=') && x.includes(' log=- source=ci runs='));
+  const none = lines.findLast(x => x.startsWith('CARRY_NONE: '))?.slice('CARRY_NONE: '.length);
+  if (at < 0) return none ? { none } : {};
+  const got = / tests_ran=(\d+|n\/a)( unit=files)? log=- source=ci runs=(\S+)/.exec(lines[at]!);
+  const here = / skipped_here=(\d+) tests_ran_here=(\S+)$/.exec(lines[at]!);
+  const notOwed = lines.slice(at + 1).find(x => x.startsWith('gstack-evidence: not owed: '))?.slice('gstack-evidence: not owed: '.length);
+  return { runs: got?.[3], tests: got?.[1], files: !!got?.[2], ...(notOwed ? { notOwed } : {}), ...(here ? { here: `skipped_here=${here[1]} file(s) tests_ran_here=${here[2]}` } : {}) };
+}
+
+/** The per_file runner command for `files`: `{files}` replaced by the paths, each single-quoted for bash. */
+export const perFileCommand = (template: string, files: string[]): string =>
+  template.replaceAll('{files}', files.map(f => `'${f.replace(/'/g, `'\\''`)}'`).join(' '));
 
 /** `<path>: <message>` errors for `ship_lanes_from`; empty when valid. Shared with lib/pregate/config.ts. */
 export function shipLanesErrors(raw: unknown, profileNames: readonly string[]): Array<{ path: string; message: string }> {
   if (raw === undefined) return [];
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [{ path: 'ship_lanes_from', message: 'must be an object of exact lane command → { profiles: [run_profiles names], inventory: command }' }];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [{ path: 'ship_lanes_from', message: 'must be an object of exact lane command → { profiles: [run_profiles names], inventory: command } or { profiles, jobs: [job names] }' }];
   const errors: Array<{ path: string; message: string }> = [];
   const oneLine = (s: unknown) => typeof s === 'string' && !!s.trim() && s.length <= 512 && !/[\0\r\n]/.test(s);
+  const declared = new Map<string, string>(Object.keys(raw as object).map(k => [k, 'a key']));
   for (const [command, m] of Object.entries(raw as Record<string, unknown>)) {
     const at = `ship_lanes_from[${JSON.stringify(command)}]`;
     if (!oneLine(command)) errors.push({ path: at, message: 'the key must be the exact lane command: one line under 512 characters' });
-    if (!m || typeof m !== 'object' || Array.isArray(m)) { errors.push({ path: at, message: 'must be { profiles, inventory }' }); continue; }
+    if (!m || typeof m !== 'object' || Array.isArray(m)) { errors.push({ path: at, message: 'must be { profiles, inventory } or { profiles, jobs }' }); continue; }
     const o = m as Record<string, unknown>;
-    for (const k of Object.keys(o)) if (k !== 'profiles' && k !== 'inventory') errors.push({ path: `${at}.${k}`, message: 'unknown key; valid keys: profiles, inventory' });
+    for (const k of Object.keys(o)) if (!['profiles', 'inventory', 'jobs', 'aliases', 'per_file'].includes(k)) errors.push({ path: `${at}.${k}`, message: 'unknown key; valid keys: profiles, inventory, jobs, aliases, per_file' });
+    if ('per_file' in o && (!oneLine(o.per_file) || !(o.per_file as string).includes('{files}') || !('inventory' in o))) errors.push({ path: `${at}.per_file`, message: 'must be one command line under 512 characters containing {files}, on an entry with an inventory (it runs the inventory files CI skipped entirely)' });
+    if ('aliases' in o) {
+      const aliases = o.aliases;
+      if (!Array.isArray(aliases) || !aliases.length || aliases.some(a => !oneLine(a)) || new Set(aliases).size !== aliases.length) errors.push({ path: `${at}.aliases`, message: 'must be a non-empty array of distinct exact lane commands, each one line under 512 characters' });
+      else for (const a of aliases as string[]) {
+        if (declared.has(a)) errors.push({ path: `${at}.aliases`, message: `${JSON.stringify(a)} is already ${declared.get(a)}; each exact command maps to one entry` });
+        else declared.set(a, `an alias of ${JSON.stringify(command)}`);
+      }
+    }
     if (!Array.isArray(o.profiles) || !o.profiles.length || o.profiles.some(p => typeof p !== 'string')) errors.push({ path: `${at}.profiles`, message: 'must be a non-empty array of run_profiles names' });
     else for (const p of o.profiles as string[]) if (!profileNames.includes(p)) errors.push({ path: `${at}.profiles`, message: `${JSON.stringify(p)} is not a run_profiles name` });
-    if (!oneLine(o.inventory)) errors.push({ path: `${at}.inventory`, message: 'must be one command line under 512 characters that prints the lane\'s test files, one per line' });
+    if (('inventory' in o) === ('jobs' in o)) errors.push({ path: at, message: 'declare exactly one of inventory (a command listing the lane\'s test files) or jobs (the CI jobs that run it)' });
+    else if ('jobs' in o) {
+      const jobs = o.jobs;
+      if (!Array.isArray(jobs) || !jobs.length || jobs.some(j => typeof j !== 'string' || !oneLine(j) || j.length > 128) || new Set(jobs).size !== jobs.length) errors.push({ path: `${at}.jobs`, message: 'must be a non-empty array of distinct CI job names, each one line under 128 characters' });
+    } else if (!oneLine(o.inventory)) errors.push({ path: `${at}.inventory`, message: 'must be one command line under 512 characters that prints the lane\'s test files, one per line' });
   }
   return errors;
 }

lib/harness-register.ts

@@ -22,7 +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';
+import { activateHook, assertHookRoot, foreignOpenclawConfig, hookChoice, hookConfig, 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';
@@ -135,7 +135,7 @@ 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_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), unset OPENCLAW_CONFIG_PATH or point it at the profile\'s own openclaw.json, 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' },
@@ -525,7 +525,7 @@ 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 }
+interface HookPlan { on: boolean; prevOn: boolean; explicit: boolean; retry: boolean; profile: string; root: string; files: Map<string, Buffer>; note?: string; fix?: string; requested?: boolean }
 
 /** 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 {
@@ -544,17 +544,19 @@ function hookPlan(opts: RegisterOptions, dest: string, prev: Ledger | null): Hoo
   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' : '';
+  const requested = !opts.inherit;
+  const foreign = t.name === 'openclaw' ? foreignOpenclawConfig(opts.env, profile) : '';
+  const [why, fix] = dest !== profileSkills(t.name, profile) ? ['this registration uses another skills folder (' + dest + ')', 'register without --skills-dir to get the hook, or pass --no-start-hook to keep this registration without it']
+    : foreign ? ['OPENCLAW_CONFIG_PATH points OpenClaw at ' + foreign + ', outside that profile', 'unset OPENCLAW_CONFIG_PATH or set it to ' + hookConfig('openclaw', profile) + ', then register again'] : ['', ''];
   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)' });
+    return off({ ...plan, on: false, requested, fix, 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 off({ ...plan, on: false, requested, fix: HARNESS_CODES[e.code].fix, note: 'off: ' + e.message + ' (' + choice.source + ' asked for the hook)' });
   }
   return { ...plan, files: hookFiles(t.name, root) };
 }
@@ -562,7 +564,7 @@ function hookPlan(opts: RegisterOptions, dest: string, prev: Ledger | null): Hoo
 /** 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 } : {}) };
+  if (!hook.on) return { state: 'off', ...(hook.note ? { detail: hook.note } : {}), ...(released || hook.fix ? { fix: released || hook.fix } : {}), ...(hook.requested ? { required: true } : {}) };
   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' };
@@ -678,7 +680,7 @@ export function register(opts: RegisterOptions): RegisterResult {
     if (opts.registry && t.render === 'host') shellRegistry(opts, 'gstack_install_registry_upsert', [t.name, 'global', '-', dest, opts.checkout, opts.checkout, opts.version, '-', '-']);
     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 active = hook?.on && (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 } : {}) };

lib/harness-start-hook.ts

@@ -22,14 +22,14 @@ export const START_NOTE_MAX = 300;
 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 type HookState = 'active' | 'written' | 'disabled' | 'unknown' | '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'],
+    profileVar: 'OPENCLAW_STATE_DIR', home: '.openclaw', sub: 'extensions', skills: ['skills'], name: 'OpenClaw', config: 'openclaw.json', setup: 'openclaw onboard',
     activate: [['config', 'set', 'plugins.entries.' + HOOK_ID + '.hooks.allowConversationAccess', 'true'], ['config', 'set', 'plugins.entries.' + HOOK_ID + '.enabled', 'true']],
     files: (): Record<string, string> => ({
       'index.js': [
@@ -55,7 +55,7 @@ const SPECS = {
     }),
   },
   hermes: {
-    profileVar: 'HERMES_HOME', home: '.hermes', sub: 'plugins', skills: ['skills', 'gstack'],
+    profileVar: 'HERMES_HOME', home: '.hermes', sub: 'plugins', skills: ['skills', 'gstack'], name: 'Hermes', config: 'config.yaml', setup: 'hermes setup',
     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'),
@@ -91,6 +91,51 @@ export const hookRoot = (t: HookTarget, profile: string) => path.join(profile, S
 /** 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 harness's own config file in a profile: the file activation edits through the harness CLI. */
+export const hookConfig = (t: HookTarget, profile: string) => path.join(profile, SPECS[t].config);
+
+function canonical(p: string): string {
+  try { return fs.realpathSync(p); } catch {}
+  const parent = path.dirname(p);
+  return parent === p ? p : path.join(canonical(parent), path.basename(p));
+}
+/** The config OPENCLAW_CONFIG_PATH names when it is not the profile's own openclaw.json (compared after realpath), else ''. */
+export function foreignOpenclawConfig(env: Env, profile: string): string {
+  const v = env.OPENCLAW_CONFIG_PATH;
+  if (!v) return '';
+  const named = path.resolve(v);
+  return canonical(named) === canonical(hookConfig('openclaw', profile)) ? '' : named;
+}
+
+/** A profile with no harness config yet: turning the plugin on through the harness CLI would create a config holding only that setting, so gstack waits for the harness's own setup. */
+function noConfig(t: HookTarget, profile: string): HookResult | null {
+  const cfg = hookConfig(t, profile);
+  if (fs.existsSync(cfg)) return null;
+  const s = SPECS[t];
+  return { state: 'written', detail: 'no ' + s.name + ' config at ' + cfg + ' yet, and turning the plugin on would create one holding only that setting', fix: 'run ' + s.name + "'s own setup first (" + s.profileVar + '=' + JSON.stringify(profile) + ' ' + s.setup + '), then gstack-harness refresh' };
+}
+
+/** Reads the hook from the harness's config file when its CLI is not on PATH (a harness's own terminal tool often lacks it). */
+function inspectConfig(t: HookTarget, profile: string, fix: string): HookResult {
+  const why = t + ' is not on PATH';
+  const written: HookResult = { state: 'written', detail: why + ', so gstack could not turn the plugin on or check it', fix };
+  const cfg = hookConfig(t, profile);
+  const missing = noConfig(t, profile);
+  if (missing) return { ...missing, detail: why + ' and ' + missing.detail };
+  let plugins: any;
+  try { plugins = ((t === 'hermes' ? Bun.YAML.parse(fs.readFileSync(cfg, 'utf8')) : JSON.parse(fs.readFileSync(cfg, 'utf8'))) as any)?.plugins ?? {}; }
+  catch { return { state: 'unknown', detail: why + ' and ' + cfg + ' could not be parsed, so gstack could not check the plugin', fix: 'gstack-harness status from a shell where ' + t + ' is on PATH' }; }
+  if (t === 'hermes') {
+    const listed = (k: string) => Array.isArray(plugins[k]) && plugins[k].includes(HOOK_ID);
+    if (listed('disabled')) return { state: 'disabled', detail: 'turned off in Hermes (plugins.disabled in ' + cfg + '); gstack leaves it off', fix };
+    if (listed('enabled') && fs.existsSync(path.join(hookRoot(t, profile), 'plugin.yaml'))) return { state: 'active', detail: 'read from plugins.enabled in ' + cfg + ' (' + why + ')' };
+    return written;
+  }
+  const entry = plugins.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 (entry.enabled === true && entry.hooks?.allowConversationAccess === true) return { state: 'unknown', detail: cfg + ' turns it on, but ' + why + ', so gstack could not check that OpenClaw loads it', fix: 'gstack-harness status from a shell where openclaw is on PATH' };
+  return written;
+}
 
 /** 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> {
@@ -124,6 +169,8 @@ const onPath = (bin: string, env: Env) => (env.PATH ?? '').split(path.delimiter)
 /** 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';
+  const missing = noConfig(t, profile);
+  if (missing) return missing.detail!;
   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 + ')';
@@ -136,12 +183,14 @@ function parseJson(s: string): any {
   return null;
 }
 
-/** Reads the hook back from the harness: active (configured for new sessions), disabled by the user, or written (with the fix). */
+/** Reads the hook back from the harness: active (configured for new sessions), disabled by the user, written (with the fix), or unknown (no CLI and a config that cannot settle it). Runs no harness command while the profile has no harness config. */
 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 (!onPath(t, env)) return inspectConfig(t, profile, fix);
+  const missing = noConfig(t, profile);
+  if (missing) return missing;
   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);

lib/pregate/checks/guards.ts

@@ -11,9 +11,17 @@
  * incident: a gbrain serial test landed without its manifest row and
  * passed both the isolation check and pregate; `test/cli-goldens.test.ts`
  * spawns the CLI as a subprocess, so no import graph selects it.
+ *
+ * GST-1186: a guard whose exact command already passed at this tree is not run
+ * again. #3901's carry (gstack-evidence record-ci) carries it from a verified
+ * CI run when the base's ship_lanes_from maps the command, else a counted
+ * ledger pass of the same command at the same working tree stands
+ * (gstack-evidence passed). ship_lanes_from is read from origin/<base> only, so
+ * the PR that adds a mapping cannot carry from it yet.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { laneMapping, recordCiResult } from '../../ci-carry';
 import { matchesAny } from '../../ship-policy';
 import type { Guard } from '../config';
 import { baseInputs, sha256 } from '../context';
@@ -23,8 +31,29 @@ import { checkScratch } from '../run-scratch';
 import { readRange, STALL_IDLE, supervise } from '../supervise';
 import type { EnvironmentCause } from '../types';
 import type { CheckDef, CheckResult, PregateContext } from '../types';
+import { runScriptSync } from '../../script-invocation';
 
-interface GuardRun { guard: Guard; exit: number | null; timedOut: boolean; stalled: boolean; tail: string[]; log: string; environment: EnvironmentCause | null }
+interface GuardRun { guard: Guard; exit: number | null; timedOut: boolean; stalled: boolean; tail: string[]; log: string; environment: EnvironmentCause | null; prior?: string; carryNone?: string }
+
+const EVIDENCE = path.resolve(import.meta.dir, '..', '..', '..', 'bin', 'gstack-evidence');
+
+/**
+ * The pass that already covers this guard's exact command at this tree (GST-1186): a CI carry (or a CI skip the unchanged gate
+ * decided, printed as not owed), else a same-tree local ledger pass under the runtime the guard would launch with.
+ */
+function priorPass(ctx: PregateContext, guard: Guard, env: NodeJS.ProcessEnv): { prior?: string; carryNone?: string } {
+  const evidence = (args: string[]) => runScriptSync(EVIDENCE, args, { cwd: ctx.repoRoot, env, encoding: 'utf8', timeout: 600_000 });
+  let carryNone: string | undefined;
+  if (laneMapping(ctx.config.ship_lanes_from, guard.command)) {
+    const ci = evidence(['record-ci', '--label', `guard-${guard.id}`, '--base', ctx.base, '--', guard.command]);
+    const got = recordCiResult(String(ci.stderr ?? ''));
+    if (ci.status === 0 && got.runs) return { prior: got.notOwed ? `not owed: ${got.notOwed} runs=${got.runs}` : `carried runs=${got.runs}` };
+    carryNone = got.none ?? `record-ci exit ${ci.status}`;
+  }
+  const local = evidence(['passed', '--', guard.command]);
+  const hit = /^PASSED: (.+)$/m.exec(String(local.stdout ?? ''))?.[1];
+  return local.status === 0 && hit ? { prior: `reused ${hit}`, carryNone } : { carryNone };
+}
 
 async function runGuard(ctx: PregateContext, guard: Guard, env: NodeJS.ProcessEnv, dir: string): Promise<GuardRun> {
   const timeoutMs = guard.timeout_s ? guard.timeout_s * 1000 : ctx.timeoutMs;
@@ -53,9 +82,14 @@ async function run(ctx: PregateContext): Promise<CheckResult> {
   if (runtime.refusal) return { ...base, ...runtime.refusal, cause: 'environment', environment: launchCause('runtime', runtime.refusal.detail), lines: [`runtime: ${runtime.label}`, environmentLine(launchCause('runtime', runtime.refusal.detail))] };
   const dir = checkScratch(ctx.scratch, 'guards');
   const runs: GuardRun[] = [];
-  for (const g of selected) runs.push(await runGuard(ctx, g, runtime.env, dir));
+  for (const g of selected) {
+    const p = priorPass(ctx, g, runtime.env);
+    runs.push(p.prior ? { guard: g, exit: 0, timedOut: false, stalled: false, tail: [], log: '-', environment: null, ...p } : { ...(await runGuard(ctx, g, runtime.env, dir)), carryNone: p.carryNone });
+  }
   const lines = [`runtime: ${runtime.label}`];
   for (const r of runs) {
+    if (r.carryNone) lines.push(`CI_CARRY: none guard=${r.guard.id} (${r.carryNone})`);
+    if (r.prior) { lines.push(`GUARD: ${r.guard.id} ${r.prior}`); continue; }
     lines.push(r.stalled ? `GUARD: ${r.guard.id} stalled: no output for ${ctx.stallTimeoutMs / 1000} s${STALL_IDLE}; process group killed (log ${r.log})` : r.timedOut ? `GUARD: ${r.guard.id} timed out after ${r.guard.timeout_s ?? ctx.timeoutMs / 1000} s (log ${r.log})` : `GUARD: ${r.guard.id} exit=${r.exit} (log ${r.log})`);
     if (r.exit !== 0) lines.push(...r.tail.map(l => `  ${l}`));
     if (r.environment) lines.push(`  ${r.guard.id} ${environmentLine(r.environment)}`);
@@ -68,7 +102,8 @@ async function run(ctx: PregateContext): Promise<CheckResult> {
   if (failed.length) return { ...withRuns, status: 'fail', cause: 'diff', code: 'PREGATE_GUARD_FAILED', detail: `${failed.length} guard(s) failed: ${failed.map(r => r.guard.id).join(', ')}${timedOut.length ? `; timed out: ${timedOut.map(r => r.guard.id).join(', ')}` : ''}${blocked.length ? `; blocked by the environment: ${blocked.map(r => r.guard.id).join(', ')}` : ''}`, fix: fixOf(failed) };
   if (blocked.length) return environmentResult(withRuns, blocked[0]!.environment!, `${blocked.length} guard(s) could not run on this machine: ${blocked.map(r => `${r.guard.id} (${r.environment!.kind})`).join(', ')}${timedOut.length ? `; timed out: ${timedOut.map(r => r.guard.id).join(', ')}` : ''}`);
   if (timedOut.length) return { ...withRuns, status: 'incomplete', code: timedOut.some(r => r.stalled) ? 'PREGATE_STALLED' : 'PREGATE_INCOMPLETE', detail: `${timedOut.length} guard(s) did not finish: ${timedOut.map(r => `${r.guard.id} (${r.stalled ? 'stalled' : 'timed out'})`).join(', ')}`, fix: 'fix the hang, or raise the guard\'s timeout_s, --timeout or --stall-timeout; an unfinished guard never passes' };
-  return { ...withRuns, detail: `${runs.length} guard(s) passed: ${runs.map(r => r.guard.id).join(', ')}` };
+  const prior = runs.filter(r => r.prior).length;
+  return { ...withRuns, detail: `${runs.length} guard(s) passed: ${runs.map(r => r.guard.id).join(', ')}${prior ? ` (${prior} from an earlier pass at this tree)` : ''}` };
 }
 
 export const guardsCheck: CheckDef = { id: 'guards', stage: 'preflight', tier: 2, downgradable: false, needsRepoCommands: true, run };

lib/pregate/checks/lanes.ts

@@ -40,7 +40,7 @@ import { selectLanes, type Selection } from '../lane-selection';
 import { launchRuntime } from '../runtime';
 import { cargoModel, type CargoModel } from '../rust';
 import { adapterFor, readRange, STALL_IDLE, supervise, type Counter, type Supervised } from '../supervise';
-import { verifyFromRun, type RunProfile } from '../../run-evidence';
+import { ranFiles, verifyFromRun, type RunProfile } from '../../run-evidence';
 import { matchesAny } from '../../ship-policy';
 import type { CheckDef, CheckResult, PregateContext, RemoteObligation } from '../types';
 
@@ -643,9 +643,10 @@ function fromRun(ctx: PregateContext, sel: Selection): { line: string; passed: s
   const names = 'error' in check ? [] : fromRunProfiles(ctx, check.profiles);
   const v = 'error' in check ? { ok: false as const, reason: 'profiles_unavailable', detail: check.error } : verifyFromRun(check, ref, names, ctx.wtree, ctx.head);
   if (!v.ok) return { line: `REUSE: refused reason=${v.reason} — ${v.detail}; every selected test runs here`, passed: [] };
-  const ran = new Set(v.evidence.files);
+  const ran = new Set(ranFiles(v.evidence));
   const passed = sel.localTests.filter(t => ran.has(t));
-  return { line: `REUSE: accepted ${passed.length} of ${sel.localTests.length} selected local test file(s) from ${v.receipt}; ${sel.localTests.length - passed.length} still run`, passed, receipt: v.receipt };
+  const skipped = sel.localTests.filter(t => v.evidence.skipped?.includes(t)).length;
+  return { line: `REUSE: accepted ${passed.length} of ${sel.localTests.length} selected local test file(s) from ${v.receipt}; ${sel.localTests.length - passed.length} still run${skipped ? ` (${skipped} skipped every test in the run)` : ''}`, passed, receipt: v.receipt };
 }
 
 /**

lib/pregate/checks/literals.ts

@@ -57,10 +57,10 @@ export function constantsIn(text: string): Map<string, string> {
   return out;
 }
 
-/** Named numeric call sites (`timeout: 5000`) keyed by name; the last value per name wins, which is enough to spot a change. */
-export function callLiteralsIn(text: string): Map<string, string> {
-  const out = new Map<string, string>();
-  for (const m of text.matchAll(CALL_PATTERN)) out.set(m[1]!, m[2]!);
+/** Named numeric call sites (`timeout: 5000`) keyed by name, every value in source order. */
+export function callLiteralsIn(text: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const m of text.matchAll(CALL_PATTERN)) out.set(m[1]!, [...(out.get(m[1]!) ?? []), m[2]!]);
   return out;
 }
 
@@ -69,7 +69,14 @@ export function changedLiterals(file: string, oldText: string, newText: string):
   const oldC = constantsIn(oldText); const newC = constantsIn(newText);
   for (const [name, old] of oldC) { const now = newC.get(name); if (now !== undefined && now !== old) out.push({ name, old, new: now, file }); }
   const oldCall = callLiteralsIn(oldText); const newCall = callLiteralsIn(newText);
-  for (const [name, old] of oldCall) { const now = newCall.get(name); if (now !== undefined && now !== old && !oldC.has(name)) out.push({ name, old, new: now, file }); }
+  for (const [name, olds] of oldCall) {
+    if (oldC.has(name)) continue;
+    const added = [...(newCall.get(name) ?? [])];
+    const removed = olds.filter(v => { const i = added.indexOf(v); if (i >= 0) added.splice(i, 1); return i < 0; });
+    if (!added.length) continue;
+    const seen = new Set<string>();
+    removed.forEach((old, i) => { if (!seen.has(old)) { seen.add(old); out.push({ name, old, new: added[Math.min(i, added.length - 1)]!, file }); } });
+  }
   return out;
 }
 

lib/pregate/checks/strays.ts

@@ -12,7 +12,7 @@ import type { CheckDef, CheckResult, PregateContext } from '../types';
 
 /** Conventional root files a repo adds without a declaration. */
 export const ROOT_OK = /^(?:README|LICENSE|LICENCE|NOTICE|CHANGELOG|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|AUTHORS|VERSION|Makefile|Dockerfile|Procfile|Gemfile|Rakefile|Cargo\.(?:toml|lock)|go\.(?:mod|sum)|package(?:-lock)?\.json|bun\.lockb?|pnpm-lock\.yaml|yarn\.lock|tsconfig[\w.-]*\.json|bunfig\.toml|pyproject\.toml|pubspec\.(?:yaml|lock)|analysis_options\.yaml|dart_test\.yaml|requirements[\w.-]*\.txt|setup\.(?:py|cfg)|\.[\w.-]+|[\w.-]+\.config\.[cm]?[jt]s|[\w.-]+\.md)$/i;
-export const STRAY_NAME = /^(?:zz-|tmp|temp|scratch|debug-|probe)|\.(?:orig|rej|swp|swo|bak|tmp)$|~$|^\.DS_Store$|^Thumbs\.db$/i;
+export const STRAY_NAME = /^(?:zz-|tmp|scratch)|\.(?:orig|rej|swp|swo|bak|tmp)$|~$|^\.DS_Store$|^Thumbs\.db$/i;
 
 function run(ctx: PregateContext): CheckResult {
   const inputs = baseInputs(ctx);

lib/pregate/config.ts

@@ -46,9 +46,13 @@
  *                 tree, the command listing the gate's test files they must
  *                 cover, and the command naming the selected files the gate
  *                 itself never runs (gstack: paid files)
- *   ship_lanes_from exact /ship lane command → `{ profiles, inventory }`: the
- *                 run profiles whose verified runs at HEAD's tree carry that
- *                 lane, and the command listing its test files (lib/ci-carry.ts)
+ *   ship_lanes_from exact /ship lane command → `{ profiles, inventory }` or
+ *                 `{ profiles, jobs }`: the run profiles whose verified runs
+ *                 at HEAD's tree carry that lane, and either the command
+ *                 listing its test files or the CI jobs that run it (a lane
+ *                 with no test files, GST-1189), plus optional `aliases`:
+ *                 other exact commands for the same lane (GST-1190)
+ *                 (lib/ci-carry.ts)
  *   allowlist     `{ finding, paths?, pattern?, reason }` entries the `secrets`
  *                 check accepts as benign: a gstack-redact finding id or a
  *                 non-secret category, scoped by path globs and/or a regex
@@ -74,7 +78,8 @@ import { shipLanesErrors, type ShipLaneMapping } from '../ci-carry';
 import type { ResultCodeName } from '../result-codes';
 import { runProfileErrors, type RemoteGateRuns, type RunProfile } from '../run-evidence';
 import { sealedErrors } from '../sealed-guard';
-import { containedRelative, globToRegExp } from '../ship-policy';
+import { containedRelative, globToRegExp, runningGstackVersion, SHIP_POLICY_PATH } from '../ship-policy';
+import { cmpVersion, parseVersion } from '../version-source';
 
 export const PREGATE_CONFIG_PATH = '.gstack/pregate.json';
 export const PREGATE_CONFIG_SCHEMA = 'https://github.com/garrytan/gstack/docs/pregate.md#pregate-v1';
@@ -291,6 +296,22 @@ function git(cwd: string, args: string[]): { ok: boolean; out: string } {
   return { ok: r.status === 0 && !r.error, out: (r.stdout ?? '').trim() };
 }
 
+/**
+ * GST-1190: an unknown key in a policy whose project floor (min_gstack_version in the same tree's ship-policy.json) is
+ * above this gstack belongs to a newer gstack. It still refuses, but as an upgrade, not as a typo.
+ */
+function newerGstackErrors(parsed: { config: PregateConfig; errors: ConfigError[]; declaresLanes: boolean }, policyText: string | null): typeof parsed {
+  const unknown = (e: ConfigError) => e.message.startsWith('unknown key');
+  if (!policyText || !parsed.errors.some(unknown)) return parsed;
+  let min: unknown;
+  try { min = (JSON.parse(policyText) as Record<string, unknown> | null)?.min_gstack_version; } catch { return parsed; }
+  const running = runningGstackVersion();
+  const want = typeof min === 'string' ? parseVersion(min) : null;
+  const have = parseVersion(running);
+  if (!want || !have || cmpVersion(want, have) <= 0) return parsed;
+  return { ...parsed, errors: parsed.errors.map(e => unknown(e) ? { ...e, code: 'PREGATE_GSTACK_TOO_OLD' as const, message: `needs gstack >= ${min as string}; upgrade (this gstack is ${running} and does not know this key)` } : e) };
+}
+
 export function loadConfigFromBase(repoRoot: string, base: string, knownChecks: readonly string[] = []): ConfigLoad {
   const ref = `origin/${base.replace(/^origin\//, '')}`;
   const sha = git(repoRoot, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
@@ -302,13 +323,15 @@ export function loadConfigFromBase(repoRoot: string, base: string, knownChecks:
     if (!entry.ok || entry.out) return { unavailable: true, base: base.replace(/^origin\//, ''), detail: `${ref}:${PREGATE_CONFIG_PATH} could not be read and git cannot confirm it is absent` };
     return { config: DEFAULT_CONFIG, errors: [], present: false, label: `${ref}@${sha.out.slice(0, 12)} (no ${PREGATE_CONFIG_PATH})`, kind: 'none' };
   }
-  return { ...parseConfig(show.out, knownChecks), present: true, label: `${ref}@${sha.out.slice(0, 12)}:${PREGATE_CONFIG_PATH}`, kind: 'base' };
+  const policy = git(repoRoot, ['show', `${sha.out}:${SHIP_POLICY_PATH}`]);
+  return { ...newerGstackErrors(parseConfig(show.out, knownChecks), policy.ok ? policy.out : null), present: true, label: `${ref}@${sha.out.slice(0, 12)}:${PREGATE_CONFIG_PATH}`, kind: 'base' };
 }
 
 export function loadConfigFromHead(repoRoot: string, knownChecks: readonly string[] = []): ConfigLoad {
   const file = path.join(repoRoot, PREGATE_CONFIG_PATH);
   if (!fs.existsSync(file)) return { config: DEFAULT_CONFIG, errors: [], present: false, label: `head (no ${PREGATE_CONFIG_PATH})`, kind: 'none' };
-  return { ...parseConfig(fs.readFileSync(file, 'utf8'), knownChecks), present: true, label: `head (unreviewed) ${PREGATE_CONFIG_PATH}`, kind: 'head' };
+  const policy = path.join(repoRoot, SHIP_POLICY_PATH);
+  return { ...newerGstackErrors(parseConfig(fs.readFileSync(file, 'utf8'), knownChecks), fs.existsSync(policy) ? fs.readFileSync(policy, 'utf8') : null), present: true, label: `head (unreviewed) ${PREGATE_CONFIG_PATH}`, kind: 'head' };
 }
 
 /** A symlink to nothing on the way to `file` (a dotfiles link not yet cloned): a policy the user meant to have, not an absent one. */
@@ -365,7 +388,7 @@ export function explainConfig(): string {
     'remote_gate: the repo\'s remote test gate command; under 8 cores the test tier becomes a requires-remote obligation naming it, and gstack-pregate --remote runs it (it must print PREGATE_REMOTE: tree=<tree> tests=<n> failed=<n>) (docs/pregate.md#remote-gate)',
     'run_profiles: name → { workflow, events, jobs, artifact, max_age_hours?, os? }; the GitHub Actions runs gstack-pregate clear --run verifies as evidence on the identical tree (docs/pregate.md#run-evidence)',
     'remote_gate_runs: { profiles, inventory, skipped? }; the run profiles that together clear the remote gate obligation, the command listing the gate\'s test files they must cover, and an optional command printing which selected files (PREGATE_FILES_FILE) the gate itself does not run, which then need no run (docs/pregate.md#run-evidence)',
-    'ship_lanes_from: exact /ship lane command → { profiles, inventory }; a verified run of each profile at HEAD\'s clean tree whose tree.json covers the inventory carries the lane instead of running it again (docs/pregate.md#ci-carry)',
+    'ship_lanes_from: exact /ship lane command → { profiles, inventory } or { profiles, jobs }, with optional aliases (other exact commands for the same lane); a verified run of each profile at HEAD\'s clean tree whose tree.json covers the inventory, or whose newest attempt ran every named job to success, carries the lane instead of running it again (docs/pregate.md#ci-carry)',
     `allowlist: [{ finding, paths?, pattern?, reason }]: benign findings the secrets check accepts and names as allowlisted. finding is a gstack-redact id (env.kv, google.api_key, pii.phone.e164, …) or a category (${ALLOWLISTABLE_CATEGORIES.join(', ')}); paths are globs; pattern is a regex matched at the finding's position in the added line; one of the two is required, reason always. Never ${NON_ALLOWLISTABLE.join(' or ')} or engine.* (docs/pregate.md#allowlist)`,
     'no .gstack/pregate.json on the base: <state root>/projects/<slug>/pregate.json is read instead (state root: GSTACK_STATE_ROOT, else GSTACK_HOME, else GSTACK_STATE_DIR, else a gstack plugin data dir, else ~/.gstack, per docs/state-root.md; run --explain prints the resolved path; outside the repo, so a PR cannot reach it; a path inside the checkout is ignored)',
   ].join('\n') + '\n';

lib/pregate/index.ts

@@ -267,7 +267,7 @@ function userPolicyChange(file: PregateFile): string | null {
 
 export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck; flaky?: FlakyInput }
 /** What a run clear needs: the base branch's run profiles, the verifier's dependencies, the clock, and the remote gate's inventory. */
-export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string }; failures?: FailureDeps }
+export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; unchanged?: (p: RunProfile) => string | null; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string }; failures?: FailureDeps }
 export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution; exception?: PregateException } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
 
 /**

lib/pregate/run-check.ts

@@ -11,20 +11,58 @@ 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 { ghArtifactDeps, ghRunDeps, runInventory } from '../run-evidence';
+import { ghArtifactDeps, ghRunDeps, runInventory, type RunProfile } from '../run-evidence';
 import { wtreeFingerprint } from '../script-invocation';
 import { resolveBaseBranch } from '../ship-policy';
 import { normalizeRemoteUrl } from '../ship-queue-train-record';
 import { REMOTE_GATE_LANE } from './checks/lanes';
-import { PREGATE_CONFIG_PATH, isConfigUnavailable, loadConfigFromBase } from './config';
+import { PREGATE_CONFIG_PATH, isConfigUnavailable, loadConfigFromBase, loadConfigFromHead } from './config';
 import type { RunCheck } from './index';
 
 /**
- * `profiled` says whether `lane` may have a run profile: an unreadable base counts as profiled, so a lane is
- * recorded unverified only once the base shows it has none.
+ * Null when a skippable profile's workflow, its declared `scripts` and every repo path its gate job names are byte-identical
+ * at HEAD and origin/<base> (GST-1190); else the first that differs. Named paths are read from the gate job's block in the base
+ * workflow (after `${{ … }}` prefixes, and also under each working-directory), plus package.json when the job runs a package
+ * script. Files the gate reaches indirectly (imports, a package script's own files) count only when `scripts` declares them.
  */
-export function buildRunCheck(root: string, lane: string | null, allowRepoCommands: boolean, base = resolveBaseBranch(root)): RunCheck | { error: string; profiled?: boolean } {
-  const loaded = loadConfigFromBase(root, base);
+export function gateInputsChanged(root: string, base: string, p: RunProfile): string | null {
+  const ref = `origin/${base.replace(/^origin\//, '')}`;
+  const wf = `.github/workflows/${p.workflow}`;
+  const gate = p.skippable?.gate;
+  if (!gate) return 'the profile names no gate job';
+  const blob = (rev: string, f: string) => { const r = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}:${f}`], { cwd: root, encoding: 'utf8', timeout: 30_000 }); return r.status === 0 ? r.stdout.trim() : null; };
+  const show = spawnSync('git', ['show', `${ref}:${wf}`], { cwd: root, encoding: 'utf8', timeout: 30_000, maxBuffer: 8 * 1024 * 1024 });
+  if (show.status !== 0) return `${wf} is not on ${ref}`;
+  const lines = show.stdout.split('\n');
+  const jobsAt = lines.findIndex(l => /^jobs:\s*$/.test(l));
+  const blocks: string[][] = [];
+  for (let i = jobsAt + 1; jobsAt >= 0 && i < lines.length && !/^\S/.test(lines[i]!); i++) {
+    if (/^  [\w-]+:\s*$/.test(lines[i]!)) blocks.push([lines[i]!]);
+    else blocks.at(-1)?.push(lines[i]!);
+  }
+  const block = blocks.find(b => b[0]!.trim() === `${gate}:` || b.some(l => /^    name:/.test(l) && l.trim() === `name: ${gate}`));
+  if (!block) return `${wf} on ${ref} has no job ${gate}`;
+  const text = block.join('\n');
+  const dirs = ['', ...[...text.matchAll(/working-directory:\s*['"]?([\w.\/-]+)/g)].map(m => `${m[1]!.replace(/^\.?\/+|\/+$/g, '')}/`)];
+  const tokens = [...text.matchAll(/[\w.\/-]+/g)].map(m => m[0]).filter(t => t.includes('/') || /\.(sh|ts|js|mjs|cjs|py|rb)$/.test(t));
+  const named = [...new Set(tokens.flatMap(t => dirs.map(d => path.posix.normalize(d + t.replace(/^\.?\/+/, ''))).filter(n => !n.startsWith('..'))))];
+  const pkg = /\b(bun|npm|pnpm|yarn)\s+(run\s+)?[\w:-]+/.test(text) ? dirs.map(d => `${d}package.json`) : [];
+  for (const f of [wf, ...(p.skippable!.scripts ?? []), ...named, ...pkg]) {
+    const a = blob(ref, f);
+    const b = blob('HEAD', f);
+    if (a === null && b === null && f !== wf && !p.skippable!.scripts?.includes(f)) continue;
+    if (a === null || a !== b) return `${f} differs from ${ref}`;
+  }
+  return null;
+}
+
+/**
+ * `profiled` says whether `lane` may have a run profile: an unreadable base counts as profiled, so a lane is
+ * recorded unverified only once the base shows it has none. `policy: 'head'` reads the branch's profiles instead, only
+ * for gstack-ship-preflight --simulate, a dry run that records and clears nothing.
+ */
+export function buildRunCheck(root: string, lane: string | null, allowRepoCommands: boolean, base = resolveBaseBranch(root), policy: 'base' | 'head' = 'base'): RunCheck | { error: string; profiled?: boolean } {
+  const loaded = policy === 'head' ? loadConfigFromHead(root) : loadConfigFromBase(root, base);
   if (isConfigUnavailable(loaded)) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is unreadable (${loaded.detail}); run profiles come only from the base`, profiled: true };
   if (loaded.errors.length) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is invalid: ${loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}`, profiled: true };
   const origin = spawnSync('git', ['config', '--get', 'remote.origin.url'], { cwd: root, encoding: 'utf8', timeout: 30_000 });
@@ -32,6 +70,7 @@ export function buildRunCheck(root: string, lane: string | null, allowRepoComman
   if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === null ? false : lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] };
   return {
     repo, deps: ghRunDeps(repo, root), failures: ghArtifactDeps(repo), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
+    unchanged: p => gateInputsChanged(root, base, p),
     inventory: (command, tree, selected) => {
       if (!allowRepoCommands) return { error: 'the inventory command is a pin-file command; pass --allow-repo-commands' };
       const at = () => { const fp = wtreeFingerprint({ cwd: root }); return 'tree' in fp ? fp.tree : null; };

lib/restamp.ts

@@ -313,7 +313,7 @@ export function branchAddedLines(cwd: string, since: string, files: string[], to
   return out;
 }
 
-const escapeRegExp = (t: string) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+export const escapeRegExp = (t: string) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const VERSION_RE = '(?<v>\\d+(?:\\.\\d+){1,3})(?![0-9.])';
 /**
  * The built-in stamp forms as scanners, the version in the `v` group: `(was X)`, `since: X` and `vX`.

lib/result-codes-release.ts

@@ -16,6 +16,11 @@ export const RELEASE_RESULT_CODES = {
     summary: 'the ship policy sets min_gstack_version above this gstack, so this gstack refuses to read it',
     fix: 'upgrade gstack (bin/gstack-upgrade, or the session install with --for <skill>) to the version named, then rerun',
   },
+  PREGATE_GSTACK_TOO_OLD: {
+    anchor: 'pregate-gstack-too-old',
+    summary: 'the pregate policy uses a key this gstack does not know, and the project floor (min_gstack_version in .gstack/ship-policy.json) is above this gstack, so the key belongs to a newer gstack; the policy stays refused',
+    fix: 'upgrade gstack (bin/gstack-upgrade, or the session install with --for <skill>) to at least the version named, then rerun',
+  },
   QUEUE_NOT_READY: {
     anchor: 'queue-not-ready',
     summary: 'the lane is not ready to report: the working tree, HEAD or CI state does not match the pushed PR head',

lib/run-evidence.ts

@@ -42,7 +42,11 @@ import * as path from 'node:path';
 import { sha256Hex, writeReceipt } from './egress-receipt';
 import { runBashSync } from './script-invocation';
 
-export interface RunProfile { workflow: string; events: string[]; jobs: string[]; artifact: string; max_age_hours?: number; os?: string }
+/**
+ * `skippable` (GST-1190): named jobs the workflow may skip by path; a skip counts only in a pull_request run whose `gate` job
+ * succeeded, with the workflow, the declared `scripts` and any path the gate's steps name matching origin/<base> byte for byte.
+ */
+export interface RunProfile { workflow: string; events: string[]; jobs: string[]; artifact: string; max_age_hours?: number; os?: string; skippable?: { jobs: string[]; gate: string; scripts: string[] } }
 export interface RemoteGateRuns { profiles: string[]; inventory: string; skipped?: string }
 export interface ApiRun {
   id: number; run_attempt: number; status: string; conclusion: string | null; event: string; head_sha: string;
@@ -50,7 +54,7 @@ export interface ApiRun {
   repository?: { full_name: string } | null; head_repository?: { full_name: string } | null;
 }
 export interface ApiJob { name: string; conclusion: string | null; completed_at?: string | null }
-export interface TreeRecord { run_id?: unknown; run_attempt?: unknown; event?: unknown; sha?: unknown; head_sha?: unknown; tree?: unknown; reused?: unknown; reuse?: unknown; os?: unknown; files?: unknown; tests?: unknown }
+export interface TreeRecord { run_id?: unknown; run_attempt?: unknown; event?: unknown; sha?: unknown; head_sha?: unknown; tree?: unknown; reused?: unknown; reuse?: unknown; os?: unknown; files?: unknown; tests?: unknown; skipped_files?: unknown }
 
 /** What a red run's reader needs beyond RunDeps (lib/pregate/flaky-exception.ts): every file of one artifact, and a pull request's head. */
 export interface RunArtifactDeps {
@@ -69,14 +73,15 @@ export interface RunDeps {
 }
 
 export type RunRefusal = 'run_ref_invalid' | 'other_repository' | 'fork_run' | 'workflow_mismatch' | 'event_mismatch' | 'run_in_progress'
-  | 'run_not_success' | 'job_missing' | 'job_ambiguous' | 'job_not_success' | 'artifact_missing' | 'artifact_mismatch'
+  | 'run_not_success' | 'job_missing' | 'job_ambiguous' | 'job_skipped' | 'job_not_success' | 'artifact_missing' | 'artifact_mismatch'
   | 'artifact_reused' | 'tree_mismatch' | 'newer_run_vetoes' | 'run_changed' | 'run_stale' | 'os_mismatch' | 'api_error';
-export interface RunEvidence { run_id: number; run_attempt: number; head_sha: string; tree: string; profile: string; event: string; finished_at: string; files: string[]; tests: number | null }
+/** `skipped`: the files whose every test skipped on the runner (tree.json `skipped_files`, GST-1190); undefined when an older tree.json does not say. */
+export interface RunEvidence { run_id: number; run_attempt: number; head_sha: string; tree: string; profile: string; event: string; finished_at: string; files: string[]; tests: number | null; skipped?: string[]; skipped_jobs?: string[] }
 export type RunVerdict = { ok: true; evidence: RunEvidence } | { ok: false; reason: RunRefusal; detail: string };
 
 const SHA = /^[0-9a-f]{40}$/;
 const RUN_EVENTS = ['push', 'workflow_dispatch', 'pull_request'];
-const PROFILE_KEYS = ['workflow', 'events', 'jobs', 'artifact', 'max_age_hours', 'os'];
+const PROFILE_KEYS = ['workflow', 'events', 'jobs', 'artifact', 'max_age_hours', 'os', 'skippable'];
 const WORKFLOW_FILE = /^[A-Za-z0-9_.-]+\.ya?ml$/;
 const NAME = /^[A-Za-z0-9_.\/-]{1,128}$/;
 export const DEFAULT_MAX_AGE_HOURS = 24;
@@ -113,6 +118,14 @@ export function runProfileErrors(profiles: unknown, gateRuns: unknown): Array<{
       if (typeof p.artifact !== 'string' || !NAME.test(p.artifact)) errors.push({ path: `${at}.artifact`, message: 'must be the artifact name holding tree.json' });
       if ('max_age_hours' in p && (!Number.isInteger(p.max_age_hours) || (p.max_age_hours as number) < 1 || (p.max_age_hours as number) > 168)) errors.push({ path: `${at}.max_age_hours`, message: 'must be an integer from 1 to 168' });
       if ('os' in p && (typeof p.os !== 'string' || !/^(Linux|macOS|Windows)$/.test(p.os))) errors.push({ path: `${at}.os`, message: 'must be Linux, macOS or Windows' });
+      if ('skippable' in p) {
+        const s = p.skippable as Record<string, unknown> | null;
+        const names = (v: unknown) => Array.isArray(v) && v.length > 0 && v.length <= 32 && v.every(x => typeof x === 'string' && !!x.trim() && x.length <= 128);
+        const repoPath = (x: unknown) => typeof x === 'string' && !!x && !x.startsWith('/') && !x.split('/').includes('..') && !/[\0\r\n]/.test(x);
+        if (!s || typeof s !== 'object' || Array.isArray(s) || Object.keys(s).some(k => !['jobs', 'gate', 'scripts'].includes(k)) || !names(s.jobs) || typeof s.gate !== 'string' || !s.gate.trim()
+          || (s.jobs as string[]).includes(s.gate as string) || !Array.isArray(s.scripts) || !s.scripts.length || !s.scripts.every(repoPath))
+          errors.push({ path: `${at}.skippable`, message: 'must be { jobs: [job names], gate: <the job that decides the skip>, scripts: [every repo file the gate reads] }, the gate not among the jobs' });
+      }
     }
   }
   if (gateRuns !== undefined && gateRuns !== null) {
@@ -135,13 +148,13 @@ export function runProfileErrors(profiles: unknown, gateRuns: unknown): Array<{
 const fail = (reason: RunRefusal, detail: string): RunVerdict => ({ ok: false, reason, detail });
 /** When a run's newest attempt started. A run vetoes the candidate when it started at or after the second the candidate was created: a red re-run of an older run counts, and re-running the candidate does not hide a failure in between. */
 const started = (r: ApiRun): string => r.run_started_at ?? r.created_at ?? '';
-const normalPath = (f: string): string => f.replace(/^(\.\/)+/, '');
+export const normalPath = (f: string): string => f.replace(/^(\.\/)+/, '');
 
 /**
  * The verdict for run `runRef` under `profile`. `vetoHeads` are further heads
  * whose newer runs of the same workflow can veto (the consumer's own head).
  */
-export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; profileName: string; profile: RunProfile; vetoHeads?: string[]; now: Date }): RunVerdict {
+export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; profileName: string; profile: RunProfile; vetoHeads?: string[]; now: Date; unchanged?: (p: RunProfile) => string | null }): RunVerdict {
   const id = parseRunRef(o.runRef, o.repo);
   if (id === null) return fail('run_ref_invalid', `${JSON.stringify(o.runRef)} is not a run id or a run URL on ${o.repo}`);
   const p = o.profile;
@@ -162,10 +175,22 @@ export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; prof
     const maxAge = p.max_age_hours ?? DEFAULT_MAX_AGE_HOURS;
     if (!Number.isFinite(finished)) return fail('api_error', `${at} has no completion time`);
     if (o.now.getTime() - finished > maxAge * 3600_000) return fail('run_stale', `${at} finished ${finishedAt}, more than ${maxAge} h before now`);
+    const skippedJobs: string[] = [];
     for (const name of p.jobs) {
       const hits = jobs.filter(j => j.name === name);
       if (hits.length === 0) return fail('job_missing', `${at} has no job named ${name}`);
       if (hits.length > 1) return fail('job_ambiguous', `${at} has ${hits.length} jobs named ${name}`);
+      if (hits[0]!.conclusion === 'skipped') {
+        const skip = p.skippable;
+        if (!skip?.jobs.includes(name)) return fail('job_skipped', `${at}'s ${name} job was skipped`);
+        if (run.event !== 'pull_request') return fail('job_skipped', `${at}'s ${name} job was skipped in a ${run.event} run; only a pull_request run's gate diffs against the PR base, so only its skip counts`);
+        const gate = jobs.filter(j => j.name === skip.gate);
+        if (gate.length !== 1 || gate[0]!.conclusion !== 'success') return fail('job_skipped', `${at}'s ${name} job was skipped and its gate job ${skip.gate} ${gate.length === 1 ? `concluded ${gate[0]!.conclusion}` : gate.length ? 'is ambiguous' : 'is missing'}`);
+        const changed = o.unchanged ? o.unchanged(p) : 'no base copy of the workflow was compared';
+        if (changed) return fail('job_skipped', `${at}'s ${name} job was skipped, but ${changed}, so this branch decided the skip`);
+        skippedJobs.push(name);
+        continue;
+      }
       if (hits[0]!.conclusion !== 'success') return fail('job_not_success', `${at}'s ${name} job concluded ${hits[0]!.conclusion}`);
     }
     const heads = [...new Set([run.head_sha, ...(o.vetoHeads ?? []).filter(h => SHA.test(h))])];
@@ -195,11 +220,13 @@ export function verifyRun(deps: RunDeps, o: { repo: string; runRef: string; prof
     if (p.os && !oses.includes(p.os)) return fail('os_mismatch', `${at} ran on ${oses.filter(Boolean).map(String).join(', ') || 'an unrecorded OS'}; ${o.profileName} requires ${p.os}`);
     if (rec.files !== undefined && (!Array.isArray(rec.files) || rec.files.some(f => typeof f !== 'string'))) return fail('artifact_mismatch', `${at}'s ${p.artifact} files is not a list of paths`);
     if (rec.tests !== undefined && (!Number.isInteger(rec.tests) || (rec.tests as number) < 0)) return fail('artifact_mismatch', `${at}'s ${p.artifact} tests is not a non-negative integer`);
+    if (rec.skipped_files !== undefined && (!Array.isArray(rec.skipped_files) || rec.skipped_files.some(f => typeof f !== 'string'))) return fail('artifact_mismatch', `${at}'s ${p.artifact} skipped_files is not a list of paths`);
     const files = ((rec.files ?? []) as string[]).map(normalPath);
     const tests = rec.tests === undefined ? null : (rec.tests as number);
     const changed = runChanged(deps, id, run.run_attempt);
     if (changed) return fail('run_changed', changed);
-    return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files, tests } };
+    const skipped = rec.skipped_files === undefined ? {} : { skipped: (rec.skipped_files as string[]).map(normalPath) };
+    return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files, tests, ...skipped, ...(skippedJobs.length ? { skipped_jobs: skippedJobs } : {}) } };
   } catch (e: any) {
     return fail('api_error', `reading run ${id} failed: ${String(e?.message ?? e).slice(0, 300)}`);
   }
@@ -219,13 +246,21 @@ export function runInventory(command: string, cwd: string, env?: Record<string,
 }
 
 /** The files in `inventory` that no verified run's tree.json lists. */
-export function uncoveredFiles(inventory: string[], evidence: RunEvidence[]): string[] {
-  const ran = new Set(evidence.flatMap(e => e.files.map(normalPath)));
+/** A run's files minus the ones whose every test skipped there (GST-1190): only those ran anything. Older tree.json: all files. */
+export const ranFiles = (e: RunEvidence): string[] => { const skipped = new Set(e.skipped ?? []); return e.files.map(normalPath).filter(f => !skipped.has(f)); };
+
+/**
+ * The inventory files no run covers. `skipped: 'uncovered'` (a carry, which drops tests on a machine where they might run)
+ * also counts a file every test of which skipped in the run; `'covered'` (the remote gate, a Linux runner like CI) does not.
+ */
+export function uncoveredFiles(inventory: string[], evidence: RunEvidence[], skipped: 'uncovered' | 'covered' = 'covered'): string[] {
+  const ran = new Set(evidence.flatMap(e => (skipped === 'uncovered' ? ranFiles(e) : e.files.map(normalPath))));
   return inventory.filter(f => !ran.has(normalPath(f)));
 }
 
 /** What a run check reads: the repository, the verifier's dependencies, the base branch's profiles and the clock. */
-export interface RunSource { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date }
+/** `unchanged` (findCarry only): null when a profile's workflow and gate inputs match the base, else which file differs. */
+export interface RunSource { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date; unchanged?: (p: RunProfile) => string | null }
 export type FromRunVerdict = { ok: true; evidence: RunEvidence; receipt: string } | { ok: false; reason: string; detail: string };
 
 /**

lib/ship-bin-common.ts

@@ -10,6 +10,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fragmentSlug } from './changelog-fragments';
+import { laneMapping, recordCiResult, type ShipLaneMapping } from './ci-carry';
 import { isConfigUnavailable, loadConfigFromBase } from './pregate/config';
 import { parseUnifiedDiff, versionAtRef } from './restamp';
 import { branchSides, stampOnlyLine } from './stamp-only';
@@ -113,7 +114,8 @@ export function releasePaths(policy: Record<string, any> | null, cwd: string, re
  * added since the merge base with origin/<base>, and not added by the base since): after a lost slot and a merge of the
  * base its stale stamp is older than `ref`'s VERSION, so it must be at or newer than the fork point's version instead,
  * the bound gstack-restamp's stamp_paths stage uses (GST-895; the fork version itself since GST-963). A branch line is
- * named by its position, and with a kept VERSION only such a line may move (GST-979, GST-980).
+ * named by its position, and with a kept VERSION only such a line may move (GST-979, GST-980); on it a declared
+ * `stamp_placeholders` value may also become the new version inside a `stamp_patterns` template (GST-1026).
  */
 export function stampedFiles(policy: Record<string, any> | null, cwd: string, ref: string, base: string): string[] {
   const globs = Array.isArray(policy?.stamp_files) ? policy.stamp_files.filter((s: unknown): s is string => typeof s === 'string') : [];
@@ -123,11 +125,13 @@ export function stampedFiles(policy: Record<string, any> | null, cwd: string, re
   let after = '';
   try { after = extractVersion(fs.readFileSync(path.join(cwd, before.rel), 'utf8'), before.rel); } catch { return []; }
   if (!after) return [];
-  const templates = Array.isArray(policy?.stamp_patterns) ? policy.stamp_patterns.filter((s: unknown): s is string => typeof s === 'string') : [];
+  const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string') : []);
+  const templates = strings(policy?.stamp_patterns);
+  const placeholders = strings(policy?.stamp_placeholders);
   const diff = git(cwd, ['diff', '--unified=0', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', ref]);
   if (diff.status !== 0) return [];
   const side = branchSides(cwd, `origin/${base}`, 'HEAD', before.version, ref);
-  const stamp = (rel: string, removed: string, added: string, at: number): boolean => stampOnlyLine(removed, added, before.version, after, templates, side(rel), at);
+  const stamp = (rel: string, removed: string, added: string, at: number): boolean => stampOnlyLine(removed, added, before.version, after, templates, side(rel), at, placeholders);
   return parseUnifiedDiff(diff.stdout).filter(f => f.status === 'M' && !f.binary && !f.modeChanged && matchesAny(globs, f.path) && f.hunks.length > 0 &&
     f.hunks.every(h => h.removed.length === h.added.length && h.removed.every((line, i) => stamp(f.path, line, h.added[i]!, h.removedAt[i]!)))).map(f => f.path);
 }
@@ -171,15 +175,15 @@ export function laneConcurrency(mode: string | undefined, cpus = os.availablePar
   return cpus <= 4 ? 1 : Infinity;
 }
 
-export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; reused?: string; carryNone?: string }
+export interface LaneResult { label: string; exit: number | null; testsRan: string; log: string; carried?: string; reused?: string; carryNone?: string; notOwed?: string; here?: string }
 
-/** The base branch's `ship_lanes_from` entry for each lane whose command is a key, byte for byte (the ledger binds its sha256). */
-export function mappedLanes(cwd: string, base: string, list: { label: string; command: string }[]): Map<string, { profiles: string[]; inventory: string }> {
+/** The base branch's `ship_lanes_from` entry for each lane whose command is a key or a declared alias, byte for byte (the ledger binds its sha256). */
+export function mappedLanes(cwd: string, base: string, list: { label: string; command: string }[]): Map<string, ShipLaneMapping> {
   const loaded = loadConfigFromBase(cwd, base);
-  const map = new Map<string, { profiles: string[]; inventory: string }>();
+  const map = new Map<string, ShipLaneMapping>();
   if (isConfigUnavailable(loaded) || loaded.errors.length) return map;
   const from = loaded.config.ship_lanes_from;
-  for (const l of list) if (Object.prototype.hasOwnProperty.call(from, l.command)) map.set(l.label, from[l.command]!);
+  for (const l of list) { const m = laneMapping(from, l.command); if (m) map.set(l.label, m); }
   return map;
 }
 
@@ -189,9 +193,9 @@ export function mappedLanes(cwd: string, base: string, list: { label: string; co
  */
 export function carryLane(cwd: string, base: string, l: { label: string; command: string }): LaneResult {
   const rec = bin(cwd, 'gstack-evidence', ['record-ci', '--label', l.label, '--base', base, '--', l.command], 600_000);
-  const got = / tests_ran=(\d+) log=- source=ci runs=(\S+)/.exec(rec.stderr);
-  if (rec.status === 0 && got) return { label: l.label, exit: 0, testsRan: got[1]!, log: '-', carried: got[2]! };
-  return { label: l.label, exit: null, testsRan: 'unknown', log: '-', carryNone: /^CARRY_NONE: (.+)$/m.exec(rec.stderr)?.[1] ?? `record_failed: ${firstLine(rec.stderr)}` };
+  const got = recordCiResult(rec.stderr);
+  if (rec.status === 0 && got.runs) return { label: l.label, exit: 0, testsRan: got.files ? `${got.tests} (files)` : got.tests!, log: '-', carried: got.runs, ...(got.notOwed ? { notOwed: got.notOwed } : {}), ...(got.here ? { here: got.here } : {}) };
+  return { label: l.label, exit: null, testsRan: 'unknown', log: '-', carryNone: got.none ?? `record_failed: ${firstLine(rec.stderr)}` };
 }
 
 /**
@@ -201,7 +205,7 @@ export function carryLane(cwd: string, base: string, l: { label: string; command
  */
 export async function runLanes(cwd: string, list: { label: string; command: string }[], concurrency = Infinity, opts: { base?: string; reuse?: boolean } = {}): Promise<LaneResult[]> {
   const out: LaneResult[] = [];
-  const mapped = opts.base ? mappedLanes(cwd, opts.base, list) : new Map<string, { profiles: string[]; inventory: string }>();
+  const mapped = opts.base ? mappedLanes(cwd, opts.base, list) : new Map<string, ShipLaneMapping>();
   let next = 0;
   const worker = async () => {
     while (next < list.length) {
@@ -222,7 +226,8 @@ export async function runLanes(cwd: string, list: { label: string; command: stri
 
 /** Step 5's lane verdict: a lane passes on its runner count, never exit 0 alone; a carried lane names its CI runs. */
 export function laneLine(l: LaneResult): { line: string; ok: boolean } {
-  if (l.carried) return { line: `LANE: ${l.label} carried run=${l.carried} tests_ran=${l.testsRan}`, ok: true };
+  if (l.notOwed) return { line: `LANE: ${l.label} not owed: ${l.notOwed} run=${l.carried}`, ok: true };
+  if (l.carried) return { line: `LANE: ${l.label} carried run=${l.carried} tests_ran=${l.testsRan}${l.here ? ` ${l.here}` : ''}`, ok: true };
   const zero = l.exit === 0 && l.testsRan === '0';
   const state = l.exit !== 0 ? 'FAIL' : zero ? 'ZERO-RUN' : l.testsRan === 'unknown' ? 'pass (count unavailable)' : 'pass';
   return { line: `LANE: ${l.label} ${state} exit=${l.exit} tests_ran=${l.testsRan} log=${l.log}${l.reused ? ` reused=${l.reused}` : ''}`, ok: l.exit === 0 && !zero };

lib/ship-policy-stamps.ts

@@ -0,0 +1,35 @@
+/**
+ * Validation of the stamp policy keys (stamp_patterns templates and stamp_placeholders), split out of ship-policy.ts
+ * to keep that module under the module-size ratchet.
+ */
+import type { PolicyError } from './ship-policy';
+import { parseVersion } from './version-source';
+
+const MAX_TEMPLATES = 16;
+const MAX_TEMPLATE = 128;
+const MAX_PLACEHOLDERS = 16;
+const MAX_PLACEHOLDER = 32;
+export const VERSION_SLOT = '{version}';
+
+export function templateErrors(value: unknown, out: PolicyError[]): void {
+  if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_patterns', message: 'must be an array of literal templates' }); return; }
+  if (value.length > MAX_TEMPLATES) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_patterns', message: `more than ${MAX_TEMPLATES} templates` });
+  value.forEach((t, i) => {
+    const at = `stamp_patterns[${i}]`;
+    if (typeof t !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
+    if (t.split(VERSION_SLOT).length !== 2) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(t)} must contain exactly one ${VERSION_SLOT}` });
+    else if (t.length > MAX_TEMPLATE || /[\0\r\n]/.test(t)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one line of at most ${MAX_TEMPLATE} characters` });
+  });
+}
+
+export function placeholderErrors(value: unknown, out: PolicyError[]): void {
+  if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_placeholders', message: 'must be an array of literal placeholders' }); return; }
+  if (value.length > MAX_PLACEHOLDERS) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_placeholders', message: `more than ${MAX_PLACEHOLDERS} placeholders` });
+  value.forEach((p, i) => {
+    const at = `stamp_placeholders[${i}]`;
+    if (typeof p !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
+    if (!p.trim() || p.length > MAX_PLACEHOLDER || /[\0\r\n]/.test(p)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one non-empty line of at most ${MAX_PLACEHOLDER} characters` });
+    else if (p.includes(VERSION_SLOT)) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(p)} must not contain ${VERSION_SLOT}` });
+    else if (parseVersion(p)) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(p)} is a version, not a placeholder` });
+  });
+}

lib/ship-policy.ts

@@ -18,6 +18,8 @@ import * as path from 'node:path';
 import { defaultBaseBranch, noDefaultBaseLine } from './default-base';
 import { RESULT_CODES, type ResultCodeName } from './result-codes';
 import { cmpVersion, parseVersion } from './version-source';
+import { placeholderErrors, templateErrors } from './ship-policy-stamps';
+export { VERSION_SLOT } from './ship-policy-stamps';
 
 export const SHIP_POLICY_PATH = '.gstack/ship-policy.json';
 export const SHIP_POLICY_SCHEMA = 'https://github.com/garrytan/gstack/docs/ship-policy.md#schema-v1';
@@ -64,6 +66,8 @@ export interface ShipPolicy {
   stamp_files: string[];
   /** Literal stamp templates with one `{version}` slot, beside the built-in `(was X)`, `since: X`, `vX`; writer and classifier share them. */
   stamp_patterns: string[];
+  /** Placeholders (`TBD`) a restamp may replace with the new version inside a `stamp_patterns` template, on the branch's own lines only. */
+  stamp_placeholders: string[];
   /** The repo's own restamp, run first in the staging worktree with the target version; gstack's version writer is skipped. */
   restamp_command: string | null;
   /** Migration numbering: `{ dir, id }` where `id` is a regex with one capture group over the file name. */
@@ -161,6 +165,7 @@ export const DEFAULT_POLICY: ShipPolicy = {
   maintainers: [],
   stamp_files: [],
   stamp_patterns: [],
+  stamp_placeholders: [],
   restamp_command: null,
   migrations: null,
   gate_command: null,
@@ -193,6 +198,7 @@ export const POLICY_EXPLANATIONS: Record<PolicyKey, string> = {
   maintainers: 'GitHub logins treated as maintainers by /review contributor mode; empty uses repository push permission.',
   stamp_files: 'The repo’s stamp rule: globs of the only files that may differ by a stamp (version file, manifests, plugin trees, the PR’s own since: rows). Empty keeps gstack’s per-file rules; set, it applies before every rule.',
   stamp_patterns: 'Literal templates with exactly one {version} slot (at most 16, 128 characters each), for example `"version": "{version}"` or `since: \'{version}\'`; the restamp writer and the tree receipt use them beside (was X), since: X and vX.',
+  stamp_placeholders: 'Literal placeholders (at most 16, one line, 32 characters each, never `{version}` or a version), for example `["TBD"]`: a line the branch added that reads a placeholder in a stamp_patterns template (`since: \'TBD\'`) may become that template at the new version, and finish, the receipt carry and the tree receipt read it as a stamp. Empty (default) accepts no placeholder.',
   restamp_command: 'The repo’s own restamp, run first in gstack-restamp’s staging worktree (a clean checkout of HEAD) with the target version as its argument and in GSTACK_RESTAMP_VERSION; gstack’s version writer is skipped, output confinement still applies. Needs a clean caller tree and --allow-repo-commands.',
   migrations: '{ dir, id }: the migration directory and a regex with one capture group for the number in a file name; `gstack-pregate regate` reports MIGRATION_COLLISION against the base branch and every open PR.',
   gate_command: 'The repo’s full pre-merge gate command. gstack-ship-queue gate-ahead and ready print it for the caller to run (in the background or in CI); gstack never executes it. null when the repo has none.',
@@ -236,6 +242,7 @@ export const BUMP_NEVER_KEY_VERSION = '1.91.353.0';
 export const BASE_RED_KEY_VERSION = '1.91.374.0';
 /** `train.gates` and `train.land` are values of the older train key, so compatErrors checks them by value, as for bump: never. */
 export const TRAIN_GATES_KEY_VERSION = '1.92.0.0';
+export const STAMP_PLACEHOLDERS_KEY_VERSION = '1.94.16.0';
 export const REVIEW_EXCLUDE_KEY_VERSION = '1.93.33.0';
 export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
   bump: '1.91.73.0', queue_mode: '1.91.73.0', release_tool: '1.91.73.0', release_outputs: '1.91.73.0', stamp_paths: '1.91.73.0',
@@ -245,6 +252,7 @@ export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
   train: TRAIN_KEYS_VERSION, review_scope: REVIEW_SCOPE_KEY_VERSION, docs: DOCS_CAPS_KEY_VERSION,
   changelog_fragments: CHANGELOG_FRAGMENTS_KEY_VERSION,
   base_red: BASE_RED_KEY_VERSION, review_exclude_paths: REVIEW_EXCLUDE_KEY_VERSION,
+  stamp_placeholders: STAMP_PLACEHOLDERS_KEY_VERSION,
 };
 
 const newer = (a: string, b: string): boolean => cmpVersion(parseVersion(a)!, parseVersion(b)!) > 0;
@@ -274,9 +282,6 @@ const MAX_PATTERN = 256;
 const MAX_REGEX = 512;
 const MAX_COMMAND = 512;
 const SHA_RE = /^[0-9a-f]{7,64}$/;
-const MAX_TEMPLATES = 16;
-const MAX_TEMPLATE = 128;
-export const VERSION_SLOT = '{version}';
 
 function hasDotDot(p: string): boolean {
   return p.split(/[\\/]+/).some(seg => seg === '..');
@@ -343,17 +348,6 @@ function excludeErrors(value: unknown, out: PolicyError[]): void {
   });
 }
 
-function templateErrors(value: unknown, out: PolicyError[]): void {
-  if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_patterns', message: 'must be an array of literal templates' }); return; }
-  if (value.length > MAX_TEMPLATES) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_patterns', message: `more than ${MAX_TEMPLATES} templates` });
-  value.forEach((t, i) => {
-    const at = `stamp_patterns[${i}]`;
-    if (typeof t !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
-    if (t.split(VERSION_SLOT).length !== 2) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(t)} must contain exactly one ${VERSION_SLOT}` });
-    else if (t.length > MAX_TEMPLATE || /[\0\r\n]/.test(t)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one line of at most ${MAX_TEMPLATE} characters` });
-  });
-}
-
 function migrationErrors(value: unknown, out: PolicyError[]): void {
   const m = value as Record<string, unknown> | null;
   if (!m || typeof m !== 'object' || Array.isArray(m)) { out.push({ code: 'POLICY_INVALID', path: 'migrations', message: 'must be { dir, id } or null' }); return; }
@@ -497,6 +491,7 @@ export function validatePolicy(raw: unknown, opts: { gstackVersion?: string } =
   if ('release_outputs' in obj) listErrors('release_outputs', obj.release_outputs, errors, globError);
   if ('stamp_files' in obj) listErrors('stamp_files', obj.stamp_files, errors, globError);
   if ('stamp_patterns' in obj) templateErrors(obj.stamp_patterns, errors);
+  if ('stamp_placeholders' in obj) placeholderErrors(obj.stamp_placeholders, errors);
   if ('restamp_command' in obj && obj.restamp_command !== null) {
     const t = obj.restamp_command;
     if (typeof t !== 'string' || !t.trim()) errors.push({ code: 'POLICY_INVALID', path: 'restamp_command', message: 'must be a non-empty string or null' });

lib/ship-preflight.ts

@@ -8,8 +8,12 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { findCarry, laneMapping, mappingCoverage } from './ci-carry';
 import { defaultBaseBranch } from './default-base';
+import { isConfigUnavailable, loadConfigFromHead } from './pregate/config';
+import { buildRunCheck } from './pregate/run-check';
 import { classifyDiff } from './review-depth';
+import { wtreeFingerprint } from './script-invocation';
 import { audit } from './ship-audit';
 import { bin, carryNoneLine, firstLine, flagReader, gh, git, hostedOrigin, laneConcurrency, laneLine, lanes, Report, runLanes, shipPolicy, short } from './ship-bin-common';
 
@@ -20,6 +24,11 @@ export const PREFLIGHT_HELP = `gstack-ship-preflight — /ship Steps 1-3 and Ste
       --lanes serial|parallel   how Step 5 runs its lanes; unset, one at a time on 4 or fewer cores, all at once above
       --policy-from head   Step 5's pregate reads the branch's .gstack/pregate.json, which may only add test lanes
                            (a branch that adds the lane for a file it touches); anything else is PREGATE_HEAD_POLICY_LOOSENS
+  gstack-ship-preflight --tests-only --base <base> --policy-from head --simulate [--allow-repo-commands] --lane <label>=<command>...
+      a dry run that proves a new ship_lanes_from mapping: which lanes the branch's own map would carry from a verified
+      CI run at this tree. Every line starts SIMULATION:; no lane runs, no evidence or ledger row is written and no
+      obligation clears (a real carry reads origin/<base>'s map only). An inventory-mapped lane runs the branch's
+      inventory command, so it needs --allow-repo-commands. Exit 0 when every mapped lane would carry, else 1
   gstack-ship-preflight --audit --base <base> --out <dir>   the single reads and Steps 7-8's deterministic audits
       (CONTEXT, TODOS, COVERAGE_MAP, Coverage, PLAN_*, READER: coverage=needed|none plan=needed|none)
 
@@ -168,6 +177,40 @@ async function tests(cwd: string, base: string, list: { label: string; command:
   r.next('Step 6: select eval suites for prompt-related changes with the project\'s selector, then Step 7');
 }
 
+/**
+ * --simulate (GST-1190): HEAD's ship_lanes_from and run_profiles, findCarry against this tree, nothing else. It never calls
+ * gstack-evidence or gstack-pregate, so it writes no row and clears no obligation: a PR controls both its own map and the
+ * CI that would satisfy it, so head policy never carries. The branch's inventory commands run only with `allow`
+ * (--allow-repo-commands), as gstack-ci-carry find --simulate requires.
+ */
+function simulate(cwd: string, base: string, list: { label: string; command: string }[], allow: boolean): { text: string; exit: number } {
+  const lines: string[] = [];
+  const say = (s: string) => lines.push(`SIMULATION: ${s}`);
+  const done = (exit: number) => ({ text: lines.join('\n') + '\n', exit });
+  const loaded = loadConfigFromHead(cwd);
+  say(`policy ${isConfigUnavailable(loaded) ? 'unavailable' : loaded.label}; a dry run: only the branch's inventory commands run, and only with --allow-repo-commands; no evidence or ledger row is written, nothing clears (a carry reads origin/${base}'s map only)`);
+  if (isConfigUnavailable(loaded) || loaded.errors.length) { say(`refused: ${isConfigUnavailable(loaded) ? loaded.detail : loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}`); return done(1); }
+  const check = buildRunCheck(cwd, null, allow, base, 'head');
+  if ('error' in check) { say(`refused: ${check.error}`); return done(1); }
+  const head = git(cwd, ['rev-parse', 'HEAD']).stdout.trim();
+  const tree = git(cwd, ['rev-parse', 'HEAD^{tree}']).stdout.trim();
+  const wtree = () => { const fp = wtreeFingerprint({ cwd }); return 'tree' in fp ? fp.tree : null; };
+  let mapped = 0;
+  let carried = 0;
+  for (const l of list) {
+    const m = laneMapping(loaded.config.ship_lanes_from, l.command);
+    if (!m) { say(`LANE: ${l.label} not mapped by the branch's ship_lanes_from; /ship would run it`); continue; }
+    mapped++;
+    if (m.inventory && !allow) { say(`CI_CARRY: none label=${l.label} (inventory_not_allowed: the branch's inventory command is a pin-file command; pass --allow-repo-commands)`); continue; }
+    const v = findCarry(check, { profiles: m.profiles, head, tree, wtree, ...mappingCoverage(m, cwd) });
+    if (!v.ok) { say(`CI_CARRY: none label=${l.label} (${v.reason}: ${v.detail})`); continue; }
+    carried++;
+    say(`LANE: ${l.label} would carry run=${v.runs.map(e => `${e.run_id}/${e.run_attempt}`).join(',')} tests_ran=${v.tests}${v.unit ? ` unit=${v.unit}` : ''}${v.remainder ? ` and would run ${v.remainder.length} skipped file(s) here with per_file` : ''}`);
+  }
+  say(`${carried} of ${mapped} mapped lane(s) would carry once origin/${base} holds this map`);
+  return done(mapped > 0 && carried === mapped ? 0 : 1);
+}
+
 export async function preflight(argv: readonly string[], cwd: string): Promise<{ text: string; exit: number }> {
   const { flag, has } = flagReader(argv);
   const base = flag('--base');
@@ -182,6 +225,7 @@ export async function preflight(argv: readonly string[], cwd: string): Promise<{
   if (!['base', 'head'].includes(policyFrom)) return { text: 'gstack-ship-preflight: --policy-from needs base|head\n', exit: 2 };
   if (!base || typeof list === 'string') return { text: `gstack-ship-preflight: ${typeof list === 'string' ? list : '--base <base> is required'}\n`, exit: 2 };
   if (has('--tests-only') && !list.length) return { text: 'gstack-ship-preflight: --tests-only needs at least one --lane <label>=<command>\n', exit: 2 };
+  if (has('--simulate')) return has('--tests-only') && policyFrom === 'head' && list.length ? simulate(cwd, base, list, has('--allow-repo-commands')) : { text: 'gstack-ship-preflight: --simulate needs --tests-only --policy-from head and at least one --lane <label>=<command>\n', exit: 2 };
   const mode = flag('--lanes');
   const concurrency = has('--lanes') && mode === undefined ? '--lanes needs serial or parallel' : laneConcurrency(mode);
   if (typeof concurrency === 'string') return { text: `gstack-ship-preflight: ${concurrency}\n`, exit: 2 };

lib/ship-receipt.ts

@@ -237,9 +237,9 @@ const CARRY_RERUNS = ['CI at head (gstack-ship-queue ready requires it); test an
 
 /**
  * The file's text at the reviewed head and at HEAD, with the release version each head carries (from `VERSION`, else
- * `package.json`) and the base policy's `stamp_patterns` templates.
+ * `package.json`) and the base policy's `stamp_patterns` templates and `stamp_placeholders`.
  */
-export interface CarryChange { before: string | null; after: string | null; oldVersion?: string | null; newVersion?: string | null; templates?: readonly string[]; side?: BranchSide }
+export interface CarryChange { before: string | null; after: string | null; oldVersion?: string | null; newVersion?: string | null; templates?: readonly string[]; side?: BranchSide; placeholders?: readonly string[] }
 
 /**
  * A policy-named stamp path's change is a stamp when the new text reads as the
@@ -262,7 +262,7 @@ export function stampOnlyText(change: CarryChange): boolean {
   const now = after.split('\n');
   if (was.length !== now.length) return false;
   const changed = was.map((line, i) => i).filter(i => was[i] !== now[i]);
-  return changed.length > 0 && changed.every(i => stampOnlyLine(was[i]!, now[i]!, oldVersion, newVersion, change.templates ?? [], change.side, i + 1));
+  return changed.length > 0 && changed.every(i => stampOnlyLine(was[i]!, now[i]!, oldVersion, newVersion, change.templates ?? [], change.side, i + 1, change.placeholders ?? []));
 }
 
 /**

lib/ship-release.ts

@@ -173,16 +173,20 @@ function commitRelease(cwd: string, release: string[], trailer: string | undefin
 
 /**
  * A harness pin edit that only records changed harness files as non-behavioral at the same version and patterns (GST-1031): release
- * metadata, like a version stamp. A bump, a pattern change or an entry without its reason is behavior.
+ * metadata, like a version stamp. The pins live one file per harness file under scripts/harness-pins/ (GST-1084), beside a manifest
+ * holding only version and patterns. A bump, a pattern change or a pin without its reason is behavior.
  */
-const HARNESS_PIN = 'scripts/harness-version.json';
+const HARNESS_MANIFEST = 'scripts/harness-version.json';
+const HARNESS_PINS = 'scripts/harness-pins/';
 function harnessRepin(cwd: string, from: string, to: string, p: string): boolean {
-  if (p !== HARNESS_PIN) return false;
-  const read = (tree: string): any => { const s = git(cwd, ['show', `${tree}:${p}`]); try { return s.status === 0 ? JSON.parse(s.stdout) : null; } catch { return null; } };
-  const a = read(from), b = read(to);
-  if (!a?.files || !b?.files || typeof b.files !== 'object' || a.version !== b.version || JSON.stringify(a.patterns) !== JSON.stringify(b.patterns)) return false;
-  return Object.entries(b.files as Record<string, any>).every(([f, e]) => JSON.stringify(a.files[f]) === JSON.stringify(e)
-    || (e?.since === b.version && typeof e?.nonBehavioral === 'string' && e.nonBehavioral.trim().length >= 10));
+  if (p !== HARNESS_MANIFEST && !(p.startsWith(HARNESS_PINS) && p.endsWith('.json'))) return false;
+  const read = (tree: string, file: string): any => { const s = git(cwd, ['show', `${tree}:${file}`]); if (s.status !== 0) return undefined; try { return JSON.parse(s.stdout); } catch { return null; } };
+  const a = read(from, HARNESS_MANIFEST), b = read(to, HARNESS_MANIFEST);
+  if (!a || !b || Object.keys(b).sort().join() !== 'patterns,version' || a.version !== b.version || JSON.stringify(a.patterns) !== JSON.stringify(b.patterns)) return false;
+  if (p === HARNESS_MANIFEST) return true;
+  const e = read(to, p);
+  return e === undefined || JSON.stringify(read(from, p)) === JSON.stringify(e)
+    || (e?.since === b.version && typeof e?.nonBehavioral === 'string' && e.nonBehavioral.trim().length >= 10);
 }
 
 /**

lib/stamp-only.ts

@@ -4,7 +4,8 @@
  * lines the branch wrote itself. Split from restamp.ts (module-size ratchet).
  */
 import { spawnSync } from 'node:child_process';
-import { branchAddedLines, forkVersion, rewriteStamps, stampMentions } from './restamp';
+import { branchAddedLines, escapeRegExp, forkVersion, rewriteStamps, stampMentions } from './restamp';
+import { VERSION_SLOT } from './ship-policy';
 import { cmpVersion, parseVersion, versionWidth } from './version-source';
 
 /**
@@ -26,12 +27,20 @@ import { cmpVersion, parseVersion, versionWidth } from './version-source';
  * stage's bound for its own lines (GST-895, GST-963): finish's stampedFiles,
  * the tree receipt and the receipt carry all pass the same side. When the
  * version does not move (a slot that keeps its claimed VERSION), only such a
- * branch line may change: the stage moves nothing else then.
+ * branch line may change: the stage moves nothing else then. On such a branch
+ * line a declared placeholder (`stamp_placeholders`, GST-1026: gbrain's
+ * `since: 'TBD'`) may also become the new version, but only inside a
+ * `stamp_patterns` template with literal text around its slot, never a built-in
+ * form: with at least one such rewrite, the line must then be the added line,
+ * or one whose remaining stamp-form moves pass the fork-version bound.
  */
-export function stampOnlyLine(removed: string, added: string, oldV: string, newV: string, templates: readonly string[] = [], side?: BranchSide, at?: number): boolean {
+export function stampOnlyLine(removed: string, added: string, oldV: string, newV: string, templates: readonly string[] = [], side?: BranchSide, at?: number, placeholders: readonly string[] = []): boolean {
   if (removed === added) return false;
   if (oldV !== newV && stampOnlyWithin(removed, added, oldV, newV, templates)) return true;
-  return !!side && at !== undefined && side.at.has(at) && side.added.has(removed) && stampOnlyWithin(removed, added, side.fork, newV, templates);
+  if (!side || at === undefined || !side.at.has(at) || !side.added.has(removed)) return false;
+  if (stampOnlyWithin(removed, added, side.fork, newV, templates)) return true;
+  const filled = fillPlaceholders(removed, newV, templates, placeholders);
+  return filled.count > 0 && (filled.text === added || stampOnlyWithin(filled.text, added, side.fork, newV, templates));
 }
 
 /**
@@ -64,6 +73,21 @@ export function branchSides(repoRoot: string, baseRef: string, head: string, fal
   };
 }
 
+/** Each declared placeholder rewritten to `newV` inside each template with literal text around its slot (a bare edge at a word boundary). */
+function fillPlaceholders(removed: string, newV: string, templates: readonly string[], placeholders: readonly string[]): { text: string; count: number } {
+  let text = removed;
+  let count = 0;
+  for (const t of templates) {
+    const [pre, post] = t.split(VERSION_SLOT) as [string, string];
+    if (!pre && !post) continue;
+    for (const p of placeholders) {
+      const re = new RegExp(`${escapeRegExp(pre)}${pre ? '' : '(?<![A-Za-z0-9_.])'}${escapeRegExp(p)}${post ? '' : '(?![A-Za-z0-9_.])'}${escapeRegExp(post)}`, 'g');
+      text = text.replace(re, () => { count++; return pre + newV + post; });
+    }
+  }
+  return { text, count };
+}
+
 function stampOnlyWithin(removed: string, added: string, oldV: string, newV: string, templates: readonly string[]): boolean {
   const floor = parseVersion(oldV);
   const width = versionWidth(oldV);

lib/tree-receipt.ts

@@ -78,15 +78,16 @@ export function classifyFiles(repoRoot: string, fileDiffs: FileDiff[], gated: st
 /**
  * Every removed/added pair differs only by stamp rewrites to the new version:
  * the old version, or a tentative one (newer than it) the stamp_paths stage
- * moved (#3512), each in a stamp form (`stampOnlyLine`, bounded by the fork version on the branch's own lines).
+ * moved (#3512), each in a stamp form (`stampOnlyLine`, bounded by the fork version on the branch's own lines, where a
+ * declared placeholder may also move inside a stamp_patterns template, GST-1026).
  */
-function stampOnlyHunks(hunks: FileDiff['hunks'], oldV: string, newV: string, templates: readonly string[], side?: BranchSide): { why: string; line: number } | null {
+function stampOnlyHunks(hunks: FileDiff['hunks'], oldV: string, newV: string, templates: readonly string[], side?: BranchSide, placeholders: readonly string[] = []): { why: string; line: number } | null {
   for (const h of hunks) {
     if (h.removed.length !== h.added.length) return { why: `${h.removed.length} line(s) removed, ${h.added.length} added`, line: h.at };
     for (let i = 0; i < h.removed.length; i++) {
       const r = h.removed[i]!;
       const a = h.added[i]!;
-      if (!stampOnlyLine(r, a, oldV, newV, templates, side, h.removedAt[i])) return { why: `${JSON.stringify(r.trim().slice(0, 60))} -> ${JSON.stringify(a.trim().slice(0, 60))}`, line: h.at + i };
+      if (!stampOnlyLine(r, a, oldV, newV, templates, side, h.removedAt[i], placeholders)) return { why: `${JSON.stringify(r.trim().slice(0, 60))} -> ${JSON.stringify(a.trim().slice(0, 60))}`, line: h.at + i };
     }
   }
   return null;
@@ -130,7 +131,7 @@ export function classifyFile(repoRoot: string, f: FileDiff, gated: string, curre
   const rule = matchesAny(policy.stamp_paths, f.path) ? 'stamp_paths' : matchesAny(policy.release_outputs, f.path) ? 'release_outputs' : matchesAny(policy.stamp_files, f.path) ? 'stamp_files' : null;
   const own = rule ? side?.(f.path) : undefined;
   if (oldV && newV && (oldV !== newV || own) && rule) {
-    const bad = stampOnlyHunks(f.hunks, oldV, newV, policy.stamp_patterns, own);
+    const bad = stampOnlyHunks(f.hunks, oldV, newV, policy.stamp_patterns, own, policy.stamp_placeholders);
     return bad ? changed(rule, bad.why, bad.line) : stamp(rule);
   }
   return changed('other', `${f.hunks.length} hunk(s) outside every stamp rule`);