feat(server): background services update themselves#17586

@@ -73,6 +77,7 @@ const make = Effect.fn("updates.UpdateWindow.make")(function* () {
         provider.updateState?.status === "queued" || provider.updateState?.status === "running",
     );
     if (providerUpdating) found.push("provider-update");
+    if (restartsServer && (yield* terminals.hasBusyTerminals)) found.push("terminal-work");

@@ -561,6 +596,22 @@ export class Launcher {
     child.role = "active";
     await discardDatabaseBackup(this.#baseDir, committed.id).catch(() => undefined);
     await sendMessage(child.process, { type: "committed", updateId: committed.id });
+    await this.#pruneRuntimes();
+  }
+
+  async #pruneRuntimes(): Promise<void> {
+    try {
+      // The unit's ExecStart names a specific runtime/versions/<v>/t3.
+      const executableDir = NodePath.dirname(await NodeFSP.realpath(process.execPath));
+      const versionsDir = NodePath.join(this.#baseDir, "runtime", "versions");

@@ -380,6 +385,34 @@ async function runtimeExists(baseDir: string, version: string): Promise<boolean>
   }
 }
 
+/**
+ * Removes completed runtimes nothing can return to, so unattended updates do
+ * not fill the disk. The launcher's own version stays because the service unit
+ * names that executable; the active version, the version an update came from,
+ * and a pending target stay because recovery may start them.
+ */
+export async function pruneServiceRuntimes(
+  baseDir: string,
+  state: ServiceState,
+  launcherVersion: string | undefined,
+): Promise<void> {
+  const keep = new Set([state.activeVersion]);
+  if (launcherVersion !== undefined) keep.add(launcherVersion);
+  if (state.update !== undefined) {
+    keep.add(state.update.fromVersion);
+    if (state.update.status === "pending") keep.add(state.update.targetVersion);
+  }
+  const versionsDir = NodePath.join(baseDir, "runtime", "versions");
+  for (const entry of await NodeFSP.readdir(versionsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !isExactServiceVersion(entry.name) || keep.has(entry.name)) {
+      continue;
+    }
+    // An incomplete directory is a staging in progress, not an old runtime.
+    if (!(await runtimeExists(baseDir, entry.name))) continue;
+    await NodeFSP.rm(NodePath.join(versionsDir, entry.name), { recursive: true, force: true });

@@ -0,0 +1,158 @@
+import { ORCHESTRATION_PROTOCOL_VERSION } from "@t3tools/contracts";
+import { CLI_RELEASE_BASE_URL_ENV, cliReleaseChannelOf } from "@t3tools/shared/cliRelease";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/http";
+
+import packageJson from "../../package.json" with { type: "json" };
+import { resolveNewestVersion } from "../cli/update.ts";
+import * as ServerSelfUpdate from "../cloud/selfUpdate.ts";
+import * as ServerConfig from "../config.ts";
+import * as ServiceLauncherClient from "../cloud/serviceLauncherClient.ts";
+import { compareExactServiceVersions } from "../cloud/serviceProtocol.ts";
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+import { forkParked } from "../serverActivation.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as UpdateWindow from "./UpdateWindow.ts";
+
+/**
+ * Updates this environment in the background when `automaticUpdates` is on.
+ *
+ * - Background service installs stage the newest release on their channel,
+ *   then hand off to the launcher once the update window opens.
+ * - Desktop-hosted servers wait for the app to finish its background
+ *   download, then relaunch it through the existing prepare/commit handoff
+ *   once no window is in use.
+ * - Foreground and `npx` servers cannot replace themselves and are skipped.
+ */
+export const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    // A dev server must not relaunch the desktop app or service it runs beside.
+    if ((yield* ServerConfig.ServerConfig).devUrl !== undefined) return;
+    const selfUpdate = yield* ServerSelfUpdate.ServerSelfUpdate;
+    const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+    const receiver = yield* DesktopTelemetryReceiver.DesktopTelemetryReceiver;
+    const updateWindow = yield* UpdateWindow.UpdateWindow;
+    const serverSettings = yield* ServerSettings.ServerSettingsService;
+    const timings = yield* UpdateWindow.updateTimings;
+    const httpClient = yield* HttpClient.HttpClient;
+    // Same mirror the staged download uses, so a mirror lists what it serves.
+    const releaseBaseUrl = Option.getOrUndefined(
+      yield* Config.String(CLI_RELEASE_BASE_URL_ENV).pipe(Config.option),
+    );
+    const currentVersion = packageJson.version;
+    // Targets this process already gave up on; the launcher remembers rollbacks across restarts.
+    const skippedTargets = new Set<string>();
+    if (launcher.lastOutcome !== undefined && launcher.lastOutcome.status !== "committed") {
+      skippedTargets.add(launcher.lastOutcome.targetVersion);
+    }
+
+    const automaticUpdatesEnabled = serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.automaticUpdates),
+      Effect.orElseSucceed(() => false),
+    );
+
+    const updateBootService = Effect.gen(function* () {
+      if (!(yield* automaticUpdatesEnabled)) return;
+      const targetVersion = yield* resolveNewestVersion(
+        cliReleaseChannelOf(currentVersion),
+        releaseBaseUrl,
+      ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient));
+      if (
+        compareExactServiceVersions(targetVersion, currentVersion) <= 0 ||
+        skippedTargets.has(targetVersion)
+      ) {
+        return;
+      }
+      yield* Effect.logInfo("Staging a background server update", { targetVersion });
+      const staged = yield* selfUpdate.stage(targetVersion);
+      if (
+        staged.orchestrationProtocol !== undefined &&
+        staged.orchestrationProtocol !== ORCHESTRATION_PROTOCOL_VERSION
+      ) {
+        // Connected clients would be refused until they update; leave this one to a person.
+        skippedTargets.add(targetVersion);
+        yield* Effect.logInfo("Skipping a background update that changes the client protocol", {
+          targetVersion,
+        });
+        return;
+      }
+      yield* updateWindow.runWhenOpen(
+        { closesWindows: false },
+        Effect.gen(function* () {
+          // The setting may have been turned off while waiting.
+          if (!(yield* automaticUpdatesEnabled)) return;
+          skippedTargets.add(targetVersion);
+          yield* Effect.logInfo("Installing a background server update", { targetVersion });
+          yield* selfUpdate.update({ targetVersion });
+        }),
+      );

@@ -0,0 +1,453 @@
+// @effect-diagnostics nodeBuiltinImport:off globalTimers:off preferSchemaOverJson:off -- Standalone launcher shares this Node-only process ownership core.
+import * as NodeChildProcess from "node:child_process";
+import * as NodeCrypto from "node:crypto";
+import * as NodeFS from "node:fs";
+import * as NodeFSP from "node:fs/promises";
+import * as NodePath from "node:path";
+import * as NodeUtil from "node:util";
+
+const execFile = NodeUtil.promisify(NodeChildProcess.execFile);
+
+interface Identity {
+  readonly pid: number;
+  readonly startTime: string;
+}
+interface OwnedProcess extends Identity {
+  readonly pgid: number;
+}
+interface Entry {
+  readonly version: 1;
+  readonly instanceId: string;
+  readonly hostname: string;
+  readonly stateDir: string;
+  readonly owner: Identity;
+  readonly processes: ReadonlyArray<OwnedProcess>;
+}
+interface ObservedProcess extends OwnedProcess {
+  readonly ppid: number;
+  readonly zombie: boolean;
+}
+export interface ProcessController {
+  readonly snapshot: () => ReadonlyArray<ObservedProcess> | Promise<ReadonlyArray<ObservedProcess>>;
+  readonly identity?: (pid: number) => ObservedProcess | undefined;
+  readonly signal: (pid: number, signal: NodeJS.Signals) => void;
+  readonly exists: (pid: number) => boolean;
+}
+const same = (a: Identity, b: Identity) => a.pid === b.pid && a.startTime === b.startTime;
+const object = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+const identity = (value: unknown): value is Identity =>
+  object(value) &&
+  Number.isSafeInteger(value.pid) &&
+  Number(value.pid) > 0 &&
+  typeof value.startTime === "string" &&
+  value.startTime.length > 0;
+const owned = (value: unknown): value is OwnedProcess =>
+  identity(value) && "pgid" in value && Number.isSafeInteger(value.pgid);
+function decodeEntry(text: string): Entry {
+  const value: unknown = JSON.parse(text);
+  if (
+    !object(value) ||
+    value.version !== 1 ||
+    typeof value.instanceId !== "string" ||
+    !value.instanceId ||
+    typeof value.hostname !== "string" ||
+    typeof value.stateDir !== "string" ||
+    !identity(value.owner) ||
+    !Array.isArray(value.processes) ||
+    !value.processes.every(owned)
+  )
+    throw new Error("Invalid provider process record");
+  return value as unknown as Entry;
+}
+function decodeProcessTable(value: unknown): ReadonlyArray<ObservedProcess> {
+  if (
+    !Array.isArray(value) ||
+    !value.every(
+      (p: unknown) =>
+        owned(p) &&
+        "ppid" in p &&
+        Number.isSafeInteger(p.ppid) &&
+        "zombie" in p &&
+        typeof p.zombie === "boolean",
+    )
+  )
+    throw new Error("Invalid process table");
+  return value as ReadonlyArray<ObservedProcess>;
+}
+
+/** Linux boot/start ticks, macOS ps and Windows CIM supply creation identities. */
+function controllerFor(
+  platform: NodeJS.Platform,
+  environment: NodeJS.ProcessEnv,
+): ProcessController {
+  const boot =
+    platform === "linux"
+      ? NodeFS.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()
+      : "";
+  const parseLinux = (pid: number, stat: string): ObservedProcess => {
+    const fields = stat.slice(stat.lastIndexOf(") ") + 2).split(" ");
+    return {
+      pid,
+      ppid: Number(fields[1]),
+      pgid: Number(fields[2]),
+      startTime: `${boot}:${fields[19]}`,
+      zombie: fields[0] === "Z" || fields[0] === "X",
+    };
+  };
+  return {
+    ...(platform === "linux"
+      ? {
+          identity: (pid: number) => {
+            try {
+              return parseLinux(pid, NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8"));
+            } catch {
+              return undefined;
+            }
+          },
+        }
+      : {}),
+    snapshot: async () => {
+      if (platform === "linux") {
+        const pids = (await NodeFSP.readdir("/proc")).filter((name) => /^[1-9][0-9]*$/.test(name));
+        const table: Array<ObservedProcess> = [];
+        // Bound concurrent reads without blocking the server on the whole process table.
+        for (let offset = 0; offset < pids.length; offset += 32) {
+          const rows = await Promise.all(
+            pids.slice(offset, offset + 32).map(async (name) => {
+              try {
+                return parseLinux(
+                  Number(name),
+                  await NodeFSP.readFile(`/proc/${name}/stat`, "utf8"),
+                );
+              } catch {
+                return undefined;
+              }
+            }),
+          );
+          for (const row of rows) if (row) table.push(row);
+        }
+        return table;
+      }
+      if (platform === "darwin") {
+        const { stdout: output } = await execFile(
+          "/bin/ps",
+          ["-axo", "pid=,ppid=,pgid=,stat=,lstart="],
+          {
+            encoding: "utf8",
+            timeout: 5_000,
+            maxBuffer: 8 * 1024 * 1024,
+            env: { ...environment, LC_ALL: "C", TZ: "UTC" },
+          },
+        );
+        return output.split("\n").flatMap((line) => {
+          const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+          return match
+            ? [
+                {
+                  pid: Number(match[1]),
+                  ppid: Number(match[2]),
+                  pgid: Number(match[3]),
+                  zombie: match[4]!.startsWith("Z"),
+                  startTime: match[5]!,
+                },
+              ]
+            : [];
+        });
+      }
+      if (platform === "win32") {
+        const { stdout: output } = await execFile(
+          "powershell.exe",
+          [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "$ErrorActionPreference='Stop'; @(Get-CimInstance Win32_Process | Where-Object { $_.CreationDate -and $_.ProcessId -gt 0 } | ForEach-Object { @{pid=[int]$_.ProcessId; ppid=[int]$_.ParentProcessId; pgid=0; startTime=$_.CreationDate.ToUniversalTime().Ticks.ToString(); zombie=$false} }) | ConvertTo-Json -Compress",
+          ],
+          {
+            encoding: "utf8",
+            timeout: 10_000,
+            windowsHide: true,
+            maxBuffer: 8 * 1024 * 1024,
+            env: environment,
+          },
+        );
+        return decodeProcessTable(JSON.parse(output));
+      }
+      throw new Error(`Provider process ownership is unsupported on ${platform}`);
+    },
+    signal: (pid, signal) => {
+      process.kill(pid, signal);
+    },
+    exists: (pid) => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch (cause) {
+        return (cause as NodeJS.ErrnoException).code !== "ESRCH";
+      }
+    },
+  };
+}
+
+function creationTime(identity: Identity): bigint | undefined {
+  const ticks = identity.startTime.split(":").at(-1)!;
+  if (/^\d+$/.test(ticks)) return BigInt(ticks);
+  const parsed = Date.parse(`${identity.startTime} UTC`);
+  return Number.isFinite(parsed) ? BigInt(parsed) : undefined;
+}
+
+/** Admits descendants only through a live, matching identity, or its still-owned private process group. */
+function discover(entry: Entry, table: ReadonlyArray<ObservedProcess>): Entry {
+  const found = new Map(entry.processes.map((p) => [`${p.pid}:${p.startTime}`, p]));
+  const live = table.filter((p) => !p.zombie && entry.processes.some((owned) => same(owned, p)));
+  const groups = new Set(
+    live
+      .filter(
+        (p) =>
+          p.pgid > 0 && entry.processes.some((owned) => owned.pgid > 0 && owned.pgid === p.pgid),
+      )
+      .map((p) => p.pgid),
+  );
+  const parents = new Map(live.map((p) => [p.pid, p]));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const p of table) {
+      if (p.zombie || found.has(`${p.pid}:${p.startTime}`)) continue;
+      const parent = parents.get(p.ppid);
+      const parentBirth = parent ? creationTime(parent) : undefined;
+      const childBirth = creationTime(p);
+      const childOfParent =
+        parent !== undefined &&
+        (parentBirth === undefined || childBirth === undefined || childBirth >= parentBirth);
+      if (!childOfParent && !groups.has(p.pgid)) continue;
+      found.set(`${p.pid}:${p.startTime}`, {
+        pid: p.pid,
+        startTime: p.startTime,
+        pgid: groups.has(p.pgid) ? p.pgid : 0,
+      });
+      parents.set(p.pid, p);
+      changed = true;
+    }
+  }
+  return { ...entry, processes: [...found.values()] };
+}
+
+/** Node-only core shared with the launcher, including older-runtime fallback. */
+export async function make(input: {
+  readonly stateDir: string;
+  readonly ownerPid?: number;
+  readonly controller?: ProcessController;
+  readonly installLeaseDirectory?: string;
+  readonly platform: NodeJS.Platform;
+  readonly environment: NodeJS.ProcessEnv;
+  readonly hostname: string;
+}) {
+  const { platform, environment, hostname } = input;
+  const controller = input.controller ?? controllerFor(platform, environment);
+  const directory = NodePath.join(input.stateDir, "provider-processes");
+  NodeFS.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const ownerPid = input.ownerPid ?? process.pid;
+  const owner = (await controller.snapshot()).find((p) => p.pid === ownerPid && !p.zombie);
+  if (!owner) throw new Error("Could not identify the provider process owner");
+  const instanceId = NodeCrypto.randomUUID();
+  const tracked = new Map<string, Entry>();
+  const write = (file: string, entry: Entry) => {
+    const temporary = `${file}.tmp`;
+    NodeFS.writeFileSync(temporary, JSON.stringify(entry), { mode: 0o600 });
+    NodeFS.renameSync(temporary, file);
+  };
+  const survivors = (entry: Entry, table: ReadonlyArray<ObservedProcess>) =>
+    table.filter((p) => !p.zombie && entry.processes.some((owned) => same(owned, p)));
+  const refresh = async () => {
+    if (tracked.size === 0) return;
+    const table = await controller.snapshot();
+    for (const [file, entry] of tracked) {
+      const discovered = discover(entry, table);
+      const next = {
+        ...discovered,
+        processes: discovered.processes.filter(
+          (p) =>
+            table.some((observed) => same(p, observed) && !observed.zombie) ||
+            (!table.some((observed) => observed.pid === p.pid) && controller.exists(p.pid)),
+        ),
+      };
+      if (next.processes.length === 0) {
+        NodeFS.rmSync(file, { force: true });
+        tracked.delete(file);
+      } else if (JSON.stringify(next.processes) !== JSON.stringify(entry.processes)) {
+        write(file, next);
+        tracked.set(file, next);
+      }
+    }
+  };
+  const signal = async (p: Identity, signal: NodeJS.Signals) => {
+    // Refresh immediately before each signal, including escalation. Never signal by group id or taskkill /t.
+    const observed = controller.identity
+      ? controller.identity(p.pid)
+      : (await controller.snapshot()).find((candidate) => candidate.pid === p.pid);
+    if (!observed || observed.zombie || !same(p, observed)) return;
+    try {
+      controller.signal(p.pid, signal);
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "ESRCH") throw cause;
+    }
+  };
+  // A server started from a provider or terminal can descend from it with its own
+  // detached install supervisor. Stopping that group would corrupt a shared CLI.
+  const withoutInstaller = (entry: Entry, table: ReadonlyArray<ObservedProcess>): Entry => {
+    if (input.installLeaseDirectory === undefined) return entry;
+    let leader: number;
+    try {
+      leader = Number(
+        NodeFS.readFileSync(NodePath.join(input.installLeaseDirectory, "install.json"), "utf8"),
+      );
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code === "ENOENT") return entry;
+      throw cause;
+    }
+    if (!Number.isSafeInteger(leader) || leader <= 0)
+      throw new Error("Invalid provider install lease");
+    // Windows has no process groups, so its installer is found through parents.
+    const installer = new Set([leader]);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const p of table) {
+        if (!installer.has(p.pid) && (p.pgid === leader || installer.has(p.ppid))) {
+          installer.add(p.pid);
+          changed = true;
+        }
+      }
+    }
+    return {
+      ...entry,
+      processes: entry.processes.filter(
+        (p) => !table.some((observed) => installer.has(observed.pid) && same(p, observed)),
+      ),
+    };
+  };
+  const reap = async (file: string, entry: Entry) => {
+    let table = await controller.snapshot();
+    const liveOwner = table.find((p) => same(entry.owner, p));
+    if (liveOwner && !liveOwner.zombie) return;
+    // A restricted/failed process query cannot establish that an owner died.
+    if (
+      !liveOwner &&
+      !table.some((p) => p.pid === entry.owner.pid) &&
+      controller.exists(entry.owner.pid)
+    ) {
+      throw new Error("Could not verify the recorded provider owner");
+    }
+    let next = withoutInstaller(discover(entry, table), table);
+    if (platform !== "win32") {
+      // Freeze to a fixed point. A child may fork while its parent is being stopped.
+      const stopped = new Set<string>();
+      for (let attempt = 0; attempt < 100; attempt++) {
+        const pending = survivors(next, table).filter(
+          (p) => !stopped.has(`${p.pid}:${p.startTime}`),
+        );
+        if (pending.length === 0) break;
+        for (const p of pending) {
+          await signal(p, "SIGSTOP");
+          stopped.add(`${p.pid}:${p.startTime}`);
+        }
+        table = await controller.snapshot();
+        next = withoutInstaller(discover(next, table), table);
+        if (attempt === 99) throw new Error("Provider process tree did not stop for cleanup");
+      }
+    }
+    // Persist newly discovered children before signalling: recovery can itself be killed.
+    write(file, next);

@@ -3175,6 +3178,16 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       ),
     );
 
+  const hasBusyTerminals: TerminalManager["Service"]["hasBusyTerminals"] = readManagerState.pipe(
+    Effect.map((state) =>
+      [...state.sessions.values()].some(
+        (session) =>
+          session.status === "starting" ||
+          (session.status === "running" && session.hasRunningSubprocess),

@@ -772,7 +826,19 @@ export class Launcher {
       await this.#startTrial(pending);
       return;
     }
-    throw new Error(`Active child exited unexpectedly (${String(code ?? signal ?? "unknown")}).`);
+    // Restart in-process so systemd's start limit cannot strand an unattended
+    // service behind a crashing release.
+    if (performance.now() - child.startedAt >= STABLE_RUN_MS) {
+      this.#crashDelayMs = CRASH_RESTART_BASE_MS;
+    }
+    const delay = this.#crashDelayMs;
+    this.#crashDelayMs = Math.min(delay * 2, CRASH_RESTART_MAX_MS);
+    this.#timer = setTimeout(() => {

@@ -2951,29 +2982,34 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
     );
   };
 
-  const write: TerminalManager["Service"]["write"] = Effect.fn("terminal.write")(function* (input) {
-    const terminalId = input.terminalId;
-    const session = yield* requireSession(input.threadId, terminalId);
-    const process = session.process;
-    if (!process || session.status !== "running") {
-      if (session.status === "exited") return;
-      return yield* new TerminalNotRunningError({
-        threadId: input.threadId,
-        terminalId,
-      });
-    }
-    session.inputCount += 1;
-    yield* Effect.try({
-      try: () => process.write(input.data),
-      catch: (cause) =>
-        new TerminalWriteError({
+  const writeUnlocked: TerminalManager["Service"]["write"] = Effect.fn("terminal.write")(
+    function* (input) {
+      const terminalId = input.terminalId;
+      const session = yield* requireSession(input.threadId, terminalId);
+      const process = session.process;
+      if (!process || session.status !== "running") {
+        if (session.status === "exited") return;
+        return yield* new TerminalNotRunningError({
           threadId: input.threadId,
           terminalId,
-          terminalPid: process.pid,
-          cause,
-        }),
-    });
-  });
+        });
+      }
+      session.inputCount += 1;
+      yield* Effect.try({
+        try: () => process.write(input.data),
+        catch: (cause) =>
+          new TerminalWriteError({
+            threadId: input.threadId,
+            terminalId,
+            terminalPid: process.pid,
+            cause,
+          }),
+      });
+    },
+  );
+
+  const write: TerminalManager["Service"]["write"] = (input) =>
+    withRestartPermit(writeUnlocked(input));

@@ -0,0 +1,158 @@
+import { ORCHESTRATION_PROTOCOL_VERSION } from "@t3tools/contracts";
+import { CLI_RELEASE_BASE_URL_ENV, cliReleaseChannelOf } from "@t3tools/shared/cliRelease";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/http";
+
+import packageJson from "../../package.json" with { type: "json" };
+import { resolveNewestVersion } from "../cli/update.ts";
+import * as ServerSelfUpdate from "../cloud/selfUpdate.ts";
+import * as ServerConfig from "../config.ts";
+import * as ServiceLauncherClient from "../cloud/serviceLauncherClient.ts";
+import { compareExactServiceVersions } from "../cloud/serviceProtocol.ts";
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+import { forkParked } from "../serverActivation.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as UpdateWindow from "./UpdateWindow.ts";
+
+/**
+ * Updates this environment in the background when `automaticUpdates` is on.
+ *
+ * - Background service installs stage the newest release on their channel,
+ *   then hand off to the launcher once the update window opens.
+ * - Desktop-hosted servers wait for the app to finish its background
+ *   download, then relaunch it through the existing prepare/commit handoff
+ *   once no window is in use.
+ * - Foreground and `npx` servers cannot replace themselves and are skipped.
+ */
+export const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    // A dev server must not relaunch the desktop app or service it runs beside.
+    if ((yield* ServerConfig.ServerConfig).devUrl !== undefined) return;
+    const selfUpdate = yield* ServerSelfUpdate.ServerSelfUpdate;
+    const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+    const receiver = yield* DesktopTelemetryReceiver.DesktopTelemetryReceiver;
+    const updateWindow = yield* UpdateWindow.UpdateWindow;
+    const serverSettings = yield* ServerSettings.ServerSettingsService;
+    const timings = yield* UpdateWindow.updateTimings;
+    const httpClient = yield* HttpClient.HttpClient;
+    // Same mirror the staged download uses, so a mirror lists what it serves.
+    const releaseBaseUrl = Option.getOrUndefined(
+      yield* Config.String(CLI_RELEASE_BASE_URL_ENV).pipe(Config.option),
+    );
+    const currentVersion = packageJson.version;
+    // Targets this process already gave up on; the launcher remembers rollbacks across restarts.
+    const skippedTargets = new Set<string>();
+    if (launcher.lastOutcome !== undefined && launcher.lastOutcome.status !== "committed") {
+      skippedTargets.add(launcher.lastOutcome.targetVersion);
+    }
+
+    const automaticUpdatesEnabled = serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.automaticUpdates),
+      Effect.orElseSucceed(() => false),
+    );
+
+    const updateBootService = Effect.gen(function* () {
+      if (!(yield* automaticUpdatesEnabled)) return;
+      const targetVersion = yield* resolveNewestVersion(
+        cliReleaseChannelOf(currentVersion),
+        releaseBaseUrl,
+      ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient));
+      if (
+        compareExactServiceVersions(targetVersion, currentVersion) <= 0 ||
+        skippedTargets.has(targetVersion)
+      ) {
+        return;
+      }
+      yield* Effect.logInfo("Staging a background server update", { targetVersion });
+      const staged = yield* selfUpdate.stage(targetVersion);
+      if (
+        staged.orchestrationProtocol !== undefined &&
+        staged.orchestrationProtocol !== ORCHESTRATION_PROTOCOL_VERSION
+      ) {
+        // Connected clients would be refused until they update; leave this one to a person.
+        skippedTargets.add(targetVersion);
+        yield* Effect.logInfo("Skipping a background update that changes the client protocol", {
+          targetVersion,
+        });
+        return;
+      }
+      yield* updateWindow.runWhenOpen(
+        { closesWindows: false },
+        Effect.gen(function* () {
+          // The setting may have been turned off while waiting.
+          if (!(yield* automaticUpdatesEnabled)) return;
+          skippedTargets.add(targetVersion);
+          yield* Effect.logInfo("Installing a background server update", { targetVersion });
+          yield* selfUpdate.update({ targetVersion });
+        }),
+      );
+    }).pipe(
+      Effect.catchCause((cause) => Effect.logWarning("Background server update failed", { cause })),
+      Effect.withSpan("updates.ServerAutoUpdater.bootService"),
+    );
+
+    const updateDesktopApp = (downloadedVersion: string) =>
+      Effect.gen(function* () {
+        if (!(yield* automaticUpdatesEnabled) || skippedTargets.has(downloadedVersion)) return;

@@ -0,0 +1,158 @@
+import { ORCHESTRATION_PROTOCOL_VERSION } from "@t3tools/contracts";
+import { CLI_RELEASE_BASE_URL_ENV, cliReleaseChannelOf } from "@t3tools/shared/cliRelease";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/http";
+
+import packageJson from "../../package.json" with { type: "json" };
+import { resolveNewestVersion } from "../cli/update.ts";
+import * as ServerSelfUpdate from "../cloud/selfUpdate.ts";
+import * as ServerConfig from "../config.ts";
+import * as ServiceLauncherClient from "../cloud/serviceLauncherClient.ts";
+import { compareExactServiceVersions } from "../cloud/serviceProtocol.ts";
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+import { forkParked } from "../serverActivation.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as UpdateWindow from "./UpdateWindow.ts";
+
+/**
+ * Updates this environment in the background when `automaticUpdates` is on.
+ *
+ * - Background service installs stage the newest release on their channel,
+ *   then hand off to the launcher once the update window opens.
+ * - Desktop-hosted servers wait for the app to finish its background
+ *   download, then relaunch it through the existing prepare/commit handoff
+ *   once no window is in use.
+ * - Foreground and `npx` servers cannot replace themselves and are skipped.
+ */
+export const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    // A dev server must not relaunch the desktop app or service it runs beside.
+    if ((yield* ServerConfig.ServerConfig).devUrl !== undefined) return;
+    const selfUpdate = yield* ServerSelfUpdate.ServerSelfUpdate;
+    const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+    const receiver = yield* DesktopTelemetryReceiver.DesktopTelemetryReceiver;
+    const updateWindow = yield* UpdateWindow.UpdateWindow;
+    const serverSettings = yield* ServerSettings.ServerSettingsService;
+    const timings = yield* UpdateWindow.updateTimings;
+    const httpClient = yield* HttpClient.HttpClient;
+    // Same mirror the staged download uses, so a mirror lists what it serves.
+    const releaseBaseUrl = Option.getOrUndefined(
+      yield* Config.String(CLI_RELEASE_BASE_URL_ENV).pipe(Config.option),
+    );
+    const currentVersion = packageJson.version;
+    // Targets this process already gave up on; the launcher remembers rollbacks across restarts.
+    const skippedTargets = new Set<string>();
+    if (launcher.lastOutcome !== undefined && launcher.lastOutcome.status !== "committed") {
+      skippedTargets.add(launcher.lastOutcome.targetVersion);
+    }
+
+    const automaticUpdatesEnabled = serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.automaticUpdates),
+      Effect.orElseSucceed(() => false),
+    );
+
+    const updateBootService = Effect.gen(function* () {
+      if (!(yield* automaticUpdatesEnabled)) return;
+      const targetVersion = yield* resolveNewestVersion(
+        cliReleaseChannelOf(currentVersion),
+        releaseBaseUrl,
+      ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient));
+      if (
+        compareExactServiceVersions(targetVersion, currentVersion) <= 0 ||
+        skippedTargets.has(targetVersion)
+      ) {
+        return;
+      }
+      yield* Effect.logInfo("Staging a background server update", { targetVersion });
+      const staged = yield* selfUpdate.stage(targetVersion);
+      if (
+        staged.orchestrationProtocol !== undefined &&
+        staged.orchestrationProtocol !== ORCHESTRATION_PROTOCOL_VERSION
+      ) {
+        // Connected clients would be refused until they update; leave this one to a person.
+        skippedTargets.add(targetVersion);
+        yield* Effect.logInfo("Skipping a background update that changes the client protocol", {
+          targetVersion,
+        });
+        return;
+      }

@@ -72,13 +72,25 @@ update can roll back to the previous version. If the update still fails:
 2. Check that you updated the server's machine, not only the device you are using.
 3. For a command-line server, stop it and relaunch the exact version shown in the notice.
 
-## Update providers
+## Automatic updates
 
 **Settings → General → Update automatically** is on by default. Each environment
-installs provider CLI updates in the background once no thread is running or
-waiting for you, no client has been used for 15 minutes, and no scheduled task
-or usage-limit resume is due within 5 minutes. A failed update is retried
-after 6 hours or when a newer version is published.
+waits until no thread is running or waiting for you, no client has been used for
+15 minutes, and no scheduled task or usage-limit resume is due within 5 minutes.

@@ -72,13 +72,28 @@ update can roll back to the previous version. If the update still fails:
 2. Check that you updated the server's machine, not only the device you are using.
 3. For a command-line server, stop it and relaunch the exact version shown in the notice.
 
-## Update providers
+## Automatic updates
 
 **Settings → General → Update automatically** is on by default. Each environment
-installs provider CLI updates in the background once no thread is running or
-waiting for you, no client has been used for 15 minutes, and no scheduled task
-or usage-limit resume is due within 5 minutes. A failed update is retried
-after 6 hours or when a newer version is published.
+waits until no thread is running or waiting for you, no client has been used for
+15 minutes, and no scheduled task or usage-limit resume is due within 5 minutes.
+Then it installs:
+
+- provider CLI updates that have a one-click update;
+- the newest T3 Code release on its channel, when it runs as a background service
+  (`t3 service install`). It downloads first and restarts only inside that window.
+
+Background services also wait for integrated terminal commands to finish.
+
+Desktop updates download in the background and install when you quit the app.
+The app stays open while you work, including when it hosts multiple backends.

@@ -0,0 +1,133 @@
+import { ORCHESTRATION_PROTOCOL_VERSION } from "@t3tools/contracts";
+import { cliReleaseChannelOf } from "@t3tools/shared/cliRelease";
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
+import { HttpClient } from "effect/http";
+
+import packageJson from "../../package.json" with { type: "json" };
+import { resolveNewestVersion } from "../cli/update.ts";
+import * as ServerSelfUpdate from "../cloud/selfUpdate.ts";
+import * as ServiceLauncherClient from "../cloud/serviceLauncherClient.ts";
+import { compareExactServiceVersions } from "../cloud/serviceProtocol.ts";
+import * as ServerConfig from "../config.ts";
+import * as ProviderInstallLock from "../provider/ProviderInstallLock.ts";
+import { forkParked } from "../serverActivation.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as UpdateWindow from "./UpdateWindow.ts";
+
+const FIRST_PASS_DELAY = Duration.minutes(2);
+/** How often a staged update rechecks the update window. */
+const WINDOW_RECHECK = Duration.minutes(1);
+const RELEASE_CHECK_INTERVAL = Duration.hours(1);
+/** How long a handed-off update may take to stop this server. */
+const HANDOFF_TIMEOUT = Duration.minutes(5);
+/** Turn starts wait for any held install lock, so holding this one closes the gate. */
+const RESTART_LOCK_KEY = "server-restart";
+
+/**
+ * Updates a background-service install in the background when
+ * `automaticUpdates` is on: stages the newest release on its channel right
+ * away, then hands off to the launcher once the update window opens. Desktop,
+ * `npx`, terminal and dev servers cannot replace themselves and are skipped.
+ */
+export const makeUpdatePass = () =>
+  Effect.gen(function* () {
+    // A dev server must not restart the service it runs beside.
+    if ((yield* ServerConfig.ServerConfig).devUrl !== undefined) return { pass: Effect.void };
+    const selfUpdate = yield* ServerSelfUpdate.ServerSelfUpdate;
+    if (selfUpdate.capability !== "boot-service") return { pass: Effect.void };
+    const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+    const updateWindow = yield* UpdateWindow.UpdateWindow;
+    const installLock = yield* ProviderInstallLock.ProviderInstallLock;
+    const serverSettings = yield* ServerSettings.ServerSettingsService;
+    const httpClient = yield* HttpClient.HttpClient;
+    const currentVersion = packageJson.version;
+    let staged: string | undefined;
+    let nextReleaseCheckAt = 0;
+    // A release the launcher rolled back would otherwise loop hourly; others are skipped per version.
+    const skipped = new Set<string>();
+    if (launcher.lastOutcome !== undefined && launcher.lastOutcome.status !== "committed") {
+      skipped.add(launcher.lastOutcome.targetVersion);
+    }
+
+    const enabled = serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.automaticUpdates),
+      Effect.orElseSucceed(() => false),
+    );
+
+    const stageNewest = Effect.gen(function* () {
+      nextReleaseCheckAt =
+        (yield* Clock.currentTimeMillis) + Duration.toMillis(RELEASE_CHECK_INTERVAL);
+      const targetVersion = yield* resolveNewestVersion(cliReleaseChannelOf(currentVersion)).pipe(
+        Effect.provideService(HttpClient.HttpClient, httpClient),
+      );
+      if (
+        compareExactServiceVersions(targetVersion, currentVersion) <= 0 ||
+        skipped.has(targetVersion)
+      ) {
+        return;
+      }
+      yield* Effect.logInfo("Staging a background server update", { targetVersion });
+      const { orchestrationProtocol } = yield* selfUpdate.stage(targetVersion);
+      if (orchestrationProtocol !== ORCHESTRATION_PROTOCOL_VERSION) {
+        // Connected clients would be refused after the restart.
+        skipped.add(targetVersion);
+        yield* Effect.logInfo("Skipping a background update with a different client protocol", {
+          targetVersion,
+        });
+        return;
+      }
+      staged = targetVersion;
+    });
+
+    const handOff = (targetVersion: string) =>
+      Effect.gen(function* () {
+        // The setting may have been turned off while waiting for the window.
+        if (!(yield* enabled)) return;
+        staged = undefined;
+        skipped.add(targetVersion);
+        yield* Effect.logInfo("Installing a background server update", { targetVersion });
+        yield* selfUpdate.update({ targetVersion }).pipe(
+          // Refused before the handoff (say, a manual update in progress): stage again next check.
+          Effect.tapError(() => Effect.sync(() => skipped.delete(targetVersion))),
+        );
+        // The launcher stops this server after accepting. Held until then, a turn
+        // cannot start in the gap, but not forever if the launcher never does.
+        yield* Effect.sleep(HANDOFF_TIMEOUT);
+        yield* Effect.logWarning("The service launcher did not stop this server after an update", {
+          targetVersion,
+        });
+      });
+
+    const pass = Effect.gen(function* () {
+      if (!(yield* enabled)) return;
+      if (staged === undefined && (yield* Clock.currentTimeMillis) >= nextReleaseCheckAt) {

@@ -72,13 +72,26 @@ update can roll back to the previous version. If the update still fails:
 2. Check that you updated the server's machine, not only the device you are using.
 3. For a command-line server, stop it and relaunch the exact version shown in the notice.
 
-## Update providers
+## Automatic updates
 
 **Settings → General → Update automatically** is on by default. Each environment
-installs provider CLI updates in the background once no thread is running or
-waiting for you, no client has been used for 15 minutes, and no scheduled task
-or usage-limit resume is due within 5 minutes. A failed update is retried
-after 6 hours or when a newer version is published.
+waits until no thread is running or waiting for you, no background work is pending,
+no client has been used for 15 minutes, and no scheduled task or usage-limit resume
+is due within 5 minutes.
+Then it installs:
+
+- provider CLI updates that have a one-click update;
+- the newest T3 Code release on its channel, when it runs as a background service
+  (`t3 service install`). It downloads first and restarts only inside that window.
+
+Background services also wait for integrated terminal commands to finish.

@@ -380,6 +385,41 @@ async function runtimeExists(baseDir: string, version: string): Promise<boolean>
   }
 }
 
+/**
+ * Removes completed runtimes nothing can return to, so unattended updates do
+ * not fill the disk. Keep both the running launcher and a deferred CLI/service
+ * install, which may name different executables. Recovery also needs the active
+ * version, the version an update came from, and a pending target.
+ */
+export async function pruneServiceRuntimes(
+  baseDir: string,
+  state: ServiceState,
+  launcherVersion: string | undefined,
+): Promise<void> {
+  const keep = new Set([state.activeVersion]);
+  if (launcherVersion !== undefined) keep.add(launcherVersion);
+  const installedVersion = await NodeFSP.readFile(restartPendingPath(baseDir), "utf8").catch(
+    (error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    },
+  );
+  if (installedVersion !== undefined) keep.add(installedVersion.trim());
+  if (state.update !== undefined) {
+    keep.add(state.update.fromVersion);
+    if (state.update.status === "pending") keep.add(state.update.targetVersion);
+  }
+  const versionsDir = NodePath.join(baseDir, "runtime", "versions");
+  for (const entry of await NodeFSP.readdir(versionsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !isExactServiceVersion(entry.name) || keep.has(entry.name)) {
+      continue;
+    }
+    // An incomplete directory is a staging in progress, not an old runtime.
+    if (!(await runtimeExists(baseDir, entry.name))) continue;
+    await NodeFSP.rm(NodePath.join(versionsDir, entry.name), { recursive: true, force: true });