@gethmy/agent 1.4.2 → 1.6.0

package/dist/budget.d.ts

@@ -38,8 +38,10 @@ export declare class BudgetGuard {
      */
     isTerminal(reason: GuardReason): boolean;
     /**
-     * Apply the DLQ label to a card and post a comment explaining why.
-     * Safe to call repeatedly — labels are idempotent.
+     * Apply the DLQ label to a card, persist the reason, and append a
+     * post-mortem block to the card description listing the last 3 failure
+     * summaries. Safe to call repeatedly — labels are idempotent and the
+     * description block is delimited so reruns replace rather than stack.
      */
     markDlq(client: HarmonyApiClient, card: Card, reason: GuardReason, detail: string): Promise<void>;
 }

package/dist/budget.js

@@ -71,8 +71,10 @@ export class BudgetGuard {
             reason === "card_cost_cap");
     }
     /**
-     * Apply the DLQ label to a card and post a comment explaining why.
-     * Safe to call repeatedly — labels are idempotent.
+     * Apply the DLQ label to a card, persist the reason, and append a
+     * post-mortem block to the card description listing the last 3 failure
+     * summaries. Safe to call repeatedly — labels are idempotent and the
+     * description block is delimited so reruns replace rather than stack.
      */
     async markDlq(client, card, reason, detail) {
         await this.store.markDlq(card.id, `${reason}: ${detail}`);
@@ -86,9 +88,46 @@ export class BudgetGuard {
         catch (err) {
             log.warn(TAG, `failed to add dlq label to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
         }
+        try {
+            const recent = this.store.getRecentFailures(card.id, 3);
+            const block = buildDlqDescriptionBlock(reason, detail, recent);
+            const existing = card.description ?? "";
+            const stripped = stripDlqBlock(existing);
+            await client.updateCard(card.id, {
+                description: `${stripped}${stripped ? "\n\n" : ""}${block}`,
+            });
+        }
+        catch (err) {
+            log.warn(TAG, `failed to post DLQ summary to #${card.short_id}: ${err instanceof Error ? err.message : err}`);
+        }
         log.warn(TAG, `#${card.short_id} DLQ'd — ${reason}: ${detail}`);
     }
 }
+const DLQ_MARKER = "---\n**Agent DLQ**";
+function buildDlqDescriptionBlock(reason, detail, failures) {
+    const lines = [DLQ_MARKER, `Cap hit: ${reason} — ${detail}`];
+    if (failures.length > 0) {
+        lines.push("", "Recent failures:");
+        for (const f of failures) {
+            const when = new Date(f.ts).toISOString().replace("T", " ").slice(0, 16);
+            const tag = f.reason ? ` [${f.reason}]` : "";
+            const branch = f.recoveryBranch
+                ? `\n  recover: \`git fetch && git checkout ${f.recoveryBranch}\``
+                : "";
+            lines.push(`- ${when} UTC${tag} — ${f.summary}${branch}`);
+        }
+    }
+    else {
+        lines.push("", "_No prior failure summaries recorded._");
+    }
+    return lines.join("\n");
+}
+function stripDlqBlock(description) {
+    const idx = description.indexOf(DLQ_MARKER);
+    if (idx < 0)
+        return description.trimEnd();
+    return description.slice(0, idx).trimEnd();
+}
 function formatCents(cents) {
     return `$${(cents / 100).toFixed(2)}`;
 }

package/dist/completion.d.ts

@@ -1,5 +1,6 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card } from "@harmony/shared";
+import type { StateStore } from "./state-store.js";
 import type { CostUpdate } from "./stream-parser.js";
 import { type AgentConfig } from "./types.js";
 export interface SessionStats {
@@ -7,6 +8,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 +29,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, stateStore?: StateStore): Promise<void>;

package/dist/completion.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { moveCardToColumn } from "./board-helpers.js";
-import { createPullRequest, detectGitProvider, pushBranch } from "./git-pr.js";
+import { writeEpisode } from "./episode-writer.js";
+import { createPullRequest, detectGitProvider, getBranchWebUrl, pushBranch, } from "./git-pr.js";
 import { log } from "./log.js";
 import { AGENT_NAME, agentIdentifier } from "./types.js";
 import { attemptAutoFix, reportFindings, runVerification, } from "./verification.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, stateStore) {
+    // 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) {
@@ -41,7 +49,22 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
         cleanupWorktree(worktreePath, branchName);
         return;
     }
-    // 1. Verification gate
+    // 1. Push branch FIRST so commits are durable on origin regardless of
+    // verification outcome. A failed verify (below) then preserves the work
+    // under `agent-attempts/*` for `failedAttemptRetentionDays`. Without this
+    // ordering, verify failures used to orphan commits in a deleted worktree —
+    // recoverable only via `git reflog`.
+    log.info(TAG, `Pushing branch ${branchName} (pre-verify)...`);
+    try {
+        pushBranch(branchName, worktreePath);
+    }
+    catch (err) {
+        // Push failure shouldn't prevent verification from running, but the
+        // safety guarantee is gone — surface it loudly so the operator notices.
+        log.error(TAG, `pre-verify push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+    }
+    const recoveryUrl = getBranchWebUrl(branchName, worktreePath);
+    // 2. Verification gate
     if (config.verification.enabled) {
         await client.updateAgentProgress(card.id, {
             agentIdentifier: agentIdentifier(workerId),
@@ -51,6 +74,7 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
             progressPercent: 80,
         });
         let result = await runVerification(worktreePath, config, workerId);
+        let autoFixAttempts = 0;
         if (!result.passed && config.verification.autoFix) {
             for (let attempt = 0; attempt < config.verification.maxFixAttempts; attempt++) {
                 log.info(TAG, `Auto-fix attempt ${attempt + 1}/${config.verification.maxFixAttempts}`);
@@ -64,28 +88,61 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
                 const allErrors = [...result.buildErrors, ...result.lintWarnings];
                 await attemptAutoFix(worktreePath, config, allErrors);
                 result = await runVerification(worktreePath, config, workerId);
+                autoFixAttempts = attempt + 1;
                 if (result.passed) {
                     log.info(TAG, `Auto-fix succeeded on attempt ${attempt + 1}`);
+                    // Push again so the auto-fix commit is also durable on origin.
+                    try {
+                        pushBranch(branchName, worktreePath);
+                    }
+                    catch (err) {
+                        log.warn(TAG, `post-fix push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+                    }
                     break;
                 }
             }
         }
+        verificationResult = result;
         if (!result.passed) {
             log.warn(TAG, `Verification failed for #${card.short_id} — reporting findings`);
-            await reportFindings(client, card.id, result);
+            // Push the latest tip (including any auto-fix attempts) so the
+            // failed branch on origin reflects what verify saw.
+            try {
+                pushBranch(branchName, worktreePath);
+            }
+            catch (err) {
+                log.warn(TAG, `post-fail push failed for ${branchName}: ${err instanceof Error ? err.message : err}`);
+            }
+            const failureSummary = buildVerificationFailureSummary(result, autoFixAttempts);
+            try {
+                await stateStore?.recordFailureSummary(card.id, {
+                    summary: failureSummary,
+                    reason: "verification",
+                    recoveryBranch: branchName,
+                });
+            }
+            catch (err) {
+                log.debug(TAG, `recordFailureSummary failed: ${err instanceof Error ? err.message : err}`);
+            }
+            await reportFindings(client, card.id, result, {
+                branchName,
+                branchUrl: recoveryUrl,
+            });
             await moveCardToColumn(client, card, config.verification.failColumn);
             await client.endAgentSession(card.id, {
-                status: "paused",
+                status: "failed",
+                failureReason: "verification",
+                failureSummary,
+                recoveryBranch: branchName,
                 ...buildTokenPayload(sessionStats),
             });
+            // Local-only cleanup. The remote ref under `agent-attempts/*` stays
+            // up; the GC sweep (worktree-gc.ts) prunes it after retention.
             cleanupWorktree(worktreePath, branchName);
             return;
         }
         log.info(TAG, `Verification passed for #${card.short_id}`);
     }
-    // 2. Push branch (force-push on rework if remote branch already exists)
-    log.info(TAG, `Pushing branch ${branchName}...`);
-    pushBranch(branchName, worktreePath);
     // 3. Create PR
     let prUrl = null;
     if (config.completion.createPR) {
@@ -106,10 +163,47 @@ 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}` : ""}`);
 }
+function buildVerificationFailureSummary(result, autoFixAttempts) {
+    const counts = [];
+    if (result.buildErrors.length > 0) {
+        counts.push(`${result.buildErrors.length} build error(s)`);
+    }
+    if (result.lintWarnings.length > 0) {
+        counts.push(`${result.lintWarnings.length} lint issue(s)`);
+    }
+    if (result.reviewFindings.length > 0) {
+        counts.push(`${result.reviewFindings.length} review finding(s)`);
+    }
+    const head = counts.length > 0 ? counts.join(", ") : "verification failed";
+    const tail = autoFixAttempts > 0 ? ` after ${autoFixAttempts} auto-fix attempt(s)` : "";
+    return `${head}${tail}`;
+}
 function checkHasCommits(worktreePath, baseBranch) {
     try {
         const count = execFileSync("git", ["rev-list", "--count", `origin/${baseBranch}..HEAD`], { cwd: worktreePath, encoding: "utf-8" }).trim();

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/git-pr.d.ts

@@ -19,6 +19,19 @@ export declare function checkPrMergeStatus(prUrl: string, cwd: string, provider:
 export declare function extractPrUrl(description: string | null): string | null;
 export declare function remoteBranchExists(branchName: string, cwd: string): boolean;
 export declare function pushBranch(branchName: string, cwd: string): void;
+/**
+ * Push the current branch's tip to `newRef` on origin and delete `oldRef`.
+ * Used when an approved attempt graduates from `agent-attempts/*` to
+ * `agent/*` — keeps the commits durable across the rename and avoids any
+ * window where the work is unreachable on origin.
+ */
+export declare function renameRemoteBranch(oldRef: string, newRef: string, cwd: string): void;
+/**
+ * Best-effort public branch URL for the recovery button on a failed session.
+ * Returns null when we can't infer a tree URL — the daemon falls back to a
+ * plain `git fetch && git checkout <ref>` instruction in that case.
+ */
+export declare function getBranchWebUrl(branchName: string, cwd: string): string | null;
 export declare function buildPrBody(card: Card, commitLog: string): string;
 export declare function createPullRequest(card: Card, branchName: string, worktreePath: string, config: AgentConfig, provider: GitProvider): string | null;
 export declare function findExistingPr(branchName: string, worktreePath: string, provider: GitProvider): string | null;