@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/lab/subject/installation-salt.ts

@@ -4,6 +4,7 @@ import { dirname } from "node:path";
 import { labInstallationSaltPath, labRoot } from "../paths";
 
 const SALT_BYTES = 32;
+const installationSaltCache = new Map<string, Uint8Array>();
 const UNSUPPORTED_DIRECTORY_FSYNC_CODES = new Set(["EINVAL", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
 
 function readSaltFile(path: string): Uint8Array {
@@ -14,6 +15,25 @@ function readSaltFile(path: string): Uint8Array {
   return new Uint8Array(bytes);
 }
 
+function cacheSalt(path: string, salt: Uint8Array): Uint8Array {
+  const cached = new Uint8Array(salt);
+  installationSaltCache.set(path, cached);
+  return new Uint8Array(cached);
+}
+
+/** Read the existing local fingerprint salt without creating Lab state. */
+export function readExistingInstallationSalt(configDir?: string): Uint8Array | null {
+  const path = labInstallationSaltPath(configDir);
+  const cached = installationSaltCache.get(path);
+  if (cached) return new Uint8Array(cached);
+  try {
+    return cacheSalt(path, readSaltFile(path));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
 function removeStagingFile(path: string): void {
   try { unlinkSync(path); }
   catch (error) {
@@ -45,7 +65,7 @@ export function readInstallationSalt(configDir?: string): Uint8Array {
   const root = labRoot(configDir);
   mkdirSync(root, { recursive: true, mode: 0o700 });
 
-  try { return readSaltFile(path); }
+  try { return cacheSalt(path, readSaltFile(path)); }
   catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
   }
@@ -67,10 +87,10 @@ export function readInstallationSalt(configDir?: string): Uint8Array {
       linkSync(stagingPath, path);
       try { fsyncDirectory(dirname(path)); }
       catch { throw new Error("harness_failure: installation salt directory fsync failed"); }
-      return new Uint8Array(salt);
+      return cacheSalt(path, salt);
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      return readSaltFile(path);
+      return cacheSalt(path, readSaltFile(path));
     }
   } finally {
     if (fd !== undefined) {
@@ -78,4 +98,4 @@ export function readInstallationSalt(configDir?: string): Uint8Array {
     }
     removeStagingFile(stagingPath);
   }
-}
+}

package/src/lab/subject/protocol-subject.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { jcsStringify } from "../digest";
+import type { ProtocolSubjectV1 } from "../events/types";
+import type { ProtocolExecutionContextV1 } from "../conformance/types";
+
+/** Frozen CL-01 protocol compatibility identity. */
+export const PROTOCOL_COMPATIBILITY_VERSION = "protocol-v1";
+
+/** Adapter identity used by the deterministic protocol harness for a wire protocol. */
+export function protocolAdapterForUpstreamProtocol(protocol: string): string {
+  switch (protocol) {
+    case "openai-responses":
+      return "openai-responses";
+    case "anthropic-messages":
+      return "anthropic";
+    case "openai-chat":
+      return "openai-chat";
+    default:
+      throw new Error(`unsupported protocol identity: ${protocol}`);
+  }
+}
+
+/**
+ * Exact CL-01 behavior fingerprint for one protocol execution context.
+ *
+ * `effectiveAdapter` is optional so the harness keeps its historical mapping,
+ * while routing consumers may require an exact production adapter match. A
+ * provider-specific adapter that merely speaks an OpenAI-shaped wire therefore
+ * cannot borrow generic protocol evidence unless CL-01 actually produced the
+ * same adapter identity.
+ */
+export function protocolBehaviorFingerprintV1(
+  ctx: ProtocolExecutionContextV1,
+  effectiveAdapter = protocolAdapterForUpstreamProtocol(ctx.upstreamProtocol),
+): string {
+  const values = {
+    schemaVersion: 1,
+    resolverVersion: 1,
+    values: {
+      "wire.adapter": {
+        source: "lab_forced",
+        value: effectiveAdapter,
+      },
+      "wire.upstreamProtocol": {
+        source: "lab_forced",
+        value: ctx.upstreamProtocol,
+      },
+      "runtime.arch": {
+        source: "lab_forced",
+        value: process.arch,
+      },
+      "runtime.bunVersion": {
+        source: "lab_forced",
+        value: process.versions.bun ?? Bun.version,
+      },
+      "runtime.platform": {
+        source: "lab_forced",
+        value: process.platform,
+      },
+    },
+  };
+  return createHash("sha256").update(jcsStringify(values)).digest("hex");
+}
+
+/** Build the exact ProtocolSubjectV1 consumed by CL-01 projection. */
+export function buildProtocolSubjectV1(
+  ctx: ProtocolExecutionContextV1,
+  effectiveAdapter = protocolAdapterForUpstreamProtocol(ctx.upstreamProtocol),
+): ProtocolSubjectV1 {
+  return Object.freeze({
+    subjectSchemaVersion: 1,
+    subjectKind: "protocol",
+    opencodexCompatibilityVersion: PROTOCOL_COMPATIBILITY_VERSION,
+    effectiveAdapter,
+    inboundProtocol: ctx.inboundProtocol,
+    upstreamProtocol: ctx.upstreamProtocol,
+    surface: ctx.surface,
+    behaviorFingerprint: protocolBehaviorFingerprintV1(ctx, effectiveAdapter),
+  });
+}

package/src/lab/subject/route-subject.ts

@@ -34,6 +34,7 @@ export function buildRouteSubjectV1(
   routeContext: LabRouteContext,
   destination: LabDestinationV1,
   configDir?: string,
+  installationSalt?: Uint8Array | string,
 ): RouteSubjectV1 {
   if (!routeContext.providerInstanceKey) throw new Error("harness_failure: provider instance identity is required");
   if (!/^[0-9a-f]{64}$/.test(routeContext.opencodexCompatibilityVersion)) {
@@ -44,7 +45,7 @@ export function buildRouteSubjectV1(
   if (adapterValue !== routeContext.effectiveAdapter || protocolValue !== routeContext.upstreamProtocol) {
     throw new Error("harness_failure: behavior resolver output does not match exact route");
   }
-  const salt = readInstallationSalt(configDir);
+  const salt = installationSalt ?? readInstallationSalt(configDir);
   const providerInstanceFingerprint = localFingerprint("providerInstance", routeContext.providerInstanceKey, salt);
   const dependencies = canonicalDependencies(routeContext.dependencies);
   const subject: RouteSubjectV1 = {

package/src/lib/fabric-task-execution-authority.ts

@@ -0,0 +1,7 @@
+import type { TrustedFabricPatchExecutor } from "../lab/fabric/types";
+import { isHostIssuedFabricPatchExecutor } from "./fabric-task-host";
+
+/** Trusted exact-route fabric patch executor recognition facade. */
+export function isTrustedFabricPatchExecutor(value: unknown): value is TrustedFabricPatchExecutor {
+  return isHostIssuedFabricPatchExecutor(value);
+}

package/src/lib/fabric-task-host.ts

@@ -0,0 +1,29 @@
+import type { FabricPatchExecutor, FabricPatchExecutorInput, TrustedFabricPatchExecutor } from "../lab/fabric/types";
+
+const HOST_ISSUED_EXECUTORS = new WeakSet<object>();
+
+/**
+ * Trusted host integration boundary for CL-07 exact-route fabric patch production.
+ *
+ * @internal host integration only
+ */
+export function createHostIssuedFabricPatchExecutor(
+  executorModulePath: string,
+  execute: FabricPatchExecutor,
+): TrustedFabricPatchExecutor {
+  const capability: TrustedFabricPatchExecutor = Object.freeze({
+    executorModulePath,
+    execute: (input: FabricPatchExecutorInput) => Promise.resolve(execute(input)),
+  });
+  HOST_ISSUED_EXECUTORS.add(capability);
+  return capability;
+}
+
+/** Internal recognition check consumed by the read-only authority facade. */
+export function isHostIssuedFabricPatchExecutor(value: unknown): value is TrustedFabricPatchExecutor {
+  if (typeof value !== "object" || value === null || !HOST_ISSUED_EXECUTORS.has(value as object)) return false;
+  const capability = value as TrustedFabricPatchExecutor;
+  return typeof capability.executorModulePath === "string"
+    && capability.executorModulePath.length > 0
+    && typeof capability.execute === "function";
+}

package/src/lib/lab-live-route-production.ts

@@ -0,0 +1,130 @@
+/**
+ * Production host integration for CL-03 trusted exact-route execution.
+ *
+ * Issues a host-recognized `TrustedLabRouteExecutor` that routes provider traffic
+ * through the CL-03 credential lease, pinned transport, and observation normalization
+ * pipeline. Secret material stays outside Lab modules.
+ *
+ * @internal host integration only
+ */
+import { resolveEnvValue } from "../config";
+import {
+  getValidAccessTokenSnapshot,
+  OAuthLoginRequiredError,
+  UnsupportedOAuthProviderError,
+} from "../oauth";
+import type { OcxConfig } from "../types";
+import { createCredentialLease } from "../lab/live/credential-lease";
+import {
+  liveUpstreamRequestPath,
+  normalizeLabLiveTransportObservation,
+} from "../lab/live/executor";
+import { createPinnedTransport } from "../lab/live/transport";
+import { TransportError } from "../lab/live/transport";
+import type { LabRouteContext } from "../lab/live/types";
+import { createLabAuthorizedPinnedSender } from "./lab-live-pinned-sender";
+import { createHostIssuedLabRouteExecutor } from "./lab-live-host";
+import type { TrustedLabRouteExecutor } from "../lab/live/types";
+
+const CREDENTIAL_HEADER = /(authorization|api[-_]?key|token|secret|credential|cookie)/i;
+
+export interface ProductionLabRouteExecutorDeps {
+  configDir?: string;
+  loadConfig: () => OcxConfig;
+}
+
+async function buildLabProviderAuthHeaders(
+  routeContext: LabRouteContext,
+  config: OcxConfig,
+): Promise<Record<string, string>> {
+  const provider = config.providers?.[routeContext.providerId];
+  if (!provider || provider.disabled === true) {
+    throw new TransportError("auth_blocked", "provider unavailable");
+  }
+  if (provider.authMode === "forward") {
+    throw new TransportError("auth_blocked", "forward auth unsupported for lab probes");
+  }
+  if (provider.authMode === "local") {
+    throw new TransportError("auth_blocked", "local provider unsupported for lab probes");
+  }
+
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+
+  if (provider.authMode === "oauth") {
+    let protocol: string;
+    try {
+      protocol = new URL(routeContext.baseUrl).protocol;
+    } catch {
+      throw new TransportError("auth_blocked", "invalid OAuth provider destination");
+    }
+    if (protocol !== "https:") {
+      throw new TransportError("auth_blocked", "OAuth lab probes require HTTPS");
+    }
+    try {
+      const snapshot = await getValidAccessTokenSnapshot(routeContext.providerId);
+      headers.Authorization = `Bearer ${snapshot.accessToken}`;
+    } catch (error) {
+      if (error instanceof OAuthLoginRequiredError || error instanceof UnsupportedOAuthProviderError) {
+        throw new TransportError("auth_blocked", "oauth unavailable");
+      }
+      // Non-terminal refresh failures (network, lock contention, provider transient errors)
+      // are harness/infrastructure failures rather than evidence that credentials are invalid.
+      throw new TransportError("harness_failure", "oauth refresh unavailable");
+    }
+  } else {
+    const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+    if (!apiKey) throw new TransportError("auth_blocked", "missing api key");
+    if (provider.adapter === "anthropic" && provider.apiKeyTransport === "x-api-key") {
+      headers["x-api-key"] = apiKey;
+    } else {
+      headers.Authorization = `Bearer ${apiKey}`;
+    }
+  }
+
+  if (provider.headers) {
+    for (const [name, value] of Object.entries(provider.headers)) {
+      if (CREDENTIAL_HEADER.test(name)) continue;
+      const resolved = resolveEnvValue(value);
+      headers[name] = typeof resolved === "string" ? resolved : value;
+    }
+  }
+
+  return headers;
+}
+
+/** Create the process-local trusted CL-03 route executor for Lab automation dispatch. */
+export function createProductionLabRouteExecutor(
+  deps: ProductionLabRouteExecutorDeps,
+): TrustedLabRouteExecutor {
+  return createHostIssuedLabRouteExecutor(async (input) => {
+    if (!input.initiatingRequest) {
+      throw new TransportError("harness_failure", "live scenario missing initiating request");
+    }
+    const config = deps.loadConfig();
+    const lease = createCredentialLease({
+      destination: input.destination,
+      transportId: "lab-automation",
+      budget: input.limits.maxRequests,
+    });
+    const authHeaders = await buildLabProviderAuthHeaders(input.routeContext, config);
+    const sender = createLabAuthorizedPinnedSender(async () => authHeaders);
+    const transport = createPinnedTransport({
+      destination: input.destination,
+      lease,
+      sender,
+      limits: input.limits,
+      transportId: "lab-automation",
+    });
+    const path = liveUpstreamRequestPath(input.routeContext.upstreamProtocol);
+    const response = await transport.request({
+      method: "POST",
+      path,
+      body: input.initiatingRequest,
+      signal: input.signal,
+    });
+    return normalizeLabLiveTransportObservation(input.routeContext, response);
+  });
+}

package/src/lib/local-management-capability.ts

@@ -0,0 +1,100 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const LOCAL_MANAGEMENT_EXPECTED_PID_HEADER = "x-opencodex-local-expected-pid";
+export const LOCAL_MANAGEMENT_NONCE_HEADER = "x-opencodex-local-nonce";
+export const LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER = "x-opencodex-local-expires-at";
+export const LOCAL_MANAGEMENT_CAPABILITY_HEADER = "x-opencodex-local-capability";
+export const LOCAL_MANAGEMENT_CAPABILITY_TTL_MS = 10_000;
+
+export const LOCAL_MANAGEMENT_READ_PATHS = {
+  codexAccounts: "/api/codex-auth/accounts",
+  systemMemory: "/api/system/memory",
+} as const;
+
+export type LocalManagementReadPath =
+  typeof LOCAL_MANAGEMENT_READ_PATHS[keyof typeof LOCAL_MANAGEMENT_READ_PATHS];
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+const LOCAL_READ_METHOD = "GET";
+
+export type ExpectedLocalManagementPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedLocalManagementPid(value: string | null): ExpectedLocalManagementPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+function isLocalManagementReadPath(path: string): path is LocalManagementReadPath {
+  return path === LOCAL_MANAGEMENT_READ_PATHS.codexAccounts
+    || path === LOCAL_MANAGEMENT_READ_PATHS.systemMemory;
+}
+
+function localReadCapabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== LOCAL_READ_METHOD || !isLocalManagementReadPath(path)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) return null;
+  return `opencodex-local-management-read-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}\n${expiresAt}`;
+}
+
+/** Process-scoped authorization for one allowlisted local management GET. */
+export function createLocalManagementReadCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = localReadCapabilityPayload(nonce, method, path, pid, port, expiresAt);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalManagementReadCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  expiresAt: number,
+  capability: string | null,
+  now = Date.now(),
+): boolean {
+  if (!nonce || !capability || !BASE64URL_256.test(capability)) return false;
+  if (
+    !Number.isSafeInteger(now)
+    || expiresAt <= now
+    || expiresAt > now + LOCAL_MANAGEMENT_CAPABILITY_TTL_MS
+  ) return false;
+  const expected = createLocalManagementReadCapability(
+    secret,
+    nonce,
+    method,
+    path,
+    pid,
+    port,
+    expiresAt,
+  );
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/server-resource-ownership.ts

@@ -0,0 +1,71 @@
+type Cleanup = () => void;
+
+type ServerResourceOwner = {
+  token: symbol;
+  cleanups: Set<Cleanup>;
+};
+
+export type ServerResourceOwnerLease = {
+  release(): void;
+};
+
+const owners: ServerResourceOwner[] = [];
+
+function currentOwner(): ServerResourceOwner | undefined {
+  return owners.at(-1);
+}
+
+/** Acquire ownership for resources created while one server instance starts. */
+export function acquireServerResourceOwner(): ServerResourceOwnerLease {
+  const owner: ServerResourceOwner = {
+    token: Symbol("server-resource-owner"),
+    cleanups: new Set(),
+  };
+  owners.push(owner);
+
+  let released = false;
+  return {
+    release() {
+      if (released) return;
+      released = true;
+      const index = owners.findIndex(candidate => candidate.token === owner.token);
+      if (index !== -1) owners.splice(index, 1);
+      for (const cleanup of [...owner.cleanups]) {
+        try {
+          cleanup();
+        } catch {
+          // Resource cleanup is best-effort and one failed hook must not retain siblings.
+        }
+      }
+      owner.cleanups.clear();
+    },
+  };
+}
+
+/** Attach cleanup to the server instance currently being started. */
+export function registerCurrentServerResourceCleanup(cleanup: Cleanup): () => void {
+  const owner = currentOwner();
+  if (!owner) return () => {};
+  owner.cleanups.add(cleanup);
+  let attached = true;
+  return () => {
+    if (!attached) return;
+    attached = false;
+    owner.cleanups.delete(cleanup);
+  };
+}
+
+/** Test-only reset for isolated lifecycle tests. */
+export function resetServerResourceOwnershipForTests(): void {
+  for (const owner of [...owners].reverse()) {
+    for (const cleanup of [...owner.cleanups]) {
+      try {
+        cleanup();
+      } catch {
+        // Test reset must leave no retained owner even when a synthetic cleanup throws.
+      }
+    }
+    owner.cleanups.clear();
+  }
+  owners.length = 0;
+}

package/src/lib/windows-elevation.ts

@@ -21,6 +21,13 @@ type TrustedSystemDirectoryResolver = () => string;
 type IsUserAnAdmin = () => number;
 type WindowsElevationProbe = () => boolean | null;
 
+export class WindowsSystemDirectoryFfiUnavailableError extends Error {
+  constructor() {
+    super("Failed to load GetSystemDirectoryW from kernel32.dll.");
+    this.name = "WindowsSystemDirectoryFfiUnavailableError";
+  }
+}
+
 let getSystemDirectoryWFn: GetSystemDirectoryW | null | undefined;
 let trustedSystemDirectoryResolverForTests: TrustedSystemDirectoryResolver | null = null;
 let isUserAnAdminFn: (() => boolean) | null | undefined;
@@ -114,7 +121,7 @@ export function resolveTrustedWindowsSystemDirectory(): string {
   }
   const getSystemDirectoryW = loadGetSystemDirectoryW();
   if (!getSystemDirectoryW) {
-    throw new Error("Failed to load GetSystemDirectoryW from kernel32.dll.");
+    throw new WindowsSystemDirectoryFfiUnavailableError();
   }
 
   let size = 260;

package/src/lib/windows-user-principal.ts

@@ -20,11 +20,71 @@
  * would mean passing an absolute deadline through the runner interface.
  */
 
-import { resolveTrustedWindowsPowerShellExe } from "./windows-elevation";
+import { existsSync } from "node:fs";
+import { win32 as windowsPath } from "node:path";
+
+import {
+  resolveTrustedWindowsPowerShellExe,
+  WindowsSystemDirectoryFfiUnavailableError,
+} from "./windows-elevation";
 
 const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
 const SID_EXPRESSION =
   "[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value";
+const DEFAULT_WINDOWS_ARM64_POWERSHELL = windowsPath.join(
+  "C:\\Windows\\System32",
+  "WindowsPowerShell",
+  "v1.0",
+  "powershell.exe",
+);
+
+type PrincipalExecutableResolution = Readonly<{
+  platform: NodeJS.Platform;
+  arch: string;
+  resolveTrusted: () => string;
+  pathExists: (path: string) => boolean;
+}>;
+
+/**
+ * Bun's Windows ARM64 build cannot currently execute the `bun:ffi` call used
+ * by the general System32 resolver. The ACL identity lookup has a narrower
+ * authority than the elevation helpers: it starts one non-elevated PowerShell
+ * command and accepts only a SID-shaped result. Keep its fallback equally
+ * narrow by using the fixed, OS-protected default installation path only.
+ *
+ * Environment and PATH lookup are deliberately absent. A Windows installation
+ * outside C:\\Windows keeps failing closed rather than executing a binary chosen
+ * by caller-controlled `SystemRoot`, `WINDIR`, or `PATH` values.
+ */
+function resolveWindowsPrincipalPowerShellExecutable(
+  resolution: PrincipalExecutableResolution = {
+    platform: process.platform,
+    arch: process.arch,
+    resolveTrusted: resolveTrustedWindowsPowerShellExe,
+    pathExists: existsSync,
+  },
+): string {
+  try {
+    return resolution.resolveTrusted();
+  } catch (error) {
+    if (
+      !(error instanceof WindowsSystemDirectoryFfiUnavailableError) ||
+      resolution.platform !== "win32" ||
+      resolution.arch !== "arm64" ||
+      !resolution.pathExists(DEFAULT_WINDOWS_ARM64_POWERSHELL)
+    ) {
+      throw error;
+    }
+    return DEFAULT_WINDOWS_ARM64_POWERSHELL;
+  }
+}
+
+/** Test-only dependency-injected view of the Windows ARM64 executable boundary. */
+export function resolveWindowsPrincipalPowerShellExecutableForTests(
+  resolution: PrincipalExecutableResolution,
+): string {
+  return resolveWindowsPrincipalPowerShellExecutable(resolution);
+}
 
 export interface WindowsPrincipalLookupResult {
   success: boolean;
@@ -52,7 +112,7 @@ const POWERSHELL_ARGS = [
 ] as const;
 
 function windowsPrincipalPowerShellCommand(): string[] {
-  return [resolveTrustedWindowsPowerShellExe(), ...POWERSHELL_ARGS];
+  return [resolveWindowsPrincipalPowerShellExecutable(), ...POWERSHELL_ARGS];
 }
 
 /** Test-only readback of the exact trusted executable and static arguments. */

package/src/lib/winsw.ts

@@ -17,7 +17,7 @@ import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir, loadConfig } from "../config";
 import { recordOwnedConfigPath } from "./config-ownership";
 import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from "./bun-runtime";
@@ -63,6 +63,11 @@ function currentCodexHomeAbsolute(): string {
   return raw ? resolve(expandUserPath(raw)) : join(homedir(), ".codex");
 }
 
+function windowsServicePathAbsolute(raw: string): string {
+  const expanded = expandUserPath(raw);
+  return win32.isAbsolute(expanded) ? win32.normalize(expanded) : resolve(expanded);
+}
+
 export interface WinswEntry {
   bun: string;
   /** Provenance of `bun`, resolved together with it so the two can never disagree. */
@@ -103,6 +108,7 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
     `  <env name="OCX_API_TOKEN_FILE" value="${xmlEscape(serviceApiTokenFilePath())}"/>`,
     `  <env name="PATH" value="${xmlEscape(env.PATH ?? "")}"/>`,
     env.CODEX_HOME?.trim() ? `  <env name="CODEX_HOME" value="${xmlEscape(currentCodexHomeAbsolute())}"/>` : null,
+    env.CODEX_SQLITE_HOME?.trim() ? `  <env name="CODEX_SQLITE_HOME" value="${xmlEscape(windowsServicePathAbsolute(env.CODEX_SQLITE_HOME.trim()))}"/>` : null,
     `  <env name="OPENCODEX_HOME" value="${xmlEscape(getConfigDir())}"/>`,
     aclTimeout ? `  <env name="OPENCODEX_ACL_TIMEOUT_MS" value="${xmlEscape(aclTimeout)}"/>` : null,
   ].filter((line): line is string => Boolean(line));
@@ -394,4 +400,4 @@ export function winswStatusSummary(): string {
 export function defaultWinswEntry(cliDir: string): WinswEntry {
   const runtime = durableBunRuntime();
   return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(cliDir, "cli", "index.ts") };
-}
+}