@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/config/pending-teardown.ts

@@ -0,0 +1,286 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { atomicWriteFile } from "./atomic-write";
+import { getConfigDir } from "./paths";
+
+/**
+ * Ownership receipt for a deferred shared teardown (#3008).
+ *
+ * `ocx stop` asks the proxy NOT to restore native Codex and the Grok fence, because a
+ * stopped Task Scheduler can respawn the proxy and a survivor must keep its client
+ * config. That hands one obligation to the parent — and a bare query flag cannot express
+ * an obligation: if the parent dies between the child's exit and its own restore, the
+ * shared config keeps pointing at a proxy that is gone, with nothing on disk saying so.
+ *
+ * The receipt is that missing state. The parent writes it BEFORE asking for a deferred
+ * stop and removes it only after its own restore, so a later `ocx stop`/`ocx update` can
+ * see the abandoned obligation and finish it once that proxy is proven down.
+ *
+ * ## Why the nonce is the FILENAME
+ *
+ * One shared file cannot be cleared safely. Read-compare-unlink is three syscalls, and a
+ * concurrent stop replacing the file between the compare and the unlink means this run
+ * deletes an obligation it never owned — the check passed against bytes that are already
+ * gone. Giving each claim its own path removes the race rather than serializing it:
+ * `unlink` names one specific obligation, so it can only ever delete that one. Two
+ * concurrent stops hold two receipts, which is the truth of the situation.
+ */
+export type PendingTeardownReceipt = {
+  /** Process that accepted the obligation, so a live owner is distinguishable from a dead one. */
+  ownerPid: number;
+  /** Identity of this claim; also its filename, which is what makes a clear a single-syscall delete. */
+  nonce: string;
+  /** ISO timestamp, for diagnostics only; recovery is decided by liveness, not by age. */
+  createdAt: string;
+  /**
+   * Endpoint the owner was stopping.
+   *
+   * Recovery has to prove THAT proxy is down, and after a crash the runtime-port record
+   * is usually gone. Falling back to the configured port asks the wrong question for a
+   * proxy started with an explicit `--port`: the configured port refuses while the live
+   * one keeps serving, and its client config gets torn out from under it.
+   */
+  endpoint: { hostname: string; port: number };
+  /**
+   * How the endpoint was obtained.
+   *
+   * `exact` came from the runtime record or a successful liveness probe — the address the
+   * stop actually contacted. `guessed` is the configured listen address, recorded because
+   * an obligation with a weak address beats no obligation at all, but it is NOT evidence:
+   * a proxy on an explicit `--port` can be respawned there while the configured port
+   * refuses, and treating that refusal as proof would restore under a live proxy. A
+   * guessed receipt therefore fails closed into manual recovery.
+   */
+  endpointSource: "exact" | "guessed";
+};
+
+/**
+ * What is on disk, kept distinct from what it means.
+ *
+ * Collapsing a malformed file into "no receipt" loses the one fact recovery needs: an
+ * obligation may still be outstanding, and its owner can no longer be identified. That
+ * state must not silently authorize a deferral, and it must not wedge every later stop
+ * either — see {@link quarantinePendingTeardown}.
+ */
+export type PendingTeardownRead =
+  | { state: "missing" }
+  | { state: "valid"; receipt: PendingTeardownReceipt }
+  | { state: "invalid"; nonce: string; detail: string };
+
+/**
+ * The home itself could not be listed.
+ *
+ * Distinct from an invalid receipt: there is no file to quarantine and no nonce to name,
+ * so it must never be fed to the receipt machinery. It blocks like any obligation, but the
+ * remedy is to fix the directory and retry, not to remove something.
+ */
+export type TeardownScanFailure = { state: "unscannable"; detail: string };
+
+import {
+  isPendingTeardownFileName,
+  isAnyTeardownObligationFileName,
+  PENDING_TEARDOWN_PREFIX as PREFIX,
+  PENDING_TEARDOWN_SUFFIX as SUFFIX,
+  PENDING_TEARDOWN_UNREADABLE_SUFFIX as UNREADABLE_SUFFIX,
+  pendingTeardownNonceFromFileName,
+} from "./pending-teardown-names.mjs";
+
+const NONCE_RE = /^[0-9a-f]{32}$/;
+
+export function pendingTeardownPathFor(nonce: string): string {
+  return join(getConfigDir(), `${PREFIX}${nonce}${SUFFIX}`);
+}
+
+function isReceipt(value: unknown, nonce: string): value is PendingTeardownReceipt {
+  if (!value || typeof value !== "object") return false;
+  const receipt = value as Record<string, unknown>;
+  const endpoint = receipt.endpoint as Record<string, unknown> | undefined;
+  const endpointOk = !!endpoint
+    && typeof endpoint === "object"
+    && typeof endpoint.hostname === "string"
+    && endpoint.hostname.trim() !== ""
+    && Number.isInteger(endpoint.port)
+    && Number(endpoint.port) > 0
+    && Number(endpoint.port) <= 65535;
+  return Number.isSafeInteger(receipt.ownerPid)
+    && Number(receipt.ownerPid) > 0
+    // The body must agree with the name: a receipt whose nonce was edited to name a
+    // different claim would let a request authorize a deferral it does not own.
+    && receipt.nonce === nonce
+    && typeof receipt.createdAt === "string"
+    && (receipt.endpointSource === "exact" || receipt.endpointSource === "guessed")
+    && endpointOk;
+}
+
+/** Claim a deferred teardown for this process. Returns the receipt that was written. */
+export function claimPendingTeardown(
+  endpoint: { hostname: string; port: number },
+  endpointSource: "exact" | "guessed",
+  ownerPid: number = process.pid,
+): PendingTeardownReceipt {
+  const dir = getConfigDir();
+  assertNotRealHomeUnderTest(dir);
+  const nonce = randomBytes(16).toString("hex");
+  const receipt: PendingTeardownReceipt = { ownerPid, nonce, createdAt: new Date().toISOString(), endpoint, endpointSource };
+  atomicWriteFile(pendingTeardownPathFor(nonce), JSON.stringify(receipt, null, 2) + "\n");
+  return receipt;
+}
+
+export function readPendingTeardown(nonce: string): PendingTeardownRead {
+  if (!NONCE_RE.test(nonce)) return { state: "missing" };
+  let raw: string;
+  try {
+    raw = readFileSync(pendingTeardownPathFor(nonce), "utf-8");
+  } catch (error) {
+    // Only "there is no file" is absence. A permission error, or a directory sitting where
+    // the receipt belongs, means something IS there and cannot be read; calling that
+    // missing hides an obligation that may still be outstanding.
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { state: "missing" };
+    return { state: "invalid", nonce, detail: `unreadable (${code ?? "unknown"})` };
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isReceipt(parsed, nonce)) return { state: "valid", receipt: parsed };
+    const digest = createHash("sha256").update(raw).digest("hex").slice(0, 12);
+    return { state: "invalid", nonce, detail: `malformed receipt (sha256 ${digest})` };
+  } catch {
+    return { state: "invalid", nonce, detail: "unparseable JSON" };
+  }
+}
+
+/** An obligation that exists on disk — the "missing" case cannot occur in a listing. */
+export type OutstandingTeardown = Exclude<PendingTeardownRead, { state: "missing" }> | TeardownScanFailure;
+
+/**
+ * Every obligation currently on disk, attributable or not.
+ *
+ * A scan that FAILS is not an empty scan. Swallowing a permission or I/O error into `[]`
+ * would let `handleStop` restore client config with an unread obligation sitting right
+ * there, so anything but a missing home surfaces as one unreadable obligation the caller
+ * must treat like any other: blocking, and needing a human.
+ */
+export function listPendingTeardowns(): OutstandingTeardown[] {
+  let names: string[];
+  try {
+    names = readdirSync(getConfigDir());
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    // Not an invalid RECEIPT: there is no file here and no nonce to name. Synthesizing one
+    // would hand a fabricated identity to the quarantine and clear paths, which could then
+    // rename or delete a real receipt that happened to carry it.
+    return [{ state: "unscannable", detail: `the opencodex home could not be listed (${(error as NodeJS.ErrnoException).code ?? "unknown"})` }];
+  }
+  const out: OutstandingTeardown[] = [];
+  for (const name of names) {
+    // One naming rule, shared with the npm launcher: the two lanes drifting apart is
+    // exactly how the Node updater stopped seeing receipts at all.
+    if (!isPendingTeardownFileName(name)) continue;
+    const nonce = pendingTeardownNonceFromFileName(name)!;
+    const read = readPendingTeardown(nonce);
+    if (read.state !== "missing") out.push(read);
+  }
+  return out;
+}
+
+/**
+ * Is any obligation outstanding, whether or not it can still be attributed?
+ *
+ * Quarantined receipts count. Filing an unreadable one away must not let the next update
+ * install over a teardown that never ran — that would turn "we could not tell" into "it
+ * is fine", which is the failure this whole mechanism exists to prevent.
+ */
+export function pendingTeardownOutstanding(): boolean {
+  try {
+    return readdirSync(getConfigDir()).some(isAnyTeardownObligationFileName);
+  } catch (error) {
+    // Only a missing home is empty. Any other scan failure may be hiding an obligation,
+    // and reporting "none" would unblock an update over a teardown that never ran.
+    return (error as NodeJS.ErrnoException).code !== "ENOENT";
+  }
+}
+
+/** Paths of quarantined obligations awaiting a human. */
+export function listQuarantinedTeardowns(): string[] {
+  try {
+    return readdirSync(getConfigDir())
+      .filter(name => name.startsWith(PREFIX) && name.endsWith(UNREADABLE_SUFFIX))
+      .map(name => join(getConfigDir(), name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Remove exactly one obligation.
+ *
+ * The nonce is the filename, so this is a compare-and-delete in one syscall: it can never
+ * remove a receipt another process wrote, because that receipt lives at a different path.
+ * Returns whether the obligation is gone — a failed unlink is reported rather than
+ * swallowed, since a receipt that survives its discharge re-triggers recovery forever.
+ */
+export function clearPendingTeardown(nonce: string): boolean {
+  try {
+    unlinkSync(pendingTeardownPathFor(nonce));
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT";
+  }
+}
+
+/**
+ * Move an unattributable obligation aside.
+ *
+ * An invalid receipt names no endpoint, so nothing can prove its proxy is down, so it can
+ * never be discharged the normal way. Left in place it is not merely useless: both
+ * updater gates treat an outstanding receipt as a reason to run the stop, and that stop
+ * would fail on the same receipt every time — an update that can never proceed.
+ *
+ * Renaming stops the recovery loop from re-reading garbage on every stop, but it
+ * deliberately does NOT stop the obligation from counting: `pendingTeardownOutstanding`
+ * still sees it, so both updaters keep refusing to install over a teardown that never
+ * ran. Only a human removing the file ends the enforcement.
+ *
+ * Returns the path it was moved to, or null when it could not be moved.
+ */
+export function quarantinePendingTeardown(nonce: string): string | null {
+  const from = pendingTeardownPathFor(nonce);
+  if (!existsSync(from)) return null;
+  const to = join(getConfigDir(), `${PREFIX}${nonce}${UNREADABLE_SUFFIX}`);
+  try {
+    renameSync(from, to);
+    return to;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when a previous deferred stop left its obligation unfinished.
+ *
+ * A receipt whose owner is still alive belongs to a stop that is still running: leave it
+ * alone. Only an abandoned obligation is a candidate, and a VALID one still has to prove
+ * its endpoint is down before anything is restored — an invalid one never can, which is
+ * what {@link quarantinePendingTeardown} exists for.
+ */
+export function isPendingTeardownAbandoned(
+  read: PendingTeardownRead | TeardownScanFailure,
+  isAlive: (pid: number) => boolean,
+  selfPid: number = process.pid,
+): boolean {
+  if (read.state === "missing") return false;
+  // A home that cannot be listed may be hiding an obligation. It is not recoverable and
+  // not removable; the caller blocks on it and asks for the directory to be fixed.
+  if (read.state === "unscannable") return true;
+  if (read.state === "invalid") return true;
+  if (read.receipt.ownerPid === selfPid) return false;
+  return !isAlive(read.receipt.ownerPid);
+}
+
+/** Does this request name an obligation that exists and is readable? */
+export function deferralMatchesReceipt(nonce: string | null): boolean {
+  if (!nonce || !NONCE_RE.test(nonce)) return false;
+  return readPendingTeardown(nonce).state === "valid";
+}

package/src/generated/compatibility-version.json

@@ -10,7 +10,7 @@
     },
     {
       "path": "package.json",
-      "sha256": "2f4952bf558b8eb933baf016cdf0f17b492df49c6d28977dbc132511e0e87039"
+      "sha256": "d90634511c7c4700a847a147914f913ffc8e68f604c9fab2c5fbcc94a33c8f3d"
     },
     {
       "path": "scripts/model-metadata.source.json",
@@ -130,7 +130,7 @@
     },
     {
       "path": "src/adapters/cursor/live-models.ts",
-      "sha256": "a879e9abb107b428428f4b794631855ce5ffe1fc6c1efaea35aa236ce85ada79"
+      "sha256": "14952cb90aff21691c8690dd227ca9c011e8eac945ada84886aca6c663cba827"
     },
     {
       "path": "src/adapters/cursor/live-smoke-gate.ts",
@@ -338,7 +338,7 @@
     },
     {
       "path": "src/adapters/openai-responses.ts",
-      "sha256": "99ce3fa3f92a71f2911b4374c57d6127b090c07c80312190fe4cf5d03e0d5990"
+      "sha256": "70c58ec5f2a0f6e67ace885973373b976d053068be9c19a7f4355dfb4ecbde5b"
     },
     {
       "path": "src/adapters/registry.ts",
@@ -374,7 +374,7 @@
     },
     {
       "path": "src/bridge.ts",
-      "sha256": "7601fe2e59c0b479705aa1c94432d9d4995baa9032cc3afe1ff45146ad33707b"
+      "sha256": "949af46c2a1eba9c25283a442326c2e6acfd07e9653abec5488ec3bade1faa23"
     },
     {
       "path": "src/chat/inbound.ts",
@@ -550,7 +550,7 @@
     },
     {
       "path": "src/cli/dispatch.ts",
-      "sha256": "06d982ffba1599a6c8cd897144565b6d71053152b450fd87b76616c15662cedf"
+      "sha256": "7a755e1a26b2fe769d5d3cb68022ec7ae32df8f423ef5698590a4276933baed7"
     },
     {
       "path": "src/cli/doctor.ts",
@@ -570,7 +570,7 @@
     },
     {
       "path": "src/cli/index.ts",
-      "sha256": "882ed1ad0bc92b1d3a031cc0904d3e3a2c77c7e683e5cf83b0cdd260a5c20870"
+      "sha256": "447dd3d1b3ca743f9041ee6644b4d106ce5baf10ddee324fa559be06ef1534c3"
     },
     {
       "path": "src/cli/init.ts",
@@ -582,7 +582,7 @@
     },
     {
       "path": "src/cli/integrations.ts",
-      "sha256": "5c54432f2b8c53d83f4b40d72a2922745b095c1c0280fe6188f6b9af33f891bb"
+      "sha256": "ead7fa2e3db71765e3a63ff275265599878de180ca653bf03d06427eec3e235e"
     },
     {
       "path": "src/cli/interactive-confirm.ts",
@@ -672,6 +672,10 @@
       "path": "src/cli/tray-proxy.ts",
       "sha256": "35878717b3b9c9e9d7793fc88a72ddf21d7b2c9b41c3a6dd12f5bb5d5343a6d5"
     },
+    {
+      "path": "src/cli/uninstall-plan.ts",
+      "sha256": "786c9f754b76a8a7fbf11a1893f8eb9a228138e822eee50c21513ea248ece34e"
+    },
     {
       "path": "src/cli/usage-report.ts",
       "sha256": "0c590155ff4c4dbb39ea0a91160abf54a1b70e24060eb792df27a36fba98637a"
@@ -722,7 +726,7 @@
     },
     {
       "path": "src/codex/account-store.ts",
-      "sha256": "db95c62d3f9edb4013e7c3f13e56680c494063182a8747781ef315e4d531ba98"
+      "sha256": "27786f63ee9887225ffeb4b6dd9a9e3592e89add7a3dbf4b190dbf5b4ceb1faa"
     },
     {
       "path": "src/codex/account-usability.ts",
@@ -746,7 +750,7 @@
     },
     {
       "path": "src/codex/auth-api.ts",
-      "sha256": "d3c2d30ec9b919cd7a366c5a968b3697735cc7ad1ce9d9f6fa711c905fe9a397"
+      "sha256": "60aa8e4d07fd5881c79fc3b7f9decbe8c669d14be2f71d48b01ab4da6e094790"
     },
     {
       "path": "src/codex/auth-collision.ts",
@@ -814,7 +818,7 @@
     },
     {
       "path": "src/codex/catalog/provider-fetch.ts",
-      "sha256": "05bbedcadd91339176745ba89d6ecb1a9b0813844f8f7361ab427d14b53e84ae"
+      "sha256": "d8d3de67bdef52c26518948024a6a4dcfe7bbda6a9139b2eb4de26327eaed4a7"
     },
     {
       "path": "src/codex/catalog/sync.ts",
@@ -874,7 +878,7 @@
     },
     {
       "path": "src/codex/history-job.ts",
-      "sha256": "951fdca381d50485f443f999fa0608e597cc078c9428d58faeb0e670739dce58"
+      "sha256": "de26dbf66f1829fa414f787507256e1cb2c9e0977c8de389445b27546d1ab462"
     },
     {
       "path": "src/codex/history-lock.ts",
@@ -882,7 +886,7 @@
     },
     {
       "path": "src/codex/history-manifest.ts",
-      "sha256": "b06a7f92e3be17dff561ad5790e6ab41b9b2f392b8d0343d23bc2025d9791c68"
+      "sha256": "92431ddf0d11bab671c89a4b99e86049b1794b7ac9f07e7ba2709508d349cab8"
     },
     {
       "path": "src/codex/history-migration-guardian.ts",
@@ -890,7 +894,7 @@
     },
     {
       "path": "src/codex/history-provider.ts",
-      "sha256": "3806236a1614440d8d5aa88612454efb82c64586d6f7c69ceaf00b0ad8564d9a"
+      "sha256": "1dd6c56defc42647592d5858147655fbd618368db0cccffc8234dd76135a0a86"
     },
     {
       "path": "src/codex/history-transition.ts",
@@ -898,7 +902,7 @@
     },
     {
       "path": "src/codex/history-worker.ts",
-      "sha256": "6fa95723c28b1944f718ca5f8963b44f2318f0460b061b5cb6cbfce09f11726c"
+      "sha256": "f3dc8ad9a64af62423eac8d106e76a87d5f8be1aa098cc204fd7c8d7bbc9daae"
     },
     {
       "path": "src/codex/home.ts",
@@ -1080,13 +1084,21 @@
       "path": "src/codex/prompt-text-probe.ts",
       "sha256": "6ab1a59afb4f0a5a7239490d5c3ec6d07f52f8cc323a60462a1776eff065e028"
     },
+    {
+      "path": "src/codex/quota-401-recovery.ts",
+      "sha256": "a7098de48a250f10212da8f26a098e3f139649adf295f7f9df789ad6e3e8ff52"
+    },
+    {
+      "path": "src/codex/quota-recovery-timing.ts",
+      "sha256": "b8c0c6911b8ef908bfc81919005942f73672e7e0d51a593200736d3557bfce43"
+    },
     {
       "path": "src/codex/quota-rejection.ts",
       "sha256": "610c38395e08eaeb318cfed5c8472d9c0c8f1b818dd79dc6f45c5b6fbdbce226"
     },
     {
       "path": "src/codex/quota.ts",
-      "sha256": "ac3a3e4a96f544a0d650dbe4b53e6bcdd7af29dd8380b2d03bacadae495f4220"
+      "sha256": "f30fe0a4a652a28ee9200a352d9fad31a979e2dd6bf0324002dc72b25404286d"
     },
     {
       "path": "src/codex/refresh.ts",
@@ -1102,7 +1114,7 @@
     },
     {
       "path": "src/codex/routing.ts",
-      "sha256": "d4022f427c6957c76aff57473e91aa61bdf1df69c9e1922c61b6da546c4f91a5"
+      "sha256": "4515c98f6b2e7dbd8ba3f5bf961329a3a0006bffc9e587bba957f05e7789bb6c"
     },
     {
       "path": "src/codex/runtime.ts",
@@ -1118,7 +1130,7 @@
     },
     {
       "path": "src/codex/subagent-model-fallback.ts",
-      "sha256": "4ac30d47eec9211745e007edd3cef711dc0653b77cfc5941903f44f74119dbb1"
+      "sha256": "ab942407bcdd7d8d6b25e5be7c14e17a0d1d7262a48bb3f2364e75f014c6bedb"
     },
     {
       "path": "src/codex/sync.ts",
@@ -1196,6 +1208,18 @@
       "path": "src/config/paths.ts",
       "sha256": "61f45ac80e0b176b870dd660867f6f5799e61b55ae2fdfce5691bbb9e66e6049"
     },
+    {
+      "path": "src/config/pending-teardown-names.d.mts",
+      "sha256": "8e56b8414ad9b3eacd2ca9711c766edc1b6254b92839245b473fee55f6f122a9"
+    },
+    {
+      "path": "src/config/pending-teardown-names.mjs",
+      "sha256": "3fe7314b6dabda15bd2ecb673145ab56a19fc4dabd3d097a2899137a962566f1"
+    },
+    {
+      "path": "src/config/pending-teardown.ts",
+      "sha256": "6ac830654afcdb183c27b4af5b75af978e82ea325d07f39597786e655c3006a8"
+    },
     {
       "path": "src/config/process-state.ts",
       "sha256": "248fed86efbbb2f5c653ce3e08af7a3471ea28a3c04dff094c33916d8a3a9f01"
@@ -1298,7 +1322,7 @@
     },
     {
       "path": "src/integrations/journal.ts",
-      "sha256": "51a2a759aa383093bf6d73d2b48a3ca0fc86839641a5c350187eb214bc57c68c"
+      "sha256": "961d68c7b35e151e030cd2853223b0c1575fad77af444e768ff321f6e8a6b330"
     },
     {
       "path": "src/integrations/merge.ts",
@@ -1350,7 +1374,7 @@
     },
     {
       "path": "src/integrations/writer.ts",
-      "sha256": "e69674605c41714a634903e464769df4ceb3a1a220351f4b01048df909124265"
+      "sha256": "3945b3b4c408c613f76672c8cb213d84433ec4474966d9e9f00923f6a3707ed9"
     },
     {
       "path": "src/lab/artifacts/sanitize.ts",
@@ -1982,7 +2006,7 @@
     },
     {
       "path": "src/lib/process-control.ts",
-      "sha256": "1b48b8040679bcf0fd0128aaeee98bd354ae657663b207820b96bd8b573bfec1"
+      "sha256": "04d59915906bcd833d0e89a38dddc83f33f1632ca9b6014d93d030c3372914b8"
     },
     {
       "path": "src/lib/provider-outbound.ts",
@@ -2030,7 +2054,7 @@
     },
     {
       "path": "src/lib/state-store-registrations.ts",
-      "sha256": "3bfa6dd9ce8e2211ad65db0957d0767fddce95567ac531a2b5c0d9659fe7b26f"
+      "sha256": "f108d262fb54d753458631b9bb16c22474ea398181331b9a2cb87d9b487864c7"
     },
     {
       "path": "src/lib/state-store-sweeper.ts",
@@ -2182,7 +2206,7 @@
     },
     {
       "path": "src/oauth/index.ts",
-      "sha256": "de8c1c5dea51568d81b029b2fc0798df9a49b2c5b1d4d7762ba41b47aba53d72"
+      "sha256": "0ac7f18a0ef2d45ae400a1f408e39ecf64b30c02ce4afca1abc7e21b34a6a913"
     },
     {
       "path": "src/oauth/key-providers.ts",
@@ -2226,7 +2250,7 @@
     },
     {
       "path": "src/oauth/store.ts",
-      "sha256": "dac8d397d9d6be2419faee6c018f5358accab8836ab9ce344b62c8c12e7b3900"
+      "sha256": "209b0e02f69cd60b09d832a770382c5a88f3b94bb8663d9c1c22b87e05596b2e"
     },
     {
       "path": "src/oauth/token-guardian.ts",
@@ -2486,11 +2510,11 @@
     },
     {
       "path": "src/responses/spill-store.ts",
-      "sha256": "c68cde506896938c7e39b35ddd6b0192837880d77d83647dd00c7d9bd436311f"
+      "sha256": "a28d0896063ff0828a4de660ff43a942278425fac765db6f057f162666f5e758"
     },
     {
       "path": "src/responses/state.ts",
-      "sha256": "e96d4d3cdfa96981b0d8becb09b652eae369264f572d152aa80100a0e6d28cf8"
+      "sha256": "9982437898211d879156666d375cc0c1fcc90b04297332ff74b320ca389d1c14"
     },
     {
       "path": "src/responses/thought-signature-replay.ts",
@@ -2690,7 +2714,7 @@
     },
     {
       "path": "src/server/management-api.ts",
-      "sha256": "414af95a8be79d00c6f0aeb1c0a75d70a25161ff5176e1cefbc79160b016aec0"
+      "sha256": "b448917c5d5fe7dcb6d9988e8bf98ba4b377f960d74269c767cbb626045101f4"
     },
     {
       "path": "src/server/management-auth.ts",
@@ -2730,7 +2754,7 @@
     },
     {
       "path": "src/server/management/integration-routes.ts",
-      "sha256": "95afa1158362e7423d095cbe290687b169be8263ef48039cb5402243e38886f8"
+      "sha256": "3f27c3eda18b24766f9215f962f5ffa5f146d5c34043fbbc4688ea5ee9aa3374"
     },
     {
       "path": "src/server/management/lab-automation-routes.ts",
@@ -2946,7 +2970,7 @@
     },
     {
       "path": "src/server/responses/encrypted-payload.ts",
-      "sha256": "0e48bc0b453fc6b037d334d06a6454af46d8214f29b286a197d0bfdee138e215"
+      "sha256": "e9a5edf2ed2c9bda8e5244e50687b3ef9526841a0846fa325ce9cce6209188a7"
     },
     {
       "path": "src/server/responses/fetch-helpers.ts",
@@ -3004,6 +3028,10 @@
       "path": "src/server/startup-health-cache.ts",
       "sha256": "c4e1972bc3029389ce3f6a40477ca242b250b36c6dd5382b61124ad4f64aa920"
     },
+    {
+      "path": "src/server/stop-teardown.ts",
+      "sha256": "8e0dcffcc7e2acc0f8751830a623fd1a4f9b81e7e09eaa6e67abd1ef319f01ce"
+    },
     {
       "path": "src/server/system-env.ts",
       "sha256": "e83b17223b42325c562be8925bfe573d4c342c68b0c9195b39657cfb64d3f0ea"
@@ -3026,7 +3054,7 @@
     },
     {
       "path": "src/service.ts",
-      "sha256": "c8db18110d1c0e8ce06e7f4d568352508553ae4d5b2d9604d4f0054e0774457a"
+      "sha256": "182b27c731968f27140c0b2a509bb00036ef9433841ff7eef36541df5810b7d7"
     },
     {
       "path": "src/sidecar/auth.ts",
@@ -3150,7 +3178,7 @@
     },
     {
       "path": "src/update/index.ts",
-      "sha256": "f7ffb1f406760a2490b7f9f6c4373357bb455d6348d5b105a4462ffde0b7d44d"
+      "sha256": "fd3aed5d8eb3c02b1391f736b5971e20405475c931134860eddd733ca5e0e0be"
     },
     {
       "path": "src/update/job.ts",
@@ -3176,6 +3204,30 @@
       "path": "src/update/npm-invocation.mjs",
       "sha256": "25292222b9fa1ed00fc01164e9e9f25e82ca1820c73c20643171380467b4628b"
     },
+    {
+      "path": "src/update/proxy-liveness-probe.d.mts",
+      "sha256": "14b2051f2e14542720190a02ee950f1cbd79eefd044380a735c8e6a53edc5864"
+    },
+    {
+      "path": "src/update/proxy-liveness-probe.mjs",
+      "sha256": "5edce8e566742a174f4262a124b62d8b69120117ff622398f09105fde2361349"
+    },
+    {
+      "path": "src/update/stop-contract.d.mts",
+      "sha256": "e284b5830ee058aed46f09eee2cdcab7ddca54cdc4564df07102fd080551461d"
+    },
+    {
+      "path": "src/update/stop-contract.mjs",
+      "sha256": "006056e10a136927c5bc5e2afc047064e7f7516827ce3646a6e7717ffd9d548f"
+    },
+    {
+      "path": "src/update/stop-decision.d.mts",
+      "sha256": "23cbb6e3ecd1051b0258f7fe4cea8ce54fc6e39c997bd73e3fe17df538f332e9"
+    },
+    {
+      "path": "src/update/stop-decision.mjs",
+      "sha256": "3e9a210b820171d03f862a094077da6623c047e113b116d72d73b830cd0adf2c"
+    },
     {
       "path": "src/update/transactional-install.d.mts",
       "sha256": "8409a8514e798b45a2e3132bdf0f3fa64590e44827cb09367ae7d33dd85c57d7"
@@ -3238,11 +3290,11 @@
     },
     {
       "path": "src/vision/eligibility.ts",
-      "sha256": "0cf9d282723759f9b85e2ee563e7492878d8fd0c5de0e50688d404ef6632f288"
+      "sha256": "232243b48dd985eb57f6cd3ec2bfa39f943965d878828b5164b594614247df5e"
     },
     {
       "path": "src/vision/index.ts",
-      "sha256": "8b46ba96b3c1cc5d4a57eb3b3edcc9d3f6c791fc6a5e5e26d4adc89afbcae116"
+      "sha256": "bc519374596668b8e28ddb4e12ff625d30a62f5f13d5c4679580831d2cc6d343"
     },
     {
       "path": "src/vision/reasoning.ts",

package/src/integrations/journal.ts

@@ -19,7 +19,18 @@ import { atomicWriteFile } from "../config";
 import { ensureDir, fingerprint, integrationsDir, type OwnershipRecord } from "./ownership";
 import { isIntegrationClientId, type IntegrationClientId } from "./registry";
 
-export type OperationKind = "apply" | "disable" | "refresh" | "restore";
+/**
+ * `overwrite` is deliberately distinct from `apply`. Both write our block, but
+ * only one of them replaced something the user or another tool had put there,
+ * and the rollback list is exactly where that distinction matters.
+ *
+ * This union is re-declared, not imported, in two other places -- the management
+ * route envelope and the GUI adapter -- because neither imports across that
+ * boundary. `tests/integrations-journal.test.ts` asserts the three agree, since
+ * nothing else can: a kind persisted here and missing there renders as a raw
+ * key with no type error anywhere.
+ */
+export type OperationKind = "apply" | "disable" | "refresh" | "restore" | "overwrite";
 
 /**
  * Tagged so "the file did not exist" and "the snapshot was collected" stay