@akagilnc/pi-workflow-roles 0.1.4528 → 0.1.4620

package/dist/public-cli/option-definitions.js

@@ -436,12 +436,12 @@ const REVIEWER_OPTIONS = [
         canonical: "--lens",
         aliases: [],
         valueMetavar: "completeness|correctness",
-        required: true,
+        required: false,
         repeatable: false,
         form: "option",
         description: {
-            en: "Required single review lens: completeness or correctness (no default).",
-            zh: "必填单 lens：completeness 或 correctness（无默认值）。",
+            en: "Optional single-lens override: completeness or correctness; omitted runs both in parallel.",
+            zh: "可选单 lens 覆盖：completeness 或 correctness；省略时并行运行两轴。",
         },
     },
     {
@@ -997,9 +997,9 @@ const ROLE_COMMAND_HELP = {
     },
     reviewer: {
         command: "reviewer",
-        summary: "Fixed-target single-lens review (completeness or correctness).",
+        summary: "Fixed-target parallel two-lens review, with an optional single-lens override.",
         usage: [
-            "ak-role reviewer --base <revision> --lens completeness|correctness --authority-ref <ref> [options] <instruction>",
+            "ak-role reviewer --base <revision> [--lens completeness|correctness] --authority-ref <ref> [options] <instruction>",
         ],
         examples: [
             'ak-role reviewer --base main --lens completeness --authority-ref docs/adr/0001.md "Review the branch."',
@@ -1050,7 +1050,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 收敛，下一步？"',

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

@@ -8,7 +8,7 @@
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
-import { buildResumeContinuationPrompt, RESUME_TRANSPORT_ENVELOPE, } from "./run-lifecycle.js";
+import { buildAutoResumeContinuationPrompt, buildResumeContinuationPrompt, RESUME_TRANSPORT_ENVELOPE, } from "./run-lifecycle.js";
 import { CliUsageError } from "./cli-errors.js";
 import { bindAdmittedTicketNumber, buildInstructionTransportPrompt, freezeAttachmentsIntoRun, } from "./invocation.js";
 import { readRecordedSubmissionRows } from "../submission-ledger.js";
@@ -878,6 +878,9 @@ export async function runPostAdmissionSeatResume(input) {
         }
         adapters = prepared.adapters;
     }
+    // Call-local execution env; afterAdmittedPrepare may replace it (Reviewer fresh-copy).
+    let env = input.env;
+    let preparedCleanup;
     const buildRequestAfterLease = async () => {
         let openCourtAttemptId;
         // Build uses the admitted judged under this lease (rehydrated when open
@@ -945,8 +948,15 @@ export async function runPostAdmissionSeatResume(input) {
     // Court recovery / open under lease, then dispatch.
     // Station-child same-ticket/same-parent resume is call-local auto-resume
     // (#840 / #416). Public `ak-role resume` stays one-shot (ADR 0080).
+    // afterAdmittedPrepare runs inside this try so mint failure and cleanup share one finally.
     try {
-        if (input.env.stationChild === true) {
+        if (input.afterAdmittedPrepare !== undefined) {
+            const prepared = await input.afterAdmittedPrepare(loaded.admitted);
+            if (prepared.env !== undefined)
+                env = prepared.env;
+            preparedCleanup = prepared.cleanup;
+        }
+        if (env.stationChild === true) {
             let firstTurn;
             const stationAdapters = withOnceSuccessfulBeforeDispatch(adapters);
             // One public call → one detour scope across in-place auto-resume dispatches.
@@ -957,11 +967,11 @@ export async function runPostAdmissionSeatResume(input) {
             });
             return await runWithAutoResumeLoop({
                 admitted: loaded.admitted,
-                principalAuthority: input.env.principalAuthority,
-                isPrincipalAvailable: resolveHostAwareSessionAvailability(input.env.host, input.env.principalAuthority),
+                principalAuthority: env.principalAuthority,
+                isPrincipalAvailable: resolveHostAwareSessionAvailability(env.host, env.principalAuthority),
                 io: input.io,
-                sessionAppender: input.env.sessionAppender,
-                autoResumeLimit: input.env.autoResumeLimit,
+                sessionAppender: env.sessionAppender,
+                autoResumeLimit: env.autoResumeLimit,
                 buildInitialPayload: () => ({ resumeTurn: false }),
                 buildResumePayload: () => ({ resumeTurn: true }),
                 // Same as public manual resume: prior-court sealed acceptance is not a
@@ -995,7 +1005,7 @@ export async function runPostAdmissionSeatResume(input) {
                     dispatch: async (turnRequest) => {
                         const result = await dispatchPostAdmissionTurn({
                             admitted: loaded.admitted,
-                            env: input.env,
+                            env,
                             io: attemptIo,
                             request: turnRequest,
                             lease,
@@ -1005,14 +1015,14 @@ export async function runPostAdmissionSeatResume(input) {
                                 ? {}
                                 : { effectiveEngine: input.effectiveEngine }),
                         });
-                        return settleDeferredPersist(loaded.admitted, input.env.principalAuthority, stationAdapters, attemptIo, result);
+                        return settleDeferredPersist(loaded.admitted, env.principalAuthority, stationAdapters, attemptIo, result);
                     },
                 }),
             });
         }
         return await runPostAdmissionManualResume({
             admitted: loaded.admitted,
-            env: input.env,
+            env,
             io: input.io,
             adapters,
             ...(input.effectiveEngine === undefined
@@ -1030,6 +1040,11 @@ export async function runPostAdmissionSeatResume(input) {
         }
         throw error;
     }
+    finally {
+        if (preparedCleanup !== undefined) {
+            await preparedCleanup();
+        }
+    }
 }
 /**
  * Shared post-admission one-shot path: folds into runPostAdmissionResumable (#840 / #416).
@@ -1047,7 +1062,7 @@ export async function runPostAdmissionOneShot(input) {
             ...input.request,
             continuation: {
                 kind: "resume",
-                prompt: buildResumeContinuationPrompt({
+                prompt: buildAutoResumeContinuationPrompt({
                     packageRoot: input.env.packageRoot,
                     ...pickEngineAxis({
                         engine: input.effectiveEngine ?? input.env.engine,

package/dist/public-cli/reviewer-run.js

@@ -0,0 +1,339 @@
+/**
+ * Public Reviewer Role run: admit → post-admission coordinator → settle Terminal result (#917 / #517).
+ * Package-owned ak-cross-m-review method is forced; users never submit
+ * extra packets. Controlled-failure settlement reuses #107.
+ * #526: execution via RoleTurnHost; argv is Pi adapter internal.
+ */
+import { resolve } from "node:path";
+import { appendEngineSessionMaterial, engineSessionMaterialFromOptions, pickEngineAxis, } from "../package-resources/engine-material.js";
+import { loadPackagedMethodSkillMaterial, resolvePackagedMethodSkillPath, } from "../package-resources/method-skill.js";
+import { CliUsageError } from "./cli-errors.js";
+import { admitReviewerInvocation, buildReviewerTransportPrompt, } from "./invocation.js";
+import { loadResumableReviewerRun, markRunAdmitted, RESUME_TRANSPORT_ENVELOPE, } from "./run-lifecycle.js";
+import { presentStructuralRejection, readEngineDetourInfrastructureFailure, trySettleReviewerTerminalResult, } from "./settlement.js";
+import { formatTerminalResult, isLawfulTypedTerminalOutcome, } from "./terminal.js";
+import { projectRoleTurnRequest, } from "./turn-request.js";
+import { presentControlledFailure, resolveResumeMethodMaterialAdapters, runPostAdmissionResumable, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+function reviewerMethods(packageRoot) {
+    return [{ kind: "skill", path: resolvePackagedMethodSkillPath(packageRoot, "ak-cross-m-review") }];
+}
+/**
+ * All Reviewer turns (explicit --lens, dual-lens child, resume) execute in a
+ * fresh worktree of the source tree's current HEAD (#946 统一新副本). Dual-lens
+ * summon already injects executionCwd; only mint when absent. Cleanup failure
+ * is diagnostic only and does not flip the exit code. Mint failure propagates
+ * so the caller can settle a controlled failure against the admitted run.
+ */
+async function runReviewerTurnInFreshCopy(env, projectRoot, io, body) {
+    if (env.executionCwd !== undefined) {
+        return body(env);
+    }
+    const { withEphemeralReviewerWorktree } = await import("../public-role-summons.js");
+    return await withEphemeralReviewerWorktree({
+        projectRoot,
+        onCleanupDiagnostic: (diagnostic) => {
+            io.stderr(`${diagnostic}\n`);
+        },
+        run: (executionCwd) => body({ ...env, executionCwd }),
+    });
+}
+/** Project admitted Reviewer invocation onto the host-neutral turn request. */
+export function buildReviewerTurnRequest(admitted, options) {
+    return projectRoleTurnRequest(admitted, {
+        activation: {
+            role: "reviewer",
+            baseRevision: admitted.baseRevision,
+            lens: admitted.lens,
+            authorityRefs: admitted.authorityRefs,
+            ...(admitted.ticketNumber === undefined ? {} : { ticketNumber: admitted.ticketNumber }),
+        },
+        methods: reviewerMethods(options.packageRoot),
+    }, options);
+}
+function reviewerAdapters(packageRoot, methodMaterial) {
+    return {
+        trySettle: (admitted, authority, scope) => methodMaterial === undefined
+            ? Promise.resolve(undefined)
+            : trySettleReviewerTerminalResult(admitted, authority, {
+                methodProvenance: methodMaterial.provenance,
+                methodSkillPath: methodMaterial.skillPath,
+                methodSkillConfiguredPath: resolvePackagedMethodSkillPath(packageRoot, "ak-cross-m-review"),
+            }, scope),
+        resolveRunnerKnownFailure: async ({ result, sessionFile }) => {
+            const infrastructureFailure = await readEngineDetourInfrastructureFailure(sessionFile);
+            return infrastructureFailure === undefined
+                ? result.knownFailure
+                : {
+                    ...(infrastructureFailure.cause === undefined
+                        ? {}
+                        : { cause: infrastructureFailure.cause }),
+                    diagnostic: infrastructureFailure.diagnostic,
+                    ...(infrastructureFailure.identity === undefined
+                        ? {}
+                        : { identity: infrastructureFailure.identity }),
+                };
+        },
+    };
+}
+async function loadReviewerMethodMaterial(packageRoot) {
+    return await loadPackagedMethodSkillMaterial(packageRoot, "ak-cross-m-review");
+}
+/** Continue the existing method turn; frozen axes remain on typed activation fields. */
+function reviewerResumePrompt(env, message) {
+    const lines = [RESUME_TRANSPORT_ENVELOPE];
+    if (message !== undefined)
+        lines.push("", message);
+    return appendEngineSessionMaterial(lines, engineSessionMaterialFromOptions({
+        ...pickEngineAxis(env),
+        packageRoot: env.packageRoot,
+    })).join("\n");
+}
+export async function runPublicReviewer(argv, env, io, parseReviewerArgv) {
+    let parsed;
+    try {
+        parsed = parseReviewerArgv(argv);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    // Omitted public lens is the parallel two-axis branch mark; never admitted as a parent run.
+    // Each leg reuses this call's public argv and only adds --lens (#946 / 10a).
+    if (parsed.lens === undefined) {
+        const { summonParallelReviewerLenses } = await import("../public-role-summons.js");
+        const children = await summonParallelReviewerLenses({
+            argv,
+            // Replay argv under the same cwd the single-axis entry would see (10a).
+            // Do not substitute the resolved project path — relative --project must
+            // not be re-resolved against a shifted cwd.
+            cwd: env.cwd,
+            projectRoot: resolve(parsed.project ?? env.cwd),
+            // Typed base from the public parse — precheck only; child argv stays verbatim.
+            baseRevision: parsed.baseRevision,
+            home: env.home,
+            agentDir: env.agentDir,
+            ...(env.credentials === undefined ? {} : { credentials: env.credentials }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+            ...(env.host === undefined ? {} : { host: env.host }),
+            ...(env.engine === undefined ? {} : { engine: env.engine }),
+            ...(env.engineModel === undefined ? {} : { engineModel: env.engineModel }),
+            packageRoot: env.packageRoot,
+            ...(env.signal === undefined ? {} : { signal: env.signal }),
+            ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+            roleTurnHost: env.roleTurnHost,
+            ...(env.hostAdapters === undefined ? {} : { hostAdapters: env.hostAdapters }),
+            principalAuthority: env.principalAuthority,
+            ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+        });
+        const childResults = [children.completeness, children.correctness];
+        const terminals = childResults
+            .map((child) => child.terminal)
+            .filter((terminal) => terminal !== undefined);
+        // ADR 0052 / terminal.ts: lawful typed child terminals (accepted / no_receipt /
+        // audit_escalation) are not batch failures. Child exitCode remains the live
+        // surface for seal/infrastructure overlays that keep the original Terminal.
+        // failedChildren counts only non-lawful/missing child Terminals; seal overlays
+        // that flip exitCode while keeping lawful Terminals are a separate identity.
+        const failedChildren = childResults.filter((child) => child.terminal === undefined
+            || !isLawfulTypedTerminalOutcome(child.terminal.roleOutcome)).length;
+        const overlayExit = childResults.some((child) => child.exitCode !== 0);
+        const failed = failedChildren > 0 || overlayExit;
+        const overlayDiagnostics = [...new Set(childResults
+                .map((child) => child.stderr)
+                .filter((text) => typeof text === "string" && text !== ""))];
+        const terminal = {
+            batch: "reviewer",
+            roleOutcome: failed
+                ? {
+                    kind: "failure",
+                    role: "reviewer",
+                    diagnostic: failedChildren > 0
+                        ? "Reviewer batch child failure"
+                        : (overlayDiagnostics[0] ?? "Reviewer batch infrastructure failure"),
+                    decisiveFacts: { failedChildren },
+                    payloads: terminals,
+                }
+                : { kind: "accepted", role: "reviewer", payloads: terminals },
+            reviewerChildren: {
+                ...(children.completeness.terminal === undefined ? {} : { completeness: children.completeness.terminal }),
+                ...(children.correctness.terminal === undefined ? {} : { correctness: children.correctness.terminal }),
+            },
+            reviewerChildOutcomes: {
+                completeness: { exitCode: children.completeness.exitCode, ...(children.completeness.stderr === undefined ? {} : { stderr: children.completeness.stderr }) },
+                correctness: { exitCode: children.correctness.exitCode, ...(children.correctness.stderr === undefined ? {} : { stderr: children.correctness.stderr }) },
+            },
+            // Batch has no parent run and no own attendance; no-advice is affirmative
+            // only (navigator-attendance.ts). Children carry their own navigator facts.
+            navigator: {
+                disposition: "unavailable",
+                source: "unknown",
+                reason: "Reviewer batch has no parent-run Navigator attendance",
+            },
+            artifacts: terminals.flatMap((item) => item.artifacts),
+        };
+        io.stdout(formatTerminalResult(terminal));
+        return { exitCode: failed ? 1 : 0, terminal };
+    }
+    let admitted;
+    try {
+        admitted = await admitReviewerInvocation({
+            home: env.home,
+            principalAuthority: env.principalAuthority,
+            cwd: env.cwd,
+            instruction: parsed.instruction,
+            attachmentPaths: parsed.attachmentPaths,
+            baseRevision: parsed.baseRevision,
+            lens: parsed.lens,
+            authorityRefs: parsed.authorityRefs,
+            ...(parsed.project === undefined ? {} : { project: parsed.project }),
+            ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+            ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    await markRunAdmitted(admitted, env.principalAuthority);
+    let methodMaterial;
+    try {
+        methodMaterial = await loadReviewerMethodMaterial(env.packageRoot);
+    }
+    catch (error) {
+        return (await presentControlledFailure(admitted, {
+            timedOut: false,
+            code: null,
+            stderr: "",
+            thrown: error,
+        }, reviewerAdapters(env.packageRoot), env.principalAuthority, io));
+    }
+    // Fresh copy for this call (explicit --lens or dual-lens child with pre-set cwd).
+    // Durable projectRoot stays the caller project; only the host turn uses the sandbox.
+    try {
+        return await runReviewerTurnInFreshCopy(env, admitted.projectRoot, io, async (sandboxedEnv) => await runPostAdmissionResumable({
+            admitted,
+            env: sandboxedEnv,
+            io,
+            buildInitialRequest: () => buildReviewerTurnRequest(admitted, {
+                packageRoot: sandboxedEnv.packageRoot,
+                home: sandboxedEnv.home,
+                agentDir: sandboxedEnv.agentDir,
+                ...(sandboxedEnv.model === undefined ? {} : { model: sandboxedEnv.model }),
+                ...pickEngineAxis(sandboxedEnv),
+                ...(sandboxedEnv.timeoutMs === undefined ? {} : { timeoutMs: sandboxedEnv.timeoutMs }),
+                ...(admitted.correlationId === undefined && sandboxedEnv.correlationId === undefined
+                    ? {}
+                    : { correlationId: admitted.correlationId ?? sandboxedEnv.correlationId }),
+                // Ephemeral worktree cwd; durable projectRoot stays on admitted caller project.
+                ...(sandboxedEnv.executionCwd === undefined ? {} : { cwd: sandboxedEnv.executionCwd }),
+                continuation: {
+                    kind: "initial",
+                    prompt: buildReviewerTransportPrompt(admitted, engineSessionMaterialFromOptions({
+                        ...pickEngineAxis(sandboxedEnv),
+                        packageRoot: sandboxedEnv.packageRoot,
+                    })),
+                },
+            }),
+            buildResumeRequest: () => buildReviewerTurnRequest(admitted, {
+                packageRoot: sandboxedEnv.packageRoot,
+                home: sandboxedEnv.home,
+                agentDir: sandboxedEnv.agentDir,
+                ...(sandboxedEnv.model === undefined ? {} : { model: sandboxedEnv.model }),
+                ...pickEngineAxis(sandboxedEnv),
+                ...(sandboxedEnv.timeoutMs === undefined ? {} : { timeoutMs: sandboxedEnv.timeoutMs }),
+                ...(admitted.correlationId === undefined && sandboxedEnv.correlationId === undefined
+                    ? {}
+                    : { correlationId: admitted.correlationId ?? sandboxedEnv.correlationId }),
+                // In-batch auto-resume keeps the same call's sandbox (dual-lens or single).
+                ...(sandboxedEnv.executionCwd === undefined ? {} : { cwd: sandboxedEnv.executionCwd }),
+                continuation: {
+                    kind: "resume",
+                    prompt: reviewerResumePrompt(sandboxedEnv),
+                },
+            }),
+            adapters: reviewerAdapters(sandboxedEnv.packageRoot, methodMaterial),
+            ...(sandboxedEnv.engine === undefined ? {} : { effectiveEngine: sandboxedEnv.engine }),
+        }));
+    }
+    catch (error) {
+        return (await presentControlledFailure(admitted, {
+            timedOut: false,
+            code: null,
+            stderr: "",
+            thrown: error,
+        }, reviewerAdapters(env.packageRoot, methodMaterial), env.principalAuthority, io));
+    }
+}
+/**
+ * Resume a previously admitted Reviewer Role run after a typed HTTP 429.
+ * Restores task/base/session identity; model override is temporary.
+ * Execution always uses a fresh worktree of the source tree at resume time
+ * (#946 统一新副本 / 10a) — no old worktree, no ownership record.
+ * Fresh-copy mint reuses the coordinator's single pre-lease load via
+ * afterAdmittedPrepare; does not pre-load outside the coordinator.
+ */
+export async function runPublicReviewerResume(request, env, io) {
+    // Call-local cell: afterAdmittedPrepare writes executionCwd; buildTurnRequest reads it.
+    // Keeps the single-load coordinator contract — no preliminary load outside.
+    const sandbox = {
+        ...(env.executionCwd === undefined ? {} : { executionCwd: env.executionCwd }),
+    };
+    return await runPostAdmissionSeatResume({
+        request,
+        env,
+        io,
+        load: (effective) => loadResumableReviewerRun(env.home, effective.runId, env.principalAuthority),
+        buildTurnRequest: (admitted, effective) => {
+            const activeEnv = sandbox.executionCwd === undefined
+                ? env
+                : { ...env, executionCwd: sandbox.executionCwd };
+            const base = resumeTurnRequestProjectionOptions(admitted, effective, activeEnv);
+            return buildReviewerTurnRequest(admitted, {
+                ...base,
+                // Fresh copy at resume time; durable projectRoot unchanged.
+                ...(sandbox.executionCwd === undefined ? {} : { cwd: sandbox.executionCwd }),
+                continuation: {
+                    kind: "resume",
+                    prompt: reviewerResumePrompt(activeEnv, effective.message),
+                },
+            });
+        },
+        adapters: reviewerAdapters(env.packageRoot),
+        afterAdmittedLoad: async (admitted) => {
+            return resolveResumeMethodMaterialAdapters({
+                admitted,
+                authority: env.principalAuthority,
+                io,
+                loadMaterial: () => loadReviewerMethodMaterial(env.packageRoot),
+                adaptersWith: (material) => reviewerAdapters(env.packageRoot, material),
+                emptyAdapters: reviewerAdapters(env.packageRoot),
+            });
+        },
+        afterAdmittedPrepare: async (admitted) => {
+            // Already sandboxed (in-batch auto-resume path) — nothing to mint.
+            if (sandbox.executionCwd !== undefined) {
+                return { env: { ...env, executionCwd: sandbox.executionCwd } };
+            }
+            const { openEphemeralReviewerWorktree } = await import("../public-role-summons.js");
+            const opened = await openEphemeralReviewerWorktree({
+                projectRoot: admitted.projectRoot,
+                onCleanupDiagnostic: (diagnostic) => {
+                    io.stderr(`${diagnostic}\n`);
+                },
+            });
+            sandbox.executionCwd = opened.executionCwd;
+            return {
+                env: { ...env, executionCwd: opened.executionCwd },
+                cleanup: opened.close,
+            };
+        },
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}

package/dist/public-cli/run-lifecycle.js

@@ -26,20 +26,31 @@ export const V1_RESUMABLE_PROVIDERS = ["openai-codex", "xai"];
  * source: runWithAutoResumeLoop receives the effective value once per call.
  */
 export const AUTO_RESUME_LIMIT = 2;
-/** Package-owned turn trigger for resume. Not caller instruction and not semantic task content. */
-export const RESUME_TRANSPORT_ENVELOPE = "[ak-role:resume-continue]";
 /**
- * Unique continuation-prompt selector for manual/auto engine-axis resume
- * (#471 / #600 / #736). Message present → those bytes; absent → engine pointers only.
- * #836: no transport-token prompt, no line-by-line 重新读 rewrite.
+ * Package-owned non-empty Chinese neutral resume transport (#959 / ADR 0073).
+ * Used by:
+ *   - auto-resume (all seats via buildAutoResumeContinuationPrompt) — required so
+ *     hosts that reject empty stdin (codex) still receive a prompt;
+ *   - reviewer seat manual resume (reviewerResumePrompt) — same non-empty need on
+ *     that seat's own manual entry.
+ * Generic bare `ak-role resume` stays empty-capable via selectResumeContinuationPrompt
+ * / buildResumeContinuationPrompt — ADR 0080 keeps auto and generic-manual entries separate.
+ */
+export const RESUME_TRANSPORT_ENVELOPE = "继续。";
+/**
+ * Manual resume continuation selector (#471 / #600 / #736 / ADR 0080).
+ * Message present → those bytes; absent → engine pointers only (may be empty).
+ * Caller message (including blank) still wins verbatim when supplied.
+ * Auto-resume must use buildAutoResumeContinuationPrompt — do not fold the
+ * non-empty Chinese envelope into this shared manual selector (#959).
  */
 export function selectResumeContinuationPrompt(message, engineMaterial) {
     const lines = message !== undefined ? [message] : [];
     return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 /**
- * Resume continuation with engine material resolved from the seat env (#600).
- * Seat table / invocation engine axis rides the same prompt seam as initial runs.
+ * Manual resume continuation with engine material from the seat env (#600).
+ * Bare manual resume stays empty-prompt-capable; auto-resume is a separate entry.
  */
 export function buildResumeContinuationPrompt(options) {
     return selectResumeContinuationPrompt(options.message, engineSessionMaterialFromOptions({
@@ -47,6 +58,17 @@ export function buildResumeContinuationPrompt(options) {
         ...pickEngineAxis(options),
     }));
 }
+/**
+ * Auto-resume continuation only (#959 / ADR 0080).
+ * Always non-empty: Chinese neutral envelope plus optional engine pointers.
+ * Never call this from manual `ak-role resume`.
+ */
+export function buildAutoResumeContinuationPrompt(options) {
+    return selectResumeContinuationPrompt(RESUME_TRANSPORT_ENVELOPE, engineSessionMaterialFromOptions({
+        packageRoot: options.packageRoot,
+        ...pickEngineAxis(options),
+    }));
+}
 const RUN_STATE_FILE = "run-state.json";
 const WRITER_LOCK_FILE = "writer.lock";
 /** @deprecated #416: 429-only classification removed; kept for compatibility. */

package/dist/public-cli/settlement.js

@@ -157,7 +157,7 @@ async function closedLedgerOutcome(admitted, role, scope) {
 function coordinatesFromAdmitted(authority, admitted) {
     return authority.decode(admitted.principal);
 }
-import { exitCodeForTerminalOutcome, formatTerminalResult, isLawfulTypedTerminalOutcome, recommendationNavigatorFact, } from "./terminal.js";
+import { exitCodeForTerminalOutcome, formatTerminalResult, isLawfulTypedTerminalOutcome, adviceNavigatorFact, } from "./terminal.js";
 export { exitCodeForTerminalOutcome, formatTerminalResult, isLawfulTypedTerminalOutcome, };
 /**
  * Host stderr as recorded — full bytes, no flood filter, no char clip (#836).
@@ -457,7 +457,13 @@ export function explicitInternalKnownFailureClassificationInput(failure) {
         ...(failure.details === undefined ? {} : { knownDetails: failure.details }),
     };
 }
-/** Post-role Navigator delivery grace (Issue #11 / #101 / #106 / #159). */
+/**
+ * Post-role Navigator delivery grace (Issue #11 / #101 / #106 / #159).
+ * After the parent finishes: wait at most this long for navigator output, then
+ * stop waiting. Navigator must already be running from parent start (prepare
+ * host round in parallel); this window is only the tail after parent end — not
+ * the budget to start a cold full host turn (owner 2026-09-17 #959).
+ */
 export const NAVIGATOR_POST_ROLE_GRACE_MS = 10_000;
 function isMissingPathError(error) {
     return (error instanceof Error &&
@@ -1334,11 +1340,6 @@ export async function appendRunAttemptHistory(source, outcome) {
     }
     catch { }
 }
-function navigatorPhaseValue(value) {
-    if (value === "plan" || value === "apply")
-        return value;
-    return null;
-}
 /**
  * Minimal attendance provenance against the bound marker (ADR 0043).
  * Keep only invocationId + post-terminal ordering. Runtime-self-produced
@@ -1357,35 +1358,48 @@ function parseNavigatorAttendanceDetails(details) {
     const advisoryDiagnostic = typeof details.routePlaybookReadFailure === "string"
         ? { advisoryDiagnostic: details.routePlaybookReadFailure }
         : {};
-    if (disposition === "recommendation") {
-        const next = details.next;
-        if (!isRecord(next) || typeof next.role !== "string") {
+    // #959: advice prose is presented as-is. Legacy "recommendation" with next/reason/
+    // command is projected into prose so historical sessions still render — never wash
+    // a real recommendation into no-advice when any advice body is recoverable.
+    if (disposition === "advice" || disposition === "recommendation") {
+        let prose;
+        if (typeof details.prose === "string" && details.prose.trim() !== "") {
+            prose = details.prose;
+        }
+        else {
+            const next = isRecord(details.next) && typeof details.next.role === "string"
+                ? details.next.role
+                : undefined;
+            const reason = typeof details.reason === "string" && details.reason.trim() !== ""
+                ? details.reason
+                : undefined;
+            const command = typeof details.command === "string" && details.command.trim() !== ""
+                ? details.command
+                : undefined;
+            if (reason !== undefined && next !== undefined) {
+                prose = `${reason}（下一步：${next}）`;
+            }
+            else if (reason !== undefined) {
+                prose = reason;
+            }
+            else if (next !== undefined) {
+                // Historical recommendation with only typed next — still real advice.
+                prose = `下一步：${next}`;
+            }
+            else if (command !== undefined) {
+                prose = command;
+            }
+        }
+        if (prose === undefined || prose.trim() === "") {
+            // Attended but empty body is affirmative no-advice, not unavailable (#959).
             return {
-                disposition: "unavailable",
-                source: "unknown",
-                reason: "navigator recommendation missing typed next role",
+                disposition: "no-advice",
+                ...advisoryDiagnostic,
             };
         }
-        const reason = typeof details.reason === "string" ? details.reason : "";
-        const route = Array.isArray(details.route)
-            ? details.route
-                .filter(isRecord)
-                .map((target) => ({
-                role: String(target.role),
-                phase: navigatorPhaseValue(target.phase),
-            }))
-            : undefined;
-        return recommendationNavigatorFact({
+        return adviceNavigatorFact({
+            prose,
             ...advisoryDiagnostic,
-            next: {
-                role: next.role,
-                phase: navigatorPhaseValue(next.phase),
-            },
-            reason,
-            ...(route === undefined ? {} : { route }),
-            ...(typeof details.command === "string"
-                ? { modelCommand: details.command }
-                : {}),
         });
     }
     if (disposition === "unavailable") {