@trim21/personal-pi-extensions 0.1.628 → 0.1.631

package/package.json

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

package/src/bwrap/approval-rules.ts

@@ -3,9 +3,11 @@
  * 用 tree-sitter 解析命令（含嵌套 `$(...)`），对每条命令的原文做通配
  * 匹配，对 allow/deny 规则求值。规则匹配不经过任何命令归一——BashArity
  * 归一模式只用于 "allow forever" 的建议规则（见 approval-suggest.ts）。
- * 接入 bwrap 的 `dangerouslyDisableSandbox` 审批：命中规则自动
- * 放行/拒绝，未命中才弹审批对话框。文件输出重定向（`>` / `>>` / `&>`
- * 等）不会因命令规则自动放行，避免 `echo *` 把 `echo '' > file` 带过。
+ * 接入 bwrap 的 `dangerouslyDisableSandbox` 审批：审批规则集
+ * （createApprovalRuleSet）独占「自动放行 / 自动拒绝 / 交人审」的判定、
+ * allow 覆盖查询、待允许模式与规则追加，调用方只描述用户动作。
+ * 文件输出重定向（`>` / `>>` / `&>` 等）不会因命令规则自动放行，
+ * 避免 `echo *` 把 `echo '' > file` 带过。
  *
  * 参考实现：
  * - opencode packages/core/src/util/wildcard.ts（通配匹配）
@@ -209,27 +211,17 @@ export function matchRule(input: string, pattern: string): boolean {
   return new RegExp(`^${escaped}$`, "s").test(input);
 }
 
-// ── 规则求值 ────────────────────────────────────────────────────────────────
+// ── 命令树展平 ──────────────────────────────────────────────────────────────
 
 /**
- * 对命令（含所有嵌套命令）求值：
- * - deny 优先：任一命令命中 deny 规则即整体拒绝
- * - 文件输出重定向不自动放行：即使命令规则全匹配，也返回 undefined 交人审
- * - allow 需全量：所有命令都命中 allow 规则才整体放行，否则返回
- *   undefined（有命令未命中规则，交给人审），避免未允许的命令被同链放行带过。
- * - 匹配输入是命令原文（tree-sitter command 节点 text，含嵌套逐条展开），
- *   对齐 opencode shell.ts 的 patterns；通配规则按字面写，`--` 与普通
- *   token 无区别。
- * 规则内后写优先（findLast，对齐 opencode PermissionV2）。
+ * 展平命令树：每条命令本身 + 其所有嵌套命令（`$(...)` 内的），父在子前。
+ * 求值与建议模式生成（approval-suggest.ts）共用——后者依赖本模块，
+ * 反向 import 会成环，所以展平放在这里。
  */
-export async function evaluateBashApproval(
-  command: string,
-  rules: readonly ApprovalRule[],
-): Promise<ApprovalAction | undefined> {
-  const parsed = await parseBashCommands(command);
-  const raws: string[] = [];
+export function flattenCommands(parsed: ParsedBash): BashCommand[] {
+  const flat: BashCommand[] = [];
   const visit = (cmd: BashCommand) => {
-    raws.push(cmd.raw);
+    flat.push(cmd);
     for (const nested of cmd.nested) {
       visit(nested);
     }
@@ -237,21 +229,101 @@ export async function evaluateBashApproval(
   for (const cmd of parsed.commands) {
     visit(cmd);
   }
-  if (raws.length === 0) {
-    return;
+  return flat;
+}
+
+// ── 审批规则集 ──────────────────────────────────────────────────────────────
+
+export interface ApprovalRuleSetOptions {
+  /** 当前规则（读取时取最新，追加后无需重建规则集）。规则数组即优先级：靠后优先。 */
+  rules: () => readonly ApprovalRule[];
+  /** 命令 → 候选模式（BashArity）；注入以免与 approval-suggest.ts 成环。 */
+  suggestPatterns: (command: string) => Promise<readonly string[]>;
+  /** 追加 allow 规则并持久化；resolve 后 rules() 必须能看到它们，抛错即视为未追加。 */
+  persist: (rules: readonly ApprovalRule[]) => Promise<void>;
+}
+
+export interface ApprovalRuleSet {
+  /**
+   * 对命令（含所有嵌套命令）求值：deny 优先 / allow 需全量 / 含文件输出
+   * 重定向不自动放行。返回 undefined 表示未命中规则，交人工审批。
+   */
+  evaluate(command: string): Promise<ApprovalAction | undefined>;
+  /**
+   * 该字符串（命令原文或候选模式）是否被最后一条匹配的规则允许。
+   * 只回答 allow 覆盖，不考虑 deny 与重定向——放行判定一律用 evaluate。
+   */
+  isAllowed(pattern: string): boolean;
+  /** 命令的候选模式（去重）中尚未被 allow 规则覆盖的那些；审批子菜单的唯一来源。 */
+  pendingPatterns(command: string): Promise<string[]>;
+  /** 追加 allow 规则并持久化；persist 成功后立即生效。 */
+  addAllowRules(patterns: readonly string[]): Promise<void>;
+}
+
+/**
+ * 审批规则集：命令自动判定、allow 覆盖查询、待允许模式与规则追加的唯一 owner。
+ * 规则数组的顺序即优先级：靠后优先（项目规则经 deepMerge 排在全局规则之后）。
+ * 三条协作方由调用方注入：规则 getter（reload 或追加后无需重建规则集）、
+ * 候选模式生成、持久化副作用（文件读写留在调用方）。
+ */
+export function createApprovalRuleSet(options: ApprovalRuleSetOptions): ApprovalRuleSet {
+  const { rules, suggestPatterns, persist } = options;
+
+  /** 最后一条匹配 input 的规则；数组靠后者优先（对齐 opencode PermissionV2）。 */
+  function lastMatch(input: string): ApprovalRule | undefined {
+    return rules().findLast((rule) => matchRule(input, rule.pattern));
+  }
+
+  function isAllowed(pattern: string): boolean {
+    return lastMatch(pattern)?.action === "allow";
   }
-  let allowed = 0;
-  for (const raw of raws) {
-    const rule = rules.findLast((r) => matchRule(raw, r.pattern));
-    if (rule?.action === "deny") {
-      return "deny";
+
+  async function evaluate(command: string): Promise<ApprovalAction | undefined> {
+    const parsed = await parseBashCommands(command);
+    // 匹配输入是命令原文（tree-sitter command 节点 text，含嵌套逐条展开），
+    // 对齐 opencode shell.ts 的 patterns；通配规则按字面写，`--` 与普通 token 无区别。
+    const raws = flattenCommands(parsed).map((cmd) => cmd.raw);
+    if (raws.length === 0) {
+      return; // 空命令或解析失败：没有可匹配的命令，交人审
+    }
+    let allowed = 0;
+    for (const raw of raws) {
+      const rule = lastMatch(raw);
+      if (rule?.action === "deny") {
+        return "deny";
+      }
+      if (rule?.action === "allow") {
+        allowed++;
+      }
+    }
+    // 文件输出重定向不自动放行：即使命令规则全匹配也交人审
+    if (parsed.hasFileOutputRedirect) {
+      return;
     }
-    if (rule?.action === "allow") {
-      allowed++;
+    // allow 需全量：有命令未命中规则时交人审，避免未允许的命令被同链放行带过
+    return allowed === raws.length ? "allow" : undefined;
+  }
+
+  async function pendingPatterns(command: string): Promise<string[]> {
+    const pending: string[] = [];
+    const seen = new Set<string>();
+    for (const pattern of await suggestPatterns(command)) {
+      if (seen.has(pattern) || isAllowed(pattern)) {
+        continue;
+      }
+      seen.add(pattern);
+      pending.push(pattern);
     }
+    return pending;
   }
-  if (parsed.hasFileOutputRedirect) {
-    return;
+
+  async function addAllowRules(patterns: readonly string[]): Promise<void> {
+    const additions: ApprovalRule[] = patterns.map((pattern) => ({ action: "allow", pattern }));
+    if (additions.length === 0) {
+      return; // 解析失败或未勾选：本次处理，不写配置
+    }
+    await persist(additions);
   }
-  return allowed === raws.length ? "allow" : undefined;
+
+  return { evaluate, isAllowed, pendingPatterns, addAllowRules };
 }

package/src/bwrap/approval-suggest.ts

@@ -8,7 +8,7 @@
  */
 import { readFileSync } from "node:fs";
 
-import { type BashCommand, parseBashCommands } from "./approval-rules.js";
+import { type BashCommand, flattenCommands, parseBashCommands } from "./approval-rules.js";
 
 /**
  * 命令前缀 → 定义该命令的 token 数。`git checkout main` → `git` 的 arity 2，
@@ -41,21 +41,7 @@ export function commandPattern(command: BashCommand): string {
 }
 
 /** 命令（含所有嵌套命令）的 BashArity 建议模式列表（命令替换里的命令也展开）。 */
-function patternsFromCommands(commands: BashCommand[]): string[] {
-  const flat: string[] = [];
-  const visit = (cmd: BashCommand) => {
-    flat.push(commandPattern(cmd));
-    for (const nested of cmd.nested) {
-      visit(nested);
-    }
-  };
-  for (const cmd of commands) {
-    visit(cmd);
-  }
-  return flat;
-}
-
 export async function commandPatternsFor(command: string): Promise<string[]> {
   const parsed = await parseBashCommands(command);
-  return patternsFromCommands(parsed.commands);
+  return flattenCommands(parsed).map((cmd) => commandPattern(cmd));
 }

package/src/bwrap/runtime.ts

@@ -14,17 +14,24 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { throttle } from "lodash-es";
 import { type TObject, Type } from "typebox";
+import { Value } from "typebox/value";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { fenceCodeBlock } from "../lib/markdown.js";
 import { isUnknownArray } from "../lib/narrow.js";
+import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { formatDisplayPath } from "../lib/path.js";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
 import { type SelectAction, selectMultiple, selectWithOptionalInput } from "../lib/ui.js";
-import { type ApprovalRule, evaluateBashApproval, matchRule } from "./approval-rules.js";
+import {
+  type ApprovalRule,
+  type ApprovalRuleSet,
+  createApprovalRuleSet,
+} from "./approval-rules.js";
 import { commandPatternsFor } from "./approval-suggest.js";
 import {
   type BwrapConfig,
+  bwrapConfigFileSchema,
   findBwrap,
   findMihomo,
   type FsMode,
@@ -381,6 +388,20 @@ export function sandboxHintBlock(hint: string | undefined): { type: "text"; text
   return hint === undefined ? [] : [{ type: "text", text: hint }];
 }
 
+/**
+ * 项目配置文件形状非法时的错误：消息带文件路径与字段位置，cause 保留校验错误
+ * （Value.Check 只回答是否合法，详情用同一 schema 解析一次取到）。
+ */
+function invalidConfigError(path: string, raw: unknown): Error {
+  try {
+    parseWithSchema(bwrapConfigFileSchema, raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new Error(`Invalid bwrap configuration at ${path}: ${detail}`, { cause: error });
+  }
+  return new Error(`Invalid bwrap configuration at ${path}: schema validation failed`);
+}
+
 export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private bwrapUnavailable = false;
@@ -539,8 +560,14 @@ export class BwrapRuntime {
       ) {
         throw new Error(UNSANDBOXED_DENIED);
       }
-      // 先按 approvalRules 自动判定：allow 直接放行，deny 直接拒绝，未命中才弹框
-      const decision = await evaluateBashApproval(request.command, runtime.approvalRules);
+      // 先按 approvalRules 自动判定：allow 直接放行，deny 直接拒绝，未命中才弹框。
+      // 规则集跟随 this.resolved，reload 或追加规则后无需重建
+      const ruleSet = createApprovalRuleSet({
+        rules: () => this.resolve(request.ctx).approvalRules,
+        suggestPatterns: commandPatternsFor,
+        persist: (rules) => this.persistAllowRules(request.ctx, rules),
+      });
+      const decision = await ruleSet.evaluate(request.command);
       if (decision === "deny") {
         throw new Error(`Command denied by bwrap approval rule: ${request.command}`);
       }
@@ -551,6 +578,7 @@ export class BwrapRuntime {
             request.command,
             request.description,
             execCwd,
+            ruleSet,
           )) === "sandbox";
       }
     }
@@ -686,12 +714,13 @@ export class BwrapRuntime {
     command: string,
     reason: string | undefined,
     execCwd: string,
+    ruleSet: ApprovalRuleSet,
   ): Promise<FullAccessGrant> {
     // hasUI 判定推迟到审批时刻：无 UI 会话弹不了审批框，按用户点 Deny 的标准文案拒绝
     if (!ctx.hasUI) {
       throw new Error(UNSANDBOXED_DENIED);
     }
-    const decision = await this.approveFullAccessUI(ctx, command, reason, execCwd);
+    const decision = await this.approveFullAccessUI(ctx, command, reason, execCwd, ruleSet);
     // 关闭对话框 = 中断并拒绝，不循环重问
     if (decision === undefined) {
       ctx.abort();
@@ -706,13 +735,13 @@ export class BwrapRuntime {
       }
       case DENY: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         throw new Error(UNSANDBOXED_DENIED);
       }
       case DENY_WITH_REASON: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         const feedback = decision.reason?.trim() ?? "";
         throw new Error(
@@ -723,7 +752,7 @@ export class BwrapRuntime {
       }
       case ALLOW_ONCE: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         return "full-access";
       }
@@ -744,22 +773,14 @@ export class BwrapRuntime {
     command: string,
     reason: string | undefined,
     execCwd: string,
+    ruleSet: ApprovalRuleSet,
   ): Promise<FullAccessUIDecision | undefined> {
     // 弹框前解析命令的持久化规则：`echo 1 | head` → `echo *`、`head *`。
     // 持久化规则的勾选折叠进 EDIT_RULES 子菜单，主决策列表只保留放行/拒绝，
     // 避免一屏 checkbox 淹没决策项。
-    const patterns = await commandPatternsFor(command);
     // 子菜单只列出未命中 allow 规则的 pattern：已提前允许的部分自动放行，
     // 无需再展示或重复勾选持久化（deny 命中的命令在 evaluate 阶段已被拒绝）。
-    const rules = this.resolve(ctx).approvalRules;
-    const unallowedPatterns = [
-      ...new Set(
-        patterns.filter((pattern) => {
-          const rule = rules.findLast((r) => matchRule(pattern, r.pattern));
-          return rule?.action !== "allow";
-        }),
-      ),
-    ];
+    const unallowedPatterns = await ruleSet.pendingPatterns(command);
     // dcg 扫描建议是可选的参考文本：未安装时静默跳过；已安装但扫描失败
     // 时 notify 提示，弹窗本身与无 dcg 时一致
     const outcome = await dcgSuggestion(command);
@@ -837,23 +858,27 @@ export class BwrapRuntime {
     }
   }
 
-  /** 把命令的权限模式写入项目 sandbox.json 的 approvalRules（allow forever）。 */
-  private async persistAllowRule(
+  /**
+   * 规则集的持久化实现：把勾选的 allow 规则追加进项目 sandbox.json 的
+   * approvalRules，并刷新缓存的规则使其立即生效。
+   */
+  private async persistAllowRules(
     ctx: ExtensionContext,
-    command: string,
-    patterns?: string[],
+    newRules: readonly ApprovalRule[],
   ): Promise<void> {
-    const rulePatterns = patterns ?? (await commandPatternsFor(command));
-    if (rulePatterns.length === 0) {
-      return; // 解析失败：本次处理，不写规则
-    }
-    const newRules: ApprovalRule[] = rulePatterns.map((pattern) => ({ action: "allow", pattern }));
     const { project } = getBwrapConfigPaths(ctx.cwd);
     let config: Record<string, unknown> = {};
     if (existsSync(project)) {
-      config = JSON.parse(readFileSync(project, "utf8")) as Record<string, unknown>;
+      const raw: unknown = JSON.parse(readFileSync(project, "utf8"));
+      // 会话开始时已校验过配置文件：这里再查一次形状（Value.Check 同时收窄类型），
+      // 避免把新规则追加进一个后续加载必然失败的文件（只在配置文件被中途改坏时可达）
+      if (!Value.Check(bwrapConfigFileSchema, raw)) {
+        throw invalidConfigError(project, raw);
+      }
+      config = raw;
     }
-    // 既有规则按不透明值原样保留（形状不认识也不丢），只追加本次允许的规则。
+    // 既有规则按不透明值原样保留（形状不认识也不丢），只追加本次允许的规则；
+    // 与规则无关的字段（含不认识的）同样原样写回，不经过 schema 往返
     const existing = isUnknownArray(config.approvalRules) ? config.approvalRules : [];
     config.approvalRules = [...existing, ...newRules];
     await mkdir(dirname(project), { recursive: true });

package/src/lib/lsp/client.ts

@@ -1123,6 +1123,56 @@ export async function create(input: CreateInput): Promise<LspClient> {
     });
   }
 
+  /** 轮询的归宿：谁先让等待收敛，以及没有收敛时是哪一种耗尽。 */
+  type PollOutcome = "pulled" | "pushed" | "pullTimedOut" | "budgetExhausted";
+
+  /**
+   * 等「当前文档版本」的诊断就绪，两种等待模式的唯一一份轮询实现。
+   * pull 与 push 语义相同（都是等当前文档版本的诊断结果）：先 pull，拿到就绪结论
+   * 即返回；pull 超时说明服务器未响应，不再重试 pull，把「是否退回等 push」交给
+   * 调用方；否则进入三路竞速——版本匹配的 push / 服务器注册表变化 / pull 重试间隔，
+   * 除 push 命中外都再来一轮，直到预算耗尽、连接关闭或等待被中断。
+   */
+  async function pollUntilSettled(request: {
+    path: string;
+    /** 本次等待的预算（毫秒）。 */
+    budgetMs: number;
+    /** 预算起点（调用方传 request.after ?? Date.now()）。 */
+    startedAt: number;
+    /** 版本匹配的 push 兜底，由调用方按自己的预算创建。 */
+    pushWait: Promise<boolean>;
+    /** pull 入口（两种模式各自的那一个）。 */
+    pull: (path: string) => Promise<PullResult>;
+    /** 该模式的就绪判据。 */
+    isSettled: (result: PullResult) => boolean;
+    signal?: AbortSignal;
+  }): Promise<PollOutcome> {
+    while (!connectionClosed && !request.signal?.aborted) {
+      const remaining = request.budgetMs - (Date.now() - request.startedAt);
+      if (remaining <= 0) {
+        return "budgetExhausted";
+      }
+      const result = await request.pull(request.path);
+      if (request.isSettled(result)) {
+        return "pulled";
+      }
+      if (result.timedOut) {
+        return "pullTimedOut";
+      }
+      const next = await Promise.race([
+        request.pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
+        waitForRegistrationChange(remaining).then((changed) =>
+          changed ? ("registration" as const) : ("timeout" as const),
+        ),
+        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
+      ]);
+      if (next === "push") {
+        return "pushed";
+      }
+    }
+    return "budgetExhausted";
+  }
+
   /**
    * 等待「当前文档版本」的诊断结论。返回值表示就绪是否被证实：true = 拿到了
    * 当前版本的诊断结果（push / pull / 已有结论）；false = 等满预算或连接关闭
@@ -1150,9 +1200,6 @@ export async function create(input: CreateInput): Promise<LspClient> {
       files[request.path]?.lastPushEmpty === true
         ? Math.min(diagnosticsDocumentWaitTimeoutMs, diagnosticsSilentWaitTimeoutMs)
         : diagnosticsDocumentWaitTimeoutMs;
-    // pull 与 push 语义相同：都是等「当前文档版本」的诊断结果，统一一个循环。
-    // 先 pull（拿到即返回）；pull 超时说明服务器未响应，不再重试 pull，只等
-    // 版本匹配的 push 兜底；版本不匹配的 push 一律忽略（防迟到旧结果）。
     const pushWait = waitForFreshPush({
       path: request.path,
       version: request.version,
@@ -1160,30 +1207,24 @@ export async function create(input: CreateInput): Promise<LspClient> {
       timeout: budget,
     });
 
-    while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = budget - (Date.now() - startedAt);
-      if (remaining <= 0) {
-        return false;
-      }
-      const result = await requestDocumentDiagnostics(request.path);
-      if (result.matched) {
-        return true;
-      }
-      if (result.timedOut) {
-        return await pushWait;
-      }
-      const next = await Promise.race([
-        pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
-        waitForRegistrationChange(remaining).then((changed) =>
-          changed ? ("registration" as const) : ("timeout" as const),
-        ),
-        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
-      ]);
-      if (next === "push") {
-        return true;
-      }
-    }
-    return false;
+    const outcome = await pollUntilSettled({
+      path: request.path,
+      budgetMs: budget,
+      startedAt,
+      pushWait,
+      pull: requestDocumentDiagnostics,
+      isSettled: (result) => result.matched,
+      signal: request.signal,
+    });
+    // 对应重构前的返回路径：pulled / pushed → `return true`（pull 命中或等到
+    // 版本匹配的 push）；pullTimedOut → `return await pushWait`（pull 挂起不重试，
+    // 但继续等 push 到预算结束，返回是否等到）；budgetExhausted（含连接关闭 /
+    // 中断）→ 循环尾 `return false`。
+    return (
+      outcome === "pulled" ||
+      outcome === "pushed" ||
+      (outcome === "pullTimedOut" && (await pushWait))
+    );
   }
 
   async function waitForFullDiagnostics(request: {
@@ -1200,29 +1241,20 @@ export async function create(input: CreateInput): Promise<LspClient> {
       timeout: diagnosticsFullWaitTimeoutMs,
     });
 
-    while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = diagnosticsFullWaitTimeoutMs - (Date.now() - startedAt);
-      if (remaining <= 0) {
-        return;
-      }
-      const result = await requestFullDiagnostics(request.path);
-      if (result.handled || result.matched) {
-        return;
-      }
-      if (result.timedOut) {
-        await pushWait;
-        return;
-      }
-      const next = await Promise.race([
-        pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
-        waitForRegistrationChange(remaining).then((changed) =>
-          changed ? ("registration" as const) : ("timeout" as const),
-        ),
-        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
-      ]);
-      if (next === "push") {
-        return;
-      }
+    const outcome = await pollUntilSettled({
+      path: request.path,
+      budgetMs: diagnosticsFullWaitTimeoutMs,
+      startedAt,
+      pushWait,
+      pull: requestFullDiagnostics,
+      isSettled: (result) => result.handled || result.matched,
+      signal: request.signal,
+    });
+    // 对应重构前的返回路径：pulled / pushed / budgetExhausted 都对应 `return`
+    // （就绪、等到 push 或耗尽预算）；pullTimedOut → `await pushWait; return`，
+    // 即 pull 挂起后仍等 push 兜底到预算结束，结果丢弃（本函数返回 void）。
+    if (outcome === "pullTimedOut") {
+      await pushWait;
     }
   }
 

package/src/spawn-agent.ts

@@ -24,7 +24,10 @@
  * so one log entry is always exactly one rendered line. The final line is
  * always the subagent name as a code span (`` `scout` ``), followed by the
  * live usage stats when there are any; it rides outside the rolling window so
- * it is never trimmed. While the model is thinking, a transient
+ * it is never trimmed. The model name on that line is the model the session
+ * actually uses, which differs from the frontmatter string when the declared
+ * model resolved to nothing and the SDK fell back to a default. While the
+ * model is thinking, a transient
  * `thinking ( N chars )` line sits between the log and the footer showing the
  * live character count of the streamed thinking; it disappears when the
  * thinking block ends.
@@ -177,6 +180,7 @@ interface SubagentResult {
   messages: AgentMessage[];
   stderr: string;
   usage: UsageStats;
+  /** 实际生效的模型 id（fallback 之后），不是 frontmatter 里写的名字。 */
   model?: string;
   stopReason?: string;
   errorMessage?: string;
@@ -378,6 +382,11 @@ function toolSegment(name: string, count: number): string {
 /** The subset of AgentSession runAgent relies on (injectable for tests). */
 export interface SubagentSession {
   agent: { state: { messages: AgentMessage[] } };
+  /**
+   * Model the session actually runs (after any SDK fallback), shown in the
+   * progress footer. Optional: injected test sessions need not expose it.
+   */
+  model?: { id: string };
   subscribe(listener: AgentSessionEventListener): () => void;
   prompt(text: string, options?: PromptOptions): Promise<void>;
   abort(): Promise<void>;
@@ -453,7 +462,6 @@ export async function runAgent(
       contextTokens: 0,
       turns: 0,
     },
-    model: agent.model,
   };
 
   let session: SubagentSession;
@@ -466,6 +474,10 @@ export async function runAgent(
     return result;
   }
 
+  // 面板显示实际生效的模型：frontmatter 里的模型名解析不到时，SDK 会静默
+  // fallback 到默认模型，回显配置原文会掩盖这次 fallback。
+  result.model = session.model?.id;
+
   let logLines: string[] = [];
   // 工具调用行合并:连续的 tool_execution_start 事件合并在同一 `tool:` 行
   // (如 `tool: read x 2, glob`),相同工具名连续出现时计为 `name x N`,