@tea-agent/loop-agent 0.39.0-next.9 → 0.39.0

package/dist/commands/inspect-next.js

@@ -0,0 +1,8 @@
+import { collectNextInfo, formatNextInfo, } from "../../scripts/next-info.mjs";
+export async function runInspectNext(repoRoot, args = []) {
+    const json = args.includes("--json");
+    const result = collectNextInfo({ cwd: repoRoot });
+    process.stdout.write(formatNextInfo(result, { json }));
+    if (!result.ok)
+        process.exitCode = result.exitCode || 1;
+}

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,14 +2,17 @@ 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";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
-import { isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
+import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
+import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 /**
  * Writer classification for a length-stopped thinking-only attempt: the model
@@ -326,6 +329,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"));
@@ -480,10 +513,11 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         throw new Error(`unknown command capability: ${capability}`);
                     }
                     if (capability === "playwright-cli") {
-                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet) ??
+                        const layout = frontendTestLayoutFromSpec(meta.spec);
+                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet, layout) ??
                             input.task.id;
-                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet) ??
-                            `testcase/frontend/evidence/${caseId}`;
+                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet, layout) ??
+                            `${layout.evidenceDir}/${caseId}`;
                         playwrightToolContext = {
                             repoRoot: input.cwd,
                             runDir: meta.runDir,
@@ -491,7 +525,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                             caseId,
                             evidenceDir,
                             baseUrl: await resolveValidatedFrontendBaseUrlFromContext(input.cwd, meta.runDir),
-                            inputRoot: "testcase/frontend/fixtures",
+                            inputRoot: layout.fixturesDir,
+                            layout,
                         };
                         // Cleanup must be confirmed before a new case; otherwise default-session
                         // isolation is unknown and no Pi invocation is permitted.
@@ -549,6 +584,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),
@@ -563,6 +621,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" ||
@@ -808,6 +869,13 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         isBackendTestCompletenessRetryCandidate(input.task)) {
         try {
             const writerRole = backendTestWriterProgressRoleForTask(input.task.id);
+            const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+                ? {
+                    testRoot: meta.spec.backendTestLayout.testRoot,
+                    markdownRel: meta.spec.backendTestLayout.markdownRel,
+                    scriptRel: meta.spec.backendTestLayout.scriptRel,
+                }
+                : undefined);
             const progress = isBackendTestShardChildTask(input.task)
                 ? await assessBackendTestShardChildCompleteness({
                     workspaceRoot: input.cwd,
@@ -815,12 +883,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     writeSet: input.task.writeSet ?? [],
                 })
                 : isBackendTestMdPlanTask(input.task)
-                    ? await assessBackendTestMdPlanCompleteness(input.cwd)
+                    ? await assessBackendTestMdPlanCompleteness(input.cwd, backendLayout)
                     : isBackendTestPytestPlanTask(input.task)
-                        ? await assessBackendTestPytestPlanCompleteness(input.cwd)
+                        ? await assessBackendTestPytestPlanCompleteness(input.cwd, backendLayout)
                         : writerRole === "pytest-generate"
-                            ? await assessBackendTestPytestWriterCompleteness(input.cwd)
-                            : await assessBackendTestMdWriterCompleteness(input.cwd);
+                            ? await assessBackendTestPytestWriterCompleteness(input.cwd, backendLayout)
+                            : await assessBackendTestMdWriterCompleteness(input.cwd, backendLayout);
             await writeBackendTestWriterProgressArtifacts({
                 runDir: meta.runDir,
                 progress,
@@ -877,22 +945,31 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (meta.writeGuardAttribution === "best-effort") {
         stderrParts.push("write guard note: concurrent rank writers use best-effort per-node attribution; keep same-rank writeSet entries disjoint");
     }
-    // Pure provider stall/timeout with zero workspace side effects is eligible
-    // for a single writer transport retry (implement-pi flake resilience).
-    // Partial writes, tool calls, or write-guard failures keep raw `timeout`.
-    const writerCleanTimeout = !mapped.ok &&
-        mapped.failureCategory === "timeout" &&
-        writeGuardOk &&
+    const rawFailureCategory = mapped.failureCategory;
+    const writeToolCallCount = readWriterThinkingExhaustionEvidence(result).writeToolCallCount;
+    const zeroSideEffects = writeGuardOk &&
         !completenessFailure &&
         !writerThinkingExhausted &&
-        isWriterTransportRetryCandidate(input.task) &&
+        !writerOutcomeViolation &&
         changeManifestChangedFiles !== undefined &&
         changeManifestChangedFiles.length === 0 &&
-        readWriterThinkingExhaustionEvidence(result).writeToolCallCount === 0;
+        writeToolCallCount === 0;
+    const targetCleanTransport = !mapped.ok &&
+        isTargetTemplateTransientRetryNode(input.task) &&
+        rawFailureCategory !== undefined &&
+        ["timeout", "network", "rate-limit", "unavailable"].includes(rawFailureCategory) &&
+        zeroSideEffects;
+    const frontendCleanTimeout = !mapped.ok &&
+        rawFailureCategory === "timeout" &&
+        isWriterTransportRetryCandidate(input.task) &&
+        !isTargetTemplateTransientRetryNode(input.task) &&
+        zeroSideEffects;
+    const writerCleanTimeout = targetCleanTransport || frontendCleanTimeout;
     return {
         ...mapped,
         ok: false,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
+        ...(rawFailureCategory ? { rawFailureCategory } : {}),
         failureCategory: mapped.ok
             ? writeGuardOk
                 ? completenessFailure
@@ -977,6 +1054,15 @@ function parseWriterImplementationOutcome(text) {
     const lines = text.split(/\r?\n/);
     const candidates = [];
     for (const [lineIndex, line] of lines.entries()) {
+        const localizedOutcome = localizedWriterImplementationOutcome(line);
+        if (localizedOutcome) {
+            candidates.push({
+                lineIndex,
+                value: localizedOutcome,
+                outcome: localizedOutcome,
+            });
+            continue;
+        }
         const nextLine = lines[lineIndex + 1];
         const normalized = normalizeProtocolLine(line, WRITER_OUTCOME_PROTOCOL_LINE, nextLine);
         if (normalized === undefined)
@@ -1005,6 +1091,26 @@ function parseWriterImplementationOutcome(text) {
         candidates,
     };
 }
+function localizedWriterImplementationOutcome(line) {
+    const normalized = normalizedProtocolValue(line);
+    const match = /^(?:实现|实施)结果\s*[:：]\s*(已变更|已更改|已修改|已满足|无需变更|已阻塞|阻塞)$/u.exec(normalized);
+    if (!match)
+        return undefined;
+    switch (match[1]) {
+        case "已变更":
+        case "已更改":
+        case "已修改":
+            return "changed";
+        case "已满足":
+        case "无需变更":
+            return "already-satisfied";
+        case "已阻塞":
+        case "阻塞":
+            return "blocked";
+        default:
+            return undefined;
+    }
+}
 function isWriterImplementationOutcome(value) {
     return (value === "changed" || value === "already-satisfied" || value === "blocked");
 }

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