@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

package/src/resources/extensions/gsd/guided-flow.ts

@@ -42,7 +42,7 @@ import { gsdHome } from "./gsd-home.js";
 import {
   gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
-  relMilestoneFile, relSliceFile,
+  relMilestoneFile, relSliceFile, clearPathCache,
 } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
@@ -51,7 +51,7 @@ import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativ
 import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { getIsolationMode, loadEffectiveGSDPreferences } from "./preferences.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
@@ -94,13 +94,14 @@ import {
 import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
-import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
+import { getUnitWorkflowDispatchReadinessErrorForModel } from "./tool-contract.js";
 import {
   runPreparation,
   formatCodebaseBrief,
   formatPriorContextBrief,
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { countPlanMilestoneRoadmapSlices } from "./artifact-verification.js";
 import type { MilestoneScope } from "./workspace.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import {
@@ -164,7 +165,7 @@ export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
 // The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
-// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+// state.ts remain the default for non-scope-specific units.
 
 /**
  * Scope-based overload of verifyExpectedArtifact.
@@ -176,9 +177,47 @@ export function verifyExpectedArtifactForScope(
   unitType: string,
   unitId: string,
 ): boolean {
+  if (
+    unitId === scope.milestoneId &&
+    (unitType === "discuss-milestone" || unitType === "plan-milestone")
+  ) {
+    // Layout-aware scope paths use resolveMilestoneFile; clear stale dir listings
+    // primed before discuss/plan wrote CONTEXT.md or ROADMAP.md (see checkAutoStartAfterDiscuss).
+    clearPathCache();
+  }
+  if (
+    unitId === scope.milestoneId &&
+    unitType === "discuss-milestone"
+  ) {
+    const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+    return path ? existsSync(path) : false;
+  }
+  if (unitId === scope.milestoneId && unitType === "plan-milestone") {
+    const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+    return verifyScopedPlanMilestoneArtifact(path, unitType, unitId);
+  }
   return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
 }
 
+function verifyScopedPlanMilestoneArtifact(
+  path: string | null,
+  unitType: string,
+  unitId: string,
+): boolean {
+  if (!path || !existsSync(path)) return false;
+  try {
+    const roadmapContent = readFileSync(path, "utf-8");
+    if (countPlanMilestoneRoadmapSlices(roadmapContent) === 0) {
+      logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${path}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
 /**
  * Scope-based overload of resolveExpectedArtifactPath.
  * Returns the canonical absolute path (or null) using the scope's projectRoot.
@@ -188,6 +227,10 @@ export function resolveExpectedArtifactPathForScope(
   unitType: string,
   unitId: string,
 ): string | null {
+  if (unitId === scope.milestoneId) {
+    if (unitType === "discuss-milestone") return scope.contextFile();
+    if (unitType === "plan-milestone") return scope.roadmapFile();
+  }
   return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 
@@ -570,7 +613,7 @@ interface DispatchWorkflowOptions {
   deps?: {
     loadPreferences?: typeof loadEffectiveGSDPreferences;
     selectModel?: typeof selectAndApplyModel;
-    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessError;
+    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessErrorForModel;
   };
 }
 
@@ -687,7 +730,7 @@ async function dispatchWorkflow(
   const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
   const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
   const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
-    ?? getUnitWorkflowDispatchReadinessError;
+    ?? getUnitWorkflowDispatchReadinessErrorForModel;
 
   // Route through the dynamic routing pipeline (complexity classification,
   // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
@@ -707,16 +750,12 @@ async function dispatchWorkflow(
     }
 
     const compatibilityError = getDispatchReadinessError({
-      provider: result.appliedModel?.provider ?? ctx.model?.provider,
+      model: result.appliedModel,
+      fallbackModel: ctx.model,
+      getProviderAuthMode: (provider) => ctx.modelRegistry.getProviderAuthMode(provider),
       projectRoot,
       surface: "guided flow",
       unitType,
-      authMode: result.appliedModel?.provider
-        ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
-        : ctx.model?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-          : undefined,
-      baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
       // Guided flow starts the MCP workflow server as part of dispatch, so the
       // parent session's activeTools doesn't include MCP tools yet. The MCP
       // launch config check (detectWorkflowMcpLaunchConfig) is the right gate

package/src/resources/extensions/gsd/key-manager.ts

@@ -43,6 +43,7 @@ export const PROVIDER_REGISTRY: ProviderInfo[] = [
   // must be in the canonical registry so all consumers see the same catalog.
   // See: https://github.com/open-gsd/gsd-pi/issues/4541
   { id: "claude-code",      label: "Claude Code CLI",         category: "llm",                                   authMode: "externalCli" },
+  { id: "cursor-agent",     label: "Cursor Agent",            category: "llm", envVar: "CURSOR_API_KEY",         authMode: "externalCli" },
   { id: "openai",           label: "OpenAI",                  category: "llm", envVar: "OPENAI_API_KEY",         prefixes: ["sk-"],     dashboardUrl: "platform.openai.com/api-keys" },
   { id: "github-copilot",   label: "GitHub Copilot",          category: "llm", envVar: "GITHUB_TOKEN",           authMode: "browserOAuth" },
   { id: "openai-codex",     label: "ChatGPT Plus/Pro (Codex)",category: "llm",                                   authMode: "browserOAuth" },

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -20,6 +20,7 @@ import {
   getSliceScopedArtifacts,
   getMilestoneSlices,
   getSliceTasks,
+  getTasksBySliceIds,
   getTask,
   getSlice,
   insertArtifact,
@@ -136,6 +137,12 @@ function meaningfulSection(value: string | null | undefined): string {
   return trimmed;
 }
 
+function renderGateFindings(gate: GateRow): string {
+  const findings = gate.findings.trim() || `- **Verdict:** ${gate.verdict}\n- **Rationale:** ${gate.rationale}`;
+  if (gate.verdict !== "flag") return findings;
+  return `> **Warning:** Verdict: flag - concerns recorded below\n\n${findings}`;
+}
+
 function pushIndented(lines: string[], value: string, indent = "  "): void {
   for (const line of value.split("\n")) {
     lines.push(`${indent}${line}`);
@@ -356,7 +363,7 @@ function renderTaskPlanMarkdown(task: TaskRow, taskGates: GateRow[] = []): strin
     if (gate && gate.verdict !== "omitted") {
       lines.push(`## ${label}`);
       lines.push("");
-      lines.push(gate.findings.trim() || `- **Verdict:** ${gate.verdict}\n- **Rationale:** ${gate.rationale}`);
+      lines.push(renderGateFindings(gate));
       lines.push("");
     }
   }
@@ -390,7 +397,7 @@ function renderSlicePlanMarkdown(slice: SliceRow, tasks: TaskRow[], gates: GateR
   if (q3 && q3.verdict !== "omitted") {
     lines.push("## Threat Surface");
     lines.push("");
-    lines.push(q3.findings.trim() || `- **Verdict:** ${q3.verdict}\n- **Rationale:** ${q3.rationale}`);
+    lines.push(renderGateFindings(q3));
     lines.push("");
   }
 
@@ -398,7 +405,7 @@ function renderSlicePlanMarkdown(slice: SliceRow, tasks: TaskRow[], gates: GateR
   if (q4 && q4.verdict !== "omitted") {
     lines.push("## Requirement Impact");
     lines.push("");
-    lines.push(q4.findings.trim() || `- **Verdict:** ${q4.verdict}\n- **Rationale:** ${q4.rationale}`);
+    lines.push(renderGateFindings(q4));
     lines.push("");
   }
 
@@ -876,6 +883,17 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
   const result: RenderAllResult = { rendered: 0, skipped: 0, errors: [] };
   const milestones = getAllMilestones();
 
+  // Pre-fetch slices once per milestone and batch-load all tasks in one query
+  // family, avoiding an N+1 (previously one task query per slice).
+  const slicesByMilestone = new Map<string, SliceRow[]>();
+  const slicePairs: Array<{ milestoneId: string; sliceId: string }> = [];
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    slicesByMilestone.set(milestone.id, slices);
+    for (const slice of slices) slicePairs.push({ milestoneId: milestone.id, sliceId: slice.id });
+  }
+  const tasksBySlice = getTasksBySliceIds(slicePairs);
+
   for (const milestone of milestones) {
     // Render roadmap checkboxes
     try {
@@ -894,8 +912,8 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
       result.errors.push(`milestone artifacts ${milestone.id}: ${(err as Error).message}`);
     }
 
-    // Iterate slices
-    const slices = getMilestoneSlices(milestone.id);
+    // Iterate slices (pre-fetched above)
+    const slices = slicesByMilestone.get(milestone.id) ?? [];
     for (const slice of slices) {
       // Preserve slice-scoped artifacts imported from disk, including real PLAN
       // fallback content when task rows cannot regenerate it.
@@ -931,8 +949,8 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
         );
       }
 
-      // Iterate tasks
-      const tasks = getSliceTasks(milestone.id, slice.id);
+      // Iterate tasks (batched above)
+      const tasks = tasksBySlice.get(`${milestone.id}\0${slice.id}`) ?? [];
       for (const task of tasks) {
         try {
           const ok = await renderTaskSummary(
@@ -1281,9 +1299,21 @@ export async function renderAssessmentFromDb(
   sliceId: string,
   assessmentData: AssessmentData,
 ): Promise<{ assessmentPath: string; content: string }> {
-  // Flat-phase: assessment file lives in the phase dir
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+  // Flat-phase: the assessment file lives in the phase dir, NOT in a slices/SID/
+  // subdir. resolveSlicePath() detects a slices/SID/ dir unconditionally, so a
+  // stray slices/SID/ created by an earlier planning step would send this write
+  // to a hybrid path (wrong dir, flat filename) that verification cannot find.
+  // Guard with the same legacy-base check relSlicePath() uses so flat-phase
+  // milestones always target the phase dir.
+  const mDir = resolveMilestonePath(basePath, milestoneId);
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacyLayout = mDir
+    ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
+    : false;
+  const fallbackDir = join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+  const slicePath = isLegacyLayout
+    ? (resolveSlicePath(basePath, milestoneId, sliceId) ?? fallbackDir)
+    : (mDir ?? fallbackDir);
   const phaseNum = milestoneIdToPhaseNum(milestoneId);
   const planNum = sliceIdToPlanNum(sliceId);
   const absPath = join(slicePath, planFileName(phaseNum, planNum, "ASSESSMENT"));

package/src/resources/extensions/gsd/migrate-external.ts

@@ -9,7 +9,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
-import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js";
+import { externalGsdRoot, externalStateAlreadyExistsForProject, isInsideWorktree } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
@@ -85,6 +85,16 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     }
   }
 
+  // If external state already contains project data, this is not a legacy
+  // migration source. It is likely an already-migrated project whose symlink
+  // was replaced by a real directory, so copying would risk data loss.
+  if (externalStateAlreadyExistsForProject(basePath)) {
+    return {
+      migrated: false,
+      error: "External state already exists for this project; leaving local .gsd directory untouched to avoid overwriting authoritative state",
+    };
+  }
+
   const externalPath = externalGsdRoot(basePath);
   const migratingPath = join(basePath, ".gsd.migrating");
 
@@ -94,12 +104,12 @@ export function migrateToExternalState(basePath: string): MigrationResult {
 
     // Rename .gsd -> .gsd.migrating (atomic lock).
     // On Windows, NTFS may reject rename with EPERM if file descriptors are
-    // open (VS Code watchers, antivirus on-access scan). Fall back to
-    // copy+delete (#1292).
+    // open (VS Code watchers, antivirus on-access scan). WSL/DrvFs can report
+    // the same transient lock as EACCES. Fall back to copy+delete (#1292).
     try {
       renameSync(localGsd, migratingPath);
     } catch (renameErr: any) {
-      if (renameErr?.code === "EPERM" || renameErr?.code === "EBUSY") {
+      if (renameErr?.code === "EPERM" || renameErr?.code === "EBUSY" || renameErr?.code === "EACCES") {
         try {
           cpSync(localGsd, migratingPath, { recursive: true, force: true });
           rmSync(localGsd, { recursive: true, force: true });
@@ -237,7 +247,7 @@ function isLocalGsdExternalStateJunction(basePath: string, localGsd: string): bo
  * Recover from a failed migration (`.gsd.migrating` exists).
  * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist, or removes an
  * orphaned staging directory when `.gsd` is already a verified external state
- * junction with intact current state.
+ * junction, or an intact real directory, with intact current state.
  */
 export function recoverFailedMigration(basePath: string): boolean {
   const localGsd = join(basePath, ".gsd");
@@ -245,8 +255,15 @@ export function recoverFailedMigration(basePath: string): boolean {
 
   if (!existsSync(migratingPath)) return false;
   if (existsSync(localGsd)) {
-    if (!isLocalGsdExternalStateJunction(basePath, localGsd)) return false;
     if (!isCurrentGsdStateIntactForMigratingCleanup(basePath)) return false;
+    if (!isLocalGsdExternalStateJunction(basePath, localGsd)) {
+      try {
+        const stat = lstatSync(localGsd);
+        if (!stat.isDirectory()) return false;
+      } catch {
+        return false;
+      }
+    }
     try {
       rmSync(migratingPath, { recursive: true, force: true });
       return true;

package/src/resources/extensions/gsd/milestone-merge-transaction.ts

@@ -1,6 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Process-level transaction wrapper for milestone merge closeout.
 
+import { mergeMilestoneToMain } from "./auto-worktree-merge.js";
+
 export interface MilestoneMergeTransactionResult {
   pushed: boolean;
   codeFilesChanged: boolean;
@@ -21,14 +23,14 @@ export type MilestoneMergeTransactionRunner = (
 ) => MilestoneMergeTransactionResult;
 
 export interface MilestoneMergeTransactionDeps {
-  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
+  mergeMilestone: MilestoneMergeTransactionRunner;
 }
 
 export function runMilestoneMergeTransaction(
   deps: MilestoneMergeTransactionDeps,
   input: MilestoneMergeTransactionInput,
 ): MilestoneMergeTransactionResult {
-  return deps.mergeMilestoneToMain(
+  return deps.mergeMilestone(
     input.basePath,
     input.milestoneId,
     input.roadmapContent,
@@ -36,12 +38,25 @@ export function runMilestoneMergeTransaction(
 }
 
 export function createMilestoneMergeTransaction(
-  mergeMilestoneToMain: MilestoneMergeTransactionRunner,
+  mergeMilestone: MilestoneMergeTransactionRunner,
 ): MilestoneMergeTransactionRunner {
   return function mergeMilestoneTransaction(basePath, milestoneId, roadmapContent) {
     return runMilestoneMergeTransaction(
-      { mergeMilestoneToMain },
+      { mergeMilestone },
       { basePath, milestoneId, roadmapContent },
     );
   };
 }
+
+/**
+ * Production merge transaction adapter.
+ *
+ * This is the only production construction point that knows the legacy
+ * `auto-worktree.ts` merge primitive. Lifecycle callers depend on the
+ * transaction runner interface, not the legacy implementation module.
+ */
+export function createDefaultMilestoneMergeTransaction(
+  mergeMilestone: MilestoneMergeTransactionRunner = mergeMilestoneToMain,
+): MilestoneMergeTransactionRunner {
+  return createMilestoneMergeTransaction(mergeMilestone);
+}

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
 
-import { isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
 import {
   formatCloseoutProofBlock,
   proveMilestoneCloseout,

package/src/resources/extensions/gsd/model-router.ts

@@ -24,11 +24,10 @@ export interface DynamicRoutingConfig {
   cross_provider?: boolean;        // default: true
   hooks?: boolean;                 // default: true
   /**
-   * Opt into dynamic routing for flat-rate providers (e.g. claude-code,
-   * GitHub Copilot). Default false preserves the #3453 bypass that skips
-   * routing when the subscription makes per-request cost identical.
-   * Enable only when you want per-task model selection across a flat-rate
-   * subscription (e.g. haiku for research, opus for architecture). (#4386)
+   * Override dynamic routing for flat-rate providers (e.g. claude-code,
+   * GitHub Copilot). Omit or set true to honor `dynamic_routing.enabled`;
+   * set false to preserve one-model dispatch when the subscription makes
+   * per-request cost identical.
    */
   allow_flat_rate_providers?: boolean;
 }

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
 import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import {
   mergeMilestoneStandalone,

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -21,7 +21,9 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe } from "./auto-worktree-branch-lifecycle.js";
+import { syncGsdStateToWorktreeByScope } from "./auto-worktree-sync.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";

package/src/resources/extensions/gsd/preferences-diagnostics.ts

@@ -1,8 +1,10 @@
 import type { PreferenceDiagnostic } from "./preferences-types.js";
 import {
+  loadEffectiveGSDPreferences,
   loadGlobalGSDPreferences,
   loadProjectGSDPreferences,
 } from "./preferences.js";
+import { crossAxisPreferenceWarnings } from "./preferences-validation.js";
 
 interface PreferenceNotificationContext {
   ui: {
@@ -30,6 +32,28 @@ export function collectPreferenceDiagnostics(basePath?: string): PreferenceDiagn
     seen.add(signature);
     unique.push(diagnostic);
   }
+
+  const effective = loadEffectiveGSDPreferences(basePath);
+  if (effective) {
+    const existingMessages = new Set(unique.map((diagnostic) => diagnostic.message));
+    for (const message of crossAxisPreferenceWarnings(effective.preferences)) {
+      if (existingMessages.has(message)) continue;
+      const diagnostic: PreferenceDiagnostic = {
+        path: effective.path,
+        scope: effective.scope,
+        severity: "warning",
+        kind: "validation",
+        message,
+        sanitized: true,
+      };
+      const signature = preferenceDiagnosticSignature(diagnostic);
+      if (seen.has(signature)) continue;
+      seen.add(signature);
+      existingMessages.add(message);
+      unique.push(diagnostic);
+    }
+  }
+
   return unique;
 }
 

package/src/resources/extensions/gsd/preferences-models.ts

@@ -99,10 +99,13 @@ export function resolveModelWithFallbacksForUnit(
   basePath?: string,
   availableModelIds?: string[],
   preferredModelId?: string,
+  skipProfileDefaults = false,
 ): ResolvedModelConfig | undefined {
-  const loadOpts = availableModelIds !== undefined || preferredModelId !== undefined
-    ? { availableModelIds, preferredModelId }
-    : undefined;
+  const loadOpts = {
+    ...(availableModelIds !== undefined ? { availableModelIds } : {}),
+    ...(preferredModelId !== undefined ? { preferredModelId } : {}),
+    ...(skipProfileDefaults ? { skipProfileDefaults: true } : {}),
+  };
   const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
   const chain = phaseChainForUnit(unitType);
   if (!chain) return undefined;

package/src/resources/extensions/gsd/preferences-types.ts

@@ -29,6 +29,33 @@ export interface ContextManagementConfig {
   tool_result_max_chars?: number;         // default: 800, range: 200-10000
 }
 
+/**
+ * User-tunable thresholds for the tool-call loop guard (#1198). Keeps the two
+ * guards separately configurable: the identical-args guard (catches real
+ * infinite loops) and the repeated-tool-name cap (catches improvisation loops,
+ * more likely to false-positive on legitimate automation). All fields are
+ * optional; omitted fields fall back to the built-in defaults so existing
+ * installs keep their current behavior. Also overridable via GSD_TOOL_LOOP_*
+ * environment variables.
+ */
+export interface ToolCallLoopGuardConfig {
+  /** Master switch for both guards. Default: true. */
+  enabled?: boolean;
+  /** Identical-args sliding-window guard. */
+  identical_args?: {
+    enabled?: boolean;                    // default: true
+    max_consecutive_calls?: number;       // default: 4, min: 1
+  };
+  /** Per-tool-name cap, independent of args. */
+  repeated_tool?: {
+    enabled?: boolean;                    // default: true
+    default_cap?: number;                 // default: 6, min: 1
+    repeatable_cap?: number;              // default: 15, min: 1
+    /** Additional tool names exempt from the per-tool cap (merged with built-in defaults). */
+    exempt_tools?: string[];
+  };
+}
+
 /**
  * Opt-in tool-output sandboxing for sub-sessions. When enabled, the gsd_exec
  * MCP tool runs scripts in an isolated subprocess and returns only a short
@@ -139,6 +166,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "min_request_interval_ms",
   "stale_commit_threshold_minutes",
   "context_management",
+  "tool_call_loop_guard",
   "experimental",
   "codebase",
   "slice_parallel",
@@ -440,6 +468,8 @@ export interface GSDPreferences {
    */
   context_window_override?: number;
   context_management?: ContextManagementConfig;
+  /** User-tunable tool-call loop guard thresholds (#1198). */
+  tool_call_loop_guard?: ToolCallLoopGuardConfig;
   /**
    * Tool-output sandboxing via gsd_exec. Keeps sub-session context windows
    * clean by running scripts in a subprocess and only surfacing a short