gsd-pi 2.67.0-dev.46f9884 → 2.67.0-dev.509bd95

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,3 +1,5 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
@@ -57,6 +59,61 @@ const GATE_SAFE_TOOLS = new Set([
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
+function shouldPersistWriteGateSnapshot(env = process.env) {
+    return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+}
+function writeGateSnapshotPath(basePath = process.cwd()) {
+    return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+}
+function currentWriteGateSnapshot() {
+    return {
+        verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+        activeQueuePhase,
+        pendingGateId,
+    };
+}
+function persistWriteGateSnapshot(basePath = process.cwd()) {
+    if (!shouldPersistWriteGateSnapshot())
+        return;
+    const path = writeGateSnapshotPath(basePath);
+    mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
+    const tempPath = `${path}.tmp`;
+    writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
+    renameSync(tempPath, path);
+}
+function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
+    if (!shouldPersistWriteGateSnapshot())
+        return;
+    const path = writeGateSnapshotPath(basePath);
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // swallow
+    }
+}
+function normalizeWriteGateSnapshot(value) {
+    const record = value && typeof value === "object" ? value : {};
+    const verified = Array.isArray(record.verifiedDepthMilestones)
+        ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
+        : [];
+    return {
+        verifiedDepthMilestones: [...new Set(verified)].sort(),
+        activeQueuePhase: record.activeQueuePhase === true,
+        pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
+    };
+}
+export function loadWriteGateSnapshot(basePath = process.cwd()) {
+    const path = writeGateSnapshotPath(basePath);
+    if (!existsSync(path))
+        return currentWriteGateSnapshot();
+    try {
+        return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
+    }
+    catch {
+        return currentWriteGateSnapshot();
+    }
+}
 export function isDepthVerified() {
     return verifiedDepthMilestones.size > 0;
 }
@@ -68,25 +125,34 @@ export function isMilestoneDepthVerified(milestoneId) {
         return false;
     return verifiedDepthMilestones.has(milestoneId);
 }
+export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
+    if (!milestoneId)
+        return false;
+    return snapshot.verifiedDepthMilestones.includes(milestoneId);
+}
 export function isQueuePhaseActive() {
     return activeQueuePhase;
 }
 export function setQueuePhaseActive(active) {
     activeQueuePhase = active;
+    persistWriteGateSnapshot();
 }
 export function resetWriteGateState() {
     verifiedDepthMilestones.clear();
     pendingGateId = null;
+    persistWriteGateSnapshot();
 }
 export function clearDiscussionFlowState() {
     verifiedDepthMilestones.clear();
     activeQueuePhase = false;
     pendingGateId = null;
+    clearPersistedWriteGateSnapshot();
 }
-export function markDepthVerified(milestoneId) {
+export function markDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return;
     verifiedDepthMilestones.add(milestoneId);
+    persistWriteGateSnapshot(basePath);
 }
 /**
  * Check whether a question ID matches a recognized gate pattern.
@@ -114,12 +180,14 @@ function extractContextMilestoneId(inputPath) {
  */
 export function setPendingGate(gateId) {
     pendingGateId = gateId;
+    persistWriteGateSnapshot();
 }
 /**
  * Clear the pending gate (called when the user confirms).
  */
 export function clearPendingGate() {
     pendingGateId = null;
+    persistWriteGateSnapshot();
 }
 /**
  * Get the currently pending gate, if any.
@@ -134,8 +202,11 @@ export function getPendingGate() {
  * Returns { block: true, reason } if the tool should be blocked.
  * Read-only tools and ask_user_questions itself are always allowed.
  */
-export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive) {
-    if (!pendingGateId)
+export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive) {
+    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+}
+export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
+    if (!snapshot.pendingGateId)
         return { block: false };
     if (GATE_SAFE_TOOLS.has(toolName))
         return { block: false };
@@ -145,7 +216,7 @@ export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive
     return {
         block: true,
         reason: [
-            `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+            `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
             `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`,
             `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
             `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -157,8 +228,11 @@ export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive
  * Check whether a bash command should be blocked because a discussion gate is pending.
  * Read-only bash commands are allowed; mutating commands are blocked.
  */
-export function shouldBlockPendingGateBash(command, _milestoneId, _queuePhaseActive) {
-    if (!pendingGateId)
+export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive) {
+    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+}
+export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
+    if (!snapshot.pendingGateId)
         return { block: false };
     // Allow read-only bash commands
     if (BASH_READ_ONLY_RE.test(command))
@@ -166,7 +240,7 @@ export function shouldBlockPendingGateBash(command, _milestoneId, _queuePhaseAct
     return {
         block: true,
         reason: [
-            `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+            `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
             `You MUST re-call ask_user_questions with the gate question before running mutating commands.`,
             `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
             `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -232,6 +306,9 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
  * require the milestone to be depth-verified first.
  */
 export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId) {
+    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+}
+export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType, milestoneId, sliceId) {
     if (artifactType !== "CONTEXT")
         return { block: false };
     if (sliceId)
@@ -245,7 +322,7 @@ export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceI
             ].join(" "),
         };
     }
-    if (isMilestoneDepthVerified(milestoneId))
+    if (isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId))
         return { block: false };
     return {
         block: true,
@@ -271,6 +348,9 @@ export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceI
  * @returns { block, reason } — block=true if the call should be rejected.
  */
 export function shouldBlockQueueExecution(toolName, input, queuePhaseActive) {
+    return shouldBlockQueueExecutionInSnapshot(currentWriteGateSnapshot(), toolName, input, queuePhaseActive);
+}
+export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, queuePhaseActive = snapshot.activeQueuePhase) {
     if (!queuePhaseActive)
         return { block: false };
     // Always-safe tools (read-only, discussion, planning)

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,106 @@ 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);
+    });
+}
+function buildProviderModelGroups(models, currentModel) {
+    const byProvider = new Map();
+    for (const model of sortModelsForSelection(models, currentModel)) {
+        let group = byProvider.get(model.provider);
+        if (!group) {
+            group = [];
+            byProvider.set(model.provider, group);
+        }
+        group.push(model);
+    }
+    return byProvider;
+}
+async function selectModelByProvider(title, models, ctx, currentModel) {
+    const byProvider = buildProviderModelGroups(models, currentModel);
+    const providerOptions = Array.from(byProvider.entries()).map(([provider, group]) => `${provider} (${group.length} model${group.length === 1 ? "" : "s"})`);
+    providerOptions.push("(cancel)");
+    const providerChoice = await ctx.ui.select(`${title} — choose provider:`, providerOptions);
+    if (!providerChoice || typeof providerChoice !== "string" || providerChoice === "(cancel)")
+        return undefined;
+    const providerName = providerChoice.replace(/ \(\d+ models?\)$/, "");
+    const providerModels = byProvider.get(providerName);
+    if (!providerModels || providerModels.length === 0)
+        return undefined;
+    const optionToModel = new Map();
+    const modelOptions = providerModels.map((model) => {
+        const isCurrent = currentModel && model.provider === currentModel.provider && model.id === currentModel.id;
+        const label = `${isCurrent ? "* " : ""}${model.id}`;
+        optionToModel.set(label, model);
+        return label;
+    });
+    modelOptions.push("(cancel)");
+    const modelChoice = await ctx.ui.select(`${title} — ${providerName}:`, modelOptions);
+    if (!modelChoice || typeof modelChoice !== "string" || modelChoice === "(cancel)")
+        return undefined;
+    return optionToModel.get(modelChoice);
+}
+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;
+    return selectModelByProvider(`Multiple models match "${query}"`, partialMatches, ctx, ctx.model);
+}
+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;
+        }
+        targetModel = await selectModelByProvider("Select session model:", availableModels, ctx, ctx.model);
+    }
+    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 +278,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/index.js

@@ -5,7 +5,14 @@ export function registerGSDCommand(pi) {
         getArgumentCompletions: getGsdArgumentCompletions,
         handler: async (args, ctx) => {
             const { handleGSDCommand } = await import("./dispatcher.js");
-            await handleGSDCommand(args, ctx, pi);
+            const { setStderrLoggingEnabled } = await import("../workflow-logger.js");
+            const previousStderrSetting = setStderrLoggingEnabled(false);
+            try {
+                await handleGSDCommand(args, ctx, pi);
+            }
+            finally {
+                setStderrLoggingEnabled(previousStderrSetting);
+            }
         },
     });
 }

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" },