@gethmy/agent 1.6.1 → 1.7.1

package/dist/episode-writer.js

@@ -1,6 +1,12 @@
 import { log } from "./log.js";
 const TAG = "episode-writer";
 const MAX_APPROACH_SUMMARY_CHARS = 400;
+// Richer approach summary cap (#272). The single-turn trim used a 400-char cap;
+// the assembled multi-block summary is allowed to run longer but stays bounded
+// so it doesn't bloat the recall prompt.
+const MAX_RICH_APPROACH_CHARS = 1500;
+// Cap on the changed-file list persisted per episode (#272).
+const MAX_CHANGED_FILES = 30;
 /**
  * Rule-derived quality score (0..1) for an implement run. Failures default to 0.
  * Plan §"Quality score": +0.4 if build passed, +0.2 if lint passed, +0.2 if no
@@ -41,6 +47,75 @@ export function trimApproachSummary(text) {
         return trimmed;
     return `${trimmed.slice(0, MAX_APPROACH_SUMMARY_CHARS - 1).trimEnd()}…`;
 }
+// Review rationale cap (#272 task 5). The reviewer's verdict reasoning is the
+// signal we want recallable, so it gets a far higher cap than the 400-char
+// implement trim (the upstream review summary is already sliced to ~2000).
+const MAX_REVIEW_RATIONALE_CHARS = 2000;
+/**
+ * Cap the review rationale ("why approved / rejected") richly (#272 task 5)
+ * rather than re-trimming to the 400-char implement bound. Empty input
+ * collapses to a marker so the episode still surfaces as a recallable hit.
+ */
+export function trimReviewRationale(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "(no review rationale captured)";
+    if (trimmed.length <= MAX_REVIEW_RATIONALE_CHARS)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_REVIEW_RATIONALE_CHARS - 1).trimEnd()}…`;
+}
+// Lines that read like a root-cause / gotcha / lesson — used to surface a cheap
+// deterministic `key_insight` without an LLM call (#272 task 3).
+const INSIGHT_RE = /\b(root cause|turned out|the (?:issue|problem|bug) (?:was|is)|the fix (?:was|is)|gotcha|caused by|because|the key (?:was|insight)|note that|caveat|the trick (?:was|is))\b/i;
+/**
+ * Assemble a richer approach summary from the collected assistant text blocks
+ * (#272). Joins the trailing blocks (most relevant context lives near the end
+ * of a run) up to a longer bounded cap than the single-turn trim. Falls back to
+ * the last-turn `fallback` text when no blocks were collected. No LLM call.
+ */
+export function buildRichApproachSummary(blocks, fallback) {
+    const cleaned = (blocks ?? [])
+        .map((b) => b.trim())
+        .filter((b) => b.length > 0);
+    if (cleaned.length === 0)
+        return trimApproachSummary(fallback);
+    // Walk backwards accumulating blocks until we hit the cap, then restore order.
+    const picked = [];
+    let total = 0;
+    for (let i = cleaned.length - 1; i >= 0; i--) {
+        const block = cleaned[i];
+        const cost = block.length + (picked.length > 0 ? 2 : 0);
+        if (total + cost > MAX_RICH_APPROACH_CHARS && picked.length > 0)
+            break;
+        picked.unshift(block);
+        total += cost;
+        if (total >= MAX_RICH_APPROACH_CHARS)
+            break;
+    }
+    const joined = picked.join("\n\n").trim();
+    if (joined.length === 0)
+        return trimApproachSummary(fallback);
+    if (joined.length <= MAX_RICH_APPROACH_CHARS)
+        return joined;
+    return `${joined.slice(0, MAX_RICH_APPROACH_CHARS - 1).trimEnd()}…`;
+}
+/**
+ * Extract a cheap deterministic "key insight" line from the run's assistant
+ * text (#272 task 3). Scans for a sentence/line matching a root-cause / gotcha
+ * pattern. Returns undefined when nothing matches — never fabricated, no LLM.
+ */
+export function extractKeyInsight(blocks, fallback) {
+    const source = blocks && blocks.length > 0 ? blocks.join("\n") : fallback;
+    const lines = source
+        .split(/\n|(?<=[.!?])\s+/)
+        .map((l) => l.trim())
+        .filter((l) => l.length >= 20 && l.length <= 280);
+    for (const line of lines) {
+        if (INSIGHT_RE.test(line))
+            return line;
+    }
+    return undefined;
+}
 /**
  * Build the entity payload for one episode. Pure — returned object can be
  * snapshotted in tests without hitting the network.
@@ -53,7 +128,11 @@ export function buildEpisodePayload(input, projectId) {
         });
         const type = input.outcome === "success" ? "solution" : "error";
         const importance = input.outcome === "success" ? 7 : 5;
-        const approachSummary = trimApproachSummary(input.approachSummary);
+        // Richer approach summary (#272): assemble from all collected assistant
+        // blocks when available; fall back to the single last-turn trim otherwise.
+        const approachSummary = buildRichApproachSummary(input.approachBlocks, input.approachSummary);
+        const keyInsight = extractKeyInsight(input.approachBlocks, input.approachSummary);
+        const changedFiles = (input.changedFiles ?? []).slice(0, MAX_CHANGED_FILES);
         const outcomeRationale = input.outcome === "success"
             ? `Build ${input.result.buildErrors.length === 0 ? "passed" : "failed"}, lint ${input.result.lintWarnings.length === 0 ? "clean" : "issues"}.`
             : `Verification failed: ${input.errorMessage ?? "see findings"}.`;
@@ -72,11 +151,32 @@ export function buildEpisodePayload(input, projectId) {
             },
             files_touched: input.filesEdited,
             num_turns: input.cost?.numTurns ?? 0,
+            // Provenance (#273, task 3). Agent episodes are always agent-run; stamp
+            // the card + session ids we already carry so downstream hygiene + UI can
+            // tell auto-written episodes from human-curated patterns.
+            origin: {
+                source: "agent-run",
+                source_card_id: input.card.id,
+                author: "harmony-agent",
+                ...(input.agentSessionId
+                    ? { source_session_id: input.agentSessionId }
+                    : {}),
+            },
         };
         if (input.errorMessage)
             metadata.error = input.errorMessage;
+        if (changedFiles.length > 0)
+            metadata.changed_files = changedFiles;
+        if (input.churn)
+            metadata.churn = input.churn;
+        if (keyInsight)
+            metadata.key_insight = keyInsight;
         if (input.agentSessionId)
             metadata.agent_session_id = input.agentSessionId;
+        const changedFilesLine = changedFiles.length > 0
+            ? `\n\nChanged files (${changedFiles.length}): ${changedFiles.join(", ")}`
+            : "";
+        const keyInsightLine = keyInsight ? `\n\nKey insight: ${keyInsight}` : "";
         return {
             workspace_id: input.workspaceId,
             project_id: projectId,
@@ -84,7 +184,7 @@ export function buildEpisodePayload(input, projectId) {
             memory_tier: "episode",
             scope: "project",
             title: `Agent run implement — #${input.card.short_id}: ${input.card.title}`,
-            content: `${approachSummary}\n\nOutcome: ${outcomeRationale}`,
+            content: `${approachSummary}\n\nOutcome: ${outcomeRationale}${keyInsightLine}${changedFilesLine}`,
             metadata,
             importance,
             confidence: clampConfidence(qualityScore),
@@ -94,7 +194,7 @@ export function buildEpisodePayload(input, projectId) {
     }
     // Review episode
     const qualityScore = input.verdict === "approved" ? 1 : 0.4;
-    const summary = trimApproachSummary(input.summary || "(no summary captured)");
+    const summary = trimReviewRationale(input.summary || "");
     const metadata = {
         episode_kind: "review",
         card_short_id: input.card.short_id,
@@ -110,6 +210,19 @@ export function buildEpisodePayload(input, projectId) {
         },
         files_touched: 0,
         num_turns: input.cost?.numTurns ?? 0,
+        // Provenance (#273, task 3). Review episodes are agent-run too. Prefer the
+        // review session id as the originating session when present.
+        origin: {
+            source: "agent-run",
+            source_card_id: input.card.id,
+            author: "harmony-agent",
+            ...((input.reviewSessionId ?? input.agentSessionId)
+                ? {
+                    source_session_id: (input.reviewSessionId ??
+                        input.agentSessionId),
+                }
+                : {}),
+        },
     };
     if (input.agentSessionId)
         metadata.agent_session_id = input.agentSessionId;
@@ -132,6 +245,10 @@ export function buildEpisodePayload(input, projectId) {
         agent_identifier: "harmony-agent",
     };
 }
+// DEFERRED (#272 task 6, on-plan): an optional best-effort Claude-CLI
+// distillation of the approach summary / key insight is explicitly out of scope
+// for this pass — no Anthropic SDK, no extra LLM spawn. The deterministic
+// assembly above is the v1 surface; revisit distillation in a later card.
 /**
  * Write one episode entity. Best-effort: any failure is logged and swallowed
  * so the calling pipeline can complete (plan D8: episode writes never block

package/dist/git-diff-stat.d.ts

@@ -0,0 +1,24 @@
+/** Default cap on the number of changed-file paths captured per episode. */
+export declare const MAX_CHANGED_FILES = 30;
+export interface DiffStat {
+    /** Changed file paths (authoritative — derived from the diff itself). */
+    files: string[];
+    /** Total lines added across the diff (best-effort, may be 0). */
+    insertions: number;
+    /** Total lines removed across the diff (best-effort, may be 0). */
+    deletions: number;
+}
+/**
+ * Parse `git diff --numstat` output into a changed-file list + churn totals.
+ * Pure — exported for testing. numstat lines look like:
+ *   `12\t3\tpath/to/file.ts`
+ * Binary files report `-\t-\t<path>`; those contribute 0 churn but still count
+ * as a changed file. The file list is capped at `maxFiles`.
+ */
+export declare function parseNumstat(raw: string, maxFiles?: number): DiffStat;
+/**
+ * Capture a changed-file list + churn for the work on a branch versus its base,
+ * via `git diff --numstat`. Best-effort and guarded: returns null on any
+ * failure so callers can fall back to tracked paths (#272). Never throws.
+ */
+export declare function captureDiffStat(worktreePath: string, baseBranch: string, maxFiles?: number): DiffStat | null;

package/dist/git-diff-stat.js

@@ -0,0 +1,56 @@
+import { execFileSync } from "node:child_process";
+import { log } from "./log.js";
+const TAG = "git-diff-stat";
+/** Default cap on the number of changed-file paths captured per episode. */
+export const MAX_CHANGED_FILES = 30;
+/**
+ * Parse `git diff --numstat` output into a changed-file list + churn totals.
+ * Pure — exported for testing. numstat lines look like:
+ *   `12\t3\tpath/to/file.ts`
+ * Binary files report `-\t-\t<path>`; those contribute 0 churn but still count
+ * as a changed file. The file list is capped at `maxFiles`.
+ */
+export function parseNumstat(raw, maxFiles = MAX_CHANGED_FILES) {
+    const files = [];
+    let insertions = 0;
+    let deletions = 0;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parts = trimmed.split("\t");
+        if (parts.length < 3)
+            continue;
+        const [add, del, ...pathParts] = parts;
+        const path = pathParts.join("\t");
+        if (!path)
+            continue;
+        const addN = Number.parseInt(add, 10);
+        const delN = Number.parseInt(del, 10);
+        if (Number.isFinite(addN))
+            insertions += addN;
+        if (Number.isFinite(delN))
+            deletions += delN;
+        if (files.length < maxFiles)
+            files.push(path);
+    }
+    return { files, insertions, deletions };
+}
+/**
+ * Capture a changed-file list + churn for the work on a branch versus its base,
+ * via `git diff --numstat`. Best-effort and guarded: returns null on any
+ * failure so callers can fall back to tracked paths (#272). Never throws.
+ */
+export function captureDiffStat(worktreePath, baseBranch, maxFiles = MAX_CHANGED_FILES) {
+    try {
+        const raw = execFileSync("git", ["diff", "--numstat", `${baseBranch}...HEAD`], { cwd: worktreePath, encoding: "utf-8", timeout: 30_000 });
+        return parseNumstat(raw, maxFiles);
+    }
+    catch (err) {
+        log.warn(TAG, "git diff --numstat failed", {
+            event: "diff_stat_failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}

package/dist/http-server.d.ts

@@ -30,12 +30,6 @@ export interface StatusSnapshot {
         priority: number;
         enqueuedAt: number;
     }>;
-    dlq: Array<{
-        cardId: string;
-        reason: string;
-        attempts: number;
-        totalCostCents: number;
-    }>;
     budget: {
         todayCents: number;
         dailyCapCents: number;
@@ -48,12 +42,6 @@ export interface HttpServerOptions {
     getStatus: () => StatusSnapshot;
     getHealth: () => HealthSnapshot;
     handleCommand: (cmd: Command, cardId: string) => Promise<void>;
-    /**
-     * Clear a card's DLQ marker. Routed through the daemon (not CLI
-     * direct-write) so we never have two processes racing to persist
-     * the same state-store file.
-     */
-    clearDlq: (cardId: string) => Promise<void>;
 }
 /**
  * Tiny introspection + control surface for the running daemon.
@@ -61,7 +49,7 @@ export interface HttpServerOptions {
  *
  * GET /health — 200 when healthy, 503 otherwise. Simple liveness check
  *   suitable for process supervisors (systemd, pm2, docker healthcheck).
- * GET /status — full JSON snapshot: workers, queues, DLQ, budget.
+ * GET /status — full JSON snapshot: workers, queues, budget.
  * POST /pause/:cardId, /resume/:cardId, /stop/:cardId — command path
  *   so an operator can nudge a stuck worker without killing the daemon.
  */
@@ -72,7 +60,6 @@ export declare class HttpServer {
     start(): Promise<void>;
     stop(): Promise<void>;
     private route;
-    private respondDlqClear;
     private respondHealth;
     private respondStatus;
     private respondCommand;

package/dist/http-server.js

@@ -7,7 +7,7 @@ const TAG = "http";
  *
  * GET /health — 200 when healthy, 503 otherwise. Simple liveness check
  *   suitable for process supervisors (systemd, pm2, docker healthcheck).
- * GET /status — full JSON snapshot: workers, queues, DLQ, budget.
+ * GET /status — full JSON snapshot: workers, queues, budget.
  * POST /pause/:cardId, /resume/:cardId, /stop/:cardId — command path
  *   so an operator can nudge a stuck worker without killing the daemon.
  */
@@ -53,10 +53,6 @@ export class HttpServer {
             return this.respondStatus(res);
         }
         if (method === "POST") {
-            const dlq = path.match(/^\/dlq\/clear\/([^/]+)$/);
-            if (dlq) {
-                return this.respondDlqClear(res, decodeURIComponent(dlq[1]));
-            }
             const cmd = parseCommand(path);
             if (cmd) {
                 return this.respondCommand(res, cmd.command, cmd.cardId);
@@ -65,20 +61,6 @@ export class HttpServer {
         res.writeHead(404, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: "not_found", path }));
     }
-    async respondDlqClear(res, cardId) {
-        try {
-            await this.opts.clearDlq(cardId);
-            res.writeHead(200, { "content-type": "application/json" });
-            res.end(JSON.stringify({ ok: true, cardId }));
-        }
-        catch (err) {
-            res.writeHead(500, { "content-type": "application/json" });
-            res.end(JSON.stringify({
-                error: "clear_dlq_failed",
-                detail: err instanceof Error ? err.message : String(err),
-            }));
-        }
-    }
     respondHealth(res) {
         const health = this.opts.getHealth();
         res.writeHead(health.healthy ? 200 : 503, {

package/dist/index.js

@@ -173,12 +173,6 @@ export async function main() {
             },
             getStatus: () => {
                 const queues = pool.snapshotQueues();
-                const dlq = stateStore.listDlq().map((c) => ({
-                    cardId: c.cardId,
-                    reason: c.dlqReason ?? "unknown",
-                    attempts: c.attempts,
-                    totalCostCents: c.totalCostCents,
-                }));
                 return {
                     daemonId,
                     daemonPid: process.pid,
@@ -200,7 +194,6 @@ export async function main() {
                         priority: i.priority,
                         enqueuedAt: i.enqueuedAt,
                     })),
-                    dlq,
                     budget: {
                         todayCents: stateStore.getDailyCostCents(),
                         dailyCapCents: config.agent.budget.dailyBudgetCents,
@@ -208,7 +201,6 @@ export async function main() {
                 };
             },
             handleCommand: (cmd, cardId) => pool.handleAgentCommand(cardId, cmd),
-            clearDlq: (cardId) => stateStore.clearDlq(cardId),
         })
         : null;
     // Create watcher (broadcast events from harmony-api + agent commands from UI)
@@ -267,7 +259,9 @@ export async function main() {
     }
     // Banner check lines for service intervals + pool. Compose into one
     // line each so the banner stays compact.
-    const reviewCount = config.agent.review.enabled ? 1 : 0;
+    const reviewCount = config.agent.review.enabled
+        ? config.agent.review.poolSize
+        : 0;
     banner.check(`Pool: ${config.agent.poolSize} impl${reviewCount > 0 ? ` + ${reviewCount} review` : ""}`);
     const services = [
         `Heartbeat ${config.agent.timing.reconcileIntervalMs / 1000}s`,
@@ -369,4 +363,4 @@ async function tryEnqueueCard(cardId, client, pool, config) {
     await pool.enqueue(card, column, cardLabels, subtasks, mode);
 }
 // The daemon is now launched from cli.ts so other subcommands
-// (status, doctor, gc, dlq) can load this module without side effects.
+// (status, doctor, gc) can load this module without side effects.

package/dist/pool.d.ts

@@ -5,6 +5,7 @@ import type { StateStore } from "./state-store.js";
 import { type AgentConfig, type WorkMode } from "./types.js";
 export declare class Pool {
     private client;
+    private stateStore;
     private implWorkers;
     private reviewWorkers;
     private implQueue;
@@ -14,9 +15,9 @@ export declare class Pool {
     /**
      * 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.
+     * Returns async so callers can await the give-up comment / waiting
+     * signal on skip. Budget 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): Promise<void>;
     /**

package/dist/pool.js

@@ -7,6 +7,7 @@ import { Worker } from "./worker.js";
 const TAG = "pool";
 export class Pool {
     client;
+    stateStore;
     implWorkers = [];
     reviewWorkers = [];
     implQueue;
@@ -14,29 +15,34 @@ export class Pool {
     budget;
     constructor(config, client, userEmail, workspaceId, projectId, stateStore) {
         this.client = client;
+        this.stateStore = stateStore;
         this.implQueue = new PriorityQueue(config);
         this.reviewQueue = new PriorityQueue(config);
-        this.budget = new BudgetGuard(config.budget, stateStore);
+        this.budget = new BudgetGuard(config.budget, this.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, stateStore));
         }
-        // Create review worker(s) — 1 review worker per pool
+        // Create review workers. IDs offset by `config.poolSize` so impl and
+        // review worker IDs never collide (verification + review ports both
+        // derive from the worker ID, so collision would mean port collision).
         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, workspaceId, projectId));
+            for (let i = 0; i < config.review.poolSize; i++) {
+                const reviewWorkerId = config.poolSize + i;
+                this.reviewWorkers.push(new ReviewWorker(reviewWorkerId, config, client, userEmail, () => {
+                    this.tryDispatchFor(this.reviewWorkers, this.reviewQueue, "review");
+                }, stateStore, workspaceId, projectId));
+            }
         }
     }
     /**
      * 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.
+     * Returns async so callers can await the give-up comment / waiting
+     * signal on skip. Budget checks happen here so the reconciler, realtime
+     * watcher, and manual API calls all go through the same gate.
      */
     async enqueue(card, column, labels, subtasks, mode = "implement") {
         // Don't enqueue if already in any queue or actively being worked on
@@ -51,22 +57,18 @@ export class Pool {
         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 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})`);
-                    }
+                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.
+                    log.warn(TAG, `#${card.short_id} skipped (daily_budget): ${decision.detail}`);
+                    await this.emitWaiting(card.id, `Daily budget reached — waiting for reset (${decision.detail})`);
                 }
                 else {
-                    log.debug(TAG, `#${card.short_id} in DLQ: ${decision.detail}`);
+                    // max_attempts: the daemon has given up on this card. The worker
+                    // already posted the one-shot give-up comment at the crossing, so
+                    // every later reconcile tick is expected noise — stay quiet until
+                    // the card is reassigned (which resets the attempt counter).
+                    log.debug(TAG, `#${card.short_id} gave up: ${decision.detail}`);
                 }
                 return;
             }
@@ -109,6 +111,9 @@ export class Pool {
      * Remove a card from any queue or cancel an active worker.
      */
     async removeCard(cardId) {
+        // Unassigning is the human's "try again" signal — clear any exhausted
+        // attempt counter so a reassign starts the card fresh (no DLQ to clear).
+        await this.stateStore.resetAttempts(cardId);
         // Try both queues
         for (const queue of [this.implQueue, this.reviewQueue]) {
             const removed = queue.remove(cardId);

package/dist/progress-tracker.d.ts

@@ -31,6 +31,7 @@ export declare class ProgressTracker {
     private logBuffer;
     private sessionId;
     private lastAssistantText;
+    private assistantTextBlocks;
     constructor(client: HarmonyApiClient, cardId: string, workerId: number, subtasks: {
         completed: boolean;
     }[]);
@@ -46,10 +47,12 @@ export declare class ProgressTracker {
     /** Get a summary of the session stats. */
     get stats(): {
         filesEdited: number;
+        filesEditedPaths: string[];
         filesRead: number;
         toolCalls: number;
         cost: CostUpdate | null;
         lastAssistantText: string;
+        assistantTextBlocks: string[];
     };
     private onToolStart;
     private onToolEnd;

package/dist/progress-tracker.js

@@ -5,6 +5,9 @@ const THROTTLE_MS = 5_000;
 const HEARTBEAT_MS = 60_000;
 const MAX_TASK_LENGTH = 120;
 const MAX_LOG_BUFFER = 500;
+// Cap on retained assistant text blocks so a long run can't grow the buffer
+// unbounded (#272). The episode write hook reads from the tail.
+const MAX_TEXT_BLOCKS = 40;
 // 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;
@@ -65,6 +68,9 @@ export class ProgressTracker {
     // Last assistant text block — used by the episode write hook to
     // capture an approach summary without re-running an LLM (plan §"Write hook").
     lastAssistantText = "";
+    // All non-trivial assistant text blocks, in order, used to assemble a richer
+    // structured approach summary at episode-write time (#272). Bounded.
+    assistantTextBlocks = [];
     constructor(client, cardId, workerId, subtasks) {
         this.client = client;
         this.cardId = cardId;
@@ -129,10 +135,12 @@ export class ProgressTracker {
     get stats() {
         return {
             filesEdited: this.filesEdited.size,
+            filesEditedPaths: [...this.filesEdited],
             filesRead: this.filesRead.size,
             toolCalls: this.toolCallCount,
             cost: this.lastCost,
             lastAssistantText: this.lastAssistantText,
+            assistantTextBlocks: [...this.assistantTextBlocks],
         };
     }
     onToolStart(name, input) {
@@ -212,6 +220,13 @@ export class ProgressTracker {
         // 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;
+        // Accumulate all non-trivial assistant blocks so the episode write hook can
+        // assemble a richer approach summary than the last turn alone (#272).
+        // Bounded: drop the oldest once over the cap.
+        this.assistantTextBlocks.push(trimmed);
+        if (this.assistantTextBlocks.length > MAX_TEXT_BLOCKS) {
+            this.assistantTextBlocks.shift();
+        }
         // 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,6 +10,11 @@ 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>;
+/**
+ * Fetch and serialize the card's comment thread for the agent prompt. Returns
+ * the empty string on no comments or fetch failure — never throws.
+ */
+export declare function renderCommentsSection(client: HarmonyApiClient, cardId: 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

package/dist/prompt.js

@@ -1,3 +1,4 @@
+import { serializeCommentThread } from "@harmony/shared";
 import { log } from "./log.js";
 const TAG = "prompt";
 /**
@@ -26,15 +27,42 @@ 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`);
+        // generateCardPrompt already appends the comment thread centrally.
         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}`);
+        // Fallback bypasses generateCardPrompt, so inject the thread here.
+        const commentsSection = await renderCommentsSection(client, card.id);
         return (buildFallbackPrompt(enriched, branchName, worktreePath) +
+            commentsSection +
             pastEpisodesSection);
     }
 }
+/**
+ * Fetch and serialize the card's comment thread for the agent prompt. Returns
+ * the empty string on no comments or fetch failure — never throws.
+ */
+export async function renderCommentsSection(client, cardId) {
+    try {
+        const { comments } = await client.getComments(cardId, { limit: 200 });
+        if (!Array.isArray(comments) || comments.length === 0)
+            return "";
+        const section = serializeCommentThread(comments, {
+            heading: "Comments",
+            maxComments: 40,
+        });
+        return section ? `\n\n${section}` : "";
+    }
+    catch (err) {
+        log.warn(TAG, "comment-thread fetch failed", {
+            event: "comment_fetch_failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return "";
+    }
+}
 /**
  * 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
@@ -62,7 +90,22 @@ export async function renderPastEpisodesSection(client, title, description, work
             const meta = e.metadata ?? {};
             const outcomeTag = meta.outcome ? `[${meta.outcome}]` : "[?]";
             const approach = meta.approach_summary ?? "";
-            return `- ${outcomeTag} ${e.title ?? "(untitled episode)"}\n  Approach: ${approach}`;
+            const lines = [
+                `- ${outcomeTag} ${e.title ?? "(untitled episode)"}`,
+                `  Approach: ${approach}`,
+            ];
+            // Surface the cheap deterministic root-cause line when present (#272).
+            if (meta.key_insight)
+                lines.push(`  Key insight: ${meta.key_insight}`);
+            // Show a compact changed-files list — cap the rendered count so the
+            // prompt stays small even if the stored list is long (#272).
+            if (meta.changed_files && meta.changed_files.length > 0) {
+                const shown = meta.changed_files.slice(0, 8);
+                const extra = meta.changed_files.length - shown.length;
+                const suffix = extra > 0 ? ` (+${extra} more)` : "";
+                lines.push(`  Changed files: ${shown.join(", ")}${suffix}`);
+            }
+            return lines.join("\n");
         })
             .join("\n");
         return `\n\n## Similar past tasks\n${bullets}`;