@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.822c9439

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

@@ -18,7 +18,7 @@ import { deriveState } from "./state.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
-import { isAwaitingUserInput } from "./user-input-boundary.js";
+import { isAwaitingUserInput } from "./consent-question.js";
 import {
   resolveMilestonePath,
   resolveSliceFile,
@@ -51,8 +51,7 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
-import { renderPlanCheckboxes, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
+import { renderPlanCheckboxes, renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
   checkPostUnitHooks,
@@ -96,6 +95,7 @@ import {
 } from "./project-research-policy.js";
 import { validateArtifact } from "./schemas/validate.js";
 import { verificationRetryKey } from "./auto/verification-retry-policy.js";
+import { saveCustomVerifyRetryCounts } from "./auto/custom-verify-retry-store.js";
 import { getLedger } from "./metrics.js";
 import { getUnitCostSpikeAction, resolveUnitCostSpikeMultiplier } from "./auto-budget.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
@@ -901,7 +901,7 @@ export const USER_DRIVEN_DEEP_UNITS = new Set([
   "discuss-milestone",
   "research-decision",
 ]);
-export { isAwaitingUserInput } from "./user-input-boundary.js";
+export { isAwaitingUserInput } from "./consent-question.js";
 
 function artifactValidationKind(unitType: string): "project" | "requirements" | null {
   if (unitType === "discuss-project") return "project";
@@ -990,11 +990,13 @@ async function repairCompleteSliceRoadmapProjection(
     return false;
   }
 
+  // Stale-render detection (ADR-017): the DB already says the slice is closed;
+  // this only checks whether the rendered ROADMAP projection reflects it, to
+  // decide whether a repair re-render is needed.
   const roadmapPath = resolveMilestoneFile(artifactBase, mid, "ROADMAP");
   if (roadmapPath && existsSync(roadmapPath)) {
     try {
-      const roadmap = parseLegacyRoadmap(readFileSync(roadmapPath, "utf-8"));
-      if (roadmap.slices.find((roadmapSlice) => roadmapSlice.id === sid)?.done) {
+      if (roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sid)) {
         return false;
       }
     } catch (err) {
@@ -2023,16 +2025,30 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         );
       } else if (!triggerArtifactVerified) {
         if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
-          // Tool-unavailable is the one transient invocation error: the
-          // workflow MCP server registers its surface asynchronously, so a
-          // Unit's first call can race the registration. Fall through to the
-          // bounded verification retry instead of pausing.
-          debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
+          // Tool-unavailable is transient: the workflow MCP server registers
+          // its surface asynchronously, so a Unit's first call can race the
+          // registration. Retry with escalating delay, bounded at 3 attempts.
+          // ponytail: MAX constant so the guard, log, and display all agree
+          const MAX_TOOL_UNAVAIL_RETRIES = 3;
+          if (s.toolUnavailableRetries >= MAX_TOOL_UNAVAIL_RETRIES) {
+            debugLog("postUnit", { phase: "tool-unavailable-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, retries: s.toolUnavailableRetries });
+            ctx.ui.notify(
+              `Tool unavailable for ${s.currentUnit.type} after ${MAX_TOOL_UNAVAIL_RETRIES} retries: ${s.lastToolInvocationError}. MCP server may not be starting — pausing auto-mode.`,
+              "error",
+            );
+            s.lastToolInvocationError = null;
+            await pauseAuto(ctx, pi);
+            return "dispatched";
+          }
+          s.toolUnavailableRetries++;
+          const delayMs = s.toolUnavailableRetries * 1000;
+          debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError, attempt: s.toolUnavailableRetries, delayMs });
           ctx.ui.notify(
-            `Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. The tool surface may still be registering — retrying.`,
+            `Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Waiting ${delayMs}ms for MCP server — retry ${s.toolUnavailableRetries}/${MAX_TOOL_UNAVAIL_RETRIES}.`,
             "warning",
           );
           s.lastToolInvocationError = null;
+          await new Promise(r => setTimeout(r, delayMs));
         } else if (s.lastToolInvocationError) {
           const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
           const errMsg = isUserSkip
@@ -2159,6 +2175,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
               }
             }
             s.exhaustedVerificationUnits.add(retryKey);
+            saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
             debugLog("postUnit", { phase: "artifact-verify-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });
             ctx.ui.notify(
               `${failureDetails} Pausing auto-mode after ${MAX_ARTIFACT_VERIFICATION_RETRIES} retries.`,
@@ -2168,6 +2185,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
             return "dispatched";
           }
           s.verificationRetryCount.set(retryKey, attempt);
+          saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
           s.pendingVerificationRetry = {
             unitId: s.currentUnit.id,
             failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
@@ -2189,8 +2207,11 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         if (s.pendingVerificationRetry?.unitId === s.currentUnit.id) {
           s.pendingVerificationRetry = null;
         }
+        s.toolUnavailableRetries = 0;
         s.verificationRetryCount.delete(retryKey);
         s.verificationRetryFailureHashes.delete(retryKey);
+        s.exhaustedVerificationUnits.delete(retryKey);
+        saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
 
         if (s.currentUnit.type === "complete-milestone") {
           const { milestone: mid } = parseUnitId(s.currentUnit.id);

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

@@ -40,6 +40,7 @@ import {
   composeContextModeInstructions,
   composeContractedUnitContext,
   composeInlinedContext,
+  composeToolSurfaceInstructions,
   composeUnitContext,
   type ArtifactResolver,
   type ComposedUnitContextBlock,
@@ -57,7 +58,11 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent, type UatType } from "./uat-policy.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
 import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
@@ -292,10 +297,12 @@ function prependContextModeToBlock(
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
+  const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
   const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-  if (!contextMode) return block;
-  if (!block.trim()) return contextMode;
-  return `${contextMode}\n\n${block}`;
+  const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+  if (!guidance) return block;
+  if (!block.trim()) return guidance;
+  return `${guidance}\n\n${block}`;
 }
 
 function requireUnitPromptContextContract(unitType: string): UnitPromptContextContract {
@@ -969,7 +976,7 @@ export async function inlineDecisionsFromDb(
 
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(
   base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
@@ -979,14 +986,28 @@ export async function inlineRequirementsFromDb(
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ milestoneId, sliceId });
+      let requirements = queryRequirements({ milestoneId, sliceId });
+      let broadenedScope = false;
+      if (requirements.length === 0 && sliceId) {
+        requirements = queryRequirements({ milestoneId });
+        broadenedScope = true;
+      }
+      if (requirements.length === 0 && milestoneId) {
+        requirements = queryRequirements({ status: "active" });
+        broadenedScope = true;
+      }
       if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
+        // Use compact format for non-full levels, milestone-scoped calls, and
+        // any cascade stage that broadened past the originally requested scope —
+        // a slice-scoped "full" call that fell through to the project-wide
+        // active fallback must not format those rows as full requirements.
+        const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+        const formatted = useCompact
           ? formatRequirementsCompact(requirements)
           : formatRequirementsForPrompt(requirements);
         return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
       }
+      return null;
     }
   } catch (err) {
     logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1442,6 +1463,40 @@ export async function checkNeedsReassessment(
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(
+  base: string,
+  mid: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  let summaryContent = "";
+  try {
+    const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+    if (summaryPath) {
+      summaryContent = (await loadFile(summaryPath)) ?? "";
+    }
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+
 export async function checkNeedsRunUat(
   base: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
 ): Promise<{ sliceId: string; uatType: UatType } | null> {
@@ -1470,7 +1525,8 @@ export async function checkNeedsRunUat(
             if (assessmentContent && hasVerdict(assessmentContent)) continue;
           }
           if (!shouldDispatchUatForContent(uatContent, prefs)) continue;
-          return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+          const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+          return { sliceId: sid, uatType };
         }
         return null;
       }
@@ -1503,7 +1559,8 @@ export async function checkNeedsRunUat(
       if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
     }
     if (!shouldDispatchUatForContent(uatContentFb, prefs)) continue;
-    return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+    const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+    return { sliceId: uatSid, uatType };
   }
   return null;
 }
@@ -3557,15 +3614,30 @@ export async function buildRunUatPrompt(
     null,
     cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget",
   );
+  const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+  const uatType = uatPolicy.effectiveType;
+  const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+    ? [
+      "## Runtime harness override",
+      "",
+      "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+      "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+      "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+      "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+      "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+      "",
+    ].join("\n")
+    : "";
   const inlinedContext = prependContextModeToBlock(
     "run-uat",
     base,
-    cappedInlinedContext,
+    runtimeHarnessOverride
+      ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+      : cappedInlinedContext,
   );
   emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-  const uatType = resolveEffectiveUatType(uatContent);
   const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
 
   return loadPrompt("run-uat", {
@@ -3850,18 +3922,22 @@ export async function buildReactiveExecutePrompt(
   const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
 
-  const prompt = loadPrompt("reactive-execute", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
-    readyTaskCount: String(readyTaskIds.length),
-    readyTaskList: readyTaskListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    inlinedTemplates,
-  });
+  const prompt = prependContextModeToBlock(
+    "reactive-execute",
+    base,
+    loadPrompt("reactive-execute", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      graphContext,
+      readyTaskCount: String(readyTaskIds.length),
+      readyTaskList: readyTaskListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+      inlinedTemplates,
+    }),
+  );
   emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
   return prompt;
 }
@@ -4040,17 +4116,21 @@ export async function buildGateEvaluatePrompt(
     ].join("\n"));
   }
 
-  return loadPrompt("gate-evaluate", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
-    gateCount: String(pending.length),
-    gateList: gateListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-  });
+  return prependContextModeToBlock(
+    "gate-evaluate",
+    base,
+    loadPrompt("gate-evaluate", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      slicePlanContent: planContent,
+      gateCount: String(pending.length),
+      gateList: gateListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    }),
+  );
 }
 
 export async function buildRewriteDocsPrompt(

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

@@ -28,6 +28,7 @@ import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-ide
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
 import {
@@ -994,12 +995,14 @@ export async function bootstrapAutoSession(
   // phase-specific planning model for a discuss turn (#2829).
   //
   // Precedence:
-  // 1) Explicit session override via /gsd model (this session)
-  // 2) Current session model from settings/session restore (if provider ready)
-  // 3) GSD model preferences from PREFERENCES.md (validated against live auth)
+  // 1) Explicit session override via /gsd model or /gsd auto --model (this session)
+  // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
+  // 3) Current session model from settings/session restore (if provider ready)
   //
-  // This preserves #3517 defaults while honoring explicit runtime model
-  // selection for subsequent /gsd runs in the same session.
+  // PREFERENCES.md wins over the ambient session default (#3517) so /gsd auto
+  // does not stick on claude-code/claude-sonnet-4-6 when the user configured
+  // models via /gsd workflow-preferences or PREFERENCES.md. Custom providers
+  // still skip PREFERENCES.md entirely (#4122).
   //
   // Exception (#4122): when the session provider is a custom provider declared
   // in ~/.gsd/agent/models.json (Ollama, vLLM, OpenAI-compatible proxy, etc.),
@@ -1011,7 +1014,7 @@ export async function bootstrapAutoSession(
   const sessionProviderIsCustom = isCustomProvider(ctx.model?.provider);
   const preferredModel = sessionProviderIsCustom
     ? null
-    : resolveDefaultSessionModel(ctx.model?.provider);
+    : resolveDefaultSessionModel(ctx.model?.provider, base);
   // Validate the preferred model against the live registry + provider auth so
   // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
   // start-model snapshot. Without this, every subsequent unit would try to
@@ -1041,8 +1044,8 @@ export async function bootstrapAutoSession(
     : null;
   const startThinkingSnapshot = pi.getThinkingLevel();
   const startModelSnapshot = manualSessionOverride
-    ?? currentSessionModel
     ?? validatedPreferredModel
+    ?? currentSessionModel
     ?? null;
 
   try {
@@ -1643,14 +1646,9 @@ export async function bootstrapAutoSession(
             `Cannot enter milestone ${s.currentMilestoneId}: lease is held by another worker.`,
             "error",
           );
-        } else if (enterResult.reason === "creation-failed") {
-          ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: worktree/branch creation failed. Isolation is degraded.`,
-            "error",
-          );
-        } else if (enterResult.reason === "isolation-degraded") {
+        } else if (enterResult.reason === "creation-failed" || enterResult.reason === "isolation-degraded") {
           ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: isolation is degraded from a prior worktree failure. Close processes locking the worktree and retry, or run /gsd doctor fix.`,
+            milestoneEntryBlockedGuidance(s.currentMilestoneId, enterResult.reason),
             "error",
           );
         } else if (enterResult.reason === "invalid-milestone-id") {

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

@@ -33,6 +33,24 @@ export interface UnitActivitySnapshot {
   assistantMessages: number;
 }
 
+export interface AutoUnitCloseoutRequest {
+  ctx: ExtensionContext;
+  basePath: string;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  opts?: CloseoutOptions;
+}
+
+export interface AutoUnitCloseoutResult {
+  activityFile?: string;
+  gitTransactionRecorded: boolean;
+}
+
+type GitTransactionCloseoutOptions =
+  Required<Pick<CloseoutOptions, "traceId" | "turnId" | "gitAction" | "gitStatus">>
+  & Pick<CloseoutOptions, "gitPush" | "gitError">;
+
 export const GHOST_COMPLETION_MAX_ELAPSED_MS = 500;
 
 export function snapshotUnitActivity(
@@ -76,25 +94,27 @@ export function isSuspiciousGhostCompletion(
 }
 
 /**
- * Snapshot metrics, save activity log, and fire-and-forget memory extraction
- * for a completed unit. Returns the activity log file path (if any).
+ * Snapshot metrics, save activity log, extract memories, and record the git
+ * transaction for a completed auto-mode unit.
  */
-export async function closeoutUnit(
-  ctx: ExtensionContext,
-  basePath: string,
-  unitType: string,
-  unitId: string,
-  startedAt: number,
-  opts?: CloseoutOptions,
-): Promise<string | undefined> {
-  const modelId = ctx.model?.id ?? "unknown";
-  snapshotUnitMetrics(ctx, unitType, unitId, startedAt, modelId, opts);
-  const activityFile = saveActivityLog(ctx, basePath, unitType, unitId);
+export async function closeoutAutoUnit(
+  request: AutoUnitCloseoutRequest,
+): Promise<AutoUnitCloseoutResult> {
+  const modelId = request.ctx.model?.id ?? "unknown";
+  snapshotUnitMetrics(
+    request.ctx,
+    request.unitType,
+    request.unitId,
+    request.startedAt,
+    modelId,
+    request.opts,
+  );
+  const activityFile = saveActivityLog(request.ctx, request.basePath, request.unitType, request.unitId);
 
   if (activityFile) {
     try {
-      const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import('./memory-extractor.js');
-      const llmCallFn = buildMemoryLLMCall(ctx);
+      const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import("./memory-extractor.js");
+      const llmCallFn = buildMemoryLLMCall(request.ctx);
       if (llmCallFn) {
         // Awaited: a fire-and-forget here lets memory-extractor writes land in
         // .gsd/ after closeoutUnit returns but before the milestone merge
@@ -103,11 +123,11 @@ export async function closeoutUnit(
         // bounded by the extractor's LLM call, which is the acceptable price
         // for not racing the merge boundary.
         try {
-          await extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn);
+          await extractMemoriesFromUnit(activityFile, request.unitType, request.unitId, llmCallFn);
         } catch (err) {
           logWarning(
             "engine",
-            `memory extraction failed for ${unitType}/${unitId}: ${(err as Error).message}`,
+            `memory extraction failed for ${request.unitType}/${request.unitId}: ${(err as Error).message}`,
           );
         }
       }
@@ -116,23 +136,58 @@ export async function closeoutUnit(
     }
   }
 
-  if (opts?.traceId && opts.turnId && opts.gitAction && opts.gitStatus) {
+  const gitTransaction = resolveGitTransactionOptions(request.opts);
+
+  if (gitTransaction) {
     writeTurnGitTransaction({
-      basePath,
-      traceId: opts.traceId,
-      turnId: opts.turnId,
-      unitType,
-      unitId,
+      basePath: request.basePath,
+      traceId: gitTransaction.traceId,
+      turnId: gitTransaction.turnId,
+      unitType: request.unitType,
+      unitId: request.unitId,
       stage: "record",
-      action: opts.gitAction,
-      push: opts.gitPush === true,
-      status: opts.gitStatus,
-      error: opts.gitError,
+      action: gitTransaction.gitAction,
+      push: gitTransaction.gitPush === true,
+      status: gitTransaction.gitStatus,
+      error: gitTransaction.gitError,
       metadata: {
         activityFile,
       },
     });
   }
 
-  return activityFile ?? undefined;
+  return {
+    ...(activityFile ? { activityFile } : {}),
+    gitTransactionRecorded: Boolean(gitTransaction),
+  };
+}
+
+function resolveGitTransactionOptions(
+  opts: CloseoutOptions | undefined,
+): GitTransactionCloseoutOptions | null {
+  if (!opts?.traceId || !opts.turnId || !opts.gitAction || !opts.gitStatus) return null;
+  return {
+    traceId: opts.traceId,
+    turnId: opts.turnId,
+    gitAction: opts.gitAction,
+    gitStatus: opts.gitStatus,
+    gitPush: opts.gitPush,
+    gitError: opts.gitError,
+  };
+}
+
+/**
+ * Compatibility wrapper for existing auto-loop callers. New code should prefer
+ * closeoutAutoUnit so the closeout request and result stay explicit.
+ */
+export async function closeoutUnit(
+  ctx: ExtensionContext,
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  opts?: CloseoutOptions,
+): Promise<string | undefined> {
+  const result = await closeoutAutoUnit({ ctx, basePath, unitType, unitId, startedAt, opts });
+  return result.activityFile;
 }

package/src/resources/extensions/gsd/auto-unit-tool-scope.ts

@@ -5,10 +5,10 @@ import {
 } from "./unit-tool-contracts.js";
 import {
   WORKFLOW_TOOL_ALIAS_PAIRS,
-  canonicalWorkflowSurfaceToolName,
   isWorkflowSurfaceAliasTool,
   stripMcpToolPrefix,
 } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   AUTO_UNIT_SCOPED_TOOLS,
@@ -51,9 +51,9 @@ type AutoUnitToolScopeResult = {
   displayReason?: string;
 };
 
-export function canonicalWorkflowToolName(toolName: string): string {
-  return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing scope importers.
+export { canonicalWorkflowToolName };
 
 export function isWorkflowAliasTool(toolName: string): boolean {
   return isWorkflowSurfaceAliasTool(toolName);