@akagilnc/pi-workflow-roles 0.1.2086 → 0.1.2091

package/src/evidence-child-executor.ts

@@ -29,6 +29,13 @@ import {
   prepareComplianceDispatch,
   type AuditorParentAttemptBinding,
 } from "./compliance-transport.ts";
+import { createEngineDetourToolDefinition } from "./engine-detour-tool.ts";
+import { engineNameFromEnv } from "./engine-detour.ts";
+import {
+  appendEngineSessionMaterial,
+  engineSessionMaterialFromOptions,
+  type EngineSessionMaterial,
+} from "./package-resources/engine-material.ts";
 import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT, type NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { REVIEWER_VERIFICATION_BOUNDARY } from "./reviewer-construction.ts";
@@ -41,13 +48,16 @@ import {
 } from "./upstream-error-testimony.ts";
 
 /** Package-owned system prompt for Reviewer Standards/Spec evidence children (private carrier). */
-function buildEvidenceChildSystemPrompt(): string {
-  return [
+function buildEvidenceChildSystemPrompt(
+  engineMaterial?: EngineSessionMaterial,
+): string {
+  const lines = [
     "Work only in the supplied workspace.",
     "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
     REVIEWER_VERIFICATION_BOUNDARY,
     "Return one substantive non-blank report.",
-  ].join("\n");
+  ];
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 // ── shared constants / types ──────────────────────────────────────────────
@@ -540,6 +550,11 @@ export type EvidenceChildExecuteOptions = Readonly<{
   signal?: AbortSignal;
   /** Parent directory for credential/config scratch. Defaults to os.tmpdir(). */
   credentialScratchParent?: string;
+  /**
+   * Package root for optional engine method-material resolution (#378).
+   * Required only when AK_ROLE_ENGINE is set and packaged notes should attach.
+   */
+  packageRoot?: string;
 }>;
 
 export async function executeEvidenceChild(
@@ -568,6 +583,32 @@ export async function executeEvidenceChild(
       } catch (error) {
         throw classifiedError(error, "provider");
       }
+      // #378: when labor engine is configured, legs get the same detour tool + material
+      // dual-path as the parent seat (ADR 0069 detour-rejoins-main-road).
+      const engineName = engineNameFromEnv();
+      const engineMaterial =
+        engineName === undefined
+          ? undefined
+          : options.packageRoot === undefined || options.packageRoot.trim() === ""
+            // Name-only when package root is unavailable (still a valid #376 path).
+            ? Object.freeze({ name: engineName })
+            : engineSessionMaterialFromOptions({
+                engine: engineName,
+                packageRoot: options.packageRoot,
+              });
+      // #378: detour failure is durable for this leg — later assistant reports cannot wash it.
+      let engineDetourFailure: Error | undefined;
+      const engineDetourTool =
+        engineName === undefined
+          ? undefined
+          : createEngineDetourToolDefinition({
+              engineName,
+              fail(error) {
+                const failure = error instanceof Error ? error : new Error(String(error));
+                engineDetourFailure = failure;
+                throw failure;
+              },
+            });
       // No tools allowlist — Pi defaults + unrestricted evidence surface (ADR 0064).
       // Single createAgentSession owner: in-process-session.ts.
       const { session, dispose } = await openInProcessAgentSession({
@@ -576,7 +617,10 @@ export async function executeEvidenceChild(
         model: inherited.model,
         thinkingLevel: context.thinkingLevel ?? "off",
         modelRuntime: inherited.runtime,
-        systemPrompt: buildEvidenceChildSystemPrompt(),
+        systemPrompt: buildEvidenceChildSystemPrompt(engineMaterial),
+        ...(engineDetourTool === undefined
+          ? {}
+          : { customTools: [engineDetourTool] }),
         sessionManager: createRecordSession({
           cwd: workspace,
           kind: "evidence-children",
@@ -598,8 +642,18 @@ export async function executeEvidenceChild(
         try {
           await session.prompt(delivered);
         } catch (error) {
+          // Engine detour fail becomes isError toolResult and must outrank a later
+          // provider-shaped throw from the same prompt turn (#378).
+          if (engineDetourFailure !== undefined) {
+            throw classifiedError(engineDetourFailure, "child");
+          }
           throw classifiedError(error, "provider");
         }
+        // Launched-leg detour non-zero / empty stdout / spawn failure is infrastructure:
+        // reject the leg even when the model still emits a non-blank report afterward.
+        if (engineDetourFailure !== undefined) {
+          throw classifiedError(engineDetourFailure, "child");
+        }
         if (signal?.aborted) throw new Error("Evidence child was cancelled");
         const lastAssistant = [...session.messages]
           .reverse()

package/src/public-cli/cli.ts

@@ -16,6 +16,7 @@ import {
   parsePersistentModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
+  isEngineAxisSeat,
   setPersistentSeatConfig,
   setPersistentSeatEngine,
   validatePublicCliConfigEngines,
@@ -418,7 +419,7 @@ function renderHelp(): string {
     "",
     "Role options: ak-role help <command>",
     "Persistent config: ak-role config set <seat> <provider/model:thinking>",
-    "Persistent engine (judge only): ak-role config set-engine judge <name> | unset-engine judge",
+    "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles",
   );
   return `${lines.join("\n")}\n`;
@@ -533,7 +534,7 @@ async function runConfigCommand(
   if (args[0] === "set-engine") {
     if (args.length !== 3) {
       throw new CliUsageError(
-        "usage: ak-role config set-engine judge <name>",
+        "usage: ak-role config set-engine <judge|reviewer> <name>",
       );
     }
     const seat = args[1]!;
@@ -541,9 +542,9 @@ async function runConfigCommand(
     if (!isPublicConfigurableSeat(seat)) {
       throw new CliUsageError(`unknown configurable seat: ${seat}`);
     }
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new CliUsageError(
-        `engine axis is judge-only; refused seat ${seat}`,
+        `engine axis is judge+reviewer only; refused seat ${seat}`,
       );
     }
     requireLegalEngineName(name);
@@ -564,16 +565,16 @@ async function runConfigCommand(
   if (args[0] === "unset-engine") {
     if (args.length !== 2) {
       throw new CliUsageError(
-        "usage: ak-role config unset-engine judge",
+        "usage: ak-role config unset-engine <judge|reviewer>",
       );
     }
     const seat = args[1]!;
     if (!isPublicConfigurableSeat(seat)) {
       throw new CliUsageError(`unknown configurable seat: ${seat}`);
     }
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new CliUsageError(
-        `engine axis is judge-only; refused seat ${seat}`,
+        `engine axis is judge+reviewer only; refused seat ${seat}`,
       );
     }
     let config = await loadAndValidateConfig(home, packageRoot);
@@ -606,17 +607,17 @@ export async function runAkRole(
     env = { ...env, packageRoot: await realpath(env.packageRoot) };
     const parsed = parseArgv(argv);
     // Invocation --engine rejects at the call-request seam (not role submission).
-    // #356 MVP: engine axis is Judge-only (not resume / non-Judge seats).
+    // #356 / #378: engine axis is Judge+Reviewer (not resume / other seats).
     if (parsed.engine !== undefined) {
       requireLegalEngineName(parsed.engine);
       if (
         !parsed.help &&
         parsed.command !== undefined &&
         parsed.command !== "help" &&
-        parsed.command !== "judge"
+        !isEngineAxisSeat(parsed.command)
       ) {
         throw new CliUsageError(
-          `engine axis is judge-only; refused command ${parsed.command}`,
+          `engine axis is judge+reviewer only; refused command ${parsed.command}`,
         );
       }
     }
@@ -1046,6 +1047,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...(seat.engine === undefined ? {} : { engine: seat.engine }),
           ...(env.reviewerExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.reviewerExtraPiArgs }),

package/src/public-cli/config.ts

@@ -116,8 +116,13 @@ export function setPersistentSeatConfig(
   };
 }
 
+/** Seats that own the labor-engine axis (#356 Judge; #378 Reviewer). */
+export function isEngineAxisSeat(seat: string): seat is "judge" | "reviewer" {
+  return seat === "judge" || seat === "reviewer";
+}
+
 /**
- * Set or clear persistent engine on the Judge seat only (#356 MVP).
+ * Set or clear persistent engine on Judge or Reviewer (#356 / #378).
  * Engine-only seats are rejected — model triple remains required.
  */
 export function setPersistentSeatEngine(
@@ -125,8 +130,8 @@ export function setPersistentSeatEngine(
   seat: PublicConfigurableSeat,
   engine: string | undefined,
 ): PublicCliConfig {
-  if (seat !== "judge") {
-    throw new Error(`engine axis is judge-only; refused seat ${seat}`);
+  if (!isEngineAxisSeat(seat)) {
+    throw new Error(`engine axis is judge+reviewer only; refused seat ${seat}`);
   }
   const previous = config.seats[seat];
   if (previous === undefined) {
@@ -161,8 +166,8 @@ export function seatModelOnly(seat: PersistentSeatConfig): SeatModelConfig {
 }
 
 /**
- * Config-parse seam: engine axis is Judge-only; Judge engine names need only
- * path-safety syntax (no closed material catalog; #376 / ADR 0069).
+ * Config-parse seam: engine axis is Judge+Reviewer; engine names need only
+ * path-safety syntax (no closed material catalog; #376 / #378 / ADR 0069).
  * Call with packageRoot after load / before dispatch (#356).
  * Syntax authority = assertLegalEngineName (no injected duplicate).
  */
@@ -173,9 +178,9 @@ export function validatePublicCliConfigEngines(
   for (const seat of Object.keys(config.seats) as PublicConfigurableSeat[]) {
     const row = config.seats[seat];
     if (row?.engine === undefined) continue;
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new Error(
-        `config seat ${seat} engine is not allowed; engine axis is judge-only`,
+        `config seat ${seat} engine is not allowed; engine axis is judge+reviewer only`,
       );
     }
     try {
@@ -364,14 +369,14 @@ function attachEngineAxis(
   config: PublicCliConfig,
   invocation?: InvocationModelOverride,
 ): EffectiveSeat {
-  // #356 MVP: engine axis is Judge-only. Other seats stay unconfigured.
-  if (seat.seat !== "judge") {
+  // #356 / #378: engine axis is Judge+Reviewer. Other seats stay unconfigured.
+  if (!isEngineAxisSeat(seat.seat)) {
     return {
       ...seat,
       engineSource: "unconfigured",
     };
   }
-  const persistentEngine = config.seats.judge?.engine;
+  const persistentEngine = config.seats[seat.seat]?.engine;
   if (invocation?.engine !== undefined) {
     return {
       ...seat,

package/src/public-cli/invocation.ts

@@ -1898,14 +1898,17 @@ export async function admitReviewerInvocation(
 /**
  * Build the Pi prompt transport for an admitted Reviewer request.
  * Semantic input is fixed base only — caller instruction stays provenance on disk.
+ * Optional engine material follows the same dual-path coordinates as Judge (#376/#378).
  */
 export function buildReviewerTransportPrompt(
   admitted: AdmittedReviewerInvocation,
+  engineMaterial?: EngineSessionMaterial,
 ): string {
-  return [
+  const lines = [
     `Base revision for the fixed review target: ${admitted.baseRevision}`,
     "Use this exact revision as the fixed review point.",
-  ].join("\n");
+  ];
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
 /**

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

@@ -288,8 +288,8 @@ const GLOBAL_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional Judge labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge-only).",
-      zh: "本调用可选 Judge 劳动引擎（池令名字；有包内调法笔记则附卷；仅 Judge）。",
+      en: "Optional Judge/Reviewer labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge+reviewer only).",
+      zh: "本调用可选 Judge/Reviewer 劳动引擎（池令名字；有包内调法笔记则附卷；仅 Judge+Reviewer）。",
     },
   },
   {

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

@@ -7,6 +7,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { AK_ROLE_ENGINE_ENV } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
   resolvePackagedMethodSkillPath,
@@ -65,6 +67,7 @@ import {
   resolveControlledFailureResumeObservation,
   controlledFailureInputFromResolution,
   explicitInternalKnownFailureClassificationInput,
+  readEngineDetourInfrastructureFailure,
   settleFailureTerminalResult,
   trySettleReviewerTerminalResult,
   trySettleComplianceAuditIncompleteTerminalResult,
@@ -83,6 +86,8 @@ export type ReviewerRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + leg channel). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -109,10 +114,14 @@ export function buildReviewerActivationExtraArgs(
   options: {
     packageRoot: string;
     model?: SeatModelConfig;
+    engine?: string;
     extraPiArgs?: readonly string[];
   },
 ): string[] {
-  const prompt = buildReviewerTransportPrompt(admitted);
+  const prompt = buildReviewerTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   const skillPath = resolvePackagedMethodSkillPath(
     options.packageRoot,
     "code-review",
@@ -278,12 +287,17 @@ async function dispatchAdmittedReviewer(input: {
   extraArgs: string[];
   lease: RunWriterLease;
   methodMaterial: PackagedMethodSkillMaterial;
+  /**
+   * Mechanical engine provenance for initial Reviewer dispatch only.
+   * Explicit — never read from env.engine here, so resume cannot rewrite it.
+   */
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedReviewerInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease, methodMaterial } = input;
+  const { admitted, env, io, extraArgs, lease, methodMaterial, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -296,7 +310,7 @@ async function dispatchAdmittedReviewer(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
     await clearReviewerDispatchRejection(admitted.runDirectory);
 
@@ -306,6 +320,14 @@ async function dispatchAdmittedReviewer(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    // Engine presence/name signal: registration gate + leg channel (no per-engine branch).
+    // Delete ambient inheritance first; own-key undefined mask survives process.env re-merge.
+    delete childEnv[AK_ROLE_ENGINE_ENV];
+    if (env.engine !== undefined && env.engine.trim() !== "") {
+      childEnv[AK_ROLE_ENGINE_ENV] = env.engine.trim();
+    } else {
+      childEnv[AK_ROLE_ENGINE_ENV] = undefined;
+    }
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -393,13 +415,27 @@ async function dispatchAdmittedReviewer(input: {
       };
     }
 
+    // Prefer engine-detour infrastructure failure already on the session principal
+    // over a later secondary knownFailure / provider-stop after abort (#357 T2 / #378).
+    const infrastructureFailure = await readEngineDetourInfrastructureFailure(
+      admitted.sessionFile,
+    );
     const credentialFailure = postRunMissingCredentialFailure(
       result,
       env.model,
       env.credentials,
     );
     const resolution = await resolveAuditedRunnerFailureResolution({
-      runner: result.knownFailure,
+      runner:
+        infrastructureFailure === undefined
+          ? result.knownFailure
+          : {
+              cause: infrastructureFailure.cause,
+              diagnostic: infrastructureFailure.diagnostic,
+              ...(infrastructureFailure.identity === undefined
+                ? {}
+                : { identity: infrastructureFailure.identity }),
+            },
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
       runDirectory: admitted.runDirectory,
@@ -496,6 +532,7 @@ export async function runPublicReviewer(
   const extraArgs = buildReviewerActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -509,6 +546,8 @@ export async function runPublicReviewer(
     extraArgs,
     lease,
     methodMaterial,
+    // #378: only initial Reviewer dispatch records mechanical engine provenance.
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 

package/src/reviewer-agent.ts

@@ -35,6 +35,8 @@ type Dependencies = Readonly<{
   fault?(operation: ReviewerAgentFaultPoint): void;
   /** When set, child credential/config scratch is created under this parent so cleanup proofs stay process-local. */
   credentialScratchParent?: string;
+  /** Package root for optional engine method-material on legs (#378). */
+  packageRoot?: string;
 }>;
 function classify(error: unknown, signal?: AbortSignal): ReviewerFailureClassification { if (signal?.aborted) return "cancelled"; if (typeof error === "object" && error !== null && "reviewerFailure" in error) return (error as { reviewerFailure: ReviewerFailureClassification }).reviewerFailure; return "unknown"; }
 function failed(error: unknown, target: ReviewerTargetSnapshot, prompt: ReviewerPromptText, signal?: AbortSignal, retained?: string): ReviewerFailedLegRunResult {
@@ -76,6 +78,9 @@ export function createReviewerAgentRunner(dependencies: Dependencies = {}): Revi
             ...(dependencies.credentialScratchParent === undefined
               ? {}
               : { credentialScratchParent: dependencies.credentialScratchParent }),
+            ...(dependencies.packageRoot === undefined
+              ? {}
+              : { packageRoot: dependencies.packageRoot }),
           });
           const disposition = await workspaceOwner.dispose(workspace);
           return [leg.axis, Object.freeze({ status: "successful" as const, report: child.report, usage: child.usage, target: batch.target, prompt: child.prompt, workspaceDisposition: disposition })] as const;

package/src/reviewer-child-executor.ts

@@ -5,6 +5,8 @@ import type { AcceptedReviewerLeg } from "./reviewer-dispatch.ts";
 export type ReviewerChildExecuteOptions = Readonly<{
   signal?: AbortSignal;
   credentialScratchParent?: string;
+  /** Package root for optional engine method-material on legs (#378). */
+  packageRoot?: string;
 }>;
 
 /**

package/src/role-runtime.ts

@@ -591,7 +591,7 @@ export function createRoleRuntimeExtension(
     let pendingNavigatorSettlement: Promise<void> | undefined;
     let navigatorWorkContext: NavigatorWorkContext | undefined;
     const pendingInfrastructureToolCallIds = new Set<string>();
-    // #357 T2: engine detour once-latch + registration (Judge+engine only).
+    // #357 T2 / #378: engine detour once-latch + registration (Judge|Reviewer+engine).
     let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
     // #288 primary-session thin adapter. The policy is the sole budget owner;
     // terminating-tool rejections and mechanical delivery requests share two turns.
@@ -1168,9 +1168,12 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
-        // #357 T2: Judge+engine activation registers the package detour tool once.
-        // Gate is env presence only — no per-engine execute branch; no judge-role spawn.
-        if (entry.role === "judge" && engineDetourRegistration === undefined) {
+        // #357 T2 / #378: Judge|Reviewer+engine activation registers the package detour tool once.
+        // Gate is env presence only — no per-engine execute branch; no role-module spawn.
+        if (
+          (entry.role === "judge" || entry.role === "reviewer") &&
+          engineDetourRegistration === undefined
+        ) {
           engineDetourRegistration = registerEngineDetourTool(pi, hostActions);
           if (!engineDetourRegistration.registered) {
             engineDetourRegistration = undefined;