@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/book-topology-runs-migrator.js

@@ -0,0 +1,272 @@
+/**
+ * #865 T9: migrate retained runs into ticket-scoped or unbound placement.
+ * Inventory covers legacy flat `runs/`, existing `<ticket>/runs/`, and
+ * `unbound/runs/`. Attribution reuses the shared migrating-run helper;
+ * already-canonical ticket trees copy as-is. Unbound leaves that already
+ * hold a board typed ticketNumber place under that ticket (#863 stock).
+ */
+import { cp, mkdir, rename, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { destinationRunDirectory, isTicketNumberString, listBackupRunLeaves, listMigrationBookKeys, resolveMigratingRunTicket, } from "./book-topology-migration-placement.js";
+import { reconcileMigrationPartition, } from "./book-topology-migration.js";
+import { listBookRunDirectories } from "./role-run-placement.js";
+import { rewriteRoleRunDurablePages, } from "./role-run-relocation.js";
+import { renderCurrentSync } from "./run-dossier.js";
+import { MIGRATION_TICKET_DERIVATION_PAGE, readMigrationBoardTicketNumber, } from "./run-ticket-number.js";
+import { isEnoent } from "./unknown-value.js";
+const RUNS_PARTITION = "runs";
+const RUN_LEAF = /^([A-Za-z0-9][A-Za-z0-9._-]*)@([A-Za-z][A-Za-z0-9_-]*)$/;
+function parseRunLeaf(name) {
+    const match = RUN_LEAF.exec(name);
+    if (match === null)
+        return undefined;
+    return { runId: match[1], role: match[2] };
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return false;
+        throw error;
+    }
+}
+async function writeDerivationPage(targetRunDirectory, derivation) {
+    const page = {
+        ticketNumber: derivation.ticketNumber,
+        derivation: "worktree-path-basename",
+        source: {
+            page: derivation.sourcePage,
+            field: "projectRoot",
+            path: derivation.projectRoot,
+            basename: basename(derivation.projectRoot),
+        },
+    };
+    await writeFile(join(targetRunDirectory, MIGRATION_TICKET_DERIVATION_PAGE), `${JSON.stringify(page, null, 2)}\n`, "utf8");
+}
+async function copyRunTree(source, target, isDirectory) {
+    await mkdir(dirname(target), { recursive: true });
+    if (isDirectory) {
+        await cp(source, target, { recursive: true, preserveTimestamps: true });
+        return;
+    }
+    await cp(source, target, { preserveTimestamps: true });
+}
+async function planBookMoves(backupBooksDirectory, booksDirectory, bookKey) {
+    const backupBook = join(backupBooksDirectory, bookKey);
+    const claimed = new Map();
+    const planned = [];
+    for (const leaf of await listBackupRunLeaves(backupBook)) {
+        const sourceIdentity = relative(backupBooksDirectory, leaf.sourcePath)
+            .split(sep)
+            .join("/");
+        const parsed = leaf.isDirectory ? parseRunLeaf(leaf.leafName) : undefined;
+        let targetPath;
+        let disposition;
+        let historicalRunDirectory;
+        let derivation;
+        if (leaf.layout === "issues") {
+            // issues/<ticket>/runs/<leaf> → <ticket>/runs/<leaf>; conflict refuses below.
+            const parts = leaf.relativePath.replaceAll("\\", "/").split("/");
+            const ticketStr = parts[1];
+            if (ticketStr !== undefined && isTicketNumberString(ticketStr)) {
+                targetPath = join(booksDirectory, bookKey, ticketStr, "runs", leaf.leafName);
+                disposition = "placed";
+                historicalRunDirectory = join(booksDirectory, bookKey, "issues", ticketStr, "runs", leaf.leafName);
+            }
+            else {
+                targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+                disposition = "unbound";
+                historicalRunDirectory = join(booksDirectory, bookKey, leaf.relativePath);
+            }
+            derivation = undefined;
+        }
+        else if (leaf.layout === "unbound") {
+            // #863: board typed ticket on an unbound leaf → place under that ticket.
+            // No board ticket → stay unbound. Never invent from prose or derivation.
+            const boardTicket = leaf.isDirectory
+                ? await readMigrationBoardTicketNumber(leaf.sourcePath)
+                : undefined;
+            if (parsed !== undefined && boardTicket !== undefined) {
+                targetPath = destinationRunDirectory(booksDirectory, bookKey, boardTicket, parsed.runId, parsed.role);
+                disposition = "placed";
+                historicalRunDirectory = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+            }
+            else {
+                targetPath = join(booksDirectory, bookKey, leaf.relativePath);
+                disposition = "unbound";
+                historicalRunDirectory = undefined;
+            }
+            derivation = undefined;
+        }
+        else if (leaf.layout !== "flat") {
+            // Already-canonical `<ticket>/runs/` — copy as-is.
+            targetPath = join(booksDirectory, bookKey, leaf.relativePath);
+            disposition = "placed";
+            historicalRunDirectory = undefined;
+            derivation = undefined;
+        }
+        else if (parsed === undefined) {
+            targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+            disposition = "unbound";
+            historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+            derivation = undefined;
+        }
+        else {
+            const ticket = await resolveMigratingRunTicket(leaf.sourcePath);
+            targetPath = destinationRunDirectory(booksDirectory, bookKey, ticket.ticketNumber, parsed.runId, parsed.role);
+            disposition = ticket.ticketNumber === undefined ? "unbound" : "placed";
+            historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+            derivation =
+                ticket.derivation?.method === "project-root-basename"
+                    && ticket.ticketNumber !== undefined
+                    ? {
+                        ticketNumber: ticket.ticketNumber,
+                        projectRoot: ticket.derivation.source,
+                        sourcePage: ticket.derivation.sourcePage,
+                    }
+                    : undefined;
+        }
+        const prior = claimed.get(targetPath);
+        if (prior !== undefined) {
+            throw new Error(`book topology migration refuses to overwrite ${targetPath} (already claimed by ${prior}) with ${leaf.sourcePath}`);
+        }
+        claimed.set(targetPath, leaf.sourcePath);
+        planned.push({
+            sourcePath: leaf.sourcePath,
+            sourceIdentity,
+            isDirectory: leaf.isDirectory,
+            disposition,
+            targetPath,
+            historicalRunDirectory,
+            derivation,
+        });
+    }
+    return planned;
+}
+export const bookTopologyRunsMigrator = {
+    partition: RUNS_PARTITION,
+    async migrate(context) {
+        const outcomes = [];
+        const { backupBooksDirectory, booksDirectory } = context;
+        for (const bookKey of await listMigrationBookKeys(backupBooksDirectory)) {
+            const planned = await planBookMoves(backupBooksDirectory, booksDirectory, bookKey);
+            const crossRunRewrites = planned
+                .filter((move) => move.isDirectory && move.historicalRunDirectory !== undefined)
+                .map((move) => ({
+                oldRunDirectory: move.historicalRunDirectory,
+                newRunDirectory: move.targetPath,
+            }));
+            for (const move of planned) {
+                if (await pathExists(move.targetPath)) {
+                    throw new Error(`book topology migration refuses to overwrite ${move.targetPath} with ${move.sourcePath}`);
+                }
+                await copyRunTree(move.sourcePath, move.targetPath, move.isDirectory);
+                if (move.isDirectory) {
+                    await rewriteRoleRunDurablePages({
+                        pagesDirectory: move.targetPath,
+                        oldRunDirectory: move.historicalRunDirectory ?? move.targetPath,
+                        newRunDirectory: move.targetPath,
+                        crossRunRewrites,
+                    });
+                }
+                if (move.isDirectory && move.derivation !== undefined) {
+                    await writeDerivationPage(move.targetPath, move.derivation);
+                }
+                outcomes.push({
+                    disposition: move.disposition,
+                    source: move.sourceIdentity,
+                });
+            }
+        }
+        return reconcileMigrationPartition(RUNS_PARTITION, "entries", outcomes);
+    },
+};
+/**
+ * Live in-place repair for already-migrated trees (#863 stock): plan the full
+ * board-bound unbound→ticket batch first, refuse any overwrite before mutation,
+ * rewrite durable pages (including batch `crossRunRewrites`) while sources still
+ * sit at unbound, then rename. Parse/write failures therefore leave sources in
+ * place so a retry can finish the same closure; rename-only retries still find
+ * remaining unbound sources. Leaves without a board ticket stay unbound.
+ */
+export async function relocateBoardBoundUnboundRunsInBook(bookDirectory) {
+    const bookKey = basename(bookDirectory);
+    const booksDirectory = dirname(bookDirectory);
+    const unboundRuns = join(bookDirectory, "unbound", "runs");
+    let entries;
+    try {
+        entries = await readdir(unboundRuns, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+    const planned = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const parsed = parseRunLeaf(entry.name);
+        if (parsed === undefined)
+            continue;
+        const sourcePath = join(unboundRuns, entry.name);
+        const boardTicket = await readMigrationBoardTicketNumber(sourcePath);
+        if (boardTicket === undefined)
+            continue;
+        const targetPath = destinationRunDirectory(booksDirectory, bookKey, boardTicket, parsed.runId, parsed.role);
+        planned.push({
+            sourcePath,
+            targetPath,
+            ticketNumber: boardTicket,
+        });
+    }
+    if (planned.length === 0)
+        return [];
+    for (const move of planned) {
+        if (await pathExists(move.targetPath)) {
+            throw new Error(`board-bound unbound relocate refuses to overwrite ${move.targetPath} with ${move.sourcePath}`);
+        }
+    }
+    const crossRunRewrites = planned.map((move) => ({
+        oldRunDirectory: move.sourcePath,
+        newRunDirectory: move.targetPath,
+    }));
+    const relocatedBySource = new Map(planned.map((move) => [move.sourcePath, move]));
+    // Rewrite before any rename so durable-page failures remain retryable from
+    // the same unbound sources (failure-honesty: no relocatedCount=0 whitewash).
+    for (const runDir of await listBookRunDirectories(bookDirectory)) {
+        const move = relocatedBySource.get(runDir);
+        await rewriteRoleRunDurablePages({
+            pagesDirectory: runDir,
+            oldRunDirectory: move?.sourcePath ?? runDir,
+            newRunDirectory: move?.targetPath ?? runDir,
+            crossRunRewrites,
+        });
+    }
+    for (const move of planned) {
+        await mkdir(dirname(move.targetPath), { recursive: true });
+        await rename(move.sourcePath, move.targetPath);
+        // Same live relocate seam: derived host.original follows the new run directory.
+        renderCurrentSync(move.targetPath);
+    }
+    return planned.map((move) => ({
+        from: move.sourcePath,
+        to: move.targetPath,
+        ticketNumber: move.ticketNumber,
+    }));
+}
+/**
+ * Walk every book under `booksDirectory` and relocate board-bound unbound
+ * runs in place without the whole-books topology migration's in-flight gate.
+ */
+export async function relocateBoardBoundUnboundRunsInBooks(booksDirectory) {
+    const relocated = [];
+    for (const bookKey of await listMigrationBookKeys(booksDirectory)) {
+        const batch = await relocateBoardBoundUnboundRunsInBook(join(booksDirectory, bookKey));
+        relocated.push(...batch);
+    }
+    return relocated;
+}

package/dist/collector-role.js

@@ -0,0 +1,109 @@
+import { registerFiledSubmissionTool } from "./filed-submission.js";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.js";
+import { parseCollectorPrNumber, parseCollectorRepository, } from "./collector-config.js";
+import { COLLECTOR_OUTPUT_TOOL, } from "./package-contracts/collector-output.js";
+export { COLLECTOR_OUTPUT_TOOL };
+export const COLLECTOR_REQUIRED_TOOLS = [COLLECTOR_OUTPUT_TOOL];
+/** Host tools that grant construction seat privileges — blocked for 收证席 (ADR 0064). */
+export const COLLECTOR_CONSTRUCTION_TOOLS = Object.freeze(["write", "edit"]);
+/** Envelope-owned transport flags (ADR 0018 / #676 E). */
+export const COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
+    Object.freeze({
+        name: "ak-collector-repo",
+        definition: Object.freeze({
+            description: "GitHub owner/repo target for Collector (github.com only; conservative ASCII grammar).",
+            type: "string",
+        }),
+    }),
+    Object.freeze({
+        name: "ak-collector-pr",
+        definition: Object.freeze({
+            description: "Optional positive safe-integer pull request number for Collector. Omit when the role will locate the PR via host CLI.",
+            type: "string",
+        }),
+    }),
+    Object.freeze({
+        name: "ak-collector-request-manifest",
+        definition: Object.freeze({
+            description: "Caller path to a request manifest JSON file (passed as-is; package does not read or validate).",
+            type: "string",
+        }),
+    }),
+]);
+function buildMethodContext(activation) {
+    const lines = [
+        "<collector_method>",
+        `host: github.com`,
+        `repository: ${activation.repository.canonical}`,
+        `prNumber: ${activation.prNumber === undefined ? "未绑定" : String(activation.prNumber)}`,
+        ...(activation.requestManifestPath === undefined
+            ? []
+            : [`requestManifestPath: ${activation.requestManifestPath}`]),
+        "</collector_method>",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Shared envelope installs the submission tool and material callback after lifecycle gates.
+ * Role module does not self-hook events, setActiveTools, or mode/fork checks (ADR 0018 / #676 E).
+ */
+export function createCollectorRoleRuntime(pi, dependencies) {
+    let toolsRegistered = false;
+    return {
+        async activate(_ctx) {
+            const soul = (await dependencies.loadSoul()).trim();
+            if (soul.length === 0)
+                throw new Error("Collector soul is empty");
+            const repoFlag = pi.getFlag("ak-collector-repo");
+            const prFlag = pi.getFlag("ak-collector-pr");
+            const requestManifestFlag = pi.getFlag("ak-collector-request-manifest");
+            if (typeof repoFlag !== "string" || repoFlag.trim().length === 0) {
+                throw new Error("Collector requires --ak-collector-repo");
+            }
+            const repository = parseCollectorRepository(repoFlag);
+            let prNumber;
+            if (typeof prFlag === "string" && prFlag.trim().length > 0) {
+                prNumber = parseCollectorPrNumber(prFlag);
+            }
+            else if (typeof prFlag === "number") {
+                prNumber = parseCollectorPrNumber(prFlag);
+            }
+            // #1165: opaque caller path — keep spaces/"" when the flag was provided.
+            const requestManifestPath = typeof requestManifestFlag === "string" ? requestManifestFlag : undefined;
+            return {
+                soul,
+                repository,
+                prNumber,
+                ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+            };
+        },
+        assembleMaterials(activation, baseSystemPrompt) {
+            return [
+                baseSystemPrompt,
+                "",
+                "<collector_soul>",
+                activation.soul,
+                "</collector_soul>",
+                "",
+                buildMethodContext(activation),
+            ].join("\n");
+        },
+        onToolCall(_activation, event) {
+            if (COLLECTOR_CONSTRUCTION_TOOLS.includes(event.toolName)) {
+                return {
+                    block: true,
+                    reason: `通进司为收证席，禁用施工工具 ${event.toolName}`,
+                };
+            }
+            return undefined;
+        },
+        registerBusinessTools(getActivation) {
+            if (toolsRegistered)
+                return;
+            toolsRegistered = true;
+            registerFiledSubmissionTool(pi, roleSubmissionDeclaration("collector"), {
+                readyError: () => (getActivation() === undefined ? "通进司未激活" : undefined),
+            });
+        },
+    };
+}

package/dist/compliance-transport.js

@@ -53,9 +53,11 @@ async function projectAuditorTerminal(summoned) {
   const outcome = summoned.terminal?.roleOutcome;
   if (outcome === void 0) {
     const detail = summoned.stderr?.trim();
-    throw new Error(
-      detail && detail.length > 0 ? `Auditor public summon produced no terminal (exit ${summoned.exitCode}: ${detail})` : `Auditor public summon produced no terminal (exit ${summoned.exitCode})`
-    );
+    return {
+      status: "transport_failure",
+      diagnostic: detail && detail.length > 0 ? `Auditor public summon produced no terminal (exit ${summoned.exitCode}: ${detail})` : `Auditor public summon produced no terminal (exit ${summoned.exitCode})`,
+      ...summoned.terminal === void 0 ? {} : { terminal: summoned.terminal }
+    };
   }
   const usage = await usageFromSummonedSession(summoned);
   if (outcome.kind === "no_receipt") {

package/dist/countersign-role.js

@@ -0,0 +1,17 @@
+import { courtReviewSubmissionSchema } from "./review-submission.js";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.js";
+import { COUNTERSIGN_OUTPUT_TOOL_NAME, validateRecordedCountersignOutput, } from "./countersign-contracts.js";
+export { COUNTERSIGN_OUTPUT_TOOL_NAME } from "./countersign-contracts.js";
+// #836 r16 class 1: fix/note/decisionGate are LLM/human-read narrative content —
+// no code branches on their length or nested presence. `status` alone is the
+// machine discriminator the queue reads.
+// #1055: the three-state field is an enum+required host generation constraint.
+// #1195: clauses is generation-required on this seat; package execute still does
+// not reject a missing table (ADR 0055).
+/** 给事中票庭审读五问的交卷形状（ADR 0074）；形状指引，非 schema 闸。 */
+export const countersignVerdictSchema = courtReviewSubmissionSchema;
+/**
+ * 决定工具规格。生命周期装配（注册、activate、prompt 注入、singleton 检查、
+ * terminate）归注册信封 owner——src/role-runtime.ts（ADR 0018 / #572 R2 判词）。
+ */
+export const COUNTERSIGN_TOOL_SPEC = roleSubmissionDeclaration("countersign");

package/dist/diarist-role.js

@@ -0,0 +1,8 @@
+import { DIARIST_OUTPUT_TOOL_NAME, diaristOutputSchema, validateRecordedDiaristOutput, } from "./diarist-contracts.js";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.js";
+export { DIARIST_OUTPUT_TOOL_NAME, diaristOutputSchema, } from "./diarist-contracts.js";
+export { validateRecordedDiaristOutput };
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ */
+export const DIARIST_TOOL_SPEC = roleSubmissionDeclaration("diarist");

package/dist/diarist.js

@@ -0,0 +1,15 @@
+/**
+ * 起居郎 volume commit — ADR 0075 `diarist-is-role` / #901 / #1090.
+ * LLM submits bounds; mechanical layer appends a projection commit from
+ * session volumes (pure append, no cross-submit dedupe). No human view.
+ * No lifecycle here (ADR 0018): the seat prepares, the role envelope commits.
+ */
+import { reprojectTicketProvenanceBatch } from "./ticket-provenance.js";
+/**
+ * Append per-ticket diary projections from LLM-submitted bounds (#1090 / #1107).
+ * Shape projection of sessions is the caller's job (accept hook);
+ * this seam only copies source facts into each ticket's volume.
+ */
+export async function commitDiaristProjection(input) {
+    await reprojectTicketProvenanceBatch(input);
+}

package/dist/doctor-role.js

@@ -0,0 +1,80 @@
+import { registerFiledSubmissionTool } from "./filed-submission.js";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.js";
+import { ComplianceResponseRetentionError } from "./compliance-transport.js";
+import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.js";
+import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, validateDoctorOutput } from "./doctor-contracts.js";
+import { sitianReport } from "./sitian-facade.js";
+import { errorText } from "./unknown-value.js";
+export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
+export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/<n>/runs directory", type: "string" } };
+function appendCandidate(ctx, data) {
+    try {
+        sitianReport({
+            level: "event",
+            kind: "candidate",
+            cwd: ctx.cwd,
+            sessionParent: ctx.sessionManager.getSessionFile(),
+            payload: data,
+            source: "doctor-role",
+        });
+    }
+    catch (error) {
+        throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${errorText(error)}`, { cause: error });
+    }
+    const append = ctx.sessionManager.appendCustomEntry;
+    if (typeof append === "function") {
+        try {
+            append.call(ctx.sessionManager, DOCTOR_CANDIDATE_ENTRY_TYPE, data);
+        }
+        catch (error) {
+            throw new ComplianceResponseRetentionError(`太医署候选留存失败: ${errorText(error)}`, { cause: error });
+        }
+    }
+}
+export function createDoctorRoleRuntime(pi, dependencies, host) {
+    let activation;
+    let registered = false;
+    pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
+    return { async activate() {
+            const path = pi.getFlag(DOCTOR_CASE_FLAG.name);
+            if (typeof path !== "string" || !path.trim())
+                throw new Error("Doctor requires --ak-doctor-case");
+            const soul = (await dependencies.loadSoul()).trim();
+            if (!soul)
+                throw new Error("Doctor soul is empty");
+            const patient = await dependencies.loadCase(path);
+            activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
+            if (!registered) {
+                registered = true;
+                pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "太医署证据", description: "分页读取留存的 Pi session 字节。", parameters: doctorEvidenceReadSchema, async execute(_id, params) { if (!activation)
+                        throw new Error("太医署未激活"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text", text: JSON.stringify(details) }], details }; } });
+                registerFiledSubmissionTool(pi, roleSubmissionDeclaration("doctor"), {
+                    readyError: () => (activation === undefined ? "太医署未激活" : undefined),
+                    beforeAccept: async ({ toolCallId, parameters, ctx }) => {
+                        if (activation === undefined)
+                            throw new Error("太医署未激活");
+                        const active = activation;
+                        const testimony = validateDoctorOutput(parameters, active.patient, active.store);
+                        try {
+                            appendCandidate(ctx, { version: 1, testimony, cost: active.patient.cost, readRecord: active.store.readRecord(), patientIdentity: active.patient.identity });
+                        }
+                        catch (error) {
+                            host.failInfrastructure(error, ctx, toolCallId);
+                        }
+                        return testimony;
+                    },
+                });
+                pi.on("before_agent_start", (event) => { if (!activation)
+                    throw new Error("太医署未激活"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; });
+            }
+            const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME];
+            const names = pi.getAllTools().map((tool) => tool.name);
+            for (const name of required)
+                if (names.filter((item) => item === name).length !== 1)
+                    throw new Error(`Doctor required tool collision or missing: ${name}`);
+            pi.setActiveTools(required);
+            const active = pi.getActiveTools?.() ?? required;
+            if (active.length !== 2 || !required.every((name) => active.includes(name)))
+                throw new Error("Doctor active tool narrowing failed");
+        } };
+}

package/dist/engine-detour-tool.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import {
   ENGINE_DETOUR_TOOL_NAME,
-  engineDetourFailureDiagnostic,
+  engineDetourFailureSeatText,
   isEngineDetourFailure,
   resolveEngineModel,
   resolveEngineName,
@@ -12,6 +12,7 @@ import {
   reportEngineDetourCall
 } from "./engine-detour-usage.js";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.js";
+import { serializeThrownValue } from "./serialize-thrown-value.js";
 const engineDetourArgsSchema = Type.Object(
   {
     argv: Type.Array(Type.String({ minLength: 1 }), {
@@ -31,6 +32,27 @@ function isCallerCancellation(error, signal) {
 function asError(error, fallback) {
   return error instanceof Error ? error : new Error(String(error).trim() || fallback);
 }
+function engineFailureResult(input) {
+  const details = {
+    tool: ENGINE_DETOUR_TOOL_NAME,
+    ...input.code === void 0 ? {} : { code: input.code },
+    ...input.stdout === void 0 ? {} : { stdout: input.stdout },
+    ...input.stderr === void 0 ? {} : { stderr: input.stderr },
+    ...input.errorCode === void 0 ? {} : { errorCode: input.errorCode },
+    ...input.ledgerError === void 0 ? {} : { ledgerError: input.ledgerError }
+  };
+  let text = input.text;
+  if (input.ledgerError !== void 0 && input.ledgerError.length > 0) {
+    if (text.length > 0 && !text.endsWith("\n")) text += "\n";
+    text += input.ledgerError;
+  }
+  return {
+    content: [{ type: "text", text }],
+    details,
+    // Identified detour failure is a tool error, not a seat-run death (#1213).
+    isError: true
+  };
+}
 function createEngineDetourToolDefinition(input) {
   const engineName = input.engineName;
   const engineModel = input.engineModel;
@@ -44,13 +66,6 @@ function createEngineDetourToolDefinition(input) {
     async execute(toolCallId, params, signal, _onUpdate, ctx) {
       const args = params;
       const argv = Array.isArray(args.argv) ? args.argv : [];
-      if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
-        input.fail(
-          new Error("\u52B3\u52A1\u5F15\u64CE argv \u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32\u6570\u7EC4"),
-          toolCallId,
-          ctx
-        );
-      }
       const sessionParent = ctx.sessionManager?.getSessionFile?.();
       const startedAt = Date.now();
       const runDirectory = typeof ctx.runDirectory === "string" && ctx.runDirectory.length > 0 ? ctx.runDirectory : void 0;
@@ -71,25 +86,21 @@ function createEngineDetourToolDefinition(input) {
           ...observed2.stdoutByteLength === void 0 ? {} : { stdoutByteLength: observed2.stdoutByteLength }
         });
       };
-      const failAfterLedger = (engineCause, observed2, aggregateMessage) => {
+      const recordCallOrLedgerError = (observed2) => {
         try {
           recordCall(observed2);
+          return void 0;
         } catch (recordError) {
-          input.fail(
-            new AggregateError(
-              [
-                engineCause,
-                asError(recordError, "engine detour usage ledger write failed")
-              ],
-              aggregateMessage,
-              { cause: engineCause }
-            ),
-            toolCallId,
-            ctx
-          );
+          return serializeThrownValue(recordError);
         }
-        input.fail(engineCause, toolCallId, ctx);
       };
+      if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
+        const ledgerError = recordCallOrLedgerError({});
+        return engineFailureResult({
+          text: "\u52B3\u52A1\u5F15\u64CE argv \u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32\u6570\u7EC4",
+          ...ledgerError === void 0 ? {} : { ledgerError }
+        });
+      }
       let result;
       try {
         result = await runEngineDetourOnce({
@@ -99,20 +110,26 @@ function createEngineDetourToolDefinition(input) {
         });
       } catch (error) {
         if (isCallerCancellation(error, signal)) throw error;
-        return failAfterLedger(
-          asError(error, "\u52B3\u52A1\u5F15\u64CE spawn \u5931\u8D25"),
-          {},
-          "engine detour spawn and usage ledger both failed"
-        );
+        const engineError = asError(error, "\u52B3\u52A1\u5F15\u64CE spawn \u5931\u8D25");
+        const ledgerError = recordCallOrLedgerError({});
+        const errno = typeof engineError.code === "string" ? engineError.code : void 0;
+        return engineFailureResult({
+          text: engineError.message,
+          ...errno === void 0 ? {} : { errorCode: errno },
+          ...ledgerError === void 0 ? {} : { ledgerError }
+        });
       }
       const stdoutByteLength = engineDetourStdoutByteLength(result.stdout);
       const observed = { code: result.code, stdoutByteLength };
       if (isEngineDetourFailure(result)) {
-        return failAfterLedger(
-          new Error(engineDetourFailureDiagnostic(result)),
-          observed,
-          "engine detour child-close and usage ledger both failed"
-        );
+        const ledgerError = recordCallOrLedgerError(observed);
+        return engineFailureResult({
+          text: engineDetourFailureSeatText(result),
+          code: result.code,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          ...ledgerError === void 0 ? {} : { ledgerError }
+        });
       }
       recordCall(observed);
       return {
@@ -126,7 +143,7 @@ function createEngineDetourToolDefinition(input) {
     }
   };
 }
-function registerEngineDetourTool(roleHost, hostActions) {
+function registerEngineDetourTool(roleHost) {
   const getFlag = (name) => roleHost.getFlag(name);
   const engineName = resolveEngineName(getFlag);
   if (engineName === void 0) {
@@ -135,10 +152,7 @@ function registerEngineDetourTool(roleHost, hostActions) {
   const engineModel = resolveEngineModel(getFlag);
   const definition = createEngineDetourToolDefinition({
     engineName,
-    ...engineModel === void 0 ? {} : { engineModel },
-    fail(error, toolCallId, ctx) {
-      hostActions.failInfrastructure(error, ctx, toolCallId);
-    }
+    ...engineModel === void 0 ? {} : { engineModel }
   });
   roleHost.registerTool(definition);
   return true;