@akagilnc/pi-workflow-roles 0.1.4586 → 0.1.4631

package/dist/submission-ledger.js

@@ -338,6 +338,59 @@ async function restoreState(cwd, runId, scope) {
         }, 0),
     };
 }
+/** Sole HostContext-derived session parent for ledger restore/append (never process.env). */
+function sessionParentFromHostContext(context) {
+    const runDirectory = runDirectoryFromHostContext(context);
+    if (runDirectory !== undefined)
+        return join(runDirectory, "session", "session.jsonl");
+    const sessionFile = context.sessionManager.getSessionFile?.();
+    if (typeof sessionFile === "string" && sessionFile.length > 0)
+        return sessionFile;
+    const sessionDir = context.sessionManager.getSessionDir?.();
+    if (typeof sessionDir === "string" && sessionDir.length > 0) {
+        return join(sessionDir, "session.jsonl");
+    }
+    return undefined;
+}
+function homeFromHostContext(context, home) {
+    if (home !== undefined)
+        return home;
+    const sessionParent = sessionParentFromHostContext(context);
+    return sessionParent !== undefined ? tryHomeFromAkRolesPath(sessionParent) : undefined;
+}
+/**
+ * #959: seal one accepted submission without a model tool call.
+ * Same ledger row shape and priorEventId chain as the terminating-tool wrap.
+ * Used when a prose-exit seat (navigator) harvests the final assistant text.
+ */
+export async function sealAcceptedSubmission(options) {
+    const runId = runIdentity(options.context);
+    const attemptId = attemptIdentity(options.context, runId);
+    const sessionParent = sessionParentFromHostContext(options.context);
+    const home = homeFromHostContext(options.context, options.home);
+    const state = await restoreState(options.context.cwd, runId, {
+        ...(home === undefined ? {} : { home }),
+        ...(sessionParent === undefined ? {} : { sessionParent }),
+    });
+    const pointer = sitianReport({
+        level: "event",
+        kind: "sealed",
+        subject: { runId, attemptId },
+        ...(state.prior === undefined ? {} : { priorEventId: state.prior.identity }),
+        payload: {
+            type: "sealed",
+            attemptId,
+            toolCallId: options.toolCallId,
+            role: options.role,
+            accepted: options.accepted,
+        },
+        source: "role-runtime",
+        cwd: options.context.cwd,
+        ...(home !== undefined ? { home } : {}),
+        ...(sessionParent === undefined ? {} : { sessionParent }),
+    });
+    state.prior = pointer;
+}
 /**
  * Submission ledger host — record only (#836).
  * Each terminating submission is appended with the role's original payload.
@@ -346,30 +399,10 @@ async function restoreState(cwd, runId, scope) {
  */
 export function createSubmissionLedgerHost(host, outputTools, failInfrastructure = (error) => { throw error; }, projectClosure = () => undefined, options) {
     const states = new Map();
-    /** Sole HostContext-derived run coordinate for restore and append (never process.env). */
-    const sessionParentFromContext = (context) => {
-        const runDirectory = runDirectoryFromHostContext(context);
-        if (runDirectory !== undefined) {
-            return join(runDirectory, "session", "session.jsonl");
-        }
-        const sessionFile = context.sessionManager.getSessionFile?.();
-        if (typeof sessionFile === "string" && sessionFile.length > 0)
-            return sessionFile;
-        const sessionDir = context.sessionManager.getSessionDir?.();
-        if (typeof sessionDir === "string" && sessionDir.length > 0) {
-            return join(sessionDir, "session.jsonl");
-        }
-        return undefined;
-    };
-    const resolveHomeFromContext = (context) => {
-        if (options?.home !== undefined)
-            return options.home;
-        const sessionParent = sessionParentFromContext(context);
-        return sessionParent !== undefined ? tryHomeFromAkRolesPath(sessionParent) : undefined;
-    };
+    const resolveHomeFromContext = (context) => homeFromHostContext(context, options?.home);
     const stateFor = (context, runId) => states.get(runId) ?? (() => {
         const home = resolveHomeFromContext(context);
-        const sessionParent = sessionParentFromContext(context);
+        const sessionParent = sessionParentFromHostContext(context);
         const pending = restoreState(context.cwd, runId, {
             ...(home === undefined ? {} : { home }),
             ...(sessionParent === undefined ? {} : { sessionParent }),
@@ -379,7 +412,7 @@ export function createSubmissionLedgerHost(host, outputTools, failInfrastructure
     })();
     const appendFor = (state, context, runId, attemptId, event) => {
         const home = resolveHomeFromContext(context);
-        const sessionParent = sessionParentFromContext(context);
+        const sessionParent = sessionParentFromHostContext(context);
         const pointer = sitianReport({
             level: "event",
             kind: event.type,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4586",
+  "version": "0.1.4631",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -14,5 +14,7 @@
 | `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 迁入同手册；代码只留中立指针句「本轮为结算投喂轮。」 |
 
 催交句与 2.1–2.3 打回文、重问三句不在删除列。

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).
@@ -20,8 +19,11 @@ const entries = [
   "pi/in-process-session",
   "activation-ledger-git",
   "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 +207,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/activation-ledger-topology.ts

@@ -91,11 +91,6 @@ export function activationBookDirectory(ledgerHome: string, bookKey: string): st
   return join(ledgerHome, "books", bookKey);
 }
 
-/** Append-only waiting ledger path for one book. */
-export function activationWaitingLedgerPath(ledgerHome: string, bookKey: string): string {
-  return join(activationBookDirectory(ledgerHome, bookKey), "waiting.jsonl");
-}
-
 /** True when candidate resolves strictly inside root (boundary-safe; not a string-prefix check). */
 export function pathContainedIn(root: string, candidate: string): boolean {
   const rel = relative(root, candidate);
@@ -323,7 +318,7 @@ export function ensureRealDirectoryTree(root: string, targetDir: string): string
 
 /**
  * Reject a pre-existing ledger-file symlink before open/write follows it.
- * A computed book may only append to its own regular waiting.jsonl — any symlink,
+ * A computed book path may only write its own regular file — any symlink,
  * including a target still inside the machine ledger home (cross-book redirect),
  * violates ADR 0048 partition identity. Missing paths are admitted (O_CREAT).
  */