@gethmy/agent 1.0.9 → 1.1.0

package/dist/review-worker.js

@@ -1,13 +1,18 @@
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
+import { buildTokenPayload } from "./completion.js";
 import { log } from "./log.js";
+import { signalGroup, spawnInGroup, terminateGroup } from "./process-group.js";
 import { ProgressTracker } from "./progress-tracker.js";
 import { parseReviewOutput, runReviewCompletion } from "./review-completion.js";
 import { buildReviewSystemPrompt, buildReviewUserPrompt, } from "./review-prompt.js";
 import { checkoutExistingBranch, extractBranchFromDescription, } from "./review-worktree.js";
+import { openRunLog } from "./run-log.js";
+import { newRunId } from "./state-store.js";
 import { StreamParser } from "./stream-parser.js";
+import { runTransition, TransitionError } from "./transitions.js";
 import { AGENT_NAME, agentIdentifier, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR, } from "./types.js";
-import { waitForDevServer } from "./verification.js";
+import { DevServerReadinessError, probeDevServer, waitForDevServer, } from "./verification.js";
 import { cleanupWorktree } from "./worktree.js";
 const TAG = "review-worker";
 const CANCEL_SIGINT_TIMEOUT = 30_000;
@@ -16,6 +21,7 @@ export class ReviewWorker {
     config;
     client;
     onDone;
+    stateStore;
     id;
     state = "idle";
     cardId = null;
@@ -25,14 +31,52 @@ export class ReviewWorker {
     process = null;
     devServerProcess = null;
     timeoutTimer = null;
+    heartbeatTimer = null;
     progressTracker = null;
+    lastSessionStats = null;
     aborted = false;
-    constructor(id, config, client, _userEmail, onDone) {
+    runId = null;
+    constructor(id, config, client, _userEmail, onDone, stateStore) {
         this.config = config;
         this.client = client;
         this.onDone = onDone;
+        this.stateStore = stateStore;
         this.id = id;
     }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const interval = this.config.timing.heartbeatMs;
+        this.heartbeatTimer = setInterval(() => {
+            if (this.runId) {
+                this.stateStore.heartbeat(this.runId).catch(() => {
+                    /* retry next tick */
+                });
+            }
+        }, interval);
+        // Don't block event loop shutdown for a pending heartbeat.
+        this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    async recordPhase(phase) {
+        if (!this.runId)
+            return;
+        try {
+            await this.stateStore.updateRun(this.runId, {
+                phase,
+                lastHeartbeatAt: Date.now(),
+                worktreePath: this.worktreePath,
+                branchName: this.branchName,
+            });
+        }
+        catch (err) {
+            log.warn(this.tag, `state store updateRun failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
     get tag() {
         return `${TAG}:${this.id}`;
     }
@@ -56,10 +100,29 @@ export class ReviewWorker {
         this.aborted = false;
         this.cardId = card.id;
         this.startedAt = Date.now();
+        this.runId = newRunId();
         try {
             // --- PREPARING ---
             this.state = "preparing";
             log.info(this.tag, `Preparing review for #${card.short_id} "${card.title}"`);
+            this.startHeartbeat();
+            await this.stateStore.insertRun({
+                runId: this.runId,
+                cardId: card.id,
+                cardShortId: card.short_id,
+                pipeline: "review",
+                workerId: this.id,
+                sessionId: null,
+                worktreePath: null,
+                branchName: null,
+                daemonPid: process.pid,
+                phase: "preparing",
+                startedAt: this.startedAt,
+                lastHeartbeatAt: this.startedAt,
+                endedAt: null,
+                status: "active",
+                costCents: 0,
+            });
             // Extract branch name from card description
             this.branchName = extractBranchFromDescription(card.description);
             const localMode = !this.branchName;
@@ -75,31 +138,9 @@ export class ReviewWorker {
                 // Try to find reviewable changes
                 const resolved = this.resolveLocalChanges(this.worktreePath, card.short_id);
                 if (!resolved) {
-                    // No changes found — post helpful note on the card and bail
-                    log.info(this.tag, `No local changes found for #${card.short_id} — posting note and moving to "${this.config.review.failColumn}"`);
-                    // Strip any previous agent note before appending a new one
-                    const AGENT_NOTE_SEPARATOR = "\n\n---\n**Agent Note: No branch found**";
-                    const existingDesc = card.description ?? "";
-                    const cleanDesc = existingDesc.includes(AGENT_NOTE_SEPARATOR)
-                        ? existingDesc.slice(0, existingDesc.indexOf(AGENT_NOTE_SEPARATOR))
-                        : existingDesc;
-                    const note = [
-                        cleanDesc,
-                        "",
-                        "---",
-                        "**Agent Note: No branch found**",
-                        "The review agent could not find a branch reference (`Branch: ...`) in this card's description,",
-                        `and no local uncommitted changes or recent commits referencing #${card.short_id} were found.`,
-                        "",
-                        "Please either:",
-                        "- Push the implementation branch and add `Branch: your-branch-name` to the description",
-                        '- Or move this card back to "To Do" for the implement worker to pick up',
-                    ].join("\n");
-                    await Promise.all([
-                        this.client.updateCard(card.id, { description: note }),
-                        addLabelByName(this.client, card, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR),
-                        moveCardToColumn(this.client, card, this.config.review.failColumn),
-                    ]);
+                    // No changes found — mark for human review and leave in current column
+                    log.info(this.tag, `No local changes found for #${card.short_id} — marking for human review (staying in Review)`);
+                    await addLabelByName(this.client, card, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR);
                     return;
                 }
                 log.info(this.tag, `Found local changes via ${resolved.source} for #${card.short_id}`);
@@ -129,6 +170,7 @@ export class ReviewWorker {
                 return;
             // --- REVIEWING ---
             this.state = "running";
+            await this.recordPhase("running");
             if (!this.worktreePath) {
                 throw new Error("worktreePath not set before review phase");
             }
@@ -137,8 +179,12 @@ export class ReviewWorker {
             const cwd = this.worktreePath;
             if (!localMode) {
                 log.info(this.tag, `Starting dev server on port ${port}...`);
-                this.devServerProcess = spawn("bun", ["run", "dev", "--", "--port", String(port)], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+                this.devServerProcess = spawnInGroup("bun", ["run", "dev", "--", "--port", String(port)], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+                // Invariant I2: review only proceeds with a proven-live dev server.
+                // waitForDevServer rejects on timeout / exit; probeDevServer verifies
+                // the port actually answers HTTP.
                 await waitForDevServer(this.devServerProcess, 30_000);
+                await probeDevServer(port);
                 log.info(this.tag, `Dev server ready on port ${port}`);
             }
             if (this.aborted)
@@ -182,13 +228,17 @@ export class ReviewWorker {
             // Set up progress tracking
             this.progressTracker = new ProgressTracker(this.client, card.id, this.id, subtasks);
             // Spawn Claude CLI for review with streaming
-            const stdout = await this.spawnClaude(userPrompt, systemPrompt, this.progressTracker);
+            const stdout = await this.spawnClaude(userPrompt, systemPrompt, this.progressTracker, card.short_id);
+            // Capture session stats before stopping tracker
+            this.lastSessionStats = this.progressTracker?.stats ?? null;
             this.progressTracker?.stop();
             this.progressTracker = null;
+            const sessionStats = this.lastSessionStats;
             if (this.aborted)
                 return;
             // --- COMPLETING ---
             this.state = "completing";
+            await this.recordPhase("completing");
             log.info(this.tag, `Claude review finished for #${card.short_id}`);
             // Kill dev server (only if we started one)
             if (!localMode) {
@@ -205,29 +255,75 @@ export class ReviewWorker {
                 progressPercent: 80,
             });
             // Run review completion pipeline
-            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName);
+            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName, sessionStats);
         }
         catch (err) {
             this.state = "error";
             const msg = err instanceof Error ? err.message : String(err);
             log.error(this.tag, `Error reviewing #${card.short_id}: ${msg}`);
-            // End session as paused on error
+            // End session as paused on error. Retried via runTransition so a
+            // transient API failure no longer orphans the session.
             try {
-                await this.client.endAgentSession(card.id, { status: "paused" });
+                const stats = this.lastSessionStats ?? this.progressTracker?.stats;
+                await runTransition(this.client, card, {
+                    endSession: {
+                        status: "paused",
+                        ...buildTokenPayload(stats),
+                    },
+                });
             }
-            catch {
-                // best-effort
+            catch (tErr) {
+                log.error(this.tag, `endAgentSession unrecoverable on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
             }
-            // Move card out of Review to break the re-enqueue loop
-            try {
-                await moveCardToColumn(this.client, card, this.config.review.failColumn);
-                log.info(this.tag, `Moved #${card.short_id} to "${this.config.review.failColumn}" after error`);
+            // Dev server readiness failures are infrastructure errors, not
+            // implementation errors — the code under review may be perfectly
+            // fine. Invariant I2: never approve without a live server, but
+            // also never bounce the card back to "To Do" for rework. Keep
+            // it in Review with a "Need Review" label so a human steps in.
+            if (err instanceof DevServerReadinessError) {
+                try {
+                    await addLabelByName(this.client, card, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR);
+                    log.info(this.tag, `#${card.short_id} kept in Review — dev server unavailable, human review needed`);
+                }
+                catch {
+                    log.warn(this.tag, "Failed to add Need Review label after dev-server failure");
+                }
             }
-            catch {
-                log.warn(this.tag, "Failed to move card to fail column after error");
+            else {
+                // Move card out of Review to break the re-enqueue loop for other errors
+                try {
+                    await moveCardToColumn(this.client, card, this.config.review.failColumn);
+                    log.info(this.tag, `Moved #${card.short_id} to "${this.config.review.failColumn}" after error`);
+                }
+                catch {
+                    log.warn(this.tag, "Failed to move card to fail column after error");
+                }
+            }
+            if (this.runId) {
+                try {
+                    await this.stateStore.endRun(this.runId, this.state === "error" ? "paused" : "completed");
+                }
+                catch {
+                    // best-effort
+                }
             }
         }
         finally {
+            if (this.runId) {
+                try {
+                    const run = this.stateStore.getRun(this.runId);
+                    if (run && run.endedAt === null) {
+                        // Cancelled runs are paused, not completed — they never
+                        // produced a verdict so treating them as success would be
+                        // a lie to the budget/attempt bookkeeping.
+                        const status = this.state === "error" || this.aborted ? "paused" : "completed";
+                        await this.stateStore.endRun(this.runId, status);
+                    }
+                }
+                catch {
+                    // best-effort
+                }
+            }
             this.cleanup();
             this.state = "idle";
             this.onDone(this);
@@ -240,7 +336,7 @@ export class ReviewWorker {
         if (!this.isActive || !this.process || this.process.killed)
             return;
         log.info(this.tag, `Pausing review on ${this.cardId}`);
-        this.process.kill("SIGSTOP");
+        signalGroup(this.process, "SIGSTOP");
         if (this.timeoutTimer) {
             clearTimeout(this.timeoutTimer);
             this.timeoutTimer = null;
@@ -266,7 +362,7 @@ export class ReviewWorker {
         if (!this.isActive || !this.process || this.process.killed)
             return;
         log.info(this.tag, `Resuming review on ${this.cardId}`);
-        this.process.kill("SIGCONT");
+        signalGroup(this.process, "SIGCONT");
         this.timeoutTimer = setTimeout(() => {
             log.warn(this.tag, `Timeout reached (${this.config.review.maxTimeout}ms), cancelling`);
             this.cancel();
@@ -294,6 +390,9 @@ export class ReviewWorker {
         this.aborted = true;
         this.state = "cancelling";
         log.info(this.tag, `Cancelling review on ${this.cardId}`);
+        // Capture tokens/cost snapshot before stopping the tracker so a
+        // cancelled run still persists its usage to the session.
+        const snapshotStats = this.lastSessionStats ?? this.progressTracker?.stats;
         // Stop progress tracking
         if (this.progressTracker) {
             this.progressTracker?.stop();
@@ -301,34 +400,27 @@ export class ReviewWorker {
         }
         // Kill dev server first
         this.killDevServer();
-        // Then kill Claude process with escalating signals
+        // Then kill Claude process group with escalating signals
         if (this.process && !this.process.killed) {
-            // Resume first in case the process is suspended
-            this.process.kill("SIGCONT");
-            this.process.kill("SIGINT");
-            log.debug(this.tag, "Sent SIGINT to Claude");
-            const sigintDead = await this.waitForExit(CANCEL_SIGINT_TIMEOUT);
-            if (!sigintDead) {
-                this.process.kill("SIGTERM");
-                log.debug(this.tag, "Sent SIGTERM to Claude");
-                const sigtermDead = await this.waitForExit(CANCEL_SIGTERM_TIMEOUT);
-                if (!sigtermDead) {
-                    this.process.kill("SIGKILL");
-                    log.warn(this.tag, "Sent SIGKILL to Claude");
-                }
-            }
+            await terminateGroup(this.process, {
+                sigintTimeoutMs: CANCEL_SIGINT_TIMEOUT,
+                sigtermTimeoutMs: CANCEL_SIGTERM_TIMEOUT,
+            });
         }
         // End agent session as paused
         if (this.cardId) {
             try {
-                await this.client.endAgentSession(this.cardId, { status: "paused" });
+                await this.client.endAgentSession(this.cardId, {
+                    status: "paused",
+                    ...buildTokenPayload(snapshotStats),
+                });
             }
             catch {
                 // best-effort
             }
         }
     }
-    spawnClaude(prompt, systemPrompt, tracker) {
+    spawnClaude(prompt, systemPrompt, tracker, shortId) {
         return new Promise((resolve, reject) => {
             const args = [
                 "--output-format",
@@ -346,7 +438,13 @@ export class ReviewWorker {
                 prompt,
             ];
             log.info(this.tag, `Spawning review: claude ${args.slice(0, 5).join(" ")} ...`);
-            this.process = spawn("claude", args, {
+            const runLog = openRunLog(this.tag, this.runId, shortId);
+            if (runLog) {
+                log.info(this.tag, `Run log: ${runLog.path}`);
+                runLog.stream.write(`# run=${this.runId} card=#${shortId} pipeline=review started=${new Date().toISOString()}\n` +
+                    `# args: ${args.slice(0, -2).join(" ")} -- <prompt:${prompt.length} chars>\n\n`);
+            }
+            this.process = spawnInGroup("claude", args, {
                 cwd: this.worktreePath,
                 stdio: ["ignore", "pipe", "pipe"],
             });
@@ -357,13 +455,23 @@ export class ReviewWorker {
             parser.on("text", (content) => {
                 textChunks.push(content);
             });
+            parser.on("parse_error", (msg) => {
+                log.debug(this.tag, `Stream parse error (non-fatal): ${msg}`);
+                runLog?.stream.write(`\n[parse_error] ${msg}\n`);
+            });
             // Attach parser to stdout (single consumer)
             if (this.process.stdout) {
                 parser.attach(this.process.stdout);
+                if (runLog) {
+                    this.process.stdout.on("data", (chunk) => {
+                        runLog.stream.write(chunk);
+                    });
+                }
             }
             let stderr = "";
             this.process.stderr?.on("data", (data) => {
                 stderr += data.toString();
+                runLog?.stream.write(`[stderr] ${data.toString()}`);
             });
             this.process.on("error", (err) => {
                 reject(new Error(`Failed to spawn claude: ${err.message}`));
@@ -372,6 +480,14 @@ export class ReviewWorker {
                 this.process = null;
                 // Reconstruct text from stream parser text events
                 const stdout = textChunks.join("");
+                const stats = tracker.stats;
+                if (runLog) {
+                    runLog.stream.write(`\n# exit code=${code} aborted=${this.aborted} ` +
+                        `toolCalls=${stats?.toolCalls ?? 0} filesEdited=${stats?.filesEdited ?? 0} ` +
+                        `cost=$${stats?.cost?.totalCostUsd.toFixed(4) ?? "0"} ` +
+                        `textChars=${stdout.length} ended=${new Date().toISOString()}\n`);
+                    runLog.stream.end();
+                }
                 if (this.aborted) {
                     resolve(stdout);
                 }
@@ -384,26 +500,11 @@ export class ReviewWorker {
             });
         });
     }
-    waitForExit(timeout) {
-        return new Promise((resolve) => {
-            if (!this.process || this.process.killed) {
-                resolve(true);
-                return;
-            }
-            const timer = setTimeout(() => {
-                resolve(false);
-            }, timeout);
-            this.process.once("close", () => {
-                clearTimeout(timer);
-                resolve(true);
-            });
-        });
-    }
     killDevServer() {
         if (this.devServerProcess && !this.devServerProcess.killed) {
-            this.devServerProcess.kill("SIGTERM");
+            signalGroup(this.devServerProcess, "SIGTERM");
             this.devServerProcess = null;
-            log.debug(this.tag, "Killed dev server");
+            log.debug(this.tag, "Killed dev server group");
         }
     }
     resolveLocalChanges(repoRoot, shortId) {
@@ -461,6 +562,7 @@ export class ReviewWorker {
             clearTimeout(this.timeoutTimer);
             this.timeoutTimer = null;
         }
+        this.stopHeartbeat();
         this.killDevServer();
         // Clean up worktree on error (only if we created one — skip in local mode)
         if (this.worktreePath && this.state === "error" && this.branchName) {
@@ -476,5 +578,7 @@ export class ReviewWorker {
         this.branchName = null;
         this.worktreePath = null;
         this.startedAt = null;
+        this.runId = null;
+        this.lastSessionStats = null;
     }
 }

package/dist/run-log.d.ts

@@ -0,0 +1,6 @@
+import { type WriteStream } from "node:fs";
+export interface RunLog {
+    path: string;
+    stream: WriteStream;
+}
+export declare function openRunLog(tag: string, runId: string | null, shortId: number): RunLog | null;

package/dist/run-log.js

@@ -0,0 +1,19 @@
+import { createWriteStream, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log } from "./log.js";
+export function openRunLog(tag, runId, shortId) {
+    if (!runId)
+        return null;
+    try {
+        const dir = join(homedir(), ".harmony-mcp", "runs");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${runId}-card-${shortId}.log`);
+        const stream = createWriteStream(path, { flags: "a" });
+        return { path, stream };
+    }
+    catch (err) {
+        log.warn(tag, `Failed to open run log: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}

package/dist/state-store.d.ts

@@ -0,0 +1,72 @@
+export type RunPipeline = "implement" | "review";
+export type RunStatus = "active" | "completed" | "paused" | "orphaned";
+export interface RunRecord {
+    runId: string;
+    cardId: string;
+    cardShortId: number;
+    pipeline: RunPipeline;
+    workerId: number;
+    sessionId: string | null;
+    worktreePath: string | null;
+    branchName: string | null;
+    daemonPid: number;
+    phase: string;
+    startedAt: number;
+    lastHeartbeatAt: number;
+    endedAt: number | null;
+    status: RunStatus;
+    costCents: number;
+    errorMessage?: string;
+}
+export interface CardRecord {
+    cardId: string;
+    attempts: number;
+    totalCostCents: number;
+    dlq: boolean;
+    dlqReason?: string;
+    lastAttemptAt: number | null;
+    lastOutcome: "success" | "failure" | null;
+}
+export declare function newRunId(): string;
+export declare function defaultStatePath(): string;
+/**
+ * Durable run-and-card state for the agent daemon. One writer (this daemon),
+ * so in-process serialization via a promise chain is sufficient — no file locks.
+ * Persists to JSON via write-to-tmp + rename, which is atomic on POSIX.
+ */
+export declare class StateStore {
+    private path;
+    private state;
+    private writeQueue;
+    constructor(path: string);
+    static open(path?: string): StateStore;
+    private load;
+    private persist;
+    /** Await any pending writes. Useful for tests and shutdown. */
+    flush(): Promise<void>;
+    setDaemon(daemonId: string, pid: number): Promise<void>;
+    getDaemon(): {
+        daemonId: string | null;
+        daemonPid: number | null;
+        daemonStartedAt: number | null;
+    };
+    insertRun(run: RunRecord): Promise<void>;
+    updateRun(runId: string, patch: Partial<RunRecord>): Promise<void>;
+    heartbeat(runId: string): Promise<void>;
+    endRun(runId: string, status: RunStatus, errorMessage?: string): Promise<void>;
+    getRun(runId: string): RunRecord | null;
+    getActiveRuns(): RunRecord[];
+    getRunsForCard(cardId: string): RunRecord[];
+    /** Trim completed runs older than `beforeTs` to keep the file small. */
+    purgeOldRuns(beforeTs: number): Promise<void>;
+    private ensureCard;
+    getCard(cardId: string): CardRecord | null;
+    incrementAttempt(cardId: string): Promise<number>;
+    recordOutcome(cardId: string, outcome: "success" | "failure"): Promise<void>;
+    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[];
+}