@akagilnc/pi-workflow-roles 0.1.4526 → 0.1.4586

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."',

package/dist/public-cli/post-admission.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).

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/terminal.js

@@ -107,6 +107,15 @@ export function formatTerminalResult(result) {
             lines.push(`gate-round\t${round.roundIndex}\t${round.dispatch.kind}\t${round.dispatch.officer}\t${reason}\t${round.officer.seat}\t${encodeTerminalField(round.officer.status)}\t${encodeTerminalField(JSON.stringify(round.officer.findings))}`);
         }
     }
+    if (result.reviewerChildOutcomes !== undefined) {
+        for (const axis of ["completeness", "correctness"]) {
+            const child = result.reviewerChildOutcomes[axis];
+            lines.push(`reviewer-child\t${axis}\t${child.exitCode}`);
+            if (child.stderr !== undefined && child.stderr !== "") {
+                lines.push(`reviewer-child-diagnostic\t${axis}\t${encodeTerminalField(child.stderr)}`);
+            }
+        }
+    }
     if (result.resume !== undefined) {
         // Resumable failure: run ID is revealed only inside the complete resume command.
         lines.push(`resume\t${encodeTerminalField(result.resume.command)}`);

package/dist/public-cli/turn-request.js

@@ -1,6 +1,6 @@
 import { pickEngineAxis } from "../package-resources/engine-material.js";
 export function projectRoleTurnRequest(admitted, roleDetails, options) {
-    const cwd = admitted.projectRoot ?? admitted.repoRoot ?? admitted.cwd;
+    const cwd = options.cwd ?? admitted.projectRoot ?? admitted.repoRoot ?? admitted.cwd;
     if (cwd === undefined)
         throw new Error("admitted invocation missing working directory");
     if (admitted.principal === undefined)