@akagilnc/pi-workflow-roles 0.1.5406 → 0.1.5475

package/src/packaged-role-registry.ts

@@ -96,7 +96,6 @@ export 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. */
@@ -214,7 +213,6 @@ export 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" },
@@ -309,10 +307,7 @@ export 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: [
@@ -489,7 +484,6 @@ export 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"],
@@ -504,7 +498,6 @@ export 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"],
   },
@@ -527,7 +520,6 @@ export const PUBLIC_ROLE_RECORDS = [
     settlement: "accepted",
     /** Court reask replaces the initial prompt. */
     reaskPrompt: true,
-    runnerFailure: "engine-detour-record-first",
     gateStageLabel: "审刑院",
     /** Gate summon binds --subject judge and --source-run. */
     gateSummon: "subject-source",
@@ -630,7 +622,7 @@ export type PackagedActivationFlag = {
 };
 
 /**
- * Output tool for seats whose settlement leaf is the shared accepted-tool scan.
+ * Output tool for seats whose settlement leaf is the accepted ledger.
  * Any other settlement leaf names that seat's own reader.
  */
 export function packagedRoleAcceptedOutputTool(role: string): string | undefined {

package/src/pi/adapter.ts

@@ -194,9 +194,6 @@ export function createPiRoleHostAdapter(
       } else if (registration[0] === "session_shutdown") {
         const [, handler] = registration;
         pi.on("session_shutdown", (_value, ctx) => handler({}, context(ctx)));
-      } else if (registration[0] === "after_provider_response") {
-        const [, handler] = registration;
-        pi.on("after_provider_response", (value, ctx) => handler({ status: value.status }, context(ctx)));
       } else if (registration[0] === "agent_end") {
         const [, handler] = registration;
         pi.on("agent_end", (value, ctx) => handler({

package/src/pi/role-turn-host.ts

@@ -25,6 +25,8 @@ import { ExplicitInternalActivationError } from "../host-contracts.ts";
 import { applyEngineChildEnv, ENGINE_MODEL_FLAG_NAME, normalizeEngineName } from "../engine-detour.ts";
 import { projectActivationFlags } from "../role-activation-flags.ts";
 import { encodeUserDialogueStdin } from "../user-dialogue-stdin.ts";
+import { projectThrownFailureLeaf, retainPackageFault } from "../public-cli/settlement.ts";
+import { describeErrorIdentity } from "../public-cli/run-lifecycle.ts";
 import { RECEIPT_DELIVERY_LIMIT_ENV } from "../receipt-delivery-policy.ts";
 
 /** Package-relative Internal role entrypoint (ADR 0052; same path as public-cli registry). */
@@ -156,6 +158,7 @@ export type PiSpawnRunner = (
   code: number | null;
   stderr: string;
   timedOut: boolean;
+  signal?: string;
   knownFailure?: RoleTurnKnownFailure;
 }>;
 
@@ -287,7 +290,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: Error | undefined;
       const armTimeoutAfterChildReady = (): void => {
         if (spawnOptions.timeoutMs === undefined) return;
         timer = setTimeout(() => {
@@ -302,6 +304,8 @@ export function createDefaultPiSpawnRunner(options: {
         child.kill("SIGTERM");
       };
       parentSignal?.addEventListener("abort", terminateForParentAbort, { once: true });
+      const packageErrors: unknown[] = [];
+      let identityFailure: RoleTurnKnownFailure | undefined;
       let identityRecorded: Promise<void> = Promise.resolve();
       child.once("spawn", () => {
         hasSpawned = true;
@@ -313,7 +317,12 @@ export function createDefaultPiSpawnRunner(options: {
           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) => {
@@ -323,8 +332,9 @@ 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) clearTimeout(timer);
@@ -332,33 +342,37 @@ 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(
-          () => {
-            if (settled) return;
-            settled = true;
-            if (executionError !== undefined) {
-              reject(executionError);
-              return;
+        void (async () => {
+          if (settled) return;
+          settled = true;
+          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. */ }
             }
-            if (stdinDeliveryError !== undefined) {
-              reject(stdinDeliveryError);
-              return;
-            }
-            resolveResult({
-              code,
-              stderr,
-              timedOut,
-            });
-          },
-          (error) => {
-            if (settled) return;
-            settled = true;
-            reject(error);
-          },
-        );
+          }
+          resolveResult({
+            code,
+            stderr,
+            timedOut,
+            ...(closeSignal === null ? {} : { signal: closeSignal }),
+            ...(code === 0 && !timedOut && closeSignal === null && identityFailure !== undefined
+              ? { knownFailure: identityFailure }
+              : {}),
+          });
+        })();
       });
     });
   };

package/src/prepared-role-turn.ts

@@ -37,6 +37,8 @@ export type PreparedRoleTurn = Readonly<{
     }
     | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
   >;
+  /** Drain required shutdown work. Its failures throw; ordinary transport
+   * cleanup is reported by its owner without rejecting this drain. */
   dispose?(): Promise<void>;
   /**
    * Headless CLI family (#645): role terminating-tool schema for host-native

package/src/public-cli/auto-resume.ts

@@ -13,10 +13,8 @@
  */
 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.ts";
 import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
@@ -26,7 +24,6 @@ import {
   AUTO_RESUME_LIMIT,
   describeErrorIdentity,
   acquireRunWriterLease,
-  markRunResumable,
   markRunTerminal,
   RunWriterLeaseHeldError,
   type RunWriterLease,
@@ -36,47 +33,47 @@ import { processCancelSignalName } from "./process-cancel.ts";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
 import {
   attachRecordedSubmissions,
+  ensureRealArtifactsDirectory,
   presentFailureTerminal,
-  resolveControlledFailureResumeObservation,
+  retainPackageFault,
 } from "./settlement.ts";
+
+export { ensureRealArtifactsDirectory };
 import type { CliIo } from "./cli-io.ts";
 import { serializeThrownValue } from "../serialize-thrown-value.ts";
 
-import { errorText, isEnoent } from "../unknown-value.ts";
+import { errorText } from "../unknown-value.ts";
 
 const dummyIo: CliIo = { 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: { runDirectory: string; principal?: DurablePrincipal },
-  options?: { readonly lawful?: boolean },
+  admitted: { runDirectory: string },
 ): Promise<void> {
-  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;
-  }
   await markRunTerminal(admitted.runDirectory);
 }
 
-function presentTerminal(terminal: TerminalResult, io: CliIo): void {
-  if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
-    presentFailureTerminal(terminal, io);
-  } else {
-    io.stdout(formatTerminalResult(terminal));
+export async function presentTerminal(terminal: TerminalResult, io: CliIo, runDirectory: string, held?: readonly string[]): Promise<void> {
+  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));
+    }
+  } 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),
+    });
   }
 }
 
@@ -144,38 +141,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" as const;
 
-/**
- * #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: string): Promise<string> {
-  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(): (key: string, value: unknown) => unknown {
   const seen = new WeakSet<object>();
@@ -563,11 +528,7 @@ export async function runWithAutoResumeLoop<
     } } as TerminalResult
     : 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 } as T

package/src/public-cli/countersign-run.ts

@@ -7,7 +7,7 @@ import { readableGateItem } from "../readable-gate-item.ts";
 import type { AdmittedCountersignInvocation } from "./invocation.ts";
 import type { PostAdmissionEnv } from "./post-admission.ts";
 import type { CliIo } from "./cli-io.ts";
-import type { TerminalRoleOutcome } from "./terminal.ts";
+import { currentReplyRows, type TerminalResult, type TerminalRoleOutcome } from "./terminal.ts";
 
 import { isRecord } from "../unknown-value.ts";
 
@@ -60,22 +60,6 @@ function isEscalatePayload(payload: unknown): boolean {
   );
 }
 
-/**
- * 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: TerminalRoleOutcome | undefined,
-  submissions: readonly unknown[] | undefined,
-): readonly unknown[] {
-  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
@@ -87,10 +71,9 @@ function courtDiaristPayloadRows(
  * every escalate receipt as-is, last = currentConclusion.
  */
 function courtDiaristEscalateDiagnostic(
-  roleOutcome: TerminalRoleOutcome | undefined,
-  submissions?: readonly unknown[],
+  terminal: TerminalResult | undefined,
 ): string {
-  const payloads = courtDiaristPayloadRows(roleOutcome, submissions);
+  const payloads = currentReplyRows(terminal);
   const escalatePayloads: unknown[] = [];
   for (const payload of payloads) {
     if (isEscalatePayload(payload)) escalatePayloads.push(payload);
@@ -183,14 +166,13 @@ export async function invokeCourtDiarist(
   });
 
   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 }),