gsd-pi 2.67.0-dev.46f9884 → 2.67.0-dev.a5b1d8f

package/dist/resource-loader.d.ts

@@ -22,5 +22,5 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
 export declare function initResources(agentDir: string): void;
-export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string): boolean;
+export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir?: string): boolean;
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -384,11 +384,13 @@ export function initResources(agentDir) {
     mkdirSync(agentDir, { recursive: true });
     const currentVersion = getBundledGsdVersion();
     const manifest = readManagedResourceManifest(agentDir);
+    const extensionsDir = join(agentDir, 'extensions');
     // Always prune root-level extension files that were removed from the bundle.
     // This is cheap (a few existence checks + at most one rmSync) and must run
     // unconditionally so that stale files left by a previous version are cleaned
     // up even when the version/hash match causes the full sync to be skipped.
     pruneRemovedBundledExtensions(manifest, agentDir);
+    pruneStaleSiblingFiles(bundledExtensionsDir, extensionsDir);
     // Ensure ~/.gsd/agent/node_modules symlinks to GSD's node_modules on EVERY
     // launch, not just during resource syncs. A stale/broken symlink makes ALL
     // extensions fail to resolve @gsd/* packages, rendering GSD non-functional.
@@ -402,7 +404,7 @@ export function initResources(agentDir) {
     if (manifest && manifest.gsdVersion === currentVersion) {
         // Version matches — check content fingerprint for same-version staleness.
         const currentHash = computeResourceFingerprint();
-        const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(join(agentDir, 'extensions'));
+        const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(extensionsDir, bundledExtensionsDir);
         if (manifest.contentHash && manifest.contentHash === currentHash && !hasStaleExtensionFiles) {
             return;
         }
@@ -555,14 +557,27 @@ function migrateSkillsToEcosystemDir(agentDir) {
         }
     }
 }
-export function hasStaleCompiledExtensionSiblings(extensionsDir) {
+export function hasStaleCompiledExtensionSiblings(extensionsDir, sourceDir = bundledExtensionsDir) {
     if (!existsSync(extensionsDir))
         return false;
+    const sourceFiles = existsSync(sourceDir)
+        ? new Set(readdirSync(sourceDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name))
+        : new Set();
     for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith('.ts'))
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.js'))
+            continue;
+        const siblingName = entry.name.endsWith('.ts')
+            ? entry.name.replace(/\.ts$/, '.js')
+            : entry.name.replace(/\.js$/, '.ts');
+        if (!existsSync(join(extensionsDir, siblingName)))
+            continue;
+        if (sourceFiles.has(entry.name) && sourceFiles.has(siblingName))
             continue;
-        const jsName = entry.name.replace(/\.ts$/, '.js');
-        if (existsSync(join(extensionsDir, jsName))) {
+        if (sourceFiles.has(entry.name) || sourceFiles.has(siblingName)) {
             return true;
         }
     }

package/dist/resources/GSD-WORKFLOW.md

@@ -18,7 +18,8 @@ Read these files in order and act on what they say:
 3. **`.gsd/milestones/<active>/M###-CONTEXT.md`** — Milestone-level project decisions, reference paths, constraints. Read this before doing implementation work.
 4. If a slice is active and has one, read **`S##-CONTEXT.md`** — Slice-specific decisions and constraints.
 5. If a slice is active, read its **`S##-PLAN.md`** — Which tasks exist? Which are done?
-6. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
+6. If `.gsd/CODEBASE.md` exists, skim it for fast structural orientation before broad code exploration.
+7. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
 
 Then do the thing `STATE.md` says to do next.
 
@@ -44,6 +45,7 @@ All artifacts live in `.gsd/` at the project root:
 .gsd/
   STATE.md                                  # Dashboard — always read first (derived cache; runtime, gitignored)
   DECISIONS.md                              # Append-only decisions register
+  CODEBASE.md                               # Generated codebase map cache (auto-refreshed by GSD)
   milestones/
     M001/
       M001-ROADMAP.md                       # Milestone plan (checkboxes = state)

package/dist/resources/extensions/get-secrets-from-user.js

@@ -25,6 +25,12 @@ function maskPreview(value) {
 function shellEscapeSingle(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function isSafeEnvVarKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+function isSupportedDeploymentEnvironment(env) {
+    return env === "development" || env === "preview" || env === "production";
+}
 function hydrateProcessEnv(key, value) {
     // Make newly collected secrets immediately visible to the current session.
     // Some extensions read process.env directly and do not reload .env on every call.
@@ -263,12 +269,22 @@ async function applySecrets(provided, destination, opts) {
     }
     if ((destination === "vercel" || destination === "convex") && opts.exec) {
         const env = opts.environment ?? "development";
+        if (!isSupportedDeploymentEnvironment(env)) {
+            errors.push(`environment: unsupported target environment "${env}"`);
+            return { applied, errors };
+        }
         for (const { key, value } of provided) {
+            if (!isSafeEnvVarKey(key)) {
+                errors.push(`${key}: invalid environment variable name`);
+                continue;
+            }
             const cmd = destination === "vercel"
                 ? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`
-                : `npx convex env set ${key} ${shellEscapeSingle(value)}`;
+                : "";
             try {
-                const result = await opts.exec("sh", ["-c", cmd]);
+                const result = destination === "vercel"
+                    ? await opts.exec("sh", ["-c", cmd])
+                    : await opts.exec("npx", ["convex", "env", "set", key, value]);
                 if (result.code !== 0) {
                     errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
                 }

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -40,6 +40,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getSliceTasks } from "./gsd-db.js";
 import { runPreExecutionChecks } from "./pre-execution-checks.js";
 import { writePreExecutionEvidence } from "./verification-evidence.js";
+import { ensureCodebaseMapFresh } from "./codebase-generator.js";
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
 /** Enqueue a sidecar item (hook, triage, or quick-task) for the main loop to
@@ -553,6 +554,31 @@ export async function postUnitPreVerification(pctx, opts) {
  */
 export async function postUnitPostVerification(pctx) {
     const { s, ctx, pi, buildSnapshotOpts, lockBase, stopAuto, pauseAuto, updateProgressWidget } = pctx;
+    if (s.currentUnit) {
+        try {
+            const codebasePrefs = loadEffectiveGSDPreferences()?.preferences?.codebase;
+            const refresh = ensureCodebaseMapFresh(s.basePath, codebasePrefs
+                ? {
+                    excludePatterns: codebasePrefs.exclude_patterns,
+                    maxFiles: codebasePrefs.max_files,
+                    collapseThreshold: codebasePrefs.collapse_threshold,
+                }
+                : undefined, { force: true, ttlMs: 0 });
+            if (refresh.status === "generated" || refresh.status === "updated") {
+                debugLog("postUnit", {
+                    phase: "codebase-refresh",
+                    unitType: s.currentUnit.type,
+                    unitId: s.currentUnit.id,
+                    status: refresh.status,
+                    fileCount: refresh.fileCount,
+                    reason: refresh.reason,
+                });
+            }
+        }
+        catch (e) {
+            logWarning("engine", `CODEBASE refresh failed: ${e.message}`);
+        }
+    }
     // ── Post-unit hooks ──
     if (s.currentUnit && !s.stepMode) {
         const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -8,6 +8,7 @@ import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
@@ -103,10 +104,24 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         }
     }
     let codebaseBlock = "";
+    try {
+        const codebaseOptions = loadedPreferences?.preferences?.codebase
+            ? {
+                excludePatterns: loadedPreferences.preferences.codebase.exclude_patterns,
+                maxFiles: loadedPreferences.preferences.codebase.max_files,
+                collapseThreshold: loadedPreferences.preferences.codebase.collapse_threshold,
+            }
+            : undefined;
+        ensureCodebaseMapFresh(process.cwd(), codebaseOptions);
+    }
+    catch (e) {
+        logWarning("bootstrap", `CODEBASE refresh failed: ${e.message}`);
+    }
     const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE");
-    if (existsSync(codebasePath)) {
+    const rawCodebase = readCodebaseMap(process.cwd());
+    if (existsSync(codebasePath) && rawCodebase) {
         try {
-            const rawContent = readFileSync(codebasePath, "utf-8").trim();
+            const rawContent = rawCodebase.trim();
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
@@ -116,7 +131,7 @@ export async function buildBeforeAgentStartResult(event, ctx) {
                 const content = rawContent.length > MAX_CODEBASE_CHARS
                     ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
-                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, may be stale — run /gsd codebase update to refresh)]\n\n${content}`;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
         }
         catch (e) {

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -7,6 +7,7 @@
  * Generation: walk `git ls-files`, group by directory, output with descriptions.
  * Maintenance: agent updates descriptions as it works; incremental update preserves them.
  */
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname, extname } from "node:path";
 import { execSync } from "node:child_process";
@@ -31,6 +32,10 @@ const DEFAULT_EXCLUDES = [
 ];
 const DEFAULT_MAX_FILES = 500;
 const DEFAULT_COLLAPSE_THRESHOLD = 20;
+const DEFAULT_REFRESH_TTL_MS = 30_000;
+const DEFAULT_MAX_AGE_MS = 15 * 60_000;
+const CODEBASE_METADATA_PREFIX = "<!-- gsd:codebase-meta ";
+const freshnessCache = new Map();
 // ─── Parsing ─────────────────────────────────────────────────────────────────
 /**
  * Parse an existing CODEBASE.md to extract file → description mappings.
@@ -66,6 +71,31 @@ export function parseCodebaseMap(content) {
     }
     return descriptions;
 }
+export function parseCodebaseMapMetadata(content) {
+    const metaLine = content
+        .split("\n")
+        .find((line) => line.trimStart().startsWith(CODEBASE_METADATA_PREFIX));
+    if (!metaLine)
+        return null;
+    const trimmed = metaLine.trim();
+    const jsonStart = CODEBASE_METADATA_PREFIX.length;
+    const jsonEnd = trimmed.lastIndexOf(" -->");
+    if (jsonEnd <= jsonStart)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd));
+        if (typeof parsed?.generatedAt === "string"
+            && typeof parsed?.fingerprint === "string"
+            && typeof parsed?.fileCount === "number"
+            && typeof parsed?.truncated === "boolean") {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore malformed metadata and treat the map as stale.
+    }
+    return null;
+}
 // ─── File Enumeration ────────────────────────────────────────────────────────
 function shouldExclude(filePath, excludes) {
     for (const pattern of excludes) {
@@ -103,6 +133,30 @@ function enumerateFiles(basePath, excludes, maxFiles) {
     const truncated = filtered.length > maxFiles;
     return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
+function resolveGeneratorOptions(options) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
+    const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
+    const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
+    return {
+        excludes,
+        maxFiles,
+        collapseThreshold,
+        optionSignature: JSON.stringify({
+            excludes,
+            maxFiles,
+            collapseThreshold,
+        }),
+    };
+}
+function computeCodebaseFingerprint(files, resolved, truncated) {
+    return createHash("sha1")
+        .update(JSON.stringify({
+        files,
+        truncated,
+        optionSignature: resolved.optionSignature,
+    }))
+        .digest("hex");
+}
 // ─── Grouping ────────────────────────────────────────────────────────────────
 function groupByDirectory(files, descriptions, collapseThreshold) {
     const dirMap = new Map();
@@ -131,13 +185,13 @@ function groupByDirectory(files, descriptions, collapseThreshold) {
     return groups;
 }
 // ─── Rendering ───────────────────────────────────────────────────────────────
-function renderCodebaseMap(groups, totalFiles, truncated) {
+function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
     const lines = [];
-    const now = new Date().toISOString().split(".")[0] + "Z";
     const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0);
     lines.push("# Codebase Map");
     lines.push("");
-    lines.push(`Generated: ${now} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+    lines.push(`Generated: ${metadata.generatedAt} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+    lines.push(`${CODEBASE_METADATA_PREFIX}${JSON.stringify(metadata)} -->`);
     if (truncated) {
         lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
     }
@@ -182,20 +236,35 @@ function renderCodebaseMap(groups, totalFiles, truncated) {
     }
     return lines.join("\n");
 }
+function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated) {
+    const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const descriptions = existingDescriptions ?? new Map();
+    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+    const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+    const metadata = {
+        generatedAt,
+        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+        fileCount: listed.files.length,
+        truncated: listed.truncated,
+    };
+    const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
+    return {
+        content,
+        fileCount: listed.files.length,
+        truncated: listed.truncated,
+        files: listed.files,
+        fingerprint: metadata.fingerprint,
+        generatedAt,
+    };
+}
 // ─── Public API ──────────────────────────────────────────────────────────────
 /**
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
 export function generateCodebaseMap(basePath, options, existingDescriptions) {
-    const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
-    const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
-    const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
-    const { files, truncated } = enumerateFiles(basePath, excludes, maxFiles);
-    const descriptions = existingDescriptions ?? new Map();
-    const groups = groupByDirectory(files, descriptions, collapseThreshold);
-    const content = renderCodebaseMap(groups, files.length, truncated);
-    return { content, fileCount: files.length, truncated, files };
+    const resolved = resolveGeneratorOptions(options);
+    return buildCodebaseMap(basePath, resolved, existingDescriptions);
 }
 /**
  * Incremental update: re-scan files, preserve existing descriptions,
@@ -203,6 +272,7 @@ export function generateCodebaseMap(basePath, options, existingDescriptions) {
  */
 export function updateCodebaseMap(basePath, options) {
     const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+    const resolved = resolveGeneratorOptions(options);
     // Load existing descriptions
     let existingDescriptions = new Map();
     if (existsSync(codebasePath)) {
@@ -212,7 +282,7 @@ export function updateCodebaseMap(basePath, options) {
     const existingFiles = new Set(existingDescriptions.keys());
     // Generate new map preserving descriptions — reuse the returned file list
     // to avoid a second enumeration (prevents race between content and stats).
-    const result = generateCodebaseMap(basePath, options, existingDescriptions);
+    const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
     const currentSet = new Set(result.files);
     // Count changes
     let added = 0;
@@ -232,8 +302,98 @@ export function updateCodebaseMap(basePath, options) {
         unchanged: result.files.length - added,
         fileCount: result.fileCount,
         truncated: result.truncated,
+        fingerprint: result.fingerprint,
+        generatedAt: result.generatedAt,
     };
 }
+function clearFreshnessCache(basePath) {
+    for (const key of freshnessCache.keys()) {
+        if (key === basePath || key.startsWith(`${basePath}::`)) {
+            freshnessCache.delete(key);
+        }
+    }
+}
+export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
+    const resolved = resolveGeneratorOptions(options);
+    const cacheKey = `${basePath}::${resolved.optionSignature}`;
+    const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
+    const maxAgeMs = ensureOptions?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const force = ensureOptions?.force === true;
+    const now = Date.now();
+    if (!force && ttlMs > 0) {
+        const cached = freshnessCache.get(cacheKey);
+        if (cached && now - cached.checkedAt < ttlMs) {
+            return cached.result;
+        }
+    }
+    const existing = readCodebaseMap(basePath);
+    const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+    const cacheAndReturn = (result) => {
+        freshnessCache.set(cacheKey, { checkedAt: now, result });
+        return result;
+    };
+    if (!existing) {
+        const generated = buildCodebaseMap(basePath, resolved, undefined, listed);
+        if (generated.fileCount > 0) {
+            writeCodebaseMap(basePath, generated.content);
+            return cacheAndReturn({
+                status: "generated",
+                fileCount: generated.fileCount,
+                truncated: generated.truncated,
+                generatedAt: generated.generatedAt,
+                fingerprint: generated.fingerprint,
+                reason: "missing",
+            });
+        }
+        return cacheAndReturn({
+            status: "empty",
+            fileCount: 0,
+            truncated: false,
+            generatedAt: null,
+            fingerprint,
+            reason: "no-tracked-files",
+        });
+    }
+    const metadata = parseCodebaseMapMetadata(existing);
+    const existingDescriptions = parseCodebaseMap(existing);
+    const ageMs = metadata ? now - Date.parse(metadata.generatedAt) : Number.POSITIVE_INFINITY;
+    const staleReason = !metadata ? "missing-metadata"
+        : metadata.fingerprint !== fingerprint ? "files-changed"
+            : metadata.fileCount !== listed.files.length ? "file-count-changed"
+                : metadata.truncated !== listed.truncated ? "truncation-changed"
+                    : maxAgeMs > 0 && Number.isFinite(ageMs) && ageMs > maxAgeMs ? "expired"
+                        : undefined;
+    if (!staleReason) {
+        return cacheAndReturn({
+            status: "fresh",
+            fileCount: metadata?.fileCount ?? listed.files.length,
+            truncated: metadata?.truncated ?? listed.truncated,
+            generatedAt: metadata?.generatedAt ?? null,
+            fingerprint: metadata?.fingerprint ?? fingerprint,
+        });
+    }
+    const updated = buildCodebaseMap(basePath, resolved, existingDescriptions, listed);
+    if (updated.fileCount > 0) {
+        writeCodebaseMap(basePath, updated.content);
+        return cacheAndReturn({
+            status: "updated",
+            fileCount: updated.fileCount,
+            truncated: updated.truncated,
+            generatedAt: updated.generatedAt,
+            fingerprint: updated.fingerprint,
+            reason: staleReason,
+        });
+    }
+    return cacheAndReturn({
+        status: "empty",
+        fileCount: 0,
+        truncated: false,
+        generatedAt: null,
+        fingerprint,
+        reason: staleReason,
+    });
+}
 /**
  * Write CODEBASE.md to .gsd/ directory.
  */
@@ -242,6 +402,7 @@ export function writeCodebaseMap(basePath, content) {
     mkdirSync(root, { recursive: true });
     const outPath = join(root, "CODEBASE.md");
     writeFileSync(outPath, content, "utf-8");
+    clearFreshnessCache(basePath);
     return outPath;
 }
 /**

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -29,6 +29,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
     { cmd: "export", desc: "Export milestone/slice results" },
     { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+    { cmd: "model", desc: "Switch the active session model or open a picker" },
     { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
     { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
     { cmd: "config", desc: "Set API keys for external tools" },
@@ -60,7 +61,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
     { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
     { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
-    { cmd: "codebase", desc: "Generate and manage codebase map (.gsd/CODEBASE.md)" },
+    { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
 ];
 const NESTED_COMPLETIONS = {
     auto: [
@@ -223,7 +224,7 @@ const NESTED_COMPLETIONS = {
         { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
         { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" },
         { cmd: "generate --collapse-threshold", desc: "Generate with custom collapse threshold (default: 20)" },
-        { cmd: "update", desc: "Incremental update (preserves descriptions)" },
+        { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately (preserves descriptions)" },
         { cmd: "update --max-files", desc: "Update with custom file limit" },
         { cmd: "update --collapse-threshold", desc: "Update with custom collapse threshold" },
         { cmd: "stats", desc: "Show file count, description coverage, and generation time" },

package/dist/resources/extensions/gsd/commands/dispatcher.js

@@ -6,7 +6,7 @@ import { handleWorkflowCommand } from "./handlers/workflow.js";
 export async function handleGSDCommand(args, ctx, pi) {
     const trimmed = (typeof args === "string" ? args : "").trim();
     const handlers = [
-        () => handleCoreCommand(trimmed, ctx),
+        () => handleCoreCommand(trimmed, ctx, pi),
         () => handleAutoCommand(trimmed, ctx, pi),
         () => handleParallelCommand(trimmed, ctx, pi),
         () => handleWorkflowCommand(trimmed, ctx, pi),

package/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -40,10 +40,12 @@ export function showHelp(ctx) {
         "",
         "PROJECT KNOWLEDGE",
         "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+        "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
         "",
         "SETUP & CONFIGURATION",
         "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
         "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
+        "  /gsd model          Switch active session model  [provider/model|model-id]",
         "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
         "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
         "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
@@ -152,7 +154,92 @@ export async function handleSetup(args, ctx) {
         "  /gsd setup keys    — Tool API keys\n" +
         "  /gsd setup prefs   — Global preferences wizard", "info");
 }
-export async function handleCoreCommand(trimmed, ctx) {
+function sortModelsForSelection(models, currentModel) {
+    return [...models].sort((a, b) => {
+        const aCurrent = currentModel && a.provider === currentModel.provider && a.id === currentModel.id;
+        const bCurrent = currentModel && b.provider === currentModel.provider && b.id === currentModel.id;
+        if (aCurrent && !bCurrent)
+            return -1;
+        if (!aCurrent && bCurrent)
+            return 1;
+        const providerCmp = a.provider.localeCompare(b.provider);
+        if (providerCmp !== 0)
+            return providerCmp;
+        return a.id.localeCompare(b.id);
+    });
+}
+async function resolveRequestedModel(query, ctx) {
+    const { resolveModelId } = await import("../../auto-model-selection.js");
+    const models = ctx.modelRegistry.getAvailable();
+    const exact = resolveModelId(query, models, ctx.model?.provider);
+    if (exact)
+        return exact;
+    const lowerQuery = query.toLowerCase();
+    const partialMatches = models.filter((model) => model.id.toLowerCase().includes(lowerQuery)
+        || `${model.provider}/${model.id}`.toLowerCase().includes(lowerQuery));
+    if (partialMatches.length === 1)
+        return partialMatches[0];
+    if (partialMatches.length === 0 || !ctx.hasUI)
+        return undefined;
+    const sorted = sortModelsForSelection(partialMatches, ctx.model);
+    const optionToModel = new Map();
+    const options = sorted.map((model) => {
+        const label = `${model.provider}/${model.id}`;
+        optionToModel.set(label, model);
+        return label;
+    });
+    options.push("(cancel)");
+    const choice = await ctx.ui.select(`Multiple models match "${query}" — choose one:`, options);
+    if (!choice || typeof choice !== "string" || choice === "(cancel)")
+        return undefined;
+    return optionToModel.get(choice);
+}
+async function handleModel(trimmedArgs, ctx, pi) {
+    const availableModels = ctx.modelRegistry.getAvailable();
+    if (availableModels.length === 0) {
+        ctx.ui.notify("No available models found. Check provider auth and model discovery.", "warning");
+        return;
+    }
+    if (!pi) {
+        ctx.ui.notify("Model switching is unavailable in this context.", "warning");
+        return;
+    }
+    const trimmed = trimmedArgs.trim();
+    let targetModel;
+    if (!trimmed) {
+        if (!ctx.hasUI) {
+            const current = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(none)";
+            ctx.ui.notify(`Current model: ${current}\nUsage: /gsd model <provider/model|model-id>`, "info");
+            return;
+        }
+        const optionToModel = new Map();
+        const options = sortModelsForSelection(availableModels, ctx.model).map((model) => {
+            const isCurrent = ctx.model && model.provider === ctx.model.provider && model.id === ctx.model.id;
+            const label = `${isCurrent ? "* " : ""}${model.provider}/${model.id}`;
+            optionToModel.set(label, model);
+            return label;
+        });
+        options.push("(cancel)");
+        const choice = await ctx.ui.select("Select session model:", options);
+        if (!choice || typeof choice !== "string" || choice === "(cancel)")
+            return;
+        targetModel = optionToModel.get(choice);
+    }
+    else {
+        targetModel = await resolveRequestedModel(trimmed, ctx);
+    }
+    if (!targetModel) {
+        ctx.ui.notify(`Model "${trimmed}" not found. Use /gsd model with an exact provider/model or a unique model ID.`, "warning");
+        return;
+    }
+    const ok = await pi.setModel(targetModel);
+    if (!ok) {
+        ctx.ui.notify(`No API key for ${targetModel.provider}/${targetModel.id}`, "warning");
+        return;
+    }
+    ctx.ui.notify(`Model: ${targetModel.provider}/${targetModel.id}`, "info");
+}
+export async function handleCoreCommand(trimmed, ctx, pi) {
     if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
         showHelp(ctx);
         return true;
@@ -177,6 +264,10 @@ export async function handleCoreCommand(trimmed, ctx) {
         ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
         return true;
     }
+    if (trimmed === "model" || trimmed.startsWith("model ")) {
+        await handleModel(trimmed.replace(/^model\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     if (trimmed === "mode" || trimmed.startsWith("mode ")) {
         const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
         const scope = modeArgs === "project" ? "project" : "global";

package/dist/resources/extensions/gsd/commands-bootstrap.js

@@ -44,6 +44,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "start", desc: "Start a workflow template" },
     { cmd: "templates", desc: "List available workflow templates" },
     { cmd: "extensions", desc: "Manage extensions" },
+    { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache" },
 ];
 function filterStartsWith(partial, options, prefix = "") {
     const normalizedPrefix = prefix.length > 0 ? `${prefix} ` : "";
@@ -192,6 +193,14 @@ function getGsdArgumentCompletions(prefix) {
             { cmd: "info", desc: "Show extension details" },
         ], "extensions");
     }
+    if (parts[0] === "codebase" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
+            { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately" },
+            { cmd: "stats", desc: "Show codebase-map coverage and generation time" },
+            { cmd: "help", desc: "Show usage and subcommands" },
+        ], "codebase");
+    }
     if (parts[0] === "doctor" && parts.length <= 2) {
         return filterStartsWith(partial, [
             { cmd: "fix", desc: "Auto-fix detected issues" },