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

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

@@ -29,6 +29,7 @@ import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
+import { crashResumeHint } from "./guidance.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
 import { isInFlightRuntimePhase, listUnitRuntimeRecords } from "./unit-runtime.js";
@@ -185,6 +186,7 @@ export function writeLock(basePath, unitType, unitId, sessionFile) {
  * stale session-file pointer.
  */
 export function clearLock(basePath) {
+    const legacyLock = readLegacyLock(basePath);
     clearLegacyLockFile(basePath);
     if (!isDbAvailable())
         return;
@@ -197,9 +199,13 @@ export function clearLock(basePath) {
             deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
             return;
         }
-        const lock = readLegacyLock(basePath);
-        if (lock?.pid)
-            markWorkerStoppingByPid(projectRoot, lock.pid);
+        if (legacyLock?.pid) {
+            markWorkerStoppingByPid(projectRoot, legacyLock.pid);
+            const workerByLegacyPid = getAllAutoWorkers().find((w) => w.pid === legacyLock.pid
+                && normalizeRealPath(w.project_root_realpath) === projectRoot);
+            if (workerByLegacyPid)
+                forceReleaseLeasesForWorker(workerByLegacyPid.worker_id);
+        }
         const worker = findActiveWorkerForCurrentProcess(projectRoot);
         if (worker)
             deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
@@ -289,18 +295,9 @@ export function formatCrashInfo(lock) {
         `  Started at: ${lock.unitStartedAt}`,
         `  PID: ${lock.pid}`,
     ];
-    if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
-        lines.push(`No work was lost. Run /gsd auto to restart.`);
-    }
-    else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
-        lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);
-    }
-    else if (lock.unitType.includes("execute")) {
-        lines.push(`Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`);
-    }
-    else if (lock.unitType.includes("complete")) {
-        lines.push(`Slice/milestone completion was interrupted. Run /gsd auto to finish.`);
-    }
+    const hint = crashResumeHint(lock.unitType, lock.unitId);
+    if (hint)
+        lines.push(hint);
     return lines.join("\n");
 }
 /**

package/dist/resources/extensions/gsd/db/queries.js

@@ -5,6 +5,7 @@
 // Read-only callers (forensics, dashboard, doctor) depend on this seam, not on
 // the single-writer surface.
 import { getDbOrNull } from "./engine.js";
+import { isClosedStatus } from "../status-guards.js";
 import { getGateIdsForTurn } from "../gate-registry.js";
 import { emptyTaskStatusCounts, rowToActiveTaskSummary, rowToIdStatusSummary, rowToTaskStatusCounts, rowsToStringColumn, } from "../db-lightweight-query-rows.js";
 import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequirement, rowsToRequirementCounts, } from "../db-decision-requirement-rows.js";
@@ -217,6 +218,31 @@ export function getMilestoneSlices(milestoneId) {
     const rows = getDbOrNull().prepare("SELECT * FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId });
     return rows.map(rowToSlice);
 }
+/**
+ * Consolidated DB read for dispatch/gate/completion decisions (ADR-017).
+ * `done` uses the canonical closed-status predicate (`isClosedStatus`) — the
+ * same vocabulary the SQL terminal-status fragment derives from. Decision
+ * paths must consume this instead of parsing `.gsd/*.md` projections.
+ * Rows keep `getMilestoneSlices` ordering (sequence, then id).
+ */
+export function getMilestoneSliceSummaries(milestoneId) {
+    return getMilestoneSlices(milestoneId).map((s) => ({
+        id: s.id,
+        title: s.title,
+        done: isClosedStatus(s.status),
+        depends: s.depends ?? [],
+    }));
+}
+/**
+ * Ids of slices closed per the canonical status vocabulary (ADR-017), in
+ * milestone order. Thin wrapper over `getMilestoneSliceSummaries` for the
+ * common "which slices are done?" decision-path read.
+ */
+export function getClosedSliceIds(milestoneId) {
+    return getMilestoneSliceSummaries(milestoneId)
+        .filter((s) => s.done)
+        .map((s) => s.id);
+}
 export function getArtifact(path) {
     if (!getDbOrNull())
         return null;

package/dist/resources/extensions/gsd/db-writer.js

@@ -620,27 +620,18 @@ async function mirrorDecisionToMemory(id, normalizedFields) {
 /**
  * Extract a milestone/slice reference from a deferral decision.
  *
- * Detects deferrals by checking:
- *   - scope contains "defer" (e.g., "deferral", "defer")
- *   - choice or decision contains "defer" + an M###/S## pattern
+ * Detects deferrals when the slice reference is part of the deferral phrase.
  *
  * Returns { milestoneId, sliceId } if found, null otherwise.
  */
 export function extractDeferredSliceRef(fields) {
-    const isDeferral = /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.scope) ||
-        /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.choice) ||
-        /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.decision);
-    if (!isDeferral)
-        return null;
-    // Look for M###/S## pattern in choice first, then decision
-    const slicePattern = /\b(M\d{3,4})\/(S\d{2,3})\b/;
-    const choiceMatch = fields.choice.match(slicePattern);
-    if (choiceMatch) {
-        return { milestoneId: choiceMatch[1], sliceId: choiceMatch[2] };
-    }
-    const decisionMatch = fields.decision.match(slicePattern);
-    if (decisionMatch) {
-        return { milestoneId: decisionMatch[1], sliceId: decisionMatch[2] };
+    const defersSlicePattern = /\bdefer(?:ral|red|ring|s)?\b\s+(?:(?:of|the)\s+)*(?:slice\s+)?\b(M\d{3,4})\/(S\d{2,3})\b/i;
+    const sliceIsDeferredPattern = /\b(M\d{3,4})\/(S\d{2,3})\b\s+(?:is|was|will be|should be|can be)\s+defer(?:red|ring)?\b/i;
+    for (const text of [fields.choice, fields.decision, fields.scope]) {
+        const match = text.match(defersSlicePattern) ?? text.match(sliceIsDeferredPattern);
+        if (match) {
+            return { milestoneId: match[1], sliceId: match[2] };
+        }
     }
     return null;
 }

package/dist/resources/extensions/gsd/dispatch-guard.js

@@ -2,9 +2,8 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
+import { isDbAvailable, getMilestoneSliceSummaries, getMilestone } from "./gsd-db.js";
+import { isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 const SLICE_DISPATCH_TYPES = new Set([
@@ -97,38 +96,14 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
                 continue;
             }
         }
-        let slices = null;
-        if (isDbAvailable()) {
-            const rows = getMilestoneSlices(mid);
-            if (rows.length > 0) {
-                slices = rows.map((r) => ({
-                    id: r.id,
-                    done: isClosedStatus(r.status),
-                    depends: r.depends ?? [],
-                }));
-            }
-        }
-        if (!slices) {
-            // File-based fallback: parse roadmap checkboxes
-            const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-            if (!roadmapPath)
-                continue;
-            let roadmapContent;
-            try {
-                roadmapContent = readFileSync(roadmapPath, "utf-8");
-            }
-            catch {
-                continue;
-            }
-            const parsed = parseRoadmap(roadmapContent);
-            if (parsed.slices.length === 0)
-                continue;
-            slices = parsed.slices.map((s) => ({
-                id: s.id,
-                done: s.done,
-                depends: s.depends ?? [],
-            }));
-        }
+        // DB-authoritative eligibility list (ADR-017) — markdown projections are
+        // never parsed for dispatch decisions. No DB / no rows → skip this
+        // milestone's check (unknown is not a blocker).
+        if (!isDbAvailable())
+            continue;
+        const slices = getMilestoneSliceSummaries(mid);
+        if (slices.length === 0)
+            continue;
         if (mid !== targetMid) {
             const incomplete = slices.find((slice) => !slice.done);
             if (incomplete) {

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,11 +1,11 @@
 import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -228,7 +228,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     // relative to the event log and re-render them.
     try {
         if (isDbAvailable()) {
-            const eventLogPath = join(basePath, ".gsd", "event-log.jsonl");
+            const eventLogPath = workflowEventLogPath(basePath);
             const events = readEvents(eventLogPath);
             if (events.length > 0) {
                 const lastEventTs = new Date(events[events.length - 1].ts).getTime();
@@ -239,7 +239,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
                     if (!roadmapPath || !existsSync(roadmapPath)) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
                         }
                         catch {
@@ -250,7 +250,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const projectionMtime = statSync(roadmapPath).mtimeMs;
                     if (lastEventTs > projectionMtime) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
                         }
                         catch {

package/dist/resources/extensions/gsd/doctor-environment.js

@@ -12,7 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { detectPythonExecutable } from "./python-resolver.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ── Constants ──────────────────────────────────────────────────────────────
 /** Default dev server ports to scan for conflicts. */
 const DEFAULT_DEV_PORTS = [3000, 3001, 4000, 5000, 5173, 8000, 8080, 8888];
@@ -33,11 +33,7 @@ function resolveWorktreeProjectRoot(basePath) {
     const envRoot = process.env.GSD_WORKTREE;
     if (envRoot)
         return envRoot;
-    const segment = findWorktreeSegment(basePath.replace(/\\/g, "/"));
-    if (!segment)
-        return null;
-    // Everything before the worktree segment is the project root
-    return basePath.slice(0, segment.gsdIdx);
+    return projectRootFromWorktreePath(basePath);
 }
 function tryExec(cmd, cwd) {
     try {

package/dist/resources/extensions/gsd/doctor-format.js

@@ -1,3 +1,7 @@
+import { doctorFixHint } from "./guidance.js";
+function severityTag(severity) {
+    return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 function matchesScope(unitId, scope) {
     if (!scope)
         return true;
@@ -47,8 +51,10 @@ export function formatDoctorReport(report, options) {
     if (scopedIssues.length > 0) {
         lines.push("Priority issues:");
         for (const issue of scopedIssues.slice(0, maxIssues)) {
-            const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-            lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+            lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+            const hint = doctorFixHint(issue.code);
+            if (hint && issue.severity !== "info")
+                lines.push(`  Fix: ${hint}`);
         }
         if (scopedIssues.length > maxIssues) {
             lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -66,10 +72,7 @@ export function formatDoctorReport(report, options) {
 export function formatDoctorIssuesForPrompt(issues) {
     if (issues.length === 0)
         return "- No remaining issues in scope.";
-    return issues.map(issue => {
-        const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-        return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-    }).join("\n");
+    return issues.map(issue => `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`).join("\n");
 }
 /**
  * Serialize a doctor report to JSON — suitable for CI/tooling integration.

package/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -3,10 +3,9 @@ import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadFile } from "./files.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { deriveState, isMilestoneComplete } from "./state.js";
+import { isCompletedMilestoneTerminal } from "./milestone-closeout.js";
+import { deriveState } from "./state.js";
 import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
@@ -141,21 +140,6 @@ function getSnapshotDiffCheckFailure(basePath) {
     }
     return failures.length > 0 ? failures.join("\n") : null;
 }
-async function isCompletedMilestoneTerminal(basePath, milestoneId) {
-    const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-    if (!summaryPath)
-        return false;
-    if (isDbAvailable()) {
-        const milestone = getMilestone(milestoneId);
-        return !!milestone && milestone.status === "complete";
-    }
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-    if (!roadmapContent)
-        return false;
-    const roadmap = parseLegacyRoadmap(roadmapContent);
-    return isMilestoneComplete(roadmap);
-}
 export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -401,21 +401,19 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             if (!hasBlanketIgnore) {
                 missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
             }
-            {
-                if (missing.length > 0) {
-                    issues.push({
-                        severity: "warning",
-                        code: "gitignore_missing_patterns",
-                        scope: "project",
-                        unitId: "project",
-                        message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-                        file: ".gitignore",
-                        fixable: true,
-                    });
-                    if (shouldFix("gitignore_missing_patterns")) {
-                        ensureGitignore(basePath, { manageGitignore });
-                        fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-                    }
+            if (missing.length > 0) {
+                issues.push({
+                    severity: "warning",
+                    code: "gitignore_missing_patterns",
+                    scope: "project",
+                    unitId: "project",
+                    message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+                    file: ".gitignore",
+                    fixable: true,
+                });
+                if (shouldFix("gitignore_missing_patterns")) {
+                    ensureGitignore(basePath, { manageGitignore });
+                    fixesApplied.push("added missing GSD runtime patterns to .gitignore");
                 }
             }
         }

package/dist/resources/extensions/gsd/engine-hook-contract.js

@@ -0,0 +1,70 @@
+// Project/App: gsd-pi
+// File Purpose: Typed contract for which tool lifecycle hooks fire under which
+// engine, plus the single seam for tool-name normalization.
+//
+// ── Why this contract exists ────────────────────────────────────────────────
+// External engines (claude-code-cli) pre-execute tools inside the vendor CLI
+// and hand the agent loop a `toolCall.externalResult`. The loop short-circuits
+// before `beforeToolCall`/`afterToolCall` ever run for those calls
+// (packages/pi-agent-core/src/agent-loop.ts, prepareToolCall: the
+// externalResult branch returns an "immediate" outcome before the
+// config.beforeToolCall invocation, and "immediate" outcomes skip
+// finalizeExecutedToolCall where config.afterToolCall lives).
+// `beforeToolCall`/`afterToolCall` are exactly what the extension runner maps
+// to the `tool_call`/`tool_result` extension events
+// (packages/gsd-agent-core/src/session/agent-session-extensions.ts,
+// installAgentToolHooks).
+//
+// `tool_execution_start` is emitted unconditionally before prepareToolCall
+// and `tool_execution_end` after every finalized outcome — immediate or
+// executed — so those two are the ONLY tool lifecycle hooks that fire for
+// every tool call on every engine.
+//
+// Consequence: any enforcement attached only to `tool_call` (blocking) or
+// `tool_result` (rewriting) is silently dead under external engines. Safety
+// enforcement must ride `tool_execution_start`/`tool_execution_end`, or
+// mirror across both with toolCallId dedup. See the per-registration contract
+// comments in bootstrap/register-hooks.ts for how each registered hook
+// honors (or knowingly violates) this contract.
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+/**
+ * Tool lifecycle hooks that fire for EVERY tool call on EVERY engine,
+ * including external engines (claude-code-cli) that pre-execute tools.
+ * Attach safety-critical enforcement and evidence collection here.
+ */
+export const UNIVERSAL_TOOL_HOOKS = ["tool_execution_start", "tool_execution_end"];
+/**
+ * Tool lifecycle hooks that fire ONLY for natively executed tools. External
+ * engines pre-execute tools (externalResult), short-circuiting the agent
+ * loop's beforeToolCall/afterToolCall — so handlers on these events never run
+ * for those calls. Blocking guards attached only here are dead under external
+ * engines; they need a tool_execution_start mirror to be universal.
+ */
+export const NATIVE_ONLY_TOOL_HOOKS = ["tool_call", "tool_result"];
+// Non-tool lifecycle events (session_start, agent_end, message_update, ...)
+// are intentionally NOT classified here: they are emitted by the session
+// host / extension runner independent of tool execution, so the external
+// engine short-circuit above does not apply to them. Only classify events
+// whose engine behavior has been verified against the agent loop.
+/**
+ * Canonical tool name: strips the `mcp__<server>__` prefix when present,
+ * nothing else. Use for identity checks against host/native tool names and
+ * for any guard that must NOT conflate workflow aliases with their canonical
+ * tools (e.g. write gates, evidence keys).
+ *
+ * Malformed MCP names (empty server or empty tool segment, e.g.
+ * `mcp____tool` or `mcp__server__`) are returned unchanged.
+ */
+export function canonicalToolName(toolName) {
+    return stripMcpToolPrefix(toolName);
+}
+/**
+ * Workflow-aware canonical tool name: strips the MCP prefix AND resolves
+ * workflow tool aliases to their canonical contract names. Use whenever the
+ * name is compared against the workflow tool surface (scoping, presentation,
+ * dispatch) — plain {@link canonicalToolName} would miss alias spellings.
+ */
+export function canonicalWorkflowToolName(toolName) {
+    return canonicalWorkflowSurfaceToolName(toolName);
+}

package/dist/resources/extensions/gsd/error-classifier.js

@@ -9,6 +9,7 @@
  *
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 export function createRetryState() {
     return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
 }
@@ -44,6 +45,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -77,6 +82,10 @@ export function classifyError(errorMsg, retryAfterMs) {
     if (TOOL_SCHEMA_RE.test(errorMsg)) {
         return { kind: "tool-schema", retryAfterMs: 0 };
     }
+    // Tool-surface readiness abort — transient; retry the same model shortly.
+    if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
+        return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+    }
     const isPermanent = PERMANENT_RE.test(errorMsg);
     const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
     const isUnsupportedModel = UNSUPPORTED_MODEL_MODEL_RE.test(errorMsg) &&

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -11,7 +11,11 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
+// SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
+// (shell.ts) — the single source of truth for the graceful-kill timing ladder —
+// so this sandbox can never drift from the canonical kill path it delegates to.
 export const EXEC_DEFAULTS = {
     clampTimeoutMs: 600_000,
     defaultTimeoutMs: 30_000,
@@ -120,6 +124,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: null,
                 signal: null,
                 timed_out: false,
+                force_resolved: false,
                 duration_ms: duration,
                 stdout_bytes: 0,
                 stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
@@ -172,24 +177,38 @@ export function runExecSandbox(request, opts) {
                 stderrTruncated = true;
             }
         });
+        const effectiveGraceMs = opts.kill_grace_ms ?? SIGKILL_GRACE_MS;
+        const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
         let timedOut = false;
+        let settled = false;
+        let forceResolveTimer;
         const timer = setTimeout(() => {
             timedOut = true;
-            if (useProcessGroup && child.pid != null) {
-                try {
-                    process.kill(-child.pid, "SIGKILL");
-                }
-                catch {
-                    child.kill("SIGKILL");
-                }
+            // killProcessTree handles both platforms and kills the whole tree: on Unix
+            // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
+            // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
+            // would only terminate the direct child on Windows, orphaning grandchildren.
+            if (child.pid != null) {
+                killProcessTree(child.pid, { graceMs: effectiveGraceMs });
             }
             else {
-                child.kill("SIGKILL");
+                child.kill("SIGTERM");
             }
+            // Arm hard-deadline force-resolve in case child never closes (D-state).
+            // The "SIGKILL" here is a synthetic marker (the process may not have actually
+            // received it); force_resolved=true records that this was a deadline, not an exit.
+            forceResolveTimer = setTimeout(() => {
+                finalize(null, "SIGKILL", true);
+            }, effectiveForceResolveDelay);
+            forceResolveTimer.unref?.();
         }, timeoutMs);
         timer.unref?.();
-        const finalize = (exitCode, signal) => {
+        const finalize = (exitCode, signal, forceResolved = false) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
+            clearTimeout(forceResolveTimer);
             const duration = Date.now() - started;
             const stdoutBuf = Buffer.concat(stdoutChunks);
             const stderrBuf = Buffer.concat(stderrChunks);
@@ -211,6 +230,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: exitCode,
                 signal,
                 timed_out: timedOut,
+                force_resolved: forceResolved,
                 duration_ms: duration,
                 stdout_bytes: stdoutBytes,
                 stderr_bytes: stderrBytes,
@@ -254,6 +274,7 @@ function writeMeta(path, result, request, now) {
         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,
@@ -261,7 +282,6 @@ function writeMeta(path, result, request, now) {
         stderr_truncated: result.stderr_truncated,
         stdout_path: result.stdout_path,
         stderr_path: result.stderr_path,
-        ...(request.metadata ? { metadata: request.metadata } : {}),
     };
     writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
 }

package/dist/resources/extensions/gsd/files.js

@@ -576,38 +576,52 @@ export function parseTaskPlanIO(content) {
         outputFiles: extractPaths(outputSection),
     };
 }
+/** Canonical list of recognised UAT types — uat-policy.ts re-exports this as UAT_TYPES. */
+export const UAT_TYPE_KEYWORDS = [
+    'artifact-driven',
+    'browser-executable',
+    'runtime-executable',
+    'live-runtime',
+    'mixed',
+    'human-experience',
+];
+/** Match a value against the recognised UAT type keywords (leading-keyword-only). */
+function matchUatTypeKeyword(value) {
+    const normalized = value.trim().toLowerCase();
+    return UAT_TYPE_KEYWORDS.find(keyword => normalized.startsWith(keyword));
+}
 /**
  * Extract the UAT type from a UAT file's raw content.
  *
  * UAT files have no YAML frontmatter - pass raw file content directly.
  * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
  *
+ * The canonical form is a `- UAT mode: <type>` bullet under `## UAT Type`
+ * (case-insensitive prefix, `**bold**` tolerated). When no such line exists,
+ * a line that itself starts with a recognised keyword — e.g. a bare
+ * `browser-executable` under the heading — is accepted, so agent-authored
+ * format drift does not silently fall back to artifact-driven.
+ *
  * Returns `undefined` when:
  * - the `## UAT Type` section is absent
- * - no `UAT mode:` bullet is found in the section
- * - the value does not start with a recognised keyword
+ * - a `UAT mode:` line exists but its value starts with no recognised keyword
+ * - no line in the section starts with `UAT mode:` or a recognised keyword
  */
 export function extractUatType(content) {
     const sectionText = extractSection(content, 'UAT Type');
     if (!sectionText)
         return undefined;
-    const bullets = parseBullets(sectionText);
-    const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
-    if (!modeBullet)
-        return undefined;
-    const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
-    if (rawValue.startsWith('artifact-driven'))
-        return 'artifact-driven';
-    if (rawValue.startsWith('browser-executable'))
-        return 'browser-executable';
-    if (rawValue.startsWith('runtime-executable'))
-        return 'runtime-executable';
-    if (rawValue.startsWith('live-runtime'))
-        return 'live-runtime';
-    if (rawValue.startsWith('human-experience'))
-        return 'human-experience';
-    if (rawValue.startsWith('mixed'))
-        return 'mixed';
+    const lines = parseBullets(sectionText).map(line => line.replace(/\*\*/g, ''));
+    for (const line of lines) {
+        const declared = /^uat mode:\s*(.*)$/i.exec(line);
+        if (declared)
+            return matchUatTypeKeyword(declared[1]);
+    }
+    for (const line of lines) {
+        const matched = matchUatTypeKeyword(line);
+        if (matched)
+            return matched;
+    }
     return undefined;
 }
 /**