agents-can-communicate 0.4.2 → 0.4.4

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 clients and other ACC processes to exit";
+    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,110 @@
+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");
+            const blockers = await listActivationBlockers(root, { pidIsAlive });
+            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 });
+}

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

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { ALL_ADAPTERS } from "../install-command.mjs";
+import { listActivationBlockers } from "./activation.mjs";
+import { confirmedDead, withManagerLock } from "./mutex.mjs";
+import { readControl, readManagedJson } from "./state.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceRecipe, maintenanceReport,
+  readMaintenance, writeMaintenance } from "./maintenance-state.mjs";
+
+export function maintenanceContext(control, env) {
+  return { home: control.home, env, platform: `${process.platform}-${process.arch}` };
+}
+
+export async function inspectMaintenanceServices({ control, env = process.env, root, adapters = ALL_ADAPTERS() }) {
+  const blockers = await listActivationBlockers(root, { ignorePid: process.pid });
+  const services = [];
+  for (const adapter of adapters.filter(a => control.targets.includes(a.id) && a.inspectMaintenance)) {
+    const snapshot = await adapter.inspectMaintenance(maintenanceContext(control, env));
+    if (!snapshot || !["ready", "busy"].includes(snapshot.state)) continue;
+    if (snapshot.serverVersion !== snapshot.cliVersion
+      || blockers.some(b => b.pid === snapshot.pid && b.kinds.includes("native"))) {
+      services.push({ adapterId: adapter.id, snapshot });
+    }
+  }
+  return services;
+}
+
+export async function spawnMaintenance({ root, job, packageRoot, env }) {
+  packageRoot = job.workerRoot ?? packageRoot;
+  const manifest = await readManagedJson(path.join(packageRoot, "package.json"));
+  if (manifest?.name !== "agents-can-communicate" || manifest.accManagedUpdateProtocol !== 2) {
+    throw new Error("maintenance worker implementation is unavailable");
+  }
+  const child = spawn(process.execPath, [path.join(packageRoot, "bin", "acc-maintenance-worker.mjs"), root, job.id],
+    { env, cwd: root, detached: true, stdio: "ignore" });
+  await new Promise((resolve, reject) => { child.once("spawn", resolve); child.once("error", reject); });
+  child.unref();
+  return child.pid;
+}
+
+const response = job => ({ data: { reason: "maintenance_pending", maintenance: maintenanceReport(job) }, text: maintenanceNotice(job) });
+
+async function launch(root, job, runtime) {
+  if (job.workerPid !== null && !await confirmedDead(job.workerPid)) return job;
+  try {
+    // The child reads after publication; a separate lifetime lock prevents a
+    // second command from creating two workers or overwriting its checkpoint.
+    const workerPid = await (runtime.spawnMaintenance ?? spawnMaintenance)({ root, job,
+      packageRoot: runtime.packageRoot, env: runtime.env ?? process.env });
+    return writeMaintenance(root, { ...job, workerPid });
+  } catch {
+    return writeMaintenance(root, { ...job, status: job.attempted.length ? "recovery" : "failed",
+      reasonCode: "maintenance_worker_start_failed" });
+  }
+}
+
+/** Explicit command only. Background inspection never grants restart consent. */
+export async function requestMaintenance({ root, control, options, runtime, services }) {
+  const existing = await readMaintenance(root);
+  if (existing && MAINTENANCE_ACTIVE.includes(existing.status)) {
+    return withManagerLock(root, async () => {
+      const latest = await readMaintenance(root);
+      if (!latest || !MAINTENANCE_ACTIVE.includes(latest.status)) return latest ? response(latest) : null;
+      return response(await launch(root, latest, runtime));
+    });
+  }
+  services ??= await inspectMaintenanceServices({ root, control, env: runtime.env, adapters: runtime.adapters });
+  if (services.length !== 1) return null; // More than one service needs a separate captured contract.
+  const names = services.map(s => s.snapshot.serviceId).join(", ");
+  if (!options.yes) {
+    if (options.json || runtime.isInteractive?.() !== true) return {
+      data: { reason: "confirmation_required", services: services.map(s => ({ adapterId: s.adapterId, serviceId: s.snapshot.serviceId })) },
+      text: `Finishing the update requires restarting ${names}, disconnecting open clients. Run acc update in a terminal to confirm, or acc update --yes to consent explicitly.` };
+    const approved = await runtime.confirm?.(`Restart ${names} to finish updating ACC? Open clients will disconnect; ACC will wait for idle turns, refresh integrations, restart the service and verify it. A turn started during the final restart check can be interrupted.`,
+      { input: runtime.input, output: runtime.output });
+    if (approved !== true) return { data: { reason: "maintenance_declined" },
+      text: "Client restart declined; the update remains pending until running clients exit." };
+  }
+  return withManagerLock(root, async () => {
+    const current = await readControl(root), previous = await readMaintenance(root);
+    if (previous && MAINTENANCE_ACTIVE.includes(previous.status)) return response(previous);
+    if (maintenanceRecipe(current) !== maintenanceRecipe(control)) return {
+      data: { reason: "state_changed" }, text: "Update settings changed before confirmation; run acc update again." };
+    const job = await writeMaintenance(root, { schemaVersion: 1, id: randomUUID(), status: "waiting",
+      target: current.pending ?? current.active, recipe: maintenanceRecipe(current), services,
+      workerRoot: runtime.packageRoot,
+      approvedAt: new Date().toISOString(), deadline: Date.now() + 15 * 60_000,
+      callerPid: process.pid, workerPid: null, attempted: [], reasonCode: null });
+    return response(await launch(root, job, runtime));
+  });
+}

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

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { newerVersion } from "./download.mjs";
+import { stageOwnGeneration } from "./generation.mjs";
+import { verifyGeneration } from "./install.mjs";
+import { confirmedDead, withManagerLock } from "./mutex.mjs";
+import { readControl, readManagedJson, writeControl } from "./state.mjs";
+
+/** A newly installed global CLI can supersede an older pending release locally.
+ * No workspace code or integration is admitted until normal activation passes.
+ */
+export async function stageNewerManagementRuntime(root, { packageRoot, env }) {
+  if (!packageRoot) return false;
+  const before = await readControl(root);
+  const manifest = await readManagedJson(path.join(packageRoot, "package.json"));
+  if (before?.phase !== "ready" || manifest?.name !== "agents-can-communicate"
+    || manifest.accManagedUpdateProtocol !== 2 || before.pin && before.pin !== manifest.version
+    || !newerVersion(manifest.version, before.pending?.version ?? before.active.version)) return false;
+  const candidate = await stageOwnGeneration({ packageRoot, managerRoot: root });
+  await verifyGeneration(candidate, { env });
+  return withManagerLock(root, async () => {
+    const current = await readControl(root);
+    if (current.phase !== "ready" || current.pin !== before.pin
+      || JSON.stringify([current.active, current.pending]) !== JSON.stringify([before.active, before.pending])) return false;
+    await writeControl(root, { ...current, pending: { root: candidate.root, version: candidate.version },
+      notice: `ACC ${candidate.version} is verified and ready to activate.` });
+    return true;
+  });
+}
+
+async function inspectWorker(pid) {
+  try {
+    const { stdout } = await promisify(execFile)("/bin/ps", ["-p", String(pid), "-o", "uid=,lstart=,command="],
+      { timeout: 2000, maxBuffer: 16384 });
+    const match = /^\s*(\d+)\s+(.{24})\s+(.+)\s*$/.exec(stdout);
+    return match ? { uid: Number(match[1]), start: match[2], command: match[3] } : null;
+  } catch { return null; }
+}
+
+/** 0.4.2/0.4.3 kept this ACC-owned worker lock while sleeping indefinitely.
+ * Retire only an exactly identified old helper, under the admission mutex in
+ * ready phase. Never interrupt integration writes, a client, or an unknown PID.
+ */
+export async function retireLegacyUpdateWorker(root, { inspect = inspectWorker,
+  signal = pid => process.kill(pid, "SIGTERM"), pause = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  return withManagerLock(root, async () => {
+    const control = await readControl(root);
+    if (control?.phase !== "ready") return false;
+    const manifest = await readManagedJson(path.join(control.active.root, "package.json"));
+    if (manifest?.accManagedUpdateProtocol === 2) return false;
+    const ownerFile = path.join(root, "worker", "manager.lock", "owner.json");
+    const owner = await readManagedJson(ownerFile);
+    if (!Number.isSafeInteger(owner?.pid) || owner.pid < 2 || owner.pid === process.pid
+      || typeof owner.token !== "string" || !Number.isFinite(Date.parse(owner.acquiredAt))) return false;
+    const observed = await inspect(owner.pid);
+    const suffix = ` ${path.join(control.active.root, "bin", "acc-update-worker.mjs")} ${root}`;
+    const executable = observed?.command.endsWith(suffix) ? observed.command.slice(0, -suffix.length) : null;
+    const elapsed = Date.parse(owner.acquiredAt) - Date.parse(observed?.start);
+    if (!executable || !path.isAbsolute(executable) || path.basename(executable) !== "node"
+      || observed.uid !== process.getuid?.() || !Number.isFinite(elapsed) || elapsed < 0 || elapsed > 60_000) return false;
+    if (JSON.stringify(await readManagedJson(ownerFile)) !== JSON.stringify(owner)
+      || JSON.stringify(await inspect(owner.pid)) !== JSON.stringify(observed)) return false;
+    signal(owner.pid);
+    for (let attempt = 0; attempt < 40; attempt++) {
+      if (await confirmedDead(owner.pid)) return true;
+      await pause(50);
+    }
+    return false; // Normal mutex reclamation still requires confirmed death.
+  });
+}

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

@@ -3,9 +3,11 @@ import { applyPlan, detectInstallation, livePolicyOf, loadOwnership, planInstall
   from "@agents-can-communicate/installer";
 import { ALL_ADAPTERS, clientContext, probeTimeout } from "../install-command.mjs";
 import { stablePaths, writeLaunchers } from "./launchers.mjs";
+import { bridgeLegacyMaintenance } from "./legacy-maintenance.mjs";
 
 /** Loaded from the candidate, so its own adapters supply its integration bytes. */
-export async function prepareRefresh({ control, root, env = process.env }) {
+export async function prepareRefresh({ control, root, env = process.env, callerProtocol = 1 }) {
+  await bridgeLegacyMaintenance({ control, root, env, callerProtocol });
   const dataHome = path.dirname(path.dirname(root));
   const wanted = new Set(control.targets);
   const adapters = ALL_ADAPTERS().filter(adapter => wanted.has(adapter.id));
@@ -16,12 +18,9 @@ export async function prepareRefresh({ control, root, env = process.env }) {
   const detected = await detectInstallation({ adapters, context, probeTimeoutMs: probeTimeout(env) });
   const deliveryByAdapter = Object.fromEntries(adapters.map(adapter => [adapter.id,
     livePolicyOf(recorded.find(record => record.adapterId === adapter.id))]));
-  // An unavailable probe cannot silently revoke an existing native opt-in.
-  for (const detection of detected) {
-    if (deliveryByAdapter[detection.adapterId] !== "off" && detection.nativeDelivery?.state !== "eligible") {
-      throw new Error("native integration could not be verified; update remains pending");
-    }
-  }
+  // Refresh configuration even when the client's service is temporarily absent.
+  // The installer preserves consent and existing activation; readiness stays a
+  // separate, current probe result rather than an update prerequisite.
   const plan = planInstallation({ adapters, detected, context, recorded,
     accVersion: control.pending.version, requested: control.targets, deliveryByAdapter });
   if (plan.skipped.length || plan.operations.length !== wanted.size) {

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

@@ -8,8 +8,10 @@ import { checkDue, networkDisabled } from "./policy.mjs";
 export async function scheduleWorker(root, control, { env = process.env } = {}) {
   if (!control?.auto || networkDisabled(env) || !control.pending && !checkDue(control)) return false;
   try {
-    const owner = await readManagedJson(path.join(root, "worker", "manager.lock", "owner.json"));
-    if (Number.isSafeInteger(owner?.pid) && !await confirmedDead(owner.pid)) return false;
+    for (const directory of [path.join(root, "worker"), path.join(root, "worker", "poller")]) {
+      const owner = await readManagedJson(path.join(directory, "manager.lock", "owner.json"));
+      if (Number.isSafeInteger(owner?.pid) && !await confirmedDead(owner.pid)) return false;
+    }
     const child = spawn(process.execPath,
       [path.join(control.active.root, "bin", "acc-update-worker.mjs"), root], {
         env, detached: true, stdio: "ignore", cwd: root,

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

@@ -2,6 +2,8 @@ import { activatePending } from "./activation.mjs";
 import { downloadRelease, fetchRelease, newerVersion } from "./download.mjs";
 import { withManagerLock } from "./mutex.mjs";
 import { readControl, writeControl } from "./state.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
+import { requestMaintenance } from "./maintenance.mjs";
 
 import { checkDue, networkDisabled } from "./policy.mjs";
 export { CHECK_INTERVAL_MS, networkDisabled } from "./policy.mjs";
@@ -14,6 +16,14 @@ export async function performUpdate(root, { force = false, check = false, env =
   if (initial === null) throw new Error("ACC is not enrolled; run acc install first");
   const data = { running: initial.active.version, auto: initial.auto, pin: initial.pin,
     pending: initial.pending?.version ?? null, notice: initial.notice };
+  const maintenance = await readMaintenance(root);
+  if (MAINTENANCE_ACTIVE.includes(maintenance?.status)) {
+    if (check) return { ...data, checked: false, reason: "maintenance_pending",
+      maintenance: maintenanceReport(maintenance), notice: maintenanceNotice(maintenance) };
+    const response = await requestMaintenance({ root, control: initial, options: {},
+      runtime: { env, packageRoot: initial.pending?.root ?? initial.active.root, isInteractive: () => false } });
+    return { ...data, checked: false, ...response.data, notice: response.text };
+  }
   if (!force && !check && !initial.auto) return { ...data, checked: false, reason: "auto_off" };
   // Recovery is local; the hard no-network override must not strand a partial refresh.
   if (initial.pending && !check && (force || !networkDisabled(env))) {
@@ -42,16 +52,18 @@ export async function performUpdate(root, { force = false, check = false, env =
   return { ...checked, pending: generation.version, ...await activate(root, { env, ignorePid }) };
 }
 
-/** A single detached worker may wait cheaply for native clients to exit. */
+/** One poller may wait; the update lock stays available between its passes. */
 export async function runWorker(root, { force = false, env = process.env, wait = false, ignorePid = null } = {}) {
-  return withManagerLock(`${root}/worker`, async () => {
+  const poll = async () => {
     for (;;) {
-      const result = await performUpdate(root, { force, env, ignorePid });
+      const result = await withManagerLock(`${root}/worker`,
+        () => performUpdate(root, { force, env, ignorePid }), { timeoutMs: 100 });
       if (!wait || result.reason !== "processes_active") return result;
       await new Promise(resolve => setTimeout(resolve, 60_000));
       if (!(await readControl(root))?.auto || networkDisabled(env)) return result;
     }
-  }, { timeoutMs: 100 });
+  };
+  return wait ? withManagerLock(`${root}/worker/poller`, poll, { timeoutMs: 100 }) : poll();
 }
 
 export async function recordWorkerFailure(root, error) {

package/node_modules/@agents-can-communicate/cli/src/native-delivery-status.mjs

@@ -32,7 +32,7 @@ export function nativeRemediation(entry) {
       + "then run acc doctor here");
   }
   if (native.reasonCode === "native_endpoint_unavailable") {
-    steps.push(`${entry.displayName}: check the client's local delivery service setup; `
+    steps.push(entry.nativeSetup ?? `${entry.displayName}: check the client's local delivery service setup; `
       + "ACC does not start or restart that service");
   } else if (native.reasonCode === "native_session_unavailable") {
     steps.push(`${entry.displayName}: open a session connected to the client's local delivery service`);

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/core/src/receipts.mjs

@@ -10,6 +10,7 @@ export const SAFE_OFFER_ERROR_CODES = Object.freeze([
   "recipient_unavailable",
   "transport_error",
   "transport_rejected",
+  "transport_permission_denied",
   "unsupported_client_version",
 ]);
 

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/delivery-router/src/router.mjs

@@ -1,7 +1,7 @@
 import { refreshExpiredBinding } from "./refresh-binding.mjs";
 
 const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
-  "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected",
+  "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected", "transport_permission_denied",
   "unsupported_client_version"]);
 const NAMED_LIVE_TRANSPORTS = new Set(["claude-channel", "codex-app-server"]);
 

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/src/apply.mjs

@@ -35,8 +35,9 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         const createdDirectories = await missingArtifactParents({ home: context.home,
           artifacts: operation.artifacts });
         const installContext = { ...context,
+          clientVersion: operation.clientVersion, platform: operation.platform,
           requestedLivePolicy: operation.livePolicy ?? "off",
-          livePolicy: operation.effectiveLivePolicy ?? "off" };
+          livePolicy: operation.configuredLivePolicy ?? operation.effectiveLivePolicy ?? "off" };
         const outcome = await adapter.install(installContext);
         // A consented activation is applied after the adapter's own wiring, in
         // a fixed order; an explicit off takes a recorded one back first so the
@@ -49,7 +50,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           notes.push(...describeTeardown(report));
           retainedMechanisms = report.retainedMechanisms;
         }
-        let native = null;
+        let native = operation.retainedNativeActivation ?? null;
         let appendedRcBlock = false;
         if (operation.nativeActivation !== undefined) {
           const applied = await applyNativeActivation({ adapter,
@@ -103,6 +104,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           retainedNativeActivation: retainedMechanisms.length === 0 ? null
             : { ...operation.deactivation, mechanisms: retainedMechanisms } });
         results.operations.push({ ...operation, applied: true,
+          needsAction: outcome.needsAction ?? [],
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
           removedDirectories: directories.removed, keptDirectories: directories.kept,
           missingDirectories: directories.missing,

package/node_modules/@agents-can-communicate/installer/src/detect.mjs

@@ -118,7 +118,7 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
     // deterministic rather than dependent on registry order.
     .sort((left, right) => left.id.localeCompare(right.id))
     .map(async adapter => {
-      const entry = { adapterId: adapter.id, displayName: adapter.displayName,
+      const entry = { adapterId: adapter.id, displayName: adapter.displayName, platform,
         present: false, version: null, versionOutput: null, installed: false,
         diagnostics: [], needsAction: [], capabilities: effectiveCapabilities(adapter),
         deliveryDiagnostic: null, error: null };
@@ -146,7 +146,10 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
           ? "native_delivery_unsupported" : "version_unavailable");
 
       try {
-        const detected = await adapter.detect(context);
+        const detected = await adapter.detect({ ...context, clientVersion: entry.version,
+          platform, nativeDelivery: entry.nativeDelivery });
+        if (detected.outgoingDelivery) entry.outgoingDelivery = detected.outgoingDelivery;
+        if (detected.nativeSetup) entry.nativeSetup = detected.nativeSetup;
         entry.diagnostics = [...(detected.diagnostics ?? [])];
         // What a person has to do, as opposed to what is true. Adapters that
         // have nothing to ask for say nothing.