gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/gsd/doctor-providers.ts

@@ -11,8 +11,8 @@
  *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -37,6 +37,30 @@ export interface ProviderCheckResult {
   required: boolean;
 }
 
+// ── Provider routing constants ────────────────────────────────────────────────
+
+/**
+ * Providers that use external CLI authentication (not API keys).
+ * These are always considered "found" — the host CLI handles auth.
+ */
+const CLI_AUTH_PROVIDERS = new Set([
+  "claude-code",
+  "openai-codex",
+  "google-gemini-cli",
+  "google-antigravity",
+]);
+
+/**
+ * Providers that can serve models normally associated with another provider.
+ * Key = the provider whose models can be served, Value = alternative providers to check.
+ * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
+ */
+const PROVIDER_ROUTES: Record<string, string[]> = {
+  anthropic: ["github-copilot", "claude-code"],
+  openai: ["github-copilot", "openai-codex"],
+  google: ["google-gemini-cli"],
+};
+
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 
 /**
@@ -48,7 +72,8 @@ function modelToProviderId(model: string): string | null {
 
   // Explicit provider prefix (e.g. "openrouter/deepseek-r1")
   if (model.includes("/")) {
-    const prefix = model.split("/")[0].toLowerCase();
+    const rawPrefix = model.split("/")[0];
+    const prefix = rawPrefix.toLowerCase();
     // Map known prefixes to registry IDs
     const prefixMap: Record<string, string> = {
       "anthropic-vertex": "anthropic-vertex",
@@ -62,6 +87,7 @@ function modelToProviderId(model: string): string | null {
       "github-copilot": "github-copilot",
     };
     if (prefixMap[prefix]) return prefixMap[prefix];
+    return rawPrefix;
   }
 
   const lower = model.toLowerCase();
@@ -121,13 +147,88 @@ function collectConfiguredModelProviders(): Set<string> {
 
 interface KeyLookup {
   found: boolean;
-  source: "auth.json" | "env" | "none";
+  source: "auth.json" | "env" | "models.json" | "none";
   backedOff: boolean;
 }
 
+/**
+ * Map of CLI provider IDs to their binary names on disk.
+ * Used for lightweight binary-presence checks (PATH scan, no subprocess).
+ */
+const CLI_BINARY_MAP: Record<string, string> = {
+  "claude-code": "claude",
+  "openai-codex": "codex",
+  "google-gemini-cli": "gemini",
+  "google-antigravity": "antigravity",
+};
+
+/**
+ * Check if a CLI provider's binary exists anywhere in PATH.
+ * Fast filesystem scan — no subprocess, no network, sub-1ms.
+ */
+function isCliBinaryInPath(providerId: string): boolean {
+  const binary = CLI_BINARY_MAP[providerId];
+  if (!binary) return false;
+
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+
+  // On Windows, command shims are commonly installed as .cmd/.exe/.bat/.com.
+  // Scan PATHEXT candidates in addition to the bare binary name.
+  const executableNames: string[] = [binary];
+  if (process.platform === "win32") {
+    const rawPathExt = process.env.PATHEXT
+      ?.split(";")
+      .map(ext => ext.trim())
+      .filter(Boolean) ?? [];
+    const normalizedPathExt = rawPathExt.map(ext =>
+      ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`,
+    );
+    const defaultExt = [".exe", ".cmd", ".bat", ".com"];
+    for (const ext of [...normalizedPathExt, ...defaultExt]) {
+      const candidate = `${binary}${ext}`;
+      if (!executableNames.includes(candidate)) executableNames.push(candidate);
+    }
+  }
+
+  return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
+}
+
+function modelsJsonPaths(): string[] {
+  const home = process.env.HOME ?? "~";
+  return [
+    join(home, ".gsd", "agent", "models.json"),
+    // Keep parity with custom-provider discovery during auto bootstrap.
+    join(home, ".pi", "agent", "models.json"),
+  ];
+}
+
+function hasModelsJsonApiKey(providerId: string): boolean {
+  for (const path of modelsJsonPaths()) {
+    if (!existsSync(path)) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf-8")) as {
+        providers?: Record<string, { apiKey?: unknown }>;
+      };
+      const apiKey = parsed.providers?.[providerId]?.apiKey;
+      if (typeof apiKey === "string" && apiKey.trim().length > 0) {
+        return true;
+      }
+    } catch {
+      // Malformed models.json should not break the dashboard health check.
+    }
+  }
+  return false;
+}
+
 function resolveKey(providerId: string): KeyLookup {
   const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
 
+  // claude-code never stores credentials in auth.json — GSD delegates entirely to
+  // the local CLI binary. Presence of the binary in PATH is the only signal.
+  if (providerId === "claude-code") {
+    return { found: isCliBinaryInPath("claude-code"), source: "env", backedOff: false };
+  }
+
   if (providerId === "anthropic-vertex" && process.env.ANTHROPIC_VERTEX_PROJECT_ID) {
     return { found: true, source: "env", backedOff: false };
   }
@@ -169,33 +270,15 @@ function resolveKey(providerId: string): KeyLookup {
     return { found: true, source: "env", backedOff: false };
   }
 
+  if (hasModelsJsonApiKey(providerId)) {
+    return { found: true, source: "models.json", backedOff: false };
+  }
+
   return { found: false, source: "none", backedOff: false };
 }
 
 // ── Individual check groups ────────────────────────────────────────────────────
 
-/**
- * Providers that can serve models normally associated with another provider.
- * Key = the provider whose models can be served, Value = alternative providers to check.
- * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
- */
-const PROVIDER_ROUTES: Record<string, string[]> = {
-  anthropic: ["github-copilot"],
-  openai: ["github-copilot", "openai-codex"],
-  google: ["google-gemini-cli"],
-};
-
-/**
- * Providers that use external CLI authentication (not API keys).
- * These are always considered "ok" — the host CLI handles auth.
- */
-const CLI_AUTH_PROVIDERS = new Set([
-  "claude-code",
-  "openai-codex",
-  "google-gemini-cli",
-  "google-antigravity",
-]);
-
 function checkLlmProviders(): ProviderCheckResult[] {
   const required = collectConfiguredModelProviders();
   const results: ProviderCheckResult[] = [];

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -8,9 +8,10 @@ import { deriveState } from "./state.js";
 import { saveFile } from "./files.js";
 import { nativeIsRepo, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
-import { ensureGitignore } from "./gitignore.js";
+import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
+import { splitCompletedKey } from "./forensics.js";
 
 export async function checkRuntimeHealth(
   basePath: string,
@@ -118,9 +119,6 @@ export async function checkRuntimeHealth(
       const orphaned: string[] = [];
 
       for (const key of keys) {
-        // Key format: "unitType/unitId" e.g. "execute-task/M001/S01/T01"
-        // Hook units have compound types: "hook/<hookName>/unitId"
-        const { splitCompletedKey } = await import("./forensics.js");
         const parsed = splitCompletedKey(key);
         if (!parsed) continue;
         const { unitType, unitId } = parsed;
@@ -383,6 +381,27 @@ export async function checkRuntimeHealth(
             fixable: false,
           });
         }
+
+        // ── Symlinked .gsd without .gitignore entry (#4423) ──
+        // When `.gsd` is a symlink AND not gitignored, `git add -A -- :!.gsd/...`
+        // pathspecs fail with "beyond a symbolic link". Without self-heal this
+        // silently drops new user files during auto-commit.
+        if (nativeIsRepo(basePath) && !isGsdGitignored(basePath)) {
+          issues.push({
+            severity: "warning",
+            code: "symlinked_gsd_unignored",
+            scope: "project",
+            unitId: "project",
+            message: ".gsd is a symlink to external state but is not listed in .gitignore. This causes git pathspec exclusions to fail and can lead to silently dropped new files during auto-commit. Add `.gsd` to .gitignore.",
+            file: ".gitignore",
+            fixable: true,
+          });
+
+          if (shouldFix("symlinked_gsd_unignored")) {
+            const modified = ensureGitignore(basePath);
+            if (modified) fixesApplied.push("added .gsd to .gitignore (symlinked external state)");
+          }
+        }
       }
     }
   } catch {

package/src/resources/extensions/gsd/doctor-types.ts

@@ -23,6 +23,7 @@ export type DoctorIssueCode =
   | "state_file_stale"
   | "state_file_missing"
   | "gitignore_missing_patterns"
+  | "symlinked_gsd_unignored"
   | "unresolvable_dependency"
   | "failed_migration"
   | "broken_symlink"

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

@@ -172,8 +172,14 @@ function auditRequirements(content: string | null): DoctorIssue[] {
     const notes = block.match(/^-\s+Notes:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
 
     if (status === "active" && (!owner || owner === "none" || owner === "none yet")) {
+      // #4414: Downgrade to warning. A newly-created requirement has
+      // primary_owner='' by default until the planning agent wires it to
+      // a slice via gsd_requirement_update. Flagging this as an error
+      // during normal planning is noisy — the real failure mode is when
+      // it persists past milestone completion, which is covered by other
+      // audits. Keep the signal but don't treat it as a blocker.
       issues.push({
-        severity: "error",
+        severity: "warning",
         code: "active_requirement_missing_owner",
         scope: "project",
         unitId: requirementId,

package/src/resources/extensions/gsd/ecosystem/gsd-extension-api.ts

@@ -160,6 +160,8 @@ export function createGSDExtensionAPI(
       pi.emitBeforeModelSelect(...args),
     emitAdjustToolSet: (...args: Parameters<ExtensionAPI["emitAdjustToolSet"]>) =>
       pi.emitAdjustToolSet(...args),
+    emitExtensionEvent: (...args: Parameters<ExtensionAPI["emitExtensionEvent"]>) =>
+      pi.emitExtensionEvent(...args),
 
     // ── Tool / command / shortcut / flag registration ──────────────────
     registerTool: ((tool: any) => pi.registerTool(tool)) as ExtensionAPI["registerTool"],

package/src/resources/extensions/gsd/error-classifier.ts

@@ -43,11 +43,14 @@ export function resetRetryState(state: RetryState): void {
 // ── Classification ──────────────────────────────────────────────────────────
 
 const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i;
-const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
+// Include provider-specific quota-window phrasing like:
+// - "You've hit your limit"
+// - "usage limit" / "quota reached"
+const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|quota (?:reached|hit)|limit.*resets?/i;
 // OpenRouter affordability-style quota errors should be treated as transient
 // so core retry logic can lower maxTokens and continue in-session.
 const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof/i;
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
@@ -61,7 +64,7 @@ const RESET_DELAY_RE = /reset in (\d+)s/i;
  *
  * Classification order:
  *  1. Permanent (auth/billing/quota) — unless also rate-limited
- *  2. Rate limit (429, rate.?limit, too many requests)
+ *  2. Rate limit (429, rate.?limit, too many requests, hit-your-limit/quota-window phrasing)
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)

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

@@ -0,0 +1,367 @@
+// GSD Extension — ADR-011 Phase 2 Mid-Execution Escalation
+//
+// A single module that owns: escalation artifact I/O, detection, resolution,
+// carry-forward injection lookup, and audit-event emission. Scoped to
+// execute-task only (refine-slice escalation is deferred per ADR-011).
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { EscalationArtifact, EscalationOption } from "./types.js";
+import { resolveSlicePath } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import {
+  getTask,
+  setTaskEscalationPending,
+  setTaskEscalationAwaitingReview,
+  clearTaskEscalationFlags,
+  claimEscalationOverride,
+  findUnappliedEscalationOverride,
+  setTaskBlockerSource,
+  listEscalationArtifacts,
+  type TaskRow,
+} from "./gsd-db.js";
+import { emitUokAuditEvent, buildAuditEnvelope } from "./uok/audit.js";
+import { logWarning } from "./workflow-logger.js";
+
+// ─── Paths ────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical escalation artifact path, parallel to T##-SUMMARY.md:
+ *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-ESCALATION.json
+ */
+export function escalationArtifactPath(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+): string | null {
+  const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!sDir) return null;
+  return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+}
+
+// ─── Artifact I/O ─────────────────────────────────────────────────────────
+
+/** Build an EscalationArtifact from a gsd_complete_task escalation payload. */
+export function buildEscalationArtifact(params: {
+  taskId: string;
+  sliceId: string;
+  milestoneId: string;
+  question: string;
+  options: EscalationOption[];
+  recommendation: string;
+  recommendationRationale: string;
+  continueWithDefault: boolean;
+}): EscalationArtifact {
+  // Server-side validation — the MCP Type schema already constrains shape,
+  // but we belt-and-suspenders here so non-MCP callers can't construct
+  // malformed artifacts. These checks match readEscalationArtifact's.
+  if (!Array.isArray(params.options) || params.options.length < 2 || params.options.length > 4) {
+    throw new Error(`escalation.options must have between 2 and 4 entries (got ${params.options?.length ?? 0})`);
+  }
+  const optionIds = new Set(params.options.map((o) => o.id));
+  if (optionIds.size !== params.options.length) {
+    throw new Error("escalation.options must have unique ids");
+  }
+  if (!optionIds.has(params.recommendation)) {
+    throw new Error(`escalation.recommendation "${params.recommendation}" is not one of the option ids: ${[...optionIds].join(", ")}`);
+  }
+  return {
+    version: 1,
+    taskId: params.taskId,
+    sliceId: params.sliceId,
+    milestoneId: params.milestoneId,
+    question: params.question,
+    options: params.options,
+    recommendation: params.recommendation,
+    recommendationRationale: params.recommendationRationale,
+    continueWithDefault: params.continueWithDefault,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/** Atomically write an escalation artifact and flip the appropriate DB flag. */
+export function writeEscalationArtifact(
+  basePath: string, artifact: EscalationArtifact,
+): string {
+  const path = escalationArtifactPath(basePath, artifact.milestoneId, artifact.sliceId, artifact.taskId);
+  if (!path) {
+    throw new Error(
+      `escalation: cannot resolve tasks dir for ${artifact.milestoneId}/${artifact.sliceId} — run doctor`,
+    );
+  }
+  mkdirSync(join(path, ".."), { recursive: true });
+  atomicWriteSync(path, JSON.stringify(artifact, null, 2));
+
+  if (artifact.continueWithDefault) {
+    setTaskEscalationAwaitingReview(artifact.milestoneId, artifact.sliceId, artifact.taskId, path);
+  } else {
+    setTaskEscalationPending(artifact.milestoneId, artifact.sliceId, artifact.taskId, path);
+  }
+
+  emitUokAuditEvent(basePath, buildAuditEnvelope({
+    traceId: `escalation:${artifact.milestoneId}:${artifact.sliceId}:${artifact.taskId}`,
+    category: "gate",
+    type: "escalation-manual-attention-created",
+    payload: {
+      milestoneId: artifact.milestoneId,
+      sliceId: artifact.sliceId,
+      taskId: artifact.taskId,
+      continueWithDefault: artifact.continueWithDefault,
+      optionCount: artifact.options.length,
+      recommendation: artifact.recommendation,
+    },
+  }));
+
+  return path;
+}
+
+/** Read an escalation artifact by path. Returns null when missing or malformed. */
+export function readEscalationArtifact(path: string): EscalationArtifact | null {
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const art = parsed as Partial<EscalationArtifact>;
+    // Full schema validation — invalid artifacts return null so downstream
+    // code (formatEscalationForDisplay, resolveEscalation, carry-forward)
+    // never crashes on malformed input.
+    if (art.version !== 1) return null;
+    if (typeof art.taskId !== "string" || art.taskId.length === 0) return null;
+    if (typeof art.sliceId !== "string" || art.sliceId.length === 0) return null;
+    if (typeof art.milestoneId !== "string" || art.milestoneId.length === 0) return null;
+    if (typeof art.question !== "string" || art.question.length === 0) return null;
+    // Option array constraints — kept in sync with buildEscalationArtifact so
+    // a hand-edited artifact cannot be weaker than what the writer would emit.
+    if (!Array.isArray(art.options) || art.options.length < 2 || art.options.length > 4) return null;
+    const optionIds = new Set<string>();
+    for (const opt of art.options) {
+      if (!opt || typeof opt !== "object") return null;
+      const o = opt as Partial<EscalationOption>;
+      if (typeof o.id !== "string" || o.id.length === 0) return null;
+      if (typeof o.label !== "string") return null;
+      if (typeof o.tradeoffs !== "string") return null;
+      if (optionIds.has(o.id)) return null;
+      optionIds.add(o.id);
+    }
+    if (typeof art.recommendation !== "string") return null;
+    // Recommendation must reference a real option id.
+    if (!art.options.some((o) => o.id === art.recommendation)) return null;
+    if (typeof art.continueWithDefault !== "boolean") return null;
+    if (typeof art.createdAt !== "string") return null;
+    return art as EscalationArtifact;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Detection ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the task id of the first task with an un-resolved pause-escalation
+ * (escalation_pending=1, not yet respondedAt). awaiting_review slices are NOT
+ * returned — they don't pause the loop.
+ */
+export function detectPendingEscalation(tasks: TaskRow[], basePath: string): string | null {
+  for (const t of tasks) {
+    if (t.escalation_pending !== 1) continue;
+    if (!t.escalation_artifact_path) continue;
+    const art = readEscalationArtifact(t.escalation_artifact_path);
+    if (art && !art.respondedAt) return t.id;
+  }
+  return null;
+}
+
+// ─── Resolution ───────────────────────────────────────────────────────────
+
+export interface ResolveEscalationResult {
+  status: "resolved" | "not-found" | "already-resolved" | "invalid-choice" | "rejected-to-blocker";
+  message: string;
+  artifactPath?: string;
+  chosenOption?: EscalationOption;
+}
+
+/**
+ * Apply a user response to a pending escalation:
+ *  1) Update the artifact with respondedAt/userChoice/userRationale.
+ *  2) Clear the DB escalation flags.
+ *  3) For "reject-blocker": set blocker_discovered=1 + blocker_source='reject-escalation'.
+ *  4) Emit audit events.
+ *
+ * Note: this does NOT persist a decision via saveDecisionToDb — the caller
+ * (commands/handlers/escalate.ts) owns that step so it can fail gracefully
+ * and surface the decision id in the user-visible message.
+ */
+export function resolveEscalation(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+  choice: string, rationale: string,
+): ResolveEscalationResult {
+  const task = getTask(milestoneId, sliceId, taskId);
+  if (!task || !task.escalation_artifact_path) {
+    return { status: "not-found", message: `No escalation artifact found for ${milestoneId}/${sliceId}/${taskId}.` };
+  }
+  const art = readEscalationArtifact(task.escalation_artifact_path);
+  if (!art) {
+    return { status: "not-found", message: `Escalation artifact at ${task.escalation_artifact_path} is missing or malformed.` };
+  }
+  if (art.respondedAt) {
+    return { status: "already-resolved", message: `Escalation for ${taskId} was already resolved at ${art.respondedAt}.` };
+  }
+
+  // Resolve `choice` into a concrete option.
+  let chosenOption: EscalationOption | undefined;
+  if (choice === "accept") {
+    chosenOption = art.options.find((o) => o.id === art.recommendation);
+  } else if (choice === "reject-blocker") {
+    // Handled below; no option selection.
+  } else {
+    chosenOption = art.options.find((o) => o.id === choice);
+    if (!chosenOption) {
+      const valid = ["accept", "reject-blocker", ...art.options.map((o) => o.id)].join(", ");
+      return { status: "invalid-choice", message: `Unknown choice "${choice}". Valid choices: ${valid}.` };
+    }
+  }
+
+  const respondedAt = new Date().toISOString();
+  const updated: EscalationArtifact = {
+    ...art,
+    respondedAt,
+    userChoice: choice,
+    userRationale: rationale,
+  };
+  atomicWriteSync(task.escalation_artifact_path, JSON.stringify(updated, null, 2));
+  clearTaskEscalationFlags(milestoneId, sliceId, taskId);
+
+  if (choice === "reject-blocker") {
+    setTaskBlockerSource(milestoneId, sliceId, taskId, "reject-escalation");
+    emitUokAuditEvent(basePath, buildAuditEnvelope({
+      traceId: `escalation:${milestoneId}:${sliceId}:${taskId}`,
+      category: "gate",
+      type: "escalation-rejected-to-blocker",
+      payload: { milestoneId, sliceId, taskId, rationale },
+    }));
+    return {
+      status: "rejected-to-blocker",
+      message: `Escalation rejected. Task ${taskId} now flagged as a blocker — next /gsd auto will replan slice ${sliceId}.`,
+      artifactPath: task.escalation_artifact_path,
+    };
+  }
+
+  emitUokAuditEvent(basePath, buildAuditEnvelope({
+    traceId: `escalation:${milestoneId}:${sliceId}:${taskId}`,
+    category: "gate",
+    type: "escalation-user-responded",
+    payload: {
+      milestoneId, sliceId, taskId,
+      chosenOptionId: chosenOption?.id,
+      rationale,
+    },
+  }));
+
+  return {
+    status: "resolved",
+    message: `Escalation resolved. Next task in ${sliceId} will receive the override.`,
+    artifactPath: task.escalation_artifact_path,
+    chosenOption,
+  };
+}
+
+// ─── Carry-forward lookup ─────────────────────────────────────────────────
+
+/**
+ * If this slice has a resolved-but-unapplied escalation override, atomically
+ * claim it (via DB UPDATE) and return the markdown block to prepend to the
+ * next task's prompt. Returns null when there's no unapplied override OR
+ * when another caller claimed it first (idempotent).
+ */
+export function claimOverrideForInjection(
+  basePath: string, milestoneId: string, sliceId: string,
+): { injectionBlock: string; sourceTaskId: string } | null {
+  const unapplied = findUnappliedEscalationOverride(milestoneId, sliceId);
+  if (!unapplied) return null;
+  // Validate artifact BEFORE claiming so a missing/malformed file doesn't
+  // mark the DB row as applied (which would silently swallow the override
+  // forever). If the artifact is bad, return null without touching the row.
+  const art = readEscalationArtifact(unapplied.artifactPath);
+  if (!art) {
+    logWarning(
+      "tool",
+      `escalation: artifact missing/malformed at ${unapplied.artifactPath} (task ${unapplied.taskId}); skipping without claim — operator should resolve or remove the row`,
+    );
+    return null;
+  }
+  if (!art.respondedAt || !art.userChoice) return null;
+  const claimed = claimEscalationOverride(milestoneId, sliceId, unapplied.taskId);
+  if (!claimed) return null; // lost the race
+  void basePath;
+  return {
+    injectionBlock: formatOverrideBlock(art),
+    sourceTaskId: unapplied.taskId,
+  };
+}
+
+function formatOverrideBlock(art: EscalationArtifact): string {
+  const isReject = art.userChoice === "reject-blocker";
+  const isAccept = art.userChoice === "accept";
+  const isOptionChoice = !!art.userChoice && !isReject && !isAccept;
+  // Include the stable option id in the block so downstream prompts and
+  // parsers have a machine-readable token, not just the display label.
+  const choiceLabel = isReject
+    ? "rejected — blocker path"
+    : isAccept
+      ? `accepted recommendation (${art.recommendation})`
+      : isOptionChoice
+        ? `${art.options.find((o) => o.id === art.userChoice)?.label ?? art.userChoice} (id: ${art.userChoice})`
+        : (art.userChoice ?? "unknown");
+
+  const tradeoffs = isOptionChoice
+    ? art.options.find((o) => o.id === art.userChoice)?.tradeoffs ?? ""
+    : "";
+
+  const rationale = art.userRationale ? `\n\n**User rationale:** ${art.userRationale}` : "";
+
+  return [
+    `## Escalation Override (from ${art.taskId})`,
+    "",
+    `During ${art.taskId} the executor escalated: **${art.question}**`,
+    "",
+    `The user's resolution: **${choiceLabel}**.${rationale}`,
+    tradeoffs ? `\n**Tradeoffs of this choice:** ${tradeoffs}` : "",
+    "",
+    "Apply this decision as a hard constraint for the current task. If it contradicts the task plan, surface the conflict in your summary rather than silently deviating.",
+  ].filter((line) => line !== undefined).join("\n");
+}
+
+// ─── Display ──────────────────────────────────────────────────────────────
+
+/** Human-readable summary of an artifact for `/gsd escalate show`. */
+export function formatEscalationForDisplay(art: EscalationArtifact): string {
+  const resolved = art.respondedAt
+    ? `\nResolved: ${art.respondedAt} — user chose "${art.userChoice}"${art.userRationale ? ` (rationale: ${art.userRationale})` : ""}`
+    : "\nStatus: awaiting user response";
+  const optionLines = art.options.map((o) =>
+    `  [${o.id}] ${o.label}${o.id === art.recommendation ? "  (recommended)" : ""}\n      ${o.tradeoffs}`,
+  ).join("\n");
+  return [
+    `Task ${art.taskId} (slice ${art.sliceId})`,
+    `continueWithDefault: ${art.continueWithDefault}`,
+    `Question: ${art.question}`,
+    "",
+    "Options:",
+    optionLines,
+    "",
+    `Recommendation: ${art.recommendation} — ${art.recommendationRationale}`,
+    resolved,
+    "",
+    `Resolve with: /gsd escalate resolve ${art.taskId} <${art.options.map((o) => o.id).join("|")}|accept|reject-blocker> [rationale...]`,
+  ].join("\n");
+}
+
+/** List actionable (unresolved) escalations for `/gsd escalate list`. */
+export function listActionableEscalations(milestoneId: string): TaskRow[] {
+  return listEscalationArtifacts(milestoneId, /* includeResolved */ false);
+}
+
+/** List every escalation (including resolved) for `/gsd escalate list --all`. */
+export function listAllEscalations(milestoneId: string): TaskRow[] {
+  return listEscalationArtifacts(milestoneId, /* includeResolved */ true);
+}