@akagilnc/pi-workflow-roles 0.1.3837 → 0.1.3873

package/src/host-descriptions.ts

@@ -68,6 +68,7 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
 /**
  * Headless CLI family (#645). Claude is the first row; codex (#646) adds another.
  * fixedArgs: print mode, isolation without `--bare` (OAuth stays), full permissions.
+ * stream-json + verbose: live host events for sitian records (#811); result is last line.
  * `--setting-sources` empty = load no user/project/local CLAUDE.md/hooks/skills
  * (role envelope is delivered via `--system-prompt` wholesale replace).
  * `--strict-mcp-config` with no `--mcp-config` drops operator MCP + claude.ai connectors.
@@ -77,8 +78,10 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
     binaryFromHome: Object.freeze([".local", "bin", "claude"]),
     sessionBindingFile: "claude-headless-session.json",
     fixedArgs: Object.freeze([
-      // One result envelope (not stream-json): typed receipt only; no event-stream copy.
-      "--output-format", "json",
+      // Live NDJSON events → sitian host-session records (#811); last line is the result receipt.
+      "--output-format", "stream-json",
+      // Intermediate assistant/tool/system events require verbose with stream-json.
+      "--verbose",
       "--permission-mode", "bypassPermissions",
       // Empty sources: no user/project/local operator surface (envelope owns materials).
       "--setting-sources", "",

package/src/host-session-record.ts

@@ -0,0 +1,41 @@
+/**
+ * Non-pi host turn events → sitian sole entry (ADR 0065 / 0077 / #811).
+ * Adapters capture host-native structured events; this helper only packages
+ * the common sitianReport call. session.jsonl stays header-only (#617 DK-4).
+ * Write failures propagate (SitianInfrastructureError) — not best-effort.
+ */
+import { sitianReport } from "./sitian-facade.ts";
+
+/** Volume category under `<run>/session/<kind>/records.jsonl`. */
+export const HOST_SESSION_RECORD_KIND = "host-session" as const;
+
+function eventField(event: unknown, key: string): string | undefined {
+  if (typeof event !== "object" || event === null || Array.isArray(event)) return undefined;
+  const value = (event as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Live write of one host-emitted structured event. Throws on sitian persistence failure. */
+export function reportHostSessionEvent(input: {
+  readonly host: string;
+  readonly cwd: string;
+  readonly sessionParent: string;
+  readonly source: string;
+  readonly event: unknown;
+  readonly identity?: string;
+  readonly timestamp?: string;
+}): void {
+  const identity = input.identity ?? eventField(input.event, "uuid");
+  const timestamp = input.timestamp ?? eventField(input.event, "timestamp");
+  sitianReport({
+    level: "event",
+    kind: HOST_SESSION_RECORD_KIND,
+    host: input.host,
+    cwd: input.cwd,
+    sessionParent: input.sessionParent,
+    source: input.source,
+    payload: input.event,
+    ...(identity === undefined ? {} : { identity }),
+    ...(timestamp === undefined ? {} : { timestamp }),
+  });
+}

package/src/pi/role-turn-host.ts

@@ -15,7 +15,6 @@ import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
   MethodBinding,
-  RoleTurnActivation,
   RoleTurnHost,
   RoleTurnKnownFailure,
   RoleTurnModelConfig,
@@ -24,6 +23,7 @@ import type {
 } from "../host-contracts.ts";
 import { ExplicitInternalActivationError } from "../host-contracts.ts";
 import { applyEngineChildEnv } from "../engine-detour.ts";
+import { projectActivationFlags } from "../role-activation-flags.ts";
 
 
 /** Package-relative Internal role entrypoint (ADR 0052; same path as public-cli registry). */
@@ -66,95 +66,18 @@ function buildSeatModelCliArgs(model: RoleTurnModelConfig | undefined): string[]
   ];
 }
 
-function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
-  switch (activation.role) {
-    case "judge":
-      return ["--ak-role", "judge"];
-    case "coder":
-      return [
-        "--ak-role",
-        "coder",
-        "--ak-coder-phase",
-        activation.phase,
-        "--ak-coder-task",
-        activation.taskPath,
-      ];
-    case "fixer":
-      return [
-        "--ak-role",
-        "fixer",
-        "--ak-fixer-phase",
-        activation.phase,
-        "--ak-fix-packet",
-        activation.packetPath,
-        ...(activation.prerequisitesPath === undefined
-          ? []
-          : ["--ak-fixer-prerequisites", activation.prerequisitesPath]),
-      ];
-    case "reviewer":
-      return [
-        "--ak-role",
-        "reviewer",
-        "--ak-review-base",
-        activation.baseRevision,
-        ...(activation.authorityRefs.length === 0
-          ? []
-          : ["--ak-review-authority-refs", JSON.stringify([...activation.authorityRefs])]),
-        ...(activation.ticketNumber === undefined
-          ? []
-          : ["--ak-review-ticket-number", String(activation.ticketNumber)]),
-      ];
-    case "merger":
-      return ["--ak-role", "merger", "--ak-merger-input", activation.inputPath];
-    case "collector":
-      return [
-        "--ak-role",
-        "collector",
-        "--ak-collector-repo",
-        activation.repo,
-        ...(activation.pr === undefined ? [] : ["--ak-collector-pr", activation.pr]),
-        ...(activation.requestManifestPath === undefined
-          ? []
-          : ["--ak-collector-request-manifest", activation.requestManifestPath]),
-        ...(activation.waitMs === undefined ? [] : ["--ak-collector-wait-ms", activation.waitMs]),
-      ];
-    case "doctor":
-      return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];
-    case "notary":
-      return [
-        "--ak-role",
-        "notary",
-        "--ak-notary-source-run",
-        activation.sourceRun,
-        ...(activation.ticketNumber === undefined
-          ? []
-          : ["--ak-notary-ticket-number", String(activation.ticketNumber)]),
-      ];
-    case "countersign":
-      // ticketNumber rides activation/admission/invocation only (#632: no private flag).
-      return ["--ak-role", "countersign"];
-    case "gleaner-left":
-      return [
-        "--ak-role",
-        "gleaner-left",
-        "--ak-gleaner-left-base",
-        activation.baseRevision,
-      ];
-    case "inspector":
-      return ["--ak-role", "inspector"];
-    case "gatekeeper":
-      return ["--ak-role", "gatekeeper"];
-    case "navigator":
-      return ["--ak-role", "navigator"];
-    case "auditor":
-      return ["--ak-role", "auditor"];
-    case "diarist":
-      return ["--ak-role", "diarist"];
-    default: {
-      const _exhaustive: never = activation;
-      return _exhaustive;
-    }
+/**
+ * Pi last hop only: shared envelope flags → controlled-session argv pairs (#819).
+ * Flag membership/values stay in projectActivationFlags (middle layer).
+ */
+function activationFlagsToPiArgv(flags: ReadonlyMap<string, boolean | string>): string[] {
+  const args: string[] = [];
+  for (const [name, value] of flags) {
+    if (value === false) continue;
+    args.push(`--${name}`);
+    if (value !== true) args.push(String(value));
   }
+  return args;
 }
 
 function buildMethodArgs(methods: readonly MethodBinding[]): string[] {
@@ -193,9 +116,10 @@ export function applyPiNativeSkillInvocation(
 }
 
 /**
- * Translate a closed RoleTurnRequest into Pi argv after `--no-extensions -e entry`.
- * Controlled session constants and session coordinates are adapter-internal.
- * Single forced method → Pi-native `/skill:` on the argv prompt (coder/reviewer/merger).
+ * Pi last-hop argv after `--no-extensions -e entry` (#819).
+ * Activation flag membership comes from middle-layer projectActivationFlags;
+ * this function only renders session coords, controlled constants, and pairs.
+ * Single forced method → Pi-native `/skill:` on the argv prompt (#822).
  */
 export function buildPiTurnExtraArgs(
   request: RoleTurnRequest,
@@ -222,7 +146,8 @@ export function buildPiTurnExtraArgs(
     "--session-dir",
     sessionDirectory,
     ...extraPiArgs,
-    ...buildActivationFlagArgs(request.activation),
+    // Envelope assembly = projectActivationFlags; pi only renders argv pairs.
+    ...activationFlagsToPiArgv(projectActivationFlags(request)),
     "--mode",
     "json",
     ...buildSeatModelCliArgs(request.model),

package/src/prepared-role-turn.ts

@@ -0,0 +1,68 @@
+import type { RoleTurnKnownFailure, RoleTurnRequest } from "./host-contracts.ts";
+import { renderAgentStartMaterials } from "./agent-start-materials.ts";
+
+/** The shared envelope, prepared before session/new (systemPrompt delivery) and
+ * able to observe the host's real builtin tool surface once it arrives post-session. */
+export type PreparedRoleTurn = Readonly<{
+  mcpServers: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * Structured system-prompt authority. `body` is the provider-facing prompt
+   * bytes; `materials` are typed agent-start reading materials (e.g. Notary
+   * session bound) that the adapter folds into the override at the provider
+   * boundary. This structure is the authoritative production input of the
+   * send path — never a test-only parallel face.
+   */
+  systemPrompt: { readonly body: string; readonly materials: readonly unknown[] };
+  /** Effective user prompt after host-side input transform (canonical Skill invocation). */
+  prompt: string;
+  /**
+   * Host abort signal armed only by typed infrastructure failure (envelope
+   * rememberInfrastructureFailure / non-correctable MCP catch). Lawful
+   * context.abort() (seal / non-sole) does not arm it. executeTurn races
+   * session/prompt against this so infra declarations terminate even when
+   * ACP never resolves (#593).
+   */
+  abortSignal?: AbortSignal;
+  /** Shared ledger consumes the complete ACP round after session/prompt resolves. */
+  closeRound(): Promise<
+    | { readonly accepted: true }
+    | {
+      readonly accepted: false;
+      /** Shared envelope provides officer/correctable text; adapters only deliver it (#813). */
+      readonly retry: {
+        readonly code: string;
+        readonly toolCallIds: readonly string[];
+        readonly message: string;
+      };
+    }
+    | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
+  >;
+  dispose?(): Promise<void>;
+  /**
+   * Headless CLI family (#645): role terminating-tool schema for host-native
+   * `--json-schema`. Present for every prepared turn; ACP ignores it.
+   */
+  jsonSchema: Readonly<Record<string, unknown>>;
+  /** Terminating tool name whose schema is `jsonSchema`. */
+  terminatingToolName: string;
+  /**
+   * Headless CLI family: feed host-native `structured_output` through the same
+   * terminating-tool path the MCP relay uses (ledger + gates). ACP ignores it.
+   */
+  ingestStructuredOutput(params: unknown): Promise<void>;
+}>;
+
+/** Fold structured system-prompt authority into the provider-visible ACP override. */
+export function renderSystemPromptOverride(authority: {
+  readonly body: string;
+  readonly materials: readonly unknown[];
+}): string {
+  return renderAgentStartMaterials(authority.body, authority.materials);
+}
+
+export type SessionIdentityAuthority = Readonly<{
+  load(principal: RoleTurnRequest["principal"]): Promise<string | undefined>;
+  bind(principal: RoleTurnRequest["principal"], sessionId: string): Promise<void>;
+  /** Durable principal session path for layout ownership / isAvailable — not a rebuild source (#617 DK-4). */
+  resolveSessionFile(principal: RoleTurnRequest["principal"]): string;
+}>;

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/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-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

package/src/role-activation-flags.ts

@@ -0,0 +1,53 @@
+/**
+ * Middle-layer role activation → host flag map (#819 / ADR 0082).
+ * Sole envelope-assembly definition for activation flags across host families.
+ * Host adapters only deliver these flags (ACP/headless getFlag map; pi argv pairs).
+ */
+import type { RoleTurnRequest } from "./host-contracts.ts";
+import { packagedRoleInputFlag, packagedRolePhaseFlag } from "./packaged-role-registry.ts";
+
+/** Project closed RoleTurnActivation onto the shared host flag map. */
+export function projectActivationFlags(request: RoleTurnRequest): Map<string, boolean | string> {
+  const activation = request.activation;
+  const flags = new Map<string, boolean | string>([["ak-role", activation.role]]);
+  const inputFlag = packagedRoleInputFlag(activation.role);
+  const phaseFlag = packagedRolePhaseFlag(activation.role);
+  if ("phase" in activation && phaseFlag !== undefined) flags.set(phaseFlag, activation.phase);
+  if (inputFlag !== undefined) {
+    const path = "taskPath" in activation ? activation.taskPath
+      : "packetPath" in activation ? activation.packetPath
+        : "casePath" in activation ? activation.casePath
+          : "inputPath" in activation ? activation.inputPath
+            : "sourceRun" in activation ? activation.sourceRun
+              : undefined;
+    if (path !== undefined) flags.set(inputFlag, path);
+  }
+  if (activation.role === "fixer" && activation.prerequisitesPath !== undefined) {
+    flags.set("ak-fixer-prerequisites", activation.prerequisitesPath);
+  }
+  if (activation.role === "reviewer") {
+    flags.set("ak-review-base", activation.baseRevision);
+    flags.set("ak-review-authority-refs", JSON.stringify(activation.authorityRefs));
+    if (activation.ticketNumber !== undefined) {
+      flags.set("ak-review-ticket-number", String(activation.ticketNumber));
+    }
+  }
+  // countersign ticketNumber stays on activation/admission/invocation only —
+  // no private transport flag (inner-gate material path deleted in #632).
+  if (activation.role === "notary" && activation.ticketNumber !== undefined) {
+    flags.set("ak-notary-ticket-number", String(activation.ticketNumber));
+  }
+  if (activation.role === "gleaner-left") {
+    flags.set("ak-gleaner-left-base", activation.baseRevision);
+  }
+  if (activation.role === "collector") {
+    flags.set("ak-collector-repo", activation.repo);
+    // #676 D1: pr optional at admission; omit flag when role binds from materials.
+    if (activation.pr !== undefined) flags.set("ak-collector-pr", activation.pr);
+    if (activation.requestManifestPath !== undefined) {
+      flags.set("ak-collector-request-manifest", activation.requestManifestPath);
+    }
+    if (activation.waitMs !== undefined) flags.set("ak-collector-wait-ms", activation.waitMs);
+  }
+  return flags;
+}