@tea-agent/loop-agent 0.38.2 → 0.38.3

package/CHANGELOG.md

@@ -4,10 +4,21 @@
 
 ### 变更
 
+- `next-release.yml` 防重复发布守卫补充幂等语义：`mode=recover`（dist-tags.next 已指向出自本 HEAD 的 tarball）时，手动 `workflow_dispatch` 重入不再撞 duplicate publish 硬失败，改为写 summary 后干净退出（§5.1 规则 4）；非 recover 的重复发布仍硬失败。
+
+- 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 附近报错且不关闭抽屉
 - backend-test 适配 A–D：可配置 `backendTest` 布局（`testRoot`/`markdownRel`/`scriptRel`）、用户公共前置文档引用与模块顶部 `user_shared_setup`（不写 conftest）、查询轴 Scenario Partitions 确定性展开与 fail-closed 门禁、`mode=gap-fill` 13 节点增量 DAG。Slot ID 以声明的 Partition ID 为真源（`TP-<Partition ID>-...`）。
 - 前端 plan 唯一机器契约化（JSON-only）：`frontend-plan-pi` / `frontend-plan-revision-pi` 输出收敛为「一行导语 + 唯一 fenced `json` 契约 + 唯一 `openspec-citations` 引用块」，彻底移除「可选 Markdown 说明」；plan.md（`contracts/frontend-plan.md`）改由 prewrite gate 用纯函数 `renderFrontendPlanMarkdown` 确定性渲染（不新增 DAG 节点/不新增 Pi 调用）
 - 契约 schema 新增 5 个可选字段（`implementationSteps` / `stylingStrategy` / `dependencyPolicy` / `residualRisks` / `realIntegrationGap`），`schemaVersion` 保持 1；`docs/templates/frontend-implementation-contract.schema.json` 同步
@@ -28,6 +39,13 @@
 
 ### 改进
 
+- 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 出现空步骤。
+- `dag rerun --from-node` 把尚未启动的 writer/map 视为首次执行；frontend-test probe 这种失败的 exclusive shell 可以带着下游未跑节点续跑，不必整图 `standaloneTaskRerun`。
+- Pi SDK 节点在 stall watchdog（默认 15 分钟无 provider 活动）触发后，会先 abort 当前等待，并在同一会话自动发送一次「继续」；仅 abort 已确认且尚未调用 write 工具时恢复，失败仍判 timeout。绝对墙钟超时与 CLI 后端不走这条恢复。
+- DAG 节点检查器「执行过程」时间线默认展开原始协议事件（`message_start` / `message_end`），按钮文案为「隐藏原始协议事件」；用户可点选关闭，同会话内选择会保持。
 - Operator Chat 的乐观停止现在把“视觉已停止”和 Turn ownership 分开：Abort 获得可靠终态前明确显示“正在停止”，此时可为原会话保存一条服务端持久化的“停止后发送”消息；后一次覆盖前一次，切换会话、刷新页面或 Console 重启不会丢失，旧 Turn 结束后复用正常 Turn 准入路径自动发送，并以固定 `clientRequestId` 防止重复执行。
 - Operator Chat 修复快速终止时“停止后发送”与普通发送之间的准入空洞：发送路径改读实时 ownership；若 deferred 请求恰好撞上旧 Turn 终态，会先按服务端状态对账，再使用同一 `clientRequestId` 自动转为普通发送，不再要求用户刷新重试或丢失本次提交。
 - `dag rerun-task` 现在会把父 run 最后一轮仍未解决的 `verify-pi` / review 反馈、证据引用和修订轮次带入新完整 DAG；planner、implementer 与 verifier/reviewer 必须修复或举证说明不再适用，不能仅因文件已存在就返回 `already-satisfied`。Console 同步区分「自动修订」「从失败节点恢复」「带反馈重新执行任务」。

package/README.md

@@ -24,6 +24,8 @@
 
 ### 安装
 
+需要 Node.js `>=22.19.0`。建议先运行 `node --version` 确认环境满足要求；启用 npm `engine-strict` 时，旧版本 Node.js 会直接拒绝安装。
+
 ```bash
 npm install -g @tea-agent/loop-agent@latest
 loop-agent --version

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/application/task-lifecycle/advance.js

@@ -38,6 +38,7 @@ function hasEngineeringBoundary(input) {
     return Boolean((input.allowedPaths && input.allowedPaths.length > 0) ||
         (input.forbiddenPaths && input.forbiddenPaths.length > 0) ||
         (input.verifyCommands && input.verifyCommands.length > 0) ||
+        input.backendTest !== undefined ||
         input.fromText ||
         input.fromDraftPath);
 }
@@ -632,6 +633,7 @@ export async function advanceTaskLifecycle(input) {
                     allowedPaths: effectiveInput.allowedPaths,
                     forbiddenPaths: input.forbiddenPaths,
                     verifyCommands: effectiveInput.verifyCommands,
+                    backendTest: input.backendTest,
                 },
             });
             if (!prepareResult.ok) {
@@ -687,6 +689,7 @@ export async function advanceTaskLifecycle(input) {
                                 allowedPaths: effectiveInput.allowedPaths,
                                 forbiddenPaths: input.forbiddenPaths,
                                 verifyCommands: effectiveInput.verifyCommands,
+                                backendTest: input.backendTest,
                             },
                         });
                         if (semantic.ok) {
@@ -707,6 +710,7 @@ export async function advanceTaskLifecycle(input) {
                                     allowedPaths: effectiveInput.allowedPaths,
                                     forbiddenPaths: input.forbiddenPaths,
                                     verifyCommands: effectiveInput.verifyCommands,
+                                    backendTest: input.backendTest,
                                 },
                             });
                             if (retry.ok) {

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.38.2",
-  "gitSha": "ba66152b71609e67330471e5325c1efddd200412",
-  "builtAt": "2026-08-20T07:31:23.829Z"
+  "version": "0.38.3",
+  "gitSha": "228da3eaaf3c1a2082af7b5c15aa2e4653afb3ce",
+  "builtAt": "2026-08-22T02:44:24.204Z"
 }

package/dist/commands/task-advance.js

@@ -1,4 +1,5 @@
 import { advanceTaskLifecycle, } from "../application/task-lifecycle/index.js";
+import { backendTestConfigSchema, } from "../task/config-types.js";
 import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
 import { createRunDagProgressObserver, validateRunDagProgressIntervalMs, } from "./run-dag-progress.js";
 const COMMAND = "task advance";
@@ -14,6 +15,7 @@ const USAGE = `usage:
     [--forbidden-path <glob>]...
     [--verify <label:command>]...
     [--verify-timeout <label:timeoutMs>]...
+    [--backend-test <json>]
     [--accept-recommendations <digest>]
     [--approve-gate <gate-id:digest>]
     [--reject-gate <gate-id:digest> --reason <text>]
@@ -52,6 +54,30 @@ function parseVerifyTimeout(flag) {
     }
     return { label: flag.slice(0, idx), timeoutMs };
 }
+/**
+ * Parse `--backend-test <json>` into a validated managed backendTest config.
+ * `{}` is legal (explicit clear back to the default layout).
+ */
+function parseBackendTestFlag(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`invalid --backend-test ${raw}; expected an inline JSON object`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`invalid --backend-test ${raw}; expected an inline JSON object`);
+    }
+    const result = backendTestConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const summary = result.error.issues
+            .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+            .join("; ");
+        throw new Error(`invalid --backend-test: ${summary}`);
+    }
+    return result.data ?? {};
+}
 export function parseTaskAdvanceArgs(args) {
     const options = {};
     const positional = [];
@@ -113,6 +139,10 @@ export function parseTaskAdvanceArgs(args) {
             options.verifyTimeout = pushList(options.verifyTimeout, next());
             continue;
         }
+        if (token === "--backend-test") {
+            options.backendTest = parseBackendTestFlag(next());
+            continue;
+        }
         if (token === "--accept-recommendations") {
             options.acceptRecommendations = next();
             continue;
@@ -273,6 +303,7 @@ export function toUseCaseInput(repoRoot, taskId, options, observer) {
         allowedPaths: options.allowedPaths,
         forbiddenPaths: options.forbiddenPaths,
         verifyCommands: verifyCommands.length > 0 ? verifyCommands : undefined,
+        backendTest: options.backendTest,
         approveGateToken: options.approveGate,
         rejectGateToken: options.rejectGate,
         rejectReason: options.reason,

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-event-serializer.js

@@ -51,9 +51,50 @@ export function normalizePiSessionEvent(event) {
     }
     return unifyToolPayloadFields(event);
 }
+const TERMINAL_FINISH_REASON_TYPES = new Set([
+    'message_end',
+    'turn_end',
+    'assistant_message',
+]);
+function readExplicitFinishReason(source) {
+    const message = isRecord(source.message) ? source.message : undefined;
+    const candidates = [
+        source.finish_reason,
+        source.finishReason,
+        source.stop_reason,
+        source.stopReason,
+        message?.finish_reason,
+        message?.finishReason,
+        message?.stop_reason,
+        message?.stopReason,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function applyFinishReason(original, normalized) {
+    const originalType = typeof original.type === 'string' ? original.type : undefined;
+    if (!originalType || !TERMINAL_FINISH_REASON_TYPES.has(originalType)) {
+        return normalized;
+    }
+    const existing = readExplicitFinishReason({
+        finish_reason: normalized.finish_reason,
+    });
+    if (existing !== undefined) {
+        return normalized;
+    }
+    const promoted = readExplicitFinishReason(original);
+    if (promoted === undefined) {
+        return normalized;
+    }
+    return { ...normalized, finish_reason: promoted };
+}
 /** Serialize one SDK session event as a single JSONL line. */
 export function serializeSessionEvent(event, options) {
-    const normalized = normalizePiSessionEvent(event);
+    const normalized = applyFinishReason(event, normalizePiSessionEvent(event));
     if (typeof normalized.recordedAt !== 'string') {
         normalized.recordedAt = options?.recordedAt ?? new Date().toISOString();
     }

package/dist/executors/pi-executor.js

@@ -408,6 +408,50 @@ export class BoundedTextPreview {
         ].join("\n");
     }
 }
+/**
+ * Normalize provider-specific completion-limit labels to the DAG's canonical
+ * `length` signal. Other terminal reasons remain observable without being
+ * treated as truncation.
+ */
+export function normalizeProviderStopReason(value) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return undefined;
+    const trimmed = value.trim();
+    const compact = trimmed.toLowerCase().replace(/[\s_-]/g, "");
+    if ([
+        "length",
+        "maxtokens",
+        "maxoutputtokens",
+        "outputlimit",
+        "tokenlimit",
+        "tokenlimitreached",
+    ].includes(compact)) {
+        return "length";
+    }
+    return trimmed;
+}
+/**
+ * Extract a terminal stop reason from the provider event shapes used by Pi
+ * SDK/CLI bridges. Providers disagree on `stop*` versus `finish*`; keep this
+ * boundary centralized so downstream DAG recovery sees one canonical signal.
+ */
+export function extractPiEventStopReason(event) {
+    const nested = [event.message, event.response, event.completion].filter(isRecord);
+    const containers = [...nested, event];
+    for (const container of containers) {
+        for (const key of [
+            "stopReason",
+            "stop_reason",
+            "finishReason",
+            "finish_reason",
+        ]) {
+            const normalized = normalizeProviderStopReason(container[key]);
+            if (normalized)
+                return normalized;
+        }
+    }
+    return undefined;
+}
 export class PiJsonlStreamCollector {
     lineBuffer = "";
     discardUntilNewline = false;
@@ -415,6 +459,7 @@ export class PiJsonlStreamCollector {
     parsedEvents = 0;
     tokensUsed = 0;
     outputTooLarge = false;
+    stopReason;
     subagentTotalCalls = 0;
     subagentFailedCalls = 0;
     subagentModes = new Set();
@@ -454,6 +499,7 @@ export class PiJsonlStreamCollector {
             assistantText: this.assistantText.trim(),
             outputTooLarge: this.outputTooLarge,
             parsedEvents: this.parsedEvents,
+            stopReason: this.stopReason,
             subagentStats: this.formatSubagentStats(),
             tokensUsed: this.tokensUsed,
         };
@@ -472,6 +518,10 @@ export class PiJsonlStreamCollector {
         }
     }
     consumeEvent(event) {
+        const stopReason = extractPiEventStopReason(event);
+        if (stopReason === "length" || !this.stopReason) {
+            this.stopReason = stopReason ?? this.stopReason;
+        }
         const candidate = extractAssistantTextFromEvent(event);
         if (candidate !== undefined) {
             if (candidate.length > MAX_ASSISTANT_TEXT_CHARS) {
@@ -865,6 +915,7 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
                 stdoutTruncated: stdoutPreview.truncated,
                 stderrTruncated: stderrPreview.truncated,
                 outputTooLarge: collected.outputTooLarge,
+                stopReason: collected.stopReason,
                 timedOut,
                 tokensUsed: collected.tokensUsed,
                 subagentStats: collected.subagentStats,

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;
+}