@akagilnc/pi-workflow-roles 0.1.4528 → 0.1.4620

package/resources/navigator-route-playbook.md

@@ -1,3 +1,12 @@
+## 到场阶段（#959 / ADR 0073）
+
+代码只传中立阶段指针句与 typed 材料；阶段行为说明住本手册，随案附卷。
+
+- **待命轮**：父衙门进行中。请在本宿主会话熟悉下列材料并待命；结算结果送达后，再给出下一步建议。本轮不要提交最终路线建议。
+- **结算投喂轮**：父衙门结算已送达。请根据下列材料给出下一步建议。
+
+Early 待命轮的输出由执行机制丢弃；最终路线建议只在结算投喂轮给出。
+
 ## 宿主轴（与角色命令面）
 
 游奕使自动出席，亦可 `ak-role navigator` 直调（自动出席不变）。主会话宿主由公开角色的 host 轴决定：调用 `--host` → 席位 `config set-host` → 默认 `pi`。配置默认 host 后，调用者仍用与 Pi 相同的 `ak-role <role> …` 命令面；游奕使随该宿主下的角色跑次出席，席位模型走 run 目录 `institutional-resolution.json` 的 navigator 座（显式 `config set navigator` 优先，否则继承父席有效模型），不再依赖父宿主 ExtensionContext。

package/scripts/build-package.mjs

@@ -5,7 +5,6 @@ import { build } from "esbuild";
 
 const entries = [
   "packaged-role-registry",
-  "public-command-renderer",
   "work-subject-identity",
   "navigator-invocation-identity",
   // Static import of navigator-invocation-identity (#603: non-bundle graph closure).
@@ -22,6 +21,10 @@ const entries = [
   "activation-ledger-topology",
   "activation-reconciliation",
   "archivist-record-entry",
+  // Pure subject nest topology — static import of archivist-record-entry;
+  // cold discovery without SessionManager (#636). Keep listed while that
+  // relative edge remains (#857 removal left the import graph open).
+  "archivist-record-topology",
   // Session material loaders used by published non-bundle roots.
   "session-opening-materials",
   // Value-import closure of published non-bundle roots (build-package-only loadable).
@@ -205,6 +208,8 @@ export async function buildPackageArtifacts() {
   await mkdir(pluginDir, { recursive: true });
   await cp("resources/method-host-plugin/.claude-plugin", join(pluginDir, ".claude-plugin"), { recursive: true });
   await cp("resources/methods", join(pluginDir, "skills"), { recursive: true });
+  // Packaged handbook/playbook paths resolve via injected packageRoot (#962) —
+  // do not mirror resources/ into dist/resources (one authority, no parallel copy).
 }
 
 const isMain =

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

@@ -9,6 +9,10 @@ import {
 } from "../external-host-turn-loop.ts";
 
 import { reportHostSessionEvent } from "../host-session-record.ts";
+import {
+  NAVIGATOR_OUTPUT_TOOL_NAME,
+  navigatorProseFromUnknown,
+} from "../package-contracts/navigator-output.ts";
 import {
   renderSystemPromptOverride,
   type PreparedRoleTurn,
@@ -16,6 +20,53 @@ import {
 } from "../prepared-role-turn.ts";
 import { acpModelId, type AcpHostDescription } from "./description.ts";
 
+/**
+ * #959: collect free-form agent text from ACP session/update stream.
+ * Used only when the navigator seat spoke prose without calling the output tool.
+ * ACP agent speech is only agent_message / agent_message_chunk — never user,
+ * thought, or other *_message kinds (load replay must not poison the bucket).
+ *
+ * Standard ACP nests under params.update: { sessionUpdate, content }.
+ * Flat params.sessionUpdate / string params.update remain accepted for host variants.
+ */
+function acpAgentTextChunk(params: Readonly<Record<string, unknown>>): string | undefined {
+  let kind: unknown;
+  let content: unknown;
+  let textFallback: unknown;
+
+  const nested = params.update;
+  if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+    const record = nested as Record<string, unknown>;
+    kind = record.sessionUpdate;
+    content = record.content;
+    textFallback = record.text;
+  } else {
+    kind = params.sessionUpdate ?? nested;
+    content = params.content;
+    textFallback = params.text;
+  }
+
+  if (kind !== "agent_message_chunk" && kind !== "agent_message") return undefined;
+  if (typeof content === "string" && content.length > 0) return content;
+  if (typeof content === "object" && content !== null && !Array.isArray(content)) {
+    const record = content as Record<string, unknown>;
+    if (typeof record.text === "string" && record.text.length > 0) return record.text;
+  }
+  if (Array.isArray(content)) {
+    const parts: string[] = [];
+    for (const part of content) {
+      if (typeof part === "string" && part.length > 0) parts.push(part);
+      else if (typeof part === "object" && part !== null) {
+        const record = part as Record<string, unknown>;
+        if (typeof record.text === "string" && record.text.length > 0) parts.push(record.text);
+      }
+    }
+    if (parts.length > 0) return parts.join("");
+  }
+  if (typeof textFallback === "string" && textFallback.length > 0) return textFallback;
+  return undefined;
+}
+
 /** ACP v1 surface used by the generic ACP adapter. Protocol details stay in this module. */
 export interface AcpConnection {
   request(method: string, params: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
@@ -43,7 +94,13 @@ export type AcpRoleTurnHostConfig = Readonly<{
   prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
 }>;
 
-function failure(cause: "activation" | "session" | "output", name: string, code: string, details?: Readonly<Record<string, unknown>>): RoleTurnResult {
+function failure(
+  cause: "activation" | "session" | "output",
+  name: string,
+  code: string,
+  details?: Readonly<Record<string, unknown>>,
+  diagnostic?: string,
+): RoleTurnResult {
   return {
     code: null,
     stderr: "",
@@ -51,11 +108,27 @@ function failure(cause: "activation" | "session" | "output", name: string, code:
     knownFailure: {
       cause,
       identity: { name, code },
+      ...(diagnostic === undefined ? {} : { diagnostic }),
       ...(details === undefined ? {} : { details }),
     },
   };
 }
 
+/** Success→dispose failure; existing failure keeps primary cause + cleanup detail. */
+function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
+  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+  if (outcome.knownFailure === undefined) {
+    return failure("session", "AcpDisposeFailure", "dispose-failed", { cleanupError: message }, message);
+  }
+  return {
+    ...outcome,
+    knownFailure: {
+      ...outcome.knownFailure,
+      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
+    },
+  };
+}
+
 type RpcReply = { readonly id?: unknown; readonly method?: unknown; readonly params?: unknown; readonly result?: unknown; readonly error?: unknown };
 
 function acpError(code: string, message: string, cause?: unknown): Error & { readonly code: string } {
@@ -182,10 +255,12 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
     let connection: AcpConnection | undefined;
     let sessionId: string | undefined;
     let accepted = false;
+    // Mutable so dispose failure can outrank a clean turn (headless withCleanupFailure face).
+    let outcome: RoleTurnResult = failure("session", "AcpNoOutcome", "no-outcome");
     try {
       if (prepared.mcpServers.length === 0) {
-        return failure("activation", "UncontrolledAcpSession", "ak-config-missing");
-      }
+        outcome = failure("activation", "UncontrolledAcpSession", "ak-config-missing");
+      } else {
       connection = await config.connect(request);
       // Live host-session records: ACP session/update → sitian sole entry (#811).
       // One abort + one race helper + one outer projection — write failure ends
@@ -214,8 +289,17 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
       ): Promise<Readonly<Record<string, unknown>>> =>
         raceAgainstHostAbort(connection!.request(method, params), recordAbort.signal, "host-session-record-failed");
 
+      // #959: navigator free-form agent text — only while session/prompt is in flight.
+      // session/load replays history via session/update; those must not enter the bucket
+      // (resume / set_model load would otherwise prepend prior turns as "this turn" prose).
+      const agentProseChunks: string[] = [];
+      let collectAgentProse = false;
       connection.onNotification?.((method, params) => {
         if (method !== "session/update" || hostSessionRecordFailure !== undefined) return;
+        if (collectAgentProse) {
+          const chunk = acpAgentTextChunk(params);
+          if (chunk !== undefined) agentProseChunks.push(chunk);
+        }
         try {
           reportHostSessionEvent({
             host: config.hostName,
@@ -243,11 +327,11 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
         if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) =>
           typeof entry === "object" && entry !== null
           && (entry as { modelId?: unknown }).modelId === acpModelId(config.modelPassing, request.model))) {
-          return failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
+          outcome = failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
             provider: request.model.provider,
             model: request.model.model,
           });
-        }
+        } else {
 
         const sessionBindParams = {
           cwd: request.cwd,
@@ -269,15 +353,19 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
             sessionId = await loadSession(boundSessionId);
           }
         }
+        let sessionReady = true;
         if (sessionId === undefined) {
           const session = await rpc("session/new", sessionBindParams);
           sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
           if (sessionId === undefined || sessionId === "") {
-            return failure("session", "AcpSessionFailure", "session-id-missing");
+            outcome = failure("session", "AcpSessionFailure", "session-id-missing");
+            sessionReady = false;
+          } else {
+            await config.sessionIdentity.bind(request.principal, sessionId);
           }
-          await config.sessionIdentity.bind(request.principal, sessionId);
         }
 
+        if (sessionReady) {
         // set_model seat provider:model (#778); may rebuild agent — re-bind via loadSession.
         if (config.modelPassing === "set_model" && request.model !== undefined && sessionId !== undefined) {
           await rpc("session/set_model", {
@@ -300,6 +388,9 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
             if (abortSignal !== undefined) abortParts.push(abortSignal);
             const combinedAbort = AbortSignal.any(abortParts);
             let result: Readonly<Record<string, unknown>>;
+            // Open the prose gate only for this prompt round; clear any stale chunks first.
+            agentProseChunks.length = 0;
+            collectAgentProse = prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME;
             try {
               result = await raceAgainstHostAbort(
                 activeConnection.request("session/prompt", {
@@ -310,17 +401,33 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
                 "ACP host aborted",
               );
             } catch (error) {
+              collectAgentProse = false;
+              agentProseChunks.length = 0;
               if (hostSessionRecordFailure !== undefined) {
                 return { status: "terminal", result: hostSessionRecordResult() };
               }
               throw error;
             }
+            collectAgentProse = false;
             if (result.stopReason === "refusal") {
+              agentProseChunks.length = 0;
               return {
                 status: "terminal",
                 result: failure("output", "AcpRefusal", "refusal", { sessionId }),
               };
             }
+            // #959: navigator prose exit when the model spoke without the output tool.
+            // Tool path still wins via MCP; ingest is a no-op once the tool already sealed.
+            // Emptiness via shared projector; payload keeps original bytes (LLM 原话过手).
+            if (prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME) {
+              const prose = agentProseChunks.join("");
+              agentProseChunks.length = 0;
+              if (navigatorProseFromUnknown(prose) !== undefined) {
+                await prepared.ingestStructuredOutput({ prose });
+              }
+            } else {
+              agentProseChunks.length = 0;
+            }
             return { status: "delivered", stderr: activeConnection.stderr?.() ?? "" };
           },
           async afterAccepted() {
@@ -328,14 +435,19 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
             accepted = true;
           },
         });
-        if (hostSessionRecordFailure !== undefined) return hostSessionRecordResult();
-        return turnResult;
+        outcome = hostSessionRecordFailure !== undefined ? hostSessionRecordResult() : turnResult;
+        } // sessionReady
+        } // model match else
       } catch (error) {
         // recordAbort races setup RPCs via raceAgainstHostAbort (host-aborted code);
         // noteHostSessionRecordFailure always sets the typed failure before aborting.
-        if (hostSessionRecordFailure !== undefined) return hostSessionRecordResult();
-        throw error;
+        if (hostSessionRecordFailure !== undefined) {
+          outcome = hostSessionRecordResult();
+        } else {
+          throw error;
+        }
       }
+      } // mcpServers else
     } finally {
       if (connection !== undefined) {
         if (sessionId !== undefined && !accepted) {
@@ -345,8 +457,12 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
         try { await connection.close(); }
         catch { /* keep turn result */ }
       }
-      try { await prepared.dispose?.(); }
-      catch { /* keep turn result */ }
+      try {
+        await prepared.dispose?.();
+      } catch (cleanupError) {
+        outcome = withCleanupFailure(outcome, cleanupError);
+      }
     }
+    return outcome;
   });
 }

package/src/headless-host/description.ts

@@ -83,7 +83,11 @@ export function headlessTurnArgs(options: {
   readonly description: ClaudePrintHostDescription;
   /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /**
+   * Closed JSON Schema for structured_output seats.
+   * Optional: omit for prose-exit seats (#959 navigator) so the model may speak free text.
+   */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
   /** Absolute path to host-native MCP config JSON; omitted when no AK MCP servers. */
   readonly mcpConfigPath?: string;
   readonly model?: string;
@@ -99,9 +103,10 @@ export function headlessTurnArgs(options: {
     ...description.fixedArgs,
     description.systemPromptFlag,
     options.systemPromptPath,
-    description.jsonSchemaFlag,
-    JSON.stringify(options.jsonSchema),
   ];
+  if (options.jsonSchema !== undefined) {
+    args.push(description.jsonSchemaFlag, JSON.stringify(options.jsonSchema));
+  }
   if (options.pluginDir) args.push("--plugin-dir", options.pluginDir);
   if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
     args.push(description.mcpConfigFlag, options.mcpConfigPath);
@@ -145,7 +150,7 @@ function codexTomlStringTable(entries: Readonly<Record<string, string>>): string
  * Free-form JSON leaf for Type.Unknown under Codex strict transport.
  * Strict rejects bare untyped nodes and root-level additionalProperties:true;
  * a $defs anyOf of JSON values (with nested additionalProperties as $ref)
- * is accepted and keeps array/object receipts expressible (navigator candidates).
+ * is accepted and keeps array/object receipts expressible.
  * Package code still does not validate or reject the receipt against schema.
  */
 const CODEX_JSON_VALUE_DEF = "codexJsonValue";
@@ -398,8 +403,11 @@ function codexMcpConfigArgs(
 export function codexTurnArgs(options: {
   /** Absolute path for `-c model_instructions_file=…`. */
   readonly systemPromptPath: string;
-  /** Absolute path for `--output-schema` (closed transport schema). */
-  readonly outputSchemaPath: string;
+  /**
+   * Absolute path for `--output-schema` (closed transport schema).
+   * Optional: omit for prose-exit seats (#959 navigator) so agent_message stays free text.
+   */
+  readonly outputSchemaPath?: string;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly model?: string;
   readonly effort?: string;
@@ -441,7 +449,9 @@ export function codexTurnArgs(options: {
   }
 
   args.push("-c", `model_instructions_file=${codexTomlString(options.systemPromptPath)}`);
-  args.push("--output-schema", options.outputSchemaPath);
+  if (options.outputSchemaPath !== undefined) {
+    args.push("--output-schema", options.outputSchemaPath);
+  }
   args.push(...codexMcpConfigArgs(options.mcpServers));
 
   if (options.model !== undefined && options.model !== "") {

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

@@ -39,6 +39,7 @@ import {
   isPlainObject,
   type HeadlessHostDescription,
 } from "./description.ts";
+import { NAVIGATOR_OUTPUT_TOOL_NAME } from "../package-contracts/navigator-output.ts";
 
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
@@ -406,7 +407,8 @@ function terminalFromSpawned(
 function buildTurnArgs(options: {
   readonly description: HeadlessHostDescription;
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /** Closed schema; omit for #959 navigator prose-exit seats. */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly mcpConfigPath?: string;
   readonly outputSchemaPath?: string;
@@ -422,10 +424,10 @@ function buildTurnArgs(options: {
     if (options.sessionKind === "resume" && !options.sessionId) {
       throw new Error("codex resume requires a bound thread_id");
     }
-    if (options.outputSchemaPath === undefined) throw new Error("codex requires an output schema path");
+    // #959: prose-exit seats (navigator) omit --output-schema; other seats still require it.
     return codexTurnArgs({
       systemPromptPath: options.systemPromptPath,
-      outputSchemaPath: options.outputSchemaPath,
+      ...(options.outputSchemaPath === undefined ? {} : { outputSchemaPath: options.outputSchemaPath }),
       mcpServers: options.mcpServers,
       ...(options.model === undefined ? {} : { model: options.model }),
       ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -443,7 +445,8 @@ function buildTurnArgs(options: {
   return headlessTurnArgs({
     description: options.description,
     systemPromptPath: options.systemPromptPath,
-    jsonSchema: options.jsonSchema,
+    // #959: navigator omits --json-schema so free-form prose is a lawful exit.
+    ...(options.jsonSchema === undefined ? {} : { jsonSchema: options.jsonSchema }),
     mcpConfigPath: options.mcpConfigPath,
     ...(options.model === undefined ? {} : { model: options.model }),
     ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -482,12 +485,15 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
         ? (prompt) => applyCodexSkillInvocation(request.methods, prompt)
         : (prompt) => prompt;
       if (codex) {
-        outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-        await writeFile(
-          outputSchemaPath,
-          `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
-          "utf8",
-        );
+        // #959: navigator is a prose-exit seat — no closed output-schema.
+        if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
+          outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
+          await writeFile(
+            outputSchemaPath,
+            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            "utf8",
+          );
+        }
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
         await writeFile(
@@ -517,7 +523,10 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
             args = buildTurnArgs({
               description: config.description,
               systemPromptPath,
-              jsonSchema: prepared.jsonSchema,
+              // #959: navigator prose exit — no closed JSON schema on claude either.
+              ...(prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+                ? {}
+                : { jsonSchema: prepared.jsonSchema }),
               mcpServers: prepared.mcpServers,
               ...(mcpConfigPath === undefined ? {} : { mcpConfigPath }),
               ...(outputSchemaPath === undefined ? {} : { outputSchemaPath }),
@@ -657,6 +666,20 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               });
             }
 
+            // #959: navigator prose exit — final agent_message is presented as-is.
+            // Empty text is not a lawful accepted receipt (align pi no_receipt / loud empty).
+            if (prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME) {
+              if (observation.finalMessage.trim() === "") {
+                return terminalFromSpawned(spawned, {
+                  cause: "output",
+                  identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
+                  diagnostic: spawned.stderr.trim() || "codex exec produced empty agent_message",
+                  details: { sessionId, exitCode: spawned.code },
+                });
+              }
+              await prepared.ingestStructuredOutput({ prose: observation.finalMessage });
+              return { status: "delivered", stderr: spawned.stderr };
+            }
             let receipt: unknown;
             try {
               receipt = JSON.parse(observation.finalMessage);
@@ -716,6 +739,14 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
 
           if (envelope.structured_output !== undefined) {
             await prepared.ingestStructuredOutput(envelope.structured_output);
+          } else if (
+            prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+            && typeof envelope.result === "string"
+            && envelope.result.trim() !== ""
+          ) {
+            // #959: claude prose exit — free-form result text is the receipt body
+            // when structured_output is absent (json-schema omitted for navigator).
+            await prepared.ingestStructuredOutput({ prose: envelope.result });
           }
           return { status: "delivered", stderr: spawned.stderr };
         },

package/src/host-contracts.ts

@@ -100,7 +100,6 @@ export type RoleTurnActivation =
   | {
       readonly role: "reviewer";
       readonly baseRevision: string;
-      /** Caller-selected single lens; no default (ADR 0082 reviewer-method-lens). */
       readonly lens: "completeness" | "correctness";
       readonly authorityRefs: readonly string[];
       readonly ticketNumber?: number;