gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -22,11 +22,51 @@ import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
+/**
+ * Historical static ceiling for the preamble cap. Kept as an upper bound even
+ * after context-window-aware sizing so large-window users don't suddenly see
+ * 10× looser caps than before. Small-window users get a tighter cap derived
+ * from their configured executor window.
+ */
 const MAX_PREAMBLE_CHARS = 30_000;
+/**
+ * Resolve prompt budgets from the configured executor context window.
+ *
+ * The prompt builders here don't have access to the runtime model registry
+ * (they're called from many non-ctx sites), so `resolveExecutorContextWindow`
+ * is fed the user-configurable `context_window_override` preference as the
+ * `sessionContextWindow` fallback. That preference exists specifically to
+ * cover small-window local models (e.g. 32K lemonade/llama.cpp servers) whose
+ * n_ctx is not discoverable through the model registry. Issue #4435.
+ */
+function resolvePromptBudgets() {
+    try {
+        const prefs = loadEffectiveGSDPreferences();
+        const sessionWindow = prefs?.preferences.context_window_override;
+        const windowTokens = resolveExecutorContextWindow(undefined, prefs?.preferences, sessionWindow);
+        return computeBudgets(windowTokens);
+    }
+    catch (e) {
+        logWarning("prompt", `resolvePromptBudgets failed: ${e.message}`);
+        return computeBudgets(200_000);
+    }
+}
+/**
+ * Character budget for dependency/prior slice summaries injected into dispatch
+ * prompts. Scales with the executor's configured context window (issue #4435).
+ */
+function resolveSummaryBudgetChars() {
+    return resolvePromptBudgets().summaryBudgetChars;
+}
 function capPreamble(preamble) {
-    if (preamble.length <= MAX_PREAMBLE_CHARS)
+    // Cap inlined context at min(historical 30K ceiling, scaled inline budget).
+    // The ceiling preserves pre-fix behavior for large-window users; the scaled
+    // budget tightens the cap for small-window users whose true safe limit is
+    // below 30K. `computeBudgets` allocates 40% of total chars to inline context.
+    const budget = Math.min(MAX_PREAMBLE_CHARS, resolvePromptBudgets().inlineContextBudgetChars);
+    if (preamble.length <= budget)
         return preamble;
-    return truncateAtSectionBoundary(preamble, MAX_PREAMBLE_CHARS).content;
+    return truncateAtSectionBoundary(preamble, budget).content;
 }
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 /**
@@ -872,13 +912,13 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
  * as a seed when present. The discussion agent interviews the user, writes
  * a full CONTEXT.md, and the phase transitions to pre-planning automatically.
  */
-export async function buildDiscussMilestonePrompt(mid, midTitle, base) {
+export async function buildDiscussMilestonePrompt(mid, midTitle, base, structuredQuestionsAvailable = "false") {
     const discussTemplates = inlineTemplate("context", "Context");
     const basePrompt = loadPrompt("guided-discuss-milestone", {
         milestoneId: mid,
         milestoneTitle: midTitle,
         inlinedTemplates: discussTemplates,
-        structuredQuestionsAvailable: "false",
+        structuredQuestionsAvailable,
         commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
         fastPathInstruction: "",
     });
@@ -1046,7 +1086,7 @@ export async function buildResearchSlicePrompt(mid, _midTitle, sid, sTitle, base
     if (graphBlockRS)
         inlined.push(graphBlockRS);
     inlined.push(inlineTemplate("research", "Research"));
-    const depContent = await inlineDependencySummaries(mid, sid, base);
+    const depContent = await inlineDependencySummaries(mid, sid, base, resolveSummaryBudgetChars());
     const activeOverrides = await loadActiveOverrides(base);
     const overridesInline = formatOverridesSection(activeOverrides);
     if (overridesInline)
@@ -1073,26 +1113,35 @@ export async function buildResearchSlicePrompt(mid, _midTitle, sid, sTitle, base
         ...buildSkillDiscoveryVars(),
     });
 }
-export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, level) {
-    const inlineLevel = level ?? resolveInlineLevel();
+/**
+ * Shared assembly for plan-slice and refine-slice prompts. Both builders need
+ * the same inlined context (roadmap excerpt, slice context, research, decisions,
+ * requirements, knowledge, graph subgraph, templates, dependency summaries,
+ * overrides). Extracted to prevent drift between the two sites.
+ *
+ * `prependBlocks` are pushed onto the start of the inlined array BEFORE any
+ * shared content, so callers can add unit-specific headers (e.g., the refine
+ * sketch-scope constraint).
+ */
+async function renderSlicePrompt(options) {
+    const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {} } = options;
     const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
     const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
     const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
     const researchRel = relSliceFile(base, mid, sid, "RESEARCH");
     const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
     const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
-    const inlined = [];
-    // Inject phase handoff anchor from research phase (if available)
+    const inlined = [...prependBlocks];
+    // Phase handoff anchor from research phase (if available)
     const researchSliceAnchor = readPhaseAnchor(base, mid, "research-slice");
     if (researchSliceAnchor)
         inlined.push(formatAnchorForPrompt(researchSliceAnchor));
-    // Use roadmap excerpt instead of full roadmap for context reduction
-    const roadmapExcerptPS = await inlineRoadmapExcerpt(base, mid, sid);
-    if (roadmapExcerptPS) {
-        inlined.push(roadmapExcerptPS);
+    // Roadmap excerpt with full-roadmap fallback
+    const roadmapExcerpt = await inlineRoadmapExcerpt(base, mid, sid);
+    if (roadmapExcerpt) {
+        inlined.push(roadmapExcerpt);
     }
     else {
-        // Fall back to full roadmap if excerpt fails
         inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
     }
     const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
@@ -1101,40 +1150,34 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
     const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
     if (researchInline)
         inlined.push(researchInline);
-    if (inlineLevel !== "minimal") {
-        // Derive scope from slice title for decision filtering (R005)
-        const derivedScopePS = deriveSliceScope(sTitle);
-        const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScopePS, inlineLevel);
+    if (level !== "minimal") {
+        const derivedScope = deriveSliceScope(sTitle);
+        const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScope, level);
         if (decisionsInline)
             inlined.push(decisionsInline);
-        const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel);
+        const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, level);
         if (requirementsInline)
             inlined.push(requirementsInline);
     }
-    // Use scoped knowledge based on slice title keywords
-    const keywordsPS = extractKeywords(sTitle);
-    const knowledgeInlinePS = await inlineKnowledgeScoped(base, keywordsPS);
-    if (knowledgeInlinePS)
-        inlined.push(knowledgeInlinePS);
-    // Knowledge graph: subgraph for this slice (graceful — skipped if no graph.json)
-    const graphBlockPS = await inlineGraphSubgraph(base, `${sid} ${sTitle}`, { budget: 3000 });
-    if (graphBlockPS)
-        inlined.push(graphBlockPS);
+    const knowledgeInline = await inlineKnowledgeScoped(base, extractKeywords(sTitle));
+    if (knowledgeInline)
+        inlined.push(knowledgeInline);
+    const graphBlock = await inlineGraphSubgraph(base, `${sid} ${sTitle}`, { budget: 3000 });
+    if (graphBlock)
+        inlined.push(graphBlock);
     inlined.push(inlineTemplate("plan", "Slice Plan"));
-    if (inlineLevel === "full") {
+    if (level === "full") {
         inlined.push(inlineTemplate("task-plan", "Task Plan"));
     }
-    const depContent = await inlineDependencySummaries(mid, sid, base);
-    const planActiveOverrides = await loadActiveOverrides(base);
-    const planOverridesInline = formatOverridesSection(planActiveOverrides);
-    if (planOverridesInline)
-        inlined.unshift(planOverridesInline);
+    const depContent = await inlineDependencySummaries(mid, sid, base, resolveSummaryBudgetChars());
+    const overridesInline = formatOverridesSection(await loadActiveOverrides(base));
+    if (overridesInline)
+        inlined.unshift(overridesInline);
     const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
-    // Build executor context constraints from the budget engine
     const executorContextConstraints = formatExecutorConstraints();
     const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
     const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
-    return loadPrompt("plan-slice", {
+    return loadPrompt(promptTemplate, {
         workingDirectory: base,
         milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
         slicePath: relSlicePath(base, mid, sid),
@@ -1153,6 +1196,56 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
             sliceTitle: sTitle,
             extraContext: [inlinedContext, depContent],
         }),
+        ...extraVars,
+    });
+}
+export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, level, options) {
+    const prependBlocks = [];
+    // ADR-011: when the refining-phase dispatch rule gracefully downgrades to
+    // plan-slice (progressive_planning was toggled off mid-milestone), it
+    // forwards the stored sketch_scope as a SOFT hint — context, not a hard
+    // constraint. The planner is free to expand beyond it.
+    if (options?.softScopeHint && options.softScopeHint.trim().length > 0) {
+        prependBlocks.push(`## Prior Sketch Scope (soft hint — non-binding)\n\n${options.softScopeHint.trim()}\n\n` +
+            `This scope was captured during an earlier progressive-planning pass that was later disabled. Treat it as context only — you may plan beyond it if the work genuinely requires more scope. Do NOT treat this as a hard boundary.`);
+    }
+    return renderSlicePrompt({
+        mid, sid, sTitle, base,
+        level: level ?? resolveInlineLevel(),
+        promptTemplate: "plan-slice",
+        prependBlocks,
+    });
+}
+/**
+ * ADR-011 refine-slice: expand a sketch into a full plan using the current
+ * codebase state and prior slice summary. Mechanically similar to plan-slice
+ * but framed as a *transformation* (sketch → full plan) rather than a
+ * blank-sheet planning pass. Reuses inlineDependencySummaries for prior
+ * slice SUMMARY and inlines the stored sketch_scope as a hard constraint.
+ */
+export async function buildRefineSlicePrompt(mid, _midTitle, sid, sTitle, base, level) {
+    // Pull the stored sketch scope from the DB — the hard constraint we plan within.
+    let sketchScope = "";
+    try {
+        const { isDbAvailable, getSlice } = await import("./gsd-db.js");
+        if (isDbAvailable()) {
+            sketchScope = getSlice(mid, sid)?.sketch_scope ?? "";
+        }
+    }
+    catch {
+        sketchScope = "";
+    }
+    const prependBlocks = [];
+    if (sketchScope.trim().length > 0) {
+        prependBlocks.push(`## Sketch Scope (hard constraint)\n\n${sketchScope.trim()}\n\n` +
+            `Treat this as the authoritative boundary for the slice. Do not plan work outside this scope; if the scope is too narrow, surface it as a deviation rather than expanding silently.`);
+    }
+    return renderSlicePrompt({
+        mid, sid, sTitle, base,
+        level: level ?? resolveInlineLevel(),
+        promptTemplate: "refine-slice",
+        prependBlocks,
+        extraVars: { sketchScope },
     });
 }
 export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, level) {
@@ -1233,7 +1326,28 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const runtimeContext = runtimeContent
         ? `### Runtime Context\nSource: \`.gsd/RUNTIME.md\`\n\n${runtimeContent.trim()}`
         : "";
-    const phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
+    let phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
+    // ADR-011 Phase 2: inject any resolved-but-unapplied escalation override
+    // into this task's prompt. Claim is atomic via DB UPDATE WHERE IS NULL, so
+    // if a parallel build already injected it, we skip. Feature-gated by
+    // phases.mid_execution_escalation. Prepended to phaseAnchorSection so it
+    // appears near the top of the prompt above planning anchors.
+    if (prefs?.preferences?.phases?.mid_execution_escalation === true) {
+        try {
+            const { claimOverrideForInjection } = await import("./escalation.js");
+            const claimed = claimOverrideForInjection(base, mid, sid);
+            if (claimed) {
+                const block = claimed.injectionBlock + "\n\n---\n\n";
+                phaseAnchorSection = phaseAnchorSection
+                    ? `${block}${phaseAnchorSection}`
+                    : block;
+            }
+        }
+        catch (escalationErr) {
+            // Escalation module unavailable or threw — log and proceed.
+            logWarning("prompt", `escalation override injection failed: ${escalationErr.message}`);
+        }
+    }
     // Task-scoped gates owned by execute-task (Q5/Q6/Q7). Pull only the
     // gates that plan-slice actually seeded for this task — tasks with no
     // external dependencies legitimately skip Q5, tasks with no runtime

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -8,6 +8,7 @@
  */
 import { parseUnitId } from "./unit-id.js";
 import { appendEvent } from "./workflow-events.js";
+import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
 import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGates, updateTaskStatus, updateSliceStatus } from "./gsd-db.js";
@@ -212,6 +213,47 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         }
         return true;
     }
+    // #4414: research-slice parallel-research sentinel. The unitId
+    // `{mid}/parallel-research` is not a real slice — it triggers a single agent
+    // that fans out research across multiple slices. Verify success by checking
+    // that every slice which was "research-ready" in the roadmap now has a
+    // RESEARCH file. Without this, resolveExpectedArtifactPath returns null and
+    // the retry/escalation machinery silently re-dispatches forever.
+    //
+    // NOTE: this predicate mirrors the dispatch rule at
+    // auto-dispatch.ts parallel-research-slices — keep the two in sync.
+    if (unitType === "research-slice" && unitId.endsWith("/parallel-research")) {
+        const { milestone: mid } = parseUnitId(unitId);
+        if (!mid)
+            return false;
+        const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
+        if (!roadmapFile || !existsSync(roadmapFile)) {
+            logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap missing`);
+            return false;
+        }
+        try {
+            const roadmap = parseLegacyRoadmap(readFileSync(roadmapFile, "utf-8"));
+            const milestoneResearchFile = resolveMilestoneFile(base, mid, "RESEARCH");
+            for (const slice of roadmap.slices) {
+                if (slice.done)
+                    continue;
+                if (milestoneResearchFile && slice.id === "S01")
+                    continue;
+                const depsComplete = (slice.depends ?? []).every((depId) => !!resolveSliceFile(base, mid, depId, "SUMMARY"));
+                if (!depsComplete)
+                    continue;
+                if (!resolveSliceFile(base, mid, slice.id, "RESEARCH")) {
+                    logWarning("recovery", `verify-fail ${unitType} ${unitId}: slice ${slice.id} missing RESEARCH`);
+                    return false;
+                }
+            }
+            return true;
+        }
+        catch (err) {
+            logWarning("recovery", `parallel-research verification failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
     const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
     // For unit types with no verifiable artifact (null path), the parent directory
     // is missing on disk — treat as stale completion state so the key gets evicted (#313).
@@ -405,6 +447,13 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
         `Review and replace this file before relying on downstream artifacts.`,
     ].join("\n");
     writeFileSync(absPath, content, "utf-8");
+    // #4414: Clear caches so subsequent dispatch guards (e.g.
+    // resolveMilestoneFile) see the placeholder file. Without this, the
+    // cached directory listing is stale and the dispatch rule re-fires,
+    // producing an infinite loop despite the placeholder being on disk.
+    // Matches the pattern used in verifyExpectedArtifact above.
+    clearPathCache();
+    clearParseCache();
     // Mark the task/slice as complete in the DB so verifyExpectedArtifact passes.
     // Without this, the DB status stays "pending" and the dispatch loop
     // re-derives the same unit indefinitely (#2531, #2653).
@@ -414,6 +463,14 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
         if (unitType === "execute-task" && mid && sid && tid) {
             try {
                 updateTaskStatus(mid, sid, tid, "complete", ts);
+                const planPath = resolveSliceFile(base, mid, sid, "PLAN");
+                if (planPath && existsSync(planPath)) {
+                    const planContent = readFileSync(planPath, "utf-8");
+                    const updatedPlan = planContent.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"), `$1[x] **${tid}:`);
+                    if (updatedPlan !== planContent) {
+                        atomicWriteSync(planPath, updatedPlan);
+                    }
+                }
             }
             catch (e) {
                 logWarning("recovery", `updateTaskStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`);

package/dist/resources/extensions/gsd/auto-start.js

@@ -348,10 +348,11 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Detect survivor milestone branches in both pre-planning and complete phases.
         // In phase=complete, the milestone artifacts exist but finalization (merge,
         // worktree cleanup) was never run — the survivor branch must be merged.
+        // Applies to both worktree and branch isolation modes.
         let hasSurvivorBranch = false;
         if (state.activeMilestone &&
             (state.phase === "pre-planning" || state.phase === "complete") &&
-            shouldUseWorktreeIsolation() &&
+            getIsolationMode() !== "none" &&
             !detectWorktreeName(base) &&
             !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
             const milestoneBranch = `milestone/${state.activeMilestone.id}`;
@@ -547,7 +548,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             return symlinkRe.test(p);
         };
         if (s.currentMilestoneId &&
-            shouldUseWorktreeIsolation() &&
+            getIsolationMode() !== "none" &&
             !detectWorktreeName(base) &&
             !isUnderGsdWorktrees(base)) {
             buildResolver().enterMilestone(s.currentMilestoneId, {
@@ -658,7 +659,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
-            && !(effectiveProvider && isFlatRateProvider(effectiveProvider, buildFlatRateContext(effectiveProvider, ctx, bannerPrefs)));
+            && (routingConfig.allow_flat_rate_providers
+                || !(effectiveProvider && isFlatRateProvider(effectiveProvider, buildFlatRateContext(effectiveProvider, ctx, bannerPrefs))));
         // The actual ceiling may come from tier_models.heavy, not the start model.
         const effectiveCeiling = (routingConfig.enabled && routingConfig.tier_models?.heavy)
             ? routingConfig.tier_models.heavy

package/dist/resources/extensions/gsd/auto-verification.js

@@ -5,9 +5,9 @@
  * dependency audits, handles auto-fix retry logic, and writes
  * verification evidence JSON.
  *
- * Extracted from handleAgentEnd() in auto.ts. Returns a sentinel
- * value instead of calling return/pauseAuto directly — the caller
- * checks the result and handles control flow.
+ * Extracted from the pre-loop agent_end handler in auto.ts. Returns a
+ * sentinel value instead of calling return/pauseAuto directly — the
+ * caller checks the result and handles control flow.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolveSlicePath, resolveMilestoneFile } from "./paths.js";

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -20,7 +20,7 @@ import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } fr
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, } from "./native-git-bridge.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, } from "./native-git-bridge.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
@@ -792,9 +792,63 @@ export function runWorktreePostCreateHook(sourceDir, worktreeDir, hookPath) {
     }
 }
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
+/** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
 export function autoWorktreeBranch(milestoneId) {
     return `milestone/${milestoneId}`;
 }
+// ─── Branch-mode Entry ─────────────────────────────────────────────────────
+/**
+ * Enter branch isolation mode for a milestone.
+ *
+ * Creates `milestone/<MID>` from the integration branch (if it doesn't
+ * exist yet) and checks out to it.  No worktree directory is created — the
+ * project root is the working copy; only HEAD changes.
+ *
+ * Uses the same 3-tier integration-branch fallback as createAutoWorktree:
+ *   1. META.json recorded integration branch
+ *   2. git.main_branch preference
+ *   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+ */
+export function enterBranchModeForMilestone(basePath, milestoneId) {
+    const branch = autoWorktreeBranch(milestoneId);
+    const branchExists = nativeBranchExists(basePath, branch);
+    if (!branchExists) {
+        // Create the milestone branch from the integration branch start-point.
+        const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
+        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        // Validate main_branch preference exists in the repo before using it —
+        // a stale preference (e.g. "master" when repo uses "main") would cause
+        // nativeBranchForceReset to fail with a bad start-point reference.
+        const validatedPrefBranch = gitPrefs?.main_branch &&
+            typeof gitPrefs.main_branch === "string" &&
+            gitPrefs.main_branch.length > 0 &&
+            nativeBranchExists(basePath, gitPrefs.main_branch)
+            ? gitPrefs.main_branch
+            : undefined;
+        const startPoint = integrationBranch ??
+            validatedPrefBranch ??
+            nativeDetectMainBranch(basePath);
+        // nativeBranchForceReset creates (or resets) branch at startPoint,
+        // then checkout switches HEAD to it.
+        nativeBranchForceReset(basePath, branch, startPoint);
+        debugLog("auto-worktree", {
+            action: "enterBranchMode",
+            milestoneId,
+            branch,
+            startPoint,
+            created: true,
+        });
+    }
+    else {
+        debugLog("auto-worktree", {
+            action: "enterBranchMode",
+            milestoneId,
+            branch,
+            reused: true,
+        });
+    }
+    nativeCheckoutBranch(basePath, branch);
+}
 // ─── Public API ────────────────────────────────────────────────────────────
 /**
  * Create a new auto-worktree for a milestone, chdir into it, and store

package/dist/resources/extensions/gsd/auto.js

@@ -45,8 +45,9 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
+import { createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
+import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import { reconcileMergeState, } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
@@ -64,7 +65,7 @@ import { runPostUnitVerification } from "./auto-verification.js";
 import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
@@ -142,6 +143,7 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
         debugLog("auto-start-failed", { error: message });
     });
 }
+/** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
     if (prefs?.isolation === "worktree")
@@ -185,6 +187,26 @@ function deregisterSigtermHandler() {
     _deregisterSigtermHandler(s.sigtermHandler);
     s.sigtermHandler = null;
 }
+/**
+ * Wrapper: start background command polling for the configured remote channel
+ * (currently Telegram only). Stores the cleanup function on the session so
+ * every exit path can stop the interval via stopCommandPolling().
+ * No-op when no remote channel is configured.
+ */
+function startAutoCommandPolling(basePath) {
+    if (!isRemoteConfigured())
+        return;
+    // Clear any existing interval before starting a new one (e.g. resume path).
+    stopAutoCommandPolling();
+    s.commandPollingCleanup = _startCommandPolling(basePath);
+}
+/** Wrapper: stop background command polling and clear the stored cleanup. */
+function stopAutoCommandPolling() {
+    if (s.commandPollingCleanup) {
+        s.commandPollingCleanup();
+        s.commandPollingCleanup = null;
+    }
+}
 export function getAutoDashboardData() {
     const ledger = getLedger();
     const totals = ledger ? getProjectTotals(ledger.units) : null;
@@ -248,6 +270,14 @@ export function getActiveRunDir() {
 export function getAutoModeStartModel() {
     return s.autoModeStartModel;
 }
+/**
+ * Update the dashboard-facing dispatched model label.
+ * Used when runtime recovery switches models mid-unit (e.g. provider fallback)
+ * so the AUTO box reflects the active model immediately.
+ */
+export function setCurrentDispatchedModelId(model) {
+    s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
+}
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId, toolName) {
     _markToolStart(toolCallId, s.active, toolName);
@@ -392,6 +422,7 @@ function handleLostSessionLock(ctx, lockStatus) {
     s.paused = false;
     deactivateGSD();
     clearUnitTimeout();
+    stopAutoCommandPolling();
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     deregisterSigtermHandler();
@@ -427,6 +458,7 @@ function cleanupAfterLoopExit(ctx) {
     s.active = false;
     deactivateGSD();
     clearUnitTimeout();
+    stopAutoCommandPolling();
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     // Clear crash lock and release session lock so the next `/gsd next` does
@@ -471,6 +503,7 @@ export async function stopAuto(ctx, pi, reason) {
         // ── Step 1: Timers and locks ──
         try {
             clearUnitTimeout();
+            stopAutoCommandPolling();
             if (lockBase())
                 clearLock(lockBase());
             if (lockBase())
@@ -724,6 +757,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     if (!s.active)
         return;
     clearUnitTimeout();
+    stopAutoCommandPolling();
     // Flush queued follow-up messages (#3512).
     // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
     // extra LLM turns after pause. Flush them the same way run-unit.ts does.
@@ -814,6 +848,7 @@ function buildResolverDeps() {
         teardownAutoWorktree,
         createAutoWorktree,
         enterAutoWorktree,
+        enterBranchModeForMilestone,
         getAutoWorktreePath,
         autoCommitCurrentBranch,
         getCurrentBranch,
@@ -941,6 +976,11 @@ function buildLoopDeps() {
         emitJournalEvent: (entry) => _emitJournalEvent(s.basePath, entry),
     };
 }
+/**
+ * Start auto-mode. Handles both fresh-start and resume paths, sets up session
+ * state, enters the milestone worktree or branch, and dispatches the first unit.
+ * No-ops if auto-mode is already active.
+ */
 export async function startAuto(ctx, pi, base, verboseMode, options) {
     if (s.active) {
         debugLog("startAuto", { phase: "already-active", skipping: true });
@@ -1112,9 +1152,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             const level = to === "red" ? "error" : to === "yellow" ? "warning" : "info";
             ctx.ui.notify(summary, level);
         });
-        // ── Auto-worktree: re-enter worktree on resume ──
+        // ── Auto-worktree / branch-mode: re-enter on resume ──
         if (s.currentMilestoneId &&
-            shouldUseWorktreeIsolation() &&
+            getIsolationMode() !== "none" &&
             s.originalBasePath &&
             !isInAutoWorktree(s.basePath) &&
             !detectWorktreeName(s.basePath) &&
@@ -1179,12 +1219,14 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
         captureProjectRootEnv(s.originalBasePath || s.basePath);
+        startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
             ctx,
             pi,
             s,
             deps: buildLoopDeps(),
-            runLegacyLoop: autoLoop,
+            runKernelLoop: runUokKernelLoop,
+            runLegacyLoop: runLegacyAutoLoop,
         });
         cleanupAfterLoopExit(ctx);
         return;
@@ -1208,35 +1250,18 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+    startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
     await runAutoLoopWithUok({
         ctx,
         pi,
         s,
         deps: buildLoopDeps(),
-        runLegacyLoop: autoLoop,
+        runKernelLoop: runUokKernelLoop,
+        runLegacyLoop: runLegacyAutoLoop,
     });
     cleanupAfterLoopExit(ctx);
 }
-// ─── Agent End Handler ────────────────────────────────────────────────────────
-/**
- * Deprecated thin wrapper — kept as export for backward compatibility.
- * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
- * which is called directly from index.ts. The autoLoop() while loop handles all
- * post-unit processing (verification, hooks, dispatch) that this function used to do.
- *
- * If called by straggler code, it simply resolves the pending promise so the loop
- * can continue.
- */
-export async function handleAgentEnd(ctx, pi) {
-    if (!s.active || !s.cmdCtx) {
-        // Even when inactive, resolve any pending promise so the loop is unblocked.
-        resolveAgentEndCancelled();
-        return;
-    }
-    clearUnitTimeout();
-    resolveAgentEnd({ messages: [] });
-}
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
 export { describeNextUnit } from "./auto-dashboard.js";
 /** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */