pullfrog 0.1.30 → 0.1.31

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>;
@@ -94,6 +115,7 @@ export interface ToolState {
     lastProgressBody?: string;
     wasUpdated?: boolean;
     finalSummaryWritten?: boolean;
+    answerCommentPosted?: boolean;
     existingPlanCommentId?: number;
     previousPlanBody?: string;
     summaryFilePath?: string;
@@ -102,12 +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 {
@@ -115,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/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,10 @@
+/**
+ * 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;

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>;

package/dist/utils/modelAccess.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Model-access gate for explicitly-requested per-run models (`--opus`,
+ * `--model=<slug>`). An explicit model the run can't serve hard-fails *before*
+ * the agent starts with one consistent, reason-tailored error.
+ *
+ * The provenance split lives upstream: `payload.modelExplicit` is true only for
+ * a flag in the triggerer's own @pullfrog prompt. A standing default (repo
+ * setting, a model flag in org/repo `baseInstructions`, or a trigger's fallback
+ * instructions) keeps `modelExplicit = false` and never reaches the error
+ * branches here — a missing key for a standing default surfaces through
+ * `validateAgentApiKey`'s missing-key error instead (#938).
+ *
+ * `decideModelAccess` is pure (no env / IO) so the branching is unit-testable;
+ * `buildModelAccessError` renders the user-facing markdown that `main.ts`
+ * throws and `runErrorRenderer.ts` re-surfaces on both run surfaces.
+ */
+export type ModelAccessReason = "oss" | "byok_no_key" | "router";
+export type ModelAccessDecision = {
+    kind: "ok";
+}
+/** route through the Router/OSS proxy, re-targeted to the requested model. */
+ | {
+    kind: "proxy";
+    target: string;
+}
+/** run BYOK with the requested model — clear the minted proxy target. */
+ | {
+    kind: "byok";
+} | {
+    kind: "error";
+    reason: ModelAccessReason;
+};
+/**
+ * decide whether an (already-resolved) requested model can run, and how.
+ *
+ * - non-explicit / no model → `ok` (caller's missing-key validation applies).
+ * - proxy active + OSS → only the funded subsidy target routes; a different
+ *   model needs the repo's own key (`byok`) else `error("oss")`.
+ * - proxy active + Router → honor any Router-servable model (`proxy`); fall to
+ *   BYOK when locally authorized, else `error("router")`.
+ * - no proxy → the resolved model must be locally authorized, else
+ *   `error("byok_no_key")`.
+ */
+export declare function decideModelAccess(input: {
+    modelExplicit: boolean;
+    model: string | undefined;
+    oss: boolean;
+    proxyActive: boolean;
+    subsidyTarget: string | undefined;
+    resolvedModel: string | undefined;
+    authorized: Set<string>;
+}): ModelAccessDecision;
+/** marker on the throw message so `runErrorRenderer` can reclassify it. */
+export declare const MODEL_ACCESS_MARKER = "requested model is not available";
+/**
+ * render the model-access failure body (used for both the thrown error and the
+ * PR comment / job summary). one shape, reason-branched why → CTA.
+ */
+export declare function buildModelAccessError(input: {
+    reason: ModelAccessReason;
+    model: string;
+    owner: string;
+    name: string;
+}): string;

package/dist/utils/payload.d.ts

@@ -5,10 +5,18 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     version: string;
     prompt: string;
     model?: string | undefined;
+    modelExplicit?: boolean | undefined;
     triggerer?: string | undefined;
+    baseInstructions?: string | undefined;
     eventInstructions?: string;
     previousRunsNote?: string;
     event?: object;
+    xrepo?: {
+        mode: "all" | "explicit";
+        read: string[];
+        write: string[];
+        unavailable?: string[];
+    } | undefined;
     timeout?: string | undefined;
     progressComment?: {
         id: string;
@@ -32,11 +40,19 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
     "~pullfrog": true;
     version: string;
     model: string | undefined;
+    modelExplicit: boolean;
     prompt: string;
     triggerer: string | undefined;
+    baseInstructions: string | undefined;
     eventInstructions: string | undefined;
     previousRunsNote: string | undefined;
     event: PayloadEvent;
+    xrepo: {
+        mode: "all" | "explicit";
+        read: string[];
+        write: string[];
+        unavailable?: string[];
+    } | undefined;
     timeout: string | undefined;
     cwd: string | undefined;
     progressComment: {

package/dist/utils/runContext.d.ts

@@ -36,6 +36,9 @@ export interface RepoSettings {
     learnings: string | null;
     learningsHeadings: LearningsHeading[];
     envAllowlist: string | null;
+    xrepoBrief: string | null;
+    xrepoLearnings: string | null;
+    xrepoLearningsHeadings: LearningsHeading[];
 }
 /**
  * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors

package/dist/utils/runContextData.d.ts

@@ -18,6 +18,16 @@ interface ResolveRunContextDataParams {
     octokit: OctokitWithPlugins;
     token: string;
 }
+/**
+ * true when the action is pinned to a full commit SHA (vs the moving `@v0`
+ * tag or a branch). GitHub runs the action's `post:` hook (and reads
+ * `action.yml`) straight from the checked-out action ref, so a SHA pin freezes
+ * that checkout forever: the main agent still floats to the latest `^semver`
+ * via the npm bootstrap (this code is proof — it ran), but the post-run
+ * cleanup step keeps executing the pinned commit's source and never receives
+ * fixes. surfaced in the log and PR footers to nudge repos back to `@v0`.
+ */
+export declare function isActionPinnedToSha(): boolean;
 /**
  * initialize run context data: parse context, fetch repo info and settings
  */