agents-can-communicate 0.1.18 → 0.2.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,7 @@ 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 { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 
 // Kept cohesive above 300 lines because every handler shares one fail-open
@@ -22,6 +23,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
@@ -163,8 +186,18 @@ async function openContext({ cwd, dataHome, runtime, env }) {
 
 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.
@@ -186,7 +219,10 @@ const HANDLERS = {
         ...metadata,
       });
       if (resumed !== null) {
-        return { accSessionId: resumed.sessionId, generation: resumed.generation };
+        await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+          accSessionId: resumed.sessionId, generation: resumed.generation, ...clientFacts });
+        return { accSessionId: resumed.sessionId, generation: resumed.generation,
+          ...clientFacts, capabilities };
       }
     }
     const session = await context.service.openSession({
@@ -204,8 +240,9 @@ const HANDLERS = {
       descriptor: context.descriptor,
     });
     await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
-      accSessionId: session.sessionId, generation: session.generation });
-    return { accSessionId: session.sessionId, generation: session.generation };
+      accSessionId: session.sessionId, generation: session.generation, ...clientFacts });
+    return { accSessionId: session.sessionId, generation: session.generation,
+      ...clientFacts, capabilities };
   },
 
   async heartbeat({ binding, context }) {
@@ -223,7 +260,7 @@ const HANDLERS = {
     return {};
   },
 
-  async beforeTurn({ binding, context, adapter }) {
+  async beforeTurn({ binding, context, adapter, adapterId }) {
     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.
@@ -239,13 +276,14 @@ const HANDLERS = {
       .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({
+    // 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
@@ -257,8 +295,12 @@ const HANDLERS = {
     // 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 : [],
+    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 };
@@ -266,64 +308,49 @@ const HANDLERS = {
     // 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
+    const projection = !hasStructuredRenderer
       ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
-        includedMessageIds: [], includedAttentionIds: [] }
+        offeredMessageIds: [], 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 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 candidate = [projection.text, visibleDegradation].filter(Boolean).join("\n");
-    const projected = Buffer.byteLength(candidate, "utf8")
-      <= (projectionOptions.budgetBytes ?? 6_000) ? candidate : projection.text;
+    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 };
     }
 
-    // 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}`));
-    }
+    // 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.
-    // 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.
+    // 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) };
-    if (failures.length === 0 && degradation === null) return outcome;
+    const writableOffers = outcome.stdout === "" ? [] : offerInputs;
+    if (degradation === null) return { ...outcome, offerInputs: writableOffers };
     return { ...outcome,
-      stderr: [outcome.stderr, degradation,
-        failures.length === 0 ? null
-          : `acc: delivery not recorded for ${failures.join(", ")}`]
-        .filter(Boolean).join("\n") };
+      stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
+      offerInputs: writableOffers };
   },
 
   async beforeTool({ binding, context, event, adapter }) {
@@ -394,8 +421,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 +441,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 +450,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 +477,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.2.0",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

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

@@ -1,4 +1,5 @@
-import { recordInstall, removeOwned } from "./ownership.mjs";
+import { finalizeRemoval, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwnedArtifacts } from "./ownership.mjs";
 
 /**
  * Carry out a plan, one adapter at a time.
@@ -30,26 +31,41 @@ 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);
         // 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 });
+          artifacts: operation.artifacts, createdDirectories });
         results.operations.push({ ...operation, applied: true,
-          changes: outcome.changes ?? [], diagnostics: outcome.diagnostics ?? [] });
+          changes: outcome.changes ?? [], diagnostics: [
+            ...(operation.deliveryDiagnostic === undefined
+              ? [] : [operation.deliveryDiagnostic]),
+            ...(outcome.diagnostics ?? []),
+          ] });
       } 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 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,
+          removedDirectories: directories.removed, keptDirectories: directories.kept,
+          missingDirectories: directories.missing,
           diagnostics: outcome.diagnostics ?? [] });
       }
     } catch (error) {

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

@@ -1,6 +1,8 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
+import { effectiveCapabilities } from "@agents-can-communicate/adapter-sdk";
+
 const run = promisify(execFile);
 
 const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
@@ -9,7 +11,7 @@ const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
 // "0.36.1", a banner with the number somewhere inside. The number is extracted
 // where it can be, and the raw line is kept either way - "present, version
 // unreadable" is a real state and hiding it would make the client look absent.
-const VERSION = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/;
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
 
 /**
  * Ask the operating system what a client reports as its version.
@@ -36,7 +38,8 @@ const withTimeout = (work, ms, label) => new Promise((resolve, reject) => {
  * letting it throw would hide the other three behind it.
  */
 export async function detectInstallation({ adapters, context, probe = spawnProbe,
-  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS }) {
+  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+  platform = `${process.platform}-${process.arch}` }) {
   const entries = await Promise.all([...adapters]
     // Ordered by id so two runs can be diffed, and so a plan built from this is
     // deterministic rather than dependent on registry order.
@@ -44,8 +47,8 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
     .map(async adapter => {
       const entry = { adapterId: adapter.id, displayName: adapter.displayName,
         present: false, version: null, versionOutput: null, installed: false,
-        diagnostics: [], needsAction: [], capabilities: adapter.capabilities ?? {},
-        error: null };
+        diagnostics: [], needsAction: [], capabilities: effectiveCapabilities(adapter),
+        deliveryDiagnostic: null, error: null };
 
       try {
         const output = await withTimeout(
@@ -62,10 +65,12 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = error.message;
       }
+      entry.capabilities = effectiveCapabilities(adapter,
+        { clientVersion: entry.version, platform });
 
       try {
         const detected = await adapter.detect(context);
-        entry.diagnostics = detected.diagnostics ?? [];
+        entry.diagnostics = [...(detected.diagnostics ?? [])];
         // What a person has to do, as opposed to what is true. Adapters that
         // have nothing to ask for say nothing.
         entry.needsAction = detected.needsAction ?? [];
@@ -77,6 +82,16 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = entry.error ?? error.message;
       }
+      if (entry.capabilities?.delivery?.livePush !== true
+        && typeof adapter.deliveryFallback?.diagnostic === "string") {
+        const nextTurnDowngraded = adapter.capabilities?.delivery?.nextTurn === true
+          && entry.capabilities?.delivery?.nextTurn !== true;
+        entry.deliveryDiagnostic = nextTurnDowngraded
+          ? `${adapter.displayName} ${entry.version ?? "unknown version"} has no certified `
+            + `next-turn delivery on ${platform}; ${adapter.deliveryFallback.diagnostic}`
+          : adapter.deliveryFallback.diagnostic;
+        entry.diagnostics.push(entry.deliveryDiagnostic);
+      }
       return entry;
     }));
   return entries;

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

@@ -2,5 +2,6 @@
 export { detectInstallation, spawnProbe } from "./detect.mjs";
 export { planInstallation } from "./plan.mjs";
 export { applyPlan } from "./apply.mjs";
-export { fingerprint, loadOwnership, recordInstall, removeOwned, treeFingerprint,
-  verifyOwned } from "./ownership.mjs";
+export { finalizeRemoval, fingerprint, loadOwnership, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwned, removeOwnedArtifacts, treeFingerprint, verifyOwned }
+  from "./ownership.mjs";

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

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

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

@@ -8,10 +8,14 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  * it previews is a decoration, and the operator would find out only afterwards.
  */
 export function planInstallation({ adapters, detected, context, action = "install",
-  recorded = [], accVersion = null, allowDowngrade = false, requested = [] }) {
+  recorded = [], accVersion = null, allowDowngrade = false, requested = [],
+  delivery = "off" }) {
   if (!["install", "uninstall"].includes(action)) {
     throw new AccError(EXIT.USAGE, `unknown installation action: ${action}`, { action });
   }
+  if (!["off", "actionable", "all"].includes(delivery)) {
+    throw new AccError(EXIT.USAGE, `unknown delivery policy: ${delivery}`, { delivery });
+  }
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
   // What ACC recorded writing, by client. For an uninstall this is the
   // authority rather than detection: the record is the only account of what was
@@ -82,7 +86,16 @@ export function planInstallation({ adapters, detected, context, action = "instal
     // From the record when the client is gone, because that is what was written
     // and so what will be removed. Asking the adapter instead would describe an
     // install for a machine this one no longer is.
-    const artifacts = (record?.artifacts ?? adapter.planInstall(context))
+    const liveDeliverySupported = entry.capabilities?.delivery?.livePush === true;
+    const effectiveLivePolicy = liveDeliverySupported ? delivery : "off";
+    const deliveryDiagnostic = action === "install" && delivery !== "off"
+      && !liveDeliverySupported
+      ? entry.deliveryDiagnostic ?? adapter.deliveryFallback?.diagnostic
+        ?? `${adapter.displayName ?? adapter.id} has no certified live delivery for this client; durable fallback remains active`
+      : null;
+    const installContext = { ...context, requestedLivePolicy: delivery,
+      livePolicy: effectiveLivePolicy };
+    const artifacts = (record?.artifacts ?? adapter.planInstall(installContext))
       .map(artifact => ({ path: artifact.path, kind: artifact.kind ?? "file" }))
       .sort((a, b) => a.path.localeCompare(b.path));
 
@@ -96,12 +109,16 @@ export function planInstallation({ adapters, detected, context, action = "instal
       // to be inferred from a client version that is null.
       clientPresent: entry.present === true,
       alreadyInstalled: entry.installed === true,
+      livePolicy: delivery,
+      effectiveLivePolicy,
+      ...(deliveryDiagnostic === null ? {} : { deliveryDiagnostic }),
       artifacts,
       // Said in the operator's terms, not in paths: which files ACC creates
       // outright and which belong to the user and are only edited.
       summary: [
         ...(entry.present ? [] : [`${adapter.displayName ?? adapter.id} is no longer on `
           + "this machine; removing what ACC recorded writing"]),
+        ...(deliveryDiagnostic === null ? [] : [deliveryDiagnostic]),
         ...artifacts.filter(a => a.kind === "tree")
           .map(a => `${action === "install" ? "create" : "remove"} ${a.path}`),
         ...artifacts.filter(a => a.kind === "merge")