pullfrog 0.1.30 → 0.1.32

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 };
 /**
@@ -23,6 +23,41 @@ export declare const TRANSIENT_REVIEW_RETRY_DELAYS_MS: number[];
  */
 export declare function commentableLinesForFile(patch: string | undefined): CommentableLines;
 export declare function buildCommentableMap(ctx: ToolContext, pullNumber: number): Promise<Map<string, CommentableLines>>;
+/**
+ * count unresolved review threads on a PR whose root comment was authored by
+ * Pullfrog's bot. this is the full set of open Pullfrog findings on the PR —
+ * the basis for both the never-approve-with-outstanding-issues invariant (the
+ * approval gate below) and the `pullfrog-approval` status verdict. it is a
+ * function of all open findings, NOT just the latest commit's delta.
+ *
+ * outdated-but-unresolved threads still count — GitHub marks a thread
+ * `[OUTDATED]` when the anchor line moved (reformat, rename, force-push), which
+ * is not the same as the concern being addressed. human-reviewer threads are
+ * excluded: they belong to those reviewers to resolve. walks every page so a
+ * long-lived PR with >100 threads can't hide an outstanding finding.
+ */
+export declare function countOutstandingPullfrogThreads(ctx: ToolContext, pullNumber: number): Promise<number>;
+/**
+ * proactive approve-when-clean for the Fix-all / Fix-👍s flow (`fix_review`
+ * trigger). when such a run completes successfully and every Pullfrog-originated
+ * review thread it raised is resolved, post a NEW approving review summarizing
+ * the run's work.
+ *
+ * the verification step shares `countOutstandingPullfrogThreads` with the
+ * approval gate in create_pull_request_review: that gate REACTIVELY blocks a
+ * bad approval; this is the PROACTIVE approve side. approval is contingent on
+ * Pullfrog's own findings actually being addressed — never a blind post-fix
+ * approval. a Fix-👍s run that only resolved a subset naturally fails the
+ * outstanding-thread check and is left unapproved.
+ *
+ * respects `prApproveEnabled` (the repo's "Allow Pullfrog to approve PRs"
+ * opt-in): a repo that hasn't enabled binding bot approvals never gets one
+ * here. skips when the agent already rendered an explicit review verdict this
+ * run (`toolState.approval`), so an agent that found a real issue and submitted
+ * a non-approving review is never overridden. best-effort — a failure must not
+ * flip the run's outcome.
+ */
+export declare function approveAfterFix(ctx: ToolContext): Promise<void>;
 export type ReviewCommentInput = NonNullable<RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]["comments"]>[number];
 export interface DroppedComment {
     path: string;
@@ -69,7 +104,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 +138,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 +148,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 +163,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 +177,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 +187,14 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
         suggestion?: string;
         start_line?: number;
     }[];
-}>>;
+}>> & {
+    mutates?: boolean;
+};
+type FooterOpts = {
+    body: string;
+    approved: boolean;
+    hasComments: 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.
@@ -190,6 +236,7 @@ export declare function clearStrandedPendingReview(ctx: ToolContext, params: {
  * comments-only) until a body-path run happened to clear the draft.
  */
 export declare function createReviewWithStrandedRecovery(ctx: ToolContext, params: RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]): Promise<Awaited<ReturnType<typeof ctx.octokit.rest.pulls.createReview>>>;
+export declare function createAndSubmitWithFooter(ctx: ToolContext, params: RestEndpointMethodTypes["pulls"]["createReview"]["parameters"], opts: FooterOpts): Promise<Awaited<ReturnType<typeof ctx.octokit.rest.pulls.submitReview>>>;
 /**
  * report the review node ID so the WorkflowRun is marked as "review submitted".
  * exported for use in main.ts post-agent cleanup.

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,6 +14,9 @@ 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;
@@ -30,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/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>;
@@ -79,6 +100,10 @@ export interface ToolState {
         nodeId: string;
         reviewedSha: string | undefined;
     };
+    approval?: {
+        wouldApprove: boolean;
+        sha: string | undefined;
+    };
     reviewReplies?: Map<number, {
         commentId: number;
         url: string | undefined;
@@ -94,6 +119,7 @@ export interface ToolState {
     lastProgressBody?: string;
     wasUpdated?: boolean;
     finalSummaryWritten?: boolean;
+    answerCommentPosted?: boolean;
     existingPlanCommentId?: number;
     previousPlanBody?: string;
     summaryFilePath?: string;
@@ -102,12 +128,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 {
@@ -115,6 +152,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/agent.d.ts

@@ -10,7 +10,9 @@ import type { Agent } from "../agents/index.ts";
  *      Bedrock model, change `BEDROCK_MODEL_ID`, not `PULLFROG_MODEL`.
  *   2. slug from repo config / payload → alias registry. routing slugs
  *      (e.g. `bedrock/byok`) defer to a separate env var (`BEDROCK_MODEL_ID`).
- *   3. undefined — agent will auto-select.
+ *      a non-curated value with a slash passes through unchanged as a raw
+ *      models.dev specifier (same as `PULLFROG_MODEL`), not auto-selected away.
+ *   3. undefined (no slug, or a bare-word non-specifier) — agent auto-selects.
  */
 export declare function resolveModel(ctx: {
     slug?: string | undefined;

package/dist/utils/apiKeys.d.ts

@@ -33,6 +33,10 @@ export declare function validateAgentApiKey(params: {
  *     "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;
 /**

package/dist/utils/buildPullfrogFooter.d.ts

@@ -17,6 +17,40 @@ export interface BuildPullfrogFooterParams {
     customParts?: string[] | undefined;
     /** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
     model?: string | undefined;
+    /**
+     * When the action engaged the BYOK fallback, this is the slug the user
+     * had configured (e.g. "anthropic/claude-opus") — the footer renders
+     * `Using <free model> (credentials for <configured> not configured)`
+     * 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/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.

package/dist/utils/github.d.ts

@@ -40,7 +40,7 @@ type GitHubAppPermissions = {
     workflows?: WriteOnly;
 };
 type AcquireTokenOptions = {
-    repos?: string[];
+    repos?: string[] | undefined;
     permissions?: GitHubAppPermissions;
     /**
      * stashed OIDC credentials for minting after restricted mode deletes

package/dist/utils/instructions.d.ts

@@ -24,6 +24,14 @@ interface InstructionsContext {
      * `describeSetupFailure`), rendered as a SETUP HOOK FAILED banner. empty
      * string when the hook succeeded, was skipped, or wasn't configured. */
     setupHookFailure: string;
+    /** operator-authored cross-repo brief (`Account.xrepoBrief`), rendered in
+     * the CROSS-REPO section on --xrepo runs. null/empty otherwise. */
+    xrepoBrief: string | null;
+    /** absolute path to the seeded cross-repo learnings tmpfile (--xrepo runs
+     * only), or null. */
+    xrepoLearningsFilePath: string | null;
+    /** server-parsed TOC for the cross-repo learnings body. */
+    xrepoLearningsHeadings: LearningsHeading[];
 }
 export interface ResolvedInstructions {
     full: string;

package/dist/utils/isTransientNetworkError.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Predicate for transient network errors that should be retried (vs. fail fast
+ * on explicit HTTP status / validation errors that carry their own message).
+ *
+ * Matches errors from `fetch` (`fetch failed`), TCP-level interruption
+ * (`ECONNRESET`, `ETIMEDOUT`), and `AbortSignal.timeout` (`AbortError`).
+ * Callers may pass `extraPatterns` to whitelist additional transient
+ * substrings on `error.message` (e.g. provider-specific framings).
+ */
+export declare function isTransientNetworkError(error: unknown, extraPatterns?: string[]): boolean;
+/**
+ * broader transient predicate for octokit calls: an HTTP 5xx (GitHub upstream
+ * blip) OR a network-class error. distinct from `isTransientNetworkError` — an
+ * HTTP 4xx (404/401/403/422) is deterministic and fails fast. the action
+ * octokit carries only the throttling plugin + a 401 re-mint (no 5xx retry),
+ * so callers on critical paths retry idempotent GitHub reads/dispatches with
+ * this. mirrors the server's `isTransientUpstreamError`. see #999.
+ */
+export declare function isTransientOctokitError(error: unknown): boolean;

package/dist/utils/learnings.d.ts

@@ -29,7 +29,9 @@ export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary };
  * agent-targetable on long-lived repos; there is no fixed taxonomy.
  */
 export declare const LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
+export declare const XREPO_LEARNINGS_FILE_NAME = "pullfrog-xrepo-learnings.md";
 export declare function learningsFilePath(tmpdir: string): string;
+export declare function xrepoLearningsFilePath(tmpdir: string): string;
 /** seed the rolling learnings tmpfile with the verbatim DB body (or empty
  * string for fresh repos). returns the absolute path. the parsed TOC is
  * carried separately via `RepoSettings.learningsHeadings` and rendered
@@ -39,6 +41,11 @@ export declare function seedLearningsFile(params: {
     tmpdir: string;
     current: string | null;
 }): Promise<string>;
+/** seed the org-level cross-repo learnings tmpfile (--xrepo runs only). */
+export declare function seedXrepoLearningsFile(params: {
+    tmpdir: string;
+    current: string | null;
+}): Promise<string>;
 /** 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. */
@@ -60,3 +67,10 @@ export declare function readLearningsFile(path: string): Promise<string | null>;
  * normal end-of-run path and the SIGINT/SIGTERM handler.
  */
 export declare function persistLearnings(ctx: ToolContext): Promise<void>;
+/**
+ * Read the agent-edited cross-repo learnings tmpfile and PATCH it to
+ * `Account.xrepoLearnings`. Org-level analogue of `persistLearnings` —
+ * same best-effort + unchanged-from-seed gating. Only seeded on --xrepo runs,
+ * so this is a no-op when `xrepoLearningsFilePath` is unset.
+ */
+export declare function persistXrepoLearnings(ctx: ToolContext): Promise<void>;