@akagilnc/pi-workflow-roles 0.1.3826 → 0.1.3873

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

@@ -2,7 +2,18 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 
 import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
-import { renderAgentStartMaterials } from "../agent-start-materials.ts";
+import {
+  createSerializedRoleTurnHost,
+  driveExternalRoleTurnRounds,
+  raceAgainstHostAbort,
+} from "../external-host-turn-loop.ts";
+import { retainDiagnosticTail } from "../diagnostic-tail.ts";
+import { reportHostSessionEvent } from "../host-session-record.ts";
+import {
+  renderSystemPromptOverride,
+  type PreparedRoleTurn,
+  type SessionIdentityAuthority,
+} from "../prepared-role-turn.ts";
 import { acpModelId, type AcpHostDescription } from "./description.ts";
 
 /** ACP v1 surface used by the generic ACP adapter. Protocol details stay in this module. */
@@ -14,74 +25,10 @@ export interface AcpConnection {
   close(): Promise<void>;
 }
 
-/** 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 AcpPreparedTurn = 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 renderAcpSystemPromptOverride(authority: {
-  readonly body: string;
-  readonly materials: readonly unknown[];
-}): string {
-  return renderAgentStartMaterials(authority.body, authority.materials);
-}
-
-export type AcpSessionIdentityAuthority = 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;
-}>;
-
 export type AcpRoleTurnHostConfig = Readonly<{
-  sessionIdentity: AcpSessionIdentityAuthority;
+  sessionIdentity: SessionIdentityAuthority;
+  /** Seat-table host key (e.g. grok-build) for sitian host field. */
+  hostName: string;
   /** Whether a bound resume reuses the native session or mints a fresh one. */
   boundResume: AcpHostDescription["boundResume"];
   /**
@@ -91,7 +38,7 @@ export type AcpRoleTurnHostConfig = Readonly<{
    */
   modelPassing: AcpHostDescription["modelPassing"];
   connect(request: RoleTurnRequest): Promise<AcpConnection>;
-  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
+  prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
 }>;
 
 function failure(cause: "activation" | "session" | "output", name: string, code: string, details?: Readonly<Record<string, unknown>>): RoleTurnResult {
@@ -109,10 +56,6 @@ function failure(cause: "activation" | "session" | "output", name: string, code:
 
 type RpcReply = { readonly id?: unknown; readonly method?: unknown; readonly params?: unknown; readonly result?: unknown; readonly error?: unknown };
 
-function hostAbortedError(): Error & { readonly code: "host-aborted" } {
-  return Object.assign(new Error("ACP host aborted"), { code: "host-aborted" as const });
-}
-
 function acpError(code: string, message: string, cause?: unknown): Error & { readonly code: string } {
   return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
 }
@@ -132,6 +75,7 @@ export function connectAcpStdio(options: {
   let nextId = 0;
   let closed = false;
   let terminalError: Error | undefined;
+  // Rolling diagnostic tail only — not an unbounded transcript face (same class as headless).
   let stderr = "";
   const settleClosed = (error: Error): void => {
     if (closed) return;
@@ -148,7 +92,9 @@ export function connectAcpStdio(options: {
     child.stdin.end();
     child.kill("SIGTERM");
   };
-  child.stderr.setEncoding("utf8").on("data", (chunk: string) => { stderr += chunk; });
+  child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+    stderr = retainDiagnosticTail(stderr + chunk);
+  });
   child.on("error", (error) => settleClosed(acpError("acp-process-error", `ACP process error: ${error.message}`, error)));
   createInterface({ input: child.stdout }).on("line", (line) => {
     let message: RpcReply;
@@ -223,210 +169,179 @@ export function connectAcpStdio(options: {
   });
 }
 
-/**
- * Main-session ACP adapter. The injected composition callbacks are the shared
- * envelope boundary: this module owns ACP lifecycle, never role policy.
- */
+/** ACP last hop (#820): session open/load/close, prompt, MCP mount, capability/model. */
 export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHost {
-  let serial = Promise.resolve();
-  return {
-    executeTurn(request) {
-      const execution = serial.then(async (): Promise<RoleTurnResult> => {
-        const continuation = request.continuation;
-        const prepared = await config.prepare(request);
-        const systemPromptOverride = renderAcpSystemPromptOverride(prepared.systemPrompt);
-        let connection: AcpConnection | undefined;
-        let sessionId: string | undefined;
-        let accepted = false;
+  return createSerializedRoleTurnHost(async (request): Promise<RoleTurnResult> => {
+    const prepared = await config.prepare(request);
+    const systemPromptOverride = renderSystemPromptOverride(prepared.systemPrompt);
+    let connection: AcpConnection | undefined;
+    let sessionId: string | undefined;
+    let accepted = false;
+    try {
+      if (prepared.mcpServers.length === 0) {
+        return failure("activation", "UncontrolledAcpSession", "ak-config-missing");
+      }
+      connection = await config.connect(request);
+      // Live host-session records: ACP session/update → sitian sole entry (#811).
+      // One abort + one race helper + one outer projection — write failure ends
+      // any in-flight RPC as typed session infrastructure failure.
+      const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
+      const recordAbort = new AbortController();
+      let hostSessionRecordFailure: RoleTurnKnownFailure | undefined;
+      const hostSessionRecordResult = (): RoleTurnResult => ({
+        code: null,
+        stderr: "",
+        timedOut: false,
+        knownFailure: hostSessionRecordFailure!,
+      });
+      const noteHostSessionRecordFailure = (error: unknown): void => {
+        if (hostSessionRecordFailure !== undefined) return;
+        hostSessionRecordFailure = {
+          cause: "session",
+          identity: { name: "HostSessionRecordFailure", code: "host-session-record-failed" },
+          diagnostic: error instanceof Error ? error.message : String(error),
+        };
+        try { recordAbort.abort(); } catch { /* already aborted */ }
+      };
+      const rpc = (
+        method: string,
+        params: Readonly<Record<string, unknown>>,
+      ): Promise<Readonly<Record<string, unknown>>> =>
+        raceAgainstHostAbort(connection!.request(method, params), recordAbort.signal, "host-session-record-failed");
+
+      connection.onNotification?.((method, params) => {
+        if (method !== "session/update" || hostSessionRecordFailure !== undefined) return;
         try {
-          // AK injection proof is prepared MCP composition (envelope).
-          if (prepared.mcpServers.length === 0) {
-            return failure("activation", "UncontrolledAcpSession", "ak-config-missing");
-          }
-          connection = await config.connect(request);
-          const initialized = await connection.request("initialize", {
-            protocolVersion: 1,
-            clientCapabilities: {},
+          reportHostSessionEvent({
+            host: config.hostName,
+            cwd: request.cwd,
+            sessionParent,
+            source: "acp-host",
+            event: { method, params },
           });
-          const initializeMeta = initialized._meta as {
-            modelState?: { availableModels?: unknown };
-          } | undefined;
-          const modelState = initializeMeta?.modelState;
-          const availableModels = Array.isArray(modelState?.availableModels) ? modelState.availableModels : undefined;
-          if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) =>
-            typeof entry === "object" && entry !== null
-            && (entry as { modelId?: unknown }).modelId === acpModelId(config.modelPassing, request.model))) {
-            return failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
-              provider: request.model.provider,
-              model: request.model.model,
-            });
-          }
+        } catch (error) {
+          noteHostSessionRecordFailure(error);
+        }
+      });
 
-          // #617 DK-7 / #732: hand the projected prior-native session paths once,
-          // whichever record family they came from; the host reads the files itself.
-          const priorNativePaths =
-            continuation.kind === "resume"
-              ? request.hostTransition?.priorNativePaths
-              : undefined;
-          const loadConnection = connection;
-          // Shared session/new + session/load body (cwd/mcpServers/_meta).
-          const sessionBindParams = {
-            cwd: request.cwd,
-            mcpServers: prepared.mcpServers,
-            _meta: { systemPromptOverride, yoloMode: false },
-          };
-          const loadSession = async (bindSessionId: string): Promise<string> => {
-            const loaded = await loadConnection.request("session/load", {
-              sessionId: bindSessionId,
-              ...sessionBindParams,
-            });
-            return typeof loaded.sessionId === "string" && loaded.sessionId !== ""
-              ? loaded.sessionId
-              : bindSessionId;
-          };
-          if (continuation.kind === "resume" && config.boundResume === "session/load") {
-            // Same-host resume reuses the native ACP session via session/load.
-            const boundSessionId = await config.sessionIdentity.load(request.principal);
-            if (boundSessionId !== undefined && boundSessionId !== "") {
-              sessionId = await loadSession(boundSessionId);
-            }
-          }
-          if (sessionId === undefined) {
-            // Initial run, unbound resume (cross-host / lost binding), or a host
-            // whose bound resume is session/new: mint the session and bind it.
-            const session = await connection.request("session/new", sessionBindParams);
-            sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
-            if (sessionId === undefined || sessionId === "") {
-              return failure("session", "AcpSessionFailure", "session-id-missing");
-            }
-            await config.sessionIdentity.bind(request.principal, sessionId);
-          }
+      try {
+        const initialized = await rpc("initialize", {
+          protocolVersion: 1,
+          clientCapabilities: {},
+        });
+        const initializeMeta = initialized._meta as {
+          modelState?: { availableModels?: unknown };
+        } | undefined;
+        const availableModels = Array.isArray(initializeMeta?.modelState?.availableModels)
+          ? initializeMeta.modelState.availableModels
+          : undefined;
+        if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) =>
+          typeof entry === "object" && entry !== null
+          && (entry as { modelId?: unknown }).modelId === acpModelId(config.modelPassing, request.model))) {
+          return failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
+            provider: request.model.provider,
+            model: request.model.model,
+          });
+        }
 
-          // set_model hosts address the seat model by `provider:model` once the
-          // session exists; argv hosts never reach this RPC. Provider is the seat
-          // table value after owner host-alias projection (#778) — concatenated
-          // here, never dropped, never remapped in package code. set_model may
-          // rebuild the session agent and drop ACP-injected mcpServers, so re-bind
-          // via the same loadSession authority (return value is the live session id).
-          if (
-            config.modelPassing === "set_model"
-            && request.model !== undefined
-            && sessionId !== undefined
-          ) {
-            await connection.request("session/set_model", {
-              sessionId,
-              modelId: acpModelId(config.modelPassing, request.model),
-            });
-            sessionId = await loadSession(sessionId);
+        const sessionBindParams = {
+          cwd: request.cwd,
+          mcpServers: prepared.mcpServers,
+          _meta: { systemPromptOverride, yoloMode: false },
+        };
+        const loadSession = async (bindSessionId: string): Promise<string> => {
+          const loaded = await rpc("session/load", {
+            sessionId: bindSessionId,
+            ...sessionBindParams,
+          });
+          return typeof loaded.sessionId === "string" && loaded.sessionId !== ""
+            ? loaded.sessionId
+            : bindSessionId;
+        };
+        if (request.continuation.kind === "resume" && config.boundResume === "session/load") {
+          const boundSessionId = await config.sessionIdentity.load(request.principal);
+          if (boundSessionId !== undefined && boundSessionId !== "") {
+            sessionId = await loadSession(boundSessionId);
           }
+        }
+        if (sessionId === undefined) {
+          const session = await rpc("session/new", sessionBindParams);
+          sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
+          if (sessionId === undefined || sessionId === "") {
+            return failure("session", "AcpSessionFailure", "session-id-missing");
+          }
+          await config.sessionIdentity.bind(request.principal, sessionId);
+        }
 
-          let prompt =
-            priorNativePaths !== undefined && priorNativePaths.length > 0
-              ? `${prepared.prompt}\n${priorNativePaths.join("\n")}`
-              : prepared.prompt;
-          // Envelope infra abort and parent cancellation (#675 nested summons) are
-          // the same race face here: either one ends the ACP round and the finally
-          // block cancels + closes the child session.
-          const abortSignal =
-            request.signal === undefined
-              ? prepared.abortSignal
-              : prepared.abortSignal === undefined
-                ? request.signal
-                : AbortSignal.any([prepared.abortSignal, request.signal]);
-          const activeConnection = connection;
+        // set_model seat provider:model (#778); may rebuild agent — re-bind via loadSession.
+        if (config.modelPassing === "set_model" && request.model !== undefined && sessionId !== undefined) {
+          await rpc("session/set_model", {
+            sessionId,
+            modelId: acpModelId(config.modelPassing, request.model),
+          });
+          sessionId = await loadSession(sessionId);
+        }
 
-          /** Race ACP prompt against envelope abort so infra failInfrastructure cannot hang (#593). */
-          const promptOrAbort = async (
-            params: Readonly<Record<string, unknown>>,
-          ): Promise<Readonly<Record<string, unknown>>> => {
-            if (abortSignal?.aborted) {
-              // Prefer closeRound's typed failure over a bare abort race winner.
-              throw hostAbortedError();
-            }
-            const promptRequest = activeConnection.request("session/prompt", params);
-            if (abortSignal === undefined) return promptRequest;
-            return new Promise<Readonly<Record<string, unknown>>>((resolve, reject) => {
-              let settled = false;
-              const onAbort = (): void => {
-                if (settled) return;
-                settled = true;
-                promptRequest.catch(() => {});
-                reject(hostAbortedError());
-              };
-              abortSignal.addEventListener("abort", onAbort, { once: true });
-              promptRequest.then(
-                (value) => {
-                  if (settled) return;
-                  settled = true;
-                  abortSignal.removeEventListener("abort", onAbort);
-                  resolve(value);
-                },
-                (error) => {
-                  if (settled) return;
-                  settled = true;
-                  abortSignal.removeEventListener("abort", onAbort);
-                  reject(error);
-                },
-              );
-            });
-          };
-          for (let attempt = 0; attempt < 8; attempt += 1) {
+        const activeConnection = connection;
+        const activeSessionId = sessionId;
+        const turnResult = await driveExternalRoleTurnRounds(prepared, request, {
+          roundLimitName: "AcpRoundLimit",
+          currentSessionId: () => sessionId,
+          async runRound({ prompt, abortSignal }) {
+            if (hostSessionRecordFailure !== undefined) return { status: "terminal", result: hostSessionRecordResult() };
+            // Envelope infra abort, parent cancellation (#675), and host-session
+            // record abort (#811) share one race face for in-flight prompt.
+            const abortParts: AbortSignal[] = [recordAbort.signal];
+            if (abortSignal !== undefined) abortParts.push(abortSignal);
+            const combinedAbort = AbortSignal.any(abortParts);
             let result: Readonly<Record<string, unknown>>;
             try {
-              result = await promptOrAbort({
-                sessionId,
-                prompt: [{ type: "text", text: prompt }],
-              });
+              result = await raceAgainstHostAbort(
+                activeConnection.request("session/prompt", {
+                  sessionId: activeSessionId,
+                  prompt: [{ type: "text", text: prompt }],
+                }),
+                combinedAbort,
+                "ACP host aborted",
+              );
             } catch (error) {
-              // Envelope abort (typed infra declaration): closeRound owns the failure record.
-              if (
-                typeof error === "object"
-                && error !== null
-                && (error as { code?: unknown }).code === "host-aborted"
-              ) {
-                const closure = await prepared.closeRound();
-                if ("failure" in closure) {
-                  return { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
-                }
-                return failure("session", "HostAborted", "host-aborted", { sessionId });
+              if (hostSessionRecordFailure !== undefined) {
+                return { status: "terminal", result: hostSessionRecordResult() };
               }
               throw error;
             }
             if (result.stopReason === "refusal") {
-              return failure("output", "AcpRefusal", "refusal", { sessionId });
-            }
-            // session/prompt resolution is the sole typed round boundary before seal
-            // when the turn ends without host abort; abort path closes above.
-            const closure = await prepared.closeRound();
-            if (closure.accepted) {
-              // Wait for ACP's typed close acknowledgement before tearing down the
-              // process; Stop hooks and fire-and-forget cancellation are not closure.
-              await connection.request("session/close", { sessionId });
-              accepted = true;
-              return { code: 0, stderr: "", timedOut: false };
-            }
-            if ("failure" in closure) {
-              return { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
-            }
-            // Shared envelope already owns the officer/correctable text (#813).
-            prompt = closure.retry.message;
-          }
-          return failure("output", "AcpRoundLimit", "round-retry-limit", { sessionId });
-        } finally {
-          if (connection !== undefined) {
-            if (sessionId !== undefined && !accepted) {
-              try { connection.notify("session/cancel", { sessionId }); }
-              catch { /* Preserve the original turn result or failure. */ }
+              return {
+                status: "terminal",
+                result: failure("output", "AcpRefusal", "refusal", { sessionId }),
+              };
             }
-            try { await connection.close(); }
-            catch { /* Preserve the original turn result or failure. */ }
-          }
-          try { await prepared.dispose?.(); }
-          catch { /* Preserve the original turn result or failure. */ }
+            return { status: "delivered" };
+          },
+          async afterAccepted() {
+            await rpc("session/close", { sessionId: activeSessionId });
+            accepted = true;
+          },
+        });
+        if (hostSessionRecordFailure !== undefined) return hostSessionRecordResult();
+        return turnResult;
+      } catch (error) {
+        // recordAbort races setup RPCs via raceAgainstHostAbort (host-aborted code);
+        // noteHostSessionRecordFailure always sets the typed failure before aborting.
+        if (hostSessionRecordFailure !== undefined) return hostSessionRecordResult();
+        throw error;
+      }
+    } finally {
+      if (connection !== undefined) {
+        if (sessionId !== undefined && !accepted) {
+          try { connection.notify("session/cancel", { sessionId }); }
+          catch { /* keep turn result */ }
         }
-      });
-      serial = execution.then(() => undefined, () => undefined);
-      return execution;
-    },
-  };
+        try { await connection.close(); }
+        catch { /* keep turn result */ }
+      }
+      try { await prepared.dispose?.(); }
+      catch { /* keep turn result */ }
+    }
+  });
 }

package/src/canonical-skill-binding.ts

@@ -25,7 +25,10 @@ export type CanonicalSkillEvidence<Name extends CanonicalSkillName = CanonicalSk
 export type CanonicalSkillBinding<Name extends CanonicalSkillName = CanonicalSkillName> = Readonly<{
   name: Name;
   snapshot: CanonicalSkillSnapshot;
-  invocation(originalRequest: string): string;
+  /**
+   * Accept host expansion evidence when name/location/content match the binding
+   * and userMessage equals the captured original request (ADR 0032).
+   */
   captureExpansion(
     evidence: HostSkillExpansionEvidence | undefined,
     originalRequest: string,
@@ -100,9 +103,6 @@ export async function loadCanonicalSkillBinding(
   const binding: CanonicalSkillBinding<typeof name> = {
     name,
     snapshot,
-    invocation(originalRequest) {
-      return `/skill:${name} ${originalRequest}`;
-    },
     captureExpansion(evidence, originalRequest) {
       return captureCanonicalSkillExpansion(
         name,

package/src/diagnostic-tail.ts

@@ -0,0 +1,18 @@
+/**
+ * Bound diagnostic text: rolling tail only, not a dossier/transcript face.
+ * One authority for host stderr retention (headless + ACP).
+ */
+
+/** Fixed cap for retained diagnostic tails. */
+export const DIAGNOSTIC_TAIL_CAP = 16 * 1024;
+
+const CLIP_MARK = "…[stderr clipped]\n";
+
+/**
+ * Retain at most DIAGNOSTIC_TAIL_CAP characters, keeping the newest bytes
+ * when over budget. Clip mark is included inside the fixed cap.
+ */
+export function retainDiagnosticTail(text: string): string {
+  if (text.length <= DIAGNOSTIC_TAIL_CAP) return text;
+  return CLIP_MARK + text.slice(text.length - (DIAGNOSTIC_TAIL_CAP - CLIP_MARK.length));
+}

package/src/engine-detour-tool.ts

@@ -11,8 +11,8 @@ import type { HostContext, HostToolDefinition, HostToolResult, RoleHost } from "
 import {
   ENGINE_DETOUR_TOOL_NAME,
   engineDetourFailureDiagnostic,
-  engineNameFromEnv,
   isEngineDetourFailure,
+  resolveEngineName,
   runEngineDetourOnce,
 } from "./engine-detour.ts";
 
@@ -125,14 +125,15 @@ export function createEngineDetourToolDefinition(input: {
 }
 
 /**
- * Register the engine-generic detour tool once for this process when any role has
- * an engine activation signal. Returns whether registration occurred.
+ * Register the engine-generic detour tool once when any role has an engine
+ * activation signal. Signal is request-scoped via RoleHost flag, with pi
+ * child-process env as fallback (resolveEngineName). Returns whether registration occurred.
  */
 export function registerEngineDetourTool(
   roleHost: RoleHost,
   hostActions: EngineDetourHostActions,
 ): boolean {
-  const engineName = engineNameFromEnv();
+  const engineName = resolveEngineName((name) => roleHost.getFlag(name));
   if (engineName === undefined) {
     return false;
   }

package/src/engine-detour.ts

@@ -16,24 +16,42 @@ export const ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour" as const;
 /** Env presence/name signal injected by public role runs (registration gate only). */
 export const AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE" as const;
 
+/**
+ * Request-scoped engine flag on RoleHost (#818 P1).
+ * Envelope projects RoleTurnRequest.engine here so concurrent in-process hosts
+ * do not share process.env. Empty string = explicitly no engine (blocks ambient).
+ * Pi never sets this flag — resolve falls through to child-process env.
+ */
+export const ENGINE_FLAG_NAME = "ak-engine" as const;
+
 /**
  * Argv placeholder replaced by a seam-owned temp prompt file path when
  * `stagedPrompt` is set. Exactly one argv entry must equal this token.
  */
 export const ENGINE_DETOUR_STAGED_PROMPT_TOKEN = "<<ak-engine-staged-prompt>>" as const;
 
+/** Non-empty trimmed engine name, else undefined. */
+export function normalizeEngineName(engine: string | undefined): string | undefined {
+  if (engine === undefined) return undefined;
+  const trimmed = engine.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
 /**
- * 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.
+ * Sole AK_ROLE_ENGINE write seam (#391 E2 / #818).
+ * Child-process env only (pi adapter). Delete ambient first. Child-env objects
+ * keep an own-key undefined mask so a later process.env re-merge cannot revive
+ * ambient; process.env itself only deletes (Node stringifies undefined assignments).
  */
 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 {
+  const normalized = normalizeEngineName(engine);
+  if (normalized !== undefined) {
+    childEnv[AK_ROLE_ENGINE_ENV] = normalized;
+  } else if (childEnv !== process.env) {
     childEnv[AK_ROLE_ENGINE_ENV] = undefined;
   }
 }
@@ -239,8 +257,25 @@ export function engineDetourFailureDiagnostic(result: {
 
 /** Non-empty trimmed engine name from process.env, else undefined. */
 export function engineNameFromEnv(): string | undefined {
-  const raw = process.env[AK_ROLE_ENGINE_ENV];
-  if (typeof raw !== "string") return undefined;
-  const trimmed = raw.trim();
-  return trimmed === "" ? undefined : trimmed;
+  return normalizeEngineName(
+    typeof process.env[AK_ROLE_ENGINE_ENV] === "string"
+      ? process.env[AK_ROLE_ENGINE_ENV]
+      : undefined,
+  );
+}
+
+/**
+ * One activation-signal resolver (#818 P1 / ADR 0069 one gate).
+ * Request-scoped RoleHost flag wins when present (envelope always projects it,
+ * including "" for no-engine so ambient env cannot arm). Flag absent → pi
+ * child-process env via engineNameFromEnv.
+ */
+export function resolveEngineName(
+  getFlag?: (name: string) => boolean | string | undefined,
+): string | undefined {
+  if (getFlag !== undefined) {
+    const flag = getFlag(ENGINE_FLAG_NAME);
+    if (typeof flag === "string") return normalizeEngineName(flag);
+  }
+  return engineNameFromEnv();
 }