@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/lib/state-store-sweeper.ts

@@ -0,0 +1,184 @@
+export const STATE_SWEEP_INTERVAL_MS = 60_000;
+
+export interface GenerationContext {
+  generation: number;
+  providerNames: ReadonlySet<string>;
+  comboIds: ReadonlySet<string>;
+  comboTargets: ReadonlySet<string>;
+  codexAccountIds: ReadonlySet<string>;
+  oauthAccountKeys: ReadonlySet<string>;
+  configRoots: ReadonlySet<string>;
+}
+
+export interface StateStoreRegistration {
+  name: string;
+  sweepExpired?: (now: number) => number;
+  sweepLiveness?: () => number;
+  reconcileGeneration?: (context: GenerationContext) => number;
+}
+
+export interface StateSweepAfterTickRegistration {
+  name: string;
+  afterTick(): void;
+}
+
+export interface StateSweepResult {
+  storesVisited: number;
+  rowsRemoved: number;
+}
+
+export interface StateStoreSweeperOptions {
+  /** Override the 60 s interval (tests only; production uses the default). */
+  intervalMs?: number;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+const registrations = new Map<string, StateStoreRegistration>();
+const afterTickRegistrations = new Map<string, StateSweepAfterTickRegistration>();
+let configGeneration = 0;
+let attemptSequence = 0;
+let generationContextBuilder: (() => GenerationContext) | null = null;
+let reconciliationRetryPending = false;
+let interval: ReturnType<typeof setInterval> | null = null;
+
+function logCallbackFailure(name: string): void {
+  console.warn(`[state-store-sweeper] ${name} failed`);
+}
+
+export function registerStateStore(registration: StateStoreRegistration): () => void {
+  registrations.set(registration.name, registration);
+  return () => {
+    if (registrations.get(registration.name) === registration) {
+      registrations.delete(registration.name);
+    }
+  };
+}
+
+export function registerStateSweepAfterTick(registration: StateSweepAfterTickRegistration): () => void {
+  afterTickRegistrations.set(registration.name, registration);
+  return () => {
+    if (afterTickRegistrations.get(registration.name) === registration) {
+      afterTickRegistrations.delete(registration.name);
+    }
+  };
+}
+
+function runCallbacks(
+  callback: (registration: StateStoreRegistration) => (() => number) | undefined,
+): StateSweepResult {
+  let storesVisited = 0;
+  let rowsRemoved = 0;
+  for (const registration of registrations.values()) {
+    const invoke = callback(registration);
+    if (!invoke) continue;
+    storesVisited += 1;
+    try {
+      rowsRemoved += invoke();
+    } catch {
+      logCallbackFailure(registration.name);
+    }
+  }
+  return { storesVisited, rowsRemoved };
+}
+
+export function sweepExpired(now = Date.now()): StateSweepResult {
+  return runCallbacks(registration => registration.sweepExpired
+    ? () => registration.sweepExpired!(now)
+    : undefined);
+}
+
+export function sweepExpiredOnWrite(now = Date.now()): StateSweepResult {
+  const result = sweepExpired(now);
+  if (reconciliationRetryPending && generationContextBuilder) {
+    try {
+      reconcileStateGeneration(generationContextBuilder());
+    } catch {
+      // The builder reads authoritative live owners. Keep the single retry pending
+      // until a later successful owner write can obtain a complete context.
+    }
+  }
+  return result;
+}
+
+export function sweepLiveness(): StateSweepResult {
+  return runCallbacks(registration => registration.sweepLiveness);
+}
+
+function runAfterTickCallbacks(): void {
+  for (const registration of afterTickRegistrations.values()) {
+    try {
+      registration.afterTick();
+    } catch {
+      logCallbackFailure(registration.name);
+    }
+  }
+}
+
+export function captureConfigGeneration(): number {
+  return configGeneration;
+}
+
+export function setGenerationContextBuilder(build: () => GenerationContext): void {
+  generationContextBuilder = build;
+}
+
+export function reconcileStateGeneration(context: GenerationContext): StateSweepResult {
+  const candidateGeneration = ++attemptSequence;
+  const candidateContext: GenerationContext = {
+    ...context,
+    generation: candidateGeneration,
+  };
+
+  let storesVisited = 0;
+  let rowsRemoved = 0;
+  let failed = false;
+  for (const registration of registrations.values()) {
+    if (!registration.reconcileGeneration) continue;
+    storesVisited += 1;
+    try {
+      rowsRemoved += registration.reconcileGeneration(candidateContext);
+    } catch {
+      failed = true;
+      logCallbackFailure(registration.name);
+    }
+  }
+  if (failed) {
+    reconciliationRetryPending = true;
+  } else {
+    configGeneration = candidateGeneration;
+    reconciliationRetryPending = false;
+  }
+  return { storesVisited, rowsRemoved };
+}
+
+export function startStateStoreSweeper(
+  options: StateStoreSweeperOptions = {},
+): { stop(): void } {
+  stopStateStoreSweeper();
+  const now = options.now ?? Date.now;
+  interval = setInterval(() => {
+    sweepExpired(now());
+    sweepLiveness();
+    runAfterTickCallbacks();
+  }, options.intervalMs ?? STATE_SWEEP_INTERVAL_MS);
+  interval.unref?.();
+  return { stop: stopStateStoreSweeper };
+}
+
+export function stopStateStoreSweeper(): void {
+  if (!interval) return;
+  clearInterval(interval);
+  interval = null;
+}
+
+/** Test-only reset for module-global registrations, generation, and lifecycle state. */
+export function resetStateStoreSweeperForTests(): void {
+  stopStateStoreSweeper();
+  registrations.clear();
+  afterTickRegistrations.clear();
+  configGeneration = 0;
+  attemptSequence = 0;
+  generationContextBuilder = null;
+  reconciliationRetryPending = false;
+}

package/src/lib/translator-budget.ts

@@ -0,0 +1,356 @@
+export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
+export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
+export const TRANSLATOR_MAX_SSE_EVENT_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_CONNECT_FRAME_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES = 16 * 1024 * 1024;
+export const CURSOR_TRANSPORT_MAX_BUFFERED_BYTES = 32 * 1024 * 1024;
+export const CURSOR_TRANSPORT_RESUME_BYTES = 16 * 1024 * 1024;
+export const CURSOR_MAX_PENDING_FRAMES = 1024;
+export const CURSOR_PENDING_FRAMES_RESUME = 512;
+export const MAX_PENDING_IMAGE_FULFILLMENTS = 64;
+export const MAX_PENDING_OAUTH_MUTATIONS = 128;
+
+export type TranslatorBufferKind =
+  | "tool_args"
+  | "retained_collectors"
+  | "live_transient"
+  | "reasoning"
+  | "item_ids"
+  | "tool_search_sources"
+  | "cursor_transport"
+  | "cursor_kv"
+  | "request_copies";
+
+export type ExternallyCappedKind = "passthrough_serialization" | "mcp_payload";
+
+export class TranslatorBudgetExceededError extends Error {
+  readonly code = "translation_buffer_limit";
+
+  constructor(readonly kind: TranslatorBufferKind, readonly limitBytes: number) {
+    super(`translator ${kind} buffer exceeded ${limitBytes} bytes`);
+    this.name = "TranslatorBudgetExceededError";
+  }
+}
+
+export function isTranslatorBudgetExceededError(error: unknown): error is TranslatorBudgetExceededError {
+  return error instanceof TranslatorBudgetExceededError
+    || (error instanceof Error && (error as { code?: unknown }).code === "translation_buffer_limit");
+}
+
+export interface TranslatorBudgetSnapshot {
+  currentBytes: number;
+  highWaterBytes: number;
+  activeCalls: number;
+  overflows: number;
+}
+
+export interface TranslatorBudgetOptions {
+  maxCallArgumentBytes?: number;
+  maxTurnBytes?: number;
+}
+
+export interface TranslatorTransientReservation {
+  commitRetained(): void;
+  release(): void;
+}
+
+export interface TranslatorBudget {
+  openCall(id: string): void;
+  closeCall(id: string): void;
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation;
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  observeAcceptedRequestCopy(bytes: number): () => void;
+  observeExternallyCapped(kind: ExternallyCappedKind, bytes: number): () => void;
+  snapshot(): TranslatorBudgetSnapshot;
+  dispose(): void;
+}
+
+const retainedEventOwnership = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
+
+/**
+ * Charge a materialized adapter-event batch and attach its lease to the events themselves.
+ * A copied event array (for example terminal-guard collection) preserves the event objects, so
+ * the response builder can consume each source lease immediately after its replacement lands.
+ */
+export function retainTranslatedEventBatch<T extends object>(events: T[], budget: TranslatorBudget): void {
+  if (events.length === 0) return;
+  const serialized = events.map(event => JSON.stringify(event));
+  const totalBytes = Buffer.byteLength(`[${serialized.join(",")}]`);
+  budget.chargeRetained(totalBytes, { kind: "retained_collectors" });
+  for (let index = 0; index < events.length; index++) {
+    const delimiterBytes = index === events.length - 1 ? 2 : 1;
+    retainedEventOwnership.set(events[index]!, {
+      budget,
+      bytes: Buffer.byteLength(serialized[index]!) + delimiterBytes,
+    });
+  }
+}
+
+/** Transfer one charged adapter event to the response builder's newly materialized owner. */
+export function releaseTranslatedEvent(event: object, budget: TranslatorBudget): void {
+  const ownership = retainedEventOwnership.get(event);
+  if (!ownership || ownership.budget !== budget) return;
+  retainedEventOwnership.delete(event);
+  budget.releaseRetained(ownership.bytes, { kind: "retained_collectors" });
+}
+
+const liveBudgets = new Set<Budget>();
+let aggregateCurrentBytes = 0;
+let aggregateActiveCalls = 0;
+let aggregateHighWaterBytes = 0;
+let aggregateOverflows = 0;
+
+function normalizeBytes(bytes: number): number {
+  return Number.isFinite(bytes) && bytes > 0 ? Math.floor(bytes) : 0;
+}
+
+function observeAggregate(): void {
+  aggregateHighWaterBytes = Math.max(aggregateHighWaterBytes, aggregateCurrentBytes);
+}
+
+class Budget implements TranslatorBudget {
+  private readonly calls = new Map<string, { logicalBytes: number; physicalBytes: number }>();
+  private readonly charged = new Map<TranslatorBufferKind, number>();
+  private hardChargedBytes = 0;
+  private observedBytes = 0;
+  private currentBytes = 0;
+  private highWaterBytes = 0;
+  private overflowCount = 0;
+  private disposed = false;
+
+  constructor(
+    private readonly maxCallArgumentBytes: number,
+    private readonly maxTurnBytes: number,
+  ) {}
+
+  private chargedBytes(): number {
+    return this.hardChargedBytes;
+  }
+
+  observedCurrentBytes(): number {
+    return this.currentBytes;
+  }
+
+  private changed(): void {
+    const nextBytes = this.hardChargedBytes + this.observedBytes;
+    aggregateCurrentBytes += nextBytes - this.currentBytes;
+    this.currentBytes = nextBytes;
+    this.highWaterBytes = Math.max(this.highWaterBytes, nextBytes);
+    observeAggregate();
+  }
+
+  private reject(kind: TranslatorBufferKind, limitBytes: number): never {
+    this.overflowCount += 1;
+    aggregateOverflows += 1;
+    throw new TranslatorBudgetExceededError(kind, limitBytes);
+  }
+
+  private admit(kind: TranslatorBufferKind, bytes: number): number {
+    const admitted = normalizeBytes(bytes);
+    if (this.chargedBytes() + admitted > this.maxTurnBytes) this.reject(kind, this.maxTurnBytes);
+    return admitted;
+  }
+
+  openCall(id: string): void {
+    if (!this.calls.has(id)) {
+      this.calls.set(id, { logicalBytes: 0, physicalBytes: 0 });
+      aggregateActiveCalls += 1;
+    }
+  }
+
+  closeCall(id: string): void {
+    const call = this.calls.get(id);
+    if (!call) return;
+    this.hardChargedBytes = Math.max(0, this.hardChargedBytes - call.physicalBytes);
+    this.calls.delete(id);
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - 1);
+    this.changed();
+  }
+
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation {
+    const admitted = normalizeBytes(bytes);
+    if (scope.callId && admitted > this.maxCallArgumentBytes) {
+      this.reject("tool_args", this.maxCallArgumentBytes);
+    }
+    this.admit(scope.kind, admitted);
+    this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    this.hardChargedBytes += admitted;
+    this.changed();
+    let state: "reserved" | "committed" | "released" = "reserved";
+    return {
+      commitRetained: () => {
+        if (state !== "reserved") return;
+        state = "committed";
+        if (!scope.callId) return;
+        const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        call.logicalBytes = admitted;
+        call.physicalBytes += admitted;
+        this.calls.set(scope.callId, call);
+        this.changed();
+      },
+      release: () => {
+        if (state !== "reserved") return;
+        state = "released";
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - admitted);
+        this.changed();
+      },
+    };
+  }
+
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const admitted = normalizeBytes(delta);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+      if (call.logicalBytes + admitted > this.maxCallArgumentBytes) {
+        this.reject("tool_args", this.maxCallArgumentBytes);
+      }
+      this.admit(scope.kind, admitted);
+      call.logicalBytes += admitted;
+      call.physicalBytes += admitted;
+      this.calls.set(scope.callId, call);
+    } else {
+      this.admit(scope.kind, admitted);
+      this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    }
+    this.hardChargedBytes += admitted;
+    this.changed();
+  }
+
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const released = normalizeBytes(bytes);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId);
+      if (call) {
+        const actual = Math.min(released, call.physicalBytes);
+        call.physicalBytes -= actual;
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+      }
+    } else {
+      const current = this.charged.get(scope.kind) ?? 0;
+      const actual = Math.min(released, current);
+      this.charged.set(scope.kind, current - actual);
+      this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+    }
+    this.changed();
+  }
+
+  private observe(bytes: number): () => void {
+    const observed = normalizeBytes(bytes);
+    this.observedBytes += observed;
+    this.changed();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.observedBytes = Math.max(0, this.observedBytes - observed);
+      this.changed();
+    };
+  }
+
+  observeAcceptedRequestCopy(bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  observeExternallyCapped(_kind: ExternallyCappedKind, bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  snapshot(): TranslatorBudgetSnapshot {
+    return {
+      currentBytes: this.observedCurrentBytes(),
+      highWaterBytes: this.highWaterBytes,
+      activeCalls: this.calls.size,
+      overflows: this.overflowCount,
+    };
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - this.calls.size);
+    aggregateCurrentBytes = Math.max(0, aggregateCurrentBytes - this.currentBytes);
+    this.calls.clear();
+    this.charged.clear();
+    this.hardChargedBytes = 0;
+    this.observedBytes = 0;
+    this.currentBytes = 0;
+    liveBudgets.delete(this);
+    observeAggregate();
+  }
+}
+
+export function createTranslatorBudget(options: TranslatorBudgetOptions = {}): TranslatorBudget {
+  const budget = new Budget(
+    options.maxCallArgumentBytes ?? TRANSLATOR_MAX_CALL_ARGUMENT_BYTES,
+    options.maxTurnBytes ?? TRANSLATOR_MAX_TURN_BYTES,
+  );
+  liveBudgets.add(budget);
+  observeAggregate();
+  return budget;
+}
+
+export function translatorObservedBufferSnapshot(): {
+  currentBytes: number;
+  highWaterBytes: number;
+  active: number;
+} {
+  return {
+    currentBytes: aggregateCurrentBytes,
+    highWaterBytes: aggregateHighWaterBytes,
+    active: aggregateActiveCalls,
+  };
+}
+
+/** Internal diagnostics used by focused tests; never registered with app-owned memory. */
+export function translatorObservedOverflowCount(): number {
+  return aggregateOverflows;
+}
+
+/** Clears process-wide translator diagnostics and disposes leaked test budgets. */
+export function resetTranslatorAggregateForTests(): void {
+  for (const budget of liveBudgets) budget.dispose();
+  aggregateCurrentBytes = 0;
+  aggregateActiveCalls = 0;
+  aggregateHighWaterBytes = 0;
+  aggregateOverflows = 0;
+}
+
+export function finalizeTranslatorBudgetResponse(response: Response, budget: TranslatorBudget): Response {
+  if (!response.body) {
+    budget.dispose();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let finalized = false;
+  const finalize = () => {
+    if (finalized) return;
+    finalized = true;
+    budget.dispose();
+  };
+  return new Response(new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finalize();
+          controller.close();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        finalize();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try { await reader.cancel(reason); } finally { finalize(); }
+    },
+  }), { status: response.status, statusText: response.statusText, headers: response.headers });
+}

package/src/lib/windows-secret-acl.ts

@@ -19,11 +19,9 @@
  *   hardenSecretPath(path, { required: false }) — non-fatal read-path mode.
  *     Never throws. Returns { ok, diagnostics? }.
  *   hardenSecretPath(path, { required: true })  — write-path mode.
- *     Throws a sanitized error (no raw path) on Windows ACL failure — EXCEPT a
- *     genuine icacls timeout, which soft-fails (warn + ok:false) so a hung/slow
- *     icacls cannot block OAuth logins or token refresh (field report: Kimi auth
- *     stuck behind ETIMEDOUT). Real EPERM/EACCES/exit-code failures still throw:
- *     availability never silently overrides confidentiality for those.
+ *     Throws a sanitized error (no raw path) on every Windows ACL failure,
+ *     including genuine icacls timeouts. Required secret publication therefore
+ *     fails closed; only required:false read-path probes may soft-fail.
  *   hardenSecretPathAsync / hardenSecretDirAsync — same policy, async icacls
  *     runner so the event loop is not held for the child lifetime (#612).
  *   HardenOptions.timeoutMemoKey — optional destination-path key for the
@@ -170,10 +168,25 @@ export function resetHardenedStateForTests(): void {
   timedOutPaths.clear();
 }
 
+/** Forget a successful harden only after this exact ephemeral path is gone. */
+export function forgetHardenedSecretPath(targetPath: string): void {
+  hardenedPaths.delete(targetPath);
+}
+
+/** Test seam for proving ephemeral success memos do not grow across replacements. */
+export function hardenedSecretPathCountForTests(): number {
+  return hardenedPaths.size;
+}
+
 function effectivePlatform(): string {
   return platformOverride ?? platform;
 }
 
+/** Test-aware platform predicate for callers that must avoid even a no-op ACL call. */
+export function windowsSecretAclApplies(): boolean {
+  return (platformOverride ?? process.platform) === "win32";
+}
+
 /** Error carrying an honest code: ETIMEDOUT only for real timeouts, EICACLS otherwise. */
 function icaclsError(step: string, result: IcaclsResult): NodeJS.ErrnoException {
   const err = new Error(
@@ -363,14 +376,18 @@ async function describeAclStateAfterTimeoutAsync(targetPath: string, deadline: n
 function timeoutMemoKey(targetPath: string, opts: HardenOptions): string {
   // Destination-path memo only (issue #612). Never a parent directory — directory ACLs
   // are not authoritative for newly created temps.
-  return opts.timeoutMemoKey ?? targetPath;
+  //
+  // Namespace by required-ness (#766): a soft `required:false` timeout during loadConfig
+  // must not poison a later `required:true` management-token harden of the same path.
+  const base = opts.timeoutMemoKey ?? targetPath;
+  return `${opts.required ? "required" : "optional"}:${base}`;
 }
 
 /**
  * Shared harden flow for files and directories: one total budget (env-configurable)
  * covering the initial attempt, ONE timeout retry, and the diagnostic verification.
- * Real EPERM/EACCES/EICACLS failures stay fail-closed on required paths; only
- * genuine timeouts soft-fail, with an honest state-annotated diagnostic.
+ * Required paths fail closed for every hardening failure, including genuine
+ * timeouts. Optional read paths soft-fail with an honest diagnostic.
  */
 function hardenEntry(
   targetPath: string,
@@ -383,7 +400,9 @@ function hardenEntry(
   if (cache.has(targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   if (timedOutPaths.has(memoKey)) {
-    return { ok: false, diagnostics: "ACL hardening skipped — previous attempt timed out" };
+    const diagnostics = "ACL hardening skipped — previous attempt timed out";
+    if (opts.required) throw new Error(diagnostics);
+    return { ok: false, diagnostics };
   }
 
   const deadline = nowFn() + resolveHardenDeadlineMs();
@@ -405,8 +424,7 @@ function hardenEntry(
     timedOutPaths.add(memoKey);
     const state = describeAclStateAfterTimeout(targetPath, deadline);
     const annotated = `${diagnostics}; ${state}`;
-    // Timeout-only soft-fail: a hung icacls must not block OAuth/token writes.
-    // chmod is still applied by the caller.
+    if (opts.required) throw new Error(annotated);
     console.warn(`[opencodex] ${annotated} — continuing without NTFS ACL harden`);
     return { ok: false, diagnostics: annotated };
   }
@@ -426,7 +444,9 @@ async function hardenEntryAsync(
   if (cache.has(targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   if (timedOutPaths.has(memoKey)) {
-    return { ok: false, diagnostics: "ACL hardening skipped — previous attempt timed out" };
+    const diagnostics = "ACL hardening skipped — previous attempt timed out";
+    if (opts.required) throw new Error(diagnostics);
+    return { ok: false, diagnostics };
   }
 
   const deadline = nowFn() + resolveHardenDeadlineMs();
@@ -448,6 +468,7 @@ async function hardenEntryAsync(
     timedOutPaths.add(memoKey);
     const state = await describeAclStateAfterTimeoutAsync(targetPath, deadline);
     const annotated = `${diagnostics}; ${state}`;
+    if (opts.required) throw new Error(annotated);
     console.warn(`[opencodex] ${annotated} — continuing without NTFS ACL harden`);
     return { ok: false, diagnostics: annotated };
   }

package/src/lib/winsw.ts

@@ -87,12 +87,19 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   })();
   // Services never bake `--port 0` (parsePortOption rejects it); treat as default.
   const safeListenPort = listenPort > 0 && listenPort <= 65535 ? listenPort : 10100;
+  // SCM services do not inherit the interactive user environment (#764). Bake:
+  // - OPENCODEX_HOME so file-backed admin auth (`admin-api-token`) resolves
+  // - OPENCODEX_ACL_TIMEOUT_MS when set (not a secret)
+  // Never embed OPENCODEX_ADMIN_AUTH_TOKEN or OPENCODEX_API_AUTH_TOKEN values in XML —
+  // those stay file-pointer / generated-file only (uninstall retains the XML).
+  const aclTimeout = env.OPENCODEX_ACL_TIMEOUT_MS?.trim();
   const envLines = [
     `  <env name="OCX_SERVICE" value="1"/>`,
     `  <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.OPENCODEX_HOME?.trim() ? `  <env name="OPENCODEX_HOME" value="${xmlEscape(getConfigDir())}"/>` : 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));
   return `<?xml version="1.0" encoding="UTF-8"?>
 <service>
@@ -165,6 +172,12 @@ function runWinsw(args: string[]): string {
 
 /** `install /p` prompts for the service-account password on the console — stdin must be inherited. */
 function runWinswInteractive(args: string[]): void {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "WinSW install requires an interactive console to prompt for the service account password. "
+        + "Run `ocx service install --native` from an elevated Command Prompt or PowerShell window, not a hidden or piped session.",
+    );
+  }
   execFileSync(winswExePath(), args, { stdio: "inherit" });
 }