@gethmy/agent 1.6.1 → 1.7.1

package/dist/review-completion.d.ts

@@ -32,9 +32,4 @@ export interface ReviewResult {
  *    bouncing it to To Do for a parse failure that isn't a code quality signal.
  */
 export declare function parseReviewOutput(stdout: string): ReviewResult;
-/**
- * Post-review completion pipeline.
- * 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 | undefined, runLogPath: string | null | undefined, workspaceId: string | undefined, agentSessionId: string | null | undefined, stateStore: StateStore): Promise<void>;

package/dist/review-completion.js

@@ -183,6 +183,18 @@ function stripReviewSummary(description) {
  * Handles approved/rejected verdicts, creates subtasks for findings,
  * and moves the card to the appropriate column.
  */
+/**
+ * Post a review verdict as a typed comment instead of mutating the card
+ * description (card-comments plan, Phase 3). Best-effort — never throws.
+ */
+async function postReviewComment(client, card, commentType, body) {
+    try {
+        await client.addComment(card.id, body, { commentType });
+    }
+    catch (err) {
+        log.error(TAG, `Failed to post review comment to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+    }
+}
 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;
@@ -208,32 +220,28 @@ export async function runReviewCompletion(client, card, result, config, worktree
             log.warn(TAG, `Failed to add "${NEED_REVIEW_LABEL}" label: ${err instanceof Error ? err.message : err}`);
         }
         if (config.review.postFindings) {
-            const baseDesc = stripReviewSummary(freshDesc);
             const rawTail = runLogPath ? tailRunLog(runLogPath) : null;
             // Log content routinely contains ```json fences from Claude's own
-            // output; embedding it inside a 3-backtick fence would break the card's
-            // markdown. Use a 4-backtick fence and downgrade any 4+-backtick runs.
+            // output; embedding it inside a 3-backtick fence would break markdown.
+            // Use a 4-backtick fence and downgrade any 4+-backtick runs.
             const runLogTail = rawTail
-                ? rawTail.replace(/`{4,}/g, (_m) => "`".repeat(3))
+                ? rawTail.replace(/`{4,}/g, () => "`".repeat(3))
                 : null;
             const runLogHint = runLogPath
-                ? `\nRun log: \`${runLogPath}\``
-                : "\nRun log: (not captured)";
-            const summary = [
-                `\n\n${REVIEW_MARKER} Parse error**`,
-                '\nThe review agent\'s output could not be parsed. Card stays in Review with the "Need Review" label — inspect the run log below to diagnose.',
+                ? `Run log: \`${runLogPath}\``
+                : "Run log: (not captured)";
+            const body = [
+                "**Review — parse error.**",
+                'The review agent\'s output could not be parsed. Card stays in Review with the "Need Review" label — inspect the run log below to diagnose.',
                 runLogHint,
-                result.summary ? `\n\nRaw output (truncated):\n${result.summary}` : "",
+                result.summary ? `Raw output (truncated):\n${result.summary}` : "",
                 runLogTail
-                    ? `\n\nRun log tail (last ${RUN_LOG_TAIL_BYTES}B):\n\`\`\`\`\n${runLogTail}\n\`\`\`\``
+                    ? `Run log tail (last ${RUN_LOG_TAIL_BYTES}B):\n\`\`\`\`\n${runLogTail}\n\`\`\`\``
                     : "",
-            ].join("");
-            try {
-                await client.updateCard(card.id, { description: baseDesc + summary });
-            }
-            catch (err) {
-                log.error(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
-            }
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            await postReviewComment(client, card, "blocker", body);
         }
         await client.endAgentSession(card.id, {
             status: "paused",
@@ -276,30 +284,23 @@ export async function runReviewCompletion(client, card, result, config, worktree
         }
         // Add "Ready to Merge" label
         await addLabelByName(client, card, config.review.approvedLabel, config.review.approvedLabelColor);
-        // Post approval summary (card stays in Review, strip stale cycle marker)
+        // Post the approval verdict as a decision comment (card stays in Review).
         if (config.review.postFindings) {
-            const baseDesc = stripReviewSummary(freshDesc).replace(/\n\nReview cycle:\s*\d+\/\d+/, "");
             const scopeLine = result.scopeCheck
-                ? `\nScope: ${result.scopeCheck.status}${result.scopeCheck.notes ? ` — ${result.scopeCheck.notes}` : ""}`
+                ? `Scope: ${result.scopeCheck.status}${result.scopeCheck.notes ? ` — ${result.scopeCheck.notes}` : ""}`
                 : "";
-            const summaryParts = [
-                `\n\n${REVIEW_MARKER} Approved**`,
-                result.summary ? `\n${result.summary}` : "",
+            const body = [
+                "**Review — approved.**",
+                result.summary || "",
                 scopeLine,
                 result.findings.length > 0
-                    ? `\n${result.findings.length} minor finding(s) noted.`
+                    ? `${result.findings.length} minor finding(s) noted.`
                     : "",
-            ];
-            if (prUrl) {
-                summaryParts.push(`\nPR: ${prUrl}`);
-            }
-            const summary = summaryParts.join("");
-            try {
-                await client.updateCard(card.id, { description: baseDesc + summary });
-            }
-            catch (err) {
-                log.error(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
-            }
+                prUrl ? `PR: ${prUrl}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            await postReviewComment(client, card, "decision", body);
         }
         await client.endAgentSession(card.id, {
             status: "completed",
@@ -324,18 +325,14 @@ export async function runReviewCompletion(client, card, result, config, worktree
         if (currentCycle >= maxCycles) {
             log.warn(TAG, `#${card.short_id} reached max review cycles (${maxCycles}), moving to Done with note`);
             await moveCardToColumn(client, card, config.review.moveToColumn);
-            const baseDesc = stripReviewSummary(freshDesc);
-            const summary = [
-                `\n\n${REVIEW_MARKER} Needs human review**`,
-                `\nReached max review cycles (${maxCycles}). Please review manually.`,
-                result.summary ? `\n${result.summary}` : "",
-            ].join("");
-            try {
-                await client.updateCard(card.id, { description: baseDesc + summary });
-            }
-            catch (err) {
-                log.error(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
-            }
+            const body = [
+                "**Review — needs human review.**",
+                `Reached max review cycles (${maxCycles}). Please review manually.`,
+                result.summary || "",
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            await postReviewComment(client, card, "blocker", body);
             await client.endAgentSession(card.id, {
                 status: "completed",
                 ...buildTokenPayload(sessionStats),
@@ -396,26 +393,30 @@ export async function runReviewCompletion(client, card, result, config, worktree
                     log.error(TAG, `Failed to create subtask: ${err instanceof Error ? err.message : err}`);
                 }
             }));
-            // Update description with review summary and cycle counter
+            // The review cycle counter stays in the description — it is functional
+            // state used to enforce maxReviewCycles, not narrative. (This also strips
+            // any legacy summary block from the description.) The review narrative
+            // goes to a summary comment instead.
             const baseDesc = stripReviewSummary(freshDesc);
             const updatedDesc = updateReviewCycleMarker(baseDesc, currentCycle, maxCycles);
-            const scopeLine = result.scopeCheck
-                ? `\nScope: ${result.scopeCheck.status}${result.scopeCheck.notes ? ` — ${result.scopeCheck.notes}` : ""}`
-                : "";
-            const summary = [
-                `\n\n${REVIEW_MARKER} Rejected**`,
-                result.summary ? `\n${result.summary}` : "",
-                scopeLine,
-                `\n${criticalFindings.length} critical, ${majorFindings.length} major, ${minorFindings.length} minor finding(s).`,
-            ].join("");
             try {
-                await client.updateCard(card.id, {
-                    description: updatedDesc + summary,
-                });
+                await client.updateCard(card.id, { description: updatedDesc });
             }
             catch (err) {
-                log.error(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
+                log.error(TAG, `Failed to update review cycle marker: ${err instanceof Error ? err.message : err}`);
             }
+            const scopeLine = result.scopeCheck
+                ? `Scope: ${result.scopeCheck.status}${result.scopeCheck.notes ? ` — ${result.scopeCheck.notes}` : ""}`
+                : "";
+            const body = [
+                "**Review — rejected.**",
+                result.summary || "",
+                scopeLine,
+                `${criticalFindings.length} critical, ${majorFindings.length} major, ${minorFindings.length} minor finding(s).`,
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            await postReviewComment(client, card, "summary", body);
         }
         // Move back to failColumn (To Do) for re-implementation
         await moveCardToColumn(client, card, config.review.failColumn);

package/dist/startup-banner.js

@@ -104,7 +104,7 @@ function configRows(config, projectName, gitProvider) {
     rows.push({ label: "User", value: config.userEmail });
     const reviewEnabled = config.agent.review.enabled;
     const poolDesc = reviewEnabled
-        ? `Pool ${config.agent.poolSize} impl + 1 review`
+        ? `Pool ${config.agent.poolSize} impl + ${config.agent.review.poolSize} review`
         : `Pool ${config.agent.poolSize} impl`;
     const flowDesc = reviewEnabled
         ? `Pickup ${config.agent.pickupColumns[0]} → ${config.agent.completion.moveToColumn} → ${config.agent.review.moveToColumn}`

package/dist/state-store.d.ts

@@ -28,8 +28,6 @@ export interface CardRecord {
     cardId: string;
     attempts: number;
     totalCostCents: number;
-    dlq: boolean;
-    dlqReason?: string;
     lastAttemptAt: number | null;
     lastOutcome: "success" | "failure" | null;
     failureHistory?: FailureSummaryRecord[];
@@ -70,9 +68,16 @@ export declare class StateStore {
     getCard(cardId: string): CardRecord | null;
     incrementAttempt(cardId: string): Promise<number>;
     recordOutcome(cardId: string, outcome: "success" | "failure"): Promise<void>;
+    /**
+     * Reset a card's attempt counter so a card that previously gave up
+     * (attempts >= maxAttemptsPerCard) becomes eligible again. Called when a
+     * card is unassigned/reassigned — reassignment is the human's "try again".
+     * No-op for an unknown card.
+     */
+    resetAttempts(cardId: string): 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
+     * capped at 5). Read back by the give-up comment and the Agent History
      * UI section to give users a post-mortem trail across attempts.
      */
     recordFailureSummary(cardId: string, entry: Omit<FailureSummaryRecord, "ts"> & {
@@ -81,8 +86,4 @@ export declare class StateStore {
     getRecentFailures(cardId: string, limit?: number): FailureSummaryRecord[];
     addCost(cardId: string, cents: number): Promise<void>;
     getDailyCostCents(date?: string): number;
-    markDlq(cardId: string, reason: string): Promise<void>;
-    clearDlq(cardId: string): Promise<void>;
-    isDlq(cardId: string): boolean;
-    listDlq(): CardRecord[];
 }

package/dist/state-store.js

@@ -145,7 +145,6 @@ export class StateStore {
                 cardId,
                 attempts: 0,
                 totalCostCents: 0,
-                dlq: false,
                 lastAttemptAt: null,
                 lastOutcome: null,
             };
@@ -170,9 +169,22 @@ export class StateStore {
             rec.attempts = 0;
         await this.persist();
     }
+    /**
+     * Reset a card's attempt counter so a card that previously gave up
+     * (attempts >= maxAttemptsPerCard) becomes eligible again. Called when a
+     * card is unassigned/reassigned — reassignment is the human's "try again".
+     * No-op for an unknown card.
+     */
+    async resetAttempts(cardId) {
+        const rec = this.getCard(cardId);
+        if (!rec || rec.attempts === 0)
+            return;
+        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
+     * capped at 5). Read back by the give-up comment and the Agent History
      * UI section to give users a post-mortem trail across attempts.
      */
     async recordFailureSummary(cardId, entry) {
@@ -215,25 +227,4 @@ export class StateStore {
         const key = date ?? todayUtc();
         return this.state.daily.find((d) => d.date === key)?.costCents ?? 0;
     }
-    // ---------- DLQ ----------
-    async markDlq(cardId, reason) {
-        const rec = this.ensureCard(cardId);
-        rec.dlq = true;
-        rec.dlqReason = reason;
-        await this.persist();
-    }
-    async clearDlq(cardId) {
-        const rec = this.getCard(cardId);
-        if (!rec)
-            return;
-        rec.dlq = false;
-        delete rec.dlqReason;
-        await this.persist();
-    }
-    isDlq(cardId) {
-        return this.getCard(cardId)?.dlq === true;
-    }
-    listDlq() {
-        return this.state.cards.filter((c) => c.dlq);
-    }
 }

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export interface AgentConfig {
     };
     review: {
         enabled: boolean;
+        /** Concurrent review workers. Each gets its own dev-server port slot. */
+        poolSize: number;
         pickupColumns: string[];
         moveToColumn: string;
         failColumn: string;
@@ -55,15 +57,13 @@ export interface AgentConfig {
         mergedLabelColor: string;
     };
     budget: {
-        /** Max implement attempts per card before DLQ (reset on success). */
+        /**
+         * Max implement attempts per card before the daemon gives up (resets on
+         * success and on reassign). Repeated verification failures count.
+         */
         maxAttemptsPerCard: number;
-        /** Max cumulative spend per card, in cents, before DLQ. */
-        maxCentsPerCard: number;
         /** Daily spend cap, in cents (UTC day). Exceeded → pause pickups. */
         dailyBudgetCents: number;
-        /** Label applied to DLQ'd cards. */
-        dlqLabel: string;
-        dlqLabelColor: string;
     };
     http: {
         /** Local HTTP status/control server. Bound to 127.0.0.1 by default. */
@@ -129,6 +129,35 @@ export interface EpisodeMeta {
     files_touched: number;
     num_turns: number;
     error?: string;
+    /**
+     * Changed file paths for the run (#272). Capped (default first 30). Prefer
+     * the diff's authoritative list; falls back to ProgressTracker-tracked edit
+     * paths when a diff is unavailable.
+     */
+    changed_files?: string[];
+    /** Line churn for the run (#272), best-effort from `git diff --numstat`. */
+    churn?: {
+        insertions: number;
+        deletions: number;
+    };
+    /**
+     * Cheap deterministic root-cause / gotcha line extracted from the run's
+     * assistant text (#272). No LLM call — left unset when nothing matches.
+     */
+    key_insight?: string;
+    /**
+     * Provenance record (#273). Agent episodes are always `source: 'agent-run'`.
+     * Mirrors the `MemoryOrigin` shape stamped by `harmony_remember`; lives in
+     * metadata jsonb (no dedicated column). Input for provenance badges and
+     * auto-vs-curated hygiene filtering.
+     */
+    origin?: {
+        source: "manual" | "assistant" | "agent-run" | "import";
+        source_card_id?: string;
+        source_session_id?: string;
+        author?: string;
+        source_trust?: string;
+    };
     /** Provenance only — never used as memory scope. */
     agent_session_id?: string;
     /** Set on back-fill from review pipeline. */

package/dist/types.js

@@ -1,5 +1,5 @@
 export const DEFAULT_AGENT_CONFIG = {
-    poolSize: 1,
+    poolSize: 3,
     maxTimeout: 1_800_000, // 30 minutes
     pickupColumns: ["To Do"],
     priorityLabels: { urgent: 100, critical: 90, bug: 50 },
@@ -35,6 +35,7 @@ export const DEFAULT_AGENT_CONFIG = {
     },
     review: {
         enabled: true,
+        poolSize: 2,
         pickupColumns: ["Review"],
         moveToColumn: "Done",
         failColumn: "To Do",
@@ -51,10 +52,7 @@ export const DEFAULT_AGENT_CONFIG = {
     },
     budget: {
         maxAttemptsPerCard: 3,
-        maxCentsPerCard: 500, // $5.00
         dailyBudgetCents: 5000, // $50.00
-        dlqLabel: "dlq",
-        dlqLabelColor: "#dc2626",
     },
     http: {
         enabled: true,

package/dist/worker.d.ts

@@ -21,6 +21,7 @@ export declare class Worker {
     private progressTracker;
     private lastSessionStats;
     private aborted;
+    private verificationFailed;
     private sessionId;
     private runId;
     constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: Worker) => void, workspaceId: string, projectId: string, stateStore: StateStore);

package/dist/worker.js

@@ -1,4 +1,5 @@
 import { moveCardAndAddLabel } from "./board-helpers.js";
+import { buildGaveUpComment } from "./budget.js";
 import { buildTokenPayload, runCompletion, } from "./completion.js";
 import { log } from "./log.js";
 import { signalGroup, spawnInGroup, terminateGroup } from "./process-group.js";
@@ -32,6 +33,7 @@ export class Worker {
     progressTracker = null;
     lastSessionStats;
     aborted = false;
+    verificationFailed = false;
     sessionId = null;
     runId = null;
     constructor(id, config, client, _userEmail, onDone, workspaceId, projectId, stateStore) {
@@ -96,6 +98,7 @@ export class Worker {
      */
     async run(card, column, labels, subtasks) {
         this.aborted = false;
+        this.verificationFailed = false;
         this.cardId = card.id;
         this.startedAt = Date.now();
         this.runId = newRunId();
@@ -104,7 +107,7 @@ export class Worker {
             this.state = "preparing";
             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.
+            // Per-card attempt counter resets on success; give-up triggers off it.
             await this.stateStore.incrementAttempt(card.id);
             // Start the heartbeat loop so the reconciler knows this run is
             // still alive even if no phase transitions happen for a while
@@ -195,7 +198,12 @@ 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, this.stateStore);
+            const completed = await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id, this.lastSessionStats, this.workspaceId, this.sessionId, this.stateStore);
+            // A verification failure is a failed attempt, not a success — even
+            // though runCompletion returns normally (it has already moved the card
+            // to the fail column and ended the session). Flag it so the finally
+            // block records a failure and counts it toward the give-up budget.
+            this.verificationFailed = !completed;
         }
         catch (err) {
             this.state = "error";
@@ -228,8 +236,11 @@ export class Worker {
             // Only bookkeep success when we actually succeeded. "cancelling"
             // and aborted runs are failures/user-initiated stops, not wins —
             // counting them as success would reset attempts and mask real
-            // failure loops.
-            const succeeded = this.runId && this.state !== "error" && !this.aborted;
+            // failure loops. A verification failure is likewise a failed attempt.
+            const succeeded = this.runId &&
+                this.state !== "error" &&
+                !this.aborted &&
+                !this.verificationFailed;
             if (succeeded) {
                 try {
                     await this.stateStore.endRun(this.runId, "completed");
@@ -249,6 +260,18 @@ export class Worker {
                     // best-effort
                 }
             }
+            else if (this.runId && this.verificationFailed) {
+                // Verification failed (no exception was thrown). Count it as a
+                // failed attempt so repeated failures eventually trip the give-up
+                // budget — runCompletion already moved the card + ended the session.
+                try {
+                    await this.stateStore.endRun(this.runId, "paused", "verification");
+                }
+                catch {
+                    // best-effort
+                }
+                await this.recordOutcome(card.id, "failure");
+            }
             this.cleanup();
             this.state = "idle";
             this.onDone(this);
@@ -262,6 +285,26 @@ export class Worker {
                 await this.stateStore.addCost(cardId, cents);
             }
             await this.stateStore.recordOutcome(cardId, outcome);
+            // Give-up: if this failure exhausted the attempt budget, post a single
+            // human-facing comment here at the crossing. The pool guard then skips
+            // the card quietly until it is reassigned (which resets attempts), so
+            // this fires exactly once — no permanent DLQ, no label, no manual clear.
+            if (outcome === "failure") {
+                const max = this.config.budget.maxAttemptsPerCard;
+                const attempts = this.stateStore.getCard(cardId)?.attempts ?? 0;
+                if (attempts >= max) {
+                    try {
+                        const body = buildGaveUpComment(max, this.stateStore.getRecentFailures(cardId, 3));
+                        await this.client.addComment(cardId, body, {
+                            commentType: "blocker",
+                        });
+                        log.warn(this.tag, `gave up on ${cardId} after ${attempts} attempts`);
+                    }
+                    catch (err) {
+                        log.warn(this.tag, `failed to post give-up comment for ${cardId}: ${err instanceof Error ? err.message : err}`);
+                    }
+                }
+            }
         }
         catch (err) {
             log.warn(this.tag, `recordOutcome(${outcome}) failed: ${err instanceof Error ? err.message : err}`);

package/package.json

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