gsd-pi 2.80.0-dev.fbe7c8c6f → 2.81.0

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -39,7 +39,7 @@ If slice research is inlined, trust it. Explore enough code to confirm paths, bo
 5. Define slice verification before tasks. Non-trivial slices need real tests or executable assertions; boundary contracts need contract-exercising checks. Tests must not read .gitignore/gitignored paths such as `.gsd/`, `.planning/`, or `.audits/`.
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
-8. Each task needs a concrete title, Why / Files / Do / Verify / Done when, plus task-plan description, steps, must-haves, verification, inputs, and expected output. Inputs and Expected Output must include concrete backtick-wrapped paths; each task needs at least one output path.
+8. Each task needs a concrete title, Why / Files / Do / Verify / Done when, plus task-plan description, steps, must-haves, verification, inputs, and expected output. Inputs and Expected Output must include concrete backtick-wrapped paths. Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expected_output` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, or tests — those belong only in `inputs`. If a task is a pure verification or test task that produces no new files, its `expected_output` may be empty or limited to test-result artifacts (e.g. a log or assertion output). A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expected_output` — if no prior task creates it, add a task before this one that does.
 9. Persist with `gsd_plan_slice` using goal, successCriteria, optional proofLevel/integrationClosure/observabilityImpact, and tasks. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 10. Self-audit before finishing: goal/demo closure, requirement coverage, locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 11. If planning creates structural decisions, append them to `.gsd/DECISIONS.md`.

package/src/resources/extensions/gsd/prompts/quick-task.md

@@ -17,11 +17,7 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 5. Verify your work:
    - Run tests if applicable.
    - Verify both happy path and failure modes for non-trivial changes.
-6. Commit your changes atomically:
-   - Use conventional commit messages (feat:, fix:, refactor:, etc.)
-   - Stage only relevant files — never commit secrets or runtime files.
-   - Commit logical units separately if the task involves distinct changes.
-   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.
+6. {{commitInstruction}}
 7. Write a brief summary to `{{summaryPath}}`:
    - Quick tasks operate outside the milestone/slice/task DB structure, so `gsd_summary_save` (which requires a `milestone_id`) cannot be used here. Write the file directly.
 

package/src/resources/extensions/gsd/prompts/replan-slice.md

@@ -8,7 +8,7 @@ Your working directory is `{{workingDirectory}}`. All file reads, writes, and sh
 
 A completed task reported `blocker_discovered: true`, meaning the current slice plan cannot be executed as-is. Your job is to rewrite the remaining tasks in the slice plan to address the blocker while preserving all completed work.
 
-All relevant context has been preloaded below — the roadmap, current slice plan, the blocker task summary, and decisions are inlined. Start working immediately without re-reading these files.
+All relevant context has been preloaded below — the roadmap, current slice plan, blocker task summary excerpt, and decisions are inlined. Start working immediately without re-reading these files.
 
 {{inlinedContext}}
 
@@ -30,7 +30,7 @@ Consider these captures when rewriting the remaining tasks — they represent th
 
 ## Instructions
 
-1. Read the blocker task summary carefully. Understand exactly what was discovered and why it blocks the current plan.
+1. Use the inlined blocker summary excerpt first. Read the full blocker task summary only if the excerpt is absent, marked truncated, or lacks the specific blocker evidence needed to replan.
 2. Analyze the remaining `[ ]` tasks in the slice plan. Determine which are still valid, which need modification, and which should be replaced.
 3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`. Preserve or update the Threat Surface and Requirement Impact sections if the replan changes the slice's security posture or requirement coverage.
 4. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -27,13 +27,13 @@ Roadmap, slice summaries, assessments, requirements, decisions, and project cont
 Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
 
 **Reviewer A - Requirements Coverage**
-Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` or equivalent. For each requirement, check slice SUMMARY files in `.gsd/{{milestoneId}}/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/REQUIREMENTS.md` or use the inlined requirements context. For each requirement, check slice SUMMARY files under `.gsd/milestones/{{milestoneId}}/slices/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
 
 **Reviewer B - Cross-Slice Integration**
 Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
 **Reviewer C - Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for criteria. Check slice ASSESSMENT files. Verify each criterion maps to a passing assessment or clear SUMMARY evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY/UAT files under `.gsd/milestones/{{milestoneId}}/slices/`. Verify each criterion maps to passing evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 - Synthesize Findings
 

package/src/resources/extensions/gsd/quick.ts

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { GitServiceImpl, runGit } from "./git-service.js";
@@ -77,6 +77,40 @@ function ensureQuickDir(basePath: string, taskNum: number, slug: string): string
   return taskDir;
 }
 
+function isPathInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function isExternalGsdRoot(basePath: string, root: string): boolean {
+  try {
+    return !isPathInside(realpathSync(basePath), realpathSync(root));
+  } catch {
+    return !isPathInside(basePath, root);
+  }
+}
+
+export function buildQuickCommitInstruction(basePath: string, root: string): string {
+  const externalState = isExternalGsdRoot(basePath, root);
+  if (externalState) {
+    return [
+      "Commit repo changes atomically, but do not stage or commit `.gsd/quick/...`:",
+      "   - `.gsd/` resolves outside this git repository, so Git cannot stage quick-task summary files from the project repo.",
+      "   - Write the quick summary file directly at the requested path; that file is persisted by GSD external state.",
+      "   - Stage and commit only implementation/test/docs files that live inside the repository.",
+      "   - If the task only writes quick-task research/summary files and no repository files changed, do not run `git commit`; report that there was nothing in the project repo to commit.",
+    ].join("\n");
+  }
+
+  return [
+    "Commit your changes atomically:",
+    "   - Use conventional commit messages (feat:, fix:, refactor:, etc.)",
+    "   - Stage only relevant files — never commit secrets or runtime files.",
+    "   - Commit logical units separately if the task involves distinct changes.",
+    "   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.",
+  ].join("\n");
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
@@ -246,6 +280,7 @@ export async function handleQuick(
     taskDir: taskDirRel,
     branch: actualBranch,
     summaryPath,
+    commitInstruction: buildQuickCommitInstruction(basePath, root),
     date,
     taskNum: String(taskNum),
     slug,

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

@@ -0,0 +1,122 @@
+// Project/App: GSD-2
+// File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
+
+import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+
+export type RecoveryFailureKind =
+  | "tool-schema"
+  | "deterministic-policy"
+  | "stale-worker"
+  | "worktree-invalid"
+  | "verification-drift"
+  | "provider"
+  | "runtime-unknown";
+
+export type RecoveryAction = "retry" | "escalate" | "stop";
+
+export interface RecoveryClassificationInput {
+  error: unknown;
+  unitType?: string;
+  unitId?: string;
+  failureKind?: RecoveryFailureKind;
+  retryAfterMs?: number;
+}
+
+export interface RecoveryClassification {
+  failureKind: RecoveryFailureKind;
+  action: RecoveryAction;
+  reason: string;
+  exitReason: string;
+  remediation: string;
+  providerClass?: ErrorClass["kind"];
+}
+
+export function classifyFailure(input: RecoveryClassificationInput): RecoveryClassification {
+  const message = errorMessage(input.error);
+  const failureKind = input.failureKind ?? inferFailureKind(message);
+
+  switch (failureKind) {
+    case "tool-schema":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
+        exitReason: "tool-schema",
+        remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
+      };
+    case "deterministic-policy":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
+        exitReason: "deterministic-policy",
+        remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+      };
+    case "stale-worker":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
+        exitReason: "stale-worker",
+        remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
+      };
+    case "worktree-invalid":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
+        exitReason: "worktree-invalid",
+        remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
+      };
+    case "verification-drift":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: `Verification drift${unitSuffix(input)}: ${message}`,
+        exitReason: "verification-drift",
+        remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
+      };
+    case "provider": {
+      const providerClass = classifyError(message, input.retryAfterMs);
+      return {
+        failureKind,
+        action: isTransient(providerClass) ? "retry" : "escalate",
+        reason: message,
+        exitReason: `provider-${providerClass.kind}`,
+        remediation: isTransient(providerClass)
+          ? "Retry after the provider/network condition clears."
+          : "Inspect provider credentials, model entitlement, or request shape.",
+        providerClass: providerClass.kind,
+      };
+    }
+    case "runtime-unknown":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: message,
+        exitReason: "runtime-unknown",
+        remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+      };
+  }
+}
+
+function inferFailureKind(message: string): RecoveryFailureKind {
+  if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";
+  if (/deterministic policy|policy rejection|write gate|blocked by policy/i.test(message)) return "deterministic-policy";
+  if (/stale worker|stale lock|worker.*stale/i.test(message)) return "stale-worker";
+  if (/worktree|\.git|unit root|git metadata/i.test(message)) return "worktree-invalid";
+  if (/verification drift|assessment drift|state drift/i.test(message)) return "verification-drift";
+
+  const providerClass = classifyError(message);
+  return providerClass.kind === "unknown" ? "runtime-unknown" : "provider";
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error ?? "unknown runtime failure");
+}
+
+function unitSuffix(input: RecoveryClassificationInput): string {
+  if (!input.unitType && !input.unitId) return "";
+  return ` for ${input.unitType ?? "unit"} ${input.unitId ?? ""}`.trimEnd();
+}

package/src/resources/extensions/gsd/slice-cadence.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Slice-cadence merge and milestone resquash git operations.
 /**
  * Slice-cadence collapse — #4765.
  *
@@ -40,6 +42,7 @@ import { logWarning } from "./workflow-logger.js";
 import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { getMilestone, getSlice, isDbAvailable } from "./gsd-db.js";
 
 /**
  * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
@@ -72,6 +75,50 @@ function cleanupMergeArtifacts(projectRoot: string): void {
   }
 }
 
+function stripKnownIdPrefix(value: string | undefined | null, id: string): string | undefined {
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+  const lower = raw.toLowerCase();
+  const idLower = id.toLowerCase();
+  if (lower.startsWith(`${idLower}:`)) return raw.slice(id.length + 1).trim() || undefined;
+  return raw;
+}
+
+function getSliceMergeNames(milestoneId: string, sliceId: string): {
+  milestoneTitle?: string;
+  sliceTitle?: string;
+} {
+  if (!isDbAvailable()) return {};
+  return {
+    milestoneTitle: stripKnownIdPrefix(getMilestone(milestoneId)?.title, milestoneId),
+    sliceTitle: stripKnownIdPrefix(getSlice(milestoneId, sliceId)?.title, sliceId),
+  };
+}
+
+function buildSliceMergeCommitMessage(milestoneId: string, sliceId: string, milestoneBranch: string): string {
+  const names = getSliceMergeNames(milestoneId, sliceId);
+  const sliceLabel = names.sliceTitle ?? sliceId;
+  const subject = `feat: ${sliceLabel} - ${sliceId} of ${milestoneId} (slice-cadence)`;
+  const body = [
+    `Slice: ${sliceId}${names.sliceTitle ? ` - ${names.sliceTitle}` : ""}`,
+    `Milestone: ${milestoneId}${names.milestoneTitle ? ` - ${names.milestoneTitle}` : ""}`,
+    `GSD-Slice: ${sliceId}`,
+    `GSD-Milestone: ${milestoneId}`,
+    `Branch: ${milestoneBranch}`,
+  ];
+  return `${subject}\n\n${body.join("\n")}`;
+}
+
+function buildMilestoneResquashCommitMessage(milestoneId: string, sliceCount: number): string {
+  const milestoneTitle = isDbAvailable()
+    ? stripKnownIdPrefix(getMilestone(milestoneId)?.title, milestoneId)
+    : undefined;
+  const subject = milestoneTitle
+    ? `feat: ${milestoneTitle} (${milestoneId}, ${sliceCount} slices re-squashed)`
+    : `feat: ${milestoneId} (${sliceCount} slices re-squashed)`;
+  return `${subject}\n\nMilestone: ${milestoneId}${milestoneTitle ? ` - ${milestoneTitle}` : ""}\nGSD-Milestone: ${milestoneId}`;
+}
+
 function advanceMilestoneBranch(
   projectRoot: string,
   worktreeCwd: string,
@@ -227,7 +274,7 @@ export function mergeSliceToMain(
     // Commit the squash with a slice-scoped message
     const commitSha = nativeCommit(
       projectRoot,
-      `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`,
+      buildSliceMergeCommitMessage(milestoneId, sliceId, milestoneBranch),
     );
 
     // Advance the milestone branch to main so the next slice's commits start
@@ -327,7 +374,7 @@ export function resquashMilestoneOnMain(
 
     const newSha = nativeCommit(
       projectRoot,
-      `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`,
+      buildMilestoneResquashCommitMessage(milestoneId, sliceCount),
       { allowEmpty: true },
     );
 

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

@@ -84,6 +84,27 @@ const SLICE_ORCHESTRATOR_STATE_FILE = "slice-orchestrator.json";
 const TMP_SUFFIX = ".tmp";
 export const SLICE_WORKER_AUTO_ARGS = ["headless", "--json", "auto"] as const;
 
+export function _resolveSliceParallelMaxWorkersForTest(maxWorkers?: number): number {
+  return maxWorkers ?? 2;
+}
+
+export function _buildSliceWorkerEnvForTest(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  workerToken: string,
+  sourceEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...sourceEnv,
+    GSD_SLICE_LOCK: sliceId,
+    GSD_MILESTONE_LOCK: milestoneId,
+    GSD_PROJECT_ROOT: basePath,
+    GSD_PARALLEL_WORKER: "1",
+    GSD_SLICE_WORKER_TOKEN: workerToken,
+  };
+}
+
 interface PersistedSliceWorker {
   milestoneId: string;
   sliceId: string;
@@ -371,7 +392,7 @@ export async function startSliceParallel(
     return { started: [], errors: [{ sid: "all", error: "Cannot start slice-parallel from within a parallel worker" }] };
   }
 
-  const maxWorkers = opts.maxWorkers ?? 2;
+  const maxWorkers = _resolveSliceParallelMaxWorkersForTest(opts.maxWorkers);
   const budgetCeiling = opts.budgetCeiling;
 
   // Initialize orchestrator state
@@ -624,14 +645,7 @@ function spawnSliceWorker(
   try {
     child = spawn(process.execPath, [binPath, ...SLICE_WORKER_AUTO_ARGS], {
       cwd: worker.worktreePath,
-      env: {
-        ...process.env,
-        GSD_SLICE_LOCK: sliceId,
-        GSD_MILESTONE_LOCK: milestoneId,
-        GSD_PROJECT_ROOT: basePath,
-        GSD_PARALLEL_WORKER: "1",
-        GSD_SLICE_WORKER_TOKEN: worker.workerToken,
-      },
+      env: _buildSliceWorkerEnvForTest(basePath, milestoneId, sliceId, worker.workerToken),
       stdio: ["ignore", "pipe", "pipe"],
       detached: false,
     });

package/src/resources/extensions/gsd/state-reconciliation.ts

@@ -0,0 +1,57 @@
+// Project/App: GSD-2
+// File Purpose: ADR-015 State Reconciliation module for pre-dispatch runtime invariants.
+
+import { deriveState, invalidateStateCache, type DeriveStateOptions } from "./state.js";
+import type { GSDState } from "./types.js";
+
+export type StateReconciliationResult =
+  | {
+      ok: true;
+      stateSnapshot: GSDState;
+      repaired: readonly string[];
+      blockers: readonly string[];
+    }
+  | {
+      ok: false;
+      reason: string;
+      stateSnapshot?: GSDState;
+      repaired: readonly string[];
+      blockers: readonly string[];
+    };
+
+export interface StateReconciliationDeps {
+  invalidateStateCache: () => void;
+  deriveState: (basePath: string, opts?: DeriveStateOptions) => Promise<GSDState>;
+}
+
+const defaultDeps: StateReconciliationDeps = {
+  invalidateStateCache,
+  deriveState,
+};
+
+export async function reconcileBeforeDispatch(
+  basePath: string,
+  deps: StateReconciliationDeps = defaultDeps,
+  opts?: DeriveStateOptions,
+): Promise<StateReconciliationResult> {
+  deps.invalidateStateCache();
+  const stateSnapshot = await deps.deriveState(basePath, opts);
+  const blockers = stateSnapshot.blockers ?? [];
+
+  if (blockers.length > 0 || stateSnapshot.phase === "blocked") {
+    return {
+      ok: false,
+      reason: blockers[0] ?? `State reconciliation blocked in phase ${stateSnapshot.phase}`,
+      stateSnapshot,
+      repaired: ["derive-state-cache-invalidated"],
+      blockers,
+    };
+  }
+
+  return {
+    ok: true,
+    stateSnapshot,
+    repaired: ["derive-state-cache-invalidated"],
+    blockers,
+  };
+}

package/src/resources/extensions/gsd/tests/agent-end-retry.test.ts

@@ -7,104 +7,74 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
-const AUTO_RESOLVE_TS_PATH = join(__dirname, "..", "auto", "resolve.ts");
-const SESSION_TS_PATH = join(__dirname, "..", "auto", "session.ts");
-
-function getAutoTsSource(): string {
-  return readFileSync(AUTO_TS_PATH, "utf-8");
-}
-
-function getAutoResolveTsSource(): string {
-  return readFileSync(AUTO_RESOLVE_TS_PATH, "utf-8");
-}
-
-function getSessionTsSource(): string {
-  return readFileSync(SESSION_TS_PATH, "utf-8");
-}
-
-test("auto/resolve.ts declares _currentResolve for per-unit one-shot promises", () => {
-  const source = getAutoResolveTsSource();
-  assert.ok(
-    source.includes("_currentResolve"),
-    "auto/resolve.ts must declare _currentResolve for the per-unit resolve function",
-  );
-  assert.ok(
-    source.includes("_sessionSwitchInFlight"),
-    "auto/resolve.ts must declare _sessionSwitchInFlight guard",
-  );
-});
+import {
+  _consumePendingSwitchCancellation,
+  _hasPendingResolveForTest,
+  _resetPendingResolve,
+  _setCurrentResolve,
+  _setSessionSwitchInFlight,
+  isSessionSwitchInFlight,
+  resolveAgentEnd,
+  resolveAgentEndCancelled,
+} from "../auto/resolve.ts";
+import { AutoSession } from "../auto/session.ts";
 
-test("AutoSession no longer holds promise state (moved to auto-loop.ts module scope)", () => {
-  const source = getSessionTsSource();
-  // Properties should NOT exist as class fields
-  assert.ok(
-    !source.includes("pendingResolve:"),
-    "AutoSession must not declare pendingResolve (moved to auto-loop.ts)",
-  );
-  assert.ok(
-    !source.includes("pendingAgentEndQueue:"),
-    "AutoSession must not declare pendingAgentEndQueue (removed — events are dropped)",
-  );
+test.afterEach(() => {
+  _resetPendingResolve();
 });
 
-test("legacy pendingAgentEndRetry state is gone", () => {
-  const source = getSessionTsSource();
-  assert.ok(
-    !source.includes("pendingAgentEndRetry"),
-    "AutoSession should no longer use legacy pendingAgentEndRetry state",
-  );
+test("resolveAgentEnd resolves the current unit once and clears the resolver", () => {
+  const results: unknown[] = [];
+  _setCurrentResolve((result) => results.push(result));
+
+  resolveAgentEnd({ messages: ["done"] } as any);
+  resolveAgentEnd({ messages: ["late"] } as any);
+
+  assert.equal(_hasPendingResolveForTest(), false);
+  assert.equal(results.length, 1);
+  assert.deepEqual(results[0], { status: "completed", event: { messages: ["done"] } });
 });
 
-test("pauseAuto calls resolveAgentEndCancelled to unblock the loop", () => {
-  const source = getAutoTsSource();
-  const fnIdx = source.indexOf("export async function pauseAuto");
-  assert.ok(fnIdx > -1, "pauseAuto must exist in auto.ts");
-  // Extract the function body (up to the next export or top-level function)
-  const fnBlock = source.slice(fnIdx, source.indexOf("\n/**\n * Build", fnIdx + 100));
-
-  assert.ok(
-    fnBlock.includes("resolveAgentEndCancelled("),
-    "pauseAuto must call resolveAgentEndCancelled to unblock the auto-loop promise",
-  );
+test("resolveAgentEnd ignores events while a session switch is in flight", () => {
+  const results: unknown[] = [];
+  _setCurrentResolve((result) => results.push(result));
+  _setSessionSwitchInFlight(true);
+
+  resolveAgentEnd({ messages: ["ignored"] } as any);
+
+  assert.equal(isSessionSwitchInFlight(), true);
+  assert.equal(_hasPendingResolveForTest(), true);
+  assert.deepEqual(results, []);
 });
 
-test("auto-timers.ts idle watchdog catch calls resolveAgentEndCancelled", () => {
-  const TIMERS_PATH = join(__dirname, "..", "auto-timers.ts");
-  const source = readFileSync(TIMERS_PATH, "utf-8");
-
-  const idleCatchIdx = source.indexOf("[idle-watchdog] Unhandled error");
-  assert.ok(idleCatchIdx > -1, "idle watchdog catch block must exist");
-  // Check that resolveAgentEndCancelled is called near this catch
-  const catchRegion = source.slice(Math.max(0, idleCatchIdx - 200), idleCatchIdx + 200);
-  assert.ok(
-    catchRegion.includes("resolveAgentEndCancelled("),
-    "idle watchdog catch block must call resolveAgentEndCancelled",
-  );
+test("resolveAgentEndCancelled unblocks the current unit with cancellation context", () => {
+  const results: unknown[] = [];
+  _setCurrentResolve((result) => results.push(result));
+
+  const cancelled = resolveAgentEndCancelled({ category: "idle-timeout", detail: "test" } as any);
+
+  assert.equal(cancelled, true);
+  assert.equal(_hasPendingResolveForTest(), false);
+  assert.deepEqual(results, [
+    { status: "cancelled", errorContext: { category: "idle-timeout", detail: "test" } },
+  ]);
 });
 
-test("auto-timers.ts hard timeout catch calls resolveAgentEndCancelled", () => {
-  const TIMERS_PATH = join(__dirname, "..", "auto-timers.ts");
-  const source = readFileSync(TIMERS_PATH, "utf-8");
-
-  const hardCatchIdx = source.indexOf("[hard-timeout] Unhandled error");
-  assert.ok(hardCatchIdx > -1, "hard timeout catch block must exist");
-  const catchRegion = source.slice(Math.max(0, hardCatchIdx - 200), hardCatchIdx + 200);
-  assert.ok(
-    catchRegion.includes("resolveAgentEndCancelled("),
-    "hard timeout catch block must call resolveAgentEndCancelled",
-  );
+test("resolveAgentEndCancelled records cancellation that occurs during session switch", () => {
+  _setSessionSwitchInFlight(true);
+
+  const cancelled = resolveAgentEndCancelled({ category: "session-switch", detail: "test" } as any);
+
+  assert.equal(cancelled, false);
+  assert.deepEqual(_consumePendingSwitchCancellation(), {
+    errorContext: { category: "session-switch", detail: "test" },
+  });
 });
 
-test("resolveAgentEndCancelled is exported from auto/resolve.ts", () => {
-  const source = getAutoResolveTsSource();
-  assert.ok(
-    source.includes("export function resolveAgentEndCancelled"),
-    "auto/resolve.ts must export resolveAgentEndCancelled",
-  );
+test("AutoSession does not own agent_end promise state", () => {
+  const s = new AutoSession() as any;
+
+  assert.equal("pendingResolve" in s, false);
+  assert.equal("pendingAgentEndQueue" in s, false);
+  assert.equal("pendingAgentEndRetry" in s, false);
 });