@gethmy/agent 1.0.0 → 1.0.2

package/dist/progress-tracker.js

@@ -0,0 +1,361 @@
+import { log } from "./log.js";
+import { AGENT_NAME, agentIdentifier } from "./types.js";
+const TAG = "progress-tracker";
+const THROTTLE_MS = 5_000;
+const HEARTBEAT_MS = 60_000;
+const MAX_TASK_LENGTH = 120;
+const MAX_RECENT_ACTIONS = 5;
+// Hoisted regexes — avoids recompilation on every call
+const SENTENCE_SPLIT = /\.\s|\n/;
+const ACTION_PREFIX = /^(Let me|I'll|I need to|Now|First|Next|Looking|Checking|Creating|Adding|Updating|Fixing|Refactoring|Moving|The |This )/i;
+const GIT_COMMIT_RE = /\bgit\s+commit\b/;
+const BUILD_CMD_RE = /\b(test|build|lint|check|tsc|vitest|jest|(?:bun|npm|pnpm|yarn) run (?:build|lint))\b/;
+const PHASES = {
+    exploring: { min: 10, max: 25, label: "Exploring" },
+    implementing: { min: 25, max: 55, label: "Implementing" },
+    testing: { min: 55, max: 65, label: "Testing" },
+    committing: { min: 65, max: 70, label: "Committing" },
+    finishing: { min: 70, max: 75, label: "Finalizing" },
+};
+const PHASE_ORDER = {
+    exploring: 0,
+    implementing: 1,
+    testing: 2,
+    committing: 3,
+    finishing: 4,
+};
+// Tools that indicate implementation
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+function truncate(str, max) {
+    return str.length > max ? `${str.slice(0, max - 3)}...` : str;
+}
+// Map file-based tools to their display verbs
+const FILE_TOOL_VERBS = {
+    Read: ["Reading", "file_path"],
+    Edit: ["Editing", "file_path"],
+    MultiEdit: ["Editing", "file_path"],
+    Write: ["Writing", "file_path"],
+    NotebookEdit: ["Editing notebook", "notebook_path"],
+};
+export class ProgressTracker {
+    client;
+    cardId;
+    workerId;
+    phase = "exploring";
+    progress = 10;
+    toolCallCount = 0;
+    hasEdited = false;
+    lastUpdateAt = 0;
+    pendingUpdate = null;
+    pendingTask = "";
+    heartbeatTimer = null;
+    stopped = false;
+    // Rich task tracking
+    lastAction = "";
+    // Subtask tracking
+    subtaskTotal;
+    subtaskCompleted;
+    subtaskMode;
+    // Rich activity tracking
+    filesEdited = new Set();
+    filesRead = new Set();
+    lastCost = null;
+    recentActions = [];
+    constructor(client, cardId, workerId, subtasks) {
+        this.client = client;
+        this.cardId = cardId;
+        this.workerId = workerId;
+        this.subtaskTotal = subtasks.length;
+        this.subtaskCompleted = subtasks.filter((s) => s.completed).length;
+        this.subtaskMode = subtasks.length > 0;
+    }
+    /**
+     * Wire up the parser events and start the heartbeat.
+     */
+    attach(parser) {
+        parser.on("tool_start", (name, input) => {
+            this.onToolStart(name, input);
+        });
+        parser.on("tool_end", (name, _id, content) => {
+            this.onToolEnd(name, content);
+        });
+        parser.on("text", (content) => {
+            this.onText(content);
+        });
+        parser.on("cost_update", (cost) => {
+            this.lastCost = cost;
+        });
+        this.startHeartbeat();
+    }
+    /**
+     * Stop all timers and flush any pending update.
+     */
+    stop() {
+        this.stopped = true;
+        if (this.pendingUpdate) {
+            clearTimeout(this.pendingUpdate);
+            this.pendingUpdate = null;
+        }
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /** Get a summary of the session stats. */
+    get stats() {
+        return {
+            filesEdited: this.filesEdited.size,
+            filesRead: this.filesRead.size,
+            toolCalls: this.toolCallCount,
+            cost: this.lastCost,
+        };
+    }
+    onToolStart(name, input) {
+        this.toolCallCount++;
+        log.debug(TAG, `Tool: ${name} (count: ${this.toolCallCount}, phase: ${this.phase})`);
+        // Track files
+        const filePath = this.extractString(input, "file_path");
+        if (filePath) {
+            if (EDIT_TOOLS.has(name)) {
+                this.filesEdited.add(filePath);
+            }
+            else if (name === "Read" || name === "Glob" || name === "Grep") {
+                this.filesRead.add(filePath);
+            }
+        }
+        // Detect phase transitions
+        if (!this.hasEdited && EDIT_TOOLS.has(name)) {
+            this.hasEdited = true;
+            this.transitionTo("implementing");
+        }
+        else if (this.hasEdited && name === "Bash") {
+            const cmd = this.extractString(input, "command");
+            if (cmd && GIT_COMMIT_RE.test(cmd)) {
+                this.transitionTo("committing");
+            }
+            else if (cmd && BUILD_CMD_RE.test(cmd)) {
+                this.transitionTo("testing");
+            }
+        }
+        else if (name === "mcp__harmony__harmony_end_agent_session") {
+            this.transitionTo("finishing");
+        }
+        // Handle subtask toggling — override heuristic progress
+        if (name === "mcp__harmony__harmony_toggle_subtask" && this.subtaskMode) {
+            const val = this.extractString(input, "completed");
+            const completing = val === null || val === "true";
+            if (completing) {
+                this.subtaskCompleted = Math.min(this.subtaskCompleted + 1, this.subtaskTotal);
+            }
+            else {
+                this.subtaskCompleted = Math.max(this.subtaskCompleted - 1, 0);
+            }
+            const subtaskProgress = Math.round(10 + (this.subtaskCompleted / this.subtaskTotal) * 60);
+            this.progress = Math.max(this.progress, subtaskProgress);
+            this.scheduleUpdate(`Completed subtask ${this.subtaskCompleted}/${this.subtaskTotal}`);
+            return;
+        }
+        // Build rich action description and increment progress
+        const action = this.describeToolAction(name, input);
+        if (action) {
+            this.lastAction = action;
+            this.pushRecentAction(action);
+        }
+        this.incrementProgress();
+    }
+    onToolEnd(name, content) {
+        // Detect build/test failures from Bash results
+        if (name === "Bash" && content && this.phase === "testing") {
+            const lower = content.slice(-500).toLowerCase();
+            if (lower.includes("error") &&
+                (lower.includes("build failed") ||
+                    lower.includes("failed to compile") ||
+                    lower.includes("exit code 1"))) {
+                this.lastAction = "Build failed — fixing errors";
+                this.scheduleUpdate(this.lastAction);
+            }
+        }
+        // Reset heartbeat on any activity
+        this.startHeartbeat();
+    }
+    onText(content) {
+        // Capture brief reasoning snippets from Claude's text output.
+        // Only update if the text looks like a meaningful status line
+        // (skip very short fragments from streaming).
+        const trimmed = content.trim();
+        if (trimmed.length < 10)
+            return;
+        // 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();
+        if (firstLine.length >= 10 && firstLine.length <= 200) {
+            if (ACTION_PREFIX.test(firstLine)) {
+                this.lastAction = truncate(firstLine, MAX_TASK_LENGTH);
+            }
+        }
+    }
+    transitionTo(newPhase) {
+        if (PHASE_ORDER[newPhase] <= PHASE_ORDER[this.phase])
+            return;
+        log.info(TAG, `Phase: ${this.phase} → ${newPhase}`);
+        this.phase = newPhase;
+        this.progress = Math.max(this.progress, PHASES[newPhase].min);
+        // Reset stale action from prior phase; new phase starts with its own label
+        this.lastAction = "";
+        this.scheduleUpdate(PHASES[newPhase].label);
+    }
+    incrementProgress() {
+        const config = PHASES[this.phase];
+        const range = config.max - config.min;
+        const step = Math.max(1, Math.round(range / 12));
+        const newProgress = Math.min(this.progress + step, config.max);
+        if (newProgress > this.progress) {
+            this.progress = newProgress;
+            this.scheduleUpdate(this.currentTaskLabel());
+        }
+    }
+    currentTaskLabel() {
+        if (this.lastAction)
+            return this.lastAction;
+        // Include file count context when available
+        const edited = this.filesEdited.size;
+        if (edited > 0) {
+            return `${PHASES[this.phase].label} (${edited} file${edited > 1 ? "s" : ""} modified)`;
+        }
+        return PHASES[this.phase].label;
+    }
+    /**
+     * Build a human-readable description of what a tool call is doing.
+     */
+    describeToolAction(name, input) {
+        // File-based tools: Read, Edit, MultiEdit, Write, NotebookEdit
+        const fileTool = FILE_TOOL_VERBS[name];
+        if (fileTool) {
+            const [verb, key] = fileTool;
+            const fp = this.extractString(input, key);
+            return fp ? `${verb} ${this.shortPath(fp)}` : verb;
+        }
+        switch (name) {
+            case "Glob": {
+                const pattern = this.extractString(input, "pattern");
+                return pattern ? `Searching for ${pattern}` : "Searching files";
+            }
+            case "Grep": {
+                const pattern = this.extractString(input, "pattern");
+                return pattern
+                    ? `Searching for "${truncate(pattern, 40)}"`
+                    : "Searching code";
+            }
+            case "Bash": {
+                const cmd = this.extractString(input, "command");
+                return cmd
+                    ? `Running: ${truncate(cmd.split("\n")[0], 80)}`
+                    : "Running command";
+            }
+            case "Agent": {
+                const desc = this.extractString(input, "description");
+                return desc
+                    ? `Sub-agent: ${truncate(desc, 60)}`
+                    : "Delegating to sub-agent";
+            }
+            default: {
+                if (name.startsWith("mcp__harmony__harmony_")) {
+                    const toolName = name
+                        .replace("mcp__harmony__harmony_", "")
+                        .replace(/_/g, " ");
+                    return `Harmony: ${toolName}`;
+                }
+                if (name.startsWith("mcp__")) {
+                    return `Tool: ${name.split("__").pop()?.replace(/_/g, " ") ?? name}`;
+                }
+                return null;
+            }
+        }
+    }
+    /**
+     * Strip absolute paths to show only meaningful segments from src/ or packages/.
+     */
+    shortPath(filePath) {
+        const parts = filePath.split("/");
+        const srcIdx = parts.lastIndexOf("src");
+        const pkgIdx = parts.lastIndexOf("packages");
+        const anchor = Math.max(srcIdx, pkgIdx);
+        if (anchor >= 0) {
+            return parts.slice(anchor).join("/");
+        }
+        return parts.slice(-3).join("/");
+    }
+    scheduleUpdate(currentTask) {
+        if (this.stopped)
+            return;
+        const now = Date.now();
+        const elapsed = now - this.lastUpdateAt;
+        // Always track latest task so throttled sends use the freshest label
+        this.pendingTask = currentTask;
+        if (elapsed >= THROTTLE_MS) {
+            this.sendUpdate(this.pendingTask);
+        }
+        else if (!this.pendingUpdate) {
+            const delay = THROTTLE_MS - elapsed;
+            this.pendingUpdate = setTimeout(() => {
+                this.pendingUpdate = null;
+                if (!this.stopped) {
+                    // Send the latest task, not the one captured at schedule time
+                    this.sendUpdate(this.pendingTask);
+                }
+            }, delay);
+        }
+        // If there's already a pending update, pendingTask is now updated — it will use the fresh value
+    }
+    pushRecentAction(action) {
+        this.recentActions.push({
+            action,
+            ts: new Date().toISOString(),
+        });
+        if (this.recentActions.length > MAX_RECENT_ACTIONS) {
+            this.recentActions.shift();
+        }
+    }
+    sendUpdate(currentTask) {
+        this.lastUpdateAt = Date.now();
+        log.debug(TAG, `Progress: ${this.progress}% — ${currentTask}`);
+        this.client
+            .updateAgentProgress(this.cardId, {
+            agentIdentifier: agentIdentifier(this.workerId),
+            agentName: AGENT_NAME,
+            status: "working",
+            currentTask: truncate(currentTask, MAX_TASK_LENGTH),
+            progressPercent: this.progress,
+            phase: this.phase,
+            filesChanged: this.filesEdited.size,
+            costCents: Math.round((this.lastCost?.totalCostUsd ?? 0) * 100),
+            recentActions: this.recentActions,
+        })
+            .catch((err) => {
+            log.warn(TAG, `Failed to send progress update: ${err}`);
+        });
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+        }
+        this.heartbeatTimer = setTimeout(() => {
+            if (!this.stopped) {
+                const task = this.lastAction
+                    ? `Still working — ${this.lastAction}`
+                    : "Still working...";
+                this.sendUpdate(truncate(task, MAX_TASK_LENGTH));
+                this.startHeartbeat();
+            }
+        }, HEARTBEAT_MS);
+    }
+    /**
+     * Safely extract a string property from an unknown tool input.
+     */
+    extractString(input, key) {
+        if (typeof input === "object" && input !== null && key in input) {
+            return String(input[key]);
+        }
+        return null;
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,5 @@
+import type { EnrichedCard } from "./types.js";
+/**
+ * Build the prompt that gets passed to Claude CLI for working on a card.
+ */
+export declare function buildPrompt(enriched: EnrichedCard, branchName: string, worktreePath: string): string;

package/dist/prompt.js

@@ -0,0 +1,40 @@
+/**
+ * Build the prompt that gets passed to Claude CLI for working on a card.
+ */
+export function buildPrompt(enriched, branchName, worktreePath) {
+    const { card, column, labels, subtasks } = enriched;
+    const labelStr = labels.length > 0 ? labels.map((l) => l.name).join(", ") : "none";
+    const subtaskStr = subtasks.length > 0
+        ? subtasks
+            .map((s) => `- [${s.completed ? "x" : " "}] ${s.title}`)
+            .join("\n")
+        : "No subtasks defined.";
+    const description = card.description?.trim() || "No description provided.";
+    return `You are an AI agent working on a task from the Harmony project board.
+
+## Card: #${card.short_id} - ${card.title}
+**Labels**: ${labelStr}
+**Column**: ${column.name}
+**Priority**: ${card.priority}
+
+## Description
+${description}
+
+## Subtasks
+${subtaskStr}
+
+## Instructions
+1. Read the codebase and understand the context needed for this task
+2. Report progress via harmony_update_agent_progress at key milestones:
+   - After reading codebase and forming a plan (~20%)
+   - After each major implementation step (~30-60%)
+   - After completing each subtask (also toggle via harmony_toggle_subtask)
+   - Before committing (~65%)
+   Include a brief currentTask description.
+3. Implement the changes on branch \`${branchName}\`
+4. Commit your work with clear, descriptive commit messages
+5. When finished, call harmony_end_agent_session with status="completed"
+
+You are working in a git worktree at \`${worktreePath}\` on branch \`${branchName}\`.
+Do NOT push to main. All your work stays on \`${branchName}\`.`;
+}

package/dist/queue.d.ts

@@ -0,0 +1,37 @@
+import type { Card, Column, Label } from "@harmony/shared";
+import type { AgentConfig, QueueItem, WorkMode } from "./types.js";
+/**
+ * Priority queue for cards waiting to be worked on.
+ * Sorted by: label priority boost > column position boost > enqueue time (FIFO).
+ */
+export declare class PriorityQueue {
+    private config;
+    private items;
+    constructor(config: AgentConfig);
+    /**
+     * Calculate priority score for a card.
+     */
+    scoreCard(_card: Card, column: Column, labels: Label[]): number;
+    /**
+     * Add a card to the queue. If already present, update its priority.
+     */
+    enqueue(card: Card, column: Column, labels: Label[], mode?: WorkMode): void;
+    /**
+     * Remove and return the highest-priority item.
+     */
+    dequeue(): QueueItem | null;
+    /**
+     * Remove a specific card from the queue.
+     */
+    remove(cardId: string): QueueItem | null;
+    /**
+     * Check if a card is in the queue.
+     */
+    has(cardId: string): boolean;
+    /**
+     * Get all queued card IDs.
+     */
+    cardIds(): string[];
+    get length(): number;
+    peek(): QueueItem | null;
+}

package/dist/queue.js

@@ -0,0 +1,96 @@
+import { log } from "./log.js";
+const TAG = "queue";
+/**
+ * Priority queue for cards waiting to be worked on.
+ * Sorted by: label priority boost > column position boost > enqueue time (FIFO).
+ */
+export class PriorityQueue {
+    config;
+    items = [];
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Calculate priority score for a card.
+     */
+    scoreCard(_card, column, labels) {
+        let score = 0;
+        // Label boost: highest matching label wins
+        for (const label of labels) {
+            const boost = this.config.priorityLabels[label.name.toLowerCase()] ?? 0;
+            if (boost > score)
+                score = boost;
+        }
+        // Column position boost: leftmost columns get higher priority
+        if (this.config.columnBoost) {
+            score += Math.max(0, 100 - column.position * 10);
+        }
+        return score;
+    }
+    /**
+     * Add a card to the queue. If already present, update its priority.
+     */
+    enqueue(card, column, labels, mode = "implement") {
+        const existing = this.items.findIndex((i) => i.cardId === card.id);
+        if (existing !== -1) {
+            log.debug(TAG, `Card #${card.short_id} already queued, updating priority`);
+            this.items.splice(existing, 1);
+        }
+        const priority = this.scoreCard(card, column, labels);
+        const item = {
+            cardId: card.id,
+            shortId: card.short_id,
+            title: card.title,
+            priority,
+            enqueuedAt: Date.now(),
+            mode,
+        };
+        // Insert in sorted position (highest priority first, FIFO tiebreak)
+        let insertIdx = this.items.length;
+        for (let i = 0; i < this.items.length; i++) {
+            if (priority > this.items[i].priority ||
+                (priority === this.items[i].priority &&
+                    item.enqueuedAt < this.items[i].enqueuedAt)) {
+                insertIdx = i;
+                break;
+            }
+        }
+        this.items.splice(insertIdx, 0, item);
+        log.info(TAG, `Enqueued #${card.short_id} "${card.title}" (priority=${priority}, pos=${insertIdx}, queue=${this.items.length})`);
+    }
+    /**
+     * Remove and return the highest-priority item.
+     */
+    dequeue() {
+        return this.items.shift() ?? null;
+    }
+    /**
+     * Remove a specific card from the queue.
+     */
+    remove(cardId) {
+        const idx = this.items.findIndex((i) => i.cardId === cardId);
+        if (idx === -1)
+            return null;
+        const [item] = this.items.splice(idx, 1);
+        log.info(TAG, `Removed #${item.shortId} from queue`);
+        return item;
+    }
+    /**
+     * Check if a card is in the queue.
+     */
+    has(cardId) {
+        return this.items.some((i) => i.cardId === cardId);
+    }
+    /**
+     * Get all queued card IDs.
+     */
+    cardIds() {
+        return this.items.map((i) => i.cardId);
+    }
+    get length() {
+        return this.items.length;
+    }
+    peek() {
+        return this.items[0] ?? null;
+    }
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,21 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Pool } from "./pool.js";
+/**
+ * Reconciliation heartbeat: polls the board every `intervalMs` to catch
+ * missed realtime events and sync state.
+ */
+export declare class Reconciler {
+    private client;
+    private pool;
+    private projectId;
+    private agentUserId;
+    private pickupColumns;
+    private reviewColumns;
+    private approvedLabel;
+    private intervalMs;
+    private timer;
+    constructor(client: HarmonyApiClient, pool: Pool, projectId: string, agentUserId: string, pickupColumns: string[], reviewColumns: string[], approvedLabel: string, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    private tick;
+}

package/dist/reconcile.js

@@ -0,0 +1,114 @@
+import { buildLabelMap, hasLabel, resolveCardLabels } from "./board-helpers.js";
+import { log } from "./log.js";
+import { NEED_REVIEW_LABEL } from "./types.js";
+const TAG = "reconcile";
+/**
+ * Reconciliation heartbeat: polls the board every `intervalMs` to catch
+ * missed realtime events and sync state.
+ */
+export class Reconciler {
+    client;
+    pool;
+    projectId;
+    agentUserId;
+    pickupColumns;
+    reviewColumns;
+    approvedLabel;
+    intervalMs;
+    timer = null;
+    constructor(client, pool, projectId, agentUserId, pickupColumns, reviewColumns, approvedLabel, intervalMs = 60_000) {
+        this.client = client;
+        this.pool = pool;
+        this.projectId = projectId;
+        this.agentUserId = agentUserId;
+        this.pickupColumns = pickupColumns;
+        this.reviewColumns = reviewColumns;
+        this.approvedLabel = approvedLabel;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        log.info(TAG, `Heartbeat every ${this.intervalMs / 1000}s`);
+        // Run immediately, then on interval
+        this.tick();
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        log.info(TAG, "Heartbeat stopped");
+    }
+    async tick() {
+        try {
+            const board = await this.client.getBoard(this.projectId);
+            const cards = (board.cards ?? []);
+            const columns = (board.columns ?? []);
+            // Build label lookup (id → Label) to resolve card.labelIds
+            const labelMap = buildLabelMap((board.labels ?? []));
+            // Build a lookup of columns by ID
+            const columnMap = new Map();
+            for (const col of columns) {
+                columnMap.set(col.id, col);
+            }
+            // Build column ID sets for both modes
+            const pickupColumnIds = new Set(columns
+                .filter((c) => this.pickupColumns.some((name) => name.toLowerCase() === c.name.toLowerCase()))
+                .map((c) => c.id));
+            const reviewColumnIds = new Set(columns
+                .filter((c) => this.reviewColumns.some((name) => name.toLowerCase() === c.name.toLowerCase()))
+                .map((c) => c.id));
+            // Find cards assigned to our agent in either pickup or review columns
+            const assignedCards = cards.filter((c) => c.assignee_id === this.agentUserId &&
+                !c.archived_at &&
+                (pickupColumnIds.has(c.column_id) ||
+                    reviewColumnIds.has(c.column_id)));
+            const knownCardIds = this.pool.knownCardIds();
+            // All cards still assigned to the agent (any column) — used to detect
+            // genuine unassigns without false-positiving on cards the worker moved
+            // to "In Progress" or other non-pickup columns.
+            const allAgentCardIds = new Set(cards
+                .filter((c) => c.assignee_id === this.agentUserId && !c.archived_at)
+                .map((c) => c.id));
+            // Cards assigned but NOT in queue/active → enqueue (missed event)
+            for (const card of assignedCards) {
+                if (!knownCardIds.has(card.id)) {
+                    const column = columnMap.get(card.column_id);
+                    if (!column)
+                        continue;
+                    const cardLabels = resolveCardLabels(card, labelMap);
+                    const subtasks = card.subtasks ?? [];
+                    // Determine mode based on which column set the card is in
+                    const mode = reviewColumnIds.has(card.column_id)
+                        ? "review"
+                        : "implement";
+                    // Skip already-approved cards in review mode
+                    if (mode === "review" &&
+                        this.approvedLabel &&
+                        hasLabel(cardLabels, this.approvedLabel)) {
+                        log.debug(TAG, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
+                        continue;
+                    }
+                    // Skip cards with "Need Review" label (awaiting human review)
+                    if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
+                        log.debug(TAG, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
+                        continue;
+                    }
+                    log.info(TAG, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
+                    this.pool.enqueue(card, column, cardLabels, subtasks, mode);
+                }
+            }
+            // Cards in queue/active but no longer assigned to agent → cancel/remove
+            for (const knownId of knownCardIds) {
+                if (!allAgentCardIds.has(knownId)) {
+                    log.info(TAG, `Missed unassign: ${knownId} — removing`);
+                    await this.pool.removeCard(knownId);
+                }
+            }
+            log.debug(TAG, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
+        }
+        catch (err) {
+            log.error(TAG, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}