@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -9,6 +9,30 @@
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 const path = _require('node:path');
+/**
+ * Asserts that `destSubpath` resolves to a path inside `configDir`.
+ *
+ * Rejects any path that escapes the configDir root (e.g. "../../etc") and any
+ * path containing a NUL byte. This is a security gate for Phase B of
+ * ADR-1239: third-party descriptors must never be able to write outside the
+ * designated config home directory.
+ *
+ * @param configDir - The root config directory (e.g. ~/.claude).
+ * @param destSubpath - The relative path declared by the runtime descriptor.
+ * @returns The resolved absolute path under configDir.
+ * @throws {Error} if destSubpath escapes configDir or contains a NUL byte.
+ */
+function assertDestWithinConfigHome(configDir, destSubpath) {
+    if (destSubpath.includes('\0')) {
+        throw new Error(`destSubpath "${destSubpath}" contains a NUL byte and is not valid`);
+    }
+    const root = path.resolve(configDir);
+    const resolved = path.resolve(configDir, destSubpath);
+    if (resolved === root || !resolved.startsWith(root + path.sep)) {
+        throw new Error(`destSubpath "${destSubpath}" must be a strict subpath of configHome "${configDir}" — not configHome itself or outside it (escapes configHome)`);
+    }
+    return resolved;
+}
 function errorMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -36,10 +60,34 @@ function createRuntimeArtifactInstallPlan(args) {
         platform,
         resolveAttribution,
     };
+    // ADR-1235 §1: build agentCtx once per plan so agents kind entries can apply
+    // the CORRECT pre-converter cross-cutting (path rewrites → attribution → converter
+    // → normalize). This mirrors the exact per-file order in the inline agent loop
+    // in bin/install.js (lines 9330-9415). agentCtx is passed as the second arg
+    // to kind.stage() for agents kind entries with a converter (convertedAgentsKind).
+    // NO _stampNonClaudeRuntimeDefaults — agents are NOT stamped in the inline loop.
+    const os = _require('node:os');
+    const homedirFn = homedir ?? (() => os.homedir());
+    const resolvedTarget = path.resolve(layout.configDir).replace(/\\/g, '/');
+    const homeDir = homedirFn().replace(/\\/g, '/');
+    const isGlobal = scope === 'global';
+    const isOpencode = layout.runtime === 'opencode';
+    const isWindowsHost = (platform ?? process.platform) === 'win32';
+    const pathPrefix = conversionExports._computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
+    const attribution = resolveAttribution ? resolveAttribution(layout.runtime) : undefined;
+    const agentCtx = { runtime: layout.runtime, pathPrefix, attribution };
     for (const kind of layout.kinds) {
         let stagedDir;
         try {
-            stagedDir = kind.stage(resolvedProfile);
+            if (kind.kind === 'agents') {
+                // ADR-1235 §1: pass agentCtx so stageAgentsForRuntimeWithConverter applies
+                // the full inline-loop order: pathRewrites → attribution → converter → normalize.
+                // The cross-cutting is now PRE-converter (inside staging), not POST.
+                stagedDir = kind.stage(resolvedProfile, agentCtx);
+            }
+            else {
+                stagedDir = kind.stage(resolvedProfile);
+            }
         }
         catch (err) {
             return { ok: false, kind: 'stage_failed', message: errorMessage(err), cleanupDirs, failedKind: kind.kind };
@@ -54,6 +102,8 @@ function createRuntimeArtifactInstallPlan(args) {
                 const rewrittenDir = rewriteStagedSkillBodies(stagedDir, rewriteOpts);
                 sourceDir = addCleanupDir(cleanupDirs, stagedDir, rewrittenDir);
             }
+            // agents kind: cross-cutting already applied INSIDE kind.stage() via agentCtx.
+            // No POST-step needed. sourceDir stays as stagedDir.
         }
         catch (err) {
             return { ok: false, kind: 'rewrite_failed', message: errorMessage(err), cleanupDirs, failedKind: kind.kind };
@@ -61,7 +111,7 @@ function createRuntimeArtifactInstallPlan(args) {
         items.push({
             kind: kind.kind,
             sourceDir,
-            destDir: path.join(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
         });
     }
     return { ok: true, plan: { items, cleanupDirs } };
@@ -70,8 +120,8 @@ function createRuntimeArtifactUninstallPlan(layout) {
     return {
         items: layout.kinds.map((kind) => ({
             kind: kind.kind,
-            destDir: path.join(layout.configDir, kind.destSubpath),
+            destDir: assertDestWithinConfigHome(layout.configDir, kind.destSubpath),
         })),
     };
 }
-module.exports = { createRuntimeArtifactInstallPlan, createRuntimeArtifactUninstallPlan };
+module.exports = { assertDestWithinConfigHome, createRuntimeArtifactInstallPlan, createRuntimeArtifactUninstallPlan };

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -156,13 +156,16 @@ function convertedAgentsKind(destSubpath, prefix, converterName, configDir, scop
         kind: 'agents',
         destSubpath,
         prefix,
-        stage: (resolved) => {
+        stage: (resolved, agentCtx) => {
             // isGlobal is threaded so scope-aware agent converters (copilot, antigravity)
             // choose global-home vs workspace-relative paths; converters that only take
             // (content) ignore the extra positional arg. Mirrors skillsKind's scope
             // threading (#1173).
             const converter = conversionExports[converterName];
-            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter, scope === 'global');
+            // ADR-1235 §1: when agentCtx is provided (by createRuntimeArtifactInstallPlan
+            // for descriptor-driven runtimes), thread it through so stageAgentsForRuntimeWithConverter
+            // can apply the full pre-converter + post-converter sequence in the correct order.
+            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter, scope === 'global', agentCtx);
         },
     };
 }

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -84,7 +84,7 @@ function atomicWriteFileSync(target, data, options) {
     __atomicWrittenTmps.add(tmp);
     try {
         node_fs_1.default.writeFileSync(tmp, data, options);
-        node_fs_1.default.renameSync(tmp, target);
+        shellCmdProjection.retryRenameSync(tmp, target);
         // Successful rename: the tmp path no longer exists, but leave it in the
         // Set so _cleanTmpFiles can recognise it as installer-owned if it somehow
         // lingers (e.g. a rename succeeded but left a stale entry on some FS).

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -19,6 +19,10 @@ exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
 exports.getDirName = getDirName;
+exports.getRuntimeLabel = getRuntimeLabel;
+exports.getGlobalConfigHomeFragment = getGlobalConfigHomeFragment;
+exports.runtimeFlags = runtimeFlags;
+exports.getRuntimeNewProjectCommand = getRuntimeNewProjectCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const FALLBACK_ALIASES = {
@@ -152,35 +156,161 @@ function getProjectInstructionFile(runtime) {
  * `bin/install.js` re-exports this same function for back-compat.
  */
 function getDirName(runtime) {
-    if (runtime === 'copilot')
-        return '.github';
-    if (runtime === 'opencode')
-        return '.opencode';
-    if (runtime === 'gemini')
-        return '.gemini';
-    if (runtime === 'kilo')
-        return '.kilo';
-    if (runtime === 'codex')
-        return '.codex';
-    if (runtime === 'antigravity')
-        return '.agents';
-    if (runtime === 'cursor')
-        return '.cursor';
-    if (runtime === 'windsurf')
-        return '.windsurf';
-    if (runtime === 'augment')
-        return '.augment';
-    if (runtime === 'trae')
-        return '.trae';
-    if (runtime === 'qwen')
-        return '.qwen';
-    if (runtime === 'hermes')
-        return '.hermes';
-    if (runtime === 'kimi')
-        return '.kimi-code';
-    if (runtime === 'codebuddy')
-        return '.codebuddy';
-    if (runtime === 'cline')
-        return '.cline';
+    if (!runtime)
+        return '.claude';
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { runtimes } = require('./capability-registry.cjs');
+    const dir = runtimes[runtime]?.runtime?.localConfigDir;
+    if (typeof dir === 'string' && dir.length > 0)
+        return dir;
     return '.claude';
 }
+/**
+ * Curated short display labels for the install/uninstall console output, keyed
+ * by canonical runtime id. The SINGLE source of truth consumed by both
+ * `install()` and `uninstall()` in bin/install.js via `getRuntimeLabel`.
+ *
+ * Collapses the two duplicated `runtimeLabel` assignment chains that previously
+ * lived inline in bin/install.js (ADR-1239 Phase B, #1679) — the add-a-host tax:
+ * a new runtime meant remembering to add a label line in BOTH chains, and they
+ * had drifted out of sync (uninstall omitted `cline` and used a different
+ * `kimi` value than install). This table is the curated canonical resolution:
+ *   - kimi:  install 'Kimi' / uninstall 'Kimi CLI'  → 'Kimi CLI' (majority + descriptor title)
+ *   - cline: install 'Cline' / uninstall (omitted)  → 'Cline'    (majority + descriptor title)
+ *
+ * Voice: these are the SHORT UI labels, intentionally distinct from the
+ * descriptor `title` (the long product name — e.g. "OpenAI Codex CLI",
+ * "GitHub Copilot", "Gemini CLI") which serves documentation/registry display,
+ * not the install console. A future slice may relocate this to a
+ * `runtime.label` descriptor field; until then this table is the source.
+ *
+ * Lookup is RAW-ID only (no alias expansion) — callers pass an already-
+ * canonicalized runtime id, keeping the label surface explicit. Unknown/empty
+ * ids fall back to 'Claude Code' (the always-safe default, fail-closed).
+ *
+ * The drift-guard test (tests/runtime-label-policy.test.cjs) pins this table's
+ * id set to the capability-registry runtime id set, so adding/removing a runtime
+ * forces a deliberate update here.
+ */
+const RUNTIME_LABELS = {
+    claude: 'Claude Code',
+    opencode: 'OpenCode',
+    gemini: 'Gemini',
+    kilo: 'Kilo',
+    codex: 'Codex',
+    copilot: 'Copilot',
+    antigravity: 'Antigravity',
+    cursor: 'Cursor',
+    windsurf: 'Windsurf',
+    augment: 'Augment',
+    trae: 'Trae',
+    qwen: 'Qwen Code',
+    hermes: 'Hermes Agent',
+    kimi: 'Kimi CLI',
+    codebuddy: 'CodeBuddy',
+    cline: 'Cline',
+};
+/**
+ * Map a canonical runtime id to its short display label for the
+ * install/uninstall console output. Unknown/empty inputs fall back to
+ * 'Claude Code'. Sibling to `getDirName`; pure (no I/O).
+ */
+function getRuntimeLabel(runtime) {
+    if (!runtime)
+        return 'Claude Code';
+    const label = RUNTIME_LABELS[runtime];
+    return typeof label === 'string' && label.length > 0 ? label : 'Claude Code';
+}
+/**
+ * Source-string fragments for the runtime → global config-home path, used by
+ * `getConfigDirFromHome` in bin/install.js to template `path.join()` calls in
+ * generated hook scripts. Each value is a JS-source snippet (embedded quotes /
+ * commas are intentional — it is spliced into generated code as path.join args).
+ *
+ * Collapses the prior 14-branch `if (runtime === 'x') return "'...'"` chain in
+ * bin/install.js (ADR-1239 Phase B / #1679, AC2 slice 2) — the add-a-host tax:
+ * a new runtime meant remembering to add a branch here. Values are preserved
+ * BYTE-FOR-BYTE from the prior chain; golden install parity asserts generated
+ * hook output is unchanged across all 16 runtimes.
+ *
+ * Two runtimes are intentionally absent (handled by the caller, NOT this table):
+ *   - `claude`     → the default; falls through to `DEFAULT_FRAGMENT`.
+ *   - `antigravity`→ resolved dynamically via resolveAntigravityGlobalDir +
+ *                    path.relative (multi-segment, env-overridable).
+ *
+ * Unknown/empty ids fall back to the default (`.claude`).
+ */
+const DEFAULT_CONFIG_HOME_FRAGMENT = "'.claude'";
+const GLOBAL_CONFIG_HOME_FRAGMENTS = {
+    copilot: "'.copilot'",
+    opencode: "'.config', 'opencode'",
+    gemini: "'.gemini'",
+    kilo: "'.config', 'kilo'",
+    codex: "'.codex'",
+    cursor: "'.cursor'",
+    windsurf: "'.windsurf'",
+    augment: "'.augment'",
+    trae: "'.trae'",
+    qwen: "'.qwen'",
+    hermes: "'.hermes'",
+    codebuddy: "'.codebuddy'",
+    cline: "'.cline'",
+    kimi: "'.config', 'agents'",
+};
+/**
+ * Return the global config-home path-fragment source snippet for a runtime
+ * (for hook path.join() codegen). `claude`/unknown/empty → the default
+ * `'.claude'` fragment. `antigravity` is NOT handled here (caller resolves it
+ * dynamically). Pure: no I/O. Sibling to `getDirName` / `getRuntimeLabel`.
+ */
+function getGlobalConfigHomeFragment(runtime) {
+    if (!runtime)
+        return DEFAULT_CONFIG_HOME_FRAGMENT;
+    const frag = GLOBAL_CONFIG_HOME_FRAGMENTS[runtime];
+    return typeof frag === 'string' && frag.length > 0 ? frag : DEFAULT_CONFIG_HOME_FRAGMENT;
+}
+/**
+ * The runtime ids for which `bin/install.js` needs an `is<Runtime>` boolean
+ * predicate (every installed host that takes a non-claude install branch).
+ * Single source of truth — adding a runtime is one entry here, not a per-
+ * function declaration block (the add-a-host tax ADR-1239 Phase B / #1679 AC2
+ * removes).
+ */
+const RUNTIME_FLAG_IDS = Object.freeze([
+    'opencode', 'kilo', 'gemini', 'codex', 'copilot', 'antigravity', 'cursor',
+    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi',
+]);
+/**
+ * Return a frozen map of `is<Runtime>` boolean predicates for the given runtime
+ * id (e.g. `flags.isOpencode`). Collapses the four duplicated `const isX =
+ * runtime === 'x'` declaration blocks that lived in `bin/install.js`'s
+ * `uninstall`/`writeManifest`/`install`/etc. into one helper (sibling to
+ * `getDirName`/`getRuntimeLabel`). Pure: no I/O.
+ */
+function runtimeFlags(runtime) {
+    const flags = {};
+    for (const id of RUNTIME_FLAG_IDS) {
+        flags['is' + id.charAt(0).toUpperCase() + id.slice(1)] = runtime === id;
+    }
+    return Object.freeze(flags);
+}
+/**
+ * The `/gsd-new-project` invocation syntax per runtime — the post-install
+ * "next step" command string. Most runtimes use the default `/gsd-new-project`;
+ * a few hosts need a different surface syntax. Collapses the 14-line
+ * `if (runtime === 'x') command = ...` chain in bin/install.js's next-step
+ * message (ADR-1239 Phase B / #1679 AC2). Pure: no I/O.
+ */
+const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
+const RUNTIME_NEW_PROJECT_COMMANDS = {
+    gemini: '/gsd:new-project',
+    codex: '$gsd-new-project',
+    cursor: 'gsd-new-project (mention the skill name)',
+    kimi: '/skill:gsd-new-project',
+};
+function getRuntimeNewProjectCommand(runtime) {
+    if (!runtime)
+        return DEFAULT_NEW_PROJECT_COMMAND;
+    const c = RUNTIME_NEW_PROJECT_COMMANDS[runtime];
+    return typeof c === 'string' && c.length > 0 ? c : DEFAULT_NEW_PROJECT_COMMAND;
+}

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -40,6 +40,7 @@ exports.execNpm = execNpm;
 exports.execTool = execTool;
 exports.probeTty = probeTty;
 exports.normalizeContent = normalizeContent;
+exports.retryRenameSync = retryRenameSync;
 exports.platformWriteSync = platformWriteSync;
 exports.platformReadSync = platformReadSync;
 exports.platformEnsureDir = platformEnsureDir;
@@ -575,6 +576,21 @@ function atomicRenameWithRetry(tmpPath, filePath) {
     }
     return renameErr;
 }
+/**
+ * Drop-in replacement for `fs.renameSync(from, to)` that retries the transient
+ * Windows lock errnos (EPERM/EBUSY/EACCES — see DEFECT.WINDOWS-FS-OPS) a bounded
+ * number of times with a short backoff before rethrowing the final error.
+ *
+ * Idempotent on POSIX (the transient errnos do not occur), so callers retain
+ * identical semantics on macOS/Linux while gaining resilience on Windows where
+ * an antivirus scanner, indexer, or concurrent reader may briefly hold the
+ * target open. Enforced by local/require-fs-op-fallback (ADR-1703 Phase 6).
+ */
+function retryRenameSync(fromPath, toPath) {
+    const err = atomicRenameWithRetry(fromPath, toPath);
+    if (err !== null)
+        throw err;
+}
 function platformWriteSync(filePath, content, opts = {}) {
     const { content: normalized, encoding } = normalizeContent(filePath, content, opts);
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });

package/gsd-core/bin/lib/stale-bake-guard.cjs

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * Stale-bake guard for static-frontmatter runtimes (#1688, follow-up to #1650).
+ *
+ * Runtimes `codex` and `opencode` bake the resolved model ID into each agent's
+ * static config at install time (bin/install.js ~5667-5767 for codex,
+ * ~10008-10026 for opencode). Their task/spawn_agent interfaces do not accept
+ * an inline `model` parameter, so editing `model_overrides` in
+ * `.planning/config.json` or `~/.gsd/defaults.json` has NO effect until the
+ * user re-runs `gsd install <runtime>` (or `gsd update`). The failure is
+ * silent — the sub-agent just uses the prior base model. This module detects
+ * that staleness at workflow entry and emits a single stderr warning.
+ *
+ * Design: pure decision + formatter (testable, no I/O) backed by fs probes
+ * that swallow every error (the guard must never break the CLI). Dedup'd per
+ * (runtime, cwd) within a process so a single `gsd-tools init *` invocation
+ * warns at most once even though multiple agents resolve models underneath.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Runtimes whose agent config is static frontmatter/TOML baked at install time.
+ * MUST stay in sync with the bake paths in bin/install.js. The parity test in
+ * tests/stale-bake-guard.test.cjs asserts this matches the runtimes that
+ * actually emit a baked model: line id #2256 (opencode) and #49/#2256 (codex).
+ */
+const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'opencode']);
+
+const _warnedKeys = new Set();
+
+/**
+ * Pure: decide whether a stale-bake condition exists.
+ *
+ * Returns `{ stale: true, deltaMs }` when `configMtimeMs` is strictly newer
+ * than `agentMtimeMs` on a static-frontmatter runtime. Returns `null` when the
+ * guard does not apply (claude / other spawn-time runtime, missing or
+ * non-finite mtimes, or agents already at least as new as config).
+ */
+function detectStaleBake({ runtime, configMtimeMs, agentMtimeMs }) {
+  if (!runtime || !STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return null;
+  if (typeof configMtimeMs !== 'number' || typeof agentMtimeMs !== 'number') return null;
+  if (!Number.isFinite(configMtimeMs) || !Number.isFinite(agentMtimeMs)) return null;
+  if (configMtimeMs <= agentMtimeMs) return null;
+  return { stale: true, deltaMs: configMtimeMs - agentMtimeMs };
+}
+
+/**
+ * Pure: format the warning string. Returns `''` when no warning is warranted
+ * (delegates to detectStaleBake so the decision and the message cannot drift).
+ */
+function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtimeMs }) {
+  const signal = detectStaleBake({ runtime, configMtimeMs, agentMtimeMs });
+  if (!signal) return '';
+  const configDate = new Date(configMtimeMs).toISOString();
+  const installFlag = runtime === 'opencode' ? '--opencode' : '--codex';
+  return [
+    `gsd: model config in ${configPath} changed since agents were last baked (${configDate}).`,
+    `     Static-frontmatter runtime '${runtime}' ignores the new model_overrides`,
+    `     until you re-run:  gsd install ${installFlag}`,
+    `     (or 'gsd update')`,
+  ].join('\n');
+}
+
+/**
+ * Pure: resolve the active runtime id from a parsed config object.
+ * Returns the runtime string, or `'claude'` when unset (the spawn-time default
+ * for which the guard is a no-op).
+ */
+function resolveRuntimeFromConfig(config) {
+  if (config && typeof config === 'object'
+      && typeof config.runtime === 'string' && config.runtime) {
+    return config.runtime;
+  }
+  return 'claude';
+}
+
+/**
+ * Resolve the install root for a runtime's agent files, honoring the same env
+ * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR). Returns the
+ * absolute directory or `null` for unsupported runtimes.
+ */
+function resolveAgentDir(runtime, { env = process.env, homedir = os.homedir } = {}) {
+  if (runtime === 'opencode') {
+    const base = (env.OPENCODE_CONFIG_DIR && String(env.OPENCODE_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'opencode');
+    return path.join(base, 'agent');
+  }
+  if (runtime === 'codex') {
+    const base = (env.CODEX_HOME && String(env.CODEX_HOME).trim()) || path.join(homedir(), '.codex');
+    return path.join(base, 'agents');
+  }
+  return null;
+}
+
+/**
+ * Find the newest mtime across config sources that exist. Mirrors the
+ * up-to-8-levels-up walk in readGsdEffectiveModelOverrides (bin/install.js)
+ * and includes the global ~/.gsd/defaults.json. Returns
+ * `{ mtimeMs, path }` of the newest existing config, or `null` if none exist.
+ *
+ * `homedir` is injectable so tests can point the global lookup at a fixture
+ * dir (otherwise the real ~/.gsd/defaults.json on the CI runner leaks in and
+ * skews the newest-config calculation — see warnIfStaleBake orchestrator).
+ */
+function findNewestConfigMtime(cwd, { fsStatSync = fs.statSync, homedir = os.homedir } = {}) {
+  const candidates = [];
+  let probe = path.resolve(cwd || '.');
+  for (let i = 0; i < 8; i += 1) {
+    candidates.push(path.join(probe, '.planning', 'config.json'));
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  candidates.push(path.join(homedir(), '.gsd', 'defaults.json'));
+
+  let newest = null;
+  for (const p of candidates) {
+    try {
+      const st = fsStatSync(p);
+      if (st && typeof st.mtimeMs === 'number' && Number.isFinite(st.mtimeMs)
+          && (!newest || st.mtimeMs > newest.mtimeMs)) {
+        newest = { mtimeMs: st.mtimeMs, path: p };
+      }
+    } catch {
+      // not present / unreadable — skip
+    }
+  }
+  return newest;
+}
+
+/**
+ * Find the oldest mtime across installed gsd-* agent files for the runtime.
+ * Returns `{ mtimeMs, dir }` or `null` if the agent dir is absent or holds no
+ * gsd-* files (e.g. not yet installed, or uninstalled).
+ */
+function findOldestAgentMtime(runtime, { env = process.env, homedir = os.homedir, fsStatSync = fs.statSync, fsReaddirSync = fs.readdirSync } = {}) {
+  const dir = resolveAgentDir(runtime, { env, homedir });
+  if (!dir) return null;
+  let entries;
+  try {
+    entries = fsReaddirSync(dir, { withFileTypes: true });
+  } catch {
+    return null; // dir missing — runtime not installed for this user
+  }
+  let oldest = null;
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.startsWith('gsd-')) continue;
+    const isAgentFile = (runtime === 'opencode' && entry.name.endsWith('.md'))
+      || (runtime === 'codex' && (entry.name.endsWith('.toml') || entry.name.endsWith('.md')));
+    if (!isAgentFile) continue;
+    try {
+      const st = fsStatSync(path.join(dir, entry.name));
+      if (st && typeof st.mtimeMs === 'number' && Number.isFinite(st.mtimeMs)
+          && (!oldest || st.mtimeMs < oldest.mtimeMs)) {
+        oldest = { mtimeMs: st.mtimeMs, dir };
+      }
+    } catch {
+      // unreadable — skip
+    }
+  }
+  return oldest;
+}
+
+/**
+ * Orchestrator (side-effecting): probe fs, decide, write warning to stderr.
+ *
+ * - Silent on claude / other spawn-time runtimes (returns false).
+ * - Silent when agents are already at least as new as config.
+ * - Silent when config or agent dir is absent (nothing to compare).
+ * - Dedup'd per (runtime, cwd): a single process warns at most once per pair,
+ *   so repeated `resolveModelInternal` calls under one `gsd-tools init *` do
+ *   not repeat the warning.
+ * - Swallows every error: a warning helper must never break the CLI.
+ *
+ * Pass `config` to skip the internal JSON read (caller already loaded it).
+ * Returns `true` if a warning was written, `false` otherwise.
+ */
+function warnIfStaleBake(cwd, options = {}) {
+  const {
+    stderr = process.stderr,
+    config = null,
+    env = process.env,
+    homedir = os.homedir,
+    fsStatSync = fs.statSync,
+    fsReaddirSync = fs.readdirSync,
+  } = options;
+  try {
+    const resolvedConfig = config || _readRuntimeConfig(cwd, { fsStatSync });
+    const runtime = resolveRuntimeFromConfig(resolvedConfig);
+    if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return false;
+
+    const dedupKey = `${runtime}::${path.resolve(cwd || '.')}`;
+    if (_warnedKeys.has(dedupKey)) return false;
+
+    const newest = findNewestConfigMtime(cwd, { fsStatSync, homedir });
+    const oldest = findOldestAgentMtime(runtime, { env, homedir, fsStatSync, fsReaddirSync });
+    if (!newest || !oldest) return false;
+
+    const warning = formatStaleBakeWarning({
+      runtime,
+      configPath: newest.path,
+      configMtimeMs: newest.mtimeMs,
+      agentMtimeMs: oldest.mtimeMs,
+    });
+    if (!warning) return false;
+
+    stderr.write(warning + '\n');
+    _warnedKeys.add(dedupKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort minimal read of `.planning/config.json` for the `runtime` key. */
+function _readRuntimeConfig(cwd, { fsStatSync = fs.statSync } = {}) {
+  let probe = path.resolve(cwd || '.');
+  for (let i = 0; i < 8; i += 1) {
+    const candidate = path.join(probe, '.planning', 'config.json');
+    try {
+      fsStatSync(candidate);
+      const raw = fs.readFileSync(candidate, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') return parsed;
+      return {};
+    } catch {
+      // not present / unreadable / malformed — walk up
+    }
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  return {};
+}
+
+/** Test-only: reset the in-process dedup set between cases. */
+function _resetWarnedForTests() {
+  _warnedKeys.clear();
+}
+
+module.exports = {
+  STATIC_FRONTMATTER_RUNTIMES,
+  detectStaleBake,
+  formatStaleBakeWarning,
+  resolveRuntimeFromConfig,
+  resolveAgentDir,
+  findNewestConfigMtime,
+  findOldestAgentMtime,
+  warnIfStaleBake,
+  _resetWarnedForTests,
+};

package/gsd-core/bin/lib/state-command-router.cjs

@@ -155,6 +155,10 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['keep-recent'], ['dry-run']);
                 state.cmdStatePrune(cwd, { keepRecent: strArg(a, 'keep-recent') || '3', dryRun: a['dry-run'] === true }, raw);
             },
+            rebuild: () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['dry-run', 'verbose']);
+                state.cmdStateRebuild(cwd, { dryRun: a['dry-run'] === true, verbose: a['verbose'] === true }, raw);
+            },
             // complete-phase: CJS-only — no SDK counterpart.
             'complete-phase': () => {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase']);