@bitkyc08/opencodex 2.7.42 → 2.7.43

package/src/server/responses-image-gen-repair.ts

@@ -0,0 +1,118 @@
+import { collectResponsesToolGroups } from "../responses/tool-groups";
+import { relaySseWithPayloadRewrite, type SsePayloadRewrite } from "./sse-payload-rewrite";
+
+interface NamespacedTool {
+  namespace: string;
+  name: string;
+}
+
+const IMAGE_GEN_NAMESPACE = "image_gen";
+const IMAGE_GEN_DOTTED_PREFIX = `${IMAGE_GEN_NAMESPACE}.`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Restrict the generic bridge map to Codex's standalone image namespace and accept the dotted
+ * alias emitted by earlier compatibility attempts. Legacy flat dotted declarations are recovered
+ * from the raw request because the generic parser does not assign them a namespace. Exact declared
+ * names avoid splitting arbitrary double-underscore function names that belong to unrelated tools.
+ */
+export function imageGenToolCallAliases(
+  toolNsMap: ReadonlyMap<string, NamespacedTool>,
+  requestBody?: unknown,
+): Map<string, NamespacedTool> {
+  const aliases = new Map<string, NamespacedTool>();
+  for (const [wireName, tool] of toolNsMap) {
+    if (tool.namespace !== IMAGE_GEN_NAMESPACE) continue;
+    aliases.set(wireName, tool);
+    aliases.set(`${tool.namespace}.${tool.name}`, tool);
+  }
+  for (const group of collectResponsesToolGroups(requestBody)) {
+    for (const tool of group) {
+      if (
+        !isPlainObject(tool)
+        || tool.type !== "function"
+        || typeof tool.name !== "string"
+        || !tool.name.startsWith(IMAGE_GEN_DOTTED_PREFIX)
+        || tool.name.length === IMAGE_GEN_DOTTED_PREFIX.length
+      ) continue;
+      const localName = tool.name.slice(IMAGE_GEN_DOTTED_PREFIX.length);
+      const target = { namespace: IMAGE_GEN_NAMESPACE, name: localName };
+      aliases.set(`${IMAGE_GEN_NAMESPACE}__${localName}`, target);
+      aliases.set(tool.name, target);
+    }
+  }
+  return aliases;
+}
+
+/** Recursively restore only exact image-gen function-call aliases in a parsed Responses payload. */
+function restoreImageGenCalls(
+  value: unknown,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreImageGenCalls(entry, aliases);
+      changed ||= result.changed;
+      return result.value;
+    });
+    return changed ? { value: restored, changed: true } : { value, changed: false };
+  }
+  if (!isPlainObject(value)) return { value, changed: false };
+
+  let changed = false;
+  const restored: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const result = restoreImageGenCalls(entry, aliases);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  const name = typeof value.name === "string" ? value.name : undefined;
+  const target = value.type === "function_call" && name ? aliases.get(name) : undefined;
+  if (target) {
+    restored.name = target.name;
+    restored.namespace = target.namespace;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+/** Restore image-gen function calls in a non-streaming Responses JSON document. */
+export function restoreImageGenCallsInJson(
+  text: string,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): string {
+  if (aliases.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreImageGenCalls(payload, aliases);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}
+
+/** Payload rewrite for composition with other client-facing SSE transforms. */
+export function createImageGenCallRestoreRewrite(
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): SsePayloadRewrite | undefined {
+  if (aliases.size === 0) return undefined;
+  return (payload) => restoreImageGenCallsInJson(payload, aliases);
+}
+
+/**
+ * Restore upstream-safe image-gen aliases only on the client-facing SSE branch. The inspection and
+ * continuation-cache branch must retain raw upstream names so a replay can be sent back unchanged.
+ */
+export function relaySseWithImageGenCallRestore(
+  body: ReadableStream<Uint8Array>,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): ReadableStream<Uint8Array> {
+  const rewrite = createImageGenCallRestoreRewrite(aliases);
+  return rewrite ? relaySseWithPayloadRewrite(body, rewrite) : body;
+}

package/src/server/responses-item-id-repair.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { ResponsesItemIdRepairConfig } from "../types";
+import { relaySseWithPayloadRewrite, type SsePayloadRewrite } from "./sse-payload-rewrite";
 
 type RepairableItemType = "message" | "reasoning";
 
@@ -35,44 +36,6 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-function nextSseBlock(buffer: string): { block: string; delimiter: string; rest: string } | null {
-  const match = buffer.match(/\r?\n\r?\n/);
-  if (!match || match.index === undefined) return null;
-  return {
-    block: buffer.slice(0, match.index),
-    delimiter: match[0],
-    rest: buffer.slice(match.index + match[0].length),
-  };
-}
-
-function sseDataPayload(block: string): string | null {
-  const data: string[] = [];
-  for (const line of block.split(/\r?\n/)) {
-    if (!line.startsWith("data:")) continue;
-    const value = line.slice(5);
-    data.push(value.startsWith(" ") ? value.slice(1) : value);
-  }
-  return data.length > 0 ? data.join("\n") : null;
-}
-
-function replaceSseDataPayload(block: string, payload: string): string {
-  const newline = block.includes("\r\n") ? "\r\n" : "\n";
-  const lines = block.split(/\r?\n/);
-  const rewritten: string[] = [];
-  let replaced = false;
-  for (const line of lines) {
-    if (!line.startsWith("data:")) {
-      rewritten.push(line);
-      continue;
-    }
-    if (!replaced) {
-      rewritten.push(`data: ${payload}`);
-      replaced = true;
-    }
-  }
-  return replaced ? rewritten.join(newline) : block;
-}
-
 function asOutputIndex(value: unknown): number | null {
   return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
 }
@@ -221,57 +184,19 @@ function repairEventPayload(
  *   type에 재사용해도 function_call id/call_id는 보존된다. opt-in 게이트웨이는 sequential streams에서도
  *   고유한 canonical id를 얻지만, 보정이 필요한 경우에만 JS stream 재작성 비용을 지불한다.
  */
+/** Stateful payload rewrite for composition with other client-facing SSE transforms. */
+export function createResponsesItemIdPayloadRewrite(
+  config: ResponsesItemIdRepairConfig,
+): SsePayloadRewrite {
+  const state = createRepairState(config);
+  return (payload) => repairEventPayload(payload, state);
+}
+
 export function relaySseWithResponsesItemIdRepair(
   body: ReadableStream<Uint8Array>,
   config: ResponsesItemIdRepairConfig,
 ): ReadableStream<Uint8Array> {
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  const encoder = new TextEncoder();
-  const state = createRepairState(config);
-  let buffer = "";
-
-  const emitProcessedBlocks = (
-    controller: ReadableStreamDefaultController<Uint8Array>,
-    flushFinal = false,
-  ): void => {
-    let next: { block: string; delimiter: string; rest: string } | null;
-    while ((next = nextSseBlock(buffer))) {
-      buffer = next.rest;
-      const payload = sseDataPayload(next.block);
-      const repairedPayload = payload ? repairEventPayload(payload, state) : undefined;
-      const block = payload && repairedPayload !== undefined && repairedPayload !== payload
-        ? replaceSseDataPayload(next.block, repairedPayload)
-        : next.block;
-      controller.enqueue(encoder.encode(block + next.delimiter));
-    }
-    if (flushFinal && buffer.length > 0) {
-      const payload = sseDataPayload(buffer);
-      const repairedPayload = payload ? repairEventPayload(payload, state) : undefined;
-      const block = payload && repairedPayload !== undefined && repairedPayload !== payload
-        ? replaceSseDataPayload(buffer, repairedPayload)
-        : buffer;
-      controller.enqueue(encoder.encode(block));
-      buffer = "";
-    }
-  };
-
-  return new ReadableStream<Uint8Array>({
-    async pull(controller) {
-      const { done, value } = await reader.read();
-      if (done) {
-        buffer += decoder.decode();
-        emitProcessedBlocks(controller, true);
-        controller.close();
-        return;
-      }
-      buffer += decoder.decode(value, { stream: true });
-      emitProcessedBlocks(controller);
-    },
-    cancel(reason) {
-      reader.cancel(reason).catch(() => {});
-    },
-  });
+  return relaySseWithPayloadRewrite(body, createResponsesItemIdPayloadRewrite(config));
 }
 
 export function hasResponsesItemIdRepair(config: ResponsesItemIdRepairConfig | undefined): boolean {

package/src/server/sse-payload-rewrite.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared client-facing SSE payload rewrite shell.
+ *
+ * Multiple opt-in transforms (image-gen namespace restore, item-id repair, …) compose into one
+ * parse/stringify pass so a tee'd stream is not re-framed twice per event.
+ */
+
+export type SsePayloadRewrite = (payload: string) => string;
+
+/** Split one complete SSE event block while retaining its original blank-line delimiter. */
+export function nextSseBlock(buffer: string): { block: string; delimiter: string; rest: string } | null {
+  const match = buffer.match(/\r?\n\r?\n/);
+  if (!match || match.index === undefined) return null;
+  return {
+    block: buffer.slice(0, match.index),
+    delimiter: match[0],
+    rest: buffer.slice(match.index + match[0].length),
+  };
+}
+
+/** Join all data lines from one SSE event according to the event-stream field rules. */
+export function sseDataPayload(block: string): string | null {
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    data.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  return data.length > 0 ? data.join("\n") : null;
+}
+
+/** Replace an SSE event's data field while preserving non-data fields and newline style. */
+export function replaceSseDataPayload(block: string, payload: string): string {
+  const newline = block.includes("\r\n") ? "\r\n" : "\n";
+  const lines = block.split(/\r?\n/);
+  const rewritten: string[] = [];
+  let replaced = false;
+  for (const line of lines) {
+    if (!line.startsWith("data:")) {
+      rewritten.push(line);
+      continue;
+    }
+    if (!replaced) {
+      rewritten.push(`data: ${payload}`);
+      replaced = true;
+    }
+  }
+  return replaced ? rewritten.join(newline) : block;
+}
+
+/** Apply rewrites left-to-right; empty list is identity. */
+export function composeSsePayloadRewrites(...rewrites: SsePayloadRewrite[]): SsePayloadRewrite {
+  if (rewrites.length === 0) return (payload) => payload;
+  if (rewrites.length === 1) return rewrites[0]!;
+  return (payload) => {
+    let next = payload;
+    for (const rewrite of rewrites) next = rewrite(next);
+    return next;
+  };
+}
+
+/**
+ * Relay an SSE body through a single JS pull wrapper, rewriting each event's data payload in place.
+ * Non-data fields and framing are preserved; invalid JSON payloads are left to the rewrite callback.
+ */
+export function relaySseWithPayloadRewrite(
+  body: ReadableStream<Uint8Array>,
+  rewrite: SsePayloadRewrite,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+
+  const emitProcessedBlocks = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    flushFinal = false,
+  ): void => {
+    let next: { block: string; delimiter: string; rest: string } | null;
+    while ((next = nextSseBlock(buffer))) {
+      buffer = next.rest;
+      const payload = sseDataPayload(next.block);
+      const rewrittenPayload = payload ? rewrite(payload) : undefined;
+      const block = payload && rewrittenPayload !== undefined && rewrittenPayload !== payload
+        ? replaceSseDataPayload(next.block, rewrittenPayload)
+        : next.block;
+      controller.enqueue(encoder.encode(block + next.delimiter));
+    }
+    if (flushFinal && buffer.length > 0) {
+      const payload = sseDataPayload(buffer);
+      const rewrittenPayload = payload ? rewrite(payload) : undefined;
+      const block = payload && rewrittenPayload !== undefined && rewrittenPayload !== payload
+        ? replaceSseDataPayload(buffer, rewrittenPayload)
+        : buffer;
+      controller.enqueue(encoder.encode(block));
+      buffer = "";
+    }
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        buffer += decoder.decode();
+        emitProcessedBlocks(controller, true);
+        controller.close();
+        return;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      emitProcessedBlocks(controller);
+    },
+    cancel(reason) {
+      reader.cancel(reason).catch(() => {});
+    },
+  });
+}

package/src/server/system-env.ts

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -6,6 +6,7 @@ import { resolveAutoContext, type AutoContextMode } from "../claude/context-wind
 import { PROXY_MARKER, defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import type { OcxConfig } from "../types";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 /**
  * Does the opencodex dummy marker belong in the system environment?
@@ -72,8 +73,10 @@ function writeShellEnvFile(port: number, config: OcxConfig, modelEnv: Record<str
   if (config.claudeCode?.alwaysEnableEffort === true) {
     lines.push(conditional("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1"));
   }
+  const shellEnvPath = getShellEnvFilePath();
+  recordOwnedConfigPath(getConfigDir(), shellEnvPath);
   mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
-  writeFileSync(getShellEnvFilePath(), lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+  writeFileSync(shellEnvPath, lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
 }
 
 function removeShellEnvFile(): void {
@@ -128,6 +131,19 @@ const SYSTEM_ENV_NAMES = [
   "ANTHROPIC_AUTH_TOKEN",
 ] as const;
 
+const MANAGED_SYSTEM_ENV_NAMES = new Set<string>([
+  ...SYSTEM_ENV_NAMES,
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_FABLE_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL",
+  "CLAUDE_CODE_MAX_CONTEXT_TOKENS",
+  "DISABLE_COMPACT",
+  "CLAUDE_CODE_AUTO_COMPACT_WINDOW",
+  "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT",
+]);
+
 interface SystemEnvTracking {
   pid: number;
   port: number;
@@ -147,7 +163,7 @@ export function getSystemEnvTrackingPath(): string {
 export function launchctlGetenv(name: string): string | undefined {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return undefined;
   try {
-    const value = execSync(`launchctl getenv ${name}`, { encoding: "utf8" }).trim();
+    const value = execFileSync("/bin/launchctl", ["getenv", name], { encoding: "utf8" }).trim();
     return value || undefined;
   } catch {
     return undefined;
@@ -160,22 +176,23 @@ function readTracking(): SystemEnvTracking | undefined {
     if (!Number.isInteger(tracking.port) || typeof tracking.pid !== "number" || typeof tracking.injectedAt !== "string") {
       return undefined;
     }
-    return tracking as SystemEnvTracking;
+    const injectedKeys = Array.isArray(tracking.injectedKeys)
+      ? [...new Set(tracking.injectedKeys.filter(
+        (name): name is string => typeof name === "string" && MANAGED_SYSTEM_ENV_NAMES.has(name),
+      ))]
+      : undefined;
+    return { ...tracking, injectedKeys } as SystemEnvTracking;
   } catch {
     return undefined;
   }
 }
 
-function shellArg(value: string): string {
-  return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
-}
-
 function setLaunchctlEnv(name: string, value: string): void {
-  execSync(`launchctl setenv ${name} ${shellArg(value)}`);
+  execFileSync("/bin/launchctl", ["setenv", name, value]);
 }
 
 function unsetLaunchctlEnv(name: string): void {
-  execSync(`launchctl unsetenv ${name}`);
+  execFileSync("/bin/launchctl", ["unsetenv", name]);
 }
 
 function ownedBaseUrl(port: number): string {
@@ -183,6 +200,7 @@ function ownedBaseUrl(port: number): string {
 }
 
 function writeTracking(port: number, injectedKeys: string[]): void {
+  recordOwnedConfigPath(getConfigDir(), getSystemEnvTrackingPath());
   mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
   writeFileSync(getSystemEnvTrackingPath(), JSON.stringify({
     pid: process.pid,

package/src/service.ts

@@ -34,6 +34,7 @@ import {
 import { defaultWinswEntry, installWinswService, startWinswService, stopWinswService, statusWinswRaw, uninstallWinswService, winswStatusSummary, WINSW_SERVICE_ID, WINSW_SHA256, WINSW_VERSION } from "./lib/winsw";
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from "./lib/win-paths";
+import { recordOwnedConfigPath } from "./lib/config-ownership";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -146,6 +147,7 @@ function writeServiceInstallState(backend: ServiceBackend = "scheduler"): void {
   };
   for (const path of serviceStatePaths()) {
     const dir = dirname(path);
+    recordOwnedConfigPath(getConfigDir(), path);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
     try { chmodSync(path, 0o600); } catch { /* best-effort */ }
@@ -254,6 +256,7 @@ function writeServiceApiTokenFile(): string | null {
   if (!token) return null;
   const path = serviceApiTokenFilePath();
   const dir = getConfigDir();
+  recordOwnedConfigPath(dir, path);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
   if (process.platform === "win32") hardenSecretDir(dir, { required: true });
   writeFileSync(path, `${token}\n`, { encoding: "utf8", mode: 0o600 });
@@ -1039,6 +1042,43 @@ function taskXmlHasPrefixedTag(xml: string, tag: string): boolean {
  * Absence means the documented schema default (#432); a present element must still
  * match exactly, so a malformed or explicitly unsafe value never reads as healthy.
  */
+/**
+ * Decode XML's five predefined entities, exactly once.
+ *
+ * Task Scheduler re-encodes element text when it exports a task, so a needle we
+ * escaped ourselves can never match its output (#608). Compare decoded values
+ * instead of encoded ones.
+ *
+ * The single pass is the point: decoding twice would turn `"` into `"`,
+ * letting a doubly-encoded value impersonate the expected launcher path.
+ */
+function taskXmlDecodeEntities(value: string): string {
+  return value.replace(/&(amp|lt|gt|quot|apos);/g, (_, name: string) => (
+    name === "amp" ? "&"
+      : name === "lt" ? "<"
+        : name === "gt" ? ">"
+          : name === "quot" ? "\""
+            : "'"
+  ));
+}
+
+/**
+ * Exactly one unprefixed `<tag>` whose DECODED text equals `expected`.
+ *
+ * Unlike taskXmlOptionalValueEquals(), an absent element is NOT a pass: these
+ * elements name what actually gets executed, so a missing <Command>/<Arguments>
+ * must fail the health check rather than inherit a schema default.
+ */
+function taskXmlDecodedValueEquals(xml: string, tag: string, expected: string): boolean {
+  // Same reasoning as the optional helper: `<t:Arguments>` must not read as absent.
+  if (taskXmlHasPrefixedTag(xml, tag)) return false;
+  if (taskXmlElementCount(xml, tag) !== 1) return false;
+  // `[^<]*` refuses nested markup, so a decoy inside a child element cannot match.
+  const value = new RegExp(`<${tag}(?:\\s[^>]*?)?>([^<]*)<\\/${tag}>`, "i").exec(xml)?.[1];
+  if (value === undefined) return false;
+  return taskXmlDecodeEntities(value).trim() === expected.trim();
+}
+
 function taskXmlOptionalValueEquals(xml: string, tag: string, expected: string): boolean {
   // Check the prefixed form first: treating `<t:Enabled>false</t:Enabled>` as an
   // omission would turn an explicitly disabled task into a healthy one.
@@ -1076,8 +1116,11 @@ export function windowsTaskRegistrationHealthy(
     && taskXmlOptionalValueEquals(settings, "Enabled", "true")
     && /<MultipleInstancesPolicy>\s*IgnoreNew\s*<\/MultipleInstancesPolicy>/i.test(settings)
     && /<ExecutionTimeLimit>\s*PT0S\s*<\/ExecutionTimeLimit>/i.test(settings)
-    && action.includes(`<Command>${taskXmlString(wscript)}</Command>`)
-    && action.includes(`<Arguments>${taskXmlString(`/b /nologo "${launcher}"`)}</Arguments>`);
+    // Compare decoded VALUES, not encodings: Task Scheduler canonicalizes the
+    // quotes we wrote as `&quot;` back to literal `"` on export, so an escaped
+    // needle never matched and a healthy task read as permanently stale (#608).
+    && taskXmlDecodedValueEquals(action, "Command", wscript)
+    && taskXmlDecodedValueEquals(action, "Arguments", `/b /nologo "${launcher}"`);
 }
 
 export interface WindowsSchedulerXmlState {
@@ -1112,6 +1155,7 @@ export function readWindowsSchedulerXmlState(
 function installLaunchd(): void {
   const dir = join(homedir(), "Library", "LaunchAgents");
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   const p = plistPath();
@@ -1148,6 +1192,7 @@ function writeServiceAssetWithRetry(path: string, content: string, encoding: "ut
 }
 
 function installWindows(): void {
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   // Transactional backend switch: installing the scheduler backend removes a native
@@ -1183,6 +1228,7 @@ function installWindows(): void {
  * reported) — never a silent fallback to the scheduler.
  */
 async function installWindowsNative(): Promise<void> {
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   let hadScheduler = false;
@@ -1321,6 +1367,7 @@ function installSystemd(): void {
   ensureUserBusEnv(); // reach the user bus over a bare SSH session (F9)
   const dir = unitDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   writeFileSync(unitPath(), buildUnit(), "utf8");

package/src/storage/cleanup-job.ts

@@ -0,0 +1,57 @@
+/**
+ * Single-flight wrapper for manual archived cleanup (management API).
+ *
+ * Shares the CODEX_HOME storage-mutation coordinator with trash restore and
+ * (Phase 3) policy-driven cleanup.
+ */
+import { resolveCodexHomeDir } from "../codex/home";
+import {
+  executeArchivedCleanup,
+  type CleanupResult,
+  type ExecuteCleanupOptions,
+} from "./cleanup";
+import {
+  resetStorageMutationCoordinatorForTests,
+  setStorageMutationCoordinatorTestHooks,
+  withStorageMutationSlot,
+  type StorageMutationCoordinatorTestHooks,
+} from "./storage-mutation-coordinator";
+
+export type CleanupJobTestHooks = StorageMutationCoordinatorTestHooks;
+
+export function setArchivedCleanupJobTestHooks(hooks: CleanupJobTestHooks | null): void {
+  setStorageMutationCoordinatorTestHooks(hooks);
+}
+
+export function resetArchivedCleanupJobForTests(): void {
+  resetStorageMutationCoordinatorForTests();
+}
+
+/**
+ * Run archived cleanup under the shared storage-mutation gate.
+ * Returns immediately with `storage_mutation_busy` when restore or another
+ * cleanup is in flight for the same CODEX_HOME.
+ */
+export async function runArchivedCleanupJob(
+  options: ExecuteCleanupOptions,
+): Promise<CleanupResult> {
+  const codexHome = options.codexHome ?? resolveCodexHomeDir();
+  const mode = options.mode;
+  const percent = options.percent;
+  const result = await withStorageMutationSlot("cleanup", codexHome, () =>
+    executeArchivedCleanup(options),
+  );
+  if (result && typeof result === "object" && "ok" in result && result.ok === false
+    && "error" in result && result.error === "storage_mutation_busy") {
+    return {
+      ok: false,
+      mode,
+      percent,
+      count: 0,
+      bytes: 0,
+      removedPaths: [],
+      error: "storage_mutation_busy",
+    };
+  }
+  return result as CleanupResult;
+}