pullfrog 0.0.200 → 0.0.202

package/dist/internal.js

@@ -11,7 +11,7 @@ var providers = {
     models: {
       "claude-opus": {
         displayName: "Claude Opus",
-        resolve: "anthropic/claude-opus-4-6",
+        resolve: "anthropic/claude-opus-4-7",
         openRouterResolve: "openrouter/anthropic/claude-opus-4.6",
         preferred: true
       },
@@ -39,7 +39,7 @@ var providers = {
       },
       "gpt-codex-mini": {
         displayName: "GPT Codex Mini",
-        resolve: "openai/codex-mini-latest",
+        resolve: "openai/gpt-5.1-codex-mini",
         openRouterResolve: "openrouter/openai/gpt-5.1-codex-mini"
       },
       o3: {
@@ -129,7 +129,7 @@ var providers = {
       },
       "claude-opus": {
         displayName: "Claude Opus",
-        resolve: "opencode/claude-opus-4-6",
+        resolve: "opencode/claude-opus-4-7",
         openRouterResolve: "openrouter/anthropic/claude-opus-4.6"
       },
       "claude-sonnet": {
@@ -319,7 +319,7 @@ function formatMcpToolRef(agentId, toolName) {
   switch (agentId) {
     case "claude":
       return `mcp__${pullfrogMcpName}__${toolName}`;
-    case "opentoad":
+    case "opencode":
       return `${pullfrogMcpName}_${toolName}`;
     default:
       return agentId;
@@ -368,7 +368,7 @@ GitHub's markdown parser requires a blank line between ALL block-level elements.
 Rules:
 - \`##\` titles and key-change bullet lead-ins are plain-language summaries; backtick only actual code tokens (files, types, functions) where they appear in the title
 - ALL variable names, identifiers, and file names in body text must be in backticks
-- ALL file references MUST link to the PR Files Changed view. Compute anchors by running \`echo -n 'path/to/file.ts' | sha256sum\` via shell for each file. NEVER fabricate hex strings \u2014 run the actual command. If shell is unavailable, omit the #diff- anchor rather than guessing.
+- ALL file references MUST link to the PR Files Changed view. Use the \`diff-<hex>\` anchor precomputed next to each filename in the \`checkout_pr\` TOC \u2014 do NOT run \`sha256sum\` or any other shell command to compute anchors. NEVER fabricate hex strings. If a file is not in the TOC, omit the \`#diff-\` anchor rather than guessing.
 - Add <br/> before each ## heading for visual spacing. Do NOT use horizontal rules (---)
 - Do NOT include raw diff stats like '+123 / -45' or line counts
 - Do NOT include code blocks or repeat diff contents
@@ -443,7 +443,7 @@ ${learningsStep(t, 6)}`
       description: "Review code, PRs, or implementations; provide feedback or suggestions; identify issues; or check code quality, style, and correctness",
       prompt: `### Checklist
 
-1. Checkout the PR via \`${t("checkout_pr")}\` \u2014 this returns PR metadata and a \`diffPath\`. Read the diff to identify the major areas of change.
+1. Checkout the PR via \`${t("checkout_pr")}\` \u2014 this returns PR metadata and a \`diffPath\`. read the diff TOC first and treat its file line ranges as your coverage checklist.
 
 2. For each area of change:
    - read the diff and trace data flow, check boundaries, and verify assumptions
@@ -460,6 +460,7 @@ ${learningsStep(t, 6)}`
 4. Submit \u2014 ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\`.
    Do NOT call \`report_progress\` \u2014 the review is the final record and the progress
    comment will be cleaned up automatically.
+   note: the first create_pull_request_review submission may error with a one-time diff-coverage nudge listing unread TOC regions. retry the same call to proceed \u2014 optionally after reading the listed ranges. the pre-flight will not block again this session.
 
    - **critical issues** (blocks merge \u2014 bugs, security, data loss):
      \`approved: false\`. Body begins with a GitHub alert blockquote, e.g.:
@@ -477,7 +478,7 @@ ${learningsStep(t, 6)}`
       description: "Re-review a PR after new commits are pushed; focus on new changes since the last review",
       prompt: `### Checklist
 
-1. Checkout the PR via \`${t("checkout_pr")}\` \u2014 this returns PR metadata, \`diffPath\` (full diff), and \`incrementalDiffPath\` (changes since last reviewed version, if available).
+1. Checkout the PR via \`${t("checkout_pr")}\` \u2014 this returns PR metadata, \`diffPath\` (full diff), and \`incrementalDiffPath\` (changes since last reviewed version, if available). read the diff TOC first and use its line ranges as your coverage checklist.
 
 2. If \`incrementalDiffPath\` is present, read it to see what changed since the last review. This is a range-diff that isolates the net changes, filtering out base branch noise. If not present, fall back to reviewing the full PR diff.
 
@@ -501,6 +502,7 @@ ${learningsStep(t, 6)}`
    - in some cases you may receive a complete diff for the whole pull request instead of an incremental one. when this happens, you will need to determine what changes have happened since Pullfrog's most recent review.
 
 7. Submit \u2014 Do NOT call \`report_progress\` or \`create_issue_comment\` \u2014 the review is the final record and the progress comment will be cleaned up automatically. the review body always includes the reviewed changes from step 6a. append \`Prior review feedback:\\n\` with the checklist from step 6b only if any prior comments were addressed. Follow these rules:
+   - note: the first create_pull_request_review submission may error with a one-time diff-coverage nudge listing unread TOC regions. retry the same call to proceed \u2014 optionally after reading the listed ranges. the pre-flight will not block again this session.
    - IF NO NEW ISSUES, NON-SUBSTANTIVE CHANGES ONLY (trivial formatting, import reordering, comment tweaks): do NOT submit a review. Do NOT call \`report_progress\`. Exit \u2014 the progress comment will be cleaned up automatically.
    - ELSE IF NEW CRITICAL ISSUES (blocks merge): call \`${t("create_pull_request_review")}\` with \`approved: false\`, all comments, and the review body. body opens with a GitHub alert blockquote (e.g. \`> [!CAUTION]\\n> This PR introduces ...\`), then the reviewed changes summary and prior feedback (if any).
    - ELSE IF NEW RECOMMENDED CHANGES (non-critical): call \`${t("create_pull_request_review")}\` with \`approved: false\`, all comments, and the review body. body opens with \`> [!IMPORTANT]\\n> ...\` alert, then the reviewed changes summary and prior feedback (if any).
@@ -605,7 +607,7 @@ ${PR_SUMMARY_FORMAT}`
     }
   ];
 }
-var modes = computeModes("opentoad");
+var modes = computeModes("opencode");
 
 // utils/buildPullfrogFooter.ts
 var PULLFROG_DIVIDER = "<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->";

package/dist/lifecycle.d.ts

@@ -1,2 +1,2 @@
 /** timeout for lifecycle hook scripts */
-export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 120000;
+export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 600000;

package/dist/mcp/checkout.d.ts

@@ -5,6 +5,9 @@ export type FormatFilesResult = {
     content: string;
     toc: string;
 };
+export type FetchAndFormatPrDiffResult = FormatFilesResult & {
+    files: PullFile[];
+};
 /**
  * formats PR files with explicit line numbers for each code line.
  * preserves all original diff info (file headers, hunk headers) and adds:
@@ -19,6 +22,7 @@ export type CheckoutPrResult = {
     success: true;
     number: number;
     title: string;
+    body: string | null;
     base: string;
     localBranch: string;
     remoteBranch: string;
@@ -29,13 +33,21 @@ export type CheckoutPrResult = {
     diffPath: string;
     incrementalDiffPath?: string | undefined;
     toc: string;
+    commitCount: number;
+    commitLog: string;
+    /** true when commitLog was capped because the PR has more commits than we render */
+    commitLogTruncated: boolean;
+    /** true when commit metadata could not be computed (e.g. base ref unreachable after shallow fetch). commitCount/commitLog are zero/empty in that case, not "no commits". */
+    commitLogUnavailable: boolean;
+    /** non-fatal warning from the post-checkout lifecycle hook, if any */
+    hookWarning?: string | undefined;
     instructions: string;
 };
 /**
  * fetches PR files from GitHub and formats them with line numbers and TOC.
  * this is the core diff formatting logic, extracted for testability.
  */
-export declare function fetchAndFormatPrDiff(ctx: ToolContext, pullNumber: number): Promise<FormatFilesResult>;
+export declare function fetchAndFormatPrDiff(ctx: ToolContext, pullNumber: number): Promise<FetchAndFormatPrDiffResult>;
 import type { GitContext } from "../utils/setup.ts";
 export type PrData = {
     number: number;
@@ -54,7 +66,9 @@ type CheckoutPrBranchParams = GitContext & {
  * Assumes origin remote is already configured with authentication.
  * Updates toolState.issueNumber, toolState.checkoutSha, and toolState.pushUrl (for fork PRs).
  */
-export declare function checkoutPrBranch(pr: PrData, params: CheckoutPrBranchParams): Promise<void>;
+export declare function checkoutPrBranch(pr: PrData, params: CheckoutPrBranchParams): Promise<{
+    hookWarning?: string | undefined;
+}>;
 export declare function CheckoutPrTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
     pull_number: number;
 }, {

package/dist/mcp/comment.d.ts

@@ -5,6 +5,7 @@ import type { ToolContext } from "./server.ts";
  * and hasn't been updated with progress or error messages.
  */
 export declare const LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
+export declare function isLeapingIntoActionCommentBody(body: string): boolean;
 export declare function addFooter(ctx: ToolContext, body: string): string;
 export declare const Comment: import("arktype/internal/variants/object.ts").ObjectType<{
     issueNumber: number;

package/dist/mcp/geminiSanitizer.d.ts

@@ -0,0 +1,17 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Tool } from "fastmcp";
+import type { ToolContext } from "./server.ts";
+/**
+ * Recursively transform a JSON schema to gemini's stricter subset.
+ * See module header for the exact transforms applied.
+ */
+export declare function sanitizeForGemini(schema: unknown): unknown;
+export declare function wrapSchemaForGemini(schema: StandardSchemaV1<any>): StandardSchemaV1<any>;
+export declare function sanitizeToolForGemini<T extends Tool<any, any>>(tool: T): T;
+/**
+ * true when the effective upstream model is served by google's generative
+ * language API — directly (`google/*`), via opencode (`opencode/gemini-*`),
+ * or via openrouter (`openrouter/google/gemini-*`). slug-substring match
+ * works because every gemini route's model id contains "gemini".
+ */
+export declare function isGeminiRouted(ctx: ToolContext): boolean;

package/dist/mcp/git.d.ts

@@ -1,4 +1,7 @@
 import type { ToolContext } from "./server.ts";
+export declare function rejectIfLeadingDash(value: string, kind: string): void;
+export declare function rejectSpecialRef(value: string, kind: string): void;
+export declare function validateTagName(tag: string): void;
 export declare const PushBranch: import("arktype/internal/variants/object.ts").ObjectType<{
     force: import("arktype/internal/attributes.ts").Default<boolean, false>;
     branchName?: string;
@@ -10,11 +13,14 @@ export declare function PushBranchTool(ctx: ToolContext): import("fastmcp").Tool
     branchName?: string;
     force?: boolean;
 }>>;
+export declare const AUTH_REQUIRED_REDIRECT: Record<string, string>;
+export declare const NOSHELL_BLOCKED_SUBCOMMANDS: Record<string, string>;
+export declare const NOSHELL_BLOCKED_ARGS: string[];
 export declare function GitTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
-    subcommand: string;
+    command: string;
     args?: string[];
 }, {
-    subcommand: string;
+    command: string;
     args?: string[];
 }>>;
 export declare function GitFetchTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{

package/dist/mcp/review.d.ts

@@ -1,4 +1,67 @@
+import type { RestEndpointMethodTypes } from "@octokit/rest";
 import type { ToolContext } from "./server.ts";
+export type CommentableLines = {
+    RIGHT: Set<number>;
+    LEFT: Set<number>;
+};
+/**
+ * parse a PR file's patch to determine which line numbers on each side are
+ * valid anchors for inline comments. GitHub only accepts comments on lines
+ * inside a diff hunk: added/context lines on RIGHT, removed/context lines
+ * on LEFT.
+ */
+export declare function commentableLinesForFile(patch: string | undefined): CommentableLines;
+export declare function buildCommentableMap(ctx: ToolContext, pullNumber: number): Promise<Map<string, CommentableLines>>;
+export type ReviewCommentInput = NonNullable<RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]["comments"]>[number];
+export interface DroppedComment {
+    path: string;
+    line: number;
+    startLine?: number | undefined;
+    side: "LEFT" | "RIGHT";
+    reason: string;
+}
+export declare function validateInlineComments(comments: ReviewCommentInput[], map: Map<string, CommentableLines>): {
+    valid: ReviewCommentInput[];
+    dropped: DroppedComment[];
+};
+export declare const MAX_DROPPED_COMMENT_LINES = 50;
+/**
+ * reason a create_pull_request_review call should be skipped without hitting
+ * GitHub. returned by reviewSkipDecision; null means submit normally.
+ */
+export type ReviewSkipDecision = {
+    kind: "no-issues";
+    reason: string;
+} | {
+    kind: "empty-downgraded-approve";
+    reason: string;
+};
+/**
+ * decide whether to skip a review submission before any network call.
+ *
+ * GitHub rejects `event: "COMMENT"` reviews with no body and no inline comments
+ * with HTTP 422 "Unprocessable Entity". two paths produce that shape:
+ *
+ *   1. `!approved` + empty body/comments: agent's "no issues found" result.
+ *      skipping preserves the agent's intent (nothing to post is a fine
+ *      outcome for a review run) without a spurious 422.
+ *   2. `approved` + `!prApproveEnabled` + empty body/comments: the runtime
+ *      downgrades APPROVE to COMMENT when prApproveEnabled is off, and the
+ *      resulting empty-COMMENT is exactly the shape GitHub 422s. skipping
+ *      here surfaces the cause (downgrade + nothing to say) instead of an
+ *      opaque 422 the agent can't recover from.
+ *
+ * legitimate bare approvals (`approved` + `prApproveEnabled`, no body/comments)
+ * are never skipped — GitHub accepts empty APPROVE reviews and the approval
+ * stamp itself is the review's content.
+ */
+export declare function reviewSkipDecision(params: {
+    approved: boolean;
+    body: string | null | undefined;
+    hasComments: boolean;
+    prApproveEnabled: boolean;
+}): ReviewSkipDecision | null;
+export declare function formatDroppedCommentsNote(dropped: DroppedComment[]): string;
 export declare const CreatePullRequestReview: import("arktype/internal/variants/object.ts").ObjectType<{
     pull_number: number;
     body?: string;
@@ -40,6 +103,47 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
         start_line?: number;
     }[];
 }>>;
+/**
+ * clear a pending review draft stranded on the PR by a prior hard-killed run
+ * (workflow timeout, OOM) so the next createReview can succeed.
+ *
+ * GitHub enforces one-pending-review-per-user-per-PR. if the previous process
+ * died between createReview(PENDING) and submitReview, the draft remains and
+ * the next run's createReview 422s with "already has a pending review".
+ * listReviews only exposes PENDING reviews to their author, so filtering on
+ * state === "PENDING" is already scoped to the authed token's own draft.
+ *
+ * if `originalErr` is not a pending-review 422, or no leftover is found, this
+ * function rethrows `originalErr` so the caller surfaces the original failure.
+ * delete failures with 404 (draft already gone) or 422 (draft submitted by a
+ * concurrent caller) are swallowed — the caller's retry will succeed in both
+ * cases. any other delete error is rethrown unchanged.
+ *
+ * known limitation: if two runs on the SAME PR share the authed token and
+ * overlap in time, the loser's createReview 422s on the winner's still-active
+ * draft. recovery would then delete the winner's active draft and the
+ * winner's submitReview would 404. this is not distinguishable from a
+ * genuinely-stranded draft via the review object alone (PENDING reviews
+ * expose no created_at timestamp, and both reviews are authored by the same
+ * bot user). rely on workflow-level concurrency controls (e.g. a concurrency
+ * key keyed to the PR number) to prevent overlap.
+ */
+export declare function clearStrandedPendingReview(ctx: ToolContext, params: {
+    owner: string;
+    repo: string;
+    pull_number: number;
+    originalErr: unknown;
+}): Promise<void>;
+/**
+ * single-step createReview (event != PENDING) with stranded-draft recovery.
+ * the body path goes through createAndSubmitWithFooter which already recovers
+ * from a stranded PENDING draft at its own createReview call. the no-body path
+ * used to call createReview directly with no recovery — so a PR whose previous
+ * body-path run crashed between createReview(PENDING) and submitReview would
+ * permanently 422 any subsequent no-body review (approve-with-no-feedback or
+ * 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>>>;
 /**
  * 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/server.d.ts

@@ -3,10 +3,12 @@ import type { AgentUsage } from "../agents/index.ts";
 import { type AgentId } from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { PrepResult } from "../prep/index.ts";
+import type { DiffCoverageState } from "../utils/diffCoverage.ts";
 import type { OctokitWithPlugins } from "../utils/github.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
 import type { RunContextData } from "../utils/runContextData.ts";
 import type { TodoTracker } from "../utils/todoTracking.ts";
+import type { CommentableLines } from "./review.ts";
 export type BackgroundProcess = {
     pid: number;
     outputPath: string;
@@ -29,6 +31,9 @@ export interface ToolState {
     pushDest?: StoredPushDest;
     issueNumber?: number;
     checkoutSha?: string;
+    commentableLinesByFile?: Map<string, CommentableLines>;
+    commentableLinesPullNumber?: number;
+    commentableLinesCheckoutSha?: string | undefined;
     beforeSha?: string;
     selectedMode?: string;
     backgroundProcesses: Map<string, BackgroundProcess>;
@@ -55,6 +60,7 @@ export interface ToolState {
     usageEntries: AgentUsage[];
     model?: string | undefined;
     todoTracker?: TodoTracker | undefined;
+    diffCoverage?: DiffCoverageState | undefined;
 }
 interface InitToolStateParams {
     progressCommentId: string | undefined;
@@ -78,6 +84,7 @@ export interface ToolContext {
     jobId: string | undefined;
     mcpServerUrl: string;
     tmpdir: string;
+    resolvedModel: string | undefined;
 }
 type JsonSchema = Record<string, unknown>;
 type McpHttpServerOptions = {
@@ -85,6 +92,11 @@ type McpHttpServerOptions = {
 };
 /**
  * Start the MCP HTTP server.
+ *
+ * The returned disposer is idempotent — safe to call multiple times.
+ * Callers (e.g. the inner activity-timeout handler in main.ts) may need to
+ * stop the server before the `await using` block exits; a subsequent
+ * automatic dispose is then a no-op.
  */
 export declare function startMcpHttpServer(ctx: ToolContext, options?: McpHttpServerOptions): Promise<{
     url: string;

package/dist/mcp/shared.d.ts

@@ -18,4 +18,4 @@ export declare const handleToolError: (error: unknown) => ToolResult;
  * @param toolName - optional tool name for error logging
  */
 export declare const execute: <T, R extends Record<string, any> | string>(fn: (params: T) => Promise<R>, toolName?: string) => (params: T) => Promise<ToolResult>;
-export declare const addTools: (_ctx: ToolContext, server: FastMCP<any>, tools: Tool<any, any>[]) => FastMCP<any>;
+export declare const addTools: (ctx: ToolContext, server: FastMCP<any>, tools: Tool<any, any>[]) => FastMCP<any>;

package/dist/modes.d.ts

@@ -4,6 +4,6 @@ export interface Mode {
     description: string;
     prompt?: string | undefined;
 }
-export declare const PR_SUMMARY_FORMAT = "### Default format\n\nFollow this structure exactly:\n\n<b>TL;DR</b> \u2014 1-3 sentences on what the PR does and why. Focus on intent, not mechanics.\nNOTE: use HTML bold <b>TL;DR</b>, NOT markdown bold **TL;DR**.\n\n### Key changes\n\n- **Short human-readable title** \u2014 1 sentence per change. Write a short prose phrase (title case or sentence case); 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 PR from this list alone.\n\n<sub><b>Summary</b> \uFF5C {file_count} files \uFF5C {commit_count} commits \uFF5C base: `{base}` \u2190 `{head}`</sub>\nNOTE: the metadata line goes AFTER the bullet list, not before it.\n\nThen for each key change, a ## section with a short descriptive title that reads like a documentation heading (e.g. ## Live todo checklist tracking).\n\n<br/>\n\n## Example readable section title\n\n> **Before:** [old behavior/state]<br/>**After:** [new behavior/state]\nIMPORTANT: Before and After MUST be on a SINGLE blockquote line with an inline <br/> between them. Two separate `>` lines creates a double line break.\n\n1-2 sentences of explanation. Break up text with tables, blockquotes, or lists \u2014 NEVER 3+ plain paragraphs in a row.\n\nIf a change warrants deeper explanation, use a blockquoted details/summary framed as a question:\n> <details><summary>How does X work?</summary>\n> Extended explanation here.\n> </details>\n\nEnd each section with a file links trail (3-4 key files max):\n[`file.ts`](https://github.com/{owner}/{repo}/pull/{number}/files#diff-{sha256hex_of_filepath}) \u00B7 ...\n\nSingle-feature PRs: skip the ## sections. Fold before/after and explanation into the header after key changes.\n\nCRITICAL \u2014 GitHub markdown rendering rule:\nGitHub's markdown parser requires a blank line between ALL block-level elements. This includes transitions between: HTML tags (<br/>, <sub>, <details>, <b>, etc.) and markdown syntax (headings, lists, blockquotes, paragraphs). Without a blank line, GitHub treats the 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\nRules:\n- `##` titles and key-change bullet lead-ins are plain-language summaries; backtick only actual code tokens (files, types, functions) where they appear in the title\n- ALL variable names, identifiers, and file names in body text must be in backticks\n- ALL file references MUST link to the PR Files Changed view. Compute anchors by running `echo -n 'path/to/file.ts' | sha256sum` via shell for each file. NEVER fabricate hex strings \u2014 run the actual command. If shell is unavailable, omit the #diff- anchor rather than guessing.\n- Add <br/> before each ## heading for visual spacing. Do NOT use horizontal rules (---)\n- Do NOT include raw diff stats like '+123 / -45' or line counts\n- Do NOT include code blocks or repeat diff contents\n- Do NOT include a changelog section \u2014 the key changes list serves this purpose\n- Focus on *intent*, not *what* \u2014 the diff already shows what changed\n- Get the file count and commit count from the checkout_pr metadata, not by counting manually";
+export declare const PR_SUMMARY_FORMAT = "### Default format\n\nFollow this structure exactly:\n\n<b>TL;DR</b> \u2014 1-3 sentences on what the PR does and why. Focus on intent, not mechanics.\nNOTE: use HTML bold <b>TL;DR</b>, NOT markdown bold **TL;DR**.\n\n### Key changes\n\n- **Short human-readable title** \u2014 1 sentence per change. Write a short prose phrase (title case or sentence case); 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 PR from this list alone.\n\n<sub><b>Summary</b> \uFF5C {file_count} files \uFF5C {commit_count} commits \uFF5C base: `{base}` \u2190 `{head}`</sub>\nNOTE: the metadata line goes AFTER the bullet list, not before it.\n\nThen for each key change, a ## section with a short descriptive title that reads like a documentation heading (e.g. ## Live todo checklist tracking).\n\n<br/>\n\n## Example readable section title\n\n> **Before:** [old behavior/state]<br/>**After:** [new behavior/state]\nIMPORTANT: Before and After MUST be on a SINGLE blockquote line with an inline <br/> between them. Two separate `>` lines creates a double line break.\n\n1-2 sentences of explanation. Break up text with tables, blockquotes, or lists \u2014 NEVER 3+ plain paragraphs in a row.\n\nIf a change warrants deeper explanation, use a blockquoted details/summary framed as a question:\n> <details><summary>How does X work?</summary>\n> Extended explanation here.\n> </details>\n\nEnd each section with a file links trail (3-4 key files max):\n[`file.ts`](https://github.com/{owner}/{repo}/pull/{number}/files#diff-{sha256hex_of_filepath}) \u00B7 ...\n\nSingle-feature PRs: skip the ## sections. Fold before/after and explanation into the header after key changes.\n\nCRITICAL \u2014 GitHub markdown rendering rule:\nGitHub's markdown parser requires a blank line between ALL block-level elements. This includes transitions between: HTML tags (<br/>, <sub>, <details>, <b>, etc.) and markdown syntax (headings, lists, blockquotes, paragraphs). Without a blank line, GitHub treats the 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\nRules:\n- `##` titles and key-change bullet lead-ins are plain-language summaries; backtick only actual code tokens (files, types, functions) where they appear in the title\n- ALL variable names, identifiers, and file names in body text must be in backticks\n- ALL file references MUST link to the PR Files Changed view. Use the `diff-<hex>` anchor precomputed next to each filename in the `checkout_pr` TOC \u2014 do NOT run `sha256sum` or any other shell command to compute anchors. NEVER fabricate hex strings. If a file is not in the TOC, omit the `#diff-` anchor rather than guessing.\n- Add <br/> before each ## heading for visual spacing. Do NOT use horizontal rules (---)\n- Do NOT include raw diff stats like '+123 / -45' or line counts\n- Do NOT include code blocks or repeat diff contents\n- Do NOT include a changelog section \u2014 the key changes list serves this purpose\n- Focus on *intent*, not *what* \u2014 the diff already shows what changed\n- Get the file count and commit count from the checkout_pr metadata, not by counting manually";
 export declare function computeModes(agentId: AgentId): Mode[];
 export declare const modes: Mode[];

package/dist/utils/activity.d.ts

@@ -1,5 +1,7 @@
 export declare const DEFAULT_ACTIVITY_TIMEOUT_MS = 300000;
 export declare const DEFAULT_ACTIVITY_CHECK_INTERVAL_MS = 5000;
+export declare const ACTIVITY_NOISE_PATTERNS: readonly RegExp[];
+export declare function isActivityNoise(chunk: string | Uint8Array): boolean;
 type ActivityTimeoutContext = {
     timeoutMs: number;
     checkIntervalMs: number;
@@ -7,6 +9,8 @@ type ActivityTimeoutContext = {
 export type ActivityTimeout = {
     promise: Promise<never>;
     stop: () => void;
+    /** force the timeout to reject immediately with a custom reason */
+    forceReject: (reason: string) => void;
 };
 /**
  * mark activity to reset the no-output timeout.

package/dist/utils/agent.d.ts

@@ -3,7 +3,9 @@ import type { Agent } from "../agents/index.ts";
  * resolve the effective model for this run.
  *
  * priority:
- *   1. PULLFROG_MODEL env var (explicit specifier override)
+ *   1. PULLFROG_MODEL env var — resolved through the alias registry first,
+ *      so values like "anthropic/claude-opus" become "anthropic/claude-opus-4-7".
+ *      raw specifiers (e.g. "anthropic/claude-opus-4-6") pass through unchanged.
  *   2. slug from repo config / payload → alias registry
  *   3. undefined — agent will auto-select
  */

package/dist/utils/diffCoverage.d.ts

@@ -0,0 +1,62 @@
+export type DiffLineRange = {
+    startLine: number;
+    endLine: number;
+};
+export type DiffTocEntry = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+};
+export type DiffCoverageFileBreakdown = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    coveredLines: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+};
+export type DiffCoverageBreakdown = {
+    totalLines: number;
+    coveredLines: number;
+    unreadLines: number;
+    coveragePercent: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+    files: DiffCoverageFileBreakdown[];
+};
+export type DiffCoverageState = {
+    diffPath: string;
+    totalLines: number;
+    tocEntries: DiffTocEntry[];
+    coveredRanges: DiffLineRange[];
+    coveragePreflightRan: boolean;
+    lastBreakdown?: string | undefined;
+};
+export declare function countLines(params: {
+    content: string;
+}): number;
+export declare function parseDiffTocEntries(params: {
+    toc: string;
+}): DiffTocEntry[];
+export declare function createDiffCoverageState(params: {
+    diffPath: string;
+    totalLines: number;
+    toc: string;
+}): DiffCoverageState;
+export declare function recordDiffReadFromToolUse(params: {
+    state: DiffCoverageState | undefined;
+    toolName: string;
+    input: unknown;
+    cwd: string;
+}): boolean;
+export declare function getDiffCoverageBreakdown(params: {
+    state: DiffCoverageState;
+}): DiffCoverageBreakdown;
+export declare function renderDiffCoverageBreakdown(params: {
+    diffPath: string;
+    breakdown: DiffCoverageBreakdown;
+}): string;
+export declare function countLinesInRanges(params: {
+    ranges: DiffLineRange[];
+}): number;

package/dist/utils/lifecycle.d.ts

@@ -2,8 +2,20 @@ export interface ExecuteLifecycleHookParams {
     event: string;
     script: string | null;
 }
+export interface LifecycleHookResult {
+    /**
+     * human-readable warning when the hook failed. includes retry guidance:
+     * transient spawn/exit errors are worth retrying, timeouts and
+     * persistent failures are not. absent when the hook succeeded or was
+     * skipped.
+     */
+    warning?: string;
+}
 /**
  * execute a lifecycle hook script if one is configured.
- * runs the script in a bash shell with a timeout.
+ *
+ * soft-fails: instead of throwing on hook errors, returns a warning string
+ * so callers can choose whether to surface it (mcp tools) or upgrade it to
+ * a fatal error (setup/prepush). timeouts are flagged as non-retryable.
  */
-export declare function executeLifecycleHook(params: ExecuteLifecycleHookParams): Promise<void>;
+export declare function executeLifecycleHook(params: ExecuteLifecycleHookParams): Promise<LifecycleHookResult>;

package/dist/utils/log.d.ts

@@ -1,7 +1,7 @@
 /**
  * Logging utilities that work well in both local and GitHub Actions environments
  */
-import type { AgentUsage } from "../agents/shared.ts";
+import { type AgentUsage } from "../agents/shared.ts";
 /** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
 export declare function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T>;
 /**
@@ -86,7 +86,18 @@ export declare function formatJsonValue(value: unknown): string;
  */
 export declare function formatIndentedField(label: string, content: string): string;
 /**
- * format aggregated usage data as a markdown table for the GitHub step summary
+ * format aggregated usage data as a markdown table for the GitHub step summary.
+ *
+ * columns mirror the per-run stdout token table emitted by `logTokenTable`
+ * (Input / Cache Read / Cache Write / Output / Total / Cost ($)) so the job
+ * summary and the in-run logs can be compared row-for-row.
+ *
+ * notes:
+ *   - `AgentUsage.inputTokens` is the sum of non-cached input + cache read
+ *     + cache write (set that way by both agent harnesses' `buildUsage`),
+ *     so the non-cached Input column is recovered by subtracting cache fields.
+ *   - `costUsd` is sourced from models.dev (OpenCode) or `total_cost_usd`
+ *     (Claude CLI). absent rows show `—` so per-agent coverage is obvious.
  */
 export declare function formatUsageSummary(entries: AgentUsage[]): string;
 export {};

package/dist/utils/patchWorkflowRunFields.d.ts

@@ -1,6 +1,29 @@
+import type { AgentUsage } from "../agents/shared.ts";
 import type { ToolContext } from "../mcp/server.ts";
-/** Keys accepted by PATCH /api/workflow-run/[runId] — keep in sync with `ALLOWED_FIELDS` in `app/api/workflow-run/[runId]/route.ts`. */
+/**
+ * Artifact tracking fields — one-off PATCHes from MCP tools as GitHub entities
+ * are created during the run. Strings only (GraphQL node IDs).
+ * Keep in sync with `STRING_FIELDS` in `app/api/workflow-run/[runId]/route.ts`.
+ */
 export type WorkflowRunArtifactPatchKey = "prNodeId" | "issueNodeId" | "reviewNodeId" | "planCommentNodeId" | "summaryCommentNodeId";
-export type WorkflowRunArtifactPatch = Partial<Record<WorkflowRunArtifactPatchKey, string>>;
-/** PATCH workflow-run artifact fields (Pullfrog JWT, not GitHub). */
-export declare function patchWorkflowRunFields(ctx: ToolContext, fields: WorkflowRunArtifactPatch): Promise<void>;
+/**
+ * Usage fields — aggregated across all agent calls and PATCHed once at
+ * end-of-run. Token counts are Int4 on the DB side (ample for any realistic
+ * run); `costUsd` is a Decimal populated by provider-reported dollar amounts.
+ * Keep in sync with `INT_FIELDS` + `DECIMAL_FIELDS` in the server route.
+ */
+export type WorkflowRunUsagePatchKey = "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "costUsd";
+export type WorkflowRunPatch = Partial<Record<WorkflowRunArtifactPatchKey, string>> & Partial<Record<WorkflowRunUsagePatchKey, number>>;
+/** PATCH workflow-run fields (Pullfrog JWT, not GitHub). */
+export declare function patchWorkflowRunFields(ctx: ToolContext, fields: WorkflowRunPatch): Promise<void>;
+/**
+ * Sum per-agent usage entries into a single WorkflowRunPatch payload.
+ * Returns an empty object when there's nothing to report, which causes
+ * `patchWorkflowRunFields` to no-op — safe to call unconditionally from
+ * end-of-run paths. Zero-valued fields are dropped so the DB only stores
+ * positive sums (and NULL means "not reported").
+ *
+ * Token sums are clamped to INT4_MAX to guarantee the payload the server
+ * sees is always self-consistent across all numeric columns.
+ */
+export declare function aggregateUsage(entries: AgentUsage[]): WorkflowRunPatch;

package/dist/utils/runContext.d.ts

@@ -17,6 +17,7 @@ export interface RepoSettings {
     prApproveEnabled: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;
+    envAllowlist: string | null;
 }
 export interface RunContext {
     settings: RepoSettings;

package/dist/utils/secrets.d.ts

@@ -1,14 +1,21 @@
 /**
  * Secret detection and env filtering utilities
+ *
+ * subprocess env filtering: default-deny allowlist model.
+ * only vars in the safe set or user allowlist are passed to child processes.
+ *
+ * log redaction: SENSITIVE_PATTERNS are used to identify secret values
+ * for redaction in logs and GHA masking (independent of subprocess filtering).
  */
 export declare const SENSITIVE_PATTERNS: RegExp[];
 export declare function isSensitiveEnvName(key: string): boolean;
-/** filter env vars, removing sensitive values (tokens, keys, secrets) */
+export declare function setEnvAllowlist(raw: string): void;
+/** filter env vars using default-deny allowlist: safe set + user allowlist */
 export declare function filterEnv(): Record<string, string>;
 export type EnvMode = "restricted" | "inherit" | Record<string, string>;
 /**
  * resolve env mode to actual env object
- * - "restricted" (default): filterEnv() to prevent secret leakage
+ * - "restricted" (default): filterEnv() — only safe set + user allowlist
  * - "inherit": full process.env
  * - object: custom env merged with restricted base
  */

package/dist/utils/setup.d.ts

@@ -12,6 +12,19 @@ export declare function createTempDirectory(): string;
  * Setup the test repository for running actions
  */
 export declare function setupTestRepo(options: SetupOptions): void;
+/**
+ * remove any `[includeIf ...]` entries from the local git config so that
+ * actions/checkout-persisted credentials don't ride alongside ASKPASS-provided
+ * auth for subsequent git operations.
+ *
+ * SECURITY: git config subsection values can contain arbitrary characters
+ * including `$(...)` command substitutions, and `${IFS}` spacing tricks defeat
+ * naive split-on-space filtering. we read keys via the `-z` (null-terminated)
+ * output format and feed them to a spawn-array `git config --unset-all` so
+ * the shell never interpolates key contents — closing the RCE path that a
+ * string-interpolated `execSync(...)` would expose.
+ */
+export declare function removeIncludeIfEntries(repoDir: string): void;
 export interface GitContext {
     gitToken: string;
     owner: string;