feat(server): install provider CLI updates in the background#17585

@@ -1,12 +1,33 @@
 import * as KeyedLock from "@t3tools/shared/KeyedLock";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+
+/** Shares background install admission with provider startup, before either touches a CLI. */
+export class ProviderMaintenanceAdmission extends Context.Service<
+  ProviderMaintenanceAdmission,
+  {
+    readonly withPermit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  }
+>()("t3/provider/providerMaintenanceCommandCoordinator/ProviderMaintenanceAdmission") {}
+
+// Keep one layer reference so the update window and turn startup share its permit.
+export const admissionLayer = Layer.effect(
+  ProviderMaintenanceAdmission,
+  Effect.map(Semaphore.make(1), (permit) =>
+    ProviderMaintenanceAdmission.of({ withPermit: permit.withPermits(1) }),
+  ),
+);

@@ -0,0 +1,232 @@
+import type { ScheduledTaskId, ThreadId } from "@t3tools/contracts";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Semaphore from "effect/Semaphore";
+
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
+import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
+import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
+import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
+import * as ServerSettings from "../serverSettings.ts";
+
+/** Work due this soon keeps the window closed, so it does not start late. */
+const UPDATE_LOOKAHEAD = Duration.minutes(5);
+/**
+ * Tasks repeating at least this often always have a run due soon. Missed runs
+ * catch up after a restart, so they only block while running.
+ */
+const FREQUENT_TASK_INTERVAL = Duration.minutes(15);
+
+/**
+ * Background update pacing. `T3CODE_UPDATE_LAB=1` (scripts/update-lab.ts)
+ * shortens the waits so update flows can be exercised in seconds.
+ */
+export const updateTimings = Config.Boolean("T3CODE_UPDATE_LAB").pipe(
+  Config.withDefault(false),
+  Config.map((lab) => ({
+    /**
+     * How long every client must be untouched before an update may interrupt
+     * it. Clients report activity about every 25s, so this must stay well above that.
+     */
+    quietPeriod: lab ? Duration.seconds(60) : Duration.minutes(15),
+    /** How often a waiting update rechecks the window or looks for new versions. */
+    recheck: lab ? Duration.seconds(5) : Duration.seconds(30),
+    firstPassDelay: lab ? Duration.seconds(10) : Duration.minutes(2),
+    passInterval: lab ? Duration.seconds(20) : Duration.minutes(10),
+  })),
+);
+
+export type UpdateWindowBlocker =
+  | { readonly type: "active-threads"; readonly threadIds: ReadonlyArray<ThreadId> }
+  | { readonly type: "recent-interaction"; readonly quietAt: DateTime.Utc }
+  | { readonly type: "focused-window" }
+  | { readonly type: "provider-update" }
+  | {
+      readonly type: "scheduled-task";
+      readonly taskId: ScheduledTaskId;
+      readonly title: string;
+      /** Null while the task is running. */
+      readonly runsAt: DateTime.Utc | null;
+    }
+  | {
+      readonly type: "usage-limit-resume";
+      readonly threadId: ThreadId;
+      readonly resumesAt: DateTime.Utc;
+    };
+
+export interface UpdateWindowOptions {
+  /** The update closes the app windows (a desktop install), not just a reconnect. */
+  readonly closesWindows: boolean;
+}
+
+export interface UpdateWindowStatus {
+  readonly open: boolean;
+  readonly blockers: ReadonlyArray<UpdateWindowBlocker>;
+}
+
+/**
+ * Decides when a background update may restart the server, replace a provider
+ * CLI, or relaunch the desktop app without cutting off someone's work.
+ */
+export class UpdateWindow extends Context.Service<
+  UpdateWindow,
+  {
+    readonly check: (options: UpdateWindowOptions) => Effect.Effect<UpdateWindowStatus>;
+    /**
+     * Runs `install` if the window is open, holding a lock every background
+     * install shares, so a server restart never cuts off a CLI install.
+     */
+    readonly runIfOpen: <A, E, R>(
+      options: UpdateWindowOptions,
+      install: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<Option.Option<A>, E, R>;
+    /** Waits for the window, then runs `install` like `runIfOpen`. */
+    readonly runWhenOpen: <A, E, R>(
+      options: UpdateWindowOptions,
+      install: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E, R>;
+  }
+>()("t3/updates/UpdateWindow") {}
+
+export const make = Effect.fn("updates.UpdateWindow.make")(function* () {
+  const projections = yield* ProjectionStore.ProjectionStoreV2;
+  const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
+  const scheduledTasks = yield* ScheduledTaskService.ScheduledTaskService;
+  const serverSettings = yield* ServerSettings.ServerSettingsService;
+  const providers = yield* ProviderRegistry.ProviderRegistry;
+  const timings = yield* updateTimings;
+
+  const check: UpdateWindow["Service"]["check"] = Effect.fn("updates.UpdateWindow.check")(
+    function* (options) {
+      const now = yield* DateTime.now;
+      const horizon = DateTime.addDuration(now, UPDATE_LOOKAHEAD);
+      const blockers: Array<UpdateWindowBlocker> = [];
+
+      // A failed read keeps the window closed: guessing "idle" could cut off a turn.
+      const activeThreadIds = yield* projections.getRecoveryThreadIds("active-work").pipe(
+        Effect.tapError((cause) =>
+          Effect.logWarning("Update window could not read threads", { cause }),
+        ),
+        Effect.option,
+      );
+      if (Option.isNone(activeThreadIds)) {
+        return { open: false, blockers: [{ type: "active-threads", threadIds: [] }] };
+      }
+      if (activeThreadIds.value.length > 0) {
+        blockers.push({ type: "active-threads", threadIds: activeThreadIds.value });
+      }
+
+      // Includes installs someone started by hand.
+      const providerUpdating = (yield* providers.getProviders).some(
+        (provider) =>
+          provider.updateState?.status === "queued" || provider.updateState?.status === "running",
+      );
+      if (providerUpdating) {
+        blockers.push({ type: "provider-update" });
+      }
+
+      const lastInteraction = yield* backgroundPolicy.lastClientInteractionAt;
+      if (Option.isSome(lastInteraction)) {
+        const quietAt = DateTime.addDuration(lastInteraction.value, timings.quietPeriod);
+        if (DateTime.isGreaterThan(quietAt, now)) {
+          blockers.push({ type: "recent-interaction", quietAt });
+        }
+      }
+
+      if (options.closesWindows) {
+        const policy = yield* backgroundPolicy.snapshot;
+        const hostIdleSeconds = policy.hostPower.stale ? null : policy.hostPower.idleSeconds;
+        const hostAway =
+          hostIdleSeconds !== null && hostIdleSeconds >= Duration.toSeconds(timings.quietPeriod);
+        const windowFocused = policy.leases.some(
+          (lease) => lease.clientKind === "desktop-renderer" && lease.focused,
+        );
+        if (windowFocused && !hostAway) {
+          blockers.push({ type: "focused-window" });
+        }
+      }
+
+      const tasks = yield* scheduledTasks.list().pipe(
+        Effect.tapError((cause) =>
+          Effect.logWarning("Update window could not read scheduled tasks", { cause }),
+        ),
+        Effect.option,
+      );
+      if (Option.isNone(tasks)) {
+        return { open: false, blockers };
+      }
+      for (const task of tasks.value.tasks) {
+        if (task.lastRunStatus === "running") {
+          blockers.push({
+            type: "scheduled-task",
+            taskId: task.id,
+            title: task.title,
+            runsAt: null,
+          });
+          continue;
+        }
+        if (!task.enabled || task.nextRunAt === null) continue;
+        if (
+          task.schedule.type === "interval" &&
+          task.schedule.everyMs < Duration.toMillis(FREQUENT_TASK_INTERVAL)
+        ) {
+          continue;
+        }
+        const runsAt = DateTime.make(task.nextRunAt);
+        if (Option.isSome(runsAt) && !DateTime.isGreaterThan(runsAt.value, horizon)) {
+          blockers.push({
+            type: "scheduled-task",
+            taskId: task.id,
+            title: task.title,
+            runsAt: runsAt.value,
+          });
+        }
+      }
+
+      const settings = yield* serverSettings.getSettings.pipe(Effect.option);
+      if (Option.isSome(settings) && settings.value.autoResumeLimitedThreads) {
+        const limited = yield* projections
+          .getLimitRecoveryCandidates({ now: horizon, autoResume: true, snooze: false })
+          .pipe(Effect.orElseSucceed(() => []));

@@ -0,0 +1,451 @@
+// @effect-diagnostics nodeBuiltinImport:off - Host leases coordinate independent Node servers.
+// oxlint-disable t3code/no-global-process-runtime -- Leases belong to the OS user and process, not an environment.
+import * as NodeCrypto from "node:crypto";
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { lock } from "proper-lockfile";
+import * as Context from "effect/Context";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Deferred from "effect/Deferred";
+import * as Semaphore from "effect/Semaphore";
+import * as Schema from "effect/Schema";
+import * as Maintenance from "@t3tools/provider-core/server/maintenance";
+
+const HeldWrite = Context.Reference<{ readonly owner: object; active: boolean } | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldWrite",
+  { defaultValue: () => null },
+);
+
+interface ReadToken {
+  readonly lease: { readonly owner: object; readonly file: string; users: number };
+  active: boolean;
+}
+const HeldRead = Context.Reference<ReadToken | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldRead",
+  { defaultValue: () => null },
+);
+
+const HeldGate = Context.Reference<{
+  readonly handoff: Effect.Effect<void>;
+  readonly resume: Effect.Effect<void>;
+} | null>("t3/provider/ProviderMaintenanceHostLock/HeldGate", { defaultValue: () => null });
+
+// Linux exposes a process start identity, so recycled PIDs cannot pin a dead reader.
+const processIdentity = (pid: number) => {
+  if (NodeOS.platform() !== "linux") return null;
+  const fields = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").at(-1)!.split(" ");
+  return fields[0] === "Z" ? "" : fields[19]!;
+};
+
+export const installLeasePath = (directory: string) => NodePath.join(directory, "install.json");
+
+/** Start identity includes the Linux boot so leases cannot survive a reboot's PID reuse. */
+export const readProcessIdentity = (pid: number): string | null => {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    const platform = NodeOS.platform();
+    if (platform === "linux") {
+      const start = processIdentity(pid);
+      return start
+        ? `${NodeFS.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${start}`
+        : null;
+    }
+    if (platform !== "darwin" && platform !== "win32") return null;
+    const scan =
+      platform === "win32"
+        ? NodeChildProcess.spawnSync(
+            "powershell.exe",
+            [
+              "-NoProfile",
+              "-NonInteractive",
+              "-Command",
+              `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}' -ErrorAction Stop).CreationDate.ToUniversalTime().ToString('o')`,
+            ],
+            { encoding: "utf8", timeout: 10_000, windowsHide: true },
+          )
+        : NodeChildProcess.spawnSync("ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8",
+            timeout: 10_000,
+            env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+          });
+    return scan.error || scan.status !== 0 ? null : scan.stdout.trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+export const isProcessAlive = (pid: number, identity?: string | null) => {
+  try {
+    process.kill(pid, 0);
+    if (processIdentity(pid) === "") return false;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ESRCH" || error.code === "ENOENT")
+    )
+      return false;
+    return true;
+  }
+  if (identity == null) return true;
+  const current = readProcessIdentity(pid);
+  return current === null || current === identity;
+};
+
+const decodeInstallLease = Schema.decodeSync(
+  Schema.fromJsonString(
+    Schema.Union([
+      Schema.Number,
+      Schema.Struct({
+        pid: Schema.Number,
+        identity: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ]),
+  ),
+);
+
+/** A dead supervisor's installer still owns admission until its entire process group exits. */
+export const installIsAlive = (directory: string): boolean => {
+  const file = installLeasePath(directory);
+  let pid: number;
+  let identity: string | null | undefined;
+  try {
+    const lease = decodeInstallLease(NodeFS.readFileSync(file, "utf8"));
+    pid = typeof lease === "number" ? lease : lease.pid;
+    identity = typeof lease === "number" ? undefined : lease.identity;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid provider install lease");
+  if (isProcessAlive(pid, identity)) return true;
+  return installChildrenAreAlive(pid);
+};
+
+/** The installer can leave children writing after its root exits. Failed scans keep admission closed. */
+export const installChildrenAreAlive = (pid: number): boolean => {
+  const windows = NodeOS.platform() === "win32";
+  const scan = windows
+    ? NodeChildProcess.spawnSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          'Get-CimInstance Win32_Process -ErrorAction Stop | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)" }',
+        ],
+        { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      )
+    : NodeChildProcess.spawnSync("ps", ["-ax", "-o", "pid=", "-o", "pgid=", "-o", "stat="], {
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+  if (scan.error || scan.status !== 0)
+    throw new Error("Could not inspect provider installer processes");
+  if (windows) {
+    const descendants = new Set([pid]);

@@ -408,27 +468,62 @@ export const resolvePackageManagedProviderMaintenance = Effect.fn(
   )
     ? manual
     : native;
+  const vitePlus = yield* resolveVitePlusPackageInstall(context, packageName);
+  if (vitePlus) {
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      env: context.env,
+      platform: context.platform,
+      installationKey: keyFor(vitePlus),
+      packageName,
+      updateExecutable: "vp",
+      updateArgs: ["i", "-g", packageName],
+      updateLockKey: "vite-plus-global",
+    });
+  }
+  // Vite+ package shims resolve to vp itself, not the installed package.
+  if (/\/vp(?:\.exe)?$/.test(normalizeCommandPath(context.realCommandPath))) return manual;
   if (commandPaths.some(isVitePlusGlobalCommandPath)) {
     return makeProviderMaintenanceCapabilities({
       provider: definition.provider,
+      env: context.env,
+      platform: context.platform,
+      installationKey: keyFor(rootAt("/.vite-plus/")),
       packageName,
       updateExecutable: "vp",
       updateArgs: ["i", "-g", packageName],
       updateLockKey: "vite-plus-global",
     });
   }
-  if (commandPaths.some(isBunGlobalCommandPath)) {
+  const bunBin = context.env.BUN_INSTALL?.trim().replace(/[\\/]+$/, "");
+  if (
+    commandPaths.some(isBunGlobalCommandPath) ||
+    (bunBin &&

@@ -86,123 +104,144 @@ interface VerifiedProviderRefresh {
 
 const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 
-const runProviderMaintenanceCommandWithSpawner = Effect.fn("ProviderMaintenanceRunner.runCommand")(
-  function* (input: {
-    readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
-    readonly command: string;
-    readonly args: ReadonlyArray<string>;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly onProgress?: (line: string) => Effect.Effect<void>;
-  }) {
-    const collectCommandResult = Effect.fn("ProviderMaintenanceRunner.collectCommandResult")(
-      function* () {
-        // Resolve the executable for the host platform before spawning. On
-        // Windows the update tools are batch shims (e.g. `npm` -> `npm.cmd`),
-        // which a bare ChildProcess.spawn cannot launch (spawn npm ENOENT);
-        // resolveSpawnCommand finds the real `.cmd` and routes it through the
-        // shell. On Linux/macOS (incl. the WSL backend) this is a no-op.
-        const resolved = yield* resolveSpawnCommand(input.command, input.args);
-        const child = yield* input.spawner
-          .spawn(
-            ChildProcess.make(resolved.command, resolved.args, {
-              shell: resolved.shell,
-              ...(input.env ? { env: input.env, extendEnv: true } : {}),
-            }),
-          )
-          .pipe(
-            Effect.mapError(
-              (cause) =>
-                new ProviderMaintenanceCommandError({
-                  message: `Failed to run update command ${input.command}: ${cause.message}`,
-                  cause,
-                }),
-            ),
-          );
-        yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
-
-        // Holds the newest output line not yet reported; the sampler takes it.
-        const pendingProgress = yield* Ref.make<string | null>(null);
-        const onProgress = input.onProgress;
-        if (onProgress) {
-          yield* Ref.getAndSet(pendingProgress, null).pipe(
-            Effect.flatMap((line) => (line === null ? Effect.void : onProgress(line))),
-            Effect.repeat(Schedule.spaced(UPDATE_PROGRESS_INTERVAL)),
-            Effect.forkScoped,
-          );
-        }
-        const trackProgress = <E>(stream: Stream.Stream<Uint8Array, E>) => {
-          if (!onProgress) {
-            return stream;
-          }
-          const decoder = new TextDecoder();
-          let partialLine = "";
-          return stream.pipe(
-            Stream.tap((chunk) => {
-              const split = splitOutputLines(partialLine, decoder.decode(chunk, { stream: true }));
-              partialLine = split.partialLine;
-              // A progress bar that redraws with a leading `\r` keeps its newest
-              // frame unterminated, so that frame is the latest status.
-              const line =
-                toProgressLine(split.partialLine) ??
-                split.lines.map(toProgressLine).findLast((value) => value !== null);
-              return line ? Ref.set(pendingProgress, line) : Effect.void;
-            }),
-          );
-        };
+export interface ProviderInstallInput {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+  readonly onProgress?: ((line: string) => Effect.Effect<void>) | undefined;
+  /** Called with the installer's pid once it is running, for the install lock. */
+  readonly recordChildPid: (pid: number) => Effect.Effect<void>;
+}
 
-        const [stdout, stderr, exitCode] = yield* Effect.all(
-          [
-            collectUint8StreamText({
-              stream: trackProgress(child.stdout),
-              maxBytes: UPDATE_OUTPUT_MAX_BYTES,
-            }),
-            collectUint8StreamText({
-              stream: trackProgress(child.stderr),
-              maxBytes: UPDATE_OUTPUT_MAX_BYTES,
-            }),
-            child.exitCode,
-          ],
-          { concurrency: "unbounded" },
-        ).pipe(
-          Effect.mapError(
-            (cause) =>
-              new ProviderMaintenanceCommandError({
-                message: cause instanceof Error ? cause.message : "Update command failed to run.",
-                cause,
-              }),
-          ),
-        );
+/** Runs one provider installer to completion. */
+export class ProviderInstaller extends Context.Service<
+  ProviderInstaller,
+  {
+    readonly run: (
+      input: ProviderInstallInput,
+    ) => Effect.Effect<ProviderMaintenanceCommandResult, Error>;
+  }
+>()("t3/provider/providerMaintenanceRunner/ProviderInstaller") {}
 
-        return {
-          stdout: stdout.text,
-          stderr: stderr.text,
-          exitCode: Number(exitCode),
-          timedOut: false,
-          stdoutTruncated: stdout.truncated,
-          stderrTruncated: stderr.truncated,
-        } satisfies ProviderMaintenanceCommandResult;
-      },
+const noop = () => {};
+
+/**
+ * Runs an installer as a detached process whose output goes to a log file. It
+ * is not tied to this server: quitting the server neither kills the installer
+ * nor breaks its stdio (no EPIPE), so an npm extract is never cut in half. Only
+ * the backstop ends it, and a result is returned once it exits.
+ */
+export const runDetachedInstall = Effect.fn("ProviderMaintenanceRunner.runDetachedInstall")(
+  function* (
+    input: ProviderInstallInput,
+    spawnProcess: typeof NodeChildProcess.spawn = NodeChildProcess.spawn,
+  ) {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const platform = yield* HostProcess.Platform;
+    const environment = yield* HostProcess.Environment;
+    // Resolve the executable for the host platform before spawning. On
+    // Windows the update tools are batch shims (e.g. `npm` -> `npm.cmd`),
+    // which a bare spawn cannot launch (spawn npm ENOENT); resolveSpawnCommand
+    // finds the real `.cmd` and routes it through the shell. On Linux/macOS
+    // (incl. the WSL backend) this is a no-op.
+    const resolved = yield* resolveSpawnCommand(input.command, input.args, {
+      ...(input.env ? { env: input.env } : {}),
+      extendEnv: true,
+    });
+    const toError = (cause: unknown) =>
+      new ProviderMaintenanceCommandError({
+        message: `Failed to run update command ${input.command}: ${cause instanceof Error ? cause.message : "unknown error"}`,
+        cause,
+      });
+    const logPath = yield* fileSystem.makeTempFileScoped({ prefix: "t3-provider-install-" });
+    // The child gets its own copy of this fd, so it is closed here once the child has spawned.
+    const logFd = yield* Effect.acquireRelease(
+      Effect.sync(() => NodeFS.openSync(logPath, "a")),
+      (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
     );
 
-    return yield* collectCommandResult().pipe(
-      Effect.scoped,
-      Effect.timeoutOption(Duration.millis(UPDATE_TIMEOUT_MS)),
-      Effect.map((result) =>
-        Option.match(result, {
-          onSome: (value) => value,
-          onNone: () =>
-            ({
-              stdout: "",
-              stderr: "",
-              exitCode: null,
-              timedOut: true,
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            }) satisfies ProviderMaintenanceCommandResult,
+    // Listeners are registered in the spawn tick: Node emits `spawn` and `exit`
+    // asynchronously, and a late listener would wait forever.
+    const { spawned, exited } = yield* Effect.try({
+      try: () => {
+        const child = spawnProcess(resolved.command, resolved.args, {
+          shell: resolved.shell,
+          detached: true,
+          windowsHide: true,
+          stdio: ["ignore", logFd, logFd],
+          ...(input.env ? { env: { ...environment, ...input.env } } : {}),
+        });
+        const spawned = Deferred.makeUnsafe<number, Error>();
+        const exited = Deferred.makeUnsafe<number | null>();
+        child.on("error", (cause) => Deferred.doneUnsafe(spawned, Effect.fail(toError(cause))));
+        child.once("spawn", () => Deferred.doneUnsafe(spawned, Effect.succeed(child.pid ?? 0)));
+        child.once("exit", (code) => Deferred.doneUnsafe(exited, Effect.succeed(code)));
+        child.unref();
+        return { spawned, exited };
+      },
+      catch: toError,
+    });
+    const pid = yield* Deferred.await(spawned);
+    yield* input.recordChildPid(pid);

@@ -0,0 +1,174 @@
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+
+/** A lock file this old is stale even if a process with its pid is alive (pid reuse). */
+const MAX_LOCK_AGE = Duration.hours(1);
+const IDLE_POLL_INTERVAL = Duration.seconds(1);
+
+export class ProviderInstallLockError extends Schema.TaggedError<ProviderInstallLockError>()(
+  "ProviderInstallLockError",
+  { cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return "Could not use the provider install lock directory.";
+  }
+}
+
+/**
+ * A lock on running a provider installer, shared by every T3 server on this
+ * host. Two servers must never run `npm i -g` on the same prefix at once, and
+ * a CLI must not be replaced while another server is launching it.
+ */
+export class ProviderInstallLock extends Context.Service<
+  ProviderInstallLock,
+  {
+    /**
+     * Runs `run` while holding the lock for `lockKey`, or returns `None` without
+     * running when another process holds it. `run` calls `recordChildPid` with the
+     * installer's pid: a detached installer outlives this server, and the lock
+     * stays held until it exits.
+     */
+    readonly tryRun: <A, E, R>(
+      lockKey: string,
+      run: (recordChildPid: (pid: number) => Effect.Effect<void>) => Effect.Effect<A, E, R>,
+    ) => Effect.Effect<Option.Option<A>, E | ProviderInstallLockError, R>;
+    /** Completes once no installer holds any lock, or when the lock directory cannot be read. */
+    readonly untilIdle: Effect.Effect<void>;
+    /** Whether any lock is held right now. A failed read is an error, not "free". */
+    readonly anyHeld: Effect.Effect<boolean, ProviderInstallLockError>;
+  }
+>()("t3/provider/ProviderInstallLock") {}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    // EPERM: the process exists but belongs to someone else.
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+const make = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const environment = yield* HostProcess.Environment;
+  const homeDirectory = yield* HostProcess.HomeDirectory;
+  const cacheHome = environment.XDG_CACHE_HOME || path.join(homeDirectory, ".cache");
+  const directory = path.join(cacheHome, "t3", "provider-install");
+
+  const toLockError = (cause: unknown) => new ProviderInstallLockError({ cause });
+  const ignoreNotFound =
+    <B>(fallback: B) =>
+    <A>(effect: Effect.Effect<A, PlatformError>): Effect.Effect<A | B, PlatformError> =>
+      effect.pipe(
+        Effect.catchTags({
+          PlatformError: (error) =>
+            error.reason._tag === "NotFound" ? Effect.succeed(fallback) : Effect.fail(error),
+        }),
+      );
+
+  /** Held while a recorded process is alive; a file mid-write counts as held until it ages out. */
+  const isHeld = Effect.fn("ProviderInstallLock.isHeld")(function* (file: string) {
+    const info = yield* fileSystem.stat(file);
+    const modifiedAt = Option.match(info.mtime, {
+      onNone: () => 0,
+      onSome: (date) => date.getTime(),
+    });
+    if ((yield* Clock.currentTimeMillis) - modifiedAt >= Duration.toMillis(MAX_LOCK_AGE)) {
+      return false;
+    }
+    // The file holds one pid: this server's, then its installer's once spawned.
+    const pid = Number.parseInt(yield* fileSystem.readFileString(file), 10);
+    return Number.isNaN(pid) || isPidAlive(pid);
+  });
+
+  const writePid = (file: string, pid: number, flag: "w" | "wx") =>
+    fileSystem.writeFileString(file, String(pid), { flag });
+
+  /** Creates the lock file exclusively; false when it exists and is held. A stale one is reclaimed once. */
+  const acquire = Effect.fn("ProviderInstallLock.acquire")(function* (file: string) {
+    yield* fileSystem.makeDirectory(directory, { recursive: true });
+    const create = writePid(file, process.pid, "wx").pipe(
+      Effect.as(true),
+      Effect.catchTags({
+        PlatformError: (error) =>
+          error.reason._tag === "AlreadyExists" ? Effect.succeed(false) : Effect.fail(error),
+      }),
+    );
+    if (yield* create) return true;
+    if (yield* isHeld(file).pipe(ignoreNotFound(false))) return false;
+    yield* fileSystem.remove(file, { force: true });
+    return yield* create;
+  });
+
+  const tryRun: ProviderInstallLock["Service"]["tryRun"] = (lockKey, run) => {
+    const file = path.join(directory, `${encodeURIComponent(lockKey)}.lock`);
+    return Effect.acquireUseRelease(
+      acquire(file).pipe(
+        Effect.mapError(toLockError),
+        // The ref holds the installer pid once `run` records it.
+        Effect.flatMap((acquired) =>
+          acquired ? Ref.make<number | undefined>(undefined) : Effect.succeed(undefined),
+        ),
+      ),
+      (installerPid) =>
+        installerPid === undefined
+          ? Effect.succeedNone
+          : run((pid) =>
+              Ref.set(installerPid, pid).pipe(
+                Effect.andThen(writePid(file, pid, "w")),
+                Effect.catch((cause) =>
+                  Effect.logWarning("Could not record the provider installer in its lock", {
+                    cause,
+                  }),
+                ),
+              ),
+            ).pipe(Effect.map(Option.some)),
+      (installerPid) =>
+        installerPid === undefined
+          ? Effect.void
+          : Ref.get(installerPid).pipe(
+              // A detached installer outlives this server; its pid keeps the lock held.
+              Effect.flatMap((pid) =>
+                pid !== undefined && isPidAlive(pid)
+                  ? Effect.void
+                  : fileSystem.remove(file, { force: true }),
+              ),
+              Effect.ignore,
+            ),
+    );
+  };
+
+  const anyHeld = Effect.gen(function* () {
+    const names = yield* fileSystem.readDirectory(directory).pipe(ignoreNotFound([]));
+    for (const name of names) {
+      if (!name.endsWith(".lock")) continue;
+      if (yield* isHeld(path.join(directory, name)).pipe(ignoreNotFound(false))) return true;
+    }
+    return false;
+  }).pipe(Effect.mapError(toLockError));
+
+  const untilIdle: Effect.Effect<void> = Effect.suspend(() =>
+    anyHeld.pipe(
+      Effect.orElseSucceed(() => false),

@@ -0,0 +1,451 @@
+// @effect-diagnostics nodeBuiltinImport:off - Host leases coordinate independent Node servers.
+// oxlint-disable t3code/no-global-process-runtime -- Leases belong to the OS user and process, not an environment.
+import * as NodeCrypto from "node:crypto";
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { lock } from "proper-lockfile";
+import * as Context from "effect/Context";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Deferred from "effect/Deferred";
+import * as Semaphore from "effect/Semaphore";
+import * as Schema from "effect/Schema";
+import * as Maintenance from "@t3tools/provider-core/server/maintenance";
+
+const HeldWrite = Context.Reference<{ readonly owner: object; active: boolean } | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldWrite",
+  { defaultValue: () => null },
+);
+
+interface ReadToken {
+  readonly lease: { readonly owner: object; readonly file: string; users: number };
+  active: boolean;
+}
+const HeldRead = Context.Reference<ReadToken | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldRead",
+  { defaultValue: () => null },
+);
+
+const HeldGate = Context.Reference<{
+  readonly handoff: Effect.Effect<void>;
+  readonly resume: Effect.Effect<void>;
+} | null>("t3/provider/ProviderMaintenanceHostLock/HeldGate", { defaultValue: () => null });
+
+// Linux exposes a process start identity, so recycled PIDs cannot pin a dead reader.
+const processIdentity = (pid: number) => {
+  if (NodeOS.platform() !== "linux") return null;
+  const fields = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").at(-1)!.split(" ");
+  return fields[0] === "Z" ? "" : fields[19]!;
+};
+
+export const installLeasePath = (directory: string) => NodePath.join(directory, "install.json");
+
+/** Start identity includes the Linux boot so leases cannot survive a reboot's PID reuse. */
+export const readProcessIdentity = (pid: number): string | null => {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    const platform = NodeOS.platform();
+    if (platform === "linux") {
+      const start = processIdentity(pid);
+      return start
+        ? `${NodeFS.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${start}`
+        : null;
+    }
+    if (platform !== "darwin" && platform !== "win32") return null;
+    const scan =
+      platform === "win32"
+        ? NodeChildProcess.spawnSync(
+            "powershell.exe",
+            [
+              "-NoProfile",
+              "-NonInteractive",
+              "-Command",
+              `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}' -ErrorAction Stop).CreationDate.ToUniversalTime().ToString('o')`,
+            ],
+            { encoding: "utf8", timeout: 10_000, windowsHide: true },
+          )
+        : NodeChildProcess.spawnSync("ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8",
+            timeout: 10_000,
+            env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+          });
+    return scan.error || scan.status !== 0 ? null : scan.stdout.trim() || null;
+  } catch {
+    return null;
+  }
+};
+
+export const isProcessAlive = (pid: number, identity?: string | null) => {
+  try {
+    process.kill(pid, 0);
+    if (processIdentity(pid) === "") return false;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ESRCH" || error.code === "ENOENT")
+    )
+      return false;
+    return true;
+  }
+  if (identity == null) return true;
+  const current = readProcessIdentity(pid);
+  return current === null || current === identity;
+};
+
+const decodeInstallLease = Schema.decodeSync(
+  Schema.fromJsonString(
+    Schema.Union([
+      Schema.Number,
+      Schema.Struct({
+        pid: Schema.Number,
+        identity: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ]),
+  ),
+);
+
+/** A dead supervisor's installer still owns admission until its entire process group exits. */
+export const installIsAlive = (directory: string): boolean => {
+  const file = installLeasePath(directory);
+  let pid: number;
+  let identity: string | null | undefined;
+  try {
+    const lease = decodeInstallLease(NodeFS.readFileSync(file, "utf8"));
+    pid = typeof lease === "number" ? lease : lease.pid;
+    identity = typeof lease === "number" ? undefined : lease.identity;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid provider install lease");
+  if (isProcessAlive(pid, identity)) return true;
+  return installChildrenAreAlive(pid);
+};
+
+/** The installer can leave children writing after its root exits. Failed scans keep admission closed. */
+export const installChildrenAreAlive = (pid: number): boolean => {
+  const windows = NodeOS.platform() === "win32";
+  const scan = windows
+    ? NodeChildProcess.spawnSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          'Get-CimInstance Win32_Process -ErrorAction Stop | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)" }',
+        ],
+        { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      )
+    : NodeChildProcess.spawnSync("ps", ["-ax", "-o", "pid=", "-o", "pgid=", "-o", "stat="], {
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+  if (scan.error || scan.status !== 0)
+    throw new Error("Could not inspect provider installer processes");
+  if (windows) {
+    const descendants = new Set([pid]);
+    const rows = scan.stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => line.split("|").map(Number));
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const [child, parent] of rows) {
+        if (
+          parent !== undefined &&
+          child !== undefined &&
+          child !== scan.pid &&
+          descendants.has(parent) &&
+          !descendants.has(child)
+        ) {
+          descendants.add(child);
+          changed = true;
+        }
+      }
+    }
+    if (descendants.size > 1) return true;
+  } else if (
+    scan.stdout.split(/\r?\n/).some((line) => {
+      const [child, group, state] = line.trim().split(/\s+/);
+      return (
+        Number(child) !== pid &&
+        Number(child) !== scan.pid &&
+        Number(group) === pid &&
+        state !== undefined &&
+        !state.startsWith("Z")
+      );
+    })
+  )
+    return true;
+  return false;
+};
+
+/**
+ * One user-wide reader/writer gate, deliberately covering every CLI: package
+ * managers can replace several providers in one installation. Readers overlap;
+ * an installer closes admission before waiting for active turns to drain.
+ */
+export const make = (directory: string) => {
+  const owner = {};
+  const readers = NodePath.join(directory, "readers");
+  const prepare = Effect.sync(() => NodeFS.mkdirSync(readers, { recursive: true }));
+  const acquireGate = (compromised: Deferred.Deferred<never>) =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* () {
+        yield* prepare;
+        const services = yield* Effect.context<never>();
+        while (true) {
+          while (yield* Effect.sync(() => installIsAlive(directory))) {
+            yield* Effect.interruptible(restore(Effect.sleep("1 second")));
+          }
+          let preserve = false;
+          const result = yield* Effect.tryPromise(() =>
+            lock(NodePath.join(directory, "gate"), {
+              realpath: false,
+              stale: 120_000,
+              update: 10_000,
+              fs: {
+                ...NodeFS,
+                rmdir: (
+                  path: NodeFS.PathLike,
+                  callback: (error: NodeJS.ErrnoException | null) => void,
+                ) => {
+                  if (preserve) callback(null);
+                  else NodeFS.rmdir(path, callback);
+                },
+              },
+              onCompromised: (error) =>
+                Effect.runSyncWith(services)(Deferred.die(compromised, error)),
+            }),
+          ).pipe(Effect.result);
+          if (result._tag === "Success") {
+            // An installer may have registered after our first check, before its
+            // server died and this gate's heartbeat expired.
+            const alive = yield* Effect.sync(() => {
+              const alive = installIsAlive(directory);
+              // Reclaim under the gate so no scan can erase a newer install lease.
+              if (!alive) NodeFS.rmSync(installLeasePath(directory), { force: true });
+              return alive;
+            }).pipe(Effect.onError(() => Effect.promise(() => result.success())));
+            if (alive) {
+              yield* Effect.promise(() => result.success());
+              continue;
+            }
+            return {
+              release: result.success,
+              handoff: async () => {
+                preserve = true;
+                await result.success();
+              },
+            };
+          }
+          const cause = result.failure.cause;
+          if (!(cause instanceof Error) || !("code" in cause) || cause.code !== "ELOCKED") {
+            return yield* Effect.die(cause);
+          }
+          yield* Effect.interruptible(restore(Effect.sleep("100 millis")));
+        }
+      }),
+    );
+  const withGate = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.acquireUseRelease(
+      Effect.gen(function* () {
+        const compromised = yield* Deferred.make<never>();
+        let current = yield* acquireGate(compromised);
+        let held = true;
+        const token = {
+          handoff: Effect.promise(async () => {
+            await current.handoff();
+            held = false;
+          }),
+          resume: Effect.map(acquireGate(compromised), (gate) => {
+            current = gate;
+            held = true;
+          }),
+        };
+        return {
+          token,
+          compromised,
+          release: () => (held ? current.release() : Promise.resolve()),
+        };
+      }),
+      ({ token, compromised }) =>
+        effect.pipe(
+          Effect.provideService(HeldGate, token),
+          Effect.raceFirst(Deferred.await(compromised)),
+        ),
+      ({ release }) => Effect.promise(release),
+    );
+  // Stop this process's heartbeat and exit hook without opening the gate. The
+  // acknowledged supervisor maintains the same gate, then releases it on exit.
+  const handoff = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.flatMap(HeldGate, (gate) =>
+      gate === null
+        ? Effect.die(new Error("Provider install requires the host write lease"))
+        : Effect.uninterruptibleMask((restore) =>
+            gate.handoff.pipe(
+              Effect.andThen(restore(effect)),
+              Effect.onExit((exit) =>
+                exit._tag === "Failure" && Cause.hasInterrupts(exit.cause)
+                  ? Effect.void
+                  : restore(gate.resume),
+              ),
+            ),
+          ),
+    );
+
+  const readPermit = Semaphore.makeUnsafe(1);
+  const readTokens = new WeakMap<Effect.Effect<void>, ReadToken>();
+  const registerRead = Effect.sync(() => {
+    const file = NodePath.join(readers, `${process.pid}-${NodeCrypto.randomUUID()}`);
+    NodeFS.writeFileSync(file, processIdentity(process.pid) ?? "", { flag: "wx" });
+    return file;
+  });
+  // A provider can launch helper CLIs while its turn holds a read lease.
+  // Joining that lease must not wait behind an installer draining this turn.
+  const acquireRead = Effect.uninterruptible(
+    Effect.gen(function* () {
+      const inherited = yield* HeldRead;
+      const held = yield* HeldWrite;
+      const lease =
+        inherited?.lease.owner === owner && inherited.active
+          ? inherited.lease
+          : {
+              owner,
+              // An install's scoped verification keeps its own reader if it outlives the writer.
+              file: yield* held?.owner === owner && held.active
+                ? registerRead
+                : Effect.acquireUseRelease(
+                    Effect.interruptible(readPermit.take(1)),
+                    () => withGate(registerRead),
+                    () => Effect.asVoid(readPermit.release(1)),
+                  ),
+              users: 0,
+            };
+      lease.users++;
+      const token = { lease, active: true };
+      const release = Effect.sync(() => {
+        if (!token.active) return;
+        token.active = false;
+        if (--lease.users === 0) NodeFS.rmSync(lease.file, { force: true });
+      });
+      readTokens.set(release, token);
+      return release;
+    }),
+  );
+  const withRead = <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    inheritedRelease?: Effect.Effect<void>,
+  ) => {
+    const inherited = inheritedRelease === undefined ? undefined : readTokens.get(inheritedRelease);
+    const read = Effect.acquireUseRelease(
+      acquireRead,
+      (release) => effect.pipe(Effect.provideService(HeldRead, readTokens.get(release)!)),
+      (release) => release,
+    );
+    return inherited === undefined ? read : read.pipe(Effect.provideService(HeldRead, inherited));
+  };
+  const drained = Effect.sync(() => {
+    let busy = false;
+    for (const file of NodeFS.readdirSync(readers)) {
+      const pid = Number(file.split("-")[0]);
+      try {
+        process.kill(pid, 0);
+        const identity = processIdentity(pid);

@@ -0,0 +1,378 @@
+// @effect-diagnostics nodeBuiltinImport:off - Host leases coordinate independent Node servers.
+// oxlint-disable t3code/no-global-process-runtime -- Leases belong to the OS user and process, not an environment.
+import * as NodeCrypto from "node:crypto";
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { lock } from "proper-lockfile";
+import * as Context from "effect/Context";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Deferred from "effect/Deferred";
+import * as Semaphore from "effect/Semaphore";
+import * as Maintenance from "@t3tools/provider-core/server/maintenance";
+
+const HeldWrite = Context.Reference<{ readonly owner: object; active: boolean } | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldWrite",
+  { defaultValue: () => null },
+);
+
+const HeldGate = Context.Reference<{
+  readonly handoff: Effect.Effect<void>;
+  readonly resume: Effect.Effect<void>;
+} | null>("t3/provider/ProviderMaintenanceHostLock/HeldGate", { defaultValue: () => null });
+
+// Linux exposes a process start identity, so recycled PIDs cannot pin a dead reader.
+const processIdentity = (pid: number) => {
+  if (NodeOS.platform() !== "linux") return null;
+  const fields = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").at(-1)!.split(" ");
+  return fields[0] === "Z" ? "" : fields[19]!;
+};
+
+export const installLeasePath = (directory: string) => NodePath.join(directory, "install.json");
+
+export const isProcessAlive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return processIdentity(pid) !== "";
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ESRCH" || error.code === "ENOENT")
+    )
+      return false;
+    throw error;
+  }
+};
+
+/** A dead supervisor's installer still owns admission until its entire process group exits. */
+export const installIsAlive = (directory: string): boolean => {
+  const file = installLeasePath(directory);
+  let pid: number;
+  try {
+    pid = Number(NodeFS.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid provider install lease");
+  if (isProcessAlive(pid)) return true;
+  return installChildrenAreAlive(pid);
+};
+
+/** The installer can leave children writing after its root exits. Failed scans keep admission closed. */
+export const installChildrenAreAlive = (pid: number): boolean => {
+  const windows = NodeOS.platform() === "win32";
+  const scan = windows
+    ? NodeChildProcess.spawnSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          'Get-CimInstance Win32_Process -ErrorAction Stop | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)" }',
+        ],
+        { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      )
+    : NodeChildProcess.spawnSync("ps", ["-ax", "-o", "pid=", "-o", "pgid=", "-o", "stat="], {
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+  if (scan.error || scan.status !== 0)
+    throw new Error("Could not inspect provider installer processes");
+  if (windows) {
+    const descendants = new Set([pid]);
+    const rows = scan.stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => line.split("|").map(Number));
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const [child, parent] of rows) {
+        if (
+          parent !== undefined &&
+          child !== undefined &&
+          child !== scan.pid &&
+          descendants.has(parent) &&
+          !descendants.has(child)
+        ) {
+          descendants.add(child);
+          changed = true;
+        }
+      }
+    }
+    if (descendants.size > 1) return true;
+  } else if (
+    scan.stdout.split(/\r?\n/).some((line) => {
+      const [child, group, state] = line.trim().split(/\s+/);
+      return (
+        Number(child) !== pid &&
+        Number(child) !== scan.pid &&
+        Number(group) === pid &&
+        state !== undefined &&
+        !state.startsWith("Z")
+      );
+    })
+  )
+    return true;
+  return false;
+};
+
+/**
+ * One user-wide reader/writer gate, deliberately covering every CLI: package
+ * managers can replace several providers in one installation. Readers overlap;
+ * an installer closes admission before waiting for active turns to drain.
+ */
+export const make = (directory: string) => {
+  const owner = {};
+  const readers = NodePath.join(directory, "readers");
+  const prepare = Effect.sync(() => NodeFS.mkdirSync(readers, { recursive: true }));
+  const acquireGate = (compromised: Deferred.Deferred<never>) =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* () {
+        yield* prepare;
+        const services = yield* Effect.context<never>();
+        while (true) {
+          while (yield* Effect.sync(() => installIsAlive(directory))) {
+            yield* Effect.interruptible(restore(Effect.sleep("1 second")));
+          }
+          let preserve = false;
+          const result = yield* Effect.tryPromise(() =>
+            lock(NodePath.join(directory, "gate"), {
+              realpath: false,
+              stale: 120_000,
+              update: 10_000,
+              fs: {
+                ...NodeFS,
+                rmdir: (
+                  path: NodeFS.PathLike,
+                  callback: (error: NodeJS.ErrnoException | null) => void,
+                ) => {
+                  if (preserve) callback(null);
+                  else NodeFS.rmdir(path, callback);
+                },
+              },
+              onCompromised: (error) =>
+                Effect.runSyncWith(services)(Deferred.die(compromised, error)),
+            }),
+          ).pipe(Effect.result);
+          if (result._tag === "Success") {
+            // An installer may have registered after our first check, before its
+            // server died and this gate's heartbeat expired.
+            if (yield* Effect.sync(() => installIsAlive(directory))) {
+              yield* Effect.promise(() => result.success());
+              continue;
+            }
+            // Reclaim only under the gate, so a concurrent stale-owner scan
+            // cannot erase a newer supervisor's lease.
+            yield* Effect.sync(() => NodeFS.rmSync(installLeasePath(directory), { force: true }));
+            return {
+              release: result.success,
+              handoff: async () => {
+                preserve = true;
+                await result.success();
+              },
+            };
+          }
+          const cause = result.failure.cause;
+          if (!(cause instanceof Error) || !("code" in cause) || cause.code !== "ELOCKED") {
+            return yield* Effect.die(cause);
+          }
+          yield* Effect.interruptible(restore(Effect.sleep("100 millis")));
+        }
+      }),
+    );
+  const withGate = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.acquireUseRelease(
+      Effect.gen(function* () {
+        const compromised = yield* Deferred.make<never>();
+        let current = yield* acquireGate(compromised);
+        let held = true;
+        const token = {
+          handoff: Effect.promise(async () => {
+            await current.handoff();
+            held = false;
+          }),
+          resume: Effect.map(acquireGate(compromised), (gate) => {
+            current = gate;
+            held = true;
+          }),
+        };
+        return {
+          token,
+          compromised,
+          release: () => (held ? current.release() : Promise.resolve()),
+        };
+      }),
+      ({ token, compromised }) =>
+        effect.pipe(
+          Effect.provideService(HeldGate, token),
+          Effect.raceFirst(Deferred.await(compromised)),
+        ),
+      ({ release }) => Effect.promise(release),
+    );
+  // Stop this process's heartbeat and exit hook without opening the gate. The
+  // acknowledged supervisor maintains the same gate, then releases it on exit.
+  const handoff = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.flatMap(HeldGate, (gate) =>
+      gate === null
+        ? Effect.die(new Error("Provider install requires the host write lease"))
+        : Effect.uninterruptibleMask((restore) =>
+            gate.handoff.pipe(
+              Effect.andThen(restore(effect)),
+              Effect.onExit((exit) =>
+                exit._tag === "Failure" && Cause.hasInterrupts(exit.cause)
+                  ? Effect.void
+                  : restore(gate.resume),
+              ),
+            ),
+          ),
+    );
+
+  const readPermit = Semaphore.makeUnsafe(1);
+  let readCount = 0;
+  let readFile: string | undefined;
+  const registerRead = Effect.sync(() => {
+    const file = NodePath.join(readers, `${process.pid}-${NodeCrypto.randomUUID()}`);
+    NodeFS.writeFileSync(file, processIdentity(process.pid) ?? "", { flag: "wx" });
+    return file;
+  });
+  // A provider can launch helper CLIs while its turn holds a read lease.
+  // Joining that lease must not wait behind an installer draining this turn.
+  const acquireRead = Effect.flatMap(HeldWrite, (held) =>
+    held?.owner === owner && held.active
+      ? // A scoped verification can outlive the install. Its own reader remains
+        // visible to the next writer without admitting unrelated launches here.
+        registerRead.pipe(
+          Effect.map((file) => Effect.sync(() => NodeFS.rmSync(file, { force: true }))),
+        )
+      : Effect.acquireUseRelease(
+          Effect.interruptible(readPermit.take(1)),
+          () =>
+            Effect.uninterruptible(
+              Effect.gen(function* () {
+                if (readCount === 0) {

@@ -266,6 +275,9 @@ export const make = Effect.fn("background.policy.make")(function* () {
           expiresAt,
         };
         yield* Ref.update(leasesRef, (leases) => upsertClientActivityLease(leases, lease, now));
+        if (input.recentlyInteracted) {

@@ -3595,6 +3614,23 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
                   )
                   ELSE 0 END
               `;
+            case "active-work":
+              return sql`
+                SELECT thread_id FROM orchestration_v2_projection_runs
+                WHERE status IN ('preparing', 'starting', 'running', 'waiting')
+                UNION
+                SELECT threads.thread_id FROM orchestration_v2_projection_provider_threads AS threads
+                WHERE CASE WHEN json_valid(threads.payload_json)
+                    THEN json_array_length(threads.payload_json, '$.pendingBackgroundTasks') > 0
+                    ELSE 0 END
+                  AND EXISTS (
+                    SELECT 1 FROM orchestration_v2_projection_provider_session_bindings AS bindings
+                    CROSS JOIN orchestration_v2_projection_provider_sessions AS sessions
+                      ON sessions.provider_session_id = bindings.provider_session_id
+                    WHERE bindings.thread_id = threads.thread_id
+                      AND sessions.status NOT IN ('stopped', 'error')

@@ -0,0 +1,362 @@
+// @effect-diagnostics nodeBuiltinImport:off globalTimers:off globalDate:off preferSchemaOverJson:off - Detached runtime boundary; receipts survive their server.
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import * as NodeCrypto from "node:crypto";
+import * as Context from "effect/Context";
+import * as Clock from "effect/Clock";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { resolveSelfInvocation, selfInvocationArgs } from "@t3tools/shared/nodeRuntime";
+import { ProviderDriverKind, ProviderInstanceId } from "@t3tools/contracts";
+import * as ServerConfig from "../config.ts";
+import * as HostLock from "./ProviderMaintenanceHostLock.ts";
+import type { ProviderMaintenanceCommandResult } from "./providerMaintenanceRunner.ts";
+
+const Result = Schema.Struct({
+  stdout: Schema.String,
+  stderr: Schema.String,
+  exitCode: Schema.NullOr(Schema.Number),
+  timedOut: Schema.Boolean,
+  stdoutTruncated: Schema.Boolean,
+  stderrTruncated: Schema.Boolean,
+});
+const Receipt = Schema.Struct({
+  id: Schema.String,
+  provider: ProviderDriverKind,
+  instanceId: ProviderInstanceId,
+  instanceIds: Schema.Array(ProviderInstanceId),
+  origin: Schema.optional(Schema.Literals(["manual", "background"])),
+  targetVersion: Schema.optional(Schema.String),
+  exactVersion: Schema.optional(Schema.Boolean),
+  startedAt: Schema.String,
+  finishedAt: Schema.optional(Schema.String),
+  command: Schema.String,
+  args: Schema.Array(Schema.String),
+  env: Schema.optional(Schema.Record(Schema.String, Schema.UndefinedOr(Schema.String))),
+  parentPid: Schema.Number,
+  directory: Schema.String,
+  pid: Schema.optional(Schema.Number),
+  progress: Schema.optional(Schema.String),
+  result: Schema.optional(Result),
+});
+export type InstallReceipt = typeof Receipt.Type;
+const decodeReceipt = Schema.decodeSync(Schema.fromJsonString(Receipt));
+export const readReceipt = (file: string) => decodeReceipt(NodeFS.readFileSync(file, "utf8"));
+const writeReceipt = (file: string, receipt: InstallReceipt) => {
+  const temp = `${file}.${process.pid}.tmp`;
+  NodeFS.writeFileSync(temp, JSON.stringify(receipt), { mode: 0o600 });
+  NodeFS.renameSync(temp, file);
+};
+
+type InstallInput = Pick<
+  InstallReceipt,
+  | "provider"
+  | "instanceId"
+  | "instanceIds"
+  | "origin"
+  | "targetVersion"
+  | "exactVersion"
+  | "startedAt"
+  | "command"
+  | "args"
+  | "env"
+> & {
+  readonly onProgress?: (line: string) => Effect.Effect<void>;
+};
+
+export class ProviderInstallError extends Data.TaggedError("ProviderInstallError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+const installError = (cause: unknown) =>
+  new ProviderInstallError({
+    message: cause instanceof Error ? cause.message : "Provider installer could not run.",
+    cause,
+  });
+
+export class ProviderInstallSupervisor extends Context.Service<
+  ProviderInstallSupervisor,
+  {
+    readonly run: (
+      input: InstallInput,
+    ) => Effect.Effect<ProviderMaintenanceCommandResult, ProviderInstallError>;
+    readonly receipts: Effect.Effect<ReadonlyArray<InstallReceipt>, ProviderInstallError>;
+  }
+>()("t3/provider/ProviderInstallSupervisor") {}
+
+export const layer = Layer.effect(
+  ProviderInstallSupervisor,
+  Effect.gen(function* () {
+    const config = yield* ServerConfig.ServerConfig;
+    const host = yield* HostLock.ProviderMaintenanceHostLock;
+    const invocation = yield* resolveSelfInvocation();
+    const root = NodePath.join(config.stateDir, "provider-updates");
+    const run: ProviderInstallSupervisor["Service"]["run"] = Effect.fn(
+      "ProviderInstallSupervisor.run",
+    )(function* (input) {
+      const file = NodePath.join(root, `${encodeURIComponent(input.instanceId)}.json`);
+      const receipt: InstallReceipt = {
+        ...input,
+        id: NodeCrypto.randomUUID(),
+        parentPid: process.pid,
+        directory: host.directory,
+      };
+      yield* Effect.try(() => {
+        NodeFS.mkdirSync(root, { recursive: true, mode: 0o700 });
+        NodeFS.rmSync(`${file}.start`, { force: true });
+        writeReceipt(file, receipt);
+      });
+      yield* Effect.tryPromise(
+        () =>
+          new Promise<void>((resolve, reject) => {
+            // The relay exits before the supervisor starts the installer. On Windows,
+            // detached alone does not remove a process from taskkill /t's parent tree.
+            const relay = NodeChildProcess.spawn(
+              invocation.command,
+              [...selfInvocationArgs(invocation, ["__provider-install-relay", file])],
+              {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+                env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
+              },
+            );
+            relay.once("error", reject);
+            relay.once("spawn", () => {
+              relay.unref();
+              resolve();
+            });
+          }),
+      );
+      const readCurrent = Effect.try(() => {
+        const current = readReceipt(file);
+        if (current.id !== receipt.id)
+          throw new ProviderInstallError({ message: "Provider install receipt replaced." });
+        return current;
+      });
+      const deadline = (yield* Clock.currentTimeMillis) + 30_000;
+      while (true) {
+        const current = yield* readCurrent;
+        if (current.result) return current.result;
+        if (current.pid !== undefined) break;
+        if ((yield* Clock.currentTimeMillis) >= deadline)
+          return yield* Effect.fail(
+            new ProviderInstallError({ message: "Provider install supervisor did not start." }),
+          );
+        yield* Effect.sleep("100 millis");
+      }
+      return yield* host.handoff(
+        Effect.gen(function* () {
+          let started = false;
+          let progress: string | undefined;
+          while (true) {
+            const current = yield* readCurrent;
+            if (current.result) return current.result;
+            if (current.pid !== undefined && !started) {
+              // Only acknowledge after the durable lease is visible. A server dying
+              // before this write cannot authorize a late installer to start.
+              yield* Effect.try(() =>
+                NodeFS.writeFileSync(`${file}.start`, receipt.id, { mode: 0o600 }),
+              );
+              started = true;
+            }
+            if (current.progress && current.progress !== progress) {
+              progress = current.progress;
+              if (input.onProgress) yield* input.onProgress(progress);
+            }
+            if (!started && (yield* Clock.currentTimeMillis) >= deadline)
+              return yield* Effect.fail(
+                new ProviderInstallError({ message: "Provider install supervisor did not start." }),
+              );
+            if (started && !(yield* Effect.sync(() => HostLock.installIsAlive(host.directory)))) {
+              return yield* Effect.fail(
+                new ProviderInstallError({
+                  message: "Provider install supervisor exited without a result.",
+                }),
+              );
+            }
+            yield* Effect.sleep("1 second");
+          }
+        }),
+      );
+    }, Effect.mapError(installError));
+    return ProviderInstallSupervisor.of({
+      run,
+      receipts: Effect.try(() =>
+        NodeFS.existsSync(root)
+          ? NodeFS.readdirSync(root)
+              .filter((file) => file.endsWith(".json"))
+              .map((file) => readReceipt(NodePath.join(root, file)))
+          : [],
+      ).pipe(Effect.mapError(installError)),
+    });
+  }),
+);
+
+/** The server holds the gate until the supervisor has registered its own install lease. */
+export async function runInstallSubcommand(command: string, args: ReadonlyArray<string>) {
+  const file = args[0];
+  if (!file) throw new Error("Missing provider install receipt");
+  if (command === "__provider-install-relay") {
+    const invocation = await Effect.runPromise(
+      resolveSelfInvocation().pipe(Effect.provide(NodeServices.layer)),
+    );
+    NodeFS.writeFileSync(`${file}.stdout`, "", { mode: 0o600 });
+    NodeFS.writeFileSync(`${file}.stderr`, "", { mode: 0o600 });
+    const stdout = NodeFS.openSync(`${file}.stdout`, "a", 0o600);
+    const stderr = NodeFS.openSync(`${file}.stderr`, "a", 0o600);
+    const child = NodeChildProcess.spawn(
+      invocation.command,
+      [...selfInvocationArgs(invocation, ["__provider-install", file, String(process.pid)])],
+      {
+        detached: true,
+        stdio: ["ignore", stdout, stderr],
+        windowsHide: true,
+        env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
+      },
+    );
+    NodeFS.closeSync(stdout);
+    NodeFS.closeSync(stderr);
+    await new Promise<void>((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    child.unref();
+    return;
+  }
+  let receipt = readReceipt(file);
+  const relayPid = Number(args[1]);
+  // The live relay is the only link into the desktop/server's Windows tree.
+  while (HostLock.isProcessAlive(relayPid)) await new Promise((resolve) => setTimeout(resolve, 25));
+  const lease = HostLock.installLeasePath(receipt.directory);
+  const candidate = `${lease}.${process.pid}`;
+  NodeFS.writeFileSync(candidate, String(process.pid), { flag: "wx", mode: 0o600 });
+  try {
+    // A delayed relay must never overwrite an already running install's owner.
+    NodeFS.linkSync(candidate, lease);
+  } finally {
+    NodeFS.rmSync(candidate, { force: true });
+  }
+  // Quit signals must never interrupt an install. SIGKILL still leaves the
+  // process group in the lease, which other servers inspect before reclaiming.
+  process.on("SIGTERM", () => {});
+  process.on("SIGINT", () => {});
+  const truncated = new Set<string>();
+  const output = (suffix: string) => {
+    const fd = NodeFS.openSync(file + suffix, "r+");
+    try {
+      const size = NodeFS.fstatSync(fd).size;
+      const buffer = Buffer.alloc(Math.min(size, 10_000));
+      NodeFS.readSync(fd, buffer, 0, buffer.length, Math.max(0, size - buffer.length));
+      if (size > buffer.length) truncated.add(suffix);
+      if (size > 20_000) {
+        NodeFS.ftruncateSync(fd, 0);
+        NodeFS.writeSync(fd, buffer, 0, buffer.length, 0);
+      }
+      return { text: buffer.toString("utf8"), truncated: truncated.has(suffix) };
+    } finally {
+      NodeFS.closeSync(fd);
+    }
+  };
+  let heartbeat: NodeJS.Timeout | undefined;
+  let ownsGate = false;
+  let installerFinished = false;
+  const beat = (format: (line: string) => string | null) => {
+    NodeFS.utimesSync(lease, new Date(), new Date());
+    NodeFS.utimesSync(NodePath.join(receipt.directory, "gate.lock"), new Date(), new Date());
+    const text = output(".stderr").text || output(".stdout").text;

@@ -0,0 +1,397 @@
+// @effect-diagnostics nodeBuiltinImport:off - Host leases coordinate independent Node servers.
+// oxlint-disable t3code/no-global-process-runtime -- Leases belong to the OS user and process, not an environment.
+import * as NodeCrypto from "node:crypto";
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { lock } from "proper-lockfile";
+import * as Context from "effect/Context";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Deferred from "effect/Deferred";
+import * as Semaphore from "effect/Semaphore";
+import * as Maintenance from "@t3tools/provider-core/server/maintenance";
+
+const HeldWrite = Context.Reference<{ readonly owner: object; active: boolean } | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldWrite",
+  { defaultValue: () => null },
+);
+
+interface ReadToken {
+  readonly lease: { readonly owner: object; readonly file: string; users: number };
+  active: boolean;
+}
+const HeldRead = Context.Reference<ReadToken | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldRead",
+  { defaultValue: () => null },
+);
+
+const HeldGate = Context.Reference<{
+  readonly handoff: Effect.Effect<void>;
+  readonly resume: Effect.Effect<void>;
+} | null>("t3/provider/ProviderMaintenanceHostLock/HeldGate", { defaultValue: () => null });
+
+// Linux exposes a process start identity, so recycled PIDs cannot pin a dead reader.
+const processIdentity = (pid: number) => {
+  if (NodeOS.platform() !== "linux") return null;
+  const fields = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").at(-1)!.split(" ");
+  return fields[0] === "Z" ? "" : fields[19]!;
+};
+
+export const installLeasePath = (directory: string) => NodePath.join(directory, "install.json");
+
+export const isProcessAlive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return processIdentity(pid) !== "";
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ESRCH" || error.code === "ENOENT")
+    )
+      return false;
+    throw error;
+  }
+};
+
+/** A dead supervisor's installer still owns admission until its entire process group exits. */
+export const installIsAlive = (directory: string): boolean => {
+  const file = installLeasePath(directory);
+  let pid: number;
+  try {
+    pid = Number(NodeFS.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid provider install lease");
+  if (isProcessAlive(pid)) return true;
+  return installChildrenAreAlive(pid);
+};
+
+/** The installer can leave children writing after its root exits. Failed scans keep admission closed. */
+export const installChildrenAreAlive = (pid: number): boolean => {
+  const windows = NodeOS.platform() === "win32";
+  const scan = windows
+    ? NodeChildProcess.spawnSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          'Get-CimInstance Win32_Process -ErrorAction Stop | ForEach-Object { Write-Output "$($_.ProcessId)|$($_.ParentProcessId)" }',
+        ],
+        { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      )
+    : NodeChildProcess.spawnSync("ps", ["-ax", "-o", "pid=", "-o", "pgid=", "-o", "stat="], {
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+  if (scan.error || scan.status !== 0)
+    throw new Error("Could not inspect provider installer processes");
+  if (windows) {
+    const descendants = new Set([pid]);
+    const rows = scan.stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => line.split("|").map(Number));
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const [child, parent] of rows) {
+        if (
+          parent !== undefined &&
+          child !== undefined &&
+          child !== scan.pid &&
+          descendants.has(parent) &&
+          !descendants.has(child)
+        ) {
+          descendants.add(child);
+          changed = true;
+        }
+      }
+    }
+    if (descendants.size > 1) return true;
+  } else if (
+    scan.stdout.split(/\r?\n/).some((line) => {
+      const [child, group, state] = line.trim().split(/\s+/);
+      return (
+        Number(child) !== pid &&
+        Number(child) !== scan.pid &&
+        Number(group) === pid &&
+        state !== undefined &&
+        !state.startsWith("Z")
+      );
+    })
+  )
+    return true;
+  return false;
+};
+
+/**
+ * One user-wide reader/writer gate, deliberately covering every CLI: package
+ * managers can replace several providers in one installation. Readers overlap;
+ * an installer closes admission before waiting for active turns to drain.
+ */
+export const make = (directory: string) => {
+  const owner = {};
+  const readers = NodePath.join(directory, "readers");
+  const prepare = Effect.sync(() => NodeFS.mkdirSync(readers, { recursive: true }));
+  const acquireGate = (compromised: Deferred.Deferred<never>) =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* () {
+        yield* prepare;
+        const services = yield* Effect.context<never>();
+        while (true) {
+          while (yield* Effect.sync(() => installIsAlive(directory))) {
+            yield* Effect.interruptible(restore(Effect.sleep("1 second")));
+          }
+          let preserve = false;
+          const result = yield* Effect.tryPromise(() =>
+            lock(NodePath.join(directory, "gate"), {
+              realpath: false,
+              stale: 120_000,
+              update: 10_000,
+              fs: {
+                ...NodeFS,
+                rmdir: (
+                  path: NodeFS.PathLike,
+                  callback: (error: NodeJS.ErrnoException | null) => void,
+                ) => {
+                  if (preserve) callback(null);
+                  else NodeFS.rmdir(path, callback);
+                },
+              },
+              onCompromised: (error) =>
+                Effect.runSyncWith(services)(Deferred.die(compromised, error)),
+            }),
+          ).pipe(Effect.result);
+          if (result._tag === "Success") {
+            // An installer may have registered after our first check, before its
+            // server died and this gate's heartbeat expired.
+            if (yield* Effect.sync(() => installIsAlive(directory))) {

@@ -0,0 +1,174 @@
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+
+/** A lock file this old is stale even if a process with its pid is alive (pid reuse). */
+const MAX_LOCK_AGE = Duration.hours(1);
+const IDLE_POLL_INTERVAL = Duration.seconds(1);
+
+export class ProviderInstallLockError extends Schema.TaggedError<ProviderInstallLockError>()(
+  "ProviderInstallLockError",
+  { cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return "Could not use the provider install lock directory.";
+  }
+}
+
+/**
+ * A lock on running a provider installer, shared by every T3 server on this
+ * host. Two servers must never run `npm i -g` on the same prefix at once, and
+ * a CLI must not be replaced while another server is launching it.
+ */
+export class ProviderInstallLock extends Context.Service<
+  ProviderInstallLock,
+  {
+    /**
+     * Runs `run` while holding the lock for `lockKey`, or returns `None` without
+     * running when another process holds it. `run` calls `recordChildPid` with the
+     * installer's pid: a detached installer outlives this server, and the lock
+     * stays held until it exits.
+     */
+    readonly tryRun: <A, E, R>(
+      lockKey: string,
+      run: (recordChildPid: (pid: number) => Effect.Effect<void>) => Effect.Effect<A, E, R>,
+    ) => Effect.Effect<Option.Option<A>, E | ProviderInstallLockError, R>;
+    /** Completes once no installer holds any lock, or when the lock directory cannot be read. */
+    readonly untilIdle: Effect.Effect<void>;
+    /** Whether any lock is held right now. A failed read is an error, not "free". */
+    readonly anyHeld: Effect.Effect<boolean, ProviderInstallLockError>;
+  }
+>()("t3/provider/ProviderInstallLock") {}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    // EPERM: the process exists but belongs to someone else.
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+const make = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const environment = yield* HostProcess.Environment;
+  const homeDirectory = yield* HostProcess.HomeDirectory;
+  const cacheHome = environment.XDG_CACHE_HOME || path.join(homeDirectory, ".cache");
+  const directory = path.join(cacheHome, "t3", "provider-install");
+
+  const toLockError = (cause: unknown) => new ProviderInstallLockError({ cause });
+  const ignoreNotFound =
+    <B>(fallback: B) =>
+    <A>(effect: Effect.Effect<A, PlatformError>): Effect.Effect<A | B, PlatformError> =>
+      effect.pipe(
+        Effect.catchTags({
+          PlatformError: (error) =>
+            error.reason._tag === "NotFound" ? Effect.succeed(fallback) : Effect.fail(error),
+        }),
+      );
+
+  /** Held while a recorded process is alive; a file mid-write counts as held until it ages out. */
+  const isHeld = Effect.fn("ProviderInstallLock.isHeld")(function* (file: string) {
+    const info = yield* fileSystem.stat(file);
+    const modifiedAt = Option.match(info.mtime, {
+      onNone: () => 0,
+      onSome: (date) => date.getTime(),
+    });
+    if ((yield* Clock.currentTimeMillis) - modifiedAt >= Duration.toMillis(MAX_LOCK_AGE)) {
+      return false;
+    }
+    // The file holds one pid: this server's, then its installer's once spawned.
+    const pid = Number.parseInt(yield* fileSystem.readFileString(file), 10);
+    return Number.isNaN(pid) || isPidAlive(pid);
+  });
+
+  const writePid = (file: string, pid: number, flag: "w" | "wx") =>
+    fileSystem.writeFileString(file, String(pid), { flag });
+
+  /** Creates the lock file exclusively; false when it exists and is held. A stale one is reclaimed once. */
+  const acquire = Effect.fn("ProviderInstallLock.acquire")(function* (file: string) {
+    yield* fileSystem.makeDirectory(directory, { recursive: true });
+    const create = writePid(file, process.pid, "wx").pipe(
+      Effect.as(true),
+      Effect.catchTags({
+        PlatformError: (error) =>
+          error.reason._tag === "AlreadyExists" ? Effect.succeed(false) : Effect.fail(error),
+      }),
+    );
+    if (yield* create) return true;
+    if (yield* isHeld(file).pipe(ignoreNotFound(false))) return false;
+    yield* fileSystem.remove(file, { force: true });

@@ -0,0 +1,206 @@
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+
+/** A lock file this old is stale even if a process with its pid is alive (pid reuse). */
+const MAX_LOCK_AGE = Duration.hours(1);
+/** A reclaim sentinel this old was left by a process that died mid-reclaim. */
+const MAX_SENTINEL_AGE = Duration.seconds(10);
+const IDLE_POLL_INTERVAL = Duration.seconds(1);
+
+export class ProviderInstallLockError extends Schema.TaggedError<ProviderInstallLockError>()(
+  "ProviderInstallLockError",
+  { cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return "Could not use the provider install lock directory.";
+  }
+}
+
+/**
+ * A lock on running a provider installer, shared by every T3 server on this
+ * host. Two servers must never run `npm i -g` on the same prefix at once, and
+ * a CLI must not be replaced while another server is launching it.
+ */
+export class ProviderInstallLock extends Context.Service<
+  ProviderInstallLock,
+  {
+    /**
+     * Runs `run` while holding the lock for `lockKey`, or returns `None` without
+     * running when another process holds it. `run` calls `recordChildPid` with the
+     * installer's pid: a detached installer outlives this server, and the lock
+     * stays held until it exits.
+     */
+    readonly tryRun: <A, E, R>(
+      lockKey: string,
+      run: (recordChildPid: (pid: number) => Effect.Effect<void>) => Effect.Effect<A, E, R>,
+    ) => Effect.Effect<Option.Option<A>, E | ProviderInstallLockError, R>;
+    /** Completes once no installer holds any lock, or when the lock directory cannot be read. */
+    readonly untilIdle: Effect.Effect<void>;
+    /** Whether any lock is held right now. A failed read is an error, not "free". */
+    readonly anyHeld: Effect.Effect<boolean, ProviderInstallLockError>;
+  }
+>()("t3/provider/ProviderInstallLock") {}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    // EPERM: the process exists but belongs to someone else.
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+const make = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const environment = yield* HostProcess.Environment;
+  const homeDirectory = yield* HostProcess.HomeDirectory;
+  const cacheHome = environment.XDG_CACHE_HOME || path.join(homeDirectory, ".cache");
+  const directory = path.join(cacheHome, "t3", "provider-install");
+
+  const toLockError = (cause: unknown) => new ProviderInstallLockError({ cause });
+  const ignoreNotFound =
+    <B>(fallback: B) =>
+    <A>(effect: Effect.Effect<A, PlatformError>): Effect.Effect<A | B, PlatformError> =>
+      effect.pipe(
+        Effect.catchTags({
+          PlatformError: (error) =>
+            error.reason._tag === "NotFound" ? Effect.succeed(fallback) : Effect.fail(error),
+        }),
+      );
+
+  /** Held while a recorded process is alive; a file mid-write counts as held until it ages out. */
+  const isHeld = Effect.fn("ProviderInstallLock.isHeld")(function* (file: string) {
+    const info = yield* fileSystem.stat(file);
+    const modifiedAt = Option.match(info.mtime, {
+      onNone: () => 0,
+      onSome: (date) => date.getTime(),
+    });
+    if ((yield* Clock.currentTimeMillis) - modifiedAt >= Duration.toMillis(MAX_LOCK_AGE)) {
+      return false;
+    }
+    // The file holds one pid: this server's, then its installer's once spawned.
+    const pid = Number.parseInt(yield* fileSystem.readFileString(file), 10);
+    return Number.isNaN(pid) || isPidAlive(pid);
+  });
+
+  const writePid = (file: string, pid: number, flag: "w" | "wx") =>
+    fileSystem.writeFileString(file, String(pid), { flag });
+
+  /** Creates `file` exclusively; false when it already exists. */
+  const createExclusively = (file: string) =>
+    writePid(file, process.pid, "wx").pipe(
+      Effect.as(true),
+      Effect.catchTags({
+        PlatformError: (error) =>
+          error.reason._tag === "AlreadyExists" ? Effect.succeed(false) : Effect.fail(error),
+      }),
+    );
+
+  /** Takes the short-lived sentinel that serializes reclaimers; one left by a crashed process is removed. */
+  const claimSentinel = Effect.fn("ProviderInstallLock.claimSentinel")(function* (
+    sentinel: string,
+  ) {
+    if (yield* createExclusively(sentinel)) return true;
+    const info = yield* fileSystem.stat(sentinel).pipe(ignoreNotFound(undefined));
+    if (info !== undefined) {
+      const modifiedAt = Option.match(info.mtime, {
+        onNone: () => 0,
+        onSome: (date) => date.getTime(),
+      });
+      if ((yield* Clock.currentTimeMillis) - modifiedAt < Duration.toMillis(MAX_SENTINEL_AGE)) {
+        return false;
+      }
+      yield* fileSystem.remove(sentinel, { force: true });

@@ -564,6 +567,19 @@ function needsRecovery(
         )
       );
     }
+    case "active-work":
+      return (
+        projection.runs.some(
+          (run) =>
+            ["preparing", "starting", "running", "waiting"].includes(run.status) ||
+            (run.status === "queued" && run.queueHeld !== true),
+        ) ||
+        projection.runtimeRequests.some((request) => request.status === "pending") ||
+        projection.providerThreads.some(
+          (thread) =>
+            thread.status === "active" || (thread.pendingBackgroundTasks?.length ?? 0) > 0,

@@ -478,20 +581,16 @@ export const resolvePackageManagedProviderMaintenance = Effect.fn(
         `${packageName}@latest`,
       ],
       updateLockKey: `npm-global:${normalizeCommandPath(npmPrefix)}`,
+      installationKey: `${packageName}:${identity(npmPrefix)}`,

@@ -564,6 +567,19 @@ function needsRecovery(
         )
       );
     }
+    case "active-work":
+      return (
+        projection.runs.some(
+          (run) =>
+            ["preparing", "starting", "running", "waiting"].includes(run.status) ||
+            (run.status === "queued" && run.queueHeld !== true),
+        ) ||
+        projection.runtimeRequests.some((request) => request.status === "pending") ||
+        projection.providerThreads.some(
+          (thread) =>
+            thread.status === "active" || (thread.pendingBackgroundTasks?.length ?? 0) > 0,

@@ -56,21 +57,27 @@ const resolveInstance = (
 export const make = Effect.gen(function* () {
   const registry = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
   const sourceControl = yield* SourceControlProviderRegistry.SourceControlProviderRegistry;
+  const admission = yield* ProviderMaintenanceCoordinator.ProviderMaintenanceAdmission;
+  // Waits out a background install so a provider CLI is never launched mid-replacement.
+  const instanceFor = (operation: TextGenerationOp, instanceId: ProviderInstanceId) =>
+    admission
+      .withPermit(Effect.void)

@@ -1694,6 +1744,50 @@ export const layerWithOptions = (
               modelFamily: normalizeModelMetricLabel(model),
             },
           });
+        const startTurn = (input: Parameters<typeof runtime.startTurn>[0], compact = false) =>
+          observeActivity(
+            providerSessionId,
+            ensureThreadAttached({
+              providerSessionId,
+              threadId: input.threadId,
+              providerInstanceId: runtime.instanceId,
+            }),
+          ).pipe(
+            Effect.andThen(
+              holdThreadLoaded({
+                providerSessionId,
+                threadId: input.threadId,
+                providerThread: input.providerThread,
+              }),
+            ),
+            Effect.andThen(
+              // Failed starts may not emit turn.terminal; clear only their own busy key.
+              Effect.acquireUseRelease(
+                observeActivity(
+                  providerSessionId,
+                  markBusy(
+                    providerSessionId,
+                    busyTurnKey(input.providerThread.id, input.runOrdinal),
+                  ),
+                ),
+                () =>
+                  hostLock.withRead(
+                    (compact ? runtime.compactThread!(input) : runtime.startTurn(input)).pipe(
+                      turnMetrics("send", input.modelSelection.model),
+                    ),
+                    hostLeases.get(runtime),
+                  ),
+                (_, exit) =>
+                  Exit.isFailure(exit)
+                    ? observeActivity(
+                        providerSessionId,
+                        markIdle(providerSessionId, input.providerThread.id, input.runOrdinal),
+                      )
+                    : Effect.void,
+              ),
+            ),
+            hostLock.withRead,

@@ -0,0 +1,397 @@
+// @effect-diagnostics nodeBuiltinImport:off - Host leases coordinate independent Node servers.
+// oxlint-disable t3code/no-global-process-runtime -- Leases belong to the OS user and process, not an environment.
+import * as NodeCrypto from "node:crypto";
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { lock } from "proper-lockfile";
+import * as Context from "effect/Context";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Deferred from "effect/Deferred";
+import * as Semaphore from "effect/Semaphore";
+import * as Maintenance from "@t3tools/provider-core/server/maintenance";
+
+const HeldWrite = Context.Reference<{ readonly owner: object; active: boolean } | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldWrite",
+  { defaultValue: () => null },
+);
+
+interface ReadToken {
+  readonly lease: { readonly owner: object; readonly file: string; users: number };
+  active: boolean;
+}
+const HeldRead = Context.Reference<ReadToken | null>(
+  "t3/provider/ProviderMaintenanceHostLock/HeldRead",
+  { defaultValue: () => null },
+);
+
+const HeldGate = Context.Reference<{
+  readonly handoff: Effect.Effect<void>;
+  readonly resume: Effect.Effect<void>;
+} | null>("t3/provider/ProviderMaintenanceHostLock/HeldGate", { defaultValue: () => null });
+
+// Linux exposes a process start identity, so recycled PIDs cannot pin a dead reader.
+const processIdentity = (pid: number) => {
+  if (NodeOS.platform() !== "linux") return null;
+  const fields = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").at(-1)!.split(" ");
+  return fields[0] === "Z" ? "" : fields[19]!;
+};
+
+export const installLeasePath = (directory: string) => NodePath.join(directory, "install.json");
+
+export const isProcessAlive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return processIdentity(pid) !== "";
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ESRCH" || error.code === "ENOENT")
+    )
+      return false;
+    throw error;
+  }
+};
+
+/** A dead supervisor's installer still owns admission until its entire process group exits. */
+export const installIsAlive = (directory: string): boolean => {
+  const file = installLeasePath(directory);
+  let pid: number;
+  try {
+    pid = Number(NodeFS.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid provider install lease");
+  if (isProcessAlive(pid)) return true;

@@ -0,0 +1,232 @@
+import type { ScheduledTaskId, ThreadId } from "@t3tools/contracts";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Semaphore from "effect/Semaphore";
+
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
+import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
+import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
+import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
+import * as ServerSettings from "../serverSettings.ts";
+
+/** Work due this soon keeps the window closed, so it does not start late. */
+const UPDATE_LOOKAHEAD = Duration.minutes(5);
+/**
+ * Tasks repeating at least this often always have a run due soon. Missed runs
+ * catch up after a restart, so they only block while running.
+ */
+const FREQUENT_TASK_INTERVAL = Duration.minutes(15);
+
+/**
+ * Background update pacing. `T3CODE_UPDATE_LAB=1` (scripts/update-lab.ts)
+ * shortens the waits so update flows can be exercised in seconds.
+ */
+export const updateTimings = Config.Boolean("T3CODE_UPDATE_LAB").pipe(
+  Config.withDefault(false),
+  Config.map((lab) => ({
+    /**
+     * How long every client must be untouched before an update may interrupt
+     * it. Clients report activity about every 25s, so this must stay well above that.
+     */
+    quietPeriod: lab ? Duration.seconds(60) : Duration.minutes(15),
+    /** How often a waiting update rechecks the window or looks for new versions. */
+    recheck: lab ? Duration.seconds(5) : Duration.seconds(30),
+    firstPassDelay: lab ? Duration.seconds(10) : Duration.minutes(2),
+    passInterval: lab ? Duration.seconds(20) : Duration.minutes(10),
+  })),
+);
+
+export type UpdateWindowBlocker =
+  | { readonly type: "active-threads"; readonly threadIds: ReadonlyArray<ThreadId> }
+  | { readonly type: "recent-interaction"; readonly quietAt: DateTime.Utc }
+  | { readonly type: "focused-window" }
+  | { readonly type: "provider-update" }
+  | {
+      readonly type: "scheduled-task";
+      readonly taskId: ScheduledTaskId;
+      readonly title: string;
+      /** Null while the task is running. */
+      readonly runsAt: DateTime.Utc | null;
+    }
+  | {
+      readonly type: "usage-limit-resume";
+      readonly threadId: ThreadId;
+      readonly resumesAt: DateTime.Utc;
+    };
+
+export interface UpdateWindowOptions {
+  /** The update closes the app windows (a desktop install), not just a reconnect. */
+  readonly closesWindows: boolean;
+}
+
+export interface UpdateWindowStatus {
+  readonly open: boolean;
+  readonly blockers: ReadonlyArray<UpdateWindowBlocker>;
+}
+
+/**
+ * Decides when a background update may restart the server, replace a provider
+ * CLI, or relaunch the desktop app without cutting off someone's work.
+ */
+export class UpdateWindow extends Context.Service<
+  UpdateWindow,
+  {
+    readonly check: (options: UpdateWindowOptions) => Effect.Effect<UpdateWindowStatus>;
+    /**
+     * Runs `install` if the window is open, holding a lock every background
+     * install shares, so a server restart never cuts off a CLI install.
+     */
+    readonly runIfOpen: <A, E, R>(
+      options: UpdateWindowOptions,
+      install: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<Option.Option<A>, E, R>;
+    /** Waits for the window, then runs `install` like `runIfOpen`. */
+    readonly runWhenOpen: <A, E, R>(
+      options: UpdateWindowOptions,
+      install: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E, R>;
+  }
+>()("t3/updates/UpdateWindow") {}
+
+export const make = Effect.fn("updates.UpdateWindow.make")(function* () {
+  const projections = yield* ProjectionStore.ProjectionStoreV2;
+  const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
+  const scheduledTasks = yield* ScheduledTaskService.ScheduledTaskService;
+  const serverSettings = yield* ServerSettings.ServerSettingsService;
+  const providers = yield* ProviderRegistry.ProviderRegistry;
+  const timings = yield* updateTimings;
+
+  const check: UpdateWindow["Service"]["check"] = Effect.fn("updates.UpdateWindow.check")(
+    function* (options) {
+      const now = yield* DateTime.now;
+      const horizon = DateTime.addDuration(now, UPDATE_LOOKAHEAD);
+      const blockers: Array<UpdateWindowBlocker> = [];
+
+      // A failed read keeps the window closed: guessing "idle" could cut off a turn.
+      const activeThreadIds = yield* projections.getRecoveryThreadIds("active-work").pipe(
+        Effect.tapError((cause) =>
+          Effect.logWarning("Update window could not read threads", { cause }),
+        ),
+        Effect.option,
+      );
+      if (Option.isNone(activeThreadIds)) {
+        return { open: false, blockers: [{ type: "active-threads", threadIds: [] }] };
+      }
+      if (activeThreadIds.value.length > 0) {
+        blockers.push({ type: "active-threads", threadIds: activeThreadIds.value });
+      }
+
+      // Includes installs someone started by hand.
+      const providerUpdating = (yield* providers.getProviders).some(
+        (provider) =>
+          provider.updateState?.status === "queued" || provider.updateState?.status === "running",
+      );
+      if (providerUpdating) {
+        blockers.push({ type: "provider-update" });
+      }
+
+      const lastInteraction = yield* backgroundPolicy.lastClientInteractionAt;
+      if (Option.isSome(lastInteraction)) {
+        const quietAt = DateTime.addDuration(lastInteraction.value, timings.quietPeriod);
+        if (DateTime.isGreaterThan(quietAt, now)) {
+          blockers.push({ type: "recent-interaction", quietAt });
+        }
+      }
+
+      if (options.closesWindows) {
+        const policy = yield* backgroundPolicy.snapshot;
+        const hostIdleSeconds = policy.hostPower.stale ? null : policy.hostPower.idleSeconds;
+        const hostAway =
+          hostIdleSeconds !== null && hostIdleSeconds >= Duration.toSeconds(timings.quietPeriod);
+        const windowFocused = policy.leases.some(
+          (lease) => lease.clientKind === "desktop-renderer" && lease.focused,
+        );
+        if (windowFocused && !hostAway) {
+          blockers.push({ type: "focused-window" });
+        }
+      }
+
+      const tasks = yield* scheduledTasks.list().pipe(
+        Effect.tapError((cause) =>
+          Effect.logWarning("Update window could not read scheduled tasks", { cause }),
+        ),
+        Effect.option,
+      );
+      if (Option.isNone(tasks)) {
+        return { open: false, blockers };
+      }
+      for (const task of tasks.value.tasks) {
+        if (task.lastRunStatus === "running") {
+          blockers.push({
+            type: "scheduled-task",
+            taskId: task.id,
+            title: task.title,
+            runsAt: null,
+          });
+          continue;
+        }
+        if (!task.enabled || task.nextRunAt === null) continue;
+        if (
+          task.schedule.type === "interval" &&
+          task.schedule.everyMs < Duration.toMillis(FREQUENT_TASK_INTERVAL)
+        ) {
+          continue;
+        }

@@ -2800,6 +2809,38 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          serverScoped
+          settingKeys={["automaticUpdates"]}
+          {...searchableSetting("automatic-updates")}
+          description="Install updates for provider CLIs that support one-click updates in the background on the selected environments while nothing is running."
+          status={
+            !supportsAutomaticUpdates
+              ? "All selected connected environments must support automatic updates."
+              : undefined
+          }
+          resetAction={
+            supportsAutomaticUpdates &&
+            settings.automaticUpdates !== DEFAULT_UNIFIED_SETTINGS.automaticUpdates ? (
+              <SettingResetButton
+                label="automatic updates"
+                onClick={() =>
+                  updateSettings({ automaticUpdates: DEFAULT_UNIFIED_SETTINGS.automaticUpdates })
+                }
+              />
+            ) : null
+          }
+          control={
+            <ScopedSwitch
+              settingKeys={["automaticUpdates"]}
+              checked={settings.automaticUpdates}
+              disabled={!supportsAutomaticUpdates}

@@ -242,6 +252,16 @@ export function ProviderUpdatePrimaryNotification() {
       void (async () => {
         const results = [];
         for (const provider of oneClickProviders) {
+          const current = latestProvidersRef.current.find(
+            (candidate) => candidate.instanceId === provider.instanceId,
+          );
+          if (
+            !current ||
+            !isProviderUpdateCandidate(current) ||
+            !canOneClickUpdateProviderCandidate(current, latestProvidersRef.current)
+          ) {
+            continue;

@@ -0,0 +1,381 @@
+// @effect-diagnostics nodeBuiltinImport:off globalTimers:off globalDate:off preferSchemaOverJson:off - Detached runtime boundary; receipts survive their server.
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import * as NodeCrypto from "node:crypto";
+import * as Context from "effect/Context";
+import * as Clock from "effect/Clock";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { resolveSelfInvocation, selfInvocationArgs } from "@t3tools/shared/nodeRuntime";
+import { ProviderDriverKind, ProviderInstanceId } from "@t3tools/contracts";
+import * as ServerConfig from "../config.ts";
+import * as HostLock from "./ProviderMaintenanceHostLock.ts";
+import type { ProviderMaintenanceCommandResult } from "./providerMaintenanceRunner.ts";
+
+const Result = Schema.Struct({
+  stdout: Schema.String,
+  stderr: Schema.String,
+  exitCode: Schema.NullOr(Schema.Number),
+  timedOut: Schema.Boolean,
+  stdoutTruncated: Schema.Boolean,
+  stderrTruncated: Schema.Boolean,
+});
+const Receipt = Schema.Struct({
+  id: Schema.String,
+  provider: ProviderDriverKind,
+  instanceId: ProviderInstanceId,
+  instanceIds: Schema.Array(ProviderInstanceId),
+  origin: Schema.optional(Schema.Literals(["manual", "background"])),
+  targetVersion: Schema.optional(Schema.String),
+  exactVersion: Schema.optional(Schema.Boolean),
+  startedAt: Schema.String,
+  finishedAt: Schema.optional(Schema.String),
+  command: Schema.String,
+  args: Schema.Array(Schema.String),
+  env: Schema.optional(Schema.Record(Schema.String, Schema.UndefinedOr(Schema.String))),
+  parentPid: Schema.Number,
+  parentIdentity: Schema.optional(Schema.NullOr(Schema.String)),
+  directory: Schema.String,
+  pid: Schema.optional(Schema.Number),
+  progress: Schema.optional(Schema.String),
+  result: Schema.optional(Result),
+});
+export type InstallReceipt = typeof Receipt.Type;
+const decodeReceipt = Schema.decodeSync(Schema.fromJsonString(Receipt));
+export const readReceipt = (file: string) => decodeReceipt(NodeFS.readFileSync(file, "utf8"));
+const writeReceipt = (file: string, receipt: InstallReceipt) => {
+  const temp = `${file}.${process.pid}.tmp`;
+  NodeFS.writeFileSync(temp, JSON.stringify(receipt), { mode: 0o600 });
+  NodeFS.renameSync(temp, file);
+};
+
+type InstallInput = Pick<
+  InstallReceipt,
+  | "provider"
+  | "instanceId"
+  | "instanceIds"
+  | "origin"
+  | "targetVersion"
+  | "exactVersion"
+  | "startedAt"
+  | "command"
+  | "args"
+  | "env"
+> & {
+  readonly onProgress?: (line: string) => Effect.Effect<void>;
+};
+
+export class ProviderInstallError extends Data.TaggedError("ProviderInstallError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+const installError = (cause: unknown) =>
+  new ProviderInstallError({
+    message: cause instanceof Error ? cause.message : "Provider installer could not run.",
+    cause,
+  });
+
+export class ProviderInstallSupervisor extends Context.Service<
+  ProviderInstallSupervisor,
+  {
+    readonly run: (
+      input: InstallInput,
+    ) => Effect.Effect<ProviderMaintenanceCommandResult, ProviderInstallError>;
+    readonly receipts: Effect.Effect<ReadonlyArray<InstallReceipt>, ProviderInstallError>;
+  }
+>()("t3/provider/ProviderInstallSupervisor") {}
+
+export const layer = Layer.effect(
+  ProviderInstallSupervisor,
+  Effect.gen(function* () {
+    const config = yield* ServerConfig.ServerConfig;
+    const host = yield* HostLock.ProviderMaintenanceHostLock;
+    const invocation = yield* resolveSelfInvocation();
+    const root = NodePath.join(config.stateDir, "provider-updates");
+    const run: ProviderInstallSupervisor["Service"]["run"] = Effect.fn(
+      "ProviderInstallSupervisor.run",
+    )(function* (input) {
+      const file = NodePath.join(root, `${encodeURIComponent(input.instanceId)}.json`);
+      const receipt: InstallReceipt = {
+        ...input,
+        id: NodeCrypto.randomUUID(),
+        parentPid: process.pid,
+        parentIdentity: HostLock.readProcessIdentity(process.pid),
+        directory: host.directory,
+      };
+      yield* Effect.try(() => {
+        NodeFS.mkdirSync(root, { recursive: true, mode: 0o700 });
+        NodeFS.rmSync(`${file}.start`, { force: true });
+        writeReceipt(file, receipt);
+      });
+      yield* Effect.tryPromise(
+        () =>
+          new Promise<void>((resolve, reject) => {
+            // The relay exits before the supervisor starts the installer. On Windows,
+            // detached alone does not remove a process from taskkill /t's parent tree.
+            const relay = NodeChildProcess.spawn(
+              invocation.command,
+              [...selfInvocationArgs(invocation, ["__provider-install-relay", file])],
+              {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+                env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
+              },
+            );
+            relay.once("error", reject);
+            relay.once("spawn", () => {
+              relay.unref();
+              resolve();
+            });
+          }),
+      );
+      const readCurrent = Effect.try(() => {
+        const current = readReceipt(file);
+        if (current.id !== receipt.id)
+          throw new ProviderInstallError({ message: "Provider install receipt replaced." });
+        return current;
+      });
+      const deadline = (yield* Clock.currentTimeMillis) + 30_000;
+      while (true) {
+        const current = yield* readCurrent;
+        if (current.result) return current.result;
+        if (current.pid !== undefined) break;
+        if ((yield* Clock.currentTimeMillis) >= deadline)
+          return yield* Effect.fail(
+            new ProviderInstallError({ message: "Provider install supervisor did not start." }),
+          );
+        yield* Effect.sleep("100 millis");
+      }
+      return yield* host.handoff(
+        Effect.gen(function* () {
+          let started = false;
+          let progress: string | undefined;
+          while (true) {
+            const current = yield* readCurrent;
+            if (current.result) return current.result;
+            if (current.pid !== undefined && !started) {
+              // Only acknowledge after the durable lease is visible. A server dying
+              // before this write cannot authorize a late installer to start.
+              yield* Effect.try(() =>
+                NodeFS.writeFileSync(`${file}.start`, receipt.id, { mode: 0o600 }),
+              );
+              started = true;
+            }
+            if (current.progress && current.progress !== progress) {
+              progress = current.progress;
+              if (input.onProgress) yield* input.onProgress(progress);
+            }
+            if (!started && (yield* Clock.currentTimeMillis) >= deadline)
+              return yield* Effect.fail(
+                new ProviderInstallError({ message: "Provider install supervisor did not start." }),
+              );
+            if (started && !(yield* Effect.sync(() => HostLock.installIsAlive(host.directory)))) {
+              return yield* Effect.fail(
+                new ProviderInstallError({
+                  message: "Provider install supervisor exited without a result.",
+                }),
+              );
+            }