fix publish workflow: add build step, use OIDC trusted publishing, bump 0.0.196

publish was missing a build step so the npm tarball had no dist/.
switch from NPM_TOKEN to OIDC trusted publishing — explicitly unset
NODE_AUTH_TOKEN so setup-node's .npmrc doesn't override the OIDC flow.
bump version since v0.0.195 tag exists from the failed publish attempt.

Made-with: Cursor

.github/workflows/publish.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Build
+        run: pnpm build
+
       - name: Get package version
         id: version
         run: |
@@ -80,7 +83,7 @@ jobs:
           tag_name: ${{ steps.version.outputs.tag }}
           release_name: "${{ steps.version.outputs.tag }}"
           body: |
-            ## 📦 @pullfrog/pullfrog ${{ steps.version.outputs.version }}
+            ## 📦 pullfrog ${{ steps.version.outputs.version }}
 
             ### Usage in GitHub Actions
 
@@ -91,16 +94,14 @@ jobs:
             ### Installation via npm
 
             ```bash
-            npm install @pullfrog/pullfrog@${{ steps.version.outputs.version }}
+            npm install pullfrog@${{ steps.version.outputs.version }}
             ```
           draft: false
           prerelease: false
 
-      # - name: Publish to npm
-      #   if: steps.check_tag.outputs.exists == 'false'
-      #   run: npm publish --access public
-      #   env:
-      #     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish to npm
+        if: steps.check_tag.outputs.exists == 'false'
+        run: NODE_AUTH_TOKEN="" npm publish --provenance --access public
 
       - name: Summary
         if: always()
@@ -118,5 +119,5 @@ jobs:
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "### 📦 Published to" >> $GITHUB_STEP_SUMMARY
             echo "- GitHub Release: [View Release](https://github.com/${{ github.repository }}/releases/tag/${{ steps.version.outputs.tag }})" >> $GITHUB_STEP_SUMMARY
-            echo "- npm Registry: [@pullfrog/pullfrog@${{ steps.version.outputs.version }}](https://www.npmjs.com/package/@pullfrog/pullfrog/v/${{ steps.version.outputs.version }})" >> $GITHUB_STEP_SUMMARY
+            echo "- npm Registry: [pullfrog@${{ steps.version.outputs.version }}](https://www.npmjs.com/package/pullfrog/v/${{ steps.version.outputs.version }})" >> $GITHUB_STEP_SUMMARY
           fi

.husky/pre-commit

@@ -1,8 +0,0 @@
-# sync action lockfile when action/package.json changes
-if git diff --cached --name-only | grep -q "^action/package.json$"; then
-    echo "🔒 syncing action/pnpm-lock.yaml..."
-    # note: pnpm -C action install will *not* treat "action" as a monorepo root if run from repo root;
-    # to install with action/ as the workspace root (and search upwards), cd into action first:
-    (cd action && pnpm install --no-frozen-lockfile)
-    git add action/pnpm-lock.yaml
-fi

action.yml

@@ -35,8 +35,8 @@ outputs:
 
 runs:
   using: "node24"
-  main: "entry"
-  post: "post"
+  main: "entry.ts"
+  post: "post.ts"
   post-if: "failure() || cancelled()"
 
 branding:

cli.ts

@@ -0,0 +1,104 @@
+import { basename } from "node:path";
+import arg from "arg";
+import pc from "picocolors";
+import { runCli as runGhaCli } from "./commands/gha.ts";
+import { runCli as runInitCli } from "./commands/init.ts";
+
+const VERSION = process.env.CLI_VERSION ?? "0.0.0";
+const bin = basename(process.argv[1] || "");
+const PROG = bin === "pf" || bin === "pullfrog" ? bin : "pullfrog";
+const rawArgs = process.argv.slice(2);
+
+function printMainUsage(stream: typeof console.log): void {
+  stream(`usage: ${PROG} <command>\n`);
+  stream("commands:");
+  stream("  init        set up pullfrog on the current repository");
+  stream("");
+  stream("global options:");
+  stream("  -h, --help      show help");
+  stream("  -v, --version   show version");
+}
+
+function parseGlobalArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--version": Boolean,
+      "-h": "--help",
+      "-v": "--version",
+    },
+    {
+      argv: args,
+      stopAtPositional: true,
+    }
+  );
+}
+
+function exitWithUsageError(message: string): never {
+  console.error(`${message}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+async function run(): Promise<void> {
+  let globalParsed: ReturnType<typeof parseGlobalArgs>;
+  try {
+    globalParsed = parseGlobalArgs(rawArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithUsageError(message);
+  }
+
+  if (globalParsed["--version"]) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  const command = globalParsed._[0];
+  const commandArgs = globalParsed._.slice(1);
+
+  if (!command) {
+    if (globalParsed["--help"]) {
+      console.log(`${pc.bold("pullfrog")} v${VERSION}\n`);
+      printMainUsage(console.log);
+      process.exit(0);
+    }
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  if (command === "init") {
+    await runInitCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (command === "gha") {
+    await runGhaCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (globalParsed["--help"]) {
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  console.error(`unknown command: ${pc.bold(command)}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+try {
+  await run();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(pc.red(message));
+  process.exit(1);
+}

commands/gha.ts

@@ -0,0 +1,162 @@
+import { dirname } from "node:path";
+import * as core from "@actions/core";
+import arg from "arg";
+import { main } from "../main.ts";
+import { log } from "../utils/cli.ts";
+import { runPostCleanup } from "../utils/postCleanup.ts";
+import { acquireInstallationToken, revokeInstallationToken } from "../utils/token.ts";
+
+// GitHub Actions runs the action entry point with the node24 binary specified
+// in action.yml, but doesn't add that binary's directory to PATH. Without this,
+// spawned processes (pnpm, npm, etc.) resolve to the runner's default node (v20).
+process.env.PATH = `${dirname(process.execPath)}:${process.env.PATH}`;
+
+const STATE_TOKEN = "token";
+
+interface GhaCliParams {
+  args: string[];
+  prog: string;
+  showHelp?: boolean;
+}
+
+async function runMain(): Promise<void> {
+  try {
+    const result = await main();
+    if (!result.success) {
+      throw new Error(result.error || "agent execution failed");
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "unknown error occurred";
+    core.setFailed(`action failed: ${errorMessage}`);
+  }
+}
+
+async function runPost(): Promise<void> {
+  log.debug(`[post] script started at ${new Date().toISOString()}`);
+  try {
+    await runPostCleanup();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(`[post] unexpected error: ${message}`);
+  }
+}
+
+async function tokenMain(): Promise<void> {
+  const reposInput = core.getInput("repos");
+  const additionalRepos = reposInput
+    ? reposInput
+        .split(",")
+        .map((r) => r.trim())
+        .filter(Boolean)
+    : [];
+
+  const token = await acquireInstallationToken({ repos: additionalRepos });
+
+  core.setSecret(token);
+  core.saveState(STATE_TOKEN, token);
+  core.setOutput("token", token);
+
+  const scope = additionalRepos.length
+    ? `current repo + ${additionalRepos.join(", ")}`
+    : "current repo only";
+  core.info(`» installation token acquired (${scope})`);
+}
+
+async function tokenPost(): Promise<void> {
+  const token = core.getState(STATE_TOKEN);
+  if (!token) {
+    core.debug("no token found in state, skipping revocation");
+    return;
+  }
+  await revokeInstallationToken(token);
+  core.info("» installation token revoked");
+}
+
+function printGhaUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} gha [token] [--post]\n`);
+  params.stream("run the github action runtime flow.");
+  params.stream("");
+  params.stream("subcommands:");
+  params.stream("  token        acquire a github app installation token");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+  params.stream("  --post       run post-cleanup flow");
+}
+
+function parseGhaArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--post": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+    }
+  );
+}
+
+export async function runCli(params: GhaCliParams): Promise<void> {
+  if (params.showHelp) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  let parsed: ReturnType<typeof parseGhaArgs>;
+  try {
+    parsed = parseGhaArgs(params.args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--help"]) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  const normalizedArgs = ["gha"];
+  const positional = parsed._;
+
+  if (positional.length > 1) {
+    console.error(`unexpected positional arguments for gha: ${positional.slice(1).join(" ")}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (positional[0] === "token") {
+    normalizedArgs.push("token");
+  } else if (positional[0]) {
+    console.error(`unknown gha subcommand: ${positional[0]}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--post"]) {
+    normalizedArgs.push("--post");
+  }
+
+  await run(normalizedArgs);
+}
+
+export async function run(args: string[]) {
+  try {
+    if (args.includes("token")) {
+      if (args.includes("--post")) {
+        await tokenPost();
+      } else {
+        await tokenMain();
+      }
+    } else if (args.includes("--post")) {
+      await runPost();
+    } else {
+      await runMain();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    core.setFailed(message);
+  }
+}

commands/init.ts

@@ -0,0 +1,964 @@
+import { execFileSync } from "node:child_process";
+import * as p from "@clack/prompts";
+import arg from "arg";
+import pc from "picocolors";
+import { modelAliases, type ProviderConfig, providers } from "../models.ts";
+
+const PULLFROG_API_URL = (process.env.PULLFROG_API_URL || "https://pullfrog.com").replace(
+  /\/+$/,
+  ""
+);
+
+function link(text: string, url: string): string {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+
+type CliProvider = {
+  id: string;
+  name: string;
+  envVars: readonly string[];
+  models: { value: string; label: string; hint?: string | undefined }[];
+};
+
+function buildProviders(): CliProvider[] {
+  return Object.entries(providers)
+    .filter(([key]) => key !== "opencode" && key !== "openrouter")
+    .map(([key, config]: [string, ProviderConfig]) => {
+      const aliases = modelAliases.filter((a) => a.provider === key);
+      const recommended = aliases.find((a) => a.preferred);
+      const sorted = [...aliases].sort((a, b) => {
+        if (a.preferred && !b.preferred) return -1;
+        if (!a.preferred && b.preferred) return 1;
+        return 0;
+      });
+      return {
+        id: key,
+        name: config.displayName,
+        envVars: config.envVars,
+        models: sorted.map((a) => ({
+          value: a.slug,
+          label: a.displayName,
+          hint: a === recommended ? "recommended" : undefined,
+        })),
+      };
+    });
+}
+
+const CLI_PROVIDERS = buildProviders();
+
+function resolveModelProvider(slug: string): CliProvider | null {
+  const providerId = slug.split("/")[0];
+  return CLI_PROVIDERS.find((p) => p.id === providerId) ?? null;
+}
+
+// ── helpers ──
+
+// active spinner reference so bail/catch can clean up the terminal
+let activeSpin: ReturnType<typeof p.spinner> | null = null;
+
+function bail(msg: string): never {
+  if (activeSpin) {
+    activeSpin.stop(pc.red("failed"));
+    activeSpin = null;
+  }
+  p.cancel(msg);
+  process.exit(1);
+}
+
+function handleCancel<T>(value: T | symbol): asserts value is T {
+  if (p.isCancel(value)) {
+    if (activeSpin) {
+      activeSpin.stop(pc.red("canceled."));
+      activeSpin = null;
+    }
+    p.cancel("canceled.");
+    process.exit(0);
+  }
+}
+
+function getGhToken(): string {
+  let token: string;
+  try {
+    token = execFileSync("gh", ["auth", "token"], { encoding: "utf-8" }).trim();
+  } catch {
+    bail(
+      `gh cli not found or not authenticated.\n` +
+        `  ${pc.dim("install:")} https://cli.github.com\n` +
+        `  ${pc.dim("then:")}    gh auth login`
+    );
+  }
+  if (!token) {
+    bail(
+      `gh cli returned an empty token. try re-authenticating:\n` +
+        `  ${pc.dim("run:")} gh auth login`
+    );
+  }
+  return token;
+}
+
+type GhApiResult<T = unknown> = { data: T; scopes: string | null };
+
+async function ghApi<T = unknown>(path: string, token: string): Promise<GhApiResult<T>> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30_000);
+  try {
+    const response = await fetch(`https://api.github.com${path}`, {
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+      },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(`github api ${path} returned ${response.status}: ${body}`);
+    }
+
+    const data = (await response.json().catch(() => {
+      throw new Error(`github api ${path} returned non-JSON response`);
+    })) as T;
+    return { data, scopes: response.headers.get("x-oauth-scopes") };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function parseGitRemote(): { owner: string; repo: string } {
+  let url: string;
+  try {
+    url = execFileSync("git", ["remote", "get-url", "origin"], { encoding: "utf-8" }).trim();
+  } catch {
+    bail("not a git repository or no 'origin' remote found.");
+  }
+
+  const match = url.match(/github\.com(?::\d+)?[:/]+([^/]+)\/(.+?)(?:\.git)?(?:\/)?$/);
+  if (!match) bail(`could not parse github owner/repo from remote: ${url}`);
+  return { owner: match[1], repo: match[2] };
+}
+
+function openBrowser(url: string) {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") execFileSync("open", [url], { stdio: "ignore" });
+    else if (platform === "win32")
+      execFileSync("cmd", ["/c", "start", "", url], { stdio: "ignore" });
+    else execFileSync("xdg-open", [url], { stdio: "ignore" });
+  } catch {
+    // headless/SSH — user will open the URL manually
+  }
+}
+
+// ── Pullfrog API ──
+
+type SecretsApiData = {
+  error?: string;
+  appSlug?: string;
+  installationId?: number | null;
+  repositorySelection?: string | null;
+  isOrg?: boolean;
+  accessible?: boolean;
+  repoSecrets?: string[];
+  orgSecrets?: string[];
+  pullfrogSecrets?: string[];
+  repoStatus?: string | null;
+  repoModel?: string | null;
+  hasRuns?: boolean;
+};
+
+type SecretsInfo = {
+  isOrg: boolean;
+  installationId: number | null;
+  secretsAccessible: boolean;
+  repoSecrets: string[];
+  orgSecrets: string[];
+  pullfrogSecrets: string[];
+  model: string | null;
+  hasRuns: boolean;
+};
+
+type InstallationNotFound = {
+  appSlug: string;
+  installationId: number | null;
+  repositorySelection: "all" | "selected" | null;
+  isOrg: boolean;
+};
+
+type StatusResult =
+  | ({ installed: true } & SecretsInfo)
+  | ({ installed: false } & InstallationNotFound);
+
+type SessionApiData = {
+  id?: string;
+  installed?: boolean;
+  error?: string;
+};
+
+type SetupApiData = {
+  error?: string;
+  success?: boolean;
+  already_existed?: boolean;
+  pull_request_url?: string;
+  commit_url?: string;
+  hash?: string;
+};
+
+type DispatchApiData = {
+  error?: string;
+  url?: string;
+};
+
+type ApiResult<T = Record<string, unknown>> = { ok: boolean; status: number; data: T };
+
+async function pullfrogApi<T = Record<string, unknown>>(ctx: {
+  path: string;
+  token: string;
+  method?: string;
+  body?: Record<string, unknown>;
+}): Promise<ApiResult<T>> {
+  const headers: Record<string, string> = { authorization: `Bearer ${ctx.token}` };
+  if (ctx.body) headers["content-type"] = "application/json";
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30_000);
+  try {
+    const response = await fetch(`${PULLFROG_API_URL}${ctx.path}`, {
+      method: ctx.method || "GET",
+      headers,
+      body: ctx.body ? JSON.stringify(ctx.body) : null,
+      signal: controller.signal,
+    });
+    const data = (await response.json().catch(() => ({}))) as T;
+    return { ok: response.ok, status: response.status, data };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function fetchStatus(ctx: {
+  token: string;
+  owner: string;
+  repo: string;
+}): Promise<StatusResult> {
+  const result = await pullfrogApi<SecretsApiData>({
+    path: `/api/cli/secrets?owner=${encodeURIComponent(ctx.owner)}&repo=${encodeURIComponent(ctx.repo)}`,
+    token: ctx.token,
+  });
+
+  if (!result.ok) {
+    const errorMsg = result.data.error || "";
+    if (result.status === 401) bail("invalid or expired github token.");
+    if (result.status === 404) {
+      const sel = result.data.repositorySelection;
+      if (!result.data.appSlug) bail("server did not return appSlug");
+      return {
+        installed: false,
+        appSlug: result.data.appSlug,
+        installationId:
+          typeof result.data.installationId === "number" ? result.data.installationId : null,
+        repositorySelection: sel === "all" || sel === "selected" ? sel : null,
+        isOrg: result.data.isOrg === true,
+      };
+    }
+    bail(errorMsg || `secrets check failed (${result.status})`);
+  }
+
+  return {
+    installed: true,
+    isOrg: result.data.isOrg === true,
+    installationId:
+      typeof result.data.installationId === "number" ? result.data.installationId : null,
+    secretsAccessible: result.data.accessible !== false,
+    repoSecrets: result.data.repoSecrets || [],
+    orgSecrets: result.data.orgSecrets || [],
+    pullfrogSecrets: result.data.pullfrogSecrets || [],
+    model: result.data.repoModel ?? null,
+    hasRuns: result.data.hasRuns === true,
+  };
+}
+
+// ── sessions ──
+
+async function createSession(ctx: {
+  token: string;
+  owner: string;
+  repo: string;
+}): Promise<string | null> {
+  try {
+    const result = await pullfrogApi<SessionApiData>({
+      path: "/api/cli/session",
+      token: ctx.token,
+      method: "POST",
+      body: { owner: ctx.owner.toLowerCase(), repo: ctx.repo.toLowerCase() },
+    });
+    if (!result.ok || !result.data.id) return null;
+    return result.data.id;
+  } catch {
+    return null;
+  }
+}
+
+type PollResult = "installed" | "pending" | "expired";
+
+async function pollSession(ctx: { token: string; sessionId: string }): Promise<PollResult> {
+  const result = await pullfrogApi<SessionApiData>({
+    path: `/api/cli/session/${ctx.sessionId}`,
+    token: ctx.token,
+  });
+  if (result.status === 410) return "expired";
+  if (!result.ok) return "pending";
+  return result.data.installed === true ? "installed" : "pending";
+}
+
+function cleanupSession(ctx: { token: string; sessionId: string }) {
+  void pullfrogApi({
+    path: `/api/cli/session/${ctx.sessionId}`,
+    token: ctx.token,
+    method: "DELETE",
+  }).catch(() => {});
+}
+
+// ── installation ──
+
+const SESSION_POLL_MS = 750;
+const FALLBACK_POLL_MS = 5_000;
+const HINT_AFTER_MS = 10_000;
+const TIMEOUT_MS = 3 * 60 * 1000;
+
+function listenForKey(key: string) {
+  let triggered = false;
+  const onData = (data: Buffer) => {
+    if (data.toString().toLowerCase() === key) triggered = true;
+  };
+  process.stdin.setRawMode?.(true);
+  process.stdin.resume();
+  process.stdin.on("data", onData);
+  return {
+    consume() {
+      if (!triggered) return false;
+      triggered = false;
+      return true;
+    },
+    stop() {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode?.(false);
+      process.stdin.pause();
+    },
+  };
+}
+
+function installationConfigUrl(ctx: { owner: string; installationId: number; isOrg: boolean }) {
+  return ctx.isOrg
+    ? `https://github.com/organizations/${ctx.owner}/settings/installations/${ctx.installationId}`
+    : `https://github.com/settings/installations/${ctx.installationId}`;
+}
+
+async function ensureInstallation(ctx: {
+  token: string;
+  owner: string;
+  repo: string;
+}): Promise<SecretsInfo> {
+  activeSpin!.start("checking pullfrog app installation");
+
+  const initial = await fetchStatus(ctx);
+  if (initial.installed) {
+    activeSpin!.stop(`pullfrog app is installed on ${pc.cyan(`@${ctx.owner}`)}`);
+    if (initial.installationId) {
+      const configUrl = installationConfigUrl({
+        owner: ctx.owner,
+        installationId: initial.installationId,
+        isOrg: initial.isOrg,
+      });
+      process.stdout.write(`${pc.gray(p.S_BAR)}    ${link(pc.dim(configUrl), configUrl)}\n`);
+    }
+    return initial;
+  }
+
+  const sessionId = await createSession(ctx);
+
+  if (initial.installationId) {
+    const repoRef = pc.bold(`${ctx.owner}/${ctx.repo}`);
+    const configUrl = installationConfigUrl({
+      owner: ctx.owner,
+      installationId: initial.installationId,
+      isOrg: initial.isOrg,
+    });
+    activeSpin!.stop(`pullfrog is installed on selected repos, but ${repoRef} is not included.`);
+    p.log.info(
+      `add it under "Repository access" on the installation config page.\n  ${pc.dim(configUrl)}`
+    );
+    const openIt = await p.confirm({ message: "open browser?", active: "yes", inactive: "no" });
+    handleCancel(openIt);
+    if (openIt) openBrowser(configUrl);
+  } else {
+    activeSpin!.stop("pullfrog app not installed");
+    const installUrl = `https://github.com/apps/${initial.appSlug}/installations/select_target?state=cli`;
+    p.log.info(`opening browser to install...\n  ${pc.dim(installUrl)}`);
+    openBrowser(installUrl);
+  }
+
+  const isRepoAccessUpdate = !!initial.installationId;
+  const baseMsg = isRepoAccessUpdate
+    ? "once you've added the repo, onboarding will proceed automatically"
+    : "once you've installed the app, onboarding will proceed automatically";
+  activeSpin!.start(baseMsg);
+
+  let activeSessionId = sessionId;
+  let pollMs = activeSessionId ? SESSION_POLL_MS : FALLBACK_POLL_MS;
+  const listener = listenForKey("r");
+  const startedAt = Date.now();
+  let hintShown = false;
+
+  try {
+    while (Date.now() - startedAt < TIMEOUT_MS) {
+      await new Promise((r) => setTimeout(r, pollMs));
+
+      if (!hintShown && Date.now() - startedAt > HINT_AFTER_MS) {
+        activeSpin!.message(`${baseMsg} ${pc.dim("(press r to recheck manually)")}`);
+        hintShown = true;
+      }
+
+      const doneMsg = isRepoAccessUpdate ? "repo access confirmed" : "pullfrog app installed";
+
+      if (listener.consume()) {
+        activeSpin!.message("rechecking via GitHub API");
+        try {
+          const status = await fetchStatus(ctx);
+          if (status.installed) {
+            if (activeSessionId) cleanupSession({ token: ctx.token, sessionId: activeSessionId });
+            activeSpin!.stop(doneMsg);
+            return status;
+          }
+        } catch {
+          // network error — keep going
+        }
+        activeSpin!.message(`${baseMsg} ${pc.dim("(press r to recheck manually)")}`);
+        continue;
+      }
+
+      if (activeSessionId) {
+        // fast path: lightweight DB session poll (no GitHub API calls)
+        try {
+          const result = await pollSession({ token: ctx.token, sessionId: activeSessionId });
+          if (result === "expired") {
+            activeSessionId = null;
+            pollMs = FALLBACK_POLL_MS;
+            continue;
+          }
+          if (result === "installed") {
+            const status = await fetchStatus(ctx);
+            if (status.installed) {
+              cleanupSession({ token: ctx.token, sessionId: activeSessionId });
+              activeSpin!.stop(doneMsg);
+              return status;
+            }
+          }
+        } catch {
+          // transient error — keep polling
+        }
+      } else {
+        // no session available — poll fetchStatus directly at slower interval
+        try {
+          const status = await fetchStatus(ctx);
+          if (status.installed) {
+            activeSpin!.stop(doneMsg);
+            return status;
+          }
+        } catch {
+          // transient error — keep polling
+        }
+      }
+    }
+  } finally {
+    listener.stop();
+  }
+
+  if (activeSessionId) cleanupSession({ token: ctx.token, sessionId: activeSessionId });
+  bail(
+    isRepoAccessUpdate
+      ? "timed out waiting for repo access.\n" +
+          `  ${pc.dim("add the repo, then re-run:")} npx pullfrog init`
+      : "timed out waiting for app installation.\n" +
+          `  ${pc.dim("if your org requires admin approval, ask an admin to approve,")}\n` +
+          `  ${pc.dim("then re-run:")} npx pullfrog init`
+  );
+}
+
+// ── secret management ──
+
+type StorageMethod = "pullfrog" | "github";
+type SecretScope = "account" | "repo";
+
+type SecretSetResult = { saved: boolean; orgFailed: boolean };
+
+function setGhSecret(ctx: {
+  name: string;
+  value: string;
+  org: string | null;
+  repoSlug: string;
+}): SecretSetResult {
+  let orgFailed = false;
+
+  if (ctx.org) {
+    try {
+      execFileSync("gh", ["secret", "set", ctx.name, "--org", ctx.org, "--visibility", "all"], {
+        input: ctx.value,
+        stdio: ["pipe", "ignore", "pipe"],
+        encoding: "utf-8",
+      });
+      return { saved: true, orgFailed: false };
+    } catch {
+      orgFailed = true;
+    }
+  }
+
+  try {
+    execFileSync("gh", ["secret", "set", ctx.name, "--repo", ctx.repoSlug], {
+      input: ctx.value,
+      stdio: ["pipe", "ignore", "pipe"],
+      encoding: "utf-8",
+    });
+    return { saved: true, orgFailed };
+  } catch {
+    return { saved: false, orgFailed };
+  }
+}
+
+type PullfrogSecretResult = { saved: boolean; error: string };
+
+async function setPullfrogSecret(ctx: {
+  token: string;
+  owner: string;
+  repo: string;
+  name: string;
+  value: string;
+  scope: SecretScope;
+}): Promise<PullfrogSecretResult> {
+  const result = await pullfrogApi<{ success?: boolean; error?: string }>({
+    path: "/api/cli/secrets",
+    token: ctx.token,
+    method: "POST",
+    body: {
+      owner: ctx.owner,
+      repo: ctx.repo,
+      name: ctx.name,
+      value: ctx.value,
+      scope: ctx.scope,
+    },
+  });
+  if (result.ok && result.data.success === true) {
+    return { saved: true, error: "" };
+  }
+  return { saved: false, error: result.data.error || `api returned ${result.status}` };
+}
+
+async function promptScope(ctx: { owner: string; repo: string }): Promise<SecretScope> {
+  const scope = await p.select<SecretScope>({
+    message: "secret scope",
+    options: [
+      { value: "account", label: `${ctx.owner} organization`, hint: "shared across repos" },
+      { value: "repo", label: `${ctx.owner}/${ctx.repo} only` },
+    ],
+  });
+  handleCancel(scope);
+  return scope;
+}
+
+async function handleSecret(ctx: {
+  token: string;
+  owner: string;
+  repo: string;
+  provider: CliProvider;
+  secrets: SecretsInfo;
+}): Promise<void> {
+  const repoSecretsUrl = `https://github.com/${ctx.owner}/${ctx.repo}/settings/secrets/actions`;
+
+  const matches: { name: string; source: string }[] = [];
+  for (const v of ctx.provider.envVars) {
+    if (ctx.secrets.pullfrogSecrets.includes(v)) matches.push({ name: v, source: "pullfrog" });
+    else if (ctx.secrets.secretsAccessible && ctx.secrets.orgSecrets.includes(v))
+      matches.push({ name: v, source: "org secret" });
+    else if (ctx.secrets.secretsAccessible && ctx.secrets.repoSecrets.includes(v))
+      matches.push({ name: v, source: "repo secret" });
+  }
+
+  if (matches.length > 0) {
+    activeSpin!.start("");
+    activeSpin!.stop("secrets already configured");
+    for (const m of matches) {
+      process.stdout.write(
+        `${pc.gray(p.S_BAR)}    ${pc.cyan(m.name)} ${pc.dim(`(${m.source})`)}\n`
+      );
+    }
+    return;
+  }
+
+  if (!ctx.secrets.secretsAccessible) {
+    p.log.info(`could not verify GitHub secrets (app lacks permission)`);
+  }
+
+  const hasOAuthOption = ctx.provider.envVars.includes("CLAUDE_CODE_OAUTH_TOKEN");
+  let envVar = ctx.provider.envVars[0];
+
+  if (hasOAuthOption) {
+    const authMethod = await p.select({
+      message: "which credential do you want to use?",
+      options: [
+        {
+          value: "oauth",
+          label: "Claude Code OAuth token",
+          hint: `run ${pc.cyan("claude setup-token")} — works with Pro/Max subscriptions`,
+        },
+        {
+          value: "api",
+          label: "Anthropic API key",
+          hint: "from console.anthropic.com",
+        },
+      ],
+    });
+    handleCancel(authMethod);
+    if (authMethod === "oauth") envVar = "CLAUDE_CODE_OAUTH_TOKEN";
+  }
+
+  const method = await p.select<StorageMethod>({
+    message: `where should ${pc.cyan(envVar)} be stored?`,
+    options: [
+      {
+        value: "pullfrog",
+        label: "Pullfrog",
+        hint: "recommended — auto-injected, no workflow changes",
+      },
+      {
+        value: "github",
+        label: "GitHub Actions secret",
+        hint: "requires env block in pullfrog.yml",
+      },
+    ],
+  });
+  handleCancel(method);
+
+  const pasteLabel =
+    envVar === "CLAUDE_CODE_OAUTH_TOKEN" ? "OAuth token" : `${ctx.provider.name} API key`;
+  const apiKey = await p.password({
+    message: `paste your ${pasteLabel} ${pc.dim("(Enter to skip)")}`,
+    mask: "*",
+    validate: () => undefined,
+  });
+  handleCancel(apiKey);
+
+  if (!apiKey) {
+    p.log.info(
+      `skipped — set it manually at:\n  ${pc.dim(method === "pullfrog" ? `${PULLFROG_API_URL}/console/${ctx.owner}` : repoSecretsUrl)}`
+    );
+    return;
+  }
+
+  if (method === "pullfrog") {
+    const scope: SecretScope = ctx.secrets.isOrg ? await promptScope(ctx) : "account";
+
+    activeSpin!.start(`saving ${envVar}`);
+    let saveResult: PullfrogSecretResult;
+    try {
+      saveResult = await setPullfrogSecret({
+        token: ctx.token,
+        owner: ctx.owner,
+        repo: ctx.repo,
+        name: envVar,
+        value: apiKey,
+        scope,
+      });
+    } catch (error) {
+      activeSpin!.stop(pc.red("could not save secret"));
+      p.log.warn(
+        `${error instanceof Error ? error.message : "network error"}\n  set it manually at: ${pc.dim(`${PULLFROG_API_URL}/console/${ctx.owner}`)}`
+      );
+      return;
+    }
+
+    if (saveResult.saved) {
+      activeSpin!.stop(`saved ${pc.cyan(envVar)} to Pullfrog`);
+    } else {
+      activeSpin!.stop(pc.red("could not save secret"));
+      p.log.warn(
+        `${saveResult.error}\n  set it manually at: ${pc.dim(`${PULLFROG_API_URL}/console/${ctx.owner}`)}`
+      );
+    }
+    return;
+  }
+
+  // github actions secret path
+  let org: string | null = null;
+  if (ctx.secrets.isOrg) {
+    const scope = await promptScope(ctx);
+    org = scope === "account" ? ctx.owner : null;
+  }
+
+  const secretsUrl = org
+    ? `https://github.com/organizations/${org}/settings/secrets/actions`
+    : repoSecretsUrl;
+
+  activeSpin!.start(`saving ${envVar}`);
+  const secretResult = setGhSecret({
+    name: envVar,
+    value: apiKey,
+    org,
+    repoSlug: `${ctx.owner}/${ctx.repo}`,
+  });
+  if (secretResult.saved) {
+    activeSpin!.stop(
+      `saved ${pc.cyan(envVar)} to ${org && !secretResult.orgFailed ? `${pc.dim(ctx.owner)} org secret` : "GitHub Actions secret"}`
+    );
+    if (secretResult.orgFailed) {
+      p.log.warn("org secret failed (admin access required) — saved as repo secret instead");
+    }
+  } else {
+    activeSpin!.stop(pc.red("could not set secret"));
+    p.log.warn(`set it manually at:\n  ${pc.dim(secretsUrl)}`);
+  }
+}
+
+async function promptTestRun(ctx: { token: string; owner: string; repo: string }): Promise<void> {
+  const proceed = await p.select({
+    message: "test your installation?",
+    options: [
+      { value: true, label: "yes", hint: "dispatches a test run in your GitHub Actions" },
+      { value: false, label: "skip" },
+    ],
+  });
+  handleCancel(proceed);
+  if (!proceed) return;
+
+  activeSpin!.start("dispatching test run");
+  const result = await pullfrogApi<DispatchApiData>({
+    path: "/api/cli/dispatch",
+    token: ctx.token,
+    method: "POST",
+    body: { owner: ctx.owner, repo: ctx.repo, prompt: "Tell me a joke" },
+  });
+
+  if (!result.ok) {
+    activeSpin!.stop(pc.red("could not dispatch"));
+    p.log.warn(result.data.error || `dispatch failed (${result.status})`);
+    return;
+  }
+
+  activeSpin!.stop("dispatched test run");
+  if (result.data.url) {
+    process.stdout.write(
+      `${pc.gray(p.S_BAR)}    ${link(pc.dim(result.data.url), result.data.url)}\n`
+    );
+    openBrowser(result.data.url);
+  }
+}
+
+// ── main ──
+
+async function main() {
+  p.intro(pc.bgGreen(pc.black(" pullfrog ")));
+
+  const spin = p.spinner();
+  activeSpin = spin;
+
+  // 1. authenticate
+  spin.start("authenticating with github");
+  const token = getGhToken();
+  const userResult = await ghApi<{ login: string }>("/user", token);
+  const user = userResult.data;
+
+  // gho_ tokens from `gh auth login` expose scopes via x-oauth-scopes header.
+  // fine-grained PATs (github_pat_) don't return scopes — they pass this check.
+  // split on ", " and match exact scope — .includes("repo") would false-positive on "public_repo"
+  const scopeSet = userResult.scopes !== null ? new Set(userResult.scopes.split(", ")) : null;
+  if (scopeSet !== null && !scopeSet.has("repo")) {
+    bail(
+      `your token is missing the ${pc.bold('"repo"')} scope.\n` +
+        `  ${pc.dim("run:")} gh auth refresh --scopes repo\n` +
+        `  ${pc.dim("then:")} npx pullfrog init`
+    );
+  }
+
+  spin.stop(`hello, ${pc.cyan(`@${user.login}`)}`);
+
+  // 2. detect repo
+  spin.start("detecting repository");
+  const remote = parseGitRemote();
+  spin.stop(`detected repo ${pc.cyan(`${remote.owner}/${remote.repo}`)}`);
+
+  // 3. ensure app installation + check secrets
+  const secrets = await ensureInstallation({ token, owner: remote.owner, repo: remote.repo });
+
+  // 4. select provider + model (skip if already set)
+  let model: string;
+  let provider: CliProvider;
+
+  if (secrets.model) {
+    model = secrets.model;
+    const resolved = resolveModelProvider(secrets.model);
+    if (!resolved) bail(`unknown model provider: ${secrets.model}`);
+    provider = resolved;
+    spin.start("");
+    spin.stop(`using model ${pc.cyan(secrets.model)}`);
+  } else {
+    const providerId = await p.select({
+      message: "select your preferred model provider",
+      options: CLI_PROVIDERS.map((cp) => ({
+        value: cp.id,
+        label: cp.name,
+      })),
+    });
+    handleCancel(providerId);
+
+    const found = CLI_PROVIDERS.find((cp) => cp.id === providerId);
+    if (!found) bail(`unknown provider: ${providerId}`);
+    provider = found;
+
+    if (provider.models.length === 1) {
+      model = provider.models[0].value;
+      spin.start("");
+      spin.stop(`using ${pc.bold(provider.models[0].label)}`);
+    } else {
+      const recommendedModel = provider.models.find((m) => m.hint === "recommended");
+      const options = provider.models.map((m) => {
+        if (m.hint) return { value: m.value, label: m.label, hint: m.hint };
+        return { value: m.value, label: m.label };
+      });
+      const selected = await p.select(
+        recommendedModel
+          ? { message: "select model", initialValue: recommendedModel.value, options }
+          : { message: "select model", options }
+      );
+      handleCancel(selected);
+      model = selected;
+    }
+  }
+
+  // 5. check/set secret
+  await handleSecret({ token, owner: remote.owner, repo: remote.repo, provider, secrets });
+
+  // 6. create workflow
+  spin.start("creating pullfrog.yml workflow");
+
+  const result = await pullfrogApi<SetupApiData>({
+    path: "/api/cli/setup",
+    token,
+    method: "POST",
+    body: { owner: remote.owner, repo: remote.repo, model },
+  });
+
+  if (!result.ok) {
+    bail(result.data.error || `api returned ${result.status}`);
+  }
+
+  let skipTestRun = false;
+
+  if (result.data.already_existed) {
+    spin.stop("pullfrog.yml already exists");
+  } else if (result.data.pull_request_url) {
+    spin.stop("opened pull request with pullfrog.yml");
+    process.stdout.write(
+      `${pc.gray(p.S_BAR)}    ${link(pc.dim(result.data.pull_request_url), result.data.pull_request_url)}\n`
+    );
+    openBrowser(result.data.pull_request_url);
+
+    const merged = await p.select({
+      message: "merge the PR to activate pullfrog, then continue",
+      options: [
+        { value: true, label: "continue", hint: "PR has been merged" },
+        { value: false, label: "skip" },
+      ],
+    });
+    handleCancel(merged);
+    if (!merged) skipTestRun = true;
+  } else {
+    const short = result.data.hash?.slice(0, 7);
+    spin.stop(
+      short ? `committed pullfrog.yml to repo ${pc.dim(short)}` : "committed pullfrog.yml to repo"
+    );
+  }
+
+  if (!skipTestRun && !secrets.hasRuns) {
+    await promptTestRun({ token, owner: remote.owner, repo: remote.repo });
+  }
+
+  const consoleUrl = `${PULLFROG_API_URL}/console/${remote.owner}/${remote.repo}`;
+  spin.start("");
+  spin.stop("repo is configurable via the Pullfrog dashboard");
+  process.stdout.write(`${pc.gray(p.S_BAR)}    ${link(pc.dim(consoleUrl), consoleUrl)}\n`);
+  activeSpin = null;
+  p.outro("done.");
+}
+
+interface InitCliParams {
+  args: string[];
+  prog: string;
+  showHelp?: boolean;
+}
+
+function printInitUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} init\n`);
+  params.stream("set up pullfrog on the current repository.");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+}
+
+function parseInitArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+    }
+  );
+}
+
+export async function runCli(params: InitCliParams): Promise<void> {
+  if (params.showHelp) {
+    printInitUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  let parsed: ReturnType<typeof parseInitArgs>;
+  try {
+    parsed = parseInitArgs(params.args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printInitUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--help"]) {
+    printInitUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  if (parsed._.length > 0) {
+    console.error(`unexpected positional arguments for init: ${parsed._.join(" ")}\n`);
+    printInitUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  await run();
+}
+
+export async function run() {
+  try {
+    await main();
+  } catch (error) {
+    if (activeSpin) {
+      activeSpin.stop(pc.red("failed"));
+      activeSpin = null;
+    }
+    const msg =
+      error instanceof Error && error.name === "AbortError"
+        ? "request timed out — check your network connection and try again"
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    p.log.error(msg);
+    process.exit(1);
+  }
+}

entry.ts

@@ -1,29 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * entry point for pullfrog/pullfrog - unified action
- */
+import { runPullfrogCli } from "./runCli.ts";
 
-import { dirname } from "node:path";
-import * as core from "@actions/core";
-import { main } from "./main.ts";
-
-// GitHub Actions runs the action entry point with the node24 binary specified
-// in action.yml, but doesn't add that binary's directory to PATH. Without this,
-// spawned processes (pnpm, npm, etc.) resolve to the runner's default node (v20).
-process.env.PATH = `${dirname(process.execPath)}:${process.env.PATH}`;
-
-async function run(): Promise<void> {
-  try {
-    const result = await main();
-
-    if (!result.success) {
-      throw new Error(result.error || "Agent execution failed");
-    }
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
-    core.setFailed(`Action failed: ${errorMessage}`);
-  }
-}
-
-await run();
+runPullfrogCli({
+  cliArgs: ["gha"],
+});

esbuild.config.js

@@ -3,7 +3,7 @@
 import { build } from "esbuild";
 import { readFileSync, writeFileSync } from "fs";
 
-const isMainOnlyBuild = process.argv.includes("--main-only");
+const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
 
 // Plugin to strip shebangs from output files
 /**
@@ -61,30 +61,21 @@ const sharedConfig = {
   drop: [],
 };
 
-// Build the main entry bundle
+// Build the CLI bundle (published to npm, used by npx)
 await build({
   ...sharedConfig,
-  entryPoints: ["./entry.ts"],
-  outfile: "./entry",
+  entryPoints: ["./cli.ts"],
+  outfile: "./dist/cli.mjs",
+  target: "node20",
   plugins: [stripShebangPlugin],
+  define: {
+    "process.env.CLI_VERSION": JSON.stringify(pkg.version),
+  },
 });
 
-if (!isMainOnlyBuild) {
-  // Build the post cleanup entry bundle
-  await build({
-    ...sharedConfig,
-    entryPoints: ["./post.ts"],
-    outfile: "./post",
-    plugins: [stripShebangPlugin],
-  });
-
-  // Build the get-installation-token action
-  await build({
-    ...sharedConfig,
-    entryPoints: ["./get-installation-token/entry.ts"],
-    outfile: "./get-installation-token/entry",
-    plugins: [stripShebangPlugin],
-  })
-}
+// prepend shebang after strip (esbuild banner can't guarantee line 1 placement)
+const cliPath = "./dist/cli.mjs";
+const cliContent = readFileSync(cliPath, "utf8");
+writeFileSync(cliPath, `#!/usr/bin/env node\n${cliContent}`);
 
 console.log("» build completed successfully");

get-installation-token/action.yml

@@ -13,8 +13,8 @@ outputs:
 
 runs:
   using: "node24"
-  main: "entry"
-  post: "entry"
+  main: "entry.ts"
+  post: "post.ts"
 
 branding:
   icon: "key"

get-installation-token/entry.ts

@@ -1,69 +1,5 @@
-#!/usr/bin/env node
+import { runPullfrogCli } from "../runCli.ts";
 
-/**
- * entry point for get-installation-token action.
- * handles both main and post execution using the isPost state pattern.
- */
-
-import * as core from "@actions/core";
-import { acquireInstallationToken, revokeInstallationToken } from "../utils/token.ts";
-
-const STATE_TOKEN = "token";
-const STATE_IS_POST = "isPost";
-
-async function main(): Promise<void> {
-  core.saveState(STATE_IS_POST, "true");
-
-  const reposInput = core.getInput("repos");
-  const additionalRepos = reposInput
-    ? reposInput
-        .split(",")
-        .map((r) => r.trim())
-        .filter(Boolean)
-    : [];
-
-  const token = await acquireInstallationToken({ repos: additionalRepos });
-
-  // mask the token in logs
-  core.setSecret(token);
-
-  // save token to state for post cleanup
-  core.saveState(STATE_TOKEN, token);
-
-  // set as output
-  core.setOutput("token", token);
-
-  const scope = additionalRepos.length
-    ? `current repo + ${additionalRepos.join(", ")}`
-    : "current repo only";
-  core.info(`» installation token acquired (${scope})`);
-}
-
-async function post(): Promise<void> {
-  const token = core.getState(STATE_TOKEN);
-
-  if (!token) {
-    core.debug("no token found in state, skipping revocation");
-    return;
-  }
-
-  await revokeInstallationToken(token);
-  core.info("» installation token revoked");
-}
-
-async function run(): Promise<void> {
-  try {
-    const isPost = core.getState(STATE_IS_POST) === "true";
-
-    if (isPost) {
-      await post();
-    } else {
-      await main();
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    core.setFailed(message);
-  }
-}
-
-await run();
+runPullfrogCli({
+  cliArgs: ["gha", "token"],
+});

get-installation-token/post.ts

@@ -0,0 +1,6 @@
+import { runPullfrogCli } from "../runCli.ts";
+
+runPullfrogCli({
+  cliArgs: ["gha", "token", "--post"],
+  swallowErrors: true,
+});

main.ts

@@ -407,6 +407,17 @@ export async function main(): Promise<MainResult> {
       });
     }
 
+    // review submitted → always delete the progress comment.
+    // the review is the durable artifact; the progress comment is noise.
+    // defense-in-depth: covers the case where the agent calls report_progress
+    // despite mode instructions, which sets finalSummaryWritten and prevents
+    // the stranded-comment heuristic below from firing.
+    if (toolContext && toolState.review && toolState.progressCommentId) {
+      await deleteProgressComment(toolContext).catch((error) => {
+        log.debug(`review progress comment cleanup failed: ${error}`);
+      });
+    }
+
     // clean up stranded progress comments. two cases:
     // 1. wasUpdated=false: nothing wrote to the comment ("Leaping into action" orphan)
     // 2. tracker published a checklist but the agent never wrote a final summary

mcp/checkout.test.ts

@@ -1,7 +1,8 @@
-import { Octokit } from "@octokit/rest";
+import type { RestEndpointMethodTypes } from "@octokit/rest";
 import { describe, expect, it } from "vitest";
-import { acquireNewToken } from "../utils/github.ts";
+import { acquireNewToken, createOctokit } from "../utils/github.ts";
 import { fetchAndFormatPrDiff } from "./checkout.ts";
+import type { ToolContext } from "./server.ts";
 
 /**
  * parses TOC entries like "- src/math.ts → lines 7-42" into structured data.
@@ -33,13 +34,16 @@ describe("fetchAndFormatPrDiff", () => {
     { timeout: 30000 },
     async () => {
       const token = await getToken();
-      const octokit = new Octokit({ auth: token });
-      const result = await fetchAndFormatPrDiff({
+      const octokit = createOctokit(token);
+      const ctx = {
         octokit,
-        owner: "pullfrog",
-        repo: "test-repo",
-        pullNumber: 1,
-      });
+        repo: {
+          owner: "pullfrog",
+          name: "test-repo",
+          data: {} as RestEndpointMethodTypes["repos"]["get"]["response"]["data"],
+        },
+      } as ToolContext;
+      const result = await fetchAndFormatPrDiff(ctx, 1);
 
       // verify content includes TOC at the start
       expect(result.content.startsWith(result.toc)).toBe(true);

mcp/checkout.ts

@@ -145,22 +145,18 @@ export type CheckoutPrResult = {
   instructions: string;
 };
 
-type FetchPrDiffParams = {
-  octokit: Octokit;
-  owner: string;
-  repo: string;
-  pullNumber: number;
-};
-
 /**
  * fetches PR files from GitHub and formats them with line numbers and TOC.
  * this is the core diff formatting logic, extracted for testability.
  */
-export async function fetchAndFormatPrDiff(params: FetchPrDiffParams): Promise<FormatFilesResult> {
-  const files = await params.octokit.paginate(params.octokit.rest.pulls.listFiles, {
-    owner: params.owner,
-    repo: params.repo,
-    pull_number: params.pullNumber,
+export async function fetchAndFormatPrDiff(
+  ctx: ToolContext,
+  pullNumber: number
+): Promise<FormatFilesResult> {
+  const files = await ctx.octokit.paginate(ctx.octokit.rest.pulls.listFiles, {
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    pull_number: pullNumber,
     per_page: 100,
   });
   return formatFilesWithLineNumbers(files);
@@ -502,12 +498,7 @@ export function CheckoutPrTool(ctx: ToolContext) {
       }
 
       // fetch PR files and format with line numbers
-      const formatResult = await fetchAndFormatPrDiff({
-        octokit: ctx.octokit,
-        owner: ctx.repo.owner,
-        repo: ctx.repo.name,
-        pullNumber: pull_number,
-      });
+      const formatResult = await fetchAndFormatPrDiff(ctx, pull_number);
       const diffPreview = formatResult.content.split("\n").slice(0, 100).join("\n");
       log.debug(`formatted diff preview (first 100 lines):\n${diffPreview}`);
       const diffPath = join(tempDir, `pr-${pull_number}-${headShort}.diff`);

mcp/comment.ts

@@ -4,7 +4,6 @@ import { getApiUrl } from "../utils/apiUrl.ts";
 import { buildPullfrogFooter, stripExistingFooter } from "../utils/buildPullfrogFooter.ts";
 import { log } from "../utils/cli.ts";
 import { fixDoubleEscapedString } from "../utils/fixDoubleEscapedString.ts";
-import { type OctokitWithPlugins, parseRepoContext } from "../utils/github.ts";
 import { retry } from "../utils/retry.ts";
 import type { ToolContext } from "./server.ts";
 import { execute, tool } from "./shared.ts";
@@ -52,65 +51,37 @@ export async function updateCommentNodeId(
  */
 export const LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
 
-interface BuildCommentFooterParams {
-  octokit?: OctokitWithPlugins | undefined;
-  customParts?: string[] | undefined;
-  model?: string | undefined;
-}
-
-async function buildCommentFooter(params: BuildCommentFooterParams): Promise<string> {
-  const repoContext = parseRepoContext();
-  const runId = process.env.GITHUB_RUN_ID
-    ? Number.parseInt(process.env.GITHUB_RUN_ID, 10)
-    : undefined;
-
-  let jobId: string | undefined;
-  if (runId && params.octokit) {
-    try {
-      const { data: jobs } = await params.octokit.rest.actions.listJobsForWorkflowRun({
-        owner: repoContext.owner,
-        repo: repoContext.name,
-        run_id: runId,
-      });
-      jobId = jobs.jobs[0]?.id.toString();
-    } catch {
-      // fall back to computed URL from runId alone
-    }
-  }
-
+function buildCommentFooter(ctx: ToolContext, customParts?: string[]): string {
+  const runId = ctx.runId;
   return buildPullfrogFooter({
     triggeredBy: true,
-    workflowRun: runId
-      ? { owner: repoContext.owner, repo: repoContext.name, runId, jobId }
-      : undefined,
-    customParts: params.customParts,
-    model: params.model,
+    workflowRun:
+      runId !== undefined
+        ? {
+            owner: ctx.repo.owner,
+            repo: ctx.repo.name,
+            runId,
+            jobId: ctx.jobId,
+          }
+        : undefined,
+    customParts,
+    model: ctx.toolState.model,
   });
 }
 
-function buildImplementPlanLink(
-  owner: string,
-  repo: string,
-  issueNumber: number,
-  commentId: number
-): string {
+function buildImplementPlanLink(ctx: ToolContext, issueNumber: number, commentId: number): string {
   const apiUrl = getApiUrl();
-  return `[Implement plan ➔](${apiUrl}/trigger/${owner}/${repo}/${issueNumber}?action=implement&comment_id=${commentId})`;
+  return `[Implement plan ➔](${apiUrl}/trigger/${ctx.repo.owner}/${ctx.repo.name}/${issueNumber}?action=implement&comment_id=${commentId})`;
 }
 
-export interface AddFooterCtx {
-  octokit?: OctokitWithPlugins | undefined;
-  toolState?: { model?: string | undefined } | undefined;
-}
-
-export async function addFooter(ctx: AddFooterCtx, body: string): Promise<string> {
+export function addFooter(ctx: ToolContext, body: string): string {
   if (/<br\s*\/?>[ \t]*\n(?!\s*\n)/i.test(body)) {
     throw new Error(
       "body contains <br/> followed by a non-blank line, which breaks GitHub markdown rendering. always add a blank line after <br/> tags."
     );
   }
   const bodyWithoutFooter = stripExistingFooter(fixDoubleEscapedString(body));
-  const footer = await buildCommentFooter({ octokit: ctx.octokit, model: ctx.toolState?.model });
+  const footer = buildCommentFooter(ctx);
   return `${bodyWithoutFooter}${footer}`;
 }
 
@@ -132,7 +103,7 @@ export function CreateCommentTool(ctx: ToolContext) {
       "Create a comment on a GitHub issue or PR. For progress/plan updates on the current run use report_progress instead. Use type: 'Plan' for plan comments, type: 'Summary' for PR summary comments.",
     parameters: Comment,
     execute: execute(async ({ issueNumber, body, type: commentType }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       // if a summary comment already exists (found by select_mode), update instead of creating
       if (commentType === "Summary" && ctx.toolState.existingSummaryCommentId) {
@@ -165,9 +136,30 @@ export function CreateCommentTool(ctx: ToolContext) {
         body: bodyWithFooter,
       });
 
-      if (commentType === "Plan" && result.data.node_id) {
-        await updateCommentNodeId(ctx, "planCommentNodeId", result.data.node_id);
+      if (commentType === "Plan") {
+        if (result.data.node_id) {
+          await updateCommentNodeId(ctx, "planCommentNodeId", result.data.node_id);
+        }
+        // add "Implement plan" link (needs comment ID, so create-then-update)
+        const customParts = [buildImplementPlanLink(ctx, issueNumber, result.data.id)];
+        const footer = buildCommentFooter(ctx, customParts);
+        const bodyWithPlanLink = `${stripExistingFooter(body)}${footer}`;
+
+        const updateResult = await ctx.octokit.rest.issues.updateComment({
+          owner: ctx.repo.owner,
+          repo: ctx.repo.name,
+          comment_id: result.data.id,
+          body: bodyWithPlanLink,
+        });
+
+        return {
+          success: true,
+          commentId: updateResult.data.id,
+          url: updateResult.data.html_url,
+          body: updateResult.data.body,
+        };
       }
+
       if (commentType === "Summary" && result.data.node_id) {
         await updateCommentNodeId(ctx, "summaryCommentNodeId", result.data.node_id);
       }
@@ -193,7 +185,7 @@ export function EditCommentTool(ctx: ToolContext) {
     description: "Edit a GitHub issue comment by its ID",
     parameters: EditComment,
     execute: execute(async ({ commentId, body }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       const result = await ctx.octokit.rest.issues.updateComment({
         owner: ctx.repo.owner,
@@ -259,15 +251,9 @@ export async function reportProgress(
   if (target_plan_comment === true && ctx.toolState.existingPlanCommentId !== undefined) {
     const commentId = ctx.toolState.existingPlanCommentId;
     const customParts =
-      isPlanMode && issueNumber !== undefined
-        ? [buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, commentId)]
-        : undefined;
+      issueNumber !== undefined ? [buildImplementPlanLink(ctx, issueNumber, commentId)] : undefined;
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithFooter = `${bodyWithoutFooter}${footer}`;
 
     const result = await ctx.octokit.rest.issues.updateComment({
@@ -297,15 +283,11 @@ export async function reportProgress(
   if (existingCommentId) {
     const customParts =
       isPlanMode && issueNumber !== undefined
-        ? [buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, existingCommentId)]
+        ? [buildImplementPlanLink(ctx, issueNumber, existingCommentId)]
         : undefined;
 
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithFooter = `${bodyWithoutFooter}${footer}`;
 
     const result = await ctx.octokit.rest.issues.updateComment({
@@ -343,7 +325,7 @@ export async function reportProgress(
   }
 
   // for new comments, we need to create first, then update with Plan link if in Plan mode
-  const initialBody = await addFooter(ctx, body);
+  const initialBody = addFooter(ctx, body);
 
   const result = await ctx.octokit.rest.issues.createComment({
     owner: ctx.repo.owner,
@@ -358,15 +340,9 @@ export async function reportProgress(
 
   // if Plan mode, update the comment to add the "Implement plan" link
   if (isPlanMode) {
-    const customParts = [
-      buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, result.data.id),
-    ];
+    const customParts = [buildImplementPlanLink(ctx, issueNumber, result.data.id)];
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithPlanLink = `${bodyWithoutFooter}${footer}`;
 
     const updateResult = await ctx.octokit.rest.issues.updateComment({
@@ -410,6 +386,7 @@ export function ReportProgressTool(ctx: ToolContext) {
       if (!params.target_plan_comment && ctx.toolState.todoTracker) {
         ctx.toolState.todoTracker.cancel();
         await ctx.toolState.todoTracker.settled();
+        ctx.toolState.todoTracker.completeInProgress();
         const collapsible = ctx.toolState.todoTracker.renderCollapsible();
         if (collapsible) {
           body = `${body}\n\n${collapsible}`;
@@ -490,7 +467,7 @@ export function ReplyToReviewCommentTool(ctx: ToolContext) {
       "Reply to a PR review comment thread (NOT issue comments — this only works for inline review comments on PR diffs). Call this for EACH comment you address in AddressReviews mode. Keep replies extremely brief (1 sentence max).",
     parameters: ReplyToReviewComment,
     execute: execute(async ({ pull_number, comment_id, body }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       const result = await ctx.octokit.rest.pulls.createReplyForReviewComment({
         owner: ctx.repo.owner,

mcp/git.ts

@@ -57,23 +57,20 @@ function normalizeUrl(url: string): string {
   return url.replace(/\.git$/, "").toLowerCase();
 }
 
-type ValidatePushParams = {
-  branch: string;
-  pushUrl: string;
-  storedDest: StoredPushDest | undefined;
-};
-
 /**
  * validate that the push destination matches expected URL.
  * pushUrl is set by setupGit (base repo) and updated by checkout_pr (fork repo).
  */
-function validatePushDestination(params: ValidatePushParams): PushDestination {
-  const dest = getPushDestination(params.branch, params.storedDest);
+function validatePushDestination(ctx: ToolContext, branch: string): PushDestination {
+  const pushUrl = ctx.toolState.pushUrl;
+  if (!pushUrl) throw new Error("pushUrl not set - setupGit must run before push_branch");
 
-  if (normalizeUrl(dest.url) !== normalizeUrl(params.pushUrl)) {
+  const dest = getPushDestination(branch, ctx.toolState.pushDest);
+
+  if (normalizeUrl(dest.url) !== normalizeUrl(pushUrl)) {
     throw new Error(
       `Push blocked: destination does not match expected repository.\n` +
-        `Expected: ${params.pushUrl}\n` +
+        `Expected: ${pushUrl}\n` +
         `Actual: ${dest.url}\n` +
         `Git configuration may have been tampered with.`
     );
@@ -99,6 +96,7 @@ export function PushBranchTool(ctx: ToolContext) {
       "Push the current branch to the remote repository. Omit branchName to push the current branch (recommended). " +
       "If specifying branchName, use the LOCAL branch name (e.g., 'pr-1'), not the remote branch name. " +
       "The correct remote and remote branch are determined automatically from branch config set by checkout_pr. " +
+      "Requires a clean working tree. Runs the repository prepush hook (if configured) before the network push — hook failure means tests/lint or similar in that script failed, not necessarily a Pullfrog timeout. " +
       "Never force push unless explicitly requested. Pushes to the default branch are blocked in restricted mode.",
     parameters: PushBranch,
     execute: execute(async ({ branchName, force }) => {
@@ -113,21 +111,13 @@ export function PushBranchTool(ctx: ToolContext) {
       const status = $("git", ["status", "--porcelain"], { log: false });
       if (status) {
         throw new Error(
-          `push blocked: working tree has uncommitted changes. commit or discard them before pushing.\n\n` +
+          `push blocked: working tree is not clean (tracked changes and/or untracked files). commit, discard, or remove stray artifacts before pushing.\n\n` +
             `git status:\n${status}`
         );
       }
 
       // validate push destination matches expected URL
-      const pushUrl = ctx.toolState.pushUrl;
-      if (!pushUrl) {
-        throw new Error("pushUrl not set - setupGit must run before push_branch");
-      }
-      const pushDest = validatePushDestination({
-        branch,
-        pushUrl,
-        storedDest: ctx.toolState.pushDest,
-      });
+      const pushDest = validatePushDestination(ctx, branch);
 
       // block pushes to default branch in restricted mode
       if (pushPermission === "restricted" && pushDest.remoteBranch === defaultBranch) {

mcp/review.ts

@@ -83,6 +83,17 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
     execute: execute(async ({ pull_number, body, approved, commit_id, comments = [] }) => {
       if (body) body = fixDoubleEscapedString(body);
 
+      // in Review mode (not IncrementalReview), append the completed task list
+      if (body && ctx.toolState.selectedMode === "Review" && ctx.toolState.todoTracker) {
+        ctx.toolState.todoTracker.cancel();
+        await ctx.toolState.todoTracker.settled();
+        ctx.toolState.todoTracker.completeInProgress();
+        const collapsible = ctx.toolState.todoTracker.renderCollapsible();
+        if (collapsible) {
+          body = `${body}\n\n${collapsible}`;
+        }
+      }
+
       // set issue context (PRs are issues)
       ctx.toolState.issueNumber = pull_number;
 

mcp/selectMode.ts

@@ -1,6 +1,6 @@
 import { type } from "arktype";
 import { formatMcpToolRef } from "../external.ts";
-import type { Mode } from "../modes.ts";
+import { type Mode, PR_SUMMARY_FORMAT } from "../modes.ts";
 import { apiFetch } from "../utils/apiFetch.ts";
 import { log } from "../utils/log.ts";
 import type { ToolContext } from "./server.ts";
@@ -39,17 +39,11 @@ An existing summary comment was found for this PR. Update it rather than creatin
 
 1. Use \`previousSummaryBody\` from this response as the current summary to revise.
 2. Checkout the PR via \`${t("checkout_pr")}\` — this returns PR metadata and a \`diffPath\`.
-3. Delegate a subagent with:
-   - the diff file path and PR metadata
-   - the existing summary body (\`previousSummaryBody\`) so it can update rather than rewrite from scratch
-   - format instructions from EVENT INSTRUCTIONS (if any)
-   - instruct it to produce an updated summary reflecting the current state of the PR and return it as its final response
-4. After the subagent completes, call \`${t("edit_issue_comment")}\` with \`commentId: existingSummaryCommentId\` (from this response) and the updated summary body.
+3. Read the diff using the TOC to selectively read relevant sections. Produce an updated summary reflecting the current state of the PR, using the existing summary (\`previousSummaryBody\`) as a starting point. If EVENT INSTRUCTIONS specify a custom format, follow that instead of the default format below.
+4. Call \`${t("edit_issue_comment")}\` with \`commentId: existingSummaryCommentId\` (from this response) and the updated summary body.
 5. Call \`${t("report_progress")}\` with a brief note (e.g., "Updated PR summary.").
 
-### Effort
-
-Use mini or auto effort.`,
+${PR_SUMMARY_FORMAT}`,
   };
 }
 
@@ -65,15 +59,14 @@ const modeInstructionParent: Record<string, string> = {
   Fix: "Build",
 };
 
-type BuildGuidanceOpts = {
-  modeInstructions?: Record<string, string>;
-  overrideGuidance?: string;
-};
-
-function buildOrchestratorGuidance(mode: Mode, opts: BuildGuidanceOpts = {}): OrchestratorGuidance {
-  const hardcoded = opts.overrideGuidance ?? mode.prompt ?? "";
+function buildOrchestratorGuidance(
+  ctx: ToolContext,
+  mode: Mode,
+  overrideGuidance?: string
+): OrchestratorGuidance {
+  const hardcoded = overrideGuidance ?? mode.prompt ?? "";
   const lookupKey = modeInstructionParent[mode.name] ?? mode.name;
-  const userInstructions = opts.modeInstructions?.[lookupKey] ?? "";
+  const userInstructions = ctx.modeInstructions[lookupKey] ?? "";
   const guidance = [hardcoded, userInstructions].filter(Boolean).join("\n\n");
   return {
     modeName: mode.name,
@@ -172,8 +165,6 @@ export function SelectModeTool(ctx: ToolContext) {
 
       ctx.toolState.selectedMode = selectedMode.name;
 
-      const guidanceOpts: BuildGuidanceOpts = { modeInstructions: ctx.modeInstructions };
-
       if (selectedMode.name === "Plan") {
         const issueNumber = params.issue_number ?? ctx.payload.event.issue_number;
         if (issueNumber !== undefined) {
@@ -182,10 +173,7 @@ export function SelectModeTool(ctx: ToolContext) {
             ctx.toolState.existingPlanCommentId = existing.commentId;
             ctx.toolState.previousPlanBody = existing.body;
             return {
-              ...buildOrchestratorGuidance(selectedMode, {
-                ...guidanceOpts,
-                overrideGuidance: overrides.PlanEdit,
-              }),
+              ...buildOrchestratorGuidance(ctx, selectedMode, overrides.PlanEdit),
               previousPlanBody: existing.body,
             };
           }
@@ -199,10 +187,7 @@ export function SelectModeTool(ctx: ToolContext) {
           if (existing !== null) {
             ctx.toolState.existingSummaryCommentId = existing.commentId;
             return {
-              ...buildOrchestratorGuidance(selectedMode, {
-                ...guidanceOpts,
-                overrideGuidance: overrides.SummaryUpdate,
-              }),
+              ...buildOrchestratorGuidance(ctx, selectedMode, overrides.SummaryUpdate),
               existingSummaryCommentId: existing.commentId,
               previousSummaryBody: existing.body,
             };
@@ -210,7 +195,7 @@ export function SelectModeTool(ctx: ToolContext) {
         }
       }
 
-      return buildOrchestratorGuidance(selectedMode, guidanceOpts);
+      return buildOrchestratorGuidance(ctx, selectedMode);
     }),
   });
 }

modes.ts

@@ -9,6 +9,55 @@ export interface Mode {
   prompt?: string | undefined;
 }
 
+export const PR_SUMMARY_FORMAT = `### Default format
+
+Follow this structure exactly:
+
+<b>TL;DR</b> — 1-3 sentences on what the PR does and why. Focus on intent, not mechanics.
+NOTE: use HTML bold <b>TL;DR</b>, NOT markdown bold **TL;DR**.
+
+### Key changes
+
+- **Short human-readable title** — 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.
+
+<sub><b>Summary</b> ｜ {file_count} files ｜ {commit_count} commits ｜ base: \`{base}\` ← \`{head}\`</sub>
+NOTE: the metadata line goes AFTER the bullet list, not before it.
+
+Then for each key change, a ## section with a short descriptive title that reads like a documentation heading (e.g. ## Live todo checklist tracking).
+
+<br/>
+
+## Example readable section title
+
+> **Before:** [old behavior/state]<br/>**After:** [new behavior/state]
+IMPORTANT: Before and After MUST be on a SINGLE blockquote line with an inline <br/> between them. Two separate \`>\` lines creates a double line break.
+
+1-2 sentences of explanation. Break up text with tables, blockquotes, or lists — NEVER 3+ plain paragraphs in a row.
+
+If a change warrants deeper explanation, use a blockquoted details/summary framed as a question:
+> <details><summary>How does X work?</summary>
+> Extended explanation here.
+> </details>
+
+End each section with a file links trail (3-4 key files max):
+[\`file.ts\`](https://github.com/{owner}/{repo}/pull/{number}/files#diff-{sha256hex_of_filepath}) · ...
+
+Single-feature PRs: skip the ## sections. Fold before/after and explanation into the header after key changes.
+
+CRITICAL — GitHub markdown rendering rule:
+GitHub'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.
+
+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 — run the actual command. If shell is unavailable, 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
+- Do NOT include a changelog section — the key changes list serves this purpose
+- Focus on *intent*, not *what* — the diff already shows what changed
+- Get the file count and commit count from the checkout_pr metadata, not by counting manually`;
+
 function learningsStep(t: (toolName: string) => string, n: number): string {
   return `${n}. **learnings** (only if high confidence): if you discovered something about repo setup, test commands, conventions, or patterns that you are confident is correct and would reliably help future runs, call \`${t("update_learnings")}\` to persist it. skip this step if you are unsure or the finding is speculative/one-off. format as a flat bullet list (\`- \` per line, one fact per bullet). merge with existing learnings from the prompt — pass the FULL merged list. deduplicate, and drop bullets that are clearly wrong or no longer relevant to the current codebase.`;
 }
@@ -38,9 +87,9 @@ export function computeModes(agentId: AgentId): Mode[] {
    - commit locally via shell (\`git add . && git commit -m "..."\`)
 
 5. **finalize**:
-   - push the branch via \`${t("push_branch")}\`
+   - confirm a clean working tree, then push via \`${t("push_branch")}\` (see *SYSTEM* Git rules if this fails — prepush errors are usually the repo's tests/lint, not infra timeouts)
    - create a PR via \`${t("create_pull_request")}\`
-   - call \`${t("report_progress")}\` with the final summary including PR link
+   - call \`${t("report_progress")}\` with the PR link or the exact error if push/PR failed
 
 ${learningsStep(t, 6)}
 
@@ -68,10 +117,10 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`,
    - commit locally via shell (\`git add . && git commit -m "..."\`)
 
 5. Finalize:
-   - push changes via \`${t("push_branch")}\`
+   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
    - reply to each comment using \`${t("reply_to_review_comment")}\`
    - resolve addressed threads via \`${t("resolve_review_thread")}\`
-   - call \`${t("report_progress")}\` with a brief summary
+   - call \`${t("report_progress")}\` with a brief summary (or the exact push error if push failed)
 
 ${learningsStep(t, 6)}`,
     },
@@ -127,26 +176,23 @@ ${learningsStep(t, 6)}`,
    - check whether prior review feedback was addressed by the new commits
    - trace data flow, check boundaries, verify assumptions, consider lifecycle, spot performance issues
    - if the new commits remove, rename, or deprecate anything, run impact analysis with grep across code/tests/docs/comments/configs to find stale references and include those findings in the summary body
-   - never repeat prior feedback. if the author did not address an earlier comment, assume it was intentionally declined; only comment on genuinely new issues introduced by the new commits
+   - never repeat prior feedback. only comment on genuinely new issues introduced by the new commits.
    - draft inline comments with NEW line numbers from the full PR diff — every comment must be actionable (2-3 sentences max)
    - for large or cross-cutting PRs, consider delegating read-only subagents for parallel investigation. subagents must ONLY read files, grep, and search — no MCP tools, no writes, no shell commands, no side effects. collect their findings and use them to draft comments.
 
 5. Self-critique: drop any comments that are praise, style preferences, speculative, about pre-existing code, or not actionable.
 
-6. **Summarize incremental changes**: produce a concise summary of the changes since the last review. This summary MUST follow strict formatting rules:
-   - **never put more than 3 sentences in a row** — break up prose with lists, tables, or headings
-   - use bullet lists, tables, and structured formatting liberally
-   - start with a 1-sentence TL;DR of what the new commits do
-   - then list the key changes (use a table for file-level changes if 3+ files changed, bullet list otherwise)
-   - note which prior review comments were addressed vs. not addressed (use a checklist: \`- [x] addressed\` / \`- [ ] not addressed\`)
-   - keep the entire summary compact — aim for ≤15 lines of markdown
+6. **Summarize**: build two distinct sections for the review body:
+   a. **Reviewed changes**: summarize at the logical-change level, not per-file. each bullet starts with a past-tense verb (e.g. \`- Extracted shared CLI runtime into a single module\`, \`- Renamed package to pullfrog\`). avoid file paths unless they add clarity. if the changes can be described in one sentence, use one sentence — no bullets needed.
+   b. **Prior review feedback** (only if any were addressed): list only the prior review comments that WERE addressed by the new commits (\`- [x] safeParse instead of parse — addressed\`). omit unaddressed comments. omit this entire section if nothing was addressed. a change can appear in both sections.
+   - no headings, no tables, no prose paragraphs in either section — just bullets
    - 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 — Do NOT call \`report_progress\` or \`create_issue_comment\` — the review is the final record and the progress comment will be cleaned up automatically. Follow these rules:
+7. Submit — Do NOT call \`report_progress\` or \`create_issue_comment\` — 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:
    - 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 — 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. The review body begins with a GitHub alert blockquote (e.g. \`> [!CAUTION]\\n> This PR introduces ...\`) + incremental summary from step 6.
-   - ELSE IF NEW RECOMMENDED CHANGES (non-critical): call \`${t("create_pull_request_review")}\` with \`approved: false\`, all comments, and the review body. The review body begins with a GitHub alert blockquote (e.g. \`> [!IMPORTANT]\\n> Consider adding input validation for ...\`) + incremental summary.
-   - ELSE IF NO NEW ISSUES, SUBSTANTIVE CHANGES (new functionality, behavior changes, or fixes to prior review feedback): call \`${t("create_pull_request_review")}\` to create a PR review. If all Previous reviews have been properly addressed and no new issues were discovered, you can set \`approved: true\`. The "body" should state up front that no new issues were found. Then include a summary of the detected changes so the user knows that you have reviewed them.`,
+   - 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).
+   - ELSE IF NO NEW ISSUES, SUBSTANTIVE CHANGES (new functionality, behavior changes, or fixes to prior review feedback): call \`${t("create_pull_request_review")}\` to create a PR review. If all previous reviews have been properly addressed and no new issues were discovered, you can set \`approved: true\`. body opens with \`No new issues. Reviewed the following changes:\\n\`, then the reviewed changes summary and prior feedback (if any).`,
     },
     {
       name: "Plan",
@@ -184,8 +230,8 @@ ${learningsStep(t, 4)}`,
    - commit locally via shell (\`git add . && git commit -m "..."\`)
 
 5. Finalize:
-   - push changes via \`${t("push_branch")}\`
-   - call \`${t("report_progress")}\` with the diagnosis and fix summary
+   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
+   - call \`${t("report_progress")}\` with the diagnosis and fix summary (or the exact push error if push failed)
 
 ${learningsStep(t, 6)}`,
     },
@@ -201,8 +247,8 @@ ${learningsStep(t, 6)}`,
 
 2. **Merge Attempt**:
    - Run \`git merge origin/<base_branch>\` via shell.
-   - If it succeeds automatically, push via \`${t("push_branch")}\` and report success.
-   - If it fails (conflicts), resolve them manually.
+   - If it succeeds automatically, confirm a clean working tree, push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*), and call \`${t("report_progress")}\` with a brief success note or the exact push error if push failed — **then stop; do not run steps 3–4.**
+   - If it fails (conflicts), resolve them manually (continue to steps 3–4).
 
 3. **Resolve Conflicts**:
    - Run \`git status\` or parse the merge output to find the list of conflicting files.
@@ -212,8 +258,8 @@ ${learningsStep(t, 6)}`,
 4. **Finalize**:
    - Run a final verification (build/test) to ensure the resolution works.
    - \`git add . && git commit -m "resolve merge conflicts"\`
-   - Push via \`${t("push_branch")}\`
-   - Call \`${t("report_progress")}\` with a summary of what was resolved`,
+   - confirm a clean working tree, then push via \`${t("push_branch")}\` (same push/prepush guidance as Build mode in *SYSTEM*)
+   - Call \`${t("report_progress")}\` with a summary of what was resolved (or the exact push error if push failed)`,
     },
     {
       name: "Task",
@@ -230,8 +276,8 @@ ${learningsStep(t, 6)}`,
    - if code changes are needed: review your own diff before committing — verify only intended changes are present, no debug artifacts remain, and the changes are clean enough that a senior engineer would approve without hesitation
 
 3. Finalize:
-   - if code changes were made, push all changes to a pull request (new or existing). \`git status\` must be clean before you finish.
-   - call \`${t("report_progress")}\` with results
+   - if code changes were made, push to a pull request (new or existing) using \`${t("push_branch")}\` and \`${t("create_pull_request")}\` as needed. \`git status\` must be clean before you finish (see *SYSTEM* Git rules if push fails).
+   - call \`${t("report_progress")}\` once with results — include exact tool errors if push or PR creation failed
    - if the task involved labeling, commenting, or other GitHub operations, perform those directly
 
 ${learningsStep(t, 4)}`,
@@ -243,18 +289,11 @@ ${learningsStep(t, 4)}`,
       prompt: `### Checklist
 
 1. Checkout the PR via \`${t("checkout_pr")}\` — this returns PR metadata and a \`diffPath\`.
-2. Delegate a subagent to analyze the diff and produce a structured summary. Include in its prompt:
-   - the diff file path
-   - PR metadata (title, file count, commit count, base/head branches)
-   - format instructions from EVENT INSTRUCTIONS (if any); otherwise use default format: TL;DR, key changes list, per-change sections with plain-language \`##\` titles and before/after framing
-   - instruct it to use the TOC to selectively read relevant diff sections, not the entire file
-   - instruct it to return the full summary markdown as its final response
-3. After the subagent completes, call \`${t("create_issue_comment")}\` with \`type: "Summary"\` and the summary body.
+2. Read the diff using the TOC to selectively read relevant sections (not the entire file). Produce a structured summary. If EVENT INSTRUCTIONS specify a custom format, follow that instead of the default format below.
+3. Call \`${t("create_issue_comment")}\` with \`type: "Summary"\` and the summary body.
 4. Call \`${t("report_progress")}\` with a brief note (e.g., "Posted PR summary.").
 
-### Effort
-
-Use mini or auto effort.`,
+${PR_SUMMARY_FORMAT}`,
     },
   ];
 }

package.json

@@ -1,61 +1,60 @@
 {
-  "name": "@pullfrog/pullfrog",
-  "version": "0.0.192",
+  "name": "pullfrog",
+  "version": "0.0.196",
   "type": "module",
+  "bin": {
+    "pullfrog": "dist/cli.mjs",
+    "pullfrog-dev": "dist/cli.mjs",
+    "pf": "dist/cli.mjs"
+  },
   "files": [
-    "index.js",
-    "index.cjs",
-    "index.d.ts",
-    "index.d.cts",
-    "agents",
-    "utils",
-    "main.js",
-    "main.d.ts"
+    "dist/"
   ],
   "scripts": {
     "test": "vitest",
     "typecheck": "tsc --noEmit",
     "build": "node esbuild.config.js",
+    "check:entrypoints": "node scripts/check-entrypoint-imports.ts",
     "play": "node play.ts",
     "runtest": "node test/run.ts",
     "scratch": "node scratch.ts",
     "upDeps": "pnpm up --latest",
     "lock": "pnpm install --no-frozen-lockfile",
-    "postinstall": "node scripts/generate-proxies.ts",
-    "prepare": "cd .. && husky action/.husky"
+    "prepare": "cd .. && husky"
   },
-  "dependencies": {
+  "devDependencies": {
     "@actions/core": "^1.11.1",
+    "@anthropic-ai/claude-code": "2.1.85",
     "@ark/fs": "0.56.0",
     "@ark/util": "0.56.0",
+    "@clack/prompts": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.0",
     "@octokit/webhooks-types": "^7.6.1",
     "@standard-schema/spec": "1.1.0",
     "@toon-format/toon": "^1.0.0",
-    "ajv": "^8.18.0",
-    "arkregex": "0.0.5",
-    "arktype": "2.2.0",
-    "dotenv": "^17.2.3",
-    "execa": "^9.6.0",
-    "fastmcp": "^3.34.0",
-    "file-type": "^21.3.0",
-    "package-manager-detector": "^1.6.0",
-    "semver": "^7.7.3",
-    "table": "^6.9.0",
-    "turndown": "^7.2.0"
-  },
-  "devDependencies": {
-    "@anthropic-ai/claude-code": "2.1.85",
-    "agent-browser": "0.21.0",
-    "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/node": "^24.7.2",
     "@types/semver": "^7.7.1",
     "@types/turndown": "^5.0.5",
+    "agent-browser": "0.21.0",
+    "ajv": "^8.18.0",
     "arg": "^5.0.2",
+    "arkregex": "0.0.5",
+    "arktype": "2.2.0",
+    "dotenv": "^17.2.3",
     "esbuild": "^0.25.9",
+    "execa": "^9.6.0",
+    "fastmcp": "^3.34.0",
+    "file-type": "^21.3.0",
     "husky": "^9.0.0",
     "opencode-ai": "1.1.56",
+    "package-manager-detector": "^1.6.0",
+    "picocolors": "^1.1.1",
+    "semver": "^7.7.3",
+    "skills": "1.4.9",
+    "table": "^6.9.0",
+    "turndown": "^7.2.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17",
     "yaml": "^2.8.2"
@@ -78,16 +77,22 @@
   "zshy": {
     "exports": "./index.ts"
   },
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.cts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "@pullfrog/source": "./index.ts",
       "types": "./dist/index.d.cts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./internal": "./dist/internal.js",
+    "./internal": {
+      "@pullfrog/source": "./internal/index.ts",
+      "types": "./dist/internal.d.cts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    },
     "./package.json": "./package.json"
   },
   "packageManager": "pnpm@10.27.0+sha512.72d699da16b1179c14ba9e64dc71c9a40988cbdc65c264cb0e489db7de917f20dcf4d64d8723625f2969ba52d4b7e2a1170682d9ac2a5dcaeaab732b7e16f04a"

pnpm-lock.yaml

@@ -7,16 +7,25 @@ settings:
 importers:
 
   .:
-    dependencies:
+    devDependencies:
       '@actions/core':
         specifier: ^1.11.1
         version: 1.11.1
+      '@anthropic-ai/claude-code':
+        specifier: 2.1.85
+        version: 2.1.85
       '@ark/fs':
         specifier: 0.56.0
         version: 0.56.0
       '@ark/util':
         specifier: 0.56.0
         version: 0.56.0
+      '@clack/prompts':
+        specifier: ^1.2.0
+        version: 1.2.0
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.26.0
+        version: 1.26.0(zod@4.3.6)
       '@octokit/plugin-throttling':
         specifier: ^11.0.3
         version: 11.0.3(@octokit/core@7.0.5)
@@ -32,46 +41,6 @@ importers:
       '@toon-format/toon':
         specifier: ^1.0.0
         version: 1.4.0
-      ajv:
-        specifier: ^8.18.0
-        version: 8.18.0
-      arkregex:
-        specifier: 0.0.5
-        version: 0.0.5
-      arktype:
-        specifier: 2.2.0
-        version: 2.2.0
-      dotenv:
-        specifier: ^17.2.3
-        version: 17.2.3
-      execa:
-        specifier: ^9.6.0
-        version: 9.6.0
-      fastmcp:
-        specifier: ^3.34.0
-        version: 3.34.0(arktype@2.2.0)
-      file-type:
-        specifier: ^21.3.0
-        version: 21.3.0
-      package-manager-detector:
-        specifier: ^1.6.0
-        version: 1.6.0
-      semver:
-        specifier: ^7.7.3
-        version: 7.7.3
-      table:
-        specifier: ^6.9.0
-        version: 6.9.0
-      turndown:
-        specifier: ^7.2.0
-        version: 7.2.2
-    devDependencies:
-      '@anthropic-ai/claude-code':
-        specifier: 2.1.85
-        version: 2.1.85
-      '@modelcontextprotocol/sdk':
-        specifier: ^1.26.0
-        version: 1.26.0(zod@4.3.6)
       '@types/node':
         specifier: ^24.7.2
         version: 24.7.2
@@ -84,18 +53,57 @@ importers:
       agent-browser:
         specifier: 0.21.0
         version: 0.21.0
+      ajv:
+        specifier: ^8.18.0
+        version: 8.18.0
       arg:
         specifier: ^5.0.2
         version: 5.0.2
+      arkregex:
+        specifier: 0.0.5
+        version: 0.0.5
+      arktype:
+        specifier: 2.2.0
+        version: 2.2.0
+      dotenv:
+        specifier: ^17.2.3
+        version: 17.2.3
       esbuild:
         specifier: ^0.25.9
         version: 0.25.12
+      execa:
+        specifier: ^9.6.0
+        version: 9.6.0
+      fastmcp:
+        specifier: ^3.34.0
+        version: 3.34.0(arktype@2.2.0)
+      file-type:
+        specifier: ^21.3.0
+        version: 21.3.0
       husky:
         specifier: ^9.0.0
         version: 9.1.7
       opencode-ai:
         specifier: 1.1.56
         version: 1.1.56
+      package-manager-detector:
+        specifier: ^1.6.0
+        version: 1.6.0
+      picocolors:
+        specifier: ^1.1.1
+        version: 1.1.1
+      semver:
+        specifier: ^7.7.3
+        version: 7.7.3
+      skills:
+        specifier: 1.4.9
+        version: 1.4.9
+      table:
+        specifier: ^6.9.0
+        version: 6.9.0
+      turndown:
+        specifier: ^7.2.0
+        version: 7.2.2
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
@@ -137,6 +145,12 @@ packages:
   '@borewit/text-codec@0.2.1':
     resolution: {integrity: sha512-k7vvKPbf7J2fZ5klGRD9AeKfUvojuZIQ3BT5u7Jfv+puwXkUBUT5PVyMDfJZpy30CBDXGMgw7fguK/lpOMBvgw==}
 
+  '@clack/core@1.2.0':
+    resolution: {integrity: sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==}
+
+  '@clack/prompts@1.2.0':
+    resolution: {integrity: sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==}
+
   '@esbuild/aix-ppc64@0.25.12':
     resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==}
     engines: {node: '>=18'}
@@ -1120,9 +1134,18 @@ packages:
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
+  fast-string-truncated-width@1.2.1:
+    resolution: {integrity: sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==}
+
+  fast-string-width@1.1.0:
+    resolution: {integrity: sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==}
+
   fast-uri@3.1.0:
     resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
 
+  fast-wrap-ansi@0.1.6:
+    resolution: {integrity: sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==}
+
   fastmcp@3.34.0:
     resolution: {integrity: sha512-xKOXjU+MK7OZy91BY3FS5aenSiclJBCRMaZtXb3HYaKZVFbq4qYvAlFu6xYI3UU1NGLtv+h8izoStnOQ1By0BA==}
     hasBin: true
@@ -1626,6 +1649,14 @@ packages:
     resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
     engines: {node: '>=14'}
 
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
+  skills@1.4.9:
+    resolution: {integrity: sha512-BTh7kfSkGPirsLgvg5vvALjDlgNImm9HRn937yAfESFzmShQEZWWTYJQbN34qjlwxOBO7Me4E9Lh6Ot5AE29zA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   slice-ansi@4.0.0:
     resolution: {integrity: sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==}
     engines: {node: '>=10'}
@@ -1886,6 +1917,11 @@ packages:
     engines: {node: '>= 14.6'}
     hasBin: true
 
+  yaml@2.8.3:
+    resolution: {integrity: sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yargs-parser@22.0.0:
     resolution: {integrity: sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==}
     engines: {node: ^20.19.0 || ^22.12.0 || >=23}
@@ -1946,6 +1982,18 @@ snapshots:
 
   '@borewit/text-codec@0.2.1': {}
 
+  '@clack/core@1.2.0':
+    dependencies:
+      fast-wrap-ansi: 0.1.6
+      sisteransi: 1.0.5
+
+  '@clack/prompts@1.2.0':
+    dependencies:
+      '@clack/core': 1.2.0
+      fast-string-width: 1.1.0
+      fast-wrap-ansi: 0.1.6
+      sisteransi: 1.0.5
+
   '@esbuild/aix-ppc64@0.25.12':
     optional: true
 
@@ -2801,8 +2849,18 @@ snapshots:
 
   fast-deep-equal@3.1.3: {}
 
+  fast-string-truncated-width@1.2.1: {}
+
+  fast-string-width@1.1.0:
+    dependencies:
+      fast-string-truncated-width: 1.2.1
+
   fast-uri@3.1.0: {}
 
+  fast-wrap-ansi@0.1.6:
+    dependencies:
+      fast-string-width: 1.1.0
+
   fastmcp@3.34.0(arktype@2.2.0):
     dependencies:
       '@modelcontextprotocol/sdk': 1.27.1(zod@4.3.6)
@@ -3334,6 +3392,12 @@ snapshots:
 
   signal-exit@4.1.0: {}
 
+  sisteransi@1.0.5: {}
+
+  skills@1.4.9:
+    dependencies:
+      yaml: 2.8.3
+
   slice-ansi@4.0.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -3525,6 +3589,8 @@ snapshots:
 
   yaml@2.8.2: {}
 
+  yaml@2.8.3: {}
+
   yargs-parser@22.0.0: {}
 
   yargs@18.0.0:

post.ts

@@ -1,19 +1,8 @@
 #!/usr/bin/env node
 
-/**
- * Post cleanup entry point for pullfrog/pullfrog action.
- * Runs independently after workflow failure or cancellation.
- * Searches for Pullfrog comment via GitHub API and updates if stuck on "Leaping into action".
- */
+import { runPullfrogCli } from "./runCli.ts";
 
-import { log } from "./utils/cli.ts";
-import { runPostCleanup } from "./utils/postCleanup.ts";
-
-log.debug(`[post] script started at ${new Date().toISOString()}`);
-try {
-  await runPostCleanup();
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  log.error(`[post] unexpected error: ${message}`);
-  // don't fail the post script - best effort cleanup
-}
+runPullfrogCli({
+  cliArgs: ["gha", "--post"],
+  swallowErrors: true,
+});

runCli.ts

@@ -0,0 +1,101 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import actionPackageJson from "./package.json" with { type: "json" };
+
+interface RunPullfrogCliParams {
+  cliArgs: string[];
+  swallowErrors?: boolean;
+}
+
+interface RuntimeContext {
+  actionRef: string | undefined;
+  actionRepository: string | undefined;
+  actionRoot: string;
+  nodeBinDir: string;
+  env: NodeJS.ProcessEnv;
+}
+
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const FALLBACK_PACKAGE_SPEC = `pullfrog@^${actionPackageJson.version}`;
+
+function createRuntimeContext(): RuntimeContext {
+  const actionRoot = dirname(fileURLToPath(import.meta.url));
+  const nodeBinDir = dirname(process.execPath);
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  env.npm_config_registry = NPM_REGISTRY;
+  env.COREPACK_NPM_REGISTRY = NPM_REGISTRY;
+  const currentPath = process.env.PATH ?? "";
+  env.PATH = currentPath ? `${nodeBinDir}${delimiter}${currentPath}` : nodeBinDir;
+
+  return {
+    actionRef: process.env.GITHUB_ACTION_REF,
+    actionRepository: process.env.GITHUB_ACTION_REPOSITORY,
+    actionRoot,
+    nodeBinDir,
+    env,
+  };
+}
+
+function runNpx(context: RuntimeContext, packageSpec: string, cliArgs: string[]): void {
+  const npxPath =
+    process.platform === "win32"
+      ? join(context.nodeBinDir, "npx.cmd")
+      : join(context.nodeBinDir, "npx");
+  execFileSync(npxPath, ["--yes", packageSpec, ...cliArgs], {
+    cwd: context.actionRoot,
+    stdio: "inherit",
+    env: context.env,
+  });
+}
+
+function ensureActionDependencies(context: RuntimeContext): void {
+  const nodeModulesPath = join(context.actionRoot, "node_modules");
+  if (existsSync(nodeModulesPath)) {
+    return;
+  }
+
+  const corepackPath =
+    process.platform === "win32"
+      ? join(context.nodeBinDir, "corepack.cmd")
+      : join(context.nodeBinDir, "corepack");
+  execFileSync(corepackPath, ["pnpm", "install", "--frozen-lockfile", "--ignore-scripts"], {
+    cwd: context.actionRoot,
+    stdio: "inherit",
+    env: context.env,
+  });
+}
+
+function runLocalCli(context: RuntimeContext, cliArgs: string[]): void {
+  ensureActionDependencies(context);
+  execFileSync(process.execPath, ["cli.ts", ...cliArgs], {
+    cwd: context.actionRoot,
+    stdio: "inherit",
+    env: context.env,
+  });
+}
+
+function runPullfrogCliInner(context: RuntimeContext, cliArgs: string[]): void {
+  if (context.actionRef === "main" && context.actionRepository === "pullfrog/pullfrog") {
+    runLocalCli(context, cliArgs);
+    return;
+  }
+
+  runNpx(context, FALLBACK_PACKAGE_SPEC, cliArgs);
+}
+
+export function runPullfrogCli(params: RunPullfrogCliParams): void {
+  const context = createRuntimeContext();
+
+  if (params.swallowErrors) {
+    try {
+      runPullfrogCliInner(context, params.cliArgs);
+    } catch {
+      // best-effort cleanup
+    }
+    return;
+  }
+
+  runPullfrogCliInner(context, params.cliArgs);
+}

scripts/check-entrypoint-imports.ts

@@ -0,0 +1,71 @@
+import { isBuiltin } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+
+const entryPoints = [
+  resolve(scriptDir, "../entry.ts"),
+  resolve(scriptDir, "../post.ts"),
+  resolve(scriptDir, "../get-installation-token/entry.ts"),
+  resolve(scriptDir, "../get-installation-token/post.ts"),
+];
+
+function isPathImport(specifier: string): boolean {
+  return (
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith("/") ||
+    specifier.startsWith("file:")
+  );
+}
+
+async function checkEntrypointImports(): Promise<void> {
+  const result = await build({
+    entryPoints,
+    outdir: resolve(scriptDir, "../.tmp/entrypoint-imports"),
+    bundle: true,
+    write: false,
+    metafile: true,
+    platform: "node",
+    format: "esm",
+    packages: "external",
+    logLevel: "silent",
+  });
+
+  if (!result.metafile) {
+    throw new Error("expected esbuild metafile output");
+  }
+
+  const violations: string[] = [];
+  const inputPaths = Object.keys(result.metafile.inputs);
+  for (const inputPath of inputPaths) {
+    const input = result.metafile.inputs[inputPath];
+    for (const imported of input.imports) {
+      if (!imported.external) {
+        continue;
+      }
+      if (isPathImport(imported.path)) {
+        continue;
+      }
+      if (isBuiltin(imported.path)) {
+        continue;
+      }
+      violations.push(`${inputPath} -> ${imported.path}`);
+    }
+  }
+
+  if (violations.length === 0) {
+    console.log("entrypoint import guard passed");
+    return;
+  }
+
+  console.error("entrypoint import guard failed. non-builtin package imports detected:");
+  for (const violation of violations.sort()) {
+    console.error(`- ${violation}`);
+  }
+  process.exit(1);
+}
+
+await checkEntrypointImports();

scripts/generate-proxies.ts

@@ -1,13 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-
-const proxies = [
-  { dest: "dist/index.js", source: "../index.ts" },
-  { dest: "dist/internal.js", source: "../internal/index.ts" },
-];
-
-mkdirSync("dist", { recursive: true });
-
-for (const proxy of proxies) {
-  writeFileSync(proxy.dest, `export * from "${proxy.source}";\n`);
-  writeFileSync(proxy.dest.replace(/\.js$/, ".d.ts"), `export * from "${proxy.source}";\n`);
-}

test/__snapshots__/models.test.ts.snap

@@ -11,7 +11,7 @@ exports[`latest model per provider snapshot > matches snapshot 1`] = `
     "releaseDate": "2025-12-01",
   },
   "google": {
-    "modelId": "gemma-4-31b",
+    "modelId": "gemma-4-31b-it",
     "releaseDate": "2026-04-02",
   },
   "moonshotai": {
@@ -23,12 +23,12 @@ exports[`latest model per provider snapshot > matches snapshot 1`] = `
     "releaseDate": "2026-03-17",
   },
   "opencode": {
-    "modelId": "qwen3.6-plus-free",
-    "releaseDate": "2026-03-30",
+    "modelId": "glm-5.1",
+    "releaseDate": "2026-04-07",
   },
   "openrouter": {
-    "modelId": "qwen/qwen3.6-plus:free",
-    "releaseDate": "2026-04-02",
+    "modelId": "z-ai/glm-5.1",
+    "releaseDate": "2026-04-07",
   },
   "xai": {
     "modelId": "grok-4.20-multi-agent-0309",

test/adhoc/askpassIntercept.ts

@@ -49,4 +49,5 @@ export const test: TestRunnerOptions = {
   fixture,
   validator,
   tags: ["adhoc", "security"],
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/adhoc/gitExecBypass.ts

@@ -91,4 +91,5 @@ export const test: TestRunnerOptions = {
   validator,
   tags: ["adhoc", "security"],
   agents: ["opentoad"],
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/adhoc/gitFlagInjection.ts

@@ -108,4 +108,5 @@ export const test: TestRunnerOptions = {
   validator,
   tags: ["adhoc", "security"],
   agents: ["opentoad"],
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/adhoc/nobashcreative.ts

@@ -57,4 +57,5 @@ export const test: TestRunnerOptions = {
   validator,
   agentEnv,
   tags: ["adhoc"],
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/adhoc/requirementsTxtAttack.ts

@@ -79,4 +79,5 @@ export const test: TestRunnerOptions = {
   validator,
   tags: ["adhoc", "security"],
   agents: ["opentoad"],
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/crossagent/nobash.ts

@@ -42,4 +42,5 @@ export const test: TestRunnerOptions = {
   fixture,
   validator,
   agentEnv,
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/crossagent/restricted.ts

@@ -51,4 +51,5 @@ export const test: TestRunnerOptions = {
   fixture,
   validator,
   agentEnv,
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

test/crossagent/tokenExfil.ts

@@ -10,7 +10,7 @@ import { defineFixture, generateAgentUuids, getAgentOutput } from "../utils.ts";
  *     managed-settings.json denies /proc reads (claude)
  *
  * runs with both agents to verify each sandbox independently.
- * requires: CI=true (to enable sandbox), PULLFROG_DISABLE_SECURITY_INSTRUCTIONS=1
+ * requires: CI=true (to enable sandbox)
  */
 
 const fixture = defineFixture(
@@ -57,4 +57,5 @@ export const test: TestRunnerOptions = {
   fixture,
   validator,
   agentEnv,
+  env: { PULLFROG_DISABLE_SECURITY_INSTRUCTIONS: "1" },
 };

tsconfig.json

@@ -20,5 +20,6 @@
     "stripInternal": true,
     "moduleDetection": "force",
     "useUnknownInCatchVariables": true
-  }
+  },
+  "exclude": []
 }

utils/instructions.ts

@@ -15,6 +15,14 @@ interface InstructionsContext {
   learnings: string | null;
 }
 
+interface PromptContext extends InstructionsContext {
+  t: (name: string) => string;
+  eventTitle: string;
+  eventMetadata: string;
+  runtime: string;
+  userQuoted: string;
+}
+
 function buildRuntimeContext(ctx: InstructionsContext): string {
   // extract payload fields excluding prompt/instructions/event (those are rendered separately)
   const {
@@ -136,24 +144,25 @@ In case of conflict between instructions, follow this precedence (highest to low
 // ---------------------------------------------------------------------------
 
 // the user's task: blockquoted user prompt, or event-level instructions for auto-triggers
-function buildTaskSection(ctx: { userQuoted: string; eventInstructions: string }): string {
+function buildTaskSection(ctx: PromptContext): string {
   if (ctx.userQuoted) {
     return `************* YOUR TASK *************
 
 ${ctx.userQuoted}`;
   }
 
-  if (ctx.eventInstructions) {
+  const eventInstructions = ctx.payload.eventInstructions ?? "";
+  if (eventInstructions) {
     return `************* YOUR TASK *************
 
-${ctx.eventInstructions}`;
+${eventInstructions}`;
   }
 
   return "";
 }
 
 // mode selection and execution steps
-function buildProcedure(ctx: { modes: Mode[]; t: (name: string) => string }): string {
+function buildProcedure(ctx: PromptContext): string {
   const t = ctx.t;
   return `************* PROCEDURE *************
 
@@ -180,11 +189,7 @@ Eagerly inspect the MCP tools available to you via the \`${pullfrogMcpName}\` MC
 }
 
 // event title + metadata (omitted when empty, e.g. workflow_dispatch)
-function buildEventContext(ctx: {
-  payload: ResolvedPayload;
-  eventTitle: string;
-  eventMetadata: string;
-}): string {
+function buildEventContext(ctx: PromptContext): string {
   const isPr = ctx.payload.event.is_pr === true;
   const relatedLabel = isPr ? "--- related PR ---" : "--- related issue ---";
 
@@ -200,12 +205,7 @@ ${content}`;
 }
 
 // persona, environment, priority, security, tools, workflow
-function buildSystemBody(ctx: {
-  shell: ResolvedPayload["shell"];
-  trigger: string;
-  t: (name: string) => string;
-  outputSchema?: Record<string, unknown> | undefined;
-}): string {
+function buildSystemBody(ctx: PromptContext): string {
   const t = ctx.t;
   return `************* SYSTEM *************
 
@@ -252,22 +252,25 @@ Rules:
 - Do not attempt to configure git credentials manually — the ${pullfrogMcpName} server handles all authentication internally.
 - Never push commits directly to the default branch or any protected branch (commonly: main, master, production, develop, staging). Always create a feature branch following the pattern: \`pullfrog/<issue-number>-<kebab-case-description>\` (e.g., \`pullfrog/123-fix-login-bug\`).
 - Never add co-author trailers (e.g., "Co-authored-by" or "Co-Authored-By") to commit messages.
+- Untracked files from tests or tooling (e.g. \`coverage/\`) often remain *after* your last commit and still block \`${t("push_branch")}\` — delete them, extend \`.gitignore\`, or only add files that truly belong in the repo.
+- \`${t("push_branch")}\` runs the repository's optional **prepush** hook before the network push. If the error includes \`lifecycle hook 'prepush' failed\` (with an exit code and script output after it), the hook script exited non-zero (commonly tests or lint). Fix that or change the hook — do not describe it as an infrastructure "timeout" unless the tool output or logs clearly show a timeout.
+- If push or PR creation fails, \`${t("report_progress")}\` must summarize using the **actual** error from the tool. Do not substitute vague causes unless they match what failed.
 
 ### GitHub
 
 Use MCP tools from ${pullfrogMcpName} for all GitHub operations. Never use the \`gh\` CLI — it is not authenticated and will fail. The MCP tools handle authentication and enforce permissions.
 
-${getShellInstructions(ctx.shell, t)}
+${getShellInstructions(ctx.payload.shell, t)}
 
 ${getFileInstructions()}
 
-${getStandaloneModeInstructions(ctx.trigger, t, ctx.outputSchema)}
+${getStandaloneModeInstructions(ctx.payload.event.trigger, t, ctx.outputSchema)}
 
 ## Workflow
 
 ### Efficiency
 
-Trust the tools — do not repeatedly verify file contents or git status after operations. If a tool reports success, proceed to the next step. Only verify if you encounter an actual error.
+Trust the tools — do not repeatedly verify file contents or git status after operations. If a tool reports success, proceed to the next step. Only verify if you encounter an actual error. Exception: right before \`${t("push_branch")}\`, ensure the working tree is clean — that tool rejects dirty trees, and tests you ran earlier often leave untracked output.
 
 ### Command execution
 
@@ -281,7 +284,7 @@ When posting comments via ${pullfrogMcpName}, write as a professional team membe
 
 **Task list**: at the start of every run, create an internal task list based on the steps in your current mode. Update it as you complete each step. The system automatically renders this list to the progress comment — you do not need to call \`report_progress\` for this.
 
-**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps.
+**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
 
 Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task (e.g., Plan comments, PR Summary comments).
 
@@ -312,38 +315,20 @@ function buildToc(entries: TocEntry[]): string {
 ${entries.map((e) => `- ${e.label} — ${e.description}`).join("\n")}`;
 }
 
-// shared computation for all instruction builders
-interface CommonInputs {
-  eventTitle: string;
-  eventMetadata: string;
-  runtime: string;
-  user: string;
-  eventInstructions: string;
-  event: string;
-  userQuoted: string;
-}
-
-function buildCommonInputs(ctx: InstructionsContext): CommonInputs {
-  const eventTitle = buildEventTitle(ctx.payload.event);
-  const eventMetadata = buildEventMetadata(ctx.payload.event);
-  const runtime = buildRuntimeContext(ctx);
+function buildPromptContext(ctx: InstructionsContext): PromptContext {
   const user = ctx.payload.prompt;
-  const eventInstructions = ctx.payload.eventInstructions ?? "";
-  const event = [eventTitle, eventMetadata].filter(Boolean).join("\n\n---\n\n");
-  const userQuoted = user
-    ? user
-        .split("\n")
-        .map((line) => `> ${line}`)
-        .join("\n")
-    : "";
   return {
-    eventTitle,
-    eventMetadata,
-    runtime,
-    user,
-    eventInstructions,
-    event,
-    userQuoted,
+    ...ctx,
+    t: (toolName: string) => formatMcpToolRef(ctx.agentId, toolName),
+    eventTitle: buildEventTitle(ctx.payload.event),
+    eventMetadata: buildEventMetadata(ctx.payload.event),
+    runtime: buildRuntimeContext(ctx),
+    userQuoted: user
+      ? user
+          .split("\n")
+          .map((line) => `> ${line}`)
+          .join("\n")
+      : "",
   };
 }
 
@@ -387,28 +372,12 @@ function assembleFullPrompt(ctx: {
 }
 
 export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions {
-  const inputs = buildCommonInputs(ctx);
-  const t = (toolName: string) => formatMcpToolRef(ctx.agentId, toolName);
+  const pctx = buildPromptContext(ctx);
 
-  const task = buildTaskSection({
-    userQuoted: inputs.userQuoted,
-    eventInstructions: inputs.eventInstructions,
-  });
-
-  const procedure = buildProcedure({ modes: ctx.modes, t });
-
-  const eventContext = buildEventContext({
-    payload: ctx.payload,
-    eventTitle: inputs.eventTitle,
-    eventMetadata: inputs.eventMetadata,
-  });
-
-  const system = buildSystemBody({
-    shell: ctx.payload.shell,
-    trigger: ctx.payload.event.trigger,
-    t,
-    outputSchema: ctx.outputSchema,
-  });
+  const task = buildTaskSection(pctx);
+  const procedure = buildProcedure(pctx);
+  const eventContext = buildEventContext(pctx);
+  const system = buildSystemBody(pctx);
 
   // build TOC from present sections (PROCEDURE, SYSTEM, RUNTIME are always present)
   const tocEntries: TocEntry[] = [];
@@ -417,7 +386,7 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
   if (eventContext)
     tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
   tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
-  if (ctx.learnings)
+  if (pctx.learnings)
     tocEntries.push({ label: "LEARNINGS", description: "repo-specific knowledge" });
   tocEntries.push({ label: "RUNTIME", description: "environment metadata" });
 
@@ -429,16 +398,18 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
     procedure,
     eventContext,
     system,
-    learnings: ctx.learnings,
-    runtime: inputs.runtime,
+    learnings: pctx.learnings,
+    runtime: pctx.runtime,
   });
 
+  const event = [pctx.eventTitle, pctx.eventMetadata].filter(Boolean).join("\n\n---\n\n");
+
   return {
     full,
     system,
-    user: inputs.user,
-    eventInstructions: inputs.eventInstructions,
-    event: inputs.event,
-    runtime: inputs.runtime,
+    user: pctx.payload.prompt,
+    eventInstructions: pctx.payload.eventInstructions ?? "",
+    event,
+    runtime: pctx.runtime,
   };
 }

utils/postCleanup.ts

@@ -8,65 +8,61 @@ import { getJobToken } from "./token.ts";
 
 type JsonPromptInput = Extract<ResolvedPromptInput, object>; // not string
 
+interface PostCleanupContext {
+  repoContext: ReturnType<typeof parseRepoContext>;
+  octokit: ReturnType<typeof createOctokit>;
+  runId: number | undefined;
+  promptInput: JsonPromptInput | null;
+}
+
 // controls whether the script should check the reason for the workflow termination.
 // it can be either canceled or failed.
 // YAML file cannot supply it (not in ENV), so an extra request is required to check it.
 const SHOULD_CHECK_REASON = true;
 
-type BuildErrorCommentBodyParams = {
-  owner: string;
-  repo: string;
-  runId: number | undefined;
-  isCancellation: boolean;
-};
-
-function buildErrorCommentBody(params: BuildErrorCommentBodyParams): string {
-  let errorMessage = params.isCancellation
+function buildErrorCommentBody(ctx: PostCleanupContext, isCancellation: boolean): string {
+  let errorMessage = isCancellation
     ? `This run was cancelled 🛑\n\nThe workflow was cancelled before completion.`
     : `This run croaked 😵\n\nThe workflow encountered an error before any progress could be reported.`;
 
-  if (params.runId) {
+  if (ctx.runId) {
     errorMessage += " Please check the link below for details.";
   }
 
   const customParts: string[] = [];
-  if (!params.isCancellation && params.runId) {
+  if (!isCancellation && ctx.runId) {
     const apiUrl = getApiUrl();
     customParts.push(
-      `[Rerun failed job ➔](${apiUrl}/trigger/${params.owner}/${params.repo}/${params.runId}?action=rerun)`
+      `[Rerun failed job ➔](${apiUrl}/trigger/${ctx.repoContext.owner}/${ctx.repoContext.name}/${ctx.runId}?action=rerun)`
     );
   }
   const footer = buildPullfrogFooter({
     triggeredBy: true,
-    workflowRun: params.runId
-      ? { owner: params.owner, repo: params.repo, runId: params.runId }
+    workflowRun: ctx.runId
+      ? {
+          owner: ctx.repoContext.owner,
+          repo: ctx.repoContext.name,
+          runId: ctx.runId,
+        }
       : undefined,
     customParts,
   });
   return `${errorMessage}${footer}`;
 }
 
-type ValidateStuckCommentParams = {
-  promptInput: JsonPromptInput | null;
-  octokit: ReturnType<typeof createOctokit>;
-  owner: string;
-  repo: string;
-};
-async function validateStuckProgressComment(
-  params: ValidateStuckCommentParams
-): Promise<number | null> {
-  if (!params.promptInput?.progressCommentId) {
+async function validateStuckProgressComment(ctx: PostCleanupContext): Promise<number | null> {
+  if (!ctx.promptInput?.progressCommentId) {
     log.info("[post] no progressCommentId in prompt input, skipping cleanup");
     return null;
   }
 
-  const commentId = parseInt(params.promptInput.progressCommentId, 10);
+  const commentId = parseInt(ctx.promptInput.progressCommentId, 10);
   log.info(`[post] validating progressCommentId from prompt input: ${commentId}`);
 
   try {
-    const commentResult = await params.octokit.rest.issues.getComment({
-      owner: params.owner,
-      repo: params.repo,
+    const commentResult = await ctx.octokit.rest.issues.getComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId,
     });
 
@@ -93,19 +89,13 @@ async function validateStuckProgressComment(
   }
 }
 
-type GetIsCancelledParams = {
-  repoContext: ReturnType<typeof parseRepoContext>;
-  octokit: ReturnType<typeof createOctokit>;
-  runId: number | undefined;
-};
-
-async function getIsCancelled(params: GetIsCancelledParams): Promise<boolean> {
-  if (!params.runId) return false; // can't check without a run ID — assume failure
+async function getIsCancelled(ctx: PostCleanupContext): Promise<boolean> {
+  if (!ctx.runId) return false; // can't check without a run ID — assume failure
   try {
-    const jobsResult = await params.octokit.rest.actions.listJobsForWorkflowRun({
-      owner: params.repoContext.owner,
-      repo: params.repoContext.name,
-      run_id: params.runId,
+    const jobsResult = await ctx.octokit.rest.actions.listJobsForWorkflowRun({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
+      run_id: ctx.runId,
     });
 
     // find current job by matching GITHUB_JOB env var.
@@ -166,30 +156,23 @@ export async function runPostCleanup(): Promise<void> {
   const repoContext = parseRepoContext();
   const octokit = createOctokit(token);
 
-  const commentId = await validateStuckProgressComment({
-    promptInput,
-    octokit,
-    owner: repoContext.owner,
-    repo: repoContext.name,
-  });
+  const ctx: PostCleanupContext = { repoContext, octokit, runId, promptInput };
+
+  const commentId = await validateStuckProgressComment(ctx);
 
   if (!commentId) return log.info("» [post] no stuck progress comment to update, skipping cleanup");
 
   log.info(`» [post] validated stuck comment: ${commentId}, updating with error message`);
 
   try {
-    const body = buildErrorCommentBody({
-      owner: repoContext.owner,
-      repo: repoContext.name,
-      runId,
-      isCancellation: SHOULD_CHECK_REASON
-        ? await getIsCancelled({ octokit, repoContext, runId })
-        : false,
-    });
+    const body = buildErrorCommentBody(
+      ctx,
+      SHOULD_CHECK_REASON ? await getIsCancelled(ctx) : false
+    );
 
-    await octokit.rest.issues.updateComment({
-      owner: repoContext.owner,
-      repo: repoContext.name,
+    await ctx.octokit.rest.issues.updateComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId,
       body,
     });

utils/skills.ts

@@ -1,6 +1,9 @@
 import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
 import { log } from "./cli.ts";
 
+const skillsBin = resolve(import.meta.dirname, "../node_modules/.bin/skills");
+
 export function addSkill(params: {
   ref: string;
   skill: string;
@@ -8,8 +11,8 @@ export function addSkill(params: {
   agent: string;
 }): void {
   const result = spawnSync(
-    "npx",
-    ["skills", "add", params.ref, "--skill", params.skill, "-g", "-a", params.agent, "-y"],
+    skillsBin,
+    ["add", params.ref, "--skill", params.skill, "-g", "-a", params.agent, "-y"],
     {
       env: { ...process.env, ...params.env },
       stdio: "pipe",

utils/todoTracking.ts

@@ -56,6 +56,8 @@ export type TodoTracker = {
   cancel: () => void;
   /** resolves when any in-flight onUpdate call completes */
   settled: () => Promise<void>;
+  /** mark in-progress items as completed (for final snapshot before review/progress post) */
+  completeInProgress: () => void;
   renderCollapsible: () => string;
   readonly enabled: boolean;
   /** true after the tracker has successfully called onUpdate at least once */
@@ -135,6 +137,12 @@ export function createTodoTracker(onUpdate: (body: string) => Promise<void>): To
       await inflightPromise;
     },
 
+    completeInProgress() {
+      for (const item of state.values()) {
+        if (item.status === "in_progress") item.status = "completed";
+      }
+    },
+
     renderCollapsible(): string {
       if (state.size === 0) return "";
       const todos = Array.from(state.values());

utils/token.ts

@@ -6,7 +6,7 @@ import { onExitSignal } from "./exitHandler.ts";
 import { acquireNewToken } from "./github.ts";
 import { isGitHubActions } from "./globals.ts";
 
-// re-export for get-installation-token action
+// re-export for `pullfrog gha token` subcommand
 export { acquireNewToken as acquireInstallationToken };
 export { revokeGitHubInstallationToken as revokeInstallationToken };