agents-can-communicate 0.2.0 → 0.3.0

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

@@ -2,9 +2,13 @@
 // that survives between two ephemeral hook processes.
 export { CAPABILITY_SHAPE, assertCapabilities, defineAdapter } from "./capabilities.mjs";
 export { effectiveCapabilities, validateCertification } from "./certification.mjs";
+export { NATIVE_ACTIVATION_KINDS, NATIVE_BINDING_MODES, NATIVE_PLATFORMS, NATIVE_REASON_CODES,
+  compareStableVersions, evaluateNativeEligibility, parseStableVersion,
+  validateNativeActivationPlan, validateNativeDeliveryContract, validateNativeHandshake }
+  from "./native-delivery.mjs";
 export { EVENT_KINDS, NORMALIZED_EVENT_KEYS, normalizedEvent } from "./events.mjs";
-export { assertRunner, bakeSkillCommand, defaultCli, defaultRunner, removeInstalledTree,
-  runnerExists, writeHookShim }
+export { assertRunner, bakeSkillCommand, defaultBootstrap, defaultChannel, defaultCli,
+  defaultRunner, removeInstalledTree, runnerExists, writeHookShim }
   from "./hook-shim.mjs";
 export { BEGIN, END, removeTomlBlock, renderBlock, stripBlock, tomlString, writeTomlBlock }
   from "./toml-block.mjs";

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

@@ -0,0 +1,76 @@
+import path from "node:path";
+
+import { COMMAND_NAME, IDENTIFIER, NATIVE_ACTIVATION_KINDS, SHELL_SOURCE, assertReasonCode,
+  closed, deepFreeze, isPlainObject, isText, usage } from "./native-vocabulary.mjs";
+
+// A native activation plan is what an adapter hands the installer: closed
+// mechanisms made of executables and argument arrays, never shell source. The
+// generic installer records artifact ids and executes only the apply command
+// of a native service, and only during apply.
+
+function validateCommand(value, label) {
+  if (value === null) return null;
+  closed(value, ["executable", "args"], label);
+  if (!isText(value.executable) || !path.isAbsolute(value.executable)) {
+    usage(`${label} executable must be an absolute path`);
+  }
+  if (!Array.isArray(value.args) || value.args.some(arg => typeof arg !== "string"
+    || SHELL_SOURCE.test(arg))) {
+    usage(`${label} args must be plain argument strings, never shell source`);
+  }
+  return { executable: value.executable, args: [...value.args] };
+}
+
+function validateMechanism(mechanism, index) {
+  const label = `native activation mechanism ${index}`;
+  if (!isPlainObject(mechanism) || !NATIVE_ACTIVATION_KINDS.includes(mechanism.kind)) {
+    usage(`${label} kind must be one of ${NATIVE_ACTIVATION_KINDS.join(", ")}`);
+  }
+  if (mechanism.kind === "shell-bootstrap") {
+    closed(mechanism, ["kind", "command", "realExecutable", "prefixArgs"], label);
+    if (!isText(mechanism.command) || !COMMAND_NAME.test(mechanism.command)) {
+      usage(`${label} command must be a bare command name`);
+    }
+    if (!isText(mechanism.realExecutable) || !path.isAbsolute(mechanism.realExecutable)) {
+      usage(`${label} realExecutable must be an absolute path`);
+    }
+    if (!Array.isArray(mechanism.prefixArgs) || mechanism.prefixArgs.some(arg => !isText(arg)
+      || SHELL_SOURCE.test(arg))) {
+      usage(`${label} prefixArgs must be plain argument strings, never shell source`);
+    }
+    return { kind: mechanism.kind, command: mechanism.command,
+      realExecutable: mechanism.realExecutable, prefixArgs: [...mechanism.prefixArgs] };
+  }
+  if (mechanism.kind === "native-config") {
+    closed(mechanism, ["kind", "artifactIds"], label);
+    if (!Array.isArray(mechanism.artifactIds) || mechanism.artifactIds.length === 0
+      || mechanism.artifactIds.some(id => !isText(id) || !IDENTIFIER.test(id))) {
+      usage(`${label} artifactIds must be non-empty closed identifiers`);
+    }
+    return { kind: mechanism.kind, artifactIds: [...mechanism.artifactIds] };
+  }
+  closed(mechanism, ["kind", "serviceId", "preExisting", "applyCommand", "teardownCommand"], label);
+  if (!isText(mechanism.serviceId) || !IDENTIFIER.test(mechanism.serviceId)) {
+    usage(`${label} serviceId must be a closed identifier`);
+  }
+  if (typeof mechanism.preExisting !== "boolean") usage(`${label} preExisting must be a boolean`);
+  const commandLabel = key => `${label} ${key} must be null or { executable, args }`;
+  for (const key of ["applyCommand", "teardownCommand"]) {
+    if (mechanism[key] !== null && !isPlainObject(mechanism[key])) usage(commandLabel(key));
+  }
+  return { kind: mechanism.kind, serviceId: mechanism.serviceId, preExisting: mechanism.preExisting,
+    applyCommand: validateCommand(mechanism.applyCommand, `${label} applyCommand`),
+    teardownCommand: validateCommand(mechanism.teardownCommand, `${label} teardownCommand`) };
+}
+
+export function validateNativeActivationPlan(value) {
+  closed(value, ["eligible", "reasonCode", "mechanisms"], "native activation plan");
+  if (typeof value.eligible !== "boolean") usage("native activation plan eligible must be a boolean");
+  assertReasonCode(value.reasonCode, "native activation plan");
+  if (!Array.isArray(value.mechanisms)) usage("native activation plan mechanisms must be an array");
+  if (!value.eligible && value.mechanisms.length > 0) {
+    usage("an ineligible native activation plan must not carry mechanisms");
+  }
+  return deepFreeze({ eligible: value.eligible, reasonCode: value.reasonCode,
+    mechanisms: value.mechanisms.map(validateMechanism) });
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-delivery.mjs

@@ -0,0 +1,202 @@
+import { CONTRACT_ID, FINGERPRINT, HANDSHAKE_KEYS, KNOWN_BAD_REASON, NATIVE_ACTIVATION_KINDS,
+  NATIVE_BINDING_MODES, NATIVE_PLATFORMS, PROBE_KEYS, TIMESTAMP, assertModes,
+  assertReasonCode, closed, compareStableVersions, deepFreeze, isPlainObject, isText,
+  parseStableVersion, usage } from "./native-vocabulary.mjs";
+
+// The native-delivery compatibility contract: a per-platform minimum that is a
+// real passing capture, one or more anchors naming the captured protocol, an
+// explicit denylist, and the activation kinds an adapter may ask the installer
+// for. There is deliberately no maximum: a newer stable client is admitted only
+// when a current read-only probe and a per-session handshake confirm the same
+// protocol contract. Exact-version certification still governs every other
+// capability; this rule is used for native live delivery alone.
+
+export { NATIVE_ACTIVATION_KINDS, NATIVE_BINDING_MODES, NATIVE_PLATFORMS, NATIVE_REASON_CODES,
+  compareStableVersions, parseStableVersion } from "./native-vocabulary.mjs";
+export { validateNativeActivationPlan } from "./native-activation.mjs";
+
+const orderedModes = modes => NATIVE_BINDING_MODES.filter(mode => modes.includes(mode));
+
+export function validateNativeDeliveryContract(value, { certification, client }) {
+  closed(value, ["minimumByPlatform", "anchors", "knownBad", "activationKinds"], "nativeDelivery");
+  const minimums = value.minimumByPlatform;
+  if (!isPlainObject(minimums) || Object.keys(minimums).length === 0) {
+    usage("nativeDelivery.minimumByPlatform must map at least one captured platform to a version");
+  }
+  for (const [platform, version] of Object.entries(minimums)) {
+    if (!NATIVE_PLATFORMS.includes(platform)) {
+      usage(`nativeDelivery.minimumByPlatform names an unknown platform ${platform}`);
+    }
+    if (parseStableVersion(version) === null) {
+      usage(`nativeDelivery.minimumByPlatform ${platform} must be a stable version`);
+    }
+  }
+  if (!Array.isArray(value.anchors) || value.anchors.length === 0) {
+    usage("nativeDelivery.anchors must name at least one passing capture");
+  }
+  const anchors = value.anchors.map((anchor, index) => {
+    closed(anchor, ["platform", "version", "protocolContract"], "nativeDelivery anchor");
+    const minimum = minimums[anchor.platform];
+    if (minimum === undefined) {
+      usage(`nativeDelivery anchor ${index} platform ${anchor.platform} has no minimum`);
+    }
+    if (parseStableVersion(anchor.version) === null
+      || compareStableVersions(anchor.version, minimum) < 0) {
+      usage(`nativeDelivery anchor ${index} version must be a stable version at or above the minimum`);
+    }
+    if (!isText(anchor.protocolContract) || !CONTRACT_ID.test(anchor.protocolContract)) {
+      usage(`nativeDelivery anchor ${index} protocolContract must be a closed identifier`);
+    }
+    const proven = (certification?.evidence ?? []).some(item => item.result === "pass"
+      && item.capability === "delivery.livePush" && item.client === client
+      && item.version === anchor.version && item.platform === anchor.platform);
+    if (!proven) {
+      usage(`nativeDelivery anchor ${anchor.version} on ${anchor.platform} has no passing `
+        + "delivery.livePush certification", { anchor });
+    }
+    return { ...anchor };
+  });
+  for (const [platform, minimum] of Object.entries(minimums)) {
+    if (!anchors.some(anchor => anchor.platform === platform && anchor.version === minimum)) {
+      usage(`nativeDelivery minimum ${minimum} on ${platform} must be the first passing capture: `
+        + "no anchor matches it");
+    }
+  }
+  if (!Array.isArray(value.knownBad)) usage("nativeDelivery.knownBad must be an array");
+  const knownBad = value.knownBad.map(entry => {
+    const exact = isPlainObject(entry) && Object.hasOwn(entry, "version");
+    closed(entry, exact ? ["version", "reasonCode"] : ["from", "to", "reasonCode"],
+      "nativeDelivery.knownBad entry");
+    for (const key of exact ? ["version"] : ["from", "to"]) {
+      if (parseStableVersion(entry[key]) === null) {
+        usage(`nativeDelivery.knownBad ${key} must be a stable version`);
+      }
+    }
+    if (!exact && compareStableVersions(entry.from, entry.to) > 0) {
+      usage("nativeDelivery.knownBad interval from must not exceed to");
+    }
+    if (entry.reasonCode !== KNOWN_BAD_REASON) {
+      usage(`nativeDelivery.knownBad reasonCode must be ${KNOWN_BAD_REASON}`);
+    }
+    return { ...entry };
+  });
+  const kinds = value.activationKinds;
+  if (!Array.isArray(kinds) || kinds.length === 0 || new Set(kinds).size !== kinds.length
+    || kinds.some(kind => !NATIVE_ACTIVATION_KINDS.includes(kind))) {
+    usage(`nativeDelivery.activationKinds must be unique entries of ${NATIVE_ACTIVATION_KINDS.join(", ")}`);
+  }
+  return deepFreeze({ minimumByPlatform: { ...minimums }, anchors, knownBad,
+    activationKinds: [...kinds] });
+}
+
+function knownBadHit(contract, version) {
+  return contract.knownBad.some(entry => (Object.hasOwn(entry, "version")
+    ? compareStableVersions(version, entry.version) === 0
+    : compareStableVersions(version, entry.from) >= 0 && compareStableVersions(version, entry.to) <= 0));
+}
+
+// The static half of the rule: platform, minimum, prerelease, and denylist.
+function evaluateStatic(adapter, { clientVersion, platform }) {
+  const contract = adapter?.nativeDelivery;
+  if (contract === undefined) {
+    return { reasonCode: "native_delivery_unsupported", minimumVersion: null, protocolContract: null };
+  }
+  const minimumVersion = typeof platform === "string"
+    ? (contract.minimumByPlatform[platform] ?? null) : null;
+  if (minimumVersion === null) {
+    return { reasonCode: "platform_not_captured", minimumVersion: null, protocolContract: null };
+  }
+  const anchor = contract.anchors.find(item => item.platform === platform
+    && item.version === minimumVersion);
+  const facts = { minimumVersion, protocolContract: anchor.protocolContract };
+  if (!isText(clientVersion)) return { ...facts, reasonCode: "version_unavailable" };
+  if (parseStableVersion(clientVersion) === null) {
+    return { ...facts, reasonCode: "prerelease_not_captured" };
+  }
+  if (compareStableVersions(clientVersion, minimumVersion) < 0) {
+    return { ...facts, reasonCode: "below_minimum_version" };
+  }
+  if (knownBadHit(contract, clientVersion)) return { ...facts, reasonCode: "known_bad_version" };
+  return { ...facts, reasonCode: null };
+}
+
+function validateNativeProbe(probe) {
+  closed(probe, PROBE_KEYS, "native probe");
+  if (typeof probe.supported !== "boolean") usage("native probe supported must be a boolean");
+  if (probe.clientVersion !== null && !isText(probe.clientVersion)) {
+    usage("native probe clientVersion must be a string or null");
+  }
+  if (probe.protocolContract !== null
+    && (!isText(probe.protocolContract) || !CONTRACT_ID.test(probe.protocolContract))) {
+    usage("native probe protocolContract must be a closed identifier or null");
+  }
+  if (probe.executableFingerprint !== null
+    && (!isText(probe.executableFingerprint) || !FINGERPRINT.test(probe.executableFingerprint))) {
+    usage("native probe executableFingerprint must be sha256:<64 hex> or null");
+  }
+  assertModes(probe.modes, "native probe");
+  assertReasonCode(probe.reasonCode, "native probe");
+  return probe;
+}
+
+export function evaluateNativeEligibility(adapter, { clientVersion, platform, probe }) {
+  const rule = evaluateStatic(adapter, { clientVersion, platform });
+  const base = { eligible: false, reasonCode: null, minimumVersion: rule.minimumVersion,
+    protocolContract: rule.protocolContract, modes: [] };
+  const closedResult = reasonCode => deepFreeze({ ...base, reasonCode });
+  if (rule.reasonCode !== null) return closedResult(rule.reasonCode);
+  if (probe === null || probe === undefined) return closedResult("feature_probe_failed");
+  const facts = validateNativeProbe(probe);
+  if (facts.supported !== true) return closedResult(facts.reasonCode ?? "feature_probe_failed");
+  if (facts.clientVersion !== clientVersion) return closedResult("probe_version_mismatch");
+  if (facts.protocolContract !== rule.protocolContract) return closedResult("protocol_mismatch");
+  const modes = orderedModes(facts.modes);
+  if (!modes.includes("livePush")) return closedResult("feature_probe_failed");
+  return deepFreeze({ eligible: true, reasonCode: null, minimumVersion: rule.minimumVersion,
+    protocolContract: rule.protocolContract, modes });
+}
+
+function validateNativeHandshakeShape(handshake) {
+  closed(handshake, HANDSHAKE_KEYS, "native handshake");
+  if (typeof handshake.supported !== "boolean") usage("native handshake supported must be a boolean");
+  if (handshake.clientVersion !== null && !isText(handshake.clientVersion)) {
+    usage("native handshake clientVersion must be a string or null");
+  }
+  if (handshake.protocolContract !== null && (!isText(handshake.protocolContract)
+    || !CONTRACT_ID.test(handshake.protocolContract))) {
+    usage("native handshake protocolContract must be a closed identifier or null");
+  }
+  assertModes(handshake.modes, "native handshake");
+  assertReasonCode(handshake.reasonCode, "native handshake");
+  if (handshake.supported) {
+    if (!isText(handshake.opaqueEndpointRef)) {
+      usage("native handshake opaqueEndpointRef must be a non-empty opaque string");
+    }
+    if (!isText(handshake.leaseUntil) || !TIMESTAMP.test(handshake.leaseUntil)
+      || Number.isNaN(Date.parse(handshake.leaseUntil))) {
+      usage("native handshake leaseUntil must be a UTC timestamp");
+    }
+  } else if (handshake.opaqueEndpointRef !== null || handshake.leaseUntil !== null) {
+    usage("an unsupported native handshake carries no endpoint or lease");
+  }
+  return handshake;
+}
+
+// The per-session half: the same static rule again, then the adapter's live
+// handshake facts. The launch-time executable fingerprint stays probe-only.
+export function validateNativeHandshake(adapter, { clientVersion, platform, handshake }) {
+  const rule = evaluateStatic(adapter, { clientVersion, platform });
+  const base = { ok: false, reasonCode: null, protocolContract: rule.protocolContract, modes: [],
+    opaqueEndpointRef: null, leaseUntil: null };
+  const closedResult = reasonCode => deepFreeze({ ...base, reasonCode });
+  if (rule.reasonCode !== null) return closedResult(rule.reasonCode);
+  if (handshake === null || handshake === undefined) return closedResult("handshake_failed");
+  const facts = validateNativeHandshakeShape(handshake);
+  if (facts.supported !== true) return closedResult(facts.reasonCode ?? "handshake_failed");
+  if (facts.clientVersion !== clientVersion) return closedResult("handshake_version_mismatch");
+  if (facts.protocolContract !== rule.protocolContract) return closedResult("protocol_mismatch");
+  const modes = orderedModes(facts.modes);
+  if (!modes.includes("livePush")) return closedResult("handshake_failed");
+  return deepFreeze({ ok: true, reasonCode: null, protocolContract: rule.protocolContract, modes,
+    opaqueEndpointRef: facts.opaqueEndpointRef, leaseUntil: facts.leaseUntil });
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-vocabulary.mjs

@@ -0,0 +1,101 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// The closed vocabulary behind native delivery - binding modes, activation
+// kinds, captured platforms, reason codes - and the small validation
+// primitives every native module shares. Kept apart so the contract, the
+// activation plan, and later the hook helper all speak one dialect.
+
+export const NATIVE_BINDING_MODES = Object.freeze([
+  "livePush", "idleWake", "busyQueue", "replyRoute",
+]);
+
+export const NATIVE_ACTIVATION_KINDS = Object.freeze([
+  "shell-bootstrap", "native-config", "native-service",
+]);
+
+export const NATIVE_PLATFORMS = Object.freeze([
+  "darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-x64",
+]);
+
+// Every reason a client is not live, closed so doctor, hooks, and docs share
+// one vocabulary and vendor strings never leak through it.
+export const NATIVE_REASON_CODES = Object.freeze([
+  "native_delivery_unsupported", "platform_not_captured", "version_unavailable",
+  "prerelease_not_captured", "below_minimum_version", "known_bad_version",
+  "feature_probe_failed", "probe_timeout", "probe_version_mismatch", "protocol_mismatch",
+  "handshake_failed", "handshake_timeout", "handshake_version_mismatch",
+  "session_generation_stale", "client_process_unknown", "unsupported_shell",
+  // The transport works, but ACC cannot tell which workspace the session is in,
+  // so it has no honest way to address it. Measured on Codex 0.152.1: native
+  // delivery requires `--remote unix://`, and in that mode the hook payload and
+  // the App Server's own thread record both report the daemon's directory
+  // rather than the session's. Joining a session to whatever project the daemon
+  // happened to start in is worse than not joining it at all.
+  "workspace_identity_unavailable",
+]);
+
+export const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?$/;
+export const CONTRACT_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export const IDENTIFIER = /^[a-z][a-z0-9_-]*$/;
+export const COMMAND_NAME = /^[a-z][a-z0-9_.-]*$/;
+export const FINGERPRINT = /^sha256:[0-9a-f]{64}$/;
+export const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+export const SHELL_SOURCE = /[;&|<>`\n\0]|\$\(/;
+export const KNOWN_BAD_REASON = "known_bad_version";
+export const PROBE_KEYS = ["supported", "clientVersion", "protocolContract", "executableFingerprint",
+  "modes", "reasonCode"];
+export const HANDSHAKE_KEYS = ["supported", "clientVersion", "protocolContract", "modes",
+  "opaqueEndpointRef", "leaseUntil", "reasonCode"];
+
+export function usage(message, details = {}) {
+  throw new AccError(EXIT.USAGE, message, details);
+}
+
+export const isPlainObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+export const isText = value => typeof value === "string" && value !== "";
+
+export function closed(value, keys, label) {
+  if (!isPlainObject(value)) usage(`${label} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key)) usage(`unknown ${label} field ${key}`, { key });
+  }
+  for (const key of keys) {
+    if (!Object.hasOwn(value, key)) usage(`${label} requires ${key}`, { key });
+  }
+}
+
+export function deepFreeze(value) {
+  if (value === null || typeof value !== "object") return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+
+export function parseStableVersion(text) {
+  const match = typeof text === "string" ? STABLE_VERSION.exec(text) : null;
+  return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function compareStableVersions(left, right) {
+  const a = parseStableVersion(left);
+  const b = parseStableVersion(right);
+  if (a === null || b === null) {
+    usage("native version comparison needs two stable semantic versions", { left, right });
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function assertModes(modes, label) {
+  if (!Array.isArray(modes) || new Set(modes).size !== modes.length
+    || modes.some(mode => !NATIVE_BINDING_MODES.includes(mode))) {
+    usage(`${label} modes must be unique entries of ${NATIVE_BINDING_MODES.join(", ")}`);
+  }
+}
+
+export function assertReasonCode(value, label) {
+  if (value !== null && !NATIVE_REASON_CODES.includes(value)) {
+    usage(`${label} reasonCode must be null or a closed native reason code`, { reasonCode: value });
+  }
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/session-binding.mjs

@@ -21,13 +21,26 @@ const fileFor = (runtimeDir, harnessSessionId) => path.join(runtimeDir, "binding
  * plus the exact client facts observed at attach time - no prompt, transcript,
  * or harness state.
  */
+const isPid = value => Number.isInteger(value) && value > 0;
+
 export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSessionId,
-  generation, clientVersion, platform }) {
+  generation, clientVersion, platform, clientPid }) {
   const file = fileFor(runtimeDir, harnessSessionId);
   await mkdir(path.dirname(file), { recursive: true });
   const record = { schemaVersion: SCHEMA_VERSION, harnessSessionId, accSessionId, generation };
   if (typeof clientVersion === "string" && clientVersion !== "") record.clientVersion = clientVersion;
   if (typeof platform === "string" && platform !== "") record.platform = platform;
+  // The vendor process this session runs in, resolved once at SessionStart.
+  // A native endpoint is matched against it, so a binding without one can
+  // still heartbeat and deliver at the next turn but cannot go live until a
+  // fresh start resolves the process again.
+  if (clientPid !== undefined && clientPid !== null) {
+    if (!isPid(clientPid)) {
+      throw new AccError(EXIT.USAGE, "session binding clientPid must be a positive integer",
+        { clientPid });
+    }
+    record.clientPid = clientPid;
+  }
   const temporary = `${file}.${process.pid}.tmp`;
   await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   // Replace rather than append: re-attaching supersedes the old generation, and
@@ -60,6 +73,7 @@ export async function loadSessionBinding({ runtimeDir, harnessSessionId }) {
   const binding = { accSessionId: record.accSessionId, generation: record.generation };
   if (typeof record.clientVersion === "string") binding.clientVersion = record.clientVersion;
   if (typeof record.platform === "string") binding.platform = record.platform;
+  if (isPid(record.clientPid)) binding.clientPid = record.clientPid;
   return binding;
 }
 
@@ -98,7 +112,8 @@ export async function listSessionBindings({ runtimeDir }) {
       accSessionId: record.accSessionId, generation: record.generation,
       ...(typeof record.clientVersion === "string"
         ? { clientVersion: record.clientVersion } : {}),
-      ...(typeof record.platform === "string" ? { platform: record.platform } : {}) });
+      ...(typeof record.platform === "string" ? { platform: record.platform } : {}),
+      ...(isPid(record.clientPid) ? { clientPid: record.clientPid } : {}) });
   }
   return bindings;
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/cli/src/args.mjs

@@ -49,12 +49,12 @@ export const COMMANDS = Object.freeze({
   // `--downgrade` because an older acc first on PATH will otherwise rewire every
   // client to itself, and the only symptom is a guard behaving like the version
   // it came from.
-  install: { required: [], optional: ["adapter", "home", "delivery"],
+  install: { required: [], optional: ["home", "delivery"], repeated: ["adapter"],
     flags: ["dry-run", "downgrade"] },
   // `--dry-run` on both, because the preview was computed for either action and
   // only `install` could ask for it. Removal is the side that reaches into a
   // client's configuration - including a client that has left the machine.
-  uninstall: { required: [], optional: ["adapter", "home"], flags: ["dry-run"] },
+  uninstall: { required: [], optional: ["home"], repeated: ["adapter"], flags: ["dry-run"] },
   // Asking npm whether there is a newer ACC. The one command that touches the
   // network, and never on the hook path.
   update: { required: [], optional: [], flags: ["apply"] },

package/node_modules/@agents-can-communicate/cli/src/doctor-command.mjs

@@ -2,7 +2,7 @@ import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-import { detectInstallation, loadOwnership, verifyOwned }
+import { detectInstallation, livePolicyOf, loadOwnership, shellOf, verifyOwned }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
@@ -65,6 +65,21 @@ export function staleInstall({ recorded, running }) {
   return recorded === running ? null : { recorded, running };
 }
 
+const RUNTIME_LABEL = Object.freeze({ active: "active", waiting: "waiting for a live session",
+  inactive: "not enabled", degraded: "degraded", unsupported: "unsupported" });
+
+/** One human clause for a native-delivery state, next-action implied, never overclaiming. */
+export function describeNative(native) {
+  if (native.eligibility === "unsupported") {
+    return `unsupported${native.reasonCode ? ` (${native.reasonCode})` : ""}`;
+  }
+  const enabled = native.configured ? `enabled (${native.policy})` : "eligible, not enabled";
+  const runtime = RUNTIME_LABEL[native.runtime] ?? native.runtime;
+  const degraded = native.eligibility === "degraded" && native.reasonCode
+    ? ` - ${native.reasonCode}` : "";
+  return `${native.eligibility} - ${enabled} - ${runtime}${degraded}`;
+}
+
 /**
  * The runner version behind whatever ACC wrote for one client.
  *
@@ -101,15 +116,39 @@ async function findShims(root, depth) {
   return found;
 }
 
-async function diagnoseAdapters({ options, runtime }) {
+// One closed native-delivery report per adapter, built only from detection,
+// ownership, and later the live binding facts - never inferred from a
+// configured shim alone. eligibility is what the client could do; configured is
+// whether a policy was recorded; policy is that recorded policy; runtime is
+// filled in from current bindings; modes and reasonCode carry the closed
+// detail. runtime "active" never means the model read anything.
+function nativeState(detected, recordedPolicy) {
+  const native = detected ?? { state: "unsupported", reasonCode: "native_delivery_unsupported" };
+  const eligibility = native.state === "eligible" ? "eligible"
+    : native.state === "degraded" ? "degraded" : "unsupported";
+  const policy = recordedPolicy ?? "off";
+  const configured = policy !== "off";
+  const modes = native.state === "eligible" && Array.isArray(native.probe?.modes)
+    ? [...native.probe.modes] : [];
+  const runtime = eligibility === "unsupported" ? "unsupported"
+    : !configured ? "inactive" : "waiting";
+  return { eligibility, configured, policy, runtime, modes, reasonCode: native.reasonCode ?? null };
+}
+
+export async function diagnoseAdapters({ options, runtime, detect = detectInstallation }) {
   // The same home `acc install --home` writes to, or the real one. Reading a
   // different home than install wrote to reports every adapter as missing.
   const home = options?.home ?? runtime?.env?.HOME ?? homedir();
   const { data: dataHome } = platformPaths({ platform: runtime?.platform,
     env: runtime?.env ?? {} });
-  const clients = clientContext(home, path.join(dataHome, "acc"));
+  // The same shell and environment install reads, so detection plans the same
+  // shell bootstrap it would apply. Omitting them left detection with a null
+  // shell, which degrades every shell-bootstrap client to `unsupported_shell` -
+  // so a zsh machine with a working shim read as degraded on every run.
+  const clients = clientContext(home, path.join(dataHome, "acc"),
+    { shell: shellOf(runtime?.env ?? {}), env: runtime?.env ?? {} });
   const adapters = ALL_ADAPTERS();
-  const detected = await detectInstallation({ adapters, context: clients,
+  const detected = await detect({ adapters, context: clients,
     probeTimeoutMs: probeTimeout(runtime?.env) });
   const record = await loadOwnership({ dataHome });
   const running = typeof runtime?.version === "function"
@@ -162,7 +201,8 @@ async function diagnoseAdapters({ options, runtime }) {
     // an npm upgrade with no `acc install`, and reporting both is what makes the
     // divergence legible rather than hidden behind a single reassuring number.
     return { ...entry, stale, wired, bundleVersion, owned: { modified: owned.modified,
-      missing: owned.missing, intact: owned.intact.length }, remediation };
+      missing: owned.missing, intact: owned.intact.length },
+      nativeDelivery: nativeState(entry.nativeDelivery, livePolicyOf(installed)), remediation };
   }));
 }
 
@@ -214,6 +254,23 @@ export async function runDoctor({ options, context, runtime }) {
   // front.
   const service = context.service ?? await context.openService();
   const status = await service.collectStatus({});
+  // The runtime column is the only part that needs a live read: a current
+  // reachable binding for this adapter is "active", an expired one "degraded".
+  const bindingsByAdapter = new Map();
+  for (const binding of status.deliveryBindings ?? []) {
+    const existing = bindingsByAdapter.get(binding.adapterId);
+    if (existing === undefined || binding.reachable) bindingsByAdapter.set(binding.adapterId, binding);
+  }
+  for (const adapter of adapters) {
+    const native = adapter.nativeDelivery;
+    if (native.eligibility === "unsupported") continue;
+    const binding = bindingsByAdapter.get(adapter.adapterId);
+    native.runtime = binding === undefined ? (native.configured ? "waiting" : "inactive")
+      : binding.reachable ? "active" : "degraded";
+    if (binding !== undefined && Array.isArray(binding.availableModes)) {
+      native.modes = binding.availableModes.filter(mode => mode !== "nextTurn");
+    }
+  }
 
   const data = {
     workspaceId: context.descriptor.id,
@@ -241,6 +298,11 @@ export async function runDoctor({ options, context, runtime }) {
   ...adapters.filter(adapter => (adapter.present || adapter.installed)
     && typeof adapter.deliveryDiagnostic === "string")
     .map(adapter => `  ${adapter.deliveryDiagnostic}`),
+  // One concise native-delivery line per detected client, distinguishing
+  // eligibility, the recorded policy, and the live runtime state. It never
+  // claims that "active" means a model read anything.
+  ...adapters.filter(adapter => adapter.present)
+    .map(adapter => `  ${adapter.displayName} native delivery: ${describeNative(adapter.nativeDelivery)}`),
   ...data.remediation.map(line => `  ${line}`),
   // `0 of 4` is a true line that reads as a broken machine, and on an
   // MCP-only one it would read that way on every run forever. The server needs