@yeaft/webchat-agent 1.0.495 → 1.0.497

package/skills/review-merge-tag/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: review-merge-tag
+description: 用 RepoWorkflow 在任意 GitHub 仓库执行开发 worktree、精确 PR review snapshot、base-ref CAS landing、数字 tag 与 workflow 验证；避免重复手工 git/gh 检查。
+---
+
+# Repository Workflow
+
+不要逐条调用 `git fetch`、`git worktree list`、`gh pr view`、`git ls-remote` 和 `gh run watch` 来发现同一批事实。Session 内使用 `RepoWorkflow` 工具。非 Yeaft 环境可用 `yeaft-repo` CLI 执行 `prepare` 和 `review-prep`，这两个阶段返回与工具相同的紧凑 JSON；CLI 不能执行 `land`。
+
+## 三个边界
+
+### 1. 开发准备
+
+```json
+{
+  "phase": "prepare",
+  "name": "fix-short-description"
+}
+```
+
+它会在当前仓库中确定远端默认分支、拉取最新精确基线、检查 worktree/branch/path 冲突，并创建或安全复用 `yeaft-wt/<name>`。后续开发只使用返回的 `worktree.path`。
+
+### 2. 独立 review 准备
+
+Reviewer 调用：
+
+```json
+{
+  "phase": "review-prep",
+  "pr": 123
+}
+```
+
+它会一次冻结 GitHub PR 的 base branch/base SHA/head/merge snapshot、检查 draft/conflict/checks，并创建 detached exact-snapshot review worktree。Reviewer 必须审查返回的 `reviewWorktree.path`，并把明确结论、`pullRequest.baseBranch`、`pullRequest.baseSha`、`pullRequest.headSha` 和 `pullRequest.snapshotSha` 交回开发者。
+
+工具只冻结事实，不替代代码审查。
+
+### 3. Review 通过后的落地
+
+只有收到独立 reviewer 的明确批准后才能调用。Reviewer 必须用 `RouteForward` 把绑定仓库、PR、exact base branch/base SHA/head/merge snapshot 的结构化批准交回 landing VP；宿主会随该 handoff 铸造不可序列化、一次性的 approval capability。随后 landing VP 才能在处理该 handoff 的同一 turn 调用：
+
+```json
+{
+  "phase": "land",
+  "pr": 123,
+  "baseBranch": "main",
+  "baseSha": "<exact 40-char base SHA>",
+  "reviewedHead": "<exact 40-char head SHA>",
+  "reviewedSnapshot": "<exact 40-char merge snapshot SHA>",
+  "tagPrefix": "v1.0.",
+  "workflow": "Dev Release"
+}
+```
+
+`approvedBy` 等普通字符串没有授权语义。`land` 只接受宿主 capability，并重新冻结 PR；任何 repo、PR、recipient、base branch、base SHA、head 或 snapshot 不匹配都会停止。Reviewed snapshot 必须以批准的 base SHA/head 为两个父提交；landing 的目标 ref 只从批准的 base branch 推导，并在任何写入前拒绝 PR retarget。之后它通过单次 receive-pack 更新，用 `--force-with-lease=<base-ref>:<approved-base>` 将该 exact snapshot 安装到批准的远端 base。若 base 在最后冻结与 receive 之间前进，lease 会拒绝更新，并且不会创建 tag。若要求 tag，它只在 base CAS 成功后从远端 tags 数值计算下一版，用 create-only lease 推送并复核 base 与 tag。若要求 workflow，它等待匹配 tag 与 reviewed snapshot SHA 的 run 完成。
+
+Worktree cleanup 不属于 landing。`land` 会在任何仓库或远端副作用前拒绝 cleanup 请求，包括 active `repoRoot`；需要 cleanup 时必须在 landing 完成后走独立操作，cleanup 失败不能改变 landing 结果。
+
+## 通用性与边界
+
+- 适用于 Agent 可访问的任意本地 GitHub 仓库，不包含项目路径或固定 `main` 假设。
+- 需要 `git` 和已认证的 `gh` CLI；不依赖 Python，也不通过 shell 拼接命令。
+- 当前不支持 GitLab/Bitbucket；不要把 GitHub 成功误报为 forge-agnostic。
+- 自动化只消除重复事实核对，不消除独立 review、测试选择、代码判断或用户授权。
+- `land` 后若 workflow 失败，merge/tag 可能已经完成；读取错误 JSON 的 `details.remoteEffects`，不要盲目重试或重打 tag。
+
+## CLI
+
+Yeaft 外部或人工终端只可运行准备阶段：
+
+```bash
+yeaft-repo prepare --name fix-short-description
+yeaft-repo review-prep --pr 123
+```
+
+独立 CLI 不能执行 `land`。Landing 必须在 Session 中通过 `RepoWorkflow` 工具执行，并携带当前 handoff 由宿主签发、绑定 exact review 的 approval capability；普通参数或 `approvedBy` 字符串不能替代该 capability。
+
+每条可用命令 stdout 只输出一个成功 JSON；失败时 stderr 输出一个带稳定 `code` 和副作用状态的 JSON。

package/yeaft/cli-session-runner.js

@@ -250,7 +250,10 @@ export function createCliSessionRunner({
       sessionMembers: meta.roster.slice(),
       sessionAnnouncement: meta.announcement || '',
       vpPersona: personaFactory(vpId, loaded),
-      router: createRouter({ coordinator: scopedCoordinator, guard: routeForwardGuard }),
+      router: createRouter({
+        coordinator: scopedCoordinator,
+        guard: routeForwardGuard,
+      }),
       inboundEnvelope: envelope,
       userAlreadyPersisted: true,
       causalRootId,

package/yeaft/engine.js

@@ -1416,6 +1416,7 @@ export class Engine {
         ? vpCtx.projectSessionIds.slice()
         : [],
       threadId: vpCtx?.threadId || this.#currentThreadId || MAIN_THREAD_ID,
+      turnId: vpCtx?.turnId || null,
       currentVpId: vpCtx?.senderVpId || this.#vpId || null,
       // task-704b: per-tool-result hard cap derives from this. Threaded
       // from the live model (resolveModel(currentModel)) every turn so
@@ -3847,6 +3848,7 @@ export class Engine {
         projectInstruction,
         projectLabel,
         threadId: runtimeThreadId,
+        turnId: vpTurnId,
         inboundEnvelope,
         taskId,
         taskMembers,

package/yeaft/init.js

@@ -15,7 +15,7 @@ import { mutateAgentConfig } from './config-store.js';
 // layout AND rewrites pre-rename per-message frontmatter (groupId → sessionId).
 // Idempotent via the `.yeaft-migration.done` sentinel file.
 import { migrateSessions } from './migrate/sessions.js';
-import { bundledYeaftSkillsDir } from './skills.js';
+import { bundledYeaftSkillsDirs } from './skills.js';
 
 /**
  * Check if an error is a permission error (EACCES or EPERM).
@@ -353,7 +353,10 @@ function readManifest(filePath) {
  * @returns {{ copied: number, updated: number, preserved: number, skipped: number }}
  */
 export function seedBundledSkills(userSkillsDir, warnings = []) {
-  const bundled = bundledYeaftSkillsDir();
+  // Seed only the highest-priority root. Runtime loading still scans every
+  // bundled root; flattening lower-priority roots into the user tier here
+  // would erase bundled provenance and conflict ordering.
+  const bundled = bundledYeaftSkillsDirs().at(-1);
   if (!bundled) {
     return { copied: 0, updated: 0, preserved: 0, skipped: 0 };
   }

package/yeaft/routing/router.js

@@ -28,6 +28,122 @@
 import { resolveMemberId } from '../sessions/roster.js';
 import { createLoopGuard, extendCausedBy } from './loop-guard.js';
 
+const repoApprovals = new WeakMap();
+const REPO_APPROVAL_ISSUER_IDS = new Set(['martin']);
+export const REPO_APPROVAL_TTL_MS = 2 * 60 * 1000;
+
+function normalizeId(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeSha(value) {
+  const sha = normalizeId(value).toLowerCase();
+  return /^[0-9a-f]{40}$/.test(sha) ? sha : '';
+}
+
+function normalizeApprovalRepository(value) {
+  const repository = normalizeId(value).replace(/\.git$/i, '');
+  const segments = repository.split('/');
+  if (segments.length === 2) segments.unshift('github.com');
+  if (segments.length !== 3) return '';
+  const [host, owner, name] = segments;
+  const safePart = part => /^[a-z0-9_.-]+$/i.test(part) && part !== '.' && part !== '..';
+  if (!safePart(host) || !safePart(owner) || !safePart(name) || !host.includes('.')) return '';
+  return `${host}/${owner}/${name}`.toLowerCase();
+}
+
+function isRepoApprovalIssuer(vpId) {
+  return REPO_APPROVAL_ISSUER_IDS.has(normalizeId(vpId));
+}
+
+/**
+ * Mint authority only inside the canonical Router path after roster identity
+ * resolution. Keeping this function module-private prevents callers from
+ * turning a claimed issuer string into landing authority.
+ */
+function issueRepoApprovalCapability(input = {}, { now = Date.now } = {}) {
+  const sessionId = normalizeId(input.sessionId);
+  const issuerVpId = normalizeId(input.issuerVpId);
+  const recipientVpId = normalizeId(input.recipientVpId);
+  const repository = normalizeApprovalRepository(input.repository);
+  const pr = Number(input.pr);
+  const baseBranch = normalizeId(input.baseBranch);
+  const baseSha = normalizeSha(input.baseSha);
+  const reviewedHead = normalizeSha(input.reviewedHead);
+  const reviewedSnapshot = normalizeSha(input.reviewedSnapshot);
+  const issuedAt = Number(now());
+  if (!sessionId || !isRepoApprovalIssuer(issuerVpId) || !recipientVpId || issuerVpId === recipientVpId
+    || !repository || !Number.isSafeInteger(pr) || pr <= 0 || !baseBranch || !baseSha
+    || !reviewedHead || !reviewedSnapshot || !Number.isFinite(issuedAt)) {
+    return null;
+  }
+  const capability = Object.freeze(Object.create(null));
+  repoApprovals.set(capability, {
+    sessionId,
+    issuerVpId,
+    recipientVpId,
+    repository,
+    pr,
+    baseBranch,
+    baseSha,
+    reviewedHead,
+    reviewedSnapshot,
+    issuedAt,
+    expiresAt: issuedAt + REPO_APPROVAL_TTL_MS,
+    turnId: null,
+  });
+  return capability;
+}
+
+export function isRepoApprovalCapability(capability) {
+  return Boolean(capability && typeof capability === 'object' && repoApprovals.has(capability));
+}
+
+/** Bind a freshly issued capability to the exact Web execution that received it. */
+export function bindRepoApprovalCapability(capability, expected = {}, { now = Date.now } = {}) {
+  if (!capability || typeof capability !== 'object') return false;
+  const grant = repoApprovals.get(capability);
+  const turnId = normalizeId(expected.turnId);
+  const currentTime = Number(now());
+  if (!grant || !turnId || !Number.isFinite(currentTime)) return false;
+  if (currentTime > grant.expiresAt
+    || grant.turnId
+    || grant.sessionId !== normalizeId(expected.sessionId)
+    || grant.recipientVpId !== normalizeId(expected.recipientVpId)) {
+    repoApprovals.delete(capability);
+    return false;
+  }
+  grant.turnId = turnId;
+  return true;
+}
+
+export function revokeRepoApprovalCapability(capability) {
+  if (!capability || typeof capability !== 'object') return false;
+  return repoApprovals.delete(capability);
+}
+
+/** Consume a capability exactly once and verify its complete landing tuple. */
+export function consumeRepoApprovalCapability(capability, expected = {}, { now = Date.now } = {}) {
+  if (!capability || typeof capability !== 'object') return null;
+  const grant = repoApprovals.get(capability);
+  repoApprovals.delete(capability);
+  if (!grant) return null;
+  const currentTime = Number(now());
+  const matches = Number.isFinite(currentTime)
+    && currentTime <= grant.expiresAt
+    && grant.turnId
+    && grant.turnId === normalizeId(expected.turnId)
+    && grant.sessionId === normalizeId(expected.sessionId)
+    && grant.recipientVpId === normalizeId(expected.recipientVpId)
+    && grant.repository === normalizeApprovalRepository(expected.repository)
+    && grant.pr === Number(expected.pr)
+    && grant.baseBranch === normalizeId(expected.baseBranch)
+    && grant.baseSha === normalizeSha(expected.baseSha)
+    && grant.reviewedHead === normalizeSha(expected.reviewedHead)
+    && grant.reviewedSnapshot === normalizeSha(expected.reviewedSnapshot);
+  return matches ? Object.freeze({ ...grant }) : null;
+}
+
 function routeForwardParentFromEnvelope(envelope) {
   const msg = envelope?.msg;
   const meta = msg?.meta;
@@ -75,7 +191,8 @@ export function createRouter(deps = {}) {
   if (!coordinator || typeof coordinator.ingest !== 'function') {
     throw new Error('createRouter: coordinator (with ingest()) is required');
   }
-  const guard = deps.guard || createLoopGuard({ now: deps.now });
+  const now = typeof deps.now === 'function' ? deps.now : Date.now;
+  const guard = deps.guard || createLoopGuard({ now });
 
   /**
    * Forward a message from a VP to another VP (or @all). Routes through
@@ -122,6 +239,8 @@ export function createRouter(deps = {}) {
     }
     const meta = coordinator.group.getMeta();
     if (!meta) return { ok: false, error: 'group_not_initialised' };
+    const senderVpId = resolveMemberId(meta, from);
+    if (!senderVpId) return { ok: false, error: 'sender_not_in_roster' };
     const claimedVpIds = args.inboundEnvelope?._cliTurnContext?.claimedVpIds;
 
     // Roster membership — `all` is reserved broadcast sentinel handled by
@@ -132,7 +251,7 @@ export function createRouter(deps = {}) {
     if (targetVpId !== 'all' && !targetVpId) {
       return { ok: false, error: 'target_not_in_roster' };
     }
-    if (targetVpId === from) {
+    if (targetVpId === senderVpId) {
       return { ok: false, error: 'self_forward_rejected' };
     }
     if (targetVpId !== 'all' && claimedVpIds?.has?.(targetVpId)) {
@@ -146,6 +265,24 @@ export function createRouter(deps = {}) {
     // spec's intent ("depth of forwards already taken").
     const chain = extendCausedBy(args.inboundEnvelope || null, null);
     const routeForwardParent = routeForwardParentFromEnvelope(args.inboundEnvelope);
+    let repoApproval = null;
+    if (args.repoApproval !== undefined) {
+      if (targetVpId === 'all') {
+        return { ok: false, error: 'repo_approval_requires_single_target' };
+      }
+      if (!isRepoApprovalIssuer(senderVpId)) {
+        return { ok: false, error: 'repo_approval_issuer_forbidden' };
+      }
+      repoApproval = issueRepoApprovalCapability({
+        ...args.repoApproval,
+        sessionId: meta.id,
+        issuerVpId: senderVpId,
+        recipientVpId: targetVpId,
+      }, { now });
+      if (!repoApproval) {
+        return { ok: false, error: 'invalid_repo_approval' };
+      }
+    }
 
     // Loop guard: for broadcast, use 'all' as the target key so one VP
     // spamming @all still gets throttled even if each cycle hits different
@@ -182,6 +319,7 @@ export function createRouter(deps = {}) {
         // of UI replay and future visible history so it doesn't render as a
         // second assistant/user block after the target VP answers.
         internal: true,
+        ...(repoApproval ? { _repoApproval: repoApproval } : {}),
         meta: {
           synthetic: true,
           injectedBy: 'route_forward',

package/yeaft/skills.js

@@ -28,9 +28,10 @@
  *
  * The standard tier order set up by `createSkillManager` is:
  *
- *   tier 1 (bundled): wherever yeaft-skills is installed on disk — typically
- *           ~/.claude/skills/yeaft-skills/skills/. Read-only — `save()` and
- *           `remove()` never target this tier.
+ *   tier 1 (bundled): all available external yeaft-skills roots plus the Agent
+ *           package's own skills. External roots load first; Agent built-ins
+ *           win bundled-name conflicts. Read-only — `save()` and `remove()`
+ *           never target this tier.
  *   tier 2 (user):    <yeaftDir>/skills (e.g. ~/.yeaft/skills). User edits
  *           land here. `save()` writes here. `init.js` seeds it from tier 1
  *           on first boot so users start with the bundled Yeaft skills.
@@ -1197,8 +1198,9 @@ export class SkillManager {
  * Create a SkillManager wired with the standard layered tier list and load it.
  *
  * Tier order (lowest → highest priority):
- *   1. bundled        — the yeaft-skills package on disk, located via
- *      `bundledYeaftSkillsDir()` (typically ~/.claude/skills/yeaft-skills/skills/).
+ *   1. bundled        — every available bundled root returned by
+ *      `bundledYeaftSkillsDirs()`. External packages add skills, while the
+ *      Agent package loads last so its built-in skills win bundled conflicts.
  *   2. user           — `<yeaftDir>/skills` (e.g. ~/.yeaft/skills). User edits + saves.
  *   3. project-claude — `<workDir>/.claude/skills` when a workDir is provided.
  *      Claude Code project assets, loaded so a project that integrates Claude
@@ -1218,7 +1220,7 @@ export class SkillManager {
  * @returns {SkillManager}
  */
 export function createSkillManager(yeaftDir, workDir, options = {}) {
-  const bundled = bundledYeaftSkillsDir();
+  const bundledDirs = bundledYeaftSkillsDirs();
   const userDir = join(yeaftDir, 'skills');
   const projectRoots = [...new Set(String(workDir || '')
     .split(delimiter)
@@ -1228,9 +1230,9 @@ export function createSkillManager(yeaftDir, workDir, options = {}) {
   const codexProjectDirs = projectRoots.map(root => join(root, '.agents', 'skills'));
   const projectDirs = projectRoots.map(root => join(root, '.yeaft', 'skills'));
 
-  const dirs = [bundled, userDir, ...claudeProjectDirs, ...codexProjectDirs, ...projectDirs].filter(Boolean);
+  const dirs = [...bundledDirs, userDir, ...claudeProjectDirs, ...codexProjectDirs, ...projectDirs];
   const tierByDir = {};
-  if (bundled) tierByDir[bundled] = 'bundled';
+  for (const dir of bundledDirs) tierByDir[dir] = 'bundled';
   tierByDir[userDir] = 'user';
   for (const dir of claudeProjectDirs) tierByDir[dir] = 'project-claude';
   for (const dir of codexProjectDirs) tierByDir[dir] = 'project-codex';
@@ -1256,56 +1258,75 @@ export function createSkillManager(yeaftDir, workDir, options = {}) {
 // ─── Bundled-skills resolver ──────────────────────────────
 
 /**
- * Locate the bundled `yeaft-skills` package on disk.
+ * Locate every available bundled Skill root on disk.
  *
- * Resolution order (first existing directory wins):
- *   1. $YEAFT_SKILLS_BUNDLED_DIR — explicit env override (testing / packaging)
- *   2. ~/.claude/skills/yeaft-skills/skills/    — standard Claude Code plugin layout
- *   3. ~/.claude/plugins/yeaft-skills/skills/   — alternate plugin layout
- *   4. <agent-pkg>/skills/                       — bundled-with-agent fallback so
- *      a future npm release can ship its own skills directory
+ * The returned array is ordered from lowest to highest priority, matching the
+ * `SkillManager` layered-load contract:
+ *   1. ~/.claude/plugins/yeaft-skills/skills/   — alternate plugin layout
+ *   2. ~/.claude/skills/yeaft-skills/skills/    — standard Claude Code layout
+ *   3. $YEAFT_SKILLS_BUNDLED_DIR                 — explicit additional root
+ *   4. <agent-pkg>/skills/                       — authoritative Agent built-ins
  *
- * Returns `null` when none exist — callers must tolerate this (Yeaft still
- * runs; the user just sees no pre-installed bundled skills). Co-located here
- * (rather than in init.js) so both `createSkillManager()` and init.js's seed
- * step can call it without a module cycle.
+ * All existing roots coexist. The Agent package is deliberately last so an
+ * external package or env override cannot shadow safety-critical built-ins.
+ * User and project tiers still load after these roots and retain their existing
+ * higher-priority customization semantics.
  *
- * @returns {string|null}
+ * @returns {string[]}
  */
-export function bundledYeaftSkillsDir() {
+export function bundledYeaftSkillsDirs() {
   const candidates = [];
+  const home = homedir();
+  if (home) {
+    candidates.push(join(home, '.claude', 'plugins', 'yeaft-skills', 'skills'));
+    candidates.push(join(home, '.claude', 'skills', 'yeaft-skills', 'skills'));
+  }
 
   const envOverride = process.env.YEAFT_SKILLS_BUNDLED_DIR;
   if (envOverride && typeof envOverride === 'string' && envOverride.length > 0) {
     candidates.push(envOverride);
   }
 
-  const home = homedir();
-  if (home) {
-    candidates.push(join(home, '.claude', 'skills', 'yeaft-skills', 'skills'));
-    candidates.push(join(home, '.claude', 'plugins', 'yeaft-skills', 'skills'));
-  }
-
-  // Bundled-with-agent fallback: <agent-pkg-root>/skills. The package root is
-  // the directory containing agent/, so we walk up from this file.
+  // Bundled-with-agent root: <agent-pkg>/skills. The package root is the
+  // directory containing yeaft/, so walk up from this file.
   try {
     const here = dirname(fileURLToPath(import.meta.url));
-    // here = .../agent/yeaft
-    const agentRoot = join(here, '..', '..');
-    candidates.push(join(agentRoot, 'skills'));
+    candidates.push(join(here, '..', 'skills'));
   } catch {
     // fileURLToPath can throw on exotic loaders — non-fatal.
   }
 
-  for (const c of candidates) {
+  const roots = [];
+  for (const candidate of candidates) {
+    if (!candidate || roots.includes(candidate)) continue;
     try {
-      if (c && existsSync(c) && statSync(c).isDirectory()) {
-        return c;
+      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        roots.push(candidate);
       }
     } catch {
-      // permission errors etc. — try the next candidate.
+      // Permission errors etc. make this candidate unavailable.
     }
   }
+  return roots;
+}
 
-  return null;
+/**
+ * Back-compatible singular resolver with the original first-existing order.
+ * New callers that load Skills must use `bundledYeaftSkillsDirs()` so all
+ * roots coexist.
+ *
+ * @returns {string|null}
+ */
+export function bundledYeaftSkillsDir() {
+  const roots = bundledYeaftSkillsDirs();
+  const envOverride = process.env.YEAFT_SKILLS_BUNDLED_DIR;
+  const home = homedir();
+  const legacyOrder = [
+    envOverride,
+    home ? join(home, '.claude', 'skills', 'yeaft-skills', 'skills') : null,
+    home ? join(home, '.claude', 'plugins', 'yeaft-skills', 'skills') : null,
+  ];
+  return legacyOrder.find(candidate => candidate && roots.includes(candidate))
+    || roots.at(-1)
+    || null;
 }

package/yeaft/sub-agent/execution-control.js

@@ -0,0 +1,90 @@
+/** Sub-agent-local execution policy. No Session config or parent registry is mutated. */
+import { createHash } from 'node:crypto';
+import { ToolRegistry, isToolErrorOutput } from '../tools/registry.js';
+
+/** Defaults are safety ceilings, not targets; explicit positive limits override each field. */
+export function resolveSubAgentBudget(budget, persona) {
+  return {
+    max_tool_calls: persona === 'implementer' ? 128 : 64,
+    wall_time_ms: 15 * 60 * 1000,
+    ...budget,
+  };
+}
+
+export function createExecutionStats() {
+  return { toolCalls: 0, completedCalls: 0, failedCalls: 0, repeatedResults: 0, recentCalls: [], warning: null };
+}
+
+function fingerprint(value) {
+  return createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+}
+
+/**
+ * Structural child-only fence, including aliases and MCP hot registration. The
+ * synchronous reservation precedes execute(), so parallel calls cannot overshoot.
+ * Parent Active Tool Set checks remain independent and must not be bypassed.
+ */
+export class SubAgentToolRegistry extends ToolRegistry {
+  constructor({ allows = () => true, agent = null, stopBudget = null } = {}) {
+    super();
+    this.allows = allows;
+    this.agent = agent;
+    this.stopBudget = stopBudget;
+    this.recentFingerprints = [];
+  }
+
+  register(tool) {
+    if (this.allows(tool)) super.register(tool);
+    return this;
+  }
+
+  async execute(name, input, ctx = {}) {
+    const tool = this.get(name);
+    if (!tool) throw new Error(`Unknown or disallowed child tool: ${name}`);
+    const agent = this.agent;
+    if (!agent) return super.execute(name, input, ctx);
+    // Serial dispatch can resume after a tool_start yield; never start a write
+    // after cancellation, even when the underlying tool ignores AbortSignal.
+    const signal = agent.abortController?.signal;
+    if (signal?.aborted) throw new Error(String(signal.reason || 'Sub-agent aborted'));
+    const stats = agent.execution || (agent.execution = createExecutionStats());
+    const limit = agent.budget?.max_tool_calls;
+    if (limit !== undefined && stats.toolCalls >= limit) {
+      const reason = `max_tool_calls (${limit}) reached; return partial evidence to the parent before extending scope`;
+      this.stopBudget?.(reason);
+      throw new Error(reason);
+    }
+    stats.toolCalls += 1;
+    agent.usage ||= { tokens: 0, turns: 0, startedAt: Date.now() };
+    agent.usage.toolCalls = stats.toolCalls;
+    const entry = { name: tool.name, status: 'running' };
+    stats.recentCalls.push(entry);
+    if (stats.recentCalls.length > 8) stats.recentCalls.shift();
+    if (limit && stats.toolCalls >= Math.ceil(limit * 0.75)) {
+      stats.warning = 'Tool budget nearly exhausted. Collect the current evidence; do not restart the same investigation.';
+    }
+    try {
+      const output = await super.execute(name, input, ctx);
+      const failed = tool.errorOutput === 'json-error-envelope' && isToolErrorOutput(output);
+      entry.status = failed ? 'error' : 'completed';
+      stats.completedCalls += 1;
+      if (failed) stats.failedCalls += 1;
+      // Advisory only: repeated results are not proof of semantic non-progress.
+      // Read ranges, cursors and changed outputs have distinct fingerprints.
+      try {
+        if (tool.isReadOnly?.(input) === true) {
+          const key = fingerprint([tool.name, input, output]);
+          if (this.recentFingerprints.includes(key)) stats.repeatedResults += 1;
+          this.recentFingerprints.push(key);
+          if (this.recentFingerprints.length > 12) this.recentFingerprints.shift();
+        }
+      } catch { /* Advisory instrumentation must never turn a successful tool into a retry. */ }
+      return output;
+    } catch (error) {
+      entry.status = 'error';
+      stats.completedCalls += 1;
+      stats.failedCalls += 1;
+      throw error;
+    }
+  }
+}

package/yeaft/sub-agent/liveness.js

@@ -131,6 +131,13 @@ export function diagnoseAgentLiveness(agent, opts = {}) {
     && msSinceActivity >= thresholdMs;
   return {
     ...liveness,
+    execution: agent?.execution ? {
+      ...agent.execution,
+      recentCalls: agent.execution.recentCalls.map(call => ({ ...call })),
+      remainingToolCalls: Math.max(0, (agent.budget?.max_tool_calls || 0) - agent.execution.toolCalls),
+      limits: agent.budget,
+      progressNote: 'Execution counts and repeated results are diagnostics, not proof of semantic progress or stalling.',
+    } : null,
     msSinceLastEvent: liveness.msSinceLastEvent ?? msSinceActivity,
     stale,
     stalled: stale,