@pourkit/cli 0.0.0-next-20260623054630 → 0.0.0-next-20260625065443

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";
@@ -7401,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();
@@ -7505,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: [
@@ -7541,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(
@@ -7904,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,
@@ -7952,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) {
@@ -7976,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) => {
@@ -8021,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 };
@@ -8096,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 };
@@ -8197,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 };
@@ -8498,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 };
 }
@@ -8524,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
   );
 }
@@ -8546,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);
@@ -8562,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) {
@@ -8575,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) {
@@ -8586,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;
@@ -8611,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);
@@ -8622,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) {
@@ -8654,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);
@@ -8670,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(
@@ -8690,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({
@@ -8731,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);
@@ -8742,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) {
@@ -8753,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);
@@ -8769,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(
@@ -8789,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({
@@ -8831,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();
@@ -8858,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
   };
@@ -8886,22 +9193,136 @@ function writeTerminalRecord(repoRoot2, prdRef, status, targetName, startReceipt
     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") {
@@ -8920,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;
@@ -8940,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 = {
@@ -8962,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,
@@ -8985,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;
@@ -9026,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";
@@ -9035,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,
@@ -9043,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,
@@ -9149,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") {
@@ -9157,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;
@@ -9200,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
           );
         }
       }
@@ -9229,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;
   }
 }
 
@@ -9357,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",
@@ -9366,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
     };
@@ -9391,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);
@@ -10093,9 +10634,9 @@ Recall before substantial work: before starting non-trivial planning or implemen
 
 Capture durable knowledge: store concise reusable observations when a durable resolved error, design decision, user preference, significant outcome, or long-session progress summary is discovered. Do not store trivial details, raw logs, transcripts, tool output, git status, prompt dumps, secrets, or ephemeral state.
 
-Database path: use \`$POURKIT_ICM_DB\` when set, otherwise use \`.pourkit/icm/memories.db\`. The Pourkit Memory Store is repo-scoped; do not use a global ICM database or topic naming as the isolation boundary.
+Database path: host CLI commands must pass \`--db .pourkit/icm/memories.db\` from the repository root. Pourkit-launched Docker runs set \`$POURKIT_ICM_DB\` to the mounted container DB path for runtime plumbing. The Pourkit Memory Store is repo-scoped; do not use a global ICM database or topic naming as the isolation boundary.
 
-CLI fallback: when MCP memory tools are unavailable, recall with \`icm --db "$POURKIT_ICM_DB" recall "<query>"\` or \`icm --db .pourkit/icm/memories.db recall "<query>"\`, and store durable observations with \`icm --db "$POURKIT_ICM_DB" store -c "<concise reusable observation>"\` or \`icm --db .pourkit/icm/memories.db store -c "<concise reusable observation>"\`.
+CLI fallback: when MCP memory tools are unavailable, recall with \`icm --db .pourkit/icm/memories.db recall "<query>"\`, and store durable observations with \`icm --db .pourkit/icm/memories.db store -c "<concise reusable observation>"\`.
 
 Memory is advisory only. Never treat memory as a replacement for reading current repository files, Run Context, artifacts, or verification output. When memory conflicts with current source or canonical state, current source and canonical state win.
 
@@ -10107,17 +10648,17 @@ You MUST use it actively. Not optional.
 
 ### Recall (before starting work)
 \`\`\`bash
-icm recall "query"                        # search memories
-icm recall "query" -t "topic-name"        # filter by topic
-icm recall-context "query" --limit 5      # formatted for prompt injection
+icm --db .pourkit/icm/memories.db recall "query"                        # search memories
+icm --db .pourkit/icm/memories.db recall "query" -t "topic-name"        # filter by topic
+icm --db .pourkit/icm/memories.db recall-context "query" --limit 5      # formatted for prompt injection
 \`\`\`
 
 ### Store \u2014 MANDATORY triggers
-You MUST call \`icm store\` when ANY of the following happens:
-1. **Error resolved** \u2192 \`icm store -t errors-resolved -c "description" -i high -k "keyword1,keyword2"\`
-2. **Architecture/design decision** \u2192 \`icm store -t decisions-{project} -c "description" -i high\`
-3. **User preference discovered** \u2192 \`icm store -t preferences -c "description" -i critical\`
-4. **Significant task completed** \u2192 \`icm store -t context-{project} -c "summary of work done" -i high\`
+You MUST call \`icm --db .pourkit/icm/memories.db store\` when ANY of the following happens:
+1. **Error resolved** \u2192 \`icm --db .pourkit/icm/memories.db store -t errors-resolved -c "description" -i high -k "keyword1,keyword2"\`
+2. **Architecture/design decision** \u2192 \`icm --db .pourkit/icm/memories.db store -t decisions-{project} -c "description" -i high\`
+3. **User preference discovered** \u2192 \`icm --db .pourkit/icm/memories.db store -t preferences -c "description" -i critical\`
+4. **Significant task completed** \u2192 \`icm --db .pourkit/icm/memories.db store -t context-{project} -c "summary of work done" -i high\`
 5. **Conversation exceeds ~20 tool calls without a store** \u2192 store a progress summary
 
 Do this BEFORE responding to the user. Not after. Not later. Immediately.
@@ -10126,9 +10667,9 @@ Do NOT store: trivial details, info already in CLAUDE.md, ephemeral state (build
 
 ### Other commands
 \`\`\`bash
-icm update <id> -c "updated content"     # edit memory in-place
-icm health                                # topic hygiene audit
-icm topics                                # list all topics
+icm --db .pourkit/icm/memories.db update <id> -c "updated content"     # edit memory in-place
+icm --db .pourkit/icm/memories.db health                                # topic hygiene audit
+icm --db .pourkit/icm/memories.db topics                                # list all topics
 \`\`\`
 <!-- icm:end -->`;
 }
@@ -12296,9 +12837,13 @@ Init applied: ${result.applied} operations applied, ${result.skipped} skipped.`
 
 // commands/memory-init.ts
 import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync17, writeFileSync as writeFileSync5 } from "fs";
+import { execFile as execFile3 } from "child_process";
 import { join as join17 } from "path";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
 async function runMemoryInitCommand(options) {
   const cwd = options.cwd ?? process.cwd();
+  const execCommand = options.execCommand ?? execFileAsync3;
   const configPath = join17(cwd, ".pourkit", "config.json");
   if (!existsSync17(configPath)) {
     return {
@@ -12331,7 +12876,21 @@ async function runMemoryInitCommand(options) {
     const next = { ...raw, memory };
     writeFileSync5(configPath, JSON.stringify(next, null, 2) + "\n");
   }
-  mkdirSync8(join17(cwd, ".pourkit", "icm"), { recursive: true });
+  const memoryDir = join17(cwd, ".pourkit", "icm");
+  const memoryDbPath = join17(memoryDir, "memories.db");
+  mkdirSync8(memoryDir, { recursive: true });
+  let dbInitialized = false;
+  let warning;
+  try {
+    await execCommand(
+      "icm",
+      ["--db", memoryDbPath, "recall", "pourkit memory init smoke"],
+      { cwd }
+    );
+    dbInitialized = true;
+  } catch {
+    warning = "ICM is not available or could not initialize .pourkit/icm/memories.db. Install ICM and run `pourkit doctor` to verify repo-scoped memory setup.";
+  }
   const gitignorePath = join17(cwd, ".gitignore");
   updateManagedBlockSync(gitignorePath, generateGitignoreBlock());
   const managed = await generateManagedAgentInstructions({
@@ -12352,7 +12911,9 @@ async function runMemoryInitCommand(options) {
   return {
     ok: true,
     alreadyEnabled,
-    message: alreadyEnabled ? "Memory is already enabled. Refreshed repo-scoped memory setup." : "Memory enabled. Run `pourkit doctor` to verify setup."
+    dbInitialized,
+    warning,
+    message: `${alreadyEnabled ? "Memory is already enabled. Refreshed repo-scoped memory setup." : "Memory enabled. Run `pourkit doctor` to verify setup."}${warning ? ` ${warning}` : ""}`
   };
 }
 function updateManagedBlockSync(filePath, content) {
@@ -12494,7 +13055,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();
@@ -12533,6 +13094,8 @@ function localSchemaDir(repoRoot2) {
   return resolve3(repoRoot2, ".pourkit/schema");
 }
 var MANAGED_BLOCK_BEGIN2 = "<!-- BEGIN POURKIT MANAGED BLOCK -->\n";
+var MANAGED_BLOCK_BEGIN_MARKER = MANAGED_BLOCK_BEGIN2.trim();
+var MANAGED_BLOCK_END_MARKER = "<!-- END POURKIT MANAGED BLOCK -->";
 var OLD_DOCS_PATH_PATTERN = ".pourkit/docs/agents/";
 function resolvePackagedManagedPath(...segments) {
   return resolve3(__dirname3, "..", "managed", ...segments);
@@ -12557,7 +13120,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) {
@@ -12812,7 +13375,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",
@@ -12952,8 +13515,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)}`
         });
       }
     }
@@ -12965,7 +13528,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({
@@ -12988,7 +13551,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({
@@ -13009,7 +13572,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({
@@ -13031,7 +13594,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({
@@ -13052,7 +13615,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({
@@ -13090,21 +13653,53 @@ async function validateMemoryHealth(cwd, memoryConfig) {
     ok: hasGitignoreEntry,
     detail: hasGitignoreEntry ? ".gitignore covers .pourkit/icm/" : ".gitignore does not cover .pourkit/icm/"
   });
+  const memoryDbPath = resolve3(cwd, ".pourkit", "icm", "memories.db");
+  const hasMemoryDb = existsSync18(memoryDbPath);
+  checks.push({
+    name: "icm-db-exists",
+    ok: hasMemoryDb,
+    detail: hasMemoryDb ? ".pourkit/icm/memories.db exists" : ".pourkit/icm/memories.db is missing"
+  });
   const shapeValid = memoryConfig.enabled === true && memoryConfig.provider === "icm";
   checks.push({
     name: "config-memory-shape",
     ok: shapeValid,
     detail: shapeValid ? "memory: { enabled: true, provider: icm }" : `invalid memory config: enabled=${memoryConfig.enabled}, provider=${memoryConfig.provider}`
   });
+  const staleAgentFiles = ["AGENTS.md", "CLAUDE.md"].filter((fileName) => {
+    const filePath = resolve3(cwd, fileName);
+    if (!existsSync18(filePath)) return false;
+    const content = readFileSync18(filePath, "utf-8");
+    const managedBlock = extractManagedBlockContent(content);
+    return managedBlock !== null && hasBareIcmMemoryCommand(managedBlock);
+  });
+  checks.push({
+    name: "agent-memory-instructions",
+    ok: staleAgentFiles.length === 0,
+    detail: staleAgentFiles.length === 0 ? "managed agent memory instructions avoid bare ICM commands" : `stale bare ICM commands found in ${staleAgentFiles.join(", ")}`
+  });
   checks.push({
     name: "docker-image-advisory",
     ok: true,
     detail: "advisory only"
   });
   const ok = checks.filter((c) => c.name !== "docker-image-advisory").every((c) => c.ok);
-  const recommendation = ok ? null : "Run `pourkit memory init` to repair ICM memory setup, install ICM on PATH for host planning, or rebuild the sandbox image for Docker runs.";
+  const recommendation = ok ? null : "Run `pourkit memory init` or `pourkit sync workflow-pack` to repair ICM memory setup, install ICM on PATH for host planning, or rebuild the sandbox image for Docker runs.";
   return { ok, enabled: true, checks, recommendation };
 }
+function hasBareIcmMemoryCommand(content) {
+  return /(^|\n)\s*icm\s+(recall|recall-context|store|update|health|topics)\b/.test(
+    content
+  ) || /`icm\s+(recall|recall-context|store|update|health|topics)\b/.test(content);
+}
+function extractManagedBlockContent(content) {
+  const beginIdx = content.indexOf(MANAGED_BLOCK_BEGIN_MARKER);
+  if (beginIdx === -1) return null;
+  const contentStart = beginIdx + MANAGED_BLOCK_BEGIN_MARKER.length;
+  const endIdx = content.indexOf(MANAGED_BLOCK_END_MARKER, contentStart);
+  if (endIdx === -1) return null;
+  return content.slice(contentStart, endIdx);
+}
 async function runDoctorCommand(options) {
   const repoRootPath = options.cwd ?? process.cwd();
   const schemaDir = localSchemaDir(repoRootPath);
@@ -13245,7 +13840,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);
@@ -13288,7 +13883,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) {
@@ -13397,7 +13992,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 = [];
@@ -13412,7 +14007,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));
       }
     }
   }
@@ -13665,7 +14260,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);
@@ -13741,7 +14336,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);
@@ -15533,11 +16128,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260623054630")) {
-    return "0.0.0-next-20260623054630";
+  if (isPackageVersion("0.0.0-next-20260625065443")) {
+    return "0.0.0-next-20260625065443";
   }
-  if (isReleaseVersion("0.0.0-next-20260623054630")) {
-    return "0.0.0-next-20260623054630";
+  if (isReleaseVersion("0.0.0-next-20260625065443")) {
+    return "0.0.0-next-20260625065443";
   }
   try {
     const root = repoRoot();