@gethmy/agent 1.4.2 → 1.6.0

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 {
@@ -27,7 +28,7 @@ export class Pool {
             const reviewWorkerId = config.poolSize; // offset to avoid ID collision
             this.reviewWorkers.push(new ReviewWorker(reviewWorkerId, config, client, userEmail, () => {
                 this.tryDispatchFor(this.reviewWorkers, this.reviewQueue, "review");
-            }, stateStore));
+            }, stateStore, workspaceId, projectId));
         }
     }
     /**
@@ -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/progress-tracker.d.ts

@@ -30,6 +30,7 @@ export declare class ProgressTracker {
     private lastCost;
     private logBuffer;
     private sessionId;
+    private lastAssistantText;
     constructor(client: HarmonyApiClient, cardId: string, workerId: number, subtasks: {
         completed: boolean;
     }[]);
@@ -48,6 +49,7 @@ export declare class ProgressTracker {
         filesRead: number;
         toolCalls: number;
         cost: CostUpdate | null;
+        lastAssistantText: string;
     };
     private onToolStart;
     private onToolEnd;

package/dist/progress-tracker.js

@@ -62,6 +62,9 @@ export class ProgressTracker {
     lastCost = null;
     logBuffer = [];
     sessionId = null;
+    // Last assistant text block — used by the episode write hook to
+    // capture an approach summary without re-running an LLM (plan §"Write hook").
+    lastAssistantText = "";
     constructor(client, cardId, workerId, subtasks) {
         this.client = client;
         this.cardId = cardId;
@@ -129,6 +132,7 @@ export class ProgressTracker {
             filesRead: this.filesRead.size,
             toolCalls: this.toolCallCount,
             cost: this.lastCost,
+            lastAssistantText: this.lastAssistantText,
         };
     }
     onToolStart(name, input) {
@@ -205,6 +209,9 @@ export class ProgressTracker {
         const trimmed = content.trim();
         if (trimmed.length < 10)
             return;
+        // Always remember the latest non-trivial assistant turn for the episode
+        // write hook — last-turn trim, no LLM rewrite (plan §"Write hook").
+        this.lastAssistantText = trimmed;
         // Extract first sentence or line as a brief description
         const end = trimmed.search(SENTENCE_SPLIT);
         const firstLine = (end === -1 ? trimmed : trimmed.slice(0, end)).trim();

package/dist/prompt.d.ts

@@ -10,3 +10,9 @@ import type { EnrichedCard } from "./types.js";
  * Falls back to a minimal local prompt if the API call fails.
  */
 export declare function buildPrompt(enriched: EnrichedCard, branchName: string, worktreePath: string, client: HarmonyApiClient, workspaceId: string, projectId?: string): Promise<string>;
+/**
+ * Recall similar past episodes (implement solution/error type) and render them
+ * as a "Similar past tasks" section. Returns the empty string on no hits or
+ * recall failure — never throws.
+ */
+export declare function renderPastEpisodesSection(client: HarmonyApiClient, title: string, description: string, workspaceId: string, projectId?: string): Promise<string>;

package/dist/prompt.js

@@ -11,6 +11,10 @@ const TAG = "prompt";
  */
 export async function buildPrompt(enriched, branchName, worktreePath, client, workspaceId, projectId) {
     const { card } = enriched;
+    // Phase 1.5 read hook: surface similar past episodes for this card. Block
+    // on recall — v2 §6.3 budget already caps latency. Errors degrade silently
+    // so prompt build always succeeds (plan §"Read hook").
+    const pastEpisodesSection = await renderPastEpisodesSection(client, card.title, card.description ?? "", workspaceId, projectId);
     try {
         const result = await client.generateCardPrompt({
             cardId: card.id,
@@ -22,12 +26,53 @@ Do NOT push to main. All your work stays on \`${branchName}\`.
 When finished, call harmony_end_agent_session with status="completed".`,
         });
         log.info(TAG, `Generated prompt for #${card.short_id} — ${result.contextSummary.memoryCount} memories, ${result.tokenEstimate} tokens`);
-        return result.prompt;
+        return result.prompt + pastEpisodesSection;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         log.warn(TAG, `Failed to generate prompt via API, using fallback: ${msg}`);
-        return buildFallbackPrompt(enriched, branchName, worktreePath);
+        return (buildFallbackPrompt(enriched, branchName, worktreePath) +
+            pastEpisodesSection);
+    }
+}
+/**
+ * Recall similar past episodes (implement solution/error type) and render them
+ * as a "Similar past tasks" section. Returns the empty string on no hits or
+ * recall failure — never throws.
+ */
+export async function renderPastEpisodesSection(client, title, description, workspaceId, projectId) {
+    if (!projectId)
+        return "";
+    try {
+        const query = `${title}\n${description}`.trim();
+        const { entities } = await client.harmonyRecall({
+            workspaceId,
+            projectId,
+            query,
+            type: ["solution", "error"],
+            memory_tier: "episode",
+            scope: "project",
+            topK: 3,
+        });
+        if (entities.length === 0)
+            return "";
+        const bullets = entities
+            .map((entity) => {
+            const e = entity;
+            const meta = e.metadata ?? {};
+            const outcomeTag = meta.outcome ? `[${meta.outcome}]` : "[?]";
+            const approach = meta.approach_summary ?? "";
+            return `- ${outcomeTag} ${e.title ?? "(untitled episode)"}\n  Approach: ${approach}`;
+        })
+            .join("\n");
+        return `\n\n## Similar past tasks\n${bullets}`;
+    }
+    catch (err) {
+        log.warn(TAG, "past-episodes recall failed", {
+            event: "episode_recall_failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return "";
     }
 }
 /**

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): 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

@@ -1,7 +1,8 @@
 import { readFileSync, statSync } from "node:fs";
 import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
 import { buildTokenPayload } from "./completion.js";
-import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
+import { backfillReviewVerdict, findLatestImplementEpisode, writeEpisode, } from "./episode-writer.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";
@@ -182,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) {
+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 {
@@ -247,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
@@ -321,6 +340,24 @@ export async function runReviewCompletion(client, card, result, config, worktree
                 status: "completed",
                 ...buildTokenPayload(sessionStats),
             });
+            // Max-cycles rejection: the verdict still teaches "this approach kept
+            // failing review" — write the episode + back-fill before exiting.
+            if (workspaceId) {
+                const origId = await findLatestImplementEpisode(client, workspaceId, card.project_id, card.short_id);
+                const reviewId = await writeEpisode(client, {
+                    kind: "review",
+                    card,
+                    workspaceId,
+                    verdict: "rejected",
+                    summary: `Reached max review cycles (${maxCycles}). ${result.summary}`,
+                    cost: sessionStats?.cost ?? null,
+                    agentSessionId: agentSessionId ?? null,
+                    originalEpisodeId: origId,
+                });
+                if (origId) {
+                    await backfillReviewVerdict(client, origId, "rejected", reviewId);
+                }
+            }
             if (branchName) {
                 cleanupWorktree(worktreePath, branchName);
             }
@@ -382,12 +419,54 @@ 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}"`);
     }
+    // Episode write + verdict back-fill (Phase 1.5). Runs for approved or
+    // rejected verdicts only — "error" verdicts return early above. Best-effort:
+    // failures are logged by writeEpisode/backfillReviewVerdict and never block
+    // worktree cleanup.
+    if (workspaceId &&
+        (result.verdict === "approved" || result.verdict === "rejected")) {
+        const originalEpisodeId = await findLatestImplementEpisode(client, workspaceId, card.project_id, card.short_id);
+        const reviewEpisodeId = await writeEpisode(client, {
+            kind: "review",
+            card,
+            workspaceId,
+            verdict: result.verdict,
+            summary: result.summary,
+            cost: sessionStats?.cost ?? null,
+            agentSessionId: agentSessionId ?? null,
+            originalEpisodeId,
+        });
+        if (originalEpisodeId) {
+            await backfillReviewVerdict(client, originalEpisodeId, result.verdict, reviewEpisodeId);
+        }
+    }
     // Cleanup worktree (skip in local mode — no worktree to clean)
     if (branchName) {
         cleanupWorktree(worktreePath, branchName);

package/dist/review-worker.d.ts

@@ -7,6 +7,7 @@ export declare class ReviewWorker {
     private client;
     private onDone;
     private stateStore;
+    private workspaceId?;
     id: number;
     state: WorkerState;
     cardId: string | null;
@@ -22,7 +23,8 @@ export declare class ReviewWorker {
     private aborted;
     private runId;
     private lastRunLogPath;
-    constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: ReviewWorker) => void, stateStore: StateStore);
+    private sessionId;
+    constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: ReviewWorker) => void, stateStore: StateStore, workspaceId?: string | undefined, _projectId?: string);
     private startHeartbeat;
     private stopHeartbeat;
     private recordPhase;

package/dist/review-worker.js

@@ -23,6 +23,7 @@ export class ReviewWorker {
     client;
     onDone;
     stateStore;
+    workspaceId;
     id;
     state = "idle";
     cardId = null;
@@ -38,11 +39,13 @@ export class ReviewWorker {
     aborted = false;
     runId = null;
     lastRunLogPath = null;
-    constructor(id, config, client, _userEmail, onDone, stateStore) {
+    sessionId = null;
+    constructor(id, config, client, _userEmail, onDone, stateStore, workspaceId, _projectId) {
         this.config = config;
         this.client = client;
         this.onDone = onDone;
         this.stateStore = stateStore;
+        this.workspaceId = workspaceId;
         this.id = id;
     }
     startHeartbeat() {
@@ -152,7 +155,7 @@ export class ReviewWorker {
                 log.info(this.tag, `Review branch: ${this.branchName}`);
             }
             // Start agent session and make it visible on the board
-            await this.client.startAgentSession(card.id, {
+            const { session: reviewSession } = await this.client.startAgentSession(card.id, {
                 agentIdentifier: agentIdentifier(this.id),
                 agentName: `${AGENT_NAME} (Review)`,
                 status: "working",
@@ -161,6 +164,12 @@ export class ReviewWorker {
                     : "Setting up review worktree",
                 progressPercent: 5,
             });
+            this.sessionId =
+                reviewSession &&
+                    typeof reviewSession === "object" &&
+                    "id" in reviewSession
+                    ? (reviewSession.id ?? null)
+                    : null;
             // Fire label addition concurrently with sync worktree checkout
             const labelPromise = addLabelByName(this.client, card, "agent", "#8b5cf6");
             if (!localMode) {
@@ -182,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;
@@ -281,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);
+            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;