pullfrog 0.0.201 → 0.0.203

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,102 @@
+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;
+};
+/**
+ * decision returned by duplicateReviewDecision when a session has already
+ * submitted a review and the current call would be a duplicate.
+ */
+export type DuplicateReviewDecision = {
+    kind: "already-submitted";
+    reviewId: number;
+    reason: string;
+};
+/**
+ * decide whether a second create_pull_request_review call in the same session
+ * is a duplicate of an earlier submission.
+ *
+ * the agent is instructed to call create_pull_request_review exactly once per
+ * Review-mode session (see action/modes.ts), but in practice it sometimes
+ * submits twice — once with substantive feedback, then again with the
+ * canonical "Reviewed — no issues found." body when the prompt's branch
+ * logic re-classifies non-blocking observations. the second submission is
+ * always redundant: the first review is the record, and the duplicate just
+ * 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
+ * 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
+ * to compare against — is a duplicate.
+ */
+export declare function duplicateReviewDecision(params: {
+    existing: {
+        id: number;
+        reviewedSha: string | undefined;
+    } | undefined;
+    currentCheckoutSha: string | undefined;
+}): DuplicateReviewDecision | null;
+/**
+ * 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 +138,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/models.d.ts

@@ -60,10 +60,27 @@ export declare function getModelEnvVars(slug: string): string[];
 export declare const modelAliases: ModelAlias[];
 /** 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;
+/**
+ * walk the fallback chain to the terminal (non-deprecated) alias.
+ * returns undefined if the chain is broken, exhausted, or cyclic.
+ *
+ * use this in UI display sites (dropdown trigger labels, PR-comment footers,
+ * etc.) so a deprecated stored slug renders as the model the user actually
+ * runs against — not the historical name. selectable lists should still hide
+ * deprecated aliases by filtering on `!a.fallback`.
+ */
+export declare function resolveDisplayAlias(slug: string): ModelAlias | undefined;
 /**
  * resolve a model slug to the CLI-ready model string, following the fallback
  * chain when a model is deprecated. returns the first non-deprecated resolve
  * target, or undefined if the chain is exhausted or broken.
  */
 export declare function resolveCliModel(slug: string): string | undefined;
+/**
+ * resolve a model slug to the OpenRouter-ready model string, following the
+ * fallback chain when a model is deprecated. returns undefined if the chain
+ * is exhausted/broken or the terminal alias has no openrouter equivalent
+ * (e.g. free opencode models).
+ */
+export declare function resolveOpenRouterModel(slug: string): string | undefined;
 export {};

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/skills/git-archaeology/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: git-archaeology
+description: Investigate how code reached its current state — when a line, function, import, or whole file was changed or deleted, who removed it, and what it looked like before. Use when `git blame` came up empty, when content has been refactored away, or when you need the full evolution of a function across commits.
+---
+
+# Git history archaeology
+
+`git blame` only sees what's still in the working tree. For anything that was
+deleted, moved, or refactored away, you need the commands below. Most agents
+under-use them and end up scrolling through `git log -p` instead.
+
+## Output discipline (read first)
+
+`git log -p` on a long-lived file can dump tens of thousands of lines and blow
+the context window. Always:
+
+1. **Start narrow.** Use `--oneline` or `--stat` to get a list of candidate
+   commits.
+2. **Drill in.** Use `git show <sha> -- <path>` for the diff of one specific
+   commit.
+3. **Scope the search.** Add `--since="3 months ago"`, `-n 20`, or a path
+   restriction (`-- <path>`) so output stays manageable.
+4. **Avoid `git log -p` without a path filter** on any non-trivial repo.
+
+## Decision tree (by agent intent)
+
+### "When did this exact line, string, or import disappear?"
+
+```bash
+git log -S'<exact-string>' --oneline -- <file>
+```
+
+The pickaxe. Returns commits that **changed the count** of that string in the
+file. The most recent hit is typically the removal commit. Add `-p` only after
+you've narrowed to a few candidates.
+
+Notes:
+- `-S` is exact-string by default. Add `--pickaxe-regex` to make it a regex.
+- The argument is "cuddled" with `-S` (`-S'foo bar'`), no space.
+- `-S` will not detect pure in-file moves (count unchanged). Use `-G` for that.
+- `--pickaxe-all` shows the entire changeset of matching commits, useful when
+  a commit changes both a definition and its call sites in other files.
+
+### "When did the diff stop matching this regex?"
+
+```bash
+git log -G'<regex>' --oneline -- <file>
+```
+
+Like `-S` but matches any added or removed hunk line against the regex. Use
+`-G` when:
+- You don't know the exact string but know a pattern.
+- You want to catch in-file moves (`-S` won't).
+- You want to find any diff that touched a pattern, even if the count was
+  preserved (e.g., a refactor that changed call sites without removing the
+  function).
+
+### "How did this function evolve over time?"
+
+```bash
+git log -L :<function-name>:<file>
+```
+
+Every commit that touched the function, with diffs scoped to just the function
+body. Works for languages git understands (most mainstream ones).
+
+### "How did lines N–M evolve?"
+
+```bash
+git log -L <N>,<M>:<file>
+```
+
+### "What's the full history of this file, including across renames?"
+
+```bash
+git log --follow --oneline -- <file>      # overview
+git log --follow -p -- <file>             # with diffs (use sparingly)
+```
+
+`--follow` only works for a single file, not directories.
+
+### "Where was a now-deleted line last present?"
+
+Two-step pattern when you have an exact deleted string:
+
+```bash
+# 1. find a historical commit that contained the string
+git log -S'<deleted-string>' --oneline --all -- <file>
+
+# 2. reverse-blame from that commit to find the last commit it survived in
+git blame --reverse <old-sha>..HEAD -- <file>
+```
+
+The reverse blame tells you, for each line, the last commit it survived in
+before being modified or deleted. Pinpoints the exact deletion commit.
+
+### "This file no longer exists — when was it deleted, and what was in it?"
+
+```bash
+# find all commits that touched the path, even on other branches
+git log --all --full-history --oneline -- <deleted-path>
+
+# the most recent of those is usually the deletion. confirm:
+git show <sha> --stat
+
+# view the file's contents at any commit where it existed
+git show <sha>^:<deleted-path>
+```
+
+If you don't know the path, find it from filename alone:
+
+```bash
+# list all delete events with paths
+git log --all --diff-filter=D --summary | grep -i '<filename>'
+
+# or glob across all branches
+git log --all --oneline -- '**/<filename>.*'
+```
+
+### "Who deleted it, in one shot?"
+
+```bash
+git rev-list -n 1 HEAD -- <deleted-path>     # the deletion commit
+git show $(git rev-list -n 1 HEAD -- <deleted-path>) -- <deleted-path>
+```
+
+### "Restore a deleted file (locally, no commit)"
+
+```bash
+git restore --source=<deletion-sha>^ -- <deleted-path>
+# or, on older git:
+git checkout <deletion-sha>^ -- <deleted-path>
+```
+
+The `^` is critical — at the deletion commit the file is already gone, so we
+read from its parent.
+
+### "Search commit messages, not content"
+
+```bash
+git log --all --grep='<text>' --oneline
+git log --all --grep='<text>' -i --oneline    # case-insensitive
+```
+
+Orthogonal to `-S`/`-G`, which only see the diff.
+
+## Standard workflow for "why does this code look like this"
+
+1. `git log --follow --oneline -- <file>` — overview of commits touching it.
+2. If a recent commit looks suspicious: `git show <sha> -- <file>`.
+3. If you expected to find something and it's missing:
+   `git log -S'<expected-string>' --oneline -- <file>`.
+4. For a specific function's full lifecycle:
+   `git log -L :<fn>:<file>`.
+5. For the deletion point of a known string: pickaxe to find an old commit
+   that contained it, then `git blame --reverse <old-sha>..HEAD -- <file>`.
+
+## Useful flags reference
+
+| Flag | Effect |
+|------|--------|
+| `--all` | Search all refs, not just the current branch. Use when investigating something that may have lived only on a feature branch. |
+| `--full-history` | Keeps commits that history-simplification would otherwise drop. Needed for accurate history across merges. |
+| `--follow` | Track a single file across renames. Single-file only. |
+| `-M` / `-C` | Detect renames (`-M`) and copies (`-C`) when reading diffs. |
+| `--diff-filter=D` | Restrict to commits that **deleted** something. `A`=added, `M`=modified, `R`=renamed. |
+| `--source` | When combined with `--all`, annotate each commit with the ref it was reached from. |
+| `--pickaxe-all` | With `-S`/`-G`, show all files in the matching commit, not just the matching file. |
+| `--pickaxe-regex` | Treat the `-S` argument as a regex. |
+| `--since` / `--until` | Time-bound the search. Cheap perf win on big repos. |
+| `-n <count>` | Cap result count. |
+| `--stat` | Per-commit file stats instead of full patches. Good first pass. |
+
+## Notes and pitfalls
+
+- Always include `--` before paths to disambiguate from refs (e.g.
+  `git log -S'foo' -- src/auth.ts`).
+- `-S` triggers on **count change**. A pure refactor that moves a line within
+  the same file will not match. Use `-G` for those.
+- `-G` runs diff twice and greps; it's slower than `-S`. Scope with paths and
+  `--since` on big repos.
+- Without `--all`, `git log -- <path>` shows nothing if the path never existed
+  on the current branch. When in doubt, add `--all`.
+- `git log --full-history -- <path>` alone has had bugs in some git versions
+  for deleted files; pair with `--all` for reliability.
+- For files that were renamed, `git log -- <new-path>` only shows post-rename
+  history. Use `--follow` (one file) or `git log --all -- <old-path>` when
+  hunting across rename events.

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