@akagilnc/pi-workflow-roles 0.1.5406 → 0.1.5475

package/dist/host-contracts.js

@@ -1,3 +1,11 @@
+/**
+ * Controlled post-admission failure classes (ADR 0052 / #107). Owner = host contract.
+ * Closed set of typed facts only — never a fabricated "could not classify" label (#881).
+ * When no typed confirmation exists, omit cause and keep the original diagnostic / error pointer.
+ */
+export const CONTROLLED_FAILURE_CAUSES = [
+    "activation", "provider", "session", "output", "timeout",
+];
 /**
  * Thrown activation failure with a production-owned typed cause.
  * Prefer this over ad-hoc Error property tags so settlement retains typed identity.

package/dist/migrate-book-topology.js

@@ -682,14 +682,6 @@ var init_cli_errors = __esm({
   }
 });
 
-// src/typed-provider-http.ts
-var init_typed_provider_http = __esm({
-  "src/typed-provider-http.ts"() {
-    "use strict";
-    init_unknown_value();
-  }
-});
-
 // src/sha256.ts
 import { createHash } from "node:crypto";
 function sha256Hex(bytes) {
@@ -14057,7 +14049,6 @@ var init_packaged_role_registry = __esm({
         outputTool: JUDGE_OUTPUT_TOOL_NAME,
         auditTool: JUDGE_AUDIT_TOOL_NAME,
         settlement: "sealed",
-        runnerFailure: "engine-detour-known-first",
         /** Factory board: court until another station has started, then marshal. */
         boardPlacement: "judge-history",
         /** Navigator subject is the public admitted instruction when the run is bound. */
@@ -14175,7 +14166,6 @@ var init_packaged_role_registry = __esm({
         },
         /** Frozen base/lens/authority become the initial prompt; instruction follows. */
         transportPrompt: "skill-args",
-        runnerFailure: "engine-detour-record-first",
         boardPlacement: "marshal",
         activationFlags: [
           { field: "baseRevision", flag: "ak-review-base" },
@@ -14270,10 +14260,7 @@ var init_packaged_role_registry = __esm({
         /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
         phases: [null],
         outputTool: MERGER_OUTPUT_TOOL_NAME,
-        settlement: "residual",
-        /** #836: residual scan stays on the whole host session. */
-        residualScan: "session",
-        residualTool: MERGER_OUTPUT_TOOL_NAME,
+        settlement: "sealed",
         artifactFace: {
           evidenceRole: true,
           leaves: [
@@ -14450,7 +14437,6 @@ var init_packaged_role_registry = __esm({
         phases: [null],
         outputTool: GATEKEEPER_OUTPUT_TOOL_NAME,
         settlement: "accepted",
-        runnerFailure: "engine-detour-record-first",
         activationStage: "load-and-install",
         // Province materials; officers reuse their own public records below.
         sessionMaterials: ["CLAUDE.md", "souls/gatekeeper.md", "souls/quality-law.md", "souls/gate-output-guide.md"]
@@ -14465,7 +14451,6 @@ var init_packaged_role_registry = __esm({
         phases: [null],
         outputTool: NAVIGATOR_OUTPUT_TOOL_NAME,
         settlement: "accepted",
-        runnerFailure: "engine-detour-record-first",
         activationStage: "load-and-install",
         sessionMaterials: ["CLAUDE.md", "souls/navigator.md"]
       },
@@ -14488,7 +14473,6 @@ var init_packaged_role_registry = __esm({
         settlement: "accepted",
         /** Court reask replaces the initial prompt. */
         reaskPrompt: true,
-        runnerFailure: "engine-detour-record-first",
         gateStageLabel: "\u5BA1\u5211\u9662",
         /** Gate summon binds --subject judge and --source-run. */
         gateSummon: "subject-source",
@@ -14690,12 +14674,38 @@ var init_role_submission_declarations = __esm({
   }
 });
 
+// src/serialize-thrown-value.ts
+var init_serialize_thrown_value = __esm({
+  "src/serialize-thrown-value.ts"() {
+    "use strict";
+  }
+});
+
+// src/public-cli/terminal.ts
+var init_terminal = __esm({
+  "src/public-cli/terminal.ts"() {
+    "use strict";
+    init_serialize_thrown_value();
+  }
+});
+
 // src/run-terminal-artifacts.ts
+var RUN_TERMINAL_ERROR_SETTLEMENT_FILE, RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS, UNIQUE_ERROR_FALLBACK_STEM, UNIQUE_ERROR_FALLBACK_NAME;
 var init_run_terminal_artifacts = __esm({
   "src/run-terminal-artifacts.ts"() {
     "use strict";
     init_role_run_placement();
     init_unknown_value();
+    RUN_TERMINAL_ERROR_SETTLEMENT_FILE = "error.settlement.json";
+    RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS = [
+      `artifacts/${RUN_TERMINAL_ERROR_SETTLEMENT_FILE}`,
+      RUN_TERMINAL_ERROR_SETTLEMENT_FILE
+    ];
+    UNIQUE_ERROR_FALLBACK_STEM = "error";
+    UNIQUE_ERROR_FALLBACK_NAME = new RegExp(
+      `^${UNIQUE_ERROR_FALLBACK_STEM}\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\.json$`,
+      "i"
+    );
   }
 });
 
@@ -14711,20 +14721,15 @@ var init_gatekeeper_role = __esm({
     init_review_submission();
     init_gatekeeper_output();
     init_role_submission_declarations();
+    init_terminal();
     init_run_terminal_artifacts();
     init_unknown_value();
+    init_serialize_thrown_value();
     init_submission_errors();
     GATEKEEPER_TOOL_SPEC = roleSubmissionDeclaration("gatekeeper");
   }
 });
 
-// src/public-cli/terminal.ts
-var init_terminal = __esm({
-  "src/public-cli/terminal.ts"() {
-    "use strict";
-  }
-});
-
 // src/host-descriptions.ts
 var HOST_DESCRIPTIONS, HEADLESS_HOST_DESCRIPTIONS;
 var init_host_descriptions = __esm({
@@ -16057,7 +16062,7 @@ var init_option_definitions = __esm({
       },
       notary: {
         command: "notary",
-        summary: "Direct Notary document check (quote fidelity + ticket alignment); zero prompt/attachment.",
+        summary: "Direct Notary summons; duties: souls/notary.md. Zero prompt/attachment.",
         usage: ["ak-role notary --source-run <runId@role|path> [options]"],
         examples: [
           "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@judge",
@@ -16220,8 +16225,6 @@ var init_run_lifecycle = __esm({
     init_role_run_placement();
     init_run_ticket_number();
     init_cli_errors();
-    init_typed_provider_http();
-    init_typed_provider_http();
     init_collector_config();
     init_role_run_relocation();
     init_engine_material();

package/dist/packaged-role-registry.js

@@ -59,7 +59,6 @@ const PUBLIC_ROLE_RECORDS = [
     outputTool: JUDGE_OUTPUT_TOOL_NAME,
     auditTool: JUDGE_AUDIT_TOOL_NAME,
     settlement: "sealed",
-    runnerFailure: "engine-detour-known-first",
     /** Factory board: court until another station has started, then marshal. */
     boardPlacement: "judge-history",
     /** Navigator subject is the public admitted instruction when the run is bound. */
@@ -177,7 +176,6 @@ const PUBLIC_ROLE_RECORDS = [
     },
     /** Frozen base/lens/authority become the initial prompt; instruction follows. */
     transportPrompt: "skill-args",
-    runnerFailure: "engine-detour-record-first",
     boardPlacement: "marshal",
     activationFlags: [
       { field: "baseRevision", flag: "ak-review-base" },
@@ -272,10 +270,7 @@ const PUBLIC_ROLE_RECORDS = [
     /** Method-material load failure keeps the activation cause (not reviewer/fixer). */
     phases: [null],
     outputTool: MERGER_OUTPUT_TOOL_NAME,
-    settlement: "residual",
-    /** #836: residual scan stays on the whole host session. */
-    residualScan: "session",
-    residualTool: MERGER_OUTPUT_TOOL_NAME,
+    settlement: "sealed",
     artifactFace: {
       evidenceRole: true,
       leaves: [
@@ -452,7 +447,6 @@ const PUBLIC_ROLE_RECORDS = [
     phases: [null],
     outputTool: GATEKEEPER_OUTPUT_TOOL_NAME,
     settlement: "accepted",
-    runnerFailure: "engine-detour-record-first",
     activationStage: "load-and-install",
     // Province materials; officers reuse their own public records below.
     sessionMaterials: ["CLAUDE.md", "souls/gatekeeper.md", "souls/quality-law.md", "souls/gate-output-guide.md"]
@@ -467,7 +461,6 @@ const PUBLIC_ROLE_RECORDS = [
     phases: [null],
     outputTool: NAVIGATOR_OUTPUT_TOOL_NAME,
     settlement: "accepted",
-    runnerFailure: "engine-detour-record-first",
     activationStage: "load-and-install",
     sessionMaterials: ["CLAUDE.md", "souls/navigator.md"]
   },
@@ -490,7 +483,6 @@ const PUBLIC_ROLE_RECORDS = [
     settlement: "accepted",
     /** Court reask replaces the initial prompt. */
     reaskPrompt: true,
-    runnerFailure: "engine-detour-record-first",
     gateStageLabel: "\u5BA1\u5211\u9662",
     /** Gate summon binds --subject judge and --source-run. */
     gateSummon: "subject-source",

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

@@ -14,6 +14,8 @@ import { ExplicitInternalActivationError } from "../host-contracts.js";
 import { applyEngineChildEnv, ENGINE_MODEL_FLAG_NAME, normalizeEngineName } from "../engine-detour.js";
 import { projectActivationFlags } from "../role-activation-flags.js";
 import { encodeUserDialogueStdin } from "../user-dialogue-stdin.js";
+import { projectThrownFailureLeaf, retainPackageFault } from "../public-cli/settlement.js";
+import { describeErrorIdentity } from "../public-cli/run-lifecycle.js";
 import { RECEIPT_DELIVERY_LIMIT_ENV } from "../receipt-delivery-policy.js";
 /** Package-relative Internal role entrypoint (ADR 0052; same path as public-cli registry). */
 const INTERNAL_ROLE_ENTRYPOINT_RELATIVE = "extensions/role-runtime.ts";
@@ -191,7 +193,6 @@ export function createDefaultPiSpawnRunner(options) {
             // fall back to rejecting on `error` if `close` never fires (e.g. spawn
             // never succeeded so no `close` event will arrive).
             let hasSpawned = false;
-            let executionError;
             const armTimeoutAfterChildReady = () => {
                 if (spawnOptions.timeoutMs === undefined)
                     return;
@@ -207,6 +208,8 @@ export function createDefaultPiSpawnRunner(options) {
                 child.kill("SIGTERM");
             };
             parentSignal?.addEventListener("abort", terminateForParentAbort, { once: true });
+            const packageErrors = [];
+            let identityFailure;
             let identityRecorded = Promise.resolve();
             child.once("spawn", () => {
                 hasSpawned = true;
@@ -217,7 +220,10 @@ export function createDefaultPiSpawnRunner(options) {
                 if (typeof runDirectory === "string" &&
                     runDirectory !== "" &&
                     options.recordLaunchedPiIdentity !== undefined) {
-                    identityRecorded = options.recordLaunchedPiIdentity(runDirectory, piIdentity);
+                    identityRecorded = Promise.resolve().then(() => options.recordLaunchedPiIdentity(runDirectory, piIdentity)).catch((error) => {
+                        packageErrors.push(error);
+                        identityFailure = projectThrownFailureLeaf(error);
+                    });
                 }
             });
             child.stderr.setEncoding("utf8").on("data", (chunk) => {
@@ -227,8 +233,10 @@ export function createDefaultPiSpawnRunner(options) {
                 // A pre-spawn error has no child lifecycle to close. After spawn,
                 // retain the execution error and let the mandatory close event own
                 // cleanup and the single settlement.
-                if (settled || hasSpawned) {
-                    executionError = error;
+                if (settled)
+                    return;
+                if (hasSpawned) {
+                    packageErrors.push(error);
                     return;
                 }
                 if (timer !== undefined)
@@ -237,33 +245,43 @@ export function createDefaultPiSpawnRunner(options) {
                 settled = true;
                 reject(error);
             });
-            child.on("close", (code) => {
+            // `close` carries (code, signal): a signal-killed child reports code null.
+            // Both travel out so a signal death is never read as a clean exit.
+            child.on("close", (code, closeSignal) => {
                 if (timer !== undefined)
                     clearTimeout(timer);
                 parentSignal?.removeEventListener("abort", terminateForParentAbort);
-                void identityRecorded.then(() => {
+                void (async () => {
                     if (settled)
                         return;
                     settled = true;
-                    if (executionError !== undefined) {
-                        reject(executionError);
-                        return;
-                    }
-                    if (stdinDeliveryError !== undefined) {
-                        reject(stdinDeliveryError);
-                        return;
+                    await identityRecorded;
+                    if (stdinDeliveryError !== undefined)
+                        packageErrors.push(stdinDeliveryError);
+                    for (const error of packageErrors) {
+                        const diagnostic = `Pi transport handling failed beside host terminal: ${describeErrorIdentity(error)}`;
+                        const runDirectory = spawnOptions.env.AK_ROLE_RUN_DIR;
+                        if (runDirectory !== undefined) {
+                            await retainPackageFault({ runDirectory, diagnostic, error });
+                        }
+                        else {
+                            // Bare runner callers have no admitted artifact directory.
+                            try {
+                                process.stderr.write(`${diagnostic}\n`);
+                            }
+                            catch { /* Best-effort presentation beside the already closed child. */ }
+                        }
                     }
                     resolveResult({
                         code,
                         stderr,
                         timedOut,
+                        ...(closeSignal === null ? {} : { signal: closeSignal }),
+                        ...(code === 0 && !timedOut && closeSignal === null && identityFailure !== undefined
+                            ? { knownFailure: identityFailure }
+                            : {}),
                     });
-                }, (error) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    reject(error);
-                });
+                })();
             });
         });
     };

package/dist/public-cli/auto-resume.js

@@ -13,45 +13,46 @@
  */
 import { constants as fsConstants } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, open } from "node:fs/promises";
+import { open } from "node:fs/promises";
 import { join } from "node:path";
-import { roleRunArtifactsDirectory } from "../role-run-placement.js";
-import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRunResumable, markRunTerminal, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
+import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRunTerminal, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
 import { parseAutoResumeLimit } from "./config.js";
 import { processCancelSignalName } from "./process-cancel.js";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult } from "./terminal.js";
-import { attachRecordedSubmissions, presentFailureTerminal, resolveControlledFailureResumeObservation, } from "./settlement.js";
+import { attachRecordedSubmissions, ensureRealArtifactsDirectory, presentFailureTerminal, retainPackageFault, } from "./settlement.js";
+export { ensureRealArtifactsDirectory };
 import { serializeThrownValue } from "../serialize-thrown-value.js";
-import { errorText, isEnoent } from "../unknown-value.js";
+import { errorText } from "../unknown-value.js";
 const dummyIo = { stdout: () => { }, stderr: () => { } };
 /**
  * Persist run-state after a host-turn result, outside the retried dispatch try.
- * Lawful settlement always seals terminal — a typed 429 observation must not
- * win (#416 成功即停). 429 only marks resumable on the controlled-failure path.
- * Write failure must escape the retried dispatch try instead of becoming a
- * synthetic host-turn terminal.
+ * The host outcome already decided the terminal. This write only seals the run.
  */
-export async function persistReturnedRunState(admitted, options) {
-    if (options?.lawful === true) {
-        await markRunTerminal(admitted.runDirectory);
-        return;
-    }
-    const resumeObservation = await resolveControlledFailureResumeObservation({
-        runDirectory: admitted.runDirectory,
-    });
-    const typedHttp429 = resumeObservation.typedHttp429;
-    if (admitted.principal !== undefined && typedHttp429 !== undefined) {
-        await markRunResumable(admitted.runDirectory, typedHttp429);
-        return;
-    }
+export async function persistReturnedRunState(admitted) {
     await markRunTerminal(admitted.runDirectory);
 }
-function presentTerminal(terminal, io) {
-    if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
-        presentFailureTerminal(terminal, io);
+export async function presentTerminal(terminal, io, runDirectory, held) {
+    try {
+        if (held !== undefined) {
+            for (const value of held)
+                io.stdout(value);
+        }
+        else if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
+            presentFailureTerminal(terminal, io);
+        }
+        else {
+            io.stdout(formatTerminalResult(terminal));
+        }
     }
-    else {
-        io.stdout(formatTerminalResult(terminal));
+    catch (error) {
+        // Presentation consumes a settled report; it never reopens dispatch or
+        // replaces the host's cause, identity or open details.
+        await retainPackageFault({
+            runDirectory,
+            diagnostic: `terminal presentation failed beside host terminal: ${describeErrorIdentity(error)}`,
+            error,
+            stderr: (text) => io.stderr(text),
+        });
     }
 }
 /**
@@ -89,39 +90,6 @@ export class TurnDispatchedFailure extends Error {
 }
 /** Session custom-entry type carrying the pointer to one dispatch error file. */
 export const DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention";
-/**
- * #182-A hardened path identity, mirrored from settlement.ts's
- * ensureAuditEvidenceDirectory: a planted symlink at the run directory or the
- * artifacts path must not receive a durable run artifact (O_NOFOLLOW only
- * protects the final file name; recursive mkdir would accept a symlinked
- * parent). Fails loudly with the true cause instead. Shared by every caller
- * that needs a durable run-artifacts write independent of session/dossier
- * health — dispatch-error retention here, and post-admission's best-effort
- * cleanup diagnostic (#840 bounce class 2).
- */
-export async function ensureRealArtifactsDirectory(runDirectory) {
-    const runStat = await lstat(runDirectory);
-    if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
-        throw new Error("run artifact retention: run directory is not a real directory");
-    }
-    const artifactsDir = roleRunArtifactsDirectory(runDirectory);
-    try {
-        const existing = await lstat(artifactsDir);
-        if (existing.isSymbolicLink() || !existing.isDirectory()) {
-            throw new Error("run artifact retention: artifacts path is not a real directory");
-        }
-    }
-    catch (error) {
-        if (!isEnoent(error))
-            throw error;
-        await mkdir(artifactsDir, { recursive: true });
-        const created = await lstat(artifactsDir);
-        if (created.isSymbolicLink() || !created.isDirectory()) {
-            throw new Error("run artifact retention: artifacts directory is not a real directory");
-        }
-    }
-    return artifactsDir;
-}
 /** Cycle- and bigint-safe JSON replacer so serialization itself cannot drop data. */
 function jsonSafeReplacer() {
     const seen = new WeakSet();
@@ -406,12 +374,7 @@ export async function runWithAutoResumeLoop(options) {
             } }
         : terminal;
     if (complete !== undefined) {
-        if (isLawfulTypedTerminalOutcome(complete.roleOutcome)) {
-            options.io.stdout(formatTerminalResult(complete));
-        }
-        else {
-            presentTerminal(complete, options.io);
-        }
+        await presentTerminal(complete, options.io, options.admitted.runDirectory);
     }
     return stoppedResult === undefined
         ? { exitCode: 1, terminal: complete }

package/dist/public-cli/countersign-run.js

@@ -1,24 +1,11 @@
 import { readableGateItem } from "../readable-gate-item.js";
+import { currentReplyRows } from "./terminal.js";
 import { isRecord } from "../unknown-value.js";
 function isEscalatePayload(payload) {
     if (!isRecord(payload))
         return false;
     return (payload.status === "escalate");
 }
-/**
- * Rows a parent may read from a nested diarist terminal (#836 / #953).
- * Accepted/audit use role result payloads; failure history is submissions only.
- */
-function courtDiaristPayloadRows(roleOutcome, submissions) {
-    if (roleOutcome === undefined)
-        return submissions ?? [];
-    if (roleOutcome.kind === "accepted" || roleOutcome.kind === "audit_escalation") {
-        return roleOutcome.payloads ?? [];
-    }
-    if (roleOutcome.kind === "failure")
-        return submissions ?? [];
-    return [];
-}
 /**
  * Parent diagnostic for court-diarist escalate (#953 / 失败诚实 / 传话).
  * Relays diarist escalate payload(s) via readableGateItem — never invents
@@ -29,8 +16,8 @@ function courtDiaristPayloadRows(roleOutcome, submissions) {
  * no courtAttempt sole-filter on diarist). Same law as secretariat parent face:
  * every escalate receipt as-is, last = currentConclusion.
  */
-function courtDiaristEscalateDiagnostic(roleOutcome, submissions) {
-    const payloads = courtDiaristPayloadRows(roleOutcome, submissions);
+function courtDiaristEscalateDiagnostic(terminal) {
+    const payloads = currentReplyRows(terminal);
     const escalatePayloads = [];
     for (const payload of payloads) {
         if (isEscalatePayload(payload))
@@ -100,14 +87,13 @@ export async function invokeCourtDiarist(input, env, io) {
             : { hostAdapters: env.hostAdapters }),
     });
     const roleOutcome = result.terminal?.roleOutcome;
-    const submissions = result.terminal?.submissions;
     // Escalate routing is a boolean over the preserved sequence (#881). Reasons and
     // payload bodies stay on roleOutcome — never rewritten into a sole identity reason.
     if (latestPayloadEscalated(roleOutcome)) {
         return {
             identity: {
                 kind: "escalate",
-                diagnostic: courtDiaristEscalateDiagnostic(roleOutcome, submissions),
+                diagnostic: courtDiaristEscalateDiagnostic(result.terminal),
             },
             ...(result.admitted === undefined ? {} : { admitted: result.admitted }),
             ...(result.terminal === undefined ? {} : { terminal: result.terminal }),