@gethmy/agent 1.0.9 → 1.1.1

package/dist/worker.d.ts

@@ -1,5 +1,6 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card, Column, Label, Subtask } from "@harmony/shared";
+import { type StateStore } from "./state-store.js";
 import { type AgentConfig, type WorkerState } from "./types.js";
 export declare class Worker {
     private config;
@@ -7,6 +8,7 @@ export declare class Worker {
     private onDone;
     private workspaceId;
     private projectId;
+    private stateStore;
     id: number;
     state: WorkerState;
     cardId: string | null;
@@ -15,11 +17,16 @@ export declare class Worker {
     startedAt: number | null;
     private process;
     private timeoutTimer;
+    private heartbeatTimer;
     private progressTracker;
     private lastSessionStats;
     private aborted;
     private sessionId;
-    constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: Worker) => void, workspaceId: string, projectId: string);
+    private runId;
+    constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: Worker) => void, workspaceId: string, projectId: string, stateStore: StateStore);
+    private startHeartbeat;
+    private stopHeartbeat;
+    private recordPhase;
     get tag(): string;
     get isIdle(): boolean;
     get isActive(): boolean;
@@ -28,6 +35,7 @@ export declare class Worker {
      * PREPARING → RUNNING → COMPLETING → IDLE
      */
     run(card: Card, column: Column, labels: Label[], subtasks: Subtask[]): Promise<void>;
+    private recordOutcome;
     /**
      * Pause the current work by suspending the Claude process (SIGSTOP).
      */
@@ -41,6 +49,5 @@ export declare class Worker {
      */
     cancel(): Promise<void>;
     private spawnClaude;
-    private waitForExit;
     private cleanup;
 }

package/dist/worker.js

@@ -1,10 +1,13 @@
-import { spawn } from "node:child_process";
 import { moveCardAndAddLabel } from "./board-helpers.js";
-import { runCompletion } from "./completion.js";
+import { buildTokenPayload, runCompletion, } from "./completion.js";
 import { log } from "./log.js";
+import { signalGroup, spawnInGroup, terminateGroup } from "./process-group.js";
 import { ProgressTracker } from "./progress-tracker.js";
 import { buildPrompt } from "./prompt.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, } from "./types.js";
 import { cleanupWorktree, createWorktree, makeBranchName } from "./worktree.js";
 const TAG = "worker";
@@ -16,6 +19,7 @@ export class Worker {
     onDone;
     workspaceId;
     projectId;
+    stateStore;
     id;
     state = "idle";
     cardId = null;
@@ -24,18 +28,56 @@ export class Worker {
     startedAt = null;
     process = null;
     timeoutTimer = null;
+    heartbeatTimer = null;
     progressTracker = null;
     lastSessionStats;
     aborted = false;
     sessionId = null;
-    constructor(id, config, client, _userEmail, onDone, workspaceId, projectId) {
+    runId = null;
+    constructor(id, config, client, _userEmail, onDone, workspaceId, projectId, stateStore) {
         this.config = config;
         this.client = client;
         this.onDone = onDone;
         this.workspaceId = workspaceId;
         this.projectId = projectId;
+        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(() => {
+                    /* next tick will retry */
+                });
+            }
+        }, 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,
+                sessionId: this.sessionId,
+            });
+        }
+        catch (err) {
+            log.warn(this.tag, `state store updateRun failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
     get tag() {
         return `${TAG}:${this.id}`;
     }
@@ -56,11 +98,36 @@ export class Worker {
         this.aborted = false;
         this.cardId = card.id;
         this.startedAt = Date.now();
+        this.runId = newRunId();
         try {
             // --- PREPARING ---
             this.state = "preparing";
             this.branchName = makeBranchName(card.short_id, card.title);
             log.info(this.tag, `Preparing #${card.short_id} "${card.title}"`);
+            // Per-card attempt counter resets on success; DLQ 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
+            // (Claude can spend 5+ minutes in one tool call).
+            this.startHeartbeat();
+            // Record this run durably so we can recover on crash.
+            await this.stateStore.insertRun({
+                runId: this.runId,
+                cardId: card.id,
+                cardShortId: card.short_id,
+                pipeline: "implement",
+                workerId: this.id,
+                sessionId: null,
+                worktreePath: null,
+                branchName: this.branchName,
+                daemonPid: process.pid,
+                phase: "preparing",
+                startedAt: this.startedAt,
+                lastHeartbeatAt: this.startedAt,
+                endedAt: null,
+                status: "active",
+                costCents: 0,
+            });
             // Start agent session and make it visible on the board
             const { session } = await this.client.startAgentSession(card.id, {
                 agentIdentifier: agentIdentifier(this.id),
@@ -76,6 +143,7 @@ export class Worker {
                 log.warn(TAG, "startAgentSession returned no session id");
             }
             this.sessionId = sid;
+            await this.recordPhase("preparing");
             // Move card to "In Progress" and add "agent" label so the board shows the progress ring
             const moved = await moveCardAndAddLabel(this.client, card, "In Progress", "agent");
             if (!moved) {
@@ -89,6 +157,7 @@ export class Worker {
                 return;
             // --- RUNNING ---
             this.state = "running";
+            await this.recordPhase("running");
             const enriched = {
                 card,
                 column,
@@ -115,6 +184,7 @@ export class Worker {
                 return;
             // --- VERIFYING + COMPLETING ---
             this.state = "verifying";
+            await this.recordPhase("verifying");
             log.info(this.tag, `Claude finished for #${card.short_id}, running verification & completion`);
             await this.client.updateAgentProgress(card.id, {
                 agentIdentifier: agentIdentifier(this.id),
@@ -124,28 +194,79 @@ export class Worker {
                 progressPercent: 75,
             });
             this.state = "completing";
+            await this.recordPhase("completing");
             await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id, this.lastSessionStats);
         }
         catch (err) {
             this.state = "error";
             const msg = err instanceof Error ? err.message : String(err);
             log.error(this.tag, `Error on #${card.short_id}: ${msg}`);
-            // End session as paused on error
+            // End session as paused. Retried — a transient API blip here used
+            // to orphan the session and leave the card stuck with a progress ring.
             try {
-                await this.client.endAgentSession(card.id, {
-                    status: "paused",
+                await runTransition(this.client, card, {
+                    endSession: {
+                        status: "paused",
+                        ...buildTokenPayload(this.lastSessionStats),
+                    },
                 });
             }
-            catch {
-                // best-effort
+            catch (tErr) {
+                log.error(this.tag, `endAgentSession unrecoverable on #${card.short_id}: ${tErr instanceof TransitionError ? tErr.detail : tErr}`);
+            }
+            if (this.runId) {
+                try {
+                    await this.stateStore.endRun(this.runId, "paused", msg);
+                }
+                catch {
+                    // state-store best-effort; already persisted on last heartbeat
+                }
+                await this.recordOutcome(card.id, "failure");
             }
         }
         finally {
+            // 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;
+            if (succeeded) {
+                try {
+                    await this.stateStore.endRun(this.runId, "completed");
+                }
+                catch {
+                    // best-effort — state store failures don't block worker exit
+                }
+                await this.recordOutcome(card.id, "success");
+            }
+            else if (this.runId && this.aborted) {
+                // Cancelled run: don't touch attempts counter, but close the
+                // state store row so it isn't mistaken for a live run.
+                try {
+                    await this.stateStore.endRun(this.runId, "paused", "cancelled");
+                }
+                catch {
+                    // best-effort
+                }
+            }
             this.cleanup();
             this.state = "idle";
             this.onDone(this);
         }
     }
+    async recordOutcome(cardId, outcome) {
+        try {
+            const cost = this.lastSessionStats?.cost;
+            if (cost) {
+                const cents = Math.round(cost.totalCostUsd * 100);
+                await this.stateStore.addCost(cardId, cents);
+            }
+            await this.stateStore.recordOutcome(cardId, outcome);
+        }
+        catch (err) {
+            log.warn(this.tag, `recordOutcome(${outcome}) failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
     /**
      * Pause the current work by suspending the Claude process (SIGSTOP).
      */
@@ -153,7 +274,7 @@ export class Worker {
         if (!this.isActive || !this.process || this.process.killed)
             return;
         log.info(this.tag, `Pausing work on ${this.cardId}`);
-        this.process.kill("SIGSTOP");
+        signalGroup(this.process, "SIGSTOP");
         // Pause the timeout timer
         if (this.timeoutTimer) {
             clearTimeout(this.timeoutTimer);
@@ -180,7 +301,7 @@ export class Worker {
         if (!this.isActive || !this.process || this.process.killed)
             return;
         log.info(this.tag, `Resuming work on ${this.cardId}`);
-        this.process.kill("SIGCONT");
+        signalGroup(this.process, "SIGCONT");
         // Restart timeout timer with remaining time (use full timeout for simplicity)
         this.timeoutTimer = setTimeout(() => {
             log.warn(this.tag, `Timeout reached (${this.config.maxTimeout}ms), cancelling`);
@@ -210,31 +331,22 @@ export class Worker {
         this.state = "cancelling";
         log.info(this.tag, `Cancelling work on ${this.cardId}`);
         if (this.process && !this.process.killed) {
-            // Resume first in case the process is suspended
-            this.process.kill("SIGCONT");
-            // Step 1: SIGINT (let Claude save state gracefully)
-            this.process.kill("SIGINT");
-            log.debug(this.tag, "Sent SIGINT");
-            const sigintDead = await this.waitForExit(CANCEL_SIGINT_TIMEOUT);
-            if (sigintDead)
-                return;
-            // Step 2: SIGTERM
-            this.process.kill("SIGTERM");
-            log.debug(this.tag, "Sent SIGTERM");
-            const sigtermDead = await this.waitForExit(CANCEL_SIGTERM_TIMEOUT);
-            if (sigtermDead)
-                return;
-            // Step 3: SIGKILL
-            this.process.kill("SIGKILL");
-            log.warn(this.tag, "Sent SIGKILL");
+            await terminateGroup(this.process, {
+                sigintTimeoutMs: CANCEL_SIGINT_TIMEOUT,
+                sigtermTimeoutMs: CANCEL_SIGTERM_TIMEOUT,
+            });
         }
-        // End agent session as paused
+        // End agent session as paused (retry on API jitter).
         if (this.cardId) {
             try {
-                await this.client.endAgentSession(this.cardId, { status: "paused" });
+                const stats = this.lastSessionStats ?? this.progressTracker?.stats;
+                await this.client.endAgentSession(this.cardId, {
+                    status: "paused",
+                    ...buildTokenPayload(stats),
+                });
             }
-            catch {
-                // best-effort
+            catch (err) {
+                log.warn(this.tag, `endAgentSession after cancel failed: ${err instanceof Error ? err.message : err}`);
             }
         }
     }
@@ -256,7 +368,13 @@ export class Worker {
                 prompt,
             ];
             log.info(this.tag, `Spawning: claude ${args.slice(0, 4).join(" ")} ...`);
-            this.process = spawn("claude", args, {
+            const runLog = openRunLog(this.tag, this.runId, card.short_id);
+            if (runLog) {
+                log.info(this.tag, `Run log: ${runLog.path}`);
+                runLog.stream.write(`# run=${this.runId} card=#${card.short_id} 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"],
             });
@@ -271,13 +389,20 @@ export class Worker {
             // Attach stdout to parser
             if (this.process.stdout) {
                 parser.attach(this.process.stdout);
+                if (runLog) {
+                    this.process.stdout.on("data", (chunk) => {
+                        runLog.stream.write(chunk);
+                    });
+                }
             }
             parser.on("parse_error", (msg) => {
                 log.debug(this.tag, `Stream parse error (non-fatal): ${msg}`);
+                runLog?.stream.write(`\n[parse_error] ${msg}\n`);
             });
             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}`));
@@ -288,6 +413,14 @@ export class Worker {
                 this.progressTracker?.flushFinal();
                 this.progressTracker?.stop();
                 this.progressTracker = null;
+                if (runLog) {
+                    const stats = this.lastSessionStats;
+                    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"} ` +
+                        `ended=${new Date().toISOString()}\n`);
+                    runLog.stream.end();
+                }
                 if (this.aborted) {
                     resolve(); // Cancellation is not an error
                 }
@@ -300,26 +433,12 @@ export class Worker {
             });
         });
     }
-    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);
-            });
-        });
-    }
     cleanup() {
         if (this.progressTracker) {
             this.progressTracker.stop();
             this.progressTracker = null;
         }
+        this.stopHeartbeat();
         this.lastSessionStats = undefined;
         if (this.timeoutTimer) {
             clearTimeout(this.timeoutTimer);
@@ -339,5 +458,7 @@ export class Worker {
         this.branchName = null;
         this.worktreePath = null;
         this.startedAt = null;
+        this.runId = null;
+        this.sessionId = null;
     }
 }

package/dist/worktree-gc.d.ts

@@ -0,0 +1,39 @@
+import type { StateStore } from "./state-store.js";
+export interface GcResult {
+    checked: number;
+    removed: string[];
+    skipped: string[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+export interface GcOptions {
+    /** Directories younger than this are kept (a worker may be about to use them). */
+    minAgeMs?: number;
+    /** Optional sync clock, for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * One-shot garbage collection for `.harmony-worktrees/*`.
+ *
+ * A directory is removed when BOTH:
+ *   - no active run in the state store has it as its `worktreePath`, AND
+ *   - it was last modified more than `minAgeMs` ago (default 1h).
+ *
+ * The age check protects brand-new worktrees that a worker just created
+ * but hasn't yet recorded the path for in the state store.
+ *
+ * Returns a summary; callers decide whether to log at info or warn.
+ */
+export declare function runWorktreeGc(basePath: string, store: StateStore, opts?: GcOptions): GcResult;
+export declare class WorktreeGc {
+    private basePath;
+    private store;
+    private intervalMs;
+    private timer;
+    constructor(basePath: string, store: StateStore, intervalMs: number);
+    start(): void;
+    stop(): void;
+    private tick;
+}

package/dist/worktree-gc.js

@@ -0,0 +1,139 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { log } from "./log.js";
+import { cleanupWorktree } from "./worktree.js";
+const TAG = "worktree-gc";
+/**
+ * One-shot garbage collection for `.harmony-worktrees/*`.
+ *
+ * A directory is removed when BOTH:
+ *   - no active run in the state store has it as its `worktreePath`, AND
+ *   - it was last modified more than `minAgeMs` ago (default 1h).
+ *
+ * The age check protects brand-new worktrees that a worker just created
+ * but hasn't yet recorded the path for in the state store.
+ *
+ * Returns a summary; callers decide whether to log at info or warn.
+ */
+export function runWorktreeGc(basePath, store, opts = {}) {
+    const minAgeMs = opts.minAgeMs ?? 60 * 60 * 1000;
+    const now = (opts.now ?? Date.now)();
+    const result = { checked: 0, removed: [], skipped: [], errors: [] };
+    const repoRoot = getRepoRoot();
+    if (!repoRoot) {
+        result.errors.push({ path: "<repo-root>", error: "not a git repo" });
+        return result;
+    }
+    const baseAbs = resolve(repoRoot, basePath);
+    let entries;
+    try {
+        entries = readdirSync(baseAbs);
+    }
+    catch {
+        // Directory doesn't exist yet — nothing to GC, not an error.
+        return result;
+    }
+    const activePaths = new Set(store
+        .getActiveRuns()
+        .map((r) => r.worktreePath)
+        .filter((p) => !!p));
+    for (const entry of entries) {
+        const full = resolve(baseAbs, entry);
+        result.checked++;
+        let mtimeMs;
+        try {
+            const stat = statSync(full);
+            if (!stat.isDirectory()) {
+                result.skipped.push(full);
+                continue;
+            }
+            mtimeMs = stat.mtimeMs;
+        }
+        catch (err) {
+            result.errors.push({
+                path: full,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        if (activePaths.has(full)) {
+            result.skipped.push(full);
+            continue;
+        }
+        if (now - mtimeMs < minAgeMs) {
+            result.skipped.push(full);
+            continue;
+        }
+        try {
+            cleanupWorktree(full);
+            result.removed.push(full);
+        }
+        catch (err) {
+            result.errors.push({
+                path: full,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Prune any stale metadata leftover from deleted worktrees.
+    try {
+        execFileSync("git", ["worktree", "prune"], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // non-fatal
+    }
+    if (result.removed.length > 0) {
+        log.info(TAG, `GC removed ${result.removed.length} orphan worktree(s): ${result.removed.map((p) => p.split("/").pop()).join(", ")}`);
+    }
+    if (result.errors.length > 0) {
+        log.warn(TAG, `GC had ${result.errors.length} error(s): ${result.errors
+            .map((e) => `${e.path}: ${e.error}`)
+            .join("; ")}`);
+    }
+    return result;
+}
+export class WorktreeGc {
+    basePath;
+    store;
+    intervalMs;
+    timer = null;
+    constructor(basePath, store, intervalMs) {
+        this.basePath = basePath;
+        this.store = store;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        log.info(TAG, `worktree GC every ${this.intervalMs / 1000}s`);
+        // Run once at startup, then on interval.
+        this.tick();
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    tick() {
+        try {
+            runWorktreeGc(this.basePath, this.store);
+        }
+        catch (err) {
+            log.warn(TAG, `GC tick failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}
+function getRepoRoot() {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/agent",
-  "version": "1.0.9",
+  "version": "1.1.1",
   "description": "Push-based agent daemon for Harmony — watches board assignments and spawns Claude CLI workers",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@supabase/supabase-js": "2.95.3",
-    "@gethmy/mcp": "^2.0.0"
+    "@gethmy/mcp": "^2.4.3"
   },
   "devDependencies": {
     "@harmony/shared": "workspace:*",