pullfrog 0.1.29 → 0.1.31

package/dist/mcp/resolveRepoCtx.d.ts

@@ -0,0 +1,34 @@
+import { type RepoAccess } from "../toolState.ts";
+import { type OctokitWithPlugins } from "../utils/github.ts";
+import type { ToolContext } from "./server.ts";
+/**
+ * per-repo execution context for a single tool call. resolved from the
+ * optional `repo` param (a bare repo name — owner-implicit, same account as
+ * the primary). carries the correct token tier + working directory so a tool
+ * can talk to GitHub and run git against the right checkout.
+ */
+export interface RepoCtx {
+    owner: string;
+    name: string;
+    /** working tree: primary = process.cwd(); secondary = ctx.tmpdir/xrepo/<name> */
+    dir: string;
+    access: RepoAccess;
+    /** octokit scoped to the repo's tier (write tokens for primary/write, read token for read) */
+    octokit: OctokitWithPlugins;
+    /** git token scoped to the repo's tier */
+    gitToken: string;
+    /** re-mint this tier's git token on an auth-class push failure (push retries) */
+    refreshGitToken: ((stale: string) => Promise<string>) | undefined;
+}
+/**
+ * resolve the execution context for a `repo`-scoped tool call.
+ *
+ * - omitted / primary name → the primary ctx (unchanged single-repo path).
+ * - a `write`-tier secondary → the same write-scoped tokens as the primary
+ *   (mcpToken + gitToken are minted over the write set ∪ primary).
+ * - a `read`-tier secondary → the contents:read token (clone-for-reference).
+ *
+ * throws when `repo` isn't a registered checkout — secondaries must be cloned
+ * via `checkout_repo` first, which is what populates `toolState.repos`.
+ */
+export declare function resolveRepoCtx(ctx: ToolContext, repo?: string | undefined): RepoCtx;

package/dist/mcp/review.d.ts

@@ -1,5 +1,5 @@
 import type { RestEndpointMethodTypes } from "@octokit/rest";
-import type { CommentableLines } from "../toolState.ts";
+import { type CommentableLines } from "../toolState.ts";
 import type { ToolContext } from "./server.ts";
 export type { CommentableLines };
 /**
@@ -69,7 +69,7 @@ export type DuplicateReviewDecision = {
  * adds noise to the PR.
  *
  * legitimate follow-up reviews after new commits ARE allowed: the
- * new-commits-mid-review path advances toolState.checkoutSha past the
+ * new-commits-mid-review path advances the primary repo state's checkoutSha past the
  * previously reviewed sha, and a subsequent checkout_pr advances it again.
  * any call where checkoutSha has moved past the prior reviewedSha is a real
  * follow-up and goes through. anything else — same sha, or no checkoutSha
@@ -103,6 +103,7 @@ export declare function duplicateReviewDecision(params: {
  */
 export declare function reviewSkipDecision(params: {
     approved: boolean;
+    requestChanges?: boolean;
     body: string | null | undefined;
     hasComments: boolean;
     prApproveEnabled: boolean;
@@ -112,6 +113,7 @@ export declare const CreatePullRequestReview: import("arktype/internal/variants/
     pull_number: number;
     body?: string;
     approved?: boolean;
+    request_changes?: boolean;
     commit_id?: string;
     comments?: {
         path: string;
@@ -126,6 +128,7 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
     pull_number: number;
     body?: string;
     approved?: boolean;
+    request_changes?: boolean;
     commit_id?: string;
     comments?: {
         path: string;
@@ -139,6 +142,7 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
     pull_number: number;
     body?: string;
     approved?: boolean;
+    request_changes?: boolean;
     commit_id?: string;
     comments?: {
         path: string;
@@ -148,7 +152,9 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
         suggestion?: string;
         start_line?: number;
     }[];
-}>>;
+}>> & {
+    mutates?: boolean;
+};
 /**
  * clear a pending review draft stranded on the PR by a prior hard-killed run
  * (workflow timeout, OOM) so the next createReview can succeed.

package/dist/mcp/reviewComments.d.ts

@@ -147,7 +147,9 @@ export declare function GetReviewCommentsTool(ctx: ToolContext): import("fastmcp
 }, {
     pull_number: number;
     review_id: number;
-}>>;
+}>> & {
+    mutates?: boolean;
+};
 export declare const ListPullRequestReviews: import("arktype/internal/variants/object.ts").ObjectType<{
     pull_number: number;
 }, {}>;
@@ -155,7 +157,9 @@ export declare function ListPullRequestReviewsTool(ctx: ToolContext): import("fa
     pull_number: number;
 }, {
     pull_number: number;
-}>>;
+}>> & {
+    mutates?: boolean;
+};
 export declare const ResolveReviewThread: import("arktype/internal/variants/object.ts").ObjectType<{
     thread_id: string;
 }, {}>;
@@ -163,5 +167,7 @@ export declare function ResolveReviewThreadTool(ctx: ToolContext): import("fastm
     thread_id: string;
 }, {
     thread_id: string;
-}>>;
+}>> & {
+    mutates?: boolean;
+};
 export {};

package/dist/mcp/selectMode.d.ts

@@ -15,4 +15,6 @@ export declare function SelectModeTool(ctx: ToolContext): import("fastmcp").Tool
 }, {
     mode: string;
     issue_number?: number;
-}>>;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/server.d.ts

@@ -1,11 +1,12 @@
 import "./arkConfig.ts";
-import { type AgentId } from "../external.ts";
+import { type AgentId, type XrepoConfig } from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { ToolState } from "../toolState.ts";
 import type { OctokitWithPlugins } from "../utils/github.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
 import type { AccountPlan } from "../utils/runContext.ts";
 import type { RunContextData } from "../utils/runContextData.ts";
+import { type PullfrogTool } from "./shared.ts";
 export interface ToolContext {
     agentId: AgentId;
     repo: RunContextData["repo"];
@@ -13,11 +14,15 @@ export interface ToolContext {
     octokit: OctokitWithPlugins;
     githubInstallationToken: string;
     gitToken: string;
+    refreshGitToken: ((stale: string) => Promise<string>) | undefined;
+    readToken: string | undefined;
+    xrepo: XrepoConfig | undefined;
     apiToken: string;
     modes: Mode[];
     postCheckoutScript: string | null;
     prepushScript: string | null;
     prApproveEnabled: boolean;
+    signedCommits: boolean;
     modeInstructions: Record<string, string>;
     toolState: ToolState;
     runId: number | undefined;
@@ -29,6 +34,7 @@ export interface ToolContext {
     resolvedModel: string | undefined;
 }
 type JsonSchema = Record<string, unknown>;
+export declare function buildOrchestratorTools(ctx: ToolContext, outputSchema?: JsonSchema): PullfrogTool[];
 type McpHttpServerOptions = {
     outputSchema?: JsonSchema | undefined;
 };

package/dist/mcp/shared.d.ts

@@ -1,7 +1,24 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { FastMCP, Tool } from "fastmcp";
 import type { ToolContext } from "./server.ts";
-export declare const tool: <const params>(toolDef: Tool<any, StandardSchemaV1<params>>) => Tool<any, StandardSchemaV1<params>>;
+/** extract the HTTP status from an unknown thrown value (octokit RequestError etc.), or undefined. */
+export declare function getHttpStatus(err: unknown): number | undefined;
+/**
+ * a Pullfrog MCP tool definition. `mutates` marks a named state-changing tool
+ * that must be reserved for the orchestrator and denied to subagents — it is
+ * the single source of truth the subagent deny list derives from (see
+ * action/agents/subagentToolGates.ts). general-purpose execution tools (`git`,
+ * `shell`) are deliberately left unmarked: they can mutate but are allowed for
+ * subagents and gated by command-arg validation instead.
+ */
+export type PullfrogTool = Tool<any, any> & {
+    mutates?: boolean;
+};
+export declare const tool: <const params>(toolDef: Tool<any, StandardSchemaV1<params>> & {
+    mutates?: boolean;
+}) => Tool<any, StandardSchemaV1<params>> & {
+    mutates?: boolean;
+};
 export interface ToolResult {
     content: {
         type: "text";

package/dist/mcp/shell.d.ts

@@ -26,7 +26,9 @@ export declare function ShellTool(ctx: ToolContext): import("fastmcp").Tool<any,
     timeout?: number;
     working_directory?: string;
     background?: boolean;
-}>>;
+}>> & {
+    mutates?: boolean;
+};
 export declare const KillBackgroundParams: import("arktype/internal/variants/object.ts").ObjectType<{
     handle: string;
 }, {}>;
@@ -34,4 +36,6 @@ export declare function KillBackgroundTool(ctx: ToolContext): import("fastmcp").
     handle: string;
 }, {
     handle: string;
-}>>;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/upload.d.ts

@@ -3,4 +3,6 @@ export declare function UploadFileTool(ctx: ToolContext): import("fastmcp").Tool
     path: string;
 }, {
     path: string;
-}>>;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/xrepo.d.ts

@@ -0,0 +1,15 @@
+import type { ToolContext } from "./server.ts";
+export declare const ListRepos: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function ListReposTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>> & {
+    mutates?: boolean;
+};
+export declare const CheckoutRepo: import("arktype/internal/variants/object.ts").ObjectType<{
+    repo: string;
+}, {}>;
+export declare function CheckoutRepoTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    repo: string;
+}, {
+    repo: string;
+}>> & {
+    mutates?: boolean;
+};

package/dist/models.d.ts

@@ -36,7 +36,11 @@ export interface ModelAlias {
     preferred: boolean;
     /** whether this alias is free and requires no API key */
     isFree: boolean;
-    /** slug of a replacement model — presence implies this model is deprecated */
+    /** slug of a replacement model to resolve through. presence means this alias
+     * never runs as-is — resolution redirects to the replacement and it's hidden
+     * from pickers. covers permanent deprecation AND riding out a temporarily
+     * unavailable model: point it at a cheaper tier (downgrade) or a working
+     * sibling/higher tier (upgrade), then clear it when the model returns. */
     fallback: string | undefined;
     /** dynamic-resolution discriminant — see ModelRouting docs */
     routing: ModelRouting | undefined;
@@ -57,7 +61,9 @@ interface ModelDef {
     preferred?: boolean;
     envVars?: readonly string[];
     isFree?: boolean;
-    /** slug of a replacement model — presence implies this model is deprecated */
+    /** slug of a replacement model to resolve through — permanent deprecation or
+     * temporary unavailability (downgrade/upgrade until the model returns). see
+     * ModelAlias.fallback. */
     fallback?: string;
     /** dynamic-resolution discriminant — see ModelRouting docs */
     routing?: ModelRouting;
@@ -104,9 +110,53 @@ export declare function getModelEnvVars(slug: string): string[];
  * see `provider.managedCredentials` and wiki/codex-auth.md. */
 export declare function getModelManagedCredentials(slug: string): string[];
 export declare const modelAliases: ModelAlias[];
-export declare const DEFAULT_PROXY_MODEL: string;
-/** short label for the model auto-select picks today (console hint copy). */
-export declare function getAutoSelectHintModel(): string;
+/**
+ * `repo.model` sentinels for the two managed auto tiers. stored verbatim in
+ * the DB (they pass the `provider/model` shape check) and resolved to a
+ * concrete alias by `resolveDisplayAlias` below, so every downstream consumer
+ * (CLI resolve, OpenRouter resolve, footer label) handles them transparently.
+ *
+ * `efficient` mirrors the OSS/default subsidy model (Kimi K2 — fast + cheap);
+ * `intelligent` is the frontier pick (Claude Opus). a `null` model means the
+ * tier hasn't been pinned: callers default by card status via `defaultAutoTier`.
+ */
+export declare const AUTO_EFFICIENT = "auto/efficient";
+export declare const AUTO_INTELLIGENT = "auto/intelligent";
+export type AutoTier = typeof AUTO_EFFICIENT | typeof AUTO_INTELLIGENT;
+export declare function isAutoTier(slug: string | null | undefined): slug is AutoTier;
+/**
+ * the tier to default to when the user hasn't pinned one. card on file →
+ * intelligent (they've signalled willingness to pay for frontier reviews);
+ * otherwise → efficient (safe, cheap). server (`run-context`) and the console
+ * picker both call this so the displayed default and the runtime default agree.
+ */
+export declare function defaultAutoTier(hasCard: boolean): AutoTier;
+/**
+ * the auto tier that actually runs for an account, enforcing the card gate:
+ * the intelligent tier (Opus) requires a card on file, so a no-card account is
+ * always clamped to efficient (Kimi) — whether intelligent was the card-based
+ * default or an explicit pick made while a card was once present. keeps a trial
+ * balance from being torched on a premium model before the user has a card.
+ * `model` may be null, an `auto/*` sentinel, or a concrete pick being
+ * clamped — callers route concrete picks here only when `!hasCard` (carded
+ * concrete picks resolve directly), so a concrete `model` always lands on the
+ * efficient tier via the no-card early return.
+ */
+export declare function resolveAutoTier(params: {
+    model: string | null;
+    hasCard: boolean;
+}): AutoTier;
+/**
+ * Router-resolvable — the set a card on file unlocks. custom (non-Auto) picks
+ * are card-gated wholesale on the Router: the console locks the Custom tab
+ * without a card and the server clamps any stored pick to the efficient tier.
+ * a pick with no openRouterResolve (a model OpenRouter doesn't serve yet)
+ * lands on the efficient default with or without a card, so "add a card to
+ * run this model" messaging would be false for it — hence the predicate.
+ * resolveOpenRouterModel walks display aliases, so auto sentinels and
+ * deprecated slugs are judged by the model that actually runs.
+ */
+export declare function isCardGatedModel(slug: string): boolean;
 /** resolve a model slug to its concrete models.dev specifier (e.g. "anthropic/claude-opus-4-6") */
 export declare function resolveModelSlug(slug: string): string | undefined;
 /**
@@ -132,6 +182,9 @@ export declare function resolveCliModel(slug: string): string | undefined;
  * (e.g. free opencode models).
  */
 export declare function resolveOpenRouterModel(slug: string): string | undefined;
+export declare const DEFAULT_PROXY_MODEL: string;
+/** short label for the model auto-select picks today (console hint copy). */
+export declare function getAutoSelectHintModel(): string;
 /** env var that supplies the Bedrock model ID for the `bedrock/byok` slug. */
 export declare const BEDROCK_MODEL_ID_ENV = "BEDROCK_MODEL_ID";
 /** env var that supplies the Vertex AI model ID for the `vertex/byok` slug. */

package/dist/modes.d.ts

@@ -5,7 +5,7 @@ export interface Mode {
     prompt?: string | undefined;
 }
 export declare const PR_SUMMARY_FORMAT = "### Default format\n\nThe body has at most three parts in this exact order:\n\n1. **Reviewed changes preamble** \u2014 one bolded inline lead-in describing what was reviewed in this run, a bullet list of the substantive changes, and an HTML comment carrying review metadata for downstream agents.\n2. **Cross-cutting issue sections** (zero or more) \u2014 one `### ` heading per concern, with a human-readable problem write-up and a collapsed `<details>Technical details</details>` block underneath.\n3. **`### \u2139\uFE0F Nitpicks`** at the very bottom (only if there are nits worth surfacing in the body) \u2014 a flat bullet list, no technical-details block.\n\nInline-vs-body split: concerns that anchor to a specific line go inline (use the `comments` parameter). Body `### ` sections are reserved for concerns that **have no line to anchor to** \u2014 typically because the concern is about *absence* (something the diff should have done but didn't), *sequencing* (rollout / deletion / migration order), *design decisions only the human can make*, or *scope questions the diff implicitly raises but doesn't address*. A concern that anchors to a line but has broad implications still goes inline (use the technical-details block there to capture the implications \u2014 see Inline technical details below). If you found no non-anchorable concerns, the body has zero `### ` issue sections \u2014 just the preamble + metadata.\n\n## 1. Reviewed changes preamble\n\nOpen with a single bolded inline lead-in followed immediately by the bullet list (no `### Key changes` heading, no `<b>TL;DR</b>`):\n\n```\n**Reviewed changes** \u2014 one sentence on what was reviewed in this run. For Review (initial), this is what the PR does and why. For IncrementalReview, this is what changed since the prior pullfrog review. Focus on intent, not mechanics.\n\n- **Short human-readable title** \u2014 1 sentence per substantive change. Write a short prose phrase; when you name a file, type, or function, put that name in backticks (e.g. **Add \\`TodoTracker\\` for live checklists**). A reviewer should understand the full reviewed scope from this list alone \u2014 this IS the dispassionate \"what was reviewed and what changed\" overview, so cover the substantive changes, not just the loudest ones.\n\n<!--\nPullfrog review metadata \u2014 for any agent (or human-with-agent) reading this\nreview. Incorporate the fields below into your understanding of the context\nthis review was made in. The findings below were written against\n{head_sha_short}; if new commits have landed on {head_ref} since this review\nwas submitted, treat any specific bug, file, or line callout as POTENTIALLY\nSTALE \u2014 re-diff against {head_sha_short} (or trigger a fresh review) and\nfactor commits past {head_sha_short} into your understanding of the current\nstate before acting on findings.\n\n- Mode: Review (initial)   or   IncrementalReview (delta against prior pullfrog review)\n- Files reviewed: {file_count}\n- Commits reviewed: {commit_count}\n- Base: {base_ref} ({base_sha_short})\n- Head: {head_ref} ({head_sha_short})\n- Reviewed commits:\n  - {sha_short} \u2014 {commit_subject}\n  - ...\n- Prior pullfrog review: none   or   {prior_sha_short} ({prior_review_html_url})\n- Submitted at: {iso_timestamp}\n-->\n```\n\nPull every metadata field from the `checkout_pr` tool's response \u2014 file count, commit count, base/head ref + SHA, the commit list. For `IncrementalReview` runs, populate `Prior pullfrog review` with the prior review's commit_id (short SHA) and `html_url` from `list_pull_request_reviews`.\n\n## 2. Cross-cutting issue sections (zero or more)\n\nFor each cross-cutting concern, one `### ` section. Use this exact shape:\n\n```\n### {emoji} {short, descriptive title \u2014 what's wrong, not what to do}\n\n{Human-readable problem write-up. Describes the PROBLEM only \u2014 what's broken, what the symptom is, what the blast radius is. NO asks, NO suggested fixes, NO \"the right thing to do is...\". Asks and fixes live in the technical-details block below; the visible part is for the human to *understand* the problem, not to implement it.}\n\n<details><summary>Technical details</summary>\n\n\\`\\`\\`\\`markdown\n# {title repeated}\n\n## Affected sites\n- {file path:line} \u2014 {what's wrong there}\n- ...\n\n## Required outcome\n- {what the fix needs to achieve, not how to achieve it}\n- ...\n\n## Suggested approach (optional)\n{When the fix shape is non-obvious, sketch one or more reasonable directions. Skip when the outcome alone makes the fix obvious.}\n\n## Open questions for the human (optional)\n- {Any decision an implementing agent shouldn't make unilaterally \u2014 pricing thresholds, breaking-change policy, naming, scope of follow-up.}\n\\`\\`\\`\\`\n\n</details>\n```\n\nConcrete example of the visible part of a non-anchored section (technical-details block unchanged from the template above):\n\n```\n### \u2139\uFE0F Legacy `opencode.ts` has no documented deletion plan\n\nThe v2 harness lands alongside the v1 file and imports one helper from it. Worth a follow-up issue or a TODO so the next maintainer doesn't have to re-derive the cleanup plan.\n```\n\nThe example's value is its *shape*: a finding about absence (no deletion plan), not a line-anchored bug. Body sections live or die on whether the concern genuinely doesn't fit on a line.\n\n**Heading severity emoji** \u2014 every `### ` heading carries one:\n\n- \uD83D\uDEA8 critical \u2014 blocks merge (data loss, security, broken core flow)\n- \u26A0\uFE0F important \u2014 must address before merging (regression, missing validation, incorrect behavior)\n- \u2139\uFE0F informational \u2014 surfaced for awareness; mergeable as-is\n\n**Visible problem write-up rules:**\n\n- **No asks, no suggested fixes** in the visible part. The visible portion describes the problem; the technical-details block describes the fix shape and any open questions. The exception: a fix so self-evident that NOT stating it would be weird (e.g. \"the typo is missing an 'r'\") \u2014 in that case, fold it into the problem statement and skip the suggested-approach block in technical details too.\n- **Never two successive plain paragraphs.** Every transition between block-level elements must alternate prose with structure: paragraph \u2192 bullet list \u2192 paragraph; paragraph \u2192 code fence \u2192 bullet list; paragraph \u2192 table \u2192 paragraph. Two consecutive paragraphs in a row create a wall of text that's impossible to digest. If you catch yourself writing one, find a way to split it: pull a list out of it, drop a 2-3 line code fence between them, or merge them into a single tighter paragraph.\n- **Per-paragraph budget:** ~3 sentences max. Past that, you're explaining where you should be structuring.\n- **Identifier discipline still applies** in the visible part. Lead with behavior in plain English; name an identifier only when it's the subject of the concern or a public surface a reader would recognize. The technical-details block is where dense identifier references belong.\n\n**Technical-details block rules:**\n\n- Wrapped in a 4-backtick markdown fence (`\\`\\`\\`\\`markdown ... \\`\\`\\`\\``) so it's visually distinct, one-click copyable, and can contain its own 3-backtick code fences without escape gymnastics. The contents are agent-readable \u2014 a fix-agent will pull the body down and use this block as the brief.\n- File paths and `file:line` refs are encouraged (and necessary) \u2014 the next agent uses these to navigate. Identifier density is fine here.\n- Slightly more verbose than the absolute minimum is OK when it materially helps the next agent: a small code snippet showing the symptom, a short table of mismatched key/column pairs, a one-paragraph \"why CI doesn't catch it\" note. Skip massive regression-test scaffolding or full route rewrites \u2014 the implementing agent writes those.\n- Use the four standard sections (`Affected sites`, `Required outcome`, optional `Suggested approach`, optional `Open questions for the human`). Skip the optional sections when they wouldn't add anything.\n\n## Inline technical details\n\nInline comments are short (~2-3 sentences) by default. When an inline finding has broader implications worth recording for a fix-agent \u2014 e.g. a localized bug whose proper fix requires touching several files, or where the right fix depends on a design decision the human needs to make \u2014 append a collapsed `<details><summary>Technical details</summary>` block to the inline comment's body. Same shape as the body-section technical-details block (4-backtick fenced markdown, `## Affected sites` / `## Required outcome` / optional `## Suggested approach` / optional `## Open questions for the human`).\n\nGitHub renders the same markdown parser in inline comments as in the review body, so the collapsed-details affordance works the same way. The visible part of the inline comment stays scannable; the depth is one click away for any agent that needs it.\n\n## 3. `### \u2139\uFE0F Nitpicks` (optional, last section)\n\nOnly when there are nits that for some reason can't be inlined. Filepaths in nit text are fine \u2014 these are simple enough that a human or agent reads once and acts. No technical-details block.\n\n```\n### \u2139\uFE0F Nitpicks\n\n- {nit, with file path inline if useful, \u2264 ~200 chars}\n- ...\n```\n\n## Inline comment shape\n\nInline comments use the same severity framing as body `### ` sections, scaled down for line-anchored use:\n\n- **Lead with a 1-2 sentence problem statement.** The reader is looking at the line in question, so don't restate what the line says \u2014 describe what's wrong with it. Optionally prefix the visible line with a severity emoji (\uD83D\uDEA8 / \u26A0\uFE0F / \u2139\uFE0F) when severity isn't obvious from context.\n- **Optional `<details><summary>Technical details</summary>...</details>` collapsible** for findings whose technical context (longer file:line references, related-code snippets, suggested approach, regression-risk notes) would overwhelm the human-readable lead-in. Same agent-readable purpose, same 4-backtick fence shape, and same 4-section structure as the body's technical-details block \u2014 see *Inline technical details* above. Encouraged whenever the depth helps a downstream fix-agent; don't force one when the inline lead-in already says everything.\n- **Visible portion \u2264 2-3 sentences.** If you find yourself writing more, that's the cue to split the depth into the `Technical details` collapsible.\n\n## Body-wide rules\n\n- **Inline-vs-body discipline (repeated for emphasis):** anything that anchors to a specific line goes inline (with a `<details>Technical details</details>` block when the implications are broad). The body is for non-anchorable concerns only \u2014 absence, sequencing, design decisions, scope questions, architectural risk.\n- **No `### Issues found` heading** above the issue sections \u2014 each `### ` heading IS the issue.\n- **Severity emoji on every `### ` heading** (\uD83D\uDEA8 / \u26A0\uFE0F / \u2139\uFE0F). No emoji on the preamble lead-in or anywhere else.\n- **GitHub block-level rendering**: GitHub's markdown parser requires a blank line between ALL block-level elements (HTML tags like `<br/>`, `<sub>`, `<details>`, `<b>` and markdown syntax like headings, lists, blockquotes, code fences, paragraphs). Without a blank line, GitHub treats following content as a continuation of the HTML block and renders markdown syntax as literal text. ALWAYS separate block-level elements with a blank line.\n- **Backtick-wrap** every variable, identifier, or file name when you mention one (in either visible or technical-details portions).\n- **Don't repeat diff content**, don't include raw `+123 / -45` stats, don't include a changelog section, don't use horizontal rules (`---`).\n- **Pull file/commit counts from `checkout_pr` metadata** \u2014 never count manually.\n- **Legacy headings REMOVED.** Do not use `### Key changes`, `### Issues found`, `<b>TL;DR</b>`, or `<sub><b>Summary</b>`. The new structure subsumes them.";
-export declare function computeModes(agentId: AgentId): Mode[];
+export declare function computeModes(agentId: AgentId, signedCommits?: boolean): Mode[];
 export declare const modes: Mode[];
 /**
  * modes that legitimately never modify the working tree. used by the post-run

package/dist/toolState.d.ts

@@ -32,6 +32,40 @@ export type CommentableLines = {
     RIGHT: Set<number>;
     LEFT: Set<number>;
 };
+/** access tier of a checked-out repo, drives token routing + push gating. */
+export type RepoAccess = "primary" | "write" | "read";
+/**
+ * per-repo working-tree + PR state. the primary repo is keyed like any other
+ * in `toolState.repos`; secondaries are added by `checkout_repo`. this is the
+ * single source of truth for all repo-scoped git/PR state — there are no
+ * parallel inline fields on `ToolState`. read via `primaryRepoState(toolState)`
+ * for primary-only call sites, or `requireRepoState(toolState, owner, name)`
+ * when a `repo` param routes to a specific checkout.
+ */
+export interface RepoToolState {
+    owner: string;
+    name: string;
+    /** working directory: primary = `process.cwd()`; secondary = `ctx.tmpdir/xrepo/<name>` */
+    dir: string;
+    access: RepoAccess;
+    defaultBranch?: string;
+    pushUrl?: string;
+    pushDest?: StoredPushDest;
+    initialHead?: {
+        kind: "branch";
+        name: string;
+    } | {
+        kind: "detached";
+        sha: string;
+    };
+    issueNumber?: number;
+    checkoutSha?: string;
+    commentableLinesByFile?: Map<string, CommentableLines>;
+    commentableLinesPullNumber?: number;
+    commentableLinesCheckoutSha?: string | undefined;
+    beforeSha?: string;
+    diffCoverage?: DiffCoverageState | undefined;
+}
 /**
  * mutable per-run record of facts that occurred during execution. shared
  * between the action process and the MCP server (one process — toolState is
@@ -55,21 +89,8 @@ export type CommentableLines = {
  * MCP tool already records.
  */
 export interface ToolState {
-    pushUrl?: string;
-    pushDest?: StoredPushDest;
-    initialHead?: {
-        kind: "branch";
-        name: string;
-    } | {
-        kind: "detached";
-        sha: string;
-    };
-    issueNumber?: number;
-    checkoutSha?: string;
-    commentableLinesByFile?: Map<string, CommentableLines>;
-    commentableLinesPullNumber?: number;
-    commentableLinesCheckoutSha?: string | undefined;
-    beforeSha?: string;
+    repos: Map<string, RepoToolState>;
+    primaryRepoKey: string;
     selectedMode?: string;
     prepushFailureCount: number;
     backgroundProcesses: Map<string, BackgroundProcess>;
@@ -94,6 +115,7 @@ export interface ToolState {
     lastProgressBody?: string;
     wasUpdated?: boolean;
     finalSummaryWritten?: boolean;
+    answerCommentPosted?: boolean;
     existingPlanCommentId?: number;
     previousPlanBody?: string;
     summaryFilePath?: string;
@@ -102,15 +124,23 @@ export interface ToolState {
     learningsFilePath?: string;
     learningsSeed?: string;
     learningsPersistAttempted?: boolean;
+    xrepoLearningsFilePath?: string;
+    xrepoLearningsSeed?: string;
+    xrepoLearningsPersistAttempted?: boolean;
     output?: string | undefined;
     usageEntries: AgentUsage[];
     model?: string | undefined;
     modelFallback?: {
         from: string;
     } | undefined;
+    unselectedProxyDefault?: boolean | undefined;
+    modelClamped?: {
+        from: string;
+        reason: "card" | "noRouterPath";
+    } | undefined;
+    shaPinned?: boolean | undefined;
     oss?: boolean | undefined;
     todoTracker?: TodoTracker | undefined;
-    diffCoverage?: DiffCoverageState | undefined;
     agentDiagnostic?: AgentDiagnostic | undefined;
 }
 interface InitToolStateParams {
@@ -118,6 +148,26 @@ interface InitToolStateParams {
         id: string;
         type: ProgressCommentType;
     } | undefined;
+    owner: string;
+    name: string;
+    dir: string;
 }
 export declare function initToolState(params: InitToolStateParams): ToolState;
+/** stable "owner/name" key for the `repos` map. lowercased — GitHub repo names are case-insensitive. */
+export declare function repoKey(owner: string, name: string): string;
+/** the primary (triggering) repo's state. throws if init hasn't run. */
+export declare function primaryRepoState(toolState: ToolState): RepoToolState;
+/**
+ * state for a specific checked-out repo. throws when the repo isn't a
+ * registered checkout — keeps the push/PR allow-set honest (the only way a
+ * secondary becomes registered is via `checkout_repo`).
+ */
+export declare function requireRepoState(toolState: ToolState, owner: string, name: string): RepoToolState;
+/** get-or-create a repo's state (used by checkout_repo when registering a secondary). */
+export declare function ensureRepoState(toolState: ToolState, init: {
+    owner: string;
+    name: string;
+    dir: string;
+    access: RepoAccess;
+}): RepoToolState;
 export {};

package/dist/utils/apiCommit.d.ts

@@ -0,0 +1,40 @@
+/** one working-tree change to include in an API commit. */
+export type ChangedFile = {
+    path: string;
+    deleted: boolean;
+};
+/**
+ * all working-tree changes vs HEAD: tracked changes (committed-to-index,
+ * staged, and unstaged all collapse into `git diff HEAD`) plus untracked
+ * files from `git status`. respects .gitignore. throws on unresolved
+ * conflicts — the caller's guidance is to resolve and `git add` first.
+ */
+export declare function detectWorkingTreeChanges(): ChangedFile[];
+/**
+ * refuse content the API path cannot faithfully commit: git-lfs files (the
+ * pointer would be committed without the lfs object upload that the git
+ * pre-push hook performs) and directories (nested repositories / submodule
+ * pointers). other clean filters are fine — blob content goes through
+ * `git hash-object`, which applies them exactly like a local commit.
+ */
+export declare function assertApiCommittable(files: ChangedFile[]): Promise<void>;
+/**
+ * create one GitHub-signed commit on `remoteBranch` containing `files` read
+ * from the working tree, parented on `parents` (first parent supplies the
+ * base tree; a second parent — MERGE_HEAD — makes it a true merge commit so
+ * base-branch integration doesn't pollute the PR diff). empty `files` with
+ * two parents concludes a merge that resolved to the first parent's tree.
+ * creates the remote branch at the new commit when it doesn't exist yet.
+ */
+export declare function createSignedCommit(params: {
+    token: string;
+    owner: string;
+    repo: string;
+    remoteBranch: string;
+    message: string;
+    parents: string[];
+    files: ChangedFile[];
+}): Promise<{
+    sha: string;
+    createdBranch: boolean;
+}>;

package/dist/utils/apiKeys.d.ts

@@ -27,8 +27,27 @@ export declare function validateAgentApiKey(params: {
  *     {"type":"error","error":{"type":"authentication_error", ...
  *     "Invalid bearer token"}}`) emitted by the Claude CLI for revoked /
  *     mistyped / rotated `ANTHROPIC_API_KEY`. see #782.
+ *   - expired credentials (#931): Bedrock 403 `Failed to authenticate. API
+ *     Error: 403 {"Message":"*** has expired"}` (short-lived bearer tokens),
+ *     OpenAI OAuth "Your authentication token has expired", and Codex
+ *     "Token refresh failed: 401". the Bedrock pattern is anchored to the
+ *     Claude CLI emission ("Failed to authenticate. API Error:") so generic
+ *     auth chatter in agent stderr can't misclassify a hang as a key error.
+ *   - DeepSeek invalid key (#960): `Authentication Fails, Your api key:
+ *     ****XXXX is invalid`. anchored to "Your api key: ... is invalid" so it
+ *     can't collide with DeepSeek's already-handled `Insufficient balance`
+ *     billing shape (which routes to formatProviderBillingExhausted).
  */
 export declare function isApiKeyAuthError(text: string): boolean;
+/**
+ * Expired OAuth-connection credential shapes (#931) — the fix is to
+ * re-authenticate the provider connection (`pullfrog auth <provider>`), not
+ * to rotate a repo-secret API key, so `formatApiKeyErrorSummary` renders
+ * distinct copy for these. Patterns are deliberately narrow:
+ * "authentication token has expired" (not bare "token has expired") so a
+ * GitHub installation-token expiry can't be misread as an LLM key problem.
+ */
+export declare function isOAuthCredentialExpiredError(text: string): boolean;
 /**
  * Friendly Markdown summary for both the missing-key and invalid-key cases.
  * Used in the catch / result-failure paths in `main.ts` to overwrite the raw

package/dist/utils/buildPullfrogFooter.d.ts

@@ -24,6 +24,33 @@ export interface BuildPullfrogFooterParams {
      * so the substitution is visible in PR comments + reviews.
      */
     fallbackFrom?: string | undefined;
+    /**
+     * When a Router account had a model (or the intelligent tier) selected that
+     * the server clamped to the efficient default — custom picks are card-gated
+     * wholesale. `from` is the configured slug (e.g. "anthropic/claude-opus");
+     * `reason` names the binding constraint — "card" (no card on file) renders
+     * `Using <Kimi K2> (<Claude Opus> needs a card on file)`, "noRouterPath"
+     * (no openRouterResolve yet and no stored provider key) renders a
+     * provider-key nudge — so the downgrade is visible rather than silently
+     * presenting Kimi as the pick.
+     */
+    clamped?: {
+        from: string;
+        reason: "card" | "noRouterPath";
+    } | undefined;
+    /**
+     * true when the run used the default proxy model only because no model was
+     * selected (Router billing + "auto"). the footer appends a note nudging the
+     * user to pick a model — the cost-optimized default is a weaker reviewer
+     * than a frontier model.
+     */
+    unselectedProxyDefault?: boolean | undefined;
+    /**
+     * true when the action is pinned to a full commit SHA — the footer leads
+     * with a maintenance nudge to switch to the moving `@v0` tag (a SHA pin
+     * freezes the post-run cleanup step, which silently fails the workflow).
+     */
+    shaPinned?: boolean | undefined;
     /**
      * true when the run's model costs are covered by the Pullfrog for OSS
      * program — the footer renders `Using <model> (free via Pullfrog for OSS)`

package/dist/utils/claudeSubscription.d.ts

@@ -0,0 +1,30 @@
+export type SubscriptionPreflight = {
+    usable: true;
+} | {
+    usable: false;
+    reason: string;
+};
+/**
+ * preflight a Claude subscription OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`)
+ * with a 1-token Messages call, so the agent can fall back to
+ * `ANTHROPIC_API_KEY` when the subscription is exhausted or revoked instead
+ * of failing the whole run at its first model call. rides the same de-facto
+ * OAuth surface Claude Code itself uses: Bearer auth + the
+ * `claude-code-20250219,oauth-2025-04-20` betas + the identity system prompt.
+ *
+ * probes the run's own model when known — subscription limits can be
+ * per-model ("You've hit your Opus limit"), so a cheaper stand-in could pass
+ * preflight and still leave the run dead on arrival.
+ *
+ * fail-open by design: only 401 (revoked/expired token) and 429
+ * (session/weekly/per-model limit) mark the token unusable. network errors,
+ * 5xx, and request-shape drift (400) all keep today's subscription-first
+ * behavior, so the preflight can never fail a run that would have worked —
+ * the worst wrong answer is a run that bills the API key instead of the
+ * subscription.
+ */
+export declare function preflightClaudeSubscription(params: {
+    token: string;
+    /** bare Anthropic model id the run will use (e.g. "claude-fable-5") */
+    model: string | undefined;
+}): Promise<SubscriptionPreflight>;

package/dist/utils/errorReport.d.ts

@@ -1,4 +1,4 @@
-import type { ToolState } from "../toolState.ts";
+import { type ToolState } from "../toolState.ts";
 interface ReportErrorParams {
     toolState: ToolState;
     error: string;
@@ -6,7 +6,7 @@ interface ReportErrorParams {
     /**
      * When the run has no pre-existing progress comment to update (silent
      * IncrementalReview / pull_request_synchronize, mode-less polls), create
-     * a fresh issue comment on `toolState.issueNumber` instead of returning
+     * a fresh issue comment on the primary repo state's `issueNumber` instead of returning
      * silently. Used for terminal errors (BillingError, TransientError) where
      * the GH job summary is the only other surface and most users never open
      * it. see #775.