agents-can-communicate 0.4.3 → 0.5.0

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/download.mjs

@@ -2,9 +2,11 @@ import { execFile } from "node:child_process";
 import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { declaredStoreVersion } from "./activation.mjs";
 import { stageOwnGeneration } from "./generation.mjs";
 import { verifyGeneration } from "./install.mjs";
 import { managedDirectory } from "./state.mjs";
+import { releaseStagingHold } from "./staging.mjs";
 import { ENTRY_KINDS } from "./entry.mjs";
 
 const NAME = "agents-can-communicate";
@@ -65,7 +67,20 @@ export async function downloadRelease(root, release, { env = process.env } = {})
     for (const name of ENTRY_KINDS) await access(path.join(packageRoot, "bin", "entrypoints", `${name}.mjs`));
     await access(path.join(packageRoot, "bin", "acc-update-worker.mjs"));
     const generation = await stageOwnGeneration({ packageRoot, managerRoot: root });
-    await verifyGeneration(generation, { env });
-    return { version: generation.version, root: generation.root };
+    // A failed verify, or any other failure before this function actually
+    // returns, means this candidate is abandoned here, so release its hold
+    // now - declaredStoreVersion included, so a future change to it (or any
+    // other exception in this region) cannot silently leak the hold instead
+    // of releasing it. Only a clean return hands the hold on to the caller
+    // (worker.mjs), since publication happens later there, and it is
+    // responsible for releasing it once that publish attempt resolves.
+    try {
+      await verifyGeneration(generation, { env });
+      return { version: generation.version, root: generation.root,
+        storeVersion: await declaredStoreVersion(generation.root), hold: generation.hold };
+    } catch (error) {
+      await releaseStagingHold(generation.hold);
+      throw error;
+    }
   } finally { await rm(temporary, { recursive: true, force: true }); }
 }

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/entry.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { scheduleWorker } from "./schedule.mjs";
 import { acquireRuntime } from "./leases.mjs";
-import { canonicalManagerRoot, readControl } from "./state.mjs";
+import { canonicalManagerRoot, readControl, readManagedJson } from "./state.mjs";
 
 export const ENTRY_KINDS = Object.freeze([
   "acc", "acc-hook", "acc-mcp", "acc-bootstrap", "acc-claude-channel",
@@ -53,6 +53,31 @@ function unavailable(kind) {
   }
 }
 
+const stableVersion = value => typeof value === "string" && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value);
+function newerVersion(left, right) {
+  if (!stableVersion(left) || !stableVersion(right)) return false;
+  const a = left.split(".").map(BigInt), b = right.split(".").map(BigInt);
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return a[index] > b[index];
+  return false;
+}
+
+/** Pending means downloaded and verified. Older packages do not advertise this
+ * management-only protocol; never load them speculatively for workspace work.
+ */
+async function updateImplementation(packageRoot, control) {
+  let selected = null;
+  for (const candidate of [{ root: packageRoot }, control.pending].filter(candidate => candidate?.root)) {
+    try {
+      const manifest = await readManagedJson(path.join(candidate.root, "package.json"));
+      if (manifest?.name !== "agents-can-communicate" || manifest.accManagedUpdateProtocol !== 2
+        || candidate.version !== undefined && manifest.version !== candidate.version
+        || !newerVersion(manifest.version, selected?.version ?? control.active.version)) continue;
+      selected = { root: candidate.root, version: manifest.version };
+    } catch { /* Unreadable alternatives leave the active implementation available. */ }
+  }
+  return selected?.root ?? null;
+}
+
 /** The lease lasts until OS process death, including callbacks after main returns. */
 export async function runEntry({ kind, packageRoot, managerRoot, managedRequired = false }) {
   if (!ENTRY_KINDS.includes(kind)) throw new Error("unknown ACC entry point");
@@ -66,6 +91,7 @@ export async function runEntry({ kind, packageRoot, managerRoot, managedRequired
   }
   let selected = packageRoot;
   let managed = null;
+  let managementOnly = false;
   let root;
   try {
     const requestedDataHome = bootstrapOptions === null ? null : await canonicalManagerRoot(bootstrapOptions.dataHome);
@@ -81,30 +107,44 @@ export async function runEntry({ kind, packageRoot, managerRoot, managedRequired
     if (control !== null) {
       selected = control.active.root;
       managed = root;
-      const lease = await acquireRuntime(root, { pid: process.pid, kind });
-      selected = lease.runtime.root;
-      managed = root;
-      const quiet = kind === "acc" && ["update", "install", "uninstall", "help", "version",
-        "--help", "-h", "--version", "-v", "-V"].includes(process.argv[2]);
-      if (!quiet) await scheduleWorker(root, control);
+      const update = kind === "acc" && ["update", "doctor"].includes(process.argv[2])
+        ? await updateImplementation(packageRoot, control) : null;
+      if (update !== null) {
+        selected = update;
+        managementOnly = true;
+      } else {
+        const lease = await acquireRuntime(root, { pid: process.pid, kind });
+        selected = lease.runtime.root;
+        const quiet = kind === "acc" && ["update", "install", "uninstall", "help", "version",
+          "--help", "-h", "--version", "-v", "-V"].includes(process.argv[2]);
+        if (!quiet) await scheduleWorker(root, control);
+      }
     } else if (managedRequired) throw new Error("managed runtime is not initialized");
   } catch {
     // Help and update recovery must remain reachable when state cannot admit a
     // workspace command. The CLI parser enforces this restricted path; merely
     // putting --help in a message value cannot bypass runtime admission.
+    // `selected` was read before this catch and, on this path, holds no
+    // lease or pin of its own - a generation reclaimed in the meantime makes
+    // this import fail with ENOENT. Degrade below like any other admission
+    // failure instead of crashing with a raw stack.
     if (kind === "acc" && selected) {
-      const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", "acc.mjs")).href);
-      await runtime.main({ managerRoot: root ?? null, packageRoot: selected, managementOnly: true });
-      return;
+      try {
+        const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", "acc.mjs")).href);
+        await runtime.main({ managerRoot: root ?? null, packageRoot: selected, managementOnly: true });
+        return;
+      } catch { /* Fall through to the same graceful unavailability below. */ }
     }
     unavailable(kind);
     if (kind === "acc-claude-channel" && selected) {
-      const { startInertChannel } = await import(pathToFileURL(path.join(selected,
-        "bin", "entrypoints", "claude-channel-stdio.mjs")).href);
-      startInertChannel();
+      try {
+        const { startInertChannel } = await import(pathToFileURL(path.join(selected,
+          "bin", "entrypoints", "claude-channel-stdio.mjs")).href);
+        startInertChannel();
+      } catch { /* The stderr notice above already fired either way. */ }
     }
     return;
   }
   const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", `${kind}.mjs`)).href);
-  await runtime.main({ managerRoot: managed, packageRoot: selected });
+  await runtime.main({ managerRoot: managed, packageRoot: selected, ...(managementOnly ? { managementOnly } : {}) });
 }

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/generation.mjs

@@ -3,6 +3,8 @@ import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm }
   from "node:fs/promises";
 import path from "node:path";
 
+import { attachStagingTemp, holdStagedGeneration, releaseStagingHold } from "./staging.mjs";
+
 const NAME = "agents-can-communicate";
 const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 
@@ -134,34 +136,51 @@ export async function stageOwnGeneration({ packageRoot, managerRoot }) {
   await directory(generations);
   const target = path.join(generations, `${manifest.version}-${digest.slice(0, 24)}`);
   const result = { version: manifest.version, root: target, digest };
-  if (await existingMatches(target, files)) return result;
-  const staging = await mkdtemp(path.join(generations, ".staging-"));
+  // Held before the check that may return `target` unchanged (it can already
+  // be sitting on disk unprotected from an earlier run) and, on the staging
+  // path below, before the rename that makes a freshly built `target`
+  // visible at all: reclaim must never observe the directory without also
+  // observing why it exists. The caller now owns this hold - see its own
+  // `hold` on the returned value - and must release it on every exit from
+  // its own attempt, once the generation is either published or abandoned.
+  // A hold this function itself never hands off (because it throws instead
+  // of returning) is released here, in its own catch, rather than left for
+  // a confirmed-dead reap to eventually find.
+  const hold = await holdStagedGeneration({ root, generationRoot: target });
   try {
-    const directories = new Set([staging]);
-    for (const [name, file] of files) {
-      const destination = path.join(staging, name);
-      await mkdir(path.dirname(destination), { recursive: true });
-      for (let parent = path.dirname(destination); parent !== staging; parent = path.dirname(parent)) directories.add(parent);
-      const handle = await open(destination, "wx", file.mode);
+    if (await existingMatches(target, files)) return { ...result, hold };
+    const staging = await mkdtemp(path.join(generations, ".staging-"));
+    try {
+      await attachStagingTemp(hold, staging);
+      const directories = new Set([staging]);
+      for (const [name, file] of files) {
+        const destination = path.join(staging, name);
+        await mkdir(path.dirname(destination), { recursive: true });
+        for (let parent = path.dirname(destination); parent !== staging; parent = path.dirname(parent)) directories.add(parent);
+        const handle = await open(destination, "wx", file.mode);
+        try {
+          await handle.writeFile(file.bytes);
+          await handle.chmod(file.mode);
+          await handle.sync();
+        } finally { await handle.close(); }
+      }
+      for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
+        const handle = await open(directory, "r");
+        try { await handle.sync(); } finally { await handle.close(); }
+      }
       try {
-        await handle.writeFile(file.bytes);
-        await handle.chmod(file.mode);
-        await handle.sync();
-      } finally { await handle.close(); }
-    }
-    for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
-      const handle = await open(directory, "r");
+        await rename(staging, target);
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY"].includes(error.code) || !await existingMatches(target, files)) throw error;
+      }
+      const handle = await open(generations, "r");
       try { await handle.sync(); } finally { await handle.close(); }
+      return { ...result, hold };
+    } finally {
+      await rm(staging, { recursive: true, force: true });
     }
-    try {
-      await rename(staging, target);
-    } catch (error) {
-      if (!["EEXIST", "ENOTEMPTY"].includes(error.code) || !await existingMatches(target, files)) throw error;
-    }
-    const handle = await open(generations, "r");
-    try { await handle.sync(); } finally { await handle.close(); }
-    return result;
-  } finally {
-    await rm(staging, { recursive: true, force: true });
+  } catch (error) {
+    await releaseStagingHold(hold);
+    throw error;
   }
 }

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/install.mjs

@@ -3,12 +3,15 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { declaredStoreVersion } from "./activation.mjs";
 import { validateManagedLocation } from "./location.mjs";
 import { stageOwnGeneration } from "./generation.mjs";
 import { writeLaunchers } from "./launchers.mjs";
 import { canonicalManagerRoot, readControl, writeControl } from "./state.mjs";
 import { scheduleWorker } from "./schedule.mjs";
+import { releaseStagingHold } from "./staging.mjs";
 import { withManagerLock } from "./mutex.mjs";
+import { retireManagedHolds } from "./retire.mjs";
 
 const exec = promisify(execFile);
 export async function verifyGeneration(runtime, { env = process.env } = {}) {
@@ -27,35 +30,44 @@ export async function verifyGeneration(runtime, { env = process.env } = {}) {
 export async function installManaged({ packageRoot, managerRoot, dataHome, home, targets, env, apply, cwd }) {
   const root = await validateManagedLocation({ managerRoot, dataHome, home, cwd, env });
   const candidate = await stageOwnGeneration({ packageRoot, managerRoot: root });
-  await verifyGeneration(candidate, { env });
-  return withManagerLock(root, async () => {
-    const previous = await readControl(root);
-    if (previous !== null && previous.home !== home) {
-      throw new Error("this ACC data home manages another client home; use a separate ACC_DATA_HOME");
-    }
-    if (previous !== null && previous.active.root !== candidate.root) {
-      throw new Error("install from the active managed runtime; use acc update to switch versions");
-    }
-    const runtime = { version: candidate.version, root: candidate.root };
-    const autoPreference = previous?.autoPreference ?? previous?.auto ?? true;
-    // Full removal pauses workers without revoking the user's choice. Keep a
-    // partial-removal pause until explicit opt-in; this install may omit its failed target.
-    const auto = previous?.targets.length ? previous.auto : autoPreference;
-    const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
-      auto, autoPreference, pin: previous?.pin ?? null,
-      checkedAt: previous?.checkedAt ?? null, home,
-      targets: [...new Set([...(previous?.targets ?? []), ...targets])], notice: null };
-    await writeControl(root, control);
-    const paths = await writeLaunchers(root, runtime.root);
-    const result = await apply({ ...paths, preserveVersions: true });
-    if (result.failed.length === 0) {
-      const ready = await writeControl(root, { ...control, phase: "ready", pending: null });
-      await scheduleWorker(root, ready, { env });
-    } else {
-      await writeControl(root, { ...control, notice: "Integration refresh is incomplete; run acc update to recover." });
-    }
-    return result;
-  });
+  // The hold candidate.hold carries survives verification and publication;
+  // release it on every exit from this attempt, once the generation is
+  // either published (independently protected by the control pointer this
+  // writes below) or abandoned (any throw between here and there).
+  try {
+    await verifyGeneration(candidate, { env });
+    return await withManagerLock(root, async () => {
+      const previous = await readControl(root);
+      if (previous !== null && previous.home !== home) {
+        throw new Error("this ACC data home manages another client home; use a separate ACC_DATA_HOME");
+      }
+      if (previous !== null && previous.active.root !== candidate.root) {
+        throw new Error("install from the active managed runtime; use acc update to switch versions");
+      }
+      const runtime = { version: candidate.version, root: candidate.root,
+        storeVersion: await declaredStoreVersion(candidate.root) };
+      const autoPreference = previous?.autoPreference ?? previous?.auto ?? true;
+      // Full removal pauses workers without revoking the user's choice. Keep a
+      // partial-removal pause until explicit opt-in; this install may omit its failed target.
+      const auto = previous?.targets.length ? previous.auto : autoPreference;
+      const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
+        auto, autoPreference, pin: previous?.pin ?? null,
+        checkedAt: previous?.checkedAt ?? null, home,
+        targets: [...new Set([...(previous?.targets ?? []), ...targets])], notice: null };
+      await writeControl(root, control);
+      const paths = await writeLaunchers(root, runtime.root);
+      const result = await apply({ ...paths, preserveVersions: true });
+      if (result.failed.length === 0) {
+        const ready = await writeControl(root, { ...control, phase: "ready", pending: null });
+        await scheduleWorker(root, ready, { env });
+      } else {
+        await writeControl(root, { ...control, notice: "Integration refresh is incomplete; run acc update to recover." });
+      }
+      return result;
+    });
+  } finally {
+    await releaseStagingHold(candidate.hold);
+  }
 }
 
 /** Removal updates enrollment under the same fence, so an updater cannot reinstall it. */
@@ -69,6 +81,11 @@ export async function uninstallManaged({ managerRoot, apply }) {
     const removed = new Set(result.operations.filter(operation => operation.applied)
       .map(operation => operation.adapterId));
     const targets = control.targets.filter(id => !removed.has(id));
+    // Holds this install published must stop blocking a later activation. The
+    // client processes keep running; only the records ACC owns are retired.
+    if (targets.length === 0) {
+      await retireManagedHolds({ root, workspaces: path.join(path.dirname(root), "workspaces") });
+    }
     await writeControl(root, { ...control, targets,
       autoPreference: control.autoPreference ?? control.auto,
       auto: targets.length > 0 && result.failed.length === 0 && control.auto,

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/legacy-maintenance.mjs

@@ -0,0 +1,47 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { askConfirmation } from "../confirm.mjs";
+import { ALL_ADAPTERS } from "../install-command.mjs";
+import { MAINTENANCE_ACTIVE, readMaintenance } from "./maintenance-state.mjs";
+
+const inspectServices = async options => (await import("./maintenance.mjs")).inspectMaintenanceServices(options);
+const request = async options => (await import("./maintenance.mjs")).requestMaintenance(options);
+const handoff = () => Object.assign(new Error("ACC maintenance needs confirmation or recovery; run acc update."),
+  { code: "ACC_LEGACY_MAINTENANCE_HANDOFF" });
+
+async function isLegacyWorker(argv, control, root) {
+  if (argv.length !== 3) return false;
+  try {
+    return await realpath(argv[1]) === await realpath(path.join(control.active.root, "bin", "acc-update-worker.mjs"))
+      && await realpath(argv[2]) === await realpath(root);
+  } catch { return false; }
+}
+
+/** Old activation imports this candidate before taking its admission fence.
+ * Only request/schedule here: the detached job waits for this process to exit.
+ * Throwing in the old background worker unwinds its idle-loop lock normally.
+ */
+export async function bridgeLegacyMaintenance({ control, root, env = process.env, callerProtocol = 1 }, {
+  argv = process.argv, input = process.stdin, output = process.stdout,
+  inspect = inspectServices, requestMaintenance = request,
+} = {}) {
+  if (callerProtocol >= 2) return null;
+  const worker = await isLegacyWorker(argv, control, root);
+  const interactive = argv[2] === "update" && !argv.includes("--json")
+    && input.isTTY === true && output.isTTY === true;
+  if (!worker && !interactive) return null;
+  const existing = await readMaintenance(root);
+  let services;
+  if (!MAINTENANCE_ACTIVE.includes(existing?.status)) {
+    if (!control.pending) return null;
+    services = await inspect({ root, control, env, adapters: ALL_ADAPTERS() });
+    if (!services.length) return null;
+    if (worker) throw handoff();
+  }
+  const result = await requestMaintenance({ root, control, options: { json: false }, services,
+    runtime: { env, input, output, confirm: askConfirmation,
+      isInteractive: () => interactive, packageRoot: control.pending?.root ?? control.active.root } });
+  if (worker) throw handoff();
+  if (result?.text) output.write(`${result.text}\n`);
+  return result;
+}

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/maintenance-state.mjs

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { managedDirectory, readManagedJson, validateRuntime, writeManagedJson } from "./state.mjs";
+
+export const MAINTENANCE_ACTIVE = ["waiting", "stopping", "refreshing", "restarting", "recovery"];
+const statuses = [...MAINTENANCE_ACTIVE, "completed", "failed", "cancelled"];
+export const maintenanceRecipe = c => JSON.stringify([c.active, c.pending, c.home, c.targets, c.auto, c.pin]);
+
+export async function readMaintenance(root) {
+  if (!await managedDirectory(root)) return null;
+  const value = await readManagedJson(path.join(root, "maintenance.json"));
+  if (value === undefined) return null;
+  if (value.schemaVersion !== 1 || typeof value.id !== "string" || !/^[a-f0-9-]{36}$/.test(value.id)
+    || !statuses.includes(value.status) || typeof value.recipe !== "string"
+    || typeof value.workerRoot !== "string" || !path.isAbsolute(value.workerRoot)
+    || !Number.isFinite(value.deadline) || !Number.isSafeInteger(value.callerPid) || value.callerPid < 1
+    || !(value.workerPid === null || Number.isSafeInteger(value.workerPid) && value.workerPid > 0)
+    || !Array.isArray(value.services) || value.services.length !== 1
+    || !value.services.every(s => typeof s.adapterId === "string" && s.snapshot
+      && Number.isSafeInteger(s.snapshot.pid) && s.snapshot.pid > 0)
+    || !Array.isArray(value.attempted) || !value.attempted.every(id => value.services.some(s => s.adapterId === id))) {
+    throw new Error("invalid update maintenance record");
+  }
+  await validateRuntime(root, value.target);
+  return value;
+}
+
+/** Caller holds the admission mutex or the exclusive maintenance-worker lock. */
+export async function writeMaintenance(root, job) {
+  await writeManagedJson(path.join(root, "maintenance.json"), job);
+  return job;
+}
+
+export function maintenanceReport(job) {
+  return { id: job.id, status: job.status, version: job.target.version,
+    reasonCode: job.reasonCode ?? null, workerPid: job.workerPid,
+    ...(job.status === "waiting" && job.waiting ? { waiting: job.waiting } : {}),
+    services: job.services.map(({ adapterId, snapshot }) => ({ adapterId,
+      serviceId: snapshot.serviceId, pid: snapshot.pid, clientVersion: snapshot.cliVersion,
+      serverVersion: snapshot.serverVersion })) };
+}
+
+export function maintenanceNotice(job) {
+  const version = job.target.version;
+  if (job.status === "completed") return `ACC ${version} update maintenance completed; the client service was restarted and verified.`;
+  if (job.status === "cancelled") return `Update maintenance cancelled (${job.reasonCode}); no client service was stopped.`;
+  if (job.status === "failed") return `Update maintenance failed (${job.reasonCode}); run acc update to retry.`;
+  if (job.status === "recovery") return `Client service recovery is pending (${job.reasonCode}); run acc update to retry recovery.`;
+  if (job.status === "waiting") {
+    const waiting = job.waiting?.reason === "service_busy" ? `idle client work (${job.waiting.busyThreads ?? "unknown"} active turns, ${job.waiting.queuedRequests ?? "unknown"} queued requests)`
+      : job.waiting?.reason === "other_processes" ? `${job.waiting.processes} other or unidentified process(es) to exit`
+        : job.waiting?.reason === "caller_exit" ? "the requesting command to exit"
+          : job.waiting?.reason === "update_worker" ? "another ACC updater"
+            : "idle client work and any ACC process still holding this update";
+    return `ACC ${version} update maintenance is scheduled; waiting for ${waiting}. Open clients will disconnect during restart. Check acc doctor for progress.`;
+  }
+  return `ACC ${version} update maintenance: ${job.status}. Check acc doctor for the result.`;
+}

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/maintenance-worker.mjs

@@ -0,0 +1,118 @@
+import { ALL_ADAPTERS } from "../install-command.mjs";
+import { activatePending, listActivationBlockers } from "./activation.mjs";
+import { confirmedDead, defaultPidIsAlive, withManagerLock } from "./mutex.mjs";
+import { readControl } from "./state.mjs";
+import { maintenanceContext } from "./maintenance.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceRecipe, readMaintenance, writeMaintenance } from "./maintenance-state.mjs";
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const deferred = waiting => Object.assign(new Error("maintenance waiting"), { code: "MAINTENANCE_WAIT", waiting });
+const refused = reasonCode => Object.assign(new Error("maintenance refused"), { reasonCode });
+
+/** No runtime lease: this worker must outlive the client that requested it.
+ * Its own mutex serializes checkpoints; admission remains separately fenced.
+ */
+export async function runMaintenance(root, { jobId, env = process.env, adapters = ALL_ADAPTERS(),
+  pidIsAlive = defaultPidIsAlive, pause = sleep, now = Date.now, activate = activatePending } = {}) {
+  return withManagerLock(`${root}/maintenance-worker`, async () => {
+    let job;
+    // Publication owns admission until spawn's PID is durable. Wait for it
+    // before writing checkpoints, including when recovering an older job.
+    await withManagerLock(root, async () => {
+      job = await readMaintenance(root);
+      if (job && (!jobId || job.id === jobId) && MAINTENANCE_ACTIVE.includes(job.status)) {
+        job = await writeMaintenance(root, { ...job, workerPid: process.pid });
+      }
+    });
+    if (!job || jobId && job.id !== jobId || !MAINTENANCE_ACTIVE.includes(job.status)) return job;
+    const save = async changes => { job = await writeMaintenance(root, { ...job, ...changes }); return job; };
+    const waitFor = async waiting => {
+      if (JSON.stringify(job.waiting) !== JSON.stringify(waiting)) await save({ waiting });
+      await pause(1000);
+    };
+    const adapter = adapters.find(a => a.id === job.services[0].adapterId);
+    if (!adapter?.stopForMaintenance || !adapter.startAfterMaintenance) return save({ status: "failed", reasonCode: "maintenance_adapter_unavailable" });
+    const expected = job.services[0].snapshot;
+    let control = await readControl(root);
+    const context = maintenanceContext(control, env);
+
+    async function restore(result, reasonCode = null) {
+      await save({ status: "restarting", reasonCode });
+      let restarted;
+      try { restarted = await adapter.startAfterMaintenance({ context, expected }); }
+      catch { restarted = { ok: false, reasonCode: "service_start_failed" }; }
+      if (!restarted?.ok) return save({ status: "recovery", reasonCode: restarted?.reasonCode ?? "service_start_failed" });
+      return save({ status: result?.activated ? "completed" : "failed",
+        reasonCode: result?.activated ? null : reasonCode ?? result?.reason ?? "update_incomplete" });
+    }
+
+    // A crash after the stop checkpoint can mean either side of the command.
+    // Never repeat it. Forward repair still obeys native/ACC lifetime fences,
+    // then the idempotent adapter start restores the already-approved service.
+    if (job.attempted.length) {
+      let result;
+      try {
+        control = await readControl(root);
+        if (!control.pending && control.active.root === job.target.root && control.phase === "ready") result = { activated: true };
+        else if (maintenanceRecipe(control) === job.recipe) {
+          result = await withManagerLock(`${root}/worker`, () => activate(root, { env, pidIsAlive }));
+        }
+      } catch { /* Restoration still runs when forward repair is unavailable. */ }
+      return restore(result, result?.reason ?? "maintenance_interrupted");
+    }
+
+    for (;;) {
+      control = await readControl(root);
+      if (maintenanceRecipe(control) !== job.recipe) return save({ status: "cancelled", reasonCode: "update_state_changed" });
+      if (now() > job.deadline) return save({ status: "cancelled", reasonCode: "idle_wait_expired" });
+      if (!await confirmedDead(job.callerPid, pidIsAlive)) { await waitFor({ reason: "caller_exit" }); continue; }
+      let result;
+      try {
+        result = await withManagerLock(`${root}/worker`, async () => {
+          const beforeActivation = async current => {
+            if (maintenanceRecipe(current) !== job.recipe) throw refused("update_state_changed");
+            // Same fallback as maintenance.mjs's own target: judge other
+            // holds against the pending generation's contract when one is
+            // being activated, otherwise against the generation already
+            // running, since there is no incoming generation to compare to.
+            // Pick the whole generation record, not a per-field fallback, so
+            // a pending generation declaring no contract of its own is
+            // judged as "none" rather than silently borrowing active's.
+            const blockers = await listActivationBlockers(root, { pidIsAlive,
+              incomingStoreVersion: (current.pending ?? current.active).storeVersion });
+            const others = blockers.filter(b => b.pid !== expected.pid || b.kinds.some(kind => kind !== "native"));
+            if (others.length) throw deferred({ reason: "other_processes", processes: others.length });
+            const snapshot = await adapter.inspectMaintenance(context);
+            if (snapshot?.state === "busy") throw deferred({ reason: "service_busy",
+              busyThreads: snapshot.busyThreads, queuedRequests: snapshot.queuedRequests });
+            if (snapshot?.state !== "ready") throw refused("service_readiness_changed");
+            // Durable before the vendor command: recovery restores without
+            // assuming whether the previous worker reached the actual stop.
+            await save({ status: "stopping", attempted: [adapter.id], waiting: null });
+            const stopped = await adapter.stopForMaintenance({ context, expected });
+            if (stopped?.ok === false && stopped.stopAttempted === false) {
+              await save({ status: "waiting", attempted: [] });
+              if (stopped.reasonCode === "service_busy") throw deferred({ reason: "service_busy",
+                busyThreads: stopped.snapshot?.busyThreads, queuedRequests: stopped.snapshot?.queuedRequests });
+            }
+            if (!stopped?.ok) throw refused(stopped?.reasonCode ?? "service_stop_failed");
+            await save({ status: "refreshing" });
+          };
+          if (control.pending) return activate(root, { env, pidIsAlive, beforeActivation });
+          return withManagerLock(root, async () => {
+            await beforeActivation(await readControl(root));
+            return { activated: true, version: control.active.version };
+          });
+        }, { timeoutMs: 100 });
+      } catch (error) {
+        if (!job.attempted.length && (error.code === "MAINTENANCE_WAIT" || /manager lock held/.test(error.message))) {
+          await waitFor(error.waiting ?? { reason: "update_worker" }); continue;
+        }
+        if (job.attempted.length) return restore(null, error.reasonCode ?? "maintenance_failed");
+        return save({ status: "failed", reasonCode: error.reasonCode ?? "maintenance_failed" });
+      }
+      if (job.attempted.length) return restore(result);
+      return save({ status: "cancelled", reasonCode: result?.reason ?? "update_state_changed" });
+    }
+  }, { timeoutMs: 100, pidIsAlive });
+}