opentoad->pullfrog

* feat: add prepush lifecycle hook

Add `prepushScript` configuration — an optional shell script that runs
automatically before pushing code to the remote repository. Reuses the
existing `executeLifecycleHook` infrastructure (bash execution, 2-min
timeout, error propagation on non-zero exit). When unconfigured the
hook is a no-op.

Made-with: Cursor

* fix: add prepushScript to run-context API response, fix UI separator

Include prepushScript in the settings returned by the run-context
endpoint so the hook actually fires in production. Also fix the
separator pattern in AgentSettings to match the existing convention
(spacer + hr + spacer instead of margin).

Made-with: Cursor

agents/opentoad.ts

@@ -10,7 +10,7 @@
  * the agent process itself gets full env (needs LLM API keys, PATH, etc.).
  * security is enforced at the tool layer, not the process layer.
  */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
@@ -21,15 +21,14 @@ import { log } from "../utils/cli.ts";
 import { installFromNpmTarball } from "../utils/install.ts";
 import { spawn } from "../utils/subprocess.ts";
 import { ThinkingTimer } from "../utils/timer.ts";
+import type { TodoTracker } from "../utils/todoTracking.ts";
+import { getDevDependencyVersion } from "../utils/version.ts";
 import { type AgentResult, type AgentRunContext, type AgentUsage, agent } from "./shared.ts";
 
-// pinned CLI version
-const OPENCODE_CLI_VERSION = "1.1.56";
-
 async function installOpencodeCli(): Promise<string> {
   return await installFromNpmTarball({
     packageName: "opencode-ai",
-    version: OPENCODE_CLI_VERSION,
+    version: getDevDependencyVersion("opencode-ai"),
     executablePath: "bin/opencode",
     installDependencies: true,
   });
@@ -54,6 +53,7 @@ function buildSecurityConfig(ctx: AgentRunContext, model: string | undefined): s
       read: "allow",
       webfetch: "allow",
       external_directory: "deny",
+      skill: "allow",
     },
     mcp: {
       [ghPullfrogMcpName]: { type: "remote", url: ctx.mcpServerUrl },
@@ -117,7 +117,11 @@ function resolveOpenCodeModel(ctx: {
   if (ctx.modelSlug) {
     const resolved = resolveCliModel(ctx.modelSlug);
     if (resolved) {
-      log.info(`» model: ${resolved} (from repo config)`);
+      if (resolved !== ctx.modelSlug) {
+        log.info(`» model: ${ctx.modelSlug} (resolved to ${resolved})`);
+      } else {
+        log.info(`» model: ${resolved}`);
+      }
       return resolved;
     }
     log.warning(`» unknown model slug "${ctx.modelSlug}" — falling through to auto-select`);
@@ -170,6 +174,23 @@ function detectProviderError(text: string): string | null {
   return null;
 }
 
+function addSkill(params: { ref: string; skill: string; env: Record<string, string> }): void {
+  const result = spawnSync(
+    "npx",
+    ["skills", "add", params.ref, "--skill", params.skill, "-g", "-a", "opencode", "-y"],
+    {
+      env: { ...process.env, ...params.env },
+      stdio: "pipe",
+      timeout: 30_000,
+    }
+  );
+  if (result.status === 0) {
+    log.info(`installed ${params.skill} skill`);
+  } else {
+    log.info(`${params.skill} skill install failed: ${(result.stderr?.toString() || "").trim()}`);
+  }
+}
+
 // ── NDJSON event types ─────────────────────────────────────────────────────────
 
 interface OpenCodeInitEvent {
@@ -290,6 +311,7 @@ type RunParams = {
   args: string[];
   cwd: string;
   env: Record<string, string | undefined>;
+  todoTracker?: TodoTracker | undefined;
 };
 
 async function runOpenCode(params: RunParams): Promise<AgentResult> {
@@ -308,7 +330,7 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
   function buildUsage(): AgentUsage | undefined {
     return accumulatedTokens.input > 0 || accumulatedTokens.output > 0
       ? {
-          agent: "opentoad",
+          agent: "pullfrog",
           inputTokens: accumulatedTokens.input,
           outputTokens: accumulatedTokens.output,
         }
@@ -390,6 +412,17 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
       if (event.part?.state?.status === "completed" && event.part.state.output) {
         log.debug(`  output: ${event.part.state.output}`);
       }
+
+      // agent's explicit MCP report_progress takes priority over todo tracking
+      if (toolName.includes("report_progress") && params.todoTracker) {
+        log.debug("» report_progress detected, disabling todo tracking");
+        params.todoTracker.cancel();
+      }
+
+      // parse todowrite events for live progress tracking
+      if (toolName === "todowrite" && params.todoTracker?.enabled) {
+        params.todoTracker.update(event.part?.state?.input);
+      }
     },
     tool_result: (event: OpenCodeToolResultEvent) => {
       const toolId = event.part?.callID || event.tool_id;
@@ -531,6 +564,12 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
       },
     });
 
+    if (result.exitCode === 0) {
+      await params.todoTracker?.flush();
+    } else {
+      params.todoTracker?.cancel();
+    }
+
     const duration = performance.now() - startTime;
     log.info(
       `» ${params.label} completed in ${Math.round(duration)}ms with exit code ${result.exitCode}`
@@ -584,6 +623,7 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
 
     return { success: true, output: finalOutput || output, usage };
   } catch (error) {
+    params.todoTracker?.cancel();
     const duration = performance.now() - startTime;
     const errorMessage = error instanceof Error ? error.message : String(error);
     const isActivityTimeout = errorMessage.includes("activity timeout");
@@ -628,8 +668,19 @@ export const opentoad = agent({
         modelSlug: ctx.payload.model,
       });
 
-    const tempHome = ctx.tmpdir;
-    mkdirSync(join(tempHome, ".config", "opencode"), { recursive: true });
+    const homeEnv = {
+      HOME: ctx.tmpdir,
+      XDG_CONFIG_HOME: join(ctx.tmpdir, ".config"),
+    };
+
+    mkdirSync(join(homeEnv.XDG_CONFIG_HOME, "opencode"), { recursive: true });
+
+    const agentBrowserVersion = getDevDependencyVersion("agent-browser");
+    addSkill({
+      ref: `vercel-labs/agent-browser@v${agentBrowserVersion}`,
+      skill: "agent-browser",
+      env: homeEnv,
+    });
 
     const args = ["run", ctx.instructions.full, "--format", "json", "--print-logs"];
 
@@ -637,8 +688,7 @@ export const opentoad = agent({
     // security is enforced via OPENCODE_CONFIG_CONTENT (bash: deny) and MCP tool filtering.
     const env: Record<string, string | undefined> = {
       ...process.env,
-      HOME: tempHome,
-      XDG_CONFIG_HOME: join(tempHome, ".config"),
+      ...homeEnv,
       OPENCODE_CONFIG_CONTENT: buildSecurityConfig(ctx, model),
       GOOGLE_GENERATIVE_AI_API_KEY:
         process.env.GOOGLE_GENERATIVE_AI_API_KEY || process.env.GEMINI_API_KEY,
@@ -646,15 +696,16 @@ export const opentoad = agent({
 
     const repoDir = process.cwd();
 
-    log.debug(`» starting OpenToad (OpenCode): ${cliPath} ${args.join(" ")}`);
+    log.debug(`» starting Pullfrog (OpenCode): ${cliPath} ${args.join(" ")}`);
     log.debug(`» working directory: ${repoDir}`);
 
     return runOpenCode({
-      label: "OpenToad",
+      label: "Pullfrog",
       cliPath,
       args,
       cwd: repoDir,
       env,
+      todoTracker: ctx.todoTracker,
     });
   },
 });

agents/shared.ts

@@ -1,6 +1,7 @@
 import { log } from "../utils/cli.ts";
 import type { ResolvedInstructions } from "../utils/instructions.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
+import type { TodoTracker } from "../utils/todoTracking.ts";
 
 /**
  * token/cost usage data from a single agent run
@@ -33,6 +34,7 @@ export interface AgentRunContext {
   mcpServerUrl: string;
   tmpdir: string;
   instructions: ResolvedInstructions;
+  todoTracker?: TodoTracker | undefined;
 }
 
 export interface Agent {

get-installation-token/entry

@@ -25743,6 +25743,7 @@ async function apiFetch(options) {
 }
 
 // utils/retry.ts
+import { setTimeout as sleep } from "node:timers/promises";
 var defaultShouldRetry = (error2) => {
   if (!(error2 instanceof Error)) return false;
   return error2.name === "AbortError" || error2.message.includes("fetch failed") || error2.message.includes("ECONNRESET") || error2.message.includes("ETIMEDOUT");
@@ -25763,7 +25764,7 @@ async function retry(fn, options = {}) {
       }
       const delay = delayMs * attempt;
       log.info(`\xBB ${label} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delay}ms...`);
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await sleep(delay);
     }
   }
   throw lastError;

main.ts

@@ -1,6 +1,7 @@
 // changes to tool permissions should be reflected in wiki/granular-tools.md
 
 import * as core from "@actions/core";
+import { deleteProgressComment, reportProgress } from "./mcp/comment.ts";
 import {
   initToolState,
   startMcpHttpServer,
@@ -35,6 +36,7 @@ import { createTempDirectory, setupGit } from "./utils/setup.ts";
 import { killTrackedChildren } from "./utils/subprocess.ts";
 import { parseTimeString, TIMEOUT_DISABLED } from "./utils/time.ts";
 import { Timer } from "./utils/timer.ts";
+import { createTodoTracker } from "./utils/todoTracking.ts";
 import { getJobToken, resolveTokens } from "./utils/token.ts";
 import { resolveRun } from "./utils/workflow.ts";
 
@@ -203,6 +205,8 @@ export async function main(): Promise<MainResult> {
 
   const runInfo = await resolveRun({ octokit });
   let toolContext: ToolContext | undefined;
+  let progressCallbackDisabled = false;
+  let todoTracker: ReturnType<typeof createTodoTracker> | undefined;
 
   try {
     if (payload.cwd && process.cwd() !== payload.cwd) {
@@ -271,6 +275,7 @@ export async function main(): Promise<MainResult> {
       apiToken: runContext.apiToken,
       modes,
       postCheckoutScript: runContext.repoSettings.postCheckoutScript,
+      prepushScript: runContext.repoSettings.prepushScript,
       prApproveEnabled: runContext.repoSettings.prApproveEnabled,
       modeInstructions: runContext.repoSettings.modeInstructions,
       toolState,
@@ -289,6 +294,7 @@ export async function main(): Promise<MainResult> {
       repo: runContext.repo,
       modes,
       outputSchema,
+      learnings: runContext.repoSettings.learnings,
     });
     // log instructions as soon as they are fully resolved
     const logParts = [
@@ -308,11 +314,22 @@ export async function main(): Promise<MainResult> {
       checkIntervalMs: DEFAULT_ACTIVITY_CHECK_INTERVAL_MS,
     });
     activityTimeout.promise.catch(() => {}); // prevent unhandled rejection if agent wins race
+    todoTracker = createTodoTracker(async (body) => {
+      if (progressCallbackDisabled || !toolContext) return;
+      try {
+        await reportProgress(toolContext, { body });
+      } catch (err) {
+        log.debug(`progress update failed: ${err}`);
+      }
+    });
+    toolState.todoTracker = todoTracker;
+
     const agentPromise = agent.run({
       payload,
       mcpServerUrl: mcpHttpServer.url,
       tmpdir,
       instructions,
+      todoTracker,
     });
 
     // timeout enforcement: default is 1 hour, but can be overridden via flags in the prompt:
@@ -354,7 +371,7 @@ export async function main(): Promise<MainResult> {
       );
     }
 
-    // post-agent review cleanup: reportReviewNodeId → follow-up dispatch → delete progress comment.
+    // post-agent review cleanup: reportReviewNodeId → follow-up re-review dispatch.
     // runs after the agent exits so ordering is architecturally guaranteed (no LLM involvement).
     // best-effort: cleanup failures must not turn a successful agent run into a failure.
     if (toolContext) {
@@ -363,6 +380,25 @@ export async function main(): Promise<MainResult> {
       });
     }
 
+    // clean up stranded progress comments. two cases:
+    // 1. wasUpdated=false: nothing wrote to the comment ("Leaping into action" orphan)
+    // 2. tracker published a checklist but the agent never wrote a final summary
+    //    (hasPublished=true, finalSummaryWritten=false).
+    // in both cases, delete the comment so it doesn't linger with stale content.
+    // wasUpdated is intentionally NOT set here — cleanup is not a real progress update.
+    // uses finalSummaryWritten (not todoTracker.enabled) so cleanup survives API failures
+    // in report_progress where cancel() ran but the write didn't succeed.
+    const trackerWasLastWriter = todoTracker?.hasPublished && !toolState.finalSummaryWritten;
+    if (
+      toolContext &&
+      toolState.progressCommentId &&
+      (!toolState.wasUpdated || trackerWasLastWriter)
+    ) {
+      await deleteProgressComment(toolContext).catch((error) => {
+        log.debug(`stranded progress comment cleanup failed: ${error}`);
+      });
+    }
+
     await writeJobSummary(toolState);
 
     // emit structured output marker for test validation
@@ -378,6 +414,8 @@ export async function main(): Promise<MainResult> {
     });
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : "unknown error occurred";
+    progressCallbackDisabled = true;
+    todoTracker?.cancel();
     killTrackedChildren();
     log.error(errorMessage);
 

mcp/comment.ts

@@ -329,7 +329,7 @@ export async function reportProgress(
     };
   }
 
-  // null = progress comment was deliberately deleted (e.g. by create_pull_request_review)
+  // null = progress comment was deleted by stranded-comment cleanup in main.ts
   if (existingCommentId === null) {
     return { body, action: "skipped" };
   }
@@ -400,17 +400,33 @@ export function ReportProgressTool(ctx: ToolContext) {
   return tool({
     name: "report_progress",
     description:
-      "Share progress on the associated GitHub issue/PR. Call this to post updates as you work. The first call creates a comment, subsequent calls update it. Use this throughout your work to keep stakeholders informed.",
+      "Share progress on the associated GitHub issue/PR. The first call creates a comment; subsequent calls update it in place. You MUST call this at the end of every run with a brief final summary (1-3 sentences). The completed task list is automatically appended in a collapsible section — do not restate individual steps.",
     parameters: ReportProgress,
     execute: execute(async (params) => {
-      const reportParams: { body: string; target_plan_comment?: boolean } = { body: params.body };
+      let body = params.body;
+
+      // for non-plan calls: stop auto-updates, wait for in-flight writes to settle,
+      // then append completed task list collapsible
+      if (!params.target_plan_comment && ctx.toolState.todoTracker) {
+        ctx.toolState.todoTracker.cancel();
+        await ctx.toolState.todoTracker.settled();
+        const collapsible = ctx.toolState.todoTracker.renderCollapsible();
+        if (collapsible) {
+          body = `${body}\n\n${collapsible}`;
+        }
+      }
+
+      const reportParams: { body: string; target_plan_comment?: boolean } = { body };
       if (params.target_plan_comment !== undefined) {
         reportParams.target_plan_comment = params.target_plan_comment;
       }
       const result = await reportProgress(ctx, reportParams);
 
+      if (!params.target_plan_comment) {
+        ctx.toolState.finalSummaryWritten = true;
+      }
+
       if (result.action === "skipped") {
-        // no-op: no comment target, but progress is still tracked for job summary
         return {
           success: true,
           message:
@@ -428,9 +444,9 @@ export function ReportProgressTool(ctx: ToolContext) {
 
 /**
  * Delete the progress comment if it exists.
- * Used after submitting a PR review since the review body contains all necessary info.
- * Sets progressCommentId to null, which prevents future report_progress calls from
- * creating a new comment (the agent may call report_progress again after this).
+ * Used by main.ts for stranded-comment cleanup (orphaned "Leaping into action" or
+ * checklist left by the todo tracker when the agent didn't call report_progress).
+ * Sets progressCommentId to null so subsequent report_progress calls are no-ops.
  */
 export async function deleteProgressComment(ctx: ToolContext): Promise<boolean> {
   const existingCommentId = ctx.toolState.progressCommentId;
@@ -455,7 +471,6 @@ export async function deleteProgressComment(ctx: ToolContext): Promise<boolean>
 
   // set to null (not undefined) so report_progress skips instead of creating a new comment
   ctx.toolState.progressCommentId = null;
-  ctx.toolState.wasUpdated = true;
 
   return true;
 }

mcp/git.ts

@@ -2,6 +2,7 @@ import { regex } from "arkregex";
 import { type } from "arktype";
 import { log } from "../utils/cli.ts";
 import { $git } from "../utils/gitAuth.ts";
+import { executeLifecycleHook } from "../utils/lifecycle.ts";
 import { $ } from "../utils/shell.ts";
 import type { StoredPushDest, ToolContext } from "./server.ts";
 import { execute, tool } from "./shared.ts";
@@ -143,6 +144,8 @@ export function PushBranchTool(ctx: ToolContext) {
         ? ["--force", "-u", pushDest.remoteName, refspec]
         : ["-u", pushDest.remoteName, refspec];
 
+      await executeLifecycleHook({ event: "prepush", script: ctx.prepushScript });
+
       log.debug(`pushing ${branch} to ${pushDest.remoteName}/${pushDest.remoteBranch}`);
       if (force) {
         log.warning(`force pushing - this will overwrite remote history`);

mcp/learnings.ts

@@ -0,0 +1,41 @@
+import { type } from "arktype";
+import { apiFetch } from "../utils/apiFetch.ts";
+import type { ToolContext } from "./server.ts";
+import { execute, tool } from "./shared.ts";
+
+const UpdateLearningsParams = type({
+  learnings: type.string.describe(
+    "the FULL merged learnings as a flat bullet list. each line starts with `- `. one discrete, actionable fact per bullet. combine existing bullets from the prompt with your new discoveries. deduplicate — if an existing bullet covers the same fact, update it in place rather than adding a new one. drop bullets that are clearly wrong or no longer relevant to the current codebase. keep the list focused and concise."
+  ),
+});
+
+export function UpdateLearningsTool(ctx: ToolContext) {
+  return tool({
+    name: "update_learnings",
+    description:
+      "persist operational learnings about this repository (setup steps, test commands, key conventions, patterns). ONLY call this when you have high confidence the information is correct and broadly useful for future runs — not for one-off findings or uncertain observations. format: flat bullet list (`- ` per line, one fact per bullet). pass the FULL merged list — combine existing learnings from the prompt with new discoveries. deduplicate, and drop bullets that are clearly wrong or no longer relevant to the current codebase.",
+    parameters: UpdateLearningsParams,
+    execute: execute(async (params) => {
+      const response = await apiFetch({
+        path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/learnings`,
+        method: "PATCH",
+        headers: {
+          authorization: `Bearer ${ctx.apiToken}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          learnings: params.learnings,
+          model: ctx.toolState.model,
+        }),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`failed to update learnings: ${error}`);
+      }
+
+      return { success: true };
+    }),
+  });
+}

mcp/review.ts

@@ -70,6 +70,7 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
     description:
       "Submit a review for an existing pull request. " +
       "Each call creates a permanent, visible review on the PR — NEVER submit test or diagnostic reviews. " +
+      "Reviews with no body AND no comments are silently skipped (nothing to post). " +
       "IMPORTANT: 95%+ of feedback should be in 'comments' array with file paths and line numbers. " +
       "Only use 'body' for a 1-2 sentence summary with urgency and critical callouts. " +
       "Use 'suggestion' to propose replacement code - MUST preserve exact indentation of original code. " +
@@ -84,8 +85,9 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
       // set issue context (PRs are issues)
       ctx.toolState.issueNumber = pull_number;
 
-      // skip empty reviews (no body, no inline comments) — nothing to post
-      if (!body && comments.length === 0) {
+      // skip empty COMMENT reviews (no body, no inline comments) — nothing to post.
+      // APPROVE reviews are never skipped: the approval stamp itself is the content.
+      if (!approved && !body && comments.length === 0) {
         log.info(
           "review has no body and no inline comments — skipping submission (no issues found)"
         );

mcp/selectMode.ts

@@ -19,6 +19,10 @@ function resolveMode(modes: Mode[], modeName: string): Mode | null {
   return modes.find((m) => m.name.toLowerCase() === modeName.toLowerCase()) ?? null;
 }
 
+function learningsStep(n: number): string {
+  return `${n}. **learnings** (only if high confidence): if you discovered something about repo setup, test commands, conventions, or patterns that you are confident is correct and would reliably help future runs, call \`${ghPullfrogMcpName}/update_learnings\` to persist it. skip this step if you are unsure or the finding is speculative/one-off. format as a flat bullet list (\`- \` per line, one fact per bullet). merge with existing learnings from the prompt — pass the FULL merged list. deduplicate, and drop bullets that are clearly wrong or no longer relevant to the current codebase.`;
+}
+
 const modeGuidance: Record<string, string> = {
   Build: `### Checklist
 
@@ -40,6 +44,8 @@ const modeGuidance: Record<string, string> = {
    - create a PR via \`${ghPullfrogMcpName}/create_pull_request\`
    - call \`${ghPullfrogMcpName}/report_progress\` with the final summary including PR link
 
+${learningsStep(5)}
+
 ### Notes
 
 For simple, well-defined tasks, skip the plan phase and go straight to build.`,
@@ -86,7 +92,9 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
    - push changes via \`${ghPullfrogMcpName}/push_branch\`
    - reply to each comment using \`${ghPullfrogMcpName}/reply_to_review_comment\`
    - resolve addressed threads via \`${ghPullfrogMcpName}/resolve_review_thread\`
-   - call \`${ghPullfrogMcpName}/report_progress\` with a brief summary`,
+   - call \`${ghPullfrogMcpName}/report_progress\` with a brief summary
+
+${learningsStep(6)}`,
 
   Review: `### Checklist
 
@@ -103,10 +111,9 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
 
 3. Self-critique: review all drafted comments and drop any that are praise, style preferences, speculative/unverified claims, about pre-existing code unrelated to the PR, or not actionable.
 
-4. Submit a **single** review:
-   - call \`${ghPullfrogMcpName}/create_pull_request_review\` with all comments and a unified summary body
-   - call \`${ghPullfrogMcpName}/report_progress\` with the summary
-   - if no actionable issues found, skip the review — just call \`report_progress\` noting the PR was reviewed`,
+4. Submit:
+   - **actionable issues found**: call \`${ghPullfrogMcpName}/create_pull_request_review\` with all comments, a 1-3 sentence summary body, and \`approved: false\`. Then call \`report_progress\` with a 1-sentence summary.
+   - **no actionable issues found**: do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Reviewed — no issues found.").`,
 
   IncrementalReview: `### Checklist
 
@@ -126,10 +133,9 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
 
 5. Self-critique: drop any comments that are praise, style preferences, speculative, about pre-existing code, or not actionable.
 
-6. Submit a **single** review:
-   - if actionable issues found: call \`${ghPullfrogMcpName}/create_pull_request_review\` with \`approved: false\`, all comments, and an **empty body** (do NOT include a summary — inline comments speak for themselves and a top-level comment clutters the PR conversation on every re-review)
-   - if no actionable issues found: submit with \`approved: true\` and an **empty body** (no inline comments, no summary)
-   - do NOT call \`${ghPullfrogMcpName}/report_progress\` — incremental reviews should be silent`,
+6. Submit:
+   - **actionable issues found**: call \`${ghPullfrogMcpName}/create_pull_request_review\` with \`approved: false\`, all comments, and an **empty body** — inline comments speak for themselves, and a top-level body clutters the PR conversation on every re-review cycle. Then call \`report_progress\` with a 1-sentence summary.
+   - **no actionable issues found**: do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Re-reviewed — no new issues found.").`,
 
   Plan: `### Checklist
 
@@ -139,7 +145,9 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
 
 2. Produce a structured, actionable plan with clear milestones.
 
-3. Call \`${ghPullfrogMcpName}/report_progress\` with the plan.`,
+3. Call \`${ghPullfrogMcpName}/report_progress\` with the plan.
+
+${learningsStep(4)}`,
 
   PlanEdit: `### Checklist (editing existing plan)
 
@@ -170,7 +178,9 @@ An existing plan comment was found for this issue. Update that comment with the
 
 5. Finalize:
    - push changes via \`${ghPullfrogMcpName}/push_branch\`
-   - call \`${ghPullfrogMcpName}/report_progress\` with the diagnosis and fix summary`,
+   - call \`${ghPullfrogMcpName}/report_progress\` with the diagnosis and fix summary
+
+${learningsStep(6)}`,
 
   Task: `### Checklist
 
@@ -185,7 +195,9 @@ An existing plan comment was found for this issue. Update that comment with the
 3. Finalize:
    - call \`${ghPullfrogMcpName}/report_progress\` with results
    - if the task involved code changes, push via \`${ghPullfrogMcpName}/push_branch\` and create a PR via \`${ghPullfrogMcpName}/create_pull_request\`
-   - if the task involved labeling, commenting, or other GitHub operations, perform those directly`,
+   - if the task involved labeling, commenting, or other GitHub operations, perform those directly
+
+${learningsStep(4)}`,
 
   Summarize: `### Checklist
 
@@ -195,8 +207,9 @@ An existing plan comment was found for this issue. Update that comment with the
    - PR metadata (title, file count, commit count, base/head branches)
    - format instructions from EVENT INSTRUCTIONS (if any); otherwise use default format: TL;DR, key changes list, per-change sections with plain-language \`##\` titles and before/after framing
    - instruct it to use the TOC to selectively read relevant diff sections, not the entire file
-   - instruct it to return the full summary markdown via \`${ghPullfrogMcpName}/set_output\`
+   - instruct it to return the full summary markdown as its final response
 3. After the subagent completes, call \`${ghPullfrogMcpName}/create_issue_comment\` with \`type: "Summary"\` and the summary body.
+4. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Posted PR summary.").
 
 ### Effort
 
@@ -212,8 +225,9 @@ An existing summary comment was found for this PR. Update it rather than creatin
    - the diff file path and PR metadata
    - the existing summary body (\`previousSummaryBody\`) so it can update rather than rewrite from scratch
    - format instructions from EVENT INSTRUCTIONS (if any)
-   - instruct it to produce an updated summary reflecting the current state of the PR and return via \`${ghPullfrogMcpName}/set_output\`
+   - instruct it to produce an updated summary reflecting the current state of the PR and return it as its final response
 4. After the subagent completes, call \`${ghPullfrogMcpName}/edit_issue_comment\` with \`commentId: existingSummaryCommentId\` (from this response) and the updated summary body.
+5. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Updated PR summary.").
 
 ### Effort
 

mcp/server.ts

@@ -1,15 +1,18 @@
 // this must be imported first
 import "./arkConfig.ts";
 import { createServer } from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
 import { FastMCP, type Tool } from "fastmcp";
 import type { AgentUsage } from "../agents/index.ts";
 import { ghPullfrogMcpName } from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { PrepResult } from "../prep/index.ts";
+import { closeBrowserDaemon } from "../utils/browser.ts";
 import { log } from "../utils/cli.ts";
 import type { OctokitWithPlugins } from "../utils/github.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
 import type { RunContextData } from "../utils/runContextData.ts";
+import type { TodoTracker } from "../utils/todoTracking.ts";
 import { CheckoutPrTool } from "./checkout.ts";
 import { GetCheckSuiteLogsTool } from "./checkSuite.ts";
 import {
@@ -29,6 +32,7 @@ import { GetIssueCommentsTool } from "./issueComments.ts";
 import { GetIssueEventsTool } from "./issueEvents.ts";
 import { IssueInfoTool } from "./issueInfo.ts";
 import { AddLabelsTool } from "./labels.ts";
+import { UpdateLearningsTool } from "./learnings.ts";
 import { SetOutputTool } from "./output.ts";
 import { CreatePullRequestTool, UpdatePullRequestBodyTool } from "./pr.ts";
 import { PullRequestInfoTool } from "./prInfo.ts";
@@ -49,6 +53,8 @@ export type BackgroundProcess = {
   pidPath: string;
 };
 
+export type BrowserDaemon = { binDir: string; error?: never } | { binDir?: never; error: string };
+
 export type StoredPushDest = {
   remoteName: string;
   remoteBranch: string;
@@ -68,6 +74,7 @@ export interface ToolState {
   checkoutSha?: string;
   selectedMode?: string;
   backgroundProcesses: Map<string, BackgroundProcess>;
+  browserDaemon?: BrowserDaemon | undefined;
   review?: {
     id: number;
     nodeId: string;
@@ -80,8 +87,14 @@ export interface ToolState {
   };
   // undefined = no comment yet, number = active comment, null = deliberately deleted
   progressCommentId: number | null | undefined;
+  // immutable snapshot: true if a progress comment was pre-created at init time.
+  // survives deleteProgressComment so handleAgentResult can still detect "expected but never reported".
+  hadProgressComment: boolean;
   lastProgressBody?: string;
   wasUpdated?: boolean;
+  // set after a non-plan report_progress successfully writes the final summary.
+  // decoupled from todoTracker.enabled so cleanup detection survives API failures.
+  finalSummaryWritten?: boolean;
   // set by select_mode when Plan + issue_number and plan-comment API returns existing plan (for report_progress target_plan_comment)
   existingPlanCommentId?: number;
   previousPlanBody?: string;
@@ -90,6 +103,7 @@ export interface ToolState {
   output?: string;
   usageEntries: AgentUsage[];
   model?: string | undefined;
+  todoTracker?: TodoTracker | undefined;
 }
 
 interface InitToolStateParams {
@@ -106,6 +120,7 @@ export function initToolState(params: InitToolStateParams): ToolState {
 
   return {
     progressCommentId: resolvedId,
+    hadProgressComment: !!resolvedId,
     backgroundProcesses: new Map(),
     usageEntries: [],
   };
@@ -120,6 +135,7 @@ export interface ToolContext {
   apiToken: string;
   modes: Mode[];
   postCheckoutScript: string | null;
+  prepushScript: string | null;
   prApproveEnabled: boolean;
   modeInstructions: Record<string, string>;
   toolState: ToolState;
@@ -191,9 +207,13 @@ function buildCommonTools(ctx: ToolContext, outputSchema?: JsonSchema): Tool<any
     GitTool(ctx),
     GitFetchTool(ctx),
     UploadFileTool(ctx),
-    SetOutputTool(ctx, outputSchema),
   ];
 
+  const isStandalone = ctx.payload.event.trigger === "unknown";
+  if (isStandalone || outputSchema) {
+    tools.push(SetOutputTool(ctx, outputSchema));
+  }
+
   // MCP shell with filtered env (no secrets leaked to child processes)
   if (ctx.payload.shell === "restricted") {
     tools.push(ShellTool(ctx));
@@ -213,6 +233,7 @@ function buildOrchestratorTools(ctx: ToolContext, outputSchema?: JsonSchema): To
     DeleteBranchTool(ctx),
     CreatePullRequestTool(ctx),
     UpdatePullRequestBodyTool(ctx),
+    UpdateLearningsTool(ctx),
   ];
 }
 
@@ -304,7 +325,7 @@ async function killBackgroundProcesses(toolState: ToolState): Promise<void> {
       // already dead
     }
   }
-  await new Promise((resolve) => setTimeout(resolve, 200));
+  await sleep(200);
   for (const proc of backgroundProcesses.values()) {
     try {
       process.kill(-proc.pid, "SIGKILL");
@@ -332,6 +353,7 @@ export async function startMcpHttpServer(
   return {
     url: startResult.url,
     [Symbol.asyncDispose]: async () => {
+      closeBrowserDaemon(ctx.toolState);
       await killBackgroundProcesses(ctx.toolState);
       await startResult.server.stop();
     },

mcp/shell.ts

@@ -4,7 +4,9 @@ import { randomUUID } from "node:crypto";
 import { closeSync, openSync, writeFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { type } from "arktype";
+import { ensureBrowserDaemon } from "../utils/browser.ts";
 import { log } from "../utils/log.ts";
 import { resolveEnv } from "../utils/secrets.ts";
 import type { ToolContext } from "./server.ts";
@@ -115,7 +117,12 @@ function spawnShell(params: SpawnParams): ChildProcess {
     // sudo is only needed for unshare; the actual command should run as the normal user
     // to avoid ownership mismatches with files created by the Node.js parent process.
     const username = userInfo().username;
-    const escaped = params.command.replace(/'/g, "'\\''");
+    // su -p resets PATH on many Linux systems (ALWAYS_SET_PATH in /etc/login.defs).
+    // restore it from the SANDBOX_PATH env var that survives the su transition.
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: we need to restore the PATH variable
+    const pathRestore = 'export PATH="${SANDBOX_PATH:-$PATH}"; ';
+    const escaped = (pathRestore + params.command).replace(/'/g, "'\\''");
+    envArgs.push(`SANDBOX_PATH=${params.env.PATH ?? ""}`);
     return spawn(
       "sudo",
       [
@@ -195,6 +202,21 @@ Do NOT use this tool for git commands — use the dedicated git tools instead.`,
       const cwd = params.working_directory ?? process.cwd();
       const env = resolveEnv(ctx.payload.shell === "enabled" ? "inherit" : "restricted");
 
+      if (params.command.includes("agent-browser")) {
+        const daemonError = ensureBrowserDaemon(ctx.toolState);
+        if (daemonError) {
+          return {
+            output: `browser daemon unavailable: ${daemonError}`,
+            exit_code: 1,
+            timed_out: false,
+          };
+        }
+        const binDir = ctx.toolState.browserDaemon?.binDir;
+        if (binDir) {
+          env.PATH = `${binDir}:${env.PATH ?? ""}`;
+        }
+      }
+
       if (params.background) {
         const tempDir = getTempDir();
         const handle = `bg-${randomUUID().slice(0, 8)}`;
@@ -305,7 +327,7 @@ export function KillBackgroundTool(ctx: ToolContext) {
       } catch {
         // already dead
       }
-      await new Promise((resolve) => setTimeout(resolve, 200));
+      await sleep(200);
       try {
         process.kill(-proc.pid, "SIGKILL");
       } catch {

modes.ts

@@ -15,7 +15,7 @@ export const ModeSchema = type({
   prompt: "string",
 });
 
-const reportProgressInstruction = `Use ${ghPullfrogMcpName}/report_progress to share progress and results. Continue calling it as you make progress — it will update the same comment. Never create additional comments manually.`;
+const reportProgressInstruction = `Use ${ghPullfrogMcpName}/report_progress to share your **final** results in 1-3 sentences. The completed task list is automatically preserved in a collapsible section below your summary — do not repeat individual steps in the summary. Focus on the outcome and link to any artifacts (PRs, branches). Never create additional comments manually.`;
 
 const dependencyInstallationStep = `If this task will require running tests, builds, linters, or CLI commands that need installed packages, call \`${ghPullfrogMcpName}/start_dependency_installation\` NOW. This is non-blocking and allows dependencies to install in the background while you continue. Later, call \`${ghPullfrogMcpName}/await_dependency_installation\` before running commands that need them. Skip this step if only reading code or answering questions.`;
 
@@ -47,14 +47,12 @@ export function computeModes(): Mode[] {
 
 7. **COMMIT** - Commit your changes using \`${ghPullfrogMcpName}/git\` (e.g., \`git add .\` then \`git commit -m "message"\`), then push with \`${ghPullfrogMcpName}/push_branch\`. Do NOT use \`git push\` directly - it requires credentials that only the MCP tool provides.
 
-8. **PROGRESS** - ${reportProgressInstruction}
-
-9. **PR** - Determine whether to create a PR (if not already on a PR branch):
+8. **PR** - Determine whether to create a PR (if not already on a PR branch):
    - **Default behavior**: Create a PR using ${ghPullfrogMcpName}/create_pull_request with an informative title and body. If you are working in the context of an issue (check EVENT DATA for \`issue_number\` where \`is_pr\` is not true), include "Closes #<issue_number>" in the PR body to auto-close the issue when merged.
    - **Draft PR request**: If the user explicitly asks for a draft PR (e.g. "draft PR", "create as draft", "WIP"), create a PR with \`draft: true\`.
    - **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.
 
-10. **FINAL REPORT** - Call report_progress one final time ONLY if you haven't already included all the important information (PR links, branch links, summary) in a previous report_progress call. If you already called report_progress with complete information including PR links after creating the PR, you do NOT need to call it again. Only make a final call if you need to add missing information. When making the final call, ensure it includes:
+9. **FINAL REPORT** - ${reportProgressInstruction} Ensure the summary includes:
    - A summary of what was accomplished
    - Links to any artifacts created (PRs, branches, issues)
    - If you created a PR, ALWAYS include the PR link. e.g.:
@@ -66,7 +64,6 @@ export function computeModes(): Mode[] {
      [\`pullfrog/branch-name\`](https://github.com/pullfrog/scratch/tree/pullfrog/branch-name) • [Create PR ➔](https://github.com/pullfrog/scratch/compare/main...pullfrog/branch-name?quick_pull=1&title=<informative_title>&body=<informative_body>)
      \`\`\`
 
-   Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task. Please review the PR." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.
 `,
     },
     {
@@ -120,14 +117,13 @@ Keep the progress comment extremely brief. The summary should be 1-2 sentences m
    - **Impact analysis**: Identify what was removed, renamed, or deprecated in the PR. Use grep to search the broader codebase for remaining references to those things in code, tests, docs, comments, and configs. Report stale references in the review body.
    - Do NOT stop at "this looks reasonable." Dig until you either find a problem or have concrete evidence there isn't one.
 
-4. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable: the author should need to change something in response. 2-3 sentences max. Use the NEW line number from the diff (second column: \`| OLD | NEW | TYPE | CODE\`). If no issues found, skip to step 5. NO COMPLIMENTS. NO NITPICKING ABOUT CHANGES UNRELATED TO THE MAIN CHANGE. Non-actionable comments (praise, style preferences, minor optimizatfixons, documentation nits) must not be drafted.
+4. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable: the author should need to change something in response. 2-3 sentences max. Use the NEW line number from the diff (second column: \`| OLD | NEW | TYPE | CODE\`). If no issues found, skip to step 5. NO COMPLIMENTS. NO NITPICKING ABOUT CHANGES UNRELATED TO THE MAIN CHANGE. Non-actionable comments (praise, style preferences, minor optimizations, documentation nits) must not be drafted.
 
 5. **WRITE SUMMARY** - Draft a 1-3 sentence summary for the review body. If issues were found, include urgency level and any concerns about code outside the diff. If no issues were found, write a brief approval summary (e.g., "Changes look good. No issues found.").
 
-6. **SUBMIT** — Always submit a review via ${ghPullfrogMcpName}/create_pull_request_review:
-   - \`body\`: The summary from step 5
-   - \`comments\`: The inline comments from step 4
-   - \`approved\`: Set to \`true\` ONLY if the review contains no actionable feedback — neither inline comments nor actionable content in the body. An approval signals "no changes needed."
+6. **SUBMIT** — Determine whether to submit a review:
+   - **Issues found**: Submit via ${ghPullfrogMcpName}/create_pull_request_review with the summary body from step 5, the inline comments from step 4, and \`approved: false\`. Then call \`report_progress\` with a 1-sentence summary (e.g., "Reviewed — found 3 issues.").
+   - **No issues found**: Do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Reviewed — no issues found.").
 
 ${permalinkTip}
 `,
@@ -159,12 +155,9 @@ ${permalinkTip}
 
 6. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable. 2-3 sentences max. Use the NEW line number from the full PR diff. NO COMPLIMENTS. NO NITPICKING.
 
-7. **WRITE SUMMARY** - Draft a 1-3 sentence summary for the review body. Focus on what changed since the last review and whether the new changes are sound. If issues were found, include urgency level. If no issues were found, write a brief approval summary.
-
-8. **SUBMIT** — Use ${ghPullfrogMcpName}/create_pull_request_review:
-   - \`body\`: The summary from step 7
-   - \`comments\`: The inline comments from step 6
-   - \`approved\`: Set to \`true\` ONLY if the review contains no actionable feedback — neither inline comments nor actionable content in the body. An approval signals "no changes needed."
+7. **SUBMIT** — Determine whether to submit a review:
+   - **Issues found**: Submit via ${ghPullfrogMcpName}/create_pull_request_review with \`approved: false\`, the inline comments from step 6, and an **empty body** — inline comments speak for themselves, and a top-level body clutters the PR conversation on every re-review cycle. Then call \`report_progress\` with a 1-sentence summary (e.g., "Re-reviewed — found 2 issues in the new commits.").
+   - **No issues found**: Do NOT submit a review. Call \`report_progress\` with a brief note (e.g., "Re-reviewed — no new issues found.").
 
 ${permalinkTip}
 `,
@@ -308,9 +301,7 @@ Your job is to fix issues THIS PR introduced, not to fix all CI failures. If in
      - **Draft PR request**: If the user explicitly asks for a draft PR (e.g. "draft PR", "create as draft", "WIP"), create a PR with \`draft: true\`.
      - **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.
 
-5. **PROGRESS** - ${reportProgressInstruction}
-
-Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.`,
+5. **PROGRESS** - ${reportProgressInstruction}`,
     },
     {
       name: "Summarize",
@@ -326,6 +317,8 @@ Do NOT overwrite a good comment with links/details with a generic message like "
 
 4. **POST** - Call ${ghPullfrogMcpName}/create_issue_comment with type: 'Summary' and the summary body.
 
+5. **PROGRESS** - ${reportProgressInstruction}
+
 ${permalinkTip}`,
     },
   ];

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pullfrog/pullfrog",
-  "version": "0.0.182",
+  "version": "0.0.183",
   "type": "module",
   "files": [
     "index.js",
@@ -31,7 +31,6 @@
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.0",
     "@octokit/webhooks-types": "^7.6.1",
-    "@opencode-ai/sdk": "^1.0.143",
     "@standard-schema/spec": "1.1.0",
     "@toon-format/toon": "^1.0.0",
     "ajv": "^8.18.0",
@@ -47,6 +46,7 @@
     "turndown": "^7.2.0"
   },
   "devDependencies": {
+    "agent-browser": "0.21.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/node": "^24.7.2",
     "@types/semver": "^7.7.1",
@@ -54,6 +54,7 @@
     "arg": "^5.0.2",
     "esbuild": "^0.25.9",
     "husky": "^9.0.0",
+    "opencode-ai": "1.1.56",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17",
     "yaml": "^2.8.2"

pnpm-lock.yaml

@@ -26,9 +26,6 @@ importers:
       '@octokit/webhooks-types':
         specifier: ^7.6.1
         version: 7.6.1
-      '@opencode-ai/sdk':
-        specifier: ^1.0.143
-        version: 1.0.143
       '@standard-schema/spec':
         specifier: 1.1.0
         version: 1.1.0
@@ -81,6 +78,9 @@ importers:
       '@types/turndown':
         specifier: ^5.0.5
         version: 5.0.6
+      agent-browser:
+        specifier: 0.21.0
+        version: 0.21.0
       arg:
         specifier: ^5.0.2
         version: 5.0.2
@@ -90,12 +90,15 @@ importers:
       husky:
         specifier: ^9.0.0
         version: 9.1.7
+      opencode-ai:
+        specifier: 1.1.56
+        version: 1.1.56
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
       vitest:
         specifier: ^4.0.17
-        version: 4.0.17(@types/node@24.7.2)(yaml@2.8.2)
+        version: 4.0.17(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2)
       yaml:
         specifier: ^2.8.2
         version: 2.8.2
@@ -547,9 +550,6 @@ packages:
   '@octokit/webhooks-types@7.6.1':
     resolution: {integrity: sha512-S8u2cJzklBC0FgTwWVLaM8tMrDuDMVE4xiTK4EYXM9GntyvrdbSoxqDQa+Fh57CCNApyIpyeqPhhFEmHPfrXgw==}
 
-  '@opencode-ai/sdk@1.0.143':
-    resolution: {integrity: sha512-dtmkBfJ7IIAHzL6KCzAlwc9GybfJONVeCsF6ePYySpkuhslDbRkZBJYb5vqGd1H5zdsgjc6JjuvmOf0rPWUL6A==}
-
   '@rollup/rollup-android-arm-eabi@4.55.1':
     resolution: {integrity: sha512-9R0DM/ykwfGIlNu6+2U09ga0WXeZ9MRC2Ter8jnz8415VbuIykVuc6bhdrbORFZANDmTDvq26mJrEVTl8TdnDg==}
     cpu: [arm]
@@ -753,6 +753,10 @@ packages:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
 
+  agent-browser@0.21.0:
+    resolution: {integrity: sha512-isVHEeb2WL5hLhr4o+zNmcYwmBrldxvrH+FIoRoUmDxyrHr3bhIS6L8BlUMHqT77YtkPq0YSmwoBRrwqeouw9Q==}
+    hasBin: true
+
   ajv-formats@3.0.1:
     resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
     peerDependencies:
@@ -1209,6 +1213,10 @@ packages:
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+    hasBin: true
+
   jose@6.1.3:
     resolution: {integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==}
 
@@ -1316,6 +1324,65 @@ packages:
   once@1.4.0:
     resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
 
+  opencode-ai@1.1.56:
+    resolution: {integrity: sha512-OAF0G/1jVXpOrCh++M5gFEZ0bRLiXOnbxSYMFx5TOoD0OhCjHJS1JlARzaLDAx461qBnn+jocI9BBxD0wwFH3Q==}
+    hasBin: true
+
+  opencode-darwin-arm64@1.1.56:
+    resolution: {integrity: sha512-0HqvLm7tcYZr4VJgEzi3Wicia5M9yCX66O7Cv470Qu4+GGbCC2sTTmzQu6pCehSleYgkZsiSBNRcFcW/6F7v0Q==}
+    cpu: [arm64]
+    os: [darwin]
+
+  opencode-darwin-x64-baseline@1.1.56:
+    resolution: {integrity: sha512-Z9QO9cTC9TnlUxTfEtDbvZbRFxc5Je8rs2Ei0cLH46W9gHGhh1fW4oX64tcrlhF5NUDKJzr/qwdoMfmKkeu53A==}
+    cpu: [x64]
+    os: [darwin]
+
+  opencode-darwin-x64@1.1.56:
+    resolution: {integrity: sha512-8ZhNd4sFbDviT1OJs42C35Bx2/z6mkcb7uNhPHX3KKm27KOm7cYjFQa1UTF5or3ZpjkjPQpR/cpo7TELvnnmRA==}
+    cpu: [x64]
+    os: [darwin]
+
+  opencode-linux-arm64-musl@1.1.56:
+    resolution: {integrity: sha512-f30SmYX4xE2fUsnNl66dDX++8iTMI9PLXz7BRHhgXL4XAdMpUUJbOKIsw3ZUB0KWHwjR8cjkEJQOZxR3HPbrZg==}
+    cpu: [arm64]
+    os: [linux]
+
+  opencode-linux-arm64@1.1.56:
+    resolution: {integrity: sha512-wEmIEXiEKghurQYgKY5yFUFOmnT/QIlAbYnVeH73gSqOwlYFUUlowXLDJnF+3OGd6m000qalhCxjExL7qKINWw==}
+    cpu: [arm64]
+    os: [linux]
+
+  opencode-linux-x64-baseline-musl@1.1.56:
+    resolution: {integrity: sha512-EC8EGTJCgTZgGIMZdQjOKGXw02+igo0am1Ry6wrPrB0li7XBlYbY6dz8tL3FlknRVMLamtGtb3tXQ6tqbwjX0g==}
+    cpu: [x64]
+    os: [linux]
+
+  opencode-linux-x64-baseline@1.1.56:
+    resolution: {integrity: sha512-jKOvhkNLcn0h6zmKX+hDdkODijSVDxjAGTZp8BPbJCCJVxnKll9dYfDMTqxi3YN6yXp6sBvyaJT1mcpf8knkeA==}
+    cpu: [x64]
+    os: [linux]
+
+  opencode-linux-x64-musl@1.1.56:
+    resolution: {integrity: sha512-9BFYBPgpY2RrUd7/Ul0VNh+6B9l0FmCNRUV4yYmeFGee9ZDgPem5YGicsKAMQqS/5X0jW3ZWje+KBbBQz4RMwQ==}
+    cpu: [x64]
+    os: [linux]
+
+  opencode-linux-x64@1.1.56:
+    resolution: {integrity: sha512-0FP3BzLjn+a9naTtm9hpHibJ+eV1RkI+tItcDQXKwHtvzoBUvytDRP8v6TotEHNtNF0ZLAb3OGurwDIIdtLarg==}
+    cpu: [x64]
+    os: [linux]
+
+  opencode-windows-x64-baseline@1.1.56:
+    resolution: {integrity: sha512-zEokdohfoDjWzwULvlSq0Y/tRoVmz2/6GofYO936buPQf09cBcPqpAgLUjZV+pQI0Atyd05YG3BCO4PQxmXzdw==}
+    cpu: [x64]
+    os: [win32]
+
+  opencode-windows-x64@1.1.56:
+    resolution: {integrity: sha512-zm/oaWT5uGrW3DumKRHiqv2L2pKwrTvhsT4XUSfIPLQn5EvrYNU6bh3WFO4v71ZBjSIKx5Q7rEvTEQvFiFEZFQ==}
+    cpu: [x64]
+    os: [win32]
+
   package-manager-detector@1.6.0:
     resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
@@ -2060,8 +2127,6 @@ snapshots:
 
   '@octokit/webhooks-types@7.6.1': {}
 
-  '@opencode-ai/sdk@1.0.143': {}
-
   '@rollup/rollup-android-arm-eabi@4.55.1':
     optional: true
 
@@ -2182,13 +2247,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.17(vite@7.3.1(@types/node@24.7.2)(yaml@2.8.2))':
+  '@vitest/mocker@4.0.17(vite@7.3.1(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2))':
     dependencies:
       '@vitest/spy': 4.0.17
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@24.7.2)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2)
 
   '@vitest/pretty-format@4.0.17':
     dependencies:
@@ -2222,6 +2287,8 @@ snapshots:
       mime-types: 3.0.2
       negotiator: 1.0.0
 
+  agent-browser@0.21.0: {}
+
   ajv-formats@3.0.1(ajv@8.17.1):
     optionalDependencies:
       ajv: 8.17.1
@@ -2752,6 +2819,9 @@ snapshots:
 
   isexe@2.0.0: {}
 
+  jiti@2.6.1:
+    optional: true
+
   jose@6.1.3: {}
 
   jose@6.2.0: {}
@@ -2855,6 +2925,53 @@ snapshots:
     dependencies:
       wrappy: 1.0.2
 
+  opencode-ai@1.1.56:
+    optionalDependencies:
+      opencode-darwin-arm64: 1.1.56
+      opencode-darwin-x64: 1.1.56
+      opencode-darwin-x64-baseline: 1.1.56
+      opencode-linux-arm64: 1.1.56
+      opencode-linux-arm64-musl: 1.1.56
+      opencode-linux-x64: 1.1.56
+      opencode-linux-x64-baseline: 1.1.56
+      opencode-linux-x64-baseline-musl: 1.1.56
+      opencode-linux-x64-musl: 1.1.56
+      opencode-windows-x64: 1.1.56
+      opencode-windows-x64-baseline: 1.1.56
+
+  opencode-darwin-arm64@1.1.56:
+    optional: true
+
+  opencode-darwin-x64-baseline@1.1.56:
+    optional: true
+
+  opencode-darwin-x64@1.1.56:
+    optional: true
+
+  opencode-linux-arm64-musl@1.1.56:
+    optional: true
+
+  opencode-linux-arm64@1.1.56:
+    optional: true
+
+  opencode-linux-x64-baseline-musl@1.1.56:
+    optional: true
+
+  opencode-linux-x64-baseline@1.1.56:
+    optional: true
+
+  opencode-linux-x64-musl@1.1.56:
+    optional: true
+
+  opencode-linux-x64@1.1.56:
+    optional: true
+
+  opencode-windows-x64-baseline@1.1.56:
+    optional: true
+
+  opencode-windows-x64@1.1.56:
+    optional: true
+
   package-manager-detector@1.6.0: {}
 
   parse-ms@4.0.0: {}
@@ -3159,7 +3276,7 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vite@7.3.1(@types/node@24.7.2)(yaml@2.8.2):
+  vite@7.3.1(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2):
     dependencies:
       esbuild: 0.27.2
       fdir: 6.5.0(picomatch@4.0.3)
@@ -3170,12 +3287,13 @@ snapshots:
     optionalDependencies:
       '@types/node': 24.7.2
       fsevents: 2.3.3
+      jiti: 2.6.1
       yaml: 2.8.2
 
-  vitest@4.0.17(@types/node@24.7.2)(yaml@2.8.2):
+  vitest@4.0.17(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2):
     dependencies:
       '@vitest/expect': 4.0.17
-      '@vitest/mocker': 4.0.17(vite@7.3.1(@types/node@24.7.2)(yaml@2.8.2))
+      '@vitest/mocker': 4.0.17(vite@7.3.1(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2))
       '@vitest/pretty-format': 4.0.17
       '@vitest/runner': 4.0.17
       '@vitest/snapshot': 4.0.17
@@ -3192,7 +3310,7 @@ snapshots:
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@24.7.2)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.7.2)(jiti@2.6.1)(yaml@2.8.2)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.7.2

post

@@ -41556,7 +41556,7 @@ var core3 = __toESM(require_core(), 1);
 // package.json
 var package_default = {
   name: "@pullfrog/pullfrog",
-  version: "0.0.182",
+  version: "0.0.183",
   type: "module",
   files: [
     "index.js",
@@ -41587,7 +41587,6 @@ var package_default = {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.0",
     "@octokit/webhooks-types": "^7.6.1",
-    "@opencode-ai/sdk": "^1.0.143",
     "@standard-schema/spec": "1.1.0",
     "@toon-format/toon": "^1.0.0",
     ajv: "^8.18.0",
@@ -41603,6 +41602,7 @@ var package_default = {
     turndown: "^7.2.0"
   },
   devDependencies: {
+    "agent-browser": "0.21.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/node": "^24.7.2",
     "@types/semver": "^7.7.1",
@@ -41610,6 +41610,7 @@ var package_default = {
     arg: "^5.0.2",
     esbuild: "^0.25.9",
     husky: "^9.0.0",
+    "opencode-ai": "1.1.56",
     typescript: "^5.9.3",
     vitest: "^4.0.17",
     yaml: "^2.8.2"
@@ -41752,10 +41753,15 @@ async function validateStuckProgressComment(params) {
       repo: params.repo,
       comment_id: commentId
     });
-    if (commentResult.data.body?.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
+    const body = commentResult.data.body ?? "";
+    if (body.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
       log.info(`[post] comment ${commentId} is stuck on "Leaping into action"`);
       return commentId;
     }
+    if (/^- \[[ x]\] |^- \*\*→\*\* |^- ~~/.test(body)) {
+      log.info(`[post] comment ${commentId} is stuck on a todo checklist`);
+      return commentId;
+    }
     log.info(`[post] comment ${commentId} is not stuck (already updated or different content)`);
     return null;
   } catch (error2) {

utils/browser.ts

@@ -0,0 +1,133 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ToolState } from "../mcp/server.ts";
+import { log } from "./cli.ts";
+import { filterEnv } from "./secrets.ts";
+import { getDevDependencyVersion } from "./version.ts";
+
+// agent-browser already discovers chrome via `which` and the playwright cache as fallbacks,
+// so this list only needs to cover the GHA ubuntu-latest runner where we know the exact path.
+const CHROME_PATHS = ["/usr/bin/google-chrome-stable"];
+
+let systemChromePath: string | undefined;
+
+function findSystemChromePath(): string | undefined {
+  if (typeof systemChromePath === "string") {
+    // return cached result but normalize to undefined if empty
+    return systemChromePath || undefined;
+  }
+  for (const p of CHROME_PATHS) {
+    if (existsSync(p)) {
+      systemChromePath = p;
+      log.info(`found system chrome: ${p}`);
+      return p;
+    }
+  }
+  // set to an empty string to indicate no system chrome found
+  // and to avoid repeated lookups
+  systemChromePath = "";
+  log.info(`no system chrome found (checked: ${CHROME_PATHS.join(", ")})`);
+}
+
+function buildEnv(): Record<string, string> {
+  const env: Record<string, string> = { ...filterEnv() };
+  const chromePath = findSystemChromePath();
+  if (chromePath) {
+    env.AGENT_BROWSER_EXECUTABLE_PATH = chromePath;
+  }
+  return env;
+}
+
+/**
+ * ensure the agent-browser daemon is running by issuing a real command.
+ *
+ * agent-browser is stateful — it manages a persistent browser process via a
+ * daemon that communicates over a Unix socket. we start the daemon here,
+ * outside of ShellTool, because ShellTool's child process lifecycle would
+ * kill it between invocations and the daemon must survive across calls.
+ *
+ * despite ShellTool commands running inside unshare-sandboxed namespaces,
+ * they can still reach this daemon because the Unix socket is discoverable
+ * regardless of unshare's PID/mount isolation. starting the daemon in the
+ * host namespace keeps it alive while sandboxed shells come and go.
+ *
+ * agent-browser auto-starts its daemon on the first CLI invocation and
+ * keeps it alive via the socket for subsequent commands.
+ * we run `open about:blank` as the seed command to trigger this.
+ * idempotent — only runs once.
+ */
+export function ensureBrowserDaemon(toolState: ToolState): string | undefined {
+  if (toolState.browserDaemon) {
+    return toolState.browserDaemon.error;
+  }
+
+  const agentBrowserVersion = getDevDependencyVersion("agent-browser");
+  log.info(`installing agent-browser@${agentBrowserVersion}...`);
+  const install = spawnSync("npm", ["install", "-g", `agent-browser@${agentBrowserVersion}`], {
+    stdio: "pipe",
+    encoding: "utf-8",
+  });
+  if (install.status !== 0) {
+    const error = `agent-browser install failed: ${(install.stderr || install.stdout || "unknown error").trim()}`;
+    log.error(error);
+    toolState.browserDaemon = { error };
+    return error;
+  }
+  log.info("agent-browser installed");
+
+  let binDir: string;
+  try {
+    const binPath = execFileSync("which", ["agent-browser"], { encoding: "utf-8" }).trim();
+    binDir = dirname(binPath);
+    log.info(`agent-browser binary: ${binPath}`);
+  } catch {
+    const error = "agent-browser binary not found in PATH after install";
+    log.error(error);
+    toolState.browserDaemon = { error };
+    return error;
+  }
+
+  const env = buildEnv();
+
+  // `open about:blank` triggers daemon auto-start and returns once the daemon + browser are ready
+  log.info("starting browser daemon...");
+  const seed = spawnSync("agent-browser", ["open", "about:blank"], {
+    env,
+    stdio: "pipe",
+    encoding: "utf-8",
+    timeout: 30_000,
+  });
+
+  if (seed.status !== 0) {
+    const output = (seed.stderr || seed.stdout || "unknown error").trim();
+    const error = `agent-browser open about:blank failed (exit=${seed.status}): ${output}`;
+    log.error(error);
+    toolState.browserDaemon = { error };
+    return error;
+  }
+  log.debug(`seed command done (exit=0): ${(seed.stdout || "").trim()}`);
+
+  toolState.browserDaemon = { binDir };
+  log.info("browser daemon ready");
+}
+
+export function closeBrowserDaemon(toolState: ToolState): void {
+  if (!toolState.browserDaemon?.binDir) {
+    delete toolState.browserDaemon;
+    return;
+  }
+  delete toolState.browserDaemon;
+
+  try {
+    log.info("closing browser daemon...");
+    spawnSync("agent-browser", ["close"], {
+      env: filterEnv(),
+      stdio: "pipe",
+      timeout: 10_000,
+    });
+    log.info("browser daemon closed");
+  } catch {
+    // best-effort
+  }
+}

utils/install.ts

@@ -4,6 +4,7 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pipeline } from "node:stream/promises";
+import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "./cli.ts";
 
 export interface InstallFromNpmTarballParams {
@@ -172,7 +173,7 @@ async function fetchWithRetry(
       const waitSeconds = parseInt(retryAfter, 10);
       if (!Number.isNaN(waitSeconds) && waitSeconds > 0) {
         log.info(`» rate limited, waiting ${waitSeconds} seconds before retry...`);
-        await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
+        await sleep(waitSeconds * 1000);
         const retryResponse = await fetch(url, { headers });
         if (!retryResponse.ok) {
           throw new Error(

utils/instructions.ts

@@ -11,6 +11,7 @@ interface InstructionsContext {
   repo: RunContextData["repo"];
   modes: Mode[];
   outputSchema?: Record<string, unknown> | undefined;
+  learnings: string | null;
 }
 
 function buildRuntimeContext(ctx: InstructionsContext): string {
@@ -211,7 +212,13 @@ When posting comments via ${ghPullfrogMcpName}, write as a professional team mem
 
 ### Progress reporting
 
-ALWAYS use \`report_progress\` to share your results and progress — never \`create_issue_comment\`. The \`report_progress\` tool updates the pre-created progress comment on the issue/PR. Using \`create_issue_comment\` instead creates duplicate comments and leaves the progress comment stuck in its initial state. The \`create_issue_comment\` tool is only for creating NEW standalone comments unrelated to your task progress.
+**Task list**: at the start of every run, create an internal task list based on the steps in your current mode. Update it as you complete each step. The system automatically renders this list to the progress comment — you do not need to call \`report_progress\` for this.
+
+**\`report_progress\`**: you MUST call this exactly once at the end of every run with a brief final summary (1-3 sentences). Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the completed task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps.
+
+Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task (e.g., Plan comments, PR Summary comments).
+
+**After a PR review is submitted**, still call \`report_progress\` with your final summary. The progress comment persists as a record of what was done.
 
 ### If you get stuck
 
@@ -328,13 +335,20 @@ interface AssembleFullPromptInput {
   runtime: string;
   system: string;
   contextSections: string;
+  learnings: string | null;
 }
 
 function assembleFullPrompt(ctx: AssembleFullPromptInput): string {
+  const learningsSection = ctx.learnings
+    ? `************* REPO INTELLIGENCE *************\n\n${ctx.learnings}`
+    : "";
+
   const rawFull = `************* RUNTIME CONTEXT *************
 
 ${ctx.runtime}
 
+${learningsSection}
+
 ${ctx.system}
 
 ${ctx.contextSections}`;
@@ -359,8 +373,6 @@ ${ctx.modes.map((m) => `- "${m.name}": ${m.description}`).join("\n")}
 
 Follow the mode guidance to complete the task. Use your native file and shell tools for local operations, and the ${ghPullfrogMcpName} MCP tools for GitHub/git operations.
 
-When done, call \`${ghPullfrogMcpName}/set_output\` with the final result. This makes it available as the GitHub Action output.
-
 ### No-action cases
 
 If the task clearly requires no work, call \`${ghPullfrogMcpName}/report_progress\` directly to explain why no action is needed.`;
@@ -385,6 +397,7 @@ If the task clearly requires no work, call \`${ghPullfrogMcpName}/report_progres
     runtime: inputs.runtime,
     system,
     contextSections,
+    learnings: ctx.learnings,
   });
 
   return {

utils/postCleanup.ts

@@ -70,11 +70,20 @@ async function validateStuckProgressComment(
       comment_id: commentId,
     });
 
-    if (commentResult.data.body?.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
+    const body = commentResult.data.body ?? "";
+
+    if (body.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
       log.info(`[post] comment ${commentId} is stuck on "Leaping into action"`);
       return commentId;
     }
 
+    // detect stranded todo checklists left by the tracker when the process was killed
+    // before the agent could call report_progress with a final summary
+    if (/^- \[[ x]\] |^- \*\*→\*\* |^- ~~/.test(body)) {
+      log.info(`[post] comment ${commentId} is stuck on a todo checklist`);
+      return commentId;
+    }
+
     log.info(`[post] comment ${commentId} is not stuck (already updated or different content)`);
     return null;
   } catch (error) {

utils/retry.ts

@@ -1,3 +1,4 @@
+import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "./cli.ts";
 
 export type RetryOptions = {
@@ -38,7 +39,7 @@ export async function retry<T>(fn: () => Promise<T>, options: RetryOptions = {})
 
       const delay = delayMs * attempt;
       log.info(`» ${label} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delay}ms...`);
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await sleep(delay);
     }
   }
 

utils/reviewCleanup.ts

@@ -1,5 +1,4 @@
 import type { WriteablePayload } from "../external.ts";
-import { deleteProgressComment } from "../mcp/comment.ts";
 import { reportReviewNodeId } from "../mcp/review.ts";
 import type { ToolContext } from "../mcp/server.ts";
 import { log } from "./cli.ts";
@@ -34,8 +33,6 @@ export async function postReviewCleanup(ctx: ToolContext): Promise<void> {
       "follow-up re-review dispatch"
     );
   }
-
-  await bestEffort(() => deleteProgressComment(ctx), "delete progress comment");
 }
 
 async function bestEffort(fn: () => Promise<unknown>, label: string): Promise<void> {

utils/run.ts

@@ -19,7 +19,7 @@ export async function handleAgentResult(ctx: HandleAgentResultParams): Promise<M
     };
   }
 
-  if (!ctx.toolState.wasUpdated && ctx.toolState.progressCommentId && !ctx.silent) {
+  if (!ctx.toolState.wasUpdated && ctx.toolState.hadProgressComment && !ctx.silent) {
     const error = ctx.result.error || "agent completed without reporting progress";
     try {
       await reportErrorToComment({

utils/runContext.ts

@@ -14,10 +14,12 @@ export interface RepoSettings {
   modes: Mode[];
   setupScript: string | null;
   postCheckoutScript: string | null;
+  prepushScript: string | null;
   push: PushPermission;
   shell: ShellPermission;
   prApproveEnabled: boolean;
   modeInstructions: Record<string, string>;
+  learnings: string | null;
 }
 
 export interface RunContext {
@@ -32,10 +34,12 @@ const defaultSettings: RepoSettings = {
   modes: [],
   setupScript: null,
   postCheckoutScript: null,
+  prepushScript: null,
   push: "restricted",
   shell: "restricted",
   prApproveEnabled: false,
   modeInstructions: {},
+  learnings: null,
 };
 
 const defaultRunContext: RunContext = {
@@ -91,6 +95,7 @@ export async function fetchRunContext(params: {
         modes: data.settings?.modes ?? [],
         setupScript: data.settings?.setupScript ?? null,
         postCheckoutScript: data.settings?.postCheckoutScript ?? null,
+        prepushScript: data.settings?.prepushScript ?? null,
       },
       apiToken: data.apiToken,
       oss: data.oss ?? false,

utils/todoTracking.ts

@@ -0,0 +1,154 @@
+import { log } from "./log.ts";
+
+type TodoItem = {
+  id: string;
+  content: string;
+  status: "pending" | "in_progress" | "completed" | "cancelled";
+};
+
+function isValidTodoStatus(value: string): value is TodoItem["status"] {
+  return (
+    value === "pending" || value === "in_progress" || value === "completed" || value === "cancelled"
+  );
+}
+
+function parseTodowriteInput(input: unknown): { todos: unknown[]; merge: boolean } | undefined {
+  if (!input || typeof input !== "object" || !("todos" in input)) return undefined;
+  if (!Array.isArray(input.todos)) return undefined;
+  const merge = "merge" in input && input.merge === true;
+  return { todos: input.todos, merge };
+}
+
+function parseTodoItem(entry: unknown, index: number): TodoItem | undefined {
+  if (!entry || typeof entry !== "object") return undefined;
+  if (!("content" in entry) || typeof entry.content !== "string") return undefined;
+  const id = "id" in entry && typeof entry.id === "string" ? entry.id : String(index);
+  const status =
+    "status" in entry && typeof entry.status === "string" && isValidTodoStatus(entry.status)
+      ? entry.status
+      : "pending";
+  return { id, content: entry.content, status };
+}
+
+function renderTodoMarkdown(todos: TodoItem[]): string {
+  return todos
+    .map((todo) => {
+      switch (todo.status) {
+        case "completed":
+          return `- [x] ${todo.content}`;
+        case "cancelled":
+          return `- ~~${todo.content}~~`;
+        case "in_progress":
+          return `- **→** ${todo.content}`;
+        case "pending":
+          return `- [ ] ${todo.content}`;
+        default:
+          todo.status satisfies never;
+          return `- [ ] ${todo.content}`;
+      }
+    })
+    .join("\n");
+}
+
+export type TodoTracker = {
+  update: (input: unknown) => void;
+  flush: () => Promise<void>;
+  cancel: () => void;
+  /** resolves when any in-flight onUpdate call completes */
+  settled: () => Promise<void>;
+  renderCollapsible: () => string;
+  readonly enabled: boolean;
+  /** true after the tracker has successfully called onUpdate at least once */
+  readonly hasPublished: boolean;
+};
+
+const DEBOUNCE_MS = 2000;
+
+export function createTodoTracker(onUpdate: (body: string) => Promise<void>): TodoTracker {
+  const state = new Map<string, TodoItem>();
+  let enabled = true;
+  let hasPublished = false;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let inflightPromise: Promise<void> = Promise.resolve();
+
+  function scheduleUpdate() {
+    if (!enabled) return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      if (!enabled || state.size === 0) return;
+      const markdown = renderTodoMarkdown(Array.from(state.values()));
+      inflightPromise = inflightPromise
+        .then(async () => {
+          if (!enabled) return;
+          await onUpdate(markdown);
+          hasPublished = true;
+        })
+        .catch((err) => {
+          log.debug(`todo progress update failed: ${err}`);
+        });
+    }, DEBOUNCE_MS);
+  }
+
+  return {
+    update(input: unknown) {
+      if (!enabled) return;
+      const parsed = parseTodowriteInput(input);
+      if (!parsed) return;
+      if (!parsed.merge) state.clear();
+      for (const [index, entry] of parsed.todos.entries()) {
+        const item = parseTodoItem(entry, index);
+        if (item) state.set(item.id, item);
+      }
+      log.debug(`» todowrite: ${state.size} items tracked`);
+      scheduleUpdate();
+    },
+
+    async flush() {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (!enabled || state.size === 0) return;
+      const markdown = renderTodoMarkdown(Array.from(state.values()));
+      inflightPromise = inflightPromise
+        .then(async () => {
+          if (!enabled) return;
+          await onUpdate(markdown);
+          hasPublished = true;
+        })
+        .catch((err) => {
+          log.debug(`todo progress flush failed: ${err}`);
+        });
+      await inflightPromise;
+    },
+
+    cancel() {
+      enabled = false;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+    },
+
+    async settled() {
+      await inflightPromise;
+    },
+
+    renderCollapsible(): string {
+      if (state.size === 0) return "";
+      const todos = Array.from(state.values());
+      const completed = todos.filter((t) => t.status === "completed").length;
+      const markdown = renderTodoMarkdown(todos);
+      return `<details>\n<summary>Task list (${completed}/${todos.length} completed)</summary>\n\n${markdown}\n\n</details>`;
+    },
+
+    get enabled() {
+      return enabled;
+    },
+
+    get hasPublished() {
+      return hasPublished;
+    },
+  };
+}

utils/version.ts

@@ -0,0 +1,10 @@
+import semver from "semver";
+import packageJson from "../package.json" with { type: "json" };
+
+export function getDevDependencyVersion(name: keyof typeof packageJson.devDependencies): string {
+  const version = packageJson.devDependencies[name];
+  if (!semver.valid(version)) {
+    throw new Error(`dev dependency "${name}" must be a pinned version, got "${version}"`);
+  }
+  return version;
+}