@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/lib/spend-reservation-ledger.ts

@@ -60,6 +60,9 @@ import { dirname, join } from "node:path";
 // Definition-site import, not the ../config barrel -- same reasoning as
 // src/quota/reset-seen-store.ts: the barrel pulls ~154 modules into a hot path.
 import { getConfigDir } from "../config/paths";
+// Type-only, so it is erased before this module has a runtime import graph at all. The
+// config SHAPE is what this file needs; the config loader is what the note above keeps out.
+import type { OcxSpendConfig, OcxSpendScopeConfig } from "../types/config";
 import { assertNotRealHomeUnderTest } from "./test-home-guard";
 // Windows chmod does not remove inherited ACEs; this is the repository's icacls path.
 import { hardenSecretPath } from "./windows-secret-acl";
@@ -147,6 +150,24 @@ export interface SpendReservationRequest {
   /** Enforceable output ceiling -- max_output_tokens or the model's documented cap. */
   readonly outputCeilingTokens: number;
   readonly at?: number;
+  /**
+   * This send has ALREADY left for upstream and is being recorded rather than admitted.
+   *
+   * Some transports report their physical sends after the fact -- the passthrough ladder
+   * reports through `onSendsConsumed`, and an adapter's inner retries are counted when they
+   * finish. For those, a ceiling cannot refuse anything: the tokens are spent. Refusing to
+   * BOOK them is the worse answer, and it is not hypothetical -- it is a fixpoint. The send
+   * that would cross the ceiling gets dropped from the total, the total stays just under the
+   * limit forever, the scope never reads as exhausted, and the ceiling never fires again for
+   * any request. So a recorded send skips the limit check and takes the scope over its
+   * ceiling, which is what makes the NEXT request refusable.
+   *
+   * It skips the durability refusal for the same reason: a journal that could not be written
+   * is a reason to report degradation, never a reason to forget spend that really happened.
+   * Identity, capacity and journal-integrity denials still apply -- those say the ledger
+   * cannot account for the send at all, which no flag here can change.
+   */
+  readonly alreadySent?: boolean;
 }
 
 /**
@@ -468,6 +489,20 @@ export interface SpendReservationLedger {
   prune(now?: number): void;
   /** Whether this send id is already known, and therefore refused. */
   knows(sendId: string): boolean;
+  /**
+   * Replace the live policy.
+   *
+   * Every figure already accounted survives: raising, lowering or clearing a ceiling changes
+   * what is REFUSED from here on and never what was spent. Rebuilding the ledger instead
+   * would replay the journal into a second set of maps while the first still holds this
+   * process's open reservations, and the two would then disagree about what is in flight.
+   */
+  reconfigure(next: SpendReservationPolicy): void;
+  /**
+   * The policy in force. A live read, not a copy: a caller that formats a refusal has to name
+   * the ceiling this ledger would enforce on the NEXT request, not the one it was built with.
+   */
+  readonly policy: SpendReservationPolicy;
   /** Journal writes that failed; a nonzero count means durability is degraded. */
   readonly persistFailures: number;
   /**
@@ -495,13 +530,17 @@ export function createSpendReservationLedger(options: {
    */
   readonly salt?: string;
 } = {}): SpendReservationLedger {
-  const policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
+  // Mutable because the ceilings are operator configuration, and configuration is reloadable.
+  // The three bounds below are read through functions for the same reason: a value captured
+  // at construction would answer for the policy this ledger was BUILT with, and an operator
+  // who raised a bound would keep the old one until the process restarted.
+  let policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
   const journal = options.journal;
   const now = options.now ?? (() => Date.now());
   const salt = options.salt ?? "";
-  const maxTrackedScopes = policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
-  const maxTrackedSends = policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
-  const compactAfterRecords = policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
+  const maxTrackedScopes = (): number => policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
+  const maxTrackedSends = (): number => policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
+  const compactAfterRecords = (): number => policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
   const scopes = new Map<string, ScopeState>();
   const reservations = new Map<string, Reservation>();
   let persistFailures = 0;
@@ -753,7 +792,7 @@ export function createSpendReservationLedger(options: {
    */
   const compact = (at: number): void => {
     const rewrite = journal?.rewrite;
-    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords) return;
+    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords()) return;
     const checkpoint: JournalRecord = {
       v: 1,
       kind: "checkpoint",
@@ -791,12 +830,12 @@ export function createSpendReservationLedger(options: {
   const makeRoom = (refs: readonly ScopeRef[], at: number): SpendDenial | undefined => {
     evictSends(at, false);
     evictScopes(at, false);
-    while (reservations.size >= maxTrackedSends) {
+    while (reservations.size >= maxTrackedSends()) {
       if (evictSends(at, true) === 0) return { reason: "tracking-capacity-exhausted" };
     }
     let fresh = 0;
     for (const ref of refs) if (!scopes.has(scopeKey(ref.scope, ref.alias))) fresh += 1;
-    while (scopes.size + fresh > maxTrackedScopes) {
+    while (scopes.size + fresh > maxTrackedScopes()) {
       if (evictScopes(at, true) === 0) {
         return { reason: "tracking-capacity-exhausted", scope: refs[0]?.scope };
       }
@@ -808,6 +847,7 @@ export function createSpendReservationLedger(options: {
     get persistFailures() { return persistFailures; },
     get corruptRecords() { return corruptRecords; },
     get degraded() { return persistFailures > 0 || corruptRecords > 0; },
+    get policy() { return policy; },
 
     reserve(request: SpendReservationRequest): SpendReservationDecision {
       const tokens = sanitizeTokens(request.inputTokens) + sanitizeTokens(request.outputCeilingTokens);
@@ -834,7 +874,9 @@ export function createSpendReservationLedger(options: {
       // reservation booked on the scopes that would have passed. Reading state without
       // creating it matters here -- a denied request must not leave a tracked scope behind.
       for (const ref of refs) {
-        const limit = limitFor(ref.scope);
+        // A recorded send has no limit to fail: it already happened, and the point of booking
+        // it is to let the total go OVER the ceiling so the next request can be refused.
+        const limit = request.alreadySent === true ? undefined : limitFor(ref.scope);
         if (limit === undefined) continue;
         const state = scopes.get(scopeKey(ref.scope, ref.alias));
         const projected = (state ? state.settled + state.reserved + state.unresolved : 0) + tokens;
@@ -853,7 +895,7 @@ export function createSpendReservationLedger(options: {
       // limit a failed write refuses the request rather than admitting one that a restart
       // would forget -- which is exactly the disk-full and permission case durability is for.
       const durable = append({ v: 1, kind: "reserve", send, targets: refs, tokens, at });
-      if (!durable && enforced) {
+      if (!durable && enforced && request.alreadySent !== true) {
         return { reserved: false, denial: { reason: "reserve-not-durable", sendId: request.sendId } };
       }
       applyReserve(send, refs, tokens, at);
@@ -931,10 +973,72 @@ export function createSpendReservationLedger(options: {
       evictSends(at, false);
       evictScopes(at, false);
     },
+
+    reconfigure(next: SpendReservationPolicy): void {
+      policy = next;
+    },
   };
 }
 
 let sharedLedger: SpendReservationLedger | undefined;
+/**
+ * The operator policy in effect. Held beside the ledger rather than inside it because the
+ * ledger is built lazily: a configured ceiling has to be remembered from startup until the
+ * first request that actually reserves, and an install that configures nothing must still
+ * open no journal.
+ */
+let sharedPolicy: SpendReservationPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
+
+/** Whether any scope carries a ceiling -- that is, whether anything at all can be refused. */
+export function spendCeilingsConfigured(policy: SpendReservationPolicy = sharedPolicy): boolean {
+  return policy.root.maxTokens !== undefined
+    || policy.identity.maxTokens !== undefined
+    || policy.pool.maxTokens !== undefined;
+}
+
+/** The policy the process-wide ledger enforces right now. */
+export function sharedSpendPolicy(): SpendReservationPolicy {
+  return sharedPolicy;
+}
+
+const spendScopeLimitFromConfig = (scope: OcxSpendScopeConfig | undefined): SpendScopeLimit =>
+  scope?.maxTokens !== undefined && Number.isFinite(scope.maxTokens) && scope.maxTokens > 0
+    ? { maxTokens: Math.trunc(scope.maxTokens) }
+    : {};
+
+/**
+ * The ledger policy an operator's `spend` section asks for.
+ *
+ * An absent section, an empty one, and one whose every ceiling is absent all produce the
+ * unconfigured default: observe-only accounting that refuses nothing. That equivalence is the
+ * load-bearing part. This ledger is on and journaling by default, so shipping a default
+ * ceiling would start refusing real traffic on the first upgrade that ran this code, against
+ * a number nobody chose. There is deliberately no default figure here at all.
+ */
+export function spendPolicyFromConfig(spend: OcxSpendConfig | undefined): SpendReservationPolicy {
+  const retentionDays = spend?.retentionDays;
+  return {
+    root: spendScopeLimitFromConfig(spend?.root),
+    identity: spendScopeLimitFromConfig(spend?.identity),
+    pool: spendScopeLimitFromConfig(spend?.pool),
+    retentionMs: retentionDays !== undefined && Number.isFinite(retentionDays) && retentionDays > 0
+      ? Math.trunc(retentionDays) * 24 * 60 * 60_000
+      : DEFAULT_SPEND_RESERVATION_POLICY.retentionMs,
+  };
+}
+
+/**
+ * Apply an operator policy to the process-wide ledger.
+ *
+ * Startup calls this with the loaded config, and a reload may call it again: the ledger keeps
+ * every figure it has already accounted, so changing a ceiling changes what is refused from
+ * here on and never what was spent. It does not CREATE the ledger -- an install that
+ * configures no ceiling must not open a journal merely because the server started.
+ */
+export function configureSharedSpendLedger(policy: SpendReservationPolicy): void {
+  sharedPolicy = policy;
+  sharedLedger?.reconfigure(policy);
+}
 
 /**
  * Process-wide ledger backed by the journal under OPENCODEX_HOME. Created lazily so
@@ -947,6 +1051,7 @@ export function sharedSpendLedger(): SpendReservationLedger {
     sharedLedger = createSpendReservationLedger({
       journal: createFileSpendJournal(join(home, SPEND_LEDGER_JOURNAL_FILENAME)),
       salt: loadOrCreateSpendLedgerSalt(join(home, SPEND_LEDGER_SALT_FILENAME)),
+      policy: sharedPolicy,
     });
   }
   return sharedLedger;
@@ -955,4 +1060,5 @@ export function sharedSpendLedger(): SpendReservationLedger {
 /** Test seam. Production never discards the ledger: that would reset a spent budget. */
 export function resetSharedSpendLedgerForTest(): void {
   sharedLedger = undefined;
+  sharedPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
 }

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

@@ -30,8 +30,13 @@
  */
 
 import { existsSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
 import { env, platform } from "node:process";
-import { waitForSubprocessExit } from "./bounded-subprocess";
+import {
+  SUBPROCESS_KILL_GRACE_MS,
+  waitForSubprocessExit,
+  type SubprocessDeadlineScheduler,
+} from "./bounded-subprocess";
 import { resolveTrustedWindowsIcaclsExe } from "./windows-elevation";
 import {
   cachedCurrentWindowsIdentity,
@@ -48,17 +53,32 @@ const hardenedPaths = new Map<string, HardenedIdentity>();
  * that attempt was consumed. Ordinary callers never consume it.
  */
 const timedOutPaths = new Map<string, boolean>();
+/** Compatibility slack before the outer belt releases a caller whose killed child has not reaped. */
+const ASYNC_ICACLS_BELT_MARGIN_MS = 250;
+const pendingAsyncIcaclsReaps = new Map<string, Set<Promise<void>>>();
+
+const scheduleAsyncIcaclsBelt: SubprocessDeadlineScheduler = (callback, milliseconds) => {
+  const timer = setTimeout(callback, milliseconds);
+  return () => clearTimeout(timer);
+};
+let asyncIcaclsBeltScheduler: SubprocessDeadlineScheduler = scheduleAsyncIcaclsBelt;
 
 /**
- * The memo value: `object:freshness` for a file a harden was actually attributed
- * to.
+ * The memo value: the `object` plus `freshness` of a file a harden was actually
+ * attributed to.
  *
  * There is deliberately no null member. An observation that cannot be read is
  * not stored at all — the entry is deleted — because a "recorded as unverifiable"
  * value was dead code the moment attribution became a before/after comparison,
  * and a branch nothing can reach is a branch no test can defend.
+ *
+ * It is the observation itself rather than a joined string so that the two
+ * questions stay separately askable after storage. `reattributeHardenedSecretPath`
+ * has to compare the object while deliberately ignoring the freshness, and
+ * recovering one half out of `dev:ino:ctimeNs` by counting colons would make that
+ * comparison depend on a format nothing declares.
  */
-type HardenedIdentity = string;
+type HardenedIdentity = PathObservation;
 
 /**
  * What a stat can tell us about WHICH OBJECT is at a path.
@@ -128,8 +148,8 @@ function observe(targetPath: string): PathObservation | null {
   }
 }
 
-function memoValue(seen: PathObservation): HardenedIdentity {
-  return `${seen.object}:${seen.freshness}`;
+function sameObservation(a: PathObservation, b: PathObservation): boolean {
+  return a.object === b.object && a.freshness === b.freshness;
 }
 
 /**
@@ -155,7 +175,7 @@ function memoSatisfied(cache: Map<string, HardenedIdentity>, targetPath: string)
   // without any ACL work. That needs exact-identity ABA to bite — outside the
   // proof bound this unit claims — but "the consequence is out of scope" is not a
   // reason to keep an entry we have just proven does not describe what is there.
-  if (current === null || memoValue(current) !== remembered) {
+  if (current === null || !sameObservation(current, remembered)) {
     cache.delete(targetPath);
     return false;
   }
@@ -203,7 +223,7 @@ function recordHarden(
     cache.delete(targetPath);
     return false;
   }
-  cache.set(targetPath, memoValue(after));
+  cache.set(targetPath, after);
   return true;
 }
 
@@ -339,7 +359,7 @@ function defaultIcaclsRunner(args: string[], timeoutMs: number): IcaclsResult {
 /**
  * Async icacls runner (#612): yields the event loop while waiting for the child.
  * Async Subprocess has no exitedDueToTimeout, so the shared settlement helper
- * classifies the deadline and abandons a child that does not settle after kill.
+ * classifies the deadline and keeps waiting for a killed child to actually exit.
  */
 async function defaultAsyncIcaclsRunner(args: string[], timeoutMs: number): Promise<IcaclsResult> {
   const proc = trySpawnIcacls(args);
@@ -359,21 +379,78 @@ async function defaultAsyncIcaclsRunner(args: string[], timeoutMs: number): Prom
 function awaitAsyncIcaclsRunner(args: string[], timeoutMs: number): Promise<IcaclsResult> {
   return new Promise(resolve => {
     let settled = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
+    let cancelBelt: (() => void) | undefined;
     const finish = (result: IcaclsResult): void => {
       if (settled) return;
       settled = true;
-      if (timer !== undefined) clearTimeout(timer);
+      cancelBelt?.();
       resolve(result);
     };
-    timer = setTimeout(
-      () => finish({ success: false, exitCode: null, timedOut: true, stdout: "" }),
-      Math.max(1, timeoutMs),
+    const runner = asyncIcaclsRunner(args, timeoutMs).then(
+      result => { finish(result); },
+      () => { finish(spawnFailedResult()); },
+    );
+    // The belt has to outlast the runner it is guarding, or it is not a belt -- it is the
+    // deadline. The runner may now legitimately outlive it while a killed child is reaped. The
+    // caller is still released, but the target is registered so removal can wait for the distinct
+    // handle-release question instead of treating flight settlement as proof that the child died.
+    cancelBelt = asyncIcaclsBeltScheduler(
+      () => {
+        const targetPath = args[0];
+        if (targetPath) registerPendingAsyncIcaclsReap(targetPath, runner);
+        finish({ success: false, exitCode: null, timedOut: true, stdout: "" });
+      },
+      Math.max(1, timeoutMs) + SUBPROCESS_KILL_GRACE_MS + ASYNC_ICACLS_BELT_MARGIN_MS,
     );
-    void asyncIcaclsRunner(args, timeoutMs).then(finish, () => finish(spawnFailedResult()));
   });
 }
 
+function registerPendingAsyncIcaclsReap(targetPath: string, reap: Promise<void>): void {
+  let pending = pendingAsyncIcaclsReaps.get(targetPath);
+  if (!pending) {
+    pending = new Set();
+    pendingAsyncIcaclsReaps.set(targetPath, pending);
+  }
+  pending.add(reap);
+  void reap.finally(() => {
+    pending!.delete(reap);
+    if (pending!.size === 0) pendingAsyncIcaclsReaps.delete(targetPath);
+  });
+}
+
+function pathIsAtOrBelow(targetPath: string, rootPath: string): boolean {
+  const relativePath = relative(resolve(rootPath), resolve(targetPath));
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+/** True while an async icacls runner still owns this exact path after its caller's belt fired. */
+export function windowsSecretAclReapPendingForPath(targetPath: string): boolean {
+  return (pendingAsyncIcaclsReaps.get(targetPath)?.size ?? 0) > 0;
+}
+
+/** Non-blocking removal guard for callers that must refuse rather than wait for a stuck child. */
+export function windowsSecretAclReapPendingAtOrBelow(rootPath: string): boolean {
+  return [...pendingAsyncIcaclsReaps.keys()]
+    .some(targetPath => pathIsAtOrBelow(targetPath, rootPath));
+}
+
+/**
+ * Removal barrier for a file or tree that may still be held by a timed-out icacls child.
+ *
+ * This wait is deliberately separate from ordinary startup and shutdown: a genuinely stuck child
+ * must not defeat the caller-facing belt. Code that chooses to remove the target has the stricter
+ * contract and must not proceed until every registered runner at or below it has actually reaped.
+ */
+export async function flushWindowsSecretAclReapsBeforeRemoval(rootPath: string): Promise<void> {
+  while (true) {
+    const pending = [...pendingAsyncIcaclsReaps]
+      .filter(([targetPath]) => pathIsAtOrBelow(targetPath, rootPath))
+      .flatMap(([, reaps]) => [...reaps]);
+    if (pending.length === 0) return;
+    await Promise.all(pending);
+  }
+}
+
 let icaclsRunner: IcaclsRunner = defaultIcaclsRunner;
 let asyncIcaclsRunner: AsyncIcaclsRunner = defaultAsyncIcaclsRunner;
 let platformOverride: string | null = null;
@@ -389,6 +466,13 @@ export function setAsyncIcaclsRunnerForTests(runner: AsyncIcaclsRunner | null):
   asyncIcaclsRunner = runner ?? defaultAsyncIcaclsRunner;
 }
 
+/** Test seam: fire the outer caller-facing belt without sleeping. */
+export function setAsyncIcaclsBeltSchedulerForTests(
+  scheduler: SubprocessDeadlineScheduler | null,
+): void {
+  asyncIcaclsBeltScheduler = scheduler ?? scheduleAsyncIcaclsBelt;
+}
+
 /**
  * Test seam: force the platform gate (e.g. "win32") so CI on POSIX reaches the runner.
  *
@@ -423,6 +507,58 @@ export function forgetHardenedSecretPath(targetPath: string): void {
   hardenedPaths.delete(targetPath);
 }
 
+/**
+ * Re-attribute an existing file memo to the SAME object after the caller wrote
+ * content to it through a descriptor whose identity it verified.
+ *
+ * This exists because `freshness` is `ctimeNs`, and on Windows libuv reports
+ * `st_ctim` from the NTFS ChangeTime, which moves when file DATA is written. An
+ * atomic writer therefore invalidated its own memo between the harden that
+ * protects the empty temp and the harden before the rename, and paid a second
+ * full `/grant:r` + `/inheritance:r` + `/remove:g` sequence to reapply the ACL
+ * that was already on the file. Every secret write on Windows paid it twice.
+ *
+ * Only the freshness moves, and only for an unchanged object: a different object
+ * retires the entry instead. A caller must have proven, immediately beforehand,
+ * that `targetPath` resolves to the object its own descriptor refers to.
+ *
+ * The cost of this is worth stating exactly, because `PathObservation` documents
+ * that freshness also moves when PERMISSIONS change, and this call cannot tell
+ * the two apart. So a DACL change landing between the harden and this call is
+ * absorbed instead of forcing a re-harden. That window is the caller's own
+ * content write; every permission change after this call still moves ctime
+ * again and still misses the memo, so the detection this memo provides is
+ * relocated, not removed.
+ *
+ * What makes the absorbed window acceptable is who can be in it. Once the harden
+ * has run, the DACL is an explicit owner-only ACE with inheritance removed, so
+ * no other principal can open the file for `WRITE_DAC` at all. The one principal
+ * who can still rewrite that DACL is one holding a handle opened BEFORE the
+ * harden, and Windows keeps the access granted to an open handle: that principal
+ * can equally rewrite the DACL after any later harden, and after the rename, on
+ * the same object. A second mutation pass never bounded that capability — it
+ * stripped an ACE the holder could immediately re-add — so declining to repeat
+ * it removes no guarantee anyone had.
+ *
+ * Refusal is cheap and safe in either direction: an unmoved memo simply means the
+ * caller's next harden runs in full.
+ *
+ * Returns whether the memo now describes what is at the path.
+ */
+export function reattributeHardenedSecretPath(targetPath: string): boolean {
+  const remembered = hardenedPaths.get(targetPath);
+  if (remembered === undefined) return false;
+  const current = observe(targetPath);
+  // Unreadable, or a different object: this is exactly the case the memo must
+  // not cover. Retire it so the next harden is a real one.
+  if (current === null || current.object !== remembered.object) {
+    hardenedPaths.delete(targetPath);
+    return false;
+  }
+  hardenedPaths.set(targetPath, current);
+  return true;
+}
+
 /**
  * Ephemeral-path lifecycle release: clears the success memo AND any timeout
  * memo keyed by THIS TEMP path in both namespaces. Call only after the temp is

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

@@ -160,7 +160,11 @@ async function defaultAsyncWindowsPrincipalRunner(
     stderr: "ignore",
     windowsHide: true,
   });
-  const { exitCode, timedOut } = await waitForSubprocessExit(proc, timeoutMs);
+  // No kill grace. The grace exists so a dying child releases a path someone is about to
+  // remove; this lookup holds no such path, and it runs during `ocx start`, where the composed
+  // acceptance cases already measure real startups at up to 38.8s against a bounded watchdog.
+  // Paying two extra seconds per timed-out resolution there buys nothing and costs margin.
+  const { exitCode, timedOut } = await waitForSubprocessExit(proc, timeoutMs, 0);
   // `.bytes()` rather than `.text()`, for the same reason as the sync runner above.
   const stdout: string | Uint8Array = !timedOut && proc.stdout
     ? await new Response(proc.stdout).bytes().catch(() => new Uint8Array())