@gethmy/agent 1.9.1 → 1.9.2

package/dist/cli.js

@@ -220,12 +220,170 @@ var init_board_helpers = __esm(() => {
   init_log();
 });
 
+// src/plan-phase.ts
+function scoreComplexity(enriched) {
+  const { card, labels, subtasks } = enriched;
+  let score = 0;
+  const desc = (card.description ?? "").trim();
+  if (desc.length > 600)
+    score += 3;
+  else if (desc.length > 200)
+    score += 2;
+  else if (desc.length > 0)
+    score += 1;
+  score += Math.min(subtasks.length, 4);
+  const names = labels.map((l) => l.name.toLowerCase());
+  if (names.some((n) => /feature|epic|refactor|architecture|migration/.test(n))) {
+    score += 2;
+  }
+  if (names.some((n) => /typo|chore|trivial|docs/.test(n))) {
+    score -= 2;
+  }
+  return Math.max(0, score);
+}
+function shouldPlan(enriched, config) {
+  if (!config.enabled)
+    return false;
+  const { card } = enriched;
+  const hasPlan = !!card.plan_id;
+  const needsRefresh = card.needs_plan_refresh === true;
+  if (hasPlan && !needsRefresh)
+    return false;
+  return scoreComplexity(enriched) >= config.minComplexityScore;
+}
+function buildPlanPrompt(enriched, worktreePath) {
+  const { card, column, labels, subtasks } = enriched;
+  const labelStr = labels.length > 0 ? labels.map((l) => l.name).join(", ") : "none";
+  const subtaskStr = subtasks.length > 0 ? subtasks.map((s) => `- ${s.title}`).join(`
+`) : "No subtasks defined.";
+  const description = card.description?.trim() || "No description provided.";
+  return `You are a senior engineer producing an IMPLEMENTATION PLAN for a task on the Harmony board. You are in PLAN MODE: explore the codebase to ground the plan, but do NOT write, edit, or commit any code in this pass.
+
+## Card: #${card.short_id} - ${card.title}
+**Labels**: ${labelStr}
+**Column**: ${column.name}
+**Priority**: ${card.priority}
+
+## Description
+${description}
+
+## Subtasks
+${subtaskStr}
+
+## Your job
+1. Read the parts of the codebase relevant to this task (use Read/Grep/Glob; do NOT edit).
+2. Decide the smallest correct approach. Note the exact files you expect to touch.
+3. Call out risks, unknowns, and anything that needs a human decision.
+4. Break the work into ordered, independently-verifiable tasks.
+
+You are exploring the worktree at \`${worktreePath}\`. Read-only this pass — no Write/Edit/Bash-that-mutates, no commits.
+
+## Output contract
+End your final message with EXACTLY ONE fenced block tagged \`plan\`, in this structure:
+
+\`\`\`plan
+# <one-line plan title>
+
+## Approach
+<2-4 sentences: the chosen approach and why>
+
+## Files
+- <path> — <what changes here>
+
+## Steps
+1. <ordered step>
+2. <ordered step>
+
+## Tasks
+- [ ] <discrete, verifiable task>
+- [ ] <discrete, verifiable task>
+
+## Risks
+- <risk / unknown / decision needed, or "none">
+\`\`\`
+
+The \`## Tasks\` checklist is parsed into trackable tasks, so keep each line a single concrete action.`;
+}
+function extractPlanArtifact(assistantText, fallbackTitle) {
+  const text = assistantText ?? "";
+  const fenced = text.match(PLAN_FENCE);
+  const markdown = (fenced ? fenced[1] : text).trim();
+  const titleMatch = markdown.match(H1);
+  const title = (titleMatch?.[1] ?? fallbackTitle).trim() || fallbackTitle;
+  return {
+    title,
+    markdown,
+    tasks: parseTasksSection(markdown)
+  };
+}
+function parseTasksSection(markdown) {
+  const lines = markdown.split(`
+`);
+  const tasks = [];
+  let inTasks = false;
+  for (const line of lines) {
+    const heading = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (heading) {
+      inTasks = /^tasks\b/i.test(heading[1].trim());
+      continue;
+    }
+    if (!inTasks)
+      continue;
+    const item = line.match(TASK_LINE);
+    if (item) {
+      const content = item[1].trim();
+      if (content)
+        tasks.push({ content });
+    }
+  }
+  return tasks;
+}
+function buildPlanComment(artifact) {
+  const body = artifact.markdown.trim();
+  return [
+    "## \uD83E\uDDED Plan (agent, advisory)",
+    "",
+    "The daemon explored the worktree read-only and produced this plan before implementing. Implementation is starting now in the same run.",
+    "",
+    body
+  ].join(`
+`);
+}
+function buildGatedPlanComment(artifact, pickupColumnName) {
+  const body = artifact.markdown.trim();
+  return [
+    "## \uD83E\uDDED Plan (agent, awaiting approval)",
+    "",
+    `The daemon explored the worktree read-only and produced this plan. Implementation is **gated on your approval** — review the plan below, then move this card to **${pickupColumnName}** to start implementation with it. Edit the linked plan first if the approach needs changes.`,
+    "",
+    body
+  ].join(`
+`);
+}
+var DEFAULT_PLANNING_CONFIG, PLAN_FENCE, H1, TASK_LINE;
+var init_plan_phase = __esm(() => {
+  DEFAULT_PLANNING_CONFIG = {
+    enabled: false,
+    mode: "advisory",
+    model: "sonnet",
+    maxTurns: 40,
+    postComment: true,
+    awaitingApprovalColumn: "To Do",
+    minComplexityScore: 3,
+    approvalTtlHours: 0
+  };
+  PLAN_FENCE = /```plan\s*\n([\s\S]*?)```/i;
+  H1 = /^#\s+(.+?)\s*$/m;
+  TASK_LINE = /^\s*(?:[-*]\s*\[[ xX]?\]|[-*]|\d+[.)])\s+(.+?)\s*$/;
+});
+
 // src/types.ts
 function agentIdentifier(workerId) {
   return `harmony-daemon-${workerId}`;
 }
-var DEFAULT_AGENT_CONFIG, NEED_REVIEW_LABEL = "Need Review", NEED_REVIEW_LABEL_COLOR = "#f59e0b", AGENT_NAME = "Harmony Agent";
+var DEFAULT_AGENT_CONFIG, IN_PROGRESS_COLUMN = "In Progress", NEED_REVIEW_LABEL = "Need Review", NEED_REVIEW_LABEL_COLOR = "#f59e0b", AGENT_NAME = "Harmony Agent";
 var init_types = __esm(() => {
+  init_plan_phase();
   DEFAULT_AGENT_CONFIG = {
     poolSize: 3,
     maxTimeout: 1800000,
@@ -292,7 +450,8 @@ var init_types = __esm(() => {
       staleHeartbeatMs: 120000,
       reconcileIntervalMs: 60000,
       worktreeGcIntervalMs: 5 * 60000
-    }
+    },
+    planning: DEFAULT_PLANNING_CONFIG
   };
 });
 
@@ -388,6 +547,10 @@ function loadDaemonConfig() {
     timing: {
       ...DEFAULT_AGENT_CONFIG.timing,
       ...agentOverrides.timing ?? {}
+    },
+    planning: {
+      ...DEFAULT_AGENT_CONFIG.planning,
+      ...agentOverrides.planning ?? {}
     }
   };
   return {
@@ -447,6 +610,20 @@ async function validateColumnReferences(client, projectId, config) {
     }
     required.push({ value: config.review.moveToColumn, where: "review.moveToColumn" }, { value: config.review.failColumn, where: "review.failColumn" });
   }
+  if (config.planning.enabled && config.planning.mode === "gated") {
+    required.push({
+      value: config.planning.awaitingApprovalColumn,
+      where: "planning.awaitingApprovalColumn"
+    });
+    const parkCol = config.planning.awaitingApprovalColumn?.toLowerCase();
+    const allPickups = [
+      ...config.pickupColumns,
+      ...config.review.enabled ? config.review.pickupColumns : []
+    ];
+    if (parkCol && allPickups.some((c) => c.toLowerCase() === parkCol)) {
+      issues.push(`planning.awaitingApprovalColumn: "${config.planning.awaitingApprovalColumn}" is also a pickup column (implement or review) — a gated card parked there is picked up immediately, bypassing approval. Use a column the daemon does not pick up from.`);
+    }
+  }
   for (const { value, where } of required) {
     if (!value)
       continue;
@@ -841,24 +1018,63 @@ import {
 class HttpServer {
   opts;
   server = null;
+  boundPort = null;
   constructor(opts) {
     this.opts = opts;
   }
+  get port() {
+    return this.boundPort;
+  }
   async start() {
-    return new Promise((resolve, reject) => {
-      this.server = createServer((req, res) => {
-        this.route(req, res).catch((err) => {
-          log.error(TAG3, `unhandled: ${err instanceof Error ? err.message : err}`);
-          if (!res.headersSent) {
-            res.writeHead(500, { "content-type": "application/json" });
-            res.end(JSON.stringify({ error: "internal_error" }));
-          }
-        });
+    this.server = createServer((req, res) => {
+      this.route(req, res).catch((err) => {
+        log.error(TAG3, `unhandled: ${err instanceof Error ? err.message : err}`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "internal_error" }));
+        }
       });
-      this.server.once("error", reject);
-      this.server.listen(this.opts.port, this.opts.bindAddr, () => {
+    });
+    const attempts = Math.max(1, this.opts.maxPortAttempts ?? 10);
+    const startPort = this.opts.port;
+    for (let i = 0;i < attempts; i++) {
+      const port = startPort + i;
+      try {
+        await this.listenOnce(port);
+        this.boundPort = port;
+        if (port !== startPort) {
+          log.info(TAG3, `port ${startPort} busy — bound to ${port} instead`);
+        }
+        return port;
+      } catch (err) {
+        const lastAttempt = i === attempts - 1;
+        if (isAddrInUse(err) && !lastAttempt) {
+          log.debug(TAG3, `port ${port} in use, trying ${port + 1}`);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw new Error("HTTP server failed to bind");
+  }
+  listenOnce(port) {
+    return new Promise((resolve, reject) => {
+      const server = this.server;
+      if (!server) {
+        reject(new Error("server not created"));
+        return;
+      }
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        reject(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
         resolve();
-      });
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(port, this.opts.bindAddr);
     });
   }
   async stop() {
@@ -868,6 +1084,7 @@ class HttpServer {
       this.server?.close(() => resolve());
     });
     this.server = null;
+    this.boundPort = null;
   }
   async route(req, res) {
     const url = new URL(req.url ?? "/", "http://localhost");
@@ -914,6 +1131,9 @@ class HttpServer {
     }
   }
 }
+function isAddrInUse(err) {
+  return typeof err === "object" && err !== null && err.code === "EADDRINUSE";
+}
 function parseCommand(path) {
   const match = path.match(/^\/(pause|resume|stop)\/([^/]+)$/);
   if (!match)
@@ -1374,6 +1594,62 @@ function formatCents(cents) {
   return `$${(cents / 100).toFixed(2)}`;
 }
 
+// src/error-classifier.ts
+function parseRetryAfterMs(message) {
+  const match = message.match(/retry[- ]?after["':\s]+(\d+)/i);
+  if (!match)
+    return;
+  const seconds = Number(match[1]);
+  if (!Number.isFinite(seconds) || seconds <= 0)
+    return;
+  return seconds * 1000;
+}
+function classifyRunError(message) {
+  if (!message)
+    return { kind: null };
+  const retryAfterMs = parseRetryAfterMs(message);
+  if (AUTH.test(message))
+    return { kind: "auth", retryAfterMs };
+  if (OUT_OF_CREDITS.test(message))
+    return { kind: "out_of_credits", retryAfterMs };
+  if (USAGE_LIMIT.test(message))
+    return { kind: "usage_limit", retryAfterMs };
+  if (RATE_LIMIT.test(message))
+    return { kind: "rate_limit", retryAfterMs };
+  return { kind: null };
+}
+function describeApiError(kind) {
+  switch (kind) {
+    case "auth":
+      return "Anthropic auth error — agent paused, check API credentials";
+    case "out_of_credits":
+      return "Anthropic credit balance too low — retrying after top-up";
+    case "usage_limit":
+      return "Anthropic usage limit reached — retrying after reset";
+    case "rate_limit":
+      return "Anthropic rate limit hit — retrying shortly";
+  }
+}
+function cooldownMsFor(kind) {
+  switch (kind) {
+    case "rate_limit":
+      return 60000;
+    case "usage_limit":
+      return 15 * 60000;
+    case "out_of_credits":
+      return 30 * 60000;
+    case "auth":
+      return 30 * 60000;
+  }
+}
+var AUTH, OUT_OF_CREDITS, USAGE_LIMIT, RATE_LIMIT;
+var init_error_classifier = __esm(() => {
+  AUTH = /\b401\b|invalid x-api-key|authentication_error|unauthorized|oauth token (?:has )?expired|please run .*login|invalid bearer token/i;
+  OUT_OF_CREDITS = /\b402\b|credit balance is too low|insufficient (?:funds|credit|balance)|billing|payment required|purchase more credits/i;
+  USAGE_LIMIT = /usage limit|daily limit|monthly limit|quota (?:exceeded|reached)|reached your .{0,20}limit|usage_limit_reached|limit will reset/i;
+  RATE_LIMIT = /\b429\b|\b529\b|rate[ _-]?limit|too many requests|overloaded_error|"type"\s*:\s*"overloaded"/i;
+});
+
 // src/queue.ts
 class PriorityQueue {
   config;
@@ -2386,13 +2662,15 @@ class ProgressTracker {
   sessionId = null;
   lastAssistantText = "";
   assistantTextBlocks = [];
-  constructor(client, cardId, workerId, subtasks) {
+  constructor(client, cardId, workerId, subtasks, initialPhase = "exploring") {
     this.client = client;
     this.cardId = cardId;
     this.workerId = workerId;
     this.subtaskTotal = subtasks.length;
     this.subtaskCompleted = subtasks.filter((s) => s.completed).length;
     this.subtaskMode = subtasks.length > 0;
+    this.phase = initialPhase;
+    this.progress = PHASES[initialPhase].min;
   }
   setSessionId(id) {
     this.sessionId = id;
@@ -2720,6 +2998,7 @@ var init_progress_tracker = __esm(() => {
   GIT_COMMIT_RE = /\bgit\s+commit\b/;
   BUILD_CMD_RE = /\b(test|build|lint|check|tsc|vitest|jest|(?:bun|npm|pnpm|yarn) run (?:build|lint))\b/;
   PHASES = {
+    planning: { min: 5, max: 20, label: "Planning" },
     exploring: { min: 10, max: 25, label: "Exploring" },
     implementing: { min: 25, max: 55, label: "Implementing" },
     testing: { min: 55, max: 65, label: "Testing" },
@@ -2727,6 +3006,7 @@ var init_progress_tracker = __esm(() => {
     finishing: { min: 70, max: 75, label: "Finalizing" }
   };
   PHASE_ORDER = {
+    planning: -1,
     exploring: 0,
     implementing: 1,
     testing: 2,
@@ -3032,6 +3312,14 @@ ${finding.description}${locationLine}`
 `);
       await postReviewComment(client, card, "summary", body);
     }
+    if (config.planning.enabled && card.plan_id) {
+      try {
+        await client.updateCard(card.id, { needsPlanRefresh: true });
+        log.info(TAG15, `#${card.short_id} flagged needs_plan_refresh after rejected review`);
+      } catch (err) {
+        log.warn(TAG15, `Failed to flag needs_plan_refresh for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
     await moveCardToColumn(client, card, config.review.failColumn);
     const failureSummary = `Review rejected (cycle ${currentCycle}/${maxCycles}): ${criticalFindings.length} critical, ${majorFindings.length} major, ${minorFindings.length} minor`;
     const recoveryBranch = branchName ?? undefined;
@@ -3444,6 +3732,13 @@ class StateStore {
     await this.persist();
     return rec.attempts;
   }
+  async decrementAttempt(cardId) {
+    const rec = this.getCard(cardId);
+    if (!rec || rec.attempts === 0)
+      return;
+    rec.attempts = Math.max(0, rec.attempts - 1);
+    await this.persist();
+  }
   async recordOutcome(cardId, outcome) {
     const rec = this.ensureCard(cardId);
     rec.lastOutcome = outcome;
@@ -4692,6 +4987,7 @@ class Worker {
   projectId;
   stateStore;
   onCardCompleted;
+  onApiError;
   id;
   state = "idle";
   cardId = null;
@@ -4708,7 +5004,7 @@ class Worker {
   verificationFailed = false;
   sessionId = null;
   runId = null;
-  constructor(id, config, client, agentId, onDone, workspaceId, projectId, stateStore, onCardCompleted) {
+  constructor(id, config, client, agentId, onDone, workspaceId, projectId, stateStore, onCardCompleted, onApiError) {
     this.config = config;
     this.client = client;
     this.agentId = agentId;
@@ -4717,6 +5013,7 @@ class Worker {
     this.projectId = projectId;
     this.stateStore = stateStore;
     this.onCardCompleted = onCardCompleted;
+    this.onApiError = onApiError;
     this.id = id;
   }
   startHeartbeat() {
@@ -4757,7 +5054,7 @@ class Worker {
     return this.state === "idle";
   }
   get isActive() {
-    return this.state === "preparing" || this.state === "running" || this.state === "verifying" || this.state === "completing";
+    return this.state === "preparing" || this.state === "planning" || this.state === "running" || this.state === "verifying" || this.state === "completing";
   }
   async run(card, column, labels, subtasks) {
     this.aborted = false;
@@ -4803,7 +5100,7 @@ class Worker {
       }
       this.sessionId = sid;
       await this.recordPhase("preparing");
-      const moved = await moveCardAndAddLabel(this.client, card, "In Progress", "agent");
+      const moved = await moveCardAndAddLabel(this.client, card, IN_PROGRESS_COLUMN, "agent");
       if (!moved) {
         log.warn(this.tag, `Card #${card.short_id} was NOT moved to "In Progress" — check API logs`);
       }
@@ -4812,8 +5109,6 @@ class Worker {
       this.worktreePath = createWorktree(this.config.worktree.basePath, this.config.worktree.baseBranch, this.branchName);
       if (this.aborted)
         return;
-      this.state = "running";
-      await this.recordPhase("running");
       const enriched = {
         card,
         column,
@@ -4821,6 +5116,19 @@ class Worker {
         subtasks,
         mode: "implement"
       };
+      if (shouldPlan(enriched, this.config.planning)) {
+        this.state = "planning";
+        await this.recordPhase("planning");
+        const parked = await this.runPlanningPhase(enriched);
+        if (this.aborted)
+          return;
+        if (parked) {
+          log.info(this.tag, `#${card.short_id} parked for plan approval — ending run`);
+          return;
+        }
+      }
+      this.state = "running";
+      await this.recordPhase("running");
       const prompt = await buildPrompt(enriched, this.branchName, this.worktreePath, this.client, this.workspaceId, this.projectId);
       await this.client.updateAgentProgress(card.id, {
         agentIdentifier: agentIdentifier(this.id),
@@ -4859,21 +5167,46 @@ class Worker {
       this.state = "error";
       const msg = err instanceof Error ? err.message : String(err);
       log.error(this.tag, `Error on #${card.short_id}: ${msg}`);
+      const rawStderr = err?.stderr;
+      const errClass = classifyRunError(typeof rawStderr === "string" && rawStderr ? rawStderr : msg);
+      const apiError = errClass.kind !== null;
+      if (apiError) {
+        try {
+          this.onApiError?.(errClass);
+        } catch {}
+      }
+      if (this.worktreePath) {
+        try {
+          cleanupWorktree(this.worktreePath, this.branchName ?? undefined);
+        } catch {
+          log.warn(this.tag, "Failed to cleanup worktree before requeue");
+        }
+        this.worktreePath = null;
+      }
+      const failureReason = apiError ? errClass.kind : "other";
+      const failureSummary = apiError ? describeApiError(errClass.kind) : `Run failed: ${msg.slice(0, 300)}`;
       try {
         await runTransition(this.client, card, {
+          move: { columnName: this.config.pickupColumns[0] ?? "To Do" },
           endSession: {
-            status: "paused",
+            status: "failed",
+            failureReason,
+            failureSummary,
             ...buildTokenPayload(this.lastSessionStats)
           }
         });
       } catch (tErr) {
-        log.error(this.tag, `endAgentSession unrecoverable on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
+        log.error(this.tag, `error transition failed on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
       }
       if (this.runId) {
         try {
-          await this.stateStore.endRun(this.runId, "paused", msg);
+          await this.stateStore.endRun(this.runId, "failed", errClass.kind ?? msg);
         } catch {}
-        await this.recordOutcome(card.id, "failure");
+        if (apiError) {
+          await this.stateStore.decrementAttempt(card.id);
+        } else {
+          await this.recordOutcome(card.id, "failure");
+        }
       }
     } finally {
       const succeeded = this.runId && this.state !== "error" && !this.aborted && !this.verificationFailed;
@@ -5017,7 +5350,122 @@ class Worker {
       }
     }
   }
-  async spawnClaude(prompt, card, subtasks) {
+  async runPlanningPhase(enriched) {
+    const planning = this.config.planning;
+    const { card } = enriched;
+    log.info(this.tag, `Planning pass for #${card.short_id} (mode=${planning.mode}, model=${planning.model})`);
+    await this.client.updateAgentProgress(card.id, {
+      agentIdentifier: agentIdentifier(this.id),
+      agentName: AGENT_NAME,
+      status: "working",
+      currentTask: "Planning approach (read-only)",
+      progressPercent: 5,
+      phase: "planning"
+    }).catch(() => {});
+    const planPrompt = buildPlanPrompt(enriched, this.worktreePath);
+    let planTimedOut = false;
+    const planTimeout = setTimeout(() => {
+      planTimedOut = true;
+      log.warn(this.tag, "Planning pass exceeded timeout — abandoning, implementing directly");
+      if (this.process && !this.process.killed) {
+        terminateGroup(this.process, {
+          sigintTimeoutMs: 1e4,
+          sigtermTimeoutMs: 5000
+        }).catch(() => {});
+      }
+    }, Math.min(this.config.maxTimeout, PLAN_PHASE_TIMEOUT));
+    try {
+      await this.spawnClaude(planPrompt, card, [], {
+        model: planning.model,
+        maxTurns: planning.maxTurns,
+        allowedTools: PLAN_ALLOWED_TOOLS,
+        initialPhase: "planning"
+      });
+    } catch (err) {
+      log.warn(this.tag, `Planning pass failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+      return false;
+    } finally {
+      clearTimeout(planTimeout);
+    }
+    if (this.aborted || planTimedOut)
+      return false;
+    const stats = this.lastSessionStats;
+    if (stats?.cost) {
+      const cents = Math.round(stats.cost.totalCostUsd * 100);
+      if (cents > 0) {
+        try {
+          await this.stateStore.addCost(card.id, cents);
+        } catch {}
+      }
+    }
+    const planText = stats?.lastAssistantText ?? "";
+    if (!planText.trim()) {
+      log.warn(this.tag, `Planning pass for #${card.short_id} produced no text — implementing directly`);
+      return false;
+    }
+    const artifact = extractPlanArtifact(planText, card.title);
+    let planId = null;
+    try {
+      const result = await this.client.createPlan(this.projectId, {
+        title: artifact.title,
+        content: artifact.markdown,
+        source: "agent",
+        tasks: artifact.tasks
+      });
+      const plan = result?.plan;
+      const createdId = plan && typeof plan === "object" && "id" in plan ? plan.id : null;
+      if (createdId) {
+        await this.client.updateCard(card.id, {
+          planId: createdId,
+          needsPlanRefresh: false
+        });
+        planId = createdId;
+      }
+      log.info(this.tag, `Stored plan ${planId ?? "(unlinked)"} for #${card.short_id} (${artifact.tasks.length} tasks)`);
+    } catch (err) {
+      log.warn(this.tag, `Failed to store/link plan (non-fatal): ${err instanceof Error ? err.message : err}`);
+    }
+    if (planning.mode === "gated" && planId) {
+      try {
+        if (planning.postComment) {
+          await this.client.addComment(card.id, buildGatedPlanComment(artifact, planning.awaitingApprovalColumn), {
+            commentType: "decision",
+            agentSessionId: this.sessionId ?? undefined
+          });
+        }
+        await runTransition(this.client, card, {
+          move: { columnName: planning.awaitingApprovalColumn },
+          removeLabels: ["agent"],
+          endSession: {
+            status: "completed",
+            progressPercent: 20,
+            ...buildTokenPayload(stats)
+          }
+        }, { store: this.stateStore, runId: this.runId ?? undefined });
+        log.info(this.tag, `#${card.short_id} parked in "${planning.awaitingApprovalColumn}" for plan approval`);
+        this.lastSessionStats = undefined;
+        return true;
+      } catch (err) {
+        log.warn(this.tag, `Gated park failed for #${card.short_id} (non-fatal, implementing directly): ${err instanceof TransitionError ? err.detail : err instanceof Error ? err.message : err}`);
+      }
+    }
+    if (planId && planning.postComment) {
+      try {
+        await this.client.addComment(card.id, buildPlanComment(artifact), {
+          commentType: "decision",
+          agentSessionId: this.sessionId ?? undefined
+        });
+      } catch (err) {
+        log.warn(this.tag, `Failed to post advisory plan comment (non-fatal): ${err instanceof Error ? err.message : err}`);
+      }
+    }
+    return false;
+  }
+  async spawnClaude(prompt, card, subtasks, opts = {}) {
+    const model = opts.model ?? this.config.claude.model;
+    const maxTurns = opts.maxTurns ?? this.config.claude.maxTurns;
+    const allowedTools = opts.allowedTools ?? IMPLEMENT_ALLOWED_TOOLS;
+    const initialPhase = opts.initialPhase ?? "exploring";
     return new Promise((resolve3, reject) => {
       const args = [
         "-p",
@@ -5025,11 +5473,11 @@ class Worker {
         "--output-format",
         "stream-json",
         "--model",
-        this.config.claude.model,
+        model,
         "--max-turns",
-        String(this.config.claude.maxTurns),
+        String(maxTurns),
         "--allowedTools",
-        "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*",
+        allowedTools,
         ...this.config.claude.additionalArgs,
         "--",
         prompt
@@ -5048,7 +5496,7 @@ class Worker {
         stdio: ["ignore", "pipe", "pipe"]
       });
       const parser = new StreamParser;
-      this.progressTracker = new ProgressTracker(this.client, card.id, this.id, subtasks);
+      this.progressTracker = new ProgressTracker(this.client, card.id, this.id, subtasks, initialPhase);
       if (this.sessionId) {
         this.progressTracker.setSessionId(this.sessionId);
       }
@@ -5093,7 +5541,9 @@ class Worker {
         } else if (code === 0) {
           resolve3();
         } else {
-          reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`));
+          const err = new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`);
+          err.stderr = stderr;
+          reject(err);
         }
       });
     });
@@ -5125,11 +5575,13 @@ class Worker {
     this.sessionId = null;
   }
 }
-var TAG23 = "worker", CANCEL_SIGINT_TIMEOUT2 = 30000, CANCEL_SIGTERM_TIMEOUT2 = 1e4;
+var TAG23 = "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__*", PLAN_PHASE_TIMEOUT;
 var init_worker = __esm(() => {
   init_board_helpers();
   init_completion();
+  init_error_classifier();
   init_log();
+  init_plan_phase();
   init_process_group();
   init_progress_tracker();
   init_prompt();
@@ -5139,6 +5591,7 @@ var init_worker = __esm(() => {
   init_transitions();
   init_types();
   init_worktree();
+  PLAN_PHASE_TIMEOUT = 10 * 60000;
 });
 
 // src/pool.ts
@@ -5154,6 +5607,8 @@ class Pool {
   budget;
   sleepGuard = new SleepGuard;
   shuttingDown = false;
+  apiCooldownUntil = 0;
+  authPaused = false;
   onCardCompleted = null;
   constructor(config, client, _userEmail, workspaceId, projectId, stateStore, agentId) {
     this.client = client;
@@ -5172,7 +5627,7 @@ class Pool {
         }
       }, workspaceId, projectId, stateStore, async (completedCard) => {
         await this.onCardCompleted?.(completedCard);
-      }));
+      }, (err) => this.noteApiError(err)));
     }
     if (config.review.enabled) {
       for (let i = 0;i < config.review.poolSize; i++) {
@@ -5193,6 +5648,17 @@ class Pool {
       return;
     }
     if (mode === "implement") {
+      if (this.authPaused) {
+        log.debug(TAG24, `#${card.short_id} held — agent paused (auth error)`);
+        await this.emitWaiting(card.id, "Agent paused — Anthropic auth error, check API credentials");
+        return;
+      }
+      const cooldownMs = this.apiCooldownRemainingMs();
+      if (cooldownMs > 0) {
+        log.debug(TAG24, `#${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`);
+        return;
+      }
       const decision = this.budget.check(card.id);
       if (!decision.allow) {
         if (decision.reason === "daily_budget") {
@@ -5242,6 +5708,26 @@ class Pool {
       log.debug(TAG24, `waiting emit failed for ${cardId}: ${err instanceof Error ? err.message : err}`);
     }
   }
+  noteApiError(err) {
+    if (!err.kind)
+      return;
+    if (err.kind === "auth") {
+      if (!this.authPaused) {
+        log.error(TAG24, "Auth error from Claude CLI — pausing implement pickups until the daemon is restarted with valid credentials");
+      }
+      this.authPaused = true;
+      return;
+    }
+    const cooldownMs = err.retryAfterMs ?? cooldownMsFor(err.kind);
+    const until = Date.now() + cooldownMs;
+    if (until > this.apiCooldownUntil) {
+      this.apiCooldownUntil = until;
+      log.warn(TAG24, `${describeApiError(err.kind)} — pausing implement pickups for ${Math.round(cooldownMs / 1000)}s`);
+    }
+  }
+  apiCooldownRemainingMs() {
+    return Math.max(0, this.apiCooldownUntil - Date.now());
+  }
   async removeCard(cardId) {
     await this.stateStore.resetAttempts(cardId);
     this.lastWaitingEmit.delete(cardId);
@@ -5369,6 +5855,7 @@ class Pool {
 }
 var TAG24 = "pool";
 var init_pool = __esm(() => {
+  init_error_classifier();
   init_log();
   init_queue();
   init_review_worker();
@@ -5378,6 +5865,78 @@ var init_pool = __esm(() => {
   init_worker();
 });
 
+// src/port-registry.ts
+var exports_port_registry = {};
+__export(exports_port_registry, {
+  recordDaemonPort: () => recordDaemonPort,
+  lookupDaemonPort: () => lookupDaemonPort,
+  defaultRegistryPath: () => defaultRegistryPath,
+  clearDaemonPort: () => clearDaemonPort
+});
+import {
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  renameSync as renameSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname2, join as join4 } from "node:path";
+function defaultRegistryPath() {
+  return join4(homedir4(), ".harmony-mcp", "agent-ports.json");
+}
+function load(path) {
+  if (!existsSync5(path))
+    return {};
+  try {
+    const raw = readFileSync4(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object")
+      return parsed;
+    return {};
+  } catch (err) {
+    log.warn(TAG25, `failed to read ${path}: ${err instanceof Error ? err.message : err}`);
+    return {};
+  }
+}
+function save(path, registry) {
+  const dir = dirname2(path);
+  if (!existsSync5(dir))
+    mkdirSync3(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync2(tmp, JSON.stringify(registry, null, 2), "utf-8");
+  renameSync2(tmp, path);
+}
+function recordDaemonPort(projectId, entry, path = defaultRegistryPath()) {
+  try {
+    const registry = load(path);
+    registry[projectId] = { ...entry, updatedAt: Date.now() };
+    save(path, registry);
+  } catch (err) {
+    log.warn(TAG25, `failed to record port for ${projectId}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+function lookupDaemonPort(projectId, path = defaultRegistryPath()) {
+  const registry = load(path);
+  return registry[projectId] ?? null;
+}
+function clearDaemonPort(projectId, pid, path = defaultRegistryPath()) {
+  try {
+    const registry = load(path);
+    const existing = registry[projectId];
+    if (!existing || existing.pid !== pid)
+      return;
+    delete registry[projectId];
+    save(path, registry);
+  } catch (err) {
+    log.warn(TAG25, `failed to clear port for ${projectId}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+var TAG25 = "port-registry";
+var init_port_registry = __esm(() => {
+  init_log();
+});
+
 // src/recovery.ts
 function isProcessAlive(pid, currentPid) {
   if (pid === currentPid)
@@ -5394,7 +5953,7 @@ async function fetchCardSafely(client, cardId) {
     const { card } = await client.getCard(cardId);
     return card;
   } catch (err) {
-    log.warn(TAG25, `cannot fetch card ${cardId}: ${err instanceof Error ? err.message : err}`);
+    log.warn(TAG26, `cannot fetch card ${cardId}: ${err instanceof Error ? err.message : err}`);
     return null;
   }
 }
@@ -5404,7 +5963,7 @@ async function recoverOrphans(store, client, config) {
     return [];
   }
   const outcomes = [];
-  log.info(TAG25, `recovering ${active.length} orphan run(s) from prior daemon`);
+  log.info(TAG26, `recovering ${active.length} orphan run(s) from prior daemon`);
   for (const run of active) {
     const outcome = {
       runId: run.runId,
@@ -5416,11 +5975,11 @@ async function recoverOrphans(store, client, config) {
     };
     outcomes.push(outcome);
     if (isProcessAlive(run.daemonPid, process.pid)) {
-      log.warn(TAG25, `run ${run.runId} claims live daemon pid ${run.daemonPid} — skipping`);
+      log.warn(TAG26, `run ${run.runId} claims live daemon pid ${run.daemonPid} — skipping`);
       outcome.actions.push("skipped: daemon pid still alive");
       continue;
     }
-    log.info(TAG25, `recovering ${run.pipeline} run ${run.runId} for card #${run.cardShortId}`);
+    log.info(TAG26, `recovering ${run.pipeline} run ${run.runId} for card #${run.cardShortId}`);
     await recoverRun(run, store, client, config, outcome);
   }
   return outcomes;
@@ -5438,7 +5997,7 @@ async function recoverRun(run, store, client, config, outcome) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     outcome.errors.push(`endAgentSession: ${msg}`);
-    log.warn(TAG25, `endAgentSession failed for ${run.cardId}: ${msg}`);
+    log.warn(TAG26, `endAgentSession failed for ${run.cardId}: ${msg}`);
   }
   const card = await fetchCardSafely(client, run.cardId);
   if (card) {
@@ -5479,9 +6038,9 @@ async function recoverRun(run, store, client, config, outcome) {
     const msg = err instanceof Error ? err.message : String(err);
     outcome.errors.push(`endRun: ${msg}`);
   }
-  log.info(TAG25, `recovered run ${run.runId} (card #${run.cardShortId}): ${outcome.actions.join(", ")}${outcome.errors.length ? ` | errors: ${outcome.errors.join("; ")}` : ""}`);
+  log.info(TAG26, `recovered run ${run.runId} (card #${run.cardShortId}): ${outcome.actions.join(", ")}${outcome.errors.length ? ` | errors: ${outcome.errors.join("; ")}` : ""}`);
 }
-var TAG25 = "recovery", RECOVERED_LABEL = "agent-recovered", RECOVERED_LABEL_COLOR = "#f59e0b";
+var TAG26 = "recovery", RECOVERED_LABEL = "agent-recovered", RECOVERED_LABEL_COLOR = "#f59e0b";
 var init_recovery = __esm(() => {
   init_board_helpers();
   init_log();
@@ -5529,7 +6088,7 @@ class Reconciler {
       clearInterval(this.timer);
       this.timer = null;
     }
-    log.info(TAG26, "Heartbeat stopped");
+    log.info(TAG27, "Heartbeat stopped");
   }
   async recoverStaleRuns() {
     if (!this.stateStore || !this.agentConfig)
@@ -5546,7 +6105,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(TAG26, `zombie run ${run.runId} (#${run.cardShortId}): ${reason} — recovering`);
+      log.warn(TAG27, `zombie run ${run.runId} (#${run.cardShortId}): ${reason} — recovering`);
       await recoverRun(run, this.stateStore, this.client, this.agentConfig, {
         runId: run.runId,
         cardId: run.cardId,
@@ -5557,6 +6116,57 @@ class Reconciler {
       });
     }
   }
+  async recoverStrandedInProgress(cards, columns, knownCardIds) {
+    const inProgressCol = columns.find((c) => c.name.toLowerCase() === IN_PROGRESS_COLUMN.toLowerCase());
+    const pickupName = this.pickupColumns[0];
+    const pickupCol = pickupName ? columns.find((c) => c.name.toLowerCase() === pickupName.toLowerCase()) : undefined;
+    if (!inProgressCol || !pickupCol)
+      return;
+    const graceMs = this.agentConfig?.timing.staleHeartbeatMs ?? 120000;
+    const now = Date.now();
+    const activeCardIds = new Set((this.stateStore?.getActiveRuns() ?? []).map((r) => r.cardId));
+    for (const card of cards) {
+      if (card.assigned_agent_id !== this.agentId || card.archived_at || card.column_id !== inProgressCol.id || knownCardIds.has(card.id) || activeCardIds.has(card.id)) {
+        continue;
+      }
+      const stalledAt = Date.parse(card.updated_at ?? "");
+      if (!Number.isFinite(stalledAt) || now - stalledAt < graceMs)
+        continue;
+      log.warn(TAG27, `#${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(TAG27, `stranded requeue failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+  async releaseStalledApprovals(cards, columns, knownCardIds) {
+    const planning = this.agentConfig?.planning;
+    if (!planning?.enabled || planning.mode !== "gated" || planning.approvalTtlHours <= 0) {
+      return;
+    }
+    const parkCol = columns.find((c) => c.name.toLowerCase() === planning.awaitingApprovalColumn.toLowerCase());
+    const pickupName = this.pickupColumns[0];
+    const pickupCol = pickupName ? columns.find((c) => c.name.toLowerCase() === pickupName.toLowerCase()) : undefined;
+    if (!parkCol || !pickupCol)
+      return;
+    const ttlMs = planning.approvalTtlHours * 3600000;
+    const now = Date.now();
+    for (const card of cards) {
+      if (card.assigned_agent_id !== this.agentId || card.archived_at || card.column_id !== parkCol.id || !card.plan_id || knownCardIds.has(card.id)) {
+        continue;
+      }
+      const parkedAt = Date.parse(card.updated_at ?? "");
+      if (!Number.isFinite(parkedAt) || now - parkedAt < ttlMs)
+        continue;
+      log.warn(TAG27, `#${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(TAG27, `auto-release failed for #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
   async tick() {
     this.lastTickAt = Date.now();
     try {
@@ -5582,37 +6192,39 @@ class Reconciler {
           const subtasks = card.subtasks ?? [];
           const mode = reviewColumnIds.has(card.column_id) ? "review" : "implement";
           if (mode === "review" && this.approvedLabel && hasLabel(cardLabels, this.approvedLabel)) {
-            log.debug(TAG26, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
+            log.debug(TAG27, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
             continue;
           }
           if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
-            log.debug(TAG26, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
+            log.debug(TAG27, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
             continue;
           }
           if (mode === "review" && !extractBranchFromDescription(card.description)) {
-            log.debug(TAG26, `Skipping #${card.short_id} — no branch reference (not qualified for auto-review)`);
+            log.debug(TAG27, `Skipping #${card.short_id} — no branch reference (not qualified for auto-review)`);
             continue;
           }
-          log.info(TAG26, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
+          log.info(TAG27, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
           await this.pool.enqueue(card, column, cardLabels, subtasks, mode);
         }
       }
       if (this.stateStore && this.agentConfig) {
         await this.recoverStaleRuns();
       }
+      await this.recoverStrandedInProgress(cards, columns, knownCardIds);
       for (const knownId of knownCardIds) {
         if (!allAgentCardIds.has(knownId)) {
-          log.info(TAG26, `Missed unassign: ${knownId} — removing`);
+          log.info(TAG27, `Missed unassign: ${knownId} — removing`);
           await this.pool.removeCard(knownId);
         }
       }
-      log.debug(TAG26, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
+      await this.releaseStalledApprovals(cards, columns, knownCardIds);
+      log.debug(TAG27, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
     } catch (err) {
-      log.error(TAG26, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG27, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
     }
   }
 }
-var TAG26 = "reconcile";
+var TAG27 = "reconcile";
 var init_reconcile = __esm(() => {
   init_board_helpers();
   init_log();
@@ -5633,6 +6245,7 @@ function prettyBanner(config, version) {
   const checks = [];
   let projectName;
   let gitProvider;
+  let httpPort;
   let failed = false;
   let rendered = false;
   return {
@@ -5642,11 +6255,14 @@ function prettyBanner(config, version) {
     setGitProvider(provider) {
       gitProvider = provider;
     },
+    setHttpPort(port) {
+      httpPort = port;
+    },
     check(message) {
       checks.push({ kind: "ok", message });
     },
     warn(message) {
-      log.warn(TAG27, message);
+      log.warn(TAG28, message);
       checks.push({ kind: "warn", message: message.split(`
 `, 1)[0] });
     },
@@ -5662,6 +6278,7 @@ function prettyBanner(config, version) {
         config,
         projectName,
         gitProvider,
+        httpPort,
         checks,
         readyMessage: message
       });
@@ -5670,22 +6287,25 @@ function prettyBanner(config, version) {
   };
 }
 function jsonBanner(config, version) {
-  log.info(TAG27, `Harmony Agent Daemon v${version} starting...`);
-  log.info(TAG27, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Model: ${config.agent.claude.model} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
+  log.info(TAG28, `Harmony Agent Daemon v${version} starting...`);
+  log.info(TAG28, `Project: ${config.projectId} | Pool: ${config.agent.poolSize} | Model: ${config.agent.claude.model} | Pickup: ${config.agent.pickupColumns.join(", ")}`);
   if (config.agent.review.enabled) {
-    log.info(TAG27, `Review: enabled | Columns: ${config.agent.review.pickupColumns.join(", ")} | → ${config.agent.review.moveToColumn} / ${config.agent.review.failColumn}`);
+    log.info(TAG28, `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(TAG27, `Git provider: ${provider}`);
+      log.info(TAG28, `Git provider: ${provider}`);
+    },
+    setHttpPort(port) {
+      log.info(TAG28, `HTTP server on port ${port}`);
     },
     check(message) {
-      log.info(TAG27, message);
+      log.info(TAG28, message);
     },
     warn(message) {
-      log.warn(TAG27, message);
+      log.warn(TAG28, message);
     },
     fail() {
       failed = true;
@@ -5693,17 +6313,25 @@ function jsonBanner(config, version) {
     async ready(message) {
       if (failed)
         return;
-      log.info(TAG27, message);
+      log.info(TAG28, message);
     }
   };
 }
 function renderPretty(input) {
-  const { version, config, projectName, gitProvider, checks, readyMessage } = input;
+  const {
+    version,
+    config,
+    projectName,
+    gitProvider,
+    httpPort,
+    checks,
+    readyMessage
+  } = input;
   const lines = [];
   lines.push("");
   lines.push(titleRule(`Harmony Agent Daemon v${version}`));
   lines.push("");
-  for (const row of configRows(config, projectName, gitProvider)) {
+  for (const row of configRows(config, projectName, gitProvider, httpPort)) {
     lines.push(`  ${dim(row.label.padEnd(9))} ${row.value}`);
   }
   lines.push("");
@@ -5717,7 +6345,7 @@ function renderPretty(input) {
   return lines.join(`
 `);
 }
-function configRows(config, projectName, gitProvider) {
+function configRows(config, projectName, gitProvider, httpPort) {
   const rows = [];
   const projectLabel = projectName ? `${projectName} (${shortenId(config.projectId)})` : shortenId(config.projectId);
   rows.push({ label: "Project", value: projectLabel });
@@ -5733,7 +6361,7 @@ function configRows(config, projectName, gitProvider) {
   if (gitProvider)
     tail.push(gitProvider);
   if (config.agent.http.enabled) {
-    tail.push(`HTTP http://${config.agent.http.bindAddr}:${config.agent.http.port}`);
+    tail.push(`HTTP http://${config.agent.http.bindAddr}:${httpPort ?? config.agent.http.port}`);
   }
   if (tail.length > 0) {
     rows.push({ label: "Git", value: tail.join("  ·  ") });
@@ -5760,7 +6388,7 @@ function cyan(s) {
 function yellow(s) {
   return `${ANSI.yellow}${s}${ANSI.reset}`;
 }
-var TAG27 = "daemon", RULE_WIDTH = 70, ANSI;
+var TAG28 = "daemon", RULE_WIDTH = 70, ANSI;
 var init_startup_banner = __esm(() => {
   init_log();
   ANSI = {
@@ -5907,18 +6535,18 @@ class Watcher {
   }
   async start() {
     if (!isPretty()) {
-      log.info(TAG28, "Connecting to Supabase realtime (broadcast)...");
+      log.info(TAG29, "Connecting to Supabase realtime (broadcast)...");
     }
     this.supabase = createClient(this.credentials.supabaseUrl, this.credentials.supabaseAnonKey);
     const presenceChannel = this.supabase.channel(`board-presence-${this.projectId}`);
     const channel = this.supabase.channel(`board-${this.projectId}`).on("broadcast", { event: "card_update" }, (msg) => {
-      log.debug(TAG28, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
+      log.debug(TAG29, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
       this.onCardBroadcast({
         event: "card_update",
         payload: msg.payload ?? {}
       });
     }).on("broadcast", { event: "card_created" }, (msg) => {
-      log.debug(TAG28, `Broadcast: card_created ${JSON.stringify(msg.payload)}`);
+      log.debug(TAG29, `Broadcast: card_created ${JSON.stringify(msg.payload)}`);
       this.onCardBroadcast({
         event: "card_created",
         payload: msg.payload ?? {}
@@ -5928,29 +6556,29 @@ class Watcher {
       const cardId = payload.card_id;
       const command = payload.command;
       if (cardId && command) {
-        log.info(TAG28, `Broadcast: agent_command ${command} for ${cardId}`);
+        log.info(TAG29, `Broadcast: agent_command ${command} for ${cardId}`);
         this.onAgentCommand?.({ cardId, command });
       }
     }).subscribe((status) => {
       if (status === "SUBSCRIBED") {
         this.connected = true;
         if (!isPretty() || !this.suppressStartupLogs) {
-          log.info(TAG28, "Broadcast subscription active");
+          log.info(TAG29, "Broadcast subscription active");
         }
         this.maybeResolveReady();
       } else if (status === "CHANNEL_ERROR") {
         this.connected = false;
-        log.error(TAG28, "Broadcast channel error — will rely on reconciliation");
+        log.error(TAG29, "Broadcast channel error — will rely on reconciliation");
       } else if (status === "TIMED_OUT") {
         this.connected = false;
-        log.warn(TAG28, "Broadcast subscription timed out — retrying...");
+        log.warn(TAG29, "Broadcast subscription timed out — retrying...");
       } else if (status === "CLOSED") {
         this.connected = false;
       }
     });
     this.channel = channel;
     presenceChannel.on("presence", { event: "sync" }, () => {
-      log.debug(TAG28, "Presence sync");
+      log.debug(TAG29, "Presence sync");
     }).subscribe(async (status) => {
       if (status === "SUBSCRIBED") {
         await presenceChannel.track({
@@ -5963,7 +6591,7 @@ class Watcher {
           agentName: this.identity.agentName
         });
         if (!isPretty() || !this.suppressStartupLogs) {
-          log.info(TAG28, "Presence tracked on board-presence channel");
+          log.info(TAG29, "Presence tracked on board-presence channel");
         }
         this.presenceTracked = true;
         this.maybeResolveReady();
@@ -5985,10 +6613,10 @@ class Watcher {
       this.supabase = null;
     }
     this.connected = false;
-    log.info(TAG28, "Broadcast subscription stopped");
+    log.info(TAG29, "Broadcast subscription stopped");
   }
 }
-var TAG28 = "watcher";
+var TAG29 = "watcher";
 var init_watcher = __esm(() => {
   init_log();
 });
@@ -6063,10 +6691,10 @@ function runWorktreeGc(basePath, store, opts = {}) {
     });
   } catch {}
   if (result.removed.length > 0) {
-    log.info(TAG29, `GC removed ${result.removed.length} orphan worktree(s): ${result.removed.map((p) => p.split("/").pop()).join(", ")}`);
+    log.info(TAG30, `GC removed ${result.removed.length} orphan worktree(s): ${result.removed.map((p) => p.split("/").pop()).join(", ")}`);
   }
   if (result.errors.length > 0) {
-    log.warn(TAG29, `GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
+    log.warn(TAG30, `GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
   }
   return result;
 }
@@ -6143,10 +6771,10 @@ function pruneFailedRemoteBranches(opts) {
     }
   }
   if (result.removed.length > 0) {
-    log.info(TAG29, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
+    log.info(TAG30, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
   }
   if (result.errors.length > 0) {
-    log.warn(TAG29, `Remote branch GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.ref}: ${e.error}`).join("; ")}`);
+    log.warn(TAG30, `Remote branch GC had ${result.errors.length} error(s): ${result.errors.map((e) => `${e.ref}: ${e.error}`).join("; ")}`);
   }
   return result;
 }
@@ -6177,13 +6805,13 @@ class WorktreeGc {
     try {
       runWorktreeGc(this.basePath, this.store);
     } catch (err) {
-      log.warn(TAG29, `GC tick failed: ${err instanceof Error ? err.message : err}`);
+      log.warn(TAG30, `GC tick failed: ${err instanceof Error ? err.message : err}`);
     }
     if (this.remoteOpts) {
       try {
         pruneFailedRemoteBranches(this.remoteOpts);
       } catch (err) {
-        log.warn(TAG29, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
+        log.warn(TAG30, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
       }
     }
   }
@@ -6197,7 +6825,7 @@ function getRepoRoot2() {
     return null;
   }
 }
-var TAG29 = "worktree-gc";
+var TAG30 = "worktree-gc";
 var init_worktree_gc = __esm(() => {
   init_log();
   init_worktree();
@@ -6279,7 +6907,7 @@ async function main() {
   } catch (err) {
     if (err instanceof ConfigValidationError) {
       banner.fail();
-      log.error(TAG30, err.message);
+      log.error(TAG31, err.message);
       process.exit(1);
     }
     throw err;
@@ -6388,25 +7016,28 @@ async function main() {
     if (shuttingDown)
       return;
     shuttingDown = true;
-    log.info(TAG30, `Received ${signal}, shutting down gracefully...`);
+    log.info(TAG31, `Received ${signal}, shutting down gracefully...`);
     reconciler.stop();
     mergeMonitor?.stop();
     worktreeGc.stop();
-    await httpServer?.stop();
+    if (httpServer) {
+      clearDaemonPort(config.projectId, process.pid);
+      await httpServer.stop();
+    }
     await watcher.stop();
     await pool.shutdown();
-    log.info(TAG30, "Daemon stopped.");
+    log.info(TAG31, "Daemon stopped.");
     process.exit(exitCode);
   };
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("uncaughtException", (err) => {
-    log.error(TAG30, `Uncaught exception: ${err.message}`);
+    log.error(TAG31, `Uncaught exception: ${err.message}`);
     exitCode = 1;
     shutdown("uncaughtException");
   });
   process.on("unhandledRejection", (reason) => {
-    log.error(TAG30, `Unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
+    log.error(TAG31, `Unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
     exitCode = 1;
     shutdown("unhandledRejection");
   });
@@ -6416,7 +7047,13 @@ async function main() {
   worktreeGc.start();
   if (httpServer) {
     try {
-      await httpServer.start();
+      const boundPort = await httpServer.start();
+      recordDaemonPort(config.projectId, {
+        port: boundPort,
+        pid: process.pid,
+        bindAddr: config.agent.http.bindAddr
+      });
+      banner.setHttpPort(boundPort);
     } catch (err) {
       banner.warn(`HTTP server failed to bind: ${err instanceof Error ? err.message : err}`);
     }
@@ -6453,34 +7090,34 @@ async function handleBroadcast(event, client, pool, config, agentId) {
   if (assignedAgentId === undefined)
     return;
   if (assignedAgentId === agentId) {
-    log.info(TAG30, `Broadcast: card ${cardId} assigned to agent`);
+    log.info(TAG31, `Broadcast: card ${cardId} assigned to agent`);
     try {
       await tryEnqueueCard(cardId, client, pool, config, agentId);
     } catch (err) {
-      log.error(TAG30, `Failed to process assignment: ${err instanceof Error ? err.message : err}`);
+      log.error(TAG31, `Failed to process assignment: ${err instanceof Error ? err.message : err}`);
     }
   } else if (pool.isCardKnown(cardId)) {
-    log.info(TAG30, `Broadcast: card ${cardId} unassigned from agent`);
+    log.info(TAG31, `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(TAG30, `Card ${cardId} no longer assigned to agent — skipping`);
+    log.debug(TAG31, `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(TAG30, `Column not found for card ${cardId}`);
+    log.warn(TAG31, `Column not found for card ${cardId}`);
     return;
   }
   const isPickupColumn = config.agent.pickupColumns.some((name) => name.toLowerCase() === column.name.toLowerCase());
   const isReviewColumn = config.agent.review.enabled && config.agent.review.pickupColumns.some((name) => name.toLowerCase() === column.name.toLowerCase());
   if (!isPickupColumn && !isReviewColumn) {
-    log.info(TAG30, `Card #${card.short_id} is in "${column.name}", not a pickup/review column — skipping`);
+    log.info(TAG31, `Card #${card.short_id} is in "${column.name}", not a pickup/review column — skipping`);
     return;
   }
   const mode = isReviewColumn ? "review" : "implement";
@@ -6488,16 +7125,16 @@ async function tryEnqueueCard(cardId, client, pool, config, agentId) {
   const cardLabels = resolveCardLabels(card, labelMap);
   const subtasks = card.subtasks ?? [];
   if (mode === "review" && config.agent.review.approvedLabel && hasLabel(cardLabels, config.agent.review.approvedLabel)) {
-    log.debug(TAG30, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
+    log.debug(TAG31, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
     return;
   }
   if (mode === "review" && !extractBranchFromDescription(card.description)) {
-    log.info(TAG30, `Card #${card.short_id} has no branch reference — skipping auto-review`);
+    log.info(TAG31, `Card #${card.short_id} has no branch reference — skipping auto-review`);
     return;
   }
   await pool.enqueue(card, column, cardLabels, subtasks, mode);
 }
-var TAG30 = "daemon", PKG_VERSION;
+var TAG31 = "daemon", PKG_VERSION;
 var init_src = __esm(() => {
   init_board_helpers();
   init_config();
@@ -6507,6 +7144,7 @@ var init_src = __esm(() => {
   init_log();
   init_merge_monitor();
   init_pool();
+  init_port_registry();
   init_reconcile();
   init_recovery();
   init_review_worktree();
@@ -6546,8 +7184,12 @@ async function runDaemon() {
 }
 async function httpCall(path, init) {
   const { loadDaemonConfig: loadDaemonConfig2 } = await Promise.resolve().then(() => (init_config(), exports_config));
+  const { lookupDaemonPort: lookupDaemonPort2 } = await Promise.resolve().then(() => (init_port_registry(), exports_port_registry));
   const cfg = loadDaemonConfig2();
-  const url = `http://${cfg.agent.http.bindAddr}:${cfg.agent.http.port}${path}`;
+  const recorded = lookupDaemonPort2(cfg.projectId);
+  const bindAddr = recorded?.bindAddr ?? cfg.agent.http.bindAddr;
+  const port = recorded?.port ?? cfg.agent.http.port;
+  const url = `http://${bindAddr}:${port}${path}`;
   return fetch(url, init);
 }
 function printStatus(body) {