@tea-agent/loop-agent 0.39.0-next.26 → 0.39.0-next.27

package/CHANGELOG.md

@@ -4,12 +4,16 @@
 
 ### 变更
 
+- frozen repair 工具审计改为按 attempt 段扫描（B1）：`session-events.jsonl` 跨 attempt 共享追加，attempt>1 的 `auditRepairAttemptToolUse` 现在只审本 attempt 字节段（newline 对齐），planner attempt 1 的 ls/find 不再被误判给 repair 轮；repair prompt 显式声明 read-only 工具契约与 allowlist 边界（B2），并内嵌 openspec-citations 输出格式正例；`LOOP_AGENT_IGNORE_STALE_DIST=1` 环境变量旁路 stale-dist guard（B3），Console spawn 的 sibling CLI 可继承。
+- frontend plan/revision 结构化输出改为冻结 repair context + hash-bound canonical artifact：attempt>1 不再重放完整 planner prompt；成功后 stdout 只保留 artifact 路径，design review / prewrite 只消费已校验 artifact，不再从节点文本 merge。失败分类补齐 `structured-repair-exhausted` / `governance-blocked`，并修正 `structured-output-truncated` / `output-too-large` 的归一化映射。
 - 将 `@earendil-works/pi-ai` 与 `@earendil-works/pi-coding-agent` 从可选依赖提升为精确 pin 的运行时依赖 `0.83.0`，将运行时直接导入的 `typebox` 精确声明为 `1.3.7`，并在根包声明 Node.js `>=22.19.0`。安装 `@tea-agent/loop-agent` 会默认装上 Pi SDK（含 `--omit=optional` 场景）；`@cursor/sdk` 仍保持 optional。availability / readiness 探针、隔离 tarball canary、发布包契约测试与安装/本地环境说明同步对齐。
 - backend-test Scenario Partition 仅接受绑定源有限 enum/分类集合的 GET/list query/path 轴；非法 Domain（空/重复/保留 token、无有限域、与 OpenAPI enum 不一致）报 `INVALID_PARTITION_DOMAIN` / `NO_FINITE_DOMAIN` / `PARTITION_SOURCE_MISMATCH` 根因，不再生成空后缀 `TP-SP-...-`、重复 slot，也不再级联 `MISSING_*_SLOT`。N6 对这些根因码 fail-closed；合法源分区缺槽仍阻断。N2 禁止为自由串/主键/required-only/boundary-only 建分区；N5 允许删除无源非法 Partition 及其派生槽位。
 - npm `next` 渠道发布改为提交数节流：main push 仅当距上次 next 发布的 source commit ≥ 5 个 commit 时才自动发布（新增 `scripts/next-publish-gate.mjs`，读已发布 tarball build-stamp 对比 HEAD）；不足阈值时 workflow 绿色跳过，手动 `workflow_dispatch` 不受限（切 release 线前强制出包 / 紧急补发）。发布文档真源 §4.1/§5.1/§7/§12 同步。
 
 ### 新增
 
+- 观察面 DAG Inspector 节点详情适配 Pi 扩展：执行器输入摘要展示节点声明的 `piExtensions` 短 id；新增「Pi 扩展运行事实」展示 `pi-extensions.json` 的 resolved（包名@版本）与 missing 降级原因（缺包降级不再静默）；产物未生成/损坏时降级提示不阻断接口，绝对路径不外泄。
+- 后端实现 DAG（standard / review-gated / supervised）的 Pi 节点支持按桶显式加载本机 Pi 导航扩展：读侧节点（除 closeout）加载 `pi-codegraph` + `pi-lens`，写侧节点只加载 `pi-codegraph`（pi-lens 的 `ast_grep_replace` 可绕过 writeSet，不加载）；前端/测试模板与省略字段节点保持扩展全关。扩展发现始终关闭，只经白名单解析 `~/.pi/agent` 与项目 `.pi` settings 的已装包（缺包降级不失败，产物 `pi-extensions.json` 记录 requested/resolved/missing）；session 后 pin 工具面剔 builtin 同名、deny 面与写工具，writer 的 `edit`/`write` 仍为 policy-wrapped；`.codegraph/**` index 同步不再计入 write-guard 越界。
 - Pi SDK 终态 session-events JSONL 顶层增加可选 `finish_reason`：仅当 `message_end` / `turn_end` / `assistant_message` 明确携带非空终止原因时由序列化层提升，不伪造默认值，也不回流 `stopReason` 诊断。
 - `backendTest` 布局配置纳入 Task Contract managed 注入面：`task advance` 新增 `--backend-test <json>`，可在公共任务生命周期内把 `testRoot`/`markdownRel`/`scriptRel`/`sharedSetupDoc`/`mode`/`gapDoc`/`executeScope` 写进 `task.json`，不再需要手工编辑（手工编辑会让任务漂移成 `externally-modified` 并拒绝 `--approve-gate`）。给出即整体替换、省略即保留既有配置（历史手写配置因此自愈）、`'{}'` 为显式清空回默认布局；重复 advance 幂等，契约保持 `managed`。`task contract diff` 把值变更标 routine `BACKEND_TEST_CONFIG_CHANGED`、丢键/清空额外标 elevated `BACKEND_TEST_CONFIG_WEAKENED`。
 - Operator Chat 文件预览抽屉新增图标「新窗口打开」：用当前已加载内容在独立浏览器窗口打开全页阅读视图，窗口内可切换「预览 / 查看原文」（带宽高的 `window.open` popup，Markdown 排版、HTML 铺满视口的空 sandbox iframe、JSON pretty-print / 其它文本等宽滚动）；打开成功后断开 `opener` 且不立刻 revoke Blob，避免空白页；弹窗被拦截时 header 附近报错且不关闭抽屉
@@ -33,6 +37,7 @@
 
 ### 改进
 
+- frontend DAG 的 materialized source references 恢复统一的有界 excerpt 与按需 read 指针，不再把 requirement/acceptance 文档全文复制进每个相关节点，也不再强制 contract/plan 重读全部绑定源文件，降低长需求在多节点中的重复上下文占用。
 - frontend-test prepare-package 会从 `docs/templates/`、`harness.json` `governanceRoot`/templates 以及 init 投影的 `ai_workspace/loop-agent/templates/` 拷贝标准场景；full init 目标仓不再静默落到仅含 `STD-FE-SMOKE-ENTRY` 的 fallback。
 - frontend-test 环境探测区分 connection-refused（curl 7）与 HTTP 4xx/5xx，并提示先启动本地前端后再从 probe 节点续跑；不再把所有不可达都写成同一句 `frontend-base-url-unreachable`。
 - frontend-test 报告解析用例 Markdown 的 `##`/`###` 标题与有序列表（`测试步骤` / `预期结果` / `前置条件与重置`）；缺 `测试目的` 时回退到用例 H1，避免主 HTML 出现空步骤。

package/bin/loop-agent.js

@@ -18,11 +18,15 @@ if (!existsSync(cliEntry)) {
  * to silently execute a dist/ that predates the latest source edit. The
  * classic failure mode is editing src/** and running the bin without
  * `npm run build`, which executes the previous build. Suppress with
- * --ignore-stale-dist when intentionally running a stale build.
+ * --ignore-stale-dist (or LOOP_AGENT_IGNORE_STALE_DIST=1, which sibling
+ * processes such as a Console-spawned CLI inherit automatically) when
+ * intentionally running a stale build.
  */
 const srcDir = join(packageRoot, "src");
-const ignoreStale = process.argv.includes("--ignore-stale-dist");
-if (ignoreStale) {
+const ignoreStale =
+  process.argv.includes("--ignore-stale-dist") ||
+  process.env.LOOP_AGENT_IGNORE_STALE_DIST === "1";
+if (process.argv.includes("--ignore-stale-dist")) {
   process.argv = process.argv.filter((arg) => arg !== "--ignore-stale-dist");
 }
 if (!ignoreStale && existsSync(srcDir)) {

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "version": "0.37.0",
-  "gitSha": "261086956566acadb9df5ed94b528938cf8d058e",
-  "builtAt": "2026-08-21T12:44:01.132Z"
+  "gitSha": "9c7e31bf37a0baf78e1135d61a7d5a2d97d8b8d3",
+  "builtAt": "2026-08-22T01:16:09.804Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
-import { executePiStep, } from "./pi-executor.js";
+import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
+import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
 import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
@@ -327,6 +328,36 @@ export async function writePiExecutorArtifacts(artifactsDir, input) {
     await writeTextArtifactFile(summaryPath, buildPiResultSummaryMarkdown(input));
     return { promptPath, summaryPath };
 }
+/**
+ * Run-owned per-node Pi extension facts (plan 2026-08-21): requested ids,
+ * resolved packages (with absolute entry paths), and degraded/missing ids.
+ * Written only for nodes that declare `piExtensions`; never into the repo-level
+ * DAG template. Best-effort: artifact failures never fail the node.
+ */
+async function writePiExtensionsArtifact(nodeArtifactsDir, requested, resolved, missing) {
+    try {
+        const runDir = path.dirname(nodeArtifactsDir);
+        const nodeId = path.basename(nodeArtifactsDir);
+        await writeDagNodeJsonArtifact(runDir, nodeId, "pi-extensions.json", {
+            schemaVersion: 1,
+            requested: [...requested],
+            resolved: resolved.map((entry) => ({
+                id: entry.id,
+                packageName: entry.packageName,
+                version: entry.version,
+                path: entry.entryPaths.join(", "),
+            })),
+            missing: missing.map((entry) => ({
+                id: entry.id,
+                reason: entry.reason,
+                ...(entry.detail ? { detail: entry.detail } : {}),
+            })),
+        });
+    }
+    catch {
+        // best-effort run fact; node execution continues
+    }
+}
 async function resolveValidatedFrontendBaseUrlFromContext(workspaceRoot, runDir) {
     try {
         const capability = JSON.parse(await readFile(path.join(runDir, "preflight-frontend-browser-tool-shell", "frontend-browser-capability.json"), "utf8"));
@@ -550,6 +581,29 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 };
             }
         }
+        // Plan 2026-08-21 D4/D6: resolve the node's explicit Pi extension
+        // allowlist against the settings inventory. Degrade on missing packages —
+        // never fail the node — and persist requested/resolved/missing facts.
+        const piExtensionsResolution = input.task.piExtensions
+            ? resolveDagPiExtensions({
+                repoRoot: input.cwd,
+                ids: input.task.piExtensions,
+            })
+            : undefined;
+        if (piExtensionsResolution) {
+            const piBackend = resolvePiBackend();
+            const cliDegraded = piBackend === "cli-only";
+            await writePiExtensionsArtifact(path.join(meta.runDir, input.task.id), input.task.piExtensions, cliDegraded ? [] : piExtensionsResolution.resolved, cliDegraded
+                ? input.task.piExtensions.map((id) => ({
+                    id,
+                    reason: "not-installed",
+                    detail: "cli backend does not load pi extensions (sdk-only v1)",
+                }))
+                : piExtensionsResolution.missing);
+        }
+        const piExtensionPaths = piExtensionsResolution && resolvePiBackend() !== "cli-only"
+            ? piExtensionsResolution.resolved.flatMap((entry) => entry.entryPaths)
+            : undefined;
         result = await piStepFn({
             attachedFiles: [],
             modelConfig: resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined),
@@ -564,6 +618,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             stallTimeoutMs: input.stallTimeoutMs,
             abortGraceMs: input.abortGraceMs,
             ...(writerToolPolicy ? { writerToolPolicy } : {}),
+            ...(piExtensionPaths && piExtensionPaths.length > 0
+                ? { piExtensionPaths }
+                : {}),
             onActivity: bridgeActivity
                 ? (activity) => {
                     if (activity.kind === "lease" ||

package/dist/executors/pi-extension-resolver.js

@@ -0,0 +1,233 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Pi extension allowlist for backend implementation DAGs (plan D2/D3).
+ * DAG specs carry these frozen short ids; the executor resolves them against
+ * the Pi agent settings package inventory at run time.
+ */
+export const DAG_PI_EXTENSION_IDS = ["pi-codegraph", "pi-lens"];
+/**
+ * Alias table: one DAG short id may resolve to multiple published package
+ * names. The first settings spec whose de-`npm:`-prefixed package name is in
+ * the alias set wins (project settings override user settings).
+ */
+export const DAG_PI_EXTENSION_PACKAGE_ALIASES = {
+    "pi-codegraph": [
+        "@estebanforge/pi-codegraph-enhanced",
+        "@vndv/pi-codegraph",
+        "pi-codegraph",
+    ],
+    "pi-lens": ["pi-lens"],
+};
+/**
+ * Extension tools that must never be activated as extras on any node (D5):
+ * they mutate files without the writer path policy. Writer nodes keep only
+ * policy-wrapped edit/write; read nodes keep only navigation tools.
+ */
+export const DAG_PI_EXTENSION_WRITE_TOOL_DENY = new Set([
+    "ast_grep_replace",
+]);
+/** Builtin tool names extensions must never replace (D5). */
+export const DAG_PI_EXTENSION_PROTECTED_BUILTIN_TOOLS = new Set(["read", "edit", "write", "bash", "grep", "find", "ls"]);
+/** Deny surface extensions must never activate (D5). */
+export const DAG_PI_EXTENSION_DENIED_TOOL_IDS = new Set([
+    "apply_patch",
+    "apply-patch",
+    "full-tools",
+    "full_tools",
+    "coding-chat",
+    "coding_chat",
+    "shell",
+]);
+export function isDagPiExtensionId(value) {
+    return DAG_PI_EXTENSION_IDS.includes(value);
+}
+function getPiAgentDir() {
+    const envDir = process.env.PI_CODING_AGENT_DIR;
+    if (envDir)
+        return envDir;
+    return path.join(os.homedir(), ".pi", "agent");
+}
+function readSettingsPackages(settingsPath) {
+    try {
+        if (!existsSync(settingsPath))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+        if (!Array.isArray(parsed.packages))
+            return undefined;
+        return parsed.packages.filter((spec) => typeof spec === "string");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Strip an `npm:` prefix from a settings package spec, e.g. `npm:pi-lens`. */
+export function packageNameFromSpec(spec) {
+    return spec.startsWith("npm:") ? spec.slice(4) : spec;
+}
+function loadPackageInventories(repoRoot) {
+    const agentDir = getPiAgentDir();
+    const userSpecs = readSettingsPackages(path.join(agentDir, "settings.json"));
+    const projectSpecs = readSettingsPackages(path.join(repoRoot, ".pi", "settings.json"));
+    const inventories = [];
+    if (userSpecs) {
+        inventories.push({
+            specs: userSpecs,
+            nodeModulesRoot: path.join(agentDir, "npm", "node_modules"),
+        });
+    }
+    if (projectSpecs) {
+        inventories.push({
+            specs: projectSpecs,
+            nodeModulesRoot: path.join(repoRoot, "node_modules"),
+        });
+    }
+    return inventories;
+}
+const EXTENSION_FILE_RE = /\.(?:ts|js|mjs|cjs)$/;
+/**
+ * Resolve a package's `pi.extensions` entries to absolute entry paths.
+ * - A file entry maps to itself.
+ * - A directory entry expands to every extension file directly inside it
+ *   (e.g. `@estebanforge/pi-codegraph-enhanced` ships `./extensions` holding
+ *   `codegraph.ts`).
+ * No `pi.extensions` declaration, or a declaration whose paths do not exist,
+ * yields no entries (caller records `no-entry`) — no heuristic scanning
+ * outside declared paths.
+ */
+export function resolvePackageEntryPaths(packageDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    }
+    catch {
+        return { entryPaths: [], reason: "no-entry" };
+    }
+    const declared = manifest.pi?.extensions;
+    if (!Array.isArray(declared)) {
+        return { entryPaths: [], reason: "no-entry" };
+    }
+    const entryPaths = [];
+    for (const entry of declared) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        const resolved = path.resolve(packageDir, entry);
+        if (!existsSync(resolved))
+            continue;
+        let isDirectory = false;
+        try {
+            isDirectory = statSync(resolved).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDirectory) {
+            entryPaths.push(resolved);
+            continue;
+        }
+        let names;
+        try {
+            names = readdirSync(resolved);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (!EXTENSION_FILE_RE.test(name))
+                continue;
+            entryPaths.push(path.join(resolved, name));
+        }
+    }
+    if (entryPaths.length === 0) {
+        return { entryPaths: [], reason: "no-entry" };
+    }
+    return { entryPaths };
+}
+/**
+ * Resolve frozen DAG short ids against the Pi settings package inventory
+ * (user `~/.pi/agent/settings.json`, then project `.pi/settings.json` — a
+ * later match on the same alias wins). Pure synchronous read; never throws.
+ */
+export function resolveDagPiExtensions(input) {
+    const inventories = loadPackageInventories(input.repoRoot);
+    const resolved = [];
+    const missing = [];
+    for (const id of input.ids) {
+        if (!isDagPiExtensionId(id)) {
+            missing.push({
+                id,
+                reason: "package-unreadable",
+                detail: `unknown pi extension id: ${id}`,
+            });
+            continue;
+        }
+        const aliases = DAG_PI_EXTENSION_PACKAGE_ALIASES[id];
+        let matched;
+        // Later inventories (project) override earlier (user).
+        for (const inventory of inventories) {
+            for (const spec of inventory.specs) {
+                const packageName = packageNameFromSpec(spec);
+                if (!aliases.includes(packageName))
+                    continue;
+                const packageDir = path.join(inventory.nodeModulesRoot, ...packageName.split("/"));
+                if (!existsSync(packageDir))
+                    continue;
+                try {
+                    const manifest = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+                    if (typeof manifest.version !== "string")
+                        continue;
+                    matched = { packageDir, packageName, version: manifest.version };
+                }
+                catch {
+                    // unreadable manifest: skip this candidate
+                }
+            }
+        }
+        if (!matched) {
+            missing.push({ id, reason: "not-installed" });
+            continue;
+        }
+        const entries = resolvePackageEntryPaths(matched.packageDir);
+        if (entries.entryPaths.length === 0) {
+            missing.push({
+                id,
+                reason: entries.reason === "no-entry" ? "no-entry" : "package-unreadable",
+            });
+            continue;
+        }
+        resolved.push({
+            id,
+            packageName: matched.packageName,
+            version: matched.version,
+            entryPaths: entries.entryPaths,
+        });
+    }
+    return { resolved, missing };
+}
+/**
+ * Compute extension tool names that may join a node's active tool allowlist
+ * after session creation (D5): new tool names registered by the loaded
+ * extensions, minus protected builtins, the deny surface, and write-capable
+ * extension tools (both buckets — writer writes stay policy-wrapped only).
+ */
+export function computeExtensionToolAllowlistExtras(sessionTools, baseline) {
+    const baselineLower = new Set(baseline.map((name) => name.toLowerCase()));
+    const extras = [];
+    for (const tool of sessionTools) {
+        const name = tool && typeof tool.name === "string" ? tool.name : undefined;
+        if (!name)
+            continue;
+        const lower = name.toLowerCase();
+        if (baselineLower.has(lower))
+            continue;
+        if (DAG_PI_EXTENSION_PROTECTED_BUILTIN_TOOLS.has(lower))
+            continue;
+        if (DAG_PI_EXTENSION_DENIED_TOOL_IDS.has(lower))
+            continue;
+        if (DAG_PI_EXTENSION_WRITE_TOOL_DENY.has(lower))
+            continue;
+        extras.push(name);
+    }
+    return extras;
+}

package/dist/executors/pi-sdk-executor.js

@@ -1,5 +1,6 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { computeExtensionToolAllowlistExtras } from "./pi-extension-resolver.js";
 import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractPiEventStopReason, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
 import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
@@ -229,6 +230,9 @@ async function createSdkSession(sdk, input, shared) {
         noContextFiles: true,
         noSkills: true,
         noExtensions: true,
+        ...(input.additionalExtensionPaths && input.additionalExtensionPaths.length > 0
+            ? { additionalExtensionPaths: input.additionalExtensionPaths }
+            : {}),
         ...(settingsManager ? { settingsManager } : {}),
         appendSystemPromptOverride: (base) => [
             ...base,
@@ -236,6 +240,19 @@ async function createSdkSession(sdk, input, shared) {
         ],
     });
     await loader.reload();
+    // Discover extension-registered tool names BEFORE session creation (plan
+    // 2026-08-21 D5): verified against the real SDK — passing extension tool
+    // names in createAgentSession `tools` activates them, while a post-create
+    // setActiveToolsByName pin leaves the active set unchanged. Merge filtered
+    // extras into the create-time allowlist; protected builtins, the deny
+    // surface, and write-capable extension tools never join.
+    const extensionToolExtras = [];
+    if (input.additionalExtensionPaths &&
+        input.additionalExtensionPaths.length > 0) {
+        const registered = collectLoaderExtensionToolNames(loader);
+        extensionToolExtras.push(...computeExtensionToolAllowlistExtras(registered.map((name) => ({ name })), input.toolNames));
+    }
+    const sessionToolNames = [...input.toolNames, ...extensionToolExtras];
     if (input.requireWriterCustomTools) {
         if (!Array.isArray(input.customTools) || input.customTools.length === 0) {
             throw new Error("pi writer tool policy missing customTools; refusing to create uncontrolled writer session");
@@ -245,7 +262,7 @@ async function createSdkSession(sdk, input, shared) {
         cwd: input.cwd,
         sessionManager: SessionManager.inMemory(input.cwd),
         resourceLoader: loader,
-        tools: input.toolNames,
+        tools: sessionToolNames,
         modelRuntime,
         ...(settingsManager ? { settingsManager } : {}),
         ...(model ? { model } : {}),
@@ -254,6 +271,22 @@ async function createSdkSession(sdk, input, shared) {
             ? { customTools: input.customTools }
             : {}),
     });
+    if (extensionToolExtras.length > 0) {
+        // Fail closed when merged extension tools did not activate: a silent
+        // pin failure must never let the node run without its declared tools.
+        const activeTools = created.session.agent?.state?.tools;
+        if (!Array.isArray(activeTools)) {
+            throw new Error("pi SDK session does not expose agent.state.tools; refusing unverifiable extension-tool activation");
+        }
+        const activeNames = new Set(activeTools
+            .map((tool) => typeof tool?.name === "string" ? tool.name : undefined)
+            .filter((name) => Boolean(name)));
+        for (const extensionToolName of extensionToolExtras) {
+            if (!activeNames.has(extensionToolName)) {
+                throw new Error(`pi SDK extension-tool activation mismatch for ${extensionToolName}: tool did not activate at session creation`);
+            }
+        }
+    }
     const customToolNames = (input.customTools ?? [])
         .map((tool) => isRecord(tool) && typeof tool.name === "string" ? tool.name : undefined)
         .filter((name) => Boolean(name));
@@ -266,7 +299,7 @@ async function createSdkSession(sdk, input, shared) {
             .map((tool) => typeof tool?.name === "string" ? tool.name : undefined)
             .filter((name) => Boolean(name)));
         for (const customToolName of customToolNames) {
-            const expectedActive = input.toolNames.includes(customToolName);
+            const expectedActive = sessionToolNames.includes(customToolName);
             if (activeNames.has(customToolName) !== expectedActive) {
                 throw new Error(`pi SDK custom-tool activation mismatch for ${customToolName}: expectedActive=${expectedActive}`);
             }
@@ -274,6 +307,47 @@ async function createSdkSession(sdk, input, shared) {
     }
     return created.session;
 }
+/**
+ * Collect tool names registered by loader-resolved extensions. The SDK exposes
+ * each extension's `tools` as a Record (name → definition) or Map; both shapes
+ * are handled. Missing getExtensions (older SDK) yields no extras — the node
+ * then runs with the baseline allowlist only.
+ */
+function collectLoaderExtensionToolNames(loader) {
+    const getExtensions = loader?.getExtensions;
+    if (typeof getExtensions !== "function")
+        return [];
+    let parsed;
+    try {
+        parsed = getExtensions.call(loader);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const extensions = parsed.extensions;
+    if (!Array.isArray(extensions))
+        return [];
+    const names = [];
+    for (const extension of extensions) {
+        if (!extension || typeof extension !== "object")
+            continue;
+        const tools = extension.tools;
+        if (tools instanceof Map) {
+            for (const key of tools.keys()) {
+                if (typeof key === "string")
+                    names.push(key);
+            }
+        }
+        else if (tools && typeof tools === "object") {
+            for (const key of Object.keys(tools)) {
+                names.push(key);
+            }
+        }
+    }
+    return names;
+}
 /**
  * Throttle high-noise Pi SDK events from session-events.jsonl.
  * Always keeps tool lifecycle, turn/agent end, assistant messages, and errors.
@@ -545,6 +619,9 @@ export async function executeSingleSdkAttempt(options) {
                 ? { customTools: writerCustomTools }
                 : {}),
             ...(requireWriterCustomTools ? { requireWriterCustomTools: true } : {}),
+            ...(options.piExtensionPaths && options.piExtensionPaths.length > 0
+                ? { additionalExtensionPaths: options.piExtensionPaths }
+                : {}),
         });
         let resolveStall;
         let resolveSettlement;

package/dist/executors/shell-write-guard.js

@@ -98,6 +98,13 @@ export function isEphemeralToolCachePath(filePath) {
     const normalized = normalizePath(filePath);
     if (!normalized)
         return false;
+    // CodeGraph extension sync side effect (plan 2026-08-21 D7): a loaded
+    // pi-codegraph extension keeps an existing .codegraph/ index fresh at
+    // session start; those index files are extension-owned run state, not
+    // writer output, so they never count as write-guard violations.
+    if (normalized === ".codegraph" || normalized.startsWith(".codegraph/")) {
+        return true;
+    }
     if (normalized === ".pytest_cache" ||
         normalized.startsWith(".pytest_cache/")) {
         return true;

package/dist/worker/observe/node-input.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { resolveDagNodeSkills } from "../../workflows/dag/skills.js";
-import { resolveDagNodePromptRedacted, resolveDagRunJson, } from "./dag-run-artifacts.js";
+import { resolveDagNodePromptRedacted, resolveDagRunArtifact, resolveDagRunJson, } from "./dag-run-artifacts.js";
 export const NODE_INPUT_SCHEMA_VERSION = 1;
 export const NODE_INPUT_PREVIEW_MAX_BYTES = 64 * 1024;
 const SHELL_GATE_KEYS = [
@@ -33,6 +33,7 @@ function unavailableBody(dagRunId, nodeId, reason, warnings = []) {
         executorInput: null,
         boundaries: null,
         promptFingerprint: null,
+        piExtensionRunFacts: null,
         warnings,
     };
 }
@@ -137,7 +138,7 @@ function resolveModelHint(spec, task) {
     }
     return null;
 }
-function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warnings) {
+function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, piExtensionRunFacts, warnings) {
     const defaults = spec.defaults && typeof spec.defaults === "object"
         ? spec.defaults
         : undefined;
@@ -268,6 +269,7 @@ function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warni
             kind,
             skills,
             modelHint: resolveModelHint(spec, task),
+            piExtensions: redactStringList(task.piExtensions),
             shell,
             static: staticBlock,
         },
@@ -284,9 +286,72 @@ function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warni
                 : null,
         },
         promptFingerprint: fingerprint,
+        piExtensionRunFacts,
         warnings,
     };
 }
+/**
+ * Load run-time Pi extension facts from <node>/pi-extensions.json (plan
+ * 2026-08-22 R2). Returns null when the node declares no piExtensions
+ * (no expected artifact). Never throws: unreadable/corrupt artifacts degrade
+ * to parseError stubs so the node-input endpoint stays 200.
+ */
+async function loadPiExtensionRunFacts(repoRoot, dagRunId, nodeId, declared, warnings) {
+    if (declared.length === 0)
+        return null;
+    const artifact = path.posix.join(nodeId, "pi-extensions.json");
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, [
+        nodeId,
+        "pi-extensions.json",
+    ]);
+    if (!resolved.ok) {
+        if (resolved.reason === "ambiguous") {
+            warnings.push("Ambiguous pi-extensions.json lifecycle copies.");
+        }
+        return {
+            artifact,
+            exists: false,
+            requested: [...declared],
+            resolved: [],
+            missing: [],
+        };
+    }
+    const empty = {
+        artifact,
+        exists: false,
+        requested: [...declared],
+        resolved: [],
+        missing: [],
+    };
+    try {
+        const raw = JSON.parse(await readFile(resolved.result.absolutePath, "utf-8"));
+        const resolvedList = Array.isArray(raw.resolved) ? raw.resolved : [];
+        const missingList = Array.isArray(raw.missing) ? raw.missing : [];
+        const projected = resolvedList
+            .filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry))
+            .map((entry) => ({
+            id: redactSecrets(String(entry.id ?? "")),
+            packageName: redactSecrets(String(entry.packageName ?? "")),
+            version: redactSecrets(String(entry.version ?? "")),
+        }));
+        const missingProjected = missingList
+            .filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry))
+            .map((entry) => ({
+            id: redactSecrets(String(entry.id ?? "")),
+            reason: redactSecrets(String(entry.reason ?? "")),
+        }));
+        return {
+            artifact,
+            exists: true,
+            requested: redactStringList(raw.requested ?? declared),
+            resolved: projected,
+            missing: missingProjected,
+        };
+    }
+    catch {
+        return { ...empty, parseError: "read-failed" };
+    }
+}
 async function loadPromptFingerprint(repoRoot, dagRunId, nodeId, warnings) {
     const resolved = resolveDagNodePromptRedacted(repoRoot, dagRunId, nodeId);
     if (!resolved.ok) {
@@ -415,8 +480,12 @@ export async function buildDagNodeInput(repoRoot, dagRunId, nodeId) {
     }
     const warnings = [];
     const fingerprint = await loadPromptFingerprint(repoRoot, dagRunId, nodeId, warnings);
+    const declaredPiExtensions = Array.isArray(task.piExtensions)
+        ? task.piExtensions.filter((item) => typeof item === "string")
+        : [];
+    const piExtensionRunFacts = await loadPiExtensionRunFacts(repoRoot, dagRunId, nodeId, declaredPiExtensions, warnings);
     // Reject unknown nested leakage by projecting only through allowlist helpers.
-    const body = projectTask(dagRunId, nodeId, runResolved.result.lifecycle, spec, task, fingerprint, warnings);
+    const body = projectTask(dagRunId, nodeId, runResolved.result.lifecycle, spec, task, fingerprint, piExtensionRunFacts, warnings);
     // Defense-in-depth: ensure raw task never sneaks in.
     if ("task" in body) {
         return {

package/dist/worker/observe/static/dag-history-labels.js

@@ -14,6 +14,10 @@ const ATTEMPT_FAILURE_LABELS = {
 	timeout: "执行超时",
 	"nonzero-exit": "命令执行失败",
 	"invalid-output": "输出格式无效",
+	"structured-output-truncated": "结构化输出被截断",
+	"output-too-large": "输出超出体积上限",
+	"structured-repair-exhausted": "结构化修复耗尽",
+	"governance-blocked": "治理规则阻断",
 	"empty-output": "输出为空",
 	auth: "认证失败",
 	quota: "额度或限流",