gsd-pi 2.82.0-dev.2841a1e44 → 2.82.0-dev.98ea09b1e

package/src/resources/GSD-WORKFLOW.md

@@ -448,6 +448,13 @@ What differed from the plan and why (or "None").
 
 The one-liner must be substantive: "JWT auth with refresh rotation using jose" not "Authentication implemented."
 
+When `key_files` or `key_decisions` are empty, render them as empty YAML lists:
+
+```yaml
+key_files: []
+key_decisions: []
+```
+
 **Slice summary:** Written when all tasks in a slice complete. Compresses all task summaries. Includes `drill_down_paths` to each task summary. During slice completion, review task summaries for `key_decisions` and ensure any significant ones are captured in `.gsd/DECISIONS.md`.
 
 **Milestone summary:** Updated each time a slice completes. Compresses all slice summaries. This is what gets injected into later slice planning instead of loading many individual summaries.

package/src/resources/extensions/claude-code-cli/partial-builder.ts

@@ -134,10 +134,11 @@ export function mapUsage(sdkUsage: NonNullableUsage, totalCostUsd: number): Usag
 		output: sdkUsage.output_tokens,
 		cacheRead: sdkUsage.cache_read_input_tokens,
 		cacheWrite: sdkUsage.cache_creation_input_tokens,
+		// Claude Agent SDK result usage is cumulative across its internal loop;
+		// repeated cache reads do not represent additional live context.
 		totalTokens:
 			sdkUsage.input_tokens +
 			sdkUsage.output_tokens +
-			sdkUsage.cache_read_input_tokens +
 			sdkUsage.cache_creation_input_tokens,
 		cost: {
 			input: 0,

package/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts

@@ -1,7 +1,24 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { mapContentBlock, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
-import type { BetaContentBlock, BetaRawMessageStreamEvent } from "../sdk-types.ts";
+import { mapContentBlock, mapUsage, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
+import type { BetaContentBlock, BetaRawMessageStreamEvent, NonNullableUsage } from "../sdk-types.ts";
+
+describe("mapUsage", () => {
+	test("excludes cumulative cache reads from context-sized totalTokens (#5243)", () => {
+		const usage: NonNullableUsage = {
+			input_tokens: 150_000,
+			output_tokens: 2_000,
+			cache_read_input_tokens: 900_000,
+			cache_creation_input_tokens: 3_000,
+		};
+
+		const mapped = mapUsage(usage, 1.23);
+
+		assert.equal(mapped.cacheRead, 900_000);
+		assert.equal(mapped.totalTokens, 155_000);
+		assert.equal(mapped.cost.total, 1.23);
+	});
+});
 
 describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 	/**

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

@@ -47,12 +47,20 @@ export interface DispatchAdapter {
     sessionProvider?: string;
     /** Model registry for executor-model lookups inside the budget engine. */
     modelRegistry?: MinimalModelRegistry;
-  }): Promise<{
-    unitType: string;
-    unitId: string;
-    reason: string;
-    preconditions: string[];
-  } | null>;
+  }): Promise<
+    | {
+        kind: "blocked";
+        reason: string;
+        action: "pause" | "stop";
+      }
+    | {
+        unitType: string;
+        unitId: string;
+        reason: string;
+        preconditions: string[];
+      }
+    | null
+  >;
 }
 
 export interface RecoveryAdapter {

package/src/resources/extensions/gsd/auto/infra-errors.ts

@@ -7,9 +7,14 @@
  */
 
 /**
- * Error codes indicating infrastructure failures that cannot be recovered by
- * retrying. Each retry re-dispatches the unit at full LLM cost, so we bail
- * immediately rather than burning budget on guaranteed failures.
+ * Error codes indicating infrastructure-level failures from the OS,
+ * filesystem, or network. This set includes permanent resource failures
+ * (ENOSPC, ENOMEM, EROFS), transient resource exhaustion (EAGAIN, ENOBUFS),
+ * and network/offline errors (ECONNREFUSED, ENOTFOUND, ENETUNREACH).
+ *
+ * Transient git failures are retried separately through
+ * TRANSIENT_GIT_RETRY_CODES in native-git-bridge.ts before escalating to the
+ * auto-loop.
  */
 export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "ENOSPC",   // disk full
@@ -19,6 +24,7 @@ export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "EMFILE",   // too many open files (process)
   "ENFILE",   // too many open files (system)
   "EAGAIN",       // resource temporarily unavailable (resource exhaustion)
+  "ENOBUFS",      // no buffer space available (transient pipe exhaustion)
   "ECONNREFUSED", // connection refused (offline / local server down)
   "ENOTFOUND",    // DNS lookup failed (offline / no network)
   "ENETUNREACH",  // network unreachable (offline / no route)

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

@@ -78,7 +78,10 @@ import { createWorkflowTurnReporter } from "./workflow-turn-reporter.js";
 import { validateWorkflowSessionLock } from "./workflow-session-lock.js";
 import { dequeueSidecarItem } from "./workflow-sidecar-queue.js";
 import { maintainWorkerHeartbeat } from "./workflow-worker-heartbeat.js";
-import { measureMemoryPressure } from "./workflow-memory-pressure.js";
+import {
+  measureMemoryPressure,
+  shouldCheckMemoryPressure,
+} from "./workflow-memory-pressure.js";
 import { buildSidecarIterationData } from "./workflow-sidecar-iteration.js";
 import {
   createExecutionGraphUnitDispatchDeps,
@@ -203,9 +206,9 @@ function logCustomVerifyRetrySaveFailure(err: unknown): void {
 }
 
 // ── Memory pressure monitoring (#3331) ──────────────────────────────────
-// Check heap usage every N iterations and trigger graceful shutdown before
-// the OS OOM killer sends SIGKILL. The threshold is 90% of the V8 heap
-// limit (--max-old-space-size or default ~1.5-4GB depending on platform).
+// Check heap usage on session startup, then every N iterations, and trigger
+// graceful shutdown before the OS OOM killer sends SIGKILL. The threshold is
+// 90% of the V8 heap limit (--max-old-space-size or default ~1.5-4GB depending on platform).
 const MEMORY_CHECK_INTERVAL = 5; // check every 5 iterations
 const MAX_CUSTOM_ENGINE_VERIFY_RETRIES = 3;
 
@@ -372,7 +375,7 @@ export async function autoLoop(
 
     // ── Memory pressure check (#3331) ──
     // Graceful shutdown before OOM killer sends SIGKILL.
-    if (iteration % MEMORY_CHECK_INTERVAL === 0) {
+    if (shouldCheckMemoryPressure(iteration, MEMORY_CHECK_INTERVAL)) {
       const mem = measureMemoryPressure();
       debugLog("autoLoop", { phase: "memory-check", ...mem });
       const memoryDecision = decideMemoryPressure({ ...mem, iteration });

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

@@ -128,6 +128,17 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         await this.deps.health.postAdvanceRecord(stopped);
         return stopped;
       }
+      if (!("unitType" in decision)) {
+        const blocked: AutoAdvanceResult = {
+          kind: "blocked",
+          reason: decision.reason,
+          action: decision.action,
+          stateSnapshot: reconciliation.stateSnapshot,
+        };
+        await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+        await this.deps.health.postAdvanceRecord(blocked);
+        return blocked;
+      }
 
       const nextKey = `${decision.unitType}:${decision.unitId}`;
 

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

@@ -1327,9 +1327,15 @@ export async function runDispatch(
   }
 
   const guardBasePath = _resolveDispatchGuardBasePath(s);
+  let mainBranch = "main";
+  try {
+    mainBranch = deps.getMainBranch(guardBasePath);
+  } catch (err) {
+    debugLog("autoLoop", { phase: "getMainBranch-failed", error: String(err) });
+  }
   const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
     guardBasePath,
-    deps.getMainBranch(guardBasePath),
+    mainBranch,
     unitType,
     unitId,
   );

package/src/resources/extensions/gsd/auto/workflow-memory-pressure.ts

@@ -19,6 +19,19 @@ export interface MeasureMemoryPressureDeps {
   heapLimitBytes: () => number;
 }
 
+/**
+ * Returns true on auto-mode startup, then every configured interval.
+ *
+ * Iteration 1 is checked explicitly so early session memory pressure cannot
+ * bypass the periodic interval guard.
+ */
+export function shouldCheckMemoryPressure(iteration: number, interval: number): boolean {
+  if (!Number.isInteger(interval) || interval <= 0) {
+    throw new Error("Memory pressure check interval must be a positive integer");
+  }
+  return iteration === 1 || iteration % interval === 0;
+}
+
 function defaultHeapLimitBytes(): number {
   const v8 = require("node:v8") as {
     getHeapStatistics?: () => { heap_size_limit?: number };

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

@@ -239,6 +239,12 @@ function missingSliceStop(mid: string, phase: string): DispatchAction {
   };
 }
 
+function isRegistryMilestoneComplete(state: GSDState, mid: string): boolean {
+  return state.registry.some((milestone) =>
+    milestone.id === mid && milestone.status === "complete"
+  );
+}
+
 /**
  * Check for milestone slices missing SUMMARY files.
  * Returns array of missing slice IDs, or empty array if all present or DB unavailable.
@@ -395,6 +401,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
       if (!EXECUTION_ENTRY_PHASES.has(state.phase)) return null;
       if (!MILESTONE_ID_RE.test(mid)) return null;
+      if (isRegistryMilestoneComplete(state, mid)) return null;
       // Align with the plan-v2 gate's lookup semantics: whitespace-only counts
       // as missing, and an auto worktree may fall back to GSD_PROJECT_ROOT.
       if (hasFinalizedMilestoneContext(basePath, mid)) return null;
@@ -709,6 +716,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     name: "pre-planning (no context) → discuss-milestone",
     match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
       if (state.phase !== "pre-planning") return null;
+      if (isRegistryMilestoneComplete(state, mid)) return null;
       const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
       const hasContext = !!(contextFile && (await loadFile(contextFile)));
       if (hasContext) return null; // fall through to next rule
@@ -1322,19 +1330,19 @@ export const DISPATCH_RULES: DispatchRule[] = [
         }
       }
 
-      // Safety guard (#2675): block completion when VALIDATION verdict is
-      // needs-remediation. The state machine treats needs-remediation as
-      // terminal (to prevent validate-milestone loops per #832), but
-      // completing-milestone should NOT proceed — remediation work is needed.
+      // Safety guard (#2675, #5747): block completion when VALIDATION
+      // verdict is non-passing. The state machine treats these verdicts as
+      // terminal, but completing-milestone should NOT proceed — remediation
+      // or human attention is needed.
       const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
       if (validationFile) {
         const validationContent = await loadFile(validationFile);
         if (validationContent) {
           const verdict = extractVerdict(validationContent);
-          if (verdict === "needs-remediation") {
+          if (verdict === "needs-remediation" || verdict === "needs-attention") {
             return {
               action: "stop",
-              reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "needs-remediation". Address the remediation findings and re-run validation, or update the verdict manually.`,
+              reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or update the verdict manually.`,
               level: "warning",
             };
           }

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -615,10 +615,11 @@ export async function selectAndApplyModel(
  * Handles formats: "provider/model", "bare-id", "org/model-name" (OpenRouter).
  */
 export function resolveModelId<T extends { id: string; provider: string }>(
-  modelId: string,
+  modelId: string | undefined,
   availableModels: T[],
   currentProvider: string | undefined,
 ): T | undefined {
+  if (!modelId) return undefined;
   const slashIdx = modelId.indexOf("/");
 
   if (slashIdx !== -1) {

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -41,6 +41,7 @@ import {
   resolveExpectedArtifactPath,
   writeBlockerPlaceholder,
   diagnoseExpectedArtifact,
+  diagnoseWorktreeIntegrityFailure,
 } from "./auto-recovery.js";
 import { regenerateIfMissing } from "./workflow-projections.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
@@ -163,7 +164,7 @@ async function buildTaskCommitContextForUnit(
     sliceTitle: stripKnownIdPrefix(slice?.title, sid),
     oneLiner: summary?.oneLiner || task?.one_liner || undefined,
     keyFiles:
-      summary?.frontmatter.key_files?.filter(f => !f.includes("{{")) ??
+      summary?.frontmatter.key_files?.filter(f => !f.includes("{{") && f.trim() !== "(none)") ??
       task?.key_files ??
       undefined,
     issueNumber: ghIssueNumber,
@@ -381,6 +382,23 @@ export function buildStepCompleteMessage(nextState: import("./types.js").GSDStat
     + `Run /clear, then /gsd to continue (or /gsd auto to run continuously).`;
 }
 
+/**
+ * Decide whether step mode should stop at the step wizard after a unit finishes.
+ *
+ * @param currentUnitType The just-finished unit type, such as "execute-task" or
+ *   "complete-milestone"; may be null/undefined when no current unit is known.
+ * @param phaseAfterUnit The freshly derived next phase, such as "executing" or
+ *   "complete"; may be null/undefined if state derivation failed.
+ * @returns true to show the step wizard; false to keep the loop running so
+ *   terminal milestone completion can reach the merge/finalization path.
+ */
+export function shouldReturnStepWizardAfterUnit(
+  currentUnitType: string | null | undefined,
+  phaseAfterUnit: string | null | undefined,
+): boolean {
+  return currentUnitType !== "complete-milestone" && phaseAfterUnit !== "complete";
+}
+
 export interface PreVerificationOpts {
   skipSettleDelay?: boolean;
   skipWorktreeSync?: boolean;
@@ -413,6 +431,11 @@ function artifactValidationKind(unitType: string): "project" | "requirements" |
 }
 
 function describeArtifactVerificationFailure(unitType: string, unitId: string, basePath: string): string {
+  const worktreeFailure = diagnoseWorktreeIntegrityFailure(basePath);
+  if (worktreeFailure) {
+    return `${worktreeFailure} Unit: ${unitType} ${unitId}.`;
+  }
+
   const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
   if (!artifactPath) {
     return `Artifact verification failed: ${unitType} "${unitId}" has no resolvable artifact path.`;
@@ -469,9 +492,17 @@ export async function autoCommitUnit(
   }
 }
 
+/**
+ * Execute the turn-level git action (commit, snapshot, or status-only).
+ *
+ * @param opts.softFailure - Defaults to false. When true, retry git failures,
+ * warn, and continue without pausing auto-mode; use for best-effort deferred
+ * closeout work where a git failure should not block the run.
+ */
 async function runCloseoutGitAction(
   pctx: PostUnitContext,
   unit: NonNullable<AutoSession["currentUnit"]>,
+  opts?: { softFailure?: boolean },
 ): Promise<"continue" | "dispatched"> {
   const { s, ctx, pi, pauseAuto } = pctx;
   const prefs = loadEffectiveGSDPreferences()?.preferences;
@@ -506,13 +537,24 @@ async function runCloseoutGitAction(
         unitId: unit.id,
       });
     } else {
-      const gitResult = runTurnGitAction({
+      const maxAttempts = opts?.softFailure ? 3 : 1;
+      let gitResult = runTurnGitAction({
         basePath: s.basePath,
         action: turnAction,
         unitType: unit.type,
         unitId: unit.id,
         taskContext,
       });
+      for (let attempt = 1; gitResult.status === "failed" && attempt < maxAttempts; attempt++) {
+        await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+        gitResult = runTurnGitAction({
+          basePath: s.basePath,
+          action: turnAction,
+          unitType: unit.type,
+          unitId: unit.id,
+          taskContext,
+        });
+      }
 
       if (uokFlags.gitops) {
         writeTurnGitTransaction({
@@ -563,12 +605,15 @@ async function runCloseoutGitAction(
         }
 
         const failureMsg = `Git ${turnAction} failed: ${(gitResult.error ?? "unknown error").split("\n")[0]}`;
-        ctx.ui.notify(failureMsg, "error");
+        ctx.ui.notify(failureMsg, opts?.softFailure ? "warning" : "error");
         debugLog("postUnit", {
-          phase: "git-action-failed-blocking",
+          phase: opts?.softFailure ? "git-action-failed-soft" : "git-action-failed-blocking",
           action: turnAction,
           error: gitResult.error ?? "unknown error",
         });
+        if (opts?.softFailure) {
+          return "continue";
+        }
         await pauseAuto(ctx, pi);
         return "dispatched";
       }
@@ -586,7 +631,10 @@ async function runCloseoutGitAction(
     s.lastGitActionFailure = message;
     s.lastGitActionStatus = "failed";
     debugLog("postUnit", { phase: "git-action", error: message, action: turnAction });
-    ctx.ui.notify(`Git ${turnAction} failed: ${message.split("\n")[0]}`, uokFlags.gitops ? "error" : "warning");
+    ctx.ui.notify(`Git ${turnAction} failed: ${message.split("\n")[0]}`, opts?.softFailure ? "warning" : "error");
+    if (opts?.softFailure) {
+      return "continue";
+    }
     if (uokFlags.gitops) {
       await pauseAuto(ctx, pi);
       return "dispatched";
@@ -1133,6 +1181,24 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           "warning",
         );
         // Fall through to "continue" — do NOT enter the retry or db-unavailable paths.
+      } else if (!triggerArtifactVerified && diagnoseWorktreeIntegrityFailure(s.basePath)) {
+        const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`;
+        const worktreeFailure = diagnoseWorktreeIntegrityFailure(s.basePath)!;
+        s.pendingVerificationRetry = null;
+        s.verificationRetryCount.delete(retryKey);
+        s.verificationRetryFailureHashes.delete(retryKey);
+        debugLog("postUnit", {
+          phase: "worktree-integrity-failure",
+          unitType: s.currentUnit.type,
+          unitId: s.currentUnit.id,
+          basePath: s.basePath,
+        });
+        ctx.ui.notify(
+          `${worktreeFailure} Retry ${s.currentUnit.id} after repair.`,
+          "error",
+        );
+        await pauseAuto(ctx, pi);
+        return "dispatched";
       } else if (!triggerArtifactVerified && !isDbAvailable()) {
         debugLog("postUnit", { phase: "artifact-verify-skip-db-unavailable", unitType: s.currentUnit.type, unitId: s.currentUnit.id });
         const dbSkipDiag = diagnoseExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
@@ -1220,7 +1286,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
   if (s.currentUnit) {
     if (shouldDeferCloseoutGitAction(s.currentUnit.type)) {
-      const gitActionResult = await runCloseoutGitAction(pctx, s.currentUnit);
+      const gitActionResult = await runCloseoutGitAction(pctx, s.currentUnit, { softFailure: true });
       if (gitActionResult === "dispatched") {
         return "stopped";
       }
@@ -1668,14 +1734,18 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // Without this notify(), /gsd in step mode finishes a unit and silently
   // exits the loop, leaving the user with no hint to /clear and /gsd again.
   if (s.stepMode) {
+    let phaseAfterUnit: string | null = null;
     try {
       const nextState = await deriveState(s.canonicalProjectRoot);
+      phaseAfterUnit = nextState.phase;
       ctx.ui.notify(buildStepCompleteMessage(nextState), "info");
     } catch (e) {
       debugLog("postUnit", { phase: "step-wizard-notify", error: String(e) });
       ctx.ui.notify(STEP_COMPLETE_FALLBACK_MESSAGE, "info");
     }
-    return "step-wizard";
+    return shouldReturnStepWizardAfterUnit(s.currentUnit?.type, phaseAfterUnit)
+      ? "step-wizard"
+      : "continue";
   }
 
   return "continue";

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

@@ -46,6 +46,7 @@ import {
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { validateArtifact } from "./schemas/validate.js";
 import { getProjectResearchStatus } from "./project-research-policy.js";
+import { isGsdWorktreePath } from "./worktree-root.js";
 
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
@@ -56,6 +57,29 @@ export {
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
+export function diagnoseWorktreeIntegrityFailure(basePath: string): string | null {
+  if (!isGsdWorktreePath(basePath)) return null;
+  if (!existsSync(basePath)) {
+    return `Worktree integrity failure: ${basePath} does not exist. Repair or recreate the worktree before retrying.`;
+  }
+
+  const gitPath = join(basePath, ".git");
+  if (!existsSync(gitPath)) {
+    return `Worktree integrity failure: ${basePath} is not a valid git worktree (.git missing). Repair or recreate the worktree before retrying.`;
+  }
+
+  try {
+    execFileSync("git", ["rev-parse", "--git-dir"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    return null;
+  } catch (err) {
+    return `Worktree integrity failure: ${basePath} is not a valid git worktree (git rev-parse failed: ${getErrorMessage(err).split("\n")[0]}). Repair or recreate the worktree before retrying.`;
+  }
+}
+
 export type ArtifactRecoveryDbRefreshResult =
   | { ok: true }
   | { ok: false; fatal: boolean; message: string; reason: string };
@@ -752,6 +776,11 @@ export function verifyExpectedArtifact(
     return false;
   }
   if (!existsSync(absPath)) {
+    const worktreeFailure = diagnoseWorktreeIntegrityFailure(base);
+    if (worktreeFailure) {
+      logError("recovery", `${worktreeFailure} Unit: ${unitType} ${unitId}.`);
+      return false;
+    }
     logWarning("recovery", `verify-fail ${unitType} ${unitId}: existsSync false for ${absPath}`);
     return false;
   }