agents-can-communicate 0.4.1 → 0.4.2

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

@@ -2,10 +2,15 @@ import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-import { detectInstallation, livePolicyOf, loadOwnership, shellOf, verifyOwned }
+import { describeDeliveryFallback, detectInstallation, livePolicyOf, loadOwnership, shellOf, verifyOwned }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { describeNative, nativeRemediation, nativeState, updateNativeRuntime } from "./native-delivery-status.mjs";
+export { describeNative } from "./native-delivery-status.mjs";
+
+import { nativeSessionLines, updateNativeSessions } from "./native-session-diagnostics.mjs";
+
 import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs";
 import { describePresence } from "./main.mjs";
 import { platformPaths } from "./platform-paths.mjs";
@@ -66,21 +71,6 @@ 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.
  *
@@ -117,25 +107,6 @@ async function findShims(root, depth) {
   return found;
 }
 
-// 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.
@@ -203,7 +174,9 @@ export async function diagnoseAdapters({ options, runtime, detect = detectInstal
     // 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 },
-      nativeDelivery: nativeState(entry.nativeDelivery, livePolicyOf(installed)), remediation };
+      nativeDelivery: nativeState(entry.nativeDelivery, livePolicyOf(installed), {
+        contract: adapters.find(adapter => adapter.id === entry.adapterId)?.nativeDelivery,
+        activation: installed?.nativeActivation }), remediation };
   }));
 }
 
@@ -259,22 +232,10 @@ 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);
-  }
+  updateNativeRuntime(adapters, status.deliveryBindings);
+  await updateNativeSessions(adapters, { service, status, root, now: clock.now() });
   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");
-    }
+    adapter.remediation.push(...nativeRemediation(adapter));
   }
 
   const data = {
@@ -301,13 +262,17 @@ export async function runDoctor({ options, context, runtime }) {
   const text = [`store healthy; ${describePresence(status.counts)}; `
     + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`,
   ...adapters.filter(adapter => (adapter.present || adapter.installed)
+    && adapter.nativeDelivery.reasonCode === "native_delivery_unsupported"
     && 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)}`),
+    .map(adapter => `  ${adapter.displayName} live delivery: `
+      + `${describeNative(adapter.nativeDelivery, { clientVersion: adapter.version })}; `
+      + `fallback: ${describeDeliveryFallback(adapter)}`),
+  ...nativeSessionLines(adapters),
   ...(manager === null ? [] : [`  automatic updates ${manager.auto ? "on" : "off"}; ACC ${manager.active.version}`
     + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(manager.notice ? [`  ${manager.notice}`] : [])]),
   ...data.remediation.map(line => `  ${line}`),

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

@@ -148,8 +148,8 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => describeChanges(operation, home)),
   ...operations.filter(operation => operation.applied
-    && typeof operation.deliveryDiagnostic === "string")
-    .map(operation => `  ${operation.deliveryDiagnostic}`),
+    && typeof (operation.deliverySummary ?? operation.deliveryDiagnostic) === "string")
+    .map(operation => `  ${operation.deliverySummary ?? operation.deliveryDiagnostic}`),
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => (operation.needsAction ?? [])
       .map(step => `  ${operation.adapterId}: ${step}`)),
@@ -203,42 +203,21 @@ export function actedOn(result) {
 const isInteractive = runtime => typeof runtime.isInteractive === "function"
   && runtime.isInteractive() === true;
 
-/**
- * One default-No question per eligible client, asked only after detection has
- * finished and only when a person is at both ends of the terminal.
- *
- * Written for someone who has never heard of this project. It used to open with
- * "Enable native live delivery" over a list of internal artefact names, which
- * told a first-time reader neither what they would gain nor what it would cost -
- * and left out the part that matters most: saying yes makes their own `claude`
- * start with the vendor's `--dangerously-load-development-channels` flag. A
- * consent prompt that hides the loudest consequence is not consent.
- *
- * So the order is the reader's, not the installer's: what changes for them,
- * what it costs, what it touches, and that "no" costs them nothing.
- */
-function questionFor(entry, context, { onlyEligible = false } = {}) {
-  const bootstrap = entry.nativeDelivery.activationPlan.mechanisms
+// One default-No question per supported client. Disclose token use and any
+// repeated channel prompt; declining only promises a verified fallback.
+function questionFor(entry) {
+  const bootstrap = entry.nativeDelivery.activationPlan?.mechanisms
     .find(mechanism => mechanism.kind === "shell-bootstrap") ?? null;
-  // The presence of a flag is what makes this worth asking about at all: it is
-  // why the client will warn at every start from now on. Which flag it is, and
-  // that a shim adds it, are answers to a question nobody is asking here - the
-  // shim `exec`s and is gone, so nothing runs "through" acc afterwards either.
-  const flags = (bootstrap?.prefixArgs ?? []).filter(argument => argument.startsWith("--"));
-  void context;
-  // Why the default is No, and why only one client is being asked about, are
-  // the two questions the bare prompt provokes and never answered: a `[y/N]`
-  // reads as "not recommended" on its own, and a single question among four
-  // installed clients reads as an omission. Both have the same short answer.
-  const aside = ["experimental", ...(onlyEligible ? [`${entry.displayName} only`] : [])]
-    .join("; ");
+  const warns = (bootstrap?.prefixArgs ?? []).some(argument => argument.startsWith("--"));
   return [
-    `Let idle agents answer each other while you are away?  (${aside})`,
-    ...(flags.length === 0 || bootstrap === null
-      ? ["  Yes: they reply without waiting for you."]
-      : [`  Yes: they reply without waiting for you, and ${entry.displayName} asks you`,
-        "       to allow development channels every time it starts."]),
-    "  No:  messages still arrive, at the session's next turn.",
+    `Let ${entry.displayName} answer peer requests while idle? (experimental)`,
+    "  Yes: automatic turns can spend tokens without waiting for you.",
+    ...(warns ? ["       Allow development channels when prompted; check the client's startup notice."] : []),
+    ...(entry.nativeDelivery.state !== "eligible"
+      ? ["       Save consent now; delivery waits for an available client service."] : []),
+    entry.capabilities?.delivery?.nextTurn === true
+      ? "  No:  use next-turn hooks (when enabled) or acc inbox."
+      : "  No:  read messages with acc inbox; automatic next-turn delivery is unavailable.",
   ].join("\n");
 }
 
@@ -250,22 +229,18 @@ function questionFor(entry, context, { onlyEligible = false } = {}) {
  * client is off unless a person answers yes here, and a dry run or a
  * non-interactive stdin/stdout makes no interactive choice at all.
  */
-export async function decideDelivery({ options, detected, recorded, runtime, dryRun, context }) {
+export async function decideDelivery({ options, detected, recorded, runtime, dryRun }) {
   const explicit = options.delivery;
   if (explicit !== undefined && !LIVE_POLICIES.includes(explicit)) {
     throw new AccError(EXIT.USAGE, `unknown delivery policy: ${explicit}`, { delivery: explicit });
   }
   const recordedById = new Map(recorded.map(install => [install.adapterId, install]));
-  // Whether this client is the only one that could be asked at all. When it is,
-  // the question says so, because otherwise being asked about one of four
-  // installed clients looks like the other three were forgotten.
-  const onlyEligible = detected
-    .filter(candidate => candidate.nativeDelivery?.state === "eligible").length === 1;
   const deliveryByAdapter = {};
   const asked = [];
   let withheld = 0;
   for (const entry of detected) {
-    const eligible = entry.nativeDelivery?.state === "eligible";
+    const eligible = entry.nativeDelivery?.state === "eligible"
+      || entry.nativeDelivery?.consentAvailable === true;
     const previous = livePolicyOf(recordedById.get(entry.adapterId));
     if (explicit !== undefined) {
       deliveryByAdapter[entry.adapterId] = explicit;
@@ -275,7 +250,7 @@ export async function decideDelivery({ options, detected, recorded, runtime, dry
       deliveryByAdapter[entry.adapterId] = "off";
       if (eligible) withheld += 1;
     } else {
-      const yes = await runtime.confirm(questionFor(entry, context, { onlyEligible }),
+      const yes = await runtime.confirm(questionFor(entry),
         { input: runtime.input, output: runtime.output }) === true;
       deliveryByAdapter[entry.adapterId] = yes ? "actionable" : "off";
       asked.push(entry.adapterId);
@@ -333,7 +308,7 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   // Decided only after detection, from the operator's explicit answer, the
   // recorded consent, or a default of off; never from inference.
   const decided = action === "install"
-    ? await decideDelivery({ options, detected, recorded, runtime, dryRun, context })
+    ? await decideDelivery({ options, detected, recorded, runtime, dryRun })
     : { deliveryByAdapter: {}, asked: [], notes: [] };
   const plan = planInstallation({ adapters, detected, context, action, recorded,
     accVersion, allowDowngrade: options.downgrade === true, requested,

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

@@ -0,0 +1,88 @@
+import { describeNativeReason } from "@agents-can-communicate/installer";
+
+export function describeNative(native, { clientVersion } = {}) {
+  const differs = native.runtime === "active" && native.sessionPolicy
+    && native.sessionPolicy !== native.policy;
+  const enabled = (native.configured ? `enabled (${native.policy})` : "off")
+    + (differs ? " for new sessions" : "");
+  const availability = native.eligibility === "eligible" ? "available"
+    : `${native.eligibility === "unsupported" ? "unavailable" : "readiness unverified"}: `
+      + describeNativeReason(native.reasonCode, { clientVersion, minimumVersion: native.minimumVersion });
+  const runtime = native.runtime === "active"
+    ? `local transport active${differs ? ` (session policy: ${native.sessionPolicy})` : ""}`
+    : native.runtime === "degraded" ? "channel unreachable"
+      : native.configured && native.runtime === "waiting"
+        ? "no live channel bound in this workspace" : null;
+  return [availability, enabled, ...(runtime ? [runtime] : [])].join("; ");
+}
+
+export function nativeRemediation(entry) {
+  const native = entry.nativeDelivery;
+  if (!(entry.present || entry.installed) || native.eligibility === "unsupported") return [];
+  const steps = [];
+  if (!native.configured && native.runtime !== "active") {
+    steps.push(`acc install --adapter ${entry.adapterId} --delivery actionable`
+      + "  # opt in to automatic peer requests; may spend tokens");
+  } else if (native.configured && native.activation === "missing") {
+    steps.push(`acc install --adapter ${entry.adapterId}`
+      + "  # complete the missing native launch setup from a supported shell");
+  } else if (native.configured && native.runtime !== "active") {
+    steps.push(`${entry.displayName}: no verified live channel in this workspace; `
+      + "open a new terminal, start a new client session and check its integration/channel prompts; "
+      + "then run acc doctor here");
+  }
+  if (native.reasonCode === "native_endpoint_unavailable") {
+    steps.push(`${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`);
+  }
+  return steps;
+}
+
+// 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.
+export function nativeState(detected, recordedPolicy, { contract, activation } = {}) {
+  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";
+  const setupRequired = contract?.activationKinds?.some(kind => kind !== "native-service") === true;
+  return { eligibility, configured, policy, runtime, modes, reasonCode: native.reasonCode ?? null,
+    minimumVersion: native.eligibility?.minimumVersion ?? null,
+    policySource: contract?.policySource ?? null,
+    activation: !setupRequired ? "not_required"
+      : activation?.mechanisms?.length > 0 ? "recorded" : "missing", sessionPolicy: null };
+}
+
+// Native runtime is workspace-specific. A hook-only binding cannot prove it;
+// legacy launch policies may outlive the policy selected for future launches.
+export function updateNativeRuntime(adapters, bindings) {
+  const byAdapter = new Map();
+  for (const binding of bindings ?? []) {
+    if (!binding.availableModes?.includes("livePush")) continue;
+    const previous = byAdapter.get(binding.adapterId);
+    if (previous === undefined || binding.reachable) byAdapter.set(binding.adapterId, binding);
+  }
+  for (const entry of adapters) {
+    const native = entry.nativeDelivery;
+    if (native.eligibility === "unsupported") continue;
+    const binding = byAdapter.get(entry.adapterId);
+    const disabled = native.policySource === "installation-record" && !native.configured;
+    native.runtime = disabled ? "inactive"
+      : binding === undefined ? (native.configured ? "waiting" : "inactive")
+        : binding.reachable ? "active" : "degraded";
+    native.sessionPolicy = disabled || !binding ? null
+      : native.policySource === "installation-record" ? native.policy : binding.livePolicy;
+    if (binding) native.modes = binding.availableModes.filter(mode => mode !== "nextTurn");
+  }
+}

package/node_modules/@agents-can-communicate/cli/src/native-session-diagnostics.mjs

@@ -0,0 +1,64 @@
+import { listSessionBindings, loadNativeAttempt } from "@agents-can-communicate/adapter-sdk";
+import { describeNativeReason } from "@agents-can-communicate/installer";
+
+// Session diagnostics are read only here, never projected into agent context.
+// Verify the owner generation against core before attributing any last attempt.
+export async function updateNativeSessions(adapters, { service, status, root, now }) {
+  const owners = await listSessionBindings({ runtimeDir: root }).catch(() => []);
+  const transports = new Map();
+  for (const entry of adapters) {
+    const native = entry.nativeDelivery;
+    native.sessions = [];
+    if (native.reasonCode === "native_delivery_unsupported") continue;
+    for (const peer of status.participants.filter(p => p.harness === entry.adapterId)) {
+      const current = (await service.locateSession(peer.sessionId))?.record;
+      if (current?.state !== "open") continue;
+      const matches = owners.filter(owner => owner.accSessionId === peer.sessionId
+        && owner.generation === current.generation);
+      const owner = matches.length === 1 ? matches[0] : null;
+      if (!transports.has(peer.participantId)) {
+        transports.set(peer.participantId, await service.listDeliveryBindings({
+          participantId: peer.participantId, now, includeExpired: true }));
+      }
+      const binding = transports.get(peer.participantId).find(b => b.sessionId === peer.sessionId
+        && b.generation === current.generation && b.adapterId === entry.adapterId
+        && b.availableModes.includes("livePush"));
+      const runtime = native.policySource === "installation-record" && !native.configured
+        ? "inactive" : !binding ? "unbound"
+          : Date.parse(binding.leaseUntil) > Date.parse(now) ? "active" : "degraded";
+      native.sessions.push({ sessionId: peer.sessionId, participantId: peer.participantId,
+        presence: peer.presence, runtime,
+        lastAttempt: owner === null ? null : await loadNativeAttempt({ runtimeDir: root, ...owner }) });
+    }
+  }
+}
+
+const failures = {
+  client_process_unknown: "the client process could not be identified; start a new client session",
+  handshake_failed: "the session handshake failed; check the client's integration/channel setup",
+  handshake_timeout: "the session handshake timed out; check the local channel and retry on the next turn",
+  handshake_version_mismatch: "the session and CLI versions differ; start a new client session",
+  session_generation_stale: "the session was replaced during the handshake",
+};
+
+function describeAttempt(attempt) {
+  if (attempt === null) return "no native binding attempt observed for this generation; "
+    + "check client hooks; an older hook runtime or a failed diagnostic write can also leave no record";
+  let detail;
+  if (attempt.state === "off") {
+    const source = attempt.policySource === "bootstrap-environment" ? "launch" : "installation";
+    detail = attempt.policyStatus === "missing" ? `${source} delivery policy was absent`
+      : attempt.policyStatus === "invalid" ? `${source} delivery policy was invalid`
+        : attempt.policyStatus === "unavailable" ? `${source} delivery policy could not be read`
+          : `${source} delivery policy was off`;
+  } else if (attempt.state === "active") detail = "local handshake succeeded";
+  else detail = failures[attempt.reasonCode] ?? describeNativeReason(attempt.reasonCode);
+  return `last attempt ${attempt.at}: ${detail}`;
+}
+
+export function nativeSessionLines(adapters) {
+  return adapters.flatMap(entry => (entry.nativeDelivery.sessions ?? []).map(session =>
+    `  ${entry.displayName} session ${session.participantId} (${session.sessionId}): `
+    + `${session.runtime === "active" ? "local transport active" : session.runtime}; `
+    + describeAttempt(session.lastAttempt)));
+}

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

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

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

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

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

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

package/node_modules/@agents-can-communicate/hook-runner/src/native-attempt.mjs

@@ -0,0 +1,43 @@
+import { storeNativeAttempt } from "@agents-can-communicate/adapter-sdk";
+import { readInstalledLivePolicyState } from "@agents-can-communicate/installer";
+
+import { establishNativeBinding, LIVE_POLICIES, livePolicyFrom } from "./native-binding.mjs";
+
+// Reserve time for turn projection, status and output before optional disk I/O.
+export function nativeDiagnosticDeadline(hookDeadline) {
+  const now = Date.now();
+  return hookDeadline - now >= 750 ? now + 250 : null;
+}
+
+// The diagnostic has its own bounded writer; it never rewrites hook ownership.
+// A failed or slow disk leaves the functional hook result intact.
+export async function bindNative({ adapter, event, hookBinding, clientVersion, platform,
+  context, paths, deadline }) {
+  const assertBudget = () => {
+    if (Date.now() >= deadline) throw new Error("hook deadline expired");
+  };
+  assertBudget();
+  const policySource = adapter?.nativeDelivery?.policySource === "installation-record"
+    ? "installation-record" : "bootstrap-environment";
+  const raw = context.env?.ACC_NATIVE_DELIVERY_POLICY;
+  const { policy, policyStatus } = policySource === "installation-record"
+    ? await readInstalledLivePolicyState({ dataHome: context.dataHome, adapterId: adapter.id })
+    : { policy: livePolicyFrom(context.env), policyStatus: raw === undefined ? "missing"
+      : !LIVE_POLICIES.includes(raw) ? "invalid" : raw === "off" ? "off" : "enabled" };
+  assertBudget();
+  const result = await establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
+    livePolicy: policy, service: context.service, runtimeDir: paths.root,
+    clock: context.service.clock, env: context.env,
+    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
+  const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
+  if (adapter.nativeDelivery && diagnosticDeadline !== null) {
+    await storeNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+      accSessionId: hookBinding.accSessionId, generation: hookBinding.generation, deadlineAt: diagnosticDeadline, nativeAttempt: {
+        at: context.service.clock.now(), event: event.kind, state: result.state,
+        reasonCode: result.reasonCode, policy, policySource, policyStatus,
+        clientProcess: Number.isInteger(hookBinding.clientPid) && hookBinding.clientPid > 0
+          ? "identified" : "unknown",
+      } }).catch(() => {});
+  }
+  return result;
+}

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -3,10 +3,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
+import { clearNativeAttempt, clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
-import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
 import { AccError, createId } from "@agents-can-communicate/protocol";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
@@ -14,7 +13,7 @@ import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
 
 import { resolveClientPid } from "./client-pid.mjs";
 import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
-import { establishNativeBinding, livePolicyFrom } from "./native-binding.mjs";
+import { bindNative, nativeDiagnosticDeadline } from "./native-attempt.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 import { withSessionLifecycle } from "./session-lifecycle.mjs";
 import { appendToolOwner, ownerHeader, ownerOnlyOutcome } from "./owner-context.mjs";
@@ -305,22 +304,6 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
     offerInputs: writableOffers };
 }
 
-// One bounded, fail-open native handshake for this exact session generation.
-// New adapters read durable consent from their installation record; legacy
-// adapters keep the environment exported by an owned shell bootstrap.
-async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
-  deadline }) {
-  assertHookBudget(deadline);
-  const livePolicy = adapter?.nativeDelivery?.policySource === "installation-record"
-    ? await readInstalledLivePolicy({ dataHome: context.dataHome, adapterId: adapter.id })
-    : livePolicyFrom(context.env);
-  assertHookBudget(deadline);
-  return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
-    livePolicy, service: context.service, runtimeDir: paths.root,
-    clock: context.service.clock, env: context.env,
-    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
-}
-
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
     readProcessTable, probeClientVersion, platform, deadline }) {
@@ -356,12 +339,12 @@ const HANDLERS = {
       branch: context.descriptor.git?.branch ?? null,
     };
     if (event.kind === "beforeTurn" && binding !== null) {
-      // A real prompt may continue after finish closed this native owner's
-      // record. Recheck after the probes: a CLI replacement can run outside
-      // the native lifecycle lock. Never adopt that replacement's identity.
+      // A genuine prompt can resume after an ephemeral removal or a durable
+      // close. Recheck after probes: a CLI replacement can run outside the
+      // native lifecycle lock. Never adopt that replacement's identity.
       const previous = await context.service.locateSession(binding.accSessionId);
-      if (previous?.record.state !== "closed"
-        || previous.record.generation !== binding.generation) {
+      if (previous !== null && (previous.record.state !== "closed"
+        || previous.record.generation !== binding.generation)) {
         throw new Error("the completed hook owner changed during turn registration");
       }
     }
@@ -432,6 +415,11 @@ const HANDLERS = {
       await context.service.clearDeliveryBinding(owner);
     }
     await clearSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId });
+    const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
+    if (diagnosticDeadline !== null) {
+      await clearNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        ...binding, deadlineAt: diagnosticDeadline });
+    }
     return {};
   },
 
@@ -450,9 +438,11 @@ const HANDLERS = {
       return { ...turn, nativeBinding: started.nativeBinding };
     }
     const current = await context.service.locateSession(binding.accSessionId);
-    if (current?.record.state === "closed" && current.record.generation === binding.generation) {
-      // finish ends an ACC incarnation, not the native conversation. Only a
-      // genuine new user turn can start another one; tool hooks cannot. Reuse
+    if (current === null
+      || current.record.state === "closed" && current.record.generation === binding.generation) {
+      // A solo detach removes its ephemeral record; a durable close retains it.
+      // Both end the ACC incarnation while the native conversation may continue.
+      // Only a genuine user turn can start another one; tool hooks cannot. Reuse
       // the crash-safe opening path, retaining its full published client facts
       // and its single native handshake rather than binding a second time.
       const started = await HANDLERS.sessionStart(input);

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

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

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

@@ -0,0 +1,36 @@
+// Shared presentation of observed delivery facts. Vendor probes provide closed
+// reasons; installation and doctor must not turn a version floor into readiness.
+const REASONS = Object.freeze({
+  native_delivery_unsupported: "this adapter has no native delivery channel",
+  platform_not_captured: "native delivery is not verified on this platform",
+  version_unavailable: "the client version could not be verified",
+  prerelease_not_captured: "this client version is not a verified stable release",
+  below_minimum_version: "the client is below the native delivery minimum version",
+  known_bad_version: "this client version has a known native delivery failure",
+  native_endpoint_unavailable: "the client's local delivery service is unavailable",
+  native_session_unavailable: "the local delivery service has no loaded client session",
+  feature_probe_failed: "the native protocol probe did not succeed",
+  probe_timeout: "the native protocol probe timed out",
+  probe_version_mismatch: "the local service and CLI versions differ",
+  protocol_mismatch: "the local service did not confirm the required protocol",
+  unsupported_shell: "automatic launch setup requires zsh",
+});
+
+export function describeNativeReason(reason, { clientVersion, minimumVersion } = {}) {
+  if (reason === "below_minimum_version" && clientVersion && minimumVersion) {
+    return `client ${clientVersion} needs version ${minimumVersion} or newer for native delivery`;
+  }
+  return REASONS[reason] ?? reason ?? "readiness is unverified";
+}
+export const describeDeliveryFallback = entry => entry.capabilities?.delivery?.nextTurn === true
+  ? "next-turn hooks (when enabled) or acc inbox" : "acc inbox";
+
+export function describeInstallDelivery(entry, policy, effectivePolicy) {
+  const state = policy === "off" ? "off" : effectivePolicy === "off"
+    ? `consent saved (${policy}); not active` : `enabled (${policy}); waiting for a verified session`;
+  const reason = entry.nativeDelivery?.reasonCode;
+  return `${entry.displayName ?? entry.adapterId} live delivery: ${state}`
+    + (reason ? `; ${describeNativeReason(reason, { clientVersion: entry.version,
+      minimumVersion: entry.nativeDelivery?.eligibility?.minimumVersion })}` : "")
+    + `; fallback: ${describeDeliveryFallback(entry)}`;
+}