@gethmy/agent 1.4.1 → 1.5.0

package/dist/completion.d.ts

@@ -7,6 +7,8 @@ export interface SessionStats {
     filesRead: number;
     toolCalls: number;
     cost: CostUpdate | null;
+    /** Trimmed last assistant text — feeds the episode write hook (Phase 1.5). */
+    lastAssistantText?: string;
 }
 export declare function buildTokenPayload(stats?: SessionStats | null): {
     costCents?: undefined;
@@ -26,4 +28,4 @@ export declare function buildTokenPayload(stats?: SessionStats | null): {
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number, sessionStats?: SessionStats): Promise<void>;
+export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number, sessionStats?: SessionStats, workspaceId?: string, agentSessionId?: string | null): Promise<void>;

package/dist/completion.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { moveCardToColumn } from "./board-helpers.js";
+import { writeEpisode } from "./episode-writer.js";
 import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
 import { log } from "./log.js";
 import { AGENT_NAME, agentIdentifier } from "./types.js";
@@ -28,7 +29,14 @@ export function buildTokenPayload(stats) {
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0, sessionStats) {
+export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0, sessionStats, workspaceId, agentSessionId) {
+    // Hoisted so the episode write hook can read final verification state.
+    let verificationResult = {
+        passed: true,
+        buildErrors: [],
+        lintWarnings: [],
+        reviewFindings: [],
+    };
     // Check if there are any commits on the branch
     const hasCommits = checkHasCommits(worktreePath, config.worktree.baseBranch);
     if (!hasCommits) {
@@ -70,6 +78,7 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
                 }
             }
         }
+        verificationResult = result;
         if (!result.passed) {
             log.warn(TAG, `Verification failed for #${card.short_id} — reporting findings`);
             await reportFindings(client, card.id, result);
@@ -78,6 +87,9 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
                 status: "paused",
                 ...buildTokenPayload(sessionStats),
             });
+            // Episode write: paused/orphaned runs skip silently (plan D8). Failure
+            // here would only fire on a status===completed path, which we don't
+            // hit when verification fails.
             cleanupWorktree(worktreePath, branchName);
             return;
         }
@@ -106,6 +118,28 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
         progressPercent: 100,
         ...buildTokenPayload(sessionStats),
     });
+    // 6a. Episode write hook (Phase 1.5): completed implement runs accumulate
+    // into project-scoped episodic memory. Best-effort — failures never block
+    // the completion path (plan §"Write hook" + D8).
+    //
+    // Outcome is constant "success" here: verification failures return early
+    // above with status=paused, and D8 mandates paused/orphaned runs skip the
+    // episode write entirely. A failure-outcome episode would require routing
+    // a separate write hook into the pre-return path, which D8 intentionally
+    // omits ("daemon crashes ≠ task outcome").
+    if (workspaceId) {
+        await writeEpisode(client, {
+            kind: "implement",
+            card,
+            workspaceId,
+            outcome: "success",
+            approachSummary: sessionStats?.lastAssistantText ?? "",
+            result: verificationResult,
+            cost: sessionStats?.cost ?? null,
+            filesEdited: sessionStats?.filesEdited ?? 0,
+            agentSessionId: agentSessionId ?? null,
+        });
+    }
     // 7. Cleanup worktree
     cleanupWorktree(worktreePath, branchName);
     log.info(TAG, `Completion done for #${card.short_id}${prUrl ? ` — PR: ${prUrl}` : ""}`);

package/dist/episode-writer.d.ts

@@ -0,0 +1,84 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Card } from "@harmony/shared";
+import type { CostUpdate } from "./stream-parser.js";
+import type { EpisodeMeta, EpisodeOutcome } from "./types.js";
+import type { VerificationResult } from "./verification.js";
+interface ImplementEpisodeInput {
+    kind: "implement";
+    card: Card;
+    workspaceId: string;
+    outcome: EpisodeOutcome;
+    approachSummary: string;
+    result: VerificationResult;
+    cost: CostUpdate | null;
+    filesEdited: number;
+    errorMessage?: string;
+    agentSessionId?: string | null;
+}
+interface ReviewEpisodeInput {
+    kind: "review";
+    card: Card;
+    workspaceId: string;
+    verdict: "approved" | "rejected";
+    summary: string;
+    cost: CostUpdate | null;
+    agentSessionId?: string | null;
+    reviewSessionId?: string | null;
+    originalEpisodeId?: string | null;
+}
+export type EpisodeInput = ImplementEpisodeInput | ReviewEpisodeInput;
+/**
+ * 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
+ * error thrown, +0.2 if run completed cleanly.
+ */
+export declare function computeQualityScore(result: VerificationResult, opts: {
+    errorThrown: boolean;
+    runCompletedCleanly: boolean;
+}): number;
+/**
+ * Trim a free-form summary down to the documented 400-char cap. v1 uses a
+ * last-turn trim rather than an LLM rewrite (plan §"Write hook"). Empty or
+ * whitespace-only input collapses to a marker so the episode still surfaces
+ * as a recallable hit (rather than an empty bullet) in future prompts.
+ */
+export declare function trimApproachSummary(text: string): string;
+/**
+ * Build the entity payload for one episode. Pure — returned object can be
+ * snapshotted in tests without hitting the network.
+ */
+export declare function buildEpisodePayload(input: EpisodeInput, projectId: string): {
+    workspace_id: string;
+    project_id?: string;
+    type: string;
+    memory_tier: string;
+    scope: string;
+    title: string;
+    content: string;
+    metadata: EpisodeMeta;
+    importance: number;
+    confidence: number;
+    tags: string[];
+    agent_identifier: string;
+};
+/**
+ * Write one episode entity. Best-effort: any failure is logged and swallowed
+ * so the calling pipeline can complete (plan D8: episode writes never block
+ * run completion).
+ *
+ * Returns the entity id on success, or null on swallowed failure.
+ */
+export declare function writeEpisode(client: HarmonyApiClient, input: EpisodeInput): Promise<string | null>;
+/**
+ * Find the most recent implement episode for a given card so the review
+ * pipeline can back-fill its verdict. Returns null when none exists or the
+ * lookup throws — back-fill is best-effort.
+ */
+export declare function findLatestImplementEpisode(client: HarmonyApiClient, workspaceId: string, projectId: string, cardShortId: number): Promise<string | null>;
+/**
+ * Apply the review verdict to an earlier implement episode (plan §"Read hook"
+ * back-fill block). Approved nudges the original episode's confidence up;
+ * rejected tombstones it via superseded_by.
+ */
+export declare function backfillReviewVerdict(client: HarmonyApiClient, originalEpisodeId: string, verdict: "approved" | "rejected", reviewEpisodeId: string | null): Promise<void>;
+export {};

package/dist/episode-writer.js

@@ -0,0 +1,232 @@
+import { log } from "./log.js";
+const TAG = "episode-writer";
+const MAX_APPROACH_SUMMARY_CHARS = 400;
+/**
+ * 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
+ * error thrown, +0.2 if run completed cleanly.
+ */
+export function computeQualityScore(result, opts) {
+    if (!result.passed)
+        return 0;
+    let score = 0;
+    if (result.buildErrors.length === 0)
+        score += 0.4;
+    if (result.lintWarnings.length === 0)
+        score += 0.2;
+    if (!opts.errorThrown)
+        score += 0.2;
+    if (opts.runCompletedCleanly)
+        score += 0.2;
+    return Math.min(1, score);
+}
+/**
+ * Clamp confidence into the documented [0.4, 1.0] band so failures retain a
+ * minimum floor (plan §"Episode record shape").
+ */
+function clampConfidence(qualityScore) {
+    return Math.max(0.4, Math.min(1.0, qualityScore));
+}
+/**
+ * Trim a free-form summary down to the documented 400-char cap. v1 uses a
+ * last-turn trim rather than an LLM rewrite (plan §"Write hook"). Empty or
+ * whitespace-only input collapses to a marker so the episode still surfaces
+ * as a recallable hit (rather than an empty bullet) in future prompts.
+ */
+export function trimApproachSummary(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "(no approach summary captured)";
+    if (trimmed.length <= MAX_APPROACH_SUMMARY_CHARS)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_APPROACH_SUMMARY_CHARS - 1).trimEnd()}…`;
+}
+/**
+ * Build the entity payload for one episode. Pure — returned object can be
+ * snapshotted in tests without hitting the network.
+ */
+export function buildEpisodePayload(input, projectId) {
+    if (input.kind === "implement") {
+        const qualityScore = computeQualityScore(input.result, {
+            errorThrown: input.errorMessage !== undefined,
+            runCompletedCleanly: input.result.passed,
+        });
+        const type = input.outcome === "success" ? "solution" : "error";
+        const importance = input.outcome === "success" ? 7 : 5;
+        const approachSummary = trimApproachSummary(input.approachSummary);
+        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"}.`;
+        const metadata = {
+            episode_kind: "implement",
+            card_short_id: input.card.short_id,
+            card_title: input.card.title,
+            approach_summary: approachSummary,
+            outcome: input.outcome,
+            quality_score: qualityScore,
+            duration_ms: input.cost?.durationMs ?? 0,
+            token_cost: {
+                input: input.cost?.totalInputTokens ?? 0,
+                output: input.cost?.totalOutputTokens ?? 0,
+                usd: input.cost?.totalCostUsd ?? 0,
+            },
+            files_touched: input.filesEdited,
+            num_turns: input.cost?.numTurns ?? 0,
+        };
+        if (input.errorMessage)
+            metadata.error = input.errorMessage;
+        if (input.agentSessionId)
+            metadata.agent_session_id = input.agentSessionId;
+        return {
+            workspace_id: input.workspaceId,
+            project_id: projectId,
+            type,
+            memory_tier: "episode",
+            scope: "project",
+            title: `Agent run implement — #${input.card.short_id}: ${input.card.title}`,
+            content: `${approachSummary}\n\nOutcome: ${outcomeRationale}`,
+            metadata,
+            importance,
+            confidence: clampConfidence(qualityScore),
+            tags: ["implement", input.outcome, `card:${input.card.short_id}`],
+            agent_identifier: "harmony-agent",
+        };
+    }
+    // Review episode
+    const qualityScore = input.verdict === "approved" ? 1 : 0.4;
+    const summary = trimApproachSummary(input.summary || "(no summary captured)");
+    const metadata = {
+        episode_kind: "review",
+        card_short_id: input.card.short_id,
+        card_title: input.card.title,
+        approach_summary: summary,
+        outcome: input.verdict === "approved" ? "success" : "failure",
+        quality_score: qualityScore,
+        duration_ms: input.cost?.durationMs ?? 0,
+        token_cost: {
+            input: input.cost?.totalInputTokens ?? 0,
+            output: input.cost?.totalOutputTokens ?? 0,
+            usd: input.cost?.totalCostUsd ?? 0,
+        },
+        files_touched: 0,
+        num_turns: input.cost?.numTurns ?? 0,
+    };
+    if (input.agentSessionId)
+        metadata.agent_session_id = input.agentSessionId;
+    if (input.reviewSessionId)
+        metadata.review_session_id = input.reviewSessionId;
+    if (input.originalEpisodeId)
+        metadata.original_episode_id = input.originalEpisodeId;
+    return {
+        workspace_id: input.workspaceId,
+        project_id: projectId,
+        type: "decision",
+        memory_tier: "episode",
+        scope: "project",
+        title: `Agent run review — #${input.card.short_id}: ${input.card.title}`,
+        content: `Review verdict: ${input.verdict}.\n\n${summary}`,
+        metadata,
+        importance: 8,
+        confidence: clampConfidence(qualityScore),
+        tags: ["review", input.verdict, `card:${input.card.short_id}`],
+        agent_identifier: "harmony-agent",
+    };
+}
+/**
+ * Write one episode entity. Best-effort: any failure is logged and swallowed
+ * so the calling pipeline can complete (plan D8: episode writes never block
+ * run completion).
+ *
+ * Returns the entity id on success, or null on swallowed failure.
+ */
+export async function writeEpisode(client, input) {
+    const payload = buildEpisodePayload(input, input.card.project_id);
+    try {
+        const { entity } = await client.createMemoryEntity({
+            ...payload,
+            metadata: payload.metadata,
+        });
+        const id = entity && typeof entity === "object" && "id" in entity
+            ? (entity.id ?? null)
+            : null;
+        log.info(TAG, `episode written for #${input.card.short_id}`, {
+            cardId: input.card.id,
+            event: "episode_write",
+            kind: input.kind,
+        });
+        return id;
+    }
+    catch (err) {
+        log.warn(TAG, `episode write failed for #${input.card.short_id}`, {
+            cardId: input.card.id,
+            event: "episode_write_failed",
+            kind: input.kind,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+/**
+ * Find the most recent implement episode for a given card so the review
+ * pipeline can back-fill its verdict. Returns null when none exists or the
+ * lookup throws — back-fill is best-effort.
+ */
+export async function findLatestImplementEpisode(client, workspaceId, projectId, cardShortId) {
+    try {
+        const { entities } = await client.harmonyRecall({
+            workspaceId,
+            projectId,
+            type: ["solution", "error"],
+            memory_tier: "episode",
+            scope: "project",
+            tags: [`card:${cardShortId}`],
+            topK: 1,
+        });
+        const first = entities[0];
+        if (first &&
+            typeof first === "object" &&
+            "id" in first &&
+            typeof first.id === "string") {
+            return first.id;
+        }
+        return null;
+    }
+    catch (err) {
+        log.warn(TAG, "implement-episode lookup failed", {
+            event: "episode_lookup_failed",
+            cardShortId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+/**
+ * Apply the review verdict to an earlier implement episode (plan §"Read hook"
+ * back-fill block). Approved nudges the original episode's confidence up;
+ * rejected tombstones it via superseded_by.
+ */
+export async function backfillReviewVerdict(client, originalEpisodeId, verdict, reviewEpisodeId) {
+    try {
+        if (verdict === "approved") {
+            const { entity } = await client.getMemoryEntity(originalEpisodeId);
+            const current = entity?.confidence ?? 0.4;
+            const bumped = Math.min(1, current + 0.05);
+            await client.updateMemoryEntity(originalEpisodeId, {
+                confidence: bumped,
+            });
+        }
+        else {
+            await client.updateMemoryEntity(originalEpisodeId, {
+                superseded_by: reviewEpisodeId,
+            });
+        }
+    }
+    catch (err) {
+        log.warn(TAG, "review back-fill failed", {
+            event: "episode_backfill_failed",
+            originalEpisodeId,
+            verdict,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

package/dist/pool.js

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

package/dist/progress-tracker.d.ts

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

package/dist/progress-tracker.js

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

package/dist/prompt.d.ts

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

package/dist/prompt.js

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

package/dist/review-completion.d.ts

@@ -36,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, sessionStats?: SessionStats | null, runLogPath?: string | null): Promise<void>;
+export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string | null, sessionStats?: SessionStats | null, runLogPath?: string | null, workspaceId?: string, agentSessionId?: string | null): Promise<void>;

package/dist/review-completion.js

@@ -1,6 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
 import { buildTokenPayload } from "./completion.js";
+import { backfillReviewVerdict, findLatestImplementEpisode, writeEpisode, } from "./episode-writer.js";
 import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
 import { log } from "./log.js";
 import { NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR, } from "./types.js";
@@ -182,7 +183,7 @@ function stripReviewSummary(description) {
  * Handles approved/rejected verdicts, creates subtasks for findings,
  * and moves the card to the appropriate column.
  */
-export async function runReviewCompletion(client, card, result, config, worktreePath, branchName, sessionStats, runLogPath) {
+export async function runReviewCompletion(client, card, result, config, worktreePath, branchName, sessionStats, runLogPath, workspaceId, agentSessionId) {
     // Re-fetch card for fresh description (avoids stale data from enqueue time)
     let freshDesc;
     try {
@@ -321,6 +322,24 @@ export async function runReviewCompletion(client, card, result, config, worktree
                 status: "completed",
                 ...buildTokenPayload(sessionStats),
             });
+            // Max-cycles rejection: the verdict still teaches "this approach kept
+            // failing review" — write the episode + back-fill before exiting.
+            if (workspaceId) {
+                const origId = await findLatestImplementEpisode(client, workspaceId, card.project_id, card.short_id);
+                const reviewId = await writeEpisode(client, {
+                    kind: "review",
+                    card,
+                    workspaceId,
+                    verdict: "rejected",
+                    summary: `Reached max review cycles (${maxCycles}). ${result.summary}`,
+                    cost: sessionStats?.cost ?? null,
+                    agentSessionId: agentSessionId ?? null,
+                    originalEpisodeId: origId,
+                });
+                if (origId) {
+                    await backfillReviewVerdict(client, origId, "rejected", reviewId);
+                }
+            }
             if (branchName) {
                 cleanupWorktree(worktreePath, branchName);
             }
@@ -388,6 +407,27 @@ export async function runReviewCompletion(client, card, result, config, worktree
         });
         log.info(TAG, `#${card.short_id} rejected (cycle ${currentCycle}/${maxCycles}) — moved to "${config.review.failColumn}"`);
     }
+    // Episode write + verdict back-fill (Phase 1.5). Runs for approved or
+    // rejected verdicts only — "error" verdicts return early above. Best-effort:
+    // failures are logged by writeEpisode/backfillReviewVerdict and never block
+    // worktree cleanup.
+    if (workspaceId &&
+        (result.verdict === "approved" || result.verdict === "rejected")) {
+        const originalEpisodeId = await findLatestImplementEpisode(client, workspaceId, card.project_id, card.short_id);
+        const reviewEpisodeId = await writeEpisode(client, {
+            kind: "review",
+            card,
+            workspaceId,
+            verdict: result.verdict,
+            summary: result.summary,
+            cost: sessionStats?.cost ?? null,
+            agentSessionId: agentSessionId ?? null,
+            originalEpisodeId,
+        });
+        if (originalEpisodeId) {
+            await backfillReviewVerdict(client, originalEpisodeId, result.verdict, reviewEpisodeId);
+        }
+    }
     // Cleanup worktree (skip in local mode — no worktree to clean)
     if (branchName) {
         cleanupWorktree(worktreePath, branchName);

package/dist/review-worker.d.ts

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

package/dist/review-worker.js

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

package/dist/types.d.ts

@@ -98,3 +98,35 @@ export interface RealtimeCredentials {
     supabaseUrl: string;
     supabaseAnonKey: string;
 }
+/** Pipeline that produced an episode. */
+export type EpisodeKind = "implement" | "review";
+/** Outcome of an implement run; review verdict maps to its own type. */
+export type EpisodeOutcome = "success" | "failure";
+/**
+ * Structured metadata persisted alongside every episode entity in
+ * `knowledge_entities.metadata`. Read by the recall path to render the
+ * "Similar past tasks" section in subsequent agent prompts.
+ */
+export interface EpisodeMeta {
+    episode_kind: EpisodeKind;
+    card_short_id: number;
+    card_title: string;
+    approach_summary: string;
+    outcome: EpisodeOutcome;
+    quality_score: number;
+    duration_ms: number;
+    token_cost: {
+        input: number;
+        output: number;
+        usd: number;
+    };
+    files_touched: number;
+    num_turns: number;
+    error?: string;
+    /** Provenance only — never used as memory scope. */
+    agent_session_id?: string;
+    /** Set on back-fill from review pipeline. */
+    review_session_id?: string;
+    /** Set on review-decision entities so back-fill can find the original. */
+    original_episode_id?: string;
+}

package/dist/worker.js

@@ -195,7 +195,7 @@ 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);
+            await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id, this.lastSessionStats, this.workspaceId, this.sessionId);
         }
         catch (err) {
             this.state = "error";

package/package.json

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