@bitkyc08/opencodex 2.16.0 → 2.17.0

package/src/integrations/writer.ts

@@ -9,6 +9,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
  */
+import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { isLoopbackHostname } from "../codex/inject";
@@ -23,7 +24,8 @@ import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
-import { patchOmpYamlSource } from "./omp-yaml-source";
+import { patchYamlFragmentSource, sourcePrunableYamlContainers } from "./omp-yaml-source";
+import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
 export type RefusalReason =
   | "not_installed"
@@ -66,6 +68,8 @@ export interface IntegrationWriteInput {
   home?: string;
   store?: IntegrationStateStore;
   io?: IntegrationIO;
+  /** Frozen once by the async coordinator; synchronous callers may omit it. */
+  resolvedPaths?: { configPath: string; detectDir: string };
 }
 
 export interface IntegrationRestoreInput extends IntegrationWriteInput {
@@ -169,11 +173,13 @@ function snapshotAbsPath(store: IntegrationStateStore, entry: JournalEntry): str
   return snapshot.kind === "stored" ? snapshot.path : undefined;
 }
 
-function ompFragmentValue(contribution: ManagedContribution): unknown | undefined {
+function sourcePreservingFragmentValue(
+  contribution: ManagedContribution,
+  path: readonly string[],
+): unknown | undefined {
   const fragment = contribution.fragments.find(item => (
-    item.path.length === 2
-    && item.path[0] === "providers"
-    && item.path[1] === "opencodex"
+    item.path.length === path.length
+    && item.path.every((key, index) => key === path[index])
   ));
   return fragment?.value;
 }
@@ -194,7 +200,7 @@ function preflight(input: IntegrationWriteInput) {
    */
   let configPath: string;
   try {
-    configPath = spec.configPath(input.env, input.home);
+    configPath = input.resolvedPaths?.configPath ?? spec.configPath(input.env, input.home);
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
@@ -239,7 +245,7 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   if (pre.failed) return pre.failed;
   const { store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } = pre;
 
-  if (io.statKind(spec.detectDir(input.env, input.home)) !== "dir") {
+  if (io.statKind(input.resolvedPaths?.detectDir ?? spec.detectDir(input.env, input.home)) !== "dir") {
     return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
   }
   if (isLoopbackOnly(clientId) && !isLoopbackHostname(input.config.hostname)) {
@@ -294,11 +300,16 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   const nextDocument = mergeContribution(base, contribution);
   let text: string;
   try {
-    if (clientId === "omp" && before !== null) {
-      const value = ompFragmentValue(contribution);
+    if (spec.sourcePreservingYaml && before !== null) {
+      const value = sourcePreservingFragmentValue(contribution, spec.sourcePreservingYaml.path);
       const patched = value === undefined
         ? null
-        : patchOmpYamlSource(before, { kind: "upsert", value }, nextDocument);
+        : patchYamlFragmentSource(
+            before,
+            spec.sourcePreservingYaml.path,
+            { kind: "upsert", value },
+            nextDocument,
+          );
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
           `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so it was left alone`);
@@ -344,7 +355,7 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
 export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, exportSpec, configPath, before, parsed, record, classified } = pre;
+  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, record, classified } = pre;
 
   if (classified.state === "absent") {
     return { ok: true, changed: false, state: "absent", clientId, message: "not applied" };
@@ -377,21 +388,32 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
    * json client classifies a sibling edit as stale (#1631) — which is why the
    * removal runs against the document as parsed NOW, and the re-serialize is
    * value-safe because non-round-tripping numbers were refused at parse time.
+   * Source-preserving YAML clients additionally compute which recorded
+   * containers are still source-empty before pruning, so a later sibling or
+   * comment makes its ancestor user-owned without protecting our leaf.
    */
+  const recordedCreated = record!.createdContainers ?? [];
+  const prunableCreated = spec.sourcePreservingYaml && before !== null
+    ? sourcePrunableYamlContainers(before, spec.sourcePreservingYaml.path, recordedCreated)
+    : recordedCreated;
+  if (prunableCreated === null) {
+    return refuse(clientId, "unsafe", "unsafe",
+      `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+  }
   const { doc, removed } = removeFragments(
     parsed,
     record!.fragmentPaths,
-    new Set(record!.createdContainers ?? []),
+    new Set(prunableCreated),
   );
   if (!removed) {
     return { ok: true, changed: false, state: "absent", clientId, message: "nothing to remove" };
   }
   let text: string;
   try {
-    if (clientId === "omp" && before !== null) {
-      const patched = patchOmpYamlSource(before, {
+    if (spec.sourcePreservingYaml && before !== null) {
+      const patched = patchYamlFragmentSource(before, spec.sourcePreservingYaml.path, {
         kind: "remove",
-        removeEmptyProviders: record!.createdContainers?.includes("providers") === true,
+        createdContainers: prunableCreated,
       }, doc);
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
@@ -435,7 +457,8 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
 
   const clientId = entry.clientId;
-  const resolvedPath = INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
+  const resolvedPath = input.resolvedPaths?.configPath
+    ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
   // Restore acts on the path the operation was journaled against. Resolving a
   // different path here would let an operation recorded for one home delete a
   // file in another.
@@ -533,3 +556,105 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     snapshotPath: snapshotAbsPath(store, restoreEntry),
   });
 }
+
+export interface CoordinatedIntegrationOptions {
+  lockSeams?: IntegrationWriterLockSeams;
+}
+
+/** Freeze all mutable resolution seams before the first lock await. */
+type FrozenIntegrationInput = IntegrationWriteInput & {
+  store: IntegrationStateStore;
+  io: IntegrationIO;
+  env: NodeJS.ProcessEnv;
+  home: string;
+  resolvedPaths: { configPath: string; detectDir: string };
+};
+
+function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
+  const env = { ...(input.env ?? process.env) };
+  const home = input.home ?? homedir();
+  const store = input.store ?? createIntegrationStateStore();
+  const io = input.io ?? defaultIntegrationIO(store);
+  const spec = INTEGRATION_CLIENTS[input.clientId];
+  const resolvedPaths = {
+    configPath: spec.configPath(env, home),
+    detectDir: spec.detectDir(env, home),
+  };
+  return { ...input, env, home, store, io, resolvedPaths };
+}
+
+function tryFreezeIntegrationInput(input: IntegrationWriteInput):
+  | { ok: true; value: FrozenIntegrationInput }
+  | { ok: false; refusal: WriteRefused } {
+  try {
+    return { ok: true, value: freezeIntegrationInput(input) };
+  } catch (error) {
+    if (!(error instanceof ClientPathError)) throw error;
+    return {
+      ok: false,
+      refusal: refuse(input.clientId, "unsafe", "unsafe", error.message),
+    };
+  }
+}
+
+async function coordinatedWrite(
+  input: IntegrationWriteInput,
+  operation: (frozen: IntegrationWriteInput) => WriteOutcome,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  const prepared = tryFreezeIntegrationInput(input);
+  if (!prepared.ok) return prepared.refusal;
+  const frozen = prepared.value;
+  const spec = INTEGRATION_CLIENTS[frozen.clientId];
+  if (!spec.writerLock) return operation(frozen);
+
+  // An absent client home is not created merely to acquire a sibling lock.
+  if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
+    return operation(frozen);
+  }
+  return withIntegrationWriterLock(
+    frozen.resolvedPaths.configPath,
+    async () => operation(frozen),
+    options?.lockSeams,
+    spec.writerLock.suffix,
+  );
+}
+
+export function applyIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, applyIntegration, options);
+}
+
+export function disableIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, disableIntegration, options);
+}
+
+export async function restoreIntegrationCoordinated(
+  input: IntegrationRestoreInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  const prepared = tryFreezeIntegrationInput(input);
+  if (!prepared.ok) return prepared.refusal;
+  const frozen = prepared.value;
+  const spec = INTEGRATION_CLIENTS[frozen.clientId];
+  if (!spec.writerLock) return restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
+    return refuse(
+      frozen.clientId,
+      "unsafe",
+      "unsafe",
+      `${frozen.resolvedPaths.detectDir} is missing; restore will not create the client home`,
+    );
+  }
+  return withIntegrationWriterLock(
+    frozen.resolvedPaths.configPath,
+    async () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift }),
+    options?.lockSeams,
+    spec.writerLock.suffix,
+  );
+}

package/src/lib/shadow-call.ts

@@ -32,23 +32,15 @@ export function isShadowSourceModel(modelId: string, configured?: unknown): bool
 /**
  * Decide whether a matching source model should use the opt-in intercept.
  *
- * Codex 0.145.0+ identifies normal user turns and maintenance requests in
- * x-codex-turn-metadata. Only an explicit normal turn bypasses interception;
- * missing or unrecognized metadata retains the legacy opt-in prefix behavior.
+ * Before Codex 0.147.0 this checked x-codex-turn-metadata and exempted
+ * request_kind "turn". Codex 0.147.0 can label background helper calls as
+ * "turn", causing them to bypass the intercept (#1684). The fix is to
+ * intercept every configured shadow source model unconditionally — the model
+ * slug alone is a sufficient signal.
  */
 export function shouldInterceptShadowCall(
   modelId: string,
   configured: unknown,
-  headers: Headers,
 ): boolean {
-  if (!isShadowSourceModel(modelId, configured)) return false;
-  const rawMetadata = headers.get("x-codex-turn-metadata");
-  if (rawMetadata === null) return true;
-
-  try {
-    const parsed = JSON.parse(rawMetadata) as { request_kind?: unknown };
-    return parsed?.request_kind !== "turn";
-  } catch {
-    return true;
-  }
+  return isShadowSourceModel(modelId, configured);
 }

package/src/server/management/integration-routes.ts

@@ -19,13 +19,14 @@ import {
 import { readIntegrationState } from "../../integrations/state";
 import { createIntegrationStateStore, type IntegrationStateStore } from "../../integrations/store";
 import {
-  applyIntegration,
-  disableIntegration,
-  restoreIntegration,
+  applyIntegrationCoordinated,
+  disableIntegrationCoordinated,
+  restoreIntegrationCoordinated,
   type IntegrationRestoreInput,
   type IntegrationWriteInput,
   type WriteRefused,
 } from "../../integrations/writer";
+import { IntegrationWriterLockBusyError, type IntegrationWriterLockSeams } from "../../integrations/writer-lock";
 import { jsonResponse } from "../auth-cors";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import type { ManagementContext } from "./context";
@@ -37,9 +38,9 @@ const INTEGRATION_MUTATION_JOIN_MS = 120_000;
 export const INTEGRATION_MUTATION_TERMINAL_MS = 10 * 60_000;
 
 type IntegrationStateRecord = Awaited<ReturnType<typeof readIntegrationState>>;
-type ApplyResult = Awaited<ReturnType<typeof applyIntegration>>;
-type DisableResult = Awaited<ReturnType<typeof disableIntegration>>;
-type RestoreResult = Awaited<ReturnType<typeof restoreIntegration>>;
+type ApplyResult = Awaited<ReturnType<typeof applyIntegrationCoordinated>>;
+type DisableResult = Awaited<ReturnType<typeof disableIntegrationCoordinated>>;
+type RestoreResult = Awaited<ReturnType<typeof restoreIntegrationCoordinated>>;
 
 export type IntegrationStateEnvelope = {
   clientId: IntegrationClientId;
@@ -95,6 +96,7 @@ class IntegrationMutationBusyError extends Error {
 const integrationMutationFlights = new Map<IntegrationClientId, IntegrationMutationFlight>();
 let integrationMutationTestHooks: {
   io?: IntegrationIO;
+  lockSeams?: IntegrationWriterLockSeams;
   /**
    * Bind every read and write in the request to one store. Without this a
    * route test could isolate the writer but not the journal listing or the
@@ -185,6 +187,7 @@ function runIntegrationMutationFlight<T>(
 export function setIntegrationMutationFlightTestHooks(
   hooks: {
     io?: IntegrationIO;
+    lockSeams?: IntegrationWriterLockSeams;
     /** Binds the WHOLE request — reads, writes and journal — to one store. */
     store?: IntegrationStateStore;
     run?: (operation: () => Promise<unknown>) => Promise<unknown>;
@@ -433,6 +436,7 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
 
     const opId = parsed.opId.trim();
     const confirmDrift = parsed.confirmDrift ?? false;
+    let restoreClientId: IntegrationClientId | undefined;
     try {
       const store = integrationStore();
       const operation = store.findOperation(opId);
@@ -443,6 +447,7 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
           opId,
         }, 404, req, ctx.config);
       }
+      restoreClientId = operation.clientId;
       const snapshot = store.readSnapshot(operation);
       if (snapshot.kind === "expired") {
         return jsonResponse({
@@ -462,7 +467,9 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
         operation.clientId,
         `restore:${opId}:${confirmDrift}`,
         writeInput.io?.now ?? Date.now,
-        () => Promise.resolve(restoreIntegration(restoreInput)),
+        () => restoreIntegrationCoordinated(restoreInput, {
+          lockSeams: integrationMutationTestHooks?.lockSeams,
+        }),
       );
       if (!result.ok) {
         /*
@@ -478,11 +485,11 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
       }
       return jsonResponse(result satisfies IntegrationRestoreEnvelope, 200, req, ctx.config);
     } catch (error) {
-      if (error instanceof IntegrationMutationBusyError) {
+      if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError) {
         return jsonResponse({
           error: "integration mutation busy",
           code: "integration_mutation_busy",
-          clientId: error.clientId,
+          clientId: restoreClientId ?? (error instanceof IntegrationMutationBusyError ? error.clientId : undefined),
         }, 409, req, ctx.config);
       }
       return internalErrorResponse(error, ctx);
@@ -519,18 +526,18 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
       requestedClient,
       parsed.enabled ? "apply" : "disable",
       input.io?.now ?? Date.now,
-      () => Promise.resolve(parsed.enabled
-        ? applyIntegration(input)
-        : disableIntegration(input)),
+      () => parsed.enabled
+        ? applyIntegrationCoordinated(input, { lockSeams: integrationMutationTestHooks?.lockSeams })
+        : disableIntegrationCoordinated(input, { lockSeams: integrationMutationTestHooks?.lockSeams }),
     );
     if (!result.ok) return writerFailureResponse(requestedClient, result, ctx);
     return jsonResponse(result satisfies IntegrationToggleEnvelope, 200, req, ctx.config);
   } catch (error) {
-    if (error instanceof IntegrationMutationBusyError) {
+    if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError) {
       return jsonResponse({
         error: "integration mutation busy",
         code: "integration_mutation_busy",
-        clientId: error.clientId,
+        clientId: requestedClient,
       }, 409, req, ctx.config);
     }
     return internalErrorResponse(error, ctx);

package/src/server/responses/core.ts

@@ -1582,7 +1582,6 @@ async function handleResponsesInner(
   if (_sci?.enabled && _sci.model && shouldInterceptShadowCall(
     parsed.modelId,
     _sci.sourceModels,
-    req.headers,
   )) {
     const _sciOriginal = parsed.modelId;
     parsed.modelId = _sci.model;

package/src/types.ts

@@ -756,11 +756,11 @@ export interface OcxConfig {
    */
   customModelCatalogMigration?: unknown;
   /**
-   * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
-   * commit messages, skill orchestration) to a user-chosen model. Default intercepted
-   * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
-   * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
-   * Normal Codex turns identified by request_kind=turn are never rewritten.
+  * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
+  * commit messages, skill orchestration) to a user-chosen model. Default intercepted
+  * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
+  * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
+   * All requests for configured shadow source models are intercepted unconditionally.
    */
   shadowCallIntercept?: {
     /** When true, requests for known shadow/helper source models are rewritten to the configured model. */