@akagilnc/pi-workflow-roles 0.1.3556 → 0.1.3565

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

@@ -3,9 +3,10 @@ import { createInterface } from "node:readline";
 
 import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
 import { renderAgentStartMaterials } from "../agent-start-materials.ts";
+import type { AcpHostDescription } from "./description.ts";
 
-/** ACP v1 surface used by the Grok adapter. Protocol details stay in this module. */
-export interface GrokAcpConnection {
+/** ACP v1 surface used by the generic ACP adapter. Protocol details stay in this module. */
+export interface AcpConnection {
   request(method: string, params: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
   notify(method: string, params: Readonly<Record<string, unknown>>): void;
   /** Subscribe to agent→client notifications (session/update stream, etc.). */
@@ -15,7 +16,7 @@ export interface GrokAcpConnection {
 
 /** 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 GrokPreparedTurn = Readonly<{
+export type AcpPreparedTurn = Readonly<{
   mcpServers: readonly Readonly<Record<string, unknown>>[];
   /**
    * Structured system-prompt authority. `body` is the provider-facing prompt
@@ -45,24 +46,26 @@ export type GrokPreparedTurn = Readonly<{
 }>;
 
 /** Fold structured system-prompt authority into the provider-visible ACP override. */
-export function renderGrokSystemPromptOverride(authority: {
+export function renderAcpSystemPromptOverride(authority: {
   readonly body: string;
   readonly materials: readonly unknown[];
 }): string {
   return renderAgentStartMaterials(authority.body, authority.materials);
 }
 
-export type GrokSessionIdentityAuthority = Readonly<{
+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 GrokRoleTurnHostConfig = Readonly<{
-  sessionIdentity: GrokSessionIdentityAuthority;
-  connect(request: RoleTurnRequest): Promise<GrokAcpConnection>;
-  prepare(request: RoleTurnRequest): Promise<GrokPreparedTurn>;
+export type AcpRoleTurnHostConfig = Readonly<{
+  sessionIdentity: AcpSessionIdentityAuthority;
+  /** Whether a bound resume reuses the native session or mints a fresh one. */
+  boundResume: AcpHostDescription["boundResume"];
+  connect(request: RoleTurnRequest): Promise<AcpConnection>;
+  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
 }>;
 
 function failure(cause: "activation" | "session" | "output", name: string, code: string, details?: Readonly<Record<string, unknown>>): RoleTurnResult {
@@ -81,7 +84,7 @@ 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("Grok host aborted"), { code: "host-aborted" as const });
+  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 } {
@@ -89,23 +92,14 @@ function acpError(code: string, message: string, cause?: unknown): Error & { rea
 }
 
 /** One ACP JSON-RPC stdio process. Natural close/SIGTERM are its only lifecycle exits. */
-export function connectGrokAcpStdio(options: {
+export function connectAcpStdio(options: {
   readonly binary: string;
+  readonly args: readonly string[];
   readonly cwd: string;
   readonly env: NodeJS.ProcessEnv;
-  readonly model?: string;
-  readonly toolset?: string;
   readonly onNotification?: (method: string, params: Readonly<Record<string, unknown>>) => void;
-}): Promise<GrokAcpConnection> {
-  const args = [
-    "agent",
-    ...(options.model === undefined ? [] : ["--model", options.model]),
-    "stdio",
-  ];
-  const env = options.toolset === undefined
-    ? options.env
-    : { ...options.env, GROK_CONFIG: JSON.stringify({ toolset: options.toolset }) };
-  const child = spawn(options.binary, args, { cwd: options.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+}): Promise<AcpConnection> {
+  const child = spawn(options.binary, [...options.args], { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", "pipe"] });
   const pending = new Map<number, { resolve(value: Readonly<Record<string, unknown>>): void; reject(error: Error): void }>();
   const notificationHandlers: Array<(method: string, params: Readonly<Record<string, unknown>>) => void> = [];
   if (options.onNotification !== undefined) notificationHandlers.push(options.onNotification);
@@ -128,12 +122,12 @@ export function connectGrokAcpStdio(options: {
     child.kill("SIGTERM");
   };
   child.stderr.setEncoding("utf8").on("data", (chunk: string) => { stderr += chunk; });
-  child.on("error", (error) => settleClosed(acpError("acp-process-error", `Grok ACP process error: ${error.message}`, error)));
+  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;
     try { message = JSON.parse(line) as RpcReply; }
     catch (error) {
-      terminate(acpError("acp-invalid-json", `Invalid Grok ACP JSON: ${String(error)}`, error));
+      terminate(acpError("acp-invalid-json", `Invalid ACP JSON: ${String(error)}`, error));
       return;
     }
     if (typeof message.method === "string") {
@@ -142,14 +136,14 @@ export function connectGrokAcpStdio(options: {
       for (const handler of notificationHandlers) handler(message.method, params);
       if (typeof message.id === "number") {
         if (message.method !== "session/request_permission") {
-          terminate(acpError("acp-unsupported-client-request", `Unsupported Grok ACP client request: ${message.method}`));
+          terminate(acpError("acp-unsupported-client-request", `Unsupported ACP client request: ${message.method}`));
           return;
         }
         const choices = Array.isArray(params.options) ? params.options : [];
         const selected = choices.find((value) =>
           typeof value === "object" && value !== null && (value as { kind?: unknown }).kind === "allow_once") as { optionId?: unknown } | undefined;
         if (typeof selected?.optionId !== "string") {
-          terminate(acpError("acp-permission-missing-allow-once", "Grok ACP permission request omitted allow_once"));
+          terminate(acpError("acp-permission-missing-allow-once", "ACP permission request omitted allow_once"));
           return;
         }
         child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: { outcome: { outcome: "selected", optionId: selected.optionId } } })}\n`);
@@ -160,13 +154,13 @@ export function connectGrokAcpStdio(options: {
     const waiter = pending.get(message.id);
     if (waiter === undefined) return;
     pending.delete(message.id);
-    if (message.error !== undefined) waiter.reject(acpError("acp-upstream-error", `Grok ACP error: ${JSON.stringify(message.error)}`));
+    if (message.error !== undefined) waiter.reject(acpError("acp-upstream-error", `ACP error: ${JSON.stringify(message.error)}`));
     else waiter.resolve((message.result ?? {}) as Readonly<Record<string, unknown>>);
   });
-  child.on("close", (code) => settleClosed(acpError("acp-closed", `Grok ACP closed (${String(code)}): ${stderr}`)));
+  child.on("close", (code) => settleClosed(acpError("acp-closed", `ACP closed (${String(code)}): ${stderr}`)));
   return Promise.resolve({
     request(method, params) {
-      if (closed) return Promise.reject(terminalError ?? acpError("acp-connection-closed", "Grok ACP connection is closed"));
+      if (closed) return Promise.reject(terminalError ?? acpError("acp-connection-closed", "ACP connection is closed"));
       const id = ++nextId;
       return new Promise((resolve, reject) => {
         pending.set(id, { resolve, reject });
@@ -175,12 +169,12 @@ export function connectGrokAcpStdio(options: {
           const waiter = pending.get(id);
           if (waiter === undefined) return;
           pending.delete(id);
-          waiter.reject(acpError("acp-write-failed", `Grok ACP write failed: ${error.message}`, error));
+          waiter.reject(acpError("acp-write-failed", `ACP write failed: ${error.message}`, error));
         });
       });
     },
     notify(method, params) {
-      if (closed) throw terminalError ?? acpError("acp-connection-closed", "Grok ACP connection is closed");
+      if (closed) throw terminalError ?? acpError("acp-connection-closed", "ACP connection is closed");
       child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
     },
     onNotification(handler) {
@@ -188,7 +182,7 @@ export function connectGrokAcpStdio(options: {
     },
     async close() {
       if (closed) return;
-      settleClosed(acpError("acp-connection-closed", "Grok ACP connection is closed"));
+      settleClosed(acpError("acp-connection-closed", "ACP connection is closed"));
       child.stdin.end();
       child.kill("SIGTERM");
       await new Promise<void>((resolve) => child.once("close", () => resolve()));
@@ -197,23 +191,23 @@ export function connectGrokAcpStdio(options: {
 }
 
 /**
- * Main-session Grok adapter. The injected composition callbacks are the shared
+ * Main-session ACP adapter. The injected composition callbacks are the shared
  * envelope boundary: this module owns ACP lifecycle, never role policy.
  */
-export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurnHost {
+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);
-        let connection: GrokAcpConnection | undefined;
+        let connection: AcpConnection | undefined;
         let sessionId: string | undefined;
         let accepted = false;
         try {
           // AK injection proof is prepared MCP composition (envelope).
           if (prepared.mcpServers.length === 0) {
-            return failure("activation", "UncontrolledGrokSession", "ak-config-missing");
+            return failure("activation", "UncontrolledAcpSession", "ak-config-missing");
           }
           connection = await config.connect(request);
           const initialized = await connection.request("initialize", {
@@ -227,60 +221,47 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
           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 === request.model?.model)) {
-            return failure("activation", "GrokHostModelMismatch", "host-model-mismatch", {
+            return failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
               provider: request.model.provider,
               model: request.model.model,
             });
           }
 
-          // #617 DK-7: hand Pi session path once; Grok reads the file itself.
+          // #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?.previousHost === "pi"
-              ? request.hostTransition.priorNativePaths
+              ? request.hostTransition?.priorNativePaths
               : undefined;
-          if (continuation.kind === "resume") {
+          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 !== "") {
-              // Same-host Grok resume reuses native ACP session via session/load.
               const loaded = await connection.request("session/load", {
                 sessionId: boundSessionId,
                 cwd: request.cwd,
                 mcpServers: prepared.mcpServers,
-                _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
+                _meta: { systemPromptOverride: renderAcpSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
               });
               sessionId = typeof loaded.sessionId === "string" && loaded.sessionId !== ""
                 ? loaded.sessionId
                 : boundSessionId;
-            } else {
-              // Unbound resume (cross-host or lost binding): session/new + bind.
-              const session = await connection.request(
-                "session/new",
-                {
-                  cwd: request.cwd,
-                  mcpServers: prepared.mcpServers,
-                  _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
-                },
-              );
-              sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
-              if (sessionId === undefined || sessionId === "") {
-                return failure("session", "GrokAcpSessionFailure", "session-id-missing");
-              }
-              await config.sessionIdentity.bind(request.principal, sessionId);
             }
-          } else {
-            // Initial run: session/new + bind.
+          }
+          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",
               {
                 cwd: request.cwd,
                 mcpServers: prepared.mcpServers,
-                _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
+                _meta: { systemPromptOverride: renderAcpSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
               },
             );
             sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
             if (sessionId === undefined || sessionId === "") {
-              return failure("session", "GrokAcpSessionFailure", "session-id-missing");
+              return failure("session", "AcpSessionFailure", "session-id-missing");
             }
             await config.sessionIdentity.bind(request.principal, sessionId);
           }
@@ -353,7 +334,7 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
               throw error;
             }
             if (result.stopReason === "refusal") {
-              return failure("output", "GrokAcpRefusal", "refusal", { sessionId });
+              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.
@@ -370,7 +351,7 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
             }
             prompt = `The prior terminal submission was rejected (${closure.retry.code}). Resubmit it as the sole terminal tool call. Rejected call ids: ${closure.retry.toolCallIds.join(", ") || "none"}.`;
           }
-          return failure("output", "GrokAcpRoundLimit", "round-retry-limit", { sessionId });
+          return failure("output", "AcpRoundLimit", "round-retry-limit", { sessionId });
         } finally {
           if (connection !== undefined) {
             if (sessionId !== undefined && !accepted) {
@@ -389,19 +370,3 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
     },
   };
 }
-
-const PRIVATE_COMPAT_ENV = Object.fromEntries(
-  ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) =>
-    ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) =>
-      [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
-);
-
-/** Child environment shared by ACP agent processes. */
-export function controlledGrokChildEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-  return {
-    ...base,
-    ...PRIVATE_COMPAT_ENV,
-    GROK_MEMORY: "0",
-    GROK_SUBAGENTS: "0",
-  };
-}

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

@@ -2,15 +2,15 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import type { DurablePrincipal, DurablePrincipalAuthority } from "../host-contracts.ts";
-import type { GrokSessionIdentityAuthority } from "./role-turn-host.ts";
-
-/** ACP binding filename written only by the grok host on initial bind. */
-export const GROK_ACP_SESSION_BINDING = "grok-acp-session.json";
+import type { AcpSessionIdentityAuthority } from "./role-turn-host.ts";
 
 /** Durable ACP binding stored beside the host-owned session principal. */
-export function createGrokSessionIdentityAuthority(authority: DurablePrincipalAuthority): GrokSessionIdentityAuthority {
+export function createAcpSessionIdentityAuthority(
+  authority: DurablePrincipalAuthority,
+  sessionBindingFile: string,
+): AcpSessionIdentityAuthority {
   const bindingPath = (principal: DurablePrincipal): string =>
-    join(authority.decode(principal).sessionDirectory, GROK_ACP_SESSION_BINDING);
+    join(authority.decode(principal).sessionDirectory, sessionBindingFile);
   return {
     resolveSessionFile(principal) {
       return authority.decode(principal).sessionFile;
@@ -19,7 +19,7 @@ export function createGrokSessionIdentityAuthority(authority: DurablePrincipalAu
       try {
         const value: unknown = JSON.parse(await readFile(bindingPath(principal), "utf8"));
         if (typeof value !== "object" || value === null || typeof (value as { sessionId?: unknown }).sessionId !== "string") {
-          throw new Error("durable Grok ACP session binding is invalid");
+          throw new Error("durable ACP session binding is invalid");
         }
         return (value as { sessionId: string }).sessionId;
       } catch (error) {

package/src/host-contracts.ts

@@ -140,12 +140,14 @@ export type RoleTurnModelConfig = {
 
 /**
  * Typed cross-host resume handoff (#617 DK-4).
- * Present only when post-admission projects a real switch between known hosts.
- * Cross-host prior volume: previous native record paths for the live host (DK-7).
+ * Present only when post-admission projects a real host switch.
+ * priorNativeKind names the record family the paths belong to — Pi's own
+ * session file, or sitian run records (ADR 0077) — so a consuming adapter
+ * reads the handoff without knowing which host wrote it.
  * Target host reads those files itself; projector never copies bytes.
  */
 export type RoleTurnHostTransition = {
-  readonly previousHost: "pi" | "grok-build";
+  readonly priorNativeKind: "pi-native" | "sitian";
   readonly priorNativePaths: readonly string[];
 };
 

package/src/host-descriptions.ts

@@ -0,0 +1,51 @@
+/**
+ * Packaged host description table (#729 / #731).
+ * Key = seat-table `host` value; the row is the generic ACP factory's input.
+ * pi is the in-process default, not a row.
+ * Unregistered names fail closed (#510); this table does not fallback.
+ */
+import type { AcpHostDescription } from "./acp-host/description.ts";
+
+/** Grok CLI reads vendor-private compat surfaces unless each is disabled by name. */
+const PRIVATE_COMPAT_ENV = Object.fromEntries(
+  ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) =>
+    ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) =>
+      [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
+);
+
+export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
+
+export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = 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",
+    }),
+  }),
+});
+
+export function lookupHostDescription(host: string): AcpHostDescription | undefined {
+  return Object.hasOwn(HOST_DESCRIPTIONS, host) ? HOST_DESCRIPTIONS[host] : undefined;
+}
+
+export function packagedExternalHostNames(): readonly string[] {
+  return Object.keys(HOST_DESCRIPTIONS);
+}
+
+/** Legal persistent/invocation host: default pi, or a table key. */
+export function assertRegisteredHostName(host: string): string {
+  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostDescription(host) !== undefined) {
+    return host;
+  }
+  throw new Error(`unregistered host: ${host}`);
+}

package/src/host-transition-prior-native.ts

@@ -1,19 +1,13 @@
 /**
  * Single authority for #617 DK-4 cross-host prior-native projection.
- * Closed host discriminators only; unknown previous/live hosts never inject.
+ * Classifies the prior volume into the two record families that exist
+ * (Pi native session file / sitian run records), never by host name.
  */
 import { access, readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import type { RoleTurnHostTransition } from "./host-contracts.ts";
 
-const KNOWN_ROLE_TURN_HOSTS = ["pi", "grok-build"] as const;
-type KnownRoleTurnHost = (typeof KNOWN_ROLE_TURN_HOSTS)[number];
-
-function isKnownRoleTurnHost(value: string): value is KnownRoleTurnHost {
-  return (KNOWN_ROLE_TURN_HOSTS as readonly string[]).includes(value);
-}
-
 function isEnoent(error: unknown): boolean {
   return typeof error === "object" && error !== null && (error as NodeJS.ErrnoException).code === "ENOENT";
 }
@@ -59,13 +53,12 @@ async function listSitianRecordPaths(sessionParent: string): Promise<string[]> {
 }
 
 /**
- * Project one hostTransition only for a real switch between known hosts.
- * Unknown host names → undefined (no inject). Empty native volume still
- * yields a typed switch (empty path list).
+ * Project one hostTransition only for a real host switch. Empty native volume
+ * still yields a typed switch (empty path list).
  *
- * Pi previous → Pi session.jsonl path.
- * Grok previous → sitian records on the live run (#717). Grok CLI journals
- * stay in the operator grok home; they are not copied here.
+ * Pi wrote its own session.jsonl; every other host's run volume is the sitian
+ * record set on the live run (ADR 0077 `record-scope-phase-two`, #717) — the CLI's
+ * own journals stay in the operator home and are never copied here.
  */
 export async function projectHostTransitionPriorNative(input: {
   readonly previousHost: string;
@@ -73,20 +66,15 @@ export async function projectHostTransitionPriorNative(input: {
   readonly piSessionFile: string;
 }): Promise<RoleTurnHostTransition | undefined> {
   if (input.previousHost === input.liveHost) return undefined;
-  if (!isKnownRoleTurnHost(input.previousHost) || !isKnownRoleTurnHost(input.liveHost)) {
-    return undefined;
-  }
   if (input.previousHost === "pi") {
-    const paths = await listPiNativeRecordPaths(input.piSessionFile);
     return {
-      previousHost: "pi",
-      priorNativePaths: paths,
+      priorNativeKind: "pi-native",
+      priorNativePaths: await listPiNativeRecordPaths(input.piSessionFile),
     };
   }
-  // previousHost === "grok-build": sitian path handoff only — do not read bytes.
-  const paths = await listSitianRecordPaths(input.piSessionFile);
+  // Sitian path handoff only — do not read bytes.
   return {
-    previousHost: "grok-build",
-    priorNativePaths: paths,
+    priorNativeKind: "sitian",
+    priorNativePaths: await listSitianRecordPaths(input.piSessionFile),
   };
 }

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

@@ -406,9 +406,10 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
   return {
     async executeTurn(request: RoleTurnRequest): Promise<RoleTurnResult> {
       // #617 DK-7: Pi argv gets projected native paths once; never record bytes.
+      // Pi already owns its own session file, so only sitian prior volume rides in.
       let turnRequest = request;
       const paths =
-        request.hostTransition?.previousHost === "grok-build"
+        request.hostTransition?.priorNativeKind === "sitian"
           ? request.hostTransition.priorNativePaths
           : undefined;
       if (

package/src/public-cli/cli.ts

@@ -38,8 +38,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 } from "../host-contracts.ts";
-import { loadProductionGrokHostFactory } from "./load-production-grok-host.ts";
+import type { RoleTurnHost, RoleTurnRequest } from "../host-contracts.ts";
+import { packagedExternalHostNames } from "../host-descriptions.ts";
+import { loadProductionAcpHostFactory } from "./load-production-acp-host.ts";
 import {
   createPiRoleTurnHost,
   appendPiSessionCustomEntry,
@@ -321,19 +322,19 @@ function resolveRoleTurnHost(
     recordLaunchedRolePackageIdentity,
     observeLaunchedRolePackageIdentity,
   });
-  // Composition-root unique adapter table (#522 / #580): pi + S6 grok-build true adapter.
-  const adapters = env.hostAdapters ?? [
+  // Composition-root adapter table: pi (in-process default) + one ACP adapter per description-table key.
+  const adapters: readonly NamedRoleTurnHostAdapter[] = env.hostAdapters ?? [
     { name: "pi", create: () => ({ ok: true as const, host: piHost }) },
-    {
-      name: "grok-build",
+    ...packagedExternalHostNames().map((name) => ({
+      name,
       create: () => {
         // 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) => {
-              hostPromise ??= loadProductionGrokHostFactory(env.packageRoot).then((create) =>
+            executeTurn: async (request: RoleTurnRequest) => {
+              hostPromise ??= loadProductionAcpHostFactory(env.packageRoot, name).then((create) =>
                 create({
                   packageRoot: env.packageRoot,
                   principalAuthority: options.principalAuthority,
@@ -344,7 +345,7 @@ function resolveRoleTurnHost(
           },
         };
       },
-    },
+    })),
   ];
   const hostName = options.seat.host;
   const adapter = adapters.find((candidate) => candidate.name === hostName);

package/src/public-cli/config.ts

@@ -4,6 +4,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
+import { assertRegisteredHostName, DEFAULT_ROLE_TURN_HOST } from "../host-descriptions.ts";
 import { assertLegalEngineName } from "../package-resources/engine-material.ts";
 import { resolveConfiguredProvinceOfficer } from "../institutional-resolution.ts";
 import {
@@ -218,7 +219,8 @@ export function setPersistentSeatHost(
     }
     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 } } };
 }
 
 /**
@@ -295,7 +297,7 @@ export function setAutoResumeLimit(
  * Config-parse seam: persistent call axes belong to PUBLIC_CALLABLE_ROLES;
  * engine names need only path-safety syntax (no closed material catalog;
  * #376 / #378 / #391 / ADR 0069). Syntax authority = assertLegalEngineName
- * (no injected duplicate).
+ * (no injected duplicate). Persistent host must be pi or a description-table key (#510 / #731).
  */
 export function validatePublicCliConfigAxes(
   config: PublicCliConfig,
@@ -303,14 +305,25 @@ export function validatePublicCliConfigAxes(
 ): void {
   for (const seat of Object.keys(config.seats) as PublicConfigurableSeat[]) {
     const row = config.seats[seat];
-    if (row?.engine === undefined) continue;
-    try {
-      assertLegalEngineName(row.engine);
-    } catch (error) {
-      throw new Error(
-        `config seat ${seat} engine is illegal: ${row.engine}`,
-        { cause: error },
-      );
+    if (row?.engine !== undefined) {
+      try {
+        assertLegalEngineName(row.engine);
+      } catch (error) {
+        throw new Error(
+          `config seat ${seat} engine is illegal: ${row.engine}`,
+          { cause: error },
+        );
+      }
+    }
+    if (row?.host !== undefined) {
+      try {
+        assertRegisteredHostName(row.host);
+      } catch (error) {
+        throw new Error(
+          `config seat ${seat} host is unregistered: ${row.host}`,
+          { cause: error },
+        );
+      }
     }
   }
 }
@@ -550,7 +563,7 @@ function attachHostAxis(
   if (invocation?.host !== undefined) return { ...seat, host: invocation.host, hostSource: "invocation" };
   const persistent = config.seats[seat.seat]?.host;
   if (persistent !== undefined) return { ...seat, host: persistent, hostSource: "persistent" };
-  return { ...seat, host: "pi", hostSource: "default" };
+  return { ...seat, host: DEFAULT_ROLE_TURN_HOST, hostSource: "default" };
 }
 
 function attachEngineAxis(

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

@@ -0,0 +1,52 @@
+/**
+ * Deferred loader for the packaged generic ACP RoleTurnHost factory.
+ *
+ * Public ak-role bin must not statically value-import the production host (or its
+ * role-runtime / pi-coding-agent edges). Specifier is runtime-constructed so
+ * esbuild leaves this import external (ADR 0052 discovery stays peer-free).
+ *
+ * Host selection is a description-table lookup: the row for the seat's host key
+ * is the factory input. There is no host-name fork here.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { AcpHostDescription } from "../acp-host/description.ts";
+import { lookupHostDescription } from "../host-descriptions.ts";
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+
+export type ProductionAcpHostFactory = (options: {
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+}) => RoleTurnHost;
+
+type GenericAcpHostFactory = (options: {
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+  description: AcpHostDescription;
+}) => RoleTurnHost;
+
+/**
+ * Resolve the production ACP host factory for one registered host key without a
+ * static graph edge into the public CLI bundle.
+ */
+export async function loadProductionAcpHostFactory(
+  packageRoot: string,
+  host: string,
+): Promise<ProductionAcpHostFactory> {
+  const description = lookupHostDescription(host);
+  if (description === undefined) {
+    throw new Error(`unregistered host: ${host}`);
+  }
+  const built = join(packageRoot, "dist/acp-host/production-host.js");
+  const source = join(packageRoot, "src/acp-host/production-host.ts");
+  // Prefer the built artifact (plain node); fall back to source under tsx tests.
+  const target = existsSync(built) ? built : source;
+  const href = pathToFileURL(target).href;
+  const mod = (await import(href)) as {
+    createProductionAcpRoleTurnHost: GenericAcpHostFactory;
+  };
+  const create = mod.createProductionAcpRoleTurnHost;
+  return (options) => create({ ...options, description });
+}