gsd-pi 2.59.0 → 2.60.0-dev.2580e65

package/src/resources/extensions/gsd/auto.ts

@@ -115,7 +115,7 @@ import {
   formatCost,
   formatTokenCount,
 } from "./metrics.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { setLogBasePath, logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -316,8 +316,9 @@ export function getAutoDashboardData(): AutoDashboardData {
     if (s.basePath) {
       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,
@@ -565,8 +566,9 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   try {
     if (lockBase()) clearLock(lockBase());
     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);
@@ -578,8 +580,9 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
     s.basePath = s.originalBasePath;
     try {
       process.chdir(s.basePath);
-    } catch {
+    } catch (err) {
       /* best-effort */
+      logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
   }
 }
@@ -651,8 +654,9 @@ export async function stopAuto(
           } else {
             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) {
@@ -687,8 +691,9 @@ export async function stopAuto(
         s.basePath = s.originalBasePath;
         try {
           process.chdir(s.basePath);
-        } catch {
+        } catch (err) {
           /* best-effort */
+          logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
       }
     } catch (e) {
@@ -760,7 +765,9 @@ export async function stopAuto(
     try {
       const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
       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 {
@@ -794,7 +801,9 @@ export async function stopAuto(
         const { closeBrowser } = await import("../browser-tools/lifecycle.js");
         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();
@@ -852,16 +861,18 @@ export async function pauseAuto(
       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;
   }
@@ -1085,7 +1096,9 @@ export async function startAuto(
           s.originalBasePath = meta.originalBasePath || base;
           s.stepMode = meta.stepMode ?? requestedStepMode;
           s.paused = true;
-          try { unlinkSync(pausedPath); } catch { /* non-fatal */ }
+          try { unlinkSync(pausedPath); } 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",
@@ -1096,7 +1109,9 @@ export async function startAuto(
           const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
           if (!mDir || summaryFile) {
             // Stale milestone — clean up and fall through to fresh bootstrap
-            try { unlinkSync(pausedPath); } catch { /* non-fatal */ }
+            try { unlinkSync(pausedPath); } 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",
@@ -1107,7 +1122,9 @@ export async function startAuto(
             s.stepMode = meta.stepMode ?? requestedStepMode;
             s.paused = true;
             // Clean up the persisted file — we're consuming it
-            try { unlinkSync(pausedPath); } catch { /* non-fatal */ }
+            try { unlinkSync(pausedPath); } 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",
@@ -1115,8 +1132,9 @@ export async function startAuto(
           }
         }
       }
-    } 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" });
     }
   }
 
@@ -1242,8 +1260,9 @@ export async function startAuto(
 
   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");
 
@@ -1415,8 +1434,9 @@ export async function dispatchHookUnit(
     if (match) {
       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 {
       ctx.ui.notify(
@@ -1453,7 +1473,9 @@ export async function dispatchHookUnit(
   ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
 
   // Ensure cwd matches basePath before hook dispatch (#1389)
-  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch {}
+  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch (err) {
+    logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+  }
 
   debugLog("dispatchHookUnit", {
     phase: "send-message",
@@ -1475,3 +1497,4 @@ export {
   buildLoopRemediationSteps,
 } from "./auto-recovery.js";
 export { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
+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";
@@ -85,7 +86,7 @@ export async function handleAgentEnd(
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         ctx.ui.notify(`Auto-mode error after empty-content abort: ${message}. Stopping auto-mode.`, "error");
-        try { await pauseAuto(ctx, pi); } catch { /* best-effort */ }
+        try { await pauseAuto(ctx, pi); } catch (e) { logWarning("bootstrap", `pauseAuto failed after empty-content abort: ${(e as Error).message}`); }
       }
       return;
     }
@@ -212,8 +213,8 @@ export async function handleAgentEnd(
     ctx.ui.notify(`Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`, "error");
     try {
       await pauseAuto(ctx, pi);
-    } catch {
-      // best-effort
+    } catch (e) {
+      logWarning("bootstrap", `pauseAuto failed in agent_end handler: ${(e as Error).message}`);
     }
   }
 }

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -413,8 +413,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
     try {
       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 as Error).message}`);
     }
   }
 
@@ -883,6 +883,84 @@ export function registerDbTools(pi: ExtensionAPI): void {
   pi.registerTool(sliceCompleteTool);
   registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete");
 
+  // ─── gsd_skip_slice (#3477 / #3487) ───────────────────────────────────
+
+  const skipSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot skip slice." }],
+        details: { operation: "skip_slice", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { getSlice, updateSliceStatus } = await import("../gsd-db.js");
+      const { invalidateStateCache } = await import("../state.js");
+
+      const slice = getSlice(params.milestoneId, params.sliceId);
+      if (!slice) {
+        return {
+          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} not found in milestone ${params.milestoneId}` }],
+          details: { operation: "skip_slice", error: "slice_not_found" } as any,
+        };
+      }
+
+      if (slice.status === "complete" || slice.status === "done") {
+        return {
+          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} is already complete — cannot skip.` }],
+          details: { operation: "skip_slice", error: "already_complete" } as any,
+        };
+      }
+
+      if (slice.status === "skipped") {
+        return {
+          content: [{ type: "text" as const, text: `Slice ${params.sliceId} is already skipped.` }],
+          details: { operation: "skip_slice", sliceId: params.sliceId, milestoneId: params.milestoneId } as any,
+        };
+      }
+
+      updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
+      invalidateStateCache();
+
+      return {
+        content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}. Auto-mode will advance past this slice.` }],
+        details: {
+          operation: "skip_slice",
+          sliceId: params.sliceId,
+          milestoneId: params.milestoneId,
+          reason: params.reason,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `skip_slice tool failed: ${msg}`, { tool: "gsd_skip_slice", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error skipping slice: ${msg}` }],
+        details: { operation: "skip_slice", error: msg } as any,
+      };
+    }
+  };
+
+  pi.registerTool({
+    name: "gsd_skip_slice",
+    label: "Skip Slice",
+    description:
+      "Mark a slice as skipped so auto-mode advances past it without executing. " +
+      "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.",
+    promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)",
+    promptGuidelines: [
+      "Use gsd_skip_slice when a slice should be bypassed — descoped, superseded, or no longer relevant.",
+      "Cannot skip a slice that is already complete.",
+      "Skipped slices satisfy downstream dependencies just like completed slices.",
+    ],
+    parameters: Type.Object({
+      sliceId: Type.String({ description: "Slice ID (e.g. S02)" }),
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M003)" }),
+      reason: Type.Optional(Type.String({ description: "Reason for skipping this slice" })),
+    }),
+    execute: skipSliceExecute,
+  });
+
   // ─── gsd_complete_milestone ────────────────────────────────────────────
 
   const milestoneCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -5,7 +5,7 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 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.
@@ -92,9 +92,7 @@ export async function ensureDbOpen(): Promise<boolean> {
             const { migrateFromMarkdown } = await import("../md-importer.js");
             migrateFromMarkdown(basePath);
           } catch (err) {
-            process.stderr.write(
-              `gsd-db: ensureDbOpen auto-migration failed: ${(err as Error).message}\n`,
-            );
+            logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${(err as Error).message}`);
           }
         }
         return opened;
@@ -106,20 +104,10 @@ export async function ensureDbOpen(): Promise<boolean> {
       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 as Error).message ?? String(err),
-    };
-    process.stderr.write(
-      `gsd-db: ensureDbOpen failed — ${JSON.stringify(diagnostic)}\n`,
-    );
+    logWarning("bootstrap", `ensureDbOpen failed: ${(err as Error).message ?? String(err)}`);
     return false;
   }
 }

package/src/resources/extensions/gsd/bootstrap/journal-tools.ts

@@ -2,6 +2,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
 import { queryJournal } from "../journal.js";
+import { logWarning } from "../workflow-logger.js";
 
 export function registerJournalTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -51,7 +52,7 @@ export function registerJournalTools(pi: ExtensionAPI): void {
         };
       } 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" as const, text: `Error querying journal: ${msg}` }],
           details: { operation: "journal_query", error: msg } as any,

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -263,14 +263,71 @@ export function registerHooks(pi: ExtensionAPI): void {
   });
 
   pi.on("before_provider_request", async (event) => {
+    const payload = event.payload as Record<string, unknown> | null;
+    if (!payload || typeof payload !== "object") return;
+
+    // ── Observation Masking ─────────────────────────────────────────────
+    // Replace old tool results with placeholders to reduce context bloat.
+    // Only active during auto-mode when context_management.observation_masking is enabled.
+    if (isAutoActive()) {
+      try {
+        const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+        const prefs = loadEffectiveGSDPreferences();
+        const cmConfig = prefs?.preferences.context_management;
+
+        // Observation masking: replace old tool results with placeholders
+        if (cmConfig?.observation_masking !== false) {
+          const keepTurns = cmConfig?.observation_mask_turns ?? 8;
+          const { createObservationMask } = await import("../context-masker.js");
+          const mask = createObservationMask(keepTurns);
+          const messages = payload.messages;
+          if (Array.isArray(messages)) {
+            payload.messages = mask(messages);
+          }
+        }
+
+        // Tool result truncation: cap individual tool result content length.
+        // In pi-ai format, toolResult messages have role: "toolResult" and content: TextContent[].
+        // Creates new objects to avoid mutating shared conversation state.
+        const maxChars = cmConfig?.tool_result_max_chars ?? 800;
+        const msgs = payload.messages;
+        if (Array.isArray(msgs)) {
+          payload.messages = msgs.map((msg: Record<string, unknown>) => {
+            // Match toolResult messages (role: "toolResult", content is array of content blocks)
+            if (msg?.role === "toolResult" && Array.isArray(msg.content)) {
+              const blocks = msg.content as Array<Record<string, unknown>>;
+              const totalLen = blocks.reduce((sum: number, b) => sum + (typeof b.text === "string" ? b.text.length : 0), 0);
+              if (totalLen > maxChars) {
+                const truncated = blocks.map(b => {
+                  if (typeof b.text === "string" && b.text.length > maxChars) {
+                    return { ...b, text: b.text.slice(0, maxChars) + "\n…[truncated]" };
+                  }
+                  return b;
+                });
+                return { ...msg, content: truncated };
+              }
+            }
+            return msg;
+          });
+        }
+      } catch { /* non-fatal */ }
+    }
+
+    // ── Service Tier ────────────────────────────────────────────────────
     const modelId = event.model?.id;
-    if (!modelId) return;
+    if (!modelId) return payload;
     const { getEffectiveServiceTier, supportsServiceTier } = await import("../service-tier.js");
     const tier = getEffectiveServiceTier();
-    if (!tier || !supportsServiceTier(modelId)) return;
-    const payload = event.payload as Record<string, unknown> | null;
-    if (!payload || typeof payload !== "object") return;
+    if (!tier || !supportsServiceTier(modelId)) return payload;
     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/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 
+import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
 import { loadPrompt } from "../prompt-loader.js";
 import { readForensicsMarker } from "../forensics.js";
@@ -83,8 +84,8 @@ export async function buildBeforeAgentStartResult(
         memoryBlock = `\n\n${formatted}`;
       }
     }
-  } catch {
-    // non-fatal
+  } catch (e) {
+    logWarning("bootstrap", `memory block fetch failed: ${(e as Error).message}`);
   }
 
   let newSkillsBlock = "";
@@ -111,8 +112,8 @@ export async function buildBeforeAgentStartResult(
           : rawContent;
         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 as Error).message}`);
     }
   }
 
@@ -158,8 +159,8 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
         globalSizeKb = Buffer.byteLength(content, "utf-8") / 1024;
         globalKnowledge = content;
       }
-    } catch {
-      // skip
+    } catch (e) {
+      logWarning("bootstrap", `global knowledge file read failed: ${(e as Error).message}`);
     }
   }
 
@@ -170,8 +171,8 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
     try {
       const content = readFileSync(knowledgePath, "utf-8").trim();
       if (content) projectKnowledge = content;
-    } catch {
-      // skip
+    } catch (e) {
+      logWarning("bootstrap", `project knowledge file read failed: ${(e as Error).message}`);
     }
   }
 
@@ -429,8 +430,8 @@ export function clearForensicsMarker(basePath: string): void {
   if (existsSync(markerPath)) {
     try {
       unlinkSync(markerPath);
-    } catch {
-      // non-fatal
+    } catch (e) {
+      logWarning("bootstrap", `unlinkSync forensics marker failed: ${(e as Error).message}`);
     }
   }
 }

package/src/resources/extensions/gsd/captures.ts

@@ -15,7 +15,7 @@ import { gsdRoot } from "./paths.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
-export type Classification = "quick-task" | "inject" | "defer" | "replan" | "note";
+export type Classification = "quick-task" | "inject" | "defer" | "replan" | "note" | "stop" | "backtrack";
 
 export interface CaptureEntry {
   id: string;
@@ -42,7 +42,7 @@ export interface TriageResult {
 
 const CAPTURES_FILENAME = "CAPTURES.md";
 const VALID_CLASSIFICATIONS: readonly string[] = [
-  "quick-task", "inject", "defer", "replan", "note",
+  "quick-task", "inject", "defer", "replan", "note", "stop", "backtrack",
 ];
 
 // ─── Path Resolution ──────────────────────────────────────────────────────────
@@ -285,6 +285,75 @@ export function loadActionableCaptures(basePath: string, currentMilestoneId?: st
   );
 }
 
+/**
+ * Load unexecuted stop captures — user directives to halt auto-mode.
+ * These are checked in the pre-dispatch guard pipeline (runGuards) to
+ * pause auto-mode before the next unit is dispatched.
+ */
+export function loadStopCaptures(basePath: string): CaptureEntry[] {
+  return loadAllCaptures(basePath).filter(
+    c => c.status === "resolved" && !c.executed &&
+      (c.classification === "stop" || c.classification === "backtrack"),
+  );
+}
+
+/**
+ * Load unexecuted backtrack captures specifically — captures directing
+ * auto-mode to abandon current milestone and return to a previous one.
+ */
+export function loadBacktrackCaptures(basePath: string): CaptureEntry[] {
+  return loadAllCaptures(basePath).filter(
+    c => c.status === "resolved" && !c.executed && c.classification === "backtrack",
+  );
+}
+
+/**
+ * Revert captures that were silenced by non-triage agents.
+ *
+ * When an execute-task or other non-triage agent writes `**Status:** resolved`
+ * to CAPTURES.md, it bypasses the triage pipeline entirely. This function
+ * detects such captures (resolved but missing the Classification field that
+ * triage always writes) and reverts them to pending so the triage sidecar
+ * picks them up properly.
+ *
+ * Returns the number of captures reverted.
+ */
+export function revertExecutorResolvedCaptures(basePath: string): number {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return 0;
+
+  let content = readFileSync(filePath, "utf-8");
+  let reverted = 0;
+
+  const all = loadAllCaptures(basePath);
+  for (const capture of all) {
+    // A properly triaged capture has both resolved status AND a classification.
+    // An executor-silenced capture has resolved status but NO classification.
+    if (capture.status === "resolved" && !capture.classification) {
+      const sectionRegex = new RegExp(
+        `(### ${escapeRegex(capture.id)}\\n(?:(?!### ).)*?)(?=### |$)`,
+        "s",
+      );
+      const match = sectionRegex.exec(content);
+      if (match) {
+        let section = match[1];
+        section = section.replace(
+          /\*\*Status:\*\*\s*resolved/i,
+          "**Status:** pending",
+        );
+        content = content.replace(sectionRegex, section);
+        reverted++;
+      }
+    }
+  }
+
+  if (reverted > 0) {
+    writeFileSync(filePath, content, "utf-8");
+  }
+
+  return reverted;
+}
+
 /**
  * Retroactively stamp a capture with a milestone ID.
  *

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -229,8 +229,10 @@ const NESTED_COMPLETIONS: CompletionMap = {
   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" },
   ],