@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/codex/management-convergence.ts

@@ -1,4 +1,5 @@
 import type { OcxConfig } from "../types";
+import { resolvePendingInitialModelSelection } from "../providers/initial-model-selection-runtime";
 import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
 import { convergeCodexCatalog } from "./convergence";
 import type {
@@ -152,6 +153,8 @@ export function createManagementConvergeCodex(
           catalogRefresh: unexpectedCatalogFailure(false),
         });
       }
+      // Registration choices are committed independently, before sealing catalog authority.
+      await resolvePendingInitialModelSelection(retainedConfig as OcxConfig);
       const snapshot = captureCatalogAdmissionSnapshot(retainedConfig);
       const result = await convergeCodexCatalog(snapshot, request, {
         onCommitBegin: () => { commitBegan = true; },

package/src/codex/model-entitlements.ts

@@ -149,6 +149,13 @@ export function compareClientVersionsForTests(left: string, right: string): numb
 }
 
 /** Numeric-segment comparison. Only used to pick the highest floor in a known-good set. */
+// Prerelease and build suffixes are deliberately NOT ordered. Splitting on [.+-] turns the
+// suffix into a non-finite segment that reads as 0, so `0.144.0-rc.1` sorts at or above
+// `0.144.0` rather than below it, the inverse of semver. That is tolerable because every
+// version this ranks against is a release version: the gated floor, the measured minimum, and
+// the snapshot's `minimal_client_version` rows. A prerelease runtime is therefore passed
+// through exactly as it was before the floor bound tier 2, so this is not a new hazard. Order
+// the suffix properly before reusing this anywhere a prerelease has to sort below its release.
 function compareClientVersions(left: string, right: string): number {
   const l = left.split(/[.+-]/).map(Number);
   const r = right.split(/[.+-]/).map(Number);
@@ -165,9 +172,10 @@ function compareClientVersions(left: string, right: string): number {
  *
  * 1. the inbound request's own `client_version` — the only value certainly describing the
  *    client being answered;
- * 2. the selected Codex runtime version, for background sync where no request exists.
- *    Retained sync refreshes runtime evidence before discovery, which is what makes this
- *    usable here; the persisted file itself carries no freshness guarantee.
+* 2. the selected Codex runtime version, for callers with no request of their own — but never
+ *    below `GATED_MODEL_CLIENT_VERSION_FLOOR`. Retained sync refreshes runtime evidence before
+ *    discovery, which is what makes this usable here; the persisted file itself carries no
+ *    freshness guarantee.
  * 3. the floor this build's own bundled roster records for the models being gated
  *    (`GATED_MODEL_CLIENT_VERSION_FLOOR`).
  *
@@ -178,6 +186,25 @@ function compareClientVersions(left: string, right: string): number {
  * snapshot states the gated models require, so asking under it is the narrowest question
  * that can still return them.
  *
+ * The floor binds tier 2 as well, and that is the whole of #3436. #3022 gave tier 3 the
+ * measured minimum but left tier 2 to speak for itself, so a host whose persisted runtime was
+ * REAL but OLD — 0.141.0 against a measured 0.144.0 — asked upstream under a version upstream
+ * filters on, got an honest roster with no gpt-5.6, and lost sol/terra/luna everywhere. That
+ * made an outdated CLI strictly worse than no CLI at all, since the runtime-less host already
+ * asked at the floor and kept its models. The clamp only ever raises: a runtime at or above
+ * the floor is preserved exactly, because a newer client can drive models the floor cannot
+ * name.
+ *
+ * Which tier answers is a question about WHICH QUESTION IS BEING ASKED, not about background
+ * versus request path — `isDirectCallerEntitledToCodexModel` and both authorization paths in
+ * `auth-context.ts` are inbound requests that reach tier 2 because they carry no version:
+ *
+ * - No inbound version: the caller is asking whether the ACCOUNT owns the model. Upstream
+ *   only incidentally filters that answer by version, so ask at no less than the floor.
+ * - An inbound version: the caller is asking what THAT CLIENT may use. Answer verbatim, even
+ *   when it is older than the floor. Clamping there would advertise rows the client told us
+ *   it cannot drive (#2548) and would turn an honest `unknown` into a cached `denied`.
+ *
  * There is deliberately no `0.0.0`-style fallback. A placeholder describes a client that
  * predates every gated model, which is what made upstream answer with an empty roster and
  * turned absent evidence into a manufactured confirmed negative (#2886).
@@ -195,7 +222,23 @@ export function resolveCodexEntitlementClientVersion(
   const selected = bypass
     ? readRuntimeVersion(loadRuntime)
     : memoizedPersistedRuntimeVersion(loadRuntime, options.now ?? Date.now());
-  return selected ?? GATED_MODEL_CLIENT_VERSION_FLOOR;
+  return raisedToGatedFloor(selected);
+}
+
+/**
+ * The gated floor as a lower bound rather than a fallback.
+ *
+ * Applied only on the way out of the resolver. `readRuntimeVersion` and
+ * `memoizedPersistedRuntimeVersion` keep reporting what is actually on disk, because
+ * `selectedVersion` is probe evidence that runtime identity, catalog cache keys,
+ * `X-Codex-Version` and install provenance all read for their own reasons. Clamping the
+ * persisted value itself would corrupt every one of them to fix one question.
+ */
+function raisedToGatedFloor(selected: string | null): string {
+  if (selected === null) return GATED_MODEL_CLIENT_VERSION_FLOOR;
+  return compareClientVersions(selected, GATED_MODEL_CLIENT_VERSION_FLOOR) >= 0
+    ? selected
+    : GATED_MODEL_CLIENT_VERSION_FLOOR;
 }
 const MODEL_ROSTER_TTL_MS = 5 * 60_000;
 
@@ -575,6 +618,13 @@ async function fetchAccountModels(
       return unconfirmedAccountModels(credential, clientVersion, now, { kind: "parsed-empty" });
     }
     const hasUnknownGatedAbsence = [...ACCOUNT_GATED_NATIVE_MODEL_MINIMUM_CLIENT_VERSIONS]
+      // Reachable only through tier 1, an inbound client_version below the floor. Every other
+      // resolution is now structurally >= every recorded minimum, because the floor is the max
+      // of the derived value and the same measured constant these minimums hold. So this is the
+      // escape hatch for a self-declared old client, not live protection on the background path:
+      // there, an absence really was asked for at an adequate version and is a denial. If
+      // upstream ever raises its true requirement above the measured constant, that constant is
+      // the only thing standing between an entitled account and a five-minute cached denial.
       .some(([modelId, minimum]) => (
         !models.has(modelId) && compareClientVersions(clientVersion, minimum) < 0
       ));

package/src/codex/project-config-warnings.ts

@@ -32,6 +32,8 @@ interface TomlDocument {
   sections: Map<string, Record<string, string>>;
 }
 
+type TomlMultilineDelimiter = '"""' | "'''";
+
 let diagnosticsCache: { at: number; warnings: ProjectCodexConfigWarning[] } | null = null;
 
 function hasInjectedOpenaiBaseUrl(content: string): boolean {
@@ -55,14 +57,102 @@ function parseTomlString(raw: string): string {
   return raw.slice(1, -1);
 }
 
+function multilineCloseIndex(
+  line: string,
+  delimiter: TomlMultilineDelimiter,
+  from: number,
+): number {
+  let index = line.indexOf(delimiter, from);
+  while (index >= 0 && delimiter === '"""') {
+    let backslashes = 0;
+    for (let cursor = index - 1; cursor >= 0 && line[cursor] === "\\"; cursor -= 1) {
+      backslashes += 1;
+    }
+    if (backslashes % 2 === 0) break;
+    index = line.indexOf(delimiter, index + delimiter.length);
+  }
+  return index;
+}
+
+/**
+ * Find a multiline TOML string that starts outside a comment or single-line string.
+ *
+ * This parser intentionally understands only the root/table subset needed by Codex
+ * diagnostics. It still has to skip multiline string bodies lexically: prose in
+ * `developer_instructions` can contain key-shaped examples or `[table]` snippets, and
+ * treating those examples as configuration changes the diagnostic's meaning.
+ */
+function multilineStateAfterLine(
+  line: string,
+  active: TomlMultilineDelimiter | null,
+): { active: TomlMultilineDelimiter | null; consumed: boolean } {
+  if (active) {
+    const close = multilineCloseIndex(line, active, 0);
+    if (close < 0) return { active, consumed: true };
+    const tail = multilineStateAfterLine(line.slice(close + active.length), null);
+    return {
+      active: tail.active,
+      consumed: true,
+    };
+  }
+
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  let consumed = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const character = line[index]!;
+    if (quote === '"') {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === quote) quote = null;
+      continue;
+    }
+    if (quote === "'") {
+      if (character === quote) quote = null;
+      continue;
+    }
+    if (character === "#") return { active: null, consumed };
+
+    const delimiter: TomlMultilineDelimiter | null = line.startsWith('"""', index)
+      ? '"""'
+      : line.startsWith("'''", index)
+        ? "'''"
+        : null;
+    if (delimiter) {
+      consumed = true;
+      const close = multilineCloseIndex(line, delimiter, index + delimiter.length);
+      if (close < 0) return { active: delimiter, consumed: true };
+      index = close + delimiter.length - 1;
+      continue;
+    }
+    if (character === '"' || character === "'") quote = character;
+  }
+  return { active: null, consumed };
+}
+
 /** Lightweight TOML parse for root keys and [section] tables (Codex config shape). */
 export function parseTomlDocument(content: string): TomlDocument {
   const root: Record<string, string> = {};
   const sections = new Map<string, Record<string, string>>();
   let current = root;
+  let multiline: TomlMultilineDelimiter | null = null;
 
   for (const line of content.split("\n")) {
-    const table = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    const wasMultiline = multiline !== null;
+    const multilineState = multilineStateAfterLine(line, multiline);
+    multiline = multilineState.active;
+    if (multilineState.consumed) {
+      // The declaration itself is still configuration even though its multiline VALUE must
+      // not be scanned as keys/tables. A legacy root key using a multiline value therefore
+      // remains visible to strict-config diagnostics; only the body is opaque.
+      if (!wasMultiline) {
+        const declaration = line.match(/^\s*([A-Za-z0-9_.-]+)\s*=\s*(?:"""|''')/);
+        if (declaration) current[declaration[1]!] = "";
+      }
+      continue;
+    }
+
+    const table = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
     if (table) {
       const name = table[1]!.trim();
       const section = sections.get(name) ?? {};
@@ -422,4 +512,4 @@ export function printProjectCodexConfigWarnings(
     }
   }
   return warnings;
-}
+}

package/src/codex/prompt-layers/encoding.ts

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Character policy — see the header. Defined over Unicode SCALAR VALUES, not
+// UTF-16 code units, because a lone surrogate is not a scalar value and UTF-8
+// encoding would silently substitute U+FFFD.
+// ---------------------------------------------------------------------------
+
+export interface CharacterFinding {
+  /** code-point index, consistent across module, route and editor */
+  position: number;
+  reason: "control" | "unpaired-surrogate";
+  codePoint: number;
+}
+
+/** Tab to four spaces, CRLF and lone CR to LF. Applied BEFORE validation. */
+export function normalizeBody(body: string): string {
+  return body.replace(/\r\n?/g, "\n").replace(/\t/g, "    ");
+}
+
+/** First offending scalar, or null. Run AFTER normalizeBody. */
+export function findInvalidCharacter(body: string): CharacterFinding | null {
+  let position = 0;
+  for (let i = 0; i < body.length; ) {
+    const code = body.codePointAt(i)!;
+    const unit = body.charCodeAt(i);
+    const isHighSurrogate = unit >= 0xd800 && unit <= 0xdbff;
+    const isLowSurrogate = unit >= 0xdc00 && unit <= 0xdfff;
+    // codePointAt only combines a well-formed pair, so a surviving surrogate
+    // code point here is unpaired by construction.
+    if ((isHighSurrogate || isLowSurrogate) && code === unit) {
+      return { position, reason: "unpaired-surrogate", codePoint: code };
+    }
+    const isNewline = code === 0x0a;
+    const isC0 = code < 0x20 && !isNewline;
+    const isDel = code === 0x7f;
+    const isC1 = code >= 0x80 && code <= 0x9f;
+    if (isC0 || isDel || isC1) {
+      return { position, reason: "control", codePoint: code };
+    }
+    i += code > 0xffff ? 2 : 1;
+    position += 1;
+  }
+  return null;
+}
+
+/**
+ * TOML basic-string encoding, total over the accepted set: three rules, none of
+ * them in the range where `Bun.TOML.parse` misbehaves. `\r` cannot appear
+ * because normalizeBody removed it; control characters cannot appear because
+ * findInvalidCharacter rejected them.
+ */
+export function encodeBasicString(body: string): string {
+  return `"${body.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+}
+
+/**
+ * Inverse of `encodeBasicString`, deliberately narrow: it accepts ONLY the three
+ * escapes we emit. `\t`, `\f`, `\b`, `\r` and `\uXXXX` are refused rather than
+ * guessed — decoding them correctly is exactly the ambiguity the restricted set
+ * exists to avoid.
+ */
+export function decodeBasicString(literal: string): string | null {
+  if (literal.length < 2 || !literal.startsWith('"') || !literal.endsWith('"')) return null;
+  const inner = literal.slice(1, -1);
+  let out = "";
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i]!;
+    if (ch !== "\\") {
+      if (ch === '"') return null; // unescaped quote: not a single literal
+      out += ch;
+      continue;
+    }
+    const next = inner[i + 1];
+    if (next === "\\") out += "\\";
+    else if (next === '"') out += '"';
+    else if (next === "n") out += "\n";
+    else return null; // any other escape is outside what we will decode
+    i += 1;
+  }
+  return out;
+}

package/src/codex/prompt-layers/paths.ts

@@ -0,0 +1,54 @@
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { expandUserPath } from "../../config";
+import { CODEX_CONFIG_PATH } from "../paths";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+export interface Paths {
+  configPath?: string;
+  storePath?: string;
+  baseVariantDir?: string;
+}
+
+function activeCodexHome(): string {
+  const raw = process.env.CODEX_HOME?.trim();
+  if (!raw) return CODEX_CONFIG_PATH.slice(0, -"/config.toml".length);
+  const path = resolve(expandUserPath(raw));
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+export function activeConfigPath(opts?: Paths): string {
+  return opts?.configPath ?? join(activeCodexHome(), "config.toml");
+}
+
+export function activeStorePath(opts?: Paths): string {
+  return opts?.storePath ?? join(activeCodexHome(), "opencodex-prompt.json");
+}
+
+/**
+ * Where authored base-prompt variants live, one markdown file per variant.
+ *
+ * A directory of real files rather than another JSON store, because
+ * `model_instructions_file` points Codex at a path it reads directly. Embedding the
+ * bodies in `opencodex-prompt.json` would mean materialising a temp file at selection
+ * time, which is a second write path for no gain.
+ */
+export function activeBaseVariantDir(opts?: Paths): string {
+  return opts?.baseVariantDir ?? join(activeCodexHome(), "opencodex-prompt-base");
+}
+
+
+export function journalPathFor(storePath: string): string {
+  return `${storePath.replace(/\.json$/, "")}.journal`;
+}
+
+export function lockPathFor(storePath: string): string {
+  return `${storePath.replace(/\.json$/, "")}.lock`;
+}

package/src/codex/prompt-layers/revision.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createHash, type Hash } from "node:crypto";
+
+/**
+ * Feed one named field into a fingerprint, framed so that no two distinct states
+ * can produce the same digest.
+ *
+ * Framing is the whole point. Concatenating `name + ":" + contents` is ambiguous:
+ * an adversarial review of the first version of this function showed that
+ * `{override: "left", agents: "right\nAGENTS.md:tail"}` and
+ * `{override: "left\nAGENTS.md:right", agents: "tail"}` hashed identically, because
+ * a file's own bytes can imitate the separator that follows it. That is exactly a
+ * missed invalidation: the fingerprint is the probe's admission key, so two
+ * different prompt states sharing a digest means one caller is served the other's
+ * stale text.
+ *
+ * A byte length cannot be forged by content, so each field carries one. Absence is
+ * a length of -1 rather than a sentinel string, because a sentinel is just more
+ * content: the same review found that `null` collided with a file whose bytes were
+ * literally NUL + "absent".
+ */
+export function updateFingerprintField(hash: Hash, name: string, contents: string | null): void {
+  const bytes = contents === null ? -1 : Buffer.byteLength(contents, "utf8");
+  hash.update(`\n${name}:${bytes}:`);
+  if (contents !== null) hash.update(contents);
+}
+
+
+// ---------------------------------------------------------------------------
+// Byte-level hashing. The revision covers COMPLETE file bytes plus existence,
+// so removing the marker while leaving the value intact still changes it.
+// ---------------------------------------------------------------------------
+
+export function readFileOrNull(path: string): string | null {
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function computeRevision(configBytes: string | null, storeBytes: string | null): string {
+  const hash = createHash("sha256");
+  // Length-framed for the reason given on updateFingerprintField: with a bare
+  // separator, config bytes ending in "\nstore:" shift the boundary and two
+  // different pairs hash alike. That matters twice over — this value is both the
+  // probe's admission input and the optimistic-concurrency token compared in
+  // commit(), where a collision would let a write built on stale bytes through.
+  updateFingerprintField(hash, "cfg", configBytes);
+  updateFingerprintField(hash, "store", storeBytes);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export { readFileOrNull as readFileBytes };

package/src/codex/prompt-layers/toml-edit.ts

@@ -0,0 +1,163 @@
+import { OCX_SECTION_MARKER } from "../injected-marker";
+import { encodeBasicString } from "./encoding";
+import { TABLE_HEADER, ANY_DEV_INSTRUCTIONS, DEV_INSTRUCTIONS_KEY } from "./toml-read";
+
+/** Line editing, not re-serialization: the user's comments and layout survive. */
+function dominantEol(content: string): "\r\n" | "\n" {
+  const crlf = (content.match(/\r\n/g) ?? []).length;
+  if (crlf === 0) return "\n";
+  const bareLf = (content.match(/\n/g) ?? []).length - crlf;
+  return crlf >= bareLf ? "\r\n" : "\n";
+}
+
+function splitLines(content: string): string[] {
+  return content.replace(/\r\n/g, "\n").split("\n");
+}
+
+/**
+ * A leading UTF-8 BOM, split off so line editing never steps over it.
+ *
+ * Codex reads config.toml with Rust `toml_edit`, which accepts a BOM at byte 0 and
+ * nowhere else. Inserting the generated block at line index 0 pushed the BOM down
+ * to byte 58, the write reported success because our own byte comparison matched
+ * what we intended to write, and the next parse failed with
+ * "Expected a key but found (0xEF)" — a config file the user could no longer load,
+ * produced by a write that told them it worked.
+ *
+ * Editors on Windows write this byte routinely, so the file is not exotic.
+ */
+function splitBom(content: string): { bom: string; body: string } {
+  return content.startsWith("\ufeff")
+    ? { bom: "\ufeff", body: content.slice(1) }
+    : { bom: "", body: content };
+}
+
+function joinLines(lines: string[], eol: "\r\n" | "\n"): string {
+  const text = lines.join("\n");
+  return eol === "\n" ? text : text.replace(/\n/g, "\r\n");
+}
+
+function firstTableIndex(lines: string[]): number {
+  const idx = lines.findIndex(l => TABLE_HEADER.test(l));
+  return idx === -1 ? lines.length : idx;
+}
+
+/** Set a root-scope boolean, inserting above the first table when absent. */
+export function setRootBool(content: string, key: string, value: boolean): string {
+  const eol = dominantEol(content);
+  const { bom, body } = splitBom(content);
+  const lines = splitLines(body);
+  const limit = firstTableIndex(lines);
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^(\\s*${escaped}\\s*=\\s*)(?:true|false)(\\s*(?:#.*)?)$`);
+  for (let i = 0; i < limit; i += 1) {
+    const m = pattern.exec(lines[i]!);
+    if (m) {
+      lines[i] = `${m[1]}${value}${m[2]}`;
+      return bom + joinLines(lines, eol);
+    }
+  }
+  lines.splice(limit, 0, `${key} = ${value}`);
+  return bom + joinLines(lines, eol);
+}
+
+/**
+ * Set or REMOVE a root-scope basic string. `null` removes the key.
+ *
+ * Removal is what selecting the default variant does, and it has to be a real deletion
+ * rather than an empty string: `model_instructions_file = ""` is a path Codex would try
+ * to read, not an absent setting.
+ */
+export function setRootString(content: string, key: string, value: string | null): string {
+  const eol = dominantEol(content);
+  const { bom, body } = splitBom(content);
+  const lines = splitLines(body);
+  const limit = firstTableIndex(lines);
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^\\s*${escaped}\\s*=\\s*"[^"]*"\\s*(?:#.*)?$`);
+  for (let i = 0; i < limit; i += 1) {
+    if (!pattern.test(lines[i]!)) continue;
+    if (value === null) lines.splice(i, 1);
+    else lines[i] = `${key} = ${encodeBasicString(value)}`;
+    return bom + joinLines(lines, eol);
+  }
+  if (value === null) return bom + joinLines(lines, eol);
+  lines.splice(limit, 0, `${key} = ${encodeBasicString(value)}`);
+  return bom + joinLines(lines, eol);
+}
+
+/** Set a boolean inside `[table]`, appending the table when absent. */
+export function setTableBool(content: string, table: string, key: string, value: boolean): string {
+  const eol = dominantEol(content);
+  const { bom, body } = splitBom(content);
+  const lines = splitLines(body);
+  const escaped = table.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const start = lines.findIndex(l => new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`).test(l));
+  if (start === -1) {
+    const tail = lines.length > 0 && lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
+    lines.splice(tail, 0, `[${table}]`, `${key} = ${value}`);
+    return bom + joinLines(lines, eol);
+  }
+  const keyEscaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^(\\s*${keyEscaped}\\s*=\\s*)(?:true|false)(\\s*(?:#.*)?)$`);
+  let end = start + 1;
+  while (end < lines.length && !TABLE_HEADER.test(lines[end]!)) end += 1;
+  for (let i = start + 1; i < end; i += 1) {
+    const m = pattern.exec(lines[i]!);
+    if (m) {
+      lines[i] = `${m[1]}${value}${m[2]}`;
+      return bom + joinLines(lines, eol);
+    }
+  }
+  lines.splice(end, 0, `${key} = ${value}`);
+  return bom + joinLines(lines, eol);
+}
+
+/**
+ * Replace, insert, or remove the generated two-line block. Canonical form is
+ * marker + assignment at the top of the document; replacement is "find the
+ * marker, replace the next line" rather than a span search.
+ */
+export function setProjection(content: string | null, projection: string | null): string {
+  const base = content ?? "";
+  const eol = dominantEol(base);
+  // The BOM is held aside for the whole edit. This is the function that produced
+  // the corruption: the insert below is at index 0, which put the marker line
+  // ahead of a byte that is only legal at byte 0.
+  const { bom, body } = splitBom(base);
+  const lines = splitLines(body);
+  const limit = firstTableIndex(lines);
+
+  let markerAt = -1;
+  for (let i = 0; i < limit; i += 1) {
+    if (i > 0 && lines[i - 1]!.includes(OCX_SECTION_MARKER) && ANY_DEV_INSTRUCTIONS.test(lines[i]!)) {
+      markerAt = i - 1;
+      break;
+    }
+  }
+
+  if (markerAt !== -1) {
+    if (projection === null) lines.splice(markerAt, 2);
+    else lines[markerAt + 1] = `${DEV_INSTRUCTIONS_KEY} = ${encodeBasicString(projection)}`;
+    return bom + joinLines(lines, eol);
+  }
+
+  if (projection === null) return bom + joinLines(lines, eol);
+  lines.splice(0, 0, OCX_SECTION_MARKER, `${DEV_INSTRUCTIONS_KEY} = ${encodeBasicString(projection)}`);
+  return bom + joinLines(lines, eol);
+}
+
+
+/** Remove an unowned or reshaped `developer_instructions` from the root scope. */
+export function removeUnownedProjection(content: string): string {
+  const eol = dominantEol(content);
+  const lines = splitLines(content);
+  const limit = firstTableIndex(lines);
+  for (let i = 0; i < limit; i += 1) {
+    if (!ANY_DEV_INSTRUCTIONS.test(lines[i]!)) continue;
+    const marked = i > 0 && lines[i - 1]!.includes(OCX_SECTION_MARKER);
+    lines.splice(marked ? i - 1 : i, marked ? 2 : 1);
+    return joinLines(lines, eol);
+  }
+  return joinLines(lines, eol);
+}