gsd-pi 2.60.0-dev.d9052f5 → 2.61.0

package/dist/resources/extensions/gsd/auto.js

@@ -34,7 +34,7 @@ import { clearSkillSnapshot } from "./skill-discovery.js";
 import { captureAvailableSkills, resetSkillTelemetry, } from "./skill-telemetry.js";
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -137,8 +137,9 @@ export function getAutoDashboardData() {
             pendingCaptureCount = countPendingCaptures(s.basePath);
         }
     }
-    catch {
+    catch (err) {
         // Non-fatal — captures module may not be loaded
+        logWarning("engine", `capture count failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     return {
         active: s.active,
@@ -340,8 +341,9 @@ function cleanupAfterLoopExit(ctx) {
         if (lockBase())
             releaseSessionLock(lockBase());
     }
-    catch {
+    catch (err) {
         /* best-effort — mirror stopAuto cleanup */
+        logWarning("session", `lock cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     ctx.ui.setStatus("gsd-auto", undefined);
     ctx.ui.setWidget("gsd-progress", undefined);
@@ -352,8 +354,9 @@ function cleanupAfterLoopExit(ctx) {
         try {
             process.chdir(s.basePath);
         }
-        catch {
+        catch (err) {
             /* best-effort */
+            logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
     }
 }
@@ -415,8 +418,9 @@ export async function stopAuto(ctx, pi, reason) {
                         milestoneComplete = true;
                     }
                 }
-                catch {
+                catch (err) {
                     // Non-fatal — fall through to preserveBranch path
+                    logWarning("engine", `milestone summary check failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
                 }
                 if (milestoneComplete) {
                     // Milestone is complete — merge worktree branch back to main
@@ -452,8 +456,9 @@ export async function stopAuto(ctx, pi, reason) {
                 try {
                     process.chdir(s.basePath);
                 }
-                catch {
+                catch (err) {
                     /* best-effort */
+                    logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
                 }
             }
         }
@@ -522,7 +527,9 @@ export async function stopAuto(ctx, pi, reason) {
             if (existsSync(pausedPath))
                 unlinkSync(pausedPath);
         }
-        catch { /* non-fatal */ }
+        catch (err) { /* non-fatal */
+            logWarning("engine", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+        }
         // ── Step 13: Restore original model (before reset clears IDs) ──
         try {
             if (pi && ctx && s.originalModelId && s.originalModelProvider) {
@@ -556,7 +563,9 @@ export async function stopAuto(ctx, pi, reason) {
                 await closeBrowser();
             }
         }
-        catch { /* non-fatal: browser-tools may not be loaded */ }
+        catch (err) { /* non-fatal: browser-tools may not be loaded */
+            logWarning("engine", `browser teardown failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+        }
         // External cleanup (not covered by session reset)
         clearInFlightTools();
         clearSliceProgressCache();
@@ -602,16 +611,18 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
         mkdirSync(runtimeDir, { recursive: true });
         writeFileSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
     }
-    catch {
+    catch (err) {
         // Non-fatal — resume will still work via full bootstrap, just without worktree context
+        logWarning("engine", `paused-session file write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     // Close out the current unit so its runtime record doesn't stay at "dispatched"
     if (s.currentUnit && ctx) {
         try {
             await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt);
         }
-        catch {
+        catch (err) {
             // Non-fatal — best-effort closeout on pause
+            logWarning("engine", `unit closeout on pause failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
         s.currentUnit = null;
     }
@@ -798,7 +809,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                     try {
                         unlinkSync(pausedPath);
                     }
-                    catch { /* non-fatal */ }
+                    catch (err) { /* non-fatal */
+                        logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+                    }
                     ctx.ui.notify(`Resuming paused custom workflow${meta.activeRunDir ? ` (${meta.activeRunDir})` : ""}.`, "info");
                 }
                 else if (meta.milestoneId) {
@@ -810,7 +823,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         try {
                             unlinkSync(pausedPath);
                         }
-                        catch { /* non-fatal */ }
+                        catch (err) { /* non-fatal */
+                            logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+                        }
                         ctx.ui.notify(`Paused milestone ${meta.milestoneId} is ${!mDir ? "missing" : "already complete"}. Starting fresh.`, "info");
                     }
                     else {
@@ -822,14 +837,17 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         try {
                             unlinkSync(pausedPath);
                         }
-                        catch { /* non-fatal */ }
+                        catch (err) { /* non-fatal */
+                            logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+                        }
                         ctx.ui.notify(`Resuming paused session for ${meta.milestoneId}${meta.worktreePath ? ` (worktree)` : ""}.`, "info");
                     }
                 }
             }
         }
-        catch {
+        catch (err) {
             // Malformed or missing — proceed with fresh bootstrap
+            logWarning("session", `paused-session restore failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
     }
     if (s.paused) {
@@ -917,8 +935,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     try {
         syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
     }
-    catch {
+    catch (err) {
         // Best-effort only — sidebar sync must never block auto-mode startup
+        logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
     // Dispatch the first unit
@@ -1043,8 +1062,9 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
             try {
                 await pi.setModel(match);
             }
-            catch {
+            catch (err) {
                 /* non-fatal */
+                logWarning("dispatch", `hook model set failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
             }
         }
         else {
@@ -1072,7 +1092,9 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         if (process.cwd() !== s.basePath)
             process.chdir(s.basePath);
     }
-    catch { }
+    catch (err) {
+        logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+    }
     debugLog("dispatchHookUnit", {
         phase: "send-message",
         promptLength: hookPrompt.length,

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,3 +1,4 @@
+import { logWarning } from "../workflow-logger.js";
 import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
@@ -68,7 +69,9 @@ export async function handleAgentEnd(pi, event, ctx) {
                 try {
                     await pauseAuto(ctx, pi);
                 }
-                catch { /* best-effort */ }
+                catch (e) {
+                    logWarning("bootstrap", `pauseAuto failed after empty-content abort: ${e.message}`);
+                }
             }
             return;
         }
@@ -184,8 +187,8 @@ export async function handleAgentEnd(pi, event, ctx) {
         try {
             await pauseAuto(ctx, pi);
         }
-        catch {
-            // best-effort
+        catch (e) {
+            logWarning("bootstrap", `pauseAuto failed in agent_end handler: ${e.message}`);
         }
     }
 }

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -403,8 +403,8 @@ export function registerDbTools(pi) {
             const { insertMilestone } = await import("../gsd-db.js");
             insertMilestone({ id: milestoneId, status: "queued" });
         }
-        catch {
-            // Non-fatal — the safety-net in deriveStateFromDb will catch this
+        catch (e) {
+            logError("tool", `insertMilestone failed for ${milestoneId}: ${e.message}`);
         }
     }
     const milestoneGenerateIdTool = {

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { join, sep } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
-import { setLogBasePath } from "../workflow-logger.js";
+import { setLogBasePath, logWarning } from "../workflow-logger.js";
 /**
  * Resolve the correct DB path for the current working directory.
  * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
@@ -82,7 +82,7 @@ export async function ensureDbOpen() {
                         migrateFromMarkdown(basePath);
                     }
                     catch (err) {
-                        process.stderr.write(`gsd-db: ensureDbOpen auto-migration failed: ${err.message}\n`);
+                        logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${err.message}`);
                     }
                 }
                 return opened;
@@ -93,17 +93,11 @@ export async function ensureDbOpen() {
                 setLogBasePath(projectRoot);
             return opened;
         }
-        process.stderr.write(`gsd-db: ensureDbOpen failed — no .gsd directory found (resolvedPath=${resolveProjectRootDbPath(basePath)}, cwd=${basePath})\n`);
+        logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
         return false;
     }
     catch (err) {
-        const basePath = process.cwd();
-        const diagnostic = {
-            resolvedPath: resolveProjectRootDbPath(basePath),
-            cwd: basePath,
-            error: err.message ?? String(err),
-        };
-        process.stderr.write(`gsd-db: ensureDbOpen failed — ${JSON.stringify(diagnostic)}\n`);
+        logWarning("bootstrap", `ensureDbOpen failed: ${err.message ?? String(err)}`);
         return false;
     }
 }

package/dist/resources/extensions/gsd/bootstrap/journal-tools.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { queryJournal } from "../journal.js";
+import { logWarning } from "../workflow-logger.js";
 export function registerJournalTools(pi) {
     pi.registerTool({
         name: "gsd_journal_query",
@@ -51,7 +52,7 @@ export function registerJournalTools(pi) {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                process.stderr.write(`gsd-journal: gsd_journal_query tool failed: ${msg}\n`);
+                logWarning("tool", `gsd_journal_query tool failed: ${msg}`);
                 return {
                     content: [{ type: "text", text: `Error querying journal: ${msg}` }],
                     details: { operation: "journal_query", error: msg },

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -303,4 +303,11 @@ export function registerHooks(pi) {
         payload.service_tier = tier;
         return payload;
     });
+    // Capability-aware model routing hook (ADR-004)
+    // Extensions can override model selection by returning { modelId: "..." }
+    // Return undefined to let the built-in capability scoring proceed.
+    pi.on("before_model_select", async (_event) => {
+        // Default: no override — let capability scoring handle selection
+        return undefined;
+    });
 }

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

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
 import { loadPrompt } from "../prompt-loader.js";
 import { readForensicsMarker } from "../forensics.js";
@@ -61,8 +62,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             }
         }
     }
-    catch {
-        // non-fatal
+    catch (e) {
+        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
     }
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
@@ -88,8 +89,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
                 codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, may be stale — run /gsd codebase update to refresh)]\n\n${content}`;
             }
         }
-        catch {
-            // skip
+        catch (e) {
+            logWarning("bootstrap", `CODEBASE file read failed: ${e.message}`);
         }
     }
     warnDeprecatedAgentInstructions();
@@ -128,8 +129,8 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
                 globalKnowledge = content;
             }
         }
-        catch {
-            // skip
+        catch (e) {
+            logWarning("bootstrap", `global knowledge file read failed: ${e.message}`);
         }
     }
     // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
@@ -141,8 +142,8 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
             if (content)
                 projectKnowledge = content;
         }
-        catch {
-            // skip
+        catch (e) {
+            logWarning("bootstrap", `project knowledge file read failed: ${e.message}`);
         }
     }
     if (!globalKnowledge && !projectKnowledge) {
@@ -381,8 +382,8 @@ export function clearForensicsMarker(basePath) {
         try {
             unlinkSync(markerPath);
         }
-        catch {
-            // non-fatal
+        catch (e) {
+            logWarning("bootstrap", `unlinkSync forensics marker failed: ${e.message}`);
         }
     }
 }

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

@@ -216,8 +216,10 @@ const NESTED_COMPLETIONS = {
     codebase: [
         { 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 --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" },
         { cmd: "help", desc: "Show usage and available subcommands" },
     ],

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

@@ -5,26 +5,32 @@
  * Subcommands: generate, update, stats, help
  */
 import { generateCodebaseMap, updateCodebaseMap, writeCodebaseMap, getCodebaseMapStats, readCodebaseMap, } from "./codebase-generator.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 const USAGE = "Usage: /gsd codebase [generate|update|stats]\n\n" +
-    "  generate [--max-files N]  — Generate or regenerate CODEBASE.md\n" +
-    "  update                    — Incremental update (preserves descriptions)\n" +
-    "  stats                     — Show file count, coverage, and generation time\n" +
-    "  help                      — Show this help\n\n" +
-    "With no subcommand, shows stats if a map exists or help if not.";
+    "  generate [--max-files N] [--collapse-threshold N]  — Generate or regenerate CODEBASE.md\n" +
+    "  update [--max-files N] [--collapse-threshold N]    — Incremental update (preserves descriptions)\n" +
+    "  stats                                              — Show file count, coverage, and generation time\n" +
+    "  help                                               — Show this help\n\n" +
+    "With no subcommand, shows stats if a map exists or help if not.\n\n" +
+    "Configure defaults via preferences.md:\n" +
+    "  codebase:\n" +
+    "    exclude_patterns: [\"docs/\", \"fixtures/\"]\n" +
+    "    max_files: 1000\n" +
+    "    collapse_threshold: 15";
 export async function handleCodebase(args, ctx, _pi) {
     const basePath = process.cwd();
     const parts = args.trim().split(/\s+/);
     const sub = parts[0] ?? "";
     switch (sub) {
         case "generate": {
-            const maxFiles = parseMaxFiles(args, ctx);
-            if (maxFiles === false)
+            const options = resolveCodebaseOptions(args, ctx);
+            if (options === false)
                 return; // validation failed, message already shown
             const existing = readCodebaseMap(basePath);
             const existingDescriptions = existing
                 ? (await import("./codebase-generator.js")).parseCodebaseMap(existing)
                 : undefined;
-            const result = generateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined }, existingDescriptions);
+            const result = generateCodebaseMap(basePath, options, existingDescriptions);
             if (result.fileCount === 0) {
                 ctx.ui.notify("Codebase map generated with 0 files.\n" +
                     "Is this a git repository? Run 'git ls-files' to verify.", "warning");
@@ -42,10 +48,10 @@ export async function handleCodebase(args, ctx, _pi) {
                 ctx.ui.notify("No codebase map found. Run /gsd codebase generate to create one.", "warning");
                 return;
             }
-            const maxFiles = parseMaxFiles(args, ctx);
-            if (maxFiles === false)
+            const options = resolveCodebaseOptions(args, ctx);
+            if (options === false)
                 return;
-            const result = updateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined });
+            const result = updateCodebaseMap(basePath, options);
             writeCodebaseMap(basePath, result.content);
             ctx.ui.notify(`Codebase map updated: ${result.fileCount} files\n` +
                 `  Added: ${result.added} | Removed: ${result.removed} | Unchanged: ${result.unchanged}` +
@@ -93,19 +99,40 @@ function showStats(basePath, ctx) {
             : `Coverage is complete.`), "info");
 }
 /**
- * Parse and validate --max-files flag.
- * Returns the parsed number, undefined if flag not present, or false if invalid.
+ * Resolve codebase map options by merging preferences with CLI flags.
+ * CLI flags override preferences; preferences override built-in defaults.
+ * Returns false if validation failed (error already shown to user).
  */
-function parseMaxFiles(args, ctx) {
+function resolveCodebaseOptions(args, ctx) {
+    // Load preferences defaults
+    const prefs = loadEffectiveGSDPreferences()?.preferences?.codebase;
+    // Parse CLI flags
     const maxFilesStr = extractFlag(args, "--max-files");
-    if (!maxFilesStr)
-        return undefined;
-    const maxFiles = parseInt(maxFilesStr, 10);
-    if (isNaN(maxFiles) || maxFiles < 1) {
-        ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning");
-        return false;
+    const collapseStr = extractFlag(args, "--collapse-threshold");
+    // Validate --max-files
+    let maxFiles;
+    if (maxFilesStr) {
+        maxFiles = parseInt(maxFilesStr, 10);
+        if (isNaN(maxFiles) || maxFiles < 1) {
+            ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning");
+            return false;
+        }
+    }
+    // Validate --collapse-threshold
+    let collapseThreshold;
+    if (collapseStr) {
+        collapseThreshold = parseInt(collapseStr, 10);
+        if (isNaN(collapseThreshold) || collapseThreshold < 1) {
+            ctx.ui.notify("--collapse-threshold must be a positive integer (e.g. --collapse-threshold 15).", "warning");
+            return false;
+        }
     }
-    return maxFiles;
+    return {
+        // CLI flags override preferences
+        maxFiles: maxFiles ?? prefs?.max_files,
+        collapseThreshold: collapseThreshold ?? prefs?.collapse_threshold,
+        excludePatterns: prefs?.exclude_patterns,
+    };
 }
 function extractFlag(args, flag) {
     const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

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

@@ -6,6 +6,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
 import { getErrorMessage } from "./error-utils.js";
 export function formatInspectOutput(data) {
     const lines = [];
@@ -71,7 +72,7 @@ export async function handleInspect(ctx) {
         ctx.ui.notify(formatInspectOutput(data), "info");
     }
     catch (err) {
-        process.stderr.write(`gsd-db: /gsd inspect failed: ${getErrorMessage(err)}\n`);
+        logWarning("command", `/gsd inspect failed: ${getErrorMessage(err)}`);
         ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
     }
 }

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

@@ -5,12 +5,14 @@
  */
 import { deriveState } from "./state.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
+import { logWarning } from "./workflow-logger.js";
 export async function handleCleanupBranches(ctx, basePath) {
     let branches;
     try {
         branches = nativeBranchList(basePath, "gsd/*");
     }
-    catch {
+    catch (e) {
+        logWarning("command", `branch list failed: ${e.message}`);
         ctx.ui.notify("No GSD branches to clean up.", "info");
         return;
     }
@@ -20,7 +22,8 @@ export async function handleCleanupBranches(ctx, basePath) {
     try {
         merged = nativeBranchListMerged(basePath, mainBranch, "gsd/*");
     }
-    catch {
+    catch (e) {
+        logWarning("command", `merged branch list failed: ${e.message}`);
         merged = [];
     }
     const mergedNonQuick = merged.filter((b) => !b.startsWith("gsd/quick/"));
@@ -30,8 +33,8 @@ export async function handleCleanupBranches(ctx, basePath) {
             nativeBranchDelete(basePath, branch, false);
             deletedMerged++;
         }
-        catch {
-            /* skip branches that cannot be deleted */
+        catch (e) {
+            logWarning("command", `branch delete failed for ${branch}: ${e.message}`);
         }
     }
     // Also delete stale milestone branches for completed milestones when detached
@@ -61,7 +64,9 @@ export async function handleCleanupBranches(ctx, basePath) {
                         nativeBranchDelete(basePath, branch, true);
                         deletedStaleMilestones++;
                     }
-                    catch { /* non-fatal */ }
+                    catch (e) {
+                        logWarning("command", `stale milestone branch delete failed for ${branch}: ${e.message}`);
+                    }
                     continue;
                 }
             }
@@ -73,7 +78,8 @@ export async function handleCleanupBranches(ctx, basePath) {
             try {
                 roadmapContent = await loadFile(roadmapPath);
             }
-            catch {
+            catch (e) {
+                logWarning("command", `loadFile failed for ${roadmapPath}: ${e.message}`);
                 roadmapContent = null;
             }
             if (!roadmapContent)
@@ -84,13 +90,13 @@ export async function handleCleanupBranches(ctx, basePath) {
                 nativeBranchDelete(basePath, branch, true);
                 deletedStaleMilestones++;
             }
-            catch {
-                /* non-fatal */
+            catch (e) {
+                logWarning("command", `milestone branch delete failed for ${branch}: ${e.message}`);
             }
         }
     }
-    catch {
-        /* non-fatal */
+    catch (e) {
+        logWarning("command", `stale milestone cleanup failed: ${e.message}`);
     }
     const summary = [];
     if (deletedMerged > 0) {
@@ -116,7 +122,8 @@ export async function handleCleanupSnapshots(ctx, basePath) {
     try {
         refs = nativeForEachRef(basePath, "refs/gsd/snapshots/");
     }
-    catch {
+    catch (e) {
+        logWarning("command", `snapshot ref list failed: ${e.message}`);
         ctx.ui.notify("No snapshot refs to clean up.", "info");
         return;
     }
@@ -140,8 +147,8 @@ export async function handleCleanupSnapshots(ctx, basePath) {
                 nativeUpdateRef(basePath, old);
                 pruned++;
             }
-            catch {
-                /* skip individual failures */
+            catch (e) {
+                logWarning("command", `snapshot ref update failed for ${old}: ${e.message}`);
             }
         }
     }
@@ -155,7 +162,8 @@ export async function handleCleanupWorktrees(ctx, basePath) {
     try {
         statuses = getAllWorktreeHealth(basePath);
     }
-    catch {
+    catch (e) {
+        logWarning("command", `worktree health inspection failed: ${e.message}`);
         ctx.ui.notify("Failed to inspect worktrees.", "error");
         return;
     }
@@ -185,7 +193,8 @@ export async function handleCleanupWorktrees(ctx, basePath) {
                 lines.push(`  ✓ ${wt.name}  removed (branch ${wt.branch} deleted)`);
                 removed++;
             }
-            catch {
+            catch (e) {
+                logWarning("command", `worktree removal failed for ${wt.name}: ${e.message}`);
                 lines.push(`  ✗ ${wt.name}  failed to remove`);
             }
         }
@@ -228,7 +237,9 @@ export async function handleSkip(unitArg, ctx, basePath) {
             keys = JSON.parse(readFile(completedKeysFile, "utf-8"));
         }
     }
-    catch { /* start fresh */ }
+    catch (e) {
+        logWarning("command", `completed-units.json parse failed: ${e.message}`);
+    }
     // Normalize: accept "execute-task/M001/S01/T03", "M001/S01/T03", or just "T03"
     let skipKey = unitArg;
     if (!skipKey.includes("execute-task") && !skipKey.includes("plan-") && !skipKey.includes("research-") && !skipKey.includes("complete-")) {
@@ -339,7 +350,8 @@ export async function handleCleanupProjects(args, ctx) {
             .filter(e => e.isDirectory())
             .map(e => e.name);
     }
-    catch {
+    catch (e) {
+        logWarning("command", `readdir failed for project-state directory: ${e.message}`);
         ctx.ui.notify(`Failed to read project-state directory at ${projectsDir}.`, "error");
         return;
     }
@@ -413,7 +425,8 @@ export async function handleCleanupProjects(args, ctx) {
                 fsRmSync(pathJoin(projectsDir, e.hash), { recursive: true, force: true });
                 removed++;
             }
-            catch {
+            catch (err) {
+                logWarning("command", `project cleanup rm failed for ${e.hash}: ${err.message}`);
                 failed.push(e.hash);
             }
         }
@@ -479,7 +492,7 @@ export async function handleRecover(ctx, basePath) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`gsd-recover: failed: ${msg}\n`);
+        logWarning("command", `recover failed: ${msg}`);
         ctx.ui.notify(`gsd recover failed: ${msg}`, "error");
     }
 }