@akagilnc/pi-workflow-roles 0.1.2107 → 0.1.2114

package/src/collector-role.ts

@@ -4,6 +4,10 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { Static } from "typebox";
 
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 import {
   COLLECTOR_FIXED_KICKOFF,
   emptyCollectorManifest,
@@ -446,12 +450,16 @@ export function createCollectorRoleRuntime(
           );
           activation.ledger.markOutputAccepted();
           activation.ledger.completeOperational(toolCallId);
+          const acceptedDetails = withEngineLaborFallbackField(
+            receipt,
+            readActivationEngineLaborFallbackField(),
+          );
           return {
             content: [{
               type: "text" as const,
               text: "Collector receipt accepted",
             }],
-            details: receipt,
+            details: acceptedDetails,
             terminate: true as const,
           };
         } catch (error) {

package/src/doctor-role.ts

@@ -2,6 +2,10 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { disposeComplianceDecision } from "./audit-escalation.ts";
 import { appendActiveSessionCustomEntry, type ComplianceDecision } from "./compliance-transport.ts";
 import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
 
 export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
@@ -12,7 +16,7 @@ export function createDoctorRoleRuntime(pi: ExtensionAPI, dependencies: DoctorRo
   let activation: { soul: string; patient: DoctorCase; store: DoctorEvidenceStore } | undefined; let registered = false; pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
   return { async activate() { const path = pi.getFlag(DOCTOR_CASE_FLAG.name); if (typeof path !== "string" || !path.trim()) throw new Error("Doctor requires --ak-doctor-case"); const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Doctor soul is empty"); const patient = await dependencies.loadCase(path); activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
     if (!registered) { registered = true; pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "Doctor Evidence", description: "Read retained Pi session bytes with bounded pagination.", parameters: doctorEvidenceReadSchema, async execute(_id, params: { evidenceId: string; offset?: number; limit?: number }) { if (!activation) throw new Error("Doctor is not activated"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details }; } });
-      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "Doctor Output", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id, params, signal, _update, ctx): Promise<AgentToolResult<unknown>> { if (!activation) throw new Error("Doctor is not activated"); singleton(id, ctx); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try { appendActiveSessionCustomEntry(ctx, DOCTOR_CANDIDATE_ENTRY_TYPE, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity }, { unavailable: "doctor candidate retention is unavailable", failed: "doctor candidate retention failed" }); } catch (error) { host.failInfrastructure(error, ctx, id); } let audit: ComplianceDecision; try { audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal }); } catch (error) { host.failInfrastructure(error, ctx, id); } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; return disposeComplianceDecision<AgentToolResult<unknown>>(audit, { pass: (usage) => ({ content: [{ type: "text" as const, text: "Doctor output accepted" }], details, terminate: true as const, ...(usage === undefined ? {} : { usage }) }), noReceipt: (auditNoReceipt, usageProjection) => ({ content: [{ type: "text" as const, text: "Doctor output accepted; compliance audit produced no receipt" }], details: { ...details, auditNoReceipt }, terminate: true as const, ...usageProjection }), revise: (violations) => { throw new Error(`Doctor output violates its soul: ${violations.join("; ")}`); }, escalate: (result) => result, auditIncomplete: (result) => result }, details); } });
+      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "Doctor Output", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id, params, signal, _update, ctx): Promise<AgentToolResult<unknown>> { if (!activation) throw new Error("Doctor is not activated"); singleton(id, ctx); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try { appendActiveSessionCustomEntry(ctx, DOCTOR_CANDIDATE_ENTRY_TYPE, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity }, { unavailable: "doctor candidate retention is unavailable", failed: "doctor candidate retention failed" }); } catch (error) { host.failInfrastructure(error, ctx, id); } let audit: ComplianceDecision; try { audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal }); } catch (error) { host.failInfrastructure(error, ctx, id); } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; const acceptedDetails = withEngineLaborFallbackField(details, readActivationEngineLaborFallbackField()); return disposeComplianceDecision<AgentToolResult<unknown>>(audit, { pass: (usage) => ({ content: [{ type: "text" as const, text: "Doctor output accepted" }], details: acceptedDetails, terminate: true as const, ...(usage === undefined ? {} : { usage }) }), noReceipt: (auditNoReceipt, usageProjection) => ({ content: [{ type: "text" as const, text: "Doctor output accepted; compliance audit produced no receipt" }], details: { ...acceptedDetails, auditNoReceipt }, terminate: true as const, ...usageProjection }), revise: (violations) => { throw new Error(`Doctor output violates its soul: ${violations.join("; ")}`); }, escalate: (result) => result, auditIncomplete: (result) => result }, acceptedDetails); } });
       pi.on("before_agent_start", (event) => { if (!activation) throw new Error("Doctor is not activated"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { provenance: "runtime-derived from retained session bytes and sealed into the accepted receipt", cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; }); }
     const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME]; const names = pi.getAllTools().map((tool) => tool.name); for (const name of required) if (names.filter((item) => item === name).length !== 1) throw new Error(`Doctor required tool collision or missing: ${name}`); pi.setActiveTools(required); const active = pi.getActiveTools?.() ?? required; if (active.length !== 2 || !required.every((name) => active.includes(name))) throw new Error("Doctor active tool narrowing failed"); } };
 }

package/src/engine-detour-tool.ts

@@ -1,6 +1,6 @@
 /**
  * Package-owned engine detour tool (#357 T2 / #378 / #380).
- * Registered by shared role-runtime when Judge|Reviewer + engine activation signal is present.
+ * Registered by shared role-runtime when any role + engine activation signal is present.
  * Evidence-child legs install the same definition via customTools (no spawn in role modules).
  * #380: engine process failure soft-returns so the seat rejoins the main road; declaration
  * is recorded once via engine-labor-fallback (no fail-closed reject-leg).
@@ -204,7 +204,7 @@ export function createEngineDetourToolDefinition(input: {
 }
 
 /**
- * Register the engine-generic detour tool once for this process when Judge/Reviewer has
+ * Register the engine-generic detour tool once for this process when any role has
  * an engine activation signal. Returns whether registration occurred.
  * Once-latch is activation-scoped via the returned reset handle.
  */

package/src/engine-detour.ts

@@ -8,9 +8,25 @@ import { spawn } from "node:child_process";
 /** Package-owned detour tool name (settlement whitelist + session principal). */
 export const ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour" as const;
 
-/** Env presence/name signal injected by public Judge run (registration gate only). */
+/** Env presence/name signal injected by public role runs (registration gate only). */
 export const AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE" as const;
 
+/**
+ * Sole AK_ROLE_ENGINE write seam for public role child env (#391 E2).
+ * Delete ambient inheritance first; own-key undefined mask survives process.env re-merge.
+ */
+export function applyEngineChildEnv(
+  childEnv: NodeJS.ProcessEnv,
+  engine?: string,
+): void {
+  delete childEnv[AK_ROLE_ENGINE_ENV];
+  if (engine !== undefined && engine.trim() !== "") {
+    childEnv[AK_ROLE_ENGINE_ENV] = engine.trim();
+  } else {
+    childEnv[AK_ROLE_ENGINE_ENV] = undefined;
+  }
+}
+
 export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC =
   "engine detour produced empty stdout" as const;
 

package/src/engine-labor-fallback.ts

@@ -82,7 +82,7 @@ export function withEngineLaborFallbackField<T extends object>(
   return rest as T;
 }
 
-/** Install the activation-scoped latch (Judge/Reviewer session_start). */
+/** Install the activation-scoped latch (any role session_start with engine). */
 export function installActivationEngineLaborFallbackLatch(
   latch: EngineLaborFallbackLatch,
 ): void {

package/src/merger-role.ts

@@ -1,4 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  readActivationEngineLaborFallbackField,
+  withEngineLaborFallbackField,
+} from "./engine-labor-fallback.ts";
 import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, mergerOutputSchema, validateMergerInput, validateMergerOutput, type MergerInput } from "./merger-contracts.ts";
 import type { MergerGitState } from "./merger-git-state.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
@@ -47,7 +51,11 @@ export function createMergerRoleRuntime(pi: ExtensionAPI, dependencies: MergerRo
             if (state.mergeCommitId !== output.mergeCommitId || !same(state.parentObjectIds, [activation.input.targetObjectId, activation.input.sourceObjectId]) || state.unmergedPaths.length !== 0 || !state.worktreeClean || state.resolutionChangedPaths.some(path => !scope.has(path))) host.failInfrastructure(new Error("Merger completed-state verification failed"), ctx, id);
           }
           accepted = true;
-          return { content: [{ type: "text" as const, text: MERGER_ACCEPTED_TEXT }], details: output, terminate: true as const };
+          const acceptedDetails = withEngineLaborFallbackField(
+            output,
+            readActivationEngineLaborFallbackField(),
+          );
+          return { content: [{ type: "text" as const, text: MERGER_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true as const };
         } });
       pi.on("before_agent_start", event => { if (!activation) throw new Error("Merger is not activated"); const admitted = { attemptId: activation.input.attemptId, targetObjectId: activation.input.targetObjectId, sourceObjectId: activation.input.sourceObjectId, task: materialText(activation.input, "task"), authority: materialText(activation.input, "authority"), targetIntent: materialText(activation.input, "targetIntent"), sourceIntent: materialText(activation.input, "sourceIntent"), expectedConflictPaths: activation.input.expectedConflictPaths, resolutionScope: activation.input.resolutionScope, authorizedChecks: activation.input.authorizedChecks }; return { systemPrompt: `${event.systemPrompt}\n\n<merger_soul>\n${activation.soul}\n</merger_soul>\n\n<merger_assignment>\n${JSON.stringify(admitted)}\n</merger_assignment>` }; });
     }

package/src/public-cli/cli.ts

@@ -11,12 +11,12 @@ import {
 import {
   effectiveSeatConfigurations,
   formatModelSpec,
+  isEngineAxisSeat,
   loadCredentialProviders,
   loadPublicCliConfig,
   parseModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
-  isEngineAxisSeat,
   setPersistentSeatConfig,
   setPersistentSeatEngine,
   validatePublicCliConfigEngines,
@@ -58,10 +58,13 @@ import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
 import { runPublicTaishi } from "./taishi-run.ts";
 import { peekRoleRunRole } from "./run-lifecycle.ts";
 import {
+  AUTOMATIC_NAVIGATOR_SEAT,
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
+  isPublicCallableRole,
   isPublicCliSupportCommand,
   isPublicConfigurableSeat,
   listHelpCapabilities,
+  type PublicCallableRole,
   type PublicThinkingLevel,
 } from "./registry.ts";
 import {
@@ -336,6 +339,31 @@ function requireLegalEngineName(name: string): string {
   }
 }
 
+/**
+ * Persistent engine axis gate (#391 E1): PUBLIC_CALLABLE_ROLES only.
+ * Navigator is a configurable model seat but has no independent activation path.
+ */
+function requireEngineAxisSeat(
+  seat: string,
+  verb: "set-engine" | "unset-engine",
+): asserts seat is PublicCallableRole {
+  if (seat === AUTOMATIC_NAVIGATOR_SEAT) {
+    throw new CliUsageError(
+      `config ${verb} refuses navigator: no independent activation path; storing would be silently ineffective`,
+    );
+  }
+  if (!isEngineAxisSeat(seat)) {
+    throw new CliUsageError(`unknown engine-axis seat: ${seat}`);
+  }
+}
+
+/** Single seat.engine → run-options projection (#391 E2). */
+function projectSeatEngine(
+  seat: Readonly<{ engine?: string }>,
+): { engine: string } | Record<PropertyKey, never> {
+  return seat.engine === undefined ? {} : { engine: seat.engine };
+}
+
 function loadAndValidateConfig(
   home: string,
   packageRoot: string,
@@ -419,7 +447,7 @@ function renderHelp(): string {
     "",
     "Role options: ak-role help <command>",
     "Persistent config: ak-role config set <seat> <provider/model[:thinking]>",
-    "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
+    "Persistent engine (callable roles): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles",
   );
   return `${lines.join("\n")}\n`;
@@ -536,19 +564,12 @@ async function runConfigCommand(
   if (args[0] === "set-engine") {
     if (args.length !== 3) {
       throw new CliUsageError(
-        "usage: ak-role config set-engine <judge|reviewer> <name>",
+        "usage: ak-role config set-engine <seat> <name>",
       );
     }
     const seat = args[1]!;
     const name = args[2]!;
-    if (!isPublicConfigurableSeat(seat)) {
-      throw new CliUsageError(`unknown configurable seat: ${seat}`);
-    }
-    if (!isEngineAxisSeat(seat)) {
-      throw new CliUsageError(
-        `engine axis is judge+reviewer only; refused seat ${seat}`,
-      );
-    }
+    requireEngineAxisSeat(seat, "set-engine");
     requireLegalEngineName(name);
     let config = await loadAndValidateConfig(home, packageRoot);
     try {
@@ -567,18 +588,11 @@ async function runConfigCommand(
   if (args[0] === "unset-engine") {
     if (args.length !== 2) {
       throw new CliUsageError(
-        "usage: ak-role config unset-engine <judge|reviewer>",
+        "usage: ak-role config unset-engine <seat>",
       );
     }
     const seat = args[1]!;
-    if (!isPublicConfigurableSeat(seat)) {
-      throw new CliUsageError(`unknown configurable seat: ${seat}`);
-    }
-    if (!isEngineAxisSeat(seat)) {
-      throw new CliUsageError(
-        `engine axis is judge+reviewer only; refused seat ${seat}`,
-      );
-    }
+    requireEngineAxisSeat(seat, "unset-engine");
     let config = await loadAndValidateConfig(home, packageRoot);
     try {
       config = setPersistentSeatEngine(config, seat, undefined);
@@ -609,17 +623,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 / #378: engine axis is Judge+Reviewer (not resume / other seats).
+    // #356 / #378 / #391: engine axis is every callable role (not resume / support).
     if (parsed.engine !== undefined) {
       requireLegalEngineName(parsed.engine);
       if (
         !parsed.help &&
         parsed.command !== undefined &&
         parsed.command !== "help" &&
-        !isEngineAxisSeat(parsed.command)
+        !isPublicCallableRole(parsed.command)
       ) {
         throw new CliUsageError(
-          `engine axis is judge+reviewer only; refused command ${parsed.command}`,
+          `engine axis is role commands only; refused command ${parsed.command}`,
         );
       }
     }
@@ -876,7 +890,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 }),
+          ...projectSeatEngine(seat),
           ...(env.judgeExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.judgeExtraPiArgs }),
@@ -920,6 +934,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...projectSeatEngine(seat),
           ...(env.coderExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.coderExtraPiArgs }),
@@ -963,6 +978,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...projectSeatEngine(seat),
           ...(env.fixerExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.fixerExtraPiArgs }),
@@ -1006,6 +1022,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...projectSeatEngine(seat),
           ...(env.collectorExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.collectorExtraPiArgs }),
@@ -1049,7 +1066,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 }),
+          ...projectSeatEngine(seat),
           ...(env.reviewerExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.reviewerExtraPiArgs }),
@@ -1093,6 +1110,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...projectSeatEngine(seat),
           ...(env.doctorExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.doctorExtraPiArgs }),
@@ -1136,6 +1154,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...projectSeatEngine(seat),
           ...(env.mergerExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.mergerExtraPiArgs }),

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

@@ -6,6 +6,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
   resolvePackagedMethodSkillPath,
@@ -79,6 +81,8 @@ export type CoderRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + env signal). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -96,10 +100,14 @@ export function buildCoderActivationExtraArgs(
   options: {
     packageRoot: string;
     model?: SeatModelConfig;
+    engine?: string;
     extraPiArgs?: readonly string[];
   },
 ): string[] {
-  const prompt = buildCoderTransportPrompt(admitted);
+  const prompt = buildCoderTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   const skillArgs =
     admitted.phase === "apply"
       ? [
@@ -276,12 +284,14 @@ async function dispatchAdmittedCoder(input: {
   extraArgs: string[];
   lease: RunWriterLease;
   methodProvenance?: PackagedMethodSkillProvenance;
+  /** Mechanical engine provenance for initial Coder dispatch only. */
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedCoderInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease, methodProvenance } = input;
+  const { admitted, env, io, extraArgs, lease, methodProvenance, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -294,7 +304,7 @@ async function dispatchAdmittedCoder(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -303,6 +313,7 @@ async function dispatchAdmittedCoder(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -474,6 +485,7 @@ export async function runPublicCoder(
   const extraArgs = buildCoderActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -487,6 +499,7 @@ export async function runPublicCoder(
     extraArgs,
     lease,
     ...(methodProvenance === undefined ? {} : { methodProvenance }),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 

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

@@ -6,6 +6,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   runExplicitInternalActivation,
   type ExplicitInternalKnownFailure,
@@ -64,6 +66,8 @@ export type CollectorRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + env signal). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -79,10 +83,15 @@ export function buildCollectorActivationExtraArgs(
   admitted: AdmittedCollectorInvocation,
   options: {
     model?: SeatModelConfig;
+    engine?: string;
+    packageRoot?: string;
     extraPiArgs?: readonly string[];
   } = {},
 ): string[] {
-  const prompt = buildCollectorTransportPrompt(admitted);
+  const prompt = buildCollectorTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   return [
     "--no-skills",
     "--no-prompt-templates",
@@ -174,12 +183,13 @@ async function dispatchAdmittedCollector(input: {
   io: CliIo;
   extraArgs: string[];
   lease: RunWriterLease;
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedCollectorInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease } = input;
+  const { admitted, env, io, extraArgs, lease, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -192,7 +202,7 @@ async function dispatchAdmittedCollector(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -201,6 +211,7 @@ async function dispatchAdmittedCollector(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    applyEngineChildEnv(childEnv, env.engine);
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== undefined && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -354,7 +365,9 @@ export async function runPublicCollector(
   }
 
   const extraArgs = buildCollectorActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -367,5 +380,6 @@ export async function runPublicCollector(
     io,
     extraArgs,
     lease,
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }

package/src/public-cli/config.ts

@@ -10,7 +10,10 @@ import {
   AUTOMATIC_NAVIGATOR_SEAT,
   PUBLIC_CALLABLE_ROLES,
   PUBLIC_CONFIGURABLE_SEATS,
+  isPublicCallableRole,
+  isPublicConfigurableSeat,
   type ModelRef,
+  type PublicCallableRole,
   type PublicConfigurableSeat,
   type PublicThinkingLevel,
   publicStartupCandidates,
@@ -116,23 +119,24 @@ 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";
+/**
+ * Seats that own the labor-engine axis (#391: PUBLIC_CALLABLE_ROLES only).
+ * Navigator is configurable for model but has no independent activation path.
+ */
+export function isEngineAxisSeat(seat: string): seat is PublicCallableRole {
+  return isPublicCallableRole(seat);
 }
 
 /**
- * Set or clear persistent engine on Judge or Reviewer (#356 / #378).
+ * Set or clear persistent engine on a callable role seat (#356 / #378 / #391).
  * Engine-only seats are rejected — provider/model[:thinking] remains required first.
+ * Seat type is PublicCallableRole (navigator excluded at the type boundary).
  */
 export function setPersistentSeatEngine(
   config: PublicCliConfig,
-  seat: PublicConfigurableSeat,
+  seat: PublicCallableRole,
   engine: string | undefined,
 ): PublicCliConfig {
-  if (!isEngineAxisSeat(seat)) {
-    throw new Error(`engine axis is judge+reviewer only; refused seat ${seat}`);
-  }
   const previous = config.seats[seat];
   if (previous === undefined) {
     throw new Error(
@@ -166,9 +170,10 @@ export function seatModelOnly(seat: PersistentSeatConfig): SeatModelConfig {
 }
 
 /**
- * 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).
+ * Config-parse seam: engine axis is PUBLIC_CALLABLE_ROLES; engine names need only
+ * path-safety syntax (no closed material catalog; #376 / #378 / #391 / ADR 0069).
+ * Disk-handwritten navigator.engine is rejected (no independent activation → silent
+ * ineffective would violate failure honesty). Call after load / before dispatch (#356).
  * Syntax authority = assertLegalEngineName (no injected duplicate).
  */
 export function validatePublicCliConfigEngines(
@@ -180,7 +185,7 @@ export function validatePublicCliConfigEngines(
     if (row?.engine === undefined) continue;
     if (!isEngineAxisSeat(seat)) {
       throw new Error(
-        `config seat ${seat} engine is not allowed; engine axis is judge+reviewer only`,
+        `config seat ${seat} cannot persist engine: no independent activation path; storing would be silently ineffective`,
       );
     }
     try {
@@ -356,7 +361,7 @@ function attachEngineAxis(
   config: PublicCliConfig,
   invocation?: InvocationModelOverride,
 ): EffectiveSeat {
-  // #356 / #378: engine axis is Judge+Reviewer. Other seats stay unconfigured.
+  // #391: engine axis is PUBLIC_CALLABLE_ROLES only (single isEngineAxisSeat predicate).
   if (!isEngineAxisSeat(seat.seat)) {
     return {
       ...seat,

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

@@ -6,6 +6,8 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   runExplicitInternalActivation,
   type ExplicitInternalKnownFailure,
@@ -65,6 +67,8 @@ export type DoctorRunEnv = {
   correlationId?: string;
   piRunner?: ExplicitInternalPiRunner;
   model?: SeatModelConfig;
+  /** Optional labor engine name (config→activation; session material + env signal). */
+  engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
@@ -81,10 +85,15 @@ export function buildDoctorActivationExtraArgs(
   admitted: AdmittedDoctorInvocation,
   options: {
     model?: SeatModelConfig;
+    engine?: string;
+    packageRoot?: string;
     extraPiArgs?: readonly string[];
   } = {},
 ): string[] {
-  const prompt = buildDoctorTransportPrompt(admitted);
+  const prompt = buildDoctorTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
   return [
     "--no-skills",
     "--no-prompt-templates",
@@ -155,12 +164,13 @@ async function dispatchAdmittedDoctor(input: {
   io: CliIo;
   extraArgs: string[];
   lease: RunWriterLease;
+  effectiveEngine?: string;
 }): Promise<{
   exitCode: number;
   admitted: AdmittedDoctorInvocation;
   terminal?: TerminalResult;
 }> {
-  const { admitted, env, io, extraArgs, lease } = input;
+  const { admitted, env, io, extraArgs, lease, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -173,7 +183,7 @@ async function dispatchAdmittedDoctor(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -182,6 +192,7 @@ async function dispatchAdmittedDoctor(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
+    applyEngineChildEnv(childEnv, env.engine);
     if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = env.correlationId;
     }
@@ -333,7 +344,9 @@ export async function runPublicDoctor(
   }
 
   const extraArgs = buildDoctorActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
@@ -343,5 +356,6 @@ export async function runPublicDoctor(
     io,
     extraArgs,
     lease,
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }