@akagilnc/pi-workflow-roles 0.1.5079 → 0.1.5122

package/dist/public-cli/post-admission.js

@@ -8,13 +8,13 @@
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
-import { buildAutoResumeContinuationPrompt, RESUME_TRANSPORT_ENVELOPE, } from "./run-lifecycle.js";
+import { buildAutoResumeContinuationPrompt, findRunDirectoryById, readRoleRunState, RESUME_TRANSPORT_ENVELOPE, } from "./run-lifecycle.js";
 import { CliUsageError } from "./cli-errors.js";
 import { bindAdmittedTicketNumber, buildInstructionTransportPrompt, freezeAttachmentsIntoRun, relocateAdmittedRunToTicket, } from "./invocation.js";
 import { readRecordedSubmissionRows } from "../submission-ledger.js";
 import { pathContainedIn } from "../activation-ledger-topology.js";
 import { pickEngineAxis } from "../package-resources/engine-material.js";
-import { readStoredHostSessionId, resolveHostAwareSessionAvailability } from "../session-identity.js";
+import { readStoredHostSessionId, resolveHostAwareSessionAvailability, } from "../session-identity.js";
 import { rewriteRunDirectoryPathValue } from "../role-run-relocation.js";
 import { isOfficerReviewSeat } from "../packaged-role-registry.js";
 import { deliverCaseDossierAsAttachment } from "./case-dossier-delivery.js";
@@ -39,7 +39,7 @@ import { projectHostTransitionPriorNative } from "../host-transition-prior-nativ
 import { clearCurrentCourt, clearTypedProviderHttpObservation, describeErrorIdentity, markRunRunning, readCurrentCourt, recordCurrentCourt, renderResumeCommand, } from "./run-lifecycle.js";
 import { processCancelDiagnostic, processCancelSignalName, } from "./process-cancel.js";
 import { homeFromRunDirectory } from "../activation-ledger-topology.js";
-import { attemptProducedFreshSubmission, classifyPostAdmissionFailure, controlledFailureInputFromResolution, exitCodeForTerminalOutcome, explicitInternalKnownFailureClassificationInput, formatCliDiagnostic, formatTerminalResult, inspectJudgeSession, isLawfulTypedTerminalOutcome, presentFailureTerminal, presentStructuralRejection, resolveAuditedRunnerFailureResolution, resolveControlledFailureResumeObservation, settleFailureTerminalResult, settleHostEndedNoReceipt, attachRecordedSubmissions, } from "./settlement.js";
+import { attemptProducedFreshSubmission, classifyPostAdmissionFailure, controlledFailureInputFromResolution, exitCodeForTerminalOutcome, explicitInternalKnownFailureClassificationInput, formatCliDiagnostic, formatErrorCauseDetail, formatTerminalResult, inspectJudgeSession, isLawfulTypedTerminalOutcome, presentFailureTerminal, publishedFailureErrorPath, presentStructuralRejection, resolveAuditedRunnerFailureResolution, resolveControlledFailureResumeObservation, settleFailureTerminalResult, settleHostEndedNoReceipt, attachRecordedSubmissions, rewritePublishedFailureErrorPath, } from "./settlement.js";
 import {} from "./terminal.js";
 import { ensureRealArtifactsDirectory, persistReturnedRunState, runWithAutoResumeLoop, TurnDispatchedFailure, } from "./auto-resume.js";
 function projectRelocatedTurnIdentity(request, result, admitted, relocation) {
@@ -56,6 +56,7 @@ function projectRelocatedTurnIdentity(request, result, admitted, relocation) {
         }
     }
     if (result.terminal !== undefined) {
+        rewritePublishedFailureErrorPath(result.terminal, relocation.oldRunDirectory, relocation.newRunDirectory);
         for (const artifact of result.terminal.artifacts) {
             artifact.path = rewrite(artifact.path);
         }
@@ -175,7 +176,7 @@ export async function resolveResumeMethodMaterialAdapters(input) {
             stderr: "",
             thrown: error,
             ...(input.knownCause === undefined ? {} : { knownCause: input.knownCause }),
-        }, input.emptyAdapters, input.authority, input.io);
+        }, input.emptyAdapters, input.authority, { ...input.io, omitFailureStderrDiagnostic: true });
         return { kind: "terminal", ...terminal };
     }
 }
@@ -233,15 +234,27 @@ export async function presentControlledFailure(admitted, failureInput, adapters,
     if (persistRunState && !failureInput.skipRunStateWrite) {
         await persistReturnedRunState(admitted, authority);
     }
-    const terminal = await attachRecordedSubmissions(admitted, await settleFailureTerminalResult(admitted, failure, authority, {
-        ...(resumable
-            ? { resume: { command: renderResumeCommand(admitted.runId) } }
-            : {}),
-        ...(failureInput.invocationScopeId === undefined ||
-            failureInput.invocationScopeId.length === 0
-            ? {}
-            : { invocationScopeId: failureInput.invocationScopeId }),
-    }));
+    let publishedErrorPath;
+    let terminal;
+    try {
+        const settled = await settleFailureTerminalResult(admitted, failure, authority, {
+            ...(resumable
+                ? { resume: { command: renderResumeCommand(admitted.runId) } }
+                : {}),
+            ...(failureInput.invocationScopeId === undefined ||
+                failureInput.invocationScopeId.length === 0
+                ? {}
+                : { invocationScopeId: failureInput.invocationScopeId }),
+            onErrorPublished: (path) => { publishedErrorPath = path; },
+        });
+        terminal = await attachRecordedSubmissions(admitted, settled);
+    }
+    catch (error) {
+        if (io.omitFailureStderrDiagnostic && publishedErrorPath !== undefined) {
+            writeResumeFailurePointer(io, publishedErrorPath);
+        }
+        throw error;
+    }
     presentFailureTerminal(terminal, io);
     return {
         exitCode: exitCodeForTerminalOutcome(terminal.roleOutcome),
@@ -359,8 +372,12 @@ export async function dispatchPostAdmissionTurn(input) {
             if (relocation !== undefined) {
                 projectRelocatedTurnIdentity(request, result, admitted, relocation);
             }
-            if (adapters.afterDispatch !== undefined)
-                await adapters.afterDispatch(admitted, lease);
+            const afterDispatchRelocation = adapters.afterDispatch === undefined
+                ? undefined
+                : await adapters.afterDispatch(admitted, lease);
+            if (afterDispatchRelocation !== undefined) {
+                projectRelocatedTurnIdentity(request, result, admitted, afterDispatchRelocation);
+            }
             return result;
         }
         catch (error) {
@@ -968,16 +985,24 @@ export async function runPostAdmissionSeatResume(input) {
         loaded = await input.load(request);
     }
     catch (error) {
-        if (error instanceof CliUsageError) {
-            presentStructuralRejection(error, input.io);
-            return { exitCode: 2 };
+        const usageError = error instanceof CliUsageError;
+        // Unknown usage failures retain the structural fallback. Other load
+        // failures keep the CLI's outer handling unless an existing run is found.
+        const recorded = await pointExistingRunFailure(input.env.home, request.runId, input.env.principalAuthority, input.io, error);
+        if (!recorded) {
+            if (usageError) {
+                presentStructuralRejection(error, input.io);
+                return { exitCode: 2 };
+            }
+            throw error;
         }
-        throw error;
+        return { exitCode: usageError ? 2 : 1 };
     }
     let adapters = input.adapters;
     if (input.afterAdmittedLoad !== undefined) {
         const prepared = await input.afterAdmittedLoad(loaded.admitted);
         if (prepared.kind === "terminal") {
+            showResumeErrorPointer(input.io, prepared.exitCode, prepared.terminal);
             return {
                 exitCode: prepared.exitCode,
                 admitted: prepared.admitted,
@@ -1116,26 +1141,100 @@ export async function runPostAdmissionSeatResume(input) {
                 }),
             });
         }
-        return await runPostAdmissionManualResume({
+        const resumed = await runPostAdmissionManualResume({
             admitted: loaded.admitted,
             env,
-            io: input.io,
+            io: { ...input.io, omitFailureStderrDiagnostic: true },
             adapters,
             ...(input.effectiveEngine === undefined
                 ? {}
                 : { effectiveEngine: input.effectiveEngine }),
             buildRequestAfterLease,
         });
+        showResumeErrorPointer(input.io, resumed.exitCode, resumed.terminal);
+        return resumed;
     }
     catch (error) {
-        // Turn construction may still surface structural rejection.
-        if (error instanceof CliUsageError) {
-            presentStructuralRejection(error, input.io);
-            return { exitCode: 2 };
+        if (error instanceof TurnDispatchedFailure)
+            throw error;
+        await presentResumeFailurePointer(input.io, error, (failure) => writeResumeDiagnosticFile(loaded.admitted.runDirectory, loaded.admitted.runId, failure, loaded.admitted.role));
+        return { exitCode: error instanceof CliUsageError ? 2 : 1 };
+    }
+}
+async function pointExistingRunFailure(home, runId, authority, io, thrown) {
+    let foundRunDirectory;
+    try {
+        foundRunDirectory = await findRunDirectoryById(home, runId);
+    }
+    catch {
+        return false;
+    }
+    if (foundRunDirectory === undefined)
+        return false;
+    const runDirectory = foundRunDirectory;
+    let record;
+    try {
+        record = await readRoleRunState(runDirectory, authority);
+    }
+    catch {
+        await presentResumeFailurePointer(io, thrown, (failure) => writeResumeDiagnosticFile(runDirectory, runId, failure));
+        return true;
+    }
+    if (record === undefined)
+        return false;
+    await presentResumeFailurePointer(io, thrown, (failure) => writeResumeDiagnosticFile(runDirectory, runId, failure, record.role));
+    return true;
+}
+export async function presentLocatedResumeFailure(home, runId, authority, io, thrown) {
+    return await pointExistingRunFailure(home, runId, authority, io, thrown);
+}
+function writeResumeFailurePointer(io, errorPath) {
+    io.stderr(formatCliDiagnostic(`续跑失败，当次错误记录：${errorPath}`));
+}
+export function showResumeErrorPointer(io, exitCode, terminal) {
+    if (exitCode === 0 || terminal === undefined)
+        return;
+    const publishedError = terminal.artifacts.find((artifact) => artifact.kind === "error")?.path
+        ?? publishedFailureErrorPath(terminal);
+    if (publishedError !== undefined)
+        writeResumeFailurePointer(io, publishedError);
+}
+async function presentResumeFailurePointer(io, thrown, publish) {
+    const failure = classifyPostAdmissionFailure({
+        timedOut: false,
+        code: null,
+        stderr: "",
+        thrown,
+    });
+    try {
+        writeResumeFailurePointer(io, await publish(failure));
+    }
+    catch (publishError) {
+        const cause = {
+            publishError: formatErrorCauseDetail(publishError),
+        };
+        if (thrown instanceof Error && thrown.cause !== undefined) {
+            cause.thrownCause = formatErrorCauseDetail(thrown.cause);
         }
-        throw error;
+        presentStructuralRejection({
+            message: thrown instanceof Error ? thrown.message : String(thrown),
+            cause,
+        }, io);
     }
 }
+async function writeResumeDiagnosticFile(runDirectory, runId, failure, role) {
+    const dir = await ensureRealArtifactsDirectory(runDirectory);
+    const path = join(dir, `resume-diagnostic-${randomUUID()}.json`);
+    await writeFile(path, `${JSON.stringify({
+        runId,
+        ...(role === undefined ? {} : { role }),
+        diagnostic: failure.diagnostic,
+        ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        ...(failure.identity === undefined ? {} : { identity: failure.identity }),
+        ...(failure.details === undefined ? {} : { details: failure.details }),
+    }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+    return path;
+}
 /**
  * Shared post-admission one-shot path: folds into runPostAdmissionResumable (#840 / #416).
  * All callable roles share the single auto-resume loop.

package/dist/public-cli/settlement.js

@@ -28,9 +28,10 @@ import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "../dossier-resolution.js";
 import { REVIEWER_OUTPUT_TOOL_NAME, } from "../package-contracts/reviewer-output.js";
 import { packagedAuditToolName, packagedDurableOfficerEntry, packagedProjectsTargetBindRejection, packagedRoleAcceptedOutputTool, packagedRoleMetadata, packagedSkipsGateOnInfrastructureStage, } from "../packaged-role-registry.js";
 import { SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY, SECRETARIAT_GATE_OFFICER_ENTRY_TYPE, } from "../secretariat-contracts.js";
-import { classifyPackagedRoleTerminalResult, findLatestDurablePackagedRoleTerminal, hasNavigatorInfrastructureFailureBase, isAcceptedPackagedRoleTerminalResult, isReceiptSettlementBindingClear, NAVIGATOR_INVOCATION_ENTRY, parseInvocationMarkerIdentity, } from "../navigator-invocation-identity.js";
+import { classifyPackagedRoleTerminalResult, findLatestDurablePackagedRoleTerminal, hasNavigatorInfrastructureFailureBase, isAcceptedPackagedRoleTerminalResult, isReceiptSettlementBindingClear, NAVIGATOR_INVOCATION_ENTRY, NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, parseInvocationMarkerIdentity, } from "../navigator-invocation-identity.js";
 import { NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_TURN_LIMIT, noReceiptLifecycleFacts, parseNoReceiptLifecycleFacts, } from "../receipt-delivery-policy.js";
 import { roleRunArtifactsDirectory } from "../role-run-placement.js";
+import { rewriteRunDirectoryPathValue } from "../role-run-relocation.js";
 import { listSeamOwnedUniqueErrorFacePaths, RUN_TERMINAL_ARTIFACT_FILES, RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS, } from "../run-terminal-artifacts.js";
 import { ensureRunArtifactsDir, homeFromRunDirectory, } from "./invocation.js";
 /** Ledger reads use the run's machine home — not ambient process HOME (child write vs parent settle). */
@@ -127,7 +128,11 @@ export async function attachRecordedSubmissions(admitted, terminal, scope) {
     // pass courtAttemptId here — roleOutcome already carries this-court payloads
     // from sealedLedgerOutcome when scoped; withSubmissions keeps them.
     void scope;
-    return withSubmissions(terminal, await recordedSubmissionPayloads(admitted, undefined));
+    const result = withSubmissions(terminal, await recordedSubmissionPayloads(admitted, undefined));
+    const errorPath = privateFailureErrorPaths.get(terminal);
+    if (errorPath !== undefined)
+        privateFailureErrorPaths.set(result, errorPath);
+    return result;
 }
 /**
  * Host ended with no recorded submission — lawful no_receipt (exit 0).
@@ -163,6 +168,18 @@ function coordinatesFromAdmitted(authority, admitted) {
 }
 import { coalesceSubmissionRows, exitCodeForTerminalOutcome, formatTerminalResult, isLawfulTypedTerminalOutcome, adviceNavigatorFact, } from "./terminal.js";
 export { exitCodeForTerminalOutcome, formatTerminalResult, isLawfulTypedTerminalOutcome, };
+// A resumable public Terminal omits artifact paths (#108); its actual error
+// publication remains available only to the CLI's resume presentation seam.
+const privateFailureErrorPaths = new WeakMap();
+export function publishedFailureErrorPath(terminal) {
+    return privateFailureErrorPaths.get(terminal);
+}
+export function rewritePublishedFailureErrorPath(terminal, oldRunDirectory, newRunDirectory) {
+    const errorPath = privateFailureErrorPaths.get(terminal);
+    if (errorPath !== undefined) {
+        privateFailureErrorPaths.set(terminal, rewriteRunDirectoryPathValue(errorPath, oldRunDirectory, newRunDirectory));
+    }
+}
 /**
  * Host stderr as recorded — full bytes, no flood filter, no char clip (#836).
  */
@@ -1610,7 +1627,26 @@ async function withOptionalGateProjection(base, sessionDirectory, gateContext =
     }
     return attachEngineDetourToolUsage(next, sessionDirectory, gateContext);
 }
+function routePlaybookFailureMessage(entries) {
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (entry?.type !== "custom" || entry.customType !== NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY)
+            continue;
+        const data = entry.data;
+        if (!isRecord(data) || typeof data.message !== "string" || data.message.trim() === "")
+            return undefined;
+        return data.message;
+    }
+    return undefined;
+}
 export function extractNavigatorFact(entries) {
+    const fact = extractNavigatorAttendanceFact(entries);
+    if (fact.advisoryDiagnostic !== undefined)
+        return fact;
+    const message = routePlaybookFailureMessage(entries);
+    return message === undefined ? fact : { ...fact, advisoryDiagnostic: message };
+}
+function extractNavigatorAttendanceFact(entries) {
     // Affirmative attendance only. Missing / uncorrelated / unparseable is never no-advice.
     // Minimal provenance: latest durable terminal + nearest preceding marker +
     // invocationId + post-terminal order. Marker↔terminal cardinality belongs to
@@ -2263,7 +2299,7 @@ async function writeFailureJsonRetainingCause(preferredCandidates, uniqueFallbac
     error.publicationAttempts = issues;
     throw error;
 }
-export async function publishFailureArtifacts(admitted, failure, authority) {
+export async function publishFailureArtifacts(admitted, failure, authority, onErrorPublished) {
     const { sessionDirectory, sessionFile } = coordinatesFromAdmitted(authority, admitted);
     const { baseDir, attempt: baseAttempt } = await resolveFailureArtifactsBase(admitted.runDirectory);
     const priorIssues = baseAttempt === undefined ? [] : [baseAttempt];
@@ -2327,6 +2363,7 @@ export async function publishFailureArtifacts(admitted, failure, authority) {
         ...(failure.details === undefined ? {} : { details: failure.details }),
     };
     const errorWrite = await writeFailureJsonRetainingCause(errorCandidates, uniqueFallbackDirs, "error", errorPayloadBase, priorIssues);
+    onErrorPublished?.(errorWrite.path);
     const evidencePayload = {
         runId: admitted.runId,
         sessionDirectory: sessionDirectory,
@@ -2418,7 +2455,8 @@ export async function settleFailureTerminalResult(admitted, failure, authority,
     // Exact-session attendance only — never infer no-advice from caller omission.
     const navigator = await extractNavigatorFactFromAdmittedSession(sessionFile);
     // Private durable artifacts retain the original diagnostic identity (including run ID).
-    const artifacts = await publishFailureArtifacts(admitted, failure, authority);
+    const artifacts = await publishFailureArtifacts(admitted, failure, authority, options.onErrorPublished);
+    const errorPath = artifacts.find((artifact) => artifact.kind === "error")?.path;
     const decisiveFacts = {
         ...(failure.cause === undefined ? {} : { cause: failure.cause }),
         diagnostic: failure.diagnostic,
@@ -2444,12 +2482,15 @@ export async function settleFailureTerminalResult(admitted, failure, authority,
             diagnostic: failure.diagnostic,
             decisiveFacts,
         };
-        return withOptionalGateProjection({
+        const terminal = await withOptionalGateProjection({
             roleOutcome,
             navigator,
             artifacts: [],
             resume: options.resume,
         }, sessionDirectory, detourGateContext(admitted, options));
+        if (errorPath !== undefined)
+            privateFailureErrorPaths.set(terminal, errorPath);
+        return terminal;
     }
     const roleOutcome = {
         kind: "failure",
@@ -2480,6 +2521,8 @@ export function presentFailureTerminal(terminal, io) {
     }
     io.stdout(formatTerminalResult(terminal));
     if (terminal.roleOutcome.kind === "failure") {
+        if (io.omitFailureStderrDiagnostic)
+            return;
         io.stderr(formatFailureStderrDiagnostic({
             ...(terminal.roleOutcome.cause === undefined ? {} : { cause: terminal.roleOutcome.cause }),
             diagnostic: terminal.roleOutcome.diagnostic,

package/dist/receipt-delivery-policy.js

@@ -1,5 +1,4 @@
 const RECEIPT_DELIVERY_TURN_LIMIT = 2;
-const RECEIPT_DELIVERY_PROMPT = "\u672C\u4F1A\u8BDD\u5C1A\u65E0\u5DF2\u63A5\u53D7\u7684 typed \u56DE\u6267\u3002";
 const NO_RECEIPT_LIFECYCLE_ENTRY_TYPE = "ak-no-receipt-lifecycle";
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -74,6 +73,15 @@ function createReceiptDeliveryPolicy() {
       if (accepted) return "accepted";
       return deliveryTurns < RECEIPT_DELIVERY_TURN_LIMIT ? "request-delivery" : "no-receipt";
     },
+    /** Current typed delivery facts. No prose. */
+    deliveryState() {
+      return {
+        terminalToolCalled,
+        rejectedReceipts: rejectedReceipts.map((item) => ({ ...item })),
+        deliveryTurns,
+        acceptedReceipt: false
+      };
+    },
     facts(binding) {
       return noReceiptLifecycleFacts({ terminalToolCalled, rejectedReceipts: [...rejectedReceipts], deliveryTurns, ...binding });
     }
@@ -81,7 +89,6 @@ function createReceiptDeliveryPolicy() {
 }
 export {
   NO_RECEIPT_LIFECYCLE_ENTRY_TYPE,
-  RECEIPT_DELIVERY_PROMPT,
   RECEIPT_DELIVERY_TURN_LIMIT,
   createReceiptDeliveryPolicy,
   noReceiptLifecycleFacts,

package/dist/review-submission.js

@@ -8,8 +8,8 @@ export const REVIEW_QUEUE_STATUSES = new Set(REVIEW_QUEUE_WORDS);
 /**
  * One object root. Codex structured output rejects a root anyOf, and status
  * stays a required three-state enum with no omitted-status failure branch.
- * A review seat that can still submit records a real external-dependency
- * failure as escalate plus the existing infrastructureFailure field.
+ * External-dependency failure while the seat can still submit:
+ * docs/adr/0057-schema-narrowing-cuts-the-required-set-not-the-declared-set.md
  */
 export const reviewSubmissionSchema = withTerminatingOutputDeclarations(Type.Object({
     status: Type.Union([
@@ -17,7 +17,7 @@ export const reviewSubmissionSchema = withTerminatingOutputDeclarations(Type.Obj
         Type.Literal(REVIEW_QUEUE_WORDS[1]),
         Type.Literal(REVIEW_QUEUE_WORDS[2]),
     ], {
-        description: "审核队列三态枚举，必填。审核席仍能交卷而完成审核所需的外部依赖发生真实基础设施失败时，status 取 escalate，细节写入 infrastructureFailure。不得省略 status，不得用另两个枚举值充当放行或封驳。包侧不因格式拒收。",
+        description: "审核席本轮裁决的判别状态。",
     }),
     findings: Type.Optional(Type.Unknown({ description: "审核发现，原样留存" })),
     reason: Type.Optional(Type.Unknown({ description: "上呈理由" })),

package/docs/adr/0057-schema-narrowing-cuts-the-required-set-not-the-declared-set.md

@@ -0,0 +1,9 @@
+# 交卷 schema 不把格式当拒收权
+
+Status: accepted
+
+交卷工具 schema 保留字段声明与 description；非审核席维持零 required（含记账位）、顶层开放额外属性的原决定。审核席的判别字段 status 则为三态枚举且必填，没有省略 status 的失败例外。审核席仍能交卷、而完成审核所需的外部依赖发生真实基础设施失败时，status 取上呈值，失败细节写入既有 infrastructureFailure；这不是放行或封驳。执行或宿主已失败、审核席无法交卷时，仍由宿主如实失败终局。
+
+包侧收卷：审核席除判别字段外，其余字段不必填、不限制，允许额外属性；声明不是包侧校验授权，包不因格式拒收或判死；判别字段没填或读不出时只说读不出并附收到的值，不在重交提示里另写一套状态名。key 名字不必逐字相同，合不合格由审刑院按是否读得懂来判。
+
+宿主生成端：使用宿主原生能力；Codex strict 结构化输出要求根节点为 object、对象关闭额外属性，不能以该出口承诺模型可生成未声明字段。此项宿主缺口如实报告，不另造适配层或出口；生成端的限制不变成包侧拒收权。（#1055。三态枚举必填并撤销无 status 例外：源卷 e4b50c8e-15c7-4c92-9263-959efadb24eb.jsonl，owner uuid ddff7ae0-0b1e-44eb-b80c-96d2a3d3d239、0ddc3a4e-9a53-4565-b1cc-7ba3471d11e5、1707c6ec-ac17-4876-97d1-73b57c734259。根节点须为 object：[Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)）

package/extensions/role-runtime.ts

@@ -14,14 +14,12 @@ import type { Message } from "@earendil-works/pi-ai";
 import {
   registerNavigatorModelCommand,
   resolveNavigatorAuthorityMaterial,
-  type NavigatorTargetRole,
 } from "../src/navigator-attendance.ts";
 import { loadNavigatorWorkContext as loadHostNeutralNavigatorWorkContext } from "../src/navigator-work-context.ts";
 export { resolveNavigatorAuthorityMaterial };
 import { JUDGE_OUTPUT_TOOL_NAME } from "../src/package-contracts/judge-output.ts";
 import { readOAuthKeepaliveProviders } from "../src/oauth-keepalive.ts";
 import {
-  formatNavigatorRoleHelp,
   type RoleRuntimeDependencies,
 } from "../src/role-runtime.ts";
 import { createRoleRuntimeDependencies } from "../src/role-runtime-dependencies.ts";
@@ -31,31 +29,6 @@ if (process.env.AK_ROLE_PACKAGE_ROOT === undefined || process.env.AK_ROLE_PACKAG
   process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
 }
 
-// Cold `pi -e <extension> --help` must cover installed-package process startup under CI load.
-// This bound is process-startup budget only — not settlement-to-visible presentation latency.
-export const NAVIGATOR_LIVE_HELP_TIMEOUT_MS = 30_000;
-
-/**
- * Subprocess live help (disk-reread via fresh pi -e). Kept for cold-install proofs.
- * Production Navigator prepare must not call this on the post-role grace path — under
- * concurrent CI load each role's pi --help alone can exceed the accepted 3s grace.
- */
-export async function loadNavigatorRoleHelp(
-  pi: Pick<ExtensionAPI, "exec">,
-  extensionPath: string,
-  cwd: string,
-  role: NavigatorTargetRole,
-): Promise<string> {
-  const result = await pi.exec("pi", ["--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "-e", extensionPath, "--ak-role", role, "--help"], { cwd, timeout: NAVIGATOR_LIVE_HELP_TIMEOUT_MS });
-  if (result.killed) {
-    throw new Error(`live help unavailable for ${role}: process did not settle`, { cause: result });
-  }
-  if (result.code !== 0) throw new Error(`live help unavailable for ${role}: process exited with code ${result.code}`, { cause: result });
-  return result.stdout || result.stderr;
-}
-
-export { formatNavigatorRoleHelp as formatInProcessNavigatorRoleHelp };
-
 function projectJudgeTranscriptForAudit(messages: Message[]): Message[] {
   return messages.map((message) => {
     if (message.role !== "assistant") return message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.5079",
+  "version": "0.1.5122",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",
@@ -36,6 +36,7 @@
     "schemas",
     "packets",
     "resources",
+    "docs/adr/0057-schema-narrowing-cuts-the-required-set-not-the-declared-set.md",
     "README.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",

package/resources/836-deleted-machine-instruction-inventory.md

@@ -13,8 +13,8 @@
 | `run-lifecycle.ts` A4.1 | `[ak-role:resume-continue]` | 生产码不再含此字面量。结算只跳过空轮与引擎指针续跑。 |
 | `run-lifecycle.ts` A4.2 | `重新读 <path>` | 前轮已删改写。 |
 | `submission-correctable-error.ts` A4.5 | `终局交卷并非本轮唯一工具调用。` | 删。Pi/ACP `deliverSubmissionRejection` 不再注入该句。 |
-| `role-runtime.ts` 催交 | `本会话尚无已接受的 typed 回执。` | **留**（轮次/预算，Q2）。 |
-| `navigator-attendance.ts` early prepare 开场 | `父衙门进行中。请在本宿主会话熟悉下列材料并待命；结算结果送达后，再给出下一步建议。本轮不要提交最终路线建议。` | #959 迁入 `resources/navigator-route-playbook.md`「到场阶段」；代码只留中立指针句「本轮为待命轮。」 |
-| `navigator-attendance.ts` settlement feed 开场 | `父衙门结算已送达。请根据下列材料给出下一步建议。` | #959 迁入同手册；代码只留中立指针句「本轮为结算投喂轮。」 |
+| `role-runtime.ts` 催交 | `本会话尚无已接受的 typed 回执。` | #1021 改为递当前 typed delivery 事实，不写催交句。 |
+| `navigator-attendance.ts` early prepare 开场 | `父衙门进行中。请在本宿主会话熟悉下列材料并待命；结算结果送达后，再给出下一步建议。本轮不要提交最终路线建议。` | #959 迁入 `resources/navigator-route-playbook.md`「到场阶段」。#1021 删掉代码指针句「本轮为待命轮。」：待命不调模型，只记到场。 |
+| `navigator-attendance.ts` settlement feed 开场 | `父衙门结算已送达。请根据下列材料给出下一步建议。` | #959 迁入同手册。#1021 删掉代码指针句「本轮为结算投喂轮。」：结算轮只递当前 typed 三态及指针。 |
 
 催交句与 2.1–2.3 打回文、重问三句不在删除列。

package/resources/collector-bot-handbook.md

@@ -27,6 +27,10 @@
 - 官方：https://prod.cursor.com/help/ai-features/bugbot 与 automations 文档
 - 内置 Bugbot 与同账号自定义任务须区分；某任务额度耗尽不推断其他任务失效
 
+## 工序
+
+判定任务材料后绑定本仓唯一 PR（prNumber，或由 issueNumber 解析到唯一 PR）。已有显式 PR 绑定时不必再绑。多义或无法确定时不猜，交给调用方明确目标。未绑定前不观察。观察把证据存成不可变快照；上下文里的正文只到头部，其余按 evidenceId 开卷。请求发在所引最新快照 HEAD 上；清单外的 requestId 要带上正文。交卷交 findings 指针，不把模板通知当成 finding；没有 finding 就不要编一条。未完成写现场原因，不写成没问题。
+
 ## 修正规则
 
 - 优先引用官方文档；现场差异记入仓库差异条并附 PR/证据指针

package/resources/navigator-route-playbook.md

@@ -1,11 +1,9 @@
-## 到场阶段（#959 / ADR 0073）
+## 到场阶段（#959 / ADR 0073 / #1021）
 
-代码只传中立阶段指针句与 typed 材料；阶段行为说明住本手册，随案附卷。
+阶段行为说明住本手册。代码不写阶段句，也不把本手册再拼进用户消息。
 
-- **待命轮**：父衙门进行中。请在本宿主会话熟悉下列材料并待命；结算结果送达后，再给出下一步建议。本轮不要提交最终路线建议。
-- **结算投喂轮**：父衙门结算已送达。请根据下列材料给出下一步建议。
-
-Early 待命轮的输出由执行机制丢弃；最终路线建议只在结算投喂轮给出。
+- **待命**：父衙门进行中时，代码只记到场，不调用模型。这一轮没有输出。
+- **结算**：父衙门结算送达后，用户消息只有该次 typed 三态及指针。Soul 与本手册已在系统提示里。根据这份结算和本手册给出下一步建议。
 
 ## 宿主轴（与角色命令面）
 

package/scripts/build-package.mjs

@@ -15,6 +15,10 @@ const entries = [
   // (#590: published non-bundle graph must stay closed under its own relative edges).
   "navigator-public-session",
   "navigator-session-contracts",
+  // Static import of navigator-attendance and navigator-public-session.
+  "navigator-work-base",
+  // Static import of navigator-work-base.
+  "atomic-write",
   "public-role-summons",
   "pi/in-process-session",
   "activation-ledger-git",

package/souls/coder-output-guide.md

@@ -2,4 +2,5 @@
 
 提交：标题冠 ak-roles: 在最前；forward commit，严禁 amend——改错就再提交一笔，不改历史。
 交卷回执：改动清单与票面逐项对得上；验证证据附命令与结果原文。
+completed 回执含四项证据：TDD、同模式、引入回归、行为事实。
 新造通用件：回执写明仓内、语言标准库、包生态各搜了什么、为什么不用。

package/src/auditor-soul.ts

@@ -46,8 +46,9 @@ export const AUDITOR_SESSION_MATERIALS = {
     "souls/judge-auditor.md",
     "souls/audit-law.md",
     "souls/quality-law.md",
+    "docs/adr/0057-schema-narrowing-cuts-the-required-set-not-the-declared-set.md",
   ],
-  doctor: ["CLAUDE.md", "souls/doctor-auditor.md"],
+  doctor: ["CLAUDE.md", "souls/doctor-auditor.md", "docs/adr/0057-schema-narrowing-cuts-the-required-set-not-the-declared-set.md"],
 } as const satisfies Record<
   AuditorSoulRole,
   readonly [string, string, ...(readonly string[])]

package/src/collector-role.ts

@@ -351,8 +351,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_BIND_TARGET_TOOL,
         label: "通进司认票绑定",
-        description:
-          "角色判定任务材料后绑定本仓唯一 PR 目标。可提交 prNumber 或 issueNumber（线上关联唯一 PR）；显式 --pr 已绑定时无需再调。多义或无法确定时会正确驳回，要求调用方明确 --pr。",
+        description: "绑定本仓唯一 PR 目标。",
         promptSnippet: "绑定角色判定的 issue/PR 目标",
         parameters: bindSchema,
         async execute(toolCallId: string, params: BindParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -433,7 +432,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_OBSERVE_TOOL,
         label: "通进司观察",
-        description: "抓取配置目标的完整 GitHub PR 证据，存不可变快照入卷。正文在上下文中只给头部摘录加指针；需要头部之外的正文时，用 ak_collector_read 按 evidenceId 开卷；findings 的拆分与归类由你在交件时完成。目标未绑定前须先 ak_collector_bind_target。",
+        description: "抓取配置目标的 GitHub PR 证据。",
         promptSnippet: "抓取配置目标 PR 证据",
         parameters: observeSchema,
         async execute(toolCallId: string, _params: unknown, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -464,7 +463,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_READ_TOOL,
         label: "通进司开卷",
-        description: "按 evidenceId 开卷读取一条已观测材料的全量正文与指针；只在观察头部摘录不足以判读时调用。",
+        description: "按 evidenceId 开卷读取一条已观测材料的全量正文与指针。",
         promptSnippet: "按指针开卷读材料",
         parameters: readSchema,
         async execute(toolCallId: string, params: ReadParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -499,7 +498,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_REQUEST_TOOL,
         label: "通进司请求",
-        description: "在所引最新快照 HEAD 发一次请求。requestId 可取配置清单，或角色依手册/现场判定的稳定 id；后者须同时提供 body。",
+        description: "发一次请求。",
         promptSnippet: "发一次评审请求",
         parameters: requestSchema,
         async execute(toolCallId: string, params: RequestParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -625,7 +624,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_WAIT_TOOL,
         label: "通进司等待",
-        description: "再观察前等待；实际睡眠不超过剩余等待窗。",
+        description: "等待。实际睡眠不超过剩余等待窗。",
         promptSnippet: "等待窗内等待",
         parameters: waitSchema,
         async execute(toolCallId: string, params: WaitParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -656,7 +655,7 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_OUTPUT_TOOL,
         label: "通进司输出",
-        description: "观察完成后提交原交卷。正常完工提交空对象 {}（如需报 finding，填 findings 指针数组）；仅在基础设施真实失败时才可填 infrastructureFailure，无失败时必须省略该字段。",
+        description: "提交通进司回执。",
         promptSnippet: "提交通进司回执",
         parameters: outputSchema,
         async execute(toolCallId: string, params: OutputParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {