@gethmy/agent 1.0.9 → 1.1.1

package/dist/pool.d.ts

@@ -1,16 +1,24 @@
 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";
 export declare class Pool {
+    private client;
     private implWorkers;
     private reviewWorkers;
     private implQueue;
     private reviewQueue;
-    constructor(config: AgentConfig, client: HarmonyApiClient, userEmail: string, workspaceId: string, projectId: string);
+    private budget;
+    constructor(config: AgentConfig, client: HarmonyApiClient, userEmail: string, workspaceId: string, projectId: string, stateStore: StateStore);
     /**
      * Enqueue a card for processing with the given mode.
+     *
+     * Returns async so callers can await the DLQ side-effects on skip.
+     * Budget/DLQ checks happen here so the reconciler, realtime watcher,
+     * and manual API calls all go through the same gate.
      */
-    enqueue(card: Card, column: Column, labels: Label[], subtasks: Subtask[], mode?: WorkMode): void;
+    enqueue(card: Card, column: Column, labels: Label[], subtasks: Subtask[], mode?: WorkMode): Promise<void>;
     /**
      * Remove a card from any queue or cancel an active worker.
      */
@@ -31,6 +39,23 @@ export declare class Pool {
      * Handle an agent command (pause/resume/stop) for a specific card.
      */
     handleAgentCommand(cardId: string, command: "pause" | "resume" | "stop"): Promise<void>;
+    /**
+     * Point-in-time snapshot for the HTTP /status endpoint. Safe to call
+     * from anywhere — reads in-memory state only.
+     */
+    snapshotWorkers(): Array<{
+        id: number;
+        pipeline: "implement" | "review";
+        state: string;
+        cardId: string | null;
+        cardShortId: number | null;
+        startedAt: number | null;
+        branchName: string | null;
+    }>;
+    snapshotQueues(): {
+        impl: ReturnType<PriorityQueue["snapshot"]>;
+        review: ReturnType<PriorityQueue["snapshot"]>;
+    };
     /**
      * Gracefully shutdown all workers.
      */

package/dist/pool.js

@@ -1,36 +1,45 @@
+import { BudgetGuard } from "./budget.js";
 import { log } from "./log.js";
 import { PriorityQueue } from "./queue.js";
 import { ReviewWorker } from "./review-worker.js";
 import { Worker } from "./worker.js";
 const TAG = "pool";
 export class Pool {
+    client;
     implWorkers = [];
     reviewWorkers = [];
     implQueue;
     reviewQueue;
-    constructor(config, client, userEmail, workspaceId, projectId) {
+    budget;
+    constructor(config, client, userEmail, workspaceId, projectId, stateStore) {
+        this.client = client;
         this.implQueue = new PriorityQueue(config);
         this.reviewQueue = new PriorityQueue(config);
+        this.budget = new BudgetGuard(config.budget, stateStore);
         // Create implementation workers
         for (let i = 0; i < config.poolSize; i++) {
             this.implWorkers.push(new Worker(i, config, client, userEmail, () => {
                 this.tryDispatchFor(this.implWorkers, this.implQueue, "impl");
-            }, workspaceId, projectId));
+            }, workspaceId, projectId, stateStore));
         }
         // Create review worker(s) — 1 review worker per pool
         if (config.review.enabled) {
             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));
         }
         const reviewCount = this.reviewWorkers.length;
         log.info(TAG, `Pool initialized: ${config.poolSize} impl worker(s), ${reviewCount} review worker(s)`);
     }
     /**
      * Enqueue a card for processing with the given mode.
+     *
+     * Returns async so callers can await the DLQ side-effects on skip.
+     * Budget/DLQ checks happen here so the reconciler, realtime watcher,
+     * and manual API calls all go through the same gate.
      */
-    enqueue(card, column, labels, subtasks, mode = "implement") {
+    async enqueue(card, column, labels, subtasks, mode = "implement") {
         // Don't enqueue if already in any queue or actively being worked on
         if (this.implQueue.has(card.id) ||
             this.reviewQueue.has(card.id) ||
@@ -38,6 +47,26 @@ export class Pool {
             log.debug(TAG, `Card ${card.id} already queued or active, skipping`);
             return;
         }
+        // Review pickups bypass per-card attempt limits (reviews are cheap
+        // and orthogonal to implement attempts). Daily budget still applies.
+        if (mode === "implement") {
+            const decision = this.budget.check(card.id);
+            if (!decision.allow) {
+                // Already-DLQ cards are expected noise on every reconcile tick;
+                // only the terminal decision itself deserves a warn.
+                const wasAlreadyDlq = decision.reason === "dlq";
+                if (!wasAlreadyDlq) {
+                    log.warn(TAG, `#${card.short_id} skipped (${decision.reason}): ${decision.detail}`);
+                    if (this.budget.isTerminal(decision.reason)) {
+                        await this.budget.markDlq(this.client, card, decision.reason, decision.detail);
+                    }
+                }
+                else {
+                    log.debug(TAG, `#${card.short_id} in DLQ: ${decision.detail}`);
+                }
+                return;
+            }
+        }
         const queue = mode === "review" ? this.reviewQueue : this.implQueue;
         queue.enqueue(card, column, labels, mode);
         // Store card data for when it gets dispatched
@@ -122,6 +151,42 @@ export class Pool {
                 break;
         }
     }
+    /**
+     * Point-in-time snapshot for the HTTP /status endpoint. Safe to call
+     * from anywhere — reads in-memory state only.
+     */
+    snapshotWorkers() {
+        const out = [];
+        for (const w of this.implWorkers) {
+            out.push({
+                id: w.id,
+                pipeline: "implement",
+                state: w.state,
+                cardId: w.cardId,
+                cardShortId: null,
+                startedAt: w.startedAt,
+                branchName: w.branchName,
+            });
+        }
+        for (const w of this.reviewWorkers) {
+            out.push({
+                id: w.id,
+                pipeline: "review",
+                state: w.state,
+                cardId: w.cardId,
+                cardShortId: null,
+                startedAt: w.startedAt,
+                branchName: w.branchName,
+            });
+        }
+        return out;
+    }
+    snapshotQueues() {
+        return {
+            impl: this.implQueue.snapshot(),
+            review: this.reviewQueue.snapshot(),
+        };
+    }
     /**
      * Gracefully shutdown all workers.
      */

package/dist/process-group.d.ts

@@ -0,0 +1,26 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+/**
+ * Spawn a child in its own process group so we can reliably kill the
+ * whole subtree later. The Claude CLI shells out to git, build tools,
+ * dev servers, etc. — signalling only the direct child leaves orphans.
+ *
+ * - POSIX: `detached: true` puts the child in a new process group whose
+ *   pgid equals its pid. Killing the negative pid signals every member.
+ * - Windows: `detached: true` creates a new process group that can be
+ *   signalled via the child's pid (no negation).
+ */
+export declare function spawnInGroup(command: string, args: readonly string[], options?: SpawnOptions): ChildProcess;
+/**
+ * Send a signal to every process in the group whose leader is `proc`.
+ * On POSIX, this is `process.kill(-pid, signal)`. If the group has
+ * already exited, returns silently.
+ */
+export declare function signalGroup(proc: ChildProcess, signal: NodeJS.Signals): void;
+/**
+ * Escalating termination: SIGINT → wait → SIGTERM → wait → SIGKILL.
+ * Returns when the process has exited or all signals have been sent.
+ */
+export declare function terminateGroup(proc: ChildProcess, opts: {
+    sigintTimeoutMs: number;
+    sigtermTimeoutMs: number;
+}): Promise<void>;

package/dist/process-group.js

@@ -0,0 +1,72 @@
+import { spawn, } from "node:child_process";
+import { log } from "./log.js";
+const TAG = "pgroup";
+/**
+ * Spawn a child in its own process group so we can reliably kill the
+ * whole subtree later. The Claude CLI shells out to git, build tools,
+ * dev servers, etc. — signalling only the direct child leaves orphans.
+ *
+ * - POSIX: `detached: true` puts the child in a new process group whose
+ *   pgid equals its pid. Killing the negative pid signals every member.
+ * - Windows: `detached: true` creates a new process group that can be
+ *   signalled via the child's pid (no negation).
+ */
+export function spawnInGroup(command, args, options = {}) {
+    return spawn(command, args, {
+        ...options,
+        detached: true,
+        // Keep stdio wired up so streaming still works.
+        stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+    });
+}
+/**
+ * Send a signal to every process in the group whose leader is `proc`.
+ * On POSIX, this is `process.kill(-pid, signal)`. If the group has
+ * already exited, returns silently.
+ */
+export function signalGroup(proc, signal) {
+    if (!proc.pid || proc.killed)
+        return;
+    try {
+        if (process.platform === "win32") {
+            // No process groups on Windows; best effort tree kill via the child.
+            proc.kill(signal);
+            return;
+        }
+        process.kill(-proc.pid, signal);
+    }
+    catch (err) {
+        // ESRCH means the group is already gone — that is the goal, not an error.
+        const code = err.code;
+        if (code !== "ESRCH") {
+            log.warn(TAG, `signal ${signal} to pgid ${proc.pid} failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}
+/**
+ * Escalating termination: SIGINT → wait → SIGTERM → wait → SIGKILL.
+ * Returns when the process has exited or all signals have been sent.
+ */
+export async function terminateGroup(proc, opts) {
+    if (!proc.pid || proc.killed)
+        return;
+    // Unpause first in case the process was suspended — otherwise it
+    // can't react to signals.
+    signalGroup(proc, "SIGCONT");
+    const waitForExit = (timeout) => new Promise((resolve) => {
+        if (proc.killed || proc.exitCode !== null)
+            return resolve(true);
+        const timer = setTimeout(() => resolve(false), timeout);
+        proc.once("exit", () => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+    signalGroup(proc, "SIGINT");
+    if (await waitForExit(opts.sigintTimeoutMs))
+        return;
+    signalGroup(proc, "SIGTERM");
+    if (await waitForExit(opts.sigtermTimeoutMs))
+        return;
+    signalGroup(proc, "SIGKILL");
+}

package/dist/progress-tracker.js

@@ -347,6 +347,8 @@ export class ProgressTracker {
             phase: this.phase,
             filesChanged: this.filesEdited.size,
             costCents: Math.round((this.lastCost?.totalCostUsd ?? 0) * 100),
+            inputTokens: this.lastCost?.totalInputTokens ?? 0,
+            outputTokens: this.lastCost?.totalOutputTokens ?? 0,
         })
             .catch((err) => {
             log.warn(TAG, `Failed to send progress update: ${err}`);

package/dist/queue.d.ts

@@ -34,4 +34,6 @@ export declare class PriorityQueue {
     cardIds(): string[];
     get length(): number;
     peek(): QueueItem | null;
+    /** Copy of the queue in priority order (for introspection). */
+    snapshot(): QueueItem[];
 }

package/dist/queue.js

@@ -93,4 +93,8 @@ export class PriorityQueue {
     peek() {
         return this.items[0] ?? null;
     }
+    /** Copy of the queue in priority order (for introspection). */
+    snapshot() {
+        return this.items.slice();
+    }
 }

package/dist/reconcile.d.ts

@@ -1,5 +1,7 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Pool } from "./pool.js";
+import type { StateStore } from "./state-store.js";
+import { type AgentConfig } from "./types.js";
 /**
  * Reconciliation heartbeat: polls the board every `intervalMs` to catch
  * missed realtime events and sync state.
@@ -13,9 +15,21 @@ export declare class Reconciler {
     private reviewColumns;
     private approvedLabel;
     private intervalMs;
+    private stateStore?;
+    private agentConfig?;
     private timer;
-    constructor(client: HarmonyApiClient, pool: Pool, projectId: string, agentUserId: string, pickupColumns: string[], reviewColumns: string[], approvedLabel: string, intervalMs?: number);
+    private lastTickAt;
+    get lastTick(): number | null;
+    get isRunning(): boolean;
+    constructor(client: HarmonyApiClient, pool: Pool, projectId: string, agentUserId: string, pickupColumns: string[], reviewColumns: string[], approvedLabel: string, intervalMs?: number, stateStore?: StateStore | undefined, agentConfig?: AgentConfig | undefined);
     start(): void;
     stop(): void;
+    /**
+     * Walk the state store for runs marked active whose owning daemon is
+     * dead OR whose heartbeat is stale. Each such run gets the same
+     * recovery treatment as startup orphans: session ended, card returned
+     * to pickup column with agent-recovered label, worktree cleaned up.
+     */
+    private recoverStaleRuns;
     private tick;
 }

package/dist/reconcile.js

@@ -1,5 +1,7 @@
 import { buildLabelMap, hasLabel, resolveCardLabels } from "./board-helpers.js";
 import { log } from "./log.js";
+import { isProcessAlive, recoverRun } from "./recovery.js";
+import { extractBranchFromDescription } from "./review-worktree.js";
 import { NEED_REVIEW_LABEL } from "./types.js";
 const TAG = "reconcile";
 /**
@@ -15,8 +17,17 @@ export class Reconciler {
     reviewColumns;
     approvedLabel;
     intervalMs;
+    stateStore;
+    agentConfig;
     timer = null;
-    constructor(client, pool, projectId, agentUserId, pickupColumns, reviewColumns, approvedLabel, intervalMs = 60_000) {
+    lastTickAt = null;
+    get lastTick() {
+        return this.lastTickAt;
+    }
+    get isRunning() {
+        return this.timer !== null;
+    }
+    constructor(client, pool, projectId, agentUserId, pickupColumns, reviewColumns, approvedLabel, intervalMs = 60_000, stateStore, agentConfig) {
         this.client = client;
         this.pool = pool;
         this.projectId = projectId;
@@ -25,6 +36,8 @@ export class Reconciler {
         this.reviewColumns = reviewColumns;
         this.approvedLabel = approvedLabel;
         this.intervalMs = intervalMs;
+        this.stateStore = stateStore;
+        this.agentConfig = agentConfig;
     }
     start() {
         log.info(TAG, `Heartbeat every ${this.intervalMs / 1000}s`);
@@ -39,7 +52,42 @@ export class Reconciler {
         }
         log.info(TAG, "Heartbeat stopped");
     }
+    /**
+     * Walk the state store for runs marked active whose owning daemon is
+     * dead OR whose heartbeat is stale. Each such run gets the same
+     * recovery treatment as startup orphans: session ended, card returned
+     * to pickup column with agent-recovered label, worktree cleaned up.
+     */
+    async recoverStaleRuns() {
+        if (!this.stateStore || !this.agentConfig)
+            return;
+        const now = Date.now();
+        const stale = this.agentConfig.timing.staleHeartbeatMs;
+        const active = this.stateStore.getActiveRuns();
+        const pool = this.pool;
+        for (const run of active) {
+            const foreignDaemon = run.daemonPid !== process.pid;
+            const daemonDead = foreignDaemon && !isProcessAlive(run.daemonPid, process.pid);
+            const heartbeatStale = now - run.lastHeartbeatAt > stale;
+            const ourZombie = !foreignDaemon && !pool.isCardActive(run.cardId);
+            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(TAG, `zombie run ${run.runId} (#${run.cardShortId}): ${reason} — recovering`);
+            await recoverRun(run, this.stateStore, this.client, this.agentConfig, {
+                runId: run.runId,
+                cardId: run.cardId,
+                cardShortId: run.cardShortId,
+                pipeline: run.pipeline,
+                actions: [],
+                errors: [],
+            });
+        }
+    }
     async tick() {
+        this.lastTickAt = Date.now();
         try {
             const board = await this.client.getBoard(this.projectId);
             const cards = (board.cards ?? []);
@@ -94,10 +142,23 @@ export class Reconciler {
                         log.debug(TAG, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
                         continue;
                     }
+                    // Skip review for cards without a branch reference — not qualified for auto-review
+                    if (mode === "review" &&
+                        !extractBranchFromDescription(card.description)) {
+                        log.debug(TAG, `Skipping #${card.short_id} — no branch reference (not qualified for auto-review)`);
+                        continue;
+                    }
                     log.info(TAG, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
-                    this.pool.enqueue(card, column, cardLabels, subtasks, mode);
+                    await this.pool.enqueue(card, column, cardLabels, subtasks, mode);
                 }
             }
+            // Detect zombie runs: state-store says active, but either:
+            //  (a) another daemon's PID is dead, or
+            //  (b) our daemon holds the run but no worker is on the card, or
+            //  (c) heartbeat is older than staleHeartbeatMs.
+            if (this.stateStore && this.agentConfig) {
+                await this.recoverStaleRuns();
+            }
             // Cards in queue/active but no longer assigned to agent → cancel/remove
             for (const knownId of knownCardIds) {
                 if (!allAgentCardIds.has(knownId)) {

package/dist/recovery.d.ts

@@ -0,0 +1,30 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { RunRecord, StateStore } from "./state-store.js";
+import type { AgentConfig } from "./types.js";
+export interface RecoveryOutcome {
+    runId: string;
+    cardId: string;
+    cardShortId: number;
+    pipeline: "implement" | "review";
+    actions: string[];
+    errors: string[];
+}
+/**
+ * Check if a process is still alive. A crashed daemon's PID is unlikely
+ * to be reused within a reboot window; if it is, we still treat it as
+ * orphaned because our current process is the new daemon.
+ */
+export declare function isProcessAlive(pid: number, currentPid: number): boolean;
+/**
+ * Reconcile orphaned runs from a previous daemon life.
+ *
+ * For each active run in the state store:
+ *  - If the daemon PID is alive (should not happen for a fresh process),
+ *    skip it — it's another instance.
+ *  - Otherwise: end the Harmony session, return the card to its pickup
+ *    column with the `agent-recovered` label, and cleanup the worktree.
+ *
+ * This runs once at daemon startup, before the pool accepts work.
+ */
+export declare function recoverOrphans(store: StateStore, client: HarmonyApiClient, config: AgentConfig): Promise<RecoveryOutcome[]>;
+export declare function recoverRun(run: RunRecord, store: StateStore, client: HarmonyApiClient, config: AgentConfig, outcome: RecoveryOutcome): Promise<void>;

package/dist/recovery.js

@@ -0,0 +1,136 @@
+import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
+import { log } from "./log.js";
+import { cleanupWorktree } from "./worktree.js";
+const TAG = "recovery";
+const RECOVERED_LABEL = "agent-recovered";
+const RECOVERED_LABEL_COLOR = "#f59e0b";
+/**
+ * Check if a process is still alive. A crashed daemon's PID is unlikely
+ * to be reused within a reboot window; if it is, we still treat it as
+ * orphaned because our current process is the new daemon.
+ */
+export function isProcessAlive(pid, currentPid) {
+    if (pid === currentPid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchCardSafely(client, cardId) {
+    try {
+        const { card } = (await client.getCard(cardId));
+        return card;
+    }
+    catch (err) {
+        log.warn(TAG, `cannot fetch card ${cardId}: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}
+/**
+ * Reconcile orphaned runs from a previous daemon life.
+ *
+ * For each active run in the state store:
+ *  - If the daemon PID is alive (should not happen for a fresh process),
+ *    skip it — it's another instance.
+ *  - Otherwise: end the Harmony session, return the card to its pickup
+ *    column with the `agent-recovered` label, and cleanup the worktree.
+ *
+ * This runs once at daemon startup, before the pool accepts work.
+ */
+export async function recoverOrphans(store, client, config) {
+    const active = store.getActiveRuns();
+    if (active.length === 0) {
+        log.info(TAG, "no orphan runs to recover");
+        return [];
+    }
+    const outcomes = [];
+    log.info(TAG, `recovering ${active.length} orphan run(s) from prior daemon`);
+    for (const run of active) {
+        const outcome = {
+            runId: run.runId,
+            cardId: run.cardId,
+            cardShortId: run.cardShortId,
+            pipeline: run.pipeline,
+            actions: [],
+            errors: [],
+        };
+        outcomes.push(outcome);
+        if (isProcessAlive(run.daemonPid, process.pid)) {
+            log.warn(TAG, `run ${run.runId} claims live daemon pid ${run.daemonPid} — skipping`);
+            outcome.actions.push("skipped: daemon pid still alive");
+            continue;
+        }
+        log.info(TAG, `recovering ${run.pipeline} run ${run.runId} for card #${run.cardShortId}`);
+        await recoverRun(run, store, client, config, outcome);
+    }
+    return outcomes;
+}
+export async function recoverRun(run, store, client, config, outcome) {
+    // 1. End the agent session so the card stops showing the progress ring.
+    try {
+        await client.endAgentSession(run.cardId, {
+            status: "paused",
+            progressPercent: run.phase === "completing" ? 95 : undefined,
+        });
+        outcome.actions.push("ended agent session (paused)");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        outcome.errors.push(`endAgentSession: ${msg}`);
+        log.warn(TAG, `endAgentSession failed for ${run.cardId}: ${msg}`);
+    }
+    // 2. Move card back to a safe column and add the recovered label.
+    //    - implement pipeline → pickup column (usually "To Do")
+    //    - review pipeline → leave in place (reviewer will re-pick)
+    const card = await fetchCardSafely(client, run.cardId);
+    if (card) {
+        if (run.pipeline === "implement") {
+            const target = config.pickupColumns[0];
+            if (target) {
+                try {
+                    await moveCardToColumn(client, card, target);
+                    outcome.actions.push(`moved to "${target}"`);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    outcome.errors.push(`moveCardToColumn: ${msg}`);
+                }
+            }
+        }
+        try {
+            await addLabelByName(client, card, RECOVERED_LABEL, RECOVERED_LABEL_COLOR);
+            outcome.actions.push(`labeled "${RECOVERED_LABEL}"`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            outcome.errors.push(`addLabel: ${msg}`);
+        }
+    }
+    else {
+        outcome.actions.push("card not reachable — local cleanup only");
+    }
+    // 3. Cleanup local worktree so it doesn't collide with future runs.
+    if (run.worktreePath) {
+        try {
+            cleanupWorktree(run.worktreePath, run.branchName ?? undefined);
+            outcome.actions.push("cleaned up worktree");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            outcome.errors.push(`cleanupWorktree: ${msg}`);
+        }
+    }
+    // 4. Mark the run as orphaned in the store.
+    try {
+        await store.endRun(run.runId, "orphaned", "recovered after daemon restart");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        outcome.errors.push(`endRun: ${msg}`);
+    }
+    log.info(TAG, `recovered run ${run.runId} (card #${run.cardShortId}): ${outcome.actions.join(", ")}${outcome.errors.length ? ` | errors: ${outcome.errors.join("; ")}` : ""}`);
+}

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 { AgentConfig } from "./types.js";
+import { type SessionStats } from "./completion.js";
+import { type AgentConfig } from "./types.js";
 export interface ReviewFinding {
     severity: "critical" | "major" | "minor";
     title: string;
@@ -13,14 +14,21 @@ export interface ScopeCheck {
     notes?: string;
 }
 export interface ReviewResult {
-    verdict: "approved" | "rejected";
+    verdict: "approved" | "rejected" | "error";
     summary: string;
     scopeCheck?: ScopeCheck;
     findings: ReviewFinding[];
 }
 /**
  * Parse Claude's review output into a structured ReviewResult.
- * Looks for a JSON block in the output.
+ *
+ * Tries multiple extraction strategies in order:
+ * 1. ```json ... ``` fenced block (what the prompt asks for)
+ * 2. Any top-level JSON object containing a "verdict" key (last-wins)
+ * 3. Regex for a bare `"verdict": "approved|rejected"` anywhere — lossy
+ *    but keeps the pipeline moving
+ * 4. Falls back to verdict: "error" — keeps card in Review instead of
+ *    bouncing it to To Do for a parse failure that isn't a code quality signal.
  */
 export declare function parseReviewOutput(stdout: string): ReviewResult;
 /**
@@ -28,4 +36,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): Promise<void>;
+export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string | null, sessionStats?: SessionStats | null): Promise<void>;