@pourkit/cli 0.0.0-next-20260623021955 → 0.0.0-next-20260624074234

package/dist/cli.js

@@ -5082,7 +5082,7 @@ Before handoff, run: pourkit validate-artifact finalizer ${artifactPathInWorktre
 
 // issues/issue-final-review.ts
 import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
-import { isAbsolute as isAbsolute3, join as join11 } from "path";
+import { isAbsolute as isAbsolute3, join as join11, relative as relative2, sep as sep2 } from "path";
 init_common();
 var ISSUE_FINAL_REVIEW_ARTIFACT_PATH = join11(
   ".pourkit",
@@ -5138,6 +5138,7 @@ async function runIssueFinalReview(options) {
     repoRoot: repoRoot2,
     promptTemplate: agent.promptTemplate,
     validationCommand: `pourkit validate-artifact issue-final-review ${artifactPathInWorktree} --issue-number ${issue.number} --branch-name ${builderBranch} --base-ref origin/${target.baseBranch}`,
+    worktreePath,
     reviewArtifactPath: options.reviewArtifactPath,
     reviewVerdict: options.reviewVerdict
   });
@@ -5347,6 +5348,7 @@ function loadIssueFinalReviewPrompt(options) {
     repoRoot: repoRoot2,
     promptTemplate,
     validationCommand,
+    worktreePath,
     reviewArtifactPath,
     reviewVerdict
   } = options;
@@ -5385,11 +5387,12 @@ Read the selected issue requirements, planning context (including plan and PRD c
 - If validation fails, fix the artifact or safely retouch the worktree as needed, then rerun the same command.
 - Do not finish until the validation command passes.`);
   if (reviewVerdict) {
+    const reviewArtifactPathForPrompt = reviewArtifactPath ? formatReviewArtifactPathForPrompt(worktreePath, reviewArtifactPath) : reviewArtifactPath;
     prompt += `
 
 ## Prior Review Context
 
-- Reviewer Artifact Path: ${reviewArtifactPath}
+- Reviewer Artifact Path: ${reviewArtifactPathForPrompt}
 - Prior Review Verdict: ${reviewVerdict}`;
     if (reviewVerdict === "PASS_WITH_NOTES") {
       prompt += `
@@ -5398,6 +5401,14 @@ Read the selected issue requirements, planning context (including plan and PRD c
   }
   return prompt;
 }
+function formatReviewArtifactPathForPrompt(worktreePath, reviewArtifactPath) {
+  if (!isAbsolute3(reviewArtifactPath)) return reviewArtifactPath;
+  const relativePath = relative2(worktreePath, reviewArtifactPath);
+  if (relativePath && relativePath !== ".." && !relativePath.startsWith(`..${sep2}`) && !isAbsolute3(relativePath)) {
+    return relativePath.replace(/\\/g, "/");
+  }
+  return reviewArtifactPath;
+}
 
 // pr/pr-body.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -6477,6 +6488,61 @@ function isAllowedDocumentationTokenReference(value) {
   return /^token\s*:\s*["']?<verdict>/i.test(value);
 }
 
+// issues/final-commit.ts
+init_common();
+async function runFinalCommit(options) {
+  const { worktreePath, worktreeState, baseRef, title, body, logger } = options;
+  if (worktreeState?.finalCommit?.completed) {
+    const storedSha = worktreeState.finalCommit.sha;
+    if (!storedSha) {
+      throw new Error("Final Commit state is incomplete: missing stored sha");
+    }
+    const revParse2 = await execCapture("git", ["rev-parse", "HEAD"], {
+      cwd: worktreePath,
+      logger,
+      label: "git rev-parse HEAD"
+    });
+    const currentSha = revParse2.stdout.trim();
+    if (currentSha !== storedSha) {
+      throw new Error(
+        `Final Commit state is stale: stored sha ${storedSha} does not match current HEAD ${currentSha}`
+      );
+    }
+    return { status: "skipped", sha: storedSha };
+  }
+  await assertCanonicalBaseAncestor2({
+    worktreePath,
+    baseRef,
+    stageName: "final commit",
+    logger
+  });
+  await execCapture("git", ["reset", "--soft", baseRef], {
+    cwd: worktreePath,
+    logger,
+    label: "git reset"
+  });
+  await execCapture("git", ["add", "-A"], {
+    cwd: worktreePath,
+    logger,
+    label: "git add"
+  });
+  await execCapture("git", ["commit", "--no-verify", "-m", title, "-m", body], {
+    cwd: worktreePath,
+    logger,
+    label: "git commit"
+  });
+  const revParse = await execCapture("git", ["rev-parse", "HEAD"], {
+    cwd: worktreePath,
+    logger,
+    label: "git rev-parse HEAD"
+  });
+  const sha = revParse.stdout.trim();
+  updateWorktreeRunState(worktreePath, {
+    finalCommit: { completed: true, sha }
+  });
+  return { status: "completed", sha };
+}
+
 // issues/issue-worktree-resolution.ts
 init_common();
 import { join as join14 } from "path";
@@ -6895,35 +6961,20 @@ async function completeIssueRun(options) {
   );
   const prTitle = prDescriptionAgentResult.title;
   const prBody = prDescriptionAgentResult.body;
-  const stateBeforeFinalCommit = readCurrentWorktreeState();
-  const finalCommitFromState = stateBeforeFinalCommit?.finalCommit?.completed;
-  if (!finalCommitFromState) {
-    await finalizeWorktreeCommit({
-      worktreePath: executionResult.worktreePath,
-      baseRef: `origin/${effectiveBaseBranch}`,
-      title: prTitle,
-      body: prBody,
-      logger
-    });
-    if (executionResult.worktreePath) {
-      const revParse = await execCapture("git", ["rev-parse", "HEAD"], {
-        cwd: executionResult.worktreePath,
-        logger,
-        label: "git rev-parse HEAD"
-      });
-      updateWorktreeRunState(executionResult.worktreePath, {
-        finalCommit: {
-          completed: true,
-          sha: revParse.stdout.trim()
-        }
-      });
-    }
-  }
   if (!executionResult.worktreePath) {
     throw new Error(
       "Lifecycle invariant: GitHub Issue Publication requires a worktree path"
     );
   }
+  const stateBeforeFinalCommit = readCurrentWorktreeState();
+  await runFinalCommit({
+    worktreePath: executionResult.worktreePath,
+    worktreeState: stateBeforeFinalCommit,
+    baseRef: `origin/${effectiveBaseBranch}`,
+    title: prTitle,
+    body: prBody,
+    logger
+  });
   const publication = await publishGitHubIssue({
     issue,
     branchName,
@@ -7008,30 +7059,6 @@ function extractHumanHandoffSummary(artifactContent) {
 function getRefactorArtifactDir(artifactPath) {
   return artifactPath.replace(/\/reviewers\//, "/refactors/").replace(/\/[^/]+$/, "");
 }
-async function finalizeWorktreeCommit(options) {
-  const { worktreePath, baseRef, title, body, logger } = options;
-  await assertCanonicalBaseAncestor2({
-    worktreePath,
-    baseRef,
-    stageName: "final commit",
-    logger
-  });
-  await execCapture("git", ["reset", "--soft", baseRef], {
-    cwd: worktreePath,
-    logger,
-    label: "git reset"
-  });
-  await execCapture("git", ["add", "-A"], {
-    cwd: worktreePath,
-    logger,
-    label: "git add"
-  });
-  await execCapture("git", ["commit", "--no-verify", "-m", title, "-m", body], {
-    cwd: worktreePath,
-    logger,
-    label: "git commit"
-  });
-}
 function makeIssueTransitions2(provider, config) {
   return createIssueTransitions(
     {
@@ -7385,74 +7412,244 @@ import {
   writeFileSync as writeFileSync4
 } from "fs";
 import { join as join15 } from "path";
+import { z as z2 } from "zod";
+
+// prd-run/repair-guidance.ts
 import { z } from "zod";
+var PrdRunRepairAttemptSchema = z.object({
+  attemptedAt: z.string().min(1),
+  outcome: z.enum(["blocked", "projection-failed", "unsupported-state"]),
+  failureCode: z.string().min(1),
+  summary: z.string().min(1)
+}).strict();
+var PrdRunRepairGuidanceSchema = z.object({
+  createdAt: z.string().min(1),
+  updatedAt: z.string().min(1),
+  blockedGate: z.enum([
+    "receipt-check",
+    "branch-state",
+    "git",
+    "queue",
+    "final-review"
+  ]),
+  blockedStage: z.string().min(1),
+  failureCode: z.string().regex(
+    /^[a-z][a-z0-9-]*$/,
+    "failureCode must be kebab-case (lowercase letters, digits, hyphens)"
+  ),
+  humanReadableReason: z.string().min(1),
+  repairability: z.enum([
+    "automatic-retry-safe",
+    "operator-action",
+    "unsupported-state"
+  ]),
+  nextAction: z.string().min(1),
+  nextRecommendedCommand: z.string().min(1),
+  diagnostics: z.array(z.string()).optional(),
+  offendingPaths: z.array(z.string()).optional(),
+  issue: z.object({
+    number: z.number().int().positive(),
+    title: z.string().optional(),
+    branch: z.string().optional(),
+    worktreePath: z.string().optional()
+  }).strict().optional(),
+  pr: z.object({
+    number: z.number().int().positive().optional(),
+    url: z.string().url().optional()
+  }).strict().optional(),
+  attemptHistory: z.array(PrdRunRepairAttemptSchema).optional(),
+  targetName: z.string().min(1).optional(),
+  baseBranch: z.string().min(1).optional()
+}).strict();
+function buildPrdRunRepairGuidance(input) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return PrdRunRepairGuidanceSchema.parse({
+    createdAt: now,
+    updatedAt: now,
+    blockedGate: input.blockedGate,
+    blockedStage: input.blockedStage,
+    failureCode: input.failureCode,
+    humanReadableReason: input.humanReadableReason,
+    repairability: input.repairability,
+    nextAction: input.nextAction,
+    nextRecommendedCommand: input.nextRecommendedCommand,
+    diagnostics: input.diagnostics,
+    offendingPaths: input.offendingPaths,
+    issue: input.issue,
+    pr: input.pr,
+    targetName: input.targetName,
+    baseBranch: input.baseBranch,
+    attemptHistory: void 0
+  });
+}
+function appendPrdRunRepairAttempt(guidance, attempt) {
+  const newAttempt = {
+    attemptedAt: attempt.attemptedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    outcome: attempt.outcome,
+    failureCode: attempt.failureCode,
+    summary: attempt.summary
+  };
+  const history = [...guidance.attemptHistory ?? [], newAttempt].slice(-5);
+  return PrdRunRepairGuidanceSchema.parse({
+    ...guidance,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    attemptHistory: history
+  });
+}
+function validateActivePrdRunRepairGuidance(record) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (record.repairGuidance) {
+    const parsed = PrdRunRepairGuidanceSchema.safeParse(record.repairGuidance);
+    if (parsed.success) {
+      return { ok: true, guidance: parsed.data };
+    }
+    return {
+      ok: false,
+      guidance: {
+        createdAt: now,
+        updatedAt: now,
+        blockedGate: record.blockedGate ?? "queue",
+        blockedStage: "unknown",
+        failureCode: "malformed-repair-guidance",
+        humanReadableReason: "Repair guidance state is malformed or invalid. Inspect the PRD Run record.",
+        repairability: "unsupported-state",
+        nextAction: "inspect-prd-run-state",
+        nextRecommendedCommand: `pourkit prd-run status ${record.prdRef}`,
+        diagnostics: [
+          `Validation error: ${parsed.error?.message ?? "Unknown schema error"}`
+        ]
+      }
+    };
+  }
+  return {
+    ok: false,
+    guidance: {
+      createdAt: now,
+      updatedAt: now,
+      blockedGate: record.blockedGate ?? "queue",
+      blockedStage: "unknown",
+      failureCode: "missing-repair-guidance",
+      humanReadableReason: "No active repair guidance found for a blocked or unresolved record.",
+      repairability: "unsupported-state",
+      nextAction: "inspect-prd-run-state",
+      nextRecommendedCommand: `pourkit prd-run status ${record.prdRef}`,
+      diagnostics: record.diagnostics ? [...record.diagnostics] : []
+    }
+  };
+}
+function renderPrdRunRepairGuidance(guidance) {
+  const lines = [];
+  lines.push(`Blocked Gate: ${guidance.blockedGate}`);
+  lines.push(`Blocked Stage: ${guidance.blockedStage}`);
+  lines.push(`Failure Code: ${guidance.failureCode}`);
+  lines.push(`Reason: ${guidance.humanReadableReason}`);
+  lines.push(`Repairability: ${guidance.repairability}`);
+  lines.push(`Next Action: ${guidance.nextAction}`);
+  lines.push(`Command: ${guidance.nextRecommendedCommand}`);
+  if (guidance.targetName) lines.push(`Target: ${guidance.targetName}`);
+  if (guidance.baseBranch) lines.push(`Base: ${guidance.baseBranch}`);
+  if (guidance.issue) {
+    const issueLine = `Issue: #${guidance.issue.number}${guidance.issue.title ? ` - ${guidance.issue.title}` : ""}`;
+    lines.push(issueLine);
+    if (guidance.issue.branch) lines.push(`  Branch: ${guidance.issue.branch}`);
+    if (guidance.issue.worktreePath)
+      lines.push(`  Worktree: ${guidance.issue.worktreePath}`);
+  }
+  if (guidance.pr) {
+    if (guidance.pr.url) lines.push(`PR: ${guidance.pr.url}`);
+    else if (guidance.pr.number) lines.push(`PR: #${guidance.pr.number}`);
+  }
+  if (guidance.diagnostics && guidance.diagnostics.length > 0) {
+    lines.push("Diagnostics:");
+    for (const d of guidance.diagnostics) {
+      lines.push(`  - ${d}`);
+    }
+  }
+  if (guidance.offendingPaths && guidance.offendingPaths.length > 0) {
+    lines.push("Offending Paths:");
+    for (const p of guidance.offendingPaths) {
+      lines.push(`  - ${p}`);
+    }
+  }
+  if (guidance.attemptHistory && guidance.attemptHistory.length > 0) {
+    const latest = guidance.attemptHistory[guidance.attemptHistory.length - 1];
+    lines.push(`Latest Attempt: ${latest.outcome} - ${latest.summary}`);
+    if (guidance.attemptHistory.length > 1) {
+      lines.push(`Total Attempts: ${guidance.attemptHistory.length}`);
+    }
+  }
+  return lines;
+}
+
+// prd-run/state.ts
 var PRD_RUN_STATE_DIR = ".pourkit/prd-runs";
-var PrdRunRecordSchema = z.object({
-  prdRef: z.string().regex(
+var PrdRunRecordSchema = z2.object({
+  prdRef: z2.string().regex(
     /^PRD-\d{4}$/,
     "PRD ref must use four-digit format (e.g., PRD-0052)"
   ),
-  status: z.enum([
+  status: z2.enum([
     "blocked",
     "starting",
     "running",
     "drained",
     "completed_prd_branch"
   ]),
-  updatedAt: z.string().min(1),
-  blockedGate: z.enum(["receipt-check", "branch-state", "git", "queue", "final-review"]).optional(),
-  targetName: z.string().min(1).optional(),
-  prdBranch: z.string().min(1).optional(),
-  blockedReason: z.string().min(1).optional(),
-  diagnostics: z.array(z.string()).optional(),
-  offendingPaths: z.array(z.string()).optional(),
-  start: z.object({
-    status: z.enum(["started", "succeeded", "adopted", "reused"]),
-    targetName: z.string().min(1),
-    prdBranch: z.string().min(1),
-    startBaseBranch: z.string().min(1),
-    startBaseCommit: z.string().min(1).optional(),
-    branchAction: z.enum(["created", "reused", "adopted"]).optional(),
-    startedAt: z.string().min(1).optional(),
-    queueStartedAt: z.string().min(1).optional(),
-    queueDrainedAt: z.string().min(1).optional(),
-    queueProcessedCount: z.number().int().nonnegative().optional(),
-    queueCommand: z.literal("queue-run").optional(),
-    refreshReceipts: z.tuple([]).optional()
+  updatedAt: z2.string().min(1),
+  repairGuidance: PrdRunRepairGuidanceSchema.optional(),
+  blockedGate: z2.enum(["receipt-check", "branch-state", "git", "queue", "final-review"]).optional(),
+  targetName: z2.string().min(1).optional(),
+  prdBranch: z2.string().min(1).optional(),
+  blockedReason: z2.string().min(1).optional(),
+  diagnostics: z2.array(z2.string()).optional(),
+  offendingPaths: z2.array(z2.string()).optional(),
+  start: z2.object({
+    status: z2.enum(["started", "succeeded", "adopted", "reused"]),
+    targetName: z2.string().min(1),
+    prdBranch: z2.string().min(1),
+    startBaseBranch: z2.string().min(1),
+    startBaseCommit: z2.string().min(1).optional(),
+    branchAction: z2.enum(["created", "reused", "adopted"]).optional(),
+    startedAt: z2.string().min(1).optional(),
+    queueStartedAt: z2.string().min(1).optional(),
+    queueDrainedAt: z2.string().min(1).optional(),
+    queueProcessedCount: z2.number().int().nonnegative().optional(),
+    queueCommand: z2.literal("queue-run").optional(),
+    refreshReceipts: z2.tuple([]).optional()
   }).strict().optional(),
-  finalReview: z.object({
-    status: z.enum([
+  finalReview: z2.object({
+    status: z2.enum([
       "started",
       "succeeded",
       "blocked",
       "needs_human_review",
       "final_reviewed"
     ]),
-    targetName: z.string().min(1),
-    prdBranch: z.string().min(1),
-    mergeBase: z.string().min(1).optional(),
-    verdict: z.enum([
+    targetName: z2.string().min(1),
+    prdBranch: z2.string().min(1),
+    mergeBase: z2.string().min(1).optional(),
+    verdict: z2.enum([
       "pass_no_changes",
       "pass_with_retouch",
       "needs_human_review",
       "blocked"
     ]).optional(),
-    artifactPath: z.string().min(1).optional(),
-    diagnostics: z.array(z.string()).optional(),
-    reviewedAt: z.string().min(1).optional(),
-    retouchPrNumber: z.number().int().positive().optional(),
-    retouchPrUrl: z.string().url().optional(),
-    retouchMergeCommit: z.string().min(1).optional(),
-    autoMerge: z.boolean().optional(),
-    changedPaths: z.array(z.string()).optional()
+    artifactPath: z2.string().min(1).optional(),
+    diagnostics: z2.array(z2.string()).optional(),
+    reviewedAt: z2.string().min(1).optional(),
+    retouchPrNumber: z2.number().int().positive().optional(),
+    retouchPrUrl: z2.string().url().optional(),
+    retouchMergeCommit: z2.string().min(1).optional(),
+    autoMerge: z2.boolean().optional(),
+    changedPaths: z2.array(z2.string()).optional()
   }).strict().optional(),
-  scopeChanges: z.array(
-    z.object({
-      issueNumber: z.number().int().positive(),
-      decision: z.literal("accepted_scope_change"),
-      reason: z.string().min(1),
-      acceptedBy: z.string().min(1),
-      acceptedAt: z.string().min(1)
+  scopeChanges: z2.array(
+    z2.object({
+      issueNumber: z2.number().int().positive(),
+      decision: z2.literal("accepted_scope_change"),
+      reason: z2.string().min(1),
+      acceptedBy: z2.string().min(1),
+      acceptedAt: z2.string().min(1)
     }).strict()
   ).optional()
 }).strict();
@@ -7489,6 +7686,26 @@ function readPrdRun(repoRoot2, prdRef) {
       }
     } catch {
     }
+    try {
+      const raw = JSON.parse(readFileSync15(recordPath, "utf-8"));
+      if (raw && typeof raw === "object" && raw.status === "blocked" && raw.repairGuidance !== void 0) {
+        const { repairGuidance: _unused, ...rawWithoutGuidance } = raw;
+        const baseRecord = PrdRunRecordSchema.omit({
+          repairGuidance: true
+        }).parse(rawWithoutGuidance);
+        return {
+          record: {
+            ...baseRecord,
+            repairGuidance: raw.repairGuidance
+          },
+          diagnostics: [
+            `Repair guidance validation failed at ${recordPath}`,
+            error instanceof Error ? error.message : String(error)
+          ]
+        };
+      }
+    } catch {
+    }
     return {
       record: null,
       diagnostics: [
@@ -7525,14 +7742,11 @@ function listPrdRuns(repoRoot2) {
 }
 function writePrdRunRecord(repoRoot2, record) {
   const normalized = normalizePrdRunRef(record.prdRef);
+  const parsed = PrdRunRecordSchema.parse({ ...record, prdRef: normalized });
   const stateDir = join15(repoRoot2, PRD_RUN_STATE_DIR);
   const recordPath = getRecordPath(repoRoot2, normalized);
   mkdirSync7(stateDir, { recursive: true });
-  writeFileSync4(
-    recordPath,
-    JSON.stringify({ ...record, prdRef: normalized }, null, 2),
-    "utf-8"
-  );
+  writeFileSync4(recordPath, JSON.stringify(parsed, null, 2), "utf-8");
 }
 function getRecordPath(repoRoot2, prdRef) {
   return join15(
@@ -7888,24 +8102,45 @@ function runOneQueueIssueEffect(options) {
     prdRef
   } = options;
   return Effect9.gen(function* () {
-    const outcome = yield* selectNextQueueIssue({
-      config,
-      issueProvider,
-      logger,
-      prdRef
-    });
-    if (!outcome.ok) {
-      return {
-        selected: null,
-        reason: outcome.reason,
-        code: outcome.code
-      };
+    const resumeIssueNumber = options.queueRunContext?.resumeIssueNumber;
+    let selectedIssue;
+    if (resumeIssueNumber) {
+      const fetched = yield* Effect9.tryPromise({
+        try: () => issueProvider.fetchIssue(resumeIssueNumber),
+        catch: (e) => {
+          if (e instanceof Error) {
+            return new QueueProviderError(
+              `Failed to fetch resume issue #${resumeIssueNumber}: ${e.message}`
+            );
+          }
+          throw e;
+        }
+      });
+      selectedIssue = fetched;
+      logger.step(
+        "info",
+        `Resuming issue #${selectedIssue.number}: ${selectedIssue.title}`
+      );
+    } else {
+      const outcome = yield* selectNextQueueIssue({
+        config,
+        issueProvider,
+        logger,
+        prdRef
+      });
+      if (!outcome.ok) {
+        return {
+          selected: null,
+          reason: outcome.reason,
+          code: outcome.code
+        };
+      }
+      selectedIssue = outcome.issue;
     }
-    const { issue: selected } = outcome;
     const baseBranchOverride = options.queueRunContext?.prdBranch;
     const runResult = yield* Effect9.tryPromise({
       try: () => runIssueCommand({
-        issueNumber: selected.number,
+        issueNumber: selectedIssue.number,
         targetName,
         config,
         issueProvider,
@@ -7936,7 +8171,7 @@ function runOneQueueIssueEffect(options) {
       logger.raw(`  PR URL: ${runResult.prUrl}`);
     }
     logger.raw(`  Target: ${runResult.target.name}`);
-    return { selected, runResult };
+    return { selected: selectedIssue, runResult };
   });
 }
 function runQueue(options) {
@@ -7960,6 +8195,19 @@ function runQueueLoopEffect(options, results) {
       };
     }
     const newResults = [...results, outcome];
+    if (options.queueRunContext?.resumeIssueNumber !== void 0) {
+      return {
+        drained: true,
+        processedCount: newResults.length,
+        results: newResults,
+        selected: null,
+        reason: "Resumed issue processed.",
+        code: "drained",
+        allProcessedIssuesFinalizedIntoPrdBranch: Boolean(options.queueRunContext?.prdBranch) && newResults.length > 0 && newResults.every(
+          (result) => result.runResult.publicationStatus === "merged"
+        )
+      };
+    }
     const processedIssue = yield* Effect9.tryPromise({
       try: () => options.issueProvider.fetchIssue(outcome.selected.number),
       catch: (e) => {
@@ -8005,72 +8253,79 @@ function validatePrdRunStartEvidence(record, context) {
   if (!record.start) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "missing_start_evidence",
-        reason: `PRD Run ${context.prdRef} has no start receipt.`,
+        blockedStage: "branch-materialization",
+        failureCode: "missing-start-evidence",
+        humanReadableReason: `PRD Run ${context.prdRef} has no start receipt.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (!record.start.startBaseBranch) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "missing_start_base_branch",
-        reason: `PRD Run ${context.prdRef} start receipt missing startBaseBranch.`,
+        blockedStage: "branch-materialization",
+        failureCode: "missing-start-base-branch",
+        humanReadableReason: `PRD Run ${context.prdRef} start receipt missing startBaseBranch.`,
         repairability: "operator-action",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (record.start.startBaseBranch !== context.baseBranch) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "base_mismatch",
-        reason: `PRD Run ${context.prdRef} startBaseBranch "${record.start.startBaseBranch}" does not match expected "${context.baseBranch}".`,
+        blockedStage: "branch-materialization",
+        failureCode: "base-mismatch",
+        humanReadableReason: `PRD Run ${context.prdRef} startBaseBranch "${record.start.startBaseBranch}" does not match expected "${context.baseBranch}".`,
         repairability: "operator-action",
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch",
         diagnostics: [
           `Recorded startBaseBranch: ${record.start.startBaseBranch}`,
           `Expected baseBranch: ${context.baseBranch}`
-        ],
-        offendingPaths: []
-      }
+        ]
+      })
     };
   }
   if (!record.start.prdBranch) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "missing_prd_branch",
-        reason: `PRD Run ${context.prdRef} start receipt missing prdBranch.`,
+        blockedStage: "branch-materialization",
+        failureCode: "missing-prd-branch",
+        humanReadableReason: `PRD Run ${context.prdRef} start receipt missing prdBranch.`,
         repairability: "operator-action",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (record.prdRef !== context.prdRef) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "prd_ref_mismatch",
-        reason: `PRD Run prdRef mismatch: "${record.prdRef}" does not match expected "${context.prdRef}".`,
+        blockedStage: "branch-materialization",
+        failureCode: "prd-ref-mismatch",
+        humanReadableReason: `PRD Run prdRef mismatch: "${record.prdRef}" does not match expected "${context.prdRef}".`,
         repairability: "operator-action",
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch",
         diagnostics: [
           `Recorded prdRef: ${record.prdRef}`,
           `Expected prdRef: ${context.prdRef}`
-        ],
-        offendingPaths: []
-      }
+        ]
+      })
     };
   }
   return { ok: true };
@@ -8080,95 +8335,104 @@ function validatePrdRunDrainEvidence(record, context) {
   if (!start) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_drain_evidence",
-        reason: `PRD Run ${context.prdRef} has no start receipt for drain validation.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-drain-evidence",
+        humanReadableReason: `PRD Run ${context.prdRef} has no start receipt for drain validation.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (!start.queueStartedAt) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_queue_started_at",
-        reason: `PRD Run ${context.prdRef} drain evidence missing queueStartedAt.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-queue-started-at",
+        humanReadableReason: `PRD Run ${context.prdRef} drain evidence missing queueStartedAt.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (start.queueCommand !== "queue-run") {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_queue_command",
-        reason: `PRD Run ${context.prdRef} drain evidence missing queue-run command.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-queue-command",
+        humanReadableReason: `PRD Run ${context.prdRef} drain evidence missing queue-run command.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (!start.queueDrainedAt) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_queue_drained_at",
-        reason: `PRD Run ${context.prdRef} drain evidence missing queueDrainedAt.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-queue-drained-at",
+        humanReadableReason: `PRD Run ${context.prdRef} drain evidence missing queueDrainedAt.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (typeof start.queueProcessedCount !== "number") {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_queue_processed_count",
-        reason: `PRD Run ${context.prdRef} drain evidence missing queueProcessedCount.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-queue-processed-count",
+        humanReadableReason: `PRD Run ${context.prdRef} drain evidence missing queueProcessedCount.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   if (start.queueProcessedCount <= 0) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "zero_processed",
-        reason: `PRD Run ${context.prdRef} queue drain processed zero issues.`,
+        blockedStage: "queue-drain",
+        failureCode: "zero-processed",
+        humanReadableReason: `PRD Run ${context.prdRef} queue drain processed zero issues.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [`queueProcessedCount: ${start.queueProcessedCount}`],
-        offendingPaths: []
-      }
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch",
+        diagnostics: [`queueProcessedCount: ${start.queueProcessedCount}`]
+      })
     };
   }
   if (start.prdBranch !== context.prdBranch) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "prd_branch_mismatch",
-        reason: `PRD Run ${context.prdRef} prdBranch "${start.prdBranch}" does not match expected "${context.prdBranch}".`,
+        blockedStage: "queue-drain",
+        failureCode: "prd-branch-mismatch",
+        humanReadableReason: `PRD Run ${context.prdRef} prdBranch "${start.prdBranch}" does not match expected "${context.prdBranch}".`,
         repairability: "operator-action",
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch",
         diagnostics: [
           `Recorded prdBranch: ${start.prdBranch}`,
           `Expected prdBranch: ${context.prdBranch}`
-        ],
-        offendingPaths: []
-      }
+        ]
+      })
     };
   }
   return { ok: true };
@@ -8181,14 +8445,15 @@ function validatePrdRunTerminalEvidence(record, context) {
   if (context.allChildIssuesFinalizedIntoPrdBranch !== true) {
     return {
       ok: false,
-      guidance: {
+      guidance: buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_child_finalization_evidence",
-        reason: `PRD Run ${context.prdRef} is missing proof that all child Issues finalized into ${context.prdBranch}.`,
+        blockedStage: "queue-drain",
+        failureCode: "missing-child-finalization-evidence",
+        humanReadableReason: `PRD Run ${context.prdRef} is missing proof that all child Issues finalized into ${context.prdBranch}.`,
         repairability: "operator-action",
-        diagnostics: [],
-        offendingPaths: []
-      }
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      })
     };
   }
   return { ok: true };
@@ -8482,10 +8747,11 @@ function buildBlockedOutcome(repoRoot2, prdRef, guidance, targetName) {
     status: "blocked",
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     blockedGate: guidance.blockedGate,
-    blockedReason: guidance.reason,
-    diagnostics: [...guidance.diagnostics ?? []],
-    offendingPaths: [...guidance.offendingPaths ?? []],
-    targetName
+    blockedReason: guidance.humanReadableReason,
+    ...guidance.diagnostics?.length ? { diagnostics: [...guidance.diagnostics] } : {},
+    ...guidance.offendingPaths?.length ? { offendingPaths: [...guidance.offendingPaths] } : {},
+    targetName,
+    repairGuidance: guidance
   });
   return { kind: "blocked", prdRef, guidance };
 }
@@ -8508,17 +8774,21 @@ function persistStartingPrdRunRecord(repoRoot2, prdRef, existingRecord, start, c
     start
   });
 }
-function blocked(repoRoot2, prdRef, gate, failureCode, reason, diagnostics, targetName) {
+function blocked(repoRoot2, prdRef, gate, failureCode, reason, diagnostics, targetName, stage, repairability = "operator-action") {
   return buildBlockedOutcome(
     repoRoot2,
     prdRef,
-    {
+    buildPrdRunRepairGuidance({
       blockedGate: gate,
+      blockedStage: stage ?? gate,
       failureCode,
-      reason,
-      diagnostics: diagnostics ? [...diagnostics] : [],
-      repairability: "operator-action"
-    },
+      humanReadableReason: reason,
+      repairability,
+      nextAction: repairability === "automatic-retry-safe" ? "rerun-prd-run-launch" : "inspect-and-retry",
+      nextRecommendedCommand: `pourkit prd-run launch ${prdRef}`,
+      ...diagnostics?.length ? { diagnostics: [...diagnostics] } : {},
+      ...targetName ? { targetName } : {}
+    }),
     targetName
   );
 }
@@ -8530,8 +8800,11 @@ async function startPrdRun(options) {
       options.repoRoot,
       prdRef,
       "branch-state",
-      "invalid_target_name",
-      `Invalid target name "${options.targetName}". Expected a non-empty target name.`
+      "invalid-target-name",
+      `Invalid target name "${options.targetName}". Expected a non-empty target name.`,
+      void 0,
+      void 0,
+      "start-validation"
     );
   }
   const existingRecord = readPrdRun(options.repoRoot, prdRef);
@@ -8546,10 +8819,11 @@ async function startPrdRun(options) {
       options.repoRoot,
       prdRef,
       baseResolution.gate,
-      "base_resolution_failed",
+      "base-resolution-failed",
       baseResolution.reason,
       baseResolution.diagnostics,
-      targetName
+      targetName,
+      "start-validation"
     );
   }
   if (existingRecord.record?.start) {
@@ -8559,10 +8833,12 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         "branch-state",
-        "missing_start_base_branch",
+        "missing-start-base-branch",
         `PRD Run ${prdRef} has a start receipt without startBaseBranch. Run prd-run start to create a fresh start receipt.`,
         [`Recorded start: ${JSON.stringify(existingRecord.record.start)}`],
-        targetName
+        targetName,
+        "start-validation",
+        "unsupported-state"
       );
     }
     if (recordedBaseBranch !== baseResolution.baseBranch) {
@@ -8570,13 +8846,14 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         "branch-state",
-        "base_mismatch",
+        "base-mismatch",
         `PRD Run ${prdRef} start receipt records startBaseBranch "${recordedBaseBranch}" but current base resolution resolves to "${baseResolution.baseBranch}". Use --base with the matching value or create a fresh start receipt.`,
         [
           `Recorded startBaseBranch: ${recordedBaseBranch}`,
           `Current base resolution: ${baseResolution.baseBranch} (source: ${baseResolution.source})`
         ],
-        targetName
+        targetName,
+        "start-validation"
       );
     }
     const currentStatus = existingRecord.record.status;
@@ -8595,9 +8872,12 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         fetchResult2.gate,
-        "fetch_failed",
+        "fetch-failed",
         fetchResult2.reason,
-        fetchResult2.diagnostics
+        fetchResult2.diagnostics,
+        targetName,
+        "branch-materialization",
+        "automatic-retry-safe"
       );
     }
     const branchResult2 = inspectRemotePrdBranch(options.repoRoot, prdRef);
@@ -8606,9 +8886,12 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         branchResult2.gate,
-        "branch_inspection_failed",
+        "branch-inspection-failed",
         branchResult2.reason,
-        branchResult2.diagnostics
+        branchResult2.diagnostics,
+        targetName,
+        "branch-materialization",
+        "automatic-retry-safe"
       );
     }
     if (branchResult2.exists) {
@@ -8638,14 +8921,16 @@ async function startPrdRun(options) {
           options.repoRoot,
           prdRef,
           "branch-state",
-          "unrecorded_branch_exists",
+          "unrecorded-branch-exists",
           `PRD Branch ${prdRef} already exists remotely but PRD Run state does not record the same branch and start base commit. Use --adopt-existing-branch to adopt it.`,
           [
             `Existing remote branch: ${prdRef}`,
             `Recorded start branch: ${matchingStart.prdBranch}`,
             `Recorded start base commit: ${matchingStart.startBaseCommit}`,
             `Current origin/${recordedBaseBranch} head: ${fetchResult2.startBaseCommit}`
-          ]
+          ],
+          targetName,
+          "branch-materialization"
         );
       }
       const fetchPrdResult = fetchPrdBranch(options.repoRoot, prdRef);
@@ -8654,9 +8939,12 @@ async function startPrdRun(options) {
           options.repoRoot,
           prdRef,
           fetchPrdResult.gate,
-          "fetch_prd_branch_failed",
+          "fetch-prd-branch-failed",
           fetchPrdResult.reason,
-          fetchPrdResult.diagnostics
+          fetchPrdResult.diagnostics,
+          targetName,
+          "branch-materialization",
+          "automatic-retry-safe"
         );
       }
       const ancestryResult = spawnSync2(
@@ -8674,12 +8962,14 @@ async function startPrdRun(options) {
           options.repoRoot,
           prdRef,
           "branch-state",
-          "ancestry_check_failed",
+          "ancestry-check-failed",
           `PRD Branch ${prdRef} base ancestry check failed: origin/${recordedBaseBranch} is not an ancestor of origin/${prdRef}. Cannot adopt.`,
           [
             `Base branch: origin/${recordedBaseBranch}`,
             `PRD branch: origin/${prdRef}`
-          ]
+          ],
+          targetName,
+          "branch-materialization"
         );
       }
       const adoptedStart = buildStartReceipt({
@@ -8715,9 +9005,12 @@ async function startPrdRun(options) {
       options.repoRoot,
       prdRef,
       fetchResult.gate,
-      "fetch_failed",
+      "fetch-failed",
       fetchResult.reason,
-      fetchResult.diagnostics
+      fetchResult.diagnostics,
+      targetName,
+      "branch-materialization",
+      "automatic-retry-safe"
     );
   }
   const branchResult = inspectRemotePrdBranch(options.repoRoot, prdRef);
@@ -8726,9 +9019,12 @@ async function startPrdRun(options) {
       options.repoRoot,
       prdRef,
       branchResult.gate,
-      "branch_inspection_failed",
+      "branch-inspection-failed",
       branchResult.reason,
-      branchResult.diagnostics
+      branchResult.diagnostics,
+      targetName,
+      "branch-materialization",
+      "automatic-retry-safe"
     );
   }
   if (branchResult.exists) {
@@ -8737,14 +9033,16 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         "branch-state",
-        "unrecorded_branch_exists",
+        "unrecorded-branch-exists",
         `PRD Branch ${prdRef} already exists remotely but PRD Run state does not record the same branch and start base commit. Use --adopt-existing-branch to adopt it.`,
         [
           `Existing remote branch: ${prdRef}`,
           `Recorded start branch: ${existingRecord.record?.start?.prdBranch ?? "(missing)"}`,
           `Recorded start base commit: ${existingRecord.record?.start?.startBaseCommit ?? "(missing)"}`,
           `Current origin/${baseResolution.baseBranch} head: ${fetchResult.startBaseCommit}`
-        ]
+        ],
+        targetName,
+        "branch-materialization"
       );
     }
     const fetchPrdResult = fetchPrdBranch(options.repoRoot, prdRef);
@@ -8753,9 +9051,12 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         fetchPrdResult.gate,
-        "fetch_prd_branch_failed",
+        "fetch-prd-branch-failed",
         fetchPrdResult.reason,
-        fetchPrdResult.diagnostics
+        fetchPrdResult.diagnostics,
+        targetName,
+        "branch-materialization",
+        "automatic-retry-safe"
       );
     }
     const ancestryResult = spawnSync2(
@@ -8773,12 +9074,14 @@ async function startPrdRun(options) {
         options.repoRoot,
         prdRef,
         "branch-state",
-        "ancestry_check_failed",
+        "ancestry-check-failed",
         `PRD Branch ${prdRef} base ancestry check failed: origin/${baseResolution.baseBranch} is not an ancestor of origin/${prdRef}. Cannot adopt.`,
         [
           `Base branch: origin/${baseResolution.baseBranch}`,
           `PRD branch: origin/${prdRef}`
-        ]
+        ],
+        targetName,
+        "branch-materialization"
       );
     }
     const adoptedStart = buildStartReceipt({
@@ -8815,11 +9118,14 @@ async function startPrdRun(options) {
       options.repoRoot,
       prdRef,
       "git",
-      "branch_creation_failed",
+      "branch-creation-failed",
       `Failed to create PRD Branch ${prdRef} from ${fetchResult.startBaseCommit}.`,
       [error instanceof Error ? error.message : String(error)].filter(
         (v) => Boolean(v && v.trim())
-      )
+      ),
+      targetName,
+      "branch-materialization",
+      "automatic-retry-safe"
     );
   }
   const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -8842,11 +9148,28 @@ async function startPrdRun(options) {
     diagnostics: []
   };
 }
-function buildLaunchBlockedOutcome(prdRef, guidance, resume, start) {
+function buildLaunchBlockedOutcome(repoRoot2, prdRef, guidance, resume, start, targetName, startReceipt) {
+  const enrichedGuidance = {
+    ...guidance,
+    targetName: guidance.targetName ?? targetName,
+    baseBranch: guidance.baseBranch ?? startReceipt?.startBaseBranch
+  };
+  writePrdRunRecord(repoRoot2, {
+    prdRef,
+    status: "blocked",
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    blockedGate: enrichedGuidance.blockedGate,
+    blockedReason: enrichedGuidance.humanReadableReason,
+    ...enrichedGuidance.diagnostics?.length ? { diagnostics: [...enrichedGuidance.diagnostics] } : {},
+    ...enrichedGuidance.offendingPaths?.length ? { offendingPaths: [...enrichedGuidance.offendingPaths] } : {},
+    ...targetName ? { targetName } : {},
+    ...startReceipt ? { start: startReceipt } : {},
+    repairGuidance: enrichedGuidance
+  });
   return {
     kind: "blocked",
     prdRef,
-    guidance,
+    guidance: enrichedGuidance,
     start,
     resume
   };
@@ -8860,32 +9183,146 @@ function writeDrainedRecord(repoRoot2, prdRef, startReceipt, targetName) {
     start: startReceipt
   });
 }
-function writeTerminalRecord(repoRoot2, prdRef, status, targetName, startReceipt, prdBranch) {
-  writePrdRunRecord(repoRoot2, {
-    prdRef,
-    status,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    targetName,
-    prdBranch,
-    start: startReceipt
-  });
+function writeTerminalRecord(repoRoot2, prdRef, status, targetName, startReceipt, prdBranch) {
+  writePrdRunRecord(repoRoot2, {
+    prdRef,
+    status,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    targetName,
+    prdBranch,
+    start: startReceipt
+  });
+}
+function validateRecordedIssueResumeEvidence(options) {
+  const { prdRef, guidance, startReceipt, targetName } = options;
+  const diagnostics = [];
+  if (guidance.targetName && guidance.targetName !== targetName) {
+    diagnostics.push(
+      `Recorded targetName: ${guidance.targetName}; current targetName: ${targetName}`
+    );
+  }
+  if (guidance.baseBranch && startReceipt?.startBaseBranch && guidance.baseBranch !== startReceipt.startBaseBranch) {
+    diagnostics.push(
+      `Recorded baseBranch: ${guidance.baseBranch}; current startBaseBranch: ${startReceipt.startBaseBranch}`
+    );
+  }
+  const worktreePath = guidance.issue?.worktreePath;
+  if (worktreePath) {
+    const worktreeState = readWorktreeRunState(worktreePath);
+    if (!worktreeState) {
+      diagnostics.push(
+        `Worktree Run State missing or malformed at ${worktreePath}`
+      );
+    } else {
+      if (guidance.issue?.number !== worktreeState.issueNumber) {
+        diagnostics.push(
+          `Recorded issue #${guidance.issue?.number}; Worktree Run State issue #${worktreeState.issueNumber}`
+        );
+      }
+      if (guidance.issue?.branch && guidance.issue.branch !== worktreeState.branchName) {
+        diagnostics.push(
+          `Recorded issue branch: ${guidance.issue.branch}; Worktree Run State branch: ${worktreeState.branchName}`
+        );
+      }
+      if (worktreeState.targetName !== targetName) {
+        diagnostics.push(
+          `Worktree Run State targetName: ${worktreeState.targetName}; current targetName: ${targetName}`
+        );
+      }
+      if (startReceipt?.prdBranch && worktreeState.baseBranch !== startReceipt.prdBranch) {
+        diagnostics.push(
+          `Worktree Run State baseBranch: ${worktreeState.baseBranch}; expected PRD Branch: ${startReceipt.prdBranch}`
+        );
+      }
+    }
+  }
+  if (diagnostics.length === 0) return null;
+  return buildPrdRunRepairGuidance({
+    blockedGate: "queue",
+    blockedStage: guidance.blockedStage || "queue-drain",
+    failureCode: worktreePath ? "worktree-evidence-mismatch" : "branch-evidence-mismatch",
+    humanReadableReason: `PRD Run ${prdRef} recorded repair guidance does not match current resume evidence.`,
+    repairability: "unsupported-state",
+    nextAction: "inspect-prd-run-state",
+    nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
+    diagnostics,
+    issue: guidance.issue,
+    pr: guidance.pr,
+    targetName: guidance.targetName,
+    baseBranch: guidance.baseBranch
+  });
+}
+async function attemptRecordedIssueLabelProjection(options, prdRef, resumeIssueNumber, originalGuidance) {
+  if (resumeIssueNumber === void 0) return true;
+  try {
+    await options.issueProvider.removeLabel(
+      resumeIssueNumber,
+      options.config.labels.agentInProgress
+    );
+    return true;
+  } catch {
+    const state = readPrdRun(options.repoRoot, prdRef).record;
+    const guidance = originalGuidance ?? state?.repairGuidance;
+    if (guidance) {
+      const updated = appendPrdRunRepairAttempt(guidance, {
+        outcome: "projection-failed",
+        failureCode: "label-projection-failed",
+        summary: `Failed to remove "${options.config.labels.agentInProgress}" label from issue #${resumeIssueNumber}`
+      });
+      if (state) {
+        writePrdRunRecord(options.repoRoot, {
+          ...state,
+          repairGuidance: updated,
+          updatedAt: updated.updatedAt
+        });
+      }
+    }
+    return false;
+  }
 }
 async function launchPrdRun(options) {
   const prdRef = normalizePrdRunRef(options.prdRef);
   const existingRecord = readPrdRun(options.repoRoot, prdRef);
   const plan = planPrdRunLaunchResume(existingRecord.record);
+  const rec = existingRecord.record;
+  if (rec && (rec.status === "starting" || rec.status === "running") && !rec.repairGuidance) {
+    return buildLaunchBlockedOutcome(
+      options.repoRoot,
+      prdRef,
+      buildPrdRunRepairGuidance({
+        blockedGate: "branch-state",
+        blockedStage: "start-validation",
+        failureCode: "prd-run-in-progress",
+        humanReadableReason: `PRD Run ${prdRef} is already ${rec.status}. A second launch cannot start another Queue drain while the run is in progress.`,
+        repairability: "automatic-retry-safe",
+        nextAction: "wait-or-inspect-active-run",
+        nextRecommendedCommand: "pourkit prd-run status",
+        diagnostics: [
+          `PRD Run ${prdRef} is in status "${rec.status}" without active repair guidance.`
+        ]
+      }),
+      plan,
+      void 0,
+      options.targetName
+    );
+  }
   if (existingRecord.record === null && existingRecord.diagnostics.length > 0) {
     return buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "receipt-check",
-        failureCode: "unsupported_legacy_state",
-        reason: `PRD Run ${prdRef} has a malformed or unsupported record. The stored status is no longer a valid launch state.`,
+        blockedStage: "start-validation",
+        failureCode: "unsupported-legacy-state",
+        humanReadableReason: `PRD Run ${prdRef} has a malformed or unsupported record. The stored status is no longer a valid launch state.`,
         repairability: "unsupported-state",
-        diagnostics: [...existingRecord.diagnostics],
-        offendingPaths: []
-      },
-      plan
+        nextAction: "inspect-prd-run-state",
+        nextRecommendedCommand: "pourkit prd-run status",
+        diagnostics: [...existingRecord.diagnostics]
+      }),
+      plan,
+      void 0,
+      options.targetName
     );
   }
   if (existingRecord.record?.status === "completed_prd_branch") {
@@ -8904,16 +9341,20 @@ async function launchPrdRun(options) {
     const record = existingRecord.record;
     if (!record.start) {
       return buildLaunchBlockedOutcome(
+        options.repoRoot,
         prdRef,
-        {
+        buildPrdRunRepairGuidance({
           blockedGate: "queue",
-          failureCode: "missing_drain_evidence",
-          reason: `PRD Run ${prdRef} is drained but missing start receipt.`,
+          blockedStage: "queue-drain",
+          failureCode: "missing-drain-evidence",
+          humanReadableReason: `PRD Run ${prdRef} is drained but missing start receipt.`,
           repairability: "automatic-retry-safe",
-          diagnostics: [],
-          offendingPaths: []
-        },
-        plan
+          nextAction: "rerun-prd-run-launch",
+          nextRecommendedCommand: "pourkit prd-run launch"
+        }),
+        plan,
+        void 0,
+        options.targetName
       );
     }
     const resolvedTarget = options.config ? resolveTarget(options.config, options.targetName) : null;
@@ -8924,16 +9365,22 @@ async function launchPrdRun(options) {
     });
     if (!baseResolution.ok) {
       return buildLaunchBlockedOutcome(
+        options.repoRoot,
         prdRef,
-        {
+        buildPrdRunRepairGuidance({
           blockedGate: baseResolution.gate,
-          failureCode: "base_resolution_failed",
-          reason: baseResolution.reason,
+          blockedStage: "start-validation",
+          failureCode: "base-resolution-failed",
+          humanReadableReason: baseResolution.reason,
           repairability: "operator-action",
+          nextAction: "inspect-and-retry",
+          nextRecommendedCommand: "pourkit prd-run launch",
           diagnostics: [...baseResolution.diagnostics],
           offendingPaths: [...baseResolution.offendingPaths]
-        },
-        plan
+        }),
+        plan,
+        void 0,
+        options.targetName
       );
     }
     const drainContext = {
@@ -8946,7 +9393,14 @@ async function launchPrdRun(options) {
       drainContext
     );
     if (!terminalEvidence.ok) {
-      return buildLaunchBlockedOutcome(prdRef, terminalEvidence.guidance, plan);
+      return buildLaunchBlockedOutcome(
+        options.repoRoot,
+        prdRef,
+        terminalEvidence.guidance,
+        plan,
+        void 0,
+        options.targetName
+      );
     }
     writeTerminalRecord(
       options.repoRoot,
@@ -8969,18 +9423,23 @@ async function launchPrdRun(options) {
   }
   if (plan.blocked === "missing-start-receipt") {
     return buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "missing_start_receipt",
-        reason: `PRD Run ${prdRef} is missing branch/start state. Run prd-run start or rerun prd-run launch.`,
+        blockedStage: "start-validation",
+        failureCode: "missing-start-receipt",
+        humanReadableReason: `PRD Run ${prdRef} is missing branch/start state. Run prd-run start or rerun prd-run launch.`,
         repairability: "automatic-retry-safe",
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch",
         diagnostics: [
           `PRD Run ${prdRef} is in status "${existingRecord.record?.status}" but has no start receipt.`
-        ],
-        offendingPaths: []
-      },
-      plan
+        ]
+      }),
+      plan,
+      void 0,
+      options.targetName
     );
   }
   let startOutcome;
@@ -9010,6 +9469,62 @@ async function launchPrdRun(options) {
   const currentRecord = readPrdRun(options.repoRoot, prdRef).record;
   const startReceipt = currentRecord?.start;
   const targetName = currentRecord?.targetName ?? options.targetName;
+  let resumeIssueNumber;
+  if (currentRecord?.repairGuidance) {
+    const validation = validateActivePrdRunRepairGuidance(currentRecord);
+    if (!validation.ok) {
+      return buildLaunchBlockedOutcome(
+        options.repoRoot,
+        prdRef,
+        validation.guidance,
+        plan,
+        startOutcome,
+        targetName,
+        startReceipt
+      );
+    }
+    const resumeEvidenceFailure = validateRecordedIssueResumeEvidence({
+      prdRef,
+      guidance: validation.guidance,
+      startReceipt,
+      targetName
+    });
+    if (resumeEvidenceFailure) {
+      return buildLaunchBlockedOutcome(
+        options.repoRoot,
+        prdRef,
+        resumeEvidenceFailure,
+        plan,
+        startOutcome,
+        targetName,
+        startReceipt
+      );
+    }
+    if (validation.guidance.issue?.number) {
+      resumeIssueNumber = validation.guidance.issue.number;
+    } else {
+      return buildLaunchBlockedOutcome(
+        options.repoRoot,
+        prdRef,
+        buildPrdRunRepairGuidance({
+          blockedGate: "queue",
+          blockedStage: "queue-drain",
+          failureCode: "missing-issue-identity",
+          humanReadableReason: `PRD Run ${prdRef} has repair guidance without a recorded Issue identity. Resume is not possible.`,
+          repairability: "unsupported-state",
+          nextAction: "inspect-prd-run-state",
+          nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
+          diagnostics: [
+            "Repair guidance exists but is missing issue.number field."
+          ]
+        }),
+        plan,
+        startOutcome,
+        targetName,
+        startReceipt
+      );
+    }
+  }
   if (startReceipt) {
     startReceipt.queueStartedAt = (/* @__PURE__ */ new Date()).toISOString();
     startReceipt.queueCommand = "queue-run";
@@ -9019,7 +9534,8 @@ async function launchPrdRun(options) {
     status: "running",
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     targetName,
-    start: startReceipt
+    start: startReceipt,
+    repairGuidance: currentRecord?.repairGuidance
   });
   return await launchGithubQueueDrain(
     options,
@@ -9027,98 +9543,78 @@ async function launchPrdRun(options) {
     startReceipt,
     targetName,
     plan,
-    startOutcome
+    startOutcome,
+    resumeIssueNumber
   );
 }
-async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName, plan, startOutcome) {
+async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName, plan, startOutcome, resumeIssueNumber) {
   if (!options.issueProvider || !options.prProvider || !options.executionProvider || !options.logger) {
     const reason = `PRD Run ${prdRef} requires issueProvider, prProvider, executionProvider, and logger for GitHub-backed queue drain.`;
-    writePrdRunRecord(options.repoRoot, {
-      prdRef,
-      status: "blocked",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      targetName,
-      start: startReceipt,
-      blockedGate: "queue",
-      blockedReason: reason,
-      diagnostics: [
-        "Missing one or more required providers for GitHub-backed mode.",
-        "Provide --issue-provider, --pr-provider, --execution-provider, and --logger options."
-      ],
-      offendingPaths: []
-    });
     return buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_github_providers",
-        reason,
+        blockedStage: "queue-drain",
+        failureCode: "missing-github-providers",
+        humanReadableReason: reason,
         repairability: "operator-action",
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch --with-providers",
         diagnostics: [
           "Missing one or more required providers for GitHub-backed mode."
-        ],
-        offendingPaths: []
-      },
+        ]
+      }),
       plan,
-      startOutcome
+      startOutcome,
+      targetName,
+      startReceipt
     );
   }
   if (!startReceipt) {
-    writePrdRunRecord(options.repoRoot, {
-      prdRef,
-      status: "blocked",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      targetName,
-      blockedGate: "branch-state",
-      blockedReason: `PRD Run ${prdRef} is missing start receipt before GitHub queue drain.`,
-      diagnostics: [],
-      offendingPaths: []
-    });
     return buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "branch-state",
-        failureCode: "missing_start_receipt",
-        reason: `PRD Run ${prdRef} is missing start receipt before GitHub queue drain.`,
+        blockedStage: "start-validation",
+        failureCode: "missing-start-receipt",
+        humanReadableReason: `PRD Run ${prdRef} is missing start receipt before GitHub queue drain.`,
         repairability: "automatic-retry-safe",
-        diagnostics: [],
-        offendingPaths: []
-      },
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch"
+      }),
       plan,
-      startOutcome
+      startOutcome,
+      targetName
     );
   }
   if (!options.config) {
     const reason = `PRD Run ${prdRef} requires config for GitHub-backed queue drain.`;
-    writePrdRunRecord(options.repoRoot, {
-      prdRef,
-      status: "blocked",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      targetName,
-      start: startReceipt,
-      blockedGate: "queue",
-      blockedReason: reason,
-      diagnostics: ["Missing config for GitHub-backed mode."],
-      offendingPaths: []
-    });
     return buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "missing_config",
-        reason,
+        blockedStage: "queue-drain",
+        failureCode: "missing-config",
+        humanReadableReason: reason,
         repairability: "operator-action",
-        diagnostics: ["Missing config for GitHub-backed mode."],
-        offendingPaths: []
-      },
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch --with-config",
+        diagnostics: ["Missing config for GitHub-backed mode."]
+      }),
       plan,
-      startOutcome
+      startOutcome,
+      targetName,
+      startReceipt
     );
   }
   const issueProvider = options.issueProvider;
   const prProvider = options.prProvider;
   const executionProvider = options.executionProvider;
   const logger = options.logger;
+  const originalGuidance = readPrdRun(options.repoRoot, prdRef).record?.repairGuidance;
   try {
     const outcome = await runQueueCommand({
       targetName,
@@ -9133,7 +9629,8 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
       prdRef,
       queueRunContext: {
         prdRef,
-        prdBranch: startReceipt.prdBranch
+        prdBranch: startReceipt.prdBranch,
+        ...resumeIssueNumber !== void 0 ? { resumeIssueNumber } : {}
       }
     });
     if (outcome.selected === null && outcome.code === "drained") {
@@ -9141,30 +9638,41 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
         const diagnostics = [
           "Queue drained without processing issues. No PRD-scoped candidates or runnable Issues."
         ];
-        writePrdRunRecord(options.repoRoot, {
-          prdRef,
-          status: "blocked",
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          targetName,
-          start: startReceipt,
-          blockedGate: "queue",
-          blockedReason: diagnostics[0],
-          diagnostics,
-          offendingPaths: []
-        });
-        return buildLaunchBlockedOutcome(
+        const result2 = buildLaunchBlockedOutcome(
+          options.repoRoot,
           prdRef,
-          {
+          buildPrdRunRepairGuidance({
             blockedGate: "queue",
-            failureCode: "zero_processed",
-            reason: diagnostics[0],
+            blockedStage: "queue-drain",
+            failureCode: "zero-processed",
+            humanReadableReason: diagnostics[0],
             repairability: "automatic-retry-safe",
-            diagnostics,
-            offendingPaths: []
-          },
+            nextAction: "rerun-prd-run-launch",
+            nextRecommendedCommand: "pourkit prd-run launch",
+            diagnostics
+          }),
           plan,
-          startOutcome
+          startOutcome,
+          targetName,
+          startReceipt
+        );
+        const projectionOk2 = await attemptRecordedIssueLabelProjection(
+          options,
+          prdRef,
+          resumeIssueNumber,
+          originalGuidance
         );
+        if (!projectionOk2 && originalGuidance) {
+          const updatedRecord = readPrdRun(options.repoRoot, prdRef).record;
+          return {
+            kind: "blocked",
+            prdRef,
+            guidance: updatedRecord.repairGuidance,
+            start: startOutcome,
+            resume: plan
+          };
+        }
+        return result2;
       }
       startReceipt.queueDrainedAt = (/* @__PURE__ */ new Date()).toISOString();
       startReceipt.queueProcessedCount = outcome.processedCount;
@@ -9184,10 +9692,13 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
         );
         if (!terminalEvidence.ok) {
           return buildLaunchBlockedOutcome(
+            options.repoRoot,
             prdRef,
             terminalEvidence.guidance,
             plan,
-            startOutcome
+            startOutcome,
+            targetName,
+            startReceipt
           );
         }
       }
@@ -9213,84 +9724,117 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
     }
     if (outcome.selected === null) {
       const diagnostics = [outcome.reason];
-      writePrdRunRecord(options.repoRoot, {
-        prdRef,
-        status: "blocked",
-        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        targetName,
-        start: startReceipt,
-        blockedGate: "queue",
-        blockedReason: outcome.reason,
-        diagnostics,
-        offendingPaths: []
-      });
-      return buildLaunchBlockedOutcome(
+      const result2 = buildLaunchBlockedOutcome(
+        options.repoRoot,
         prdRef,
-        {
+        buildPrdRunRepairGuidance({
           blockedGate: "queue",
-          failureCode: "queue_blocked",
-          reason: outcome.reason,
+          blockedStage: "queue-drain",
+          failureCode: "queue-blocked",
+          humanReadableReason: outcome.reason,
           repairability: "automatic-retry-safe",
-          diagnostics,
-          offendingPaths: []
-        },
+          nextAction: "rerun-prd-run-launch",
+          nextRecommendedCommand: "pourkit prd-run launch",
+          diagnostics
+        }),
         plan,
-        startOutcome
+        startOutcome,
+        targetName,
+        startReceipt
+      );
+      const projectionOk2 = await attemptRecordedIssueLabelProjection(
+        options,
+        prdRef,
+        resumeIssueNumber,
+        originalGuidance
       );
+      if (!projectionOk2 && originalGuidance) {
+        const updatedRecord = readPrdRun(options.repoRoot, prdRef).record;
+        return {
+          kind: "blocked",
+          prdRef,
+          guidance: updatedRecord.repairGuidance,
+          start: startOutcome,
+          resume: plan
+        };
+      }
+      return result2;
     }
     const outcomeReason = `Unexpected queue outcome: selected issue ${outcome.selected.number}`;
     const outcomeDiagnostics = [outcomeReason];
-    writePrdRunRecord(options.repoRoot, {
-      prdRef,
-      status: "blocked",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      targetName,
-      start: startReceipt,
-      blockedGate: "queue",
-      blockedReason: outcomeReason,
-      diagnostics: outcomeDiagnostics,
-      offendingPaths: []
-    });
-    return buildLaunchBlockedOutcome(
+    const result = buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "unexpected_queue_outcome",
-        reason: outcomeReason,
+        blockedStage: "queue-drain",
+        failureCode: "unexpected-queue-outcome",
+        humanReadableReason: outcomeReason,
         repairability: "operator-action",
-        diagnostics: outcomeDiagnostics,
-        offendingPaths: []
-      },
+        nextAction: "inspect-and-retry",
+        nextRecommendedCommand: "pourkit prd-run launch",
+        diagnostics: outcomeDiagnostics
+      }),
       plan,
-      startOutcome
+      startOutcome,
+      targetName,
+      startReceipt
+    );
+    const projectionOk = await attemptRecordedIssueLabelProjection(
+      options,
+      prdRef,
+      resumeIssueNumber,
+      originalGuidance
     );
+    if (!projectionOk && originalGuidance) {
+      const updatedRecord = readPrdRun(options.repoRoot, prdRef).record;
+      return {
+        kind: "blocked",
+        prdRef,
+        guidance: updatedRecord.repairGuidance,
+        start: startOutcome,
+        resume: plan
+      };
+    }
+    return result;
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     const diagnostics = [msg];
-    writePrdRunRecord(options.repoRoot, {
-      prdRef,
-      status: "blocked",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      targetName,
-      start: startReceipt,
-      blockedGate: "queue",
-      blockedReason: msg,
-      diagnostics,
-      offendingPaths: []
-    });
-    return buildLaunchBlockedOutcome(
+    const result = buildLaunchBlockedOutcome(
+      options.repoRoot,
       prdRef,
-      {
+      buildPrdRunRepairGuidance({
         blockedGate: "queue",
-        failureCode: "queue_exception",
-        reason: msg,
+        blockedStage: "queue-drain",
+        failureCode: "queue-exception",
+        humanReadableReason: msg,
         repairability: "automatic-retry-safe",
-        diagnostics,
-        offendingPaths: []
-      },
+        nextAction: "rerun-prd-run-launch",
+        nextRecommendedCommand: "pourkit prd-run launch",
+        diagnostics
+      }),
       plan,
-      startOutcome
+      startOutcome,
+      targetName,
+      startReceipt
+    );
+    const projectionOk = await attemptRecordedIssueLabelProjection(
+      options,
+      prdRef,
+      resumeIssueNumber,
+      originalGuidance
     );
+    if (!projectionOk && originalGuidance) {
+      const updatedRecord = readPrdRun(options.repoRoot, prdRef).record;
+      return {
+        kind: "blocked",
+        prdRef,
+        guidance: updatedRecord.repairGuidance,
+        start: startOutcome,
+        resume: plan
+      };
+    }
+    return result;
   }
 }
 
@@ -9341,7 +9885,7 @@ function mapLaunchPrdRunOutcomeToCommandResult(outcome, options) {
     };
   }
   if (outcome.kind === "blocked") {
-    const diagnostics = outcome.guidance.diagnostics ? [...outcome.guidance.diagnostics] : [outcome.guidance.reason];
+    const diagnostics = renderPrdRunRepairGuidance(outcome.guidance);
     return {
       prdRef,
       status: "blocked",
@@ -9350,7 +9894,7 @@ function mapLaunchPrdRunOutcomeToCommandResult(outcome, options) {
       resumed: [...outcome.resume.resumed],
       diagnostics,
       blockedGate: outcome.guidance.blockedGate,
-      blockedReason: outcome.guidance.reason,
+      blockedReason: outcome.guidance.humanReadableReason,
       offendingPaths: outcome.guidance.offendingPaths ? [...outcome.guidance.offendingPaths] : [],
       start: outcome.start ? mapStartPrdRunOutcomeToCommandResult(outcome.start) : void 0
     };
@@ -9375,27 +9919,40 @@ function mapStartPrdRunOutcomeToCommandResult(outcome) {
       diagnostics: [...outcome.diagnostics]
     };
   }
-  const diagnostics = outcome.guidance.diagnostics ? [...outcome.guidance.diagnostics] : [outcome.guidance.reason];
   return {
     prdRef: outcome.prdRef,
     status: "blocked",
     blockedGate: outcome.guidance.blockedGate,
-    blockedReason: outcome.guidance.reason,
-    diagnostics,
+    blockedReason: outcome.guidance.humanReadableReason,
+    diagnostics: renderPrdRunRepairGuidance(outcome.guidance),
     offendingPaths: outcome.guidance.offendingPaths ? [...outcome.guidance.offendingPaths] : []
   };
 }
 function runPrdRunStatusCommand(options) {
   const prdRef = normalizePrdRunRef(options.prdRef);
   const { record, diagnostics } = readPrdRun(options.repoRoot, prdRef);
-  return {
-    prdRef,
-    record,
-    diagnostics: record?.status === "completed_prd_branch" ? [
-      ...diagnostics,
-      buildCompletedPrdBranchHint(record.prdBranch ?? prdRef)
-    ] : diagnostics
-  };
+  if (record?.status === "completed_prd_branch") {
+    return {
+      prdRef,
+      record,
+      diagnostics: [
+        ...diagnostics,
+        buildCompletedPrdBranchHint(record.prdBranch ?? prdRef)
+      ]
+    };
+  }
+  if (record?.status === "blocked") {
+    const validated = validateActivePrdRunRepairGuidance(record);
+    return {
+      prdRef,
+      record,
+      diagnostics: [
+        ...diagnostics,
+        ...renderPrdRunRepairGuidance(validated.guidance)
+      ]
+    };
+  }
+  return { prdRef, record, diagnostics };
 }
 function runPrdRunListCommand(options) {
   return listPrdRuns(options.repoRoot);
@@ -12478,7 +13035,7 @@ async function runSerenaStatusCommand(options) {
 // commands/config-schema.ts
 import { readFileSync as readFileSync18, existsSync as existsSync18 } from "fs";
 import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile2, readdir as readdir2 } from "fs/promises";
-import { resolve as resolve3, dirname as dirname5, relative as relative2 } from "path";
+import { resolve as resolve3, dirname as dirname5, relative as relative3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import Ajv2 from "ajv";
 init_common();
@@ -12541,7 +13098,7 @@ async function readPackagedTextFile(filePath) {
   }
 }
 function isPathContained(parent, child) {
-  const relativePath = relative2(parent, child);
+  const relativePath = relative3(parent, child);
   return !relativePath.startsWith("..") && !relativePath.startsWith("../");
 }
 async function walkDir2(dir) {
@@ -12796,7 +13353,7 @@ async function validateWorkflowPack(cwd) {
   if (existsSync18(overridesDir)) {
     const overrideFiles = await walkDir2(overridesDir);
     for (const file of overrideFiles) {
-      const relPath = relative2(cwd, file);
+      const relPath = relative3(cwd, file);
       if (!warnings.some((w) => w.kind === "overridden" && w.path === relPath)) {
         warnings.push({
           severity: "warning",
@@ -12936,8 +13493,8 @@ async function validateWorkflowPack(cwd) {
         failures.push({
           severity: "failure",
           kind: "path_escape",
-          path: relative2(cwd, file),
-          message: `Override file path escapes repository: ${relative2(cwd, file)}`
+          path: relative3(cwd, file),
+          message: `Override file path escapes repository: ${relative3(cwd, file)}`
         });
       }
     }
@@ -12949,7 +13506,7 @@ async function validateWorkflowPack(cwd) {
       if (!file.endsWith(".md")) continue;
       try {
         const content = await readFile5(file, "utf-8");
-        const relPath = relative2(cwd, file);
+        const relPath = relative3(cwd, file);
         const violations = scanManagedPolicyText(content, relPath);
         for (const v of violations) {
           failures.push({
@@ -12972,7 +13529,7 @@ async function validateWorkflowPack(cwd) {
       if (!existsSync18(skillFile)) continue;
       try {
         const content = await readFile5(skillFile, "utf-8");
-        const relPath = relative2(cwd, skillFile);
+        const relPath = relative3(cwd, skillFile);
         const violations = scanManagedPolicyText(content, relPath);
         for (const v of violations) {
           failures.push({
@@ -12993,7 +13550,7 @@ async function validateWorkflowPack(cwd) {
       if (!existsSync18(promptFile)) continue;
       try {
         const content = await readFile5(promptFile, "utf-8");
-        const relPath = relative2(cwd, promptFile);
+        const relPath = relative3(cwd, promptFile);
         const violations = scanManagedPolicyText(content, relPath);
         for (const v of violations) {
           failures.push({
@@ -13015,7 +13572,7 @@ async function validateWorkflowPack(cwd) {
     if (!existsSync18(addonSkillFile)) continue;
     try {
       const content = await readFile5(addonSkillFile, "utf-8");
-      const relPath = relative2(cwd, addonSkillFile);
+      const relPath = relative3(cwd, addonSkillFile);
       const violations = scanManagedPolicyText(content, relPath);
       for (const v of violations) {
         failures.push({
@@ -13036,7 +13593,7 @@ async function validateWorkflowPack(cwd) {
     if (!existsSync18(addonDocFile)) continue;
     try {
       const content = await readFile5(addonDocFile, "utf-8");
-      const relPath = relative2(cwd, addonDocFile);
+      const relPath = relative3(cwd, addonDocFile);
       const violations = scanManagedPolicyText(content, relPath);
       for (const v of violations) {
         failures.push({
@@ -13229,7 +13786,7 @@ async function runConfigSyncSchemaCommand(options) {
 // commands/workflow-pack-sync.ts
 import { existsSync as existsSync19, readdirSync as readdirSync4 } from "fs";
 import { mkdir as mkdir6, readFile as readFile6, writeFile as writeFile3, readdir as readdir3 } from "fs/promises";
-import { resolve as resolve4, dirname as dirname6, relative as relative3, normalize as normalize2 } from "path";
+import { resolve as resolve4, dirname as dirname6, relative as relative4, normalize as normalize2 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 var __filename4 = fileURLToPath4(import.meta.url);
 var __dirname4 = dirname6(__filename4);
@@ -13272,7 +13829,7 @@ async function readPackagedTextFile2(filePath) {
   }
 }
 function isPathContained2(parent, child) {
-  const relativePath = relative3(parent, child);
+  const relativePath = relative4(parent, child);
   return !relativePath.startsWith("..") && !relativePath.startsWith("../");
 }
 function isProjectOwnedPath(relativePath) {
@@ -13381,7 +13938,7 @@ async function detectOverrides(cwd) {
     return [];
   }
   const files = await walkDir3(overridesDir);
-  return files.map((f) => relative3(cwd, f));
+  return files.map((f) => relative4(cwd, f));
 }
 async function detectProjectOwnedFiles(cwd) {
   const found = [];
@@ -13396,7 +13953,7 @@ async function detectProjectOwnedFiles(cwd) {
     if (existsSync19(fullDir)) {
       const files = await walkDir3(fullDir);
       for (const file of files) {
-        found.push(relative3(cwd, file));
+        found.push(relative4(cwd, file));
       }
     }
   }
@@ -13649,7 +14206,7 @@ async function syncSkill(skillName, catalog, acc, ctx) {
     return;
   }
   for (const sourceFile of skillFiles) {
-    const relPath = relative3(skillDir, sourceFile);
+    const relPath = relative4(skillDir, sourceFile);
     const targetRelativePath = `.pourkit/managed/skills/${skillName}/${relPath}`;
     if (isProjectOwnedPath(targetRelativePath)) {
       skippedProjectOwned.push(targetRelativePath);
@@ -13725,7 +14282,7 @@ async function syncAddonSkill(skillName, acc, ctx) {
     return;
   }
   for (const sourceFile of skillFiles) {
-    const relPath = relative3(addonSkillDir, sourceFile);
+    const relPath = relative4(addonSkillDir, sourceFile);
     const targetRelativePath = `.pourkit/managed/addons/release/skills/${skillName}/${relPath}`;
     if (isProjectOwnedPath(targetRelativePath)) {
       skippedProjectOwned.push(targetRelativePath);
@@ -15517,11 +16074,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260623021955")) {
-    return "0.0.0-next-20260623021955";
+  if (isPackageVersion("0.0.0-next-20260624074234")) {
+    return "0.0.0-next-20260624074234";
   }
-  if (isReleaseVersion("0.0.0-next-20260623021955")) {
-    return "0.0.0-next-20260623021955";
+  if (isReleaseVersion("0.0.0-next-20260624074234")) {
+    return "0.0.0-next-20260624074234";
   }
   try {
     const root = repoRoot();