@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.eed73bea

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

@@ -24,7 +24,7 @@ import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
-import { join, basename } from "node:path";
+import { join, basename, relative } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
 import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
@@ -48,6 +48,7 @@ import {
   type ExcerptResolver,
 } from "./unit-context-composer.js";
 import { resolveManifest, type ArtifactKey } from "./unit-context-manifest.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
 import { compileUnitContextContract, type UnitPromptContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
@@ -323,19 +324,53 @@ function requireComposedArtifactBlock(
   return block.body;
 }
 
+interface ExecuteTaskOnDemandResult {
+  /** Rendered block for the prompt; empty string when not shown. */
+  text: string;
+  /**
+   * Telemetry skip reason when the block was suppressed; null when the block
+   * is included. Callers pass this directly to `trackPromptContext`.
+   */
+  skipReason: string | null;
+}
+
 function renderExecuteTaskOnDemandContext(
   base: string,
   mid: string,
   sid: string,
   artifacts: readonly ArtifactKey[],
-): string {
-  if (!artifacts.includes("slice-research")) return "";
-  const researchPath = relSliceFile(base, mid, sid, "RESEARCH");
-  return [
-    "## On-demand Context",
-    "",
-    `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
-  ].join("\n");
+): ExecuteTaskOnDemandResult {
+  if (!artifacts.includes("slice-research")) {
+    return { text: "", skipReason: "not declared by contract" };
+  }
+  // Mirror dispatch's dual-resolution logic: worktree projection path first,
+  // then the authoritative project-root path via resolveExpectedArtifactPath.
+  // In worktree layouts the RESEARCH file may live under the project-root .gsd
+  // and not have been copied into the worktree projection, so resolveSliceFile
+  // (which looks only at gsdProjectionRoot) would miss it while dispatch would
+  // still treat research as satisfied.
+  const projectedFile = resolveSliceFile(base, mid, sid, "RESEARCH");
+  const researchFile: string | null = projectedFile ?? (() => {
+    const p = resolveExpectedArtifactPath("research-slice", `${mid}/${sid}`, base);
+    return p && existsSync(p) ? p : null;
+  })();
+  if (!researchFile) {
+    return { text: "", skipReason: "missing" };
+  }
+  // Use the layout-aware relative path when the file is in the worktree
+  // projection (relSliceFile), or fall back to node:path relative() when the
+  // file was only found via the project-root resolution path.
+  const researchPath = projectedFile
+    ? relSliceFile(base, mid, sid, "RESEARCH")
+    : relative(base, researchFile);
+  return {
+    text: [
+      "## On-demand Context",
+      "",
+      `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
+    ].join("\n"),
+    skipReason: null,
+  };
 }
 
 // ─── Executor Constraints ─────────────────────────────────────────────────────
@@ -1691,7 +1726,13 @@ export async function buildDiscussMilestonePrompt(
   const draftContent = draftPath ? await loadFile(draftPath) : null;
 
   if (includeDraftSeed && draftContent) {
-    return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${draftContent}`;
+    const draftRelPath = relMilestoneFile(base, mid, "CONTEXT-DRAFT");
+    const draftSeed = `### Prior Discussion Draft\nSource: \`${draftRelPath}\`\n\n${draftContent.trim()}`;
+    const cappedDraftSeed = capPreamble(draftSeed);
+    const truncationNote = cappedDraftSeed !== draftSeed
+      ? `\n\n_(Draft seed truncated; read the full draft at \`${draftRelPath}\` if needed.)_`
+      : "";
+    return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${cappedDraftSeed}${truncationNote}`;
   }
 
   return promptWithContextMode;
@@ -2807,13 +2848,14 @@ export async function buildExecuteTaskPrompt(
   const slicePlanExcerpt = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "slice-plan");
   const contractedCarryForward = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "prior-task-summaries");
   const contractedTemplates = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "templates");
-  const onDemandContext = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  const onDemandResult = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  const onDemandContext = onDemandResult.text;
   trackPromptContext(
     contextTelemetry,
     "slice-research",
     onDemandContext ? "on-demand" : "skipped",
     onDemandContext,
-    onDemandContext ? undefined : "not declared by contract",
+    onDemandContext ? undefined : onDemandResult.skipReason ?? undefined,
   );
 
   const prompt = loadPrompt("execute-task", {

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

@@ -537,14 +537,21 @@ export function verifyExpectedArtifact(
   // discuss-milestone unit with CONTEXT at phases/NN-slug/ in the project root
   // but not in the worktree resolves to null → "resolveExpectedArtifactPath
   // returned null" → finalize-retry loop (#852).
-  if (artifactBase !== base) {
+  //
+  // #870: the fallback must fire whenever the artifact is missing at
+  // `artifactBase`, NOT only when `artifactBase !== base`. When the real call
+  // site passes the worktree path as `base` (auto-post-unit.ts:1726 uses
+  // `s.currentUnit.workspaceRoot ?? s.basePath`), resolveCanonicalMilestoneRoot
+  // round-trips the worktree path back to itself, so `artifactBase === base`
+  // while still being a worktree path that lacks the projected artifact. The
+  // old `if (artifactBase !== base)` guard skipped the fallback in exactly that
+  // case, stranding CONTEXT at the project root and producing a stuck-loop.
+  if (!absPath || !existsSync(absPath)) {
     const projectRoot = resolve(resolveWorktreeProjectRoot(artifactBase));
     if (projectRoot && projectRoot !== artifactBase) {
-      if (!absPath || !existsSync(absPath)) {
-        const projectPath = resolveExpectedArtifactPath(unitType, unitId, projectRoot);
-        if (projectPath && existsSync(projectPath)) {
-          absPath = projectPath;
-        }
+      const projectPath = resolveExpectedArtifactPath(unitType, unitId, projectRoot);
+      if (projectPath && existsSync(projectPath)) {
+        absPath = projectPath;
       }
     }
   }

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

@@ -1,6 +1,8 @@
 // gsd-pi + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 
 import type { AgentEndEvent, ErrorContext } from "../auto/types.js";
 import { logWarning } from "../workflow-logger.js";
@@ -11,7 +13,7 @@ import {
   maybeHandleEmptyIntentTurn,
   resetEmptyTurnCounter,
 } from "../guided-flow.js";
-import { clearPathCache } from "../paths.js";
+import { clearPathCache, gsdRoot } from "../paths.js";
 import {
   getAutoDashboardData,
   getAutoModeStartModel,
@@ -34,7 +36,7 @@ import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { scheduleFallbackContinuation } from "./fallback-continuation.js";
-import { clearGuidedUnitContext } from "../guided-unit-context.js";
+import { clearGuidedUnitContext, getGuidedUnitContext, type GuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import {
   classifyError,
@@ -116,9 +118,14 @@ export function isUserInitiatedAbortMessage(message: string | undefined | null):
 export function shouldDeferTransientErrorToCoreRetry(
   cls: ErrorClass,
   rawErrorMsg: string,
+  deferCheckMsg: string = rawErrorMsg,
 ): boolean {
   if (!isTransient(cls) || cls.kind === "rate-limit") return false;
-  return !/retry failed after \d+ attempts:/i.test(rawErrorMsg);
+  // Empty rawErrorMsg means the SDK terminated the session without providing an
+  // error string — core is done, not mid-retry.  GSD must schedule its own
+  // retry rather than silently deferring to a core that has already exited.
+  if (!rawErrorMsg) return false;
+  return !/retry failed after \d+ attempts:/i.test(deferCheckMsg);
 }
 
 type ProviderModelFallbackParams = {
@@ -388,6 +395,108 @@ export function suppressTerminalDeletedWorktreeMessageEnd(event: MessageEndLike)
   return true;
 }
 
+function modelLabel(ctx: ExtensionContext): string {
+  const provider = ctx.model?.provider;
+  const id = ctx.model?.id;
+  return provider && id ? `${provider}/${id}` : "unknown model";
+}
+
+function isFatalManualGuidedTerminalFailure(lastMsg: unknown): boolean {
+  if (!isObjectRecord(lastMsg) || !("stopReason" in lastMsg)) return false;
+  if (lastMsg.stopReason === "error") {
+    const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+    if (isUserInitiatedAbortMessage(rawErrorMsg)) return false;
+    return true;
+  }
+  if (lastMsg.stopReason !== "aborted") return false;
+
+  const content = "content" in lastMsg ? lastMsg.content : undefined;
+  const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
+  return hasErrorMessage || !_hasEmptyAgentEndContent(content);
+}
+
+function terminalFailureDetail(lastMsg: unknown): string {
+  if (!isObjectRecord(lastMsg)) return "Provider turn ended with an unknown terminal error.";
+  const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+  const content = "content" in lastMsg ? lastMsg.content : undefined;
+  const displayMsg = resolveAgentEndErrorDisplay(rawErrorMsg, content).replace(/\s+/g, " ").trim();
+  if (displayMsg) return displayMsg.length > 300 ? `${displayMsg.slice(0, 300)}...` : displayMsg;
+  return lastMsg.stopReason === "aborted"
+    ? "Provider turn aborted with error context."
+    : "Provider stream ended with stopReason=error.";
+}
+
+function nextManualActivitySequence(activityDir: string): string {
+  let maxSeq = 0;
+  try {
+    for (const file of readdirSync(activityDir)) {
+      const match = /^(\d+)-/.exec(file);
+      if (match) maxSeq = Math.max(maxSeq, Number.parseInt(match[1]!, 10));
+    }
+  } catch {
+    return "001";
+  }
+  return String(maxSeq + 1).padStart(3, "0");
+}
+
+function writeManualGuidedTerminalErrorActivity(
+  basePath: string,
+  unitType: string,
+  model: string,
+  detail: string,
+  stopReason: unknown,
+): void {
+  const activityDir = join(gsdRoot(basePath), "activity");
+  mkdirSync(activityDir, { recursive: true });
+  const seq = nextManualActivitySequence(activityDir);
+  const safeUnitType = unitType.replace(/[^a-z0-9_.-]+/gi, "-");
+  const markerPath = join(activityDir, `${seq}-${safeUnitType}-manual-terminal-provider-error.jsonl`);
+  const message = `Manual guided ${unitType} turn ended with provider ${String(stopReason)} on ${model}: ${detail}`;
+  writeFileSync(
+    markerPath,
+    JSON.stringify({
+      type: "message",
+      message: {
+        role: "toolResult",
+        toolCallId: "manual-guided-terminal-provider-error",
+        toolName: "provider",
+        isError: true,
+        content: [{ type: "text", text: message }],
+      },
+    }) + "\n",
+    "utf-8",
+  );
+}
+
+function observeManualDiscussTerminalError(
+  ctx: ExtensionContext,
+  lastMsg: unknown,
+  guidedUnit: GuidedUnitContext | null,
+): void {
+  if (!guidedUnit?.unitType.startsWith("discuss-")) return;
+  if (!isFatalManualGuidedTerminalFailure(lastMsg)) return;
+
+  const model = modelLabel(ctx);
+  const detail = terminalFailureDetail(lastMsg);
+  ctx.ui.notify(
+    `Manual /gsd discuss ${guidedUnit.unitType} ended with a provider error on ${model}: ${detail}`,
+    "warning",
+  );
+
+  try {
+    writeManualGuidedTerminalErrorActivity(
+      guidedUnit.basePath,
+      guidedUnit.unitType,
+      model,
+      detail,
+      isObjectRecord(lastMsg) ? lastMsg.stopReason : "unknown",
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logWarning("bootstrap", `Failed to write manual guided terminal-error activity marker: ${message}`);
+  }
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -437,7 +546,9 @@ export async function handleAgentEnd(
   // rejected" loop even though the files are on disk.
   clearPathCache();
   const basePath = resolveAgentEndBasePath();
-  clearGuidedUnitContext(basePath);
+  const lastMsg = event.messages[event.messages.length - 1];
+  const guidedUnit = basePath ? getGuidedUnitContext(basePath) ?? getGuidedUnitContext() : getGuidedUnitContext();
+  clearGuidedUnitContext(guidedUnit?.basePath ?? basePath);
 
   try {
     if (await checkDeepProjectSetupAfterTurn(event, ctx, basePath)) {
@@ -466,13 +577,15 @@ export async function handleAgentEnd(
   // discussions (where isAutoActive may be false) still get recovered.
   if (maybeHandleEmptyIntentTurn(event, isAutoActive(), basePath)) return;
 
-  if (!isAutoActive()) return;
+  if (!isAutoActive()) {
+    observeManualDiscussTerminalError(ctx, lastMsg, guidedUnit);
+    return;
+  }
 
   if (shouldIgnoreAgentEndForActiveUnit(event)) {
     return;
   }
 
-  const lastMsg = event.messages[event.messages.length - 1];
   if (isSessionSwitchInFlight()) {
     _handleSessionSwitchAgentEnd(lastMsg, resolveAgentEndCancelled);
     return;
@@ -555,9 +668,9 @@ export async function handleAgentEnd(
       });
       return;
     }
-    // #3588: When errorMessage is uninformative, extract the real error from
-    // the assistant message text content for display purposes only.
-    // Classification still uses rawErrorMsg to avoid false positives from prose.
+    // #3588/#956: When errorMessage is uninformative, extract the real error
+    // from assistant text. Prefer rawErrorMsg for classification to avoid
+    // prose false-positives, but use display text when rawErrorMsg is empty.
     const displayMsg = resolveAgentEndErrorDisplay(
       rawErrorMsg,
       "content" in lastMsg ? lastMsg.content : undefined,
@@ -576,8 +689,8 @@ export async function handleAgentEnd(
     const errorDetail = displayMsg ? `: ${displayMsg}` : "";
     const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
 
-    // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
-    const cls = classifyError(rawErrorMsg, explicitRetryAfterMs);
+    // ── 1. Classify, preserving non-empty errorMessage precedence ──────
+    const cls = classifyError(rawErrorMsg || displayMsg, explicitRetryAfterMs);
 
     // ── 1a. Unsupported-model: provider rejected this model for the current
     //        account/plan at request time (#4513).  Persist a block so the
@@ -655,7 +768,7 @@ export async function handleAgentEnd(
     // Core retries transient failures in-session after this handler.
     // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
     // but let rate-limit continue into model fallback logic below (#4373).
-    if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg)) {
+    if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg, rawErrorMsg || displayMsg)) {
       return;
     }
 

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

@@ -3,6 +3,7 @@
 import { Type, StringEnum } from "@gsd/pi-ai";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
+import { SUMMARY_SAVE_CONTENT_MAX_LENGTH } from "@opengsd/contracts";
 
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen, resolveCtxCwd, resolveWorkflowToolBasePath } from "./dynamic-tools.js";
@@ -392,13 +393,17 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
       "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
       "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
+      `Keep each content payload under ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters; save large context incrementally with CONTEXT-DRAFT/PROJECT-DRAFT/REQUIREMENTS-DRAFT instead of one oversized call.`,
     ],
     parameters: Type.Object({
       milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
       slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
       task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
       artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
-      content: Type.String({ description: "The full markdown content of the artifact" }),
+      content: Type.String({
+        description: `The full markdown content of the artifact. Maximum ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save.`,
+        maxLength: SUMMARY_SAVE_CONTENT_MAX_LENGTH,
+      }),
     }),
     execute: summarySaveExecute,
     renderCall(args: any, theme: any) {

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

@@ -72,6 +72,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeUatExec(params as Parameters<typeof executeUatExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });
@@ -119,6 +120,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });

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

@@ -13,7 +13,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, canonicalPhaseDirName, clearPathCache, milestonesDir, legacyMilestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, currentWriteGateSnapshot, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId, type WriteGateSnapshot } from "./write-gate.js";
 import { canonicalToolName } from "../engine-hook-contract.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
@@ -583,6 +583,10 @@ function deferApprovalGate(gateId: string, basePath: string): void {
   // workflow MCP child already verified this gate, deferring would block
   // tools for a gate that can never legitimately arm.
   const snapshot = hostWriteGateAdapter.readState(basePath);
+  deferApprovalGateFromSnapshot(gateId, basePath, snapshot);
+}
+
+function deferApprovalGateFromSnapshot(gateId: string, basePath: string, snapshot: WriteGateSnapshot): void {
   if (isApprovalGateVerifiedInSnapshot(snapshot, gateId)) return;
   const milestoneId = extractDepthVerificationMilestoneId(gateId);
   if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return;
@@ -1233,13 +1237,15 @@ export function registerHooks(
 
     const gateId = approvalGateIdForUnit(unitType, unitId);
     if (gateId) {
+      const basePath = contextBasePath(ctx);
+      const gateSnapshot = currentWriteGateSnapshot(basePath);
       // Skip the gate if this milestone is already depth-verified — the approval
       // pattern matched again on post-verification text (a false-positive re-trigger).
       // Without this guard, the second firing blocks gsd_plan_milestone in the same
       // turn and leaves CONTEXT.md on disk with no DB row (#discuss-milestone-no-db).
       const gateMilestoneId = extractDepthVerificationMilestoneId(gateId);
-      if (gateMilestoneId && isMilestoneDepthVerified(gateMilestoneId, contextBasePath(ctx))) return;
-      deferApprovalGate(gateId, contextBasePath(ctx));
+      if (gateMilestoneId && isMilestoneDepthVerifiedInSnapshot(gateSnapshot, gateMilestoneId)) return;
+      deferApprovalGateFromSnapshot(gateId, basePath, gateSnapshot);
     }
 
     approvalQuestionAbortInFlight = true;

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -28,9 +28,10 @@ const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
 const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
 const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
 
-const contextMaintenanceCompletedForBasePath = new Set<string>();
-const contextMaintenanceInFlightByBasePath = new Map<string, Promise<boolean>>();
-const deferredContextMaintenanceByBasePath = new Map<string, Promise<void>>();
+const CONTEXT_MAINTENANCE_KEY_SEPARATOR = "\0";
+const contextMaintenanceCompletedForSession = new Set<string>();
+const contextMaintenanceInFlightBySession = new Map<string, Promise<boolean>>();
+const deferredContextMaintenanceBySession = new Map<string, Promise<void>>();
 
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
@@ -114,7 +115,8 @@ async function runSessionStartupMaintenanceOnce(
   basePath: string,
   ctx: ExtensionContext,
 ): Promise<boolean> {
-  if (contextMaintenanceCompletedForBasePath.has(basePath)) {
+  const maintenanceKey = getContextMaintenanceKey(basePath, ctx);
+  if (contextMaintenanceCompletedForSession.has(maintenanceKey)) {
     // Backfills are session-once, but memory queries and other DB-backed
     // prompt assembly still need an active adapter on every turn.
     try {
@@ -126,16 +128,16 @@ async function runSessionStartupMaintenanceOnce(
     return false;
   }
 
-  const existing = contextMaintenanceInFlightByBasePath.get(basePath);
+  const existing = contextMaintenanceInFlightBySession.get(maintenanceKey);
   const isInitiator = !existing;
   // Use a definite Promise<boolean> so `await inFlight` has a known return type.
   let inFlight: Promise<boolean>;
   if (isInitiator) {
-    inFlight = performSessionStartupMaintenance(basePath, ctx);
-    contextMaintenanceInFlightByBasePath.set(basePath, inFlight);
+    inFlight = performSessionStartupMaintenance(basePath, ctx, maintenanceKey);
+    contextMaintenanceInFlightBySession.set(maintenanceKey, inFlight);
     void inFlight.finally(() => {
-      if (contextMaintenanceInFlightByBasePath.get(basePath) === inFlight) {
-        contextMaintenanceInFlightByBasePath.delete(basePath);
+      if (contextMaintenanceInFlightBySession.get(maintenanceKey) === inFlight) {
+        contextMaintenanceInFlightBySession.delete(maintenanceKey);
       }
     });
   } else {
@@ -149,6 +151,7 @@ async function runSessionStartupMaintenanceOnce(
 async function performSessionStartupMaintenance(
   basePath: string,
   ctx: ExtensionContext,
+  maintenanceKey: string,
 ): Promise<boolean> {
   // DB-backed memory backfills run below. On a cold session the database file
   // may exist without an active in-process adapter, so open the canonical
@@ -172,11 +175,40 @@ async function performSessionStartupMaintenance(
 
   // Mark session complete before scheduling deferred work so any concurrent
   // caller that observes the completed state does not re-enter maintenance.
-  contextMaintenanceCompletedForBasePath.add(basePath);
-  scheduleDeferredContextMaintenance(basePath);
+  contextMaintenanceCompletedForSession.add(maintenanceKey);
+  scheduleDeferredContextMaintenance(basePath, maintenanceKey);
   return true;
 }
 
+function getContextMaintenanceKey(basePath: string, ctx: ExtensionContext): string {
+  return `${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}${getContextSessionPart(ctx)}`;
+}
+
+function getContextSessionPart(ctx: ExtensionContext): string {
+  const sessionManager = (ctx as {
+    sessionManager?: {
+      getSessionId?: () => string | undefined;
+      getSessionFile?: () => string | undefined;
+    };
+  }).sessionManager;
+
+  try {
+    const sessionId = sessionManager?.getSessionId?.();
+    if (typeof sessionId === "string" && sessionId.length > 0) return `id:${sessionId}`;
+  } catch (e) {
+    logWarning("bootstrap", `session-id fetch failed: ${(e as Error).message}`);
+  }
+
+  try {
+    const sessionFile = sessionManager?.getSessionFile?.();
+    if (typeof sessionFile === "string" && sessionFile.length > 0) return `file:${sessionFile}`;
+  } catch (e) {
+    logWarning("bootstrap", `session-file fetch failed: ${(e as Error).message}`);
+  }
+
+  return "process";
+}
+
 async function runDecisionsMemoryBackfill(ctx: ExtensionContext): Promise<void> {
   // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
   // and best-effort — first run absorbs the existing decisions table into
@@ -210,8 +242,8 @@ async function runKnowledgeMemoryBackfill(
   }
 }
 
-function scheduleDeferredContextMaintenance(basePath: string): void {
-  if (deferredContextMaintenanceByBasePath.has(basePath)) return;
+function scheduleDeferredContextMaintenance(basePath: string, maintenanceKey: string): void {
+  if (deferredContextMaintenanceBySession.has(maintenanceKey)) return;
 
   const task = new Promise<void>((resolve) => {
     setTimeout(() => {
@@ -219,10 +251,10 @@ function scheduleDeferredContextMaintenance(basePath: string): void {
     }, 0);
   });
 
-  deferredContextMaintenanceByBasePath.set(basePath, task);
+  deferredContextMaintenanceBySession.set(maintenanceKey, task);
   void task.finally(() => {
-    if (deferredContextMaintenanceByBasePath.get(basePath) === task) {
-      deferredContextMaintenanceByBasePath.delete(basePath);
+    if (deferredContextMaintenanceBySession.get(maintenanceKey) === task) {
+      deferredContextMaintenanceBySession.delete(maintenanceKey);
     }
   });
 }
@@ -257,8 +289,10 @@ async function reportConsolidationGapsDeferred(basePath: string): Promise<void>
 
 export async function _flushDeferredContextMaintenanceForTest(basePath?: string): Promise<void> {
   const tasks = basePath
-    ? [deferredContextMaintenanceByBasePath.get(basePath)].filter((task): task is Promise<void> => Boolean(task))
-    : [...deferredContextMaintenanceByBasePath.values()];
+    ? [...deferredContextMaintenanceBySession.entries()]
+        .filter(([key]) => key.startsWith(`${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}`))
+        .map(([, task]) => task)
+    : [...deferredContextMaintenanceBySession.values()];
   await Promise.allSettled(tasks);
 }