@akagilnc/pi-workflow-roles 0.1.5478 → 0.1.5483

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

@@ -25039,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 [];
@@ -25420,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/package.json

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

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");