@akagilnc/pi-workflow-roles 0.1.3837 → 0.1.3884

package/src/public-cli/cli.ts

@@ -43,9 +43,9 @@ import { seatModelOnly } from "./registry.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import type { CliIo } from "./cli-io.ts";
 import type { PostAdmissionEnv } from "./post-admission.ts";
-import type { RoleTurnHost, RoleTurnRequest } from "../host-contracts.ts";
+import type { RoleTurnHost } from "../host-contracts.ts";
 import { packagedExternalHostNames } from "../host-descriptions.ts";
-import { loadProductionExternalHostFactory } from "./load-production-external-host.ts";
+import { createLazyProductionExternalHost } from "./load-production-external-host.ts";
 import {
   createPiRoleTurnHost,
   appendPiSessionCustomEntry,
@@ -335,29 +335,20 @@ function resolveRoleTurnHost(
     recordLaunchedRolePackageIdentity,
     observeLaunchedRolePackageIdentity,
   });
-  // Composition-root adapter table: pi (in-process default) + one ACP adapter per description-table key.
+  // Composition-root adapter table: pi (in-process default) + one lazy external host per description-table key (#820).
   const adapters: readonly NamedRoleTurnHostAdapter[] = env.hostAdapters ?? [
     { name: "pi", create: () => ({ ok: true as const, host: piHost }) },
     ...packagedExternalHostNames().map((name) => ({
       name,
-      create: () => {
+      create: () => ({
+        ok: true as const,
         // Factory loads outside the public bin static graph (ADR 0052 peer-free discovery).
-        let hostPromise: Promise<RoleTurnHost> | undefined;
-        return {
-          ok: true as const,
-          host: {
-            executeTurn: async (request: RoleTurnRequest) => {
-              hostPromise ??= loadProductionExternalHostFactory(env.packageRoot, name).then((create) =>
-                create({
-                  packageRoot: env.packageRoot,
-                  principalAuthority: options.principalAuthority,
-                }),
-              );
-              return (await hostPromise).executeTurn(request);
-            },
-          },
-        };
-      },
+        host: createLazyProductionExternalHost({
+          packageRoot: env.packageRoot,
+          hostName: name,
+          principalAuthority: options.principalAuthority,
+        }),
+      }),
     })),
   ];
   const hostName = options.seat.host;

package/src/public-cli/invocation.ts

@@ -211,11 +211,10 @@ export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly authorityRefs: readonly string[];
 };
 
-/** Mechanical envelope derived from the active ordinary two-parent merge. */
+/** Mechanical materials read from current Git state (may be empty). */
 export type DerivedMergerEnvelope = {
   readonly targetObjectId: string;
   readonly sourceObjectId: string;
-  readonly automaticMergeTreeId: string;
   readonly expectedConflictPaths: readonly string[];
   readonly resolutionScope: readonly string[];
 };
@@ -810,17 +809,6 @@ export type ParseAnalystArgvResult =
   | ParseAnalystSweepArgv
   | ParseAnalystCohortArgv;
 
-/** Honest activation-class failure while deriving the active-merge envelope. */
-export class MergerEnvelopeDerivationError extends Error {
-  readonly code = "merger-envelope-derivation" as const;
-  /** Typed cause for #107 classifyPostAdmissionFailure (isTypedActivationError). */
-  readonly knownCause = "activation" as const;
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "MergerEnvelopeDerivationError";
-  }
-}
-
 /** Reject missing/blank path values so empty overrides cannot silently degrade. */
 function requireOptionPath(
   flag: string,
@@ -2868,7 +2856,7 @@ export function parseMergerArgv(args: readonly string[]): ParseMergerArgvResult
       token.startsWith("--resolutionScope=")
     ) {
       throw new CliUsageError(
-        "merger does not accept public packet fields; the adapter derives the active-merge envelope",
+        "merger does not accept public packet fields; the adapter reads Git merge materials",
       );
     }
     if (token.startsWith("-") && token !== "-") {
@@ -2894,36 +2882,20 @@ function mergerMaterialFromUtf8(text: string): MergerInput["materials"]["task"]
 }
 
 /**
- * Derive the mechanical Merger envelope from an already-active ordinary merge.
- * Uses the production Git seam (HEAD, sole MERGE_HEAD, AUTO_MERGE, unmerged set).
- * Failures are activation-class facts — not CLI semantic guesses.
+ * Read merger materials from current Git state.
+ * No in-progress merge / empty conflict set still yields materials (possibly empty);
+ * code does not gate attendance on merge state (#827).
  */
 export async function deriveMergerEnvelopeFromActiveMerge(
   projectRoot: string,
   gitState: MergerGitState = createProductionMergerGitState(projectRoot),
 ): Promise<DerivedMergerEnvelope> {
-  let state;
-  try {
-    state = await gitState.activeMerge();
-  } catch (error) {
-    const message =
-      error instanceof Error && error.message.trim() !== ""
-        ? error.message
-        : "Assigned repository does not have one ordinary in-progress merge";
-    throw new MergerEnvelopeDerivationError(message, { cause: error });
-  }
-  if (state.unmergedPaths.length === 0) {
-    throw new MergerEnvelopeDerivationError(
-      "Assigned repository does not have one ordinary in-progress merge with a complete conflict set",
-    );
-  }
+  const state = await gitState.activeMerge();
   const expectedConflictPaths = Object.freeze([...state.unmergedPaths]);
-  // Scope is derived as the complete conflict set; the role may not broaden it.
   const resolutionScope = Object.freeze([...state.unmergedPaths]);
   return Object.freeze({
     targetObjectId: state.targetObjectId,
     sourceObjectId: state.sourceObjectId,
-    automaticMergeTreeId: state.automaticMergeTreeId,
     expectedConflictPaths,
     resolutionScope,
   });
@@ -2945,8 +2917,9 @@ export type AdmitMergerInvocationOptions = {
 
 /**
  * Admit a Merger Role run on the common Invocation request.
- * Mechanical envelope (parents, AUTO_MERGE, conflicts, scope) is derived from
- * the active merge — callers never supply public packet fields for those facts.
+ * Git materials (parents, conflicts, scope) are read from the worktree and
+ * handed to the role as assignment materials — including when empty (#827).
+ * Callers never supply public packet fields for those facts.
  */
 export async function admitMergerInvocation(
   options: AdmitMergerInvocationOptions,
@@ -2960,8 +2933,6 @@ export async function admitMergerInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  // Derive mechanical envelope before placing a run identity so no-merge/drift
-  // fails honestly without orphan ledger rows or guessed packet fields.
   const derived = await deriveMergerEnvelopeFromActiveMerge(
     projectRoot,
     options.gitState ?? createProductionMergerGitState(projectRoot),
@@ -2988,18 +2959,18 @@ export async function admitMergerInvocation(
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 
   // Intent materials seed primary-source investigation; the method owns the work.
+  const targetLabel = derived.targetObjectId === "" ? "(none observed)" : derived.targetObjectId;
+  const sourceLabel = derived.sourceObjectId === "" ? "(none observed)" : derived.sourceObjectId;
   const targetIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for target parent ${derived.targetObjectId}. Do not invent intent.`,
+    `Investigate primary sources for target parent ${targetLabel}. Do not invent intent.`,
   );
   const sourceIntent = mergerMaterialFromUtf8(
-    `Investigate primary sources for source parent ${derived.sourceObjectId}. Do not invent intent.`,
+    `Investigate primary sources for source parent ${sourceLabel}. Do not invent intent.`,
   );
   const taskMaterial = mergerMaterialFromUtf8(instruction);
   const authorityMaterial = mergerMaterialFromUtf8(instruction);
 
-  // Validate merger envelope before placing admitted identity.
   const mergerInput = validateMergerInput({
-    version: 1,
     attemptId: runId,
     targetObjectId: derived.targetObjectId,
     sourceObjectId: derived.sourceObjectId,
@@ -3011,7 +2982,6 @@ export async function admitMergerInvocation(
     },
     expectedConflictPaths: [...derived.expectedConflictPaths],
     resolutionScope: [...derived.resolutionScope],
-    // Authorized checks remain available on the assignment; default none.
     authorizedChecks: [],
   });
 
@@ -3035,7 +3005,6 @@ export async function admitMergerInvocation(
     derived: {
       targetObjectId: derived.targetObjectId,
       sourceObjectId: derived.sourceObjectId,
-      automaticMergeTreeId: derived.automaticMergeTreeId,
       expectedConflictPaths: [...derived.expectedConflictPaths],
       resolutionScope: [...derived.resolutionScope],
     },

package/src/public-cli/load-production-acp-host.ts

@@ -25,6 +25,7 @@ type GenericAcpHostFactory = (options: {
   packageRoot: string;
   principalAuthority: DurablePrincipalAuthority;
   description: AcpHostDescription;
+  hostName: string;
 }) => RoleTurnHost;
 
 /**
@@ -48,5 +49,5 @@ export async function loadProductionAcpHostFactory(
     createProductionAcpRoleTurnHost: GenericAcpHostFactory;
   };
   const create = mod.createProductionAcpRoleTurnHost;
-  return (options) => create({ ...options, description });
+  return (options) => create({ ...options, description, hostName: host });
 }

package/src/public-cli/load-production-external-host.ts

@@ -27,3 +27,20 @@ export async function loadProductionExternalHostFactory(
   }
   throw new Error(`unregistered host: ${host}`);
 }
+
+/** Lazy production external host — sole builder for CLI adapter table + public summons (#820). */
+export function createLazyProductionExternalHost(options: {
+  readonly packageRoot: string;
+  readonly hostName: string;
+  readonly principalAuthority: DurablePrincipalAuthority;
+}): RoleTurnHost {
+  let hostPromise: Promise<RoleTurnHost> | undefined;
+  return {
+    executeTurn: async (request) => {
+      hostPromise ??= loadProductionExternalHostFactory(options.packageRoot, options.hostName).then((create) =>
+        create({ packageRoot: options.packageRoot, principalAuthority: options.principalAuthority }),
+      );
+      return (await hostPromise).executeTurn(request);
+    },
+  };
+}

package/src/public-cli/load-production-headless-host.ts

@@ -22,6 +22,7 @@ type GenericHeadlessHostFactory = (options: {
   packageRoot: string;
   principalAuthority: DurablePrincipalAuthority;
   description: HeadlessHostDescription;
+  hostName: string;
 }) => RoleTurnHost;
 
 /**
@@ -44,5 +45,5 @@ export async function loadProductionHeadlessHostFactory(
     createProductionHeadlessRoleTurnHost: GenericHeadlessHostFactory;
   };
   const create = mod.createProductionHeadlessRoleTurnHost;
-  return (options) => create({ ...options, description });
+  return (options) => create({ ...options, description, hostName: host });
 }

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

@@ -1,18 +1,13 @@
 /**
- * Public Merger Role run: derive active-merge envelope → force package
- * merge-only method → post-admission coordinator → settle Terminal result (#114 / #517).
+ * Public Merger Role run: read Git materials → force package merge-only method
+ * → post-admission coordinator → settle Terminal result (#114 / #517 / #827).
  * #526: execution via RoleTurnHost; argv is Pi adapter internal.
  */
 import type {
-  DurablePrincipalAuthority,
   MethodBinding,
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "../host-contracts.ts";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-import { ensureRealDirectoryTree } from "../activation-ledger-topology.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import {
   loadPackagedMethodSkillMaterial,
@@ -20,13 +15,10 @@ import {
   type PackagedMethodSkillMaterial,
   type PackagedMethodSkillProvenance,
 } from "../package-resources/method-skill.ts";
-import { uuidv7 } from "../uuidv7.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
   admitMergerInvocation,
   buildMergerTransportPrompt,
-  issueAdmissionPlacement,
-  MergerEnvelopeDerivationError,
   type AdmittedMergerInvocation,
 } from "./invocation.ts";
 import {
@@ -116,82 +108,6 @@ async function loadMergerMethodMaterial(
   );
 }
 
-/**
- * Structural admit shell when envelope derivation fails: keeps role-correct
- * Terminal identity for honest activation-class settlement without inventing
- * parents/conflicts (those stay empty; the gate never receives a guessed packet).
- */
-async function admitMergerShellForActivationFailure(options: {
-  home: string;
-  cwd: string;
-  instruction: string;
-  project?: string;
-  createRunId?: () => string;
-  principalAuthority: DurablePrincipalAuthority;
-}): Promise<AdmittedMergerInvocation> {
-  const projectRoot = resolve(options.project ?? options.cwd);
-  const runId = (options.createRunId ?? uuidv7)();
-  const {
-    principal,
-    sessionDirectory,
-    sessionFile,
-    runDirectory,
-    ledgerHome,
-    bookKey,
-  } = issueAdmissionPlacement(options.principalAuthority, {
-    cwd: projectRoot,
-    runId,
-    role: "merger",
-    home: options.home,
-  });
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  await mkdir(runDirectory, { recursive: true });
-  const emptyDerived = {
-    targetObjectId: "",
-    sourceObjectId: "",
-    automaticMergeTreeId: "",
-    expectedConflictPaths: [] as string[],
-    resolutionScope: [] as string[],
-  };
-  const admittedRequestPath = join(runDirectory, "admitted-request.json");
-  const mergerInputPath = join(runDirectory, "merger-input.json");
-  await writeFile(
-    admittedRequestPath,
-    `${JSON.stringify(
-      {
-        role: "merger",
-        runId,
-        bookKey,
-        projectRoot,
-        instruction: options.instruction,
-        instructionEmpty: false,
-        mergerInputPath,
-        derived: emptyDerived,
-        attachments: [],
-        sessionDirectory,
-        sessionFile,
-      },
-      null,
-      2,
-    )}\n`,
-    "utf8",
-  );
-  return {
-    role: "merger",
-    runId,
-    bookKey,
-    projectRoot,
-    instruction: options.instruction,
-    instructionEmpty: false,
-    attachments: [],
-    runDirectory,
-    principal,
-    admittedRequestPath,
-    mergerInputPath,
-    derived: emptyDerived,
-  };
-}
-
 function mergerTurnOptions(
   admitted: AdmittedMergerInvocation,
   env: MergerRunEnv,
@@ -263,33 +179,6 @@ export async function runPublicMerger(
       presentStructuralRejection(error, io);
       return { exitCode: 2 };
     }
-    if (error instanceof MergerEnvelopeDerivationError) {
-      const shell = await admitMergerShellForActivationFailure({
-        home: env.home,
-        principalAuthority: env.principalAuthority,
-        cwd: env.cwd,
-        instruction: parsed.instruction,
-        ...(parsed.project === undefined ? {} : { project: parsed.project }),
-        ...(env.createRunId === undefined
-          ? {}
-          : { createRunId: env.createRunId }),
-      });
-      await markRunAdmitted(shell, env.principalAuthority);
-      return (await presentControlledFailure(
-        shell,
-        {
-          timedOut: false,
-          code: null,
-          stderr: "",
-          thrown: error,
-          knownCause: "activation",
-          knownDiagnostic: error.message,
-        },
-        mergerAdapters(env.packageRoot),
-        env.principalAuthority,
-        io,
-      )) as { exitCode: number; admitted: AdmittedMergerInvocation; terminal: TerminalResult };
-    }
     throw error;
   }
 

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

@@ -670,7 +670,7 @@ const NOTARY_OPTIONS = [
 ] as const satisfies readonly PublicOptionDefinition[];
 
 const MERGER_OPTIONS = [
-  // Merger project face differs: requires an in-progress ordinary merge root.
+  // Merger project face: worktree whose Git materials are handed to the role.
   {
     id: "project",
     owner: "merger",
@@ -681,8 +681,8 @@ const MERGER_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Project root with one ordinary in-progress merge (defaults to cwd).",
-      zh: "已有进行中 ordinary merge 的项目根（默认 cwd）。",
+      en: "Project root whose Git merge materials are read (defaults to cwd).",
+      zh: "读取 Git merge 材料的项目根（默认 cwd）。",
     },
   },
   bindOwner("merger", SHARED_ATTACH_SEMANTICS),
@@ -1231,10 +1231,10 @@ const ROLE_COMMAND_HELP = {
   },
   merger: {
     command: "merger",
-    summary: "Resolve one ordinary merge already in conflict.",
+    summary: "Reconcile merge materials in a worktree (escalate when nothing to merge).",
     usage: ["ak-role merger [options] <instruction>"],
     examples: [
-      'ak-role merger --project /path/to/worktree "Reconcile the active merge."',
+      'ak-role merger --project /path/to/worktree "Reconcile the merge."',
     ],
   },
   inspector: {

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

@@ -1386,7 +1386,6 @@ async function loadResumableRunRecord(
         if (
           typeof d.targetObjectId === "string" &&
           typeof d.sourceObjectId === "string" &&
-          typeof d.automaticMergeTreeId === "string" &&
           Array.isArray(d.expectedConflictPaths) &&
           Array.isArray(d.resolutionScope) &&
           d.expectedConflictPaths.every((p) => typeof p === "string") &&
@@ -1395,7 +1394,6 @@ async function loadResumableRunRecord(
           derived = {
             targetObjectId: d.targetObjectId,
             sourceObjectId: d.sourceObjectId,
-            automaticMergeTreeId: d.automaticMergeTreeId,
             expectedConflictPaths: d.expectedConflictPaths as string[],
             resolutionScope: d.resolutionScope as string[],
           };

package/src/public-role-summons.ts

@@ -65,12 +65,6 @@ export type PublicSummonRequest = {
    * Never folded into argv / parent-run lookup keys (ADR 0079 卷宗指针 stays pure).
    */
   readonly gateReviewInstruction?: string;
-  /**
-   * Parent-invocation host axis (#617 / #645). Nested institutional legs inherit
-   * the live parent `--host` so a single public entry does not require mutating
-   * persistent seat host. Seat model/thinking stay on the officer seat table.
-   */
-  readonly host?: string;
   /**
    * Offline test inject — same face as public CLI env.roleTurnHost. Production
    * summons leave this unset and use the seat-resolved host.
@@ -218,7 +212,7 @@ async function createSummonEnv(options: {
   let roleTurnHost = piHost;
   if (hostName !== "pi") {
     const { lookupHostFamily } = await import("./host-descriptions.ts");
-    const { loadProductionExternalHostFactory } = await import(
+    const { createLazyProductionExternalHost } = await import(
       "./public-cli/load-production-external-host.ts"
     );
     // #729 / #645: description tables are the sole host authority — family
@@ -228,19 +222,12 @@ async function createSummonEnv(options: {
         `public role summons host unregistered: host=${hostName} seat=${options.role}`,
       );
     }
-    let hostPromise: Promise<RoleTurnHost> | undefined;
-    roleTurnHost = {
-      executeTurn: async (request) => {
-        hostPromise ??= loadProductionExternalHostFactory(options.packageRoot, hostName).then(
-          (create) =>
-            create({
-              packageRoot: options.packageRoot,
-              principalAuthority,
-            }),
-        );
-        return (await hostPromise).executeTurn(request);
-      },
-    };
+    // Same lazy external host face as public CLI (#820) — one builder, two callers.
+    roleTurnHost = createLazyProductionExternalHost({
+      packageRoot: options.packageRoot,
+      hostName,
+      principalAuthority,
+    });
   }
   // #788: host is registered above; only then project host-facing provider.
   const { loadHostProvidersTable, projectHostFacingProvider } = await import(
@@ -291,10 +278,9 @@ export async function summonPublicRole(
   const credentials =
     options.credentials ?? (await loadCredentialProviders(agentDir));
   const config = await loadPublicCliConfig(home);
-  // Nested legs inherit parent invocation host when provided (#645 review path).
-  // Model/thinking stay on the officer seat — host-only inherit (seat-table law).
-  const invocation = options.host === undefined ? undefined : { host: options.host };
-  const seat = resolveEffectiveSeat(config, options.role, credentials, invocation);
+  // Nested summons resolve host on the officer seat only (flag>seat>default pi).
+  // Parent run host is not an override channel (#821 / ADR 0082 host-flag-two-channels).
+  const seat = resolveEffectiveSeat(config, options.role, credentials);
   const env = {
     ...(await createSummonEnv({
       role: options.role,
@@ -420,47 +406,6 @@ export async function summonPublicRole(
 }
 
 /** Gate officer summons: notary/auditor via --source-run; inspector via pointer instruction. */
-/**
- * Read parent invocation host so nested officers inherit live --host only (#645).
- * Gate source runs necessarily own invocation.json — missing page, bad JSON, or
- * bad shape stay loud (failure-honesty). Absent host field is lawful (seat default).
- */
-async function parentInvocationHost(sourceRunDirectory: string): Promise<string | undefined> {
-  const { readFile } = await import("node:fs/promises");
-  const path = join(sourceRunDirectory, "invocation.json");
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch (error) {
-    const code =
-      error instanceof Error && "code" in error
-        ? (error as NodeJS.ErrnoException).code
-        : undefined;
-    throw new Error(
-      `parent invocation.json required for gate source run at ${path}: ${code ?? (error instanceof Error ? error.message : String(error))}`,
-      { cause: error },
-    );
-  }
-  let raw: unknown;
-  try {
-    raw = JSON.parse(text) as unknown;
-  } catch (error) {
-    throw new Error(
-      `parent invocation.json unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error },
-    );
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw new Error(`parent invocation.json has non-object shape at ${path}`);
-  }
-  const host = (raw as Record<string, unknown>).host;
-  if (host === undefined) return undefined;
-  if (typeof host !== "string" || host.trim() === "") {
-    throw new Error(`parent invocation.json host must be a non-empty string at ${path}`);
-  }
-  return host;
-}
-
 export async function summonGateOfficer(options: {
   readonly officer: "inspector" | "notary" | "auditor";
   readonly sourceRunDirectory: string;
@@ -501,9 +446,8 @@ export async function summonGateOfficer(options: {
       submission: options.submission,
     });
   }
-  // Inherit parent live --host only so review roundtrip stays on one host without
-  // mutating persistent seat tables (#645). Officer model/thinking stay seat-owned.
-  const parentHost = await parentInvocationHost(options.sourceRunDirectory);
+  // Officer host is seat-owned only (#821). Parent invocation.json.host stays a
+  // hostTransition consumer in post-admission — not an officer override channel.
   const common = {
     cwd: options.cwd,
     ...(home === undefined ? {} : { home }),
@@ -514,7 +458,6 @@ export async function summonGateOfficer(options: {
     ...(gateReviewInstruction === undefined
       ? {}
       : { gateReviewInstruction }),
-    ...(parentHost === undefined ? {} : { host: parentHost }),
     ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;

package/src/reviewer-agent.ts

@@ -29,7 +29,17 @@ export class ReviewerDispatchExecutionError extends Error {
     this.name = "ReviewerDispatchExecutionError";
   }
 }
-export type ReviewerAgentRunner = { run(dispatch: AcceptedReviewerExecution, options: { context: HostContext; signal?: AbortSignal }): Promise<ReviewerSuccessfulDispatchRunResult>; shutdown(): Promise<void> };
+export type ReviewerDispatchRunOptions = Readonly<{
+  context: HostContext;
+  signal?: AbortSignal;
+  /**
+   * Request-scoped RoleHost flag reader (#818).
+   * Forwards to axis sub-session so envelope legs arm engine from request.engine,
+   * not ambient process.env (same resolveEngineName gate as parent registration).
+   */
+  getFlag?: (name: string) => boolean | string | undefined;
+}>;
+export type ReviewerAgentRunner = { run(dispatch: AcceptedReviewerExecution, options: ReviewerDispatchRunOptions): Promise<ReviewerSuccessfulDispatchRunResult>; shutdown(): Promise<void> };
 export type ReviewerAgentFaultPoint = ReviewerWorkspaceFaultPoint;
 type Dependencies = Readonly<{
   fault?(operation: ReviewerAgentFaultPoint): void;
@@ -81,6 +91,7 @@ export function createReviewerAgentRunner(dependencies: Dependencies = {}): Revi
             ...(dependencies.packageRoot === undefined
               ? {}
               : { packageRoot: dependencies.packageRoot }),
+            ...(options.getFlag === undefined ? {} : { getFlag: options.getFlag }),
           });
           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

@@ -9,7 +9,7 @@ import type { Usage } from "@earendil-works/pi-ai";
 
 import type { HostContext, RoleTurnModelConfig } from "./host-contracts.ts";
 import { createEngineDetourToolDefinition } from "./engine-detour-tool.ts";
-import { engineNameFromEnv } from "./engine-detour.ts";
+import { resolveEngineName } from "./engine-detour.ts";
 import {
   appendEngineSessionMaterial,
   engineSessionMaterialFromOptions,
@@ -101,6 +101,13 @@ export type ReviewerChildExecuteOptions = Readonly<{
   credentialScratchParent?: string;
   /** Package root for optional engine method-material on legs (#378). */
   packageRoot?: string;
+  /**
+   * Request-scoped RoleHost flag reader (#818).
+   * Same single gate as registerEngineDetourTool / resolveEngineName:
+   * envelope projects request.engine here; absent → pi child-env fallback.
+   * Must not read ambient process.env as the primary signal on envelope legs.
+   */
+  getFlag?: (name: string) => boolean | string | undefined;
 }>;
 
 /**
@@ -145,7 +152,8 @@ export async function executeReviewerChild(
     const selection = await parentSelection(context);
     const { openPiInProcessSession } = await import("./pi/in-process-session.ts");
     const { createRecordSession } = await import("./archivist-record-entry.ts");
-    const engineName = engineNameFromEnv();
+    // One gate with parent registration (#818): request flag, else pi child env.
+    const engineName = resolveEngineName(options.getFlag);
     const engineMaterial =
       engineName === undefined
         ? undefined