gsd-pi 2.80.0-dev.c5f2443b3 → 2.80.0-dev.e51d2c88c

package/README.md

@@ -259,6 +259,7 @@ Full documentation is in the [`docs/`](./docs/) directory:
 
 - **[Architecture](./docs/dev/architecture.md)** — system design and dispatch pipeline
 - **[CI/CD Pipeline](./docs/dev/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
+- **[E2E Testing](./tests/e2e/README.md)** — real-process CLI/runtime coverage and CI runner expectations
 - **[Pipeline Simplification (ADR-003)](./docs/dev/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 
@@ -361,7 +362,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Context Mode** — Context Mode is enabled by default and gives every auto-mode unit guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; full stdout/stderr is saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads `.gsd/last-snapshot.md` after compaction or resume. Opt out with `context_mode.enabled: false`; tune sandbox timeout/output caps with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, and `context_mode.exec_digest_chars`.
+3. **Context Mode** — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; capped stdout/stderr and metadata are saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads a prior compaction snapshot from `.gsd/last-snapshot.md` when one exists. Opt out with `context_mode.enabled: false` to disable Context Mode guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume`; tune sandbox timeout/output caps and environment forwarding with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, `context_mode.exec_digest_chars`, and `context_mode.exec_env_allowlist`.
 
 4. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
@@ -659,10 +660,11 @@ auto_report: true
 | `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |
 | `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
-| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable `gsd_exec`, exec history guidance, and resume snapshots |
+| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable prompt guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume` |
 | `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |
 | `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
 | `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
+| `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
 | `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-4cdd0ed39f5663d1
+4a20b588f749081c

package/dist/resources/GSD-WORKFLOW.md

@@ -28,7 +28,7 @@ Then do the thing `STATE.md` says to do next.
 ## The Hierarchy
 
 ```
-Milestone  →  a shippable version (4-10 slices)
+Milestone  →  a shippable version (1-10 slices, sized to the work)
   Slice    →  one demoable vertical capability (1-7 tasks)
     Task   →  one context-window-sized unit of work (fits in one session)
 ```
@@ -331,7 +331,7 @@ The **Don't Hand-Roll** and **Common Pitfalls** sections prevent the most expens
 
 **For a milestone (roadmap):**
 1. Read `M###-CONTEXT.md`, `M###-RESEARCH.md`, and `.gsd/DECISIONS.md` if they exist.
-2. Decompose the vision into 4-10 demoable vertical slices.
+2. Decompose the vision into 1-10 demoable vertical slices. Prefer one slice for tiny, single-file, or static work unless the request clearly spans independent capabilities.
 3. Order by risk (high-risk first to validate feasibility early).
 4. Write `M###-ROADMAP.md` with checkboxes, risk levels, dependencies, demo sentences.
 5. **Write the boundary map** — for each slice, specify what it produces (functions, types, interfaces, endpoints) and what it consumes from upstream slices. This forces interface thinking before implementation and enables deterministic verification that slices actually connect.

package/dist/resources/extensions/github-sync/templates.js

@@ -8,6 +8,37 @@
  * for the `gh` CLI body parameters.
  */
 import { buildPrEvidence } from "../gsd/pr-evidence.js";
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Wrap a string in a CommonMark inline-code span, escaping any embedded
+ * backticks by selecting a fence longer than the longest backtick run inside
+ * the input. If the input begins or ends with a backtick, pad with a single
+ * space inside the fence (CommonMark requirement).
+ *
+ * Empty input returns an empty string (no fence) — there is nothing to render
+ * as code, and emitting an empty pair of backticks would produce literal
+ * backticks in GitHub-flavored markdown.
+ */
+export function inlineCode(s) {
+    if (s.length === 0)
+        return "";
+    let longestRun = 0;
+    let currentRun = 0;
+    for (const ch of s) {
+        if (ch === "`") {
+            currentRun++;
+            if (currentRun > longestRun)
+                longestRun = currentRun;
+        }
+        else {
+            currentRun = 0;
+        }
+    }
+    const fence = "`".repeat(longestRun + 1);
+    const needsPad = s.startsWith("`") || s.endsWith("`");
+    const pad = needsPad ? " " : "";
+    return `${fence}${pad}${s}${pad}${fence}`;
+}
 export function formatMilestoneIssueBody(data) {
     const lines = [];
     lines.push(`# ${data.id}: ${data.title}`);
@@ -78,7 +109,7 @@ export function formatTaskIssueBody(data) {
     if (data.files?.length) {
         lines.push("### Files");
         for (const file of data.files) {
-            lines.push(`- \`${file}\``);
+            lines.push(`- ${inlineCode(file)}`);
         }
         lines.push("");
     }
@@ -132,15 +163,14 @@ export function formatSwarmLanePRBody(data) {
     const summaries = [
         [
             "### Swarm lane",
-            `**Lane:** \`${laneLabel}\``,
-            `**Branch:** \`${data.lane.branch}\``,
+            `**Lane:** ${inlineCode(laneLabel)}`,
+            `**Branch:** ${inlineCode(data.lane.branch)}`,
             data.lane.owner ? `**Owner:** ${data.lane.owner}` : "",
-            data.lane.latestCommit ? `**Latest commit:** \`${data.lane.latestCommit}\`` : "",
+            data.lane.latestCommit ? `**Latest commit:** ${inlineCode(data.lane.latestCommit)}` : "",
         ].filter(Boolean).join("\n"),
         `### Impact area\n${data.impactArea}`,
         `### Changed contracts\n${checkedList(data.lane.changedContracts, "No shared contracts changed").join("\n")}`,
         `### Transition risks\n${checkedList(data.transitionRisks, "No transition risks identified").join("\n")}`,
-        data.lane.blockers?.length ? `### Blockers\n${data.lane.blockers.map((blocker) => `- ${blocker}`).join("\n")}` : "",
     ].filter(Boolean);
     return buildPrEvidence({
         milestoneId: laneLabel,
@@ -150,6 +180,7 @@ export function formatSwarmLanePRBody(data) {
         changeType: "refactor",
         linkedIssue: data.linkedIssue ? `Closes #${data.linkedIssue}` : undefined,
         summaries,
+        blockers: data.lane.blockers ?? [],
         testsRun: data.lane.testEvidence,
         rollbackNotes: data.rollbackPlan,
         how: "Generated by GSD GitHub Sync swarm routines from lane evidence.",
@@ -159,7 +190,7 @@ export function formatSwarmReleaseChecklistBody(data) {
     const lines = [];
     lines.push(`# UOK Swarm Release Checklist`);
     lines.push("");
-    lines.push(`**Integration branch:** \`${data.integrationBranch}\``);
+    lines.push(`**Integration branch:** ${inlineCode(data.integrationBranch)}`);
     lines.push("");
     lines.push("## Lane summary");
     lines.push("");
@@ -167,9 +198,9 @@ export function formatSwarmReleaseChecklistBody(data) {
     lines.push("|------|--------|-------|--------|--------|");
     for (const lane of data.lanes) {
         const owner = lane.owner ?? "";
-        const commit = lane.latestCommit ? `\`${lane.latestCommit}\`` : "";
+        const commit = lane.latestCommit ? inlineCode(lane.latestCommit) : "";
         const status = lane.blockers?.length ? "blocked" : "ready";
-        lines.push(`| \`${SWARM_LANE_LABELS[lane.id]}\` | \`${lane.branch}\` | ${owner} | ${commit} | ${status} |`);
+        lines.push(`| ${inlineCode(SWARM_LANE_LABELS[lane.id])} | ${inlineCode(lane.branch)} | ${owner} | ${commit} | ${status} |`);
     }
     lines.push("");
     lines.push("## Required evidence");

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

@@ -25,6 +25,8 @@ import { normalizeRealPath } from "../paths.js";
 import { decideCooldownRecovery, decideDispatchClaim, decideEngineDispatch, decideFinalizeResult, decideInfrastructureError, decideIterationErrorRecovery, decideMemoryPressure, decideModelPolicyBlocked, decideMinRequestInterval, decideWorkflowLoop, formatDispatchExceptionSummary, formatUnhandledDispatchErrorSummary, resolveUnitRequestTimestamp, shouldUseCustomEnginePath, } from "./workflow-kernel.js";
 import { hydrateCustomVerifyRetryCounts, saveCustomVerifyRetryCounts, } from "./custom-verify-retry-store.js";
 import { settleDispatchCompleted, settleDispatchFailed, } from "./workflow-dispatch-ledger.js";
+import { emitOpenUnitEndForUnit } from "../crash-recovery.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { openDispatchClaim } from "./workflow-dispatch-claim.js";
 import { completeWorkflowIteration } from "./workflow-iteration-completion.js";
 import { createWorkflowJournalReporter } from "./workflow-journal-reporter.js";
@@ -133,6 +135,24 @@ async function enforceMinRequestInterval(s, prefs) {
         await new Promise(r => setTimeout(r, decision.waitMs));
     }
 }
+function closeOutCrashedUnit(s, iterData, err) {
+    const summary = formatDispatchExceptionSummary({ error: err });
+    try {
+        emitOpenUnitEndForUnit(s.basePath, iterData.unitType, iterData.unitId, "cancelled", {
+            message: summary,
+            category: "unit-exception",
+            isTransient: false,
+        });
+        writeUnitRuntimeRecord(s.basePath, iterData.unitType, iterData.unitId, s.currentUnit?.startedAt ?? Date.now(), {
+            phase: "crashed",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "unit-exception",
+        });
+    }
+    catch (closeoutErr) {
+        logWarning("dispatch", `unit crash closeout failed: ${closeoutErr instanceof Error ? closeoutErr.message : String(closeoutErr)}`);
+    }
+}
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
  * runUnit → finalize → repeat. Exits when s.active becomes false or a
@@ -268,6 +288,19 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             // ── Blanket try/catch: one bad iteration must not kill the session
             const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
             const uokFlags = resolveUokFlags(prefs);
+            // ── Check sidecar queue before deriveState ──
+            // NOTE: Sidecar dequeue MUST run before validateWorkflowSessionLock so a
+            // queued item is popped (and the `sidecar-dequeue` journal event emitted)
+            // even when the session lock invalidates this iteration. Inverting this
+            // order silently drops queued items on lock-loss. Refs #5308.
+            const sidecarItem = await dequeueSidecarItem({
+                queue: s.sidecarQueue,
+                executionGraphEnabled: uokFlags.executionGraph,
+                scheduleQueue: scheduleSidecarQueue,
+                warnSchedulingFailure: message => logWarning("dispatch", `sidecar queue scheduling failed: ${message}`),
+                logDequeue: payload => debugLog("autoLoop", { phase: "sidecar-dequeue", ...payload }),
+                emitDequeue: payload => journalReporter.emit("sidecar-dequeue", payload),
+            });
             const sessionLockOutcome = validateWorkflowSessionLock({
                 active: s.active,
                 iteration,
@@ -287,17 +320,9 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 },
             });
             if (sessionLockOutcome.action === "stop" && sessionLockOutcome.reason === "session-lock-lost") {
+                finishTurn("stopped", "manual-attention", sessionLockOutcome.reason);
                 break;
             }
-            // ── Check sidecar queue before deriveState ──
-            const sidecarItem = await dequeueSidecarItem({
-                queue: s.sidecarQueue,
-                executionGraphEnabled: uokFlags.executionGraph,
-                scheduleQueue: scheduleSidecarQueue,
-                warnSchedulingFailure: message => logWarning("dispatch", `sidecar queue scheduling failed: ${message}`),
-                logDequeue: payload => debugLog("autoLoop", { phase: "sidecar-dequeue", ...payload }),
-                emitDequeue: payload => journalReporter.emit("sidecar-dequeue", payload),
-            });
             const ic = { ctx, pi, s, deps, prefs, iteration, flowId, nextSeq };
             journalReporter.emit("iteration-start", { iteration });
             let iterData;
@@ -331,6 +356,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     isComplete: engineState.isComplete,
                 });
                 if (engineState.isComplete) {
+                    finishTurn("completed");
                     await deps.stopAuto(ctx, pi, "Workflow complete");
                     break;
                 }
@@ -386,7 +412,17 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 }
                 // ── Unit execution (shared with dev path) ──
                 await enforceMinRequestInterval(s, prefs);
-                const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, undefined, unitDispatchDeps);
+                let unitPhaseResult;
+                try {
+                    unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, undefined, unitDispatchDeps);
+                }
+                catch (err) {
+                    if (err instanceof ModelPolicyDispatchBlockedError) {
+                        throw err;
+                    }
+                    closeOutCrashedUnit(s, iterData, err);
+                    throw err;
+                }
                 if (unitPhaseResult.action === "next") {
                     const requestTimestamp = resolveUnitRequestTimestamp(unitPhaseResult.data);
                     if (requestTimestamp !== undefined)
@@ -574,6 +610,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 if (err instanceof ModelPolicyDispatchBlockedError) {
                     throw err;
                 }
+                closeOutCrashedUnit(s, iterData, err);
                 dispatchSettled = settleDispatchFailed(dispatchId, formatDispatchExceptionSummary({ error: err }), {
                     markFailed: markDispatchFailed,
                     logWriteFailure: logDispatchLedgerWriteFailure,
@@ -734,6 +771,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 });
                 if (cooldownDecision.action === "stop") {
                     ctx.ui.notify(cooldownDecision.notifyMessage, "error");
+                    finishTurn("stopped", "timeout", msg);
                     await deps.stopAuto(ctx, pi, cooldownDecision.stopMessage);
                     break;
                 }

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

@@ -13,22 +13,22 @@ import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
 import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "../worktree-root.js";
-import { PROJECT_FILES, hasProjectFileInAncestor } from "../detection.js";
+import { classifyProject } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.js";
 import { join, basename } from "node:path";
-import { existsSync, cpSync, readdirSync } from "node:fs";
+import { existsSync, cpSync } from "node:fs";
 import { logWarning, logError, _resetLogs, drainLogs, drainAndSummarize, formatForNotification, hasAnyIssues, } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
-import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js";
+import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
 import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
 import { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -42,13 +42,6 @@ import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit,
 function isSamePathLocal(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
-function refreshPlanSliceRecoveryDbIfNeeded(unitType) {
-    if (unitType !== "plan-slice")
-        return true;
-    if (!isDbAvailable())
-        return true;
-    return refreshOpenDatabaseFromDisk();
-}
 // ─── Session timeout auto-resume state ────────────────────────────────────────
 let consecutiveSessionTimeouts = 0;
 const MAX_SESSION_TIMEOUT_AUTO_RESUMES = 3;
@@ -498,7 +491,7 @@ export async function runPreDispatch(ic, loopState) {
         }
         // #2909: postflight — restore stashed changes after successful merge
         if (preflightTransition.stashPushed) {
-            deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
+            deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightTransition.stashMarker, ctx.ui.notify.bind(ctx.ui));
         }
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         deps.invalidateAllCaches();
@@ -574,7 +567,7 @@ export async function runPreDispatch(ic, loopState) {
                 }
                 // #2909: postflight — restore stashed changes after successful merge
                 if (preflightAllComplete.stashPushed) {
-                    deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
+                    deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightAllComplete.stashMarker, ctx.ui.notify.bind(ctx.ui));
                 }
                 // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
             }
@@ -660,7 +653,7 @@ export async function runPreDispatch(ic, loopState) {
             }
             // #2909: postflight — restore stashed changes after successful merge
             if (preflightComplete.stashPushed) {
-                deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, ctx.ui.notify.bind(ctx.ui));
+                deps.postflightPopStash(s.originalBasePath || s.basePath, s.currentMilestoneId, preflightComplete.stashMarker, ctx.ui.notify.bind(ctx.ui));
             }
             // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         }
@@ -795,11 +788,18 @@ export async function runDispatch(ic, preData, loopState) {
                         level: 1,
                         action: "artifact-found",
                     });
-                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
-                    if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
-                        ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`, "warning");
+                    const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+                    if (!recoveryDb.ok) {
+                        ctx.ui.notify(recoveryDb.fatal
+                            ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                            : `${recoveryDb.message} Keeping stuck state for retry.`, "warning");
+                        if (recoveryDb.fatal) {
+                            await deps.pauseAuto(ctx, pi);
+                            return { action: "break", reason: recoveryDb.reason };
+                        }
                         return { action: "continue" };
                     }
+                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
                     deps.invalidateAllCaches();
                     loopState.recentUnits.length = 0;
                     loopState.stuckRecoveryAttempts = 0;
@@ -818,13 +818,20 @@ export async function runDispatch(ic, preData, loopState) {
                         level: 2,
                         action: "artifact-found",
                     });
-                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
-                    if (refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+                    const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+                    if (recoveryDb.ok) {
+                        ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
                         loopState.recentUnits.length = 0;
                         loopState.stuckRecoveryAttempts = 0;
                         return { action: "continue" };
                     }
-                    ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Stopping for manual recovery.`, "warning");
+                    ctx.ui.notify(recoveryDb.fatal
+                        ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                        : `${recoveryDb.message} Stopping for manual recovery.`, "warning");
+                    if (recoveryDb.fatal) {
+                        await deps.pauseAuto(ctx, pi);
+                        return { action: "break", reason: recoveryDb.reason };
+                    }
                 }
                 debugLog("autoLoop", {
                     phase: "stuck-detected",
@@ -1084,8 +1091,9 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     // Verify the working directory is a valid git checkout with project
     // files before dispatching work. A broken worktree causes agents to
     // hallucinate summaries since they cannot read or write any files.
-    // Uses the shared PROJECT_FILES list from detection.ts to support all
-    // ecosystems (Rust, Go, Python, Java, etc.), not just JS.
+    // Uses project classification so project presence is not conflated with
+    // ecosystem marker detection. Static/minimal repos become untyped-existing.
+    let projectClassification = null;
     if (s.basePath && unitType === "execute-task") {
         const gitMarker = join(s.basePath, ".git");
         const hasGit = deps.existsSync(gitMarker);
@@ -1096,30 +1104,26 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             await deps.stopAuto(ctx, pi, msg);
             return { action: "break", reason: "worktree-invalid" };
         }
-        const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f)));
-        const hasSrcDir = deps.existsSync(join(s.basePath, "src"));
-        // Xcode bundles have project-specific names (*.xcodeproj, *.xcworkspace)
-        // that cannot be matched by exact filename — scan the directory by suffix.
-        let hasXcodeBundle = false;
-        try {
-            const entries = deps.existsSync(s.basePath) ? readdirSync(s.basePath) : [];
-            hasXcodeBundle = entries.some((e) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"));
+        projectClassification = classifyProject(s.basePath);
+        if (projectClassification.kind === "invalid-repo") {
+            const msg = `Worktree health check failed: ${s.basePath} classified as invalid-repo (${projectClassification.reason}) — refusing to dispatch ${unitType} ${unitId}`;
+            debugLog("runUnitPhase", { phase: "worktree-health-invalid-repo", basePath: s.basePath, classification: projectClassification });
+            if (projectClassification.reason === "missing .git" && hasGit) {
+                ctx.ui.notify(`Warning: ${s.basePath} project classification could not confirm .git; assuming it has no project content yet — proceeding as greenfield project because worktree health reported .git present`, "warning");
+            }
+            else {
+                ctx.ui.notify(msg, "error");
+                await deps.stopAuto(ctx, pi, msg);
+                return { action: "break", reason: "worktree-invalid" };
+            }
         }
-        catch (err) {
-            debugLog("runUnitPhase", { phase: "xcode-bundle-scan-failed", basePath: s.basePath, error: String(err) });
-        }
-        // Monorepo support (#2347): if no project files in the worktree directory,
-        // walk parent directories up to the filesystem root. In monorepos,
-        // package.json / Cargo.toml etc. live in a parent directory.
-        const hasProjectFileInParent = !hasProjectFile && !hasSrcDir && !hasXcodeBundle
-            ? hasProjectFileInAncestor(s.basePath, deps.existsSync)
-            : false;
-        if (!hasProjectFile && !hasSrcDir && !hasXcodeBundle && !hasProjectFileInParent) {
-            // Greenfield projects won't have project files yet — the first task creates them.
-            // Log a warning but allow execution to proceed. The .git check above is sufficient
-            // to ensure we're in a valid working directory.
-            debugLog("runUnitPhase", { phase: "worktree-health-warn-greenfield", basePath: s.basePath, hasProjectFile, hasSrcDir, hasXcodeBundle });
-            ctx.ui.notify(`Warning: ${s.basePath} has no recognized project files — proceeding as greenfield project`, "warning");
+        else if (projectClassification.kind === "greenfield") {
+            debugLog("runUnitPhase", { phase: "worktree-health-greenfield", basePath: s.basePath, classification: projectClassification });
+            ctx.ui.notify(`Warning: ${s.basePath} has no project content yet — proceeding as greenfield project`, "warning");
+        }
+        else if (projectClassification.kind === "untyped-existing") {
+            debugLog("runUnitPhase", { phase: "worktree-health-untyped-existing", basePath: s.basePath, classification: projectClassification });
+            ctx.ui.notify(`Notice: ${s.basePath} has existing project content but no recognized tooling markers — using generic file-level workflow guidance`, "info");
         }
     }
     // Detect retry and capture previous tier for escalation
@@ -1182,6 +1186,16 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     // Prompt injection
     let finalPrompt = prompt;
+    if (unitType === "execute-task") {
+        projectClassification ??= classifyProject(s.basePath);
+        if (projectClassification.kind === "untyped-existing") {
+            const samples = projectClassification.contentFiles.slice(0, 8).join(", ") || "project files";
+            finalPrompt +=
+                "\n\n**Project classification:** Existing untyped project. No recognized build/tooling markers were detected, " +
+                    "so use generic file-level workflow guidance. Task plans and completion summaries must list every concrete " +
+                    `project file changed in \`files\` or \`expected_output\`. Detected content sample: ${samples}.`;
+        }
+    }
     if (s.pendingVerificationRetry) {
         const retryCtx = s.pendingVerificationRetry;
         s.pendingVerificationRetry = null;
@@ -1665,6 +1679,13 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
     }
     // Both pre and post verification completed without timeout — reset counter
     loopState.consecutiveFinalizeTimeouts = 0;
+    if (preUnitSnapshot) {
+        writeUnitRuntimeRecord(s.basePath, preUnitSnapshot.type, preUnitSnapshot.id, preUnitSnapshot.startedAt, {
+            phase: "finalized",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "finalize-success",
+        });
+    }
     s.currentUnit = null;
     clearCurrentPhase();
     // Surface accumulated workflow-logger issues for this unit to the user.

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

@@ -17,6 +17,7 @@ import { bumpTurnGeneration } from "./turn-epoch.js";
 // scoped pendingResolve + pendingAgentEndQueue pattern.
 let _currentResolve = null;
 let _sessionSwitchInFlight = false;
+let _pendingSwitchCancellation = null;
 // ─── Setters (needed for cross-module mutation) ─────────────────────────────
 export function _setCurrentResolve(fn) {
     _currentResolve = fn;
@@ -27,6 +28,11 @@ export function _setSessionSwitchInFlight(v) {
 export function _clearCurrentResolve() {
     _currentResolve = null;
 }
+export function _consumePendingSwitchCancellation() {
+    const pending = _pendingSwitchCancellation;
+    _pendingSwitchCancellation = null;
+    return pending;
+}
 // ─── resolveAgentEnd ─────────────────────────────────────────────────────────
 /**
  * Called from the agent_end event handler in index.ts to resolve the
@@ -90,8 +96,18 @@ export function resolveAgentEndCancelled(errorContext) {
         debugLog("resolveAgentEndCancelled", { status: "resolving-cancelled" });
         const r = _currentResolve;
         _currentResolve = null;
+        _pendingSwitchCancellation = null;
         r({ status: "cancelled", ...(errorContext ? { errorContext } : {}) });
+        return true;
+    }
+    if (_sessionSwitchInFlight) {
+        bumpTurnGeneration(`cancelled-during-switch:${errorContext?.category ?? "unknown"}`);
+        _pendingSwitchCancellation = errorContext ? { errorContext } : {};
+        debugLog("resolveAgentEndCancelled", { status: "queued-during-switch" });
+        return false;
     }
+    debugLog("resolveAgentEndCancelled", { status: "no-pending-resolve" });
+    return false;
 }
 // ─── resetPendingResolve (test helper) ───────────────────────────────────────
 /**
@@ -101,6 +117,7 @@ export function resolveAgentEndCancelled(errorContext) {
 export function _resetPendingResolve() {
     _currentResolve = null;
     _sessionSwitchInFlight = false;
+    _pendingSwitchCancellation = null;
 }
 export function _hasPendingResolveForTest() {
     return _currentResolve !== null;

package/dist/resources/extensions/gsd/auto/run-unit.js

@@ -1,14 +1,11 @@
-/**
- * auto/run-unit.ts — Single unit execution: session create → prompt → await agent_end.
- *
- * Imports from: auto/types, auto/resolve
- */
+// GSD-2 + src/resources/extensions/gsd/auto/run-unit.ts - Runs one GSD auto-mode unit from session creation through agent completion.
 import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
-import { _clearCurrentResolve, _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
+import { _clearCurrentResolve, _consumePendingSwitchCancellation, _setCurrentResolve, _setSessionSwitchInFlight, } from "./resolve.js";
 import { getCurrentTurnGeneration, runWithTurnGeneration, } from "./turn-epoch.js";
 import { debugLog } from "../debug-logger.js";
 import { logWarning } from "../workflow-logger.js";
 import { resolveAutoSupervisorConfig } from "../preferences.js";
+import { formatAutoUnitWorkingMessage } from "../working-output-messages.js";
 // Tracks the latest session-switch attempt so a late timeout settlement from an
 // older runUnit() call cannot clear the guard for a newer one.
 let sessionSwitchGeneration = 0;
@@ -74,6 +71,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     catch (sessionErr) {
         if (sessionTimeoutHandle)
             clearTimeout(sessionTimeoutHandle);
+        _consumePendingSwitchCancellation();
         const msg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
         debugLog("runUnit", {
             phase: "session-error",
@@ -86,15 +84,18 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     if (sessionTimeoutHandle)
         clearTimeout(sessionTimeoutHandle);
     if (sessionResult.cancelled) {
+        _consumePendingSwitchCancellation();
         debugLog("runUnit-session-timeout", { unitType, unitId });
         return { status: "cancelled", errorContext: { message: "Session creation timed out", category: "timeout", isTransient: true } };
     }
     if (!s.active) {
+        _consumePendingSwitchCancellation();
         return { status: "cancelled" };
     }
     if (s.currentUnitModel && typeof pi.setModel === "function") {
         const restored = await pi.setModel(s.currentUnitModel, { persist: false });
         if (!restored) {
+            _consumePendingSwitchCancellation();
             const message = `Failed to restore configured model ${s.currentUnitModel.provider}/${s.currentUnitModel.id} after session creation`;
             ctx.ui.notify(`${message}. Cancelling unit before dispatch.`, "warning");
             return {
@@ -114,6 +115,14 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     const unitPromise = new Promise((resolve) => {
         _setCurrentResolve(resolve);
     });
+    const pendingSwitchCancellation = _consumePendingSwitchCancellation();
+    if (pendingSwitchCancellation) {
+        _clearCurrentResolve();
+        return {
+            status: "cancelled",
+            ...(pendingSwitchCancellation.errorContext ? { errorContext: pendingSwitchCancellation.errorContext } : {}),
+        };
+    }
     // ── Provider request-readiness pre-check (#4555) ──
     // Verify the provider can accept requests before dispatching. If the token
     // has expired since bootstrap, return cancelled immediately so the unit is
@@ -151,22 +160,29 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     // ── Send the prompt ──
     debugLog("runUnit", { phase: "send-message", unitType, unitId });
     const requestDispatchedAt = Date.now();
-    pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
+    ctx.ui.setWorkingMessage?.(formatAutoUnitWorkingMessage(unitType, unitId));
     // ── Await agent_end with absolute timeout (H4 fix) ──
     // If supervision fails to resolve unitPromise within 30s, treat as cancelled.
     // Without this, a crashed agent that never emits agent_end hangs the loop (#3161).
-    debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId });
     const supervisor = resolveAutoSupervisorConfig();
     const UNIT_HARD_TIMEOUT_MS = Math.max(30_000, ((supervisor.hard_timeout_minutes ?? 30) * 60 * 1000) + 30_000);
     let unitTimeoutHandle;
-    const timeoutResult = new Promise((resolve) => {
-        unitTimeoutHandle = setTimeout(() => {
-            resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } });
-        }, UNIT_HARD_TIMEOUT_MS);
-    });
-    const result = await runWithTurnGeneration(capturedTurnGen, () => Promise.race([unitPromise, timeoutResult]));
-    if (unitTimeoutHandle)
-        clearTimeout(unitTimeoutHandle);
+    let result;
+    try {
+        pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
+        debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId });
+        const timeoutResult = new Promise((resolve) => {
+            unitTimeoutHandle = setTimeout(() => {
+                resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } });
+            }, UNIT_HARD_TIMEOUT_MS);
+        });
+        result = await runWithTurnGeneration(capturedTurnGen, () => Promise.race([unitPromise, timeoutResult]));
+    }
+    finally {
+        if (unitTimeoutHandle)
+            clearTimeout(unitTimeoutHandle);
+        ctx.ui.setWorkingMessage?.(undefined);
+    }
     debugLog("runUnit", {
         phase: "agent-end-received",
         unitType,