@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.fb12b103

package/src/resources/extensions/gsd/tests/unit-registry.test.ts

@@ -0,0 +1,163 @@
+// gsd-pi — ADR-033 Unit Registry parity guard.
+//
+// Pins every view derived from UNIT_REGISTRY to the exact values the
+// hand-maintained tables held before the registry existed. A failure here
+// means a registry edit changed a derived surface — intended changes update
+// the pinned expectation in the same diff.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  KNOWN_UNIT_TYPES,
+  UNIT_REGISTRY,
+  EXECUTE_TASK_UNIT_TYPES,
+  SECTION_CLOSE_GATE_UNIT_TYPES,
+  getUnitDescriptor,
+  getUnitPhaseChain,
+} from "../unit-registry.ts";
+import {
+  AUTO_UNIT_SCOPED_TOOLS,
+  UNIT_TOOL_CONTRACTS,
+  getUnitToolSurfaceContract,
+} from "../unit-tool-contracts.ts";
+import { UNIT_MANIFESTS } from "../unit-context-manifest.ts";
+import { phaseChainForUnit } from "../preferences-models.ts";
+
+// ─── Pinned pre-registry values ───────────────────────────────────────────
+
+const EXPECTED_KNOWN_UNIT_TYPES = [
+  "research-milestone",
+  "plan-milestone",
+  "discuss-milestone",
+  "validate-milestone",
+  "complete-milestone",
+  "research-slice",
+  "plan-slice",
+  "refine-slice",
+  "replan-slice",
+  "complete-slice",
+  "reassess-roadmap",
+  "execute-task",
+  "reactive-execute",
+  "run-uat",
+  "gate-evaluate",
+  "rewrite-docs",
+  "triage-captures",
+  "quick-task",
+  "workflow-preferences",
+  "discuss-project",
+  "discuss-requirements",
+  "research-decision",
+  "research-project",
+];
+
+// The contract table carried two keys KNOWN_UNIT_TYPES never had (variants)
+// and lacked two it did have (sidecars without contracts).
+const EXPECTED_CONTRACT_ONLY_TYPES = ["discuss-slice", "execute-task-simple"];
+const EXPECTED_CONTRACT_LESS_TYPES = ["triage-captures", "quick-task"];
+
+const EXPECTED_EXECUTE_TASK_SET = ["execute-task", "execute-task-simple", "reactive-execute"];
+const EXPECTED_SECTION_CLOSE_SET = [
+  ...EXPECTED_EXECUTE_TASK_SET,
+  "complete-slice",
+  "validate-milestone",
+];
+
+const EXPECTED_PHASE_CHAINS: Record<string, string[] | undefined> = {
+  "research-milestone": ["research"],
+  "research-slice": ["research"],
+  "research-project": ["research"],
+  "plan-milestone": ["planning"],
+  "plan-slice": ["planning"],
+  "refine-slice": ["planning"],
+  "replan-slice": ["planning"],
+  "discuss-milestone": ["discuss", "planning"],
+  "discuss-slice": ["discuss", "planning"],
+  "discuss-project": ["discuss", "planning"],
+  "discuss-requirements": ["discuss", "planning"],
+  "workflow-preferences": ["discuss", "planning"],
+  "research-decision": ["discuss", "planning"],
+  "execute-task": ["execution"],
+  "reactive-execute": ["execution"],
+  "execute-task-simple": ["execution_simple", "execution"],
+  "complete-slice": ["completion"],
+  "complete-milestone": ["completion"],
+  "worktree-merge": ["completion"],
+  "run-uat": ["uat", "completion"],
+  "reassess-roadmap": ["validation", "planning"],
+  "rewrite-docs": ["validation", "planning"],
+  "gate-evaluate": ["validation", "planning"],
+  "validate-milestone": ["validation", "planning"],
+  "triage-captures": undefined,
+  "quick-task": undefined,
+  subagent: ["subagent"],
+  "subagent/scout": ["subagent"],
+  "no-such-unit": undefined,
+};
+
+// ─── Derived-view parity ──────────────────────────────────────────────────
+
+test("KNOWN_UNIT_TYPES derives exactly the pre-registry list, in order", () => {
+  assert.deepEqual([...KNOWN_UNIT_TYPES], EXPECTED_KNOWN_UNIT_TYPES);
+});
+
+test("UNIT_TOOL_CONTRACTS keeps the pre-registry key set, asymmetries included", () => {
+  const contractKeys = Object.keys(UNIT_TOOL_CONTRACTS);
+  for (const variant of EXPECTED_CONTRACT_ONLY_TYPES) {
+    assert.ok(contractKeys.includes(variant), `variant ${variant} must keep its contract`);
+    assert.ok(!KNOWN_UNIT_TYPES.includes(variant as never), `${variant} must stay out of KNOWN_UNIT_TYPES`);
+  }
+  for (const sidecar of EXPECTED_CONTRACT_LESS_TYPES) {
+    assert.ok(!contractKeys.includes(sidecar), `${sidecar} must stay contract-less`);
+    assert.equal(getUnitToolSurfaceContract(sidecar), undefined);
+  }
+  const expectedKeys = [
+    ...EXPECTED_KNOWN_UNIT_TYPES.filter((t) => !EXPECTED_CONTRACT_LESS_TYPES.includes(t)),
+    ...EXPECTED_CONTRACT_ONLY_TYPES,
+  ].sort();
+  assert.deepEqual([...contractKeys].sort(), expectedKeys);
+});
+
+test("scope-class Sets match the pre-registry hand-maintained Sets", () => {
+  assert.deepEqual([...EXECUTE_TASK_UNIT_TYPES].sort(), [...EXPECTED_EXECUTE_TASK_SET].sort());
+  assert.deepEqual([...SECTION_CLOSE_GATE_UNIT_TYPES].sort(), [...EXPECTED_SECTION_CLOSE_SET].sort());
+});
+
+test("phaseChainForUnit matches the pre-registry switch for every known input", () => {
+  for (const [unitType, expected] of Object.entries(EXPECTED_PHASE_CHAINS)) {
+    assert.deepEqual(
+      phaseChainForUnit(unitType),
+      expected,
+      `phase chain for ${unitType}`,
+    );
+  }
+});
+
+test("AUTO_UNIT_SCOPED_TOOLS mirrors each contract's allowed tools", () => {
+  for (const [unitType, contract] of Object.entries(UNIT_TOOL_CONTRACTS)) {
+    assert.deepEqual(AUTO_UNIT_SCOPED_TOOLS[unitType], contract.allowedGsdTools);
+  }
+  assert.deepEqual(
+    Object.keys(AUTO_UNIT_SCOPED_TOOLS).sort(),
+    Object.keys(UNIT_TOOL_CONTRACTS).sort(),
+  );
+});
+
+// ─── Registry-internal coherence ──────────────────────────────────────────
+
+test("every primary unit type has a manifest; manifests cover nothing else", () => {
+  const manifestKeys = Object.keys(UNIT_MANIFESTS).sort();
+  assert.deepEqual(manifestKeys, [...KNOWN_UNIT_TYPES].sort());
+});
+
+test("every registry row is reachable through the descriptor accessor", () => {
+  for (const unitType of Object.keys(UNIT_REGISTRY)) {
+    const descriptor = getUnitDescriptor(unitType);
+    assert.ok(descriptor, `descriptor for ${unitType}`);
+    assert.ok(["primary", "variant"].includes(descriptor.kind));
+    assert.ok(["execute-task", "section-close", "standard"].includes(descriptor.scopeClass));
+    assert.equal(getUnitPhaseChain(unitType), descriptor.phaseChain);
+  }
+  assert.equal(getUnitDescriptor("no-such-unit"), undefined);
+});

package/src/resources/extensions/gsd/tests/web-app-uat.test.ts

@@ -15,6 +15,10 @@ function scaffoldProject(root: string, pkg: Record<string, unknown>): void {
   writeFileSync(join(root, "package.json"), JSON.stringify(pkg, null, 2));
 }
 
+const LEGACY_ENGINE = { engine: "legacy", source: "probe", reason: "test" } as const;
+const MANAGED_ENGINE = { engine: "gsd-browser", source: "probe", reason: "test" } as const;
+const OFF_ENGINE = { engine: "off", source: "env", reason: "test" } as const;
+
 describe("web-app-uat guidance", () => {
   test("returns null for non-web projects", () => {
     const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
@@ -36,15 +40,54 @@ describe("web-app-uat guidance", () => {
         scripts: { dev: "vite" },
       });
       assert.equal(detectWebApp(root), true);
-      const block = buildWebAppUatGuidanceBlock(root);
+      const block = buildWebAppUatGuidanceBlock(root, LEGACY_ENGINE);
       assert.ok(block);
       assert.match(block!, /browser-executable/);
+      assert.match(block!, /Playwright-backed `browser_\*` tools/);
       assert.match(block!, /Playwright scaffolding/);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
   });
 
+  test("describes the managed gsd-browser engine when it is the resolved backing", () => {
+    const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
+    try {
+      scaffoldProject(root, {
+        dependencies: { react: "19.0.0" },
+        scripts: { dev: "vite" },
+      });
+      const block = buildWebAppUatGuidanceBlock(root, MANAGED_ENGINE);
+      assert.ok(block);
+      assert.match(block!, /managed gsd-browser engine/);
+      assert.match(block!, /browser-executable/);
+      assert.doesNotMatch(block!, /Playwright-backed/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("steers to runtime-executable UAT when browser tools are off", () => {
+    const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
+    try {
+      scaffoldProject(root, {
+        dependencies: { react: "19.0.0" },
+        scripts: { dev: "vite" },
+      });
+      const block = buildWebAppUatGuidanceBlock(root, OFF_ENGINE);
+      assert.ok(block);
+      assert.match(block!, /browser tools are disabled/);
+      assert.doesNotMatch(block!, /- `browser-executable`/);
+      // mixed/live-runtime require browser tools per UAT_MODE_POLICIES, so the
+      // bullet must drop out too — recommending them would dead-end at dispatch.
+      assert.doesNotMatch(block!, /- `mixed`/);
+      assert.doesNotMatch(block!, /interactive `browser_\*` checks/);
+      assert.match(block!, /runtime-executable/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   test("detects existing Playwright and npm script", () => {
     const root = mkdtempSync(join(tmpdir(), "gsd-web-uat-"));
     try {

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -495,8 +495,8 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
               estimate: "10m",
               files: ["src/resources/extensions/gsd/workflow-mcp.ts"],
               verify: "node --test",
-              inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
-              expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
+              inputs: [],
+              expectedOutput: ["src/bridge-status.md"],
             },
           ],
         },

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -528,8 +528,8 @@ test("executePlanSlice writes task planning state and rendered plan artifacts",
           estimate: "15m",
           files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"],
           verify: "node --test",
-          inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
-          expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
+          inputs: [],
+          expectedOutput: ["src/bridge-status.md"],
         },
       ],
     }, base));

package/src/resources/extensions/gsd/tool-surface-readiness.ts

@@ -0,0 +1,76 @@
+// Project/App: gsd-pi
+// File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
+
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+
+/**
+ * Stable phrase recognized as transient by auto-tool-tracking's
+ * isToolUnavailableError and error-classifier's transient buckets,
+ * which build their matchers from this constant.
+ */
+export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
+
+/** MCP server statuses that will not self-heal within the session. */
+const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+
+export interface LiveToolSurfaceObservation {
+  /** Tool names the session reported at init (MCP tools appear as mcp__<server>__<tool>). */
+  tools: readonly string[];
+  /** MCP server connection statuses the session reported at init. */
+  mcpServers: readonly { name: string; status: string }[];
+}
+
+/**
+ * Verify the live tool surface observed at SDK session init covers the Unit's
+ * required workflow tools. Complements the static pre-dispatch gate
+ * (getWorkflowTransportSupportError), which only proves the MCP launch config
+ * is discoverable — the workflow server connects asynchronously after session
+ * start, so the static gate cannot see whether the tools actually registered.
+ *
+ * Returns a transient, recovery-classifiable error (kind tool-unavailable →
+ * retry) when the workflow server failed or has not yet registered a required
+ * tool, so dispatch aborts before the first model turn instead of letting the
+ * Unit improvise around "No such tool available". Returns null when no
+ * workflow server is part of this session (native tool path), when the Unit
+ * requires no workflow tools, or when the surface is ready.
+ */
+export function getToolSurfaceReadinessError(input: {
+  unitType: string | undefined;
+  workflowServerName: string | undefined;
+  observation: LiveToolSurfaceObservation;
+}): string | null {
+  const { unitType, workflowServerName, observation } = input;
+  if (!unitType || !workflowServerName) return null;
+
+  const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+  if (required.length === 0) return null;
+
+  const server = observation.mcpServers.find((entry) => entry.name === workflowServerName);
+  if (!server) {
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${required.join(", ")}`;
+  }
+
+  // The SDK does not wait for MCP servers before init — a still-connecting
+  // server reports "pending" there routinely, then registers within seconds,
+  // usually well before the Unit's first workflow tool call. Aborting on
+  // "pending" would fail the common healthy session, so it passes through;
+  // a genuine miss after pass-through still surfaces in-session as
+  // "No such tool available" and classifies tool-unavailable → bounded retry.
+  // Only statuses that cannot self-heal abort here.
+  if (server.status !== "connected" && !TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
+    return null;
+  }
+
+  const missing = required.filter(
+    (tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+  if (missing.length === 0) return null;
+
+  const serverDetail =
+    server.status === "connected"
+      ? `MCP server "${workflowServerName}" is connected but has not registered`
+      : `MCP server "${workflowServerName}" status is "${server.status}" and it has not registered`;
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: ${serverDetail}: ${missing.join(", ")}`;
+}

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -11,7 +11,7 @@ import {
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
-import { findWorktreeSegment } from "../worktree-root.js";
+import { projectRootFromWorktreePath } from "../worktree-root.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -202,12 +202,9 @@ function normalizeScanPath(value: string): string {
 
 function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
   const normalizedBase = normalizeScanPath(baseDir);
-  const segment = findWorktreeSegment(normalizedBase);
-  if (!segment || segment.gsdIdx <= 0) return null;
-  return {
-    originalRoot: normalizedBase.slice(0, segment.gsdIdx),
-    worktreeRoot: normalizedBase,
-  };
+  const originalRoot = projectRootFromWorktreePath(normalizedBase);
+  if (!originalRoot) return null;
+  return { originalRoot, worktreeRoot: normalizedBase };
 }
 
 function pathInside(parent: string, target: string): boolean {
@@ -427,6 +424,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
       stderr_bytes: result.stderr_bytes,
@@ -441,6 +439,9 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
 }
 
 function formatExit(result: ExecSandboxResult): string {
+  // force_resolved means a non-closing (D-state) child was force-resolved past its
+  // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;
   if (result.exit_code === null) return "null";

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -26,8 +26,9 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
-import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
+import { runTaskPathChecks } from "../pre-execution-checks.js";
 import type { TaskRow } from "../db-task-slice-rows.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
@@ -268,11 +269,16 @@ function validateTaskPathsBeforePersist(
   const additionalRoots = allowedRoots
     .map((root) => resolve(root))
     .filter((root) => root !== baseRoot);
-  const context = additionalRoots.length > 0 ? { additionalRoots } : undefined;
-  const checks = [
-    ...checkFilePathConsistency(taskRows, basePath, context),
-    ...checkTaskOrdering(taskRows, basePath, context),
-  ];
+  const resolvedCanonicalRoot = resolve(resolveWorktreeProjectRoot(basePath));
+  const canonicalProjectRoot = resolvedCanonicalRoot !== baseRoot ? resolvedCanonicalRoot : undefined;
+  const hasContext = additionalRoots.length > 0 || canonicalProjectRoot !== undefined;
+  const context = hasContext
+    ? {
+        ...(additionalRoots.length > 0 ? { additionalRoots } : {}),
+        ...(canonicalProjectRoot !== undefined ? { canonicalProjectRoot } : {}),
+      }
+    : undefined;
+  const checks = runTaskPathChecks(taskRows, basePath, context);
   const blocking = checks.filter((check) => !check.passed && check.blocking);
 
   if (blocking.length === 0) return null;

package/src/resources/extensions/gsd/uat-policy.ts

@@ -1,6 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
@@ -126,7 +127,7 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
 export function isUatBrowserToolName(toolName: string): boolean {
   const parsed = parseMcpToolName(toolName);
   const canonicalName = parsed?.toolName ?? toolName;
-  if (canonicalName.startsWith("browser_")) return true;
+  if (hasBrowserContractPrefix(canonicalName)) return true;
   return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 

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

@@ -0,0 +1,201 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Closeout module — durable completion pipeline behind one seam (ADR-032).
+//
+// `closeUnit` owns what makes a Unit's completion durable. This pass ships the
+// **Interactive Closeout adapter** path: commit the work and compute the
+// Closeout Git Verdict, failing closed (loudly) instead of silently when a
+// non-`none` `git.isolation` preference was never honoured by the session.
+// Motivating failure (2026-06-10): an interactive session under
+// `git.isolation: worktree` completed a milestone with every source file
+// untracked on the integration branch — no commit, no merge, no warning.
+//
+// The interactive adapter only fires on milestone boundaries — the durability
+// gap is the milestone close, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` itself stays general
+// over all boundaries for the pending Auto Closeout adapter re-seat.
+//
+// The auto loop keeps its existing closeout pipeline for now (the Auto
+// Closeout adapter re-seat is the documented next step in ADR-032); the
+// interactive trigger in bootstrap/register-hooks.ts is a no-op while
+// `isAutoActive()`, so auto-mode behaviour is untouched.
+//
+// Re-entrancy is naturally safe: a re-fired completion commits an already-clean
+// tree, which yields `nothing-to-commit`, and `appendNotification` carries its
+// own dedup window — so `closeUnit` keeps no result cache of its own.
+
+import { appendNotification, type NotifySeverity } from "./notification-store.js";
+import { readStringField } from "./auto-unit-tool-scope.js";
+import { MILESTONE_BRANCH_PREFIX } from "./branch-patterns.js";
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { getIsolationMode } from "./preferences.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { logWarning } from "./workflow-logger.js";
+
+export type CloseoutBoundary = "task" | "slice" | "milestone";
+export type CloseoutOutcome = "complete" | "failed" | "skipped";
+
+/**
+ * What git state the closeout found and did.
+ *
+ * - `committed`           — work committed on the current branch (expected under
+ *                           `isolation: none`, and for task/slice boundaries).
+ * - `nothing-to-commit`   — working tree was already clean.
+ * - `milestone-branch`    — milestone boundary closed on a `milestone/<MID>`
+ *                           branch; the merge stays owned by worktree tooling.
+ * - `isolation-bypassed`  — milestone boundary closed outside a milestone
+ *                           worktree/branch while `git.isolation` is
+ *                           `worktree`/`branch`: committed where the work sits
+ *                           and surfaced a Needs Attention notice instead of
+ *                           completing silently.
+ * - `commit-failed`       — the commit attempt threw; surfaced, never thrown.
+ */
+export type CloseoutGitVerdict =
+  | "committed"
+  | "nothing-to-commit"
+  | "milestone-branch"
+  | "isolation-bypassed"
+  | "commit-failed";
+
+export interface UnitCloseoutRequest {
+  basePath: string;
+  unitType: string;
+  /** "M001" | "M001/S01" | "M001/S01/T01" */
+  unitId: string;
+  boundary: CloseoutBoundary;
+  outcome: CloseoutOutcome;
+}
+
+export interface UnitCloseoutResult {
+  gitVerdict: CloseoutGitVerdict;
+  commitMessage: string | null;
+  /** The user-facing Needs Attention / status notice, when one was emitted. */
+  notice?: string;
+}
+
+/** Seam for tests; production callers use the defaults. */
+export interface UnitCloseoutDeps {
+  isolationMode(basePath: string): "none" | "worktree" | "branch";
+  currentBranch(basePath: string): string | null;
+  commit(basePath: string, unitType: string, unitId: string): string | null;
+  notify(message: string, severity: NotifySeverity): void;
+}
+
+const defaultDeps: UnitCloseoutDeps = {
+  isolationMode: (basePath) => getIsolationMode(basePath),
+  currentBranch: (basePath) => {
+    try {
+      return nativeGetCurrentBranch(basePath);
+    } catch {
+      return null;
+    }
+  },
+  commit: (basePath, unitType, unitId) => autoCommitCurrentBranch(basePath, unitType, unitId),
+  notify: (message, severity) => appendNotification(message, severity),
+};
+
+export function closeUnit(request: UnitCloseoutRequest, deps: UnitCloseoutDeps = defaultDeps): UnitCloseoutResult {
+  let commitMessage: string | null = null;
+  let gitVerdict: CloseoutGitVerdict;
+  let notice: string | undefined;
+
+  try {
+    commitMessage = deps.commit(request.basePath, request.unitType, request.unitId);
+    gitVerdict = commitMessage === null ? "nothing-to-commit" : "committed";
+  } catch (err) {
+    gitVerdict = "commit-failed";
+    notice = `Unit closeout commit failed for ${request.unitId}: ${err instanceof Error ? err.message : String(err)}`;
+    logWarning("engine", notice);
+    deps.notify(notice, "error");
+  }
+
+  if (request.boundary === "milestone" && gitVerdict !== "commit-failed") {
+    const isolation = deps.isolationMode(request.basePath);
+    if (isolation !== "none") {
+      const branch = deps.currentBranch(request.basePath);
+      if (branch?.startsWith(MILESTONE_BRANCH_PREFIX)) {
+        gitVerdict = "milestone-branch";
+        notice =
+          `Milestone ${request.unitId} completed on ${branch}. ` +
+          `Merge it to the integration branch with the worktree tooling (/gsd worktree merge).`;
+        deps.notify(notice, "info");
+      } else {
+        gitVerdict = "isolation-bypassed";
+        notice =
+          `Needs attention: milestone ${request.unitId} completed outside a milestone worktree/branch ` +
+          `while git.isolation is "${isolation}" — the isolation preference was not honoured this session. ` +
+          (commitMessage
+            ? `Work was committed directly on "${branch ?? "the current branch"}".`
+            : `The working tree had nothing left to commit on "${branch ?? "the current branch"}".`);
+        logWarning("engine", notice);
+        deps.notify(notice, "warning");
+      }
+    }
+  }
+
+  return { gitVerdict, commitMessage, notice };
+}
+
+// ─── Interactive Closeout adapter (tool-observation trigger) ─────────────
+
+// Canonical closeout tool → boundary. Aliases are canonicalized by the hook.
+// Only the milestone boundary is wired interactively: it is the durability gap
+// that motivated ADR-032, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` still handles every
+// boundary for the pending Auto Closeout adapter re-seat.
+const CLOSEOUT_TOOL_BOUNDARIES: Record<string, CloseoutBoundary> = {
+  gsd_complete_milestone: "milestone",
+};
+
+// Commit attribution uses the canonical unit types so interactive closeout
+// commits carry the same GSD-Unit evidence trailers the verification prompts
+// look for.
+const BOUNDARY_UNIT_TYPES: Record<CloseoutBoundary, string> = {
+  task: "execute-task",
+  slice: "complete-slice",
+  milestone: "complete-milestone",
+};
+
+export function isUnitCloseoutTool(canonicalToolName: string): boolean {
+  return canonicalToolName in CLOSEOUT_TOOL_BOUNDARIES;
+}
+
+function readId(input: unknown, camel: string, snake: string): string | undefined {
+  const value = readStringField(input, camel, snake);
+  return value && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Interactive Closeout adapter entry, called from the host's tool-observation
+ * hook for successful closeout tool calls when auto-mode is NOT active.
+ * Returns null when the tool input doesn't identify a unit.
+ */
+export function runInteractiveUnitCloseout(
+  args: { basePath: string; canonicalToolName: string; input: unknown },
+  deps: UnitCloseoutDeps = defaultDeps,
+): UnitCloseoutResult | null {
+  const boundary = CLOSEOUT_TOOL_BOUNDARIES[args.canonicalToolName];
+  if (!boundary) return null;
+
+  const milestoneId = readId(args.input, "milestoneId", "milestone_id");
+  if (!milestoneId) return null;
+  const sliceId = readId(args.input, "sliceId", "slice_id");
+  const taskId = readId(args.input, "taskId", "task_id");
+
+  let unitId = milestoneId;
+  if (boundary !== "milestone") {
+    if (!sliceId) return null;
+    unitId = boundary === "slice" ? `${milestoneId}/${sliceId}` : `${milestoneId}/${sliceId}/${taskId ?? ""}`;
+    if (boundary === "task" && !taskId) return null;
+  }
+
+  return closeUnit(
+    {
+      basePath: args.basePath,
+      unitType: BOUNDARY_UNIT_TYPES[boundary],
+      unitId,
+      boundary,
+      outcome: "complete",
+    },
+    deps,
+  );
+}