@akagilnc/pi-workflow-roles 0.1.4586 → 0.1.4631

package/src/navigator-public-session.ts

@@ -2,9 +2,12 @@
  * Navigator attendance session factory (#675 r3).
  * Each prepare turn uses the public navigator activation path (summonPublicRole) —
  * same seat table and shared envelope as `ak-role navigator`.
- * Archivist createRecordSession only books route-memory nest under the parent;
- * no openPiInProcessSession second lifecycle / no agentDir patch on the old path.
+ * Archivist createRecordSession books the attendance nest under the parent;
+ * host conversation continuity uses CLI resume (`resumeRunId`), not a package
+ * advice ledger (development-closure: do not invent package-level memory).
  */
+import { basename } from "node:path";
+
 import { sitianReport } from "./sitian-facade.ts";
 import {
   NavigatorUnavailableError,
@@ -17,6 +20,8 @@ import {
 } from "./navigator-session-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
+import type { PublicSummonResult } from "./public-role-summons.ts";
+import { CliUsageError } from "./public-cli/cli-errors.ts";
 
 /**
  * Ledger process home for navigator attendance: admitted HostContext.runDirectory
@@ -40,13 +45,73 @@ async function resolveNavigatorLedgerHome(context: HostContext): Promise<string
   return undefined;
 }
 
-export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
+/** Resume key only — points at a host run principal, never stores advice prose. */
+export const NAVIGATOR_HOST_RUN_POINTER_ENTRY = "ak-navigator-host-run";
+
+function exactRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function runIdFromNavigatorDirectory(runDirectory: string): string | undefined {
+  const entry = basename(runDirectory);
+  const suffix = "@navigator";
+  if (!entry.endsWith(suffix)) return undefined;
+  const runId = entry.slice(0, entry.length - suffix.length);
+  return runId.length > 0 ? runId : undefined;
+}
+
+export function readNavigatorHostRunPointer(entries: readonly unknown[]): string | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (!exactRecord(entry)) continue;
+    if (entry.type === "custom" && entry.customType === NAVIGATOR_HOST_RUN_POINTER_ENTRY) {
+      const data = entry.data;
+      if (exactRecord(data) && typeof data.runId === "string" && data.runId.trim() !== "") {
+        return data.runId.trim();
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Typed preflight via public CLI load path: can this run reopen as navigator?
+ * CliUsageError (code AK_ROLE_USAGE) from loadResumableInstructionSeatRun means
+ * unknown id / principal unavailable / non-instruction seat — not resumable.
+ * Other throws propagate. Never reads stderr prose.
+ */
+export async function navigatorHostRunResumable(home: string, runId: string): Promise<boolean> {
+  const { piDurablePrincipalAuthority } = await import("./pi/durable-principal.ts");
+  const { loadResumableInstructionSeatRun } = await import("./public-cli/run-lifecycle.ts");
+  try {
+    const loaded = await loadResumableInstructionSeatRun(home, runId, piDurablePrincipalAuthority);
+    return loaded.admitted.role === "navigator";
+  } catch (error) {
+    if (error instanceof CliUsageError) return false;
+    throw error;
+  }
+}
+
+export type NavigatorPublicSummon = (options: {
+  readonly role: "navigator";
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly home?: string;
+  readonly resumeRunId?: string;
+}) => Promise<PublicSummonResult>;
+
+export function createNativeNavigatorSessionFactory(deps?: {
+  /** Test/composition inject — production leaves unset and uses public-role-summons. */
+  readonly summonPublicRole?: NavigatorPublicSummon;
+  /** Test inject — production uses navigatorHostRunResumable (typed CLI load). */
+  readonly hostRunResumable?: (home: string, runId: string) => Promise<boolean>;
+}): NavigatorSessionFactory {
   return async ({ context, subject, tool }) => {
     // Model is enforced at prepare (attendance seat resolve) and at prompt (summon).
     // Factory open only books the archivist nest — no package default, no eager seat read.
     let thinkingLevel: string | undefined;
 
-    // Archivist nest for attendance route memory only (ADR 0018 / 0065) — not a session open.
+    // Archivist nest for attendance bookkeeping (ADR 0018 / 0065) — not a host session open.
     // #852: navigator/<work-subject> is the sole book-top exception; always pass subject so
     // unmaterialized/missing parent still gets a durable nest instead of silent in-memory.
     // Home comes from HostContext.runDirectory (or ledger parent path) — never context.home.
@@ -64,6 +129,14 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
     let noReceipt: NoReceiptLifecycleFacts | undefined;
     let disposed = false;
     let inFlightPrompt: Promise<unknown> | undefined;
+    /** In-factory host run id for CLI resume; durable pointer also lives on the nest. */
+    let hostRunId = readNavigatorHostRunPointer(sessionManager.getEntries() as readonly unknown[]);
+
+    const summon: NavigatorPublicSummon = deps?.summonPublicRole
+      ?? (async (options) => {
+        const { summonPublicRole } = await import("./public-role-summons.ts");
+        return summonPublicRole(options);
+      });
 
     return {
       prompt: async (text) => {
@@ -74,15 +147,28 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
         noReceipt = undefined;
         const run = (async () => {
         try {
-          const { summonPublicRole } = await import("./public-role-summons.ts");
           const summonHome = await resolveNavigatorLedgerHome(context);
-          // Public activation — same face as `ak-role navigator <instruction>` (#675).
-          const summoned = await summonPublicRole({
-            role: "navigator",
-            argv: [text],
+          const resumeRunId = hostRunId;
+
+          const baseSummon = {
+            role: "navigator" as const,
+            argv: [text] as const,
             cwd: context.cwd,
             ...(summonHome === undefined ? {} : { home: summonHome }),
-          });
+          };
+
+          // Prefer host CLI resume so prior advice stays on the host session.
+          // Fresh mint only when typed load says the principal cannot reopen.
+          const resumable = deps?.hostRunResumable ?? navigatorHostRunResumable;
+          let summoned: PublicSummonResult;
+          if (resumeRunId === undefined || summonHome === undefined) {
+            summoned = await summon(baseSummon);
+          } else if (await resumable(summonHome, resumeRunId)) {
+            summoned = await summon({ ...baseSummon, resumeRunId });
+          } else {
+            hostRunId = undefined;
+            summoned = await summon(baseSummon);
+          }
 
           const outcome = summoned.terminal?.roleOutcome;
           if (outcome === undefined) {
@@ -109,23 +195,40 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
             noReceipt = outcome;
             return;
           }
+
+          // Pin host run for the next attendance prompt on this subject (CLI resume key).
+          const runDirectory = summoned.runDirectory
+            ?? (typeof summoned.admitted?.runDirectory === "string"
+              ? summoned.admitted.runDirectory
+              : undefined);
+          if (typeof runDirectory === "string" && runDirectory.trim() !== "") {
+            const nextRunId = runIdFromNavigatorDirectory(runDirectory);
+            if (nextRunId !== undefined) {
+              hostRunId = nextRunId;
+              sessionManager.appendCustomEntry(NAVIGATOR_HOST_RUN_POINTER_ENTRY, { runId: nextRunId });
+            }
+          }
+
           if (outcome.kind !== "accepted") {
-            // Non-accepted kinds (e.g. audit_escalation): no route advice this turn.
+            // Non-accepted kinds (e.g. audit_escalation): no prose advice this turn.
             // 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[] = [];
           for (const payload of outcome.payloads ?? []) {
-            if (typeof payload !== "object" || payload === null || Array.isArray(payload)) continue;
-            const candidates = (payload as { candidates?: unknown }).candidates;
-            if (!Array.isArray(candidates)) continue;
-            await tool.execute(
-              "navigator-public-prepare",
-              { candidates },
-              undefined,
-              undefined,
-              context as never,
-            );
+            const prose = navigatorProseFromUnknown(payload);
+            if (prose !== undefined) proseParts.push(prose);
           }
+          if (proseParts.length === 0) return;
+          await tool.execute(
+            "navigator-public-prepare",
+            { prose: proseParts.join("\n\n") },
+            undefined,
+            undefined,
+            context as never,
+          );
         } catch (error) {
           if (error instanceof NavigatorUnavailableError) throw error;
           const fact = navigatorProviderFailureFromError(error);
@@ -166,10 +269,8 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
         } catch (error) {
           throw navigatorUnavailableError("model", error);
         }
-        // No live provider session is pinned here: every prompt is an independent
-        // public summon whose nested CLI reads the current seat table (#675 验收②
-        // / #617 DK-3). A seat edit between prepares therefore applies on the next
-        // summon — it is never an unavailable session.
+        // 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,

package/src/navigator-role.ts

@@ -2,12 +2,12 @@ import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-con
 
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
- * Candidates share the route-advice shape the attendance prepare tool owns.
+ * #959: navigator speaks free-form prose; tool is a lifecycle vehicle only.
  */
 export const NAVIGATOR_TOOL_SPEC = {
   name: NAVIGATOR_OUTPUT_TOOL_NAME,
   label: "游奕使建议",
-  description: "游奕使终局回执：排好序的下一步角色路线建议。",
+  description: "游奕使终局回执：散文建议，原样呈现。",
   promptSnippet: "游奕使建议",
   parameters: navigatorOutputSchema,
 } as const;

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

@@ -1,7 +1,8 @@
 /**
- * Public Navigator (游奕使) terminating receipt contracts (#639).
- * Direct public seat submits route advice with the same candidate shape the
- * attendance prepare tool owns — one shape authority for navigator advice.
+ * 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.
  * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
  */
 import { Type } from "typebox";
@@ -15,42 +16,57 @@ export const NAVIGATOR_ACCEPTED_TEXT = "游奕使建议已受理";
 export const navigatorOutputSchema = withTerminatingOutputDeclarations(
   openToolObject(
     Type.Object({
-      status: Type.Unknown({
-        description: "advice — 形状指引，非 schema 闸",
-      }),
-      candidates: Type.Unknown({
-        description: "排好序的路线建议数组，元素含 next/phase/reason — 形状指引，非 schema 闸",
+      prose: Type.Unknown({
+        description: "游奕使散文建议，原样呈现。不要求 candidates/next 等结构化字段。形状指引，非 schema 闸",
       }),
     }),
   ),
 );
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-export type NavigatorAdvice = { readonly status: "advice"; readonly candidates: readonly unknown[] };
+export type NavigatorAdvice = { readonly prose: string };
 
 /**
- * Project one lawful explicit Navigator advice receipt: candidates array,
- * each candidate a record. Broken ancillary fields are preserved as submitted —
- * shape is not an admission gate (ADR 0055 / 第 0 条).
+ * Project one Navigator advice receipt as prose.
+ * 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 / 第 0 条 / #959).
  */
 export function projectLawfulNavigatorOutput(value: unknown): NavigatorAdvice | undefined {
-  // #836: no field drop
-  return (typeof value === "object" && value !== null && !Array.isArray(value))
-    ? (value as NavigatorAdvice)
-    : undefined;
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return { prose: value };
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const record = value as Record<string, unknown>;
+    if (typeof record.prose === "string") return { prose: record.prose };
+    if (record.prose !== undefined && record.prose !== null) {
+      return { prose: typeof record.prose === "string" ? record.prose : String(record.prose) };
+    }
+    // Free-form object submission: present the whole body as prose when it has content.
+    const keys = Object.keys(record);
+    if (keys.length === 0) return { prose: "" };
+    try {
+      return { prose: JSON.stringify(record) };
+    } catch {
+      return { prose: String(record) };
+    }
+  }
+  return { prose: String(value) };
 }
 
 /**
- * Settlement/recording path: only lawful recorded candidate arrays.
- * Does not gate role admission — callers must not use this to reject a submission.
+ * Settlement/recording path: project prose. Does not gate role admission.
  */
 export function validateRecordedNavigatorOutput(value: unknown): NavigatorAdvice {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Navigator output is not an object");
+  const projected = projectLawfulNavigatorOutput(value);
+  if (projected === undefined) {
+    throw new Error("Navigator output is empty");
   }
-  return value as NavigatorAdvice;
+  return projected;
 }
 
+/** Extract display prose from any navigator payload / attendance body. */
+export function navigatorProseFromUnknown(value: unknown): string | undefined {
+  const projected = projectLawfulNavigatorOutput(value);
+  if (projected === undefined) return undefined;
+  const trimmed = projected.prose.trim();
+  return trimmed === "" ? undefined : projected.prose;
+}

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

@@ -470,9 +470,6 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
       ) {
         env.AK_ROLE_AUDITOR_SUBJECT = process.env.AK_ROLE_AUDITOR_SUBJECT;
       }
-      if (request.correlationId !== undefined && request.correlationId.trim() !== "") {
-        env.AK_CORRELATION_ID = request.correlationId;
-      }
       if (
         config.recordLaunchedRolePackageIdentity !== undefined &&
         config.observeLaunchedRolePackageIdentity !== undefined

package/src/public-cli/auto-resume.ts

@@ -32,6 +32,7 @@ import {
   type RunWriterLease,
 } from "./run-lifecycle.ts";
 import { parseAutoResumeLimit } from "./config.ts";
+import { processCancelSignalName } from "./process-cancel.ts";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
 import {
   attachRecordedSubmissions,
@@ -473,6 +474,11 @@ export async function runWithAutoResumeLoop<
    * before the first dispatch instead of silently bypassing the ceiling comparison.
    */
   autoResumeLimit?: number | undefined;
+  /**
+   * #855: process-cancel signal. Once aborted by a catchable process signal,
+   * the loop must not dispatch another turn or spawn another child.
+   */
+  signal?: AbortSignal;
   buildInitialPayload: () => TPayload;
   buildResumePayload: () => TPayload;
   dispatch: (payload: TPayload, lease: RunWriterLease, isFirst: boolean, attemptIo: CliIo) => Promise<T>;
@@ -578,6 +584,11 @@ export async function runWithAutoResumeLoop<
         if (terminal !== undefined) presentTerminal(terminal, options.io);
         return result;
       }
+      // #855: process cancel — stop even if dispatch forgot skipAutoResume.
+      if (processCancelSignalName(options.signal) !== undefined) {
+        if (terminal !== undefined) presentTerminal(terminal, options.io);
+        return result;
+      }
     }
 
     if (result !== undefined) {
@@ -616,6 +627,29 @@ export async function runWithAutoResumeLoop<
           terminal,
         } as T;
       }
+      // #855: process cancel on the throw path — do not re-dispatch; name the signal.
+      const cancelName = processCancelSignalName(options.signal);
+      if (cancelName !== undefined) {
+        const terminal = await attachDispatchExceptionTerminal(
+          options.admitted,
+          dispatchExceptionFailureTerminal({
+            role: options.admitted.role,
+            runId: options.admitted.runId,
+            causeError: lastThrownError,
+            errorFiles: retainedErrorFiles,
+            autoResumeAttempts,
+            endReason: `ak-role terminated by ${cancelName}`,
+            everyAttemptThrew,
+          }),
+          options.io,
+        );
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal,
+        } as T;
+      }
       if (!(await isPrincipalAvailable(options.admitted.principal))) {
         const terminal = await attachDispatchExceptionTerminal(
           options.admitted,

package/src/public-cli/cli.ts

@@ -305,6 +305,11 @@ export type CliEnv = {
    * skip same-ticket auto-resume. Not a public flag — the verb is the choice.
    */
   freshSummons?: true;
+  /**
+   * #855: process-level cancel (SIGTERM/SIGINT/SIGHUP). Nested turns receive
+   * the same signal so hosts can gracefully stop children.
+   */
+  signal?: AbortSignal;
 };
 
 
@@ -413,6 +418,7 @@ function createRoleEnvironment(
       ? {}
       : { autoResumeLimit: options.config.autoResumeLimit }),
     ...(env.freshSummons === true ? { freshSummons: true as const } : {}),
+    ...(env.signal === undefined ? {} : { signal: env.signal }),
   };
 }
 
@@ -1168,6 +1174,30 @@ async function runConfigCommand(
   throw new CliUsageError(`unknown config subcommand: ${args[0]}`);
 }
 
+/**
+ * #855: process-cancel handlers only for commands that run a role turn
+ * (callable roles / resume / new). analyst/roles/config/help keep Node's
+ * default SIGINT/SIGTERM termination — installing handlers would swallow Ctrl+C.
+ */
+export function commandNeedsProcessCancel(argv: readonly string[]): boolean {
+  // Decision-time parse must not escape the CLI usage boundary. Malformed
+  // global flags throw CliUsageError here; return false and let runAkRole
+  // present the same structured usage reject (exit 2). Handlers are moot
+  // when parse fails — install-or-not has no subsequent effect.
+  let parsed: ParsedGlobal;
+  try {
+    parsed = parseArgv(argv);
+  } catch (error) {
+    if (error instanceof CliUsageError) return false;
+    throw error;
+  }
+  if (parsed.help || parsed.command === undefined || parsed.command === "help") {
+    return false;
+  }
+  if (parsed.command === "resume" || parsed.command === "new") return true;
+  return isPublicCallableRole(parsed.command);
+}
+
 export async function runAkRole(
   argv: readonly string[],
   env: CliEnv,

package/src/public-cli/coder-run.ts

@@ -22,7 +22,7 @@ import {
   type AdmittedCoderInvocation,
 } from "./invocation.ts";
 import {
-  buildResumeContinuationPrompt,
+  buildAutoResumeContinuationPrompt,
   loadResumableCoderRun,
   markRunAdmitted,
   type PublicResumeRequest,
@@ -198,7 +198,7 @@ export async function runPublicCoder(
           : { correlationId: admitted.correlationId ?? env.correlationId }),
         continuation: {
           kind: "resume",
-          prompt: buildResumeContinuationPrompt({
+          prompt: buildAutoResumeContinuationPrompt({
             packageRoot: env.packageRoot,
             ...pickEngineAxis(env),
           }),

package/src/public-cli/fixer-run.ts

@@ -25,7 +25,7 @@ import {
   type AdmittedFixerInvocation,
 } from "./invocation.ts";
 import {
-  buildResumeContinuationPrompt,
+  buildAutoResumeContinuationPrompt,
   loadResumableFixerRun,
   markRunAdmitted,
   type PublicResumeRequest,
@@ -213,7 +213,7 @@ export async function runPublicFixer(
           : { correlationId: admitted.correlationId ?? env.correlationId }),
         continuation: {
           kind: "resume",
-          prompt: buildResumeContinuationPrompt({
+          prompt: buildAutoResumeContinuationPrompt({
             packageRoot: env.packageRoot,
             ...pickEngineAxis(env),
           }),

package/src/public-cli/judge-run.ts

@@ -18,7 +18,7 @@ import {
 import {
   loadResumableJudgeRun,
   markRunAdmitted,
-  buildResumeContinuationPrompt,
+  buildAutoResumeContinuationPrompt,
   type PublicResumeRequest,
 } from "./run-lifecycle.ts";
 import {
@@ -152,7 +152,7 @@ export async function runPublicJudge(
           : { correlationId: admitted.correlationId ?? env.correlationId }),
         continuation: {
           kind: "resume",
-          prompt: buildResumeContinuationPrompt({
+          prompt: buildAutoResumeContinuationPrompt({
             packageRoot: env.packageRoot,
             ...pickEngineAxis(env),
           }),

package/src/public-cli/main.ts

@@ -34,6 +34,28 @@ process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
 // The host-provided runtime must be resolvable before the CLI module graph loads it.
 ensureHostPiRuntimeResolvable(packageRoot);
 
-const { runAkRole } = await import("./cli.ts");
-const result = await runAkRole(process.argv.slice(2), { packageRoot });
-process.exitCode = result.exitCode;
+const { runAkRole, commandNeedsProcessCancel } = await import("./cli.ts");
+const { installProcessCancelHandlers } = await import("./process-cancel.ts");
+
+// #855: catchable signals only for role-turn commands. analyst/roles/config/help
+// keep Node default termination — global handlers would swallow Ctrl+C.
+const argv = process.argv.slice(2);
+const processCancel = commandNeedsProcessCancel(argv)
+  ? installProcessCancelHandlers()
+  : undefined;
+try {
+  const result = await runAkRole(argv, {
+    packageRoot,
+    ...(processCancel === undefined ? {} : { signal: processCancel.signal }),
+  });
+  // Signal termination is never a successful public exit, even if a seat
+  // somehow returned zero before settlement folded the abort.
+  process.exitCode =
+    processCancel !== undefined &&
+    processCancel.receivedSignal() !== undefined &&
+    result.exitCode === 0
+      ? 1
+      : result.exitCode;
+} finally {
+  processCancel?.dispose();
+}

package/src/public-cli/merger-run.ts

@@ -24,7 +24,7 @@ import {
 import {
   loadResumableMergerRun,
   markRunAdmitted,
-  buildResumeContinuationPrompt,
+  buildAutoResumeContinuationPrompt,
   type PublicResumeRequest,
 } from "./run-lifecycle.ts";
 import {
@@ -241,7 +241,7 @@ export async function runPublicMerger(
           : { correlationId: admitted.correlationId ?? env.correlationId }),
         continuation: {
           kind: "resume",
-          prompt: buildResumeContinuationPrompt({
+          prompt: buildAutoResumeContinuationPrompt({
             packageRoot: env.packageRoot,
             ...pickEngineAxis(env),
           }),

package/src/public-cli/option-definitions.ts

@@ -1280,7 +1280,7 @@ const ROLE_COMMAND_HELP = {
   },
   navigator: {
     command: "navigator",
-    summary: "Direct Navigator (游奕使) route advice: ordered next-role candidates.",
+    summary: "Direct Navigator (游奕使) free-form prose route advice.",
     usage: ["ak-role navigator [options] [instruction]"],
     examples: [
       'ak-role navigator "刚完成 coder apply 收敛，下一步？"',