gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

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

@@ -11,10 +11,32 @@
  *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
  */
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
+// ── 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 = {
+    anthropic: ["github-copilot", "claude-code"],
+    openai: ["github-copilot", "openai-codex"],
+    google: ["google-gemini-cli"],
+};
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 /**
  * Infer the auth provider ID from a model string.
@@ -96,8 +118,34 @@ function collectConfiguredModelProviders() {
         providers.add("anthropic");
     return providers;
 }
+/**
+ * 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 = {
+    "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) {
+    const binary = CLI_BINARY_MAP[providerId];
+    if (!binary)
+        return false;
+    const pathDirs = (process.env.PATH ?? "").split(":");
+    return pathDirs.some(dir => dir && existsSync(join(dir, binary)));
+}
 function resolveKey(providerId) {
     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 };
     }
@@ -137,26 +185,6 @@ function resolveKey(providerId) {
     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 = {
-    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() {
     const required = collectConfiguredModelProviders();
     const results = [];

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

@@ -6,9 +6,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, issues, fixesApplied, shouldFix) {
     const root = gsdRoot(basePath);
     // ── Stale crash lock ──────────────────────────────────────────────────
@@ -107,9 +108,6 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
             const keys = JSON.parse(raw);
             const orphaned = [];
             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;
@@ -352,6 +350,26 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
                         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)");
+                    }
+                }
             }
         }
     }

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

@@ -154,8 +154,14 @@ function auditRequirements(content) {
         const owner = block.match(/^-\s+Primary owning slice:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
         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/dist/resources/extensions/gsd/error-classifier.js

@@ -19,11 +19,14 @@ export function resetRetryState(state) {
 }
 // ── 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;
@@ -36,7 +39,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/dist/resources/extensions/gsd/escalation.js

@@ -0,0 +1,321 @@
+// 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 { resolveSlicePath } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { getTask, setTaskEscalationPending, setTaskEscalationAwaitingReview, clearTaskEscalationFlags, claimEscalationOverride, findUnappliedEscalationOverride, setTaskBlockerSource, listEscalationArtifacts, } 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, milestoneId, sliceId, taskId) {
+    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) {
+    // 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, artifact) {
+    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) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const art = parsed;
+        // 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();
+        for (const opt of art.options) {
+            if (!opt || typeof opt !== "object")
+                return null;
+            const o = opt;
+            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;
+    }
+    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, basePath) {
+    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;
+}
+/**
+ * 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, milestoneId, sliceId, taskId, choice, rationale) {
+    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;
+    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 = {
+        ...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, milestoneId, sliceId) {
+    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) {
+    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) {
+    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) {
+    return listEscalationArtifacts(milestoneId, /* includeResolved */ false);
+}
+/** List every escalation (including resolved) for `/gsd escalate list --all`. */
+export function listAllEscalations(milestoneId) {
+    return listEscalationArtifacts(milestoneId, /* includeResolved */ true);
+}

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

@@ -451,7 +451,32 @@ function gatherActivityLogMeta(basePath, activeMilestone) {
         return null;
     }
 }
-// ─── Completed Keys Loader ────────────────────────────────────────────────────
+// ─── Completed Keys Helpers ───────────────────────────────────────────────────
+/**
+ * Parse a completed-unit key into { unitType, unitId }.
+ *
+ * Most unit types are a single segment ("execute-task", "complete-slice", …)
+ * so the key format is simply "unitType/unitId". Hook units are the exception:
+ * their type is compound ("hook/<hookName>"), making the key look like
+ * "hook/telegram-progress/M007/S01". Splitting naïvely on the first slash
+ * yields unitType="hook" which bypasses verifyExpectedArtifact()'s
+ * startsWith("hook/") guard and produces false-positive missing-artifact
+ * errors (#2826).
+ *
+ * Returns null for malformed keys (no slash, or hook/ with no second slash).
+ */
+export function splitCompletedKey(key) {
+    if (key.startsWith("hook/")) {
+        const secondSlash = key.indexOf("/", 5); // skip past "hook/"
+        if (secondSlash === -1)
+            return null; // malformed — "hook/" with no hook name
+        return { unitType: key.slice(0, secondSlash), unitId: key.slice(secondSlash + 1) };
+    }
+    const slashIdx = key.indexOf("/");
+    if (slashIdx === -1)
+        return null;
+    return { unitType: key.slice(0, slashIdx), unitId: key.slice(slashIdx + 1) };
+}
 function loadCompletedKeys(basePath) {
     const file = join(gsdRoot(basePath), "completed-units.json");
     try {
@@ -583,34 +608,6 @@ function detectTimeouts(traces, anomalies) {
         }
     }
 }
-/**
- * Parse a completed-unit key into its unitType and unitId.
- *
- * Hook units use a compound slash-delimited type ("hook/<hookName>"), so a
- * naive `key.indexOf("/")` would split "hook/telegram-progress/M007/S01" into
- * unitType="hook" (wrong) instead of "hook/telegram-progress".
- *
- * Returns `null` for malformed keys that cannot be split.
- */
-export function splitCompletedKey(key) {
-    if (key.startsWith("hook/")) {
-        // Hook unit types are two segments: "hook/<hookName>/<unitId...>"
-        const secondSlash = key.indexOf("/", 5); // skip past "hook/"
-        if (secondSlash === -1)
-            return null; // malformed — no unitId after hook name
-        return {
-            unitType: key.slice(0, secondSlash),
-            unitId: key.slice(secondSlash + 1),
-        };
-    }
-    const slashIdx = key.indexOf("/");
-    if (slashIdx === -1)
-        return null;
-    return {
-        unitType: key.slice(0, slashIdx),
-        unitId: key.slice(slashIdx + 1),
-    };
-}
 function detectMissingArtifacts(completedKeys, basePath, activeMilestone, anomalies) {
     // Also check the worktree path for artifacts — they may exist there but not at root
     const wtBasePath = activeMilestone ? getAutoWorktreePath(basePath, activeMilestone) : null;

package/dist/resources/extensions/gsd/git-service.js

@@ -574,7 +574,6 @@ export class GitServiceImpl {
      * Run pre-merge verification check. Auto-detects test runner from project
      * files, or uses custom command from prefs.pre_merge_check.
      * Gated on prefs.pre_merge_check (false = skip, string = custom command).
-     * Stub: to be implemented in T03.
      */
     runPreMergeCheck() {
         if (this.prefs.pre_merge_check === false) {

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

@@ -129,6 +129,32 @@ export function markStepComplete(graph, stepId) {
             : s),
     };
 }
+/**
+ * Return a new graph with the specified step marked as "active".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark active
+ * @returns New graph with the step's status set to "active"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepActive(graph, stepId) {
+    const found = graph.steps.some((s) => s.id === stepId);
+    if (!found) {
+        throw new Error(`Step not found: ${stepId}`);
+    }
+    const startedAt = new Date().toISOString();
+    return {
+        ...graph,
+        steps: graph.steps.map((s) => s.id === stepId
+            ? {
+                ...s,
+                status: "active",
+                startedAt: s.startedAt ?? startedAt,
+            }
+            : s),
+    };
+}
 // ─── Iteration expansion ─────────────────────────────────────────────────
 /**
  * Expand an iterate step into concrete instances. Pure and deterministic —
@@ -221,5 +247,3 @@ export function initializeGraph(def) {
         },
     };
 }
-/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
-export { initializeGraph as graphFromDefinition };