Merge commit '9d9d4c31bb87b1215ca4ccba911318de8e04599b' into gsta251/investigate-gate

scripts/lib/free-home-guard.ts

@@ -5,8 +5,10 @@
  * the real home before and after each free shard, and names the shard's files
  * when one of those entries changed. It watches only these surfaces; it is not
  * a universal write-containment check. Live agent-session logs that a
- * concurrently running host keeps writing are excluded, and directory mtimes
- * are ignored, so only file, link and directory-set changes count.
+ * concurrently running host keeps writing are excluded, as is the one lane log
+ * `gstack-evidence run` tees this run's own output into (its exact path, from
+ * GSTACK_EVIDENCE_LOG). Directory mtimes are ignored, so only file, link and
+ * directory-set changes count.
  *
  * A shard that runs alone owns its window, so its guard names its files.
  * Concurrent shards share one HOME and cannot tell whose write a change was, so
@@ -104,6 +106,7 @@ export type FreeHomeGuardFactory = (files: string[], env: NodeJS.ProcessEnv, sta
 /** Take the baseline now; verify() returns null or the failure to report. */
 export function guardFreeHome(files: string[], env: NodeJS.ProcessEnv = process.env, scope: FreeHomeScope = { kind: 'shard' }): FreeHomeGuard {
   const home = freeHomeDir(env);
+  const ownLog = env.GSTACK_EVIDENCE_LOG && path.isAbsolute(env.GSTACK_EVIDENCE_LOG) ? path.relative(home, env.GSTACK_EVIDENCE_LOG) : null;
   const unreadable = (error: unknown) => `real home surfaces could not be snapshotted (${(error as NodeJS.ErrnoException).code ?? 'error'}); shard files: ${files.join(', ')}`;
   let before: FreeHomeSnapshot | undefined;
   let baselineError: string | undefined;
@@ -112,7 +115,7 @@ export function guardFreeHome(files: string[], env: NodeJS.ProcessEnv = process.
     verify() {
       if (!before) return baselineError!;
       try {
-        const changed = diffFreeHome(before, snapshotFreeHome(home));
+        const changed = diffFreeHome(before, snapshotFreeHome(home)).filter(entry => entry !== ownLog);
         return changed.length ? formatFreeHomeChange(changed, files, scope) : null;
       } catch (error) { return unreadable(error); }
     },

scripts/lib/shard-jobs.ts

@@ -45,16 +45,39 @@ export const FREE_JOBS_INVALID = 'FREE_JOBS_INVALID';
 export const FREE_SUBSHARD_TIMEOUT = 'FREE_SUBSHARD_TIMEOUT';
 export const FREE_SUBSHARD_REJECTED = 'FREE_SUBSHARD_REJECTED';
 const DOCS = 'docs/TESTING_INTERNALS.md#sub-shards-inside-one-ci-job';
-const JOBS_FIX = `--jobs applies only to --ci-run and defaults to 1; GSTACK_FREE_JOBS sets the local full-suite process count and never changes --ci-run. See ${DOCS}`;
+const JOBS_FIX = `--jobs applies only to --ci-run and defaults to the plan's per-shard k (1 when the plan has none); --shard-jobs applies only to --ci-plan; GSTACK_FREE_JOBS sets the local full-suite process count and never changes --ci-run. See ${DOCS}`;
 
-/** `--jobs <k>` at parse time: digits only, at least 1. */
-export function parseJobsFlag(raw: string | undefined): number {
+/** `--jobs <k>` or `--shard-jobs <k>` at parse time: digits only, at least 1. */
+export function parseJobsFlag(raw: string | undefined, flag = '--jobs'): number {
   if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
-    throw new Error(`${FREE_JOBS_INVALID}: --jobs needs a positive whole number; got ${JSON.stringify(raw ?? '')}. ${JOBS_FIX}`);
+    throw new Error(`${FREE_JOBS_INVALID}: ${flag} needs a positive whole number; got ${JSON.stringify(raw ?? '')}. ${JOBS_FIX}`);
   }
   return Number(raw);
 }
 
+export function rejectShardJobsWithoutCiPlan(): never {
+  throw new Error(`${FREE_JOBS_INVALID}: --shard-jobs needs --ci-plan. ${JOBS_FIX}`);
+}
+
+/**
+ * One planned shard's k under `--ci-plan --shard-jobs k`: at most one parallel
+ * sub-shard per file that may run in parallel, so a shard of only serial files
+ * (the exclusive TREE_MUTATING shard) keeps k = 1. Undefined means k = 1, and
+ * the plan then carries no `jobs` key, so its id matches a plan without k.
+ */
+export function plannedShardJobs(files: readonly string[], shardJobs: number, isSerial: (file: string) => boolean): number | undefined {
+  const jobs = Math.min(shardJobs, files.filter(file => !isSerial(file)).length);
+  return jobs > 1 ? jobs : undefined;
+}
+
+/** Why a plan's per-shard k cannot stand; null when absent or valid. */
+export function plannedShardJobsProblem(shard: { shard: number; files: readonly string[]; jobs?: unknown }, isSerial: (file: string) => boolean): string | null {
+  if (shard.jobs === undefined) return null;
+  const parallel = shard.files.filter(file => !isSerial(file)).length;
+  return Number.isInteger(shard.jobs) && (shard.jobs as number) >= 2 && (shard.jobs as number) <= parallel ? null
+    : `CI shard ${shard.shard} plans --jobs ${JSON.stringify(shard.jobs)} for ${parallel} parallel file(s)`;
+}
+
 export function rejectJobsWithoutCiRun(): never {
   throw new Error(`${FREE_JOBS_INVALID}: --jobs needs --ci-run. ${JOBS_FIX}`);
 }

scripts/modules-cli.ts

@@ -5,6 +5,14 @@
  *   gstack-modules validate
  *   gstack-modules render --host <h> (--loadout <name> | --modules <base>,-id,+id) --out-dir <d>
  *                         [--install-root <abs>] [--model <id>] [--plan-mode on|off]
+ *                         [--bind-model <id> --full-root <abs>]
+ *   gstack-modules resolve [--model <id>] [--loadout <name>]
+ *   gstack-modules install --full-root <abs> [--model <id>] [--loadout <name>] [--store <dir>] [--plan-mode on|off]
+ *
+ * resolve and install pick the loadout through lib/model-detect.ts. install
+ * prints `LOADOUT: …` and `SKILL_ROOT: <dir>`: the full root for full, else
+ * the published lite tree (scripts/modules-install.ts). A lite render that
+ * fails prints LOADOUT_FALLBACK and serves full, exit 0.
  *
  * Exit 0 on success, 2 on a refused input (ModuleError, printed with its code,
  * fix and docs anchor), 1 on an unexpected failure.
@@ -14,8 +22,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { resolveHostArg } from '../hosts/index';
 import { resolveModel } from './models';
-import { LOADOUTS_FILE, ModuleError, loadLoadouts, moduleCatalog, selectModules, validateLoadouts } from './modules';
+import { LOADOUTS_FILE, MODEL_ID_RE, ModuleError, loadLoadouts, moduleCatalog, normalizeModelId, selectModules, validateLoadouts } from './modules';
 import { renderLoadout } from './modules-render';
+import { installLoadout } from './modules-install';
+import { describeResolution, resolveLoadout } from '../lib/model-detect';
+import { resolveStateRoot } from '../lib/state-root';
 import type { Host } from './resolvers/types';
 
 const ROOT = path.resolve(import.meta.dir, '..');
@@ -24,7 +35,14 @@ const USAGE = `Usage:
   gstack-modules validate                   check ${LOADOUTS_FILE} against the catalog
   gstack-modules render --host <h> (--loadout <name> | --modules <base>,-id,+id) --out-dir <d>
                         [--install-root <abs>] [--model <id>] [--plan-mode on|off]
-                                            render one loadout and write loadout.lock.json
+                        [--bind-model <id> --full-root <abs>]
+                                            render one loadout and write loadout.lock.json;
+                                            --bind-model bakes the start lines an install
+                                            for that model serves
+  gstack-modules resolve [--model <id>] [--loadout <name>]
+                                            the loadout an install would serve, and why
+  gstack-modules install --full-root <abs> [--model <id>] [--loadout <name>] [--store <dir>] [--plan-mode on|off]
+                                            publish that loadout and print SKILL_ROOT
 Guide: docs/loadouts.md`;
 
 export interface CliResult { code: number; stdout: string; stderr: string }
@@ -74,10 +92,38 @@ export async function modulesMain(args: string[]): Promise<CliResult> {
       if (planMode !== undefined && planMode !== 'on' && planMode !== 'off') throw new ModuleError('MODULE_SPEC_INVALID', '--plan-mode takes on or off', 'drop it, or pass --plan-mode off');
       const installRoot = flag(rest, '--install-root');
       if (installRoot !== undefined && !/^\/[A-Za-z0-9_.@+\/-]*$/.test(installRoot)) throw new ModuleError('MODULE_SPEC_INVALID', '--install-root must be a plain absolute path', 'pass the absolute install root setup would use');
-      const selection = selectModules({ loadout, modules });
+      const bindModel = flag(rest, '--bind-model');
+      const fullRoot = flag(rest, '--full-root');
+      const selected = selectModules({ loadout, modules });
+      if ((bindModel === undefined) !== (fullRoot === undefined)) throw new ModuleError('MODULE_SPEC_INVALID', '--bind-model and --full-root go together', 'pass both, or neither');
+      if (bindModel !== undefined && !selected) throw new ModuleError('MODULE_SPEC_INVALID', '--bind-model needs a loadout that excludes something', 'drop --bind-model for the full loadout');
+      if (bindModel !== undefined && !MODEL_ID_RE.test(normalizeModelId(bindModel))) throw new ModuleError('MODULE_SPEC_INVALID', '--bind-model is not a plain model id', 'pass an id such as claude-opus-5-5');
+      if (fullRoot !== undefined && !/^\/[A-Za-z0-9_.@+\/-]*$/.test(fullRoot)) throw new ModuleError('MODULE_SPEC_INVALID', '--full-root must be a plain absolute path', 'pass the full install root, for example --full-root "$HOME/.claude/skills"');
+      const selection = selected && bindModel !== undefined ? { ...selected, boundModel: normalizeModelId(bindModel), fullRoot } : selected;
       const lock = await renderLoadout({ host, selection, outDir, installRoot: installRoot ?? null, model, planMode: planMode !== 'off' });
       return { code: 0, stdout: `RENDERED: loadout=${lock.loadout} host=${host} files=${lock.files.length} bytes=${lock.total_bytes} excluded=${lock.excluded.length} lock=${path.join(path.resolve(outDir), 'loadout.lock.json')}\n`, stderr: '' };
     }
+    if (command === 'resolve' || command === 'install') {
+      const resolution = resolveLoadout({ loadout: flag(rest, '--loadout'), model: flag(rest, '--model') });
+      const notice = resolution.notice ? `${resolution.notice}\n` : '';
+      if (command === 'resolve') return { code: 0, stdout: describeResolution(resolution) + '\n', stderr: notice };
+      const fullRoot = flag(rest, '--full-root');
+      if (!fullRoot || !/^\/[A-Za-z0-9_.@+\/-]*$/.test(fullRoot)) throw new ModuleError('MODULE_SPEC_INVALID', 'install needs --full-root <plain absolute path>', 'pass the full install root, for example --full-root "$HOME/.claude/skills"');
+      const planMode = flag(rest, '--plan-mode');
+      if (planMode !== undefined && planMode !== 'on' && planMode !== 'off') throw new ModuleError('MODULE_SPEC_INVALID', '--plan-mode takes on or off', 'drop it, or pass --plan-mode off');
+      const full = (line: string) => ({ code: 0, stdout: `${line}\nSKILL_ROOT: ${fullRoot}\n`, stderr: notice });
+      if (resolution.loadout === 'full') return full(describeResolution(resolution));
+      try {
+        const selection = selectModules({ loadout: resolution.loadout });
+        if (!selection) return full(describeResolution(resolution));
+        const store = flag(rest, '--store') ?? path.join(resolveStateRoot(), 'loadouts');
+        const result = await installLoadout({ selection, boundModel: resolution.model, fullRoot, store, planMode: planMode !== 'off' });
+        return { code: 0, stdout: `${describeResolution(resolution)} digest=${result.lock.identity_sha256.slice(0, 12)} reused=${result.reused ? 'yes' : 'no'}\nSKILL_ROOT: ${result.root}\n`, stderr: notice };
+      } catch (error) {
+        const why = error instanceof ModuleError ? `${error.code}: ${error.message}` : (error as Error).message;
+        return { code: 0, stdout: `${describeResolution({ ...resolution, loadout: 'full', model: null, reason: 'render-failed' })}\nSKILL_ROOT: ${fullRoot}\n`, stderr: `${notice}LOADOUT_FALLBACK: ${why.replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 400)}; serving full (docs/troubleshooting.md#loadout-fallback)\n` };
+      }
+    }
     return { code: 2, stdout: '', stderr: `Unknown command ${JSON.stringify(command.slice(0, 40))}.\n${USAGE}\n` };
   } catch (error) {
     if (error instanceof ModuleError) return { code: 2, stdout: '', stderr: `${error.code}: ${error.message}\n` };

scripts/modules-install.ts

@@ -0,0 +1,214 @@
+/**
+ * gstack-modules install (GSTA-161, PR 1b): a non-full loadout published as a
+ * complete, immutable skill tree beside the full install, for Capy's
+ * SKILL_ROOT. The checkout itself always stays the full render.
+ *
+ * Identity: sha256 over the effective selection (loadout, sorted exclusions,
+ * tier cap), the bound model and full root baked into each start line, the
+ * host, the overlay model, plan mode and the source tree (the git HEAD tree,
+ * plus a digest of uncommitted and untracked changes; a source git cannot read
+ * gets a one-off nonce, so it never reuses a folder). Folder: <store>/<loadout>-<identity12>.
+ * A folder is reused only when its lock names the same full identity and every
+ * listed file still hashes to its recorded sha256.
+ *
+ * Publish: render into a staging folder (section links already name the final
+ * folder), refuse dangling references, copy the source's tracked runtime assets
+ * the render lacks (templates, references, scripts; never *.tmpl, test/ or the
+ * skill's own SKILL.md), add gstack/SKILL.md for the router, write
+ * loadout.lock.json last, then rename the staging folder into place. A rename
+ * that loses a race to the same identity reuses the winner; a published folder
+ * is never replaced. Folders this installer published for the same loadout
+ * (name, digest and an install lock) beyond the newest KEEP by last use are
+ * removed once unused for PRUNE_GRACE_MS.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { runGeneration } from './gen-skill-docs';
+import { resolveModel } from './models';
+import { ModuleError, type ModuleSelection } from './modules';
+import { LOCK_FILE, danglingReferences } from './modules-render';
+import type { Host } from './resolvers/types';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const KEEP = 3;
+const PRUNE_GRACE_MS = 24 * 60 * 60 * 1000;
+
+export interface InstallRequest {
+  selection: ModuleSelection;
+  /** Validated model id the selection was made for, or null for an explicit loadout. */
+  boundModel: string | null;
+  fullRoot: string;
+  store: string;
+  host?: Host;
+  planMode?: boolean;
+}
+
+export interface InstallLock {
+  schema_version: 1;
+  kind: 'install';
+  identity_sha256: string;
+  identity: Record<string, unknown>;
+  loadout: string;
+  loadout_model: string | null;
+  full_root: string;
+  gstack_version: string;
+  excluded: string[];
+  total_bytes: number;
+  files: Array<{ path: string; bytes: number; sha256: string }>;
+}
+
+export interface InstallResult { root: string; lock: InstallLock; reused: boolean }
+
+const sha256 = (data: string | Buffer) => createHash('sha256').update(data).digest('hex');
+
+function git(root: string, args: string[]): string | null {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf-8', timeout: 30_000, maxBuffer: 64 * 1024 * 1024 });
+  return result.status === 0 ? result.stdout : null;
+}
+
+/** The git HEAD tree, plus a digest of uncommitted and untracked changes when there are any; a nonce when git cannot say. */
+export function sourceTree(root: string): string {
+  const tree = git(root, ['rev-parse', 'HEAD^{tree}'])?.trim();
+  const diff = git(root, ['diff', '--no-ext-diff', '--binary', 'HEAD']);
+  const untracked = git(root, ['ls-files', '-z', '--others', '--exclude-standard']);
+  if (!tree || diff === null || untracked === null) return `unpinned-${randomBytes(8).toString('hex')}`;
+  if (!diff && !untracked) return tree;
+  const extra = untracked.split('\0').filter(Boolean).sort().map(rel => {
+    try { return `${rel}:${sha256(fs.readFileSync(path.join(root, rel)))}`; } catch { return `${rel}:unreadable`; }
+  });
+  return `${tree}+${sha256(diff + '\0' + extra.join('\n')).slice(0, 16)}`;
+}
+
+function walk(dir: string, base = dir): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) return walk(full, base);
+    return entry.isFile() ? [path.relative(base, full).split(path.sep).join('/')] : [];
+  }).sort();
+}
+
+function hashFiles(dir: string) {
+  return walk(dir).filter(rel => rel !== LOCK_FILE).map(rel => {
+    const bytes = fs.readFileSync(path.join(dir, rel));
+    return { path: rel, bytes: bytes.length, sha256: sha256(bytes) };
+  });
+}
+
+function intact(dir: string, identity: string): InstallLock | null {
+  try {
+    const lock = JSON.parse(fs.readFileSync(path.join(dir, LOCK_FILE), 'utf-8')) as InstallLock;
+    if (lock.kind !== 'install' || lock.identity_sha256 !== identity) return null;
+    const actual = new Map(hashFiles(dir).map(f => [f.path, f.sha256]));
+    if (actual.size !== lock.files.length || lock.files.some(f => actual.get(f.path) !== f.sha256)) return null;
+    return lock;
+  } catch {
+    return null;
+  }
+}
+
+/** Copy each tracked runtime asset of a rendered skill directory that the render did not write. */
+function copyRuntimeAssets(source: string, stage: string): void {
+  const listed = git(source, ['ls-files', '-z']);
+  if (listed === null) throw new ModuleError('RENDER_FAILED', `cannot list the tracked files of ${source}`, 'install from a git checkout of gstack');
+  for (const rel of listed.split('\0').filter(Boolean)) {
+    const [dir, ...rest] = rel.split('/');
+    if (!rest.length || !fs.existsSync(path.join(stage, dir, 'SKILL.md'))) continue;
+    if (rel.endsWith('.tmpl') || rel === `${dir}/SKILL.md` || rest.some(seg => seg === 'test' || seg === 'node_modules' || seg === 'dist')) continue;
+    const to = path.join(stage, rel);
+    if (fs.existsSync(to)) continue;
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(path.join(source, rel), to);
+  }
+}
+
+function ownedInstall(dir: string): boolean {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, LOCK_FILE), 'utf-8')).kind === 'install';
+  } catch {
+    return false;
+  }
+}
+
+function prune(store: string, loadout: string, keep: string): void {
+  const name = new RegExp(`^${loadout}-[0-9a-f]{12}$`);
+  const cutoff = Date.now() - PRUNE_GRACE_MS;
+  const siblings = fs.readdirSync(store, { withFileTypes: true })
+    .filter(e => e.isDirectory() && name.test(e.name) && path.join(store, e.name) !== keep && ownedInstall(path.join(store, e.name)))
+    .map(e => ({ dir: path.join(store, e.name), mtime: fs.statSync(path.join(store, e.name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  for (const { dir, mtime } of siblings.slice(KEEP - 1)) if (mtime < cutoff) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+export async function installLoadout(request: InstallRequest): Promise<InstallResult> {
+  const source = ROOT;
+  const host = request.host ?? 'claude';
+  const planMode = request.planMode ?? true;
+  const model = request.boundModel ? resolveModel(request.boundModel) : null;
+  const selection: ModuleSelection = { ...request.selection, boundModel: request.boundModel ?? undefined, fullRoot: request.boundModel ? request.fullRoot : undefined };
+  const identity = {
+    loadout: selection.name,
+    excluded: [...selection.excluded].sort(),
+    preamble_tier_max: selection.preambleTierMax ?? null,
+    loadout_model: request.boundModel,
+    full_root: request.fullRoot,
+    host,
+    overlay_model: model,
+    plan_mode: planMode,
+    source_tree: sourceTree(source),
+  };
+  const identitySha = sha256(JSON.stringify(identity));
+  const store = path.resolve(request.store);
+  const final = path.join(store, `${selection.name}-${identitySha.slice(0, 12)}`);
+  fs.mkdirSync(store, { recursive: true });
+  const existing = intact(final, identitySha);
+  if (existing) {
+    const used = new Date();
+    fs.utimesSync(final, used, used);
+    return { root: final, lock: existing, reused: true };
+  }
+  if (fs.existsSync(final)) {
+    throw new ModuleError('RENDER_DEST_NOT_OWNED', `${final} exists but its ${LOCK_FILE} does not match this render`, `remove ${final} and rerun; nothing else was changed`);
+  }
+  const stage = `${final}.stage-${process.pid}-${randomBytes(4).toString('hex')}`;
+  try {
+    const result = await runGeneration({ host, outputRoot: stage, contentLinkRoot: final, installRoot: request.fullRoot && request.fullRoot !== path.join(os.homedir(), '.claude/skills') ? path.join(request.fullRoot, 'gstack') : null, model, planMode, modules: selection });
+    const errors = result.diagnostics.filter(d => d.kind === 'error').map(d => d.message);
+    if (result.exitCode !== 0 || errors.length) {
+      throw new ModuleError('RENDER_FAILED', `gen-skill-docs failed: ${errors.join('; ') || 'exit 1'}`, 'fix the named template or module, then rerun; side effects: none, safe to retry');
+    }
+    const dangling = danglingReferences(stage, selection);
+    if (dangling.length) throw new ModuleError('MODULE_EXCLUSION_UNSAFE', dangling.slice(0, 5).join('; '), 'exclude the referencing module too, or guard the reference with {{IF_SECTION:id}}');
+    copyRuntimeAssets(source, stage);
+    fs.mkdirSync(path.join(stage, 'gstack'), { recursive: true });
+    fs.copyFileSync(path.join(stage, 'SKILL.md'), path.join(stage, 'gstack', 'SKILL.md'));
+    const files = hashFiles(stage);
+    const lock: InstallLock = {
+      schema_version: 1,
+      kind: 'install',
+      identity_sha256: identitySha,
+      identity,
+      loadout: selection.name,
+      loadout_model: request.boundModel,
+      full_root: request.fullRoot,
+      gstack_version: fs.readFileSync(path.join(source, 'VERSION'), 'utf-8').trim(),
+      excluded: identity.excluded,
+      total_bytes: files.reduce((sum, f) => sum + f.bytes, 0),
+      files,
+    };
+    fs.writeFileSync(path.join(stage, LOCK_FILE), JSON.stringify(lock, null, 2) + '\n');
+    try {
+      fs.renameSync(stage, final);
+    } catch (error) {
+      const winner = intact(final, identitySha);
+      if (!winner) throw error;
+      return { root: final, lock: winner, reused: true };
+    }
+    prune(store, selection.name, final);
+    return { root: final, lock, reused: false };
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}

scripts/modules-render.ts

@@ -39,6 +39,9 @@ export interface LoadoutLock {
   model: string | null;
   install_root: string | null;
   plan_mode: boolean;
+  /** The model a --bind-model render bakes into its start lines, and the full root it names. */
+  loadout_model: string | null;
+  full_root: string | null;
   gstack_version: string;
   excluded: string[];
   total_bytes: number;
@@ -152,6 +155,8 @@ export async function renderLoadout(request: RenderRequest): Promise<LoadoutLock
       model: request.model ?? getHostConfig(request.host).defaultModel ?? null,
       install_root: request.installRoot ?? null,
       plan_mode: request.planMode ?? true,
+      loadout_model: request.selection?.boundModel ?? null,
+      full_root: request.selection?.fullRoot ?? null,
       gstack_version: fs.readFileSync(path.join(ROOT, 'VERSION'), 'utf-8').trim(),
       excluded: [...(request.selection?.excluded ?? [])].sort(),
       total_bytes: files.reduce((sum, f) => sum + f.bytes, 0),

scripts/modules.ts

@@ -53,6 +53,8 @@ export interface LoadoutsManifest {
   rungs: Record<(typeof RUNGS)[number], string[]>;
   pinned: string[];
   loadouts: Record<string, LoadoutDef>;
+  /** Exact model id to loadout, checked before rungs (a dated snapshot or -latest also matches). */
+  models?: Record<string, string>;
   default: Record<Rung, string>;
 }
 
@@ -106,6 +108,18 @@ export function normalizeModelId(raw: string): string {
   return raw.trim().toLowerCase().replace(/\[[^\]]*\]$/, '').trim().replace(/^[a-z0-9-]+\//, '');
 }
 
+/** Model ids that may reach generated shell or a launch file; anything else resolves to full. */
+export const MODEL_ID_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+
+/** An exact id, or the same id plus a dated snapshot (-YYYYMMDD) or -latest; a point release never matches. */
+export const modelKeyMatches = (key: string, id: string) => id === key || (id.startsWith(`${key}-`) && /^(\d{8}|latest)$/.test(id.slice(key.length + 1)));
+
+/** The manifest.models key a model id matches and the loadout it names, or undefined when none matches. */
+export function loadoutForModel(manifest: LoadoutsManifest, id: string): { key: string; loadout: string } | undefined {
+  const key = Object.keys(manifest.models ?? {}).find(k => modelKeyMatches(k, id));
+  return key === undefined ? undefined : { key, loadout: manifest.models![key] };
+}
+
 const matches = (pattern: string, id: string) => (pattern.endsWith('*') ? id.startsWith(pattern.slice(0, -1)) : id === pattern);
 
 /** The rung a model id belongs to: aliases first, then the first rung whose pattern matches. */
@@ -148,6 +162,13 @@ export function validateLoadouts(manifest: LoadoutsManifest, catalog: ModuleEntr
       seen.add(at);
     }
   }
+  const modelKeys = Object.keys(manifest.models ?? {});
+  for (const [key, name] of Object.entries(manifest.models ?? {})) {
+    if (!MODEL_ID_RE.test(key)) problems.push(`models key ${clamp(key)} must be an exact model id matching ${MODEL_ID_RE.source}`);
+    if (!has(name)) problems.push(`models.${key} names no loadout (${clamp(String(name))})`);
+    const overlap = modelKeys.find(other => other !== key && modelKeyMatches(other, key));
+    if (overlap) problems.push(`models key ${key} is also matched by ${overlap}`);
+  }
   for (const rung of [...RUNGS, 'unknown'] as const) {
     if (!has(manifest.default?.[rung])) problems.push(`default.${rung} names no loadout (${clamp(String(manifest.default?.[rung]))})`);
   }

scripts/pr-dependencies.ts

@@ -89,7 +89,7 @@ export const SELECTION_DATA_MODULES: readonly string[] = [
   // The build entry list: every compiled binary, which skills reach through their `--outfile` path instead.
   'scripts/build.sh',
   // The reason-code table: its `fix:` prose names the command a person reruns, not a file the module consumes.
-  'lib/result-codes.ts', 'lib/result-codes-release.ts', 'lib/result-codes-capy.ts', 'lib/result-codes-budget.ts', 'lib/result-codes-eval.ts', 'lib/result-codes-plan.ts', 'lib/result-codes-autoplan.ts',
+  'lib/result-codes.ts', 'lib/result-codes-release.ts', 'lib/result-codes-capy.ts', 'lib/result-codes-budget.ts', 'lib/result-codes-eval.ts', 'lib/result-codes-plan.ts', 'lib/result-codes-autoplan.ts', 'lib/result-codes-browse.ts', 'lib/result-codes-clean.ts',
   // The exercised-path map: observed commands per case, read only by exercisedConsumers() (shadow data; a change selects no paid case).
   'test/helpers/exercised-commands.json',
 ];

scripts/psychographic-signals.ts

@@ -306,29 +306,6 @@ export function resolveOptionKey(question_id: string, choice: string): string |
   return tie ? undefined : best;
 }
 
-/**
- * Apply a user choice for a question to the running dimension totals.
- *
- * @param dims - running total of dimension nudges (mutated)
- * @param signal_key - from the question registry entry
- * @param user_choice - the option key the user selected
- * @returns list of dimension deltas applied (empty if no mapping)
- */
-export function applySignal(
-  dims: Record<Dimension, number>,
-  signal_key: string,
-  user_choice: string,
-): DimensionDelta[] {
-  const subMap = SIGNAL_MAP[signal_key];
-  if (!subMap) return [];
-  const deltas = subMap[user_choice];
-  if (!deltas) return [];
-  for (const { dim, delta } of deltas) {
-    dims[dim] = (dims[dim] ?? 0) + delta;
-  }
-  return deltas;
-}
-
 /**
  * Validate that every signal_key referenced in the registry has a matching
  * entry in SIGNAL_MAP. Called by tests to catch drift.
@@ -353,17 +330,6 @@ export function validateRegistrySignalKeys(): {
   return { missing, extra };
 }
 
-/** Empty dimension totals — starting point for derivation. */
-export function newDimensionTotals(): Record<Dimension, number> {
-  return {
-    scope_appetite: 0,
-    risk_tolerance: 0,
-    detail_preference: 0,
-    autonomy: 0,
-    architecture_care: 0,
-  };
-}
-
 /** Sigmoid clamp: map accumulated delta total to [0, 1]. */
 export function normalizeToDimensionValue(total: number): number {
   // Simple sigmoid: each 1.0 of accumulated delta approaches saturation.

scripts/resolvers/aside.ts

@@ -240,6 +240,17 @@ console.log("ASIDE_DIR=" + pwd); await closeTab(pg); console.log("GSTACK_STEP_OK
 '
 \`\`\`
 
+**Touch (verified in Aside 1.26; add the Responsive override for phone size):**
+
+\`\`\`bash
+aside repl '
+const pg = await openTab("<url>"), t = (m, p) => pg._sendToTarget(m, p);
+await t("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
+for (const [type, touchPoints] of [["touchStart", [{ x: <tap-x>, y: <tap-y> }]], ["touchEnd", []]]) await t("Input.dispatchTouchEvent", { type, touchPoints });
+await closeTab(pg); console.log("GSTACK_STEP_OK");
+'
+\`\`\`
+
 **Links and their status (same-origin; on a LOCAL target each link is HEAD-checked, on a real site the user's cookies would ride every request so links are listed as \`LINK ?\` unfetched — consent to LOOK is not consent to hit every URL):**
 
 \`\`\`bash

scripts/resolvers/preamble/generate-preamble-bash.ts

@@ -23,11 +23,28 @@ import { skillStartLines } from '../runtime-root';
  * sessions refuse a command named by a variable, a `[ -x ] ||` fallback, or a
  * trailing `|| echo`. A missing helper is covered by the degraded-mode prose.
  */
+/**
+ * A loadout chosen for one model (GSTA-161) bakes its name, that model and
+ * the full install root into the start line, so gstack-skill-start can tell
+ * any other model to read the full SKILL.md. An explicit or ad-hoc selection
+ * is bound to no model and adds nothing. The values are validated literals;
+ * nothing from the environment reaches here.
+ */
+function loadoutStartFlags(ctx: TemplateContext): string {
+  const filter = ctx.modules;
+  if (!filter?.boundModel) return '';
+  if (!/^[a-z0-9-]{1,40}$/.test(filter.name)) throw new Error(`loadout name ${JSON.stringify(filter.name)} cannot be baked into a start line`);
+  if (!/^[a-z0-9][a-z0-9._-]{0,79}$/.test(filter.boundModel)) throw new Error(`model id ${JSON.stringify(filter.boundModel.slice(0, 80))} cannot be baked into a start line`);
+  if (!filter.fullRoot || !/^\/[A-Za-z0-9_.@+\/-]*$/.test(filter.fullRoot)) throw new Error('a model-bound loadout needs a plain absolute fullRoot');
+  return ` --loadout '${filter.name}' --loadout-model '${filter.boundModel}' --full-root '${filter.fullRoot}'`;
+}
+
 export function generatePreambleBash(ctx: TemplateContext): string {
   const hostConfig = getHostConfig(ctx.host);
   const start = hostConfig.usesEnvVars ? skillStartLines(ctx) : null;
   const runtimeRoot = start ? `${start.lookup}\n` : '';
   const brainHealthFlag = ctx.host === 'gbrain' || ctx.host === 'hermes' ? ' --brain-health' : '';
+  const loadoutFlags = loadoutStartFlags(ctx);
   const startCommand = start ? start.command : `${ctx.paths.binDir}/gstack-skill-start`;
 
   const entry = ['plan-design-review', 'plan-eng-review'].includes(ctx.skillName)
@@ -39,7 +56,7 @@ export function generatePreambleBash(ctx: TemplateContext): string {
   return `${entry}
 
 \`\`\`bash
-${runtimeRoot}${startCommand} --skill "${ctx.skillName}" --model "${ctx.model ?? 'none'}"${brainHealthFlag}
+${runtimeRoot}${startCommand} --skill "${ctx.skillName}" --model "${ctx.model ?? 'none'}"${loadoutFlags}${brainHealthFlag}
 \`\`\`
 
 Read the echoed \`KEY: value\` STATUS lines — they drive every preamble rule

scripts/resolvers/types.ts

@@ -140,6 +140,10 @@ export interface ModuleFilter {
   pinned: ReadonlySet<string>;
   /** Unpinned preamble pieces render as if the skill's preamble-tier were at most this. */
   preambleTierMax?: number;
+  /** The model an automatic selection was made for; the start line tells any other model to read fullRoot instead. */
+  boundModel?: string;
+  /** Absolute root of the full install that holds <skill>/SKILL.md. */
+  fullRoot?: string;
 }
 
 /** Resolver function signature. args is populated for parameterized placeholders like {{INVOKE_SKILL:name}}. */

scripts/test-free-shards.ts

@@ -77,11 +77,15 @@
  *   bun run scripts/test-free-shards.ts --attribute-home           # name real-home writers: each file alone, private HOME
  *   bun run scripts/test-free-shards.ts --ci-plan plan.json --shards 20
  *   bun run scripts/test-free-shards.ts --ci-run plan.json --shard 1 --result result.json
+ *   bun run scripts/test-free-shards.ts --ci-plan plan.json --shards 20 --shard-jobs 2
+ *       # the plan stores a per-shard k: min(k, the shard's files that may run in parallel),
+ *       # kept only when above 1, so the exclusive TREE_MUTATING shard stays one child.
  *   bun run scripts/test-free-shards.ts --ci-run plan.json --shard 1 --result result.json --jobs 4
- *       # k sub-shards side by side inside one CI job (default 1 = one child, today's behavior;
- *       # scripts/lib/shard-jobs.ts). --jobs applies only to --ci-run: a positive whole number up
- *       # to the shard's file count, else FREE_JOBS_INVALID. GSTACK_FREE_JOBS sets the local
- *       # full-suite process count and never changes --ci-run; --jobs is its only knob.
+ *       # k sub-shards side by side inside one CI job (default: the plan's per-shard k, else 1 =
+ *       # one child, today's behavior; scripts/lib/shard-jobs.ts). --jobs applies only to
+ *       # --ci-run and overrides the plan: a positive whole number up to the shard's file count,
+ *       # else FREE_JOBS_INVALID. --ci-verify requires every result to have run at the plan's k.
+ *       # GSTACK_FREE_JOBS sets the local full-suite process count and never changes --ci-run.
  *   bun run scripts/test-free-shards.ts --ci-verify plan.json --results results/
  */
 
@@ -97,8 +101,8 @@ import { attributeFreeHomeWriters, guardFreeHome, sharedFreeHome, type FreeHomeG
 import { appendStepSummary, ciHealthSummary, SEED_REFRESH_COMMAND, unseededWarning, windowsCurationLine } from './lib/free-ci-health';
 import { curateWindowsSafe, type CurationResult } from './lib/windows-curation';
 import {
-  assertSoloSeedSample, ciRunContext, parseJobsFlag, parseJunitCounts, readJunitReport, rejectJobsWithoutCiRun, runCiShard, SLOW_UNDER_LOAD, subShardRecordProblems,
-  validateJobsForShard, type ShardTestCounts, type SubShardRecord,
+  assertSoloSeedSample, ciRunContext, parseJobsFlag, parseJunitCounts, plannedShardJobs, plannedShardJobsProblem, readJunitReport, rejectJobsWithoutCiRun,
+  rejectShardJobsWithoutCiPlan, runCiShard, SLOW_UNDER_LOAD, subShardRecordProblems, validateJobsForShard, type ShardTestCounts, type SubShardRecord,
 } from './lib/shard-jobs';
 export { curateWindowsSafe, detectWindowsFragility, KNOWN_WINDOWS_INCOMPATIBLE, type CurationResult } from './lib/windows-curation';
 import {
@@ -424,19 +428,27 @@ export interface FreeCiPlan {
   version: 1;
   revision: string;
   id: string;
-  shards: Array<{ shard: number; files: string[]; predictedMs: number }>;
+  /** `jobs` is the shard's k from --shard-jobs, present only when above 1. */
+  shards: Array<{ shard: number; files: string[]; predictedMs: number; jobs?: number }>;
 }
 
+/** Files that run in the trailing serial sub-shard under k > 1, never beside another child. */
+const runsSerialUnderJobs = (file: string) => file in TREE_MUTATING || file in SLOW_UNDER_LOAD;
+
 const planDigest = (plan: Omit<FreeCiPlan, 'id'>): string =>
   createHash('sha256').update(JSON.stringify(plan)).digest('hex');
 
 /** One immutable plan is shared by isolated CI machines; never repack per job. */
-export function createFreeCiPlan(files: string[], count: number, durations: Record<string, number>, revision: string): FreeCiPlan {
+export function createFreeCiPlan(files: string[], count: number, durations: Record<string, number>, revision: string, shardJobs = 1): FreeCiPlan {
   const readers = files.filter(file => !(file in TREE_MUTATING));
   const exclusive = files.filter(file => file in TREE_MUTATING).sort();
   const packed = packShardsByDuration(readers, count, durations);
-  const shards = packed.shards.map((files, index) => ({ shard: index + 1, files, predictedMs: packed.predictedMs[index] }));
-  if (exclusive.length) shards.push({ shard: shards.length + 1, files: exclusive, predictedMs: exclusive.reduce((ms, file) => ms + (durations[file] ?? 0), 0) });
+  const planned = packed.shards.map((files, index) => ({ files, predictedMs: packed.predictedMs[index] }));
+  if (exclusive.length) planned.push({ files: exclusive, predictedMs: exclusive.reduce((ms, file) => ms + (durations[file] ?? 0), 0) });
+  const shards = planned.map(({ files, predictedMs }, index) => {
+    const jobs = plannedShardJobs(files, shardJobs, runsSerialUnderJobs);
+    return { shard: index + 1, files, predictedMs, ...(jobs ? { jobs } : {}) };
+  });
   const body = { version: 1 as const, revision, shards };
   return { ...body, id: planDigest(body) };
 }
@@ -447,6 +459,8 @@ export function validateFreeCiPlan(plan: FreeCiPlan, files: string[], revision:
     || id !== planDigest({ version, revision: plan.revision, shards })) throw new Error('CI plan identity or revision mismatch');
   if (shards.some((shard, index) => shard.shard !== index + 1 || !Array.isArray(shard.files)
     || !Number.isFinite(shard.predictedMs) || shard.predictedMs < 0)) throw new Error('Invalid CI shard plan');
+  const jobsProblems = shards.map(shard => plannedShardJobsProblem(shard, runsSerialUnderJobs)).filter(Boolean);
+  if (jobsProblems.length) throw new Error(`Invalid CI shard plan: ${jobsProblems.join('; ')}`);
   const planned = shards.flatMap(shard => shard.files).sort();
   if (new Set(planned).size !== planned.length || JSON.stringify(planned) !== JSON.stringify([...files].sort())) throw new Error('CI plan must cover every free file exactly once');
 }
@@ -486,6 +500,7 @@ export function verifyFreeCiResults(plan: FreeCiPlan, results: FreeCiResult[]):
     if (!hasCompleteCiSummary(outcome)) throw new Error('Missing or incomplete CI execution summary');
     const subShardProblems = subShardRecordProblems(result);
     if (subShardProblems.length) throw new Error(`CI shard ${outcome.shard} sub-shards rejected: ${subShardProblems.join('; ')}`);
+    if ((result.jobs ?? 1) !== (shard.jobs ?? 1)) throw new Error(`CI shard ${outcome.shard} ran at --jobs ${result.jobs ?? 1}; the plan says ${shard.jobs ?? 1}`);
     if (outcome.status === 'passed') {
       if (outcome.exitCode !== 0 || outcome.failingFiles.length || outcome.unattributedFailures || result.retry) throw new Error('Inconsistent passing CI result');
     } else {
@@ -556,8 +571,10 @@ type CliOptions = {
   result: string | null;
   results: string | null;
   filesFrom: string | null;
-  /** Set only by --jobs (with --ci-run); absent means k = 1. */
+  /** Set only by --jobs (with --ci-run); absent means the plan's per-shard k. */
   jobs?: number;
+  /** Set only by --shard-jobs (with --ci-plan); absent means k = 1 in every shard. */
+  shardJobs?: number;
 };
 
 export function parseCliOptions(argv: string[]): CliOptions {
@@ -573,6 +590,7 @@ export function parseCliOptions(argv: string[]): CliOptions {
   let quick = false;
   let attributeHome = false;
   let jobs: number | undefined;
+  let shardJobs: number | undefined;
   const paths: Record<'ciPlan' | 'ciRun' | 'ciVerify' | 'result' | 'results' | 'filesFrom', string | null> = {
     ciPlan: null, ciRun: null, ciVerify: null, result: null, results: null, filesFrom: null,
   };
@@ -597,6 +615,7 @@ export function parseCliOptions(argv: string[]): CliOptions {
     '--results': pathFlag('--results', 'results'),
     '--files-from': pathFlag('--files-from', 'filesFrom'),
     '--jobs': (next) => { jobs = parseJobsFlag(next()); },
+    '--shard-jobs': (next) => { shardJobs = parseJobsFlag(next(), '--shard-jobs'); },
     '--shards': (next) => {
       const value = next();
       if (!value) throw new Error('Missing value for --shards');
@@ -621,8 +640,9 @@ export function parseCliOptions(argv: string[]): CliOptions {
   if (paths.ciRun && (shardIndex === null || !paths.result)) throw new Error('--ci-run requires --shard and --result');
   if (paths.ciVerify && !paths.results) throw new Error('--ci-verify requires --results');
   if (jobs !== undefined && !paths.ciRun) rejectJobsWithoutCiRun();
+  if (shardJobs !== undefined && !paths.ciPlan) rejectShardJobsWithoutCiPlan();
   if (quick && (recordDurations || windowsOnly || shardIndex !== null)) throw new Error('--quick cannot change recording, Windows or shard selection');
-  return { dryRun, listOnly, recordDurations, windowsOnly, verbose, shardCount, shardIndex, wallTimeoutMs, wallTimeoutExplicit, quick, attributeHome, ...paths, ...(jobs === undefined ? {} : { jobs }) };
+  return { dryRun, listOnly, recordDurations, windowsOnly, verbose, shardCount, shardIndex, wallTimeoutMs, wallTimeoutExplicit, quick, attributeHome, ...paths, ...(jobs === undefined ? {} : { jobs }), ...(shardJobs === undefined ? {} : { shardJobs }) };
 }
 
 const describeLines = (lines: string[]) => `${lines.slice(0, 5).join(', ')}${lines.length > 5 ? ` (+${lines.length - 5} more)` : ''}`;
@@ -1350,6 +1370,8 @@ function trackShardBrowser(stateDir: string, env: NodeJS.ProcessEnv) {
         check(operation);
         if (!Number.isSafeInteger(pid) || (pid as number) <= 1) throw new BrowserCleanupError('invalid browser child identity');
         const identity = identities.get(pid as number);
+        if (!identity && identities.get(daemon as number)?.root) throw new BrowserCleanupError(
+          `browser child ownership is unconfirmed: recorded pid ${pid} (${await inspect(operation, pid as number) ? 'alive' : 'exited'}) was never seen in daemon ${daemon}'s process tree`);
         if (!identity || identity.daemon !== daemon || identity.root) throw new BrowserCleanupError('browser child ownership is unconfirmed');
         if (await live(operation, identity) && (typeof start !== 'string' || !start
           || await nativeStart(operation, identity) !== start.replace(/\s+/g, ' '))) throw new BrowserCleanupError('browser child identity was replaced');
@@ -1954,7 +1976,7 @@ async function main(): Promise<number> {
         appendStepSummary(line);
       }
       warnUnseededFreeFiles(ciFiles, durations);
-      const plan = createFreeCiPlan(ciFiles, options.shardCount, durations, revision);
+      const plan = createFreeCiPlan(ciFiles, options.shardCount, durations, revision, options.shardJobs);
       validateFreeCiPlan(plan, ciFiles, revision);
       writeJson(options.ciPlan, plan);
       console.log(JSON.stringify({ shard: plan.shards.map(shard => shard.shard) }));
@@ -1975,7 +1997,7 @@ async function main(): Promise<number> {
     }
     const shard = plan.shards[options.shardIndex! - 1];
     if (!shard || shard.shard !== options.shardIndex) throw new Error('CI shard index is outside the plan');
-    const jobs = options.jobs ?? 1;
+    const jobs = options.jobs ?? shard.jobs ?? 1;
     validateJobsForShard(jobs, shard.files.length, shard.shard);
     const durations = loadFreeTestDurations() ?? {};
     const { result, exitCode } = await runCiShard({
@@ -1986,7 +2008,7 @@ async function main(): Promise<number> {
       runShard: (files, shardNumber, totalShards, runOptions) => runFreeShard(files, shardNumber, totalShards, runOptions),
       retry: outcomes => retryFailedFreeFiles(outcomes, plan.shards.length, options),
       pack: (files, count) => packShardsByDuration(files, count, durations).shards,
-      isSerial: file => file in TREE_MUTATING || file in SLOW_UNDER_LOAD,
+      isSerial: runsSerialUnderJobs,
       terminationRequested: isTerminationRequested,
     });
     writeJson(options.result!, result);