@akagilnc/pi-workflow-roles 0.1.4673 → 0.1.4698

package/src/public-cli/terminal.ts

@@ -78,7 +78,11 @@ export type TerminalRoleOutcome =
       /** Original diagnostic identity retained for the caller. */
       diagnostic: string;
       decisiveFacts: Readonly<Record<string, unknown>>;
-      /** Already-recorded original payloads, coexist with host failure (#836 A3). */
+      /**
+       * Optional current-failure payloads (rare intentional face, e.g. reviewer
+       * child terminals). Run history does not live here — #836 / #953 keep it
+       * on TerminalResult.submissions so receivers can tell it from this failure.
+       */
       payloads?: readonly unknown[];
     };
 
@@ -165,13 +169,31 @@ export type TerminalGateFact = {
  * auto-resumes occurred during this single LLM call; it is not persisted to
  * run-state.json and does not participate in limit decisions.
  */
-/** Original payloads on a terminal — role result for accepted/audit; coexist on failure. */
+/**
+ * Current-result payloads on a terminal — accepted/audit role result, or a
+ * rare intentional failure face. Run history is TerminalResult.submissions
+ * (#836 / #953), not this helper.
+ */
 export function roleResultPayloads(outcome: TerminalRoleOutcome): readonly unknown[] {
   if (outcome.kind === "accepted" || outcome.kind === "audit_escalation") return outcome.payloads ?? [];
   if (outcome.kind === "failure") return outcome.payloads ?? [];
   return [];
 }
 
+/**
+ * Prefer non-empty current-result payloads; an empty array must not shadow
+ * top-level submissions (#953 / #836). Callers that need failure history must
+ * read TerminalResult.submissions directly — do not coalesce into failure.payloads.
+ */
+export function coalesceSubmissionRows(
+  payloads: readonly unknown[] | undefined,
+  submissions: readonly unknown[] | undefined,
+): readonly unknown[] {
+  if (payloads !== undefined && payloads.length > 0) return payloads;
+  if (submissions !== undefined && submissions.length > 0) return submissions;
+  return payloads ?? submissions ?? [];
+}
+
 export type TerminalResult = {
   roleOutcome: TerminalRoleOutcome;
   /** Default Reviewer parent: original child Terminals, keyed by frozen axis. */
@@ -187,8 +209,9 @@ export type TerminalResult = {
   navigator: TerminalNavigatorFact;
   artifacts: readonly TerminalArtifactRef[];
   /**
-   * Mirror of recorded original payloads (same bytes as roleOutcome.payloads).
-   * Kept so officer/compliance readers share one array with the role-result block.
+   * Run-scoped recorded submission history (#836). For accepted/audit this often
+   * mirrors roleOutcome.payloads; for failure it is the sole historical carrier
+   * (#953 — not copied onto failure.payloads).
    */
   submissions?: readonly unknown[];
   /**
@@ -316,16 +339,28 @@ export function formatTerminalResult(result: TerminalResult): string {
   }
   // Role-result block: original payloads, newest first for humans (#961).
   // Typed payloads/submissions stay ledger order; only this presentation reverses.
-  const payloads =
-    result.roleOutcome.kind === "accepted" || result.roleOutcome.kind === "audit_escalation"
-      ? result.roleOutcome.payloads ?? result.submissions ?? []
-      : result.roleOutcome.kind === "failure"
-        ? result.roleOutcome.payloads ?? result.submissions ?? []
+  // #953: failure history is the top-level submissions carrier (#836) — present
+  // as recorded-submission, never as this-turn submission/receipt.
+  if (result.roleOutcome.kind === "failure") {
+    const recorded = result.submissions ?? [];
+    for (let i = recorded.length - 1; i >= 0; i -= 1) {
+      const payload = recorded[i]!;
+      const rendered =
+        typeof payload === "string" ? payload : JSON.stringify(payload);
+      lines.push(`recorded-submission\t${encodeTerminalField(rendered)}`);
+    }
+  } else {
+    const payloads =
+      result.roleOutcome.kind === "accepted" ||
+      result.roleOutcome.kind === "audit_escalation"
+        ? coalesceSubmissionRows(result.roleOutcome.payloads, result.submissions)
         : result.submissions ?? [];
-  for (let i = payloads.length - 1; i >= 0; i -= 1) {
-    const payload = payloads[i]!;
-    const rendered = typeof payload === "string" ? payload : JSON.stringify(payload);
-    lines.push(`submission\t${encodeTerminalField(rendered)}`);
+    for (let i = payloads.length - 1; i >= 0; i -= 1) {
+      const payload = payloads[i]!;
+      const rendered =
+        typeof payload === "string" ? payload : JSON.stringify(payload);
+      lines.push(`submission\t${encodeTerminalField(rendered)}`);
+    }
   }
   return `${lines.join("\n")}\n`;
 }

package/src/role-runtime.ts

@@ -37,6 +37,7 @@ import {
 } from "./engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "./package-resources/engine-material.ts";
 import { registerEngineDetourTool } from "./engine-detour-tool.ts";
+import { readableGateItem } from "./readable-gate-item.ts";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
 import type { AnyCanonicalSkillBinding } from "./canonical-skill-binding.ts";
@@ -1226,18 +1227,15 @@ export function createSecretariatRoleRuntime(
                   : { packageRoot: dependencies.packageRoot }),
               });
           const details = projectSecretariatSummonResult(summoned);
-          const outcomeKind =
-            typeof details.outcomeKind === "string" ? details.outcomeKind : "unknown";
-          const contentText =
-            outcomeKind === "accepted" || outcomeKind === "audit_escalation"
-              ? "给事中回执已送达中书省"
-              : outcomeKind === "failure"
-                ? "给事中传召失败"
-                : outcomeKind === "no_receipt"
-                  ? "给事中无回执"
-                  : "给事中传召未得终局";
+          // #953 / #775: parent-visible text from typed details via readableGateItem
+          // sole source — payloads + receipt (latest) already carry 传话 facts.
           return {
-            content: [{ type: "text" as const, text: contentText }],
+            content: [
+              {
+                type: "text" as const,
+                text: readableGateItem(details),
+              },
+            ],
             details,
           };
         },

package/src/run-terminal-artifacts.ts

@@ -170,6 +170,7 @@ export function runIdFromRunDirectory(runDirectory: string): string | undefined
  * Shared parent-directory unique fallback may be adopted only when the
  * publisher-owned body.runId equals this run directory's runId. Same-run
  * artifactsDir / runDirectory candidates keep path ownership and skip this.
+ * expectedRunId undefined (unparseable run dir) → never bound.
  */
 function presentUniqueFallbackBoundToRun(
   body: Record<string, unknown>,
@@ -180,51 +181,103 @@ function presentUniqueFallbackBoundToRun(
 }
 
 /**
- * Read the first present typed terminal artifact for a run directory.
- * Order:
+ * Sole authority for seam-owned unique error.<uuid>.json candidates.
+ * Used by both clearOpposite (settlement) and readRunTerminalArtifact — do not
+ * re-enumerate the same-run / parent unique set elsewhere.
+ * Ownership:
+ * - same-run dirs (artifacts/, runDir): path ownership — all unique names
+ * - parent runs/: only body.runId-bound faces; unparseable runId or unreadable body → none
+ */
+export async function listSeamOwnedUniqueErrorFacePaths(
+  runDirectory: string,
+): Promise<readonly string[]> {
+  const artifactsDir = roleRunArtifactsDirectory(runDirectory);
+  const owned: string[] = await listUniqueErrorFallbackPaths([
+    artifactsDir,
+    runDirectory,
+  ]);
+  const expectedRunId = runIdFromRunDirectory(runDirectory);
+  for (const path of await listUniqueErrorFallbackPaths([dirname(runDirectory)])) {
+    const read = await readTerminalArtifactAtPath(path, "error.json");
+    if (read === undefined || read.status !== "present") continue;
+    if (!presentUniqueFallbackBoundToRun(read.body, expectedRunId)) continue;
+    owned.push(path);
+  }
+  return owned;
+}
+
+type PresentOrUnreadable = Exclude<RunTerminalArtifactRead, { status: "absent" }>;
+
+/**
+ * Publish contract (#953): only failure publish continues after clearOpposite
+ * failure, so a multi-class residue (residual report/audit beside a new error
+ * face) means the current settlement is failure. Prefer failure-class faces
+ * over success/audit — never filesystem mtime (copy/restore/utimes can lie).
+ */
+function failureClassRank(file: RunTerminalArtifactFile): number {
+  return file === "error.json" ? 1 : 0;
+}
+
+/**
+ * Read the current typed terminal artifact for a run directory.
+ *
+ * Candidate set (publisher-owned faces only):
  * 1) conventional artifacts/{report,error,audit-incomplete}.json
  * 2) publisher fixed failure fallbacks (error.settlement.json faces)
- * 3) publisher unique error.<uuid>.json fallbacks under same-run dirs
- * 4) shared parent-directory unique fallbacks bound by body.runId
+ * 3) seam-owned unique error.<uuid>.json via listSeamOwnedUniqueErrorFacePaths
+ *    (same-run path ownership + parent body.runId binding — shared with clear)
+ *
+ * Invariant: when more than one present face remains (e.g. clearOpposite failed
+ * during failure publish and a fallback was settled beside a residual report),
+ * adopt failure-class over success/audit by the publish contract — not mtime.
+ * Same-class ties keep candidate enumeration order (conventional before
+ * fallbacks before unique).
  *
- * Absence of every known durable face is a valid no-receipt state (not unreadable).
- * A present file that cannot be parsed as a usable typed JSON object is unreadable.
+ * Unreadable faces never outrank a present face. Parent unique unreadable
+ * files never enter the shared enumerator (cannot prove run identity).
+ * Absence of every known durable face is a valid no-receipt state.
  */
 export async function readRunTerminalArtifact(
   runDirectory: string,
 ): Promise<RunTerminalArtifactRead> {
   const artifactsDir = roleRunArtifactsDirectory(runDirectory);
+  const present: Array<Extract<PresentOrUnreadable, { status: "present" }>> = [];
+  const unreadable: Array<Extract<PresentOrUnreadable, { status: "unreadable" }>> =
+    [];
+
+  const consider = (read: RunTerminalArtifactRead | undefined): void => {
+    if (read === undefined || read.status === "absent") return;
+    if (read.status === "present") {
+      present.push(read);
+      return;
+    }
+    unreadable.push(read);
+  };
+
   for (const file of RUN_TERMINAL_ARTIFACT_FILES) {
-    const path = join(artifactsDir, file);
-    const read = await readTerminalArtifactAtPath(path, file);
-    if (read !== undefined) return read;
+    consider(await readTerminalArtifactAtPath(join(artifactsDir, file), file));
   }
 
-  // Publisher settled a durable failure outside the conventional error.json name.
   for (const relative of RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS) {
-    const path = join(runDirectory, relative);
-    const read = await readTerminalArtifactAtPath(path, "error.json");
-    if (read !== undefined) return read;
+    consider(
+      await readTerminalArtifactAtPath(join(runDirectory, relative), "error.json"),
+    );
   }
 
-  // Same-run unique faces: path ownership is the run itself — no cross-run risk.
-  for (const path of await listUniqueErrorFallbackPaths([artifactsDir, runDirectory])) {
-    const read = await readTerminalArtifactAtPath(path, "error.json");
-    if (read !== undefined) return read;
+  // Unique same-run + parent-bound faces: one enumerator shared with clear.
+  for (const path of await listSeamOwnedUniqueErrorFacePaths(runDirectory)) {
+    consider(await readTerminalArtifactAtPath(path, "error.json"));
   }
 
-  // Shared parent (runs/) unique faces: require publisher runId binding.
-  const expectedRunId = runIdFromRunDirectory(runDirectory);
-  for (const path of await listUniqueErrorFallbackPaths([dirname(runDirectory)])) {
-    const read = await readTerminalArtifactAtPath(path, "error.json");
-    if (read === undefined) continue;
-    if (read.status === "present") {
-      if (!presentUniqueFallbackBoundToRun(read.body, expectedRunId)) continue;
-      return read;
-    }
-    // Unreadable parent unique file cannot prove run identity — do not adopt.
+  if (present.length > 0) {
+    present.sort(
+      (a, b) => failureClassRank(b.file) - failureClassRank(a.file),
+    );
+    return present[0]!;
+  }
+  if (unreadable.length > 0) {
+    return unreadable[0]!;
   }
-
   return { status: "absent" };
 }
 

package/src/secretariat-role.ts

@@ -128,6 +128,8 @@ function latestObjectPayload(
  * Project nested countersign PublicSummonResult onto tool details.
  * Authority: keep typed terminal kind + payloads/diagnostic intact (gatekeeper
  * projectOfficerTerminal precedent / ADR 0052 / 失败诚实). No content gate.
+ * Parent-visible text uses this details object via readableGateItem directly
+ * (#953 — no second isomorphic projection).
  */
 export function projectSecretariatSummonResult(
   summoned: PublicSummonResult,
@@ -178,7 +180,11 @@ export function projectSecretariatSummonResult(
   }
 
   if (roleOutcome.kind === "failure") {
-    const payloads = Array.isArray(roleOutcome.payloads) ? roleOutcome.payloads : undefined;
+    // #953: current failure face is diagnostic/cause/decisiveFacts only.
+    // Historical receipts ride terminal.submissions — never as receipt/payloads.
+    const submissions = Array.isArray(terminal?.submissions)
+      ? terminal.submissions
+      : undefined;
     return {
       ...base,
       outcomeKind: "failure",
@@ -187,10 +193,9 @@ export function projectSecretariatSummonResult(
       ...(roleOutcome.decisiveFacts === undefined
         ? {}
         : { decisiveFacts: roleOutcome.decisiveFacts }),
-      ...(payloads === undefined ? {} : { payloads }),
-      ...(latestObjectPayload(payloads) === undefined
+      ...(submissions === undefined || submissions.length === 0
         ? {}
-        : { receipt: latestObjectPayload(payloads) }),
+        : { submissions }),
     };
   }