@gethmy/agent 1.14.4 → 1.15.0

package/dist/cli.js

@@ -102,6 +102,16 @@ var init_log = __esm(() => {
 });
 
 // src/board-helpers.ts
+var exports_board_helpers = {};
+__export(exports_board_helpers, {
+  resolveCardLabels: () => resolveCardLabels,
+  moveCardToColumn: () => moveCardToColumn,
+  moveCardAndAddLabel: () => moveCardAndAddLabel,
+  hasLabel: () => hasLabel,
+  findOrCreateLabel: () => findOrCreateLabel,
+  buildLabelMap: () => buildLabelMap,
+  addLabelByName: () => addLabelByName
+});
 function buildLabelMap(boardLabels) {
   const map = new Map;
   for (const label of boardLabels) {
@@ -695,6 +705,22 @@ var init_config_validation = __esm(() => {
 });
 
 // src/git-pr.ts
+var exports_git_pr = {};
+__export(exports_git_pr, {
+  validateGitProviderCli: () => validateGitProviderCli,
+  updateExistingPr: () => updateExistingPr,
+  resolvePrUrl: () => resolvePrUrl,
+  renameRemoteBranch: () => renameRemoteBranch,
+  remoteBranchExists: () => remoteBranchExists,
+  pushBranch: () => pushBranch,
+  getBranchWebUrl: () => getBranchWebUrl,
+  findExistingPr: () => findExistingPr,
+  extractPrUrl: () => extractPrUrl,
+  detectGitProvider: () => detectGitProvider,
+  createPullRequest: () => createPullRequest,
+  checkPrMergeStatus: () => checkPrMergeStatus,
+  buildPrBody: () => buildPrBody
+});
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 function detectGitProvider(cwd) {
@@ -816,6 +842,14 @@ function extractPrUrl(description) {
     return null;
   }
 }
+function resolvePrUrl(description, branchName, cwd, provider) {
+  const fromDesc = extractPrUrl(description);
+  if (fromDesc)
+    return fromDesc;
+  if (!branchName)
+    return null;
+  return findExistingPr(branchName, cwd, provider) || null;
+}
 function remoteBranchExists(branchName, cwd) {
   try {
     execFileSync("git", ["ls-remote", "--exit-code", "origin", `refs/heads/${branchName}`], { cwd, stdio: "pipe" });
@@ -1602,6 +1636,48 @@ var init_logger = () => {};
 var init_playbookCatalog = () => {};
 
 // ../harmony-shared/dist/playbookStage.js
+function normalizeLoopDef(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    return null;
+  const obj = raw;
+  if (obj.mode !== "converge" && obj.mode !== "fanout")
+    return null;
+  const mode = obj.mode;
+  const rawMax = obj.max_iterations;
+  const maxInt = typeof rawMax === "number" && Number.isFinite(rawMax) && rawMax >= 1 ? Math.floor(rawMax) : DEFAULT_LOOP_MAX_ITERATIONS;
+  const exitGate = obj.exit_gate && typeof obj.exit_gate === "object" && !Array.isArray(obj.exit_gate) ? obj.exit_gate : null;
+  const def = { mode, max_iterations: maxInt };
+  if (exitGate)
+    def.exit_gate = exitGate;
+  if (obj.item_source && typeof obj.item_source === "object" && !Array.isArray(obj.item_source)) {
+    def.item_source = obj.item_source;
+  }
+  if (typeof obj.concurrency === "number" && obj.concurrency >= 1) {
+    def.concurrency = Math.floor(obj.concurrency);
+  }
+  if (obj.on_item_fail === "continue" || obj.on_item_fail === "halt") {
+    def.on_item_fail = obj.on_item_fail;
+  }
+  return def;
+}
+function getStageLoop(stage) {
+  return normalizeLoopDef(stage.loop);
+}
+function isConvergeLoop(loop) {
+  return loop !== null && loop.mode === "converge";
+}
+function decideLoopContinuation(args) {
+  const { loop, gatePassed, hasExitGate, completedIterations } = args;
+  const max = Math.max(1, Math.floor(loop.max_iterations) || 1);
+  if (!hasExitGate) {
+    return completedIterations >= max ? "exit" : "iterate";
+  }
+  if (gatePassed)
+    return "exit";
+  if (completedIterations >= max)
+    return "exhausted";
+  return "iterate";
+}
 function readStageDefs(def) {
   if (def.steps_version !== 2)
     return [];
@@ -1638,7 +1714,7 @@ function entryActionAllowlist(entryAction) {
     return `mcp__${entryAction}`;
   return null;
 }
-var SKILL_TOOL_ALLOWLIST, HARMONY_TOOL_RE;
+var DEFAULT_LOOP_MAX_ITERATIONS = 5, SKILL_TOOL_ALLOWLIST, HARMONY_TOOL_RE;
 var init_playbookStage = __esm(() => {
   SKILL_TOOL_ALLOWLIST = {
     hmy: "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*",
@@ -2187,6 +2263,10 @@ var init_review_worktree = __esm(() => {
 });
 
 // src/merge-monitor.ts
+var exports_merge_monitor = {};
+__export(exports_merge_monitor, {
+  MergeMonitor: () => MergeMonitor
+});
 import { execFile as execFile2 } from "node:child_process";
 import { promisify as promisify2 } from "node:util";
 
@@ -2220,6 +2300,9 @@ class MergeMonitor {
     }
     log.info(TAG7, "Merge monitor stopped");
   }
+  async runOnce() {
+    await this.tick();
+  }
   async scheduleNext(delayMs) {
     await new Promise((resolve3) => {
       this.timer = setTimeout(() => resolve3(), delayMs);
@@ -2257,9 +2340,10 @@ class MergeMonitor {
       const batch = candidatesWithLabels.slice(0, 5);
       log.debug(TAG7, `Checking ${batch.length} Ready to Merge card(s)`);
       const results = await Promise.allSettled(batch.map(async ({ card, labels }) => {
-        const prUrl = extractPrUrl(card.description ?? null);
+        const branchName = extractBranchFromDescription(card.description);
+        const prUrl = resolvePrUrl(card.description ?? null, branchName, this.cwd, this.provider);
         if (!prUrl) {
-          log.debug(TAG7, `#${card.short_id} has no PR URL — skipping`);
+          log.debug(TAG7, `#${card.short_id} has no resolvable PR — skipping`);
           return;
         }
         const state = await checkPrMergeStatus(prUrl, this.cwd, this.provider);
@@ -5575,6 +5659,30 @@ class StateStore {
       rec.attempts = 0;
     await this.persist();
   }
+  getLoopIterations(cardId, stageId) {
+    const rec = this.getCard(cardId);
+    if (!rec || rec.loopStageId !== stageId)
+      return 0;
+    return rec.loopIterations ?? 0;
+  }
+  async incrementLoopIteration(cardId, stageId) {
+    const rec = this.ensureCard(cardId);
+    if (rec.loopStageId !== stageId) {
+      rec.loopStageId = stageId;
+      rec.loopIterations = 0;
+    }
+    rec.loopIterations = (rec.loopIterations ?? 0) + 1;
+    await this.persist();
+    return rec.loopIterations;
+  }
+  async resetLoopIterations(cardId) {
+    const rec = this.getCard(cardId);
+    if (!rec || rec.loopIterations == null && rec.loopStageId == null)
+      return;
+    rec.loopStageId = null;
+    rec.loopIterations = 0;
+    await this.persist();
+  }
   async resetAttempts(cardId) {
     const rec = this.getCard(cardId);
     if (!rec || rec.attempts === 0)
@@ -6708,6 +6816,26 @@ class CliAgentRunner {
     this.enqueue({ kind: "playbook_advanced", source: "system", payload });
     this.startTimer();
   }
+  recordLoopIterationStarted(payload) {
+    this.enqueue({ kind: "loop_iteration_started", source: "system", payload });
+    this.startTimer();
+  }
+  recordLoopIterationEvaluated(payload) {
+    this.enqueue({
+      kind: "loop_iteration_evaluated",
+      source: "system",
+      payload: { ...payload, evidence: truncateOutput(payload.evidence) }
+    });
+    this.startTimer();
+  }
+  recordLoopCompleted(payload) {
+    this.enqueue({ kind: "loop_completed", source: "system", payload });
+    this.startTimer();
+  }
+  recordLoopExhausted(payload) {
+    this.enqueue({ kind: "loop_exhausted", source: "system", payload });
+    this.startTimer();
+  }
   record(body) {
     this.enqueue(body);
     this.startTimer();
@@ -6803,7 +6931,7 @@ When finished, call harmony_end_agent_session with status="completed".`
 }
 async function renderCommentsSection(client, cardId) {
   try {
-    const { comments } = await client.getComments(cardId, { limit: 200 });
+    const { comments } = await client.request("GET", `/cards/${encodeURIComponent(cardId)}/comments?limit=200&order=desc`);
     if (!Array.isArray(comments) || comments.length === 0)
       return "";
     const section = serializeCommentThread(comments, {
@@ -6935,6 +7063,121 @@ async function resolveStageColumnName(client, card, stage) {
 async function persistStagePointer(client, card, body) {
   await client.request("POST", `/cards/${encodeURIComponent(card.id)}/advance-stage`, body);
 }
+async function advanceStageRun(card, stage, stageIndex, def, evaluation, deps) {
+  const loop = getStageLoop(stage);
+  if (!isConvergeLoop(loop)) {
+    if (!evaluation)
+      return { kind: "no_advance" };
+    return advanceStageOnGate(card, stage, stageIndex, def, evaluation, deps);
+  }
+  return advanceConvergeLoop(card, stage, stageIndex, def, evaluation, loop, deps);
+}
+function firstErrorMessage(evaluation) {
+  const e = evaluation?.findings.find((f) => f.level === "error");
+  return e ? e.message : null;
+}
+async function advanceConvergeLoop(card, stage, stageIndex, def, evaluation, loop, deps) {
+  const hasExitGate = loop.exit_gate != null;
+  const gatePassed = hasExitGate ? evaluation?.passed ?? false : false;
+  const gateResult = !hasExitGate ? "skipped" : gatePassed ? "passed" : "failed";
+  const maxIterations = Math.max(1, Math.floor(loop.max_iterations) || 1);
+  const iteration = await deps.stateStore.incrementLoopIteration(card.id, stage.id);
+  const decision = decideLoopContinuation({
+    loop,
+    gatePassed,
+    hasExitGate,
+    completedIterations: iteration
+  });
+  const evidence = evaluation ? evaluation.findings.map((f) => `[${f.level}] ${f.message}`).join(`
+`) : undefined;
+  const verdictGloss = !hasExitGate ? "count-only" : gatePassed ? "gate passed" : firstErrorMessage(evaluation) ?? "gate unmet";
+  const summary = `iteration ${iteration}/${maxIterations} — ${verdictGloss}${decision === "iterate" ? " → retrying" : ""}`;
+  deps.sink?.recordLoopIterationEvaluated?.({
+    stageId: stage.id,
+    iteration,
+    maxIterations,
+    gateResult,
+    evidence,
+    summary
+  });
+  log.info(TAG28, `#${card.short_id} converge loop "${stage.name}": ${summary} → ${decision}`);
+  if (decision === "exit") {
+    await deps.stateStore.resetLoopIterations(card.id).catch(() => {});
+    deps.sink?.recordLoopCompleted?.({
+      stageId: stage.id,
+      iterations: iteration,
+      maxIterations,
+      reason: hasExitGate ? "exit gate passed" : `count-only loop completed ${iteration} iteration(s)`
+    });
+    const exitEval = evaluation?.passed ? evaluation : {
+      passed: true,
+      findings: [
+        {
+          level: "info",
+          message: `Converge loop "${stage.name}" complete after ${iteration} iteration(s).`
+        }
+      ],
+      structured: evaluation?.structured ?? {}
+    };
+    return advanceStageOnGate(card, stage, stageIndex, def, exitEval, deps);
+  }
+  if (decision === "exhausted") {
+    await deps.stateStore.resetLoopIterations(card.id).catch(() => {});
+    await deps.stateStore.decrementAttempt(card.id).catch(() => {});
+    const reason = `Converge loop "${stage.name}" exhausted its ${maxIterations}-iteration budget with its exit gate still unmet — ${firstErrorMessage(evaluation) ?? "gate unmet"}. Holding for a human.`;
+    deps.sink?.recordLoopExhausted?.({
+      stageId: stage.id,
+      iterations: iteration,
+      maxIterations,
+      reason
+    });
+    try {
+      await deps.client.updateAgentProgress(card.id, {
+        agentIdentifier: "claude-code-stage",
+        agentName: "Harmony Agent",
+        status: "waiting",
+        currentTask: reason
+      });
+    } catch {}
+    await holdForHuman(deps.client, card, reason, deps.runId, deps.stateStore, {
+      keepAttempts: true
+    });
+    log.info(TAG28, `#${card.short_id} LoopExhausted: ${reason}`);
+    return { kind: "held_gate_unmet", reason };
+  }
+  await deps.stateStore.decrementAttempt(card.id).catch(() => {});
+  await writeIterationHandoff(card, stage, iteration, maxIterations, evaluation, deps);
+  const toColumn = await resolveStageColumnName(deps.client, card, stage) ?? deps.fallbackColumn;
+  try {
+    await deps.client.addComment(card.id, `Converge loop — ${summary}. Re-running "${stage.name}".`, { commentType: "progress" });
+  } catch {}
+  await runTransition(deps.client, card, {
+    move: { columnName: toColumn },
+    addLabels: [{ name: AGENT_LABEL }],
+    ...isAgentRunnableOwner(stage.owner) ? { assignAgent: deps.agentId } : {}
+  }, { store: deps.stateStore, runId: deps.runId });
+  log.info(TAG28, `#${card.short_id} converge loop "${stage.name}" — requeued to "${toColumn}" for iteration ${iteration + 1}/${maxIterations}`);
+  return { kind: "requeued_gate_unmet", toColumn };
+}
+async function writeIterationHandoff(card, stage, iteration, maxIterations, evaluation, deps) {
+  try {
+    const findings = evaluation?.findings.filter((f) => f.level !== "info") ?? [];
+    const produced = findings.length > 0 ? `Iteration ${iteration}/${maxIterations} of the "${stage.name}" converge loop did not pass its exit gate. Findings:
+${findings.map((f) => `- [${f.level}] ${f.message}`).join(`
+`)}` : `Iteration ${iteration}/${maxIterations} of the "${stage.name}" converge loop completed; the loop continues.`;
+    const body = buildHandoffCommentBody({
+      stageId: stage.id,
+      stageName: stage.name,
+      artifactType: stage.artifact_type,
+      produced,
+      decisions: [],
+      nextStageNeeds: "Address the findings above on the same branch and re-run; this stage repeats until its exit gate passes."
+    });
+    await deps.client.addComment(card.id, body, { commentType: "decision" });
+  } catch (err) {
+    log.warn(TAG28, `iteration-handoff write failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+  }
+}
 async function advanceStageOnGate(card, stage, stageIndex, def, evaluation, deps) {
   const summary = gateSummary(stage, evaluation);
   deps.sink?.recordStageGateEvaluated({
@@ -7293,7 +7536,9 @@ class Worker {
       const basePrompt = await buildPrompt(enriched, this.branchName, this.worktreePath, this.client, this.workspaceId, this.projectId);
       let prompt = basePrompt;
       if (stageCtx.kind === "run") {
-        const inherited = await this.loadInheritedHandoffSection(card.id, stageCtx.stage.id);
+        const loop = getStageLoop(stageCtx.stage);
+        const isLoop = isConvergeLoop(loop);
+        const inherited = await this.loadInheritedHandoffSection(card.id, stageCtx.stage.id, { includeOwnStage: isLoop });
         prompt = [buildStagePreamble(stageCtx.stage), inherited, basePrompt].filter(Boolean).join(`
 
 `);
@@ -7302,6 +7547,16 @@ class Worker {
           stageName: stageCtx.stage.name,
           owner: stageCtx.stage.owner
         });
+        if (isLoop && loop) {
+          const priorIterations = this.stateStore.getLoopIterations(card.id, stageCtx.stage.id);
+          this.cliRunner?.recordLoopIterationStarted({
+            stageId: stageCtx.stage.id,
+            stageName: stageCtx.stage.name,
+            iteration: priorIterations + 1,
+            maxIterations: Math.max(1, Math.floor(loop.max_iterations) || 1),
+            mode: loop.mode
+          });
+        }
       }
       await this.client.updateAgentProgress(card.id, {
         agentIdentifier: agentIdentifier(this.id),
@@ -7463,15 +7718,19 @@ class Worker {
         } catch {}
         await this.recordOutcome(card.id, "failure");
       } else if (this.runId && this.aborted) {
-        try {
-          await this.client.updateCard(card.id, { assignedAgentId: null });
-        } catch (err) {
-          log.warn(this.tag, `failed to release card after stop: ${err instanceof Error ? err.message : err}`);
-        }
-        try {
-          await runTransition(this.client, card, { removeLabels: ["agent"] });
-        } catch (tErr) {
-          log.warn(this.tag, `stop label cleanup failed on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
+        if (!this.completionStarted) {
+          try {
+            await this.client.updateCard(card.id, { assignedAgentId: null });
+          } catch (err) {
+            log.warn(this.tag, `failed to release card after stop: ${err instanceof Error ? err.message : err}`);
+          }
+          try {
+            await runTransition(this.client, card, { removeLabels: ["agent"] });
+          } catch (tErr) {
+            log.warn(this.tag, `stop label cleanup failed on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
+          }
+        } else {
+          log.info(this.tag, `cancel arrived after completion on #${card.short_id} — keeping assignment so review picks it up (#585)`);
         }
         try {
           await this.stateStore.endRun(this.runId, "paused", {
@@ -7613,15 +7872,13 @@ class Worker {
       } catch {}
     }
   }
-  async loadInheritedHandoffSection(cardId, currentStageId) {
+  async loadInheritedHandoffSection(cardId, currentStageId, opts = {}) {
     try {
-      const { comments } = await this.client.getComments(cardId, {
-        limit: 200
-      });
+      const { comments } = await this.client.request("GET", `/cards/${encodeURIComponent(cardId)}/comments?limit=200&order=desc&comment_type=decision`);
       if (!Array.isArray(comments) || comments.length === 0)
         return "";
       const handoff = extractLatestHandoff(comments, {
-        excludeStageId: currentStageId
+        excludeStageId: opts.includeOwnStage ? undefined : currentStageId
       });
       return handoff ? renderInheritedHandoffSection(handoff) : "";
     } catch (err) {
@@ -7649,7 +7906,9 @@ class Worker {
   }
   async collectStageGateEvidence(card, stage, worktreePath, subtasks) {
     try {
-      const gate = normalizeGateSpec(stage.gate);
+      const loop = getStageLoop(stage);
+      const gateSource = isConvergeLoop(loop) ? loop?.exit_gate ?? null : stage.gate;
+      const gate = normalizeGateSpec(gateSource);
       if (!gate) {
         return null;
       }
@@ -7692,11 +7951,8 @@ class Worker {
     }
   }
   async advanceFromGateEvaluation(card, stage, stageIndex, def, evaluation) {
-    if (!evaluation) {
-      return { kind: "no_advance" };
-    }
     try {
-      return await advanceStageOnGate(card, stage, stageIndex, def, evaluation, {
+      return await advanceStageRun(card, stage, stageIndex, def, evaluation, {
         client: this.client,
         stateStore: this.stateStore,
         agentId: this.agentId,
@@ -8672,6 +8928,71 @@ var init_recovery = __esm(() => {
   init_worktree();
 });
 
+// src/strand-recovery.ts
+var exports_strand_recovery = {};
+__export(exports_strand_recovery, {
+  reclaimPreReviewStrands: () => reclaimPreReviewStrands
+});
+async function reclaimPreReviewStrands(opts) {
+  const {
+    client,
+    agentId,
+    cards,
+    columns,
+    labelMap,
+    reviewColumns,
+    approvedLabel,
+    graceMs,
+    knownCardIds,
+    cwd,
+    provider
+  } = opts;
+  const now = opts.now ?? Date.now();
+  const maxPerSweep = opts.maxPerSweep ?? 5;
+  const reviewColIds = new Set(columns.filter((c) => reviewColumns.some((n) => n.toLowerCase() === c.name.toLowerCase())).map((c) => c.id));
+  if (reviewColIds.size === 0)
+    return [];
+  const reclaimed = [];
+  let checked = 0;
+  for (const card of cards) {
+    if (checked >= maxPerSweep)
+      break;
+    if (card.archived_at || !reviewColIds.has(card.column_id) || card.assigned_agent_id != null || card.assignee_id != null || knownCardIds.has(card.id)) {
+      continue;
+    }
+    const branch = extractBranchFromDescription(card.description);
+    if (!branch)
+      continue;
+    const labels = resolveCardLabels(card, labelMap);
+    if (hasLabel(labels, approvedLabel) || hasLabel(labels, NEED_REVIEW_LABEL)) {
+      continue;
+    }
+    const stalledAt = Date.parse(card.updated_at ?? "");
+    if (!Number.isFinite(stalledAt) || now - stalledAt < graceMs)
+      continue;
+    checked++;
+    const prUrl = resolvePrUrl(card.description ?? null, branch, cwd, provider);
+    if (prUrl)
+      continue;
+    log.warn(TAG33, `#${card.short_id} stranded in review (branch pushed, no PR, unowned) — re-asserting daemon assignment`);
+    try {
+      await client.updateCard(card.id, { assignedAgentId: agentId });
+      reclaimed.push(card.id);
+    } catch (err) {
+      log.error(TAG33, `review re-claim failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return reclaimed;
+}
+var TAG33 = "strand-recovery";
+var init_strand_recovery = __esm(() => {
+  init_board_helpers();
+  init_git_pr();
+  init_log();
+  init_review_worktree();
+  init_types();
+});
+
 // src/reconcile.ts
 class Reconciler {
   client;
@@ -8686,6 +9007,7 @@ class Reconciler {
   agentConfig;
   timer = null;
   lastTickAt = null;
+  gitProvider = null;
   get lastTick() {
     return this.lastTickAt;
   }
@@ -8713,7 +9035,7 @@ class Reconciler {
       clearInterval(this.timer);
       this.timer = null;
     }
-    log.info(TAG33, "Heartbeat stopped");
+    log.info(TAG34, "Heartbeat stopped");
   }
   async recoverStaleRuns() {
     if (!this.stateStore || !this.agentConfig)
@@ -8730,7 +9052,7 @@ class Reconciler {
       if (!daemonDead && !(heartbeatStale && ourZombie))
         continue;
       const reason = daemonDead ? `foreign daemon ${run.daemonPid} is dead` : `our worker lost card ${run.cardId} with ${Math.round((now - run.lastHeartbeatAt) / 1000)}s stale heartbeat`;
-      log.warn(TAG33, `zombie run ${run.runId} (#${run.cardShortId}): ${reason} — recovering`);
+      log.warn(TAG34, `zombie run ${run.runId} (#${run.cardShortId}): ${reason} — recovering`);
       await recoverRun(run, this.stateStore, this.client, this.agentConfig, {
         runId: run.runId,
         cardId: run.cardId,
@@ -8757,13 +9079,37 @@ class Reconciler {
       const stalledAt = Date.parse(card.updated_at ?? "");
       if (!Number.isFinite(stalledAt) || now - stalledAt < graceMs)
         continue;
-      log.warn(TAG33, `#${card.short_id} stranded in "${inProgressCol.name}" (no live run) — requeueing to "${pickupCol.name}"`);
+      log.warn(TAG34, `#${card.short_id} stranded in "${inProgressCol.name}" (no live run) — requeueing to "${pickupCol.name}"`);
       try {
         await this.client.moveCard(card.id, pickupCol.id);
       } catch (err) {
-        log.error(TAG33, `stranded requeue failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+        log.error(TAG34, `stranded requeue failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+  async recoverStrandedReview(cards, columns, labelMap, knownCardIds) {
+    if (this.reviewColumns.length === 0)
+      return;
+    if (!this.gitProvider) {
+      try {
+        this.gitProvider = detectGitProvider();
+      } catch {
+        return;
       }
     }
+    await reclaimPreReviewStrands({
+      client: this.client,
+      agentId: this.agentId,
+      cards,
+      columns,
+      labelMap,
+      reviewColumns: this.reviewColumns,
+      approvedLabel: this.approvedLabel,
+      graceMs: this.agentConfig?.timing.staleHeartbeatMs ?? 120000,
+      knownCardIds,
+      cwd: process.cwd(),
+      provider: this.gitProvider
+    });
   }
   async releaseStalledApprovals(cards, columns, knownCardIds) {
     const planning = this.agentConfig?.planning;
@@ -8784,11 +9130,11 @@ class Reconciler {
       const parkedAt = Date.parse(card.updated_at ?? "");
       if (!Number.isFinite(parkedAt) || now - parkedAt < ttlMs)
         continue;
-      log.warn(TAG33, `#${card.short_id} parked for approval > ${planning.approvalTtlHours}h — auto-releasing to "${pickupCol.name}"`);
+      log.warn(TAG34, `#${card.short_id} parked for approval > ${planning.approvalTtlHours}h — auto-releasing to "${pickupCol.name}"`);
       try {
         await this.client.moveCard(card.id, pickupCol.id);
       } catch (err) {
-        log.error(TAG33, `auto-release failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+        log.error(TAG34, `auto-release failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
       }
     }
   }
@@ -8831,21 +9177,21 @@ class Reconciler {
           const subtasks = card.subtasks ?? [];
           const mode = route.mode;
           if (route.stage) {
-            log.info(TAG33, `Stage card #${card.short_id} (stage "${card.current_stage}") in "${column.name}" — routing to the stage executor (implement) regardless of column`);
+            log.info(TAG34, `Stage card #${card.short_id} (stage "${card.current_stage}") in "${column.name}" — routing to the stage executor (implement) regardless of column`);
           }
           if (mode === "review" && this.approvedLabel && hasLabel(cardLabels, this.approvedLabel)) {
-            log.debug(TAG33, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
+            log.debug(TAG34, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
             continue;
           }
           if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
-            log.debug(TAG33, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
+            log.debug(TAG34, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
             continue;
           }
           if (mode === "review" && !extractBranchFromDescription(card.description)) {
-            log.debug(TAG33, `Skipping #${card.short_id} — no branch reference (not qualified for auto-review)`);
+            log.debug(TAG34, `Skipping #${card.short_id} — no branch reference (not qualified for auto-review)`);
             continue;
           }
-          log.info(TAG33, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
+          log.info(TAG34, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
           await this.pool.enqueue(card, column, cardLabels, subtasks, mode);
         }
       }
@@ -8853,25 +9199,28 @@ class Reconciler {
         await this.recoverStaleRuns();
       }
       await this.recoverStrandedInProgress(cards, columns, knownCardIds);
+      await this.recoverStrandedReview(cards, columns, labelMap, knownCardIds);
       for (const knownId of knownCardIds) {
         if (!allAgentCardIds.has(knownId)) {
-          log.info(TAG33, `Missed unassign: ${knownId} — removing`);
+          log.info(TAG34, `Missed unassign: ${knownId} — removing`);
           await this.pool.removeCard(knownId);
         }
       }
       await this.releaseStalledApprovals(cards, columns, knownCardIds);
-      log.debug(TAG33, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
+      log.debug(TAG34, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
     } catch (err) {
-      log.error(TAG33, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG34, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
     }
   }
 }
-var TAG33 = "reconcile";
+var TAG34 = "reconcile";
 var init_reconcile = __esm(() => {
   init_board_helpers();
+  init_git_pr();
   init_log();
   init_recovery();
   init_review_worktree();
+  init_strand_recovery();
   init_types();
 });
 
@@ -8904,7 +9253,7 @@ function prettyBanner(config, version) {
       checks.push({ kind: "ok", message });
     },
     warn(message) {
-      log.warn(TAG34, message);
+      log.warn(TAG35, message);
       checks.push({ kind: "warn", message: message.split(`
 `, 1)[0] });
     },
@@ -8929,25 +9278,25 @@ function prettyBanner(config, version) {
   };
 }
 function jsonBanner(config, version) {
-  log.info(TAG34, `Harmony Agent Daemon v${version} starting...`);
-  log.info(TAG34, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Model: ${config.agent.claude.model} | Runner: ${config.agent.runner} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
+  log.info(TAG35, `Harmony Agent Daemon v${version} starting...`);
+  log.info(TAG35, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Model: ${config.agent.claude.model} | Runner: ${config.agent.runner} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
   if (config.agent.review.enabled) {
-    log.info(TAG34, `Review: enabled | Columns: ${config.agent.review.pickupColumns.join(", ")} | → ${config.agent.review.moveToColumn} / ${config.agent.review.failColumn}`);
+    log.info(TAG35, `Review: enabled | Columns: ${config.agent.review.pickupColumns.join(", ")} | → ${config.agent.review.moveToColumn} / ${config.agent.review.failColumn}`);
   }
   let failed = false;
   return {
     setProjectName(_name) {},
     setGitProvider(provider) {
-      log.info(TAG34, `Git provider: ${provider}`);
+      log.info(TAG35, `Git provider: ${provider}`);
     },
     setHttpPort(port) {
-      log.info(TAG34, `HTTP server on port ${port}`);
+      log.info(TAG35, `HTTP server on port ${port}`);
     },
     check(message) {
-      log.info(TAG34, message);
+      log.info(TAG35, message);
     },
     warn(message) {
-      log.warn(TAG34, message);
+      log.warn(TAG35, message);
     },
     fail() {
       failed = true;
@@ -8955,7 +9304,7 @@ function jsonBanner(config, version) {
     async ready(message) {
       if (failed)
         return;
-      log.info(TAG34, message);
+      log.info(TAG35, message);
     }
   };
 }
@@ -9036,7 +9385,7 @@ function cyan(s) {
 function yellow(s) {
   return `${ANSI.yellow}${s}${ANSI.reset}`;
 }
-var TAG34 = "daemon", RULE_WIDTH = 70, ANSI;
+var TAG35 = "daemon", RULE_WIDTH = 70, ANSI;
 var init_startup_banner = __esm(() => {
   init_log();
   ANSI = {
@@ -9187,13 +9536,13 @@ class Watcher {
   }
   async start() {
     if (!isPretty()) {
-      log.info(TAG35, "Connecting to Supabase realtime (broadcast)...");
+      log.info(TAG36, "Connecting to Supabase realtime (broadcast)...");
     }
     this.supabase = createClient(this.credentials.supabaseUrl, this.credentials.supabaseAnonKey);
     const presenceChannel = this.supabase.channel(`board-presence-${this.projectId}`);
     this.subscribeBroadcast();
     presenceChannel.on("presence", { event: "sync" }, () => {
-      log.debug(TAG35, "Presence sync");
+      log.debug(TAG36, "Presence sync");
     }).subscribe(async (status) => {
       if (status === "SUBSCRIBED") {
         await presenceChannel.track({
@@ -9206,7 +9555,7 @@ class Watcher {
           agentName: this.identity.agentName
         });
         if (!isPretty() || !this.suppressStartupLogs) {
-          log.info(TAG35, "Presence tracked on board-presence channel");
+          log.info(TAG36, "Presence tracked on board-presence channel");
         }
         this.presenceTracked = true;
         this.maybeResolveReady();
@@ -9219,13 +9568,13 @@ class Watcher {
       return;
     const gen = ++this.broadcastGen;
     this.channel = this.supabase.channel(`board-${this.projectId}`).on("broadcast", { event: "card_update" }, (msg) => {
-      log.debug(TAG35, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
+      log.debug(TAG36, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
       this.onCardBroadcast({
         event: "card_update",
         payload: msg.payload ?? {}
       });
     }).on("broadcast", { event: "card_created" }, (msg) => {
-      log.debug(TAG35, `Broadcast: card_created ${JSON.stringify(msg.payload)}`);
+      log.debug(TAG36, `Broadcast: card_created ${JSON.stringify(msg.payload)}`);
       this.onCardBroadcast({
         event: "card_created",
         payload: msg.payload ?? {}
@@ -9235,7 +9584,7 @@ class Watcher {
       const cardId = payload.card_id;
       const command = payload.command;
       if (cardId && command) {
-        log.info(TAG35, `Broadcast: agent_command ${command} for ${cardId}`);
+        log.info(TAG36, `Broadcast: agent_command ${command} for ${cardId}`);
         this.onAgentCommand?.({ cardId, command });
       }
     }).subscribe((status) => {
@@ -9245,13 +9594,13 @@ class Watcher {
         this.connected = true;
         this.reconnectAttempts = 0;
         if (!isPretty() || !this.suppressStartupLogs) {
-          log.info(TAG35, "Broadcast subscription active");
+          log.info(TAG36, "Broadcast subscription active");
         }
         this.maybeResolveReady();
       } else if (status === "CHANNEL_ERROR" || status === "TIMED_OUT" || status === "CLOSED") {
         this.connected = false;
         if (!this.stopping) {
-          log.warn(TAG35, `Broadcast subscription ${status} — scheduling reconnect`);
+          log.warn(TAG36, `Broadcast subscription ${status} — scheduling reconnect`);
           this.scheduleReconnect();
         }
       }
@@ -9270,7 +9619,7 @@ class Watcher {
   async reconnectBroadcast() {
     if (this.stopping || !this.supabase)
       return;
-    log.warn(TAG35, `Reconnecting broadcast subscription (attempt ${this.reconnectAttempts})`);
+    log.warn(TAG36, `Reconnecting broadcast subscription (attempt ${this.reconnectAttempts})`);
     if (this.channel) {
       const old = this.channel;
       this.channel = null;
@@ -9300,10 +9649,10 @@ class Watcher {
       this.supabase = null;
     }
     this.connected = false;
-    log.info(TAG35, "Broadcast subscription stopped");
+    log.info(TAG36, "Broadcast subscription stopped");
   }
 }
-var TAG35 = "watcher";
+var TAG36 = "watcher";
 var init_watcher = __esm(() => {
   init_log();
 });
@@ -9390,10 +9739,10 @@ function runWorktreeGc(basePath, store, opts = {}) {
     });
   } catch {}
   if (result.removed.length > 0) {
-    log.info(TAG36, `GC removed ${result.removed.length} orphan worktree(s): ${result.removed.map((p) => p.split("/").pop()).join(", ")}`);
+    log.info(TAG37, `GC removed ${result.removed.length} orphan worktree(s): ${result.removed.map((p) => p.split("/").pop()).join(", ")}`);
   }
   if (result.errors.length > 0) {
-    log.warn(TAG36, `GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
+    log.warn(TAG37, `GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
   }
   return result;
 }
@@ -9423,7 +9772,7 @@ function pruneFailedRemoteBranches(opts) {
   } catch (err) {
     const detail = gitErrorDetail2(err);
     if (isTransientGitNetworkError(detail)) {
-      log.debug(TAG36, `Remote branch GC skipped — remote unreachable: ${detail}`);
+      log.debug(TAG37, `Remote branch GC skipped — remote unreachable: ${detail}`);
       return result;
     }
     result.errors.push({ ref: "fetch", error: detail });
@@ -9462,7 +9811,7 @@ function pruneFailedRemoteBranches(opts) {
       continue;
     }
     if (clock() > sweepDeadline) {
-      log.debug(TAG36, `Remote branch GC budget spent — removed ${result.removed.length}, remaining deferred to next tick`);
+      log.debug(TAG37, `Remote branch GC budget spent — removed ${result.removed.length}, remaining deferred to next tick`);
       break;
     }
     try {
@@ -9475,17 +9824,17 @@ function pruneFailedRemoteBranches(opts) {
     } catch (err) {
       const detail = gitErrorDetail2(err);
       if (isTransientGitNetworkError(detail)) {
-        log.debug(TAG36, `Remote branch GC interrupted — remote unreachable: ${detail}`);
+        log.debug(TAG37, `Remote branch GC interrupted — remote unreachable: ${detail}`);
         break;
       }
       result.errors.push({ ref, error: detail });
     }
   }
   if (result.removed.length > 0) {
-    log.info(TAG36, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
+    log.info(TAG37, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
   }
   if (result.errors.length > 0) {
-    log.warn(TAG36, `Remote branch GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.ref}: ${e.error}`).join("; ")}`);
+    log.warn(TAG37, `Remote branch GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.ref}: ${e.error}`).join("; ")}`);
   }
   return result;
 }
@@ -9516,13 +9865,13 @@ class WorktreeGc {
     try {
       runWorktreeGc(this.basePath, this.store);
     } catch (err) {
-      log.warn(TAG36, `GC tick failed: ${err instanceof Error ? err.message : err}`);
+      log.warn(TAG37, `GC tick failed: ${err instanceof Error ? err.message : err}`);
     }
     if (this.remoteOpts) {
       try {
         pruneFailedRemoteBranches(this.remoteOpts);
       } catch (err) {
-        log.warn(TAG36, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
+        log.warn(TAG37, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
       }
     }
   }
@@ -9536,7 +9885,7 @@ function getRepoRoot2() {
     return null;
   }
 }
-var TAG36 = "worktree-gc", GIT_NETWORK_TIMEOUT_MS = 30000, GIT_SSH_CONNECT_TIMEOUT_SECS = 10, GIT_PRUNE_SWEEP_BUDGET_MS = 60000, GIT_NETWORK_EXEC, TRANSIENT_GIT_NETWORK_ERROR;
+var TAG37 = "worktree-gc", GIT_NETWORK_TIMEOUT_MS = 30000, GIT_SSH_CONNECT_TIMEOUT_SECS = 10, GIT_PRUNE_SWEEP_BUDGET_MS = 60000, GIT_NETWORK_EXEC, TRANSIENT_GIT_NETWORK_ERROR;
 var init_worktree_gc = __esm(() => {
   init_log();
   init_worktree();
@@ -9640,7 +9989,7 @@ async function main() {
   } catch (err) {
     if (err instanceof ConfigValidationError) {
       banner.fail();
-      log.error(TAG37, err.message);
+      log.error(TAG38, err.message);
       process.exit(1);
     }
     throw err;
@@ -9750,7 +10099,7 @@ async function main() {
     if (shuttingDown)
       return;
     shuttingDown = true;
-    log.info(TAG37, `Received ${signal}, shutting down gracefully...`);
+    log.info(TAG38, `Received ${signal}, shutting down gracefully...`);
     reconciler.stop();
     mergeMonitor?.stop();
     worktreeGc.stop();
@@ -9760,18 +10109,18 @@ async function main() {
     }
     await watcher.stop();
     await pool.shutdown();
-    log.info(TAG37, "Daemon stopped.");
+    log.info(TAG38, "Daemon stopped.");
     process.exit(exitCode);
   };
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("uncaughtException", (err) => {
-    log.error(TAG37, `Uncaught exception: ${err.message}`);
+    log.error(TAG38, `Uncaught exception: ${err.message}`);
     exitCode = 1;
     shutdown("uncaughtException");
   });
   process.on("unhandledRejection", (reason) => {
-    log.error(TAG37, `Unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
+    log.error(TAG38, `Unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
     exitCode = 1;
     shutdown("unhandledRejection");
   });
@@ -9824,29 +10173,29 @@ async function handleBroadcast(event, client, pool, config, agentId) {
   if (assignedAgentId === undefined)
     return;
   if (assignedAgentId === agentId) {
-    log.info(TAG37, `Broadcast: card ${cardId} assigned to agent`);
+    log.info(TAG38, `Broadcast: card ${cardId} assigned to agent`);
     try {
       await pool.resetAttemptsForReassign(cardId);
       await tryEnqueueCard(cardId, client, pool, config, agentId);
     } catch (err) {
-      log.error(TAG37, `Failed to process assignment: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG38, `Failed to process assignment: ${err instanceof Error ? err.message : err}`);
     }
   } else if (pool.isCardKnown(cardId)) {
-    log.info(TAG37, `Broadcast: card ${cardId} unassigned from agent`);
+    log.info(TAG38, `Broadcast: card ${cardId} unassigned from agent`);
     await pool.removeCard(cardId);
   }
 }
 async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const { card } = await client.getCard(cardId);
   if (card.assigned_agent_id !== agentId) {
-    log.debug(TAG37, `Card ${cardId} no longer assigned to agent — skipping`);
+    log.debug(TAG38, `Card ${cardId} no longer assigned to agent — skipping`);
     return;
   }
   const board = await client.getBoard(config.projectId, { summary: true });
   const columns = board.columns;
   const column = columns.find((c) => c.id === card.column_id);
   if (!column) {
-    log.warn(TAG37, `Column not found for card ${cardId}`);
+    log.warn(TAG38, `Column not found for card ${cardId}`);
     return;
   }
   const route = classifyPickup(card, column.name, {
@@ -9855,27 +10204,27 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
     playbooks: config.agent.playbooks
   });
   if (!route) {
-    log.info(TAG37, `Card #${card.short_id} is in "${column.name}", not a pickup/review/stage column — skipping`);
+    log.info(TAG38, `Card #${card.short_id} is in "${column.name}", not a pickup/review/stage column — skipping`);
     return;
   }
   if (route.stage) {
-    log.info(TAG37, `Card #${card.short_id} is a playbook stage card (stage "${card.current_stage}") in "${column.name}" — routing to the stage executor (implement pool) regardless of column`);
+    log.info(TAG38, `Card #${card.short_id} is a playbook stage card (stage "${card.current_stage}") in "${column.name}" — routing to the stage executor (implement pool) regardless of column`);
   }
   const mode = route.mode;
   const labelMap = buildLabelMap(board.labels ?? []);
   const cardLabels = resolveCardLabels(card, labelMap);
   const subtasks = card.subtasks ?? [];
   if (mode === "review" && config.agent.review.approvedLabel && hasLabel(cardLabels, config.agent.review.approvedLabel)) {
-    log.debug(TAG37, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
+    log.debug(TAG38, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
     return;
   }
   if (mode === "review" && !extractBranchFromDescription(card.description)) {
-    log.info(TAG37, `Card #${card.short_id} has no branch reference — skipping auto-review`);
+    log.info(TAG38, `Card #${card.short_id} has no branch reference — skipping auto-review`);
     return;
   }
   await pool.enqueue(card, column, cardLabels, subtasks, mode);
 }
-var TAG37 = "daemon", PKG_VERSION;
+var TAG38 = "daemon", PKG_VERSION;
 var init_src = __esm(() => {
   init_board_helpers();
   init_config();
@@ -9909,6 +10258,7 @@ Usage:
   harmony-agent health             Exit 0 if daemon is healthy, 1 otherwise
   harmony-agent doctor             Run preflight checks (don't start)
   harmony-agent gc                 One-shot worktree garbage collection
+  harmony-agent recover            One-shot recovery of stranded Review cards
   harmony-agent help               Show this help
 
 Flags:
@@ -10047,6 +10397,53 @@ async function gcCommand() {
   }
   return 0;
 }
+async function recoverCommand() {
+  const { loadDaemonConfig: loadDaemonConfig2, createApiClient: createApiClient2 } = await Promise.resolve().then(() => (init_config(), exports_config));
+  const { MergeMonitor: MergeMonitor2 } = await Promise.resolve().then(() => (init_merge_monitor(), exports_merge_monitor));
+  const { reclaimPreReviewStrands: reclaimPreReviewStrands2 } = await Promise.resolve().then(() => (init_strand_recovery(), exports_strand_recovery));
+  const { detectGitProvider: detectGitProvider2 } = await Promise.resolve().then(() => (init_git_pr(), exports_git_pr));
+  const { buildLabelMap: buildLabelMap2 } = await Promise.resolve().then(() => (init_board_helpers(), exports_board_helpers));
+  const config = loadDaemonConfig2();
+  const client = createApiClient2(config);
+  const { agent: registeredAgent } = await client.registerWorkspaceAgent(config.workspaceId, {
+    identifier: config.agentIdentifier,
+    name: config.agentName,
+    color: config.agentColor
+  });
+  const agentId = registeredAgent.id;
+  const monitor = new MergeMonitor2(client, config.projectId, config.agent);
+  await monitor.runOnce();
+  const board = await client.getBoard(config.projectId);
+  const cards = board.cards ?? [];
+  const columns = board.columns ?? [];
+  const labelMap = buildLabelMap2(board.labels ?? []);
+  let provider;
+  try {
+    provider = detectGitProvider2();
+  } catch {
+    provider = "unknown";
+  }
+  const reclaimed = await reclaimPreReviewStrands2({
+    client,
+    agentId,
+    cards,
+    columns,
+    labelMap,
+    reviewColumns: config.agent.review.pickupColumns,
+    approvedLabel: config.agent.review.approvedLabel,
+    graceMs: config.agent.timing.staleHeartbeatMs,
+    knownCardIds: new Set,
+    cwd: process.cwd(),
+    provider
+  });
+  process.stdout.write(`recover: merge-strand pass complete; re-asserted ${reclaimed.length} pre-review strand(s)${reclaimed.length ? `: ${reclaimed.join(", ")}` : ""}
+`);
+  if (reclaimed.length) {
+    process.stdout.write(`  start/keep the daemon running so review picks these up
+`);
+  }
+  return 0;
+}
 async function dispatch(argv) {
   const args = argv.filter((a) => a !== "--pretty" && a !== "--json");
   const cmd = args[0];
@@ -10064,6 +10461,8 @@ async function dispatch(argv) {
       return doctorCommand();
     case "gc":
       return gcCommand();
+    case "recover":
+      return recoverCommand();
     case "help":
     case "--help":
     case "-h":