@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.9f86580

package/dist/resources/extensions/gsd/context-masker.js

@@ -5,13 +5,36 @@
  * Reduces context bloat between compactions with zero LLM overhead.
  * Preserves message ordering, roles, and all assistant/user messages.
  *
- * Operates on the pi-ai Message[] format (post-convertToLlm, pre-provider):
+ * Operates on provider payloads after convertToLlm:
+ *
+ * pi-ai Message[] payloads:
  *   - toolResult messages: { role: "toolResult", content: TextContent[] }
  *   - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] }
  *     and start with "Ran `" from bashExecutionToText.
+ *
+ * OpenAI/Codex Responses payloads:
+ *   - conversation items live in `input`, not `messages`
+ *   - tool results are { type: "function_call_output", output: string | content[] }
+ *   - bash results are user items with input_text content starting with "Ran `"
  */
 const MASK_PLACEHOLDER = "[result masked — within summarized history]";
 const MASK_CONTENT_BLOCK = [{ type: "text", text: MASK_PLACEHOLDER }];
+const RESPONSES_MASK_CONTENT_BLOCK = [{ type: "input_text", text: MASK_PLACEHOLDER }];
+const TRUNCATION_MARKER = "\n…[truncated]";
+function isTextLikeBlock(block) {
+    return Boolean(block && typeof block === "object" && "text" in block);
+}
+function firstTextFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const first = content.find(isTextLikeBlock);
+    return typeof first?.text === "string" ? first.text : undefined;
+}
+function isBashResultText(text) {
+    return typeof text === "string" && text.startsWith("Ran `");
+}
 function findTurnBoundary(messages, keepRecentTurns) {
     let turnsSeen = 0;
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -35,11 +58,9 @@ function findTurnBoundary(messages, keepRecentTurns) {
  * The bashExecutionToText format always starts with "Ran `".
  */
 function isBashResultUserMessage(m) {
-    if (m.role !== "user" || !Array.isArray(m.content))
+    if (m.role !== "user")
         return false;
-    const first = m.content[0];
-    return first && typeof first === "object" && "text" in first &&
-        typeof first.text === "string" && first.text.startsWith("Ran `");
+    return isBashResultText(firstTextFromContent(m.content));
 }
 function isMaskableMessage(m) {
     // Tool result messages (role: "toolResult" in pi-ai format)
@@ -66,3 +87,106 @@ export function createObservationMask(keepRecentTurns = 8) {
         });
     };
 }
+function isResponsesBashResultUserItem(item) {
+    if (item.role !== "user")
+        return false;
+    return isBashResultText(firstTextFromContent(item.content));
+}
+function findResponsesTurnBoundary(items, keepRecentTurns) {
+    let turnsSeen = 0;
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (item.role === "user" && !isResponsesBashResultUserItem(item)) {
+            turnsSeen++;
+            if (turnsSeen >= keepRecentTurns)
+                return i;
+        }
+    }
+    return 0;
+}
+/**
+ * Observation masking for OpenAI/Codex Responses API payloads.
+ *
+ * Responses payloads store the conversation under `input` instead of
+ * `messages`, with tool results as `function_call_output` items. Keep this
+ * separate from createObservationMask so each payload shape stays explicit.
+ */
+export function createResponsesInputObservationMask(keepRecentTurns = 8) {
+    return (items) => {
+        const boundary = findResponsesTurnBoundary(items, keepRecentTurns);
+        if (boundary === 0)
+            return items;
+        return items.map((item, i) => {
+            if (i >= boundary)
+                return item;
+            if (item.type === "function_call_output") {
+                return { ...item, output: MASK_PLACEHOLDER };
+            }
+            if (isResponsesBashResultUserItem(item)) {
+                return { ...item, content: RESPONSES_MASK_CONTENT_BLOCK };
+            }
+            return item;
+        });
+    };
+}
+function truncateText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars) + TRUNCATION_MARKER;
+}
+function truncateTextBlocks(content, maxChars) {
+    if (typeof content === "string") {
+        return truncateText(content, maxChars);
+    }
+    if (!Array.isArray(content))
+        return content;
+    let remaining = maxChars;
+    let didTruncate = false;
+    const nextBlocks = [];
+    for (const block of content) {
+        if (!isTextLikeBlock(block) || typeof block.text !== "string") {
+            nextBlocks.push(block);
+            continue;
+        }
+        if (remaining <= 0) {
+            didTruncate = true;
+            continue;
+        }
+        const text = block.text;
+        if (text.length <= remaining) {
+            nextBlocks.push(block);
+            remaining -= text.length;
+            continue;
+        }
+        nextBlocks.push({ ...block, text: truncateText(text, remaining) });
+        remaining = 0;
+        didTruncate = true;
+    }
+    return didTruncate ? nextBlocks : content;
+}
+function normalizedMaxChars(maxChars) {
+    return Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : 800;
+}
+export function truncateContextResultMessages(messages, maxChars = 800) {
+    const limit = normalizedMaxChars(maxChars);
+    return messages.map((message) => {
+        if (!isMaskableMessage(message))
+            return message;
+        const content = truncateTextBlocks(message.content, limit);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+export function truncateResponsesInputResultItems(items, maxChars = 800) {
+    const limit = normalizedMaxChars(maxChars);
+    return items.map((item) => {
+        if (item.type === "function_call_output") {
+            const output = truncateTextBlocks(item.output, limit);
+            return output === item.output ? item : { ...item, output };
+        }
+        if (isResponsesBashResultUserItem(item)) {
+            const content = truncateTextBlocks(item.content, limit);
+            return content === item.content ? item : { ...item, content };
+        }
+        return item;
+    });
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -178,6 +178,84 @@ export function _roadmapHasParseableSlicesForTest(roadmapContent) {
         return false;
     return parseRoadmapSlices(roadmapContent).length > 0;
 }
+function hasExecutablePlanForHandoff(milestoneId, roadmapFile) {
+    if (isDbAvailable()) {
+        return getMilestoneSlices(milestoneId).length > 0;
+    }
+    if (!roadmapFile)
+        return false;
+    try {
+        return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length > 0;
+    }
+    catch (e) {
+        logWarning("guided", `failed to parse roadmap slices for ${milestoneId}: ${e.message}`);
+        return false;
+    }
+}
+function formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan) {
+    if (hasExecutablePlan)
+        return `Milestone ${milestoneId} ready.`;
+    if (contextFile)
+        return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+    return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}
+function manifestContainsMilestone(basePath, milestoneId) {
+    try {
+        const manifest = readManifest(basePath);
+        return (Array.isArray(manifest?.milestones) &&
+            manifest.milestones.some(m => m.id === milestoneId));
+    }
+    catch (e) {
+        logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
+        return false;
+    }
+}
+function notifyDbRowRecoveryFailed(entry) {
+    entry.ctx.ui.notify(`Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
+}
+function noteDbRowRecoveryMiss(entry) {
+    entry.r3bRecoveryCount += 1;
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        notifyDbRowRecoveryFailed(entry);
+    }
+}
+function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
+    if (!isDbAvailable())
+        return true;
+    const { basePath, milestoneId } = entry;
+    const milestoneRow = getMilestone(milestoneId);
+    if (milestoneRow)
+        return true;
+    if (manifestContainsMilestone(basePath, milestoneId)) {
+        logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
+        return true;
+    }
+    if (!contextFile) {
+        entry.ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+            `PROJECT.md may have failed to register milestones. ` +
+            `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+            `then re-run /gsd to recover.`, "error");
+        return false;
+    }
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+            `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`);
+        return false;
+    }
+    logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+        `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`);
+    try {
+        insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    }
+    catch (e) {
+        logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
+    }
+    if (getMilestone(milestoneId))
+        return true;
+    noteDbRowRecoveryMiss(entry);
+    return false;
+}
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
 function buildDocsCommitInstruction(_message) {
@@ -186,10 +264,8 @@ function buildDocsCommitInstruction(_message) {
 // #4573: cap for how many times we nudge the LLM after a premature ready
 // phrase before giving up and asking the user to re-run /gsd.
 const MAX_READY_REJECTS = 2;
-// H1 (#5012): cap for Gate 1b plan-blocked recovery hints. After this many
-// consecutive recovery attempts the loop is stopped and the user is directed
-// to investigate manually.
-const MAX_PLAN_BLOCKED_RECOVERIES = 3;
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
 // #4573: matches the canonical ready phrase the discuss prompt asks the LLM
 // to emit. Accepts any M-prefixed milestone ID (three digits + optional
 // suffix) with optional trailing punctuation.
@@ -420,56 +496,12 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             return false;
         }
     }
-    // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
-    // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
-    // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
-    // depth-verification gate.  Emit a recovery hint so the next agent turn can retry
-    // gsd_plan_milestone, then return false (keep blocking auto-start).
-    // If CONTEXT.md does not exist (discuss-incomplete), Gate 1 already blocked above.
-    if (isDbAvailable()) {
-        const dbRow = getMilestone(milestoneId);
-        if (dbRow?.status === "queued" && contextFile) {
-            if (entry.planBlockedRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-                // H1: recovery loop cap reached — stop triggering new turns, escalate to user.
-                logWarning("guided", `Gate 1b: milestone ${milestoneId} plan-blocked recovery limit reached ` +
-                    `(${entry.planBlockedRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
-                ctx.ui.notify(`Milestone ${milestoneId} plan_milestone has been blocked ${entry.planBlockedRecoveryCount} times. ` +
-                    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
-                return false;
-            }
-            logWarning("guided", `Gate 1b: milestone ${milestoneId} queued with CONTEXT.md present — ` +
-                `plan_milestone was blocked; emitting recovery hint ` +
-                `(attempt ${entry.planBlockedRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
-            ctx.ui.notify(`Milestone ${milestoneId}: context file exists but milestone is still queued. ` +
-                `Retrying gsd_plan_milestone to complete the blocked planning step.`, "warning");
-            try {
-                pi.sendMessage({
-                    customType: "gsd-plan-milestone-blocked-recovery",
-                    content: `Milestone ${milestoneId} has ${contextFile} on disk but its DB row is still ` +
-                        `"queued". The gsd_plan_milestone tool was previously blocked by the ` +
-                        `depth-verification gate. Call gsd_plan_milestone now to complete the ` +
-                        `planning phase.`,
-                    display: false,
-                }, { triggerTurn: true });
-                // Increment only after a successful dispatch so transient sendMessage
-                // failures do not consume recovery budget.
-                entry.planBlockedRecoveryCount += 1;
-            }
-            catch (e) {
-                logWarning("guided", `Gate 1b recovery sendMessage failed: ${e.message}`);
-            }
-            return false;
-        }
-    }
-    // Gate 2: STATE.md must exist — written as the last step in the discuss
-    // output phase. This prevents auto-start from firing during Phase 3
-    // (sequential readiness gates for remaining milestones) in multi-milestone
-    // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been
-    // processed yet.
-    const stateFilePath = entry.scope.stateFile();
-    if (!existsSync(stateFilePath))
-        return false; // discussion not finalized yet
-    // Gate 3: Multi-milestone completeness warning
+    // Gate 1b: accept the in-flight discuss handoff. A queued DB row with pinned
+    // CONTEXT.md is Discussion Complete, Planning Pending, not a plan-blocked
+    // failure. If the row is missing, only this pending handoff may repair it.
+    if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile))
+        return false;
+    // Gate 2: Multi-milestone completeness warning
     // Parse PROJECT.md for milestone sequence, warn if any are missing context.
     // Don't block — milestones can be intentionally queued without context.
     const projectFile = resolveGsdRootFile(basePath, "PROJECT");
@@ -495,7 +527,7 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             logWarning("guided", `PROJECT.md parsing failed: ${e.message}`);
         }
     }
-    // Gate 4: Discussion manifest process verification (multi-milestone only)
+    // Gate 3: Discussion manifest process verification (multi-milestone only)
     // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
     // When it exists, validate it before auto-starting. Project history alone is
     // not a reliable signal for the current discussion mode.
@@ -541,59 +573,9 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             logWarning("guided", `manifest unlink failed: ${e.message}`);
         }
     }
-    // R3b: belt-and-suspenders for silent registration failure. The discuss flow
-    // finished and STATE.md exists, but the milestone may never have landed in
-    // the DB. Without this guard, the user sees "Milestone M001 ready." and then
-    // /gsd reports "No Active Milestone".
-    if (isDbAvailable()) {
-        const milestoneRow = getMilestone(milestoneId);
-        if (!milestoneRow) {
-            let manifestHasMilestone = false;
-            try {
-                const manifest = readManifest(basePath);
-                manifestHasMilestone = Array.isArray(manifest?.milestones) && manifest.milestones.some(m => m.id === milestoneId);
-            }
-            catch (e) {
-                logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
-            }
-            if (manifestHasMilestone) {
-                logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
-            }
-            else if (contextFile) {
-                // R3b-recovery: CONTEXT.md is on disk but gsd_plan_milestone was never called
-                // (likely blocked by the depth-verification gate re-firing on post-verification
-                // text). Auto-register as "queued" so Gate 1b can pick it up and retry
-                // gsd_plan_milestone on the next checkAutoStartAfterDiscuss call.
-                if (entry.r3bRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-                    logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
-                        `(${entry.r3bRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
-                    ctx.ui.notify(`Milestone ${milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
-                        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
-                    return false;
-                }
-                logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
-                    `for Gate 1b recovery (attempt ${entry.r3bRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
-                try {
-                    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
-                }
-                catch (e) {
-                    logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
-                }
-                entry.r3bRecoveryCount += 1;
-                ctx.ui.notify(`Milestone ${milestoneId}: context file exists but DB row was missing — recovering. Retrying gsd_plan_milestone.`, "warning");
-                return false;
-            }
-            else {
-                ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
-                    `PROJECT.md may have failed to register milestones. ` +
-                    `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
-                    `then re-run /gsd to recover.`, "error");
-                return false;
-            }
-        }
-    }
     deletePendingAutoStart(basePath);
-    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
+    const hasExecutablePlan = hasExecutablePlanForHandoff(milestoneId, roadmapFile);
+    ctx.ui.notify(formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan), "success");
     if (entry.startAuto !== false) {
         scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
     }
@@ -883,7 +865,10 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                     ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
                     : undefined,
             baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-            activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+            // Guided flow starts the MCP workflow server as part of dispatch, so the
+            // parent session's activeTools doesn't include MCP tools yet. The MCP
+            // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+            // here — not whether MCP tools are pre-registered in the parent session.
         });
         if (compatibilityError) {
             ctx.ui.notify(compatibilityError, "error");

package/dist/resources/extensions/gsd/milestone-closeout.js

@@ -15,6 +15,7 @@ import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
@@ -28,7 +29,8 @@ export async function isMilestoneCloseoutSettled(mid, basePath) {
         if (isDbAvailable()) {
             const milestone = getMilestone(mid);
             if (milestone && isClosedStatus(milestone.status)) {
-                if (verifyExpectedArtifact("complete-milestone", mid, basePath)) {
+                const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+                if (closeoutGate.ok && verifyExpectedArtifact("complete-milestone", mid, basePath)) {
                     return true;
                 }
             }

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

@@ -23,7 +23,6 @@ export function setPendingAutoStart(basePath, entry) {
     const scope = scopeMilestone(ws, entry.milestoneId);
     pendingAutoStartMap.set(basePath, {
         createdAt: Date.now(),
-        planBlockedRecoveryCount: 0,
         r3bRecoveryCount: 0,
         ...entry,
         scope,

package/dist/resources/extensions/gsd/planner-handoff.js

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Optional gsd-planner handoff after milestone planning.
+import { spawn as spawnChild } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+export const PLANNER_HANDOFF_RULE_NAME = "planning review handoff -> gsd-planner";
+export const GSD_PLANNER_COMMAND = "gsd-planner";
+function handoffDir(basePath) {
+    return join(gsdRoot(basePath), "runtime", "planner-handoffs");
+}
+function safeMilestoneFileSegment(milestoneId) {
+    return milestoneId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown";
+}
+function handoffMarkerPath(basePath, milestoneId) {
+    return join(handoffDir(basePath), `${safeMilestoneFileSegment(milestoneId)}.json`);
+}
+export function hasPlannerHandoffBeenOffered(basePath, milestoneId) {
+    return existsSync(handoffMarkerPath(basePath, milestoneId));
+}
+export function markPlannerHandoffOffered(basePath, milestoneId, source = "auto") {
+    mkdirSync(handoffDir(basePath), { recursive: true });
+    writeFileSync(handoffMarkerPath(basePath, milestoneId), JSON.stringify({
+        milestoneId,
+        source,
+        offeredAt: new Date().toISOString(),
+    }, null, 2) + "\n", "utf-8");
+}
+export function buildGsdPlannerSpawnPlan(input) {
+    const args = ["--project", input.basePath];
+    const milestoneId = input.milestoneId?.trim();
+    if (milestoneId)
+        args.push("--milestone", milestoneId);
+    args.push(...(input.extraArgs ?? []));
+    return {
+        command: GSD_PLANNER_COMMAND,
+        args,
+        cwd: input.basePath,
+    };
+}
+function quoteArg(arg) {
+    return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+export function formatGsdPlannerCommand(plan) {
+    return [plan.command, ...plan.args].map(quoteArg).join(" ");
+}
+export async function launchGsdPlanner(input, deps = {}) {
+    const plan = buildGsdPlannerSpawnPlan(input);
+    const spawn = deps.spawn ?? spawnChild;
+    let child;
+    try {
+        child = spawn(plan.command, plan.args, {
+            cwd: plan.cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            plan,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.once("error", (err) => {
+            settle({
+                status: "failed",
+                plan,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+        child.once("spawn", () => {
+            child.unref();
+            settle({ status: "launched", plan });
+        });
+    });
+}
+export function formatPlannerHandoffPauseReason(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is planned. Review or customize the plan before implementation if needed.`,
+        `Run /gsd planner to launch ${GSD_PLANNER_COMMAND}, or run /gsd auto to continue without planner changes.`,
+    ].join(" ");
+}
+export function formatPlannerLaunchUnavailable(plan, error) {
+    return [
+        `Could not launch ${GSD_PLANNER_COMMAND}: ${error.message}`,
+        `Install ${GSD_PLANNER_COMMAND} or run it manually: ${formatGsdPlannerCommand(plan)}`,
+    ].join("\n");
+}

package/dist/resources/extensions/gsd/preferences-models.js

@@ -339,6 +339,7 @@ export function resolveAutoSupervisorConfig() {
         soft_timeout_minutes: configured.soft_timeout_minutes ?? 20,
         idle_timeout_minutes: configured.idle_timeout_minutes ?? 10,
         hard_timeout_minutes: configured.hard_timeout_minutes ?? 30,
+        stalled_tool_timeout_minutes: configured.stalled_tool_timeout_minutes ?? 5,
         ...(configured.model ? { model: configured.model } : {}),
     };
 }

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -14,7 +14,7 @@ All relevant context is preloaded below. Start immediately without re-reading th
 
 ## Already Planned? Soft Brake
 
-If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
+If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_milestone_status` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
 
 If only the file or only DB rows exist, the prior write was incomplete; plan normally so the tool reconciles both.
 

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -27,7 +27,7 @@ You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply a
 ### Automation rules by mode
 
 - `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
-- `browser-executable` — use gsd-browser tools to navigate to the target URL and verify expected behavior. Prefer `mcp__gsd-browser__browser_*` tools when namespaced, or direct `browser_*` tools when surfaced without a namespace. Capture screenshots as evidence. Record pass/fail with specific assertions.
+- `browser-executable` — use browser tools to navigate to the target URL and verify expected behavior. Prefer direct `browser_*` tools when available. Capture screenshots as evidence. Record pass/fail with specific assertions.
 - `runtime-executable` — execute the specified command or script. Capture stdout/stderr as evidence. Record pass/fail based on exit code and output.
 - `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
 - `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
@@ -48,7 +48,7 @@ Choose the lightest tool that proves the check honestly:
 - Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
-- For live/runtime/UI checks, exercise the real flow with gsd-browser when applicable and inspect runtime/network/console state
+- For live/runtime/UI checks, exercise the real flow with browser tools when applicable and inspect runtime/network/console state
 - When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:
@@ -75,24 +75,10 @@ verdict: "PASS" | "FAIL" | "PARTIAL",
 notes: "<one sentence overall verdict rationale>",
 ```
 
-Use this exact `presentation` shape in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one:
+Use this canonical `presentation` object in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one. Keep `toolPresentationPlanId` as `{{toolPresentationPlanId}}`. If browser tools were actually presented for this run, add those concrete browser tool names to `presentedTools`; otherwise reuse this object exactly:
 
-```ts
-presentation: {
-  surface: "mcp",
-  presentedTools: [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-  ],
-  blockedTools: [
-    { name: "gsd_exec", reason: "forbidden during run-uat" },
-    { name: "gsd_summary_save", reason: "forbidden during run-uat" },
-    { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
-  ],
-}
+```json
+{{canonicalPresentation}}
 ```
 
 Pass `checks` with this logical shape:

package/dist/resources/extensions/gsd/prompts/system.md

@@ -118,7 +118,7 @@ Templates are in `{{templatesDir}}`.
 
 **Secrets:** Use `secure_env_collect`. Never ask the user to edit `.env` files or paste secrets.
 
-**Browser verification:** Verify frontend work against a running app with gsd-browser by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If tools are MCP-namespaced, prefer `mcp__gsd-browser__browser_*`. Retry only with a new hypothesis.
+**Browser verification:** Verify frontend work against a running app with browser tools by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If browser tools are MCP-namespaced, use that host-provided browser surface. Retry only with a new hypothesis.
 
 **Database:** Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')`; the engine owns a single-writer WAL connection. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools.
 

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

@@ -19,6 +19,14 @@ export function classifyFailure(input) {
                 exitReason: "tool-schema",
                 remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
             };
+        case "tool-contract":
+            return {
+                failureKind,
+                action: "stop",
+                reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
+                exitReason: "tool-contract",
+                remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+            };
         case "deterministic-policy":
             return {
                 failureKind,
@@ -27,6 +35,14 @@ export function classifyFailure(input) {
                 exitReason: "deterministic-policy",
                 remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
             };
+        case "lifecycle-progression":
+            return {
+                failureKind,
+                action: "stop",
+                reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
+                exitReason: "lifecycle-progression",
+                remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+            };
         case "stale-worker":
             return {
                 failureKind,
@@ -83,6 +99,10 @@ export function classifyFailure(input) {
     }
 }
 function inferFailureKind(message) {
+    if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))
+        return "tool-contract";
+    if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message))
+        return "lifecycle-progression";
     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))