@akagilnc/pi-workflow-roles 0.1.3556 → 0.1.3565

package/dist/public-cli/main.js

@@ -15385,6 +15385,48 @@ var init_institutional_resolution = __esm({
   }
 });
 
+// src/host-descriptions.ts
+function lookupHostDescription(host) {
+  return Object.hasOwn(HOST_DESCRIPTIONS, host) ? HOST_DESCRIPTIONS[host] : void 0;
+}
+function packagedExternalHostNames() {
+  return Object.keys(HOST_DESCRIPTIONS);
+}
+function assertRegisteredHostName(host) {
+  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostDescription(host) !== void 0) {
+    return host;
+  }
+  throw new Error(`unregistered host: ${host}`);
+}
+var PRIVATE_COMPAT_ENV, DEFAULT_ROLE_TURN_HOST, HOST_DESCRIPTIONS;
+var init_host_descriptions = __esm({
+  "src/host-descriptions.ts"() {
+    "use strict";
+    PRIVATE_COMPAT_ENV = Object.fromEntries(
+      ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) => ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) => [`GROK_${vendor}_${kind}_ENABLED`, "false"]))
+    );
+    DEFAULT_ROLE_TURN_HOST = "pi";
+    HOST_DESCRIPTIONS = Object.freeze({
+      /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+      "grok-build": Object.freeze({
+        binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
+        argv: Object.freeze({
+          prefix: Object.freeze(["agent"]),
+          suffix: Object.freeze(["stdio"]),
+          modelFlag: "--model"
+        }),
+        boundResume: "session/load",
+        sessionBindingFile: "grok-acp-session.json",
+        childEnv: Object.freeze({
+          ...PRIVATE_COMPAT_ENV,
+          GROK_MEMORY: "0",
+          GROK_SUBAGENTS: "0"
+        })
+      })
+    });
+  }
+});
+
 // src/public-cli/config.ts
 import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname4, join as join6 } from "node:path";
@@ -15468,7 +15510,8 @@ function setPersistentSeatHost(config, seat, host) {
     }
     return { ...config, seats: { ...config.seats, [seat]: rest } };
   }
-  return { ...config, seats: { ...config.seats, [seat]: { ...previous, host } } };
+  const registered = assertRegisteredHostName(host);
+  return { ...config, seats: { ...config.seats, [seat]: { ...previous, host: registered } } };
 }
 function setPersistentSeatEngine(config, seat, engine) {
   const previous = config.seats[seat];
@@ -15513,14 +15556,25 @@ function setAutoResumeLimit(config, limit) {
 function validatePublicCliConfigAxes(config, _packageRoot) {
   for (const seat of Object.keys(config.seats)) {
     const row = config.seats[seat];
-    if (row?.engine === void 0) continue;
-    try {
-      assertLegalEngineName(row.engine);
-    } catch (error) {
-      throw new Error(
-        `config seat ${seat} engine is illegal: ${row.engine}`,
-        { cause: error }
-      );
+    if (row?.engine !== void 0) {
+      try {
+        assertLegalEngineName(row.engine);
+      } catch (error) {
+        throw new Error(
+          `config seat ${seat} engine is illegal: ${row.engine}`,
+          { cause: error }
+        );
+      }
+    }
+    if (row?.host !== void 0) {
+      try {
+        assertRegisteredHostName(row.host);
+      } catch (error) {
+        throw new Error(
+          `config seat ${seat} host is unregistered: ${row.host}`,
+          { cause: error }
+        );
+      }
     }
   }
 }
@@ -15667,7 +15721,7 @@ function attachHostAxis(seat, config, invocation) {
   if (invocation?.host !== void 0) return { ...seat, host: invocation.host, hostSource: "invocation" };
   const persistent = config.seats[seat.seat]?.host;
   if (persistent !== void 0) return { ...seat, host: persistent, hostSource: "persistent" };
-  return { ...seat, host: "pi", hostSource: "default" };
+  return { ...seat, host: DEFAULT_ROLE_TURN_HOST, hostSource: "default" };
 }
 function attachEngineAxis(seat, config, invocation) {
   if (!isPublicCallableRole(seat.seat)) {
@@ -15788,6 +15842,7 @@ var GATE_OFFICER_SEATS;
 var init_config2 = __esm({
   "src/public-cli/config.ts"() {
     "use strict";
+    init_host_descriptions();
     init_engine_material();
     init_institutional_resolution();
     init_registry2();
@@ -15817,21 +15872,27 @@ var init_cli_errors = __esm({
   }
 });
 
-// src/public-cli/load-production-grok-host.ts
+// src/public-cli/load-production-acp-host.ts
 import { existsSync as existsSync3 } from "node:fs";
 import { join as join7 } from "node:path";
 import { pathToFileURL } from "node:url";
-async function loadProductionGrokHostFactory(packageRoot2) {
-  const built = join7(packageRoot2, "dist/grok/production-host.js");
-  const source = join7(packageRoot2, "src/grok/production-host.ts");
+async function loadProductionAcpHostFactory(packageRoot2, host) {
+  const description = lookupHostDescription(host);
+  if (description === void 0) {
+    throw new Error(`unregistered host: ${host}`);
+  }
+  const built = join7(packageRoot2, "dist/acp-host/production-host.js");
+  const source = join7(packageRoot2, "src/acp-host/production-host.ts");
   const target = existsSync3(built) ? built : source;
   const href = pathToFileURL(target).href;
   const mod = await import(href);
-  return mod.createProductionGrokRoleTurnHost;
+  const create = mod.createProductionAcpRoleTurnHost;
+  return (options) => create({ ...options, description });
 }
-var init_load_production_grok_host = __esm({
-  "src/public-cli/load-production-grok-host.ts"() {
+var init_load_production_acp_host = __esm({
+  "src/public-cli/load-production-acp-host.ts"() {
     "use strict";
+    init_host_descriptions();
   }
 });
 
@@ -16548,7 +16609,7 @@ function createPiRoleTurnHost(config) {
   return {
     async executeTurn(request) {
       let turnRequest = request;
-      const paths = request.hostTransition?.previousHost === "grok-build" ? request.hostTransition.priorNativePaths : void 0;
+      const paths = request.hostTransition?.priorNativeKind === "sitian" ? request.hostTransition.priorNativePaths : void 0;
       if (request.continuation.kind === "resume" && paths !== void 0 && paths.length > 0) {
         turnRequest = {
           ...request,
@@ -27915,9 +27976,6 @@ var init_turn_request = __esm({
 // src/host-transition-prior-native.ts
 import { access as access2, readdir as readdir6 } from "node:fs/promises";
 import { dirname as dirname11, join as join26 } from "node:path";
-function isKnownRoleTurnHost(value) {
-  return KNOWN_ROLE_TURN_HOSTS.includes(value);
-}
 function isEnoent2(error) {
   return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
@@ -27955,27 +28013,20 @@ async function listSitianRecordPaths(sessionParent) {
 }
 async function projectHostTransitionPriorNative(input) {
   if (input.previousHost === input.liveHost) return void 0;
-  if (!isKnownRoleTurnHost(input.previousHost) || !isKnownRoleTurnHost(input.liveHost)) {
-    return void 0;
-  }
   if (input.previousHost === "pi") {
-    const paths2 = await listPiNativeRecordPaths(input.piSessionFile);
     return {
-      previousHost: "pi",
-      priorNativePaths: paths2
+      priorNativeKind: "pi-native",
+      priorNativePaths: await listPiNativeRecordPaths(input.piSessionFile)
     };
   }
-  const paths = await listSitianRecordPaths(input.piSessionFile);
   return {
-    previousHost: "grok-build",
-    priorNativePaths: paths
+    priorNativeKind: "sitian",
+    priorNativePaths: await listSitianRecordPaths(input.piSessionFile)
   };
 }
-var KNOWN_ROLE_TURN_HOSTS;
 var init_host_transition_prior_native = __esm({
   "src/host-transition-prior-native.ts"() {
     "use strict";
-    KNOWN_ROLE_TURN_HOSTS = ["pi", "grok-build"];
   }
 });
 
@@ -33012,15 +33063,15 @@ function resolveRoleTurnHost(env, options) {
   });
   const adapters = env.hostAdapters ?? [
     { name: "pi", create: () => ({ ok: true, host: piHost }) },
-    {
-      name: "grok-build",
+    ...packagedExternalHostNames().map((name) => ({
+      name,
       create: () => {
         let hostPromise;
         return {
           ok: true,
           host: {
             executeTurn: async (request) => {
-              hostPromise ??= loadProductionGrokHostFactory(env.packageRoot).then(
+              hostPromise ??= loadProductionAcpHostFactory(env.packageRoot, name).then(
                 (create) => create({
                   packageRoot: env.packageRoot,
                   principalAuthority: options.principalAuthority
@@ -33031,7 +33082,7 @@ function resolveRoleTurnHost(env, options) {
           }
         };
       }
-    }
+    }))
   ];
   const hostName = options.seat.host;
   const adapter = adapters.find((candidate) => candidate.name === hostName);
@@ -33961,7 +34012,8 @@ var init_cli = __esm({
     init_config2();
     init_registry2();
     init_cli_errors();
-    init_load_production_grok_host();
+    init_host_descriptions();
+    init_load_production_acp_host();
     init_role_turn_host();
     init_invocation();
     init_option_definitions();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.3556",
+  "version": "0.1.3565",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/build-package.mjs

@@ -88,16 +88,16 @@ export async function buildPublicAkRoleBin(
 }
 
 /**
- * Deferred grok-build production host artifact. Loaded only when the composition
- * root selects grok-build — keeps role-runtime / peer edges out of the public bin.
- * packages:"external" so optional peers resolve from the install tree at selection.
+ * Deferred generic ACP production host artifact. Loaded only when the composition
+ * root selects an external host row — keeps role-runtime / peer edges out of the
+ * public bin. packages:"external" so optional peers resolve at selection.
  */
-export async function buildGrokProductionHost(
-  outfile = "dist/grok/production-host.js",
+export async function buildAcpProductionHost(
+  outfile = "dist/acp-host/production-host.js",
 ) {
   await mkdir(dirname(outfile), { recursive: true });
   await build({
-    entryPoints: ["src/grok/production-host.ts"],
+    entryPoints: ["src/acp-host/production-host.ts"],
     outfile,
     format: "esm",
     platform: "node",
@@ -108,7 +108,7 @@ export async function buildGrokProductionHost(
   });
   // role-envelope resolves ./mcp-relay.mjs from import.meta.url — keep it beside the bundle.
   await copyFile(
-    resolve("src/grok/mcp-relay.mjs"),
+    resolve("src/acp-host/mcp-relay.mjs"),
     join(dirname(outfile), "mcp-relay.mjs"),
   );
 }
@@ -137,7 +137,7 @@ export async function buildPackageArtifacts() {
     );
   }
   await buildPublicAkRoleBin();
-  await buildGrokProductionHost();
+  await buildAcpProductionHost();
 }
 
 const isMain =

package/src/acp-host/description.ts

@@ -0,0 +1,43 @@
+/**
+ * One ACP host description. Every host-specific value the generic ACP adapter
+ * needs — binary location, argv shape, resume verb, binding filename, child env
+ * — is data here; the lifecycle in role-turn-host.ts stays one copy (#732).
+ */
+import { join } from "node:path";
+
+export type AcpHostDescription = Readonly<{
+  /** Binary path segments relative to the operator home. */
+  binaryFromHome: readonly string[];
+  argv: Readonly<{
+    prefix: readonly string[];
+    suffix: readonly string[];
+    modelFlag?: string;
+    thinkingFlag?: string;
+  }>;
+  /** Which verb a bound resume uses; "session/new" hosts always mint + bind. */
+  boundResume: "session/load" | "session/new";
+  /** Durable ACP binding filename written beside the session principal. */
+  sessionBindingFile: string;
+  childEnv: Readonly<Record<string, string>>;
+}>;
+
+/** Absolute agent binary for one operator home. */
+export function resolveAcpBinary(description: AcpHostDescription, operatorHome: string): string {
+  return join(operatorHome, ...description.binaryFromHome);
+}
+
+/** Stdio argv: prefix, optional model/thinking flag pairs, suffix. */
+export function acpStdioArgs(
+  description: AcpHostDescription,
+  model?: { readonly model?: string; readonly thinking?: string },
+): string[] {
+  const { prefix, suffix, modelFlag, thinkingFlag } = description.argv;
+  const pair = (flag: string | undefined, value: string | undefined): string[] =>
+    flag === undefined || value === undefined ? [] : [flag, value];
+  return [
+    ...prefix,
+    ...pair(modelFlag, model?.model),
+    ...pair(thinkingFlag, model?.thinking),
+    ...suffix,
+  ];
+}

package/src/{grok → acp-host}/mcp-relay.mjs

@@ -2,9 +2,9 @@
 import { connect } from "node:net";
 import { createInterface } from "node:readline";
 
-const socketPath = process.env.AK_GROK_MCP_SOCKET;
-const token = process.env.AK_GROK_MCP_TOKEN;
-if (!socketPath || !token) throw new Error("AK Grok MCP relay identity is missing");
+const socketPath = process.env.AK_ACP_MCP_SOCKET;
+const token = process.env.AK_ACP_MCP_TOKEN;
+if (!socketPath || !token) throw new Error("AK ACP MCP relay identity is missing");
 
 const upstream = connect(socketPath);
 const waiters = new Map();
@@ -45,7 +45,7 @@ upstream.on("error", (error) => settle(error));
 upstream.on("close", () => {
   // Shutdown may already be requested (stdin EOF) while an RPC is still
   // in flight. Outstanding waiters must still settle, or drain never ends.
-  if (!exiting) settle(new Error("AK Grok MCP upstream closed"));
+  if (!exiting) settle(new Error("AK ACP MCP upstream closed"));
   maybeExit();
 });
 createInterface({ input: upstream }).on("line", (line) => {
@@ -56,7 +56,7 @@ createInterface({ input: upstream }).on("line", (line) => {
   if (waiter === undefined) return;
   waiters.delete(message.id);
   if (message.error !== undefined) {
-    const error = new Error(typeof message.error.message === "string" ? message.error.message : "AK Grok MCP relay failure");
+    const error = new Error(typeof message.error.message === "string" ? message.error.message : "AK ACP MCP relay failure");
     error.code = message.error.code;
     error.cause = message.error;
     waiter.reject(error);

package/src/{grok → acp-host}/production-host.ts

@@ -1,13 +1,12 @@
 /**
- * Production composition for the grok-build RoleTurnHost adapter (#580 / #522 / #717).
- * Owns injectables around the S6 true adapter; does not alter S6 adapter behavior.
+ * Production composition for the generic ACP RoleTurnHost adapter (#732).
+ * Owns injectables around the S6 true adapter; does not alter adapter behavior.
  *
- * Grok CLI uses the operator home (`~/.grok`) and credentials in place. The
- * factory does not create a run-scoped grok home, does not rewrite HOME, and
- * does not copy or scrub auth.json. Sititian records on the run are the dossier.
+ * The agent runs against the operator home and its credentials in place. The
+ * factory does not create a run-scoped agent home, does not rewrite HOME, and
+ * does not copy or scrub credentials. Sitian records on the run are the dossier.
  */
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { loadCanonicalSkillBinding as loadHomeCanonicalSkillBinding } from "../canonical-skill-binding.ts";
@@ -25,35 +24,23 @@ import { createPerDispatchReviewerAgent } from "../reviewer-agent.ts";
 import { formatNavigatorRoleHelp, type RoleRuntimeDependencies } from "../role-runtime.ts";
 import { createReviewerPinnedGitReader } from "../reviewer-pinned-git.ts";
 import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../session-opening-materials.ts";
-import { createComposedGrokRoleTurnHost } from "./role-envelope.ts";
-import {
-  connectGrokAcpStdio,
-  controlledGrokChildEnv,
-} from "./role-turn-host.ts";
-import { createGrokSessionIdentityAuthority } from "./session-identity.ts";
+import { acpStdioArgs, resolveAcpBinary, type AcpHostDescription } from "./description.ts";
+import { createComposedAcpRoleTurnHost } from "./role-envelope.ts";
+import { connectAcpStdio } from "./role-turn-host.ts";
+import { createAcpSessionIdentityAuthority } from "./session-identity.ts";
 
-export type ProductionGrokHostOptions = Readonly<{
+export type ProductionAcpHostOptions = Readonly<{
   packageRoot: string;
   principalAuthority: DurablePrincipalAuthority;
+  description: AcpHostDescription;
 }>;
 
-function resolveGrokBinary(operatorHome: string): string {
-  return join(operatorHome, ".grok", "bin", "grok");
-}
-
-function childEnv(packageRoot: string): NodeJS.ProcessEnv {
-  return {
-    ...controlledGrokChildEnv(process.env),
-    AK_PACKAGE_ROOT: packageRoot,
-  };
-}
-
 const navigatorRoutePlaybookPath = fileURLToPath(
   new URL("../../resources/navigator-route-playbook.md", import.meta.url),
 );
 
-/** Host-neutral packaged role runtime deps for the Grok parent-process envelope. */
-export function createGrokRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
+/** Host-neutral packaged role runtime deps for the ACP parent-process envelope. */
+export function createAcpRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
   const judgeAuditor = createPiJudgeAuditor();
   const doctorAuditor = createPiDoctorAuditor();
   const reviewerAgent = createPerDispatchReviewerAgent({ packageRoot });
@@ -119,22 +106,28 @@ export function createGrokRoleRuntimeDependencies(packageRoot: string): RoleRunt
 }
 
 /**
- * Assemble the production grok-build RoleTurnHost from the S6 true adapter.
- * Grok subprocesses inherit the operator home; the run directory is sitian-only.
+ * Assemble a production ACP RoleTurnHost from the S6 true adapter for one host
+ * description. Agent subprocesses inherit the operator home; the run directory
+ * is sitian-only.
  */
-export function createProductionGrokRoleTurnHost(options: ProductionGrokHostOptions): RoleTurnHost {
-  const { packageRoot, principalAuthority } = options;
-  const env = childEnv(packageRoot);
+export function createProductionAcpRoleTurnHost(options: ProductionAcpHostOptions): RoleTurnHost {
+  const { packageRoot, principalAuthority, description } = options;
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...description.childEnv,
+    AK_PACKAGE_ROOT: packageRoot,
+  };
 
-  return createComposedGrokRoleTurnHost({
-    sessionIdentity: createGrokSessionIdentityAuthority(principalAuthority),
-    roleRuntimeDependencies: createGrokRoleRuntimeDependencies(packageRoot),
+  return createComposedAcpRoleTurnHost({
+    sessionIdentity: createAcpSessionIdentityAuthority(principalAuthority, description.sessionBindingFile),
+    boundResume: description.boundResume,
+    roleRuntimeDependencies: createAcpRoleRuntimeDependencies(packageRoot),
     async connect(request) {
-      return connectGrokAcpStdio({
-        binary: resolveGrokBinary(request.home),
+      return connectAcpStdio({
+        binary: resolveAcpBinary(description, request.home),
+        args: acpStdioArgs(description, request.model),
         cwd: request.cwd,
         env,
-        ...(request.model === undefined ? {} : { model: request.model.model }),
       });
     },
   });

package/src/{grok → acp-host}/role-envelope.ts

@@ -22,9 +22,9 @@ import {
   type RoleRuntimeDependencies,
 } from "../role-runtime.ts";
 import {
-  createGrokRoleTurnHost,
-  type GrokPreparedTurn,
-  type GrokRoleTurnHostConfig,
+  createAcpRoleTurnHost,
+  type AcpPreparedTurn,
+  type AcpRoleTurnHostConfig,
 } from "./role-turn-host.ts";
 import {
   GatekeeperDecisionError,
@@ -51,7 +51,7 @@ export function parseCanonicalSkillInvocation(prompt: string): { readonly name:
 }
 
 /** Build host-side Skill expansion evidence from pre-read RoleTurnRequest.methods. */
-export function buildGrokSkillExpansion(
+export function buildAcpSkillExpansion(
   methodSkills: ReadonlyMap<string, { readonly path: string; readonly body: string }>,
   prompt: string,
 ): HostSkillExpansionEvidence | undefined {
@@ -67,7 +67,7 @@ export function buildGrokSkillExpansion(
   });
 }
 
-export function projectGrokActivationFlags(request: RoleTurnRequest): Map<string, boolean | string> {
+export function projectAcpActivationFlags(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);
@@ -114,25 +114,25 @@ async function listen(server: Server, path: string): Promise<void> {
  * Build one AK-owned MCP projection from the shared eight-seat envelope.
  * The child process is a protocol relay only; all tools execute in this process.
  */
-export function createComposedGrokRoleTurnHost(
-  config: Omit<GrokRoleTurnHostConfig, "prepare"> & {
+export function createComposedAcpRoleTurnHost(
+  config: Omit<AcpRoleTurnHostConfig, "prepare"> & {
     readonly roleRuntimeDependencies: RoleRuntimeDependencies;
     readonly socketPath?: (request: RoleTurnRequest) => string;
   },
 ) {
-  return createGrokRoleTurnHost({
+  return createAcpRoleTurnHost({
     ...config,
-    prepare: (request) => prepareGrokRoleEnvelope({
+    prepare: (request) => prepareAcpRoleEnvelope({
       request,
       dependencies: config.roleRuntimeDependencies,
       // Same durable-principal path settlement uses for isAvailable (#617 DK-4 layout).
       sessionFile: config.sessionIdentity.resolveSessionFile(request.principal),
-      socketPath: config.socketPath?.(request) ?? `/tmp/ak-grok-mcp-${randomUUID()}.sock`,
+      socketPath: config.socketPath?.(request) ?? `/tmp/ak-acp-mcp-${randomUUID()}.sock`,
     }),
   });
 }
 
-export async function prepareGrokRoleEnvelope(options: {
+export async function prepareAcpRoleEnvelope(options: {
   readonly request: RoleTurnRequest;
   readonly dependencies: RoleRuntimeDependencies;
   readonly socketPath: string;
@@ -142,9 +142,9 @@ export async function prepareGrokRoleEnvelope(options: {
    * isAvailable and envelope mint the same file. Tests may omit → runDirectory default.
    */
   readonly sessionFile?: string;
-}): Promise<GrokPreparedTurn> {
+}): Promise<AcpPreparedTurn> {
   const { request } = options;
-  const flags = projectGrokActivationFlags(request);
+  const flags = projectAcpActivationFlags(request);
   const tools = new Map<string, HostToolDefinition>();
   const handlers = new Map<string, Handler[]>();
   const calls: Array<{ toolCallId: string; toolName: string }> = [];
@@ -169,7 +169,7 @@ export async function prepareGrokRoleEnvelope(options: {
   }
 
   // Durable principal file for isAvailable / resumable settlement (public-cli).
-  // #617 DK-4: header layout only — never Grok conversation/tool writeback into Pi JSONL.
+  // #617 DK-4: header layout only — never host conversation/tool writeback into Pi JSONL.
   let sessionFile = options.sessionFile ?? join(request.runDirectory, "session", "session.jsonl");
   await mkdir(dirname(sessionFile), { recursive: true });
   if (request.continuation.kind !== "resume") {
@@ -235,16 +235,16 @@ export async function prepareGrokRoleEnvelope(options: {
     deliverSubmissionRejection(value) { rejection = value; },
     capabilities: {
       skillExpansion(prompt): HostSkillExpansionEvidence | undefined {
-        return buildGrokSkillExpansion(methodSkills, prompt);
+        return buildAcpSkillExpansion(methodSkills, prompt);
       },
     },
     registerFlag(name, definition) { if (!flags.has(name) && definition.default !== undefined) flags.set(name, definition.default); },
     getFlag(name) { return flags.get(name); },
     registerTool(tool) { tools.set(tool.name, tool); },
-    // The real AK-owned surface only; Grok's builtin surface is host-side and
+    // The real AK-owned surface only; the host builtin surface is host-side and
     // observable after session/new, never echoed back into role-requested names.
     getAllTools() { return [...tools.keys()].map((name) => ({ name })); },
-    // Grok receives tool choice as role guidance; every tool registered for the
+    // The host receives tool choice as role guidance; every tool registered for the
     // seat remains reachable through MCP.
     setActiveTools(names) { preferredTools = [...names]; },
     getActiveTools() { return [...preferredTools]; },
@@ -580,13 +580,13 @@ export async function prepareGrokRoleEnvelope(options: {
     }
     if (cleanupFailures.length === 1) throw cleanupFailures[0];
     if (cleanupFailures.length > 1) {
-      throw new AggregateError(cleanupFailures, "Grok envelope dispose cleanup failures", {
+      throw new AggregateError(cleanupFailures, "ACP envelope dispose cleanup failures", {
         cause: cleanupFailures[0],
       });
     }
   };
 
-  const closeRound: GrokPreparedTurn["closeRound"] = async () => {
+  const closeRound: AcpPreparedTurn["closeRound"] = async () => {
     // Typed round boundary: hand the complete call list to the shared ledger once.
     if (calls.length > 0) {
       const roundCalls = [...calls];
@@ -606,7 +606,7 @@ export async function prepareGrokRoleEnvelope(options: {
     }
     if (closure !== undefined) {
       // Pi flushes navigator attendance on agent_settled; session/prompt
-      // resolution is grok-build's equivalent round boundary.
+      // resolution is the ACP host equivalent round boundary.
       await emit("agent_settled", {});
       return { accepted: true as const };
     }
@@ -674,8 +674,8 @@ export async function prepareGrokRoleEnvelope(options: {
         command: process.execPath,
         args: [relay],
         env: [
-          { name: "AK_GROK_MCP_SOCKET", value: options.socketPath },
-          { name: "AK_GROK_MCP_TOKEN", value: token },
+          { name: "AK_ACP_MCP_SOCKET", value: options.socketPath },
+          { name: "AK_ACP_MCP_TOKEN", value: token },
         ],
       }],
       systemPrompt: { body: systemPromptBody, materials: readingMaterials },
@@ -693,7 +693,7 @@ export async function prepareGrokRoleEnvelope(options: {
     } catch (cleanupFailure) {
       throw new AggregateError(
         [error, cleanupFailure],
-        "prepareGrokRoleEnvelope activation failed and its dispose cleanup also failed",
+        "prepareAcpRoleEnvelope activation failed and its dispose cleanup also failed",
         { cause: error },
       );
     }