@trim21/personal-pi-extensions 0.1.550 → 0.1.552

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.550",
+  "version": "0.1.552",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/gh-readonly.ts

@@ -95,7 +95,7 @@ export function isGhAvailable(): boolean {
   return false;
 }
 
-export async function runGh(
+export function runGh(
   args: string[],
   ctx: {
     cwd?: string;
@@ -105,15 +105,13 @@ export async function runGh(
     env?: NodeJS.ProcessEnv;
   },
 ): Promise<GhResult> {
-  const proxyEnv = await ghProxy.env();
-
   return new Promise((resolve) => {
     const proc = spawn("gh", args, {
       cwd: ctx.cwd,
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
       // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
-      env: { ...process.env, ...proxyEnv, ...ctx.env, GH_PAGER: "cat" },
+      env: { ...process.env, ...ghProxy.env, ...ctx.env, GH_PAGER: "cat" },
     });
 
     let stdout = "";
@@ -349,16 +347,14 @@ function toToolResult(
  * tool's id parameter, e.g. `repo=x/y number=123`. Returns undefined when
  * neither is available, so the pendant is omitted rather than shown empty.
  */
-function subtitlePendant(
-  params: { repo?: string } & Record<string, unknown>,
-  idKey?: string,
+function subtitlePendant<IdKey extends string = never>(
+  params: { repo?: string } & Partial<Record<IdKey, string | number>>,
+  idKey?: IdKey,
 ): ToolPendant | undefined {
   const parts: string[] = [];
   if (params.repo) parts.push(`repo=${params.repo}`);
-  if (idKey) {
-    const id = params[idKey];
-    if (typeof id === "string" || typeof id === "number") parts.push(`${idKey}=${id}`);
-  }
+  const id = idKey === undefined ? undefined : params[idKey];
+  if (typeof id === "string" || typeof id === "number") parts.push(`${idKey}=${id}`);
   if (parts.length === 0) return undefined;
   return { subtitle: parts.join(" ") };
 }
@@ -756,7 +752,7 @@ export function extractStepFromLog(
 
 // ── ci-logs rendering (pure, testable) ──────────────────────────────────────
 
-export interface CiLogsResult {
+export interface ToolResult {
   content: { type: "text"; text: string }[];
   details: Record<string, unknown>;
 }
@@ -978,7 +974,7 @@ export interface PollPrChecksOptions {
   /** Test overrides. */
   intervalMs?: number;
   deadlineMs?: number;
-  onUpdate?: (msg: CiLogsResult) => void;
+  onUpdate?: (msg: ToolResult) => void;
 }
 
 /**
@@ -1136,45 +1132,243 @@ export function renderChecksVerdict(options: {
   };
 }
 
-// ── tools ────────────────────────────────────────────────────────────────────
+// ── GitHub REST client ───────────────────────────────────────────────────────
 
-export default function ghReadonlyTools(pi: ExtensionAPI) {
-  // Windows 上禁用：gh 可执行文件的探测（无扩展名 + POSIX 路径）与进程
-  // 管理（SIGTERM 信号语义）都是 POSIX 假设，不做 Windows 适配。
-  if (process.platform === "win32") {
-    pi.on("session_start", (_event, ctx) => {
-      ctx.ui.notify("gh-readonly tools are disabled on Windows.", "warning");
-    });
-    return;
+/** Toolcall input for the handlers that read through the REST API. */
+interface PrStatusParams {
+  number: number | string;
+  repo?: string;
+}
+
+interface RunIdParams {
+  run_id: number | string;
+  repo?: string;
+}
+
+interface JobIdParams {
+  job_id: number | string;
+  repo?: string;
+}
+
+interface PrChecksWaitParams {
+  number: number | string;
+  repo?: string;
+  fail_fast?: boolean;
+}
+
+interface CommitChecksWaitParams {
+  commit: number | string;
+  repo?: string;
+  event?: string;
+  fail_fast?: boolean;
+}
+
+/** What a toolcall handler receives from the framework. */
+export interface ToolCall<Params> {
+  params: Params;
+  ctx: { cwd?: string };
+  signal?: AbortSignal;
+  /** Streaming progress updates, passed through as-is. */
+  onUpdate?: (update: ToolResult) => void;
+}
+
+/**
+ * The GitHub reads that go through the REST API, with the HTTP layer injected:
+ * production hands in the proxy-aware fetch, tests hand in a stub and never
+ * touch the network. Handlers that only shell out to `gh` stay plain functions.
+ *
+ * `fetch` is a property (not module state) so a caller that needs different HTTP
+ * behavior — a test, another host — constructs its own instance.
+ */
+export class GhClient {
+  readonly fetch: typeof globalThis.fetch;
+  private readonly search: GithubSearch;
+  private readonly checks: GithubChecksClient;
+
+  constructor(fetchImpl: typeof globalThis.fetch = ghProxy.fetch) {
+    this.fetch = fetchImpl;
+    this.search = createGithubSearch({ fetch: fetchImpl });
+    this.checks = createGithubChecks({ fetch: fetchImpl });
   }
 
-  // Fail fast: the `gh` CLI is the only backend for these tools. Without it the
-  // extension registers nothing and reports the problem at session start, so
-  // the user gets one clear error instead of a dozen failing tool calls.
-  if (!isGhAvailable()) {
-    pi.on("session_start", (_event, ctx) => {
-      ctx.ui.notify(
-        "gh CLI not found in PATH: GitHub read-only tools are disabled. Install GitHub CLI (https://cli.github.com/) and reload the session.",
-        "error",
-      );
-    });
-    return;
+  /** `list-github-issues` / `list-github-prs`: browse through `gh`, search through the API. */
+  private async list(kind: "issue" | "pr", call: ToolCall<ListFilters>): Promise<ToolResult> {
+    const { params, ctx, signal } = call;
+    const result = toToolResult(
+      params.keywords
+        ? await searchList(kind, params, this.search)
+        : await listGithub(kind, params, { cwd: ctx.cwd, signal, input: params }),
+      params,
+    );
+    result.details.pendant = subtitlePendant(params);
+    return result;
+  }
+
+  listIssues(call: ToolCall<ListFilters>): Promise<ToolResult> {
+    return this.list("issue", call);
   }
 
-  pi.on("session_start", async (_event, ctx) => {
-    // 代理配置读不出来（JSON 语法错、字段类型错、proxy 不是 http(s) URL）时只告警，
-    // 工具按直连继续工作——配置写错不该让整套 GitHub 工具不可用。
-    const { error } = await ghProxy.load();
-    if (!error) return;
+  listPrs(call: ToolCall<ListFilters>): Promise<ToolResult> {
+    return this.list("pr", call);
+  }
+
+  /**
+   * `read-github-pr-status`: the PR head commit's checks as a snapshot. Same read
+   * path as the wait tools (octokit), but it never polls — pending checks come
+   * back as-is.
+   */
+  async prStatus(call: ToolCall<PrStatusParams>): Promise<ToolResult> {
+    const { params, ctx, signal } = call;
+    const { number, repo } = params;
+    const pullNumber = toPositiveId(number, "number");
+    const pendant = subtitlePendant(params, "number");
+    const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+    const { owner, repo: name } = splitRepo(effectiveRepo);
+
+    const pollSignal = signal ?? new AbortController().signal;
+    const headSha = await this.checks.pullHead(owner, name, pullNumber, pollSignal);
+    const [statuses, checkRuns] = await Promise.all([
+      this.checks.statuses(owner, name, headSha, pollSignal),
+      this.checks.checkRuns(owner, name, headSha, pollSignal),
+    ]);
+    const checks = mergeChecks(statuses, checkRuns).map((check) => ({
+      name: check.name,
+      bucket: check.bucket,
+      event: check.event,
+      run_id: check.runId,
+      job_id: check.jobId,
+      url: check.link,
+    }));
+
+    const payload = { pr: pullNumber, repo: effectiveRepo, head_sha: headSha, checks };
+    return {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      details: { ...payload, input: params, ...(pendant && { pendant }) },
+    };
+  }
+
+  /** `get-github-workflow-jobs`: every job of a run, all pages. */
+  async workflowJobs(call: ToolCall<RunIdParams>): Promise<ToolResult> {
+    const { params, ctx, signal } = call;
+    const runId = toPositiveId(params.run_id, "run_id");
+    const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
+    const { owner, repo: name } = splitRepo(effectiveRepo);
+
+    const jobs = await this.checks.runJobs(owner, name, runId, signal);
+    const result = toToolResult(JSON.stringify({ total_count: jobs.length, jobs }), params);
+    result.details.pendant = subtitlePendant(params, "run_id");
+    return result;
+  }
+
+  /** `read-github-ci-logs`: one job's raw log on disk plus its step line ranges. */
+  async ciLogs(call: ToolCall<JobIdParams>): Promise<ToolResult> {
+    const { params, ctx, signal, onUpdate } = call;
+    const { job_id, repo } = params;
+    const jobId = toPositiveId(job_id, "job_id");
+
+    const pendant = subtitlePendant(params, "job_id");
+    const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+    const { owner, repo: name } = splitRepo(effectiveRepo);
+
+    const failure = (text: string): ToolResult => ({
+      content: [{ type: "text", text }],
+      details: { input: params, ...(pendant && { pendant }) },
+    });
+
+    let target: RunJob;
     try {
-      ctx.ui.notify(`gh proxy config ignored: ${error}`, "warning");
-    } catch {
-      // 读取期间 session 可能已被替换，失效的 ctx 直接忽略
+      target = await this.checks.job(owner, name, jobId, signal);
+    } catch (error) {
+      const status = (error as { status?: number }).status;
+      if (status !== 404) throw error;
+      return failure(
+        `Job ${jobId} not found in ${effectiveRepo} — job IDs come from \`get-github-workflow-jobs\`.`,
+      );
     }
-  });
 
-  const githubSearch = createGithubSearch({ fetch: ghProxy.fetch });
-  const githubChecks = createGithubChecks({ fetch: ghProxy.fetch });
+    if (target.status === "queued") {
+      return failure(
+        `Job "${target.name}" is still queued — no logs available yet. Use \`watch-github-run\` to wait for it to start, then retry.`,
+      );
+    }
+
+    onUpdate?.({
+      content: [{ type: "text", text: `Fetching log of job "${target.name}"...` }],
+      details: {},
+    });
+
+    const rawLog = await getJobLog(target, signal, ctx.cwd, params);
+    const index = jobLogIndex(target, rawLog);
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(index, null, 2) }],
+      details: { ...index, input: params, ...(pendant && { pendant }) },
+    };
+  }
+
+  /** `wait-github-pr-checks`: poll the PR's head commit checks until they settle. */
+  async waitPrChecks(call: ToolCall<PrChecksWaitParams>): Promise<ToolResult> {
+    const { params, ctx, signal, onUpdate } = call;
+    const { number, repo, fail_fast } = params;
+
+    const pendant = subtitlePendant(params, "number");
+    onUpdate?.({
+      content: [{ type: "text", text: `Watching CI checks for PR #${number}...` }],
+      details: {},
+    });
+
+    const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+    const { owner, repo: repoName } = splitRepo(effectiveRepo);
+
+    const prOut = await ghExec(
+      ["pr", "view", String(number), "--repo", effectiveRepo, "--json", "headRefOid"],
+      { cwd: ctx.cwd, signal, input: params },
+    );
+    const { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
+
+    return this.waitChecksReport({
+      subject: `PR #${number}`,
+      owner,
+      repo: repoName,
+      headSha: headRefOid,
+      failFast: fail_fast === true,
+      signal,
+      onUpdate,
+      params,
+      pendant,
+    });
+  }
+
+  /** `wait-github-commit-checks`: same, addressed by commit/branch/tag instead of a PR. */
+  async waitCommitChecks(call: ToolCall<CommitChecksWaitParams>): Promise<ToolResult> {
+    const { params, ctx, signal, onUpdate } = call;
+    const { commit, repo, event, fail_fast } = params;
+
+    const pendant = subtitlePendant(params, "commit");
+    onUpdate?.({
+      content: [{ type: "text", text: `Watching CI checks for commit ${commit}...` }],
+      details: {},
+    });
+
+    const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+    const { owner, repo: repoName } = splitRepo(effectiveRepo);
+
+    const pollSignal = signal ?? new AbortController().signal;
+    const sha = await this.checks.headSha(owner, repoName, String(commit), pollSignal);
+
+    return this.waitChecksReport({
+      subject: `commit ${sha.slice(0, 7)}`,
+      owner,
+      repo: repoName,
+      headSha: sha,
+      failFast: fail_fast === true,
+      event,
+      signal,
+      onUpdate,
+      params,
+      pendant,
+    });
+  }
 
   /**
    * Shared wait core of `wait-github-pr-checks` and
@@ -1182,7 +1376,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
    * reports with Actions job details (display-only), render the verdict.
    * The caller resolves repo/headSha; `subject` formats the report header.
    */
-  async function waitChecksReport(options: {
+  private async waitChecksReport(options: {
     subject: string;
     owner: string;
     repo: string;
@@ -1190,10 +1384,10 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     failFast: boolean;
     event?: string;
     signal: AbortSignal | undefined;
-    onUpdate: ((msg: CiLogsResult) => void) | undefined;
+    onUpdate: ((msg: ToolResult) => void) | undefined;
     params: unknown;
     pendant?: ToolPendant;
-  }) {
+  }): Promise<ToolResult> {
     const { subject, owner, repo, headSha, failFast, event, signal, onUpdate, params, pendant } =
       options;
 
@@ -1207,7 +1401,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       headSha,
       failFast,
       event,
-      checks: githubChecks,
+      checks: this.checks,
       signal: pollSignal,
       onUpdate,
     });
@@ -1218,7 +1412,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     let enrichmentError: string | undefined;
     if (poll.checks.some((c) => c.bucket === "fail")) {
       try {
-        actionJobs = await githubChecks.actionJobs(owner, repo, headSha, pollSignal);
+        actionJobs = await this.checks.actionJobs(owner, repo, headSha, pollSignal);
       } catch (error) {
         enrichmentError =
           error instanceof Error ? error.message : "Actions job details unavailable";
@@ -1227,7 +1421,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
 
     const verdict = renderChecksVerdict({ subject, poll, actionJobs, enrichmentError });
     return {
-      content: [{ type: "text" as const, text: verdict.text }],
+      content: [{ type: "text", text: verdict.text }],
       details: {
         status: verdict.status,
         totalChecks: poll.checks.length,
@@ -1238,6 +1432,34 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       },
     };
   }
+}
+
+// ── tools ────────────────────────────────────────────────────────────────────
+
+export default function ghReadonlyTools(pi: ExtensionAPI) {
+  // Windows 上禁用：gh 可执行文件的探测（无扩展名 + POSIX 路径）与进程
+  // 管理（SIGTERM 信号语义）都是 POSIX 假设，不做 Windows 适配。
+  if (process.platform === "win32") {
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify("gh-readonly tools are disabled on Windows.", "warning");
+    });
+    return;
+  }
+
+  // Fail fast: the `gh` CLI is the only backend for these tools. Without it the
+  // extension registers nothing and reports the problem at session start, so
+  // the user gets one clear error instead of a dozen failing tool calls.
+  if (!isGhAvailable()) {
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify(
+        "gh CLI not found in PATH: GitHub read-only tools are disabled. Install GitHub CLI (https://cli.github.com/) and reload the session.",
+        "error",
+      );
+    });
+    return;
+  }
+
+  const client = new GhClient();
 
   // ── read-github-issue ──────────────────────────────────────────────────────
   pi.registerTool({
@@ -1300,15 +1522,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         }),
       ),
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const result = toToolResult(
-        params.keywords
-          ? await searchList("issue", params, githubSearch)
-          : await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return client.listIssues({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1373,15 +1588,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         }),
       ),
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const result = toToolResult(
-        params.keywords
-          ? await searchList("pr", params, githubSearch)
-          : await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return client.listPrs({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1418,35 +1626,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
       repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const pullNumber = toPositiveId(number, "number");
-      const pendant = subtitlePendant(params, "number");
-      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const { owner, repo: name } = splitRepo(effectiveRepo);
-
-      // 与 wait 工具同一条读取路径（octokit），只是这里不轮询：pending 的 check
-      // 原样返回，等结果走 wait-github-pr-checks。
-      const pollSignal = signal ?? new AbortController().signal;
-      const headSha = await githubChecks.pullHead(owner, name, pullNumber, pollSignal);
-      const [statuses, checkRuns] = await Promise.all([
-        githubChecks.statuses(owner, name, headSha, pollSignal),
-        githubChecks.checkRuns(owner, name, headSha, pollSignal),
-      ]);
-      const checks = mergeChecks(statuses, checkRuns).map((check) => ({
-        name: check.name,
-        bucket: check.bucket,
-        event: check.event,
-        run_id: check.runId,
-        job_id: check.jobId,
-        url: check.link,
-      }));
-
-      const payload = { pr: pullNumber, repo: effectiveRepo, head_sha: headSha, checks };
-      return {
-        content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
-        details: { ...payload, input: params, ...(pendant && { pendant }) },
-      };
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return client.prStatus({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1582,47 +1763,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
     }),
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { job_id, repo } = params;
-      const jobId = toPositiveId(job_id, "job_id");
-
-      const pendant = subtitlePendant(params, "job_id");
-      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const { owner, repo: name } = splitRepo(effectiveRepo);
-
-      const failure = (text: string): CiLogsResult => ({
-        content: [{ type: "text", text }],
-        details: { input: params, ...(pendant && { pendant }) },
-      });
-
-      let target: RunJob;
-      try {
-        target = await githubChecks.job(owner, name, jobId, signal);
-      } catch (error) {
-        const status = (error as { status?: number }).status;
-        if (status !== 404) throw error;
-        return failure(
-          `Job ${jobId} not found in ${effectiveRepo} — job IDs come from \`get-github-workflow-jobs\`.`,
-        );
-      }
-
-      if (target.status === "queued") {
-        return failure(
-          `Job "${target.name}" is still queued — no logs available yet. Use \`watch-github-run\` to wait for it to start, then retry.`,
-        );
-      }
-
-      onUpdate?.({
-        content: [{ type: "text", text: `Fetching log of job "${target.name}"...` }],
-        details: {},
-      });
-
-      const rawLog = await getJobLog(target, signal, ctx.cwd, params);
-      const index = jobLogIndex(target, rawLog);
-
-      return {
-        content: [{ type: "text", text: JSON.stringify(index, null, 2) }],
-        details: { ...index, input: params, ...(pendant && { pendant }) },
-      };
+      return client.ciLogs({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1637,15 +1778,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
       repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { run_id, repo } = params;
-      const runId = toPositiveId(run_id, "run_id");
-      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const { owner, repo: name } = splitRepo(effectiveRepo);
-      const jobs = await githubChecks.runJobs(owner, name, runId, signal);
-      const result = toToolResult(JSON.stringify({ total_count: jobs.length, jobs }), params);
-      result.details.pendant = subtitlePendant(params, "run_id");
-      return result;
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return client.workflowJobs({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1738,34 +1872,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       ),
     }),
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { number, repo, fail_fast } = params;
-
-      const pendant = subtitlePendant(params, "number");
-      onUpdate?.({
-        content: [{ type: "text", text: `Watching CI checks for PR #${number}...` }],
-        details: {},
-      });
-
-      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const { owner, repo: repoName } = splitRepo(effectiveRepo);
-
-      const prOut = await ghExec(
-        ["pr", "view", String(number), "--repo", effectiveRepo, "--json", "headRefOid"],
-        { cwd: ctx.cwd, signal, input: params },
-      );
-      const { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
-
-      return waitChecksReport({
-        subject: `PR #${number}`,
-        owner,
-        repo: repoName,
-        headSha: headRefOid,
-        failFast: fail_fast === true,
-        signal,
-        onUpdate,
-        params,
-        pendant,
-      });
+      return client.waitPrChecks({ params, ctx, signal, onUpdate });
     },
   });
 
@@ -1798,32 +1905,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       ),
     }),
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { commit, repo, event, fail_fast } = params;
-
-      const pendant = subtitlePendant(params, "commit");
-      onUpdate?.({
-        content: [{ type: "text", text: `Watching CI checks for commit ${commit}...` }],
-        details: {},
-      });
-
-      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const { owner, repo: repoName } = splitRepo(effectiveRepo);
-
-      const pollSignal = signal ?? new AbortController().signal;
-      const sha = await githubChecks.headSha(owner, repoName, String(commit), pollSignal);
-
-      return waitChecksReport({
-        subject: `commit ${sha.slice(0, 7)}`,
-        owner,
-        repo: repoName,
-        headSha: sha,
-        failFast: fail_fast === true,
-        event,
-        signal,
-        onUpdate,
-        params,
-        pendant,
-      });
+      return client.waitCommitChecks({ params, ctx, signal, onUpdate });
     },
   });
 

package/src/lib/gh-proxy.ts

@@ -5,12 +5,15 @@
  *   - ~/.pi/agent/gh.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost,.corp" }
  *   - HTTPS_PROXY / HTTP_PROXY / ALL_PROXY（小写变体同样接受）、NO_PROXY
  *
- * 两条出口共用同一份配置：
- *   - gh CLI 子进程：env() 给出要注入子进程的 HTTP(S)_PROXY / NO_PROXY 等变量
+ * 两条出口共用同一份配置，且在扩展加载时一次性读完：
+ *   - gh CLI 子进程：env 给出要注入子进程的 HTTP(S)_PROXY / NO_PROXY 等变量
  *   - octokit 请求：fetch 是挂了代理 dispatcher 的 fetch；未配置代理时就是全局 fetch
+ *
+ * 配置有错（JSON 语法错、字段类型不符、proxy 不是 http(s) URL）直接抛错——扩展
+ * 加载即失败，而不是带着一份被忽略的配置静默直连。
  */
 
-import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -63,54 +66,55 @@ function firstEnv(names: readonly string[], env: NodeJS.ProcessEnv): string | un
 }
 
 /** 代理必须是 http(s) URL：undici 的 ProxyAgent 只支持 HTTP CONNECT 代理。 */
-function normalizeProxy(value: string | undefined): { proxy?: string; error?: string } {
-  if (!value) return {};
+function normalizeProxy(value: string): string {
   let protocol: string;
   try {
     protocol = new URL(value).protocol;
   } catch {
-    return { error: `invalid proxy URL: ${value}` };
+    throw new Error(`invalid proxy URL: ${value}`);
   }
   if (protocol !== "http:" && protocol !== "https:") {
-    return { error: `unsupported proxy protocol: ${value} (expected http:// or https://)` };
+    throw new Error(`unsupported proxy protocol: ${value} (expected http:// or https://)`);
   }
-  return { proxy: value };
-}
-
-export interface GhProxyLoad {
-  /** 生效的代理设置（配置文件与环境变量合并后的结果）。 */
-  settings: GhProxySettings;
-  /** 配置读取/解析失败的原因；未失败时为 undefined。 */
-  error?: string;
-}
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return value;
 }
 
-/** 读配置文件；文件不存在视为未配置，其它失败只记录不抛出。 */
-async function readConfigFile(configPath: string): Promise<GhProxyLoad> {
-  let raw: string;
+/**
+ * 同步读配置：扩展加载时调用一次（node:fs/promises 在同步的初始化路径上用不了，
+ * 这里是仓库里允许的同步例外）。文件不存在 = 未配置；文件读不了、JSON 非法或
+ * 字段不符都直接抛。
+ */
+export function readGhProxySettings(
+  configPath: string = ghProxyConfigPath(),
+  env: NodeJS.ProcessEnv = process.env,
+): GhProxySettings {
+  let raw: string | undefined;
   try {
-    raw = await readFile(configPath, "utf8");
+    raw = readFileSync(configPath, "utf8");
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { settings: {} };
-    return { settings: {}, error: `${configPath}: ${describeError(error)}` };
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(`${configPath}: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      });
+    }
   }
-  try {
-    return { settings: parseGhProxyConfig(JSON.parse(raw)) };
-  } catch (error) {
-    return { settings: {}, error: `${configPath}: ${describeError(error)}` };
+
+  let file: GhProxySettings = {};
+  if (raw !== undefined) {
+    try {
+      file = parseGhProxyConfig(JSON.parse(raw));
+    } catch (error) {
+      throw new Error(`${configPath}: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      });
+    }
   }
-}
 
-async function resolveSettings(configPath: string, env: NodeJS.ProcessEnv): Promise<GhProxyLoad> {
-  const file = await readConfigFile(configPath);
-  const normalized = normalizeProxy(file.settings.proxy ?? firstEnv(PROXY_ENV_NAMES, env));
-  const noProxy = file.settings.noProxy ?? firstEnv(NO_PROXY_ENV_NAMES, env);
+  const proxy = file.proxy ?? firstEnv(PROXY_ENV_NAMES, env);
+  const noProxy = file.noProxy ?? firstEnv(NO_PROXY_ENV_NAMES, env);
   return {
-    settings: { ...(normalized.proxy && { proxy: normalized.proxy }), ...(noProxy && { noProxy }) },
-    error: file.error ?? normalized.error,
+    ...(proxy && { proxy: normalizeProxy(proxy) }),
+    ...(noProxy && { noProxy }),
   };
 }
 
@@ -132,61 +136,51 @@ export function proxyEnvVars(settings: GhProxySettings): NodeJS.ProcessEnv {
 }
 
 /**
- * 挂着代理 dispatcher 的 fetch，供 octokit 的 `request.fetch` 使用。
- *
- * octokit v5 丢弃了 node-fetch 时代的 `agent` 选项（@octokit/request 的选项里没有
- * 这个字段，也没有任何地方把它转交给 fetch），只接受自定义 fetch —— octokit
- * README 的 Proxy Servers 一节就是挂 undici 的代理 dispatcher。NO_PROXY 匹配由
- * EnvHttpProxyAgent 负责；未配置代理时原样返回全局 fetch，默认路径行为不变。
+ * 代理 dispatcher：NO_PROXY 匹配、CONNECT 隧道都交给 undici 的
+ * EnvHttpProxyAgent，octokit 侧只认自定义 fetch（v5 丢掉了 node-fetch 时代的
+ * `agent` 选项，@octokit/request 的选项里没有这个字段，也没有任何地方把它转交给
+ * fetch），所以代理只能从 fetch 挂进去。
  */
-function createFetch(settings: GhProxySettings): typeof globalThis.fetch {
-  const { proxy, noProxy } = settings;
-  if (!proxy) return globalThis.fetch;
+function createProxyDispatcher(
+  proxy: string,
+  noProxy: string | undefined,
+): NonNullable<RequestInit["dispatcher"]> {
   // undici 包与 Node 全局 fetch 各带一份 Dispatcher 类型声明（@types/node 走
   // undici-types），结构一致但 compose 重载对不上，这里只做类型层面的转换。
-  const dispatcher = new EnvHttpProxyAgent({
+  return new EnvHttpProxyAgent({
     httpProxy: proxy,
     httpsProxy: proxy,
     ...(noProxy && { noProxy }),
   }) as unknown as NonNullable<RequestInit["dispatcher"]>;
-  return (input, init) => globalThis.fetch(input, { ...init, dispatcher });
 }
 
 export interface GhProxy {
-  /** 读取配置（首个调用触发读盘，之后返回同一个缓存结果，失败不抛出）。 */
-  load(): Promise<GhProxyLoad>;
+  /** 生效的代理设置（配置文件与环境变量合并后的结果）。 */
+  readonly settings: GhProxySettings;
   /** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象。 */
-  env(): Promise<NodeJS.ProcessEnv>;
+  readonly env: NodeJS.ProcessEnv;
   /** 走代理的 fetch；未配置代理时就是全局 fetch。 */
   readonly fetch: typeof globalThis.fetch;
 }
 
 /**
- * 创建代理配置读取器。配置只在首次使用时读一次并缓存；`load` 与 `fetch` 共用这次
- * 读取，因此运行期不会出现两者看到不同配置的情况。
+ * 读一次配置并组装代理层。缓存的是 dispatcher（连接池复用），**不是**
+ * `globalThis.fetch` 本身：每次调用都取当前的全局 fetch，否则首个请求之后替换
+ * `globalThis.fetch`（插桩、测试替身）就不再生效。
  */
 export function createGhProxy(
   configPath: string = ghProxyConfigPath(),
   env: NodeJS.ProcessEnv = process.env,
 ): GhProxy {
-  let loading: Promise<GhProxyLoad> | undefined;
-  let proxied: typeof globalThis.fetch | undefined;
-
-  function load(): Promise<GhProxyLoad> {
-    loading ??= resolveSettings(configPath, env);
-    return loading;
-  }
+  const settings = readGhProxySettings(configPath, env);
+  const { proxy, noProxy } = settings;
+  let dispatcher: NonNullable<RequestInit["dispatcher"]> | undefined;
 
-  return {
-    load,
-    env: async () => {
-      const { settings } = await load();
-      return proxyEnvVars(settings);
-    },
-    fetch: async (input, init) => {
-      const { settings } = await load();
-      proxied ??= createFetch(settings);
-      return proxied(input, init);
-    },
+  const fetch: typeof globalThis.fetch = (input, init) => {
+    if (!proxy) return globalThis.fetch(input, init);
+    dispatcher ??= createProxyDispatcher(proxy, noProxy);
+    return globalThis.fetch(input, { ...init, dispatcher });
   };
+
+  return { settings, env: proxyEnvVars(settings), fetch };
 }