@akagilnc/pi-workflow-roles 0.1.2397 → 0.1.2402

package/README.md

@@ -53,7 +53,7 @@ Receipts are typed, so callers compose roles without parsing prose; ordering and
 
 On completing-side submissions the package may spawn the Menxia province before the run settles: `gatekeeper` reads the subject and dispatches an officer (`inspector` or `notary`); existing auditor hooks stay where already wired. The gate runs inside the submission session; bounce means rewrite-and-resubmit in that same session — not role failure; the final receipt is the post-gate product. `planned` / `refused` / `unfinished` skip the province. Pointers only: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md). Gate history is projected into the typed TerminalResult: an optional menxia section lists the seats that actually sat, each dispatch round (officer, optional reason verbatim), and each officer report (seat, status, findings). Absent when no gate ran. Do not scrape session prose for gate status — read the typed section.
 
-When a labor-engine detour fails and the seat continues the labor on the main road, the typed receipt may carry a mechanical `engineLaborFallback` field: `{ engine, failure, laborBy: "seat" }`. It appears only after a real detour failure that fell back to seat labor—not on detour success or caller cancel. First failure wins for the activation; model-forged `engineLaborFallback` keys are stripped unless the package latch recorded one. Sole producer: `src/engine-labor-fallback.ts`; decision record: [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md). This README only projects that contract.
+When a labor-engine detour process fails to spawn, exits nonzero, or produces no usable output, the role run stops through the existing infrastructure-failure path with the original cause visible. The seat does not continue the labor or produce a typed Receipt. Caller cancellation continues to propagate unchanged. See [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md).
 
 ## Call the roles
 

package/README.zh-CN.md

@@ -53,7 +53,7 @@ ak-role config set-auto-resume-limit 3
 
 完成侧交卷时，包可能在本局结算前起门下省：`gatekeeper` 读受审物并派官（`inspector` 给事中或 `notary` 符宝郎）；既有审刑院挂钩仍在原位。闸在交卷 session 内运行；封驳＝当场重写重交，不是角色失败；最终回执即过闸产物。`planned`／`refused`／`unfinished` 不调省。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。闸史已投影进 typed 回执：可选 menxia 段列出实际在场席位、每轮派官（officer 与逐字 reason）与各官报告（席位/判决/findings）；无闸调用时该段缺席。勿刮 session 散文当闸状态——读 typed 段。
 
-当劳务引擎绕行失败、座席回到主路继续劳务时，typed 回执可带机械字段 `engineLaborFallback`：`{ engine, failure, laborBy: "seat" }`。仅在真实绕行失败并座席顶班后出现——成功绕行或调用方 cancel 不出现。同一次 activation 内先到先得；无包内 latch 时剥离模型伪造的 `engineLaborFallback` 键。唯一构造点：`src/engine-labor-fallback.ts`；决策记录：[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)。本文只投影该契约。
+劳务引擎绕行进程无法启动、非零退出或未产生可用输出时，角色运行沿既有基础设施失败路径立即停止并保留可见真因；座席不继续顶班，也不产出 typed 回执。调用方 cancel 仍原样传播。见 [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)。
 
 ## 调用百官
 

package/dist/doctor-contracts.js

@@ -1,6 +1,5 @@
 import { Type } from "typebox";
 import { canonicalJson } from "./canonical-json.js";
-import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "./engine-labor-fallback.js";
 import { openToolObjectFromUnion } from "./open-tool-schema.js";
 export const DOCTOR_EVIDENCE_TOOL_NAME = "ak_doctor_evidence";
 export const DOCTOR_OUTPUT_TOOL_NAME = "ak_doctor_output";
@@ -67,20 +66,14 @@ catch {
 } }
 export function validateDoctorSubmissionShape(value) {
     const status = read(value, "status");
-    const base = typeof status === "string" ? seatFallbackBaseStatus(status) : status;
-    if (base !== "completed" && base !== "refused")
+    if (status !== "completed" && status !== "refused")
         throw new DoctorSubmissionContractError("Doctor submission has no recognized execution status");
-    // ADR 0071: tainted status requires latch-shaped engineLaborFallback evidence.
-    if (typeof status === "string" && !seatFallbackStatusHasLawfulEvidence(status, value)) {
-        throw new DoctorSubmissionContractError("Doctor submission has no recognized execution status");
-    }
     return value;
 }
 export function validateRecordedDoctorOutput(value) {
     const output = validateDoctorSubmissionShape(value);
     const status = read(output, "status");
-    const base = typeof status === "string" ? seatFallbackBaseStatus(status) : status;
-    if (base === "completed" && read(output, "cost") === undefined)
+    if (status === "completed" && read(output, "cost") === undefined)
         throw new Error("Completed Doctor receipt has no runtime-owned cost testimony");
     return output;
 }

package/dist/engine-detour-tool.js

@@ -1,28 +1,12 @@
 import { Type } from "typebox";
 import { ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC, ENGINE_DETOUR_TOOL_NAME, engineDetourFailureDiagnostic, engineNameFromEnv, isEngineDetourFailure, runEngineDetourOnce, } from "./engine-detour.js";
-import { activationEngineLaborFallbackLatch, recordEngineLaborFallback, } from "./engine-labor-fallback.js";
 const engineDetourArgsSchema = Type.Object({
     argv: Type.Array(Type.String({ minLength: 1 }), {
         minItems: 1,
         description: "Executable argv for one engine subprocess. First element is the command (PATH lookup); remaining elements are arguments. Build argv from the host CLI actual interface for the configured engine name; when optional packaged notes are present in the session prompt, follow those bytes. Do not invent package flags.",
     }),
 }, { additionalProperties: false });
-function seatFallbackToolResult(field, failure) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Engine detour failed: ${failure}. Perform the labor in this session (seat main road) and submit via the existing typed path. A mechanical fallback declaration will attach to the typed receipt.`,
-            },
-        ],
-        details: {
-            tool: ENGINE_DETOUR_TOOL_NAME,
-            detourFailed: true,
-            ...field,
-        },
-    };
-}
-/** Caller/upper-layer cancel must propagate; process failure is seat-fallback, not cancel. */
+/** Caller/upper-layer cancellation must propagate unchanged. */
 function isCallerCancellation(error, signal) {
     if (signal?.aborted === true)
         return true;
@@ -37,8 +21,8 @@ function isCallerCancellation(error, signal) {
  * Build one once-latch detour tool definition for a configured engine name.
  * `latch` is shared so parent registration can reset between activations.
  * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
- * Engine process failure (nonzero/empty/spawn) soft-returns seat fallback (#380).
- * Caller AbortSignal cancel propagates without writing fallback.
+ * Engine process failures (nonzero/empty/spawn) stop via `fail` with their cause.
+ * Caller AbortSignal cancellation propagates unchanged.
  */
 export function createEngineDetourToolDefinition(input) {
     const latch = input.latch ?? { used: false };
@@ -52,7 +36,7 @@ export function createEngineDetourToolDefinition(input) {
             `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once for the configured engine (${engineName}). Optional packaged notes are guidance when present; a bare engine name alone is also a valid call path.`,
             "Pass argv for the host CLI of this engine name — first element is the executable name on PATH. Follow optional packaged notes when delivered; otherwise act from the engine name and the host CLI actual interface. Do not invent package flags.",
             "On success, use the returned stdout as labor content for the existing typed submission / report path.",
-            "On engine failure the tool returns a soft failure: continue labor in this session and submit via the existing typed path. Do not treat engine failure as a reason to withhold the typed receipt.",
+            "An engine process failure stops this activation; do not continue labor in this session.",
         ],
         parameters: engineDetourArgsSchema,
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
@@ -65,15 +49,6 @@ export function createEngineDetourToolDefinition(input) {
             if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
                 input.fail(new Error("engine detour argv must be a non-empty string array"), toolCallId, ctx);
             }
-            const softFail = (failure) => {
-                // Activation-scoped latch is the sole shared recorder (parent seat + legs).
-                const fallbackLatch = activationEngineLaborFallbackLatch() ?? { field: undefined };
-                const field = recordEngineLaborFallback(fallbackLatch, {
-                    engine: engineName,
-                    failure,
-                });
-                return seatFallbackToolResult(field, failure);
-            };
             let result;
             try {
                 result = await runEngineDetourOnce({
@@ -83,15 +58,15 @@ export function createEngineDetourToolDefinition(input) {
                 });
             }
             catch (error) {
-                // Caller cancel: propagate. Spawn/engine failure: seat fallback.
-                if (isCallerCancellation(error, signal)) {
+                if (isCallerCancellation(error, signal))
                     throw error;
-                }
-                const failure = error instanceof Error ? error.message : String(error);
-                return softFail(failure.trim() === "" ? "engine detour spawn failed" : failure);
+                const cause = error instanceof Error
+                    ? error
+                    : new Error(String(error).trim() || "engine detour spawn failed");
+                input.fail(cause, toolCallId, ctx);
             }
             if (isEngineDetourFailure(result)) {
-                return softFail(engineDetourFailureDiagnostic(result));
+                input.fail(new Error(engineDetourFailureDiagnostic(result)), toolCallId, ctx);
             }
             return {
                 content: [{ type: "text", text: result.stdout }],

package/dist/evidence-child-executor.js

@@ -475,14 +475,16 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
                     engine: engineName,
                     packageRoot: options.packageRoot,
                 });
-        // #378/#380: same detour tool as parent seat. Engine process failure soft-returns
-        // seat main-road fallback (ADR 0069 detour-rejoins-main-road); tool misuse still throws.
+        // Evidence legs use the parent detour tool; retain any engine process cause
+        // so the enclosing child boundary, rather than a tool-error result, terminates.
+        let engineDetourFailure;
         const engineDetourTool = engineName === undefined
             ? undefined
             : createEngineDetourToolDefinition({
                 engineName,
                 fail(error) {
-                    throw error instanceof Error ? error : new Error(String(error));
+                    engineDetourFailure ??= error instanceof Error ? error : new Error(String(error));
+                    throw engineDetourFailure;
                 },
             });
         // No tools allowlist — Pi defaults + unrestricted evidence surface (ADR 0064).
@@ -521,8 +523,14 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
                 await session.prompt(delivered);
             }
             catch (error) {
+                if (engineDetourFailure !== undefined) {
+                    throw classifiedError(engineDetourFailure, "child");
+                }
                 throw classifiedError(error, "provider");
             }
+            if (engineDetourFailure !== undefined) {
+                throw classifiedError(engineDetourFailure, "child");
+            }
             if (signal?.aborted)
                 throw new Error("Evidence child was cancelled");
             const lastAssistant = [...session.messages]

package/dist/merger-contracts.js

@@ -1,7 +1,6 @@
 import { Type } from "typebox";
 import { isFullGitObjectId } from "./git-object-id.js";
 import { exactUtf8 } from "./exact-utf8.js";
-import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "./engine-labor-fallback.js";
 import { sha256Hex } from "./sha256.js";
 import { openToolObjectFromUnion } from "./open-tool-schema.js";
 const oidPattern = "^(?:[0-9a-f]{40}|[0-9a-f]{64})$";
@@ -70,14 +69,9 @@ export function validateMergerOutput(value, expectedAttemptId) {
     if (!record(value) || (expectedAttemptId !== undefined && value.attemptId !== expectedAttemptId))
         throw new Error("Merger output attempt mismatch");
     const status = typeof value.status === "string" ? value.status : undefined;
-    const statusBase = status !== undefined ? seatFallbackBaseStatus(status) : undefined;
-    // ADR 0071: tainted status requires latch-shaped engineLaborFallback evidence.
-    if (status !== undefined && !seatFallbackStatusHasLawfulEvidence(status, value)) {
-        throw new Error("Merger output has no recognized execution discriminator");
-    }
-    if (statusBase === "completed" && isFullGitObjectId(value.mergeCommitId))
+    if (status === "completed" && isFullGitObjectId(value.mergeCommitId))
         return structuredClone(value);
-    if (statusBase === "escalate")
+    if (status === "escalate")
         return structuredClone(value);
     throw new Error("Merger output has no recognized execution discriminator");
 }

package/dist/navigator-attendance.js

@@ -6,7 +6,6 @@ import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
-import { seatFallbackBaseStatus } from "./engine-labor-fallback.js";
 import {
   NAVIGATOR_INVOCATION_ENTRY,
   mintNavigatorInvocationId
@@ -258,13 +257,6 @@ function createNavigatorPrepareTool(onOutput) {
     }
   };
 }
-function statusListMatchesSettlement(candidateStatuses, settlementStatus) {
-  if (candidateStatuses.includes(settlementStatus)) return true;
-  const settlementBase = seatFallbackBaseStatus(settlementStatus);
-  return candidateStatuses.some(
-    (status) => seatFallbackBaseStatus(status) === settlementBase
-  );
-}
 function selectNavigatorCandidate(candidates, settlement) {
   if (settlement.kind !== "accepted") return void 0;
   const usable = candidates.filter((candidate) => candidate.next !== void 0);
@@ -275,7 +267,7 @@ function selectNavigatorCandidate(candidates, settlement) {
   if (rolePhaseMatched.length > 0) {
     if (settlement.status !== void 0) {
       const statusSpecific = rolePhaseMatched.find(
-        (candidate) => candidate.matches?.statuses !== void 0 && statusListMatchesSettlement(candidate.matches.statuses, settlement.status)
+        (candidate) => candidate.matches?.statuses !== void 0 && candidate.matches.statuses.includes(settlement.status)
       );
       if (statusSpecific !== void 0) {
         return { candidate: statusSpecific, matchedToSettlement: true };

package/dist/notary-contracts.js

@@ -4,7 +4,6 @@
  * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
  */
 import { Type } from "typebox";
-import { readActivationEngineLaborFallbackField, seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, withEngineLaborFallbackField, } from "./engine-labor-fallback.js";
 import { openToolObject } from "./open-tool-schema.js";
 export const NOTARY_OUTPUT_TOOL_NAME = "ak_notary_output";
 export const NOTARY_ACCEPTED_TEXT = "Notary output accepted";
@@ -42,10 +41,10 @@ export function validateNotaryOutput(value) {
         throw new Error("Notary output has no recognized execution discriminator");
     }
     const statusRaw = typeof value.status === "string" ? value.status : undefined;
-    if (statusRaw === undefined || !seatFallbackStatusHasLawfulEvidence(statusRaw, value)) {
+    if (statusRaw === undefined) {
         throw new Error("Notary output has no recognized execution discriminator");
     }
-    const status = seatFallbackBaseStatus(statusRaw);
+    const status = statusRaw;
     if (status === "bounce") {
         const clone = structuredClone(value);
         if (clone.disposition === undefined)
@@ -62,15 +61,11 @@ export function validateNotaryOutput(value) {
     }
     throw new Error("Notary output has no recognized execution discriminator");
 }
-/** Shape check for recorded accepted details (may include engineLaborFallback). */
 export function validateRecordedNotaryOutput(value) {
     return validateNotaryOutput(value);
 }
-export function withNotaryAcceptedDetails(output) {
-    return withEngineLaborFallbackField(output, readActivationEngineLaborFallbackField());
-}
 export function notaryDecisiveFacts(output) {
-    const status = seatFallbackBaseStatus(String(output.status));
+    const status = String(output.status);
     const facts = { status, officer: "notary" };
     if (status === "pass" || status === "bounce") {
         const findings = output.findings;

package/dist/package-contracts/judge-output.js

@@ -1,5 +1,4 @@
 /** Package-owned Judge output leaf — no role registration surface. */
-import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "../engine-labor-fallback.js";
 export const JUDGE_OUTPUT_TOOL_NAME = "ak_judge_output";
 export const JUDGE_ACCEPTED_TEXT = "Judge verdict accepted";
 export function validateAcceptedJudgeDetails(verdict) {
@@ -15,9 +14,7 @@ export function validateAcceptedJudgeDetails(verdict) {
     if (typeof judgeStatus !== "string") {
         throw new Error("Judge verdict has no execution discriminator");
     }
-    const base = seatFallbackBaseStatus(judgeStatus);
-    if (["converged", "continue", "escalate"].includes(base) &&
-        seatFallbackStatusHasLawfulEvidence(judgeStatus, verdict)) {
+    if (["converged", "continue", "escalate"].includes(judgeStatus)) {
         return verdict;
     }
     throw new Error("Judge verdict has no execution discriminator");

package/dist/package-contracts/reviewer-output.js

@@ -1,5 +1,4 @@
 /** Package-owned Reviewer intent and runtime-receipt leaves — no role registration surface. */
-import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "../engine-labor-fallback.js";
 export const REVIEWER_OUTPUT_TOOL_NAME = "ak_reviewer_output";
 export const REVIEWER_ACCEPTED_TEXT = "Reviewer report accepted";
 function isRecord(value) {
@@ -46,10 +45,6 @@ export function validateReviewerIntent(output) {
 /** Validate runtime-owned facts at their real identity seams (target pins + plain text). */
 export function validateRuntimeReviewerReceipt(output) {
     const status = read(output, "status");
-    // ADR 0071: tainted top-level status requires latch-shaped engineLaborFallback evidence.
-    if (typeof status === "string" && !seatFallbackStatusHasLawfulEvidence(status, output)) {
-        throw new Error("Reviewer receipt has no recognized execution discriminator");
-    }
     const acceptedBatch = read(output, "acceptedBatch");
     const identities = read(output, "identities");
     const construction = read(identities, "construction");
@@ -118,8 +113,7 @@ export function projectReviewerIntentToReceipt(intentValue, receiptValue) {
     const intent = validateReviewerIntent(intentValue);
     const receipt = validateRuntimeReviewerReceipt(receiptValue);
     const receiptStatus = String(receipt.status);
-    const receiptBase = seatFallbackBaseStatus(receiptStatus);
-    if (receiptBase !== intent.status || (intent.status === "completed" ? receipt.diagnostic !== undefined : receipt.diagnostic !== intent.diagnostic)) {
+    if (receiptStatus !== intent.status || (intent.status === "completed" ? receipt.diagnostic !== undefined : receipt.diagnostic !== intent.diagnostic)) {
         throw new Error("Reviewer intent and runtime receipt disagree");
     }
     return receipt;

package/dist/package-contracts/terminating-tools.js

@@ -6,7 +6,6 @@ import { COLLECTOR_ACCEPTED_TEXT, COLLECTOR_OUTPUT_TOOL, validateAcceptedCollect
 import { JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, validateAcceptedJudgeDetails, } from "./judge-output.js";
 import { REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, projectReviewerIntentToReceipt, validateReviewerIntent, validateRuntimeReviewerReceipt, } from "./reviewer-output.js";
 import { isAuditEscalationResult } from "../audit-escalation.js";
-import { seatFallbackBaseStatus, seatFallbackStatusHasLawfulEvidence, } from "../engine-labor-fallback.js";
 import { DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput } from "../doctor-contracts.js";
 import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput } from "../merger-contracts.js";
 import { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, validateRecordedNotaryOutput } from "../notary-contracts.js";
@@ -85,14 +84,10 @@ export function validateAcceptedDetails(toolName, details) {
         [NOTARY_OUTPUT_TOOL_NAME]: ["pass", "bounce"],
     };
     const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
-    const baseDiscriminator = typeof discriminator === "string" ? seatFallbackBaseStatus(discriminator) : discriminator;
-    // ADR 0071: `-by-fallback` is not independently lawful — require latch-shaped evidence.
-    const taintedWithoutEvidence = typeof discriminator === "string" &&
-        !seatFallbackStatusHasLawfulEvidence(discriminator, details);
+    const baseDiscriminator = discriminator;
     const runtimeBindingMissing = (toolName === DOCTOR_OUTPUT_TOOL_NAME && baseDiscriminator === "completed" && !(candidate?.cost !== null && typeof candidate?.cost === "object")) ||
         (toolName === REVIEWER_OUTPUT_TOOL_NAME && candidate?.version !== 2);
-    if (taintedWithoutEvidence ||
-        runtimeBindingMissing ||
+    if (runtimeBindingMissing ||
         (!collectorDiscriminator && (typeof discriminator !== "string" || !lawfulStatuses[toolName].includes(baseDiscriminator)))) {
         throw new AcceptedDetailsContractError("terminating receipt has no recognized execution discriminator");
     }
@@ -126,13 +121,13 @@ export function validateAcceptedLifecycle(toolName, argumentsValue, detailsValue
     const details = validateAcceptedDetails(toolName, detailsValue);
     if (toolName === DOCTOR_OUTPUT_TOOL_NAME) {
         const testimony = validateDoctorSubmissionShape(argumentsValue);
-        if (seatFallbackBaseStatus(String(testimony.status)) === "refused") {
+        if ((String(testimony.status)) === "refused") {
             if (!deepEqual(testimony, details))
                 throw new Error("accepted tool lifecycle details mismatch");
             return details;
         }
         const receipt = details;
-        if (seatFallbackBaseStatus(String(receipt.status)) !== "completed") {
+        if ((String(receipt.status)) !== "completed") {
             throw new Error("accepted tool lifecycle details mismatch");
         }
         const { cost: _runtimeCost, ...projected } = receipt;
@@ -156,7 +151,7 @@ export function acceptedFacts(toolName, details) {
         case MERGER_OUTPUT_TOOL_NAME: {
             const output = details;
             const status = output.status;
-            return { status, ...(seatFallbackBaseStatus(status) === "completed" && typeof output.mergeCommitId === "string" ? { commit: output.mergeCommitId } : {}) };
+            return { status, ...(status === "completed" && typeof output.mergeCommitId === "string" ? { commit: output.mergeCommitId } : {}) };
         }
         case COLLECTOR_OUTPUT_TOOL:
             return { status: "collected" };