agents-can-communicate 0.1.18 → 0.3.0

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

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
+import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
 import { createId } from "@agents-can-communicate/protocol";
@@ -11,6 +11,8 @@ import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 
 import { resolveClientPid } from "./client-pid.mjs";
+import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
+import { establishNativeBinding, livePolicyFrom } from "./native-binding.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 
 // Kept cohesive above 300 lines because every handler shares one fail-open
@@ -22,6 +24,28 @@ import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs
 // let a call through than to make someone's session sit waiting on us.
 const DEFAULT_BUDGET_MS = 5_000;
 
+const byteLength = value => Buffer.byteLength(value, "utf8");
+
+function compactInboxRecovery(messages) {
+  const first = messages[0].messageId;
+  const rest = messages.length > 1 ? ` (+${messages.length - 1} more in \`acc inbox\`)` : "";
+  return `ACC: read pending peer message: \`acc inbox --message ${first}\`${rest}`;
+}
+
+function fitDegradation(projection, visibleDegradation, messages, budgetBytes) {
+  const full = [projection, visibleDegradation].filter(Boolean).join("\n");
+  if (byteLength(full) <= budgetBytes) return full;
+  const recovery = compactInboxRecovery(messages);
+  const exactRecovery = compactInboxRecovery(messages.slice(0, 1));
+  const withRecovery = [projection, recovery].filter(Boolean).join("\n");
+  if (byteLength(withRecovery) <= budgetBytes) return withRecovery;
+  const withExactRecovery = [projection, exactRecovery].filter(Boolean).join("\n");
+  if (byteLength(withExactRecovery) <= budgetBytes) return withExactRecovery;
+  if (byteLength(recovery) <= budgetBytes) return recovery;
+  if (byteLength(exactRecovery) <= budgetBytes) return exactRecovery;
+  return projection;
+}
+
 // Declared by this process on the session it opens, so peers can tell an idle
 // session from a dead one. Only one of the four clients fires a heartbeat event,
 // so the rest refresh here: on every turn, and during a long one whenever the
@@ -161,16 +185,130 @@ async function openContext({ cwd, dataHome, runtime, env }) {
     service: createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids }) };
 }
 
+// What this turn is shown and which complete groups it may commit as
+// offered. Runs after the heartbeat and the bounded native retry.
+async function projectTurn({ binding, context, adapter, adapterId }) {
+  const sync = await context.service.sync({ sessionId: binding.accSessionId,
+    cursor: null, scope: "delta" });
+
+  // Sync already carries the roster. Calling collectStatus here used to read
+  // the entire materialised store a second time on every prompt merely to
+  // rediscover this session's participant id.
+  const mine = sync.roster
+    .find(participant => participant.sessionId === binding.accSessionId);
+
+  // What peers have said to this participant and no model has been shown yet.
+  // Without this the projector's peer block never runs in production: an
+  // agent sees only the obligation attention line, not the durable body that
+  // may be offered after the stdout transport succeeds.
+  const delivery = await context.service.nextTurnDelivery({
+    workspaceId: context.descriptor.id,
+    participantId: mine?.participantId,
+    exceptSessionId: binding.accSessionId });
+  const messages = delivery.queuedMessages;
+
+  // Solo costs nothing: nothing to say means nothing printed, not a banner
+  // announcing that nobody else is here. But something already said to you is
+  // not nothing - the check used to run before the inbox was read, so the
+  // answer to your own request vanished the moment the agent working on it
+  // closed and left you as the only session.
+  if (sync.solo && messages.length === 0) return { stdout: "" };
+
+  // The ceiling a team agreed on in `acc.workspace.json`, or the default when
+  // there is no config. Validated by the protocol and, until now, never read:
+  // the projector was always called with its own default.
+  const effective = effectiveCapabilities(adapter, binding);
+  const hasStructuredRenderer = typeof adapter.renderContextResult === "function";
+  const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
+  const projectionInput = { ...sync, messages: canOfferNextTurn ? messages : [],
+    liveOfferedMessageIds: delivery.liveOfferedMessageIds,
+    roomMessageIds: delivery.roomMessageIds,
+    currentParticipantId: mine?.participantId };
+  const projectionOptions = {
+    budgetBytes: context.descriptor.policy?.contextBudgetBytes };
+  // Delivery is state, not text parsing. Peer-controlled bodies can imitate
+  // another message's visible header, so only projector metadata proves
+  // which complete groups survived the byte budget. A custom adapter without
+  // metadata may still inject text, but cannot advance a receipt from it.
+  const projection = !hasStructuredRenderer
+    ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
+      offeredMessageIds: [], includedAttentionIds: [] }
+    : await adapter.renderContextResult(projectionInput, projectionOptions);
+  const clientFactsKnown = typeof binding.clientVersion === "string"
+    && typeof binding.platform === "string";
+  const reason = !effective.delivery.nextTurn
+    ? clientFactsKnown
+      ? `client ${binding.clientVersion} on ${binding.platform} is not certified for nextTurn`
+      : "the client version or platform is unknown"
+    : !hasStructuredRenderer ? "this adapter lacks structured delivery metadata" : null;
+  const degradation = reason !== null && messages.length > 0
+    ? `acc: ${messages.length} pending message(s) withheld because ${reason}; read `
+      + `${messages[0].messageId} with acc inbox --message ${messages[0].messageId}` : null;
+  const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
+  const budgetBytes = projectionOptions.budgetBytes ?? 6_000;
+  const projected = degradation === null ? projection.text
+    : fitDegradation(projection.text, visibleDegradation, messages, budgetBytes);
+  if (projected === "") {
+    return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
+  }
+
+  // The renderer returns ids as metadata, never as text to parse. A peer body
+  // can imitate every visible label, so only a complete group selected by the
+  // projector is eligible for the post-write offer commit.
+  const offered = new Set(canOfferNextTurn ? projection.offeredMessageIds ?? [] : []);
+  const offerInputs = messages.filter(message => offered.has(message.messageId))
+    .map(message => ({ messageId: message.messageId,
+      recipientParticipantId: mine.participantId,
+      targetSessionId: binding.accSessionId, targetGeneration: binding.generation,
+      transport: "next-turn", adapterId,
+      clientVersion: binding.clientVersion }));
+  // Same again: Kimi Code shows the model a hook's raw stdout, while Gemini
+  // and Claude Code want an envelope and drop a bare string.
+  // The entry point owns the transport boundary. This handler only prepares
+  // offer inputs; recording them here would claim delivery before stdout's
+  // callback proves that the bytes crossed.
+  const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
+  const writableOffers = outcome.stdout === "" ? [] : offerInputs;
+  if (degradation === null) return { ...outcome, offerInputs: writableOffers };
+  return { ...outcome,
+    stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
+    offerInputs: writableOffers };
+}
+
+// One bounded, fail-open native handshake for this exact session generation.
+// The policy comes only from the environment an owned shell bootstrap
+// exported; an ordinary launch has none and stays durable.
+async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
+  deadline }) {
+  return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
+    livePolicy: livePolicyFrom(context.env), service: context.service, runtimeDir: paths.root,
+    clock: context.service.clock,
+    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
+}
+
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
-    readProcessTable }) {
-    const capabilities = adapter.capabilities ?? {};
+    readProcessTable, probeClientVersion, platform, deadline }) {
+    // A repeated start refreshes the client's version/platform. Remove the old
+    // certified facts before any probe, PID lookup, resume, or open can fail;
+    // keep only the generation identity needed for a successful resume.
+    if (binding !== null) {
+      await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        accSessionId: binding.accSessionId, generation: binding.generation });
+    }
+    const clientVersion = await probeClientVersion(adapter,
+      { timeoutMs: Math.max(1, Math.min(1_000, deadline - Date.now())) });
+    const clientFacts = { clientVersion, platform };
+    const capabilities = effectiveCapabilities(adapter, clientFacts);
     // Once per session, never per turn. A client that cannot be found yields
     // null, and the session is then judged by age alone - which is exactly the
     // behaviour every session had before this existed.
     const command = adapter.client?.command ?? null;
     const pid = command === null ? null
       : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
+    const clientPid = Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    const native = hookBinding => bindNative({ adapter, event, hookBinding, ...clientFacts,
+      context, paths, deadline });
     const metadata = {
       pid,
       enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
@@ -186,7 +324,12 @@ const HANDLERS = {
         ...metadata,
       });
       if (resumed !== null) {
-        return { accSessionId: resumed.sessionId, generation: resumed.generation };
+        const hookBinding = { accSessionId: resumed.sessionId, generation: resumed.generation,
+          ...clientFacts, clientPid };
+        await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+          ...hookBinding });
+        return { accSessionId: resumed.sessionId, generation: resumed.generation,
+          ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
       }
     }
     const session = await context.service.openSession({
@@ -203,9 +346,12 @@ const HANDLERS = {
       ...metadata,
       descriptor: context.descriptor,
     });
+    const hookBinding = { accSessionId: session.sessionId, generation: session.generation,
+      ...clientFacts, clientPid };
     await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
-      accSessionId: session.sessionId, generation: session.generation });
-    return { accSessionId: session.sessionId, generation: session.generation };
+      ...hookBinding });
+    return { accSessionId: session.sessionId, generation: session.generation,
+      ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
   },
 
   async heartbeat({ binding, context }) {
@@ -223,107 +369,21 @@ const HANDLERS = {
     return {};
   },
 
-  async beforeTurn({ binding, context, adapter }) {
+  async beforeTurn(input) {
+    const { binding, context, adapter, event, paths, deadline } = input;
     if (binding === null) return {};
     // A turn is the clearest sign a session is alive. Never a reason to fail:
     // this runs in front of somebody's prompt.
     await context.service.heartbeatSession({ sessionId: binding.accSessionId,
       generation: binding.generation }).catch(() => null);
-    const sync = await context.service.sync({ sessionId: binding.accSessionId,
-      cursor: null, scope: "delta" });
-
-    // Sync already carries the roster. Calling collectStatus here used to read
-    // the entire materialised store a second time on every prompt merely to
-    // rediscover this session's participant id.
-    const mine = sync.roster
-      .find(participant => participant.sessionId === binding.accSessionId);
-
-    // What peers have said to this participant and no model has been shown yet.
-    // Without this the projector's peer block never ran in production: an agent
-    // saw only the subject of a message through its attention line, and the
-    // `injected` delivery state was unreachable.
-    const messages = await context.service.pendingMessages({
-      workspaceId: context.descriptor.id,
-      participantId: mine?.participantId,
-      exceptSessionId: binding.accSessionId });
-
-    // Solo costs nothing: nothing to say means nothing printed, not a banner
-    // announcing that nobody else is here. But something already said to you is
-    // not nothing - the check used to run before the inbox was read, so the
-    // answer to your own request vanished the moment the agent working on it
-    // closed and left you as the only session.
-    if (sync.solo && messages.length === 0) return { stdout: "" };
-
-    // The ceiling a team agreed on in `acc.workspace.json`, or the default when
-    // there is no config. Validated by the protocol and, until now, never read:
-    // the projector was always called with its own default.
-    const tracksDelivery = typeof adapter.renderContextResult === "function";
-    const projectionInput = { ...sync, messages: tracksDelivery ? messages : [],
-      currentParticipantId: mine?.participantId };
-    const projectionOptions = {
-      budgetBytes: context.descriptor.policy?.contextBudgetBytes };
-    // Delivery is state, not text parsing. Peer-controlled bodies can imitate
-    // another message's visible header, so only projector metadata proves
-    // which complete groups survived the byte budget. A custom adapter without
-    // metadata may still inject text, but cannot advance a receipt from it.
-    const projection = !tracksDelivery
-      ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
-        includedMessageIds: [], includedAttentionIds: [] }
-      : await adapter.renderContextResult(projectionInput, projectionOptions);
-    const degradation = !tracksDelivery && messages.length > 0
-      ? `acc: ${messages.length} pending message(s) withheld because this adapter lacks `
-        + `structured delivery metadata; read ${messages[0].messageId} with `
-        + `acc inbox --message ${messages[0].messageId}`
-      : null;
-    const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
-    const candidate = [projection.text, visibleDegradation].filter(Boolean).join("\n");
-    const projected = Buffer.byteLength(candidate, "utf8")
-      <= (projectionOptions.budgetBytes ?? 6_000) ? candidate : projection.text;
-    if (projected === "") {
-      return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
-    }
-
-    // Only what the model was actually shown is recorded as delivered. The
-    // budget can leave a message out, and a receipt reading `injected` for text
-    // nobody saw is worse than one still reading `queued` - the sender would be
-    // told it landed. A message left behind stays queued and goes out next turn.
-    const failures = [];
-    const includedMessages = new Set(projection.includedMessageIds ?? []);
-    for (const message of messages) {
-      if (!includedMessages.has(message.messageId)) continue;
-      await context.service.markDelivery({ sessionId: binding.accSessionId,
-        generation: binding.generation, messageId: message.messageId,
-        recipientParticipantId: mine.participantId, state: "injected" })
-        .catch(error => failures.push(`${message.messageId}: ${error.message}`));
-    }
-    // A note carries no ack obligation, so after its one full showing it leaves
-    // a single low-priority `unread_note` breadcrumb. Advancing that receipt
-    // injected -> seen the turn the breadcrumb is shown is what makes it
-    // one-shot: next turn the note reads `seen`, the breadcrumb stays quiet, and
-    // a delivered decision is recoverable without becoming a standing nag - the
-    // noise a reader learns to skip. Only what was actually shown is advanced,
-    // for the same reason the loop above only records what fit.
-    const includedAttention = new Set(projection.includedAttentionIds ?? []);
-    for (const item of sync.attention ?? []) {
-      if (item.kind !== "unread_note") continue;
-      if (!includedAttention.has(item.sourceId)) continue;
-      await context.service.markDelivery({ sessionId: binding.accSessionId,
-        generation: binding.generation, messageId: item.sourceId,
-        recipientParticipantId: mine.participantId, state: "seen" })
-        .catch(error => failures.push(`${item.sourceId}: ${error.message}`));
-    }
-    // Same again: Kimi Code shows the model a hook's raw stdout, while Gemini
-    // and Claude Code want an envelope and drop a bare string.
-    // Reported rather than swallowed. The context still goes out - losing it
-    // over bookkeeping would be the worse trade - but a receipt that failed to
-    // advance has to be visible somewhere, and stdout belongs to the model.
-    const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
-    if (failures.length === 0 && degradation === null) return outcome;
-    return { ...outcome,
-      stderr: [outcome.stderr, degradation,
-        failures.length === 0 ? null
-          : `acc: delivery not recorded for ${failures.join(", ")}`]
-        .filter(Boolean).join("\n") };
+    // A native transport that became ready only after SessionStart is picked
+    // up here and a live lease is renewed: bounded, fail-open, never on a guard.
+    const nativeBinding = livePolicyFrom(context.env) === "off" ? undefined
+      : await bindNative({ adapter, event, hookBinding: binding,
+        clientVersion: binding.clientVersion, platform: binding.platform, context, paths,
+        deadline });
+    const turn = await projectTurn(input);
+    return nativeBinding === undefined ? turn : { ...turn, nativeBinding };
   },
 
   async beforeTool({ binding, context, event, adapter }) {
@@ -394,8 +454,12 @@ const HANDLERS = {
  */
 export async function runHook({ adapterId, payload, adapters, dataHome, env,
   runtime = defaultRuntime(), budgetMs = DEFAULT_BUDGET_MS,
-  readProcessTable = defaultReadProcessTable }) {
-  const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [] };
+  readProcessTable = defaultReadProcessTable,
+  probeClientVersion = defaultProbeClientVersion,
+  platform = `${process.platform}-${process.arch}` }) {
+  const deadline = Date.now() + budgetMs;
+  const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [], deadlineAt: deadline,
+    commitOffers: async () => {} };
   let timer = null;
   try {
     const adapter = adapters?.[adapterId];
@@ -410,7 +474,7 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     const work = handler === undefined
       ? Promise.resolve({})
       : handler({ event, context, adapter, adapterId, binding, paths: context.paths,
-        readProcessTable });
+        readProcessTable, probeClientVersion, platform, deadline });
 
     // The loser of a race is not cancelled, so the timer is cleared explicitly:
     // an outstanding one keeps the process alive long past its answer.
@@ -419,6 +483,24 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     });
     Object.assign(result, await Promise.race([work, budget]));
 
+    const offerInputs = result.offerInputs ?? [];
+    let commitPromise = null;
+    result.commitOffers = () => {
+      if (commitPromise !== null) return commitPromise;
+      commitPromise = (async () => {
+        for (const input of offerInputs) {
+          const remaining = deadline - Date.now();
+          if (remaining <= 0) throw new Error("hook budget exhausted before offer commit");
+          // The durable transaction owns deadline cancellation. Racing it here
+          // would only reject the public promise while the losing writer kept
+          // waiting and could publish later.
+          await context.service.recordOfferSucceeded({ ...input, deadlineAt: deadline });
+        }
+      })();
+      return commitPromise;
+    };
+    delete result.offerInputs;
+
     const status = await context.service.collectStatus({
       workspaceId: context.descriptor.id });
     result.sessions = status.participants.filter(p => p.presence !== "offline");
@@ -428,6 +510,9 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     result.reason = error.message;
     result.decision = "allow";
     result.stdout = "";
+    // A later failure may happen after a turn prepared offer inputs. Once the
+    // fail-open path withdraws stdout, no transport boundary remains to commit.
+    result.commitOffers = async () => {};
   } finally {
     if (timer !== null) clearTimeout(timer);
   }

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.18",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

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

@@ -1,4 +1,6 @@
-import { recordInstall, removeOwned } from "./ownership.mjs";
+import { applyNativeActivation, deactivateNative } from "./native-activation.mjs";
+import { finalizeRemoval, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwnedArtifacts } from "./ownership.mjs";
 
 /**
  * Carry out a plan, one adapter at a time.
@@ -13,7 +15,7 @@ import { recordInstall, removeOwned } from "./ownership.mjs";
  * three that work, plus the name of the one that did not.
  */
 export async function applyPlan({ plan, adapters, context, dataHome, dryRun = false,
-  accVersion = null }) {
+  accVersion = null, activation = {} }) {
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
   const results = { action: plan.action, dryRun, operations: [], skipped: plan.skipped,
     failed: [] };
@@ -30,27 +32,66 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
 
     try {
       if (plan.action === "install") {
-        const outcome = await adapter.install(context);
+        const createdDirectories = await missingArtifactParents({ home: context.home,
+          artifacts: operation.artifacts });
+        const installContext = { ...context,
+          requestedLivePolicy: operation.livePolicy ?? "off",
+          livePolicy: operation.effectiveLivePolicy ?? "off" };
+        const outcome = await adapter.install(installContext);
+        // A consented activation is applied after the adapter's own wiring, in
+        // a fixed order; an explicit off takes a recorded one back first so the
+        // record written below describes the machine as it now is.
+        const notes = [];
+        if (operation.deactivation !== undefined) {
+          const report = await deactivateNative({ nativeActivation: operation.deactivation,
+            ...activation });
+          notes.push(...describeTeardown(report));
+        }
+        let native = null;
+        let appendedRcBlock = false;
+        if (operation.nativeActivation !== undefined) {
+          const applied = await applyNativeActivation({ adapter,
+            activation: operation.nativeActivation, dataHome, ...activation });
+          native = applied.nativeActivation;
+          appendedRcBlock = applied.appendedRcBlock;
+        }
         // Recorded after the write, so a record never claims an install that
         // did not happen. The reverse order would leave uninstall trying to
         // remove files nothing created.
         await recordInstall({ dataHome, adapterId: adapter.id,
           version: operation.clientVersion ?? null, accVersion,
-          artifacts: operation.artifacts });
-        results.operations.push({ ...operation, applied: true,
-          changes: outcome.changes ?? [], diagnostics: outcome.diagnostics ?? [] });
+          artifacts: operation.artifacts, createdDirectories, nativeActivation: native });
+        results.operations.push({ ...operation, applied: true, appendedRcBlock,
+          changes: outcome.changes ?? [], diagnostics: [
+            ...(operation.deliveryDiagnostic === undefined
+              ? [] : [operation.deliveryDiagnostic]),
+            ...(outcome.diagnostics ?? []),
+            ...notes,
+          ] });
       } else {
-        // Ownership first: it decides what may be deleted, and the adapter's own
-        // uninstall then unpicks the entries it added to files the user owns.
-        const owned = await removeOwned({ dataHome, adapterId: adapter.id });
+        // Keep the record until every cleanup step succeeds. It is both the
+        // authority for deletion and the only durable recipe a retry has when
+        // the client or one of ACC's own artifacts is already gone.
+        const notes = [];
+        if (operation.deactivation !== undefined) {
+          const report = await deactivateNative({ nativeActivation: operation.deactivation,
+            ...activation });
+          notes.push(...describeTeardown(report));
+        }
+        const owned = await removeOwnedArtifacts({ dataHome, adapterId: adapter.id });
         // What ownership held back is passed on, because the adapter would
         // otherwise remove its own layout unconditionally and undo the decision.
         // The case that matters: someone put their own work inside a directory
         // ACC created, and a recognised path is not a reason to delete it.
         const outcome = await adapter.uninstall({ ...context, keep: owned.kept });
+        const directories = await removeEmptyOwnedDirectories({ home: context.home,
+          directories: owned.createdDirectories });
+        await finalizeRemoval({ dataHome, adapterId: adapter.id });
         results.operations.push({ ...operation, applied: true,
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
-          diagnostics: outcome.diagnostics ?? [] });
+          removedDirectories: directories.removed, keptDirectories: directories.kept,
+          missingDirectories: directories.missing,
+          diagnostics: [...(outcome.diagnostics ?? []), ...notes] });
       }
     } catch (error) {
       results.failed.push({ adapterId: operation.adapterId, error: error.message });
@@ -58,3 +99,22 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
   }
   return results;
 }
+
+// What a deactivation actually did, said truthfully: a retained service is
+// named as retained, a modified PATH block as kept.
+function describeTeardown(report) {
+  const lines = [];
+  if (report.shell !== null) {
+    for (const file of report.shell.removedShims) lines.push(`removed shim ${file}`);
+    for (const file of report.shell.keptShims) lines.push(`kept shim ${file} - changed since ACC wrote it`);
+    if (report.shell.rcBlock === "removed") lines.push("removed the ACC PATH block");
+    if (report.shell.rcBlock === "modified") lines.push("kept the ACC PATH block - changed since ACC wrote it");
+    if (report.shell.rcBlock === "kept") lines.push("kept the ACC PATH block - another ACC shim still uses it");
+  }
+  for (const service of report.services) {
+    lines.push(service.outcome === "stopped" ? `stopped the ${service.serviceId} service`
+      : `retained the ${service.serviceId} service (${service.outcome === "retained_pre_existing"
+        ? "it existed before ACC" : "no vendor teardown exists"})`);
+  }
+  return lines;
+}

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

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { evaluateNativeEligibility } from "@agents-can-communicate/adapter-sdk";
+
+// The launch-time check behind an owned shell shim. It answers one closed
+// question - may this exact executable receive native delivery? - from the
+// static minimum, a read-only adapter probe, and a keyed cache under ACC's own
+// data home. It never throws: a shim that cannot decide launches the vendor
+// command untouched, and this module is what makes "cannot decide" cheap.
+//
+// The cache key is the executable's identity - resolved path, symlink target,
+// inode, size, mtime, and full sha256 - so an upgrade or replacement is a miss
+// and an unchanged binary skips the version spawn and the probe. A cached
+// failure is short-lived; a repaired client is never disabled for long.
+
+export const BOOTSTRAP_CACHE_SCHEMA = 1;
+export const SUPPORTED_TTL_MS = 6 * 60 * 60 * 1_000;
+export const FAILED_TTL_MS = 5 * 60 * 1_000;
+const DEFAULT_TIMEOUT_MS = 750;
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
+
+export const cachePathFor = (dataHome, adapterId) =>
+  path.join(dataHome, "acc", "native-bootstrap", `${adapterId}.json`);
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(file).on("data", chunk => hash.update(chunk))
+      .on("error", reject).on("end", () => resolve(`sha256:${hash.digest("hex")}`));
+  });
+}
+
+async function executableIdentity(realExecutable) {
+  const target = await realpath(realExecutable);
+  const facts = await stat(target);
+  if (!facts.isFile()) throw new Error("not a file");
+  return { path: realExecutable, target, inode: facts.ino, size: facts.size,
+    mtimeMs: Math.floor(facts.mtimeMs), executableFingerprint: await sha256File(target) };
+}
+
+function withTimeout(work, ms, label) {
+  let timer = null;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`${label} timed out`),
+      { code: "ETIMEDOUT" })), ms);
+  });
+  return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+
+// Read-only: the client's own version command, nothing else.
+export function defaultReadVersion({ realExecutable, versionArgs, timeoutMs }) {
+  return new Promise(resolve => {
+    execFile(realExecutable, versionArgs, { timeout: timeoutMs, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error !== null) return resolve(null);
+        resolve(VERSION.exec(`${stdout}${stderr}`)?.[1] ?? null);
+      });
+  });
+}
+
+const sameIdentity = (left, right) => left !== undefined && right !== undefined
+  && ["path", "target", "inode", "size", "mtimeMs", "executableFingerprint"]
+    .every(key => left[key] === right[key]);
+
+async function loadCache(file) {
+  try {
+    const record = JSON.parse(await readFile(file, "utf8"));
+    return record?.schemaVersion === BOOTSTRAP_CACHE_SCHEMA ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCache(file, record) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+const closedOutcome = (supported, reasonCode) => Object.freeze({ supported, reasonCode });
+
+export async function checkNativeBootstrap({ adapter, realExecutable, platform, dataHome,
+  timeoutMs = DEFAULT_TIMEOUT_MS, clock = { now: () => new Date().toISOString() },
+  readVersion = defaultReadVersion }) {
+  try {
+    if (adapter?.nativeDelivery === undefined || typeof adapter.probeNativeDelivery !== "function") {
+      return closedOutcome(false, "native_delivery_unsupported");
+    }
+    const identity = await executableIdentity(realExecutable);
+    const file = cachePathFor(dataHome, adapter.id);
+    const now = Date.parse(clock.now());
+    const cached = await loadCache(file);
+    if (cached !== null && cached.adapterId === adapter.id && cached.platform === platform
+      && sameIdentity(cached.identity, identity) && Date.parse(cached.expiresAt) > now) {
+      return closedOutcome(cached.supported, cached.reasonCode);
+    }
+
+    const clientVersion = await withTimeout(readVersion({ realExecutable: identity.target,
+      versionArgs: adapter.client?.versionArgs ?? ["--version"], timeoutMs }), timeoutMs,
+    "version probe").catch(() => null);
+    let probe = null;
+    let reasonCode = null;
+    if (clientVersion !== null) {
+      try {
+        probe = await withTimeout(adapter.probeNativeDelivery({ realExecutable: identity.target,
+          timeoutMs }), timeoutMs, "native probe");
+      } catch (error) {
+        probe = null;
+        reasonCode = error?.code === "ETIMEDOUT" ? "probe_timeout" : "feature_probe_failed";
+      }
+    }
+    let eligibility;
+    try {
+      eligibility = evaluateNativeEligibility(adapter, { clientVersion, platform, probe });
+    } catch {
+      // A malformed probe is an adapter bug, and still not a reason to change
+      // the user's launch: it fails closed like any other probe failure.
+      eligibility = { eligible: false, reasonCode: "feature_probe_failed" };
+    }
+    const supported = eligibility.eligible === true;
+    // A probe that timed out or threw is reported as such rather than as the
+    // generic verdict the missing probe would otherwise produce.
+    const outcomeReason = supported ? null : (reasonCode ?? eligibility.reasonCode
+      ?? "feature_probe_failed");
+    // Only closed facts are stored: identity, versions, the eligibility verdict.
+    // Never command output, never a message body.
+    await saveCache(file, {
+      schemaVersion: BOOTSTRAP_CACHE_SCHEMA, adapterId: adapter.id, platform, identity,
+      clientVersion, supported, reasonCode: outcomeReason,
+      protocolContract: supported ? eligibility.protocolContract : null,
+      modes: supported ? [...eligibility.modes] : [],
+      checkedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + (supported ? SUPPORTED_TTL_MS : FAILED_TTL_MS)).toISOString(),
+    }).catch(() => null);
+    return closedOutcome(supported, outcomeReason);
+  } catch {
+    return closedOutcome(false, "feature_probe_failed");
+  }
+}