@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/responses/state.ts

@@ -16,6 +16,7 @@ import {
   responseSpillDirectory,
   responseSpillPayloadCap,
   markResponseSpillPublicationSuperseded,
+  prospectiveResponseSpillBytes,
   type ResponseSpillPublicationControl,
   type ResponseSpillRef,
   writeResponseSpillDurably,
@@ -35,6 +36,30 @@ const SNAPSHOT_DEBOUNCE_MAX_MS = 30_000;
  * continuation chains) stores the full expanded input each turn — ~quadratic bytes per chain —
  * so a count cap alone cannot bound memory. Oldest-first eviction applies past this mark. */
 export const MAX_STORED_RESPONSE_BYTES = 64 * 1024 * 1024;
+/**
+ * Aggregate ceiling for the durable spill directory: the disk-side counterpart to
+ * the RAM ceiling above. Without it the spilled set is bounded only per-file
+ * (MAX_RESPONSE_SPILL_PAYLOAD_BYTES, 256 MiB) and per-entry (MAX_STORED_RESPONSES,
+ * 1000), whose product is 250 GiB — larger than the disk of any host this runs on.
+ * The only effective bound was therefore RESPONSE_TTL_MS, which makes disk use a
+ * function of client request rate rather than of anything this process controls.
+ *
+ * Measured on one macOS host, 2026-08-30: a client spilling ~150 MB payloads at
+ * ~1.4/min held 6.8 GB after 44 minutes, still climbing toward the ~12 GB an
+ * hour-long window implies, and filled the volume. Retention itself was correct
+ * throughout — the TTL evicted that whole cohort an hour later — so what was
+ * missing is a budget, not a sweep.
+ *
+ * 1 GiB comes from the same sample (n=31), whose spilled sizes are strongly
+ * bimodal: median 1.1 MiB against a p90 of 198.7 MiB, near the per-file ceiling.
+ * At that median the count cap and this ceiling bind within 8% of each other
+ * (1000 x 1.1 MiB = 1.07 GiB), so ordinary traffic sees no eviction it would not
+ * already have seen and only the large tail is cut. Erring small is the safe
+ * direction: too low costs a replay miss, an already-handled path surfaced as
+ * previous_response_not_found, while too high costs the host's disk and every
+ * unrelated process on it.
+ */
+export const MAX_SPILLED_RESPONSE_BYTES = 1024 * 1024 * 1024;
 /** Legacy snapshot selection only. Spill demotion is governed solely by the RAM cap above. */
 const SNAPSHOT_ENTRY_MAX_BYTES = 2 * 1024 * 1024;
 const SNAPSHOT_TOTAL_MAX_BYTES = 24 * 1024 * 1024;
@@ -187,12 +212,79 @@ interface PendingResponseSpill {
   cancelled: boolean;
   released: boolean;
   sizeBytes: number;
+  /** Peak on-disk bytes reserved for this publication; released exactly once on settle. */
+  reservedBytes: number;
   publicationControl: ResponseSpillPublicationControl;
 }
 
 const pendingResponseSpills = new Set<PendingResponseSpill>();
 const pendingResponseSpillById = new Map<string, PendingResponseSpill>();
 let pendingResponseSpillBytes = 0;
+/**
+ * On-disk bytes a queued publication is about to occupy but has not yet installed into
+ * `states`.
+ *
+ * `spilledResponseBytes()` walks installed spills and deferred unlinks — files that
+ * already exist. It cannot see one that `writeResponseSpillDurablyAsync` is in the
+ * middle of creating, and on Windows that middle can last as long as `icacls` takes.
+ * Without a reservation the cap holds only when writes are fast, which is not a cap.
+ *
+ * The reserved figure is the PEAK footprint, not the payload: publication can fall back
+ * from hard-linking to an exclusive copy, and during that fallback the destination copy
+ * and the temp file exist simultaneously. Reserving one envelope would leave the overshoot
+ * intact at half its magnitude.
+ *
+ * Ownership is single: a job holds its reservation from queue until
+ * `releasePendingResponseSpill`, which every exit from the publication path reaches
+ * through the `finally` in `runPendingResponseSpill` and through cancellation of a
+ * not-yet-running job. A leaked reservation is monotonic — it would ratchet the usable
+ * cap toward zero — so the release must stay on the settlement path rather than in a
+ * parallel bookkeeping pass.
+ */
+let reservedResponseSpillBytes = 0;
+/**
+ * Paths a failed cleanup left on the volume, with the bytes each one occupies.
+ *
+ * A failed unlink leaves a real file behind, so the cap has to keep seeing it. But a
+ * never-decremented total would be phantom debt: a Windows lock that clears a moment
+ * later, or the async writer's own retry, can remove the file while the charge stays
+ * forever — and with 256 MiB payloads two conservative charges consume the whole default
+ * cap, after which nothing can spill for the life of the process.
+ *
+ * So the debt is per PATH, priced at what that path actually holds, and settled the
+ * moment the path is gone. `reconcileUnreclaimableSpillPaths` re-checks on every read of
+ * the accounted total, which is the same tick that would otherwise refuse an admission.
+ */
+const unreclaimableSpillPaths = new Map<string, number>();
+
+function chargeUnreclaimableSpillPath(path: string | null | undefined, bytes: number): void {
+  if (!path || bytes <= 0) return;
+  unreclaimableSpillPaths.set(path, bytes);
+}
+
+/** Drop charges for paths that have since disappeared; returns the surviving total. */
+function reconcileUnreclaimableSpillPaths(): number {
+  let total = 0;
+  for (const [path, bytes] of [...unreclaimableSpillPaths]) {
+    if (existsSync(path)) total += bytes;
+    else unreclaimableSpillPaths.delete(path);
+  }
+  return total;
+}
+
+/**
+ * Peak on-disk footprint of publishing this candidate: temp plus destination copy.
+ *
+ * Measured from the production serializer rather than from `candidate.sizeBytes`. The
+ * resident measurement omits the `version` field the published envelope carries, so
+ * pricing an admission by it undercounts and lets a request sitting exactly at the cap
+ * still exceed it. Falls back to the resident figure only when serialization fails, which
+ * is the same condition that will fail the publication itself.
+ */
+function publicationFootprintBytes(id: string, candidate: ResidentResponseState): number {
+  const exact = prospectiveResponseSpillBytes(id, spillPayloadForResident(candidate));
+  return (exact ?? candidate.sizeBytes) * 2;
+}
 let responseSpillPublicationTail: Promise<void> = Promise.resolve();
 let responseSpillShutdownBudgetOverride: { totalMs: number; fallbackReserveMs: number } | null = null;
 let responseSpillShutdownTerminalizationPassLimitOverride: number | null = null;
@@ -210,6 +302,7 @@ function releasePendingResponseSpill(job: PendingResponseSpill): void {
   if (job.released) return;
   job.released = true;
   pendingResponseSpillBytes = Math.max(0, pendingResponseSpillBytes - job.sizeBytes);
+  reservedResponseSpillBytes = Math.max(0, reservedResponseSpillBytes - job.reservedBytes);
   pendingResponseSpills.delete(job);
   if (pendingResponseSpillById.get(job.id) === job) pendingResponseSpillById.delete(job.id);
   job.candidate = null;
@@ -222,6 +315,11 @@ function cancelPendingResponseSpill(id: string): ResponseSpillRef | undefined {
   job.cancelled = true;
   markResponseSpillPublicationSuperseded(job.publicationControl);
   const superseded = job.supersededSpill;
+  // Ownership TRANSFERS to the caller. Leaving the ref on the cancelled job would let the
+  // accounting walk count the same physical file twice — once here and once on the
+  // replacement — and an overcount evicts live continuations to make room for bytes that
+  // are not there.
+  delete job.supersededSpill;
   // A queued job has not captured the candidate in an async frame yet, so release it now.
   // A running job retains its accounting until settlement and will discard its stale file.
   if (!job.running) releasePendingResponseSpill(job);
@@ -313,6 +411,25 @@ function queuePendingResponseSpill(
     deferSupersededSpill(inheritedSpill);
     return;
   }
+  // Enforce the disk cap BEFORE the temp or destination file is created. Deleting the
+  // overflow afterwards is not equivalent: on Windows the file can outlive the decision
+  // by as long as ACL hardening takes, which is the window the measured 6.8 GiB
+  // accumulated in. Reclaim first, and only refuse if the peak footprint still does not
+  // fit — an eviction pass can free a live continuation's worth of room.
+  const footprint = publicationFootprintBytes(id, candidate);
+  // The superseded generation this job is about to own is already off `states` and not
+  // yet on the job, so it is invisible to the walk. Price it here or admission decides
+  // against a total that is short by a whole envelope.
+  const inheritedBytes = inheritedSpill?.payloadBytes ?? 0;
+  if (accountedResponseSpillBytes() + footprint + inheritedBytes > spillByteCap()) {
+    enforceSpilledResponseBudget();
+    if (accountedResponseSpillBytes() + footprint + inheritedBytes > spillByteCap()) {
+      spillCounters.writeFailures += 1;
+      replaceWithSpillFailure(id, candidate);
+      deferSupersededSpill(inheritedSpill);
+      return;
+    }
+  }
   const job: PendingResponseSpill = {
     id,
     candidate,
@@ -322,11 +439,13 @@ function queuePendingResponseSpill(
     cancelled: false,
     released: false,
     sizeBytes: candidate.sizeBytes,
+    reservedBytes: footprint,
     publicationControl: createResponseSpillPublicationControl(),
   };
   pendingResponseSpills.add(job);
   pendingResponseSpillById.set(id, job);
   pendingResponseSpillBytes += job.sizeBytes;
+  reservedResponseSpillBytes += job.reservedBytes;
   recomputeOldestResident();
   responseSpillPublicationTail = responseSpillPublicationTail
     .then(() => runPendingResponseSpill(job), () => runPendingResponseSpill(job));
@@ -418,7 +537,36 @@ function installShutdownFallbackSpill(
   aclBudgetMs: number,
 ): void {
   let ref: ResponseSpillRef | null = null;
+  // Supersession released this job's reservation, but the synchronous write below is the
+  // largest publication of the shutdown path and has its own link-then-copy fallback
+  // holding a temp and a destination at once. Re-reserve for its duration so the cap is
+  // not blind exactly where the drain does its heaviest work, and settle in `finally` so
+  // every return, throw and mismatch releases it.
+  const footprint = publicationFootprintBytes(job.id, candidate);
+  reservedResponseSpillBytes += footprint;
   try {
+    // Supersession released this job, so its superseded generation is no longer visible
+    // to the accounting walk — but the file is still on the volume until
+    // `deferSupersededSpill` or a delete takes it. Price it here or the fallback decides
+    // against a total short by that whole envelope, which is exactly the gap that lets
+    // `debt + footprint <= cap < old + debt + footprint` publish over budget.
+    const supersededBytes = job.supersededSpill?.payloadBytes ?? 0;
+    // The drain must not publish over the cap either. Reclaim first; if the footprint
+    // still does not fit — which is what unreclaimable cleanup debt looks like — the
+    // honest close-out is a tombstone, not another file on a volume that is already
+    // over budget. `replaceWithSpillFailure` is the same fail-closed ending the budget
+    // exhaustion path uses, so replay reports `spill_failed` and the client resends.
+    if (accountedResponseSpillBytes() + supersededBytes > spillByteCap()) {
+      enforceSpilledResponseBudget();
+      if (accountedResponseSpillBytes() + supersededBytes > spillByteCap()) {
+        if (states.get(job.id) === candidate) {
+          spillCounters.writeFailures += 1;
+          replaceWithSpillFailure(job.id, candidate);
+          deferSupersededSpill(job.supersededSpill);
+        }
+        throw Object.assign(new Error("Response spill shutdown fallback exceeds the durable disk cap"), { code: "ENOSPC" });
+      }
+    }
     ref = writeResponseSpillDurably(job.id, spillPayloadForResident(candidate), { aclBudgetMs });
     if (ref.payloadBytes > responseSpillPayloadCap()) {
       deleteResponseSpill(ref);
@@ -445,6 +593,8 @@ function installShutdownFallbackSpill(
       deferSupersededSpill(job.supersededSpill);
     }
     throw error;
+  } finally {
+    reservedResponseSpillBytes = Math.max(0, reservedResponseSpillBytes - footprint);
   }
 }
 
@@ -477,7 +627,20 @@ function supersedeShutdownFallbackBatch(
   }
   for (const { job } of pending) {
     const cleanupFailure = cleanupSupersededResponseSpillPublication(job.publicationControl);
-    if (cleanupFailure) failures.push(cleanupFailure);
+    if (cleanupFailure) {
+      failures.push(cleanupFailure);
+      // Cleanup failed, so an async temp or destination is STILL on the volume. Releasing
+      // the reservation would un-account a file that exists, and the fallback write that
+      // follows reserves only its own footprint — three envelopes on disk priced as two.
+      //
+      // Charge the surviving PATHS rather than a flat two envelopes: `clearOwnedPath`
+      // nulls whichever it managed to remove, so one failure is one file, not two. The
+      // charge is settled automatically once the path disappears, which a retried unlink
+      // or a released Windows lock can still do.
+      const perPath = Math.max(1, Math.floor(job.reservedBytes / 2));
+      chargeUnreclaimableSpillPath(job.publicationControl.tempPath, perPath);
+      chargeUnreclaimableSpillPath(job.publicationControl.destinationPath, perPath);
+    }
     releasePendingResponseSpill(job);
   }
 }
@@ -603,6 +766,69 @@ export function getStoredResponseBytesForTests(): number {
   return storedResponseBytes;
 }
 
+let spillByteCapOverride: number | null = null;
+
+function spillByteCap(): number {
+  return spillByteCapOverride ?? MAX_SPILLED_RESPONSE_BYTES;
+}
+
+/**
+ * Live total of durable spill payloads. Recomputed per call rather than carried as
+ * a running counter: spilled entries reach `states` through several insertion paths
+ * (demotion swap, direct oversized admission, snapshot reload), and one missed
+ * increment there would silently disable the cap, where an O(MAX_STORED_RESPONSES)
+ * walk cannot drift.
+ */
+function spilledResponseBytes(): number {
+  let total = 0;
+  for (const entry of states.values()) {
+    if (entry.kind === "spill") total += entry.spill.payloadBytes;
+  }
+  // Superseded generations awaiting a durable snapshot are still files on disk.
+  // Counting only `states` would let PENDING_SPILL_UNLINKS_MAX of them sit outside
+  // the budget while it reports itself satisfied.
+  for (const ref of pendingSpillUnlinks) total += ref.payloadBytes;
+  return total;
+}
+
+/**
+ * Accounted on-disk bytes: files that exist, plus the peak footprint of publications
+ * already in flight.
+ *
+ * The cap is enforced against this rather than against `spilledResponseBytes()` alone,
+ * because a publication that has not finished is still consuming the volume. On Windows
+ * the gap between "queued" and "installed" is however long `icacls` takes, and the
+ * measured incident this cap answers accumulated 6.8 GiB in 44 minutes.
+ */
+function accountedResponseSpillBytes(): number {
+  // Superseded generations a pending job still owns are files on disk too. A same-id
+  // replacement removes the old spill from `states` and hands its ref to the job, so
+  // counting only `states` plus `pendingSpillUnlinks` loses it for the whole publication
+  // — during a copy fallback that is old generation + new temp + new destination, three
+  // envelopes priced as two.
+  let ownedBySpillJobs = 0;
+  for (const job of pendingResponseSpills) {
+    if (job.supersededSpill) ownedBySpillJobs += job.supersededSpill.payloadBytes;
+  }
+  return spilledResponseBytes() + reservedResponseSpillBytes + ownedBySpillJobs
+    + reconcileUnreclaimableSpillPaths();
+}
+
+/** Test-only: lower/restore the durable spill cap (null restores the default). */
+export function setSpilledResponseByteCapForTests(bytes: number | null): void {
+  spillByteCapOverride = bytes;
+}
+
+/** Test-only: current durable spill accounting (proves evictions unlink their files). */
+export function getSpilledResponseBytesForTests(): number {
+  return spilledResponseBytes();
+}
+
+/** Test-only: on-disk bytes plus in-flight publication reservations. */
+export function getAccountedResponseSpillBytesForTests(): number {
+  return accountedResponseSpillBytes();
+}
+
 function serializedBytes(value: unknown): number | null {
   try {
     const serialized = JSON.stringify(value);
@@ -1495,6 +1721,60 @@ export function replayOverlapSkipsForTests(): number {
   return replayOverlapSkips;
 }
 
+/**
+ * Bring the durable spill set inside MAX_SPILLED_RESPONSE_BYTES, and report the
+ * bytes released.
+ *
+ * One owner, three callers: mutation pruning, the lazy load that follows a
+ * restart, and the periodic sweep. The periodic caller is not redundant — the
+ * mutation path only runs when traffic arrives, and a process can come up over
+ * budget from a snapshot written under a larger ceiling and then sit idle. That
+ * was observed in production at 1.8 GiB against a 1 GiB cap, held until the first
+ * request.
+ *
+ * NOT covered here: spill files orphaned by a crash. They are absent from
+ * `states`, so this function can neither see nor price them, and they stay with
+ * recoverOrphanedResponseSpills and its RESPONSE_SPILL_ORPHAN_GRACE_MS window.
+ * This ceiling therefore bounds what the store owns, which is every file it can
+ * account for, and not the directory as a whole.
+ */
+function enforceSpilledResponseBudget(): number {
+  // Price in-flight publications too: a file being created by
+  // `writeResponseSpillDurablyAsync` occupies the volume before it reaches `states`.
+  let spilledBytes = accountedResponseSpillBytes();
+  if (spilledBytes <= spillByteCap()) return 0;
+  const before = spilledBytes;
+  // Deferred generations go first. They are already superseded, so releasing one
+  // costs only the crash window the queue exists to cover — the same trade
+  // PENDING_SPILL_UNLINKS_MAX already makes against unbounded disk. Evicting a
+  // live continuation to make room for a dead file would be the wrong order.
+  while (spilledBytes > spillByteCap() && pendingSpillUnlinks.length > 0) {
+    const ref = pendingSpillUnlinks.shift()!;
+    spilledBytes -= ref.payloadBytes;
+    deleteResponseSpill(ref);
+  }
+  // Ordered by createdAt, not by map order. `states` is not an age index:
+  // demotion and spill replacement delete and reinsert entries, and
+  // writeBoundedSnapshot serializes the map reversed, so map order can put a
+  // newer continuation first — and evicting that one spends a resume the older
+  // entry would not have cost. Sorting is O(k log k) over the spilled subset and
+  // runs only on a tick already over budget.
+  const spilled = [...states]
+    .filter((pair): pair is [string, SpilledResponseState] => pair[1].kind === "spill")
+    // createdAt is millisecond-resolution, so ties are ordinary under load. A
+    // stable sort would then fall back to insertion order — the very order this
+    // is avoiding — so break ties on the response id. Not localeCompare: the
+    // order must not depend on the host locale.
+    .sort((a, b) => a[1].createdAt - b[1].createdAt
+      || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  for (const [id, entry] of spilled) {
+    if (spilledBytes <= spillByteCap()) break;
+    spilledBytes -= entry.spill.payloadBytes;
+    deleteEntry(id);
+  }
+  return before - spilledBytes;
+}
+
 function pruneResponses(at = now()): void {
   for (const [id, state] of states) {
     if (at - state.createdAt > RESPONSE_TTL_MS) deleteEntry(id);
@@ -1537,6 +1817,7 @@ function pruneResponses(at = now()): void {
       replaceWithSpillFailure(oldestId, entry);
     }
   }
+  enforceSpilledResponseBudget();
 }
 
 /** Periodic TTL-only sweep; count/byte eviction remains owned by mutation paths. */
@@ -1547,7 +1828,10 @@ export function sweepExpiredResponseStates(at = now()): number {
     deleteEntry(id);
     removed += 1;
   }
-  if (removed > 0) schedulePersist();
+  // The disk ceiling needs a caller that does not depend on traffic. The return
+  // value stays the TTL count so this function's existing contract is unchanged.
+  const reclaimed = enforceSpilledResponseBudget();
+  if (removed > 0 || reclaimed > 0) schedulePersist();
   return removed;
 }
 
@@ -1995,6 +2279,8 @@ export function clearResponseStateMemoryForTests(): void {
 export function clearResponseStateForTests(): void {
   for (const entry of states.values()) deleteOwnedSpills(entry);
   clearResponseStateMemoryForTests();
+  reservedResponseSpillBytes = 0;
+  unreclaimableSpillPaths.clear();
   try {
     unlinkSync(snapshotPath());
   } catch {

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

@@ -21,6 +21,7 @@ import { createIntegrationStateStore, type IntegrationStateStore } from "../../i
 import {
   applyIntegrationCoordinated,
   disableIntegrationCoordinated,
+  overwriteIntegrationCoordinated,
   restoreIntegrationCoordinated,
   type IntegrationRestoreInput,
   type IntegrationWriteInput,
@@ -70,7 +71,7 @@ export interface IntegrationJournalEnvelope {
 export interface IntegrationJournalRow {
   opId: string;
   clientId: IntegrationClientId;
-  kind: "apply" | "disable" | "refresh" | "restore";
+  kind: "apply" | "disable" | "refresh" | "restore" | "overwrite";
   at: string;
   configPath: string;
   snapshot: "none" | "stored" | "expired";
@@ -79,6 +80,14 @@ export interface IntegrationJournalRow {
 
 export interface IntegrationToggleBody {
   enabled: boolean;
+  /**
+   * Opt in to replacing a conflicted block with the one opencodex would write.
+   *
+   * Absent and `false` behave identically and are the only states a caller
+   * reaches by accident, which is the point: the conflict refusal protects work
+   * we did not author, so it can only be waived by asking for it by name.
+   */
+  overwriteConflict?: boolean;
 }
 
 export interface IntegrationRestoreBody {
@@ -472,16 +481,38 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
       code: "invalid_enabled",
     }, 400, req, ctx.config);
   }
+  if (parsed.overwriteConflict !== undefined && typeof parsed.overwriteConflict !== "boolean") {
+    return jsonResponse({
+      error: "overwriteConflict must be a boolean",
+      code: "invalid_overwrite_conflict",
+    }, 400, req, ctx.config);
+  }
+  /*
+   * Rejected rather than ignored. Disabling a block we do not own is precisely
+   * the deletion this subsystem exists to prevent, so a caller sending this
+   * combination has misunderstood the field, and silently dropping it would
+   * answer 200 for a request whose intent we refused.
+   */
+  if (parsed.overwriteConflict === true && parsed.enabled === false) {
+    return jsonResponse({
+      error: "overwriteConflict applies only to enabling an integration",
+      code: "invalid_overwrite_conflict",
+    }, 400, req, ctx.config);
+  }
 
   try {
     const input = await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
     const result = await runIntegrationMutationFlight(
       requestedClient,
-      parsed.enabled ? "apply" : "disable",
+      parsed.enabled ? (parsed.overwriteConflict === true ? "overwrite" : "apply") : "disable",
       input.io?.now ?? Date.now,
-      () => parsed.enabled
-        ? applyIntegrationCoordinated(input, { lockSeams: integrationMutationTestHooks?.lockSeams })
-        : disableIntegrationCoordinated(input, { lockSeams: integrationMutationTestHooks?.lockSeams }),
+      () => {
+        const options = { lockSeams: integrationMutationTestHooks?.lockSeams };
+        if (!parsed.enabled) return disableIntegrationCoordinated(input, options);
+        return parsed.overwriteConflict === true
+          ? overwriteIntegrationCoordinated(input, options)
+          : applyIntegrationCoordinated(input, options);
+      },
     );
     if (!result.ok) return writerFailureResponse(requestedClient, result, ctx);
     return jsonResponse(result satisfies IntegrationToggleEnvelope, 200, req, ctx.config);

package/src/server/management-api.ts

@@ -256,10 +256,46 @@ export async function handleManagementAPI(
   if (routed) return routed;
 
   if (url.pathname === "/api/stop" && req.method === "POST") {
-    const { restoreNativeCodexAsync } = await import("../codex/inject");
-    const { stopServiceIfInstalled, isServiceOwnershipError } = await import("../service");
+    const { installedServiceRespawnRisk, stopServiceIfInstalledDetailed, isServiceOwnershipError } = await import("../service");
+    // `ocx stop` performs its own shared teardown AFTER verifying the scheduler did not
+    // respawn the proxy (#3008). Without this the child restores native Codex and strips
+    // the Grok fence here, so a survivor found moments later has already had the shared
+    // config pulled out from under it — and the parent's `ownershipBlocked` guard can
+    // only prevent a second, redundant teardown. A direct caller sends nothing and keeps
+    // the self-contained behaviour.
+    //
+    // The query flag alone is not enough to hand over the obligation: any authenticated
+    // caller could set it and simply exit, leaving client config pointed at a proxy that
+    // no longer exists. Honour the deferral only when the caller left a pending-teardown
+    // receipt on disk, which a later stop/update can find and finish.
+    // Decide BEFORE touching the manager. Stopping the Task Scheduler task and then
+    // refusing left the proxy running with its manager stopped — worse than either
+    // outcome. This process cannot verify its own post-exit respawn window; only the
+    // receipt-backed parent `ocx stop` can, which is what the deferral exists for.
+    const { deferralMatchesReceipt } = await import("../config/pending-teardown");
+    const { deferralHonored, performStopTeardown } = await import("./stop-teardown");
+    const holdsReceipt = deferralHonored(url, deferralMatchesReceipt);
+    const respawnRisk = holdsReceipt ? "none" : installedServiceRespawnRisk();
+    if (respawnRisk === "respawnable") {
+      return jsonResponse({
+        success: false,
+        code: "respawnable_service",
+        message: "This proxy is managed by a Task Scheduler wrapper that can respawn it, so the stop must be run by `ocx stop`, which verifies the respawn window. Nothing was changed.",
+      }, 409, req, config);
+    }
+    if (respawnRisk === "unknown") {
+      // Do NOT send them to `ocx stop`: it maps the same unanswerable probe to a stop
+      // failure, so that advice would be a loop. The scheduler query itself is what needs
+      // fixing (#3008).
+      return jsonResponse({
+        success: false,
+        code: "service_state_unknown",
+        message: "The Windows Task Scheduler state could not be read, so this proxy cannot tell whether a wrapper would respawn it. Nothing was changed. Run `ocx service status` to see the query error, repair Task Scheduler access, then retry.",
+      }, 409, req, config);
+    }
+    let serviceStop: import("../service").ServiceStopOutcome;
     try {
-      stopServiceIfInstalled();
+      serviceStop = stopServiceIfInstalledDetailed();
     } catch (err) {
       if (isServiceOwnershipError(err)) {
         // The installed service belongs to another CODEX_HOME/OPENCODEX_HOME: it would respawn
@@ -269,12 +305,30 @@ export async function handleManagementAPI(
       }
       throw err;
     }
-    const restore = await restoreNativeCodexAsync();
+    // The boolean helper collapses "failed" into the same false as "no service installed",
+    // so this route used to tear down shared config and exit while a manager that refused
+    // to stop was still there to respawn the proxy (#3008).
+    if (serviceStop === "failed") {
+      return jsonResponse({
+        success: false,
+        message: "The installed service manager did not stop; it may respawn the proxy. Shared client config was left alone. Run `ocx stop` from the home that owns the service.",
+      }, 409, req, config);
+    }
+    if (serviceStop === "state-unknown") {
+      // Same case, same remedy as the pre-check: the query is what needs fixing.
+      return jsonResponse({
+        success: false,
+        code: "service_state_unknown",
+        message: "The Windows Task Scheduler state could not be read, so this proxy cannot tell whether a wrapper would respawn it. Shared client config was left alone. Run `ocx service status` to see the query error, repair Task Scheduler access, then retry.",
+      }, 409, req, config);
+    }
+    // The pre-check above already refused the respawnable case without a receipt, so
+    // reaching here with one means the parent owns the verification.
     // Both managed configs come down together on an explicit teardown. The daemon's own
     // syncCleanup skips this when OCX_SERVICE is set (so a crash/respawn keeps the fence),
-    // which is exactly why an intentional stop has to do it here.
-    const { stripGrokConfig } = await import("../grok/inject");
-    const grok = stripGrokConfig();
+    // which is exactly why an intentional stop has to do it here — unless the caller is
+    // `ocx stop`, which does it itself once the proxy is proven down.
+    const teardown = await performStopTeardown(url, { ownsReceipt: deferralMatchesReceipt });
     setTimeout(async () => {
       let shutdownSucceeded = false;
       try {
@@ -282,12 +336,12 @@ export async function handleManagementAPI(
       } catch {
         console.warn("[opencodex] shutdown drain failed");
       }
-      process.exit(shutdownSucceeded ? 0 : 1);
+      // A drained proxy whose shared teardown failed did not finish the job. Exiting 0
+      // told a supervisor the stop was clean while native Codex or the Grok fence was
+      // still pointed at this process (#3008).
+      process.exit(shutdownSucceeded && teardown.success ? 0 : 1);
     }, 200);
-    const grokNote = grok.ok ? "" : ` Grok config cleanup failed: ${grok.message}`;
-    return jsonResponse(restore.success
-      ? { success: true, message: `Proxy stopping, native Codex restored.${grokNote}` }
-      : { success: false, message: `Proxy stopping, but native Codex restore failed: ${restore.message}. Run \`ocx restore\`.${grokNote}` });
+    return jsonResponse(teardown);
   }
 
   if (url.pathname.startsWith("/api/native-main-profiles")) {

package/src/server/responses/encrypted-payload.ts

@@ -175,7 +175,24 @@ function textWithoutFernetRuns(payload: string, runs: readonly FernetTokenRun[])
   return `${text}${payload.slice(last)}`;
 }
 
-export const AGENT_MESSAGE_ROUTING_ENVELOPE = /(?:^|\n)Message Type\s*:\s*NEW_TASK[^\n]*\nTask name\s*:[^\n]*\nSender\s*:[^\n]*\nPayload\s*:\s*(?:\n|$)/gi;
+/**
+ * The routing header codex-rs writes above a delegated agent payload.
+ *
+ * `MESSAGE` is matched as well as `NEW_TASK`, and only for the unreadability CHECK --
+ * recovery stays NEW_TASK-only. #3021 reported a subagent `MESSAGE` arriving in the
+ * parent conversation as raw `gAAAA...` ciphertext after an `adapter_eof`. The detector
+ * decides "unreadable" by stripping the envelope and asking whether any plaintext
+ * survives, so an envelope shape it does not recognise counts as surviving text: a
+ * `MESSAGE` whose entire body is one Fernet token measured as READABLE and was forwarded
+ * verbatim.
+ *
+ * Widening the strip is not the same as widening recovery. Recovery decrypts, and
+ * decrypting a `MESSAGE` on the parent's behalf would build a plaintext oracle out of a
+ * payload the parent's session may have no right to read. This only lets the proxy
+ * NOTICE that what it is about to forward is unreadable ciphertext, which is what the
+ * report asks for: fail closed with a structured error rather than paste the token.
+ */
+export const AGENT_MESSAGE_ROUTING_ENVELOPE = /(?:^|\n)Message Type\s*:\s*(?:NEW_TASK|MESSAGE)[^\n]*\nTask name\s*:[^\n]*\nSender\s*:[^\n]*\nPayload\s*:\s*(?:\n|$)/gi;
 
 // CXC is the compatibility-hook control namespace. Strip only the tagged paragraph:
 // later untagged paragraphs may be genuine task text. Repeated CXC paragraphs are