pullfrog 0.1.13 → 0.1.15

package/dist/internal/index.d.ts

@@ -8,6 +8,8 @@ export type { Mode } from "../modes.ts";
 export { modes } from "../modes.ts";
 export type { BuildPullfrogFooterParams, WorkflowRunFooterInfo, } from "../utils/buildPullfrogFooter.ts";
 export { buildPullfrogFooter, PULLFROG_DIVIDER, stripExistingFooter, } from "../utils/buildPullfrogFooter.ts";
+export type { CodexAuthBody } from "../utils/codexOAuth.ts";
+export { decodeJwtExpMs, OAuthInvalidGrantError, parseCodexAuthBody, refreshCodexAuthBody, stringifyCodexAuthBody, } from "../utils/codexOAuth.ts";
 export type { ResourceUsage, UsageSummary } from "../utils/github.ts";
 export { isLeapingIntoActionCommentBody, LEAPING_INTO_ACTION_PREFIX, } from "../utils/leapingComment.ts";
 export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "../utils/learningsTruncate.ts";

package/dist/internal.js

@@ -101,7 +101,7 @@ var providers = {
       "gemini-flash": {
         displayName: "Gemini Flash",
         resolve: "google/gemini-3.5-flash",
-        openRouterResolve: "openrouter/google/gemini-3-flash-preview"
+        openRouterResolve: "openrouter/google/gemini-3.5-flash"
       }
     }
   }),
@@ -249,8 +249,8 @@ var providers = {
       },
       "gemini-flash": {
         displayName: "Gemini Flash",
-        resolve: "opencode/gemini-3-flash",
-        openRouterResolve: "openrouter/google/gemini-3-flash-preview"
+        resolve: "opencode/gemini-3.5-flash",
+        openRouterResolve: "openrouter/google/gemini-3.5-flash"
       },
       "kimi-k2": {
         displayName: "Kimi K2",
@@ -388,8 +388,8 @@ var providers = {
       },
       "gemini-flash": {
         displayName: "Gemini Flash",
-        resolve: "openrouter/google/gemini-3-flash-preview",
-        openRouterResolve: "openrouter/google/gemini-3-flash-preview"
+        resolve: "openrouter/google/gemini-3.5-flash",
+        openRouterResolve: "openrouter/google/gemini-3.5-flash"
       },
       grok: {
         displayName: "Grok",
@@ -704,6 +704,8 @@ function computeModes(agentId) {
 
    Otherwise delegate the \`${REVIEWER_AGENT_NAME}\` subagent to review your diff with fresh eyes against YOUR TASK. The subagent's baked-in system prompt enforces a non-mutative + non-recursive contract: read-only file/search/web tools and read-only MCP queries only; no writes, shell side effects, state-changing MCP calls, or nested subagent dispatch. Enforcement is prose-only \u2014 restate the constraint in your dispatch instructions and do not relax it.
 
+   Before dispatching, ensure \`origin/<base>\` is locally available \u2014 the runner is often a shallow single-branch \`actions/checkout\` (depth=1, head-only refspec), and the reviewer's \`git diff --merge-base origin/<base>\` will fail with \`ambiguous argument\` or \`no merge base\` otherwise. Run \`git fetch --no-tags --deepen=1000 origin <base>\` once; it's a no-op if the ref already has enough history. (The reviewer is read-only by contract, so it cannot do this itself \u2014 fetching is the orchestrator's job.)
+
    Compose your \`${REVIEWER_AGENT_NAME}\` dispatch prompt using this template verbatim, substituting the \`<...>\` placeholders. The preamble aligns the orchestrator side of the dispatch contract with the reviewer's baked-in system prompt \u2014 both ends say the same thing about where the work lives and what to do on an empty diff.
 
    \`\`\`
@@ -711,9 +713,11 @@ function computeModes(agentId) {
    This is a PRE-COMMIT Build-mode self-review. The work to review lives in the working tree (uncommitted), NOT in committed history.
 
    Branch: <branch> (off <base>)
-   Canonical diff command: git diff origin/<base>
+   Canonical diff command: git diff --merge-base origin/<base>
+
+   Use \`--merge-base\` (single MCP \`git\` call, no shell substitution required). NOT bare \`git diff origin/<base>\` or two-dot \`git diff origin/<base>..HEAD\` \u2014 the symmetric forms include the inverse of every commit landed on \`<base>\` since this branch forked, which is noise (and the git tool will reject those forms when the divergence is detected). \`origin/<base>...HEAD\` (three-dot) and \`--cached\` both miss the uncommitted edits self-review runs on, so they're also wrong here.
 
-   If that command returns empty, treat it as "no changes \u2014 nothing to review" and stop per your system prompt. Do not search for the work elsewhere.
+   If the merge-base diff returns empty, treat it as "no changes \u2014 nothing to review" and stop per your system prompt. Do not search for the work elsewhere.
 
    ## Your task
    <YOUR TASK content>
@@ -722,7 +726,7 @@ function computeModes(agentId) {
    <tight summary \u2014 what broke, root cause, the fix \u2014 or "no build-phase failures">
    \`\`\`
 
-   Follow the template with the diff content (\`git diff origin/<base-branch>\`, single-rev form \u2014 \`main...HEAD\` and \`--cached\` both miss the uncommitted edits self-review runs on) and your task brief. Instruct the subagent to flag bugs, logic errors, missing edge cases, gaps between request and diff, and unintended changes.
+   Follow the template with the diff content (\`git diff --merge-base origin/<base-branch>\` \u2014 single MCP \`git\` call, captures committed + staged + unstaged, excludes base-branch progress) and your task brief. Instruct the subagent to flag bugs, logic errors, missing edge cases, gaps between request and diff, and unintended changes.
 
    Delegation + research discipline (distilled from \`/anneal\` canonical \u2014 these are codified learnings from many review rounds, not theoretical best practices):
    - Do NOT summarize what you implemented \u2014 that biases the subagent toward validating the shape of your solution rather than questioning it.
@@ -864,7 +868,7 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
    You can also include your own \`read\` / \`grep\` / \`webfetch\` calls in the SAME turn as the parallel \`${REVIEWER_AGENT_NAME}\` dispatches \u2014 concurrent context-pulling on the orchestrator side runs in parallel with the lens fan-out and costs zero extra wall time.
 
    if a subagent errors out, times out, or returns nothing usable, retry once with the same lens; if it still fails, proceed with partial coverage and note the missing lens in the review body \u2014 do not skip the fan-out entirely on a single subagent failure. each subagent gets:
-   - the diff path / target \u2014 reading the diff and the codebase is its job
+   - **the absolute \`diffPath\` (and \`incrementalDiffPath\` if available) from step 2's \`${t("checkout_pr")}\` return, named verbatim in the dispatch prompt** (e.g. \`diffPath: /tmp/pullfrog-XXXX/pr-NNN-SHA.diff\`). the reviewer's baked-in system prompt selects its FIRST action on this token \u2014 paraphrasing ("review the diff", "look at this PR") sends it down the \`git diff origin/<base>\` fallback, which fails on shallow GHA checkouts. the subagent \`read\`s those files for scope; it must NOT re-derive the diff via \`git diff\` (bare \`git diff origin/<base>\` is symmetric and pulls in the inverse of any commits that landed on \`<base>\` since the branch forked \u2014 pure noise, and the git tool rejects it). reading and codebase exploration are still its job.
    - **only one lens** \u2014 never a multi-section "review for X, Y, and Z" prompt
    - **a Task \`description\` set to the lens name** (e.g. \`"security"\`, \`"correctness"\`, \`"billing-subsystem"\`) \u2014 the harness reads this field to label the subagent's log lines so parallel runs can be told apart in CI output. without it, every subagent shows up as \`subagent#N\`.
    - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search rather than trust training data, and to quote source URLs in its reasoning. action runs are non-interactive \u2014 there's no human in the loop to catch "I'm pretty sure Stripe does X."
@@ -974,7 +978,7 @@ ${PR_SUMMARY_FORMAT}`
    You can also include your own \`read\` / \`grep\` / \`webfetch\` calls in the SAME turn as the parallel \`${REVIEWER_AGENT_NAME}\` dispatches.
 
    if a subagent errors out, times out, or returns nothing usable, retry once with the same lens; if it still fails, proceed with partial coverage and note the missing lens in the review body. each subagent gets:
-   - the diff scope (incremental diff path if available, full diff otherwise). do NOT tell them to skip pre-existing issues \u2014 that suppresses regressions the new commits amplified; the "issues must be NEW" filter lives at aggregation time (step 8), not in the subagent prompt
+   - **the absolute diff path(s) from step 2's \`${t("checkout_pr")}\` return, named verbatim in the dispatch prompt.** when \`incrementalDiffPath\` is present, name BOTH (\`incrementalDiffPath: /tmp/.../pr-NNN-SHA-incremental.diff\` then \`diffPath: /tmp/.../pr-NNN-SHA.diff\`) \u2014 the reviewer's baked-in prompt reads incremental first and uses full for context; when only \`diffPath\` exists, name it alone. the subagent \`read\`s those files; it must NOT re-derive via \`git diff\` (bare \`git diff origin/<base>\` is symmetric and pulls in the inverse of base-branch progress \u2014 pure noise, and the git tool rejects it), and paraphrasing ("review the new commits") sends it down that fallback, which also fails on shallow GHA checkouts. do NOT tell them to skip pre-existing issues \u2014 that suppresses regressions the new commits amplified; the "issues must be NEW" filter lives at aggregation time (step 8), not in the subagent prompt.
    - **only one lens** \u2014 never a multi-section "review for X, Y, and Z" prompt
    - **a Task \`description\` set to the lens name** \u2014 the harness reads this field to label log lines so parallel runs can be told apart.
    - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search and quote source URLs.
@@ -1157,6 +1161,92 @@ function stripExistingFooter(body) {
   return body.substring(0, dividerIndex).trimEnd();
 }
 
+// utils/codexOAuth.ts
+var CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+var CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+var OAuthInvalidGrantError = class extends Error {
+  status;
+  constructor(status, body) {
+    super(`Codex token refresh failed: ${status} ${body}`);
+    this.name = "OAuthInvalidGrantError";
+    this.status = status;
+  }
+};
+async function refreshCodexAuthBody(body) {
+  const response = await fetch(CODEX_OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: body.tokens.refresh_token,
+      client_id: CODEX_OAUTH_CLIENT_ID
+    }).toString(),
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    if (response.status >= 400 && response.status < 500) {
+      throw new OAuthInvalidGrantError(response.status, text);
+    }
+    throw new Error(`Codex token refresh failed: ${response.status} ${text}`);
+  }
+  const tokens = await response.json();
+  const idToken = tokens.id_token ?? body.tokens.id_token;
+  const accountId = body.tokens.account_id;
+  return {
+    auth_mode: "chatgpt",
+    tokens: {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      ...idToken ? { id_token: idToken } : {},
+      ...accountId ? { account_id: accountId } : {}
+    },
+    last_refresh: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function decodeJwtExpMs(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) return null;
+  return payload.exp * 1e3;
+}
+function parseCodexAuthBody(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const v = parsed;
+  if (v.auth_mode !== "chatgpt") return null;
+  const tokens = v.tokens;
+  if (!tokens || typeof tokens !== "object") return null;
+  const t = tokens;
+  if (typeof t.access_token !== "string" || t.access_token.length === 0) return null;
+  if (typeof t.refresh_token !== "string" || t.refresh_token.length === 0) return null;
+  return {
+    auth_mode: "chatgpt",
+    tokens: {
+      access_token: t.access_token,
+      refresh_token: t.refresh_token,
+      ...typeof t.id_token === "string" ? { id_token: t.id_token } : {},
+      ...typeof t.account_id === "string" ? { account_id: t.account_id } : {}
+    },
+    ...typeof v.last_refresh === "string" ? { last_refresh: v.last_refresh } : {}
+  };
+}
+function stringifyCodexAuthBody(body) {
+  return `${JSON.stringify(body, null, 2)}
+`;
+}
+
 // utils/leapingComment.ts
 var LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
 function isLeapingIntoActionCommentBody(body) {
@@ -1292,10 +1382,12 @@ export {
   DEFAULT_PROXY_MODEL,
   LEAPING_INTO_ACTION_PREFIX,
   MAX_LEARNINGS_LENGTH,
+  OAuthInvalidGrantError,
   PULLFROG_DIVIDER,
   TIMEOUT_DISABLED,
   buildPullfrogFooter,
   createLeapingProgressComment,
+  decodeJwtExpMs,
   deleteProgressCommentApi,
   getModelEnvVars,
   getModelManagedCredentials,
@@ -1306,14 +1398,17 @@ export {
   isValidTimeString,
   modelAliases,
   modes,
+  parseCodexAuthBody,
   parseModel,
   parseTimeString,
   providers,
   pullfrogMcpName,
+  refreshCodexAuthBody,
   resolveCliModel,
   resolveDisplayAlias,
   resolveModelSlug,
   resolveOpenRouterModel,
+  stringifyCodexAuthBody,
   stripExistingFooter,
   truncateAtLineBoundary,
   updateProgressComment

package/dist/toolState.d.ts

@@ -102,7 +102,7 @@ export interface ToolState {
     learningsFilePath?: string;
     learningsSeed?: string;
     learningsPersistAttempted?: boolean;
-    output?: string;
+    output?: string | undefined;
     usageEntries: AgentUsage[];
     model?: string | undefined;
     modelFallback?: {

package/dist/utils/apiKeys.d.ts

@@ -1,10 +1,19 @@
-/** check if the user has a BYOK key for the given model's provider (does not throw) */
-export declare function hasProviderKey(model: string): boolean;
+/**
+ * Validate that the resolved model can actually be served by the chosen
+ * agent. For routing slugs (Bedrock / Vertex) the auth shape is multi-var
+ * (auth + region/location + model-id) and `opencode models` doesn't catch
+ * gaps in the latter two — keep dedicated setup validators. For the
+ * opencode path, the authoritative answer comes from OpenCode's own model
+ * introspection (`authorized` set captured in `openCodeModels.ts`). For
+ * the claude path, fall back to the static check (`ANTHROPIC_API_KEY` /
+ * `CLAUDE_CODE_OAUTH_TOKEN`).
+ */
 export declare function validateAgentApiKey(params: {
     agent: {
         name: string;
     };
     model: string | undefined;
+    authorized: Set<string>;
     owner: string;
     name: string;
 }): void;

package/dist/utils/byokFallback.d.ts

@@ -1,7 +1,6 @@
 /**
  * Slug we fall back to when a BYOK-required model is configured but the
- * runner has no provider key in env. Picked because it's free
- * (`isFree: true`, `envVars: []` — see `action/models.ts`), stable, and
+ * runner has no provider key in env. Picked because it's free, stable, and
  * currently served by OpenCode Zen without a key.
  *
  * The slug is intentionally hard-coded and not a config knob — the
@@ -18,32 +17,22 @@ export type FallbackDecision = {
     to: string;
 };
 /**
- * If the resolved model requires a BYOK key but no provider key is
- * available in env, return `fallback: true` with a free OpenCode slug
- * so the run can still succeed. Caller is responsible for swapping the
- * model state and surfacing the fallback (log line + run summary).
+ * If the resolved model is NOT in OpenCode's `authorized` set (the
+ * authoritative "what can OpenCode route right now" snapshot captured
+ * after dbSecrets + Codex auth.json are in place), swap to a free
+ * OpenCode slug so the run can still produce value. Caller is responsible
+ * for surfacing the swap (log line + run summary).
  *
- * Gates on `resolvedModel` directly (not the configured slug) so the
- * decision matches both code paths that reach this point: payload-based
- * config (`repo.model` from DB) and `PULLFROG_MODEL` env var. Both end
- * up in `resolvedModel` after `resolveModel()` runs upstream.
- *
- * Skip cases:
- *   - Router / proxy runs (`proxyModel` set): Pullfrog mints the key,
- *     no BYOK in play — never fall back.
- *   - No resolved model: keeps the existing auto-select-with-throw
- *     behavior in `validateAgentApiKey` for the "neither model nor
- *     key" case (genuine misconfig the user should see).
- *   - Resolved model is itself the free fallback: avoid suggesting we
- *     fell back to the model we're already running.
- *   - Resolved model is a Bedrock raw ID (no `/`): Bedrock has its own
- *     auth shape (`AWS_BEARER_TOKEN_BEDROCK` + region + model ID), and
- *     `validateBedrockSetup` already surfaces a tailored error. Skipping
- *     here also avoids `parseModel`'s slash requirement crashing inside
- *     `hasProviderKey`.
- *   - Resolved model has its provider key present: no fallback needed.
+ * Skip cases (return `fallback: false` without consulting `authorized`):
+ *   - Router / proxy runs (`proxyModel` set): Pullfrog mints the key.
+ *   - No resolved model: auto-select handles it downstream.
+ *   - Resolved model is the free fallback already.
+ *   - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
+ *     validators (`validateBedrockSetup` / `validateVertexSetup`) cover
+ *     auth + region/location/model-id; `opencode models` does not.
  */
 export declare function selectFallbackModelIfNeeded(input: {
     resolvedModel: string | undefined;
     proxyModel: string | undefined;
+    authorized: Set<string>;
 }): FallbackDecision;

package/dist/utils/codexHome.d.ts

@@ -1,15 +1,28 @@
+/** sandbox-hidden home for pullfrog-managed on-disk secrets in CI. bash via
+ * MCP shell tmpfs-overlays this path; opencode's internal auth module
+ * bypasses external_directory and reaches the real file. mirrors the
+ * pattern in action/agents/claude.ts installManagedSettings.
+ *
+ * not used for codex auth in local dev — the sandbox is no-op there, so
+ * the path doesn't matter. local dev keeps the existing $HOME path. */
+export declare const PULLFROG_DATA_DIR = "/var/lib/pullfrog";
 export interface InstalledCodexAuth {
     /** absolute path of the auth.json we wrote — caller passes this to the
      * post-hook via core.saveState for refresh-detection later. */
     authPath: string;
     /** value to set as XDG_DATA_HOME for the OpenCode subprocess. */
     xdgDataHome: string;
-    /** refresh_token from the env at materialization time. post-hook compares
-     * against the on-disk file after the run to detect whether OpenCode
-     * refreshed during the session. */
+    /** refresh_token from the env at materialization time. post-hook
+     * compares against the on-disk file after the run to detect whether
+     * OpenCode refreshed during the session (only happens on long runs
+     * that span >50min — see wiki/codex-auth.md "Concurrency"). */
     originalRefresh: string;
 }
 /** materialize CODEX_AUTH_JSON from env into a disk path OpenCode reads from.
  * returns null when the env var is absent, malformed, or wrong auth mode —
- * caller treats null as "no codex auth, fall through to API key flow". */
+ * caller treats null as "no codex auth, fall through to API key flow".
+ *
+ * The env value is server-side guaranteed fresh by `maybeRotateCodexSecret`
+ * in the run-context endpoint. We only parse + write it here; no refresh,
+ * no DB interaction. */
 export declare function installCodexAuth(): InstalledCodexAuth | null;

package/dist/utils/codexOAuth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure-stdlib (fetch + Buffer) Codex OAuth refresh + JWT exp decoding.
+ *
+ * Lives here (not in codexAuth.ts) so the Next.js server side can import it
+ * via pullfrog/internal without dragging in node:child_process / spawn /
+ * mkdtemp from the rest of codexAuth.ts. Used by:
+ *   - action/utils/codexAuth.ts (re-exports refreshCodexAuthBody)
+ *   - utils/codexSecretRotation.ts (server-side maybeRotate at run-context)
+ *
+ * See wiki/codex-auth.md for the end-to-end refresh lifecycle.
+ */
+export interface CodexAuthBody {
+    auth_mode: "chatgpt";
+    tokens: {
+        access_token: string;
+        refresh_token: string;
+        id_token?: string;
+        account_id?: string;
+    };
+    last_refresh?: string;
+}
+/** OAuth client id Codex CLI and OpenCode both use against `auth.openai.com`.
+ * Same chain — a refresh token minted via `codex login --device-auth` can be
+ * refreshed against this client_id. */
+export declare const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** thrown when the OAuth provider rejects the refresh token (4xx). callers
+ * can distinguish "race-lost / token revoked" from network errors via
+ * `instanceof OAuthInvalidGrantError`. */
+export declare class OAuthInvalidGrantError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** force one refresh round-trip against the OAuth provider. returns the
+ * rotated Codex-shaped blob (the auth.json body verbatim). does NOT persist
+ * — caller is responsible for writing back to wherever the token lives.
+ *
+ * server-side callers (maybeRotateCodexSecret) hold a DB row lock around
+ * this call so concurrent runs serialize: first one rotates, subsequent
+ * ones see the fresh value and skip. The 10s timeout is critical for that
+ * use: it caps how long a stalled auth.openai.com holds the row lock,
+ * keeping us well under the enclosing 30s transaction budget so the lock
+ * always releases and queued callers get a turn instead of timing out on
+ * the tx wrapper. Real OAuth latency is sub-second; 10s is generous. */
+export declare function refreshCodexAuthBody(body: CodexAuthBody): Promise<CodexAuthBody>;
+/** decode the access_token's JWT payload and return its `exp` claim in ms
+ * since epoch. returns null if the token isn't a parseable JWT or has no
+ * `exp` claim — caller falls back to "treat as expired".
+ *
+ * We don't verify the JWT signature (we'd need OpenAI's JWKS); we're only
+ * using the claim as a freshness hint. The actual auth check happens
+ * server-side at OpenAI when the token is used — trusting a fake JWT here
+ * would just delay the inevitable 401 from OpenAI. No security boundary
+ * at this decode step. */
+export declare function decodeJwtExpMs(token: string): number | null;
+/** parse + validate a Codex auth.json body from its JSON-string form.
+ * returns null on any shape mismatch — caller treats as "no codex auth". */
+export declare function parseCodexAuthBody(raw: string): CodexAuthBody | null;
+/** serialize a CodexAuthBody to its canonical on-disk form. */
+export declare function stringifyCodexAuthBody(body: CodexAuthBody): string;

package/dist/utils/gitAuth.d.ts

@@ -1,9 +1,14 @@
 /**
  * git authentication via GIT_ASKPASS.
  *
- * a localhost HTTP server serves tokens via single-use UUID codes.
- * each $git() call writes a unique askpass script with the server
- * port+code baked into the file body — no secrets in subprocess env.
+ * a localhost HTTP server serves tokens via UUID codes whose lifetime is
+ * bounded by the parent $git() invocation: register() makes the code active,
+ * the script (and any sibling subprocess — e.g. git-lfs pre-push) can fetch
+ * the token any number of times, and $git()'s finally calls revoke() to
+ * close the window. each $git() call writes a unique askpass script with
+ * the server port+code baked into the file body — no secrets in subprocess
+ * env. a replay of a revoked code trips a 409 and revokes the underlying
+ * github installation token.
  *
  * see wiki/askpass.md for full security documentation.
  */
@@ -35,9 +40,13 @@ export declare function setGitAuthServer(server: GitAuthServer): void;
  * a remote and need credentials. working-tree operations (checkout, merge)
  * use $() from shell.ts which has no token.
  *
- * per call: registers a one-time code with the auth server, writes a
- * unique askpass script with port+code baked in, spawns git with
- * GIT_ASKPASS pointing to the script, and deletes the script in finally.
+ * per call: registers a code with the auth server (valid for the lifetime
+ * of this invocation), writes a unique askpass script with port+code baked
+ * in, spawns git with GIT_ASKPASS pointing to the script. on completion,
+ * revokes the code and deletes the script in finally. multiple sibling
+ * askpass calls within one invocation (e.g. git itself + git-lfs pre-push)
+ * all see a valid code; replay attempts after finally trip a 409 and the
+ * server revokes the underlying github token as a tamper signal.
  *
  * @example
  * await $git("fetch", ["origin", "main"], { token });

package/dist/utils/gitAuthServer.d.ts

@@ -1,16 +1,22 @@
 /**
  * ASKPASS-based git authentication server.
  *
- * serves tokens via a localhost HTTP server with single-use UUID codes.
+ * serves tokens via a localhost HTTP server with per-$git()-call UUID codes.
  * each $git() call gets a unique askpass script with the port+code baked in.
  * the token never appears in subprocess env — only the script file path.
  *
- * tamper-evident: if a code is used twice, the second request triggers
- * immediate token revocation via the GitHub API as a precaution.
+ * lifetime: the code is valid for as long as the $git() invocation is
+ * running. multiple askpass calls within one invocation (e.g. git's own
+ * fetch/push + a git-lfs pre-push hook that also authenticates) all
+ * succeed. $git() calls revoke(code) in finally; subsequent requests for
+ * a revoked code trigger immediate token revocation via the GitHub API
+ * as a tamper-evidence precaution (an agent replaying the code after the
+ * legitimate window has closed is the realistic attack we still catch).
  */
 export type GitAuthServer = {
     port: number;
     register: (token: string) => string;
+    revoke: (code: string) => void;
     writeAskpassScript: (code: string) => string;
     close: () => Promise<void>;
     [Symbol.asyncDispose]: () => Promise<void>;

package/dist/utils/lifecycle.d.ts

@@ -1,6 +1,18 @@
 export interface ExecuteLifecycleHookParams {
     event: string;
     script: string | null;
+    /**
+     * when true, after the hook runs (success or failure), discard tracked-file
+     * mods so the agent doesn't see hook-generated drift (e.g. `pnpm install`
+     * rewriting a lockfile). untracked files are preserved — hooks that
+     * intentionally materialize files (e.g. a `.env` from a template) stay
+     * visible to the agent. skipped (with a warning) if the tree had
+     * pre-existing tracked changes before the hook ran, so we never clobber
+     * pre-existing work; pre-existing untracked files are ignored for this
+     * gate because `git restore --staged --worktree .` doesn't touch them
+     * anyway. no-op when no script was configured.
+     */
+    normalizeWorkingTreeAfter?: boolean;
 }
 /** structured failure info — `output` on the `exit` variant is trimmed
  * stderr, falling back to stdout when stderr is empty. */

package/dist/utils/openCodeModels.d.ts

@@ -0,0 +1,11 @@
+/** Snapshot the set of models OpenCode can serve from the current env, BEFORE
+ * Pullfrog-stored credentials are merged in. Call once early in `main.ts`. */
+export declare function captureBaselineModels(cliPath: string): void;
+/** Snapshot the set of models OpenCode can serve AFTER dbSecrets +
+ * Codex auth.json are in place. Logs the diff against the baseline as
+ * `» BYOK auth enabled N model(s): …`. */
+export declare function captureAuthorizedModels(cliPath: string): void;
+/** Authorized set captured after Pullfrog-stored auth is applied. Throws if
+ * called before `captureAuthorizedModels` — the call sites (fallback gate,
+ * api-key validation, auto-select) all run strictly after capture. */
+export declare function getAuthorizedModels(): Set<string>;

package/dist/utils/packageManager.d.ts

@@ -0,0 +1,32 @@
+export type SupportedPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+export interface PackageManagerSpec {
+    name: SupportedPackageManager;
+    /**
+     * either a concrete semver (e.g. "11.1.1") or a range (e.g. "^11.0.0").
+     * `concrete` distinguishes — corepack only accepts concrete versions.
+     */
+    version: string;
+    concrete: boolean;
+    /** which package.json field this came from */
+    source: "devEngines" | "packageManager";
+}
+/**
+ * resolve the project's intended package manager from package.json. precedence
+ * matches pnpm 11+: `devEngines.packageManager` wins over `packageManager`.
+ * when both are present, a concrete `packageManager` that satisfies a
+ * `devEngines` range is preferred (we can pin it via corepack); otherwise
+ * we warn on disagreement and stick with `devEngines`.
+ */
+export declare function resolvePackageManagerSpec(cwd: string): Promise<PackageManagerSpec | null>;
+/**
+ * ensure the requested package manager is on PATH at the declared version,
+ * provisioning via corepack when applicable. returns true if PATH now
+ * resolves to that version, false if we couldn't pin it (in which case
+ * the caller should treat PATH as untrusted and may fall back to its
+ * legacy install path).
+ *
+ * never throws: network failure, missing corepack, range-only versions —
+ * all degrade to "log warning, return false". the existing PATH binary
+ * still works; we just don't get our version guarantee.
+ */
+export declare function ensurePackageManager(spec: PackageManagerSpec): Promise<boolean>;

package/dist/utils/providerErrors.d.ts

@@ -1,3 +1,5 @@
+/** Stable label for the BYOK provider-billing-exhausted classification. */
+export declare const PROVIDER_BILLING_EXHAUSTED_LABEL = "provider billing exhausted";
 /**
  * Result of a provider-error scan: the classification label plus a
  * human-readable excerpt centered on the matched line. The excerpt is what
@@ -11,3 +13,19 @@ export type ProviderErrorMatch = {
 export declare function findProviderErrorMatch(text: string): ProviderErrorMatch | null;
 export declare function detectProviderError(text: string): string | null;
 export declare function isRouterKeylimitExhaustedError(text: string): boolean;
+/**
+ * BYOK billing-exhausted: provider rejected the request because the user's
+ * provider wallet is empty (DeepSeek "Insufficient Balance", Anthropic
+ * "credit balance is too low", OpenCode Zen `CreditsError` /
+ * `FreeUsageLimitError`, Gemini "spending cap"). Distinct from
+ * `isRouterKeylimitExhaustedError` — that's Pullfrog's Router wallet, this
+ * is the user's own provider account.
+ */
+export declare function isProviderBillingExhausted(text: string): boolean;
+/**
+ * Extract `providerID=foo` from agent error logs (OpenCode emits this on
+ * `provider error detected (...)` lines). Returns the lowercase provider
+ * slug, or null when absent. Used to render a provider-specific dashboard
+ * link in the BYOK billing-exhausted summary.
+ */
+export declare function extractProviderId(text: string): string | null;

package/dist/utils/runErrorRenderer.d.ts

@@ -3,22 +3,37 @@
  * pair of user-facing markdown bodies — one for the GitHub Actions job
  * summary tab, one for the PR progress comment.
  *
- * Four classifications, in priority order:
+ * Classifications, in dispatch order (first match wins; the api-key
+ * branch additionally folds in the activity-timeout hang body as a
+ * sub-source so a hang masking an api-key error still surfaces the api-key
+ * CTA):
  *
  *   1. `BillingError` — either the proxy-token mint already threw one (402
  *      handled inline) or the agent runtime surfaced an OpenRouter
  *      "key budget exhausted" string mid-run. Both render via
  *      `formatBillingErrorSummary` so the user sees actionable copy.
  *
- *   2. Activity-timeout hang — `errorMessage` starts with
- *      `"activity timeout"` or `"agent still pending"`. The harness keeps
- *      structured diagnostic state on `toolState.agentDiagnostic`;
- *      `formatAgentHangBody` renders that as a markdown block.
+ *   2. BYOK provider billing-exhausted (#835) — DeepSeek "Insufficient
+ *      Balance", Anthropic "credit balance is too low", OpenCode Zen
+ *      `CreditsError`, Gemini "spending cap". Checked before api-key auth
+ *      because billing-exhausted responses often carry 401 status codes
+ *      that `isApiKeyAuthError` would otherwise mis-classify.
  *
- *   3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string;
- *      `formatApiKeyErrorSummary` renders provider + console-link copy.
+ *   3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string
+ *      (or the activity-timeout hang body when present, since that's where
+ *      the underlying provider error often lands); `formatApiKeyErrorSummary`
+ *      renders provider + console-link copy.
  *
- *   4. Default — a generic `❌ Pullfrog failed` block with the raw error
+ *   4. ProviderModelNotFoundError — stale free-fallback model id no longer
+ *      in the OpenCode catalog; renders a nudge to add a BYOK key.
+ *
+ *   5. Activity-timeout hang — `errorMessage` starts with
+ *      `"activity timeout"` or `"agent still pending"` AND none of the
+ *      above matched. The harness keeps structured diagnostic state on
+ *      `toolState.agentDiagnostic`; `formatAgentHangBody` renders that as
+ *      a markdown block.
+ *
+ *   6. Default — a generic `❌ Pullfrog failed` block with the raw error
  *      message in a fenced code block. Same body for both surfaces.
  *
  * The hang body and the API-key body diverge between the two surfaces only

package/dist/utils/runLifecycle.d.ts

@@ -71,6 +71,13 @@ export declare function finalizeSuccessRun(input: {
  *
  * `lastProgressBody` and the usage table are appended to the summary so the
  * partial work the agent did before failing isn't lost.
+ *
+ * `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
+ * triggers (IncrementalReview / pull_request_synchronize / auto-label) that
+ * throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
+ * mid-billing-exhausted-retry) reach this catch path with no progress
+ * comment to update, and without `createIfMissing` the terminal error
+ * lands only in the GH job summary that most users never open. see #835.
  */
 export declare function writeRunErrorOutputs(input: {
     rendered: RenderedRunError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",
@@ -31,6 +31,7 @@
     "@ark/util": "0.56.0",
     "@clack/prompts": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@opencode-ai/sdk": "1.2.27",
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.0",
     "@octokit/webhooks-types": "^7.6.1",