@trim21/personal-pi-extensions 0.1.551 → 0.1.553

package/package.json

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

package/src/bwrap/runtime.ts

@@ -17,7 +17,7 @@ import { type TObject, Type } from "typebox";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { fenceCodeBlock } from "../lib/markdown.js";
-import { formatDisplayPath } from "../lib/path.js";
+import { formatDisplayPath, resolveHomePath } from "../lib/path.js";
 import { type SelectAction, selectMultiple, selectWithOptionalInput } from "../lib/ui.js";
 import { type ApprovalRule, evaluateBashApproval, matchRule } from "./approval-rules.js";
 import { commandPatternsFor } from "./approval-suggest.js";
@@ -91,6 +91,8 @@ export interface BwrapExecutionRequest {
  */
 export interface BwrapExecutionResult {
   exitCode: number | null;
+  /** 只描述写边界（工作区外能否写）与网络层级（关 / 白名单 / 放开），不含具体域名；未沙箱执行时为 undefined。 */
+  sandboxHint: string | undefined;
   /** 截断后的输出（尾部），未截断时为完整输出；空输出为空字符串。 */
   output: string;
   /** 完整输出的文件路径；无输出时不存在。 */
@@ -112,16 +114,19 @@ export interface BashExecutionPartial {
 export class BashInterruptedError extends Error {
   readonly kind: "timeout" | "aborted";
   readonly partial: BashExecutionPartial;
+  readonly sandboxHint: string | undefined;
 
   constructor(
     kind: "timeout" | "aborted",
     message: string,
     partial: BashExecutionPartial,
+    sandboxHint: string | undefined,
     cause: unknown,
   ) {
     super(message, { cause });
     this.kind = kind;
     this.partial = partial;
+    this.sandboxHint = sandboxHint;
     // 对齐标准错误分类：中断=AbortError（用户取消），超时=TimeoutError
     this.name = kind === "aborted" ? "AbortError" : "TimeoutError";
   }
@@ -255,6 +260,67 @@ function notifyMode(
   ctx.ui.notify(labels[mode], "info");
 }
 
+/** 沙箱内允许写入的根目录（与沙箱层同基准：相对 workspace 解析 "."、`~` 与相对路径）。 */
+function writableRoots(resolved: ResolvedBwrap, workspace: string): string[] {
+  const writable = [...resolved.writablePaths, ...resolved.extraWritablePaths].map((path) =>
+    resolveHomePath(path, workspace),
+  );
+  return [...new Set(writable)];
+}
+
+/** 网络层级：关 / 只放行白名单 / 完全放开（白名单域名本身不列出，对判断失败无用）。 */
+function describeNetwork(resolved: ResolvedBwrap): string {
+  if (!resolved.network) return "network access is off";
+  if (resolved.networkAllowlist.length > 0)
+    return "network access is limited to allowlisted addresses";
+  return "network access is unrestricted";
+}
+
+export interface SandboxHintInput {
+  /** writablePaths 中 "." 的解析基准，也是可写根目录的显示基准。 */
+  workspace: string;
+  /** 本次命令是否绕过沙箱（Windows、审批通过的全权限、allow-all）。 */
+  unsandboxed: boolean;
+}
+
+/** 命令没经沙箱时沿用 prompt 里的说法，给出在沙盒外重跑的手段。 */
+const SANDBOX_ESCAPE_HATCH =
+  "[Sandbox] If the command needs more than that, use the `dangerouslyDisableSandbox` parameter to request unsandboxed execution; the user must approve this request.";
+
+/**
+ * 命令失败时附在错误文本后的沙箱状态：写边界（可写根目录、.git 只读）+ 网络层级，
+ * 以及在沙盒外重跑的手段。只报层级不列白名单域名。
+ * 命令没经沙箱（allow-all、审批通过的全权限、Windows）时返回 undefined：
+ * 没有沙箱就没什么可提示的。
+ */
+export function describeSandbox(
+  resolved: ResolvedBwrap,
+  input: SandboxHintInput,
+): string | undefined {
+  if (input.unsandboxed) return undefined;
+  const roots = writableRoots(resolved, input.workspace);
+  const clauses = [
+    roots.length === 0
+      ? "the filesystem is read-only"
+      : `writes are limited to ${roots.map((path) => formatDisplayPath(input.workspace, path)).join(", ")}`,
+    // .git 只读保护只在工作区本身可写时才有区分度（readonly 下整个文件系统都不可写）
+    ...(roots.includes(input.workspace) ? [".git is read-only"] : []),
+    describeNetwork(resolved),
+  ];
+  return [
+    `[Sandbox] This command ran in a sandbox: ${clauses.join("; ")}.`,
+    SANDBOX_ESCAPE_HATCH,
+  ].join("\n");
+}
+
+/**
+ * 把沙箱状态拼到失败文本后（未沙箱执行时保持原文）。失败文本常以换行结尾，
+ * 先 trimEnd 保证状态与命令输出之间只有一个空行。
+ */
+export function appendSandboxHint(text: string, hint: string | undefined): string {
+  return hint === undefined ? text : `${text.trimEnd()}\n\n${hint}`;
+}
+
 export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private sandboxDisabled = false;
@@ -383,6 +449,8 @@ export class BwrapRuntime {
       runtime.mihomoPath ??= this.mihomoPath ?? findMihomo();
       this.mihomoPath = runtime.mihomoPath;
     }
+    // 命令失败时附带的沙箱状态（写边界 + 网络层级），由上层拼进错误文本
+    const sandboxHint = describeSandbox(runtime, { workspace, unsandboxed: local });
     await using output = new BashOutput(request.ctx.sessionManager.getSessionId());
     const { onUpdate } = request;
 
@@ -415,6 +483,7 @@ export class BwrapRuntime {
       const partial = await this.finalizeOutput(output);
       return {
         exitCode,
+        sandboxHint,
         output: partial.output,
         ...(partial.fullOutputPath && { fullOutputPath: partial.fullOutputPath }),
         truncation: partial.truncation,
@@ -433,6 +502,7 @@ export class BwrapRuntime {
           "timeout",
           `Command timed out after ${error.message.slice("timeout:".length)} seconds`,
           partial,
+          sandboxHint,
           error,
         );
       }
@@ -440,7 +510,13 @@ export class BwrapRuntime {
       // 兼容 pi local ops 抛的 new Error("aborted")
       if (error instanceof Error && (error.name === "AbortError" || error.message === "aborted")) {
         const partial = await this.finalizeOutput(output);
-        throw new BashInterruptedError("aborted", "Command aborted by user", partial, error);
+        throw new BashInterruptedError(
+          "aborted",
+          "Command aborted by user",
+          partial,
+          sandboxHint,
+          error,
+        );
       }
       throw error;
     } finally {

package/src/claude-code/shell.ts

@@ -10,7 +10,12 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { BashInterruptedError, type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import {
+  appendSandboxHint,
+  BashInterruptedError,
+  type BwrapRuntime,
+  createBwrapRuntime,
+} from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -151,10 +156,10 @@ export function registerShellTools(
             const full = text ? `${text}\n\nCommand aborted by user` : "Command aborted by user";
             return { content: [{ type: "text", text: full }], details: undefined };
           }
-          const full = text
+          const status = text
             ? `${text}\n\nCommand timed out after ${timeout} milliseconds`
             : `Command timed out after ${timeout} milliseconds`;
-          throw new Error(full, { cause: error });
+          throw new Error(appendSandboxHint(status, error.sandboxHint), { cause: error });
         }
         throw error;
       }
@@ -165,9 +170,11 @@ export function registerShellTools(
         const full = result.fullOutputPath
           ? await readFile(result.fullOutputPath, "utf8")
           : result.output;
-        throw new Error(formatBashError(result.exitCode, full), {
-          cause: result,
-        });
+        // 失败时附带沙箱状态：命令可能是被沙箱的写边界或网络限制挡住的
+        throw new Error(
+          appendSandboxHint(formatBashError(result.exitCode, full), result.sandboxHint),
+          { cause: result },
+        );
       }
       return formatBashSuccess(result);
     },

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 }),
   };
 }
 
@@ -151,46 +155,32 @@ function createProxyDispatcher(
 }
 
 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`（插桩、测试替身）
- * 就不再生效。
+ * 读一次配置并组装代理层。缓存的是 dispatcher（连接池复用），**不是**
+ * `globalThis.fetch` 本身：每次调用都取当前的全局 fetch，否则首个请求之后替换
+ * `globalThis.fetch`（插桩、测试替身）就不再生效。
  */
 export function createGhProxy(
   configPath: string = ghProxyConfigPath(),
   env: NodeJS.ProcessEnv = process.env,
 ): GhProxy {
-  let loading: Promise<GhProxyLoad> | undefined;
+  const settings = readGhProxySettings(configPath, env);
+  const { proxy, noProxy } = settings;
   let dispatcher: NonNullable<RequestInit["dispatcher"]> | undefined;
 
-  function load(): Promise<GhProxyLoad> {
-    loading ??= resolveSettings(configPath, env);
-    return loading;
-  }
-
-  return {
-    load,
-    env: async () => {
-      const { settings } = await load();
-      return proxyEnvVars(settings);
-    },
-    fetch: async (input, init) => {
-      const { settings } = await load();
-      const { proxy, noProxy } = settings;
-      if (!proxy) return globalThis.fetch(input, init);
-      dispatcher ??= createProxyDispatcher(proxy, noProxy);
-      return globalThis.fetch(input, { ...init, dispatcher });
-    },
+  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 };
 }

package/src/opencode/bash.ts

@@ -4,7 +4,12 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { BashInterruptedError, type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import {
+  appendSandboxHint,
+  BashInterruptedError,
+  type BwrapRuntime,
+  createBwrapRuntime,
+} from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -106,9 +111,13 @@ export default function opencodeBash(
             error.partial.truncation,
             error.partial.fullOutputPath,
           );
+          // 超时附带沙箱状态（可能是网络限制让命令挂住）；中断是用户主动取消，与沙箱无关
           const status =
             error.kind === "timeout"
-              ? `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`
+              ? appendSandboxHint(
+                  `Command exceeded timeout of ${timeout} ms. Retry with a larger timeout if the command is expected to take longer.`,
+                  error.sandboxHint,
+                )
               : "Command aborted by user";
           const full = text ? `${text}\n\n${status}` : status;
           // 对齐上游 opencode：超时与中断都不抛错，输出与状态文本一起返回
@@ -123,10 +132,16 @@ export default function opencodeBash(
       // 命令失败（非 0 退出码）不抛错：输出与状态文本一起返回
       let text = result.output || "(no output)";
       text = appendTruncationNotice(text, result.truncation, result.fullOutputPath);
+      const failed = result.exitCode !== 0 && result.exitCode !== null;
+      // 失败时附带沙箱状态：命令可能是被沙箱的写边界或网络限制挡住的
+      const status = appendSandboxHint(
+        `Command exited with code ${result.exitCode}.`,
+        failed ? result.sandboxHint : undefined,
+      );
       return {
         content: [
           { type: "text" as const, text },
-          { type: "text" as const, text: `Command exited with code ${result.exitCode}.` },
+          { type: "text" as const, text: status },
         ],
         details: {
           exitCode: result.exitCode,