@opengsd/gsd-core 1.6.0 → 1.7.0-rc.1

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;
@@ -259,6 +260,14 @@ function isManagedHookCommand(commandText, opts = {}) {
     }
     return false;
 }
+/**
+ * Detect a `"$VAR"/rest` anchored hook-script token — a path whose leading
+ * shell variable is already double-quoted with the remainder left bare (the
+ * shape `projectLocalHookPrefix` emits for local installs, e.g.
+ * `"$CLAUDE_PROJECT_DIR"/.claude/hooks/gsd-x.js`). Such a token is ALREADY a
+ * valid, correctly-quoted shell argument and must never be re-quoted.
+ */
+const ANCHORED_HOOK_SCRIPT_TOKEN = /^"\$[A-Za-z_][A-Za-z0-9_]*"\//;
 /**
  * Projection helper for legacy settings.json hook rewrites.
  *
@@ -270,8 +279,20 @@ function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptTo
     if (!absoluteRunner || !scriptPath)
         return null;
     const normalizedScriptPath = platform === 'win32' ? scriptPath.replace(/\\/g, '/') : scriptPath;
+    // #1693: a script path already carrying a `"$CLAUDE_PROJECT_DIR"`-anchored
+    // quoted prefix (local installs) is already a valid shell token — only the
+    // variable is quoted, the rest is bare. JSON.stringify-ing it on Windows
+    // yields `"\"$CLAUDE_PROJECT_DIR\"/..."` (escaped quotes inside an outer
+    // quote); node then receives an argument that *starts* with a `"`, treats it
+    // as relative, and dies with MODULE_NOT_FOUND. Emit anchored tokens verbatim;
+    // only bare absolute paths (which may contain spaces, e.g. "Program Files")
+    // need the JSON.stringify quoting. Scoped to win32: the non-Windows branch
+    // already preserves the caller's `scriptToken` (which is the bare anchored
+    // token for these inputs), so it never had the double-quote bug.
     const commandScriptToken = platform === 'win32'
-        ? JSON.stringify(normalizedScriptPath)
+        ? (ANCHORED_HOOK_SCRIPT_TOKEN.test(normalizedScriptPath)
+            ? normalizedScriptPath
+            : JSON.stringify(normalizedScriptPath))
         : (scriptToken || JSON.stringify(normalizedScriptPath));
     return projectShellCommandText({
         runnerToken: absoluteRunner,
@@ -555,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']);

package/gsd-core/bin/lib/state-io.cjs

@@ -0,0 +1,55 @@
+/**
+ * State IO seam (ADR-1239 Phase C-1, AC4 / #1680).
+ *
+ * Abstracts `.planning/` + config IO behind the negotiated `stateIO` axis
+ * (host-integration.cts):
+ *
+ *   - `filesystem`           — most hosts: reads/writes under `.planning/` +
+ *                              `configHome`. TODAY's behavior. Delegates to fs.
+ *   - `sandboxed-storage`    — VS Code web (no arbitrary FS). Seam: a
+ *                              host-supplied backend; fail-closed until Phase 5.
+ *   - `session-log-append`   — pi (JSONL session log). Seam: host-supplied
+ *                              backend; fail-closed until Phase 5.
+ *
+ * `filesystem` is the default and reproduces today's IO byte-for-behavior
+ * (planning-workspace.cts keeps routing its fs ops; this seam is the
+ * abstraction a non-filesystem host swaps in). `configHome` write-confinement
+ * (ADR-1239 Phase B / #1679) applies to the filesystem path.
+ *
+ * Minimal seam: the host-backend protocol is fixed when a real non-filesystem
+ * host lands (Phase 5 / #1682).
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStateIO = createStateIO;
+const node_fs_1 = __importDefault(require("node:fs"));
+function createStateIO({ io }, options = {}) {
+    if (io !== 'filesystem' && io !== 'sandboxed-storage' && io !== 'session-log-append') {
+        throw new TypeError(`createStateIO: io must be 'filesystem' | 'sandboxed-storage' | 'session-log-append' (got ${JSON.stringify(io)})`);
+    }
+    if (io === 'filesystem') {
+        // Today's behavior — straight fs. planning-workspace.cts keeps its routing;
+        // this is the swap-point a non-filesystem host replaces.
+        return Object.freeze({
+            io: 'filesystem',
+            read(path) { return node_fs_1.default.readFileSync(path, 'utf-8'); },
+            write(path, content) { node_fs_1.default.writeFileSync(path, content, 'utf-8'); },
+        });
+    }
+    // sandboxed-storage / session-log-append: host backend, fail-closed until bound.
+    const backend = options.backend;
+    const unbound = () => {
+        throw new Error(`${io} stateIO: no host backend bound — non-filesystem state requires a backend (Phase 5 wires the concrete host).`);
+    };
+    if (!backend || typeof backend.read !== 'function' || typeof backend.write !== 'function') {
+        return Object.freeze({ io, read: unbound, write: unbound });
+    }
+    return Object.freeze({
+        io,
+        read(path) { return backend.read(path); },
+        write(path, content) { backend.write(path, content); },
+    });
+}