bump action version to 0.1.2

ci: prune openai/gpt-pro from default models-live matrix (#637 )
* ci: prune openai/gpt-pro from default models-live matrix gpt-5.5-pro burns ~$2.40/run ($30/M input, $180/M output) — flagship reasoning tier with hidden reasoning tokens dominating cost. Multiplied by every push that touches a resolution-affecting file, the bill is untenable for a smoke that just verifies set_output works. Pruned by default; re-enable with INCLUDE_EXPENSIVE=1 or MATRIX_FILTER when validating the alias on demand. Also adds a comment-frugality rule to AGENTS.md. * ci: include list-aliases.ts in models paths-filter The matrix builder is resolution-affecting from a validation standpoint — a regression to it (e.g. accidentally pruning all aliases) wouldn't trigger models-live on its own commit.
2026-05-08 23:37:52 +00:00 · 2026-05-08 23:36:26 +00:00 · 2026-05-08 23:35:58 +00:00 · 2026-05-08 23:32:20 +00:00 · 2026-05-08 23:27:42 +00:00 · 2026-05-08 23:00:41 +00:00
31 changed files with 884 additions and 223 deletions
@@ -407,6 +407,12 @@ async function runClaude(params: RunParams): Promise<ClaudeRunResult> {
      activityTimeout: 300_000,
      onActivityTimeout: params.onActivityTimeout,
      stdio: ["ignore", "pipe", "pipe"],
+      // run claude in its own process group so SIGKILL on activity timeout /
+      // outer cancellation reaches any subprocesses it spawns (rg, file
+      // watchers, mcp transports, etc). claude itself is a node bundle so
+      // there's no shim-orphan issue like opencode-ai/bin/opencode, but
+      // detached + killGroup is the right default for any agent runtime.
+      killGroup: true,
      onStdout: async (chunk) => {
        const text = chunk.toString();
        output += text;
@@ -721,7 +727,9 @@ export const claude = agent({
      stopScript: ctx.stopScript,
      summaryFilePath: ctx.summaryFilePath,
      summarySeed: ctx.summarySeed,
-      reflectionPrompt: buildLearningsReflectionPrompt("claude"),
+      reflectionPrompt: ctx.learningsFilePath
+        ? buildLearningsReflectionPrompt(ctx.learningsFilePath)
+        : undefined,
      canResume: (r) => Boolean(r.sessionId),
      resume: async (c) => {
        const sessionId = c.previousResult.sessionId;
@@ -12,7 +12,7 @@
 * security is enforced at the tool layer, not the process layer.
 */
 import { execFileSync } from "node:child_process";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { pullfrogMcpName } from "../external.ts";
@@ -26,6 +26,11 @@ import { SPAWN_ACTIVITY_TIMEOUT_CODE, SpawnTimeoutError, spawn } from "../utils/
 import { ThinkingTimer } from "../utils/timer.ts";
 import type { TodoTracker } from "../utils/todoTracking.ts";
 import { getDevDependencyVersion } from "../utils/version.ts";
+import {
+  PULLFROG_BUS_EVENT_TYPE,
+  PULLFROG_OPENCODE_PLUGIN_FILENAME,
+  PULLFROG_OPENCODE_PLUGIN_SOURCE,
+} from "./opencodePlugin.ts";
 import { buildLearningsReflectionPrompt, runPostRunRetryLoop } from "./postRun.ts";
 import { REVIEWER_AGENT_NAME, REVIEWER_SYSTEM_PROMPT } from "./reviewer.ts";
 import { formatWithLabel, ORCHESTRATOR_LABEL, SessionLabeler } from "./sessionLabeler.ts";
@@ -280,6 +285,36 @@ interface OpenCodeErrorEvent {
  [key: string]: unknown;
 }

+/**
+ * Envelope event emitted by our `.opencode/plugin/pullfrog-events.ts` (the
+ * source lives in `opencodePlugin.ts`). The plugin subscribes to opencode's
+ * bus via `bus.subscribeAll()` and re-emits non-orchestrator
+ * `message.part.updated` events on stdout so subagent activity surfaces here.
+ *
+ * `bus_event.properties.part` matches the same `Part` shape that opencode's
+ * `cli/cmd/run.ts` uses to drive its own emit() calls, so we can route the
+ * inner part through the existing `tool_use` / `step_start` / `step_finish`
+ * / `text` handlers by synthesizing the equivalent OpenCode-style event.
+ */
+interface OpenCodeBusEnvelopeEvent {
+  type: "pullfrog_bus_event";
+  bus_event?: {
+    type?: string;
+    properties?: {
+      part?: {
+        sessionID?: string;
+        type?: string;
+        time?: { end?: number | string };
+        state?: { status?: string };
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    };
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
 type OpenCodeEvent =
  | OpenCodeInitEvent
  | OpenCodeMessageEvent
@@ -289,7 +324,8 @@ type OpenCodeEvent =
  | OpenCodeToolUseEvent
  | OpenCodeToolResultEvent
  | OpenCodeResultEvent
-  | OpenCodeErrorEvent;
+  | OpenCodeErrorEvent
+  | OpenCodeBusEnvelopeEvent;

 // ── runner ──────────────────────────────────────────────────────────────────────

@@ -324,15 +360,12 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
  // per-session labeler so parallel subagent log lines can be differentiated.
  // the orchestrator's task tool_use events seed the labeler; the next
  // previously-unseen sessionID consumes the head of the pending-label queue.
-  // NB: opencode's runtime currently encapsulates subagent execution inside
-  // the `task` tool — subagent-internal tool_use/tool_result events do not
-  // surface on the parent's NDJSON stream. The labeler is therefore mostly
-  // dormant in practice for opencode (no per-event session differentiation
-  // is needed because there are no per-subagent events). The orchestrator's
-  // `task` dispatch log (with `description: <lens>`) and the per-task
-  // duration log below are the actual attribution surface available today.
-  // The labeler is kept in place defensively so that if/when opencode begins
-  // streaming subagent sessions, attribution flips on with no further work.
+  // upstream opencode's `cli/cmd/run.ts` filters subagent events out of its
+  // NDJSON stream (`part.sessionID !== sessionID`), so we ship a per-run
+  // plugin (`action/agents/opencodePlugin.ts`, written into the tmpdir at
+  // setup) that re-emits non-orchestrator `message.part.updated` events. those
+  // arrive here as `pullfrog_bus_event` envelopes and feed the labeler with
+  // real data per subagent session.
  const labeler = new SessionLabeler();
  function eventLabel(event: Record<string, unknown>): string {
    const sid = event.sessionID ?? event.session_id;
@@ -522,25 +555,31 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
      // label is already bound); the dispatch label is for the next new
      // sessionID that appears.
      if (toolName === "task") {
-        const taskInput = (event.part?.state?.input ?? {}) as {
-          description?: string;
-          subagent_type?: string;
-          prompt?: string;
-        };
-        const dispatchedLabel = labeler.recordTaskDispatch(taskInput);
-        // dual-index by callID (fast path) AND in a FIFO queue (fallback path
-        // for when opencode's task tool_result carries a different callID).
-        const dispatch: TaskDispatch = {
-          label: dispatchedLabel,
-          startedAt: performance.now(),
-          toolUseCallID: toolId,
-        };
-        taskDispatchByCallID.set(toolId, dispatch);
-        pendingTaskDispatches.push(dispatch);
-        log.info(
-          `» dispatching subagent: ${dispatchedLabel}` +
-            (taskInput.subagent_type ? ` (subagent_type=${taskInput.subagent_type})` : "")
-        );
+        // may have been pre-registered via the plugin's early task-dispatch
+        // announcement (`pullfrog_bus_event` handler). dedupe on callID so
+        // we don't record the same dispatch twice (which would corrupt the
+        // FIFO label queue).
+        if (!taskDispatchByCallID.has(toolId)) {
+          const taskInput = (event.part?.state?.input ?? {}) as {
+            description?: string;
+            subagent_type?: string;
+            prompt?: string;
+          };
+          const dispatchedLabel = labeler.recordTaskDispatch(taskInput);
+          // dual-index by callID (fast path) AND in a FIFO queue (fallback path
+          // for when opencode's task tool_result carries a different callID).
+          const dispatch: TaskDispatch = {
+            label: dispatchedLabel,
+            startedAt: performance.now(),
+            toolUseCallID: toolId,
+          };
+          taskDispatchByCallID.set(toolId, dispatch);
+          pendingTaskDispatches.push(dispatch);
+          log.info(
+            `» dispatching subagent: ${dispatchedLabel}` +
+              (taskInput.subagent_type ? ` (subagent_type=${taskInput.subagent_type})` : "")
+          );
+        }
      } else {
        // remember non-task callIDs so a later tool_result with that callID
        // is correctly identified as not-a-task (and we don't FIFO-pop a
@@ -570,6 +609,16 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
      if (event.part?.state?.status === "completed" && event.part.state.output) {
        log.debug(withLabel(label, `  output: ${event.part.state.output}`));
      }
+      // surface tool errors at info level. opencode emits tool parts at
+      // status="error" through the same `tool_use` event the CLI's run-loop
+      // (and our injected plugin for subagent parts) emits — without this
+      // branch the only signal in the user's logs is `» <tool>(...)` with
+      // no indication the call failed. error info lives in `state.output`
+      // (an error string set by the tool layer).
+      if (event.part?.state?.status === "error") {
+        const errorMsg = event.part.state.output ?? "(no error message)";
+        log.info(withLabel(label, `» tool call failed: ${errorMsg}`));
+      }

      // agent's explicit MCP report_progress takes priority over todo tracking
      if (toolName.includes("report_progress") && params.todoTracker) {
@@ -690,6 +739,98 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
        }
      }
    },
+    [PULLFROG_BUS_EVENT_TYPE]: async (event: OpenCodeBusEnvelopeEvent) => {
+      // surface subagent activity that opencode's CLI run-loop discards (it
+      // filters `part.sessionID !== sessionID`). our injected plugin
+      // (action/agents/opencodePlugin.ts) re-emits non-orchestrator
+      // `message.part.updated` bus events; here we synthesize the equivalent
+      // CLI-style event for each known part type and dispatch through the
+      // existing handlers so labeling, attribution, and logging all reuse the
+      // same code path as the orchestrator's events. mirrors the dispatch
+      // logic in opencode-ai's `cli/cmd/run.ts` `loop()` function.
+      const busEvent = event.bus_event;
+      if (!busEvent || busEvent.type !== "message.part.updated") return;
+      const part = busEvent.properties?.part;
+      if (!part || typeof part.sessionID !== "string") return;
+      const sessionID = part.sessionID;
+      const partType = part.type;
+
+      // early task dispatch: the orchestrator's task tool fires bus events at
+      // status=running BEFORE the subagent's first message.part.updated, but
+      // the CLI's run-loop only emits the matching tool_use NDJSON event at
+      // status=completed (after the subagent finishes). without
+      // pre-registering the dispatch label here, the labeler binds the
+      // subagent's sessionID to a generic `subagent#N` fallback before the
+      // CLI's tool_use ever fires recordTaskDispatch. dedupe against
+      // taskDispatchByCallID so the late tool_use handler doesn't double-add.
+      if (partType === "tool") {
+        const status = part.state?.status;
+        const partWithToolFields = part as {
+          tool?: string;
+          callID?: string;
+          state?: { status?: string; input?: unknown };
+        };
+        // only running (not pending) — at pending state.input is still {}.
+        // by running, the LLM has filled in description/subagent_type/prompt.
+        // mirrors the same check in the plugin source.
+        const isOrchestratorTaskDispatch =
+          partWithToolFields.tool === "task" && status === "running";
+        if (isOrchestratorTaskDispatch) {
+          const callID = partWithToolFields.callID;
+          if (typeof callID === "string" && !taskDispatchByCallID.has(callID)) {
+            const taskInput = (partWithToolFields.state?.input ?? {}) as {
+              description?: string;
+              subagent_type?: string;
+              prompt?: string;
+            };
+            const dispatchedLabel = labeler.recordTaskDispatch(taskInput);
+            const dispatch: TaskDispatch = {
+              label: dispatchedLabel,
+              startedAt: performance.now(),
+              toolUseCallID: callID,
+            };
+            taskDispatchByCallID.set(callID, dispatch);
+            pendingTaskDispatches.push(dispatch);
+            log.info(
+              `» dispatching subagent: ${dispatchedLabel}` +
+                (taskInput.subagent_type ? ` (subagent_type=${taskInput.subagent_type})` : "")
+            );
+          }
+          return;
+        }
+        if (status !== "completed" && status !== "error") return;
+        await handlers.tool_use({
+          type: "tool_use",
+          sessionID,
+          part,
+        } as OpenCodeToolUseEvent);
+        return;
+      }
+      // intentionally NOT routing subagent step_start / step_finish through
+      // the orchestrator's handlers:
+      //   - step_finish carries `tokens` and `cost` and the handler folds
+      //     them into the run-wide accumulators. surfacing subagent steps
+      //     here would inflate the orchestrator's usage telemetry — and
+      //     either double-count (if opencode also bills child tokens back
+      //     up to the parent session) or just over-report. the existing
+      //     init/message/text handlers all gate on ORCHESTRATOR_LABEL for
+      //     the same reason.
+      //   - step_start mutates `currentStepId` / `currentStepType` /
+      //     `stepHistory`, which are orchestrator-scoped — using them to
+      //     attribute subagent activity in the orchestrator's tool-use
+      //     timing log would be wrong.
+      // the subagent's tool calls and text still surface (handled below)
+      // — that's the user-visible activity.
+      if (partType === "step-start" || partType === "step-finish") return;
+      if (partType === "text" && part.time?.end !== undefined) {
+        await handlers.text({
+          type: "text",
+          sessionID,
+          part,
+        } as OpenCodeTextEvent);
+        return;
+      }
+    },
  };

  const recentStderr: string[] = [];
@@ -709,6 +850,20 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
      activityTimeout: 300_000,
      onActivityTimeout: params.onActivityTimeout,
      stdio: ["ignore", "pipe", "pipe"],
+      // node_modules/opencode-ai/bin/opencode is a Node shim that spawnSyncs
+      // the native opencode-<plat>-<arch> binary with stdio:"inherit". without
+      // a process-group kill, SIGKILL hits only the shim, the native binary
+      // is reparented to PID 1, holds our stdout pipe open, and `child.close`
+      // never fires — producing zombie runs. detached + killGroup nukes the
+      // whole tree.
+      killGroup: true,
+      // NB: we used to pass `isPausedExternally: isSubagentInFlight` to suspend
+      // the activity timer during subagent dispatches. unnecessary now that
+      // our injected plugin (action/agents/opencodePlugin.ts) re-emits
+      // subagent `message.part.updated` events on opencode's stdout — those
+      // arrive at child.stdout here, fire updateActivity(), and reset
+      // lastActivityTime naturally. verified empirically in PR #634
+      // (~3.3 plugin events/sec during a typical subagent run).
      onStdout: async (chunk) => {
        const text = chunk.toString();
        output += text;
@@ -920,6 +1075,20 @@ export const opencode = agent({

    mkdirSync(join(homeEnv.XDG_CONFIG_HOME, "opencode"), { recursive: true });

+    // drop our bus-event surfacing plugin into opencode's global config dir
+    // (which we've redirected to the per-run tmpdir via XDG_CONFIG_HOME).
+    // opencode auto-discovers plugins from `<Global.Path.config>/{plugin,plugins}/*.{ts,js}`
+    // (see `packages/opencode/src/config/config.ts:633` calling
+    // `ConfigPlugin.load(dir)`), so this lands in the loader without any
+    // config wiring. critically: this MUST be inside the tmpdir, never the
+    // user's repo working tree — see AGENTS.md.
+    const opencodePluginDir = join(homeEnv.XDG_CONFIG_HOME, "opencode", "plugin");
+    mkdirSync(opencodePluginDir, { recursive: true });
+    writeFileSync(
+      join(opencodePluginDir, PULLFROG_OPENCODE_PLUGIN_FILENAME),
+      PULLFROG_OPENCODE_PLUGIN_SOURCE
+    );
+
    const agentBrowserVersion = getDevDependencyVersion("agent-browser");
    addSkill({
      ref: `vercel-labs/agent-browser@v${agentBrowserVersion}`,
@@ -981,7 +1150,9 @@ export const opencode = agent({
      stopScript: ctx.stopScript,
      summaryFilePath: ctx.summaryFilePath,
      summarySeed: ctx.summarySeed,
-      reflectionPrompt: buildLearningsReflectionPrompt("opencode"),
+      reflectionPrompt: ctx.learningsFilePath
+        ? buildLearningsReflectionPrompt(ctx.learningsFilePath)
+        : undefined,
      resume: async (c) =>
        runOpenCode({
          ...runParams,
@@ -0,0 +1,139 @@
+/**
+ * Source for the opencode plugin we drop into the per-run tmpdir at
+ * `<XDG_CONFIG_HOME>/opencode/plugin/pullfrog-events.ts`. The harness already
+ * redirects `XDG_CONFIG_HOME` to `ctx.tmpdir/.config` (see `opencode.ts`
+ * `homeEnv`), so opencode's auto-discovery scans the tmpdir, never the user's
+ * working tree. opencode's `Global.Path.config` resolves to
+ * `path.join(xdgConfig, "opencode")` and the config layer auto-discovers
+ * plugins from every directory in its scan list — including
+ * `Global.Path.config` — by globbing `{plugin,plugins}/*.{ts,js}` via
+ * `ConfigPlugin.load(dir)`.
+ *
+ * We MUST NOT write into the user's repo working tree. The repo is a checkout
+ * the agent operates on; only the agent's own tools (gated by
+ * `OPENCODE_PERMISSION`) may modify it. The whole reason we redirect HOME and
+ * XDG_CONFIG_HOME is so harness-side files (config, plugins, scratch state)
+ * land in the tmpdir.
+ *
+ * Why this plugin exists: opencode's `task` tool runs subagents in-process and
+ * the CLI's `cli/cmd/run.ts` event loop filters `part.sessionID !== sessionID`,
+ * so subagent-internal `message.part.updated` events are silently discarded
+ * before reaching our parent NDJSON stream. plugins, by contrast, receive
+ * EVERY bus event via `bus.subscribeAll()` regardless of session.
+ *
+ * The plugin re-emits every relevant bus event onto opencode's stdout as a
+ * single JSON line wrapped in a sentinel envelope. our `runOpenCode` parser
+ * recognises the envelope, unpacks it, and routes the inner part through the
+ * existing handlers with a per-session label from `SessionLabeler` so each
+ * subagent's tool calls / text appear inline alongside the orchestrator's.
+ *
+ * Dumb plugin / smart parent split: the plugin emits every part for every
+ * session. the parent dedupes against the orchestrator's own session id (which
+ * it already knows from the `init` event). this keeps the plugin trivial and
+ * keeps the per-session attribution logic on the parent side where the
+ * SessionLabeler already lives.
+ *
+ * Event-name prefixing: the wrapped event-type sentinel is
+ * `pullfrog_bus_event` — picked to be unmistakably ours so a future opencode
+ * release that introduces a coincidentally-named event type won't collide.
+ */
+
+export const PULLFROG_BUS_EVENT_TYPE = "pullfrog_bus_event" as const;
+
+export const PULLFROG_OPENCODE_PLUGIN_FILENAME = "pullfrog-events.ts" as const;
+
+/**
+ * Source written verbatim to `<XDG_CONFIG_HOME>/opencode/plugin/pullfrog-events.ts`.
+ *
+ * - Structural typing only (no runtime import of `@opencode-ai/plugin`):
+ *   opencode installs that dep into the directory containing the plugin
+ *   alongside discovery, but a) the dep isn't required for the structural
+ *   shape we use, and b) keeping zero imports avoids any module-resolution
+ *   coupling to opencode's plugin-loader internals across versions.
+ * - default export is the plugin factory (opencode's plugin loader accepts
+ *   default exports as the server entrypoint).
+ * - we only forward `message.part.updated`. that's where the user-visible
+ *   subagent activity (tool calls, text, step transitions) lives. add more
+ *   event types here if the parent needs them.
+ * - JSON.stringify+single write keeps the line atomic up to PIPE_BUF (4KB on
+ *   Linux). longer parts may interleave with concurrent stdout writers; the
+ *   parser tolerates non-JSON lines (logs them at debug) so a torn line is a
+ *   missed event, not a crash.
+ */
+export const PULLFROG_OPENCODE_PLUGIN_SOURCE = `// AUTOGENERATED by Pullfrog. do not edit; it'll be overwritten on the next run.
+// surfaces opencode subagent activity that the CLI's run-loop discards. see
+// action/agents/opencodePlugin.ts in pullfrog/app for why this exists. lives
+// inside the per-run tmpdir (XDG_CONFIG_HOME/opencode/plugin/), never inside
+// the user's working tree.
+
+const PULLFROG_BUS_EVENT_TYPE = ${JSON.stringify(PULLFROG_BUS_EVENT_TYPE)};
+
+// the first sessionID we see on a message.part.updated event is the
+// orchestrator — opencode's run command creates exactly one top-level session
+// before any subagent is dispatched, and the user-prompt text part fires
+// before the first task tool_use. we lock that sessionID in here and use it
+// to filter: the orchestrator's events are already streamed by the CLI's
+// run-loop, so we only forward (a) all subagent events, and (b) the
+// orchestrator's task tool dispatches at status="running". the CLI only
+// emits task tool_use at status=completed (after the subagent finishes), so
+// without the early announce the parent's labeler binds subagent sessions
+// before recordTaskDispatch fires and the lens label is lost.
+let orchestratorSessionID: string | undefined;
+
+function isOrchestratorTaskDispatch(part: {
+  type?: string;
+  tool?: string;
+  state?: { status?: string };
+}): boolean {
+  if (part.type !== "tool") return false;
+  if (part.tool !== "task") return false;
+  // only forward at status="running" (not "pending"). at pending the
+  // state.input is still {} — the orchestrator has emitted the part shell
+  // but the LLM hasn't filled in description/subagent_type/prompt yet. by
+  // running, input is populated and recordTaskDispatch can derive the lens
+  // label correctly.
+  return part.state?.status === "running";
+}
+
+export default async function pullfrogEventsPlugin() {
+  return {
+    event: async (input: {
+      event: {
+        type: string;
+        properties?: {
+          part?: {
+            sessionID?: string;
+            type?: string;
+            tool?: string;
+            state?: { status?: string };
+          };
+        };
+      };
+    }) => {
+      const event = input.event;
+      if (!event || typeof event !== "object") return;
+      if (event.type !== "message.part.updated") return;
+      const part = event.properties?.part;
+      const sessionID = part?.sessionID;
+      if (typeof sessionID !== "string" || sessionID.length === 0) return;
+      if (orchestratorSessionID === undefined) orchestratorSessionID = sessionID;
+
+      if (sessionID === orchestratorSessionID) {
+        // skip orchestrator events EXCEPT early task dispatches.
+        if (!part || !isOrchestratorTaskDispatch(part)) return;
+      }
+
+      try {
+        const line = JSON.stringify({
+          type: PULLFROG_BUS_EVENT_TYPE,
+          bus_event: event,
+        });
+        process.stdout.write(line + "\\n");
+      } catch {
+        // a circular reference or BigInt etc. would throw; swallow rather
+        // than letting a single bad event take down the plugin.
+      }
+    },
+  };
+}
+`;
@@ -42,10 +42,10 @@ describe("runPostRunRetryLoop — reflection turn", () => {
  });

  it("does not flip a successful run to failed when reflection returns success:false", async () => {
-    // the reflection turn is a best-effort nudge (update_learnings). if it
-    // fails — e.g. the model API errors mid-turn — the underlying task has
-    // already completed and been gated cleanly, so the run as a whole must
-    // still be reported as successful.
+    // the reflection turn is a best-effort nudge (edit the learnings
+    // tmpfile). if it fails — e.g. the model API errors mid-turn — the
+    // underlying task has already completed and been gated cleanly, so the
+    // run as a whole must still be reported as successful.
    const initial = successResult({ output: "task done" });
    const resume = vi
      .fn<(ctx: { prompt: string; previousResult: AgentResult }) => Promise<AgentResult>>()
@@ -56,7 +56,7 @@ describe("runPostRunRetryLoop — reflection turn", () => {
      initialUsage: undefined,
      stopScript: null,
      resume,
-      reflectionPrompt: "REFLECTION: call update_learnings if anything is worth saving",
+      reflectionPrompt: "REFLECTION: edit learnings file if anything is worth saving",
    });

    expect(result.success).toBe(true);
@@ -110,7 +110,7 @@ describe("runPostRunRetryLoop — reflection turn", () => {
      initialUsage: undefined,
      stopScript: null,
      resume,
-      reflectionPrompt: "REFLECTION: consider update_learnings",
+      reflectionPrompt: "REFLECTION: consider editing learnings",
    });

    expect(result.success).toBe(true);
@@ -135,7 +135,7 @@ describe("runPostRunRetryLoop — reflection turn", () => {
      initialUsage: undefined,
      stopScript: null,
      resume,
-      reflectionPrompt: "REFLECTION: consider update_learnings",
+      reflectionPrompt: "REFLECTION: consider editing learnings",
    });

    expect(result.success).toBe(true);
@@ -186,7 +186,7 @@ describe("runPostRunRetryLoop — reflection turn", () => {
      initialUsage: undefined,
      stopScript: null,
      resume,
-      reflectionPrompt: "REFLECTION: consider update_learnings",
+      reflectionPrompt: "REFLECTION: consider editing learnings",
    });

    expect(result.success).toBe(true);
@@ -1,5 +1,4 @@
 import { readFile } from "node:fs/promises";
-import { type AgentId, formatMcpToolRef } from "../external.ts";
 import { LIFECYCLE_HOOK_TIMEOUT_MS } from "../lifecycle.ts";
 import { log } from "../utils/cli.ts";
 import {
@@ -157,26 +156,30 @@ export function buildPostRunPrompt(issues: PostRunIssues): string {
 }

 /**
- * prompt for a dedicated post-run reflection turn nudging the agent to call
- * `update_learnings` if it discovered anything worth persisting.
+ * prompt for a dedicated post-run reflection turn nudging the agent to edit
+ * the rolling learnings file if it discovered anything worth persisting.
 *
- * this exists because the learnings step baked into mode checklists is
- * frequently ignored — the agent stays focused on the task and the meta-ask
- * falls through. delivering it as its own resume turn, with nothing competing
- * for attention, raises the fire rate substantially.
+ * this exists because passive "if you learned something, write it down"
+ * instructions baked into mode checklists are frequently ignored — the agent
+ * stays focused on the task and the meta-ask falls through. delivering it
+ * as its own resume turn, with nothing competing for attention, raises the
+ * fire rate substantially.
+ *
+ * the file is the single source of truth — there is no separate MCP tool
+ * call. the server reads the file at end-of-run and persists any edits to
+ * `Repo.learnings`.
 */
-export function buildLearningsReflectionPrompt(agentId: AgentId): string {
-  const t = (name: string) => formatMcpToolRef(agentId, name);
+export function buildLearningsReflectionPrompt(filePath: string): string {
  return [
-    `REFLECTION — before you finish, think back over this task: did you discover anything about this repo's setup, test commands, conventions, or patterns that you are confident is correct and would reliably help future runs?`,
+    `REFLECTION — before you finish, think back over this task: did you discover anything about this repo's setup, test commands, conventions, or patterns that is high-confidence and would reliably help future runs?`,
    "",
-    `if so, call \`${t("update_learnings")}\` to persist it.`,
+    `the rolling learnings file is at \`${filePath}\`. read it first if you haven't already, then edit it in place using your native file tools. the server reads this file at end-of-run and persists any changes — there is no tool to call.`,
    "",
-    `rules:`,
-    `- only call \`${t("update_learnings")}\` when the finding is high-confidence and broadly useful. skip if unsure, speculative, or one-off.`,
-    `- pass the FULL merged list: existing learnings from the original prompt + your new discoveries. one fact per bullet, lines starting with \`- \`.`,
-    `- deduplicate, and drop bullets that are clearly wrong or no longer relevant to the current codebase.`,
-    `- if you already called \`${t("update_learnings")}\` earlier in this run, or nothing new is worth capturing, just reply "done" and stop — do not edit the repo for this reflection.`,
+    `keep the file healthy:`,
+    `- only add bullets when the finding is high-confidence AND broadly useful. skip speculative, one-off, or "maybe" findings.`,
+    `- prune bullets that are clearly wrong, no longer relevant, or low-signal (rarely useful). a focused, accurate file beats a long stale one.`,
+    `- format: flat bullet list, one fact per line starting with \`- \`. deduplicate against existing entries — if a bullet covers the same fact, update it in place instead of adding a duplicate.`,
+    `- leave the file alone if you have nothing substantively new to add and the existing entries still look healthy. silence is a valid outcome — just reply "done" and stop.`,
  ].join("\n");
 }

@@ -133,6 +133,13 @@ export interface AgentRunContext {
   * track of multi-step instructions.
   */
  summarySeed?: string | undefined;
+  /**
+   * absolute path to the rolling repo-level learnings tmpfile. seeded for
+   * every run from `Repo.learnings`. used by the post-run reflection turn
+   * so the prompt can point the agent at a concrete path to edit; the
+   * file's content is read back and persisted by main.ts after the run.
+   */
+  learningsFilePath?: string | undefined;
  /**
   * called synchronously when the agent subprocess is killed for inner
   * activity timeout. lets main.ts tear down shared resources (MCP HTTP
@@ -22,6 +22,7 @@ import {
 import { resolveAgent, resolveModel } from "./utils/agent.ts";
 import { apiFetch } from "./utils/apiFetch.ts";
 import { validateAgentApiKey } from "./utils/apiKeys.ts";
+import { isLocalApiUrl } from "./utils/apiUrl.ts";
 import { resolveBody } from "./utils/body.ts";
 import { formatUsageSummary, log, writeSummary } from "./utils/cli.ts";
 import { recordDiffReadFromToolUse } from "./utils/diffCoverage.ts";
@@ -31,6 +32,7 @@ import { resolveGit, setGitAuthServer } from "./utils/gitAuth.ts";
 import { startGitAuthServer } from "./utils/gitAuthServer.ts";
 import { createOctokit, writeGitHubUsageSummaryToFile } from "./utils/github.ts";
 import { resolveInstructions } from "./utils/instructions.ts";
+import { readLearningsFile, seedLearningsFile } from "./utils/learnings.ts";
 import { executeLifecycleHook } from "./utils/lifecycle.ts";
 import { normalizeEnv } from "./utils/normalizeEnv.ts";
 import { aggregateUsage, patchWorkflowRunFields } from "./utils/patchWorkflowRunFields.ts";
@@ -279,18 +281,18 @@ function formatTransientErrorSummary(error: TransientError, owner: string): stri
  ].join("\n");
 }

-async function mintProxyKey(ctx: { oidcCredentials: OidcCredentials }): Promise<string | null> {
+async function mintProxyKey(ctx: {
+  oidcCredentials: OidcCredentials | null;
+  repo: { owner: string; name: string };
+}): Promise<string | null> {
  try {
-    process.env.ACTIONS_ID_TOKEN_REQUEST_URL = ctx.oidcCredentials.requestUrl;
-    process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN = ctx.oidcCredentials.requestToken;
-    const oidcToken = await core.getIDToken("pullfrog-api");
-    delete process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
-    delete process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+    const headers = await buildProxyTokenHeaders(ctx);
+    if (!headers) return null;

    const response = await apiFetch({
      path: "/api/proxy-token",
      method: "POST",
-      headers: { Authorization: `Bearer ${oidcToken}` },
+      headers,
    });

    if (response.status === 402) {
@@ -336,12 +338,44 @@ async function mintProxyKey(ctx: { oidcCredentials: OidcCredentials }): Promise<
  }
 }

+/**
+ * choose how to authenticate the `/api/proxy-token` request:
+ *
+ * - production: mint a fresh OIDC token via `core.getIDToken` and send as
+ *   `Authorization: Bearer …` (the server verifies it cryptographically).
+ * - local dev (no OIDC + `API_URL` is localhost): send `x-dev-repo:
+ *   owner/repo` instead. the server-side route only honors this header
+ *   when `NODE_ENV === "development"`, so prod is never reachable through
+ *   this branch even if the action is misconfigured.
+ *
+ * returns null when neither path is available — caller treats as soft skip.
+ */
+async function buildProxyTokenHeaders(ctx: {
+  oidcCredentials: OidcCredentials | null;
+  repo: { owner: string; name: string };
+}): Promise<Record<string, string> | null> {
+  if (ctx.oidcCredentials) {
+    process.env.ACTIONS_ID_TOKEN_REQUEST_URL = ctx.oidcCredentials.requestUrl;
+    process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN = ctx.oidcCredentials.requestToken;
+    const oidcToken = await core.getIDToken("pullfrog-api");
+    delete process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+    delete process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+    return { Authorization: `Bearer ${oidcToken}` };
+  }
+  if (isLocalApiUrl()) {
+    log.info(`» proxy: dev bypass (x-dev-repo) for ${ctx.repo.owner}/${ctx.repo.name}`);
+    return { "x-dev-repo": `${ctx.repo.owner}/${ctx.repo.name}` };
+  }
+  return null;
+}
+
 async function resolveProxyModel(ctx: {
  payload: ResolvedPayload;
  oss: boolean;
  plan: AccountPlan;
  proxyModel?: string | undefined;
  oidcCredentials: OidcCredentials | null;
+  repo: { owner: string; name: string };
 }): Promise<void> {
  // env override = BYOK escape hatch, don't proxy
  if (process.env.PULLFROG_MODEL?.trim()) return;
@@ -349,12 +383,15 @@ async function resolveProxyModel(ctx: {
  const needsProxy = isInfraCovered({ isOss: ctx.oss, plan: ctx.plan }) && ctx.proxyModel;
  if (!needsProxy) return;

-  if (!ctx.oidcCredentials) {
+  // dev affordance: when talking to a localhost API, the server-side
+  // x-dev-repo bypass replaces OIDC verification, so a play run can
+  // exercise the proxy/router/oss path without GitHub Actions OIDC.
+  if (!ctx.oidcCredentials && !isLocalApiUrl()) {
    log.warning("» proxy requested but no OIDC credentials available — skipping");
    return;
  }

-  const key = await mintProxyKey({ oidcCredentials: ctx.oidcCredentials });
+  const key = await mintProxyKey({ oidcCredentials: ctx.oidcCredentials, repo: ctx.repo });
  if (!key) return;

  process.env.OPENROUTER_API_KEY = key;
@@ -395,6 +432,58 @@ async function fetchPreviousSnapshot(ctx: ToolContext, prNumber: number): Promis
 * (on incremental runs) or serialize the placeholder scaffold (on first
 * runs), neither of which is useful.
 */
+/**
+ * Read the agent-edited repo-level learnings tmpfile and PATCH it to
+ * `Repo.learnings`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-trim-identical to its seed —
+ * the agent didn't touch it, so writing the same content back would just
+ * burn a `LearningsRevision` row and an API round-trip.
+ *
+ * `model` is forwarded so `LearningsRevision.model` keeps populating; it
+ * powers the per-revision attribution badge in the UI history view.
+ */
+async function persistLearnings(ctx: ToolContext): Promise<void> {
+  const filePath = ctx.toolState.learningsFilePath;
+  if (!filePath) return;
+  if (ctx.toolState.learningsPersistAttempted) return;
+  ctx.toolState.learningsPersistAttempted = true;
+  const current = await readLearningsFile(filePath);
+  if (current === null) {
+    log.debug(`learnings tmpfile missing or unreadable at ${filePath} — skipping persist`);
+    return;
+  }
+  const seed = ctx.toolState.learningsSeed?.trim() ?? "";
+  if (current === seed) {
+    log.debug("learnings tmpfile unchanged from seed — skipping persist");
+    return;
+  }
+  try {
+    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: current,
+        model: ctx.toolState.model,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      const error = await response.text().catch(() => "(no body)");
+      log.debug(`learnings persist failed (${response.status}): ${error}`);
+      return;
+    }
+    log.info("» learnings updated");
+  } catch (err) {
+    log.debug(`learnings persist failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 async function persistSummary(ctx: ToolContext): Promise<void> {
  const filePath = ctx.toolState.summaryFilePath;
  if (!filePath) return;
@@ -520,6 +609,7 @@ export async function main(): Promise<MainResult> {
      plan: runContext.plan,
      proxyModel: runContext.proxyModel,
      oidcCredentials,
+      repo: runContext.repo,
    });
  } catch (error) {
    if (error instanceof BillingError) {
@@ -647,6 +737,47 @@ export async function main(): Promise<MainResult> {
    log.info(`» MCP server started at ${mcpHttpServer.url}`);
    timer.checkpoint("mcpServer");

+    // seed the rolling repo-level learnings tmpfile for every run. the
+    // agent reads the file at startup (path is surfaced in the LEARNINGS
+    // section of the prompt) and may edit it during the post-run
+    // reflection turn. persistLearnings reads it back at end-of-run and
+    // PATCHes any changes to Repo.learnings, byte-trim equality against
+    // the seed gates the API call. always-seed (vs gated): learnings are
+    // universal — any run can produce them, and gating just hides the
+    // affordance.
+    //
+    // wrapped in best-effort try/catch: this block runs unconditionally,
+    // and an unwrapped filesystem failure (ENOSPC, EACCES, hostile sandbox)
+    // would unwind into the outer main() catch and flip an otherwise-
+    // successful run to "❌ Pullfrog failed" before the agent even starts.
+    // matches `persistLearnings`'s own best-effort contract — learnings
+    // are a peripheral artifact, not a load-bearing capability. on failure
+    // toolState.learningsFilePath stays unset, and downstream consumers
+    // (`persistLearnings`, agent harnesses, `resolveInstructions`) all
+    // treat undefined as "no learnings affordance this run".
+    try {
+      const learningsPath = await seedLearningsFile({
+        tmpdir,
+        current: runContext.repoSettings.learnings,
+      });
+      toolState.learningsFilePath = learningsPath;
+      try {
+        toolState.learningsSeed = await readFile(learningsPath, "utf8");
+      } catch {
+        // intentionally empty — learningsSeed stays undefined, persistLearnings
+        // will treat seed as "" and persist any non-empty content
+      }
+      log.info(
+        `» learnings seeded at ${learningsPath} (existing=${runContext.repoSettings.learnings ? "yes" : "no"})`
+      );
+      const ctxForExit = toolContext;
+      onExitSignal(() => persistLearnings(ctxForExit));
+    } catch (err) {
+      log.warning(
+        `» learnings seed failed: ${err instanceof Error ? err.message : String(err)} — continuing without learnings file`
+      );
+    }
+
    // seed the rolling PR summary tmpfile when the dispatcher requested it.
    // gated on event being a PR — issue/workflow_dispatch runs have no
    // summarySnapshot to maintain. file path is exposed to the agent via
@@ -698,7 +829,7 @@ export async function main(): Promise<MainResult> {
      modes,
      agentId,
      outputSchema,
-      learnings: runContext.repoSettings.learnings,
+      learningsFilePath: toolState.learningsFilePath ?? null,
    });
    const logParts = [
      instructions.eventInstructions
@@ -795,6 +926,7 @@ export async function main(): Promise<MainResult> {
      stopScript: runContext.repoSettings.stopScript,
      summaryFilePath: toolState.summaryFilePath,
      summarySeed: toolState.summarySeed,
+      learningsFilePath: toolState.learningsFilePath,
      onActivityTimeout: onInnerActivityTimeout,
      onToolUse: (event) => {
        const wasTracked = recordDiffReadFromToolUse({
@@ -882,6 +1014,13 @@ export async function main(): Promise<MainResult> {
      await persistSummary(toolContext);
    }

+    // same for the rolling repo-level learnings tmpfile. always seeded, so
+    // always read back; persistLearnings short-circuits when the file is
+    // unchanged from its seed.
+    if (toolContext) {
+      await persistLearnings(toolContext);
+    }
+
    // clean up stranded progress comments. the comment is stale unless
    // report_progress wrote a final summary to it — three sub-cases all reduce
    // to !finalSummaryWritten:
@@ -966,6 +1105,12 @@ export async function main(): Promise<MainResult> {
      await persistSummary(toolContext);
    }

+    // same rationale for learnings: a partial edit before a crash is still
+    // worth keeping. persistLearnings is idempotent via learningsPersistAttempted.
+    if (toolContext) {
+      await persistLearnings(toolContext);
+    }
+
    return {
      success: false,
      error: errorMessage,
@@ -78,6 +78,7 @@ export function CreateCommentTool(ctx: ToolContext) {
      });

      ctx.toolState.wasUpdated = true;
+      log.info(`» created comment ${result.data.id}`);

      if (commentType === "Plan") {
        if (result.data.node_id) {
@@ -94,6 +95,7 @@ export function CreateCommentTool(ctx: ToolContext) {
          comment_id: result.data.id,
          body: bodyWithPlanLink,
        });
+        log.info(`» updated comment ${updateResult.data.id}`);

        return {
          success: true,
@@ -132,6 +134,7 @@ export function EditCommentTool(ctx: ToolContext) {
        comment_id: commentId,
        body: bodyWithFooter,
      });
+      log.info(`» updated comment ${result.data.id}`);

      return {
        success: true,
@@ -339,6 +342,10 @@ export function ReportProgressTool(ctx: ToolContext) {
        };
      }

+      if (result.commentId !== undefined) {
+        log.info(`» ${result.action} comment ${result.commentId}`);
+      }
+
      if (!params.target_plan_comment) {
        ctx.toolState.finalSummaryWritten = true;
      }
@@ -407,6 +414,7 @@ export function ReplyToReviewCommentTool(ctx: ToolContext) {
        comment_id,
        body: bodyWithFooter,
      });
+      log.info(`» created review comment ${result.data.id} (in reply to ${comment_id})`);

      // mark progress as updated so error reporting + run-result handling know
      // a substantive write happened (used by reportErrorToComment / handleAgentResult)
@@ -351,6 +351,11 @@ export function PushBranchTool(ctx: ToolContext) {
        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
      }

+      const pushedSha = $("git", ["rev-parse", "HEAD"], { log: false }).trim();
+      log.info(
+        `» pushed branch ${branch} to ${pushDest.remoteName}/${pushDest.remoteBranch} (sha ${pushedSha})`
+      );
+
      return {
        success: true,
        branch,
@@ -595,6 +600,7 @@ export function DeleteBranchTool(ctx: ToolContext) {
      await $git("push", ["origin", "--delete", `refs/heads/${params.branchName}`], {
        token: ctx.gitToken,
      });
+      log.info(`» deleted branch ${params.branchName}`);
      return { success: true, deleted: params.branchName };
    }),
  });
@@ -625,6 +631,7 @@ export function PushTagsTool(ctx: ToolContext) {
      await $git("push", pushArgs, {
        token: ctx.gitToken,
      });
+      log.info(`» pushed tag ${params.tag}`);
      return { success: true, tag: params.tag };
    }),
  });
@@ -1,4 +1,5 @@
 import { type } from "arktype";
+import { log } from "../utils/cli.ts";
 import { fixDoubleEscapedString } from "../utils/fixDoubleEscapedString.ts";
 import { patchWorkflowRunFields } from "../utils/patchWorkflowRunFields.ts";
 import type { ToolContext } from "./server.ts";
@@ -32,6 +33,8 @@ export function IssueTool(ctx: ToolContext) {
        assignees: params.assignees ?? [],
      });

+      log.info(`» created issue #${result.data.number} (id ${result.data.id})`);
+
      const nodeId = result.data.node_id;
      if (typeof nodeId === "string" && nodeId.length > 0) {
        await patchWorkflowRunFields(ctx, {
@@ -1,4 +1,5 @@
 import { type } from "arktype";
+import { log } from "../utils/cli.ts";
 import type { ToolContext } from "./server.ts";
 import { execute, tool } from "./shared.ts";

@@ -20,6 +21,7 @@ export function AddLabelsTool(ctx: ToolContext) {
        issue_number,
        labels,
      });
+      log.info(`» added labels [${labels.join(", ")}] to issue #${issue_number}`);

      return {
        success: true,
@@ -1,41 +0,0 @@
-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 };
-    }),
-  });
-}
@@ -48,6 +48,7 @@ export function UpdatePullRequestBodyTool(ctx: ToolContext) {
        pull_number: params.pull_number,
        body: bodyWithFooter,
      });
+      log.info(`» updated pull request #${result.data.number}`);

      ctx.toolState.wasUpdated = true;

@@ -80,6 +81,7 @@ export function CreatePullRequestTool(ctx: ToolContext) {
        base: params.base,
        draft: params.draft ?? false,
      });
+      log.info(`» created pull request #${result.data.number} (id ${result.data.id})`);

      // best-effort: request review from the user who triggered the workflow
      const reviewer = ctx.payload.triggerer;
@@ -584,6 +584,7 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
      }
      const reviewId = result.data.id;
      const reviewNodeId = result.data.node_id;
+      log.info(`» created review ${reviewId} on pull request #${pull_number}`);

      // reviewedSha = what the agent actually reviewed (checkout SHA), not the
      // submission anchor (current HEAD). this ensures postReviewCleanup dispatches
@@ -735,7 +735,7 @@ export function ResolveReviewThreadTool(ctx: ToolContext) {
        });

        const thread = response.resolveReviewThread.thread;
-        log.debug(`resolved thread ${thread.id}, isResolved=${thread.isResolved}`);
+        log.info(`» resolved review thread ${thread.id}`);

        return {
          thread_id: thread.id,
@@ -39,7 +39,6 @@ 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";
@@ -143,6 +142,21 @@ export interface ToolState {
  // persisted) from redundantly re-running the DB PATCH on the
  // success-then-late-throw path.
  summaryPersistAttempted?: boolean;
+  // absolute path to the rolling repo-level learnings markdown file the
+  // agent reads at startup and may edit at end-of-run. seeded by main.ts
+  // for every run from `Repo.learnings` (empty file when no learnings
+  // exist yet); read back at end-of-run to persist any edits.
+  learningsFilePath?: string;
+  // exact bytes of the seeded learnings file at run start. compared
+  // against the file content at end-of-run to detect "agent never touched
+  // it" — in that case persistLearnings skips the DB PATCH (saving the
+  // identical content would be a no-op write that wastes a LearningsRevision
+  // row and the API round-trip).
+  learningsSeed?: string;
+  // mirror of `summaryPersistAttempted` for the learnings tmpfile — guards
+  // the error-path / exit-signal callers from a redundant second PATCH
+  // after the success path already persisted.
+  learningsPersistAttempted?: boolean;
  output?: string;
  usageEntries: AgentUsage[];
  model?: string | undefined;
@@ -189,8 +203,8 @@ export interface ToolContext {
  tmpdir: string;
  // repo-level OSS flag + account-level billing plan. together they decide
  // whether pullfrog is paying for marginal infra — see isInfraCovered in
-  // utils/runContext.ts. plan gating for things like update_learnings is
-  // enforced server-side via 402, so we pass plan along mostly for future
+  // utils/runContext.ts. plan gating for endpoints like the learnings PATCH
+  // is enforced server-side via 402, so we pass plan along mostly for future
  // use / observability. see wiki/pricing.md.
  oss: boolean;
  plan: AccountPlan;
@@ -288,7 +302,6 @@ function buildOrchestratorTools(ctx: ToolContext, outputSchema?: JsonSchema): To
    DeleteBranchTool(ctx),
    CreatePullRequestTool(ctx),
    UpdatePullRequestBodyTool(ctx),
-    UpdateLearningsTool(ctx),
  ];
 }

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { type } from "arktype";
 import { fileTypeFromBuffer } from "file-type";
 import { apiFetch } from "../utils/apiFetch.ts";
+import { log } from "../utils/cli.ts";
 import type { ToolContext } from "./server.ts";
 import { execute, tool } from "./shared.ts";

@@ -65,6 +66,8 @@ export function UploadFileTool(ctx: ToolContext) {
        throw new Error(`failed to upload file: ${uploadResponse.statusText}`);
      }

+      log.info(`» uploaded file ${publicUrl}`);
+
      return { success: true, publicUrl, filename, contentLength, contentType };
    }),
  });
@@ -65,10 +65,6 @@ Rules:
 - Focus on *intent*, not *what* — the diff already shows what changed
 - Get the file count and commit count from the checkout_pr metadata, not by counting manually`;

-function learningsStep(t: (toolName: string) => string, 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 \`${t("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.`;
-}
-
 export function computeModes(agentId: AgentId): Mode[] {
  const t = (toolName: string) => formatMcpToolRef(agentId, toolName);
  return [
@@ -125,8 +121,6 @@ export function computeModes(agentId: AgentId): Mode[] {
   - create a PR via \`${t("create_pull_request")}\`
   - call \`${t("report_progress")}\` with the PR link or the exact error if push/PR failed

-${learningsStep(t, 6)}
-
 ### Notes

 For simple, well-defined tasks, skip the plan phase and go straight to build.`,
@@ -155,9 +149,7 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
   - reply to each comment using \`${t("reply_to_review_comment")}\`
   - resolve addressed threads via \`${t("resolve_review_thread")}\`
-   - call \`${t("report_progress")}\` with a brief summary (or the exact push error if push failed)
-
-${learningsStep(t, 6)}`,
+   - call \`${t("report_progress")}\` with a brief summary (or the exact push error if push failed)`,
    },
    // Review and IncrementalReview use the multi-lens orchestrator pattern
    // (canonical source: .claude/commands/anneal.md). The orchestrator does
@@ -331,9 +323,7 @@ ${PR_SUMMARY_FORMAT}`,

 2. Produce a structured, actionable plan with clear milestones.

-3. Call \`${t("report_progress")}\` with the plan.
-
-${learningsStep(t, 4)}`,
+3. Call \`${t("report_progress")}\` with the plan.`,
    },
    {
      name: "Fix",
@@ -356,9 +346,7 @@ ${learningsStep(t, 4)}`,

 5. Finalize:
   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
-   - call \`${t("report_progress")}\` with the diagnosis and fix summary (or the exact push error if push failed)
-
-${learningsStep(t, 6)}`,
+   - call \`${t("report_progress")}\` with the diagnosis and fix summary (or the exact push error if push failed)`,
    },
    {
      name: "ResolveConflicts",
@@ -403,9 +391,7 @@ ${learningsStep(t, 6)}`,
 3. Finalize:
   - if code changes were made, push to a pull request (new or existing) using \`${t("push_branch")}\` and \`${t("create_pull_request")}\` as needed. \`git status\` must be clean before you finish (see *SYSTEM* Git rules if push fails).
   - call \`${t("report_progress")}\` once with results — include exact tool errors if push or PR creation failed
-   - if the task involved labeling, commenting, or other GitHub operations, perform those directly
-
-${learningsStep(t, 4)}`,
+   - if the task involved labeling, commenting, or other GitHub operations, perform those directly`,
    },
  ];
 }
@@ -1,6 +1,6 @@
 {
  "name": "pullfrog",
-  "version": "0.1.0",
+  "version": "0.1.2",
  "type": "module",
  "bin": {
    "pullfrog": "dist/cli.mjs",
@@ -1,38 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`latest model per provider snapshot > matches snapshot 1`] = `
-{
-  "anthropic": {
-    "modelId": "claude-opus-4-7",
-    "releaseDate": "2026-04-16",
-  },
-  "deepseek": {
-    "modelId": "deepseek-v4-pro",
-    "releaseDate": "2026-04-24",
-  },
-  "google": {
-    "modelId": "gemini-3.1-flash-lite",
-    "releaseDate": "2026-05-07",
-  },
-  "moonshotai": {
-    "modelId": "kimi-k2.6",
-    "releaseDate": "2026-04-21",
-  },
-  "openai": {
-    "modelId": "gpt-5.5-pro",
-    "releaseDate": "2026-04-23",
-  },
-  "opencode": {
-    "modelId": "gpt-5.5-pro",
-    "releaseDate": "2026-04-24",
-  },
-  "openrouter": {
-    "modelId": "x-ai/grok-4.3",
-    "releaseDate": "2026-05-01",
-  },
-  "xai": {
-    "modelId": "grok-4.3",
-    "releaseDate": "2026-05-01",
-  },
-}
-`;
@@ -18,6 +18,7 @@
 *   node action/test/list-aliases.ts
 *   MATRIX_FILTER=gemini node action/test/list-aliases.ts
 *   INCLUDE_ALL_PASSTHROUGHS=1 node action/test/list-aliases.ts
+ *   INCLUDE_EXPENSIVE=1 node action/test/list-aliases.ts
 */
 import { modelAliases } from "../models.ts";

@@ -29,6 +30,10 @@ function agentForSlug(slug: string): "claude" | "opencode" {
 // translation) is alive without re-testing every underlying model.
 const ROUTING_CANARIES = new Set(["openrouter/claude-sonnet", "opencode/claude-sonnet"]);

+// pruned by default; opt back in with INCLUDE_EXPENSIVE=1 or MATRIX_FILTER.
+// gpt-5.5-pro burns ~$2.40/run on this fixture — too expensive per-push.
+const EXPENSIVE_ALIASES = new Set(["openai/gpt-pro"]);
+
 function isPrunablePassthrough(alias: (typeof modelAliases)[number]): boolean {
  if (ROUTING_CANARIES.has(alias.slug)) return false;
  if (alias.provider === "openrouter") return true;
@@ -40,10 +45,12 @@ function isPrunablePassthrough(alias: (typeof modelAliases)[number]): boolean {

 const filter = process.env.MATRIX_FILTER?.trim() ?? "";
 const includeAllPassthroughs = process.env.INCLUDE_ALL_PASSTHROUGHS === "1";
+const includeExpensive = process.env.INCLUDE_EXPENSIVE === "1" || filter !== "";

 const matrix = modelAliases
  .filter((alias) => (filter ? alias.slug.toLowerCase().includes(filter.toLowerCase()) : true))
  .filter((alias) => includeAllPassthroughs || !isPrunablePassthrough(alias))
+  .filter((alias) => includeExpensive || !EXPENSIVE_ALIASES.has(alias.slug))
  .map((alias) => ({
    slug: alias.slug,
    agent: agentForSlug(alias.slug),
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { type ModelProvider, modelAliases, providers } from "../models.ts";
+import { modelAliases } from "../models.ts";

 // ── catalog drift tests — main-only ─────────────────────────────────────────────
 //
@@ -8,6 +8,12 @@ import { type ModelProvider, modelAliases, providers } from "../models.ts";
 // catalog drift (new model ships, old model deprecated, etc.) causes failures
 // that are unrelated to any code change in the PR — so these run only on main.
 //
+// the registry is kept in sync with upstreams by the `models-bump` cron
+// (`.github/workflows/models-bump.yml`), which scans models.dev every 12h and
+// opens a PR bumping `resolve` / `openRouterResolve` for any alias whose
+// upstream has shipped a newer GA version. these tests are the integrity gate
+// for that PR — they catch typos, removed models, and openrouter mismatches.
+//
 // run locally with `pnpm test:catalog`.
 // in CI, gated to push events on main.

@@ -106,40 +112,3 @@ describe("openRouterResolve OpenRouter API validity", async () => {
    });
  }
 });
-
-describe("latest model per provider snapshot", async () => {
-  const data = await api;
-  const providerKeys = Object.keys(providers) as ModelProvider[];
-
-  const latestByProvider: Record<string, { modelId: string; releaseDate: string }> = {};
-
-  for (const key of providerKeys) {
-    const providerData = data[key];
-    if (!providerData) continue;
-
-    let latest: { modelId: string; releaseDate: string } | undefined;
-    for (const [modelId, model] of Object.entries(providerData.models)) {
-      // skip non-GA models so beta/nightly churn doesn't break the snapshot
-      if (model.status) continue;
-      const rd = model.release_date;
-      if (!rd) continue;
-      // tiebreak by modelId for stable ordering when release dates match
-      if (
-        !latest ||
-        rd > latest.releaseDate ||
-        (rd === latest.releaseDate && modelId > latest.modelId)
-      ) {
-        latest = { modelId, releaseDate: rd };
-      }
-    }
-    if (latest) {
-      latestByProvider[key] = latest;
-    }
-  }
-
-  // when this fails, a provider shipped a new model. check whether we need
-  // to add or update an alias in models.ts before updating the snapshot.
-  it("matches snapshot", () => {
-    expect(latestByProvider).toMatchSnapshot();
-  });
-});
@@ -25,3 +25,18 @@ export function getApiUrl(): string {
  log.debug(`resolved API_URL: ${raw}`);
  return raw;
 }
+
+/**
+ * true when the action is configured to talk to a localhost API server (i.e.
+ * `pnpm dev` running on the developer's box). signals we can use dev-only
+ * affordances like the `x-dev-repo` proxy-token bypass — the corresponding
+ * server-side dev gates (`NODE_ENV === "development"`) ensure these paths
+ * never activate against prod regardless of what the action does.
+ */
+export function isLocalApiUrl(): boolean {
+  try {
+    return isLocalUrl(new URL(getApiUrl()));
+  } catch {
+    return false;
+  }
+}
@@ -12,7 +12,10 @@ interface InstructionsContext {
  modes: Mode[];
  agentId: AgentId;
  outputSchema?: Record<string, unknown> | undefined;
-  learnings: string | null;
+  /** absolute path to the seeded learnings tmpfile, or null when the file
+   * couldn't be seeded for some reason. main.ts always seeds, so in
+   * practice this is always set; the null case keeps the type honest. */
+  learningsFilePath: string | null;
 }

 interface PromptContext extends InstructionsContext {
@@ -350,11 +353,17 @@ function assembleFullPrompt(ctx: {
  procedure: string;
  eventContext: string;
  system: string;
-  learnings: string | null;
+  learningsFilePath: string | null;
  runtime: string;
 }): string {
-  const learningsSection = ctx.learnings
-    ? `************* LEARNINGS *************\n\n${ctx.learnings}`
+  // the LEARNINGS section is intentionally tiny — just the file path and a
+  // one-line "read it" instruction. embedding the contents would re-inflate
+  // the prompt every run (the previous design's failure mode) and clutter
+  // CI logs. the agent reads the file with its native file tool; the
+  // post-run reflection turn (action/agents/postRun.ts) is where editing
+  // is encouraged, with the prune-stale framing.
+  const learningsSection = ctx.learningsFilePath
+    ? `************* LEARNINGS *************\n\nRepo-level learnings accumulated by previous agent runs live at \`${ctx.learningsFilePath}\`. Read this file early and let the entries inform your approach (test commands, conventions, gotchas, etc.). The file may be empty if no learnings have been collected yet.`
    : "";

  const runtimeSection = `************* RUNTIME *************\n\n${ctx.runtime}`;
@@ -389,8 +398,8 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
  if (eventContext)
    tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
  tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
-  if (pctx.learnings)
-    tocEntries.push({ label: "LEARNINGS", description: "repo-specific knowledge" });
+  if (pctx.learningsFilePath)
+    tocEntries.push({ label: "LEARNINGS", description: "repo-specific knowledge file path" });
  tocEntries.push({ label: "RUNTIME", description: "environment metadata" });

  const toc = buildToc(tocEntries);
@@ -401,7 +410,7 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
    procedure,
    eventContext,
    system,
-    learnings: pctx.learnings,
+    learningsFilePath: pctx.learningsFilePath,
    runtime: pctx.runtime,
  });

@@ -0,0 +1,70 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  LEARNINGS_FILE_NAME,
+  learningsFilePath,
+  readLearningsFile,
+  seedLearningsFile,
+} from "./learnings.ts";
+
+describe("learnings tmpfile round-trip", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "pullfrog-learnings-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("seeds with existing learnings and reads them back verbatim", async () => {
+    const current = "- run tests with `pnpm -r test`\n- default branch is `main`";
+    const path = await seedLearningsFile({ tmpdir: dir, current });
+    expect(path).toBe(learningsFilePath(dir));
+    expect(path.endsWith(LEARNINGS_FILE_NAME)).toBe(true);
+    const read = await readLearningsFile(path);
+    expect(read).toBe(current);
+  });
+
+  it("seeds an empty file when the repo has no learnings yet", async () => {
+    // empty seed (vs scaffold-with-comment) keeps the byte-trim equality
+    // gate clean: an untouched first run reads back as "" and persistLearnings
+    // skips the API round-trip rather than writing a placeholder string into
+    // Repo.learnings.
+    const path = await seedLearningsFile({ tmpdir: dir, current: null });
+    const read = await readLearningsFile(path);
+    expect(read).toBe("");
+  });
+
+  it("returns null when the file is missing (treated as no-change by persist)", async () => {
+    const path = learningsFilePath(dir);
+    const read = await readLearningsFile(path);
+    expect(read).toBeNull();
+  });
+
+  it("trims whitespace so trailing newlines never trigger a spurious PATCH", async () => {
+    // editors commonly add a trailing newline on save. without trimming, a
+    // round-trip "read seed → save unchanged" would fail byte-equality and
+    // burn a LearningsRevision row on every run.
+    const current = "- one fact";
+    const path = await seedLearningsFile({ tmpdir: dir, current });
+    await writeFile(path, `${current}\n\n  `, "utf8");
+    const read = await readLearningsFile(path);
+    expect(read).toBe(current);
+  });
+
+  it("truncates content over the 10k server-side cap", async () => {
+    // server enforces MAX_LEARNINGS_LENGTH = 10_000. truncating client-side
+    // avoids a 400 round-trip and keeps the bytes the agent will see in the
+    // next run aligned with what the server actually stored.
+    const oversized = "x".repeat(11_000);
+    const path = await seedLearningsFile({ tmpdir: dir, current: null });
+    await writeFile(path, oversized, "utf8");
+    const read = await readLearningsFile(path);
+    expect(read).toBeTruthy();
+    expect(read?.length).toBe(10_000);
+  });
+});
@@ -0,0 +1,64 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/**
+ * Repo-level learnings — operational facts about a repo (setup steps, test
+ * commands, conventions, gotchas) that accumulate across agent runs and feed
+ * back into future runs as durable context. Modeled on the PR-summary tmpfile
+ * pattern (see action/utils/prSummary.ts):
+ *
+ *   1. server seeds `pullfrog-learnings.md` from `Repo.learnings` (or empty
+ *      when the repo has none yet)
+ *   2. the agent reads the file at startup as part of its context, and may
+ *      edit it in place at end-of-run when prompted by the reflection turn
+ *   3. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if it changed (byte-trim equality
+ *      against the seed determines change detection)
+ *
+ * Edit-in-place avoids stuffing the entire learnings list into both the
+ * prompt context and an `update_learnings` MCP tool call (which previously
+ * required passing the FULL merged list as a string parameter — an
+ * output-token tax that grew linearly with the learnings size).
+ */
+
+export const LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
+
+/** server-side cap mirrors `MAX_LEARNINGS_LENGTH` in
+ * `app/api/repo/[owner]/[repo]/learnings/route.ts`. truncating client-side
+ * keeps the PATCH from being rejected with a 400. */
+const MAX_LEARNINGS_LENGTH = 10_000;
+
+export function learningsFilePath(tmpdir: string): string {
+  return join(tmpdir, LEARNINGS_FILE_NAME);
+}
+
+/** seed the learnings file with the repo's current learnings, or an empty
+ * file when the repo has none yet. returns the absolute path. */
+export async function seedLearningsFile(params: {
+  tmpdir: string;
+  current: string | null;
+}): Promise<string> {
+  const path = learningsFilePath(params.tmpdir);
+  await mkdir(dirname(path), { recursive: true });
+  // empty file when no learnings exist yet — the agent reads it, sees
+  // nothing, and the LEARNINGS prompt section explains what the file is for.
+  // a header comment would risk being persisted as part of the first real
+  // edit, polluting the DB row with placeholder text.
+  await writeFile(path, params.current ?? "", "utf8");
+  return path;
+}
+
+/** read the agent-edited learnings file. returns null when the file is
+ * missing or unreadable (treated as "no change"). caps content at the
+ * server's max length to avoid a 400 round-trip. */
+export async function readLearningsFile(path: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length > MAX_LEARNINGS_LENGTH) return trimmed.slice(0, MAX_LEARNINGS_LENGTH);
+  return trimmed;
+}
@@ -7,7 +7,13 @@ describe("detectProviderError", () => {
      expect(detectProviderError("commit f609cc89e84596ab125d60dac568bfb2ef398396 429")).toBeNull();
    });

-    it("returns null for x-ratelimit-* response headers in 401 error JSON", () => {
+    it("classifies 401 + x-ratelimit-* headers as auth, not rate-limited", () => {
+      // OpenRouter 401 responses bundle `x-ratelimit-*` rate-limit headers
+      // alongside the auth error. the auth patterns must win — pre-fix this
+      // got tagged as `rate limited` because of the loose `\brate[_ ]limit`
+      // match against header names like `ratelimit-limit-requests`. note: in
+      // OpenRouter's actual format the header name is `ratelimit` (one word),
+      // but the dumped JSON sometimes contains `rate-limit` separators too.
      const stderr = JSON.stringify({
        error: { name: "APIError", statusCode: 401, message: "Invalid authentication credentials" },
        headers: {
@@ -16,7 +22,7 @@ describe("detectProviderError", () => {
          "x-ratelimit-reset-tokens": "2025-01-01T00:00:00Z",
        },
      });
-      expect(detectProviderError(stderr)).toBeNull();
+      expect(detectProviderError(stderr)).toBe("auth error (401)");
    });

    it("returns null for INTERNAL_SERVER_ERROR substring", () => {
@@ -29,6 +35,37 @@ describe("detectProviderError", () => {
    });
  });

+  describe("auth errors", () => {
+    it("detects 401 / 403 status codes as auth errors", () => {
+      expect(detectProviderError('{"statusCode": 401}')).toBe("auth error (401)");
+      expect(detectProviderError('{"statusCode": 403}')).toBe("auth error (403)");
+      expect(detectProviderError("status_code: 401")).toBe("auth error (401)");
+    });
+
+    it("detects OpenRouter 'User not found' (disabled/invalid key)", () => {
+      // bare `"code":401` lacks a status-key prefix so the 401 status pattern
+      // intentionally doesn't fire; the User-not-found pattern catches it.
+      expect(detectProviderError('{"error":{"message":"User not found","code":401}}')).toBe(
+        "auth error (invalid/disabled key)"
+      );
+      expect(detectProviderError("APIError: User not found.")).toBe(
+        "auth error (invalid/disabled key)"
+      );
+    });
+
+    it("detects 'Invalid authentication' phrasing", () => {
+      expect(detectProviderError("Invalid authentication credentials")).toBe(
+        "auth error (invalid credentials)"
+      );
+    });
+
+    it("detects 'No auth credentials found' phrasing", () => {
+      expect(detectProviderError("AI_APICallError: No auth credentials found")).toBe(
+        "auth error (missing credentials)"
+      );
+    });
+  });
+
  describe("real provider errors", () => {
    it("detects 429 only when adjacent to a status key", () => {
      expect(detectProviderError('{"statusCode": 429}')).toBe("rate limited (429)");
@@ -6,6 +6,17 @@ type ProviderErrorPattern = { regex: RegExp; label: string };
 const statusKey = `\\b(?:status[_ ]?code|http[_ ]?status|status)["']?\\s*[:=]\\s*["']?`;

 const PROVIDER_ERROR_PATTERNS: ProviderErrorPattern[] = [
+  // auth patterns must come BEFORE rate-limit patterns. OpenRouter 401 error
+  // payloads carry `x-ratelimit-*` response headers in the dump, and the
+  // free-form rate-limit regex below would otherwise win on word-boundary
+  // matches inside header names. canonical 401 messages: OpenRouter returns
+  // `{"error":{"message":"User not found","code":401}}` for disabled or
+  // invalid keys (https://openai.luzhipeng.com/docs/api/reference/errors-and-debugging).
+  { regex: new RegExp(`${statusKey}401\\b`, "i"), label: "auth error (401)" },
+  { regex: new RegExp(`${statusKey}403\\b`, "i"), label: "auth error (403)" },
+  { regex: /\bUser not found\b/i, label: "auth error (invalid/disabled key)" },
+  { regex: /\bInvalid authentication\b/i, label: "auth error (invalid credentials)" },
+  { regex: /\bNo auth credentials found\b/i, label: "auth error (missing credentials)" },
  { regex: new RegExp(`${statusKey}429\\b`, "i"), label: "rate limited (429)" },
  { regex: new RegExp(`${statusKey}500\\b`, "i"), label: "provider 500 error" },
  { regex: new RegExp(`${statusKey}503\\b`, "i"), label: "provider unavailable (503)" },
@@ -68,7 +68,7 @@ export function installBundledSkills(params: { home: string }): void {
      writeFileSync(join(skillDir, "SKILL.md"), content);
    }
  }
-  log.info(`installed bundled skills: ${BUNDLED_SKILL_NAMES.join(", ")}`);
+  log.success(`installed bundled skills: ${BUNDLED_SKILL_NAMES.join(", ")}`);
 }

 /**
@@ -108,7 +108,7 @@ export function addSkill(params: {
    }
  );
  if (result.status === 0) {
-    log.info(`installed ${params.skill} skill (${params.agent})`);
+    log.success(`installed ${params.skill} skill (${params.agent})`);
  } else {
    const stderr = (result.stderr?.toString() || "").trim();
    const errorMsg = result.error ? result.error.message : stderr;
@@ -1,3 +1,4 @@
+import { performance } from "node:perf_hooks";
 import { describe, expect, it } from "vitest";
 import { spawn } from "./subprocess.ts";

@@ -48,6 +49,36 @@ describe("spawn error path", () => {
    expect(afterHandles).toBeLessThanOrEqual(beforeHandles);
  });

+  it("killGroup: true propagates SIGKILL to grandchildren so close fires promptly", async () => {
+    // regression: node_modules/opencode-ai/bin/opencode is a Node shim that
+    // spawnSyncs the native binary with stdio:"inherit". without killGroup,
+    // child.kill("SIGKILL") hit only the shim — the native binary was
+    // reparented to PID 1, kept holding our stdout pipe via the inherited
+    // fds, and `child.on("close")` never fired (because pipes stayed open).
+    // a 5-min outer safety-net timer eventually rejected the agent promise,
+    // but the grandchild kept running until the GitHub Actions job-level
+    // timeout. this test replicates the shape with bash + a backgrounded
+    // sleep grandchild: with killGroup, close fires promptly after SIGKILL;
+    // without it, the parent would wait for sleep to exit (30s).
+    //
+    // the activity-check interval is fixed at 5s so the earliest the kill
+    // can fire is ~5s after start. budget 15s end-to-end.
+    const before = performance.now();
+    const result = await spawn({
+      cmd: "bash",
+      args: ["-c", "sleep 30 & wait"],
+      env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" },
+      activityTimeout: 1000,
+      killGroup: true,
+    }).catch((err) => err);
+    const elapsed = performance.now() - before;
+
+    expect(result).toBeInstanceOf(Error);
+    // 10s ceiling: 5s activity-check tick + signal delivery. a regression
+    // here (no killGroup) would hang for the full 30s sleep.
+    expect(elapsed).toBeLessThan(10_000);
+  }, 20_000);
+
  it("reports signal-killed subprocesses as failures, not success", async () => {
    // regression: before the fix, `child.on("close", (exitCode) => ...)`
    // discarded the signal parameter and `exitCode || 0` coerced the
@@ -106,6 +106,15 @@ export interface SpawnOptions {
  stdio?: ("pipe" | "ignore" | "inherit")[];
  onStdout?: (chunk: string) => void;
  onStderr?: (chunk: string) => void;
+  // when true, spawn the child detached (its own process group) and route all
+  // kill paths (timeout, activity timeout, ctrl-c) through `process.kill(-pid, ...)`
+  // so signals reach grandchildren too. critical for binaries that fork through
+  // a shim (e.g. node_modules/opencode-ai/bin/opencode is a Node shim that
+  // spawnSync's the native binary; without killGroup, SIGKILL only hits the
+  // shim and the native binary is reparented to PID 1, holds our stdout pipe
+  // open, keeps emitting NDJSON, and `child.on("close")` never fires —
+  // producing zombie runs that hang until the GitHub Actions job timeout).
+  killGroup?: boolean;
 }

 export interface SpawnResult {
@@ -127,6 +136,8 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
  let stdoutBuffer = "";
  let stderrBuffer = "";

+  const killGroup = options.killGroup ?? false;
+
  return new Promise((resolve, reject) => {
    // security: caller must provide complete env object, not merged with process.env
    const child = nodeSpawn(options.cmd, options.args, {
@@ -136,10 +147,28 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
      },
      stdio: options.stdio || ["pipe", "pipe", "pipe"],
      cwd: options.cwd || process.cwd(),
+      detached: killGroup,
    });

+    // sends `signal` to the entire process group when killGroup is set, so
+    // grandchildren (e.g. the native opencode binary spawned by the
+    // opencode-ai Node shim) die with the parent. falls back to a direct
+    // child kill if the process-group send fails (common when the child
+    // already exited or was never made a process group leader).
+    const killSelf = (signal: NodeJS.Signals): void => {
+      if (killGroup && child.pid) {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+          // fall through to direct kill
+        }
+      }
+      child.kill(signal);
+    };
+
    // track child for cleanup on Ctrl+C
-    trackChild({ child });
+    trackChild({ child, killGroup });

    let timeoutId: NodeJS.Timeout | undefined;
    let sigkillEscalatorId: NodeJS.Timeout | undefined;
@@ -157,7 +186,7 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
    if (options.timeout) {
      timeoutId = setTimeout(() => {
        isTimedOut = true;
-        child.kill("SIGTERM");
+        killSelf("SIGTERM");

        // track the escalator so a graceful SIGTERM response (close fires
        // before the 5s elapses) can clear it. without capture, this timer
@@ -165,7 +194,7 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
        // past a timed-out subprocess's clean exit.
        sigkillEscalatorId = setTimeout(() => {
          if (!child.killed) {
-            child.kill("SIGKILL");
+            killSelf("SIGKILL");
          }
        }, 5000);
      }, options.timeout);
@@ -186,9 +215,9 @@ export async function spawn(options: SpawnOptions): Promise<SpawnResult> {
          killedAtIdleMs = idleMs;
          const idleSec = Math.round(idleMs / 1000);
          log.info(
-            `no output for ${idleSec}s from pid=${child.pid} (${options.cmd}), killing process`
+            `no output for ${idleSec}s from pid=${child.pid} (${options.cmd}), killing process${killGroup ? " group" : ""}`
          );
-          child.kill("SIGKILL");
+          killSelf("SIGKILL");
          clearInterval(activityCheckIntervalId);
          try {
            options.onActivityTimeout?.();
Author	SHA1	Message	Date
Colin McDonnell	c8888cecde	bump action version to 0.1.2	2026-05-08 23:37:52 +00:00
Colin McDonnell	c0de70431e	ci: prune openai/gpt-pro from default models-live matrix (#637 ) * ci: prune openai/gpt-pro from default models-live matrix gpt-5.5-pro burns ~$2.40/run ($30/M input, $180/M output) — flagship reasoning tier with hidden reasoning tokens dominating cost. Multiplied by every push that touches a resolution-affecting file, the bill is untenable for a smoke that just verifies set_output works. Pruned by default; re-enable with INCLUDE_EXPENSIVE=1 or MATRIX_FILTER when validating the alias on demand. Also adds a comment-frugality rule to AGENTS.md. * ci: include list-aliases.ts in models paths-filter The matrix builder is resolution-affecting from a validation standpoint — a regression to it (e.g. accidentally pruning all aliases) wouldn't trigger models-live on its own commit.	2026-05-08 23:36:26 +00:00
Colin McDonnell	b0274e3265	local proxy-key testing via x-dev-repo bypass (#629 ) * local proxy-key testing via x-dev-repo bypass `pnpm play` previously couldn't exercise the proxy/router/oss code path — `resolveProxyModel` early-exits without OIDC credentials, and `mintProxyKey` always sends an OIDC bearer to `/api/proxy-token`. since GitHub Actions OIDC only exists in real workflow runs, billing flows (auto-reload, balance gates, key rotation, OSS subsidy) had no local feedback loop. a server-side dev bypass already exists at `app/api/proxy-token/route.ts` that accepts an `x-dev-repo: owner/repo` header instead of an OIDC bearer when `NODE_ENV === "development"`. wire the action side so it sends that header when there are no OIDC credentials AND `API_URL` resolves to localhost (i.e. the developer is talking to their own `pnpm dev` server). production is unreachable through this path because vercel never sets `NODE_ENV=development`. document the affordance in `wiki/action-tests.md` so the next person doesn't have to re-discover it (the server bypass had been sitting there undocumented since the WIP billing rewrite). verified end-to-end: `PLAY_LOCAL=1 GITHUB_REPOSITORY=pullfrog/app API_URL=http://localhost:3100 pnpm play …` now logs `» proxy: dev bypass (x-dev-repo) for pullfrog/app` → `» proxy: router → openrouter/ anthropic/claude-opus-4.7` → `» model: …(proxy)`, mints a real OpenRouter key against the dev DB, and the agent runs through the proxy. * wiki: cross-reference dev proxy-key affordance from main/e2e/stripe action-tests.md already documents the localhost+x-dev-repo path; mention it from the natural discovery points so the next person finds it without spelunking through git history again: - main.md: resolveProxyModel row in the dependencies table notes the two auth paths (OIDC bearer in prod, x-dev-repo in dev). - e2e-testing.md: "When to use this" calls out the lighter-weight alternative for proxy-only changes. - stripe.md: new "Loop including the action" subsection in the Dev workflow section, alongside the existing dev-script and cron-endpoint loops.	2026-05-08 23:35:58 +00:00
Colin McDonnell	8f36eca62a	action: use log.success for skill install confirmations	2026-05-08 23:32:20 +00:00
Colin McDonnell	3c9799adda	add models-bump cron + drop snapshot test every 12h, scripts/find-newer-models.ts scans models.dev for newer GA versions of every alias in action/models.ts and writes a focused per-alias diff. .github/workflows/models-bump.yml short-circuits when no candidates exist; otherwise hands the diff to pullfrog/pullfrog@main to evaluate against the policy in wiki/model-resolution.md and open a single living PR on the pullfrog/models-bump branch. drops the brittle "latest model per provider" snapshot block in action/test/models-catalog.main.test.ts (and its .snap file) — the cron keeps the registry in sync with upstreams, and the remaining validity tests act as the integrity gate on the bump PR.	2026-05-08 23:27:42 +00:00
Colin McDonnell	5f3e46c42d	fix: don't reuse disabled proxy key on workflow re-runs; non-fatal title-gen errors (#636 ) * fix: don't reuse disabled proxy key on workflow re-runs; non-fatal title-gen errors Three small surgical fixes addressing run https://github.com/pullfrog/app/actions/runs/25580969379: 1. `/api/proxy-token` idempotency now checks `finalizedAt`. GitHub re-runs share the same `run_id` (only `run_attempt` increments), so attempt N+1's action calls /api/proxy-token and inherits attempt N's `proxyKeyId`. The `workflow_run.completed` webhook between attempts retires that key on OpenRouter (`disableKey`), so attempt N+1 was getting back a disabled key and OpenRouter responded with `401 User not found` on every call. Falling through when finalized routes through the same billing gate (`handleRouterBilling` balance check), so no new attack surface. 2. OpenCode title-gen / small-model errors no longer fatal. OpenCode auto-spawns a small `agent=title small=true` background call at session start to name the thread, defaulting to `anthropic/claude-haiku-4.5` (anomalyco/opencode#1243). Pre-fix, the wrapper's `error` event handler treated any `type=error` as fatal, so a cosmetic title failure killed the run before primary inference even started. Now: stderr matching `small=true` sets a one-shot suppression flag for the next stdout `error` event, which is logged as a warning instead. 3. Provider-error classifier puts auth patterns above rate-limit. OpenRouter 401 payloads bundle `x-ratelimit-` response headers, and the loose `\brate[_ ]limit/i` pattern was winning. Added 401/403 status, `User not found`, `Invalid authentication`, `No auth credentials found` patterns ahead of rate-limit. Updated the existing 401-headers regression test to assert correct auth classification rather than `null`. opencode: correlate small-model error suppression by message, not by next-event Pullfrog self-review on #636 flagged a real concurrency hole. OpenCode forks the title-gen call (`session/prompt.ts:1452-1457` via `Effect.forkIn(scope)`) so it races primary inference. The previous one-shot `suppressNextErrorEvent` boolean had no per-call correlation: it was consumed by whichever stdout `type=error` event landed next, regardless of which subagent produced it. Under concurrent failures, a primary-agent error landing first could be silently downgraded to a warning while the small-model error then propagated fatally — the inverse of the bug the suppression was meant to prevent. Replaced the boolean with a `Set<string>` of pending small-model error messages. stderr extracts the inner `"message":"..."` from any classified provider error tagged `small=true`; the stdout `error` handler suppresses only when `event.error.data.message` matches a pending entry. Set is capped at 32 entries so a long stream of small-model failures can't wedge memory. Also corrected the comment that referenced "session summarizer" — verified in opencode source that summarize() does NOT use `small: true`; only the title generator does today (only `small: true` match in the codebase). * revert: drop opencode title-gen suppression We have no evidence — and can't construct a realistic scenario — where title-gen fails on an otherwise-successful run. Title-gen and primary share the same OPENROUTER_API_KEY and hit the same proxy/upstream; whatever breaks one breaks the other. The original repro on run 25580969379 is fully explained by the stale proxy key (fix #1) — title-gen happened to be the first call that surfaced the auth error, but every subsequent primary call would have died the same way. Suppression code adds complexity (cross-stream correlation logic, message matching, set capping) and a real failure mode of its own (a small-model error with a unique message could mask an unrelated primary error landing shortly after). Net negative. Removing.	2026-05-08 23:00:41 +00:00
Colin McDonnell	3d393c36a3	opencode: surface subagent events via injected plugin (#634 ) * opencode: surface subagent events via injected plugin opencode's cli/cmd/run.ts event loop filters all message.part.updated events to the orchestrator's session id (`part.sessionID !== sessionID` continue), so subagent-internal tool_use / text / step events were silently discarded by the CLI in --format json mode. opencode plugins, by contrast, receive every bus event via bus.subscribeAll() regardless of session. ship a per-run plugin (action/agents/opencodePlugin.ts) that re-emits non-orchestrator message.part.updated events as `pullfrog_bus_event` envelopes on opencode's stdout. the plugin is staged into <XDG_CONFIG_HOME>/opencode/plugin/pullfrog-events.ts which is already redirected to ctx.tmpdir — never the user's repo working tree. the plugin also forwards the orchestrator's task tool dispatch at state.status="running" — that's the first moment state.input is populated with description / subagent_type / prompt and it lands BEFORE the subagent's first message.part.updated. forwarding this lets SessionLabeler register the lens label early, so subagent events bind to the correct lens name (e.g. lens:correctness) instead of the subagent#N fallback. the existing tool_use handler dedupes on callID so the late status=completed event from the CLI doesn't double-record. the parent's pullfrog_bus_event handler synthesizes the equivalent CLI-style event for each part type (tool/step-start/step-finish/text) and dispatches through the same handlers used by orchestrator events, so labeling, tool-call rendering, and the formatWithLabel magenta prefix all share one code path. verified end-to-end via `pnpm play --local --raw` with a prompt that dispatches a reviewfrog subagent: orchestrator's task call now logs "» dispatching subagent: lens:read-readme-and-report-purpose" before the subagent runs, the subagent's read tool call surfaces with [lens:...] magenta prefix, and the run-end "subagent finished" attribution shows the lens name. also adds an AGENTS.md rule formalizing the no-write-to-repo invariant: action runtime must never write into the user's working tree; auxiliary files go in ctx.tmpdir via HOME / XDG_CONFIG_HOME. * drop opencodePlugin.test.ts — bullshit-test cleanup these tests spied on process.stdout.write, loaded the plugin source into a temp file via dynamic import, and asserted the output strings matched the plugin source i'd just hand-written. zero unique signal over the e2e run in preview repo, plus they violate AGENTS.md's "mocks tend to add ceremony and brittleness" rule. real signal lives in the e2e: lens label rendering, dispatch attribution, no double events. if a syntactic regression in the plugin source ever ships, opencode logs it on plugin load and the e2e fails fast — the unit tests would catch the same regression no faster. * remove isPausedExternally — plugin makes it unnecessary empirical proof from PR #634's e2e debug trace: ~3.3 pullfrog_bus_event lines per second arrive on the parent's child.stdout pipe during a typical subagent run. each one fires updateActivity() and resets lastActivityTime, so the inner spawn activity timer naturally stays armed-but-not-fired throughout the subagent's lifetime — no suspend predicate needed. drop: - SpawnOptions.isPausedExternally + the check in spawn()'s activity loop - isSubagentInFlight() in opencode.ts + its callsite - two isPausedExternally unit tests in subprocess.test.ts keep: - killGroup (the actual zombie-prevention fix; still tested) - the plugin (action/agents/opencodePlugin.ts; the architectural fix) - everything in opencode.ts that derives lens labels from task dispatches the only edge case isPausedExternally covered that the plugin doesn't is a non-streaming provider going silent for >5min during a single LLM call inside a subagent. that's a provider-behavior question, not a harness-architecture one — best fixed at the provider level if it shows up. defense-in-depth that adds indirection is harmful when the upstream architectural fix is already in place. * opencode: address review feedback on bus envelope routing three findings from PR #634 review (2026-05-08T22:13:44Z): 1. token/cost double-count: routing subagent step_finish through the orchestrator's handler folded subagent tokens/cost into the run-wide accumulators that flow to logTokenTable + AgentUsage. neighbouring init/text handlers all gate on ORCHESTRATOR_LABEL for exactly this reason. fix: drop step_start AND step_finish from the bus envelope handler — those carry orchestrator-scoped state (currentStepId, stepHistory, token accumulators) that subagent events shouldn't touch. tool calls and text from subagents still surface — that's the user-visible activity. 2. subagent tool errors invisible: routed status="error" tool parts into handlers.tool_use which only emits "» <tool>(...)" with no error indication. fix: extend handlers.tool_use itself to log "» tool call failed: <msg>" when state.status==="error". benefits the orchestrator path too — opencode CLI also emits failed tool calls as tool_use at status=error and we were swallowing the failure signal there as well. 3. stale comments + leaked local paths: plugin source had /tmp/opencode-investigate/... paths from my local clone, specific line numbers from opencode's dev branch that don't match v1.1.56, forkDetach claim that's wrong for the pinned version, and JSDoc that still listed message.updated/session.error in the forwarded set after the runtime filter narrowed to message.part.updated only. fix: drop machine-local paths, drop version-fragile line numbers, correct the forwarded-set list, generalize the "why no @opencode-ai/plugin import" rationale to be version-agnostic. second review (2026-05-08T22:27:58Z) confirms these are the only findings still open — no new issues from the isPausedExternally removal.	2026-05-08 22:46:43 +00:00
Colin McDonnell	d6de1c369a	learnings: edit-in-place tmpfile (drop `update_learnings` tool) (#635 ) * learnings: edit-in-place tmpfile (drop update_learnings tool) learnings now follow the PR-summary file pattern: server seeds `pullfrog-learnings.md` from `Repo.learnings` at startup, agent reads it as part of context, may edit in place during the post-run reflection turn, server reads back at end-of-run and PATCHes if changed. motivation: `update_learnings` required the agent to pass the FULL merged list as a string parameter — an output-token tax that grew linearly with the learnings size, and a constant prompt-context expansion since the contents were also inlined into the LEARNINGS section. for repos with mature learnings the prompt was getting visibly noisy in CI logs. key changes: - new `action/utils/learnings.ts` (seed/read helpers + 10k cap) - `main.ts`: always seed; `persistLearnings` mirrors `persistSummary` (success path, error path, exit-signal handler, idempotent guard, byte-trim equality skip); forwards `model` for `LearningsRevision.model` - `LEARNINGS` prompt section now contains only the file path + a one-line "read it" instruction (no contents inlined) - `update_learnings` MCP tool deleted; `action/mcp/learnings.ts` removed - reflection turn (`buildLearningsReflectionPrompt`) reframed around file editing with explicit prune-stale + leave-alone-if-nothing-new framing - `learningsStep` removed from every mode checklist — surface lives only in the LEARNINGS prompt section + the reflection turn now * learnings: harden seed step + refresh stale docs (review feedback) Three findings from PR review, all implemented: 1. wrap learnings seed in best-effort try/catch (action/main.ts) — the always-on seed block ran unconditionally and an unwrapped `seedLearningsFile` (mkdir + writeFile) failure (ENOSPC, EACCES, hostile sandbox) would unwind into the outer main() catch and flip an otherwise-successful run to "❌ Pullfrog failed" before the agent even started. asymmetric with `persistLearnings`'s own best-effort contract. wrap and log on failure; downstream consumers (`persistLearnings`, agent harnesses, `resolveInstructions`) already handle `learningsFilePath: undefined` cleanly. 2. refresh wiki/main.md — `resolveInstructions` parameter renamed from `learnings` to `learningsFilePath` in this PR; the data-flow diagram and the resolver dependency table both still showed the pre-refactor signature. 3. drop deleted `learnings.ts` from ROADMAP.md + RESEARCH.md "missing MCP tool tests" bullets — `action/mcp/learnings.ts` was removed in this PR; the bullets are otherwise still accurate.	2026-05-08 22:45:26 +00:00
Colin McDonnell	2e6c01670e	mcp: log artifact id after every github write (#633 ) makes debugging easier by emitting a single `» <verb> <kind> <id>` line after every successful GitHub write (and upload) the agent performs via the Pullfrog MCP, mirroring the chevron convention used elsewhere.	2026-05-08 21:48:28 +00:00
Colin McDonnell	17b610e1a1	bump action version to 0.1.1	2026-05-08 21:32:06 +00:00
Colin McDonnell	ca913c76ea	spawn: kill process group + heartbeat subagent activity (#631 ) * spawn: kill process group + heartbeat subagent activity two compounding bugs produced zombie agent runs that stalled until the GitHub-Actions job-level timeout (observed on PR #622, run 25577068620). 1. SIGKILL hit the wrong process. node_modules/opencode-ai/bin/opencode is a Node shim that spawnSyncs the native opencode-<plat>-<arch> binary with stdio:"inherit". our spawn() ran without detached, so child.kill("SIGKILL") killed only the shim. the native binary was reparented to PID 1, kept holding our stdout pipe via inherited fds, and child.on("close") never fired — leaving the agent promise pending past the 5min outer safety-net timer ("agent still pending 5min after inner activity kill — forcing exit") and the grandchild running until the runner timed out. fix: SpawnOptions gains killGroup; when set, we spawn detached and route all kill paths (timeout, activity timeout, ctrl-c) through process.kill(-pid, signal). opencode + claude opt in. 2. inner activity timer false-fired during long task subagents. opencode's `task` tool encapsulates subagent execution in-process — subagent-internal events don't reach the parent NDJSON stream — so the parent looked idle for the full subagent duration even when real work was happening, and the 5min DEFAULT_ACTIVITY_TIMEOUT_MS would fire mid-subagent. fix: SpawnOptions gains externalActivitySource; the timer fires on min(local stdout idle, external idle). opencode passes getIdleMs() from the global activity tracker and runs a 30s heartbeat (markActivity()) while at least one task dispatch is in flight. action/utils/subprocess.test.ts covers both: a bash+sleep grandchild that proves close fires <10s with killGroup, and externalActivitySource keeping the timer armed during 8s of stdout silence. * opencode: suspend activity timer instead of heartbeat during subagent runs addresses review on prior commit: replace the 30s markActivity() heartbeat with a boolean isPausedExternally predicate keyed off opencode's existing taskDispatchByCallID + pendingTaskDispatches. no fake activity, no race window between a 30s tick and a subagent that finishes between ticks. while the predicate returns true, spawn's activity check skips the kill decision and advances lastActivityTime so a clean unpause can't fire on a stale baseline. tests cover both the suspended case (8s of stdout silence + activityTimeout=1s but paused → process exits cleanly) and the resume case (paused for 500ms then unpaused → 30s sleep gets killed by activity timeout as normal).	2026-05-08 21:29:22 +00:00