@akagilnc/pi-workflow-roles 0.1.5475 → 0.1.5483

package/dist/acp-host/description.js

@@ -12,12 +12,15 @@ export function acpStdioArgs(description, model, seat) {
 }
 /**
  * The modelId the host addresses the seat model by.
- * "argv" hosts address by bare model name; "set_model" hosts address by the
- * `provider:model` modelId the ACP catalog exposes (seat provider after host
- * alias projection, concatenated — never a package provider map).
+ * "argv" hosts use the bare model on the CLI flag. "set_model" hosts use the
+ * host-native catalog form in `setModelId` (hermes `provider:model` after seat
+ * provider / host-alias projection; grok bare model — never a package map).
  */
-export function acpModelId(modelPassing, model) {
+export function acpModelId(description, model) {
     if (model?.model === undefined)
         return undefined;
-    return modelPassing === "set_model" ? `${model.provider}:${model.model}` : model.model;
+    if (description.modelPassing !== "set_model")
+        return model.model;
+    const form = description.setModelId ?? "provider:model";
+    return form === "bare" ? model.model : `${model.provider}:${model.model}`;
 }

package/dist/acp-host/production-host.js

@@ -44,15 +44,19 @@ var init_host_descriptions = __esm({
     "use strict";
     DEFAULT_ROLE_TURN_HOST = "pi";
     HOST_DESCRIPTIONS = Object.freeze({
-      /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+      /**
+       * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+       * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+       * argv `--model` is ignored by current grok (#1146 probe).
+       */
       "grok-build": Object.freeze({
         binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
         argv: Object.freeze({
           prefix: Object.freeze(["agent"]),
-          suffix: Object.freeze(["stdio"]),
-          modelFlag: "--model"
+          suffix: Object.freeze(["stdio"])
         }),
-        modelPassing: "argv",
+        modelPassing: "set_model",
+        setModelId: "bare",
         sessionBindingFile: "grok-acp-session.json"
       }),
       /**
@@ -70,6 +74,7 @@ var init_host_descriptions = __esm({
           thinkingFlag: "--reasoning"
         }),
         modelPassing: "set_model",
+        setModelId: "provider:model",
         sessionBindingFile: "hermes-acp-session.json",
         seatProfileSoul: Object.freeze({
           flag: "-p",
@@ -24837,9 +24842,11 @@ function acpStdioArgs(description, model, seat) {
     ...suffix
   ];
 }
-function acpModelId(modelPassing, model) {
+function acpModelId(description, model) {
   if (model?.model === void 0) return void 0;
-  return modelPassing === "set_model" ? `${model.provider}:${model.model}` : model.model;
+  if (description.modelPassing !== "set_model") return model.model;
+  const form = description.setModelId ?? "provider:model";
+  return form === "bare" ? model.model : `${model.provider}:${model.model}`;
 }
 
 // src/acp-host/role-turn-host.ts
@@ -25226,7 +25233,7 @@ function createAcpRoleTurnHost(config) {
         });
         const initializeMeta = initialized._meta;
         const availableModels = Array.isArray(initializeMeta?.modelState?.availableModels) ? initializeMeta.modelState.availableModels : void 0;
-        if (request.model !== void 0 && availableModels !== void 0 && !availableModels.some((entry) => typeof entry === "object" && entry !== null && entry.modelId === acpModelId(config.modelPassing, request.model))) {
+        if (request.model !== void 0 && availableModels !== void 0 && !availableModels.some((entry) => typeof entry === "object" && entry !== null && entry.modelId === acpModelId(config, request.model))) {
           outcome = externalHostFailure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
             provider: request.model.provider,
             model: request.model.model
@@ -25291,7 +25298,7 @@ function createAcpRoleTurnHost(config) {
             if (config.modelPassing === "set_model" && request.model !== void 0 && sessionId !== void 0) {
               await rpc("session/set_model", {
                 sessionId,
-                modelId: acpModelId(config.modelPassing, request.model)
+                modelId: acpModelId(config, request.model)
               });
               sessionId = await loadSession(sessionId);
             }
@@ -25512,6 +25519,7 @@ function createProductionAcpRoleTurnHost(options) {
     hostName,
     sessionIdentity: createSessionIdentityAuthority(principalAuthority, description.sessionBindingFile),
     modelPassing: description.modelPassing,
+    ...description.setModelId === void 0 ? {} : { setModelId: description.setModelId },
     roleRuntimeDependencies: createRoleRuntimeDependencies(packageRoot),
     async connect(request) {
       const seatProfile = description.seatProfileSoul;

package/dist/headless-host/description.js

@@ -54,6 +54,257 @@ function codexTomlStringTable(entries) {
     const parts = Object.entries(entries).map(([key, value]) => `${key}=${codexTomlString(value)}`);
     return `{${parts.join(",")}}`;
 }
+/**
+ * Free-form JSON leaf for Type.Unknown under Codex strict transport.
+ * Declared contract objects still close with additionalProperties:false.
+ * For Unknown, a $defs anyOf of JSON values with nested additionalProperties
+ * as $ref is accepted by Codex and keeps non-empty object receipts expressible
+ * (native probe). Package code still does not validate or reject the receipt.
+ */
+const CODEX_JSON_VALUE_DEF = "codexJsonValue";
+const CODEX_JSON_VALUE_REF = `#/$defs/${CODEX_JSON_VALUE_DEF}`;
+const CODEX_JSON_VALUE_SCHEMA = Object.freeze({
+    anyOf: Object.freeze([
+        Object.freeze({ type: "string" }),
+        Object.freeze({ type: "number" }),
+        Object.freeze({ type: "boolean" }),
+        Object.freeze({ type: "null" }),
+        Object.freeze({ type: "array", items: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }) }),
+        Object.freeze({
+            type: "object",
+            properties: Object.freeze({}),
+            required: Object.freeze([]),
+            additionalProperties: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }),
+        }),
+    ]),
+});
+/**
+ * Derive a Codex/OpenAI-strict transport schema from the package open schema.
+ * Legal open schema is untouched; this is a host-only transmission projection
+ * (#1148 / #646 / ADR 0057 / ADR 0054): every object closes, every property is
+ * required, originally-optional fields become a null union (official guidance),
+ * and originally-required declared nullability stays. Nested open-tool anyOf
+ * wrappers are flattened so every branch carries `type`, keeping descriptions.
+ * Type.Unknown / description-only leaves become the closed JSON-value $ref.
+ * Package code still does not validate or reject the receipt.
+ */
+export function closeJsonSchemaForCodex(schema) {
+    const closed = closeSchemaNode(schema);
+    const existingDefs = isRecord(closed.$defs)
+        ? closed.$defs
+        : {};
+    return {
+        ...closed,
+        $defs: {
+            ...existingDefs,
+            [CODEX_JSON_VALUE_DEF]: CODEX_JSON_VALUE_SCHEMA,
+        },
+    };
+}
+/** Pure null leaf only — composite type|null is stripped in-leaf, not dropped whole. */
+function isPureNullTypeSchema(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type === "null")
+        return true;
+    if (Array.isArray(value.type) && value.type.length > 0 && value.type.every((t) => t === "null")) {
+        return true;
+    }
+    return false;
+}
+/** Declared nullability on the open schema (type|null, anyOf null leaf, or pure null). */
+function schemaDeclaresNull(schema) {
+    if (!isRecord(schema))
+        return false;
+    if (isPureNullTypeSchema(schema))
+        return true;
+    if (Array.isArray(schema.type) && schema.type.includes("null"))
+        return true;
+    if (Array.isArray(schema.anyOf) && schema.anyOf.some(schemaDeclaresNull))
+        return true;
+    return false;
+}
+/**
+ * Within a leaf, remove null members from type arrays.
+ * Null is re-added when the union or property edge originally declared it.
+ */
+function stripNullFromLeafType(leaf) {
+    if (!isRecord(leaf) || !Array.isArray(leaf.type))
+        return leaf;
+    const nonNull = leaf.type.filter((t) => t !== "null");
+    if (nonNull.length === leaf.type.length)
+        return leaf;
+    if (nonNull.length === 0)
+        return { ...leaf, type: "null" };
+    if (nonNull.length === 1)
+        return { ...leaf, type: nonNull[0] };
+    return { ...leaf, type: nonNull };
+}
+/**
+ * Flatten nested anyOf wrappers into concrete leaf schemas.
+ * Open-tool unions often wrap leaves in description-only anyOf shells that
+ * lack `type`; strict structured output rejects those intermediate nodes.
+ * Nested shell descriptions attach to leaves that lack their own (not onto $ref).
+ * The outermost union keeps its description on the closed node via the caller.
+ */
+function flattenUnionLeaves(schema, attachShellDescription = false) {
+    if (!isRecord(schema))
+        return [schema];
+    if (!Array.isArray(schema.anyOf))
+        return [schema];
+    const shellDescription = attachShellDescription && typeof schema.description === "string"
+        ? schema.description
+        : undefined;
+    return schema.anyOf.flatMap((branch) => {
+        const leaves = flattenUnionLeaves(branch, true);
+        if (shellDescription === undefined)
+            return leaves;
+        return leaves.map((leaf) => {
+            if (!isRecord(leaf) || typeof leaf.$ref === "string")
+                return leaf;
+            if (typeof leaf.description === "string")
+                return leaf;
+            return { ...leaf, description: shellDescription };
+        });
+    });
+}
+/** Drop pure-null leaves after in-leaf null stripping; property edge may re-add null. */
+function nonNullLeaves(schema) {
+    return flattenUnionLeaves(schema)
+        .map(stripNullFromLeafType)
+        .filter((leaf) => !isPureNullTypeSchema(leaf));
+}
+function withDescription(closed, description) {
+    if (description.description === undefined)
+        return closed;
+    // Codex strict does not allow sibling keys on $ref; wrap so guidance is kept.
+    if (isRecord(closed) && typeof closed.$ref === "string") {
+        return { anyOf: [closed], ...description };
+    }
+    // Prefer a leaf's own description (nested anyOf shell) over the outer copy.
+    if (isRecord(closed) && typeof closed.description === "string")
+        return closed;
+    return isRecord(closed) ? { ...closed, ...description } : closed;
+}
+/**
+ * Property edge under strict transport.
+ * Optional → closed leaf(s) + null. Required with declared nullability keeps null.
+ * Required without declared null stays non-nullable.
+ */
+function closePropertySchema(schema, optional) {
+    const description = isRecord(schema) && typeof schema.description === "string"
+        ? { description: schema.description }
+        : {};
+    const keepNull = optional || schemaDeclaresNull(schema);
+    const leaves = nonNullLeaves(schema).map(closeSchemaNode);
+    if (leaves.length === 0)
+        return { type: "null", ...description };
+    if (!keepNull) {
+        const closed = leaves.length === 1 ? leaves[0] : { anyOf: leaves };
+        return withDescription(closed, description);
+    }
+    return { anyOf: [...leaves, { type: "null" }], ...description };
+}
+/**
+ * Strict generators require every schema node to declare `type` (or a $ref).
+ * Type.Unknown / description-only leaves → free JSON $ref (not string): array
+ * and object receipts stay expressible under --output-schema.
+ */
+function ensureTypedLeaf(schema) {
+    if (schema.type !== undefined)
+        return schema;
+    if (typeof schema.$ref === "string")
+        return schema;
+    if (isRecord(schema.properties) || schema.additionalProperties !== undefined) {
+        return { ...schema, type: "object" };
+    }
+    if (schema.items !== undefined) {
+        return { ...schema, type: "array" };
+    }
+    if (schema.const !== undefined) {
+        const value = schema.const;
+        if (value === null)
+            return { ...schema, type: "null" };
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return { ...schema, type: typeof value };
+        }
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        const sample = schema.enum.find((item) => item !== null);
+        if (typeof sample === "string" || typeof sample === "number" || typeof sample === "boolean") {
+            return { ...schema, type: typeof sample };
+        }
+    }
+    // Free JSON via $defs. $ref must stand alone (strict rejects sibling keys).
+    return { $ref: CODEX_JSON_VALUE_REF };
+}
+function originalRequiredNames(node) {
+    if (!Array.isArray(node.required))
+        return new Set();
+    return new Set(node.required.filter((item) => typeof item === "string"));
+}
+function closeSchemaNode(node) {
+    if (!isRecord(node))
+        return node;
+    // Already a ref (free-JSON leaf or pre-existing) — do not retype.
+    if (typeof node.$ref === "string")
+        return node;
+    // Union node: flatten then close each concrete leaf (do not keep untyped shells).
+    // Declared null stays — including nested unions such as array items.
+    if (Array.isArray(node.anyOf)) {
+        const description = typeof node.description === "string" ? { description: node.description } : {};
+        const keepNull = schemaDeclaresNull(node);
+        const leaves = nonNullLeaves(node).map(closeSchemaNode);
+        if (leaves.length === 0)
+            return { type: "null", ...description };
+        if (!keepNull) {
+            if (leaves.length === 1)
+                return withDescription(leaves[0], description);
+            return { anyOf: leaves, ...description };
+        }
+        return { anyOf: [...leaves, { type: "null" }], ...description };
+    }
+    let out = { ...node };
+    if (node.items !== undefined) {
+        out.items = closeSchemaNode(node.items);
+    }
+    if (isRecord(node.$defs)) {
+        out.$defs = Object.fromEntries(Object.entries(node.$defs).map(([key, value]) => [key, closeSchemaNode(value)]));
+    }
+    const hasProperties = isRecord(node.properties);
+    const isObjectType = node.type === "object"
+        || (Array.isArray(node.type) && node.type.includes("object"))
+        || hasProperties
+        || node.additionalProperties !== undefined;
+    if (hasProperties) {
+        const props = node.properties;
+        const wasRequired = originalRequiredNames(node);
+        const closedProps = {};
+        const required = [];
+        for (const [name, propSchema] of Object.entries(props)) {
+            required.push(name);
+            closedProps[name] = closePropertySchema(propSchema, !wasRequired.has(name));
+        }
+        out.properties = closedProps;
+        out.required = required;
+        out.additionalProperties = false;
+        if (out.type === undefined)
+            out.type = "object";
+        // Object nodes must not also carry residual anyOf from the open copy.
+        delete out.anyOf;
+    }
+    else if (isObjectType) {
+        out.additionalProperties = false;
+        if (!Array.isArray(out.required))
+            out.required = [];
+        if (out.type === undefined)
+            out.type = "object";
+    }
+    else {
+        out = ensureTypedLeaf(out);
+    }
+    return out;
+}
 /**
  * Project shared-envelope MCP rows into `codex -c mcp_servers.<name>.*` argv pairs.
  * Dot-path + TOML values per official config-advanced; spawn argv (no shell).

package/dist/headless-host/production-host.js

@@ -44,15 +44,19 @@ var init_host_descriptions = __esm({
     "use strict";
     DEFAULT_ROLE_TURN_HOST = "pi";
     HOST_DESCRIPTIONS = Object.freeze({
-      /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+      /**
+       * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+       * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+       * argv `--model` is ignored by current grok (#1146 probe).
+       */
       "grok-build": Object.freeze({
         binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
         argv: Object.freeze({
           prefix: Object.freeze(["agent"]),
-          suffix: Object.freeze(["stdio"]),
-          modelFlag: "--model"
+          suffix: Object.freeze(["stdio"])
         }),
-        modelPassing: "argv",
+        modelPassing: "set_model",
+        setModelId: "bare",
         sessionBindingFile: "grok-acp-session.json"
       }),
       /**
@@ -70,6 +74,7 @@ var init_host_descriptions = __esm({
           thinkingFlag: "--reasoning"
         }),
         modelPassing: "set_model",
+        setModelId: "provider:model",
         sessionBindingFile: "hermes-acp-session.json",
         seatProfileSoul: Object.freeze({
           flag: "-p",
@@ -25034,6 +25039,169 @@ function codexTomlStringTable(entries) {
   );
   return `{${parts.join(",")}}`;
 }
+var CODEX_JSON_VALUE_DEF = "codexJsonValue";
+var CODEX_JSON_VALUE_REF = `#/$defs/${CODEX_JSON_VALUE_DEF}`;
+var CODEX_JSON_VALUE_SCHEMA = Object.freeze({
+  anyOf: Object.freeze([
+    Object.freeze({ type: "string" }),
+    Object.freeze({ type: "number" }),
+    Object.freeze({ type: "boolean" }),
+    Object.freeze({ type: "null" }),
+    Object.freeze({ type: "array", items: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }) }),
+    Object.freeze({
+      type: "object",
+      properties: Object.freeze({}),
+      required: Object.freeze([]),
+      additionalProperties: Object.freeze({ $ref: CODEX_JSON_VALUE_REF })
+    })
+  ])
+});
+function closeJsonSchemaForCodex(schema) {
+  const closed = closeSchemaNode(schema);
+  const existingDefs = isRecord(closed.$defs) ? closed.$defs : {};
+  return {
+    ...closed,
+    $defs: {
+      ...existingDefs,
+      [CODEX_JSON_VALUE_DEF]: CODEX_JSON_VALUE_SCHEMA
+    }
+  };
+}
+function isPureNullTypeSchema(value) {
+  if (!isRecord(value)) return false;
+  if (value.type === "null") return true;
+  if (Array.isArray(value.type) && value.type.length > 0 && value.type.every((t) => t === "null")) {
+    return true;
+  }
+  return false;
+}
+function schemaDeclaresNull(schema) {
+  if (!isRecord(schema)) return false;
+  if (isPureNullTypeSchema(schema)) return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+  if (Array.isArray(schema.anyOf) && schema.anyOf.some(schemaDeclaresNull)) return true;
+  return false;
+}
+function stripNullFromLeafType(leaf) {
+  if (!isRecord(leaf) || !Array.isArray(leaf.type)) return leaf;
+  const nonNull = leaf.type.filter((t) => t !== "null");
+  if (nonNull.length === leaf.type.length) return leaf;
+  if (nonNull.length === 0) return { ...leaf, type: "null" };
+  if (nonNull.length === 1) return { ...leaf, type: nonNull[0] };
+  return { ...leaf, type: nonNull };
+}
+function flattenUnionLeaves(schema, attachShellDescription = false) {
+  if (!isRecord(schema)) return [schema];
+  if (!Array.isArray(schema.anyOf)) return [schema];
+  const shellDescription = attachShellDescription && typeof schema.description === "string" ? schema.description : void 0;
+  return schema.anyOf.flatMap((branch) => {
+    const leaves = flattenUnionLeaves(branch, true);
+    if (shellDescription === void 0) return leaves;
+    return leaves.map((leaf) => {
+      if (!isRecord(leaf) || typeof leaf.$ref === "string") return leaf;
+      if (typeof leaf.description === "string") return leaf;
+      return { ...leaf, description: shellDescription };
+    });
+  });
+}
+function nonNullLeaves(schema) {
+  return flattenUnionLeaves(schema).map(stripNullFromLeafType).filter((leaf) => !isPureNullTypeSchema(leaf));
+}
+function withDescription(closed, description) {
+  if (description.description === void 0) return closed;
+  if (isRecord(closed) && typeof closed.$ref === "string") {
+    return { anyOf: [closed], ...description };
+  }
+  if (isRecord(closed) && typeof closed.description === "string") return closed;
+  return isRecord(closed) ? { ...closed, ...description } : closed;
+}
+function closePropertySchema(schema, optional) {
+  const description = isRecord(schema) && typeof schema.description === "string" ? { description: schema.description } : {};
+  const keepNull = optional || schemaDeclaresNull(schema);
+  const leaves = nonNullLeaves(schema).map(closeSchemaNode);
+  if (leaves.length === 0) return { type: "null", ...description };
+  if (!keepNull) {
+    const closed = leaves.length === 1 ? leaves[0] : { anyOf: leaves };
+    return withDescription(closed, description);
+  }
+  return { anyOf: [...leaves, { type: "null" }], ...description };
+}
+function ensureTypedLeaf(schema) {
+  if (schema.type !== void 0) return schema;
+  if (typeof schema.$ref === "string") return schema;
+  if (isRecord(schema.properties) || schema.additionalProperties !== void 0) {
+    return { ...schema, type: "object" };
+  }
+  if (schema.items !== void 0) {
+    return { ...schema, type: "array" };
+  }
+  if (schema.const !== void 0) {
+    const value = schema.const;
+    if (value === null) return { ...schema, type: "null" };
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return { ...schema, type: typeof value };
+    }
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const sample = schema.enum.find((item) => item !== null);
+    if (typeof sample === "string" || typeof sample === "number" || typeof sample === "boolean") {
+      return { ...schema, type: typeof sample };
+    }
+  }
+  return { $ref: CODEX_JSON_VALUE_REF };
+}
+function originalRequiredNames(node) {
+  if (!Array.isArray(node.required)) return /* @__PURE__ */ new Set();
+  return new Set(node.required.filter((item) => typeof item === "string"));
+}
+function closeSchemaNode(node) {
+  if (!isRecord(node)) return node;
+  if (typeof node.$ref === "string") return node;
+  if (Array.isArray(node.anyOf)) {
+    const description = typeof node.description === "string" ? { description: node.description } : {};
+    const keepNull = schemaDeclaresNull(node);
+    const leaves = nonNullLeaves(node).map(closeSchemaNode);
+    if (leaves.length === 0) return { type: "null", ...description };
+    if (!keepNull) {
+      if (leaves.length === 1) return withDescription(leaves[0], description);
+      return { anyOf: leaves, ...description };
+    }
+    return { anyOf: [...leaves, { type: "null" }], ...description };
+  }
+  let out = { ...node };
+  if (node.items !== void 0) {
+    out.items = closeSchemaNode(node.items);
+  }
+  if (isRecord(node.$defs)) {
+    out.$defs = Object.fromEntries(
+      Object.entries(node.$defs).map(([key, value]) => [key, closeSchemaNode(value)])
+    );
+  }
+  const hasProperties = isRecord(node.properties);
+  const isObjectType = node.type === "object" || Array.isArray(node.type) && node.type.includes("object") || hasProperties || node.additionalProperties !== void 0;
+  if (hasProperties) {
+    const props = node.properties;
+    const wasRequired = originalRequiredNames(node);
+    const closedProps = {};
+    const required = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      required.push(name);
+      closedProps[name] = closePropertySchema(propSchema, !wasRequired.has(name));
+    }
+    out.properties = closedProps;
+    out.required = required;
+    out.additionalProperties = false;
+    if (out.type === void 0) out.type = "object";
+    delete out.anyOf;
+  } else if (isObjectType) {
+    out.additionalProperties = false;
+    if (!Array.isArray(out.required)) out.required = [];
+    if (out.type === void 0) out.type = "object";
+  } else {
+    out = ensureTypedLeaf(out);
+  }
+  return out;
+}
 function stringEnvironment(value) {
   const entries = Array.isArray(value) ? value.flatMap((item) => {
     if (!isRecord(item) || typeof item.name !== "string" || typeof item.value !== "string") return [];
@@ -25415,12 +25583,12 @@ function createHeadlessRoleTurnHost(config) {
         if (codex) {
           if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
             outputSchemaPath = join44(request.runDirectory, "headless-output-schema.json");
-            await writeFile9(outputSchemaPath, `${JSON.stringify(prepared.jsonSchema, null, 2)}
-`, "utf8");
-            await retainPackageFault({
-              runDirectory: request.runDirectory,
-              diagnostic: "codex --output-schema cannot promise this open contract: native strict output requires all properties and additionalProperties:false; the declaration is sent unchanged"
-            });
+            await writeFile9(
+              outputSchemaPath,
+              `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}
+`,
+              "utf8"
+            );
           }
         } else {
           mcpConfigPath = join44(request.runDirectory, "headless-mcp-config.json");

package/dist/host-descriptions.js

@@ -13,15 +13,19 @@ export function resolveHostBinary(description, operatorHome) {
 }
 export const DEFAULT_ROLE_TURN_HOST = "pi";
 export const HOST_DESCRIPTIONS = Object.freeze({
-    /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+    /**
+     * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+     * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+     * argv `--model` is ignored by current grok (#1146 probe).
+     */
     "grok-build": Object.freeze({
         binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
         argv: Object.freeze({
             prefix: Object.freeze(["agent"]),
             suffix: Object.freeze(["stdio"]),
-            modelFlag: "--model",
         }),
-        modelPassing: "argv",
+        modelPassing: "set_model",
+        setModelId: "bare",
         sessionBindingFile: "grok-acp-session.json",
     }),
     /**
@@ -39,6 +43,7 @@ export const HOST_DESCRIPTIONS = Object.freeze({
             thinkingFlag: "--reasoning",
         }),
         modelPassing: "set_model",
+        setModelId: "provider:model",
         sessionBindingFile: "hermes-acp-session.json",
         seatProfileSoul: Object.freeze({
             flag: "-p",

package/dist/migrate-book-topology.js

@@ -14736,15 +14736,19 @@ var init_host_descriptions = __esm({
   "src/host-descriptions.ts"() {
     "use strict";
     HOST_DESCRIPTIONS = Object.freeze({
-      /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+      /**
+       * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+       * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+       * argv `--model` is ignored by current grok (#1146 probe).
+       */
       "grok-build": Object.freeze({
         binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
         argv: Object.freeze({
           prefix: Object.freeze(["agent"]),
-          suffix: Object.freeze(["stdio"]),
-          modelFlag: "--model"
+          suffix: Object.freeze(["stdio"])
         }),
-        modelPassing: "argv",
+        modelPassing: "set_model",
+        setModelId: "bare",
         sessionBindingFile: "grok-acp-session.json"
       }),
       /**
@@ -14762,6 +14766,7 @@ var init_host_descriptions = __esm({
           thinkingFlag: "--reasoning"
         }),
         modelPassing: "set_model",
+        setModelId: "provider:model",
         sessionBindingFile: "hermes-acp-session.json",
         seatProfileSoul: Object.freeze({
           flag: "-p",

package/dist/public-cli/main.js

@@ -15805,15 +15805,19 @@ var init_host_descriptions = __esm({
     "use strict";
     DEFAULT_ROLE_TURN_HOST = "pi";
     HOST_DESCRIPTIONS = Object.freeze({
-      /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+      /**
+       * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+       * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+       * argv `--model` is ignored by current grok (#1146 probe).
+       */
       "grok-build": Object.freeze({
         binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
         argv: Object.freeze({
           prefix: Object.freeze(["agent"]),
-          suffix: Object.freeze(["stdio"]),
-          modelFlag: "--model"
+          suffix: Object.freeze(["stdio"])
         }),
-        modelPassing: "argv",
+        modelPassing: "set_model",
+        setModelId: "bare",
         sessionBindingFile: "grok-acp-session.json"
       }),
       /**
@@ -15831,6 +15835,7 @@ var init_host_descriptions = __esm({
           thinkingFlag: "--reasoning"
         }),
         modelPassing: "set_model",
+        setModelId: "provider:model",
         sessionBindingFile: "hermes-acp-session.json",
         seatProfileSoul: Object.freeze({
           flag: "-p",

package/package.json

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

package/src/acp-host/description.ts

@@ -18,11 +18,17 @@ export type AcpHostDescription = HostIdentityDescription & Readonly<{
   }>;
   /**
    * How the seat model reaches the agent:
-   * - "argv": passed as the CLI `--model` flag (grok);
-   * - "set_model": sent as an ACP `session/set_model` RPC with modelId
-   *   `provider:model` (hermes).
+   * - "argv": passed as the CLI `--model` flag;
+   * - "set_model": sent as an ACP `session/set_model` RPC after session new/load
+   *   and before prompt. Catalog modelId shape is `setModelId` (host-native).
    */
   modelPassing: "argv" | "set_model";
+  /**
+   * Host-native `session/set_model` modelId form when `modelPassing` is
+   * `"set_model"`. hermes catalogs are `provider:model`; grok catalogs are bare
+   * model ids. Ignored for `"argv"` hosts.
+   */
+  setModelId?: "bare" | "provider:model";
   /**
    * When set, the production factory ensures a seat profile whose SOUL.md is a
    * symlink to the packaged role soul, and prefixes argv with `flag <name>`.
@@ -51,14 +57,19 @@ export function acpStdioArgs(
 
 /**
  * The modelId the host addresses the seat model by.
- * "argv" hosts address by bare model name; "set_model" hosts address by the
- * `provider:model` modelId the ACP catalog exposes (seat provider after host
- * alias projection, concatenated — never a package provider map).
+ * "argv" hosts use the bare model on the CLI flag. "set_model" hosts use the
+ * host-native catalog form in `setModelId` (hermes `provider:model` after seat
+ * provider / host-alias projection; grok bare model — never a package map).
  */
 export function acpModelId(
-  modelPassing: AcpHostDescription["modelPassing"],
+  description: {
+    readonly modelPassing: AcpHostDescription["modelPassing"];
+    readonly setModelId?: AcpHostDescription["setModelId"] | undefined;
+  },
   model?: { readonly model?: string; readonly provider?: string },
 ): string | undefined {
   if (model?.model === undefined) return undefined;
-  return modelPassing === "set_model" ? `${model.provider}:${model.model}` : model.model;
+  if (description.modelPassing !== "set_model") return model.model;
+  const form = description.setModelId ?? "provider:model";
+  return form === "bare" ? model.model : `${model.provider}:${model.model}`;
 }

package/src/acp-host/production-host.ts

@@ -63,6 +63,7 @@ export function createProductionAcpRoleTurnHost(options: ProductionAcpHostOption
     hostName,
     sessionIdentity: createSessionIdentityAuthority(principalAuthority, description.sessionBindingFile),
     modelPassing: description.modelPassing,
+    ...(description.setModelId === undefined ? {} : { setModelId: description.setModelId }),
     roleRuntimeDependencies: createRoleRuntimeDependencies(packageRoot),
     async connect(request) {
       const seatProfile = description.seatProfileSoul;

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

@@ -98,10 +98,13 @@ export type AcpRoleTurnHostConfig = Readonly<{
   hostName: string;
   /**
    * How the seat model reaches the agent: "set_model" sends an ACP
-   * `session/set_model` RPC with modelId `provider:model` once the session
-   * exists (new or loaded); "argv" leaves it to the connect argv (--model).
+   * `session/set_model` RPC once the session exists (new or loaded); "argv"
+   * leaves it to the connect argv (--model). Catalog modelId shape is
+   * `setModelId` (host-native).
    */
   modelPassing: AcpHostDescription["modelPassing"];
+  /** Host-native set_model catalog id; see AcpHostDescription.setModelId. */
+  setModelId?: AcpHostDescription["setModelId"];
   connect(request: RoleTurnRequest): Promise<AcpConnection>;
   prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
 }>;
@@ -296,7 +299,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
           : 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))) {
+          && (entry as { modelId?: unknown }).modelId === acpModelId(config, request.model))) {
           outcome = failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
             provider: request.model.provider,
             model: request.model.model,
@@ -354,11 +357,11 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
         }
 
         if (sessionReady) {
-        // set_model seat provider:model (#778); may rebuild agent — re-bind via loadSession.
+        // set_model host-native catalog id (#778 / #1146); 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),
+            modelId: acpModelId(config, request.model),
           });
           sessionId = await loadSession(sessionId);
         }

package/src/headless-host/description.ts

@@ -130,6 +130,253 @@ function codexTomlStringTable(entries: Readonly<Record<string, string>>): string
   return `{${parts.join(",")}}`;
 }
 
+/**
+ * Free-form JSON leaf for Type.Unknown under Codex strict transport.
+ * Declared contract objects still close with additionalProperties:false.
+ * For Unknown, a $defs anyOf of JSON values with nested additionalProperties
+ * as $ref is accepted by Codex and keeps non-empty object receipts expressible
+ * (native probe). Package code still does not validate or reject the receipt.
+ */
+const CODEX_JSON_VALUE_DEF = "codexJsonValue";
+const CODEX_JSON_VALUE_REF = `#/$defs/${CODEX_JSON_VALUE_DEF}`;
+const CODEX_JSON_VALUE_SCHEMA = Object.freeze({
+  anyOf: Object.freeze([
+    Object.freeze({ type: "string" }),
+    Object.freeze({ type: "number" }),
+    Object.freeze({ type: "boolean" }),
+    Object.freeze({ type: "null" }),
+    Object.freeze({ type: "array", items: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }) }),
+    Object.freeze({
+      type: "object",
+      properties: Object.freeze({}),
+      required: Object.freeze([] as string[]),
+      additionalProperties: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }),
+    }),
+  ]),
+});
+
+/**
+ * Derive a Codex/OpenAI-strict transport schema from the package open schema.
+ * Legal open schema is untouched; this is a host-only transmission projection
+ * (#1148 / #646 / ADR 0057 / ADR 0054): every object closes, every property is
+ * required, originally-optional fields become a null union (official guidance),
+ * and originally-required declared nullability stays. Nested open-tool anyOf
+ * wrappers are flattened so every branch carries `type`, keeping descriptions.
+ * Type.Unknown / description-only leaves become the closed JSON-value $ref.
+ * Package code still does not validate or reject the receipt.
+ */
+export function closeJsonSchemaForCodex(
+  schema: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const closed = closeSchemaNode(schema) as Record<string, unknown>;
+  const existingDefs = isRecord(closed.$defs)
+    ? (closed.$defs as Record<string, unknown>)
+    : {};
+  return {
+    ...closed,
+    $defs: {
+      ...existingDefs,
+      [CODEX_JSON_VALUE_DEF]: CODEX_JSON_VALUE_SCHEMA,
+    },
+  };
+}
+
+/** Pure null leaf only — composite type|null is stripped in-leaf, not dropped whole. */
+function isPureNullTypeSchema(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (value.type === "null") return true;
+  if (Array.isArray(value.type) && value.type.length > 0 && value.type.every((t) => t === "null")) {
+    return true;
+  }
+  return false;
+}
+
+/** Declared nullability on the open schema (type|null, anyOf null leaf, or pure null). */
+function schemaDeclaresNull(schema: unknown): boolean {
+  if (!isRecord(schema)) return false;
+  if (isPureNullTypeSchema(schema)) return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+  if (Array.isArray(schema.anyOf) && schema.anyOf.some(schemaDeclaresNull)) return true;
+  return false;
+}
+
+/**
+ * Within a leaf, remove null members from type arrays.
+ * Null is re-added when the union or property edge originally declared it.
+ */
+function stripNullFromLeafType(leaf: unknown): unknown {
+  if (!isRecord(leaf) || !Array.isArray(leaf.type)) return leaf;
+  const nonNull = leaf.type.filter((t) => t !== "null");
+  if (nonNull.length === leaf.type.length) return leaf;
+  if (nonNull.length === 0) return { ...leaf, type: "null" };
+  if (nonNull.length === 1) return { ...leaf, type: nonNull[0] };
+  return { ...leaf, type: nonNull };
+}
+
+/**
+ * Flatten nested anyOf wrappers into concrete leaf schemas.
+ * Open-tool unions often wrap leaves in description-only anyOf shells that
+ * lack `type`; strict structured output rejects those intermediate nodes.
+ * Nested shell descriptions attach to leaves that lack their own (not onto $ref).
+ * The outermost union keeps its description on the closed node via the caller.
+ */
+function flattenUnionLeaves(schema: unknown, attachShellDescription = false): unknown[] {
+  if (!isRecord(schema)) return [schema];
+  if (!Array.isArray(schema.anyOf)) return [schema];
+  const shellDescription =
+    attachShellDescription && typeof schema.description === "string"
+      ? schema.description
+      : undefined;
+  return schema.anyOf.flatMap((branch) => {
+    const leaves = flattenUnionLeaves(branch, true);
+    if (shellDescription === undefined) return leaves;
+    return leaves.map((leaf) => {
+      if (!isRecord(leaf) || typeof leaf.$ref === "string") return leaf;
+      if (typeof leaf.description === "string") return leaf;
+      return { ...leaf, description: shellDescription };
+    });
+  });
+}
+
+/** Drop pure-null leaves after in-leaf null stripping; property edge may re-add null. */
+function nonNullLeaves(schema: unknown): unknown[] {
+  return flattenUnionLeaves(schema)
+    .map(stripNullFromLeafType)
+    .filter((leaf) => !isPureNullTypeSchema(leaf));
+}
+
+function withDescription(closed: unknown, description: Readonly<{ description?: string }>): unknown {
+  if (description.description === undefined) return closed;
+  // Codex strict does not allow sibling keys on $ref; wrap so guidance is kept.
+  if (isRecord(closed) && typeof closed.$ref === "string") {
+    return { anyOf: [closed], ...description };
+  }
+  // Prefer a leaf's own description (nested anyOf shell) over the outer copy.
+  if (isRecord(closed) && typeof closed.description === "string") return closed;
+  return isRecord(closed) ? { ...closed, ...description } : closed;
+}
+
+/**
+ * Property edge under strict transport.
+ * Optional → closed leaf(s) + null. Required with declared nullability keeps null.
+ * Required without declared null stays non-nullable.
+ */
+function closePropertySchema(schema: unknown, optional: boolean): unknown {
+  const description =
+    isRecord(schema) && typeof schema.description === "string"
+      ? { description: schema.description }
+      : {};
+  const keepNull = optional || schemaDeclaresNull(schema);
+  const leaves = nonNullLeaves(schema).map(closeSchemaNode);
+  if (leaves.length === 0) return { type: "null", ...description };
+  if (!keepNull) {
+    const closed = leaves.length === 1 ? leaves[0] : { anyOf: leaves };
+    return withDescription(closed, description);
+  }
+  return { anyOf: [...leaves, { type: "null" }], ...description };
+}
+
+/**
+ * Strict generators require every schema node to declare `type` (or a $ref).
+ * Type.Unknown / description-only leaves → free JSON $ref (not string): array
+ * and object receipts stay expressible under --output-schema.
+ */
+function ensureTypedLeaf(schema: Record<string, unknown>): Record<string, unknown> {
+  if (schema.type !== undefined) return schema;
+  if (typeof schema.$ref === "string") return schema;
+  if (isRecord(schema.properties) || schema.additionalProperties !== undefined) {
+    return { ...schema, type: "object" };
+  }
+  if (schema.items !== undefined) {
+    return { ...schema, type: "array" };
+  }
+  if (schema.const !== undefined) {
+    const value = schema.const;
+    if (value === null) return { ...schema, type: "null" };
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return { ...schema, type: typeof value };
+    }
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const sample = schema.enum.find((item) => item !== null);
+    if (typeof sample === "string" || typeof sample === "number" || typeof sample === "boolean") {
+      return { ...schema, type: typeof sample };
+    }
+  }
+  // Free JSON via $defs. $ref must stand alone (strict rejects sibling keys).
+  return { $ref: CODEX_JSON_VALUE_REF };
+}
+
+function originalRequiredNames(node: Record<string, unknown>): ReadonlySet<string> {
+  if (!Array.isArray(node.required)) return new Set();
+  return new Set(node.required.filter((item): item is string => typeof item === "string"));
+}
+
+function closeSchemaNode(node: unknown): unknown {
+  if (!isRecord(node)) return node;
+
+  // Already a ref (free-JSON leaf or pre-existing) — do not retype.
+  if (typeof node.$ref === "string") return node;
+
+  // Union node: flatten then close each concrete leaf (do not keep untyped shells).
+  // Declared null stays — including nested unions such as array items.
+  if (Array.isArray(node.anyOf)) {
+    const description =
+      typeof node.description === "string" ? { description: node.description } : {};
+    const keepNull = schemaDeclaresNull(node);
+    const leaves = nonNullLeaves(node).map(closeSchemaNode);
+    if (leaves.length === 0) return { type: "null", ...description };
+    if (!keepNull) {
+      if (leaves.length === 1) return withDescription(leaves[0], description);
+      return { anyOf: leaves, ...description };
+    }
+    return { anyOf: [...leaves, { type: "null" }], ...description };
+  }
+
+  let out: Record<string, unknown> = { ...node };
+
+  if (node.items !== undefined) {
+    out.items = closeSchemaNode(node.items);
+  }
+  if (isRecord(node.$defs)) {
+    out.$defs = Object.fromEntries(
+      Object.entries(node.$defs).map(([key, value]) => [key, closeSchemaNode(value)]),
+    );
+  }
+
+  const hasProperties = isRecord(node.properties);
+  const isObjectType =
+    node.type === "object"
+    || (Array.isArray(node.type) && node.type.includes("object"))
+    || hasProperties
+    || node.additionalProperties !== undefined;
+
+  if (hasProperties) {
+    const props = node.properties as Record<string, unknown>;
+    const wasRequired = originalRequiredNames(node);
+    const closedProps: Record<string, unknown> = {};
+    const required: string[] = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      required.push(name);
+      closedProps[name] = closePropertySchema(propSchema, !wasRequired.has(name));
+    }
+    out.properties = closedProps;
+    out.required = required;
+    out.additionalProperties = false;
+    if (out.type === undefined) out.type = "object";
+    // Object nodes must not also carry residual anyOf from the open copy.
+    delete out.anyOf;
+  } else if (isObjectType) {
+    out.additionalProperties = false;
+    if (!Array.isArray(out.required)) out.required = [];
+    if (out.type === undefined) out.type = "object";
+  } else {
+    out = ensureTypedLeaf(out);
+  }
+
+  return out;
+}
+
 /**
  * Project shared-envelope MCP rows into `codex -c mcp_servers.<name>.*` argv pairs.
  * Dot-path + TOML values per official config-advanced; spawn argv (no shell).
@@ -185,7 +432,7 @@ export function codexTurnArgs(options: {
   readonly systemPromptPath: string;
   /**
    * Absolute path for the native `--output-schema` flag.
-   * Pass the declaration unchanged; native strict output cannot promise an open contract.
+   * File holds the Codex-strict transport projection of the open declaration (#1148).
    * Optional for prose-exit seats (#959 navigator) so agent_message stays free text.
    */
   readonly outputSchemaPath?: string;

package/src/headless-host/production-host.ts

@@ -7,8 +7,7 @@
  * Intermediate AK tools ride the shared envelope MCP relay (Claude `--mcp-config`,
  * codex `-c mcp_servers.*`). The terminating receipt is the host-native schema
  * channel only (#750 submission-tool-is-schema-channel) — terminating tool is not
- * listed on MCP (Claude `--json-schema`, codex `--output-schema` receive the declaration unchanged).
- * Codex native strict output cannot promise an open contract; the adapter reports that gap.
+ * listed on MCP (Claude `--json-schema`, codex `--output-schema` closed projection).
  */
 import { randomUUID } from "node:crypto";
 

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

@@ -32,6 +32,7 @@ import {
   recordNativeSessionPointer,
 } from "../host-session-record.ts";
 import {
+  closeJsonSchemaForCodex,
   codexTurnArgs,
   headlessMcpConfigDocument,
   headlessTurnArgs,
@@ -465,16 +466,15 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
       let mcpConfigPath: string | undefined;
       let outputSchemaPath: string | undefined;
       if (codex) {
-        // Send the declaration unchanged. Any native rejection belongs to Codex;
-        // do not close the schema or substitute a different receipt outlet.
+        // #1148: Codex --output-schema requires a native strict transport schema.
+        // Project from the unique open declaration; do not alter package receipt rules.
         if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
           outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-          await writeFile(outputSchemaPath, `${JSON.stringify(prepared.jsonSchema, null, 2)}\n`, "utf8");
-          await retainPackageFault({
-            runDirectory: request.runDirectory,
-            diagnostic:
-              "codex --output-schema cannot promise this open contract: native strict output requires all properties and additionalProperties:false; the declaration is sent unchanged",
-          });
+          await writeFile(
+            outputSchemaPath,
+            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            "utf8",
+          );
         }
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");

package/src/host-descriptions.ts

@@ -32,15 +32,19 @@ export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 export type HostFamily = "acp" | "headless";
 
 export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = Object.freeze({
-  /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
+  /**
+   * Operator home `~/.grok`, native session/load resume, `agent stdio`.
+   * Model arrives as ACP `session/set_model` with bare modelId (grok catalog);
+   * argv `--model` is ignored by current grok (#1146 probe).
+   */
   "grok-build": Object.freeze({
     binaryFromHome: Object.freeze([".grok", "bin", "grok"]),
     argv: Object.freeze({
       prefix: Object.freeze(["agent"]),
       suffix: Object.freeze(["stdio"]),
-      modelFlag: "--model",
     }),
-    modelPassing: "argv",
+    modelPassing: "set_model",
+    setModelId: "bare",
     sessionBindingFile: "grok-acp-session.json",
   }),
   /**
@@ -58,6 +62,7 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
       thinkingFlag: "--reasoning",
     }),
     modelPassing: "set_model",
+    setModelId: "provider:model",
     sessionBindingFile: "hermes-acp-session.json",
     seatProfileSoul: Object.freeze({
       flag: "-p",