@gethmy/agent 1.4.2 → 1.6.0

package/dist/types.d.ts

@@ -20,6 +20,12 @@ export interface AgentConfig {
     worktree: {
         basePath: string;
         baseBranch: string;
+        /** Remote-branch prefix while an attempt is still in-flight or failed. */
+        failedBranchPrefix: string;
+        /** Remote-branch prefix after a successful run reaches Review. */
+        approvedBranchPrefix: string;
+        /** Days to keep failed-attempt branches on origin before GC removes them. */
+        failedAttemptRetentionDays: number;
     };
     verification: {
         enabled: boolean;
@@ -98,3 +104,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/types.js

@@ -18,6 +18,9 @@ export const DEFAULT_AGENT_CONFIG = {
     worktree: {
         basePath: ".harmony-worktrees",
         baseBranch: "main",
+        failedBranchPrefix: "agent-attempts/",
+        approvedBranchPrefix: "agent/",
+        failedAttemptRetentionDays: 7,
     },
     verification: {
         enabled: true,

package/dist/verification.d.ts

@@ -12,7 +12,13 @@ export declare function runBuild(worktreePath: string, timeout: number): string[
 export declare function runLint(worktreePath: string, timeout: number): string[];
 export declare function runDeepReview(worktreePath: string, config: AgentConfig, workerId: number): Promise<string[]>;
 export declare function attemptAutoFix(worktreePath: string, config: AgentConfig, errors: string[]): void;
-export declare function reportFindings(client: HarmonyApiClient, cardId: string, result: VerificationResult): Promise<void>;
+export interface RecoveryInfo {
+    /** Remote ref where the failed attempt was pushed. */
+    branchName: string;
+    /** Public URL of the branch (GitHub/GitLab/Bitbucket tree view), if known. */
+    branchUrl: string | null;
+}
+export declare function reportFindings(client: HarmonyApiClient, cardId: string, result: VerificationResult, recovery?: RecoveryInfo | null): Promise<void>;
 export declare class DevServerReadinessError extends Error {
     constructor(message: string);
 }

package/dist/verification.js

@@ -160,8 +160,13 @@ export function attemptAutoFix(worktreePath, config, errors) {
         stdio: "pipe",
     });
 }
-export async function reportFindings(client, cardId, result) {
+export async function reportFindings(client, cardId, result, recovery) {
     const items = [];
+    if (recovery) {
+        const cmd = `git fetch && git checkout ${recovery.branchName}`;
+        const url = recovery.branchUrl ? ` (${recovery.branchUrl})` : "";
+        items.push(`Recovery: \`${cmd}\`${url}`);
+    }
     for (const err of result.buildErrors) {
         items.push(`Build: ${err}`);
     }

package/dist/worker.js

@@ -102,7 +102,7 @@ export class Worker {
         try {
             // --- PREPARING ---
             this.state = "preparing";
-            this.branchName = makeBranchName(card.short_id, card.title);
+            this.branchName = makeBranchName(card.short_id, card.title, this.config.worktree.failedBranchPrefix);
             log.info(this.tag, `Preparing #${card.short_id} "${card.title}"`);
             // Per-card attempt counter resets on success; DLQ triggers off it.
             await this.stateStore.incrementAttempt(card.id);
@@ -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, this.stateStore);
         }
         catch (err) {
             this.state = "error";

package/dist/worktree-gc.d.ts

@@ -1,4 +1,21 @@
 import type { StateStore } from "./state-store.js";
+export interface RemoteBranchGcOptions {
+    /** Prefix to scan (e.g. `agent-attempts/`). */
+    prefix: string;
+    /** Retention in days. Branches older than this are removed. */
+    retentionDays: number;
+    /** Optional sync clock, for deterministic tests. */
+    now?: () => number;
+}
+export interface RemoteBranchGcResult {
+    scanned: number;
+    removed: string[];
+    skipped: string[];
+    errors: Array<{
+        ref: string;
+        error: string;
+    }>;
+}
 export interface GcResult {
     checked: number;
     removed: string[];
@@ -27,12 +44,23 @@ export interface GcOptions {
  * Returns a summary; callers decide whether to log at info or warn.
  */
 export declare function runWorktreeGc(basePath: string, store: StateStore, opts?: GcOptions): GcResult;
+/**
+ * Sweep stale failed-attempt branches off the remote.
+ *
+ * Lists `origin/<prefix>*`, asks git for each ref's committer timestamp via
+ * `for-each-ref`, and deletes anything older than `retentionDays`. Runs on
+ * the same GC tick that handles worktree directories — protecting unpushed
+ * commits is the job of the daemon (always push before verify); this sweep
+ * just keeps the namespace tidy.
+ */
+export declare function pruneFailedRemoteBranches(opts: RemoteBranchGcOptions): RemoteBranchGcResult;
 export declare class WorktreeGc {
     private basePath;
     private store;
     private intervalMs;
+    private remoteOpts?;
     private timer;
-    constructor(basePath: string, store: StateStore, intervalMs: number);
+    constructor(basePath: string, store: StateStore, intervalMs: number, remoteOpts?: RemoteBranchGcOptions | undefined);
     start(): void;
     stop(): void;
     private tick;

package/dist/worktree-gc.js

@@ -96,15 +96,114 @@ export function runWorktreeGc(basePath, store, opts = {}) {
     }
     return result;
 }
+/**
+ * Sweep stale failed-attempt branches off the remote.
+ *
+ * Lists `origin/<prefix>*`, asks git for each ref's committer timestamp via
+ * `for-each-ref`, and deletes anything older than `retentionDays`. Runs on
+ * the same GC tick that handles worktree directories — protecting unpushed
+ * commits is the job of the daemon (always push before verify); this sweep
+ * just keeps the namespace tidy.
+ */
+export function pruneFailedRemoteBranches(opts) {
+    const result = {
+        scanned: 0,
+        removed: [],
+        skipped: [],
+        errors: [],
+    };
+    if (!opts.prefix)
+        return result;
+    // 0 or negative retention is opt-out — caller wants nothing pruned.
+    if (!Number.isFinite(opts.retentionDays) || opts.retentionDays <= 0) {
+        return result;
+    }
+    const repoRoot = getRepoRoot();
+    if (!repoRoot) {
+        result.errors.push({ ref: "<repo-root>", error: "not a git repo" });
+        return result;
+    }
+    // Refresh the remote refs we know about. Pruned remote branches drop from
+    // local tracking, so we never try to delete refs the server already lost.
+    try {
+        execFileSync("git", ["fetch", "--prune", "origin"], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch (err) {
+        result.errors.push({
+            ref: "fetch",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        // Continue — for-each-ref may still find usable cached refs.
+    }
+    const refPattern = `refs/remotes/origin/${opts.prefix}*`;
+    let listing = "";
+    try {
+        listing = execFileSync("git", [
+            "for-each-ref",
+            "--format=%(refname:strip=3) %(committerdate:unix)",
+            refPattern,
+        ], { cwd: repoRoot, encoding: "utf-8" });
+    }
+    catch (err) {
+        result.errors.push({
+            ref: refPattern,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return result;
+    }
+    const cutoffSecs = (opts.now ?? Date.now)() / 1000 - opts.retentionDays * 24 * 60 * 60;
+    for (const line of listing.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const sp = trimmed.lastIndexOf(" ");
+        if (sp < 0)
+            continue;
+        const ref = trimmed.slice(0, sp);
+        const ts = Number(trimmed.slice(sp + 1));
+        result.scanned++;
+        if (!Number.isFinite(ts) || ts >= cutoffSecs) {
+            result.skipped.push(ref);
+            continue;
+        }
+        try {
+            execFileSync("git", ["push", "origin", `:refs/heads/${ref}`], {
+                cwd: repoRoot,
+                stdio: "pipe",
+            });
+            result.removed.push(ref);
+        }
+        catch (err) {
+            result.errors.push({
+                ref,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (result.removed.length > 0) {
+        log.info(TAG, `Pruned ${result.removed.length} stale remote branch(es) under ${opts.prefix}: ${result.removed.join(", ")}`);
+    }
+    if (result.errors.length > 0) {
+        log.warn(TAG, `Remote branch GC had ${result.errors.length} error(s): ${result.errors
+            .map((e) => `${e.ref}: ${e.error}`)
+            .join("; ")}`);
+    }
+    return result;
+}
 export class WorktreeGc {
     basePath;
     store;
     intervalMs;
+    remoteOpts;
     timer = null;
-    constructor(basePath, store, intervalMs) {
+    constructor(basePath, store, intervalMs, remoteOpts) {
         this.basePath = basePath;
         this.store = store;
         this.intervalMs = intervalMs;
+        this.remoteOpts = remoteOpts;
     }
     start() {
         // Run once at startup, then on interval.
@@ -124,6 +223,14 @@ export class WorktreeGc {
         catch (err) {
             log.warn(TAG, `GC tick failed: ${err instanceof Error ? err.message : err}`);
         }
+        if (this.remoteOpts) {
+            try {
+                pruneFailedRemoteBranches(this.remoteOpts);
+            }
+            catch (err) {
+                log.warn(TAG, `Remote GC tick failed: ${err instanceof Error ? err.message : err}`);
+            }
+        }
     }
 }
 function getRepoRoot() {

package/dist/worktree.d.ts

@@ -9,5 +9,10 @@ export declare function createWorktree(basePath: string, baseBranch: string, bra
 export declare function cleanupWorktree(worktreePath: string, branchName?: string): void;
 /**
  * Generate a branch name from a card's short ID and title.
+ *
+ * Agent branches start under the failedBranchPrefix (default `agent-attempts/`)
+ * and are renamed to the approvedBranchPrefix (default `agent/`) only after the
+ * Review pipeline approves them. Branches under `agent-attempts/` are pruned
+ * by the GC after `failedAttemptRetentionDays`.
  */
-export declare function makeBranchName(shortId: number, title: string): string;
+export declare function makeBranchName(shortId: number, title: string, prefix?: string): string;

package/dist/worktree.js

@@ -158,8 +158,13 @@ export function cleanupWorktree(worktreePath, branchName) {
 }
 /**
  * Generate a branch name from a card's short ID and title.
+ *
+ * Agent branches start under the failedBranchPrefix (default `agent-attempts/`)
+ * and are renamed to the approvedBranchPrefix (default `agent/`) only after the
+ * Review pipeline approves them. Branches under `agent-attempts/` are pruned
+ * by the GC after `failedAttemptRetentionDays`.
  */
-export function makeBranchName(shortId, title) {
+export function makeBranchName(shortId, title, prefix = "agent-attempts/") {
     const slug = title
         .toLowerCase()
         .trim()
@@ -168,5 +173,5 @@ export function makeBranchName(shortId, title) {
         .replace(/-+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, 40);
-    return `agent/${shortId}-${slug || "task"}`;
+    return `${prefix}${shortId}-${slug || "task"}`;
 }

package/package.json

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