@dungle-scrubs/harness-cli-normalizer 0.6.0 → 0.6.1

package/src/interpretation/turn-options.ts

@@ -8,21 +8,28 @@
  * it must refuse - is a distinct responsibility with its own vocabulary.
  * Folding it into argv.ts would make the largest interpretation file the
  * place two unrelated questions are answered.
+ *
+ * The render-to-tokens rule itself has one owner, `tokensFor` in the
+ * knowledge layer (RFC-02 change 1): every arm here validates its value,
+ * resolves the render for the phase, and calls it.
  */
-import type { HarnessDescriptor, OptionRender, SpecBase } from "../knowledge/descriptor.js";
-import { DISCOVERY_FACETS, resolveRender, TURN_OPTION_KEYS } from "../knowledge/descriptor.js";
+import type { AccessValue, HarnessDescriptor, SpecBase } from "../knowledge/descriptor.js";
+import {
+  ACCESS_VALUES,
+  DISCOVERY_FACETS,
+  resolveRender,
+  TURN_OPTION_KEYS,
+  tokensFor,
+} from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import type { DiscoveryOptions, TurnOptions } from "./argv.js";
 import { hintFor } from "./hints.js";
 import { ArgvRefusalError } from "./refusal.js";
+import { supportedBy } from "./support.js";
 import { renderToolSelection } from "./tool-selection.js";
-import { READ_PRESET } from "./tool-vocabulary.js";
+import { canonicalTable, hasCounterpart, READ_PRESET } from "./tool-vocabulary.js";
 import { CLEAN_SELECTOR, resolveModel, validateAccess, validateEffort } from "./vocabulary.js";
 
-// TOML-quoted value for config-kv: JSON.stringify is sufficient for the
-// closed vocabularies that may use it (enum, effort) - no value contains a
-// quote that would need escaping beyond JSON's.
-const tomlQuote = (value: string): string => JSON.stringify(value);
-
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
@@ -35,20 +42,10 @@ export const renderTurnOptions = (
   phase: "launch" | "resume",
 ): string[] => {
   const sequences: string[][] = [];
-
-  const accessRaw = opts.access;
-  if (accessRaw !== undefined) {
-    const v = validateAccess(accessRaw);
-    if (!v.ok) {
-      throw new ArgvRefusalError({
-        issue: "invalid-option-value",
-        harness: h.name,
-        option: "access",
-        supported: ["read", "write"],
-        detail: String(accessRaw),
-      });
-    }
-  }
+  // The turn option the access preset displaces when set (codex: sandbox),
+  // read from the descriptor so no arm below branches on a harness name.
+  const accessSpec = h.turnOptions.access;
+  const claimed = accessSpec?.kind === "access" ? accessSpec.claims : undefined;
 
   for (const key of TURN_OPTION_KEYS) {
     const spec = h.turnOptions[key];
@@ -109,16 +106,11 @@ export const renderTurnOptions = (
       for (const facet of DISCOVERY_FACETS) {
         const val = discObj[facet];
         if (val === undefined) continue;
-        // Polarity handling: disables emits on false, enables emits on true
         const facetSpec = spec.facets[facet];
         if (facetSpec === undefined) {
-          // If caller asked to disable (false for disables, true for enables) but facet not declared, refuse
-          // But if caller passed true for a disables facet, it's a no-op, not a refusal
-          // So only refuse when the caller's value would have emitted
-          // For all current descriptors polarity is disables, so false would emit -> refuse
-          // For safety, check wouldEmit logic
-          // If val would not emit anyway, skip
-          // Determine wouldEmit: if facetSpec undefined, we cannot know polarity, so treat false as intended disable -> refuse
+          // A facet the descriptor does not declare cannot be expressed.
+          // Only a value that would have emitted refuses: every current
+          // facet has "disables" polarity, so false would emit.
           if (val === false) {
             const supportedFacets = Object.keys(spec.facets);
             throw new ArgvRefusalError({
@@ -132,26 +124,15 @@ export const renderTurnOptions = (
           }
           continue;
         }
-        // Determine if this value should emit
-        let shouldEmit = false;
-        if (facetSpec.polarity === "disables" && val === false) shouldEmit = true;
-        else if (facetSpec.polarity === "enables" && val === true) shouldEmit = true;
-        else {
-          // true for disables or false for enables => no-op
-          continue;
-        }
+        // Polarity: disables emits on false, enables emits on true.
+        const shouldEmit =
+          (facetSpec.polarity === "disables" && val === false) ||
+          (facetSpec.polarity === "enables" && val === true);
         if (!shouldEmit) continue;
-        // Check resumeRender refusal
         const effective = resolveRender(facetSpec, phase);
         if (effective === null) {
           const resumeSupported = Object.entries(spec.facets)
-            .filter(
-              ([, v]) =>
-                resolveRender(
-                  v as unknown as import("../knowledge/descriptor.js").SpecBase,
-                  "resume",
-                ) !== null,
-            )
+            .filter(([, v]) => resolveRender(v as SpecBase, "resume") !== null)
             .map(([k]) => k);
           throw new ArgvRefusalError({
             issue: "unsupported-on-resume",
@@ -161,8 +142,8 @@ export const renderTurnOptions = (
             supported: resumeSupported.length ? resumeSupported : ["(none resume)"],
           });
         }
-        // Reject config-kv for discovery (only closed vocab, discovery is not)
-        if ((effective as OptionRender).kind === "config-kv") {
+        // Discovery is not a closed vocabulary, so config-kv cannot carry it.
+        if (effective.kind === "config-kv") {
           throw new ArgvRefusalError({
             issue: "invalid-option-value",
             harness: h.name,
@@ -171,21 +152,17 @@ export const renderTurnOptions = (
             supported: ["flag-list only for discovery"],
           });
         }
-        let seq: string[];
-        if ((effective as OptionRender).kind === "flag-list")
-          seq = [...(effective as Extract<OptionRender, { kind: "flag-list" }>).flags];
-        else if ((effective as OptionRender).kind === "flag-value")
-          seq = [(effective as Extract<OptionRender, { kind: "flag-value" }>).flag, ""];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(effective)]);
       }
       continue;
     }
 
-    // Access is opt-in-only, no profile default; dispatch to tool-selection for the preset.
+    // Access is opt-in-only, no profile default. One arm for every harness:
+    // the descriptor says whether a value renders through the tool list, a
+    // phase-aware render, or nothing at all.
     if (key === "access") {
       if (raw === undefined) continue;
-      if (spec === undefined) {
+      if (spec === undefined || spec.kind !== "access") {
         throw new ArgvRefusalError({
           issue: "unsupported-option",
           harness: h.name,
@@ -195,93 +172,63 @@ export const renderTurnOptions = (
           hint: hintFor(h.name, key),
         });
       }
-      const v = validateAccess(raw as string);
+      // The resume path builds from unresolved options, so the value is
+      // checked here as well as in option resolution - one rule, two gates.
+      const v = validateAccess(String(raw));
       if (!v.ok) {
         throw new ArgvRefusalError({
           issue: "invalid-option-value",
           harness: h.name,
           option: key,
-          supported: ["read", "write"],
+          supported: [...ACCESS_VALUES],
           detail: String(raw),
         });
       }
-      // When discovery.tools is off, the read preset must not re-enable tools.
-      if (raw === "read" && opts.discovery?.tools === false) {
-        if (spec.kind === "tool-preset") continue;
+      const value = v.id as AccessValue;
+      const target = spec.renders[value];
+      if (target === null) continue;
+      if (target === "tool-preset") {
+        // The read preset rides the tool list. When discovery.tools is off,
+        // it must not switch tools back on; write is no restriction.
+        if (value !== "read" || opts.discovery?.tools === false) continue;
+        const table = canonicalTable(defaultDescriptors());
+        const filtered = (READ_PRESET as readonly string[]).filter((c) =>
+          hasCounterpart(table, c, h.name, opts.toolMap),
+        );
+        if (filtered.length === 0) continue;
+        const rendered = renderToolSelection(h, { include: filtered, toolMap: opts.toolMap });
+        if (rendered.tokens.length > 0) sequences.push([...rendered.tokens]);
+        continue;
       }
-      switch (spec.kind) {
-        case "tool-preset": {
-          if (raw === "write") break;
-          const toolMapForHarness = (opts as { toolMap?: Record<string, Record<string, string>> })
-            .toolMap?.[h.name];
-          const filtered = (READ_PRESET as readonly string[]).filter((c) => {
-            if (toolMapForHarness?.[c] !== undefined) return true;
-            if (h.tools.builtins.some((b) => b.canonical === c)) return true;
-            if (h.tools.categories.some((cat) => (cat.canonical as readonly string[]).includes(c)))
-              return true;
-            return false;
-          });
-          if (filtered.length === 0) break;
-          const rendered = renderToolSelection(h, {
-            include: filtered as unknown as string[],
-            toolMap: toolMapForHarness,
-          });
-          if (rendered.tokens.length > 0) sequences.push([...rendered.tokens]);
-          break;
-        }
-        case "flag-value": {
-          const fv = spec as Extract<typeof spec, { kind: "flag-value" }>;
-          const mapped = fv.values[raw as string];
-          if (mapped !== undefined) sequences.push([fv.flag, mapped]);
-          break;
-        }
-        case "flag-list-by-value": {
-          const fl = spec as Extract<typeof spec, { kind: "flag-list-by-value" }>;
-          const list = fl.flags[raw as string] ?? [];
-          if (list.length > 0) sequences.push([...list]);
-          break;
-        }
-        default: {
-          const _exhaustive: never = spec as never;
-          throw new ArgvRefusalError({
-            issue: "invalid-option-value",
-            harness: h.name,
-            option: key,
-            supported: [],
-            detail: String(_exhaustive),
-          });
-        }
+      const render = resolveRender(target, phase);
+      if (render === null) {
+        throw new ArgvRefusalError({
+          issue: "unsupported-on-resume",
+          harness: h.name,
+          option: key,
+          supported: ["re-launch with --access, or resume without it"],
+        });
       }
+      sequences.push([...tokensFor(render, target.value)]);
       continue;
     }
 
     // Non-discovery keys
-    // Handle enum default on launch. An access preset already claimed the
-    // sandbox flag on harnesses that express access through it (codex);
-    // the enum default must not emit a second --sandbox.
+    // Handle enum default on launch. A set access preset displaces the
+    // option it claims (codex: sandbox), so that option's default must not
+    // emit a second flag beside the preset's.
     if (raw === undefined) {
-      if (key === "sandbox" && opts.access !== undefined) continue;
+      if (key === claimed && opts.access !== undefined) continue;
       if (
         spec !== undefined &&
         spec.kind === "enum" &&
         spec.default !== undefined &&
         phase === "launch"
       ) {
-        const effective = resolveRender(spec as unknown as SpecBase, phase);
+        const effective = resolveRender(spec, phase);
         if (effective === null) continue; // should not happen for launch
         // config-kv is allowed for enum (closed vocab) - no rejection needed here
-        let seq: string[];
-        if ((effective as OptionRender).kind === "flag-value")
-          seq = [(effective as Extract<OptionRender, { kind: "flag-value" }>).flag, spec.default];
-        else if ((effective as OptionRender).kind === "config-kv")
-          seq = [
-            (effective as Extract<OptionRender, { kind: "config-kv" }>).flag,
-            `${(effective as Extract<OptionRender, { kind: "config-kv" }>).key}=${tomlQuote(spec.default)}`,
-          ];
-        else if ((effective as OptionRender).kind === "flag-list")
-          seq = [...(effective as Extract<OptionRender, { kind: "flag-list" }>).flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(effective, spec.default)]);
       }
       continue;
     }
@@ -293,59 +240,59 @@ export const renderTurnOptions = (
         harness: h.name,
         option: key,
         supported: Object.keys(h.turnOptions).length ? Object.keys(h.turnOptions) : ["(none)"],
+        supportedBy: supportedBy(defaultDescriptors(), key),
         detail: String(raw),
         hint: hintFor(h.name, key),
       });
     }
 
+    // From here every spec carries a render: the discovery table and the
+    // access spec were handled above and left the loop with `continue`.
+    if (spec.kind === "discovery" || spec.kind === "access") continue;
+
     // Check resumeRender null => unsupported-on-resume
-    // For discovery we handled per-facet; for others check spec
-    if ((spec as { kind: string }).kind !== "discovery") {
-      const effective = resolveRender(spec as unknown as SpecBase, phase);
-      if (effective === null) {
-        const resumeSupported = TURN_OPTION_KEYS.filter((k) => {
-          const s = h.turnOptions[k];
-          if (!s) return false;
-          if ((s as { kind: string }).kind === "discovery") {
-            const facets = (s as unknown as { facets: Record<string, unknown> }).facets;
-            return Object.keys(facets).length > 0;
-          }
-          return resolveRender(s as unknown as SpecBase, "resume") !== null;
-        }) as string[];
-        throw new ArgvRefusalError({
-          issue: "unsupported-on-resume",
-          harness: h.name,
-          option: key,
-          supported: resumeSupported.length ? resumeSupported : ["(none)"],
-        });
-      }
-      // Reject config-kv for open vocabularies. Exception (issue #48):
-      // prompt-text rides config-kv VERBATIM on codex - both a literal and
-      // a path are accepted (live-verified 0.146.1); no quoting, because
-      // codex's k=v split takes the rest of the token raw and both probed
-      // forms passed unquoted.
-      if (
-        (spec as unknown as SpecBase).render.kind === "config-kv" &&
-        (spec as { kind: string }).kind !== "enum" &&
-        (spec as { kind: string }).kind !== "effort" &&
-        (spec as { kind: string }).kind !== "prompt-text"
-      ) {
-        throw new ArgvRefusalError({
-          issue: "invalid-option-value",
-          harness: h.name,
-          option: key,
-          supported: ["config-kv only for enum, effort, and prompt-text (issue #48)"],
-        });
-      }
+    const render = resolveRender(spec, phase);
+    if (render === null) {
+      const resumeSupported = TURN_OPTION_KEYS.filter((k) => {
+        const s = h.turnOptions[k];
+        if (!s) return false;
+        if (s.kind === "discovery") return Object.keys(s.facets).length > 0;
+        if (s.kind === "access") {
+          const read = s.renders.read;
+          return (
+            read === "tool-preset" || (read !== null && resolveRender(read, "resume") !== null)
+          );
+        }
+        return resolveRender(s, "resume") !== null;
+      }) as string[];
+      throw new ArgvRefusalError({
+        issue: "unsupported-on-resume",
+        harness: h.name,
+        option: key,
+        supported: resumeSupported.length ? resumeSupported : ["(none)"],
+      });
+    }
+    // Reject config-kv for open vocabularies. Exception (issue #48):
+    // prompt-text rides config-kv VERBATIM on codex - both a literal and
+    // a path are accepted (live-verified 0.146.1); no quoting, because
+    // codex's k=v split takes the rest of the token raw and both probed
+    // forms passed unquoted.
+    if (
+      spec.render.kind === "config-kv" &&
+      spec.kind !== "enum" &&
+      spec.kind !== "effort" &&
+      spec.kind !== "integer" &&
+      spec.kind !== "prompt-text"
+    ) {
+      throw new ArgvRefusalError({
+        issue: "invalid-option-value",
+        harness: h.name,
+        option: key,
+        supported: ["config-kv only for enum, effort, integer, and prompt-text"],
+      });
     }
 
-    // Per-kind validation and token generation
-    const effectiveRender =
-      (spec as { kind: string }).kind === "discovery"
-        ? null
-        : resolveRender(spec as unknown as SpecBase, phase);
-    // effectiveRender already checked for null
-
+    // Per-kind validation; token generation is tokensFor's alone.
     switch (spec.kind) {
       case "effort": {
         if (typeof raw !== "string") {
@@ -380,13 +327,7 @@ export const renderTurnOptions = (
             detail: raw,
           });
         }
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-value") seq = [r.flag, raw];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${tomlQuote(raw)}`];
-        else if (r.kind === "flag-list") seq = [...r.flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, raw)]);
         break;
       }
       case "enum": {
@@ -408,13 +349,7 @@ export const renderTurnOptions = (
             detail: raw,
           });
         }
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-value") seq = [r.flag, raw];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${tomlQuote(raw)}`];
-        else if (r.kind === "flag-list") seq = [...r.flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, raw)]);
         break;
       }
       case "prompt-text": {
@@ -431,13 +366,7 @@ export const renderTurnOptions = (
             detail: typeof raw === "string" ? "(empty)" : String(raw),
           });
         }
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-value") seq = [...(r.extraFlags ?? []), r.flag, raw];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${raw}`];
-        else if (r.kind === "flag-list") seq = [...r.flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, raw, "verbatim")]);
         break;
       }
       case "selector": {
@@ -459,13 +388,7 @@ export const renderTurnOptions = (
             detail: raw,
           });
         }
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-value") seq = [r.flag, raw];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${tomlQuote(raw)}`];
-        else if (r.kind === "flag-list") seq = [...r.flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, raw)]);
         break;
       }
       case "toggle": {
@@ -478,17 +401,11 @@ export const renderTurnOptions = (
             detail: String(raw),
           });
         }
-        let shouldEmit = false;
-        if (spec.polarity === "disables" && raw === false) shouldEmit = true;
-        else if (spec.polarity === "enables" && raw === true) shouldEmit = true;
+        const shouldEmit =
+          (spec.polarity === "disables" && raw === false) ||
+          (spec.polarity === "enables" && raw === true);
         if (!shouldEmit) break;
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-list") seq = [...r.flags];
-        else if (r.kind === "flag-value") seq = [r.flag, String(raw)];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${tomlQuote(String(raw))}`];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, String(raw))]);
         break;
       }
       case "integer": {
@@ -510,25 +427,11 @@ export const renderTurnOptions = (
             detail: String(raw),
           });
         }
-        const r = effectiveRender!;
-        let seq: string[];
-        if (r.kind === "flag-value") seq = [r.flag, String(raw)];
-        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${tomlQuote(String(raw))}`];
-        else if (r.kind === "flag-list") seq = [...r.flags];
-        else seq = [];
-        sequences.push(seq);
+        sequences.push([...tokensFor(render, String(raw), "verbatim")]);
         break;
       }
-      case "discovery":
-        // already handled
-        break;
-      case "tool-preset":
-      case "flag-value":
-      case "flag-list-by-value":
-        // access-only kinds - handled above for key === "access"
-        break;
       default: {
-        const _exhaustive: never = spec as never;
+        const _exhaustive: never = spec;
         throw new ArgvRefusalError({
           issue: "invalid-option-value",
           harness: h.name,

package/src/interpretation/vocabulary.ts

@@ -5,7 +5,7 @@
  * actionable without reading the descriptor. Resolution lives in ONE place
  * (resolveModel) so validation and capability claims cannot drift.
  */
-import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { ACCESS_VALUES, type HarnessDescriptor } from "../knowledge/descriptor.js";
 
 export type Validated = { readonly ok: true; readonly id: string } | ValidationRefusal;
 
@@ -14,10 +14,11 @@ export interface ValidationRefusal {
   readonly reason: string;
 }
 
-/** The selector grammar an extensible registry still demands: pi documents
- * models as provider/id[:thinking], so word characters plus the few real
- * separators - never whitespace, shell metacharacters, or control/format
- * characters, and bounded like session ids. */
+/** The one selector grammar for model ids, tool names, and toolMap keys
+ * (RFC-02 change 9): pi documents models as provider/id[:thinking], so
+ * word characters plus the few real separators - never whitespace, shell
+ * metacharacters, or control/format characters, and bounded like session
+ * ids. */
 export const CLEAN_SELECTOR = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,127}$/;
 
 export interface ResolvedModel {
@@ -54,14 +55,18 @@ export const validateModel = (h: HarnessDescriptor, model: string): Validated =>
   };
 };
 
-/** Validate an effort against the ladder that applies to the pick: the
- * model's own ladder where the harness constrains per model (codex), else
- * the harness-wide ladder. */
+/** The access preset takes one of the closed ACCESS_VALUES. */
 export const validateAccess = (value: string): Validated => {
-  if (value === "read" || value === "write") return { ok: true, id: value };
-  return { ok: false, reason: `unknown access ${JSON.stringify(value)}; accepted: read, write` };
+  if ((ACCESS_VALUES as readonly string[]).includes(value)) return { ok: true, id: value };
+  return {
+    ok: false,
+    reason: `unknown access ${JSON.stringify(value)}; accepted: ${ACCESS_VALUES.join(", ")}`,
+  };
 };
 
+/** Validate an effort against the ladder that applies to the pick: the
+ * model's own ladder where the harness constrains per model (codex), else
+ * the harness-wide ladder. */
 export const validateEffort = (h: HarnessDescriptor, effort: string, model?: string): Validated => {
   let ladder = h.vocabulary.efforts;
   if (model !== undefined && h.vocabulary.effortsByModel !== undefined) {

package/src/knowledge/claude-code.ts

@@ -27,7 +27,6 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     baseFlags: ["-p"],
     subcommands: [],
     promptStyle: "positional",
-    toolsFlag: "--allowedTools",
     // A headless turn launches with the full stream-json output set so the
     // runner can decode identity/limits and stream token deltas; bare -p
     // (granularity none) is a degraded invocation this builder never emits.
@@ -198,7 +197,9 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
         },
       },
     },
-    access: { kind: "tool-preset", render: { kind: "flag-value", flag: "--allowedTools" } },
+    // read renders the read preset through the tool list (grant plus deny
+    // complement); write is the harness default and emits nothing.
+    access: { kind: "access", renders: { read: "tool-preset", write: null } },
   },
   // Phase 0 fixtures: claude-tool-interplay.md. include is a permission
   // grant (Bash, Edit stay visible under --allowedTools Read); only the
@@ -211,7 +212,6 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     includeFlag: "--allowedTools",
     excludeFlag: "--disallowedTools",
     includeIsStrictAllowlist: false,
-    composable: true,
     builtins: [
       { name: "Bash", defaultEnabled: true, canonical: "shell" },
       { name: "Edit", defaultEnabled: true, canonical: "edit" },

package/src/knowledge/codex.ts

@@ -23,7 +23,6 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     baseFlags: ["exec", "--json", "--skip-git-repo-check"],
     subcommands: ["exec"],
     promptStyle: "positional",
-    toolsFlag: null,
     streamFlags: [],
     // Codex mints its own thread id; there is nothing to assign at launch.
     idFlag: null,
@@ -62,11 +61,13 @@ export const codexCli: HarnessDescriptor = deepFreeze({
   autonomy: { flag: "--yolo" },
   vocabulary: {
     modelFlag: "--model",
-    models: ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"],
+    models: ["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"],
     aliases: {},
     efforts: ["minimal", "low", "medium", "high", "xhigh", "max"],
     // Codex constrains ladders per model generation (v1 registry).
     effortsByModel: {
+      // https://developers.openai.com/api/docs/models/gpt-6-astra (2026-09-06).
+      "gpt-6-astra": ["low", "medium", "high", "xhigh", "max"],
       "gpt-5.5": ["minimal", "low", "medium", "high"],
       "gpt-5.6-sol": ["medium", "high", "xhigh", "max"],
       "gpt-5.6-terra": ["medium", "high", "xhigh", "max"],
@@ -109,6 +110,14 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     observedOn: { harness: "codex", model: "", version: "0.146.1", date: "2026-08-19" },
   },
   turnOptions: {
+    // Codex config reference; accepted as an integer on CLI 0.153.4.
+    // Native compaction uses this window; hcn does not count request tokens.
+    contextWindow: {
+      kind: "integer",
+      min: 1,
+      max: 272000,
+      render: { kind: "config-kv", flag: "-c", key: "model_context_window" },
+    },
     effort: {
       kind: "effort",
       render: { kind: "config-kv", flag: "-c", key: "model_reasoning_effort" },
@@ -138,11 +147,27 @@ export const codexCli: HarnessDescriptor = deepFreeze({
       // caller asked.
       resumeRender: { kind: "config-kv", flag: "-c", key: "sandbox_mode" },
     },
+    // The preset maps onto the sandbox dimension and therefore CLAIMS it:
+    // an explicit --sandbox alongside --access refuses, and the profile's
+    // sandbox default yields. Data here, not a harness-name branch.
+    // On resume the preset rides the same config-kv spelling the sandbox
+    // dimension uses (issue #72 evidence above): `codex exec resume`
+    // rejects --sandbox, and -c sandbox_mode is enforced there.
     access: {
-      kind: "flag-value",
-      flag: "--sandbox",
-      values: { read: "read-only", write: "workspace-write" },
-      render: { kind: "flag-value", flag: "--sandbox" },
+      kind: "access",
+      claims: "sandbox",
+      renders: {
+        read: {
+          render: { kind: "flag-value", flag: "--sandbox" },
+          resumeRender: { kind: "config-kv", flag: "-c", key: "sandbox_mode" },
+          value: "read-only",
+        },
+        write: {
+          render: { kind: "flag-value", flag: "--sandbox" },
+          resumeRender: { kind: "config-kv", flag: "-c", key: "sandbox_mode" },
+          value: "workspace-write",
+        },
+      },
     },
   },
   // Tools: no built-in name lists; control is feature booleans
@@ -158,7 +183,6 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     includeFlag: null,
     excludeFlag: null,
     includeIsStrictAllowlist: false,
-    composable: false,
     builtins: [],
     categories: [
       { key: "shell", disableFlag: null, configKey: "features.shell_tool", canonical: [] },