@gethmy/agent 1.5.0 → 1.6.0

package/dist/budget.d.ts

@@ -38,8 +38,10 @@ export declare class BudgetGuard {
      */
     isTerminal(reason: GuardReason): boolean;
     /**
-     * Apply the DLQ label to a card and post a comment explaining why.
-     * Safe to call repeatedly — labels are idempotent.
+     * Apply the DLQ label to a card, persist the reason, and append a
+     * post-mortem block to the card description listing the last 3 failure
+     * summaries. Safe to call repeatedly — labels are idempotent and the
+     * description block is delimited so reruns replace rather than stack.
      */
     markDlq(client: HarmonyApiClient, card: Card, reason: GuardReason, detail: string): Promise<void>;
 }

package/dist/budget.js

@@ -71,8 +71,10 @@ export class BudgetGuard {
             reason === "card_cost_cap");
     }
     /**
-     * Apply the DLQ label to a card and post a comment explaining why.
-     * Safe to call repeatedly — labels are idempotent.
+     * Apply the DLQ label to a card, persist the reason, and append a
+     * post-mortem block to the card description listing the last 3 failure
+     * summaries. Safe to call repeatedly — labels are idempotent and the
+     * description block is delimited so reruns replace rather than stack.
      */
     async markDlq(client, card, reason, detail) {
         await this.store.markDlq(card.id, `${reason}: ${detail}`);
@@ -86,9 +88,46 @@ export class BudgetGuard {
         catch (err) {
             log.warn(TAG, `failed to add dlq label to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
         }
+        try {
+            const recent = this.store.getRecentFailures(card.id, 3);
+            const block = buildDlqDescriptionBlock(reason, detail, recent);
+            const existing = card.description ?? "";
+            const stripped = stripDlqBlock(existing);
+            await client.updateCard(card.id, {
+                description: `${stripped}${stripped ? "\n\n" : ""}${block}`,
+            });
+        }
+        catch (err) {
+            log.warn(TAG, `failed to post DLQ summary to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+        }
         log.warn(TAG, `#${card.short_id} DLQ'd — ${reason}: ${detail}`);
     }
 }
+const DLQ_MARKER = "---\n**Agent DLQ**";
+function buildDlqDescriptionBlock(reason, detail, failures) {
+    const lines = [DLQ_MARKER, `Cap hit: ${reason} — ${detail}`];
+    if (failures.length > 0) {
+        lines.push("", "Recent failures:");
+        for (const f of failures) {
+            const when = new Date(f.ts).toISOString().replace("T", " ").slice(0, 16);
+            const tag = f.reason ? ` [${f.reason}]` : "";
+            const branch = f.recoveryBranch
+                ? `\n  recover: \`git fetch && git checkout ${f.recoveryBranch}\``
+                : "";
+            lines.push(`- ${when} UTC${tag} — ${f.summary}${branch}`);
+        }
+    }
+    else {
+        lines.push("", "_No prior failure summaries recorded._");
+    }
+    return lines.join("\n");
+}
+function stripDlqBlock(description) {
+    const idx = description.indexOf(DLQ_MARKER);
+    if (idx < 0)
+        return description.trimEnd();
+    return description.slice(0, idx).trimEnd();
+}
 function formatCents(cents) {
     return `$${(cents / 100).toFixed(2)}`;
 }

package/dist/completion.d.ts

@@ -1,5 +1,6 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card } from "@harmony/shared";
+import type { StateStore } from "./state-store.js";
 import type { CostUpdate } from "./stream-parser.js";
 import { type AgentConfig } from "./types.js";
 export interface SessionStats {
@@ -28,4 +29,4 @@ export declare function buildTokenPayload(stats?: SessionStats | null): {
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number, sessionStats?: SessionStats, workspaceId?: string, agentSessionId?: string | null): Promise<void>;
+export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number, sessionStats?: SessionStats, workspaceId?: string, agentSessionId?: string | null, stateStore?: StateStore): Promise<void>;

package/dist/completion.js

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { moveCardToColumn } from "./board-helpers.js";
 import { writeEpisode } from "./episode-writer.js";
-import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
+import { createPullRequest, detectGitProvider, getBranchWebUrl, pushBranch, } from "./git-pr.js";
 import { log } from "./log.js";
 import { AGENT_NAME, agentIdentifier } from "./types.js";
 import { attemptAutoFix, reportFindings, runVerification, } from "./verification.js";
@@ -29,7 +29,7 @@ export function buildTokenPayload(stats) {
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0, sessionStats, workspaceId, agentSessionId) {
+export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0, sessionStats, workspaceId, agentSessionId, stateStore) {
     // Hoisted so the episode write hook can read final verification state.
     let verificationResult = {
         passed: true,
@@ -49,7 +49,22 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
         cleanupWorktree(worktreePath, branchName);
         return;
     }
-    // 1. Verification gate
+    // 1. Push branch FIRST so commits are durable on origin regardless of
+    // verification outcome. A failed verify (below) then preserves the work
+    // under `agent-attempts/*` for `failedAttemptRetentionDays`. Without this
+    // ordering, verify failures used to orphan commits in a deleted worktree —
+    // recoverable only via `git reflog`.
+    log.info(TAG, `Pushing branch ${branchName} (pre-verify)...`);
+    try {
+        pushBranch(branchName, worktreePath);
+    }
+    catch (err) {
+        // Push failure shouldn't prevent verification from running, but the
+        // safety guarantee is gone — surface it loudly so the operator notices.
+        log.error(TAG, `pre-verify push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+    }
+    const recoveryUrl = getBranchWebUrl(branchName, worktreePath);
+    // 2. Verification gate
     if (config.verification.enabled) {
         await client.updateAgentProgress(card.id, {
             agentIdentifier: agentIdentifier(workerId),
@@ -59,6 +74,7 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
             progressPercent: 80,
         });
         let result = await runVerification(worktreePath, config, workerId);
+        let autoFixAttempts = 0;
         if (!result.passed && config.verification.autoFix) {
             for (let attempt = 0; attempt < config.verification.maxFixAttempts; attempt++) {
                 log.info(TAG, `Auto-fix attempt ${attempt + 1}/${config.verification.maxFixAttempts}`);
@@ -72,8 +88,16 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
                 const allErrors = [...result.buildErrors, ...result.lintWarnings];
                 await attemptAutoFix(worktreePath, config, allErrors);
                 result = await runVerification(worktreePath, config, workerId);
+                autoFixAttempts = attempt + 1;
                 if (result.passed) {
                     log.info(TAG, `Auto-fix succeeded on attempt ${attempt + 1}`);
+                    // Push again so the auto-fix commit is also durable on origin.
+                    try {
+                        pushBranch(branchName, worktreePath);
+                    }
+                    catch (err) {
+                        log.warn(TAG, `post-fix push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+                    }
                     break;
                 }
             }
@@ -81,23 +105,44 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
         verificationResult = result;
         if (!result.passed) {
             log.warn(TAG, `Verification failed for #${card.short_id} — reporting findings`);
-            await reportFindings(client, card.id, result);
+            // Push the latest tip (including any auto-fix attempts) so the
+            // failed branch on origin reflects what verify saw.
+            try {
+                pushBranch(branchName, worktreePath);
+            }
+            catch (err) {
+                log.warn(TAG, `post-fail push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+            }
+            const failureSummary = buildVerificationFailureSummary(result, autoFixAttempts);
+            try {
+                await stateStore?.recordFailureSummary(card.id, {
+                    summary: failureSummary,
+                    reason: "verification",
+                    recoveryBranch: branchName,
+                });
+            }
+            catch (err) {
+                log.debug(TAG, `recordFailureSummary failed: ${err instanceof Error ? err.message : err}`);
+            }
+            await reportFindings(client, card.id, result, {
+                branchName,
+                branchUrl: recoveryUrl,
+            });
             await moveCardToColumn(client, card, config.verification.failColumn);
             await client.endAgentSession(card.id, {
-                status: "paused",
+                status: "failed",
+                failureReason: "verification",
+                failureSummary,
+                recoveryBranch: branchName,
                 ...buildTokenPayload(sessionStats),
             });
-            // Episode write: paused/orphaned runs skip silently (plan D8). Failure
-            // here would only fire on a status===completed path, which we don't
-            // hit when verification fails.
+            // Local-only cleanup. The remote ref under `agent-attempts/*` stays
+            // up; the GC sweep (worktree-gc.ts) prunes it after retention.
             cleanupWorktree(worktreePath, branchName);
             return;
         }
         log.info(TAG, `Verification passed for #${card.short_id}`);
     }
-    // 2. Push branch (force-push on rework if remote branch already exists)
-    log.info(TAG, `Pushing branch ${branchName}...`);
-    pushBranch(branchName, worktreePath);
     // 3. Create PR
     let prUrl = null;
     if (config.completion.createPR) {
@@ -144,6 +189,21 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
     cleanupWorktree(worktreePath, branchName);
     log.info(TAG, `Completion done for #${card.short_id}${prUrl ? ` — PR: ${prUrl}` : ""}`);
 }
+function buildVerificationFailureSummary(result, autoFixAttempts) {
+    const counts = [];
+    if (result.buildErrors.length > 0) {
+        counts.push(`${result.buildErrors.length} build error(s)`);
+    }
+    if (result.lintWarnings.length > 0) {
+        counts.push(`${result.lintWarnings.length} lint issue(s)`);
+    }
+    if (result.reviewFindings.length > 0) {
+        counts.push(`${result.reviewFindings.length} review finding(s)`);
+    }
+    const head = counts.length > 0 ? counts.join(", ") : "verification failed";
+    const tail = autoFixAttempts > 0 ? ` after ${autoFixAttempts} auto-fix attempt(s)` : "";
+    return `${head}${tail}`;
+}
 function checkHasCommits(worktreePath, baseBranch) {
     try {
         const count = execFileSync("git", ["rev-list", "--count", `origin/${baseBranch}..HEAD`], { cwd: worktreePath, encoding: "utf-8" }).trim();

package/dist/git-pr.d.ts

@@ -19,6 +19,19 @@ export declare function checkPrMergeStatus(prUrl: string, cwd: string, provider:
 export declare function extractPrUrl(description: string | null): string | null;
 export declare function remoteBranchExists(branchName: string, cwd: string): boolean;
 export declare function pushBranch(branchName: string, cwd: string): void;
+/**
+ * Push the current branch's tip to `newRef` on origin and delete `oldRef`.
+ * Used when an approved attempt graduates from `agent-attempts/*` to
+ * `agent/*` — keeps the commits durable across the rename and avoids any
+ * window where the work is unreachable on origin.
+ */
+export declare function renameRemoteBranch(oldRef: string, newRef: string, cwd: string): void;
+/**
+ * Best-effort public branch URL for the recovery button on a failed session.
+ * Returns null when we can't infer a tree URL — the daemon falls back to a
+ * plain `git fetch && git checkout <ref>` instruction in that case.
+ */
+export declare function getBranchWebUrl(branchName: string, cwd: string): string | null;
 export declare function buildPrBody(card: Card, commitLog: string): string;
 export declare function createPullRequest(card: Card, branchName: string, worktreePath: string, config: AgentConfig, provider: GitProvider): string | null;
 export declare function findExistingPr(branchName: string, worktreePath: string, provider: GitProvider): string | null;

package/dist/git-pr.js

@@ -167,6 +167,79 @@ export function pushBranch(branchName, cwd) {
         });
     }
 }
+/**
+ * Push the current branch's tip to `newRef` on origin and delete `oldRef`.
+ * Used when an approved attempt graduates from `agent-attempts/*` to
+ * `agent/*` — keeps the commits durable across the rename and avoids any
+ * window where the work is unreachable on origin.
+ */
+export function renameRemoteBranch(oldRef, newRef, cwd) {
+    if (oldRef === newRef)
+        return;
+    let sha;
+    try {
+        sha = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch (err) {
+        throw new Error(`renameRemoteBranch: could not resolve HEAD: ${err instanceof Error ? err.message : err}`);
+    }
+    log.info(TAG, `Renaming remote ${oldRef} → ${newRef}`);
+    execFileSync("git", ["push", "origin", `${sha}:refs/heads/${newRef}`, "--force-with-lease"], { cwd, stdio: "pipe" });
+    try {
+        execFileSync("git", ["push", "origin", `:refs/heads/${oldRef}`], {
+            cwd,
+            stdio: "pipe",
+        });
+    }
+    catch (err) {
+        log.warn(TAG, `renameRemoteBranch: could not delete old ref ${oldRef}: ${err instanceof Error ? err.message : err}`);
+    }
+    try {
+        execFileSync("git", ["branch", "-m", oldRef, newRef], {
+            cwd,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Worktree may not have the old branch checked out — non-fatal.
+    }
+}
+/**
+ * Best-effort public branch URL for the recovery button on a failed session.
+ * Returns null when we can't infer a tree URL — the daemon falls back to a
+ * plain `git fetch && git checkout <ref>` instruction in that case.
+ */
+export function getBranchWebUrl(branchName, cwd) {
+    try {
+        const remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd,
+            encoding: "utf-8",
+        }).trim();
+        const encoded = branchName.split("/").map(encodeURIComponent).join("/");
+        if (/github\.com[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+            const m = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+            if (m)
+                return `https://github.com/${m[1]}/${m[2]}/tree/${encoded}`;
+        }
+        if (/gitlab\.com[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+            const m = remoteUrl.match(/gitlab\.com[:/](.+?)(?:\.git)?$/);
+            if (m)
+                return `https://gitlab.com/${m[1]}/-/tree/${encoded}`;
+        }
+        if (/bitbucket\.org[:/]([^/]+)\/([^/.]+)/.test(remoteUrl)) {
+            const m = remoteUrl.match(/bitbucket\.org[:/](.+?)(?:\.git)?$/);
+            if (m)
+                return `https://bitbucket.org/${m[1]}/branch/${encoded}`;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 // ============ PR CREATION (PROVIDER-AWARE) ============
 export function buildPrBody(card, commitLog) {
     return [

package/dist/index.js

@@ -146,7 +146,12 @@ export async function main() {
     }
     // Periodic worktree GC — removes orphan worktrees older than 1h that
     // no active run claims. Covers crashes that left worktrees behind.
-    const worktreeGc = new WorktreeGc(config.agent.worktree.basePath, stateStore, config.agent.timing.worktreeGcIntervalMs);
+    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,
+        }
+        : undefined);
     // Local status/control HTTP server.
     const startedAt = Date.now();
     const httpServer = config.agent.http.enabled

package/dist/pool.d.ts

@@ -2,7 +2,7 @@ import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card, Column, Label, Subtask } from "@harmony/shared";
 import { PriorityQueue } from "./queue.js";
 import type { StateStore } from "./state-store.js";
-import type { AgentConfig, WorkMode } from "./types.js";
+import { type AgentConfig, type WorkMode } from "./types.js";
 export declare class Pool {
     private client;
     private implWorkers;
@@ -19,6 +19,11 @@ export declare class Pool {
      * and manual API calls all go through the same gate.
      */
     enqueue(card: Card, column: Column, labels: Label[], subtasks: Subtask[], mode?: WorkMode): Promise<void>;
+    /**
+     * Best-effort waiting-state emit. Failures are swallowed because we don't
+     * want a board-API hiccup to drop the queue/budget event in pool.ts.
+     */
+    private emitWaiting;
     /**
      * Remove a card from any queue or cancel an active worker.
      */

package/dist/pool.js

@@ -2,6 +2,7 @@ import { BudgetGuard } from "./budget.js";
 import { log } from "./log.js";
 import { PriorityQueue } from "./queue.js";
 import { ReviewWorker } from "./review-worker.js";
+import { AGENT_NAME, agentIdentifier, } from "./types.js";
 import { Worker } from "./worker.js";
 const TAG = "pool";
 export class Pool {
@@ -58,6 +59,11 @@ export class Pool {
                     if (this.budget.isTerminal(decision.reason)) {
                         await this.budget.markDlq(this.client, card, decision.reason, decision.detail);
                     }
+                    else if (decision.reason === "daily_budget") {
+                        // Soft pause — surface as `waiting` so the board signals that
+                        // the daemon will pick this card up after the budget resets.
+                        await this.emitWaiting(card.id, `Daily budget reached — waiting for reset (${decision.detail})`);
+                    }
                 }
                 else {
                     log.debug(TAG, `#${card.short_id} in DLQ: ${decision.detail}`);
@@ -70,7 +76,34 @@ export class Pool {
         // Store card data for when it gets dispatched
         this.cardDataCache.set(card.id, { card, column, labels, subtasks, mode });
         const workers = mode === "review" ? this.reviewWorkers : this.implWorkers;
-        this.tryDispatchFor(workers, queue, mode);
+        const dispatched = this.tryDispatchFor(workers, queue, mode);
+        if (!dispatched) {
+            // No idle worker — the card will wait in the queue. Surface the
+            // queue position so the board ribbon shows the user something is
+            // happening even though no worker has the card yet.
+            const position = queue.cardIds().indexOf(card.id) + 1;
+            const total = queue.length;
+            await this.emitWaiting(card.id, position > 0
+                ? `Queued (${position}/${total}) — waiting for ${mode} worker`
+                : `Queued — waiting for ${mode} worker`);
+        }
+    }
+    /**
+     * Best-effort waiting-state emit. Failures are swallowed because we don't
+     * want a board-API hiccup to drop the queue/budget event in pool.ts.
+     */
+    async emitWaiting(cardId, currentTask) {
+        try {
+            await this.client.updateAgentProgress(cardId, {
+                agentIdentifier: agentIdentifier(0),
+                agentName: AGENT_NAME,
+                status: "waiting",
+                currentTask,
+            });
+        }
+        catch (err) {
+            log.debug(TAG, `waiting emit failed for ${cardId}: ${err instanceof Error ? err.message : err}`);
+        }
     }
     /**
      * Remove a card from any queue or cancel an active worker.
@@ -203,18 +236,19 @@ export class Pool {
         const idle = workers.find((w) => w.isIdle);
         if (!idle) {
             log.debug(TAG, `No idle ${label} workers (queue: ${queue.length})`);
-            return;
+            return false;
         }
         const next = queue.dequeue();
         if (!next)
-            return;
+            return false;
         const data = this.cardDataCache.get(next.cardId);
         if (!data) {
             log.warn(TAG, `No cached data for card ${next.cardId}, skipping`);
-            return;
+            return false;
         }
         this.cardDataCache.delete(next.cardId);
         log.info(TAG, `Dispatching #${next.shortId} to ${label} worker ${idle.id}`);
         idle.run(data.card, data.column, data.labels, data.subtasks);
+        return true;
     }
 }

package/dist/recovery.js

@@ -70,12 +70,18 @@ export async function recoverOrphans(store, client, config) {
 }
 export async function recoverRun(run, store, client, config, outcome) {
     // 1. End the agent session so the card stops showing the progress ring.
+    // Mark as failed (not paused) — daemon crash is an outcome, not a
+    // user-initiated pause. UI renders the destructive tint + recovery branch
+    // button if the run had pushed any commits.
     try {
         await client.endAgentSession(run.cardId, {
-            status: "paused",
+            status: "failed",
+            failureReason: "daemon_restart",
+            failureSummary: `Daemon restarted mid-${run.pipeline} (phase: ${run.phase})`,
+            recoveryBranch: run.branchName ?? undefined,
             progressPercent: run.phase === "completing" ? 95 : undefined,
         });
-        outcome.actions.push("ended agent session (paused)");
+        outcome.actions.push("ended agent session (failed: daemon_restart)");
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/review-completion.d.ts

@@ -1,6 +1,7 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card } from "@harmony/shared";
 import { type SessionStats } from "./completion.js";
+import type { StateStore } from "./state-store.js";
 import { type AgentConfig } from "./types.js";
 export interface ReviewFinding {
     severity: "critical" | "major" | "minor";
@@ -36,4 +37,4 @@ export declare function parseReviewOutput(stdout: string): ReviewResult;
  * Handles approved/rejected verdicts, creates subtasks for findings,
  * and moves the card to the appropriate column.
  */
-export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string | null, sessionStats?: SessionStats | null, runLogPath?: string | null, workspaceId?: string, agentSessionId?: string | null): Promise<void>;
+export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string | null, sessionStats?: SessionStats | null, runLogPath?: string | null, workspaceId?: string, agentSessionId?: string | null, stateStore?: StateStore): Promise<void>;

package/dist/review-completion.js

@@ -2,7 +2,7 @@ import { readFileSync, statSync } from "node:fs";
 import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
 import { buildTokenPayload } from "./completion.js";
 import { backfillReviewVerdict, findLatestImplementEpisode, writeEpisode, } from "./episode-writer.js";
-import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
+import { createPullRequest, detectGitProvider, getBranchWebUrl, pushBranch, renameRemoteBranch, } from "./git-pr.js";
 import { log } from "./log.js";
 import { NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR, } from "./types.js";
 import { cleanupWorktree } from "./worktree.js";
@@ -183,7 +183,7 @@ function stripReviewSummary(description) {
  * Handles approved/rejected verdicts, creates subtasks for findings,
  * and moves the card to the appropriate column.
  */
-export async function runReviewCompletion(client, card, result, config, worktreePath, branchName, sessionStats, runLogPath, workspaceId, agentSessionId) {
+export async function runReviewCompletion(client, card, result, config, worktreePath, branchName, sessionStats, runLogPath, workspaceId, agentSessionId, stateStore) {
     // Re-fetch card for fresh description (avoids stale data from enqueue time)
     let freshDesc;
     try {
@@ -248,12 +248,30 @@ export async function runReviewCompletion(client, card, result, config, worktree
     if (result.verdict === "approved") {
         // Ensure branch is pushed (skip in local mode — no branch to push)
         let prUrl = null;
+        let approvedBranch = branchName;
         if (branchName) {
             pushBranch(branchName, worktreePath);
+            // Graduate the branch from `agent-attempts/*` to `agent/*` so the
+            // approved PR opens on a clean ref. Renaming on origin is force-with-
+            // lease + delete-old; the old ref is the same SHA, so no work is lost.
+            const failedPrefix = config.worktree.failedBranchPrefix;
+            const approvedPrefix = config.worktree.approvedBranchPrefix;
+            if (failedPrefix &&
+                approvedPrefix &&
+                branchName.startsWith(failedPrefix)) {
+                const newRef = `${approvedPrefix}${branchName.slice(failedPrefix.length)}`;
+                try {
+                    renameRemoteBranch(branchName, newRef, worktreePath);
+                    approvedBranch = newRef;
+                }
+                catch (err) {
+                    log.warn(TAG, `Branch rename failed (continuing on ${branchName}): ${err instanceof Error ? err.message : err}`);
+                }
+            }
             // Create PR if configured
-            if (config.review.createPR) {
+            if (config.review.createPR && approvedBranch) {
                 const provider = detectGitProvider(worktreePath);
-                prUrl = createPullRequest(card, branchName, worktreePath, config, provider);
+                prUrl = createPullRequest(card, approvedBranch, worktreePath, config, provider);
             }
         }
         // Add "Ready to Merge" label
@@ -401,8 +419,29 @@ export async function runReviewCompletion(client, card, result, config, worktree
         }
         // Move back to failColumn (To Do) for re-implementation
         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;
+        const recoveryUrl = branchName
+            ? getBranchWebUrl(branchName, worktreePath)
+            : null;
+        try {
+            await stateStore?.recordFailureSummary(card.id, {
+                summary: failureSummary,
+                reason: "review",
+                recoveryBranch,
+            });
+        }
+        catch (err) {
+            log.debug(TAG, `recordFailureSummary failed: ${err instanceof Error ? err.message : err}`);
+        }
+        if (recoveryBranch) {
+            log.info(TAG, `#${card.short_id} recovery branch ${recoveryBranch}${recoveryUrl ? ` (${recoveryUrl})` : ""}`);
+        }
         await client.endAgentSession(card.id, {
-            status: "paused",
+            status: "failed",
+            failureReason: "review",
+            failureSummary,
+            recoveryBranch,
             ...buildTokenPayload(sessionStats),
         });
         log.info(TAG, `#${card.short_id} rejected (cycle ${currentCycle}/${maxCycles}) — moved to "${config.review.failColumn}"`);

package/dist/review-worker.js

@@ -191,12 +191,30 @@ export class ReviewWorker {
             if (!localMode) {
                 log.info(this.tag, `Starting dev server on port ${port}...`);
                 this.devServerProcess = spawnInGroup("bun", ["run", "dev", "--", "--port", String(port)], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+                // Surface the dev-server warmup as `waiting` so the AgentTopBar
+                // doesn't sit on a stale `working` task while the server takes
+                // 10–20 seconds to boot.
+                await this.client.updateAgentProgress(card.id, {
+                    agentIdentifier: agentIdentifier(this.id),
+                    agentName: `${AGENT_NAME} (Review)`,
+                    status: "waiting",
+                    currentTask: `Starting dev server on port ${port}…`,
+                    progressPercent: 10,
+                });
                 // Invariant I2: review only proceeds with a proven-live dev server.
                 // waitForDevServer rejects on timeout / exit; probeDevServer verifies
                 // the port actually answers HTTP.
                 await waitForDevServer(this.devServerProcess, 30_000);
                 await probeDevServer(port);
                 log.info(this.tag, `Dev server ready on port ${port}`);
+                // Restore active status now that the server is live.
+                await this.client.updateAgentProgress(card.id, {
+                    agentIdentifier: agentIdentifier(this.id),
+                    agentName: `${AGENT_NAME} (Review)`,
+                    status: "working",
+                    currentTask: "Reviewing changes",
+                    progressPercent: 15,
+                });
             }
             if (this.aborted)
                 return;
@@ -290,7 +308,7 @@ export class ReviewWorker {
                 progressPercent: 80,
             });
             // Run review completion pipeline
-            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName, sessionStats, this.lastRunLogPath, this.workspaceId, this.sessionId);
+            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName, sessionStats, this.lastRunLogPath, this.workspaceId, this.sessionId, this.stateStore);
         }
         catch (err) {
             this.state = "error";

package/dist/state-store.d.ts

@@ -18,6 +18,12 @@ export interface RunRecord {
     costCents: number;
     errorMessage?: string;
 }
+export interface FailureSummaryRecord {
+    summary: string;
+    ts: number;
+    reason?: "verification" | "review" | "daemon_restart" | "budget" | "other";
+    recoveryBranch?: string;
+}
 export interface CardRecord {
     cardId: string;
     attempts: number;
@@ -26,6 +32,7 @@ export interface CardRecord {
     dlqReason?: string;
     lastAttemptAt: number | null;
     lastOutcome: "success" | "failure" | null;
+    failureHistory?: FailureSummaryRecord[];
 }
 export declare function newRunId(): string;
 export declare function defaultStatePath(): string;
@@ -63,6 +70,15 @@ export declare class StateStore {
     getCard(cardId: string): CardRecord | null;
     incrementAttempt(cardId: string): Promise<number>;
     recordOutcome(cardId: string, outcome: "success" | "failure"): Promise<void>;
+    /**
+     * Push a failure summary onto the card's bounded history (most-recent first,
+     * capped at 5). Read back by DLQ comment formatting and the Agent History
+     * UI section to give users a post-mortem trail across attempts.
+     */
+    recordFailureSummary(cardId: string, entry: Omit<FailureSummaryRecord, "ts"> & {
+        ts?: number;
+    }): Promise<void>;
+    getRecentFailures(cardId: string, limit?: number): FailureSummaryRecord[];
     addCost(cardId: string, cents: number): Promise<void>;
     getDailyCostCents(date?: string): number;
     markDlq(cardId: string, reason: string): Promise<void>;

package/dist/state-store.js

@@ -170,6 +170,29 @@ export class StateStore {
             rec.attempts = 0;
         await this.persist();
     }
+    /**
+     * Push a failure summary onto the card's bounded history (most-recent first,
+     * capped at 5). Read back by DLQ comment formatting and the Agent History
+     * UI section to give users a post-mortem trail across attempts.
+     */
+    async recordFailureSummary(cardId, entry) {
+        const rec = this.ensureCard(cardId);
+        const next = {
+            summary: entry.summary.slice(0, 500),
+            ts: entry.ts ?? Date.now(),
+            reason: entry.reason,
+            recoveryBranch: entry.recoveryBranch,
+        };
+        const existing = rec.failureHistory ?? [];
+        rec.failureHistory = [next, ...existing].slice(0, 5);
+        await this.persist();
+    }
+    getRecentFailures(cardId, limit = 3) {
+        const rec = this.getCard(cardId);
+        if (!rec?.failureHistory)
+            return [];
+        return rec.failureHistory.slice(0, limit);
+    }
     async addCost(cardId, cents) {
         if (cents <= 0)
             return;

package/dist/types.d.ts

@@ -20,6 +20,12 @@ export interface AgentConfig {
     worktree: {
         basePath: string;
         baseBranch: string;
+        /** Remote-branch prefix while an attempt is still in-flight or failed. */
+        failedBranchPrefix: string;
+        /** Remote-branch prefix after a successful run reaches Review. */
+        approvedBranchPrefix: string;
+        /** Days to keep failed-attempt branches on origin before GC removes them. */
+        failedAttemptRetentionDays: number;
     };
     verification: {
         enabled: boolean;

package/dist/types.js

@@ -18,6 +18,9 @@ export const DEFAULT_AGENT_CONFIG = {
     worktree: {
         basePath: ".harmony-worktrees",
         baseBranch: "main",
+        failedBranchPrefix: "agent-attempts/",
+        approvedBranchPrefix: "agent/",
+        failedAttemptRetentionDays: 7,
     },
     verification: {
         enabled: true,

package/dist/verification.d.ts

@@ -12,7 +12,13 @@ export declare function runBuild(worktreePath: string, timeout: number): string[
 export declare function runLint(worktreePath: string, timeout: number): string[];
 export declare function runDeepReview(worktreePath: string, config: AgentConfig, workerId: number): Promise<string[]>;
 export declare function attemptAutoFix(worktreePath: string, config: AgentConfig, errors: string[]): void;
-export declare function reportFindings(client: HarmonyApiClient, cardId: string, result: VerificationResult): Promise<void>;
+export interface RecoveryInfo {
+    /** Remote ref where the failed attempt was pushed. */
+    branchName: string;
+    /** Public URL of the branch (GitHub/GitLab/Bitbucket tree view), if known. */
+    branchUrl: string | null;
+}
+export declare function reportFindings(client: HarmonyApiClient, cardId: string, result: VerificationResult, recovery?: RecoveryInfo | null): Promise<void>;
 export declare class DevServerReadinessError extends Error {
     constructor(message: string);
 }

package/dist/verification.js

@@ -160,8 +160,13 @@ export function attemptAutoFix(worktreePath, config, errors) {
         stdio: "pipe",
     });
 }
-export async function reportFindings(client, cardId, result) {
+export async function reportFindings(client, cardId, result, recovery) {
     const items = [];
+    if (recovery) {
+        const cmd = `git fetch && git checkout ${recovery.branchName}`;
+        const url = recovery.branchUrl ? ` (${recovery.branchUrl})` : "";
+        items.push(`Recovery: \`${cmd}\`${url}`);
+    }
     for (const err of result.buildErrors) {
         items.push(`Build: ${err}`);
     }

package/dist/worker.js

@@ -102,7 +102,7 @@ export class Worker {
         try {
             // --- PREPARING ---
             this.state = "preparing";
-            this.branchName = makeBranchName(card.short_id, card.title);
+            this.branchName = makeBranchName(card.short_id, card.title, this.config.worktree.failedBranchPrefix);
             log.info(this.tag, `Preparing #${card.short_id} "${card.title}"`);
             // Per-card attempt counter resets on success; DLQ triggers off it.
             await this.stateStore.incrementAttempt(card.id);
@@ -195,7 +195,7 @@ export class Worker {
             });
             this.state = "completing";
             await this.recordPhase("completing");
-            await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id, this.lastSessionStats, this.workspaceId, this.sessionId);
+            await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id, this.lastSessionStats, this.workspaceId, this.sessionId, this.stateStore);
         }
         catch (err) {
             this.state = "error";

package/dist/worktree-gc.d.ts

@@ -1,4 +1,21 @@
 import type { StateStore } from "./state-store.js";
+export interface RemoteBranchGcOptions {
+    /** Prefix to scan (e.g. `agent-attempts/`). */
+    prefix: string;
+    /** Retention in days. Branches older than this are removed. */
+    retentionDays: number;
+    /** Optional sync clock, for deterministic tests. */
+    now?: () => number;
+}
+export interface RemoteBranchGcResult {
+    scanned: number;
+    removed: string[];
+    skipped: string[];
+    errors: Array<{
+        ref: string;
+        error: string;
+    }>;
+}
 export interface GcResult {
     checked: number;
     removed: string[];
@@ -27,12 +44,23 @@ export interface GcOptions {
  * Returns a summary; callers decide whether to log at info or warn.
  */
 export declare function runWorktreeGc(basePath: string, store: StateStore, opts?: GcOptions): GcResult;
+/**
+ * Sweep stale failed-attempt branches off the remote.
+ *
+ * Lists `origin/<prefix>*`, asks git for each ref's committer timestamp via
+ * `for-each-ref`, and deletes anything older than `retentionDays`. Runs on
+ * the same GC tick that handles worktree directories — protecting unpushed
+ * commits is the job of the daemon (always push before verify); this sweep
+ * just keeps the namespace tidy.
+ */
+export declare function pruneFailedRemoteBranches(opts: RemoteBranchGcOptions): RemoteBranchGcResult;
 export declare class WorktreeGc {
     private basePath;
     private store;
     private intervalMs;
+    private remoteOpts?;
     private timer;
-    constructor(basePath: string, store: StateStore, intervalMs: number);
+    constructor(basePath: string, store: StateStore, intervalMs: number, remoteOpts?: RemoteBranchGcOptions | undefined);
     start(): void;
     stop(): void;
     private tick;

package/dist/worktree-gc.js

@@ -96,15 +96,114 @@ export function runWorktreeGc(basePath, store, opts = {}) {
     }
     return result;
 }
+/**
+ * Sweep stale failed-attempt branches off the remote.
+ *
+ * Lists `origin/<prefix>*`, asks git for each ref's committer timestamp via
+ * `for-each-ref`, and deletes anything older than `retentionDays`. Runs on
+ * the same GC tick that handles worktree directories — protecting unpushed
+ * commits is the job of the daemon (always push before verify); this sweep
+ * just keeps the namespace tidy.
+ */
+export function pruneFailedRemoteBranches(opts) {
+    const result = {
+        scanned: 0,
+        removed: [],
+        skipped: [],
+        errors: [],
+    };
+    if (!opts.prefix)
+        return result;
+    // 0 or negative retention is opt-out — caller wants nothing pruned.
+    if (!Number.isFinite(opts.retentionDays) || opts.retentionDays <= 0) {
+        return result;
+    }
+    const repoRoot = getRepoRoot();
+    if (!repoRoot) {
+        result.errors.push({ ref: "<repo-root>", error: "not a git repo" });
+        return result;
+    }
+    // Refresh the remote refs we know about. Pruned remote branches drop from
+    // local tracking, so we never try to delete refs the server already lost.
+    try {
+        execFileSync("git", ["fetch", "--prune", "origin"], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch (err) {
+        result.errors.push({
+            ref: "fetch",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        // Continue — for-each-ref may still find usable cached refs.
+    }
+    const refPattern = `refs/remotes/origin/${opts.prefix}*`;
+    let listing = "";
+    try {
+        listing = execFileSync("git", [
+            "for-each-ref",
+            "--format=%(refname:strip=3) %(committerdate:unix)",
+            refPattern,
+        ], { cwd: repoRoot, encoding: "utf-8" });
+    }
+    catch (err) {
+        result.errors.push({
+            ref: refPattern,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return result;
+    }
+    const cutoffSecs = (opts.now ?? Date.now)() / 1000 - opts.retentionDays * 24 * 60 * 60;
+    for (const line of listing.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const sp = trimmed.lastIndexOf(" ");
+        if (sp < 0)
+            continue;
+        const ref = trimmed.slice(0, sp);
+        const ts = Number(trimmed.slice(sp + 1));
+        result.scanned++;
+        if (!Number.isFinite(ts) || ts >= cutoffSecs) {
+            result.skipped.push(ref);
+            continue;
+        }
+        try {
+            execFileSync("git", ["push", "origin", `:refs/heads/${ref}`], {
+                cwd: repoRoot,
+                stdio: "pipe",
+            });
+            result.removed.push(ref);
+        }
+        catch (err) {
+            result.errors.push({
+                ref,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (result.removed.length > 0) {
+        log.info(TAG, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
+    }
+    if (result.errors.length > 0) {
+        log.warn(TAG, `Remote branch GC had ${result.errors.length} error(s): ${result.errors
+            .map((e) => `${e.ref}: ${e.error}`)
+            .join("; ")}`);
+    }
+    return result;
+}
 export class WorktreeGc {
     basePath;
     store;
     intervalMs;
+    remoteOpts;
     timer = null;
-    constructor(basePath, store, intervalMs) {
+    constructor(basePath, store, intervalMs, remoteOpts) {
         this.basePath = basePath;
         this.store = store;
         this.intervalMs = intervalMs;
+        this.remoteOpts = remoteOpts;
     }
     start() {
         // Run once at startup, then on interval.
@@ -124,6 +223,14 @@ export class WorktreeGc {
         catch (err) {
             log.warn(TAG, `GC tick failed: ${err instanceof Error ? err.message : err}`);
         }
+        if (this.remoteOpts) {
+            try {
+                pruneFailedRemoteBranches(this.remoteOpts);
+            }
+            catch (err) {
+                log.warn(TAG, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
+            }
+        }
     }
 }
 function getRepoRoot() {

package/dist/worktree.d.ts

@@ -9,5 +9,10 @@ export declare function createWorktree(basePath: string, baseBranch: string, bra
 export declare function cleanupWorktree(worktreePath: string, branchName?: string): void;
 /**
  * Generate a branch name from a card's short ID and title.
+ *
+ * Agent branches start under the failedBranchPrefix (default `agent-attempts/`)
+ * and are renamed to the approvedBranchPrefix (default `agent/`) only after the
+ * Review pipeline approves them. Branches under `agent-attempts/` are pruned
+ * by the GC after `failedAttemptRetentionDays`.
  */
-export declare function makeBranchName(shortId: number, title: string): string;
+export declare function makeBranchName(shortId: number, title: string, prefix?: string): string;

package/dist/worktree.js

@@ -158,8 +158,13 @@ export function cleanupWorktree(worktreePath, branchName) {
 }
 /**
  * Generate a branch name from a card's short ID and title.
+ *
+ * Agent branches start under the failedBranchPrefix (default `agent-attempts/`)
+ * and are renamed to the approvedBranchPrefix (default `agent/`) only after the
+ * Review pipeline approves them. Branches under `agent-attempts/` are pruned
+ * by the GC after `failedAttemptRetentionDays`.
  */
-export function makeBranchName(shortId, title) {
+export function makeBranchName(shortId, title, prefix = "agent-attempts/") {
     const slug = title
         .toLowerCase()
         .trim()
@@ -168,5 +173,5 @@ export function makeBranchName(shortId, title) {
         .replace(/-+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, 40);
-    return `agent/${shortId}-${slug || "task"}`;
+    return `${prefix}${shortId}-${slug || "task"}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/agent",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Push-based agent daemon for Harmony — watches board assignments and spawns Claude CLI workers",
   "type": "module",
   "main": "dist/index.js",