@gethmy/agent 1.49.5 → 1.49.6

package/README.md

@@ -121,7 +121,7 @@ harmony-agent help               # Show usage
 ## What the daemon does
 
 1. **Watches** the board in real time via Supabase Realtime.
-2. **Picks up** cards assigned to your agent user from configured columns.
+2. **Picks up** cards assigned to the daemon's virtual agent from configured columns. Moving a card to a pickup column is not enough; with `sweep.enabled` the daemon also claims unassigned cards from those columns itself.
 3. **Implements** changes in an isolated git worktree using a full-tool Claude run.
 4. **Verifies** the build + lint pass. Failures trigger an auto-fix attempt. Persistent failures move the card back to the `verification.failColumn` (default: `To Do`).
 5. **Pushes** the branch and moves the card to `Review`.

package/dist/cli.js

@@ -735,6 +735,18 @@ function formatDailyCap(cents) {
 function formatTurnCap(turns) {
   return turns < 0 ? "no cap" : `${turns} turns`;
 }
+function describeGuardDenial(reason, detail) {
+  switch (reason) {
+    case "max_attempts":
+      return `Stopped — ${detail} (\`budget.maxAttemptsPerCard\`). Reassign the card to grant a fresh attempt, or raise the limit in the daemon config.`;
+    case "card_turns":
+      return `Stopped — ${detail} (\`budget.maxTurnsPerCard\`). Reassign the card to clear the count, or raise the limit in the daemon config (-1 removes it).`;
+    case "card_runs":
+      return `Stopped — ${detail} (\`budget.maxRunsPerCard\`). Reassign the card to clear the count, or raise the limit in the daemon config (-1 removes it).`;
+    case "daily_budget":
+      return `Daily budget reached — waiting for the UTC reset (${detail}, \`budget.dailyBudgetCents\`). Raise the limit in the daemon config to continue today (-1 removes it).`;
+  }
+}
 
 class BudgetGuard {
   config;
@@ -2313,6 +2325,7 @@ var init_plan_phase = __esm(() => {
     mode: "advisory",
     model: "sonnet",
     maxTurns: 40,
+    timeoutMs: 10 * 60000,
     postComment: true,
     awaitingApprovalColumn: "To Do",
     minComplexityScore: 3,
@@ -2373,6 +2386,9 @@ var init_types = __esm(() => {
       },
       scoreBands: DEFAULT_SCORE_BANDS,
       sizingModel: "",
+      sizingMaxTurns: 25,
+      sizingMaxBudgetUsd: 0.75,
+      sizingTimeoutMs: 240000,
       researchRule: "shadow",
       reviewModel: "sonnet",
       deepReviewModel: "sonnet",
@@ -2475,6 +2491,10 @@ var init_types = __esm(() => {
       runRecordDays: 14,
       runLogDays: 30
     },
+    steering: {
+      maxTurns: 15,
+      maxIterations: 10
+    },
     planning: DEFAULT_PLANNING_CONFIG,
     contractFirst: DEFAULT_CONTRACT_CONFIG,
     boardReview: DEFAULT_BOARD_REVIEW_CONFIG,
@@ -2495,6 +2515,7 @@ __export(exports_config_validation, {
   validateVerificationConfig: () => validateVerificationConfig,
   validateSweepConfig: () => validateSweepConfig,
   validateSizingConfig: () => validateSizingConfig,
+  validateRunLimitsConfig: () => validateRunLimitsConfig,
   validateRetentionConfig: () => validateRetentionConfig,
   validateRankingConfig: () => validateRankingConfig,
   validateHttpConfig: () => validateHttpConfig,
@@ -2826,6 +2847,41 @@ function validateRetentionConfig(config) {
 ` + `  Set a positive number of days, or a negative value to keep this store forever.`, [issue]);
   }
 }
+function validateRunLimitsConfig(config) {
+  const wholeOrOff = [
+    ["planning.timeoutMs", config.planning.timeoutMs],
+    ["steering.maxTurns", config.steering.maxTurns],
+    ["steering.maxIterations", config.steering.maxIterations],
+    ["claude.sizingMaxTurns", config.claude.sizingMaxTurns],
+    ["claude.sizingTimeoutMs", config.claude.sizingTimeoutMs]
+  ];
+  const issues = [];
+  for (const [key, value] of wholeOrOff) {
+    if (value === -1)
+      continue;
+    if (!Number.isInteger(value) || value < 1) {
+      issues.push(`${key}: ${value === 0 ? '0 is ambiguous — it could mean "none allowed" or "no limit"' : `${JSON.stringify(value)} is not a positive whole number`}`);
+    }
+  }
+  const budget = config.claude.sizingMaxBudgetUsd;
+  if (budget !== -1 && !(Number.isFinite(budget) && budget > 0)) {
+    issues.push(`claude.sizingMaxBudgetUsd: ${budget === 0 ? '0 is ambiguous — it could mean "no spend allowed" or "no limit"' : `${JSON.stringify(budget)} is not a positive number`}`);
+  }
+  for (const [key, value] of [
+    ["claude.maxTurns", config.claude.maxTurns],
+    ["claude.reviewMaxTurns", config.claude.reviewMaxTurns]
+  ]) {
+    if (!Number.isInteger(value) || value < 1) {
+      issues.push(`${key}: ${JSON.stringify(value)} is not a positive whole number`);
+    }
+  }
+  if (issues.length > 0) {
+    throw new ConfigValidationError(`Invalid agent config — run limits:
+  - ${issues.join(`
+  - `)}
+` + `  Set a positive value, or -1 to remove the limit (not available for claude.maxTurns and claude.reviewMaxTurns).`, issues);
+  }
+}
 function validateRankingConfig(config) {
   const issues = [];
   const entries = Object.entries(config.ranking);
@@ -7184,9 +7240,11 @@ ${runLogTail}
       } else {
         await breakReviewLoopIfNeeded();
       }
+      const movedTo = handbackVerdict.proceed ? `I moved the card to "${config.review.moveToColumn}" instead of sending it back to "${config.review.failColumn}" again.` : "I left the card where it is instead of sending it back again.";
       const body = [
         "**Review — needs human review.**",
-        `Reached max review cycles (${maxCycles}). Please review manually.`,
+        `This card reached the limit of ${maxCycles} review cycles (\`review.maxReviewCycles\`). ${movedTo}`,
+        "Next: read the earlier review comments and fix or merge the branch by hand. To allow more automatic rounds, raise `review.maxReviewCycles` in the daemon config.",
         result.summary || ""
       ].filter(Boolean).join(`
 
@@ -9902,6 +9960,7 @@ var init_workspace_model_config = __esm(() => {
 // src/worker.ts
 import { execFileSync as execFileSync7 } from "node:child_process";
 import {
+  boundedTimerMs,
   chooseImplementModel,
   classifyRunError as classifyRunError2,
   createWorktree,
@@ -10792,7 +10851,10 @@ ${prompt}`;
       title: card.title,
       description: card.description,
       model,
-      scoreBands: claude.scoreBands
+      scoreBands: claude.scoreBands,
+      maxTurns: claude.sizingMaxTurns < 0 ? null : claude.sizingMaxTurns,
+      maxBudgetUsd: claude.sizingMaxBudgetUsd < 0 ? null : claude.sizingMaxBudgetUsd,
+      timeoutMs: claude.sizingTimeoutMs < 0 ? null : claude.sizingTimeoutMs
     });
     if (outcome.status === "sized") {
       log33.info(this.tag, `Sized #${card.short_id}: complexity ${outcome.sizing.complexity}/10 -> ${outcome.sizing.tier}`);
@@ -11031,6 +11093,10 @@ ${prompt}`;
       }
     }
   }
+  armPhaseTimer(onExpiry) {
+    const { timeoutMs } = this.config.planning;
+    return setTimeout(onExpiry, boundedTimerMs(timeoutMs < 0 ? this.config.maxTimeout : timeoutMs));
+  }
   async runPlanningPhase(enriched) {
     const planning = this.config.planning;
     const { card } = enriched;
@@ -11045,7 +11111,7 @@ ${prompt}`;
     }).catch(() => {});
     const planPrompt = buildPlanPrompt(enriched, this.worktreePath);
     let planTimedOut = false;
-    const planTimeout = setTimeout(() => {
+    const planTimeout = this.armPhaseTimer(() => {
       planTimedOut = true;
       log33.warn(this.tag, "Planning pass exceeded timeout — abandoning, implementing directly");
       if (this.sdkRunner) {
@@ -11056,7 +11122,7 @@ ${prompt}`;
           sigtermTimeoutMs: 5000
         }).catch(() => {});
       }
-    }, Math.min(this.config.maxTimeout, PLAN_PHASE_TIMEOUT));
+    });
     try {
       await this.spawnClaude(planPrompt, card, [], {
         model: planning.model,
@@ -11156,7 +11222,7 @@ ${prompt}`;
     }).catch(() => {});
     const contractPrompt = buildContractPrompt(enriched, this.worktreePath);
     let contractTimedOut = false;
-    const contractTimeout = setTimeout(() => {
+    const contractTimeout = this.armPhaseTimer(() => {
       contractTimedOut = true;
       log33.warn(this.tag, "Contract pass exceeded timeout — abandoning, implementing directly");
       if (this.sdkRunner) {
@@ -11167,7 +11233,7 @@ ${prompt}`;
           sigtermTimeoutMs: 5000
         }).catch(() => {});
       }
-    }, Math.min(this.config.maxTimeout, PLAN_PHASE_TIMEOUT));
+    });
     try {
       await this.spawnClaude(contractPrompt, card, [], {
         model: contractCfg.model,
@@ -11219,7 +11285,8 @@ ${prompt}`;
   async drainSteeringMessages(card, subtasks) {
     if (!this.cliSessionId || !this.sessionId || !this.cardId)
       return;
-    for (let i = 0;i < MAX_STEERING_ITERATIONS && !this.aborted; i++) {
+    const { maxIterations, maxTurns } = this.config.steering;
+    for (let i = 0;(maxIterations < 0 || i < maxIterations) && !this.aborted; i++) {
       let messages;
       try {
         const res = await this.client.getPendingUserMessages(this.cardId, this.sessionId, this.lastDrainedSeq);
@@ -11237,7 +11304,7 @@ ${prompt}`;
       try {
         await this.spawnClaude(buildSteeringPrompt(messages.map((m) => frameSteeringQuestion(m.text, m.questionCommentId))), card, subtasks, {
           model: this.selectImplementModel(card),
-          maxTurns: STEERING_MAX_TURNS,
+          maxTurns: maxTurns < 0 ? undefined : maxTurns,
           resumeSessionId: this.cliSessionId,
           noCommitNotice: true,
           ...this.activeRunSpawnOpts ?? {}
@@ -11543,7 +11610,7 @@ ${prompt}`;
     this.chargedTokens = emptyTokens();
   }
 }
-var TAG30 = "worker", CANCEL_SIGINT_TIMEOUT2 = 30000, CANCEL_SIGTERM_TIMEOUT2 = 1e4, STEERING_MAX_TURNS = 15, MAX_STEERING_ITERATIONS = 10, PLAN_ALLOWED_TOOLS = "Read,Grep,Glob,mcp__harmony__*", IMPLEMENT_ALLOWED_TOOLS = "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*", PLAN_PHASE_TIMEOUT;
+var TAG30 = "worker", CANCEL_SIGINT_TIMEOUT2 = 30000, CANCEL_SIGTERM_TIMEOUT2 = 1e4, PLAN_ALLOWED_TOOLS = "Read,Grep,Glob,mcp__harmony__*", IMPLEMENT_ALLOWED_TOOLS = "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*";
 var init_worker = __esm(() => {
   init_src();
   init_board_helpers();
@@ -11563,7 +11630,6 @@ var init_worker = __esm(() => {
   init_transitions();
   init_types();
   init_workspace_model_config();
-  PLAN_PHASE_TIMEOUT = 10 * 60000;
 });
 
 // src/workspace-model-cache.ts
@@ -11725,13 +11791,13 @@ class Pool {
       if (mode === "implement") {
         if (this.authPaused) {
           log35.debug(TAG31, `#${card.short_id} held — agent paused (auth error)`);
-          await this.emitWaiting(card.id, "Agent paused — Anthropic auth error, check API credentials");
+          await this.emitWaiting(card.id, "Agent paused — Anthropic auth error. Fix the API credentials, then restart the daemon.");
           return;
         }
         const cooldownMs = this.apiCooldownRemainingMs();
         if (cooldownMs > 0) {
           log35.debug(TAG31, `#${card.short_id} held — API cooldown ${Math.round(cooldownMs / 1000)}s remaining`);
-          await this.emitWaiting(card.id, `Paused — Anthropic API limit, retrying in ~${Math.round(cooldownMs / 1000)}s`);
+          await this.emitWaiting(card.id, `Paused — Anthropic API limit, retrying after ${new Date(this.apiCooldownUntil).toISOString().slice(11, 16)} UTC. Nothing to change: the daemon resumes by itself.`);
           return;
         }
         const decision = this.budget.check(card.id);
@@ -11740,6 +11806,7 @@ class Pool {
             await this.denyDailyBudget(card, decision.detail);
           } else {
             log35.debug(TAG31, `#${card.short_id} skipped (${decision.reason}): ${decision.detail}`);
+            await this.emitWaiting(card.id, describeGuardDenial(decision.reason, decision.detail));
           }
           return;
         }
@@ -11747,6 +11814,7 @@ class Pool {
         chainSuccessors = successors;
         if (blockers === null) {
           log35.warn(TAG31, `#${card.short_id} blocker check failed — deferring to next tick`);
+          await this.emitWaiting(card.id, "Waiting — could not read this card's links to check for blockers. The daemon retries on the next tick.");
           return;
         }
         if (blockers.length > 0) {
@@ -11780,7 +11848,7 @@ class Pool {
     }
   }
   async denyDailyBudget(card, detail) {
-    const reason = `Daily budget reached — waiting for reset (${detail})`;
+    const reason = describeGuardDenial("daily_budget", detail);
     const line = `#${card.short_id} skipped (daily_budget): ${detail}`;
     if (this.lastWaitingEmit.get(card.id) === reason)
       log35.debug(TAG31, line);
@@ -11788,6 +11856,11 @@ class Pool {
       log35.warn(TAG31, line);
     await this.emitWaiting(card.id, reason);
   }
+  async noteSkip(cardId, reason) {
+    if (this.isCardKnown(cardId))
+      return;
+    await this.emitWaiting(cardId, reason);
+  }
   lastWaitingEmit = new Map;
   async emitWaiting(cardId, currentTask) {
     if (this.lastWaitingEmit.get(cardId) === currentTask)
@@ -13902,6 +13975,7 @@ var init_startup_model = __esm(() => {
 // src/startup-banner.ts
 var exports_startup_banner = {};
 __export(exports_startup_banner, {
+  limitsLine: () => limitsLine,
   createStartupBanner: () => createStartupBanner,
   contextSourceLine: () => contextSourceLine
 });
@@ -13963,6 +14037,7 @@ function jsonBanner(config, version) {
   log44.info(TAG40, `Harmony Agent Daemon v${version} starting...`);
   log44.info(TAG40, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Runner: ${config.agent.runner} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
   log44.info(TAG40, `Config: ${contextSourceLine(config)}`);
+  log44.info(TAG40, `Limits: ${limitsLine(config)}`);
   if (config.agent.review.enabled) {
     log44.info(TAG40, `Review: enabled | Columns: ${config.agent.review.pickupColumns.join(", ")} | → ${config.agent.review.moveToColumn} / ${config.agent.review.failColumn}`);
   }
@@ -14042,6 +14117,7 @@ function configRows(config, projectName, gitProvider, httpPort, model) {
     value: `${modelDesc}  ·  ${poolDesc}  ·  ${flowDesc}`
   });
   rows.push({ label: "Runner", value: runnerDesc(config.agent.runner) });
+  rows.push({ label: "Limits", value: limitsLine(config) });
   const tail = [];
   if (gitProvider)
     tail.push(gitProvider);
@@ -14064,6 +14140,21 @@ function contextSourceLine(config) {
   const pinLabel = config.repoAgentPaths.size > 0 ? "repo pin, +auto-merge" : "repo pin";
   return `project+workspace ${path} (${pinLabel})  ·  rest ${globalPath}`;
 }
+function limitsLine(config) {
+  const { budget, review, worktree } = config.agent;
+  const cap = (value, unit) => value < 0 ? "unlimited" : `${value} ${unit}`;
+  const parts = [
+    `${budget.maxAttemptsPerCard} attempts/card (budget.maxAttemptsPerCard)`,
+    `${cap(budget.maxTurnsPerCard, "turns")}/card (budget.maxTurnsPerCard)`,
+    `${cap(budget.maxRunsPerCard, "runs")}/card (budget.maxRunsPerCard)`,
+    `${budget.dailyBudgetCents < 0 ? "unlimited" : `$${(budget.dailyBudgetCents / 100).toFixed(2)}`}/day (budget.dailyBudgetCents)`
+  ];
+  if (review.enabled) {
+    parts.push(`${review.maxReviewCycles} review cycles (review.maxReviewCycles)`);
+  }
+  parts.push(`failed branches ${worktree.failedAttemptRetentionDays > 0 ? `${worktree.failedAttemptRetentionDays}d` : "kept"} (worktree.failedAttemptRetentionDays)`);
+  return parts.join("  ·  ");
+}
 function titleRule(title) {
   const prefix = "─── ";
   const surround = ` `;
@@ -15020,6 +15111,7 @@ var exports_worktree_gc = {};
 __export(exports_worktree_gc, {
   runWorktreeGc: () => runWorktreeGc,
   pruneFailedRemoteBranches: () => pruneFailedRemoteBranches,
+  noteExpiringBranches: () => noteExpiringBranches,
   isTransientGitNetworkError: () => isTransientGitNetworkError,
   WorktreeGc: () => WorktreeGc
 });
@@ -15151,6 +15243,7 @@ function pruneFailedRemoteBranches(opts) {
     scanned: 0,
     removed: [],
     skipped: [],
+    expiring: [],
     errors: []
   };
   if (!opts.prefix)
@@ -15209,6 +15302,9 @@ function pruneFailedRemoteBranches(opts) {
     result.scanned++;
     if (!Number.isFinite(ts) || ts >= cutoffSecs) {
       result.skipped.push(ref);
+      if (Number.isFinite(ts) && ts < cutoffSecs + EXPIRY_NOTICE_SECS) {
+        result.expiring.push(ref);
+      }
       continue;
     }
     if (clock() > sweepDeadline) {
@@ -15272,7 +15368,10 @@ class WorktreeGc {
     }
     if (this.remoteOpts) {
       try {
-        pruneFailedRemoteBranches(this.remoteOpts);
+        const pruned = pruneFailedRemoteBranches(this.remoteOpts);
+        if (pruned.expiring.length > 0) {
+          this.remoteOpts.onExpiring?.(pruned.expiring);
+        }
       } catch (err) {
         log48.warn(TAG44, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
       }
@@ -15284,6 +15383,28 @@ class WorktreeGc {
     }
   }
 }
+async function noteExpiringBranches(store, client, refs, retentionDays, notified) {
+  for (const ref of refs) {
+    if (notified.has(ref))
+      continue;
+    const owner = store.listCards().find((c) => c.daemonBranch === ref || c.failureHistory?.some((f) => f.recoveryBranch === ref));
+    if (!owner)
+      continue;
+    notified.add(ref);
+    try {
+      await client.addComment(owner.cardId, [
+        "**Failed-attempt branch expires within a day.**",
+        `\`${ref}\` holds this card's unfinished commits. The daemon deletes failed-attempt branches after ${retentionDays} days (\`worktree.failedAttemptRetentionDays\`), and the next sweep removes this one.`,
+        "To keep the work, check it out or open a PR from it now. To keep such branches longer, raise `worktree.failedAttemptRetentionDays` in the daemon config (0 turns the sweep off)."
+      ].join(`
+
+`), { commentType: "summary" });
+    } catch (err) {
+      notified.delete(ref);
+      log48.warn(TAG44, `Failed to post the expiring-branch note for ${ref}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
 function getRepoRoot2() {
   try {
     return execFileSync8("git", [...GIT_NO_HOOKS9, "rev-parse", "--show-toplevel"], {
@@ -15293,7 +15414,7 @@ function getRepoRoot2() {
     return null;
   }
 }
-var TAG44 = "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 TAG44 = "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, EXPIRY_NOTICE_SECS;
 var init_worktree_gc = __esm(() => {
   init_run_gc();
   GIT_NETWORK_EXEC = {
@@ -15318,6 +15439,7 @@ var init_worktree_gc = __esm(() => {
     "enotfound",
     "enetunreach"
   ].join("|"), "i");
+  EXPIRY_NOTICE_SECS = 24 * 60 * 60;
 });
 
 // src/index.ts
@@ -15421,6 +15543,7 @@ async function main() {
     validateSweepConfig(config.agent);
     validateRankingConfig(config.agent);
     validateRetentionConfig(config.agent);
+    validateRunLimitsConfig(config.agent);
     validateVerificationConfig(config.agent);
     validateSizingConfig(config.agent);
     validateHttpConfig(config.agent);
@@ -15518,9 +15641,15 @@ async function main() {
       await settlePlanCriteria(client, "merge-monitor", completedCard);
     };
   }
+  const expiringNotified = new Set;
   const worktreeGc = new WorktreeGc(config.agent.worktree.basePath, stateStore, config.agent.timing.worktreeGcIntervalMs, config.agent.worktree.failedAttemptRetentionDays > 0 ? {
     prefix: config.agent.worktree.failedBranchPrefix,
-    retentionDays: config.agent.worktree.failedAttemptRetentionDays
+    retentionDays: config.agent.worktree.failedAttemptRetentionDays,
+    onExpiring: (refs) => {
+      noteExpiringBranches(stateStore, client, refs, config.agent.worktree.failedAttemptRetentionDays, expiringNotified).catch((err) => {
+        log49.warn(TAG45, `Expiring-branch notes failed: ${err}`);
+      });
+    }
   } : undefined, config.agent.retention);
   let boardReviewer = null;
   if (config.agent.boardReview.enabled) {
@@ -15715,6 +15844,7 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const column = columns.find((c) => c.id === card.column_id);
   if (!column) {
     log49.warn(TAG45, `Column not found for card ${cardId}`);
+    await pool.noteSkip(cardId, "Not picked up — the card's column was not found on the board. Check the card is in a column of this project.");
     return;
   }
   const route = classifyPickup(column.name, {
@@ -15723,6 +15853,8 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   });
   if (!route) {
     log49.info(TAG45, `Card #${card.short_id} is in "${column.name}", not a pickup/review column — skipping`);
+    const reviewColumns = config.agent.review.enabled ? config.agent.review.pickupColumns : [];
+    await pool.noteSkip(card.id, `Not picked up — "${column.name}" is not a pickup column. Pickup: ${config.agent.pickupColumns.join(", ")} (\`pickupColumns\`)${reviewColumns.length > 0 ? `; review: ${reviewColumns.join(", ")} (\`review.pickupColumns\`)` : ""}. Move the card into one of them.`);
     return;
   }
   const mode = route.mode;
@@ -15731,14 +15863,17 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const subtasks = card.subtasks ?? [];
   if (mode === "review" && config.agent.review.approvedLabel && hasLabel(cardLabels, config.agent.review.approvedLabel)) {
     log49.debug(TAG45, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
+    await pool.noteSkip(card.id, `Not reviewed — the card already has the "${config.agent.review.approvedLabel}" label (\`review.approvedLabel\`). Remove the label to queue a review.`);
     return;
   }
   if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
     log49.debug(TAG45, `Card #${card.short_id} has "${NEED_REVIEW_LABEL}" label (needs human) — skipping review`);
+    await pool.noteSkip(card.id, `Not reviewed — the card has the "${NEED_REVIEW_LABEL}" label, so a person owns the next step. Remove the label to queue another review.`);
     return;
   }
   if (mode === "review" && !qualifiesForAutoReview(card.description)) {
     log49.info(TAG45, `Card #${card.short_id} has no branch or PR reference — skipping auto-review`);
+    await pool.noteSkip(card.id, "Not reviewed — the card description has no `Branch:` line and no PR link, so there is nothing to review. Add one to queue a review.");
     return;
   }
   await pool.enqueue(card, column, cardLabels, subtasks, mode);
@@ -16737,6 +16872,7 @@ async function doctorCommand() {
     validateHttpConfig: validateHttpConfig2,
     validateRankingConfig: validateRankingConfig2,
     validateRetentionConfig: validateRetentionConfig2,
+    validateRunLimitsConfig: validateRunLimitsConfig2,
     validateSizingConfig: validateSizingConfig2,
     validateSweepConfig: validateSweepConfig2,
     validateVerificationConfig: validateVerificationConfig2
@@ -16754,6 +16890,7 @@ async function doctorCommand() {
     validateSweepConfig2(config.agent);
     validateRankingConfig2(config.agent);
     validateRetentionConfig2(config.agent);
+    validateRunLimitsConfig2(config.agent);
     validateVerificationConfig2(config.agent);
     validateSizingConfig2(config.agent);
     validateHttpConfig2(config.agent);

package/dist/index.js

@@ -734,6 +734,18 @@ function formatDailyCap(cents) {
 function formatTurnCap(turns) {
   return turns < 0 ? "no cap" : `${turns} turns`;
 }
+function describeGuardDenial(reason, detail) {
+  switch (reason) {
+    case "max_attempts":
+      return `Stopped — ${detail} (\`budget.maxAttemptsPerCard\`). Reassign the card to grant a fresh attempt, or raise the limit in the daemon config.`;
+    case "card_turns":
+      return `Stopped — ${detail} (\`budget.maxTurnsPerCard\`). Reassign the card to clear the count, or raise the limit in the daemon config (-1 removes it).`;
+    case "card_runs":
+      return `Stopped — ${detail} (\`budget.maxRunsPerCard\`). Reassign the card to clear the count, or raise the limit in the daemon config (-1 removes it).`;
+    case "daily_budget":
+      return `Daily budget reached — waiting for the UTC reset (${detail}, \`budget.dailyBudgetCents\`). Raise the limit in the daemon config to continue today (-1 removes it).`;
+  }
+}
 
 class BudgetGuard {
   config;
@@ -2312,6 +2324,7 @@ var init_plan_phase = __esm(() => {
     mode: "advisory",
     model: "sonnet",
     maxTurns: 40,
+    timeoutMs: 10 * 60000,
     postComment: true,
     awaitingApprovalColumn: "To Do",
     minComplexityScore: 3,
@@ -2372,6 +2385,9 @@ var init_types = __esm(() => {
       },
       scoreBands: DEFAULT_SCORE_BANDS,
       sizingModel: "",
+      sizingMaxTurns: 25,
+      sizingMaxBudgetUsd: 0.75,
+      sizingTimeoutMs: 240000,
       researchRule: "shadow",
       reviewModel: "sonnet",
       deepReviewModel: "sonnet",
@@ -2474,6 +2490,10 @@ var init_types = __esm(() => {
       runRecordDays: 14,
       runLogDays: 30
     },
+    steering: {
+      maxTurns: 15,
+      maxIterations: 10
+    },
     planning: DEFAULT_PLANNING_CONFIG,
     contractFirst: DEFAULT_CONTRACT_CONFIG,
     boardReview: DEFAULT_BOARD_REVIEW_CONFIG,
@@ -2494,6 +2514,7 @@ __export(exports_config_validation, {
   validateVerificationConfig: () => validateVerificationConfig,
   validateSweepConfig: () => validateSweepConfig,
   validateSizingConfig: () => validateSizingConfig,
+  validateRunLimitsConfig: () => validateRunLimitsConfig,
   validateRetentionConfig: () => validateRetentionConfig,
   validateRankingConfig: () => validateRankingConfig,
   validateHttpConfig: () => validateHttpConfig,
@@ -2825,6 +2846,41 @@ function validateRetentionConfig(config) {
 ` + `  Set a positive number of days, or a negative value to keep this store forever.`, [issue]);
   }
 }
+function validateRunLimitsConfig(config) {
+  const wholeOrOff = [
+    ["planning.timeoutMs", config.planning.timeoutMs],
+    ["steering.maxTurns", config.steering.maxTurns],
+    ["steering.maxIterations", config.steering.maxIterations],
+    ["claude.sizingMaxTurns", config.claude.sizingMaxTurns],
+    ["claude.sizingTimeoutMs", config.claude.sizingTimeoutMs]
+  ];
+  const issues = [];
+  for (const [key, value] of wholeOrOff) {
+    if (value === -1)
+      continue;
+    if (!Number.isInteger(value) || value < 1) {
+      issues.push(`${key}: ${value === 0 ? '0 is ambiguous — it could mean "none allowed" or "no limit"' : `${JSON.stringify(value)} is not a positive whole number`}`);
+    }
+  }
+  const budget = config.claude.sizingMaxBudgetUsd;
+  if (budget !== -1 && !(Number.isFinite(budget) && budget > 0)) {
+    issues.push(`claude.sizingMaxBudgetUsd: ${budget === 0 ? '0 is ambiguous — it could mean "no spend allowed" or "no limit"' : `${JSON.stringify(budget)} is not a positive number`}`);
+  }
+  for (const [key, value] of [
+    ["claude.maxTurns", config.claude.maxTurns],
+    ["claude.reviewMaxTurns", config.claude.reviewMaxTurns]
+  ]) {
+    if (!Number.isInteger(value) || value < 1) {
+      issues.push(`${key}: ${JSON.stringify(value)} is not a positive whole number`);
+    }
+  }
+  if (issues.length > 0) {
+    throw new ConfigValidationError(`Invalid agent config — run limits:
+  - ${issues.join(`
+  - `)}
+` + `  Set a positive value, or -1 to remove the limit (not available for claude.maxTurns and claude.reviewMaxTurns).`, issues);
+  }
+}
 function validateRankingConfig(config) {
   const issues = [];
   const entries = Object.entries(config.ranking);
@@ -7183,9 +7239,11 @@ ${runLogTail}
       } else {
         await breakReviewLoopIfNeeded();
       }
+      const movedTo = handbackVerdict.proceed ? `I moved the card to "${config.review.moveToColumn}" instead of sending it back to "${config.review.failColumn}" again.` : "I left the card where it is instead of sending it back again.";
       const body = [
         "**Review — needs human review.**",
-        `Reached max review cycles (${maxCycles}). Please review manually.`,
+        `This card reached the limit of ${maxCycles} review cycles (\`review.maxReviewCycles\`). ${movedTo}`,
+        "Next: read the earlier review comments and fix or merge the branch by hand. To allow more automatic rounds, raise `review.maxReviewCycles` in the daemon config.",
         result.summary || ""
       ].filter(Boolean).join(`
 
@@ -9901,6 +9959,7 @@ var init_workspace_model_config = __esm(() => {
 // src/worker.ts
 import { execFileSync as execFileSync7 } from "node:child_process";
 import {
+  boundedTimerMs,
   chooseImplementModel,
   classifyRunError as classifyRunError2,
   createWorktree,
@@ -10791,7 +10850,10 @@ ${prompt}`;
       title: card.title,
       description: card.description,
       model,
-      scoreBands: claude.scoreBands
+      scoreBands: claude.scoreBands,
+      maxTurns: claude.sizingMaxTurns < 0 ? null : claude.sizingMaxTurns,
+      maxBudgetUsd: claude.sizingMaxBudgetUsd < 0 ? null : claude.sizingMaxBudgetUsd,
+      timeoutMs: claude.sizingTimeoutMs < 0 ? null : claude.sizingTimeoutMs
     });
     if (outcome.status === "sized") {
       log33.info(this.tag, `Sized #${card.short_id}: complexity ${outcome.sizing.complexity}/10 -> ${outcome.sizing.tier}`);
@@ -11030,6 +11092,10 @@ ${prompt}`;
       }
     }
   }
+  armPhaseTimer(onExpiry) {
+    const { timeoutMs } = this.config.planning;
+    return setTimeout(onExpiry, boundedTimerMs(timeoutMs < 0 ? this.config.maxTimeout : timeoutMs));
+  }
   async runPlanningPhase(enriched) {
     const planning = this.config.planning;
     const { card } = enriched;
@@ -11044,7 +11110,7 @@ ${prompt}`;
     }).catch(() => {});
     const planPrompt = buildPlanPrompt(enriched, this.worktreePath);
     let planTimedOut = false;
-    const planTimeout = setTimeout(() => {
+    const planTimeout = this.armPhaseTimer(() => {
       planTimedOut = true;
       log33.warn(this.tag, "Planning pass exceeded timeout — abandoning, implementing directly");
       if (this.sdkRunner) {
@@ -11055,7 +11121,7 @@ ${prompt}`;
           sigtermTimeoutMs: 5000
         }).catch(() => {});
       }
-    }, Math.min(this.config.maxTimeout, PLAN_PHASE_TIMEOUT));
+    });
     try {
       await this.spawnClaude(planPrompt, card, [], {
         model: planning.model,
@@ -11155,7 +11221,7 @@ ${prompt}`;
     }).catch(() => {});
     const contractPrompt = buildContractPrompt(enriched, this.worktreePath);
     let contractTimedOut = false;
-    const contractTimeout = setTimeout(() => {
+    const contractTimeout = this.armPhaseTimer(() => {
       contractTimedOut = true;
       log33.warn(this.tag, "Contract pass exceeded timeout — abandoning, implementing directly");
       if (this.sdkRunner) {
@@ -11166,7 +11232,7 @@ ${prompt}`;
           sigtermTimeoutMs: 5000
         }).catch(() => {});
       }
-    }, Math.min(this.config.maxTimeout, PLAN_PHASE_TIMEOUT));
+    });
     try {
       await this.spawnClaude(contractPrompt, card, [], {
         model: contractCfg.model,
@@ -11218,7 +11284,8 @@ ${prompt}`;
   async drainSteeringMessages(card, subtasks) {
     if (!this.cliSessionId || !this.sessionId || !this.cardId)
       return;
-    for (let i = 0;i < MAX_STEERING_ITERATIONS && !this.aborted; i++) {
+    const { maxIterations, maxTurns } = this.config.steering;
+    for (let i = 0;(maxIterations < 0 || i < maxIterations) && !this.aborted; i++) {
       let messages;
       try {
         const res = await this.client.getPendingUserMessages(this.cardId, this.sessionId, this.lastDrainedSeq);
@@ -11236,7 +11303,7 @@ ${prompt}`;
       try {
         await this.spawnClaude(buildSteeringPrompt(messages.map((m) => frameSteeringQuestion(m.text, m.questionCommentId))), card, subtasks, {
           model: this.selectImplementModel(card),
-          maxTurns: STEERING_MAX_TURNS,
+          maxTurns: maxTurns < 0 ? undefined : maxTurns,
           resumeSessionId: this.cliSessionId,
           noCommitNotice: true,
           ...this.activeRunSpawnOpts ?? {}
@@ -11542,7 +11609,7 @@ ${prompt}`;
     this.chargedTokens = emptyTokens();
   }
 }
-var TAG30 = "worker", CANCEL_SIGINT_TIMEOUT2 = 30000, CANCEL_SIGTERM_TIMEOUT2 = 1e4, STEERING_MAX_TURNS = 15, MAX_STEERING_ITERATIONS = 10, PLAN_ALLOWED_TOOLS = "Read,Grep,Glob,mcp__harmony__*", IMPLEMENT_ALLOWED_TOOLS = "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*", PLAN_PHASE_TIMEOUT;
+var TAG30 = "worker", CANCEL_SIGINT_TIMEOUT2 = 30000, CANCEL_SIGTERM_TIMEOUT2 = 1e4, PLAN_ALLOWED_TOOLS = "Read,Grep,Glob,mcp__harmony__*", IMPLEMENT_ALLOWED_TOOLS = "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*";
 var init_worker = __esm(() => {
   init_src();
   init_board_helpers();
@@ -11562,7 +11629,6 @@ var init_worker = __esm(() => {
   init_transitions();
   init_types();
   init_workspace_model_config();
-  PLAN_PHASE_TIMEOUT = 10 * 60000;
 });
 
 // src/workspace-model-cache.ts
@@ -11724,13 +11790,13 @@ class Pool {
       if (mode === "implement") {
         if (this.authPaused) {
           log35.debug(TAG31, `#${card.short_id} held — agent paused (auth error)`);
-          await this.emitWaiting(card.id, "Agent paused — Anthropic auth error, check API credentials");
+          await this.emitWaiting(card.id, "Agent paused — Anthropic auth error. Fix the API credentials, then restart the daemon.");
           return;
         }
         const cooldownMs = this.apiCooldownRemainingMs();
         if (cooldownMs > 0) {
           log35.debug(TAG31, `#${card.short_id} held — API cooldown ${Math.round(cooldownMs / 1000)}s remaining`);
-          await this.emitWaiting(card.id, `Paused — Anthropic API limit, retrying in ~${Math.round(cooldownMs / 1000)}s`);
+          await this.emitWaiting(card.id, `Paused — Anthropic API limit, retrying after ${new Date(this.apiCooldownUntil).toISOString().slice(11, 16)} UTC. Nothing to change: the daemon resumes by itself.`);
           return;
         }
         const decision = this.budget.check(card.id);
@@ -11739,6 +11805,7 @@ class Pool {
             await this.denyDailyBudget(card, decision.detail);
           } else {
             log35.debug(TAG31, `#${card.short_id} skipped (${decision.reason}): ${decision.detail}`);
+            await this.emitWaiting(card.id, describeGuardDenial(decision.reason, decision.detail));
           }
           return;
         }
@@ -11746,6 +11813,7 @@ class Pool {
         chainSuccessors = successors;
         if (blockers === null) {
           log35.warn(TAG31, `#${card.short_id} blocker check failed — deferring to next tick`);
+          await this.emitWaiting(card.id, "Waiting — could not read this card's links to check for blockers. The daemon retries on the next tick.");
           return;
         }
         if (blockers.length > 0) {
@@ -11779,7 +11847,7 @@ class Pool {
     }
   }
   async denyDailyBudget(card, detail) {
-    const reason = `Daily budget reached — waiting for reset (${detail})`;
+    const reason = describeGuardDenial("daily_budget", detail);
     const line = `#${card.short_id} skipped (daily_budget): ${detail}`;
     if (this.lastWaitingEmit.get(card.id) === reason)
       log35.debug(TAG31, line);
@@ -11787,6 +11855,11 @@ class Pool {
       log35.warn(TAG31, line);
     await this.emitWaiting(card.id, reason);
   }
+  async noteSkip(cardId, reason) {
+    if (this.isCardKnown(cardId))
+      return;
+    await this.emitWaiting(cardId, reason);
+  }
   lastWaitingEmit = new Map;
   async emitWaiting(cardId, currentTask) {
     if (this.lastWaitingEmit.get(cardId) === currentTask)
@@ -13901,6 +13974,7 @@ var init_startup_model = __esm(() => {
 // src/startup-banner.ts
 var exports_startup_banner = {};
 __export(exports_startup_banner, {
+  limitsLine: () => limitsLine,
   createStartupBanner: () => createStartupBanner,
   contextSourceLine: () => contextSourceLine
 });
@@ -13962,6 +14036,7 @@ function jsonBanner(config, version) {
   log44.info(TAG40, `Harmony Agent Daemon v${version} starting...`);
   log44.info(TAG40, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Runner: ${config.agent.runner} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
   log44.info(TAG40, `Config: ${contextSourceLine(config)}`);
+  log44.info(TAG40, `Limits: ${limitsLine(config)}`);
   if (config.agent.review.enabled) {
     log44.info(TAG40, `Review: enabled | Columns: ${config.agent.review.pickupColumns.join(", ")} | → ${config.agent.review.moveToColumn} / ${config.agent.review.failColumn}`);
   }
@@ -14041,6 +14116,7 @@ function configRows(config, projectName, gitProvider, httpPort, model) {
     value: `${modelDesc}  ·  ${poolDesc}  ·  ${flowDesc}`
   });
   rows.push({ label: "Runner", value: runnerDesc(config.agent.runner) });
+  rows.push({ label: "Limits", value: limitsLine(config) });
   const tail = [];
   if (gitProvider)
     tail.push(gitProvider);
@@ -14063,6 +14139,21 @@ function contextSourceLine(config) {
   const pinLabel = config.repoAgentPaths.size > 0 ? "repo pin, +auto-merge" : "repo pin";
   return `project+workspace ${path} (${pinLabel})  ·  rest ${globalPath}`;
 }
+function limitsLine(config) {
+  const { budget, review, worktree } = config.agent;
+  const cap = (value, unit) => value < 0 ? "unlimited" : `${value} ${unit}`;
+  const parts = [
+    `${budget.maxAttemptsPerCard} attempts/card (budget.maxAttemptsPerCard)`,
+    `${cap(budget.maxTurnsPerCard, "turns")}/card (budget.maxTurnsPerCard)`,
+    `${cap(budget.maxRunsPerCard, "runs")}/card (budget.maxRunsPerCard)`,
+    `${budget.dailyBudgetCents < 0 ? "unlimited" : `$${(budget.dailyBudgetCents / 100).toFixed(2)}`}/day (budget.dailyBudgetCents)`
+  ];
+  if (review.enabled) {
+    parts.push(`${review.maxReviewCycles} review cycles (review.maxReviewCycles)`);
+  }
+  parts.push(`failed branches ${worktree.failedAttemptRetentionDays > 0 ? `${worktree.failedAttemptRetentionDays}d` : "kept"} (worktree.failedAttemptRetentionDays)`);
+  return parts.join("  ·  ");
+}
 function titleRule(title) {
   const prefix = "─── ";
   const surround = ` `;
@@ -15019,6 +15110,7 @@ var exports_worktree_gc = {};
 __export(exports_worktree_gc, {
   runWorktreeGc: () => runWorktreeGc,
   pruneFailedRemoteBranches: () => pruneFailedRemoteBranches,
+  noteExpiringBranches: () => noteExpiringBranches,
   isTransientGitNetworkError: () => isTransientGitNetworkError,
   WorktreeGc: () => WorktreeGc
 });
@@ -15150,6 +15242,7 @@ function pruneFailedRemoteBranches(opts) {
     scanned: 0,
     removed: [],
     skipped: [],
+    expiring: [],
     errors: []
   };
   if (!opts.prefix)
@@ -15208,6 +15301,9 @@ function pruneFailedRemoteBranches(opts) {
     result.scanned++;
     if (!Number.isFinite(ts) || ts >= cutoffSecs) {
       result.skipped.push(ref);
+      if (Number.isFinite(ts) && ts < cutoffSecs + EXPIRY_NOTICE_SECS) {
+        result.expiring.push(ref);
+      }
       continue;
     }
     if (clock() > sweepDeadline) {
@@ -15271,7 +15367,10 @@ class WorktreeGc {
     }
     if (this.remoteOpts) {
       try {
-        pruneFailedRemoteBranches(this.remoteOpts);
+        const pruned = pruneFailedRemoteBranches(this.remoteOpts);
+        if (pruned.expiring.length > 0) {
+          this.remoteOpts.onExpiring?.(pruned.expiring);
+        }
       } catch (err) {
         log48.warn(TAG44, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
       }
@@ -15283,6 +15382,28 @@ class WorktreeGc {
     }
   }
 }
+async function noteExpiringBranches(store, client, refs, retentionDays, notified) {
+  for (const ref of refs) {
+    if (notified.has(ref))
+      continue;
+    const owner = store.listCards().find((c) => c.daemonBranch === ref || c.failureHistory?.some((f) => f.recoveryBranch === ref));
+    if (!owner)
+      continue;
+    notified.add(ref);
+    try {
+      await client.addComment(owner.cardId, [
+        "**Failed-attempt branch expires within a day.**",
+        `\`${ref}\` holds this card's unfinished commits. The daemon deletes failed-attempt branches after ${retentionDays} days (\`worktree.failedAttemptRetentionDays\`), and the next sweep removes this one.`,
+        "To keep the work, check it out or open a PR from it now. To keep such branches longer, raise `worktree.failedAttemptRetentionDays` in the daemon config (0 turns the sweep off)."
+      ].join(`
+
+`), { commentType: "summary" });
+    } catch (err) {
+      notified.delete(ref);
+      log48.warn(TAG44, `Failed to post the expiring-branch note for ${ref}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
 function getRepoRoot2() {
   try {
     return execFileSync8("git", [...GIT_NO_HOOKS9, "rev-parse", "--show-toplevel"], {
@@ -15292,7 +15413,7 @@ function getRepoRoot2() {
     return null;
   }
 }
-var TAG44 = "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 TAG44 = "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, EXPIRY_NOTICE_SECS;
 var init_worktree_gc = __esm(() => {
   init_run_gc();
   GIT_NETWORK_EXEC = {
@@ -15317,6 +15438,7 @@ var init_worktree_gc = __esm(() => {
     "enotfound",
     "enetunreach"
   ].join("|"), "i");
+  EXPIRY_NOTICE_SECS = 24 * 60 * 60;
 });
 
 // src/index.ts
@@ -15420,6 +15542,7 @@ async function main() {
     validateSweepConfig(config.agent);
     validateRankingConfig(config.agent);
     validateRetentionConfig(config.agent);
+    validateRunLimitsConfig(config.agent);
     validateVerificationConfig(config.agent);
     validateSizingConfig(config.agent);
     validateHttpConfig(config.agent);
@@ -15517,9 +15640,15 @@ async function main() {
       await settlePlanCriteria(client, "merge-monitor", completedCard);
     };
   }
+  const expiringNotified = new Set;
   const worktreeGc = new WorktreeGc(config.agent.worktree.basePath, stateStore, config.agent.timing.worktreeGcIntervalMs, config.agent.worktree.failedAttemptRetentionDays > 0 ? {
     prefix: config.agent.worktree.failedBranchPrefix,
-    retentionDays: config.agent.worktree.failedAttemptRetentionDays
+    retentionDays: config.agent.worktree.failedAttemptRetentionDays,
+    onExpiring: (refs) => {
+      noteExpiringBranches(stateStore, client, refs, config.agent.worktree.failedAttemptRetentionDays, expiringNotified).catch((err) => {
+        log49.warn(TAG45, `Expiring-branch notes failed: ${err}`);
+      });
+    }
   } : undefined, config.agent.retention);
   let boardReviewer = null;
   if (config.agent.boardReview.enabled) {
@@ -15714,6 +15843,7 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const column = columns.find((c) => c.id === card.column_id);
   if (!column) {
     log49.warn(TAG45, `Column not found for card ${cardId}`);
+    await pool.noteSkip(cardId, "Not picked up — the card's column was not found on the board. Check the card is in a column of this project.");
     return;
   }
   const route = classifyPickup(column.name, {
@@ -15722,6 +15852,8 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   });
   if (!route) {
     log49.info(TAG45, `Card #${card.short_id} is in "${column.name}", not a pickup/review column — skipping`);
+    const reviewColumns = config.agent.review.enabled ? config.agent.review.pickupColumns : [];
+    await pool.noteSkip(card.id, `Not picked up — "${column.name}" is not a pickup column. Pickup: ${config.agent.pickupColumns.join(", ")} (\`pickupColumns\`)${reviewColumns.length > 0 ? `; review: ${reviewColumns.join(", ")} (\`review.pickupColumns\`)` : ""}. Move the card into one of them.`);
     return;
   }
   const mode = route.mode;
@@ -15730,14 +15862,17 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const subtasks = card.subtasks ?? [];
   if (mode === "review" && config.agent.review.approvedLabel && hasLabel(cardLabels, config.agent.review.approvedLabel)) {
     log49.debug(TAG45, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
+    await pool.noteSkip(card.id, `Not reviewed — the card already has the "${config.agent.review.approvedLabel}" label (\`review.approvedLabel\`). Remove the label to queue a review.`);
     return;
   }
   if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
     log49.debug(TAG45, `Card #${card.short_id} has "${NEED_REVIEW_LABEL}" label (needs human) — skipping review`);
+    await pool.noteSkip(card.id, `Not reviewed — the card has the "${NEED_REVIEW_LABEL}" label, so a person owns the next step. Remove the label to queue another review.`);
     return;
   }
   if (mode === "review" && !qualifiesForAutoReview(card.description)) {
     log49.info(TAG45, `Card #${card.short_id} has no branch or PR reference — skipping auto-review`);
+    await pool.noteSkip(card.id, "Not reviewed — the card description has no `Branch:` line and no PR link, so there is nothing to review. Add one to queue a review.");
     return;
   }
   await pool.enqueue(card, column, cardLabels, subtasks, mode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/agent",
-  "version": "1.49.5",
+  "version": "1.49.6",
   "description": "Push-based agent daemon for Harmony — picks up assigned cards, builds them in isolated git worktrees, and opens PRs. It runs where you put it.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",
-    "@gethmy/harness": "1.19.12",
+    "@gethmy/harness": "1.19.13",
     "@gethmy/mcp": "3.23.1",
     "@supabase/supabase-js": "2.95.3"
   },