@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/acp-host/role-turn-host.js

@@ -0,0 +1,484 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { sessionDirectoryOf, sessionFileOf } from "../role-run-placement.js";
+import { createSerializedRoleTurnHost, driveExternalRoleTurnRounds, disposeExternalRoleTurn, externalHostFailure as failure, raceAgainstHostAbort, recordTurnDelivery, retainPackageFaultBesideLivePlacement, syncTurnRequestLivePlacement, trySyncTurnRequestLivePlacement, } from "../external-host-turn-loop.js";
+import { describeErrorIdentity } from "../public-cli/run-lifecycle.js";
+import { projectThrownFailureLeaf } from "../public-cli/settlement.js";
+import { copyAndRecordHostDossier, recordNativeSessionPointer, } from "../host-session-record.js";
+import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorProseFromUnknown, } from "../package-contracts/navigator-output.js";
+import { renderSystemPromptOverride, resolveBoundHostSessionId, } from "../prepared-role-turn.js";
+import { acpModelId } from "./description.js";
+import { isRecord } from "../unknown-value.js";
+/**
+ * #959: collect free-form agent text from ACP session/update stream.
+ * Used only when the navigator seat spoke prose without calling the output tool.
+ * ACP agent speech is only agent_message / agent_message_chunk — never user,
+ * thought, or other *_message kinds (load replay must not poison the bucket).
+ *
+ * Standard ACP nests under params.update: { sessionUpdate, content }.
+ * Flat params.sessionUpdate / string params.update remain accepted for host variants.
+ */
+function acpAgentTextChunk(params) {
+    let kind;
+    let content;
+    let textFallback;
+    const nested = params.update;
+    if (isRecord(nested)) {
+        const record = nested;
+        kind = record.sessionUpdate;
+        content = record.content;
+        textFallback = record.text;
+    }
+    else {
+        kind = params.sessionUpdate ?? nested;
+        content = params.content;
+        textFallback = params.text;
+    }
+    if (kind !== "agent_message_chunk" && kind !== "agent_message")
+        return undefined;
+    if (typeof content === "string" && content.length > 0)
+        return content;
+    if (isRecord(content)) {
+        const record = content;
+        if (typeof record.text === "string" && record.text.length > 0)
+            return record.text;
+    }
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const part of content) {
+            if (typeof part === "string" && part.length > 0)
+                parts.push(part);
+            else if (typeof part === "object" && part !== null) {
+                const record = part;
+                if (typeof record.text === "string" && record.text.length > 0)
+                    parts.push(record.text);
+            }
+        }
+        if (parts.length > 0)
+            return parts.join("");
+    }
+    if (typeof textFallback === "string" && textFallback.length > 0)
+        return textFallback;
+    return undefined;
+}
+function acpError(code, message, cause) {
+    return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
+}
+/** One ACP JSON-RPC stdio process. Natural close/SIGTERM are its only lifecycle exits. */
+export function connectAcpStdio(options) {
+    const child = spawn(options.binary, [...options.args], { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", "pipe"] });
+    const pending = new Map();
+    const notificationHandlers = [];
+    if (options.onNotification !== undefined)
+        notificationHandlers.push(options.onNotification);
+    let nextId = 0;
+    let closed = false;
+    let terminalError;
+    let spawned = false;
+    let stoppedByPackage = false;
+    let nativeExit;
+    let rpcFailure;
+    child.once("spawn", () => { spawned = true; });
+    // Native stderr bytes stay separate from transport exception diagnostics.
+    let stderr = "";
+    const settleClosed = (error) => {
+        if (closed)
+            return;
+        closed = true;
+        terminalError = error;
+        for (const waiter of pending.values())
+            waiter.reject(error);
+        pending.clear();
+    };
+    // Framing corruption or a known required capability with unusable shape still
+    // closes the child. Unknown client methods are answered in-band (JSON-RPC
+    // method not found) and do not terminate the leg (#760).
+    const terminate = (error) => {
+        settleClosed(error);
+        child.stdin.end();
+        stoppedByPackage = child.kill("SIGTERM") || stoppedByPackage;
+    };
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+        stderr += chunk;
+    }).on("error", terminate);
+    child.on("error", settleClosed);
+    child.stdin.on("error", terminate);
+    createInterface({ input: child.stdout }).on("error", terminate).on("line", (line) => {
+        try {
+            const message = JSON.parse(line);
+            if (typeof message.method === "string") {
+                const params = typeof message.params === "object" && message.params !== null
+                    ? message.params : {};
+                for (const handler of notificationHandlers)
+                    handler(message.method, params);
+                if (typeof message.id === "number") {
+                    if (message.method !== "session/request_permission") {
+                        // Vendor extensions (_x.ai/*, …) and any other unhandled client request:
+                        // JSON-RPC method-not-found reply; session continues (#760).
+                        child.stdin.write(`${JSON.stringify({
+                            jsonrpc: "2.0",
+                            id: message.id,
+                            error: { code: -32601, message: `Method not found: ${message.method}` },
+                        })}\n`);
+                        return;
+                    }
+                    const choices = Array.isArray(params.options) ? params.options : [];
+                    const selected = choices.find((value) => typeof value === "object" && value !== null && value.kind === "allow_once");
+                    if (typeof selected?.optionId !== "string") {
+                        terminate(acpError("acp-permission-missing-allow-once", "ACP permission request omitted allow_once"));
+                        return;
+                    }
+                    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: { outcome: { outcome: "selected", optionId: selected.optionId } } })}\n`);
+                }
+                return;
+            }
+            if (typeof message.id !== "number")
+                return;
+            const waiter = pending.get(message.id);
+            if (waiter === undefined)
+                return;
+            pending.delete(message.id);
+            if (message.error !== undefined) {
+                const diagnostic = typeof message.error === "object" && message.error !== null
+                    && "message" in message.error && typeof message.error.message === "string"
+                    ? message.error.message : JSON.stringify(message.error);
+                rpcFailure ??= { diagnostic, details: message };
+                waiter.reject(acpError("acp-upstream-error", diagnostic, message));
+            }
+            else
+                waiter.resolve((message.result ?? {}));
+        }
+        catch (error) {
+            terminate(error);
+        }
+    });
+    const processClosed = new Promise((resolve) => {
+        child.once("close", (code, signal) => {
+            // ENOENT also emits close, but no host process was launched in that case.
+            if (spawned)
+                nativeExit = { code, timedOut: false, ...(signal === null ? {} : { signal }) };
+            settleClosed(acpError("acp-closed", "ACP process closed"));
+            resolve();
+        });
+    });
+    return Promise.resolve({
+        request(method, params) {
+            if (closed)
+                return Promise.reject(terminalError);
+            const id = ++nextId;
+            return new Promise((resolve, reject) => {
+                pending.set(id, { resolve, reject });
+                child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`, (error) => {
+                    if (error === null || error === undefined)
+                        return;
+                    const waiter = pending.get(id);
+                    if (waiter === undefined)
+                        return;
+                    pending.delete(id);
+                    waiter.reject(error);
+                });
+            });
+        },
+        notify(method, params) {
+            if (closed)
+                throw terminalError;
+            child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+        },
+        onNotification(handler) {
+            notificationHandlers.push(handler);
+        },
+        stderr() {
+            return stderr;
+        },
+        result() {
+            if (nativeExit === undefined && rpcFailure === undefined)
+                return undefined;
+            return {
+                ...(nativeExit ?? { code: null, timedOut: false }),
+                stderr,
+                ...(rpcFailure === undefined ? {} : { knownFailure: rpcFailure }),
+            };
+        },
+        async close() {
+            if (!closed)
+                terminate(acpError("acp-connection-closed", "ACP connection is closed"));
+            await processClosed;
+            return !stoppedByPackage && nativeExit !== undefined ? { ...nativeExit, stderr } : undefined;
+        },
+    });
+}
+/** ACP last hop (#820): session open/load/close, prompt, MCP mount, capability/model. */
+export function createAcpRoleTurnHost(config) {
+    return createSerializedRoleTurnHost(async (request) => {
+        const prepared = await config.prepare(request);
+        const systemPromptOverride = renderSystemPromptOverride(prepared.systemPrompt);
+        let connection;
+        let sessionId;
+        let sessionOpened = false;
+        let accepted = false;
+        // Re-resolve after mid-turn report-ticket may have moved principal (#1171).
+        const liveSessionParent = () => config.sessionIdentity.resolveSessionFile(request.principal);
+        let outcome = failure("session", "AcpNoOutcome", "no-outcome");
+        let reportedFailure;
+        let packageFailure;
+        try {
+            if (prepared.mcpServers.length === 0) {
+                outcome = failure("activation", "UncontrolledAcpSession", "ak-config-missing");
+            }
+            else {
+                connection = await config.connect(request);
+                const rpc = (method, params) => connection.request(method, params);
+                // #959: navigator free-form agent text — only while session/prompt is in flight.
+                // session/load replays history via session/update; those must not enter the bucket
+                // (resume / set_model load would otherwise prepend prior turns as "this turn" prose).
+                const agentProseChunks = [];
+                let collectAgentProse = false;
+                connection.onNotification?.((method, params) => {
+                    const isSessionUpdate = method === "session/update";
+                    if (!isSessionUpdate)
+                        return;
+                    if (collectAgentProse) {
+                        const chunk = acpAgentTextChunk(params);
+                        if (chunk !== undefined)
+                            agentProseChunks.push(chunk);
+                    }
+                });
+                const initialized = await rpc("initialize", {
+                    protocolVersion: 1,
+                    clientCapabilities: {},
+                });
+                const initializeMeta = initialized._meta;
+                const availableModels = Array.isArray(initializeMeta?.modelState?.availableModels)
+                    ? initializeMeta.modelState.availableModels
+                    : undefined;
+                if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) => typeof entry === "object" && entry !== null
+                    && entry.modelId === acpModelId(config, request.model))) {
+                    outcome = failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
+                        provider: request.model.provider,
+                        model: request.model.model,
+                    });
+                }
+                else {
+                    const sessionBindParams = {
+                        cwd: request.cwd,
+                        mcpServers: prepared.mcpServers,
+                        _meta: { systemPromptOverride, yoloMode: false },
+                    };
+                    const loadSession = async (bindSessionId) => {
+                        const loaded = await rpc("session/load", {
+                            sessionId: bindSessionId,
+                            ...sessionBindParams,
+                        });
+                        const loadedId = typeof loaded.sessionId === "string" && loaded.sessionId !== ""
+                            ? loaded.sessionId
+                            : bindSessionId;
+                        if (config.hostName !== "hermes")
+                            recordNativeSessionPointer({
+                                host: config.hostName, sessionId: loadedId, cwd: request.cwd, sessionParent: liveSessionParent(), home: request.home,
+                            });
+                        return loadedId;
+                    };
+                    let sessionReady = true;
+                    if (request.continuation.kind === "resume") {
+                        const boundSessionId = await resolveBoundHostSessionId(request, config.sessionIdentity);
+                        if (boundSessionId !== undefined && boundSessionId !== "") {
+                            sessionId = boundSessionId;
+                            sessionId = await loadSession(boundSessionId);
+                            sessionOpened = true;
+                        }
+                        else {
+                            outcome = failure("session", "AcpSessionFailure", "session-id-missing", undefined, "resume requires a bound session id");
+                            sessionReady = false;
+                        }
+                    }
+                    else {
+                        const session = await rpc("session/new", sessionBindParams);
+                        sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
+                        if (sessionId === undefined || sessionId === "") {
+                            outcome = failure("session", "AcpSessionFailure", "session-id-missing");
+                            sessionReady = false;
+                        }
+                        else {
+                            if (config.hostName !== "hermes")
+                                recordNativeSessionPointer({
+                                    host: config.hostName, sessionId, cwd: request.cwd, sessionParent: liveSessionParent(), home: request.home,
+                                });
+                            sessionOpened = true;
+                            await config.sessionIdentity.bind(request.principal, sessionId);
+                        }
+                    }
+                    if (sessionReady) {
+                        // set_model host-native catalog id (#778 / #1146); may rebuild agent — re-bind via loadSession.
+                        if (config.modelPassing === "set_model" && request.model !== undefined && sessionId !== undefined) {
+                            await rpc("session/set_model", {
+                                sessionId,
+                                modelId: acpModelId(config, request.model),
+                            });
+                            sessionId = await loadSession(sessionId);
+                        }
+                        const activeConnection = connection;
+                        const activeSessionId = sessionId;
+                        const turnResult = await driveExternalRoleTurnRounds(prepared, request, {
+                            roundLimitName: "AcpRoundLimit",
+                            currentSessionId: () => sessionId,
+                            async runRound({ prompt, abortSignal }) {
+                                // One history row per actual session/prompt start (催交回合各算一次).
+                                // MCP advertises tool.parameters; prepared.jsonSchema is the headless
+                                // draft-07 stamp of that clone — record the delivered parameters face.
+                                const { $schema: _headlessStamp, ...deliveredSchema } = prepared.jsonSchema;
+                                await recordTurnDelivery(await syncTurnRequestLivePlacement(request, config.sessionIdentity.principalAuthority), {
+                                    systemPrompt: systemPromptOverride,
+                                    outputSchema: deliveredSchema,
+                                }, "acp-host");
+                                let result;
+                                // Open the prose gate only for this prompt round; clear any stale chunks first.
+                                agentProseChunks.length = 0;
+                                collectAgentProse = prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME;
+                                try {
+                                    result = await raceAgainstHostAbort(activeConnection.request("session/prompt", {
+                                        sessionId: activeSessionId,
+                                        prompt: [{ type: "text", text: prompt }],
+                                    }), abortSignal, "ACP host aborted");
+                                }
+                                catch (error) {
+                                    collectAgentProse = false;
+                                    agentProseChunks.length = 0;
+                                    throw error;
+                                }
+                                collectAgentProse = false;
+                                if (result.stopReason === "refusal") {
+                                    agentProseChunks.length = 0;
+                                    reportedFailure = { diagnostic: result.stopReason, details: result };
+                                    return {
+                                        status: "terminal",
+                                        result: {
+                                            code: null,
+                                            stderr: activeConnection.stderr?.() ?? "",
+                                            timedOut: false,
+                                            knownFailure: reportedFailure,
+                                        },
+                                    };
+                                }
+                                // #959: navigator prose exit when the model spoke without the output tool.
+                                // Tool path still wins via MCP; ingest is a no-op once the tool already sealed.
+                                // Emptiness via shared projector; payload keeps original bytes (LLM 原话过手).
+                                if (prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME) {
+                                    const prose = agentProseChunks.join("");
+                                    agentProseChunks.length = 0;
+                                    if (navigatorProseFromUnknown(prose) !== undefined) {
+                                        await prepared.ingestStructuredOutput({ prose });
+                                    }
+                                }
+                                else {
+                                    agentProseChunks.length = 0;
+                                }
+                                return { status: "delivered", stderr: activeConnection.stderr?.() ?? "" };
+                            },
+                            async afterAccepted() {
+                                await rpc("session/close", { sessionId: activeSessionId });
+                                accepted = true;
+                            },
+                        });
+                        outcome = turnResult;
+                    } // sessionReady
+                } // model match else
+            } // mcpServers else
+        }
+        catch (error) {
+            const native = connection?.result?.();
+            reportedFailure = native?.knownFailure;
+            outcome = native ?? { code: null, stderr: connection?.stderr?.() ?? "", timedOut: false };
+            await retainPackageFaultBesideLivePlacement(request, {
+                diagnostic: `ACP turn exception beside native host facts: ${describeErrorIdentity(error)}`,
+                error,
+            });
+            // Native abnormal exit / RPC report stays primary. Otherwise this is a
+            // real package exception, not a host cause inferred from missing output.
+            if (outcome.knownFailure === undefined && !outcome.timedOut && outcome.signal === undefined
+                && (native === undefined || outcome.code === 0 || outcome.code === null)) {
+                packageFailure = projectThrownFailureLeaf(error);
+                outcome = { ...outcome, knownFailure: packageFailure };
+            }
+        }
+        finally {
+            let naturalTermination = undefined;
+            if (connection !== undefined) {
+                if (sessionId !== undefined && !accepted) {
+                    try {
+                        connection.notify("session/cancel", { sessionId });
+                    }
+                    catch (error) {
+                        await retainPackageFaultBesideLivePlacement(request, {
+                            diagnostic: `session cancel failed beside host terminal: ${describeErrorIdentity(error)}`,
+                            error,
+                        });
+                    }
+                }
+                try {
+                    naturalTermination = await connection.close();
+                }
+                catch (error) {
+                    await retainPackageFaultBesideLivePlacement(request, {
+                        diagnostic: `connection close failed beside host terminal: ${describeErrorIdentity(error)}`,
+                        error,
+                    });
+                }
+            }
+            // Both success and failure drain the native stderr stream, including
+            // bytes arriving after the last RPC response.
+            outcome = { ...outcome, stderr: connection?.stderr?.() ?? outcome.stderr };
+            // On abnormal paths, teardown has now drained the real close/stderr.
+            // A successful ACP protocol turn remains successful: its ordinary
+            // connection cleanup is not reclassified as a role failure.
+            const native = connection?.result?.() ?? naturalTermination;
+            if (native !== undefined && (naturalTermination !== undefined || outcome.code !== 0
+                || outcome.knownFailure !== undefined || outcome.timedOut || outcome.signal !== undefined)) {
+                // A late native failure stays primary over a package failure. An own
+                // SIGTERM stop alone is ordinary disposal, not a guessed host cause.
+                const nativeFailed = (native.code !== null && native.code !== 0)
+                    || (naturalTermination !== undefined && (native.timedOut || native.signal !== undefined));
+                let knownFailure = outcome.knownFailure;
+                if (nativeFailed && knownFailure !== undefined && knownFailure !== reportedFailure) {
+                    if (knownFailure !== packageFailure) {
+                        await retainPackageFaultBesideLivePlacement(request, {
+                            diagnostic: knownFailure.diagnostic ?? "ACP package failure beside late native termination",
+                            error: knownFailure,
+                        });
+                    }
+                    knownFailure = reportedFailure;
+                }
+                const { knownFailure: _nativeFailure, ...facts } = native;
+                outcome = { ...facts, ...(knownFailure === undefined ? {} : { knownFailure }) };
+            }
+            if (config.hostName !== "hermes" && sessionOpened && sessionId !== undefined) {
+                const live = await trySyncTurnRequestLivePlacement(request, config.sessionIdentity.principalAuthority);
+                if ("runDirectory" in live) {
+                    try {
+                        copyAndRecordHostDossier({
+                            host: config.hostName,
+                            sessionId,
+                            cwd: request.cwd,
+                            sessionDirectory: sessionDirectoryOf(live.runDirectory),
+                            sessionParent: sessionFileOf(live.runDirectory),
+                            ...(request.home !== undefined ? { home: request.home } : {}),
+                        });
+                    }
+                    catch (error) {
+                        await retainPackageFaultBesideLivePlacement(request, {
+                            diagnostic: `host dossier copy failed beside host terminal: ${describeErrorIdentity(error)}`,
+                            error,
+                        });
+                    }
+                }
+                else {
+                    await retainPackageFaultBesideLivePlacement(request, {
+                        diagnostic: `host dossier copy skipped: live run path resolve failed beside host terminal: ${describeErrorIdentity(live.resolveError)}`,
+                        error: live.resolveError,
+                    });
+                }
+            }
+            outcome = await disposeExternalRoleTurn(prepared, request, outcome);
+        }
+        return outcome;
+    });
+}

package/dist/activation-ledger-session.js

@@ -0,0 +1,105 @@
+import { lstatSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { errnoCode, errorText, } from "./activation-ledger-topology.js";
+/**
+ * Typed missing durable session principal. Callers discriminate with instanceof/code;
+ * never by parsing message prose. Original filesystem causes are retained.
+ */
+export class ActivationSessionFileMissingError extends Error {
+    code = "AK_ACTIVATION_SESSION_FILE_MISSING";
+    path;
+    constructor(path, options) {
+        super(`Workflow role activation durable session file does not exist: ${path}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "ActivationSessionFileMissingError";
+        this.path = path;
+    }
+}
+function materializeDeferredSessionFile(sessionManager, resolvedFile) {
+    const header = sessionManager.getHeader?.();
+    if (header === null || header === undefined || header.type !== "session") {
+        throw new ActivationSessionFileMissingError(resolvedFile);
+    }
+    // Activation does not own record placement (ADR 0065 / #221). Parent directory is the
+    // SessionManager principal's own dir — write the header in place; do not pull ledgerHome
+    // containment or ensureRealDirectoryTree back onto this admission path.
+    try {
+        writeFileSync(resolvedFile, `${JSON.stringify(header)}\n`, { flag: "wx" });
+    }
+    catch (error) {
+        if (errnoCode(error) !== "EEXIST") {
+            throw new Error(`Workflow role activation failed to materialize durable session file (${resolvedFile}): ${errorText(error)}`, { cause: error });
+        }
+        // Lost a create race — validate the winner below.
+    }
+    // Rebind full SessionManager so subsequent Pi appends use O_APPEND (flushed=true)
+    // instead of exclusive wx create against the file we just wrote.
+    if (typeof sessionManager.setSessionFile === "function") {
+        sessionManager.setSessionFile(resolvedFile);
+    }
+}
+/**
+ * Admit a durable Pi session file principal (ADR 0048/0065).
+ * Requires an existing regular file at admission (or a live SessionManager header that
+ * can be materialized onto the same path). Rejects relative paths, directories,
+ * non-files, and nonexistent paths that cannot be materialized. Original filesystem
+ * causes are retained.
+ *
+ * Record-placement (session must live under the ledger book) is NOT enforced here —
+ * that check lives on the activation ledger path. Activation only
+ * binds the durable principal identity for the role run.
+ *
+ * Upstream Pi defers exclusive create until the first assistant message. When the path
+ * is the live SessionManager principal and only the header is in memory, admission
+ * materializes that header onto the same path before the fact is written so the role
+ * fact never points at a session that may be created later.
+ */
+export function durableSessionPointer(sessionManager) {
+    const file = sessionManager.getSessionFile?.();
+    if (typeof file !== "string" || file.length === 0) {
+        throw new Error("Workflow role activation requires a durable Pi session file principal (getSessionFile); directory-only or --no-session invocations are rejected");
+    }
+    if (!isAbsolute(file)) {
+        throw new Error(`Workflow role activation requires an absolute durable session file path; got relative path: ${file}`);
+    }
+    const resolvedFile = resolve(file);
+    try {
+        lstatSync(resolvedFile);
+    }
+    catch (error) {
+        if (errnoCode(error) !== "ENOENT") {
+            throw new Error(`Workflow role activation failed to stat durable session file (${resolvedFile}): ${errorText(error)}`, { cause: error });
+        }
+        try {
+            materializeDeferredSessionFile(sessionManager, resolvedFile);
+        }
+        catch (materializeError) {
+            // Missing principal: rethrow typed missing-file identity with the original ENOENT cause.
+            // Other materialize failures keep their own typed/native identity.
+            if (materializeError instanceof ActivationSessionFileMissingError) {
+                throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+            }
+            throw materializeError;
+        }
+    }
+    let realFile;
+    try {
+        realFile = realpathSync(resolvedFile);
+    }
+    catch (error) {
+        throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+    }
+    let info;
+    try {
+        info = statSync(realFile);
+    }
+    catch (error) {
+        throw new Error(`Workflow role activation failed to stat durable session file (${realFile}): ${errorText(error)}`, { cause: error });
+    }
+    if (info.isDirectory()) {
+        throw new Error(`Workflow role activation durable session principal must be a file, not a directory: ${realFile}`);
+    }
+    if (!info.isFile()) {
+        throw new Error(`Workflow role activation durable session principal is not a regular file: ${realFile}`);
+    }
+    return { kind: "session-file", path: realFile };
+}

package/dist/activation-ledger.js

@@ -0,0 +1,8 @@
+/**
+ * Activation ledger surface: durable session principal + book/home topology.
+ * #855: two-face waiting.jsonl reconciliation deleted — this module no longer
+ * appends accepted-activation facts or own a waiting path.
+ */
+export { ActivationGitRepositoryRequiredError, resolveBookKeyFromGit, } from "./activation-ledger-git.js";
+export { ActivationSessionFileMissingError, durableSessionPointer, } from "./activation-ledger-session.js";
+export { ActivationLedgerError, activationBookDirectory, resolveActivationLedgerHome, } from "./activation-ledger-topology.js";

package/dist/activation-trace.js

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+const causeSchema = Type.Object({
+    identity: Type.String({ minLength: 1 }),
+    name: Type.String({ minLength: 1 }),
+    message: Type.String(),
+    evidenceId: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+export const activationTraceRecordSchema = Type.Object({
+    role: Type.String({ minLength: 1 }),
+    stageId: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+    status: Type.Literal("failed"),
+    timestamp: Type.String({ format: "date-time" }),
+    cause: causeSchema,
+}, { additionalProperties: false });
+let activationCauseEvidence = 0;
+const retainedActivationCauses = new Map();
+export function namedActivationCause(error) {
+    const evidenceId = `activation-cause-${++activationCauseEvidence}`;
+    retainedActivationCauses.set(evidenceId, error);
+    if (error instanceof Error) {
+        const code = error.code;
+        const name = error.name || "Error";
+        return { identity: typeof code === "string" && code.length > 0 ? code : name, name, message: error.message, evidenceId };
+    }
+    let message;
+    try {
+        message = typeof error === "string" ? error : JSON.stringify(error) ?? String(error);
+        return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message, evidenceId };
+    }
+    catch {
+        return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message: String(error), evidenceId };
+    }
+}

package/dist/audit-escalation.js

@@ -0,0 +1,7 @@
+import { isRecord } from "./unknown-value.js";
+/** Historical audit-escalation discriminator retained for reading pre-#1057 run artifacts. */
+export const AUDIT_ESCALATION_KIND = "audit_escalation";
+export function isAuditEscalationResult(value) {
+    return isRecord(value)
+        && value.kind === AUDIT_ESCALATION_KIND;
+}

package/dist/audited-run-identity.js

@@ -0,0 +1,21 @@
+/**
+ * Shared audited-run identity for review-officer startup materials (#1166 / ADR 0087).
+ * Value form is `<runId>@<席>` only — no directory path.
+ */
+import { basename } from "node:path";
+import { formatRunLeaf, parseRunLeaf } from "./role-run-placement.js";
+export const AUDITED_RUN_IDENTITY_KIND = "audited-run-identity";
+/** Identity leaf from a run directory basename; undefined when the leaf is not `runId@role`. */
+export function auditedRunIdentityFromDirectory(runDirectory) {
+    const parsed = parseRunLeaf(basename(runDirectory));
+    if (parsed === undefined)
+        return undefined;
+    return formatRunLeaf(parsed.runId, parsed.role);
+}
+export function auditedRunIdentityMaterial(identity) {
+    return { kind: AUDITED_RUN_IDENTITY_KIND, identity };
+}
+/** Identity from locator fields already in hand (notary source-run). */
+export function auditedRunIdentityFromParts(runId, role) {
+    return formatRunLeaf(runId, role);
+}