agents-can-communicate 0.1.18 → 0.3.0

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

@@ -1,15 +1,26 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
+import { effectiveCapabilities, evaluateNativeEligibility, validateNativeActivationPlan }
+  from "@agents-can-communicate/adapter-sdk";
+
+import { resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";
+
 const run = promisify(execFile);
 
+// Reasons the client itself will not change within an install: unsupported,
+// as opposed to degraded, which a repaired probe or shell may lift.
+const STATIC_REASONS = new Set(["native_delivery_unsupported", "platform_not_captured",
+  "version_unavailable", "prerelease_not_captured", "below_minimum_version",
+  "known_bad_version"]);
+
 const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
 
 // Clients print their version in their own shape: "codex-cli 0.147.0", a bare
 // "0.36.1", a banner with the number somewhere inside. The number is extracted
 // where it can be, and the raw line is kept either way - "present, version
 // unreadable" is a real state and hiding it would make the client look absent.
-const VERSION = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/;
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
 
 /**
  * Ask the operating system what a client reports as its version.
@@ -35,8 +46,65 @@ const withTimeout = (work, ms, label) => new Promise((resolve, reject) => {
  * exactly the case someone is running this command to find out about, and
  * letting it throw would hide the other three behind it.
  */
+const unsupported = reasonCode => ({ state: "unsupported", reasonCode, realExecutable: null,
+  probe: null, eligibility: null, activationPlan: null });
+const degraded = (reasonCode, facts) => ({ state: "degraded", reasonCode, activationPlan: null,
+  ...facts });
+
+/**
+ * The read-only native-delivery report for one detected client: which
+ * executable a shim would exec, what the adapter's probe saw, the static
+ * verdict, and the activation the adapter would ask for. Version, help, and
+ * protocol probes only; never a service mutation.
+ */
+async function detectNative(adapter, entry, { context, platform, probeTimeoutMs, pathEnv }) {
+  if (adapter.nativeDelivery === undefined) return unsupported("native_delivery_unsupported");
+  try {
+    const realExecutable = await resolveExecutable(adapter.client.command, { pathEnv,
+      exclude: [typeof context?.stateRoot === "string" ? shimDirFor(context.stateRoot) : null] });
+    if (realExecutable === null) return unsupported("version_unavailable");
+    const facts = { realExecutable, probe: null, eligibility: null };
+    try {
+      facts.probe = await withTimeout(Promise.resolve(adapter.probeNativeDelivery({
+        realExecutable, timeoutMs: probeTimeoutMs })), probeTimeoutMs,
+      `${adapter.id} native probe`);
+    } catch {
+      facts.probe = null;
+    }
+    try {
+      facts.eligibility = evaluateNativeEligibility(adapter,
+        { clientVersion: entry.version, platform, probe: facts.probe });
+    } catch {
+      facts.eligibility = { eligible: false, reasonCode: "feature_probe_failed" };
+    }
+    if (facts.eligibility.eligible !== true) {
+      const reasonCode = facts.eligibility.reasonCode ?? "feature_probe_failed";
+      return STATIC_REASONS.has(reasonCode)
+        ? { ...unsupported(reasonCode), ...facts } : degraded(reasonCode, facts);
+    }
+    let activationPlan;
+    try {
+      activationPlan = validateNativeActivationPlan(await adapter.planNativeActivation({
+        detection: { realExecutable, version: entry.version, platform, probe: facts.probe },
+        context, livePolicy: null }));
+    } catch {
+      return degraded("feature_probe_failed", facts);
+    }
+    if (!activationPlan.eligible) return degraded(activationPlan.reasonCode, facts);
+    const shell = context?.shell ?? null;
+    if (activationPlan.mechanisms.some(item => item.kind === "shell-bootstrap") && shell !== "zsh") {
+      return { ...degraded("unsupported_shell", facts), activationPlan };
+    }
+    return { state: "eligible", reasonCode: null, ...facts, activationPlan };
+  } catch {
+    return degraded("feature_probe_failed", { realExecutable: null, probe: null, eligibility: null });
+  }
+}
+
 export async function detectInstallation({ adapters, context, probe = spawnProbe,
-  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS }) {
+  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+  platform = `${process.platform}-${process.arch}`,
+  pathEnv = context?.env?.PATH ?? process.env.PATH ?? "" }) {
   const entries = await Promise.all([...adapters]
     // Ordered by id so two runs can be diffed, and so a plan built from this is
     // deterministic rather than dependent on registry order.
@@ -44,8 +112,8 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
     .map(async adapter => {
       const entry = { adapterId: adapter.id, displayName: adapter.displayName,
         present: false, version: null, versionOutput: null, installed: false,
-        diagnostics: [], needsAction: [], capabilities: adapter.capabilities ?? {},
-        error: null };
+        diagnostics: [], needsAction: [], capabilities: effectiveCapabilities(adapter),
+        deliveryDiagnostic: null, error: null };
 
       try {
         const output = await withTimeout(
@@ -62,10 +130,16 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = error.message;
       }
+      entry.capabilities = effectiveCapabilities(adapter,
+        { clientVersion: entry.version, platform });
+      entry.nativeDelivery = entry.present
+        ? await detectNative(adapter, entry, { context, platform, probeTimeoutMs, pathEnv })
+        : unsupported(adapter.nativeDelivery === undefined
+          ? "native_delivery_unsupported" : "version_unavailable");
 
       try {
         const detected = await adapter.detect(context);
-        entry.diagnostics = detected.diagnostics ?? [];
+        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.
         entry.needsAction = detected.needsAction ?? [];
@@ -77,6 +151,16 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = entry.error ?? error.message;
       }
+      if (entry.nativeDelivery.state !== "eligible"
+        && typeof adapter.deliveryFallback?.diagnostic === "string") {
+        const nextTurnDowngraded = adapter.capabilities?.delivery?.nextTurn === true
+          && entry.capabilities?.delivery?.nextTurn !== true;
+        entry.deliveryDiagnostic = nextTurnDowngraded
+          ? `${adapter.displayName} ${entry.version ?? "unknown version"} has no certified `
+            + `next-turn delivery on ${platform}; ${adapter.deliveryFallback.diagnostic}`
+          : adapter.deliveryFallback.diagnostic;
+        entry.diagnostics.push(entry.deliveryDiagnostic);
+      }
       return entry;
     }));
   return entries;

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

@@ -2,5 +2,13 @@
 export { detectInstallation, spawnProbe } from "./detect.mjs";
 export { planInstallation } from "./plan.mjs";
 export { applyPlan } from "./apply.mjs";
-export { fingerprint, loadOwnership, recordInstall, removeOwned, treeFingerprint,
-  verifyOwned } from "./ownership.mjs";
+export { finalizeRemoval, fingerprint, loadOwnership, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwned, removeOwnedArtifacts, treeFingerprint, verifyOwned }
+  from "./ownership.mjs";
+export { BOOTSTRAP_CACHE_SCHEMA, FAILED_TTL_MS, SUPPORTED_TTL_MS, cachePathFor,
+  checkNativeBootstrap } from "./bootstrap-runtime.mjs";
+export { BLOCK_BEGIN, BLOCK_END, SHIM_MARKER, SHIM_POLICIES, SUPPORTED_SHELLS,
+  installShellBootstrap, locateBlock, planShellBootstrap, renderCommandShim, renderPathBlock,
+  shellLiteral, uninstallShellBootstrap, validateShimEntry } from "./shell-bootstrap.mjs";
+export { LIVE_POLICIES, describeActivation, describeDeactivation, livePolicyOf, rcFileFor,
+  resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";

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

@@ -0,0 +1,161 @@
+import { execFile } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import path from "node:path";
+
+import { defaultBootstrap } from "@agents-can-communicate/adapter-sdk";
+
+import { installShellBootstrap, planShellBootstrap, uninstallShellBootstrap }
+  from "./shell-bootstrap.mjs";
+
+// The installer's side of a native activation: which owned mechanisms an
+// eligible adapter asked for, how they are applied in a fixed order, what is
+// recorded so uninstall removes only ACC's bytes, and how a recorded
+// activation is taken back. Adapter-owned native config is written by the
+// adapter's own install; a vendor service is started only here, only during
+// apply, and only when it did not already exist.
+
+export const LIVE_POLICIES = Object.freeze(["off", "actionable", "all"]);
+const MECHANISM_ORDER = ["native-config", "native-service", "shell-bootstrap"];
+const SERVICE_TIMEOUT_MS = 15_000;
+
+export const livePolicyOf = install => (LIVE_POLICIES.includes(install?.nativeActivation?.livePolicy)
+  ? install.nativeActivation.livePolicy : "off");
+
+export const shellOf = env => {
+  const shell = env?.SHELL;
+  return typeof shell === "string" && shell !== "" ? path.basename(shell) : null;
+};
+export const shimDirFor = stateRoot => path.join(stateRoot, "bin");
+// `.zshrc`, deliberately, and that makes the shim interactive-only: zsh reads
+// this file for interactive shells and not for `zsh -lc` or a script. An
+// interactive launch is where a client session comes from, and putting the PATH
+// entry somewhere every shell reads would put ACC in front of a vendor command
+// in scripts and CI that never asked for it. Worth knowing when checking an
+// install: a non-interactive shell resolving the vendor binary directly is this
+// choice working, not a broken bootstrap.
+export const rcFileFor = (home, shell) => (shell === "zsh" && typeof home === "string"
+  ? path.join(home, ".zshrc") : null);
+
+// The vendor executable a shim will exec: the first executable on PATH that is
+// not ACC's own shim directory, so a shim never resolves itself.
+export async function resolveExecutable(command, { pathEnv = "", exclude = [] } = {}) {
+  const excluded = exclude.filter(Boolean).map(directory => path.resolve(directory));
+  for (const directory of String(pathEnv).split(path.delimiter).filter(Boolean)) {
+    if (excluded.includes(path.resolve(directory))) continue;
+    const candidate = path.join(directory, command);
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // not here; keep walking PATH
+    }
+  }
+  return null;
+}
+
+const defaultExec = (executable, args) => new Promise((resolve, reject) => {
+  execFile(executable, args, { timeout: SERVICE_TIMEOUT_MS, windowsHide: true },
+    error => (error === null ? resolve() : reject(error)));
+});
+
+const ordered = mechanisms => [...mechanisms].sort((left, right) =>
+  MECHANISM_ORDER.indexOf(left.kind) - MECHANISM_ORDER.indexOf(right.kind));
+
+const renderCommand = command => [command.executable, ...command.args].join(" ");
+
+/** What an activation would touch, in the operator's words. */
+export function describeActivation(activation) {
+  const lines = [];
+  for (const mechanism of ordered(activation.mechanisms)) {
+    if (mechanism.kind === "shell-bootstrap") {
+      lines.push(`create shim ${path.join(activation.shimDir, mechanism.command)} for `
+        + `${mechanism.command} (${activation.livePolicy} live delivery)`);
+      lines.push(`add a PATH block to ${activation.rcFile}`);
+    } else if (mechanism.kind === "native-config") {
+      lines.push(`write native config ${mechanism.artifactIds.join(", ")}`);
+    } else if (mechanism.preExisting) {
+      lines.push(`use the existing ${mechanism.serviceId} service`);
+    } else if (mechanism.applyCommand !== null) {
+      lines.push(`start the ${mechanism.serviceId} service: ${renderCommand(mechanism.applyCommand)}`);
+    }
+  }
+  return lines;
+}
+
+export function describeDeactivation(nativeActivation) {
+  const lines = [];
+  for (const mechanism of nativeActivation?.mechanisms ?? []) {
+    if (mechanism.kind === "shell-bootstrap") {
+      for (const file of mechanism.ownedFiles) lines.push(`remove shim ${file.path}`);
+      lines.push(`remove the PATH block from ${mechanism.rcFile.path} once no ACC shim remains`);
+    } else if (mechanism.kind === "native-service") {
+      lines.push(mechanism.createdByAcc && mechanism.teardownCommand !== null
+        ? `stop the ${mechanism.serviceId} service: ${renderCommand(mechanism.teardownCommand)}`
+        : `leave the ${mechanism.serviceId} service in place (${mechanism.createdByAcc
+          ? "no vendor teardown exists" : "it existed before ACC"})`);
+    }
+  }
+  return lines;
+}
+
+export async function applyNativeActivation({ adapter, activation, dataHome,
+  node = process.execPath, bootstrap = defaultBootstrap(), exec = defaultExec }) {
+  const record = { livePolicy: activation.livePolicy,
+    protocolContract: activation.protocolContract, mechanisms: [] };
+  let shell = null;
+  try {
+    for (const mechanism of ordered(activation.mechanisms)) {
+      if (mechanism.kind === "native-config") {
+        record.mechanisms.push({ kind: mechanism.kind, artifactIds: [...mechanism.artifactIds] });
+      } else if (mechanism.kind === "native-service") {
+        let createdByAcc = false;
+        if (!mechanism.preExisting && mechanism.applyCommand !== null) {
+          await exec(mechanism.applyCommand.executable, mechanism.applyCommand.args);
+          createdByAcc = true;
+        }
+        record.mechanisms.push({ kind: mechanism.kind, serviceId: mechanism.serviceId,
+          createdByAcc, teardownCommand: mechanism.teardownCommand });
+      } else {
+        const plan = planShellBootstrap({ shell: activation.shell, rcFile: activation.rcFile,
+          shimDir: activation.shimDir, runtime: { node, bootstrap, dataHome },
+          entries: [{ adapterId: adapter.id, command: mechanism.command,
+            realExecutable: mechanism.realExecutable, prefixArgs: mechanism.prefixArgs,
+            livePolicy: activation.livePolicy }] });
+        const result = await installShellBootstrap({ plan });
+        if (!result.ok) throw new Error(`shell bootstrap refused: ${result.reasonCode}`);
+        shell = result;
+        record.mechanisms.push({ kind: mechanism.kind, shimDir: activation.shimDir,
+          ownedFiles: result.shims.map(shim => ({ path: shim.path, sha256: shim.sha256 })),
+          rcFile: result.rcFile });
+      }
+    }
+    return { nativeActivation: record, appendedRcBlock: shell?.rcFile.appended === true };
+  } catch (error) {
+    // Only bytes this operation wrote are taken back; a pre-existing service
+    // or a user's own file is never touched on the way out.
+    if (shell !== null) {
+      await uninstallShellBootstrap({ ownership: { shims: shell.shims, shimDir: activation.shimDir,
+        rcFile: shell.rcFile } }).catch(() => null);
+    }
+    throw error;
+  }
+}
+
+export async function deactivateNative({ nativeActivation, exec = defaultExec }) {
+  const report = { shell: null, services: [] };
+  for (const mechanism of nativeActivation?.mechanisms ?? []) {
+    if (mechanism.kind === "shell-bootstrap") {
+      report.shell = await uninstallShellBootstrap({ ownership: { shims: mechanism.ownedFiles,
+        shimDir: mechanism.shimDir, rcFile: mechanism.rcFile } });
+    } else if (mechanism.kind === "native-service") {
+      if (mechanism.createdByAcc && mechanism.teardownCommand !== null) {
+        await exec(mechanism.teardownCommand.executable, mechanism.teardownCommand.args);
+        report.services.push({ serviceId: mechanism.serviceId, outcome: "stopped" });
+      } else {
+        report.services.push({ serviceId: mechanism.serviceId,
+          outcome: mechanism.createdByAcc ? "retained_no_teardown" : "retained_pre_existing" });
+      }
+    }
+  }
+  return report;
+}

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readdir, readFile, rename, rm, rmdir, writeFile }
+  from "node:fs/promises";
 import path from "node:path";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
@@ -109,7 +110,7 @@ async function saveOwnership({ dataHome, record }) {
  * runtime, and leaves the bundle inside the client exactly where it was.
  */
 export async function recordInstall({ dataHome, adapterId, version, accVersion = null,
-  artifacts }) {
+  artifacts, createdDirectories = [], nativeActivation = null }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -118,14 +119,103 @@ export async function recordInstall({ dataHome, adapterId, version, accVersion =
     sha256: artifact.kind === "merge" ? null : await fingerprintFor(artifact),
   })));
   const record = await loadOwnership({ dataHome });
+  const previous = record.installs.find(install => install.adapterId === adapterId);
+  const directories = [...new Set([
+    ...(previous?.createdDirectories ?? []), ...createdDirectories,
+  ])].sort((left, right) => left.split(path.sep).length - right.split(path.sep).length
+    || left.localeCompare(right));
   await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
     installs: [...record.installs.filter(install => install.adapterId !== adapterId),
-      { adapterId, version, accVersion, artifacts: stamped }] } });
+      { adapterId, version, accVersion, artifacts: stamped,
+        ...(directories.length === 0 ? {} : { createdDirectories: directories }),
+        // Present only for a consented native activation. A record without it
+        // - every 0.2 install - reads as live policy off and is never rewritten
+        // merely to add the field.
+        ...(nativeActivation === null ? {} : { nativeActivation }) }] } });
 }
 
 const installFor = (record, adapterId) =>
   record.installs.find(install => install.adapterId === adapterId) ?? null;
 
+const inside = (home, candidate) => {
+  const relative = path.relative(home, candidate);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+};
+
+async function hasSymlinkAncestor(home, candidate) {
+  let current = candidate;
+  while (inside(home, current)) {
+    const stat = await lstat(current).catch(error => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (stat?.isSymbolicLink()) return true;
+    current = path.dirname(current);
+  }
+  return false;
+}
+
+/** Return planned artifact parents that do not yet exist under the client home. */
+export async function missingArtifactParents({ home, artifacts }) {
+  if (typeof home !== "string") return [];
+  const root = path.resolve(home);
+  const missing = new Set();
+  for (const artifact of artifacts) {
+    let directory = path.dirname(path.resolve(artifact.path));
+    while (inside(root, directory)) {
+      try {
+        await lstat(directory);
+        break;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        missing.add(directory);
+        directory = path.dirname(directory);
+      }
+    }
+  }
+  return [...missing].sort((left, right) =>
+    left.split(path.sep).length - right.split(path.sep).length || left.localeCompare(right));
+}
+
+/** Remove recorded parents deepest-first, but only while each remains an empty directory. */
+export async function removeEmptyOwnedDirectories({ home, directories = [] }) {
+  const result = { removed: [], kept: [], missing: [] };
+  const root = typeof home === "string" ? path.resolve(home) : null;
+  const ordered = [...new Set(directories)].sort((left, right) =>
+    right.split(path.sep).length - left.split(path.sep).length || left.localeCompare(right));
+  for (const directory of ordered) {
+    if (root === null || !inside(root, path.resolve(directory))) {
+      result.kept.push(directory);
+      continue;
+    }
+    let stat;
+    try {
+      stat = await lstat(directory);
+    } catch (error) {
+      if (error.code === "ENOENT") { result.missing.push(directory); continue; }
+      throw error;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+      || await hasSymlinkAncestor(root, path.dirname(directory))) {
+      result.kept.push(directory);
+      continue;
+    }
+    try {
+      await rmdir(directory);
+      result.removed.push(directory);
+    } catch (error) {
+      if (["ENOTEMPTY", "EEXIST"].includes(error.code)) {
+        result.kept.push(directory);
+        continue;
+      }
+      if (error.code === "ENOENT") { result.missing.push(directory); continue; }
+      throw error;
+    }
+  }
+  return result;
+}
+
 /** Compare what was written against what is there now. Read-only. */
 export async function verifyOwned({ dataHome, adapterId }) {
   const install = installFor(await loadOwnership({ dataHome }), adapterId);
@@ -141,17 +231,12 @@ export async function verifyOwned({ dataHome, adapterId }) {
   return result;
 }
 
-/**
- * Remove the files this adapter's install wrote, and only those.
- *
- * A modified file is kept and reported. A merge artifact is never deleted at
- * all: the user owns that file and ACC owns some entries inside it, which is the
- * adapter's own uninstall to unpick because it knows the format.
- */
-export async function removeOwned({ dataHome, adapterId }) {
+/** Remove owned artifacts while retaining the record as retry authority. */
+export async function removeOwnedArtifacts({ dataHome, adapterId }) {
   const record = await loadOwnership({ dataHome });
   const install = installFor(record, adapterId);
-  const result = { adapterId, removed: [], kept: [], missing: [], delegated: [] };
+  const result = { adapterId, removed: [], kept: [], missing: [], delegated: [],
+    createdDirectories: install?.createdDirectories ?? [] };
   if (install === null) return result;
 
   for (const artifact of install.artifacts) {
@@ -163,7 +248,22 @@ export async function removeOwned({ dataHome, adapterId }) {
     result.removed.push(artifact.path);
   }
 
+  return result;
+}
+
+/** Forget one install only after every adapter-owned cleanup step succeeded. */
+export async function finalizeRemoval({ dataHome, adapterId }) {
+  const record = await loadOwnership({ dataHome });
+  if (installFor(record, adapterId) === null) return false;
+
   await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
     installs: record.installs.filter(entry => entry.adapterId !== adapterId) } });
+  return true;
+}
+
+/** Remove and finalize for callers that perform no delegated adapter cleanup. */
+export async function removeOwned(options) {
+  const result = await removeOwnedArtifacts(options);
+  await finalizeRemoval(options);
   return result;
 }

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

@@ -1,5 +1,8 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { LIVE_POLICIES, describeActivation, describeDeactivation, rcFileFor, shimDirFor }
+  from "./native-activation.mjs";
+
 /**
  * Turn a detection report into exactly what would happen.
  *
@@ -8,11 +11,27 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  * it previews is a decoration, and the operator would find out only afterwards.
  */
 export function planInstallation({ adapters, detected, context, action = "install",
-  recorded = [], accVersion = null, allowDowngrade = false, requested = [] }) {
+  recorded = [], accVersion = null, allowDowngrade = false, requested = [],
+  deliveryByAdapter = {} }) {
   if (!["install", "uninstall"].includes(action)) {
     throw new AccError(EXIT.USAGE, `unknown installation action: ${action}`, { action });
   }
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
+  // One explicit answer per selected client. A missing entry is off; a policy
+  // for a client that is not part of this run is a mistake to say out loud,
+  // not something to store for later.
+  if (deliveryByAdapter === null || typeof deliveryByAdapter !== "object") {
+    throw new AccError(EXIT.USAGE, "deliveryByAdapter must map adapter ids to policies");
+  }
+  for (const [adapterId, policy] of Object.entries(deliveryByAdapter)) {
+    if (!byId.has(adapterId)) {
+      throw new AccError(EXIT.USAGE,
+        `delivery policy names ${adapterId}, which is not part of this install`, { adapterId });
+    }
+    if (!LIVE_POLICIES.includes(policy)) {
+      throw new AccError(EXIT.USAGE, `unknown delivery policy: ${policy}`, { adapterId, policy });
+    }
+  }
   // What ACC recorded writing, by client. For an uninstall this is the
   // authority rather than detection: the record is the only account of what was
   // written, and a client's configuration directory outlives the client.
@@ -82,7 +101,32 @@ export function planInstallation({ adapters, detected, context, action = "instal
     // From the record when the client is gone, because that is what was written
     // and so what will be removed. Asking the adapter instead would describe an
     // install for a machine this one no longer is.
-    const artifacts = (record?.artifacts ?? adapter.planInstall(context))
+    const delivery = deliveryByAdapter[entry.adapterId] ?? "off";
+    const native = entry.nativeDelivery ?? null;
+    const liveDeliverySupported = native?.state === "eligible"
+      && native.activationPlan?.eligible === true;
+    const effectiveLivePolicy = liveDeliverySupported ? delivery : "off";
+    const deliveryDiagnostic = action === "install" && delivery !== "off"
+      && !liveDeliverySupported
+      ? entry.deliveryDiagnostic ?? adapter.deliveryFallback?.diagnostic
+        ?? `${adapter.displayName ?? adapter.id} cannot receive native delivery `
+          + `(${native?.reasonCode ?? "native_delivery_unsupported"}); durable fallback remains active`
+      : null;
+    const installContext = { ...context, requestedLivePolicy: delivery,
+      livePolicy: effectiveLivePolicy };
+    // A consented activation that this run keeps, activates, or takes back.
+    // Only an explicit off or an uninstall removes one; an absent record never
+    // creates one.
+    const previous = recordedById.get(entry.adapterId)?.nativeActivation ?? null;
+    const nativeActivation = action === "install" && effectiveLivePolicy !== "off"
+      ? { livePolicy: effectiveLivePolicy, protocolContract: native.eligibility.protocolContract,
+        shell: context?.shell ?? null, rcFile: rcFileFor(context?.home, context?.shell),
+        shimDir: typeof context?.stateRoot === "string" ? shimDirFor(context.stateRoot) : null,
+        mechanisms: native.activationPlan.mechanisms }
+      : null;
+    const deactivation = previous !== null
+      && (action === "uninstall" || effectiveLivePolicy === "off") ? previous : null;
+    const artifacts = (record?.artifacts ?? adapter.planInstall(installContext))
       .map(artifact => ({ path: artifact.path, kind: artifact.kind ?? "file" }))
       .sort((a, b) => a.path.localeCompare(b.path));
 
@@ -96,16 +140,24 @@ export function planInstallation({ adapters, detected, context, action = "instal
       // to be inferred from a client version that is null.
       clientPresent: entry.present === true,
       alreadyInstalled: entry.installed === true,
+      livePolicy: delivery,
+      effectiveLivePolicy,
+      ...(deliveryDiagnostic === null ? {} : { deliveryDiagnostic }),
+      ...(nativeActivation === null ? {} : { nativeActivation }),
+      ...(deactivation === null ? {} : { deactivation }),
       artifacts,
       // Said in the operator's terms, not in paths: which files ACC creates
       // outright and which belong to the user and are only edited.
       summary: [
         ...(entry.present ? [] : [`${adapter.displayName ?? adapter.id} is no longer on `
           + "this machine; removing what ACC recorded writing"]),
+        ...(deliveryDiagnostic === null ? [] : [deliveryDiagnostic]),
         ...artifacts.filter(a => a.kind === "tree")
           .map(a => `${action === "install" ? "create" : "remove"} ${a.path}`),
         ...artifacts.filter(a => a.kind === "merge")
           .map(a => `${action === "install" ? "add ACC entries to" : "remove ACC entries from"} ${a.path}`),
+        ...(nativeActivation === null ? [] : describeActivation(nativeActivation)),
+        ...(deactivation === null ? [] : describeDeactivation(deactivation)),
       ],
     });
   }