@bitkyc08/opencodex 2.15.1 → 2.17.0

package/src/integrations/writer-lock.ts

@@ -0,0 +1,98 @@
+import { rm, writeFile } from "node:fs/promises";
+
+const LOCK_DEADLINE_MS = 2_000;
+const LOCK_DELAYS_MS = [20, 40, 80, 160, 200] as const;
+
+export interface IntegrationWriterLockSeams {
+  writeFile: (
+    path: string,
+    payload: string,
+    options: { flag: "wx"; mode: 0o600 },
+  ) => Promise<void>;
+  removeFile: (path: string) => Promise<void>;
+  now: () => number;
+  delay: (milliseconds: number) => Promise<void>;
+  pid: number;
+}
+
+export class IntegrationWriterLockBusyError extends Error {
+  constructor(readonly lockPath: string) {
+    super("integration_mutation_busy");
+    this.name = "IntegrationWriterLockBusyError";
+  }
+}
+
+export class IntegrationWriterLockIOError extends Error {
+  constructor(readonly lockPath: string, readonly operation: "acquire" | "release", cause: unknown) {
+    // The management route returns Error.message to its caller. Keep the
+    // private config path and OS diagnostic on typed fields/cause, not the wire.
+    super(`integration writer lock ${operation} failed`, { cause });
+    this.name = "IntegrationWriterLockIOError";
+  }
+}
+
+const defaultSeams: IntegrationWriterLockSeams = {
+  writeFile: async (path, payload, options) => { await writeFile(path, payload, options); },
+  // Match DSH rc.6: an already-absent lock is a successful release.
+  removeFile: async path => { await rm(path, { force: true }); },
+  now: () => Date.now(),
+  delay: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+  pid: process.pid,
+};
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+/**
+ * Hold the exact sibling `<settings>.lock` around one complete transaction.
+ * A contender is never deleted: release runs only after our exclusive create
+ * succeeded.
+ */
+export async function withIntegrationWriterLock<T>(
+  configPath: string,
+  operation: () => Promise<T>,
+  seams: IntegrationWriterLockSeams = defaultSeams,
+  suffix: ".lock" = ".lock",
+): Promise<T> {
+  const lockPath = `${configPath}${suffix}`;
+  const startedAt = seams.now();
+  let delayIndex = 0;
+  for (;;) {
+    try {
+      await seams.writeFile(lockPath, `${seams.pid}\n`, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") {
+        throw new IntegrationWriterLockIOError(lockPath, "acquire", error);
+      }
+      const elapsedMs = seams.now() - startedAt;
+      if (elapsedMs >= LOCK_DEADLINE_MS) {
+        throw new IntegrationWriterLockBusyError(lockPath);
+      }
+      const backoffMs = LOCK_DELAYS_MS[Math.min(delayIndex, LOCK_DELAYS_MS.length - 1)]!;
+      // Keep the final retry inside the advertised two-second deadline.
+      const delayMs = Math.min(backoffMs, LOCK_DEADLINE_MS - elapsedMs);
+      delayIndex += 1;
+      await seams.delay(delayMs);
+    }
+  }
+
+  let outcome: { ok: true; value: T } | { ok: false; error: unknown };
+  try {
+    outcome = { ok: true, value: await operation() };
+  } catch (error) {
+    outcome = { ok: false, error };
+  }
+  try {
+    await seams.removeFile(lockPath);
+  } catch (error) {
+    // Cleanup cannot replace the protected operation's actual failure.
+    if (!outcome.ok) throw outcome.error;
+    throw new IntegrationWriterLockIOError(lockPath, "release", error);
+  }
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}

package/src/integrations/writer.ts

@@ -9,6 +9,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
  */
+import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { isLoopbackHostname } from "../codex/inject";
@@ -23,7 +24,8 @@ import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
-import { patchOmpYamlSource } from "./omp-yaml-source";
+import { patchYamlFragmentSource, sourcePrunableYamlContainers } from "./omp-yaml-source";
+import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
 export type RefusalReason =
   | "not_installed"
@@ -66,6 +68,8 @@ export interface IntegrationWriteInput {
   home?: string;
   store?: IntegrationStateStore;
   io?: IntegrationIO;
+  /** Frozen once by the async coordinator; synchronous callers may omit it. */
+  resolvedPaths?: { configPath: string; detectDir: string };
 }
 
 export interface IntegrationRestoreInput extends IntegrationWriteInput {
@@ -169,11 +173,13 @@ function snapshotAbsPath(store: IntegrationStateStore, entry: JournalEntry): str
   return snapshot.kind === "stored" ? snapshot.path : undefined;
 }
 
-function ompFragmentValue(contribution: ManagedContribution): unknown | undefined {
+function sourcePreservingFragmentValue(
+  contribution: ManagedContribution,
+  path: readonly string[],
+): unknown | undefined {
   const fragment = contribution.fragments.find(item => (
-    item.path.length === 2
-    && item.path[0] === "providers"
-    && item.path[1] === "opencodex"
+    item.path.length === path.length
+    && item.path.every((key, index) => key === path[index])
   ));
   return fragment?.value;
 }
@@ -194,7 +200,7 @@ function preflight(input: IntegrationWriteInput) {
    */
   let configPath: string;
   try {
-    configPath = spec.configPath(input.env, input.home);
+    configPath = input.resolvedPaths?.configPath ?? spec.configPath(input.env, input.home);
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
@@ -213,7 +219,8 @@ function preflight(input: IntegrationWriteInput) {
   const before = target.before;
   const parsed = parseConfig(before, exportSpec.format);
   if (parsed === PARSE_FAILED) {
-    return { failed: refuse(clientId, "unsafe", "unsafe", `${configPath} could not be parsed`) } as const;
+    return { failed: refuse(clientId, "unsafe", "unsafe",
+      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
   }
   const contribution = exportSpec.buildContribution(exportContextOf(input));
   // A record proves ownership of the file it was written FOR. Matching only by
@@ -238,7 +245,7 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   if (pre.failed) return pre.failed;
   const { store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } = pre;
 
-  if (io.statKind(spec.detectDir(input.env, input.home)) !== "dir") {
+  if (io.statKind(input.resolvedPaths?.detectDir ?? spec.detectDir(input.env, input.home)) !== "dir") {
     return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
   }
   if (isLoopbackOnly(clientId) && !isLoopbackHostname(input.config.hostname)) {
@@ -293,11 +300,16 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   const nextDocument = mergeContribution(base, contribution);
   let text: string;
   try {
-    if (clientId === "omp" && before !== null) {
-      const value = ompFragmentValue(contribution);
+    if (spec.sourcePreservingYaml && before !== null) {
+      const value = sourcePreservingFragmentValue(contribution, spec.sourcePreservingYaml.path);
       const patched = value === undefined
         ? null
-        : patchOmpYamlSource(before, { kind: "upsert", value }, nextDocument);
+        : patchYamlFragmentSource(
+            before,
+            spec.sourcePreservingYaml.path,
+            { kind: "upsert", value },
+            nextDocument,
+          );
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
           `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so it was left alone`);
@@ -343,7 +355,7 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
 export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, exportSpec, configPath, before, parsed, record, classified } = pre;
+  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, record, classified } = pre;
 
   if (classified.state === "absent") {
     return { ok: true, changed: false, state: "absent", clientId, message: "not applied" };
@@ -368,22 +380,40 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
         : `${configPath} cannot be changed safely`);
   }
 
-  // current | stale only: the file fingerprint still matches our record, so the
-  // recorded paths are exactly what we put there.
+  /*
+   * current | stale only. What makes the removal safe is the BLOCK
+   * fingerprint, not the file fingerprint: the classifier verified the values
+   * at the recorded paths are byte-for-byte what we wrote, so removing them
+   * cannot take a user edit with them. The file itself may have drifted — a
+   * json client classifies a sibling edit as stale (#1631) — which is why the
+   * removal runs against the document as parsed NOW, and the re-serialize is
+   * value-safe because non-round-tripping numbers were refused at parse time.
+   * Source-preserving YAML clients additionally compute which recorded
+   * containers are still source-empty before pruning, so a later sibling or
+   * comment makes its ancestor user-owned without protecting our leaf.
+   */
+  const recordedCreated = record!.createdContainers ?? [];
+  const prunableCreated = spec.sourcePreservingYaml && before !== null
+    ? sourcePrunableYamlContainers(before, spec.sourcePreservingYaml.path, recordedCreated)
+    : recordedCreated;
+  if (prunableCreated === null) {
+    return refuse(clientId, "unsafe", "unsafe",
+      `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+  }
   const { doc, removed } = removeFragments(
     parsed,
     record!.fragmentPaths,
-    new Set(record!.createdContainers ?? []),
+    new Set(prunableCreated),
   );
   if (!removed) {
     return { ok: true, changed: false, state: "absent", clientId, message: "nothing to remove" };
   }
   let text: string;
   try {
-    if (clientId === "omp" && before !== null) {
-      const patched = patchOmpYamlSource(before, {
+    if (spec.sourcePreservingYaml && before !== null) {
+      const patched = patchYamlFragmentSource(before, spec.sourcePreservingYaml.path, {
         kind: "remove",
-        removeEmptyProviders: record!.createdContainers?.includes("providers") === true,
+        createdContainers: prunableCreated,
       }, doc);
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
@@ -427,7 +457,8 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
 
   const clientId = entry.clientId;
-  const resolvedPath = INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
+  const resolvedPath = input.resolvedPaths?.configPath
+    ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
   // Restore acts on the path the operation was journaled against. Resolving a
   // different path here would let an operation recorded for one home delete a
   // file in another.
@@ -525,3 +556,105 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     snapshotPath: snapshotAbsPath(store, restoreEntry),
   });
 }
+
+export interface CoordinatedIntegrationOptions {
+  lockSeams?: IntegrationWriterLockSeams;
+}
+
+/** Freeze all mutable resolution seams before the first lock await. */
+type FrozenIntegrationInput = IntegrationWriteInput & {
+  store: IntegrationStateStore;
+  io: IntegrationIO;
+  env: NodeJS.ProcessEnv;
+  home: string;
+  resolvedPaths: { configPath: string; detectDir: string };
+};
+
+function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
+  const env = { ...(input.env ?? process.env) };
+  const home = input.home ?? homedir();
+  const store = input.store ?? createIntegrationStateStore();
+  const io = input.io ?? defaultIntegrationIO(store);
+  const spec = INTEGRATION_CLIENTS[input.clientId];
+  const resolvedPaths = {
+    configPath: spec.configPath(env, home),
+    detectDir: spec.detectDir(env, home),
+  };
+  return { ...input, env, home, store, io, resolvedPaths };
+}
+
+function tryFreezeIntegrationInput(input: IntegrationWriteInput):
+  | { ok: true; value: FrozenIntegrationInput }
+  | { ok: false; refusal: WriteRefused } {
+  try {
+    return { ok: true, value: freezeIntegrationInput(input) };
+  } catch (error) {
+    if (!(error instanceof ClientPathError)) throw error;
+    return {
+      ok: false,
+      refusal: refuse(input.clientId, "unsafe", "unsafe", error.message),
+    };
+  }
+}
+
+async function coordinatedWrite(
+  input: IntegrationWriteInput,
+  operation: (frozen: IntegrationWriteInput) => WriteOutcome,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  const prepared = tryFreezeIntegrationInput(input);
+  if (!prepared.ok) return prepared.refusal;
+  const frozen = prepared.value;
+  const spec = INTEGRATION_CLIENTS[frozen.clientId];
+  if (!spec.writerLock) return operation(frozen);
+
+  // An absent client home is not created merely to acquire a sibling lock.
+  if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
+    return operation(frozen);
+  }
+  return withIntegrationWriterLock(
+    frozen.resolvedPaths.configPath,
+    async () => operation(frozen),
+    options?.lockSeams,
+    spec.writerLock.suffix,
+  );
+}
+
+export function applyIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, applyIntegration, options);
+}
+
+export function disableIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, disableIntegration, options);
+}
+
+export async function restoreIntegrationCoordinated(
+  input: IntegrationRestoreInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  const prepared = tryFreezeIntegrationInput(input);
+  if (!prepared.ok) return prepared.refusal;
+  const frozen = prepared.value;
+  const spec = INTEGRATION_CLIENTS[frozen.clientId];
+  if (!spec.writerLock) return restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
+    return refuse(
+      frozen.clientId,
+      "unsafe",
+      "unsafe",
+      `${frozen.resolvedPaths.detectDir} is missing; restore will not create the client home`,
+    );
+  }
+  return withIntegrationWriterLock(
+    frozen.resolvedPaths.configPath,
+    async () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift }),
+    options?.lockSeams,
+    spec.writerLock.suffix,
+  );
+}

package/src/lab/automation/orchestrator.ts

@@ -1,5 +1,6 @@
 import { readConfigDiagnostics } from "../../config";
 import { registerCurrentServerResourceCleanup } from "../../lib/server-resource-ownership";
+import { registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
 import { queryLabStatus } from "../query";
 import { rebuildLabProjection } from "../projection/rebuild";
 import { planLabAutomationRuns } from "./planner";
@@ -90,10 +91,12 @@ export function setLabAutomationDispatchDeps(deps: AutomationDispatchDeps): () =
 
   let released = false;
   let detachServerCleanup = () => {};
+  let detachShutdownHook = () => {};
   const release = () => {
     if (released) return;
     released = true;
     detachServerCleanup();
+    detachShutdownHook();
     const current = dispatchDepsByConfigDir.get(key);
     if (current?.token !== token) return;
     dispatchDepsByConfigDir.delete(key);
@@ -104,6 +107,13 @@ export function setLabAutomationDispatchDeps(deps: AutomationDispatchDeps): () =
     }
   };
   detachServerCleanup = registerCurrentServerResourceCleanup(release);
+  // Shutdown teardown is registered here, at activation, so `server/lifecycle.ts` never has
+  // to import Lab in order to stop it. Scoped to this configDir, unlike the previous
+  // unscoped call from the shutdown path.
+  detachShutdownHook = registerOptionalShutdownHook(`lab-automation:${key}`, () => {
+    requestLabAutomationShutdown();
+    stopLabAutomationScheduler(deps.configDir);
+  });
   return release;
 }
 
@@ -399,6 +409,15 @@ export function startLabAutomationScheduler(configDir?: string): void {
     if (currentOwner) existing.ownerToken = currentOwner;
     return;
   }
+  // The scheduler owns a live interval, so its teardown must be registered here rather
+  // than only in setLabAutomationDispatchDeps: the management API and the CLI can start a
+  // scheduler without ever installing dispatch deps (lab-automation-routes.ts
+  // applySchedulerPolicy, cli/lab.ts), and core no longer imports this module to stop it.
+  // Without this registration such a scheduler survives drainAndShutdown.
+  registerOptionalShutdownHook(`lab-automation-scheduler:${key}`, () => {
+    requestLabAutomationShutdown();
+    stopLabAutomationScheduler(configDir);
+  });
   shutdownRequested = false;
   const { policy, routes } = loadLabAutomationConfig(configDir);
   const now = Date.now();

package/src/lib/lab-activation.ts

@@ -0,0 +1,161 @@
+/**
+ * Compatibility Lab activation.
+ *
+ * The proxy core does not import Lab. This module is the seam that does, and the startup
+ * composition root calls it only when the install actually uses Lab, so a user with no
+ * routing profile and no automation executes no Lab code and starts no Lab timer.
+ *
+ * Activation is SYNCHRONOUS by design. Three audit rounds established that a deferred
+ * activation window is unpatchable: `routeModelInternal` is sync, and so is the
+ * subagent-fallback chain that calls `routeModel`, so those callers have nowhere to await.
+ * During such a window a policy alias would be silently dropped from a fallback chain and
+ * the subagent would run on a different model than the operator configured. Registration
+ * therefore completes before `startServer` returns, inside the same synchronous turn as
+ * `Bun.serve`, so no request can observe an unregistered slot.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/080_activation_is_synchronous.md
+ *
+ * Startup degrades, explicit operator action reports. This asymmetry is deliberate: an
+ * invalid automation config disables automation with a warning here, but the management
+ * API and CLI paths that start a scheduler leave `LabAutomationError` to surface (the
+ * management route maps it to a 400). Someone who just toggled automation should see the
+ * validation error; someone merely starting the proxy should not lose unrelated traffic.
+ *
+ * @internal host integration only
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { labAutomationPolicyPath } from "../lab/paths";
+import type { OcxConfig } from "../types";
+import { LabAutomationError } from "../lab/automation/types";
+import { registerLabPassiveRouteLinker } from "./lab-passive-linker-registration";
+import { setCompatibilityEvidenceProvider } from "../routing/compatibility/provider-slot";
+import { labCompatibilityEvidenceProvider } from "../routing/compatibility/lab-evidence-provider";
+import {
+  setLabAutomationDispatchDeps,
+  startLabAutomationScheduler,
+} from "../lab/automation/orchestrator";
+import { createProductionLabRouteExecutor } from "./lab-live-route-production";
+
+/** Activation records keyed by configDir, so one process can own several configs. */
+const activated = new Map<string, Array<() => void>>();
+
+const activationKey = (configDir?: string): string => configDir ?? "";
+
+function readJsonIfPresent(path: string): unknown {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    // A malformed or unreadable file means "not enabled": this detector must never throw
+    // during startup, and must never import Lab persistence to answer the question.
+    return null;
+  }
+}
+
+/**
+ * True when Lab automation is enabled on disk.
+ *
+ * Mirrors `loadLabAutomationConfig` precedence deliberately: the current authority is the
+ * combined `automation-config.json`, with `automation-policy.json` as the legacy fallback.
+ * Reading only the legacy file would miss every install that enabled automation through
+ * the current dashboard.
+ */
+export function labAutomationEnabledOnDisk(configDir?: string): boolean {
+  const legacyPath = labAutomationPolicyPath(configDir);
+  const combined = readJsonIfPresent(join(dirname(legacyPath), "automation-config.json"));
+  if (combined && typeof combined === "object") {
+    const policy = (combined as { policy?: unknown }).policy;
+    if (policy && typeof policy === "object") {
+      return (policy as { enabled?: unknown }).enabled === true;
+    }
+  }
+  const legacy = readJsonIfPresent(legacyPath);
+  if (legacy && typeof legacy === "object") {
+    return (legacy as { enabled?: unknown }).enabled === true;
+  }
+  return false;
+}
+
+/** True when this install actually uses Lab: any routing profile, or automation enabled. */
+export function labActivationRequired(config: OcxConfig, configDir?: string): boolean {
+  if (Object.keys(config.routingProfiles ?? {}).length > 0) return true;
+  return labAutomationEnabledOnDisk(configDir);
+}
+
+/**
+ * Register Lab into the core slots. Idempotent per configDir and safe to call again after
+ * a routing profile is created at runtime.
+ */
+export function activateLab(config: OcxConfig, configDir?: string): void {
+  const key = activationKey(configDir);
+  // INVARIANT: activation is all-or-nothing and reason-independent. Every slot is
+  // registered here regardless of WHY activation was required, which is what makes this
+  // key safe as configDir alone -- an automation-only activation still installs the
+  // compatibility provider a later profile needs. If any registration ever becomes
+  // conditional on the activation reason, this key must include that reason, or the early
+  // return will silently skip it forever.
+  if (activated.has(key)) return;
+
+  const detach: Array<() => void> = [];
+  detach.push(registerLabPassiveRouteLinker(configDir));
+  detach.push(setCompatibilityEvidenceProvider(labCompatibilityEvidenceProvider));
+
+  const routeExecutor = createProductionLabRouteExecutor({ configDir, loadConfig: () => config });
+  detach.push(setLabAutomationDispatchDeps({ configDir, loadConfig: () => config, routeExecutor }));
+
+  // Record the activation BEFORE the scheduler start. startLabAutomationScheduler runs the
+  // full automation normalizer, which throws on any field violation, and this call sits on
+  // the startup path of every install that has a routing profile. Storing the record first
+  // means a throw cannot orphan the detach receipts and leave slots registered with no
+  // activation record -- which would let a later activateLab register them a second time.
+  activated.set(key, detach);
+
+  if (labAutomationEnabledOnDisk(configDir)) {
+    try {
+      startLabAutomationScheduler(configDir);
+    } catch (err) {
+      // Neither a malformed automation file nor a busy state lock may take the proxy down
+      // at startup. Lab automation stays off for this run; routing, evidence, and every
+      // other subsystem keep working.
+      //
+      // The two causes get different messages because they need different actions, and a
+      // lock-contention failure reported as "invalid config" sends the operator to fix a
+      // file that is fine. Contention can also stall startup by up to the 5s lock wait.
+      const code = err instanceof LabAutomationError ? err.code : null;
+      if (code === "state_lock_busy" || code === "state_lock_failed") {
+        console.warn(
+          "[lab] Lab automation did not start: another process holds the automation state lock."
+          + " Automation stays off for this run and will be retried on the next start.",
+        );
+      } else {
+        console.warn(
+          "[lab] Lab automation is disabled for this run because its configuration could not be"
+          + " loaded:",
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+  }
+}
+
+/** True when this configDir has been activated. */
+export function isLabActivated(configDir?: string): boolean {
+  return activated.has(activationKey(configDir));
+}
+
+/**
+ * Test-only teardown. Deactivation is deliberately NOT a production path: tearing an
+ * activation down mid-run would finalize in-flight automation as ineligible rather than
+ * cancelled, and the orchestrator's shutdown signal is process-global. An install that
+ * creates then deletes a profile keeps Lab resident until restart, which does not affect
+ * users who never opted in.
+ */
+export function resetLabActivationForTests(): void {
+  for (const [key, detach] of [...activated]) {
+    activated.delete(key);
+    for (const release of [...detach].reverse()) {
+      try { release(); } catch { /* teardown is best-effort */ }
+    }
+  }
+}

package/src/lib/lab-passive-linker-registration.ts

@@ -0,0 +1,26 @@
+/**
+ * Registers Compatibility Lab's passive route-subject linker into the core slot.
+ *
+ * Imported only from the Lab activation path, never from the request path. This module
+ * lives outside `src/lab/` for the same reason the other `src/lib/lab-*.ts` host
+ * integrations do: it is the seam between core and the subsystem, not the subsystem.
+ *
+ * @internal host integration only
+ */
+import { setPassiveRouteLinker } from "../server/passive-route-linker";
+import { resolveProductionRouteSubject } from "../routing/compatibility/subject";
+
+/** Install the Lab linker. Returns a detach function. */
+export function registerLabPassiveRouteLinker(configDir?: string): () => void {
+  return setPassiveRouteLinker((config, providerName, modelId, routed, inboundWire) => {
+    const subject = resolveProductionRouteSubject(
+      config,
+      providerName,
+      modelId,
+      routed,
+      inboundWire,
+      configDir,
+    );
+    return subject ? subject.subjectId : null;
+  });
+}

package/src/lib/optional-shutdown-hooks.ts

@@ -0,0 +1,57 @@
+/**
+ * Core-owned registry for optional-subsystem shutdown work.
+ *
+ * The proxy core must not import an optional subsystem merely to be able to stop it.
+ * Compatibility Lab is the first case: `server/lifecycle.ts` imported
+ * `lab/automation/orchestrator` for two teardown calls, and that single edge closed an
+ * import cycle (`routing/compatibility/assemble` → `routing/quota` → `providers/quota` →
+ * `codex/auth-api` → `codex/native-main-admission` → `server/lifecycle` → Lab) that pulled
+ * ~69 `src/lab/` modules into the graph of every install, including installs with no
+ * routing profile at all.
+ *
+ * A subsystem registers its teardown when it activates. A process that never activates it
+ * registers nothing, so shutdown does no work and loads no module.
+ *
+ * Hooks are synchronous and best-effort by contract: `drainAndShutdown` runs under an
+ * absolute deadline, so a hook that throws must not prevent its siblings — or
+ * `server.stop` — from running.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/010_lifecycle_shutdown_registry.md
+ */
+
+type ShutdownHook = () => void;
+
+const hooks = new Map<string, ShutdownHook>();
+
+/**
+ * Register (or replace) the teardown for one optional subsystem.
+ *
+ * Keyed so repeated activation of the same subsystem cannot accumulate duplicate hooks.
+ * Returns a detach function so an owner-scoped lease can release its registration.
+ */
+export function registerOptionalShutdownHook(key: string, hook: ShutdownHook): () => void {
+  hooks.set(key, hook);
+  return () => {
+    // Only detach our own registration: a later activation may have replaced it.
+    if (hooks.get(key) === hook) hooks.delete(key);
+  };
+}
+
+/** Run every registered teardown. Never throws. */
+export function runOptionalShutdownHooks(): void {
+  for (const [key, hook] of [...hooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(
+        `[shutdown] optional subsystem "${key}" teardown failed:`,
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+}
+
+/** Test-only reset so an isolated lifecycle test does not inherit registrations. */
+export function resetOptionalShutdownHooksForTests(): void {
+  hooks.clear();
+}