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

package/src/resources/extensions/gsd/tests/write-gate-seam.test.ts

@@ -0,0 +1,358 @@
+// gsd-pi - Write-gate two-process seam tests.
+/**
+ * Deterministic interleaving tests for the host/child write-gate adapters
+ * (write-gate.ts). The "child" (workflow MCP server) runs in a separate
+ * process in production; these tests simulate its writes by stamping the
+ * snapshot file directly, exactly as childWriteGateAdapter persists it.
+ *
+ * Covered interleavings:
+ *   (a) child verifies on disk while the host holds stale memory — the host
+ *       re-arm must NOT clobber the verification, on BOTH windows
+ *       (tool_execution_start re-arm and the tool_call defer path);
+ *   (b) concurrent writes: every persist is an unconditional read-merge-write
+ *       (read disk → union-merge → mutate → atomic rename), so a write the
+ *       other process landed in between is folded in, never overwritten;
+ *   (c) two basePaths defer approval gates in the same process — both stay
+ *       deferred and both activate (regression for the old single global slot);
+ *   (d) old snapshot files (including ones carrying the retired epoch field)
+ *       keep loading; stale fields are dropped on the next write.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import {
+  childWriteGateAdapter,
+  clearDiscussionFlowState,
+  getPendingGate,
+  hostWriteGateAdapter,
+  loadWriteGateSnapshot,
+  markDepthVerified,
+  refreshWriteGateStateFromDisk,
+  setPendingGate,
+  type WriteGateSnapshot,
+} from "../bootstrap/write-gate.ts";
+
+function makeTempDir(prefix: string): string {
+  const dir = join(
+    tmpdir(),
+    `gsd-write-gate-seam-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function snapshotPath(basePath: string): string {
+  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+}
+
+/** Simulate a write from the OTHER process by stamping the file directly. */
+function foreignProcessWrites(basePath: string, snapshot: Partial<WriteGateSnapshot>): void {
+  mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(snapshotPath(basePath), JSON.stringify({
+    verifiedDepthMilestones: [],
+    verifiedApprovalGates: [],
+    activeQueuePhase: false,
+    pendingGateId: null,
+    ...snapshot,
+  }, null, 2), "utf-8");
+}
+
+function readDiskRaw(basePath: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(snapshotPath(basePath), "utf-8"));
+}
+
+function makeHookHarness(): {
+  handlers: Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>;
+  pi: any;
+} {
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+  return { handlers, pi };
+}
+
+function cleanup(dir: string): void {
+  clearDiscussionFlowState(dir);
+  rmSync(dir, { recursive: true, force: true });
+}
+
+const GATE = "depth_verification_M007_confirm";
+
+// ── (a) verified-on-disk wins over a host re-arm ────────────────────────────
+
+test("seam: host setPending does not clobber a child verification on disk", (t) => {
+  const dir = makeTempDir("no-clobber-adapter");
+  t.after(() => cleanup(dir));
+
+  // Host has stale memory: it armed the gate earlier (persisted to disk).
+  assert.equal(setPendingGate(GATE, dir), true, "fresh gate must arm");
+  assert.equal(getPendingGate(dir), GATE);
+
+  // Child verifies the gate in its own process (newer write on disk).
+  foreignProcessWrites(dir, {
+    verifiedDepthMilestones: ["M007"],
+    verifiedApprovalGates: [GATE],
+    writer: "child",
+  });
+
+  // Host attempts a re-arm — adapter policy: verified on disk wins.
+  assert.equal(hostWriteGateAdapter.setPending(GATE, dir), false, "re-arm must be suppressed");
+  const snapshot = loadWriteGateSnapshot(dir);
+  assert.ok(snapshot.verifiedDepthMilestones.includes("M007"), "verification must survive");
+  assert.ok((snapshot.verifiedApprovalGates ?? []).includes(GATE));
+  assert.equal(getPendingGate(dir), null, "no pending gate after suppressed re-arm");
+});
+
+test("seam: tool_call defer path does not block tools for a gate the child verified", async (t) => {
+  const dir = makeTempDir("no-clobber-defer");
+  t.after(() => cleanup(dir));
+
+  // Child verified the gate before the host ever saw the tool block.
+  foreignProcessWrites(dir, {
+    verifiedDepthMilestones: ["M007"],
+    verifiedApprovalGates: [GATE],
+    writer: "child",
+  });
+
+  const { handlers, pi } = makeHookHarness();
+  registerHooks(pi, []);
+  const ctx = { cwd: dir, ui: { notify: () => undefined } } as any;
+
+  // tool_call defer window: ask_user_questions arrives post-hoc with the gate id.
+  for (const handler of handlers.get("tool_call") ?? []) {
+    await handler({
+      toolCallId: "t-gate",
+      toolName: "ask_user_questions",
+      input: { questions: [{ id: GATE }] },
+    }, ctx);
+  }
+
+  // A subsequent tool in the same turn must NOT hit the deferred-gate block.
+  let blocked: any;
+  for (const handler of handlers.get("tool_call") ?? []) {
+    const result = await handler({
+      toolCallId: "t-next",
+      toolName: "glob",
+      input: { pattern: "*.md" },
+    }, ctx);
+    if (result?.block) blocked = result;
+  }
+  assert.equal(blocked, undefined, "verified gate must not be deferred/blocking");
+  assert.equal(getPendingGate(dir), null);
+  const snapshot = loadWriteGateSnapshot(dir);
+  assert.ok(snapshot.verifiedDepthMilestones.includes("M007"), "verification must survive the defer window");
+});
+
+test("seam: tool_execution_start re-arm window keeps the child verification", async (t) => {
+  const dir = makeTempDir("no-clobber-exec-start");
+  t.after(() => cleanup(dir));
+
+  foreignProcessWrites(dir, {
+    verifiedDepthMilestones: ["M007"],
+    verifiedApprovalGates: [GATE],
+    writer: "child",
+  });
+
+  const { handlers, pi } = makeHookHarness();
+  registerHooks(pi, []);
+  const ctx = { cwd: dir, ui: { notify: () => undefined } } as any;
+
+  for (const handler of handlers.get("tool_execution_start") ?? []) {
+    await handler({
+      toolCallId: "t-gate",
+      toolName: "mcp__gsd-workflow__ask_user_questions",
+      args: { questions: [{ id: GATE }] },
+    }, ctx);
+  }
+
+  assert.equal(getPendingGate(dir), null, "post-hoc replay must not re-arm a verified gate");
+  assert.ok(loadWriteGateSnapshot(dir).verifiedDepthMilestones.includes("M007"));
+});
+
+// ── (b) concurrent writes re-merge instead of overwriting ───────────────────
+
+test("seam: host persist re-merges a concurrent child write (unconditional read-merge-write)", (t) => {
+  const dir = makeTempDir("concurrent-write");
+  t.after(() => cleanup(dir));
+
+  // Host persists its own verification.
+  markDepthVerified("M001", dir);
+
+  // Child lands a different verification on disk while the host is idle.
+  foreignProcessWrites(dir, {
+    verifiedDepthMilestones: ["M002"],
+    writer: "child",
+  });
+
+  // Host persists again — every mutation re-reads the disk snapshot and
+  // union-merges before writing, so the child's verification survives.
+  markDepthVerified("M003", dir);
+  const merged = loadWriteGateSnapshot(dir);
+  assert.deepEqual(merged.verifiedDepthMilestones, ["M001", "M002", "M003"]);
+  assert.equal(readDiskRaw(dir).writer, "host");
+});
+
+test("seam: missing snapshot resets stale in-memory pending gate before mutation", (t) => {
+  const dir = makeTempDir("missing-snapshot-reset");
+  t.after(() => cleanup(dir));
+
+  assert.equal(setPendingGate(GATE, dir), true);
+  rmSync(snapshotPath(dir), { force: true });
+
+  markDepthVerified("M008", dir);
+
+  const snapshot = loadWriteGateSnapshot(dir);
+  assert.equal(snapshot.pendingGateId, null);
+  assert.deepEqual(snapshot.verifiedDepthMilestones, ["M008"]);
+  assert.equal(readDiskRaw(dir).pendingGateId, null);
+});
+
+test("seam: childWriteGateAdapter is write-through and stamps writer provenance", (t) => {
+  const dir = makeTempDir("child-write-through");
+  t.after(() => cleanup(dir));
+
+  foreignProcessWrites(dir, { verifiedDepthMilestones: ["M001"], writer: "host" });
+  childWriteGateAdapter.markDepthVerified("M002", dir);
+
+  const disk = readDiskRaw(dir);
+  assert.deepEqual(disk.verifiedDepthMilestones, ["M001", "M002"], "fresh disk read, then mutate");
+  assert.equal(disk.writer, "child");
+});
+
+// ── (c) per-basePath deferred gates ──────────────────────────────────────────
+
+test("seam: two basePaths defer gates in one process and both activate", async (t) => {
+  const dirA = makeTempDir("defer-a");
+  const dirB = makeTempDir("defer-b");
+  t.after(() => {
+    cleanup(dirA);
+    cleanup(dirB);
+  });
+
+  const { handlers, pi } = makeHookHarness();
+  registerHooks(pi, []);
+  const gateA = "depth_verification_M010_confirm";
+  const gateB = "depth_verification_M020_confirm";
+  const ctxA = { cwd: dirA, ui: { notify: () => undefined } } as any;
+  const ctxB = { cwd: dirB, ui: { notify: () => undefined } } as any;
+
+  for (const handler of handlers.get("tool_call") ?? []) {
+    await handler({ toolCallId: "a-1", toolName: "ask_user_questions", input: { questions: [{ id: gateA }] } }, ctxA);
+  }
+  for (const handler of handlers.get("tool_call") ?? []) {
+    await handler({ toolCallId: "b-1", toolName: "ask_user_questions", input: { questions: [{ id: gateB }] } }, ctxB);
+  }
+
+  // With the old single global slot, project A's deferral was lost the moment
+  // project B deferred. Both must still block follow-up tools.
+  for (const [ctx, label] of [[ctxA, "A"], [ctxB, "B"]] as const) {
+    let blocked: any;
+    for (const handler of handlers.get("tool_call") ?? []) {
+      const result = await handler({ toolCallId: `chk-${label}`, toolName: "glob", input: { pattern: "*" } }, ctx);
+      if (result?.block) blocked = result;
+    }
+    assert.equal(blocked?.block, true, `project ${label} deferred gate must still block`);
+    assert.match(blocked?.reason ?? "", /Approval question/);
+  }
+
+  // Activation happens via tool_execution_start in each project independently.
+  for (const [ctx, gate, dir] of [[ctxA, gateA, dirA], [ctxB, gateB, dirB]] as const) {
+    for (const handler of handlers.get("tool_execution_start") ?? []) {
+      await handler({ toolCallId: "act", toolName: "ask_user_questions", args: { questions: [{ id: gate }] } }, ctx);
+    }
+    assert.equal(getPendingGate(dir), gate, `gate must arm durably for ${dir}`);
+  }
+});
+
+// ── (d) backward compatibility: legacy snapshot fields ──────────────────────
+
+test("seam: old snapshot with a retired epoch field loads and sheds it on write", (t) => {
+  const dir = makeTempDir("legacy-snapshot");
+  t.after(() => cleanup(dir));
+
+  writeFileSync(
+    (mkdirSync(join(dir, ".gsd", "runtime"), { recursive: true }), snapshotPath(dir)),
+    JSON.stringify({
+      verifiedDepthMilestones: ["M001"],
+      verifiedApprovalGates: ["depth_verification_M001_confirm"],
+      activeQueuePhase: false,
+      pendingGateId: null,
+      // Written by an older build that still stamped the write-only epoch.
+      epoch: 7,
+    }),
+    "utf-8",
+  );
+
+  const loaded = loadWriteGateSnapshot(dir);
+  assert.deepEqual(loaded.verifiedDepthMilestones, ["M001"]);
+  assert.equal("epoch" in loaded, false, "retired epoch field is not surfaced");
+
+  const refreshed = refreshWriteGateStateFromDisk(dir);
+  assert.ok(refreshed.verifiedDepthMilestones.includes("M001"));
+
+  markDepthVerified("M002", dir);
+  const upgraded = readDiskRaw(dir);
+  assert.deepEqual(upgraded.verifiedDepthMilestones, ["M001", "M002"]);
+  assert.equal("epoch" in upgraded, false, "retired epoch field is dropped on rewrite");
+  assert.equal(upgraded.writer, "host");
+});
+
+// ── (e) corrupt snapshot is treated as a reset (matches "delete the file") ──
+
+test("seam: corrupt snapshot file resets host state instead of persisting stale pendingGateId", (t) => {
+  const dir = makeTempDir("corrupt-snapshot");
+  t.after(() => cleanup(dir));
+
+  // Host arms a gate; stale pendingGateId now lives in memory and on disk.
+  assert.equal(setPendingGate(GATE, dir), true);
+  assert.equal(getPendingGate(dir), GATE);
+
+  // The snapshot file is corrupted out-of-band (e.g. partial write from a
+  // crashed editor, foreign tool, or filesystem fault).
+  writeFileSync(snapshotPath(dir), "{ not json", "utf-8");
+
+  // refreshWriteGateStateFromDisk must treat the unreadable file the same
+  // as a missing file: full reset, including dropping the stale pending id.
+  const refreshed = refreshWriteGateStateFromDisk(dir);
+  assert.equal(refreshed.pendingGateId, null, "stale pendingGateId must not survive a corrupt snapshot");
+  assert.deepEqual(refreshed.verifiedDepthMilestones, []);
+  assert.deepEqual(refreshed.verifiedApprovalGates, []);
+  assert.equal(getPendingGate(dir), null);
+
+  // A subsequent mutation must not write the stale gate back to disk.
+  markDepthVerified("M042", dir);
+  const persisted = readDiskRaw(dir);
+  assert.equal(persisted.pendingGateId, null, "next persist must not re-stamp the stale pending id");
+  assert.deepEqual(persisted.verifiedDepthMilestones, ["M042"]);
+});
+
+test("seam: mutateWriteGateState reset path drops stale pendingGateId on a corrupt snapshot", (t) => {
+  const dir = makeTempDir("corrupt-snapshot-mutate");
+  t.after(() => cleanup(dir));
+
+  // Host arms a gate first.
+  assert.equal(setPendingGate(GATE, dir), true);
+
+  // Corrupt the snapshot directly (skipping the refresh path so we exercise
+  // the reconcile-on-mutate branch in mutateWriteGateState).
+  writeFileSync(snapshotPath(dir), "}}}", "utf-8");
+
+  // markDepthVerified runs through mutateWriteGateState; the reconcile pass
+  // must reset the in-memory state when the disk read returns null, even
+  // though the file still exists on disk.
+  markDepthVerified("M099", dir);
+
+  const persisted = readDiskRaw(dir);
+  assert.equal(persisted.pendingGateId, null, "stale pending id must not be persisted after a corrupt-snapshot reconcile");
+  assert.deepEqual(persisted.verifiedDepthMilestones, ["M099"]);
+});

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -24,6 +24,7 @@ import {
   setQueuePhaseActive,
 } from '../index.ts';
 import {
+  childWriteGateAdapter,
   markDepthVerified,
   isMilestoneDepthVerified,
   markApprovalGateVerified,
@@ -317,7 +318,11 @@ test('write-gate: reopening a gate revokes its previous verified approval', () =
       'precondition: verified approval unlocks the final project artifact',
     );
 
-    setPendingGate('depth_verification_project_confirm', base);
+    // A genuine re-ask originates from the workflow MCP child (where
+    // ask_user_questions executes): the child adapter arms unconditionally,
+    // revoking the prior approval. Host-side setPendingGate is guarded
+    // (verified-on-disk wins) and would deliberately suppress this arm.
+    childWriteGateAdapter.setPending('depth_verification_project_confirm', base);
     clearPendingGate(base);
 
     assert.strictEqual(
@@ -458,6 +463,66 @@ test('write-gate: applyAskUserQuestionsGateResult verifies confirmed pending gat
   }
 });
 
+test('write-gate: applyAskUserQuestionsGateResult reports declined pending gate (consent-verdict semantics)', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-declined-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: { answers: { [gateId]: { selected: 'Needs adjustment' } } },
+      },
+    });
+
+    assert.deepEqual(result, { status: 'declined', gateId });
+    assert.strictEqual(getPendingGate(base), gateId, 'declined gate must stay pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'declined gate must not verify depth');
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: applyAskUserQuestionsGateResult keeps empty-selection pending gate waiting (consent-verdict semantics)', () => {
+  // An empty selection is never an answer (fail-closed): the round used to
+  // report "answered" here, silently treating a missing selection as resolved.
+  const base = join(tmpdir(), `gsd-write-gate-ask-empty-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: { answers: { [gateId]: { selected: '' } } },
+      },
+    });
+
+    assert.deepEqual(result, { status: 'waiting', pendingGateId: gateId, interrupted: false });
+    assert.strictEqual(getPendingGate(base), gateId, 'unanswered gate must stay pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'unanswered gate must not verify depth');
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ─── Scenario 21: shouldBlockPendingGate blocks non-safe tools when gate is pending ──
 
 test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate', () => {
@@ -789,6 +854,7 @@ test('write-gate: resetWriteGateState persists through dangling .gsd symlink', (
       verifiedApprovalGates: [],
       activeQueuePhase: false,
       pendingGateId: null,
+      writer: 'host',
     });
   } finally {
     if (originalEnv === undefined) {

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -10,7 +10,7 @@ import {
 import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
 import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
-import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -66,9 +66,9 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "Grep",
 ] as const;
 
-export function canonicalWorkflowToolName(toolName: string): string {
-  return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
 
 export { parseMcpToolName } from "./mcp-tool-name.js";
 

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/complete-slice.ts

@@ -26,10 +26,9 @@ import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../path
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
-import { getDeclaredUatType, shouldEscalateArtifactUatToBrowser } from "../uat-policy.js";
+import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy.js";
 import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { parseRoadmap } from "../parsers-legacy.js";
+import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
@@ -91,9 +90,11 @@ function hasCompleteSliceArtifactContract(basePath: string, milestoneId: string,
     join(gsdProjectionRoot(basePath), "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
   if (!existsSync(roadmapPath)) return false;
 
+  // Projection-completeness check (ADR-017): the DB has already recorded the
+  // duplicate completion; this only verifies the rendered markdown artifacts
+  // exist and reflect it, deciding whether re-rendering is needed.
   try {
-    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    return roadmap.slices.some((slice) => slice.id === sliceId && slice.done);
+    return roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sliceId);
   } catch {
     return false;
   }
@@ -355,10 +356,18 @@ export async function handleCompleteSlice(
   // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
   // browser-executable receive browser tools (UAT_MODE_POLICIES).
   const uatContent = params.uatContent || "";
-  const declaredUatMode = getDeclaredUatType(uatContent);
-  if (shouldEscalateArtifactUatToBrowser(uatContent)) {
+  const uatPolicy = classifyUatContent(uatContent);
+  if (escalatesArtifactUatToBrowser(uatPolicy)) {
+    // Distinguish an explicit artifact-driven declaration from a missing or
+    // unparseable one that merely *defaulted* to artifact-driven — telling an
+    // agent it "declared artifact-driven" when its declaration simply failed
+    // to parse sends it into a rewrite loop with the same unparseable format.
+    const staticOnlyClause = `which only runs static/file checks and would defer the browser work to a human`;
+    const modeClause = uatPolicy.modeDeclared
+      ? `declares "UAT mode: artifact-driven", ${staticOnlyClause}`
+      : `has no parseable UAT mode declaration in its "## UAT Type" section (the declaration must be a bullet exactly like "- UAT mode: browser-executable"), so it defaults to "artifact-driven", ${staticOnlyClause}`;
     return {
-      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but ${modeClause}. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
     };
   }
 
@@ -470,8 +479,9 @@ export async function handleCompleteSlice(
 
     const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
     clearParseCache();
-    const roadmapSlice = parseRoadmap(roadmap.content).slices.find((slice) => slice.id === params.sliceId);
-    if (!roadmapSlice?.done) {
+    // Render verification (ADR-017): confirms the just-written projection
+    // reflects the DB completion; the DB row is already committed.
+    if (!roadmapRenderMarksSliceDone(roadmap.content, params.sliceId)) {
       throw new Error(`roadmap render did not mark ${params.milestoneId}/${params.sliceId} complete`);
     }
   } catch (renderErr) {

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";