@akagilnc/pi-workflow-roles 0.1.5663 → 0.1.5671

package/src/navigator-public-session.ts

@@ -6,7 +6,7 @@
  * no books/<book>/navigator/<hash>/ side-branch nest, work-context file,
  * current-session pointer, or attendance parallel ledger (#1178).
  * Host conversation continuity uses CLI resume (`resumeRunId`) within this
- * attendance lifetime (in-memory pointer); cross-turn design is #1160.
+ * attendance lifetime (in-memory pointer). Parallel byStatus prepare is #1160.
  */
 import { basename } from "node:path";
 
@@ -81,6 +81,8 @@ export type NavigatorPublicSummon = (options: {
   readonly resumeRunId?: string;
   /** Shared-lifecycle cancel forwarded from HostContext.signal (#675 / #959). */
   readonly signal?: AbortSignal;
+  /** #1160 attendance auto byStatus prepare — host mounts structured schema. */
+  readonly navigatorByStatusPrepare?: boolean;
 }) => Promise<PublicSummonResult>;
 
 type MemoryEntry = {
@@ -98,7 +100,6 @@ export function createNativeNavigatorSessionFactory(deps?: {
   return async ({ context, tool }) => {
     // Model is enforced at prepare (attendance seat resolve) and at prompt (summon).
     // Factory open only holds in-memory attendance bookkeeping — no side-branch nest.
-    let thinkingLevel: string | undefined;
     const entries: MemoryEntry[] = [];
     let providerFailure: NavigatorProviderFailureFact | undefined;
     let noReceipt: Partial<NoReceiptLifecycleFacts> | undefined;
@@ -137,6 +138,9 @@ export function createNativeNavigatorSessionFactory(deps?: {
             role: "navigator" as const,
             argv: [text] as const,
             cwd: context.cwd,
+            // Attendance prepare always asks for structured byStatus (#1160).
+            // Direct `ak-role navigator` never sets this flag.
+            navigatorByStatusPrepare: true as const,
             ...(summonHome === undefined ? {} : { home: summonHome }),
             ...(context.signal === undefined ? {} : { signal: context.signal }),
           };
@@ -222,18 +226,24 @@ export function createNativeNavigatorSessionFactory(deps?: {
             // Not a shape-unusable judgment on the navigator reply (#757).
             return;
           }
-          // #959: present navigator words as prose. No candidates/next parsing.
-          const { navigatorProseFromUnknown } = await import("./package-contracts/navigator-output.ts");
-          const proseParts: string[] = [];
+          // #959 / #1160: pass through prose and byStatus. No route parsing.
+          const {
+            byStatusToPlainObject,
+            mergePreparedAdvice,
+            preparedAdviceFromUnknown,
+          } = await import("./package-contracts/navigator-output.ts");
+          let prepared = undefined as ReturnType<typeof preparedAdviceFromUnknown>;
           for (const payload of outcome.payloads ?? []) {
-            const prose = navigatorProseFromUnknown(payload);
-            if (prose !== undefined) proseParts.push(prose);
+            prepared = mergePreparedAdvice(prepared, preparedAdviceFromUnknown(payload));
           }
-          if (proseParts.length === 0) return;
+          if (prepared === undefined) return;
           if (disposed) return;
           await tool.execute(
             "navigator-public-prepare",
-            { prose: proseParts.join("\n\n") },
+            {
+              ...(prepared.prose === undefined ? {} : { prose: prepared.prose }),
+              ...(prepared.byStatus.size === 0 ? {} : { byStatus: byStatusToPlainObject(prepared.byStatus) }),
+            },
             undefined,
             undefined,
             context as never,
@@ -264,18 +274,15 @@ export function createNativeNavigatorSessionFactory(deps?: {
         });
       },
       entries: () => entries,
-      setModel: async (next, nextThinking) => {
-        let nextParsed: ReturnType<typeof parseNavigatorModelSetting>;
+      setModel: async (next) => {
+        // Validate only — resume/fresh mint both read the live seat table
+        // (#675 / #617 DK-3). No test-only thinking observation state (#1160 F1).
         try {
-          nextParsed = parseNavigatorModelSetting(next);
+          parseNavigatorModelSetting(next);
         } catch (error) {
           throw navigatorUnavailableError("model", error);
         }
-        // Resume and fresh mint both read the live seat table (#675 / #617 DK-3).
-        // A seat edit between prepares applies on the next host turn.
-        thinkingLevel = nextThinking ?? nextParsed.thinkingLevel;
       },
-      getThinkingLevel: () => thinkingLevel,
       dispose: async () => {
         // Marker only — nested cancel and non-blocking teardown are owned by
         // navigator-attendance / role-runtime (ADR 0018 / #959).

package/src/navigator-session-contracts.ts

@@ -203,7 +203,6 @@ export type NavigatorPreparationSession = {
   /** Native message from the nested playbook read, when that read failed. */
   routePlaybookReadFailure?(): string | undefined;
   setModel?(model: string, thinkingLevel?: string): Promise<void>;
-  getThinkingLevel?(): string | undefined;
   dispose(): void | Promise<void>;
 };
 

package/src/package-contracts/navigator-output.ts

@@ -1,8 +1,8 @@
 /**
- * Public Navigator (游奕使) terminating receipt contracts (#639 / #959).
- * Navigator speaks free-form prose. The tool is only a lifecycle vehicle so the
- * host can seal a turn; the model-facing content is prose, not structured route
- * candidates. Code does not parse, rank, or judge the advice.
+ * Public Navigator (游奕使) terminating receipt contracts (#639 / #959 / #1160).
+ * Advice body is free-form prose. Status association for parallel prepare lives on
+ * `byStatus` — code picks by the settlement status field only (owner 3188b502).
+ * Code does not parse, rank, or judge advice semantics.
  * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
  */
 import { Type } from "typebox";
@@ -13,20 +13,75 @@ import { withTerminatingOutputDeclarations } from "./terminating-infrastructure.
 
 export const NAVIGATOR_OUTPUT_TOOL_NAME = "ak_navigator_output";
 
-export const navigatorOutputSchema = withTerminatingOutputDeclarations(
-  openToolObject(
-    Type.Object({
-      prose: Type.Unknown({
-        description: "游奕使散文建议，原样呈现。不要求 candidates/next 等结构化字段。",
-      }),
-    }),
-  ),
-);
+/**
+ * Single owner of prose / byStatus field declarations (#1160).
+ * Output tool and attendance prepare tool both compose from this.
+ */
+export const navigatorAdviceFields = {
+  prose: Type.Unknown({
+    description: "单条散文建议。无状态分叉时使用；原样呈现。",
+  }),
+  byStatus: Type.Unknown({
+    description:
+      "按主衙门结局 status 预写的散文建议。键为 status 字面量，值为建议正文。"
+      + "结算时代码只按实际 status 取对应原文，不解析建议语义。",
+  }),
+} as const;
+
+/** Open tool object for prose/byStatus (attendance prepare + public output body). */
+export const navigatorAdviceBodySchema = openToolObject(Type.Object(navigatorAdviceFields));
+
+export const navigatorOutputSchema = withTerminatingOutputDeclarations(navigatorAdviceBodySchema);
 
 export type NavigatorAdvice = { readonly prose: string };
 
+/** Parallel-prepare payload: status-keyed prose plus optional single prose. */
+export type PreparedNavigatorAdvice = {
+  /** Map keeps opaque status keys (including "__proto__") as own entries. */
+  readonly byStatus: ReadonlyMap<string, string>;
+  readonly prose?: string;
+};
+
+/** Serialize structured bodies with JSON; never String(object) → [object Object]. */
+function nonEmptyProse(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    return value.trim() === "" ? undefined : value;
+  }
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "object") {
+    // No catch: serialization failure must surface (failure honesty).
+    const text = JSON.stringify(value);
+    if (text === undefined || text.trim() === "" || text === "{}" || text === "[]") return undefined;
+    return text;
+  }
+  const text = String(value);
+  return text.trim() === "" ? undefined : text;
+}
+
+function setStatusProse(target: Map<string, string>, key: string, prose: string): void {
+  const prior = target.get(key);
+  target.set(key, prior === undefined ? prose : `${prior}\n\n${prose}`);
+}
+
+function byStatusFromUnknown(value: unknown): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!isRecord(value)) return out;
+  for (const [key, raw] of Object.entries(value)) {
+    const prose = nonEmptyProse(raw);
+    if (prose !== undefined) out.set(key, prose);
+  }
+  return out;
+}
+
+/** Plain object for tool.execute / host payloads; Object.fromEntries keeps opaque keys. */
+export function byStatusToPlainObject(
+  byStatus: ReadonlyMap<string, string>,
+): Record<string, string> {
+  return Object.fromEntries(byStatus);
+}
+
 /**
- * Project one Navigator advice receipt as prose.
+ * Project one Navigator advice receipt as prose (display / single-advice path).
  * Accepts { prose }, a bare string, or any object — objects stringify as the
  * prose body so historical / free-form submissions still present. Shape is not
  * an admission gate (ADR 0055 / 仓内 CLAUDE.md 开篇 / #959).
@@ -37,16 +92,13 @@ export function projectLawfulNavigatorOutput(value: unknown): NavigatorAdvice |
   if (isRecord(value)) {
     if (typeof value.prose === "string") return { prose: value.prose };
     if (value.prose !== undefined && value.prose !== null) {
-      return { prose: typeof value.prose === "string" ? value.prose : String(value.prose) };
+      const serialized = nonEmptyProse(value.prose);
+      if (serialized !== undefined) return { prose: serialized };
     }
     // Free-form object submission: present the whole body as prose when it has content.
     const keys = Object.keys(value);
     if (keys.length === 0) return { prose: "" };
-    try {
-      return { prose: JSON.stringify(value) };
-    } catch {
-      return { prose: String(value) };
-    }
+    return { prose: JSON.stringify(value) };
   }
   return { prose: String(value) };
 }
@@ -69,3 +121,77 @@ export function navigatorProseFromUnknown(value: unknown): string | undefined {
   const trimmed = projected.prose.trim();
   return trimmed === "" ? undefined : projected.prose;
 }
+
+/**
+ * Extract parallel-prepare advice. Empty / missing → undefined.
+ * Never a rejection — shape is not an admission gate.
+ */
+export function preparedAdviceFromUnknown(value: unknown): PreparedNavigatorAdvice | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") {
+    const prose = nonEmptyProse(value);
+    return prose === undefined ? undefined : { byStatus: new Map(), prose };
+  }
+  if (!isRecord(value)) {
+    const prose = nonEmptyProse(value);
+    return prose === undefined ? undefined : { byStatus: new Map(), prose };
+  }
+  const byStatus = byStatusFromUnknown(value.byStatus);
+  const hasProseField = Object.prototype.hasOwnProperty.call(value, "prose");
+  const hasByStatusField = Object.prototype.hasOwnProperty.call(value, "byStatus");
+  const prose = nonEmptyProse(value.prose);
+  if (byStatus.size === 0 && prose === undefined) {
+    // Explicit empty prose / byStatus → no advice (do not re-stringify the shell).
+    if (hasProseField || hasByStatusField) return undefined;
+    // Free-form object without byStatus/prose: single-advice compat via stringify.
+    const keys = Object.keys(value);
+    if (keys.length === 0) return undefined;
+    const text = JSON.stringify(value);
+    return text.trim() === "" || text === "{}" ? undefined : { byStatus: new Map(), prose: text };
+  }
+  return {
+    byStatus,
+    ...(prose === undefined ? {} : { prose }),
+  };
+}
+
+/** Merge status keys; same-status prose concatenates (no silent drop). */
+export function mergePreparedAdvice(
+  prior: PreparedNavigatorAdvice | undefined,
+  next: PreparedNavigatorAdvice | undefined,
+): PreparedNavigatorAdvice | undefined {
+  if (prior === undefined) return next;
+  if (next === undefined) return prior;
+  const byStatus = new Map(prior.byStatus);
+  for (const [key, prose] of next.byStatus) {
+    setStatusProse(byStatus, key, prose);
+  }
+  const proseParts = [prior.prose, next.prose]
+    .filter((part): part is string => typeof part === "string" && part.trim() !== "");
+  const prose = proseParts.length === 0 ? undefined : proseParts.join("\n\n");
+  if (byStatus.size === 0 && prose === undefined) return undefined;
+  return {
+    byStatus,
+    ...(prose === undefined ? {} : { prose }),
+  };
+}
+
+/**
+ * Pick prepared prose for a settlement status (#1160 / owner 3188b502).
+ * - byStatus present → only the matching status key (no prose fallback).
+ * - byStatus empty → single prose used as the only advice.
+ * Missing match → undefined (honest no-advice).
+ */
+export function pickPreparedProse(
+  prepared: PreparedNavigatorAdvice | undefined,
+  status: string | undefined,
+): string | undefined {
+  if (prepared === undefined) return undefined;
+  if (prepared.byStatus.size > 0) {
+    if (status === undefined) return undefined;
+    const hit = prepared.byStatus.get(status);
+    return typeof hit === "string" && hit.trim() !== "" ? hit : undefined;
+  }
+  const prose = prepared.prose;
+  return typeof prose === "string" && prose.trim() !== "" ? prose : undefined;
+}

package/src/public-cli/post-admission.ts

@@ -487,6 +487,8 @@ export type PostAdmissionEnv = {
   boundTicketNumber?: number;
   /** Station child role run (#840): omit automatic navigator attendance. */
   stationChild?: boolean;
+  /** #1160 attendance auto byStatus prepare (nested navigator only). */
+  navigatorByStatusPrepare?: boolean;
 };
 
 /**
@@ -1379,6 +1381,9 @@ export async function dispatchPostAdmissionTurn<
     if (env.stationChild !== undefined) {
       turnRequest = { ...turnRequest, stationChild: env.stationChild };
     }
+    if (env.navigatorByStatusPrepare === true) {
+      turnRequest = { ...turnRequest, navigatorByStatusPrepare: true };
+    }
     // Selected host axis rides the shared Host envelope for in-turn tools
     // (detour usage ledger) — never a pre-spawn current.json reread.
     if (typeof env.host === "string" && env.host.trim() !== "") {
@@ -1735,6 +1740,9 @@ export function resumeTurnRequestProjectionOptions(
       prompt,
     },
     ...(env.stationChild === undefined ? {} : { stationChild: env.stationChild }),
+    ...(env.navigatorByStatusPrepare === true
+      ? { navigatorByStatusPrepare: true as const }
+      : {}),
     // #1132: one configured ceiling, already resolved by the caller (#422).
     deliveryRequestLimit: deliveryLimitFromConfig(env.autoResumeLimit),
   };
@@ -1755,6 +1763,9 @@ export function roleTurnOptions(
       : { correlationId }),
     continuation,
     ...(env.stationChild === undefined ? {} : { stationChild: env.stationChild }),
+    ...(env.navigatorByStatusPrepare === true
+      ? { navigatorByStatusPrepare: true as const }
+      : {}),
     // #1132: one configured ceiling, already resolved by the caller (#422).
     deliveryRequestLimit: deliveryLimitFromConfig(env.autoResumeLimit),
   };

package/src/public-cli/turn-request.ts

@@ -70,6 +70,8 @@ export type RoleTurnRequestProjectionOptions = {
   invocationScopeId?: string;
   /** Station child role run (#840): omit automatic navigator attendance. */
   readonly stationChild?: boolean;
+  /** #1160 attendance auto byStatus prepare (not direct navigator prose). */
+  readonly navigatorByStatusPrepare?: boolean;
   /**
    * #1132: the one effective delivery-request ceiling (#422 single resolve by
    * the caller). Projected so the host adapter's own re-ask loop and the AK
@@ -123,6 +125,9 @@ export function projectRoleTurnRequest(
       ? {}
       : { invocationScopeId: options.invocationScopeId }),
     ...(options.stationChild === undefined ? {} : { stationChild: options.stationChild }),
+    ...(options.navigatorByStatusPrepare === undefined
+      ? {}
+      : { navigatorByStatusPrepare: options.navigatorByStatusPrepare }),
     ...(options.deliveryRequestLimit === undefined
       ? {}
       : { deliveryRequestLimit: options.deliveryRequestLimit }),

package/src/public-role-summons.ts

@@ -121,6 +121,11 @@ export type PublicSummonRequest = {
    * (#946 / ADR 0082).
    */
   readonly stationChild?: boolean;
+  /**
+   * #1160 attendance auto byStatus prepare. Nested navigator only — never set
+   * on direct `ak-role navigator` (keeps free-form prose exit).
+   */
+  readonly navigatorByStatusPrepare?: boolean;
 };
 
 const execFileAsync = promisify(execFile);
@@ -398,6 +403,9 @@ export async function summonPublicRole(
           // Nested court stations keep station-child semantics; dual-lens
           // ordinary Reviewer axes opt out (#946 / ADR 0082).
           ...(options.stationChild === false ? {} : { stationChild: true }),
+          ...(options.navigatorByStatusPrepare === true
+            ? { navigatorByStatusPrepare: true as const }
+            : {}),
           // Forward composition-root adapters so nested stations (e.g.
           // secretariat → diarist) select the same faux/production table (#924).
           ...(options.hostAdapters === undefined

package/src/role-runtime.ts

@@ -1107,9 +1107,10 @@ export function createRoleRuntimeExtension(
       if (settlement === undefined || attendance === undefined) return;
       const workContext = navigatorWorkContext;
       const pending = (async () => {
-        // ADR 0052 / #959: every settlement that starts a post-role feed host round
+        // ADR 0052 / #959 / #1160: every settlement that waits on parallel prepare
         // (accepted, human_decision, role_infrastructure_failure) shares one grace
         // and the same honest unavailable projection — no unbounded parallel branch.
+        // Settle picks byStatus; grace is only the tail wait, not a cold model start.
         const settlePromise = attendance.settle(settlement);
         // Attach catch immediately so a late rejection after grace timeout cannot
         // surface as unhandledRejection / stale-ctx after session dispose (#675).
@@ -1775,7 +1776,7 @@ export function createRoleRuntimeExtension(
               }
             },
           });
-          // Concrete work context starts standby attendance (record only, no model).
+          // Concrete work context starts parallel prepare (model runs now; #1160).
           // Placeholder subjects wait for before_agent_start (user prompt may replace the subject key).
           if (
             navigatorWorkContext.contextError === undefined &&