agents-can-communicate 0.10.3 → 0.11.0

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

@@ -6,6 +6,7 @@ import { AccError, CONFIG_FILENAME, EXIT, GENERIC_MESSAGE_KINDS, VALID_OBLIGATIO
   failure, ok }
   from "@agents-can-communicate/protocol";
 import { createCoordinationService } from "@agents-can-communicate/core";
+import { shellQuote } from "@agents-can-communicate/adapter-sdk";
 import { describeNativeReason } from "@agents-can-communicate/installer";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 
@@ -22,7 +23,7 @@ import { runDoctor } from "./doctor-command.mjs";
 import { runManagementDoctor } from "./managed-runtime/diagnostics.mjs";
 import { runStoreMigration } from "./store-migration-command.mjs";
 import { createGitProbe } from "./git-probe.mjs";
-import { canonicalClaim } from "./claim-spelling.mjs";
+import { runClaimCommand, runReleaseCommand } from "./claim-command.mjs";
 import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
 import { resolveOwner } from "./session-owner.mjs";
 import { discoverWorkspace } from "./workspace-discovery.mjs";
@@ -30,39 +31,6 @@ import { resolveSavedHookWorkspace } from "./hook-workspace.mjs";
 
 const DEFAULT_CADENCE_MS = 30_000;
 
-/**
- * The claim a caller means when they name a resource instead of an id.
- *
- * `acc claim` takes `--resource`; `acc release` took `--claim`. The asymmetry
- * cost every caller - a person and an agent alike - a round trip through
- * `acc status --json` to find an id they never chose. The id is still accepted,
- * and is still the precise answer when two sessions hold the same resource and
- * an authority is releasing someone else's.
- */
-async function claimOn(options, context) {
-  if (options.resource === undefined) {
-    throw new AccError(EXIT.USAGE,
-      "release needs the claim to give back: --resource is what you claimed, "
-      + "--claim is its id");
-  }
-  const resource = await canonicalClaim(options.resource, context.descriptor);
-  const { claims } = await context.service.collectStatus({});
-  // An authority releasing another session's claim is not looking for its own.
-  const mine = claims.filter(claim => claim.resource === resource
-    && (options.authority !== undefined || claim.ownerSessionId === options.session));
-
-  if (mine.length === 0) {
-    throw new AccError(EXIT.DATA, `no claim on ${resource} to release`,
-      { resource, held: claims.map(claim => claim.resource) });
-  }
-  if (mine.length > 1) {
-    throw new AccError(EXIT.DATA,
-      `${mine.length} claims on ${resource}; name the one you mean with --claim`,
-      { resource, claims: mine.map(claim => claim.claimId) });
-  }
-  return mine[0].claimId;
-}
-
 /**
  * Where this workspace's state lives, without reading a byte of it.
  *
@@ -162,7 +130,10 @@ export function recordedText(message, delivery) {
       ? `woke ${item.recipientParticipantId} via ${item.transport}; the message arrives with its next turn`
     : item.outcome === "queued"
       ? item.errorCode === "transport_permission_denied"
-        ? "live offer blocked by sender permissions; message remains queued; run acc doctor in the sending session"
+        ? "live offer blocked by sender permissions; message remains queued; retry the same command "
+          + "through approved execution"
+          + (typeof message.clientMessageId === "string"
+            ? ` with --client-message-id ${shellQuote(message.clientMessageId)}` : " with its original retry key")
         : item.errorCode === "no_live_transport"
           ? `${item.recipientParticipantId} has no live transport`
             + `${item.nativeReasonCode ? ` (${describeNativeReason(item.nativeReasonCode,
@@ -323,25 +294,8 @@ const HANDLERS = Object.freeze({
     return { data: intent, text: `intent: ${intent.summary}` };
   },
 
-  claim: async ({ options, context }) => {
-    const claim = await context.service.acquireClaim({ sessionId: options.session,
-      generation: options.generation,
-      resource: await canonicalClaim(options.resource, context.descriptor),
-      mode: options.mode ?? "exclusive", enforcement: options.enforcement ?? "advisory",
-      reason: options.reason ?? "unspecified",
-      leaseSeconds: options.lease ? positiveNumber(options.lease, "lease") : undefined,
-      descriptor: context.descriptor });
-    return { data: claim, text: `claimed ${claim.resource}` };
-  },
-
-  release: async ({ options, context }) => {
-    const claimId = options.claim ?? await claimOn(options, context);
-    const request = { claimId, sessionId: options.session,
-      generation: options.generation, authority: options.authority, reason: options.reason };
-    if (options.authority === undefined) await context.service.releaseClaim(request);
-    else await context.service.forceReleaseClaim(request);
-    return { data: { claimId }, text: `released ${claimId}` };
-  },
+  claim: runClaimCommand,
+  release: runReleaseCommand,
 
   message: async ({ options, context }) => {
     const kind = options.type ?? "note";

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/entry.mjs

@@ -32,6 +32,25 @@ export function invokedDirectly(url) {
   catch { return false; }
 }
 
+/** The display is an observation, not an admitted runtime user. A stable
+ * launcher resolves the active generation on every refresh, so an old plugin
+ * never retains a path that a same-contract update may reclaim. A concurrent
+ * replacement fails open and the next display refresh tries the new pointer. */
+export async function runIndicatorEntry({ managerRoot }) {
+  try {
+    const root = await canonicalManagerRoot(managerRoot);
+    const control = await readControl(root);
+    if (!control) throw new Error("indicator runtime missing");
+    await import(pathToFileURL(path.join(control.active.root, "bin", "acc-indicator.mjs")).href);
+  } catch {
+    const report = { health: "problem", reception: null, reasonCode: "indicator_unavailable",
+      label: "ACC !", detail: "ACC's installed indicator is unavailable.",
+      action: "Run acc update to finish runtime activation, or acc install --indicator on to repair it." };
+    process.stdout.write(process.argv.includes("--json") ? JSON.stringify(report) + "\n"
+      : "ACC ! · acc doctor\n");
+  }
+}
+
 function unavailable(kind) {
   // Never reflect control file content or payloads into a client diagnostic.
   if (kind === "acc-hook" || kind === "acc-antigravity-relay") {

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/launchers.mjs

@@ -16,6 +16,7 @@ async function durableFile(file, bytes, mode = 0o600) {
 export const stablePaths = root => ({
   cli: path.join(root, "bin", "acc.mjs"), runner: path.join(root, "bin", "acc-hook.mjs"),
   antigravityRelay: path.join(root, "bin", "acc-antigravity-relay.mjs"),
+  indicatorRunner: path.join(root, "bin", "acc-indicator.mjs"),
 });
 
 /** Publish immutable launcher modules, then atomically replace each tiny entry.
@@ -47,9 +48,10 @@ export async function writeLaunchers(root, packageRoot) {
   } finally { await removeTree(staging); }
   const bin = path.join(root, "bin");
   await managedDirectory(bin, { create: true });
-  for (const kind of ENTRY_KINDS) {
-    const bytes = `#!/usr/bin/env node\nimport { runEntry } from "../launchers/${id}/entry.mjs";\n`
-      + `await runEntry(${JSON.stringify({ kind, packageRoot, managerRoot: root, managedRequired: true })});\n`;
+  for (const kind of [...ENTRY_KINDS, "acc-indicator"]) {
+    const entry = kind === "acc-indicator" ? "runIndicatorEntry" : "runEntry";
+    const bytes = `#!/usr/bin/env node\nimport { ${entry} } from "../launchers/${id}/entry.mjs";\n`
+      + `await ${entry}(${JSON.stringify({ kind, packageRoot, managerRoot: root, managedRequired: true })});\n`;
     const temporary = path.join(bin, `.${randomUUID()}.tmp`);
     try {
       await durableFile(temporary, bytes, 0o700);

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

@@ -97,6 +97,8 @@ export async function updateNativeSessions(adapters, { service, status, root, no
 }
 
 const failures = {
+  transport_permission_denied: "this command cannot access the local delivery channel; "
+    + "check the sender's command permissions",
   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",

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

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

package/node_modules/@agents-can-communicate/core/src/claim-selectors.mjs

@@ -0,0 +1,62 @@
+import { AccError, EXIT, assertMatchableResource, assertPortableId,
+  assertResourceUri, normaliseResource } from "@agents-can-communicate/protocol";
+
+const usage = message => { throw new AccError(EXIT.USAGE, message); };
+
+export function uniqueList(value, name, normalise = item => item) {
+  if (!Array.isArray(value) || value.length === 0) usage(`${name} must be a nonempty array`);
+  const result = value.map(item => {
+    if (typeof item !== "string" || item.length === 0) usage(`${name} must contain nonempty strings`);
+    return normalise(item);
+  });
+  if (new Set(result).size !== result.length) usage(`${name} contains duplicate selectors`);
+  return result;
+}
+
+export function claimResources(value) {
+  return uniqueList(value, "resources", resource => {
+    assertMatchableResource(resource, usage);
+    const normalised = normaliseResource(resource);
+    try { return assertResourceUri(normalised, "resource"); }
+    catch (error) {
+      if (!(error instanceof AccError)) throw error;
+      throw new AccError(EXIT.USAGE, error.message, error.details);
+    }
+  });
+}
+
+export function releaseSelectors(input) {
+  const present = ["claimIds", "resources", "all"].filter(key => input[key] !== undefined);
+  if (present.length !== 1 || (present[0] === "all" && input.all !== true)) {
+    usage("release needs exactly one of claimIds, resources, or all: true");
+  }
+  if (input.authority !== undefined) usage("batch release does not accept force-release authority");
+  if (input.all === true) return { all: true };
+  if (input.resources !== undefined) return { resources: claimResources(input.resources) };
+  return { claimIds: uniqueList(input.claimIds, "claimIds", id => {
+    try { return assertPortableId(id, "claim id"); }
+    catch (error) {
+      if (!(error instanceof AccError)) throw error;
+      throw new AccError(EXIT.USAGE, error.message, error.details);
+    }
+  }) };
+}
+
+export function selectReleaseClaims(tx, selectors, sessionId) {
+  if (selectors.all === true) return tx.list("claim", claim => claim.ownerSessionId === sessionId);
+  if (selectors.claimIds !== undefined) return selectors.claimIds.map(claimId => {
+    const claim = tx.get("claim", claimId);
+    if (claim === null) throw new AccError(EXIT.CONFLICT, "the claim does not exist", { claimId });
+    return claim;
+  });
+  const claims = tx.list("claim");
+  return selectors.resources.map(resource => {
+    const mine = claims.filter(claim => claim.resource === resource && claim.ownerSessionId === sessionId);
+    if (mine.length === 0) throw new AccError(EXIT.DATA, `no claim on ${resource} to release`,
+      { resource, held: claims.map(claim => claim.resource) });
+    if (mine.length > 1) throw new AccError(EXIT.DATA,
+      `${mine.length} claims on ${resource}; name the one you mean with --claim`,
+      { resource, claims: mine.map(claim => claim.claimId) });
+    return mine[0];
+  });
+}

package/node_modules/@agents-can-communicate/core/src/claims.mjs

@@ -1,6 +1,7 @@
-import { AccError, EXIT, SCHEMA_VERSION, assertMatchableResource, createId,
-  normaliseResource, validateRecord } from "@agents-can-communicate/protocol";
+import { AccError, EXIT, SCHEMA_VERSION, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
 
+import { claimResources, releaseSelectors, selectReleaseClaims } from "./claim-selectors.mjs";
 import { ensureMaterialised } from "./materialisation.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
 
@@ -33,10 +34,11 @@ const isLive = (claim, now) => Date.parse(claim.expiresAt) > Date.parse(now);
 export function createClaimService(ports, sessions) {
   const { store, clock, ids, pidIsAlive } = ports;
 
-  async function requireOwner(input, action, tx) {
+  async function requireOwner(input, action, tx, allowEphemeral = false) {
     const current = tx === undefined
       ? (await sessions.locateSession(input.sessionId, input.workspaceId))?.record
-      : tx.get("session", input.sessionId);
+      : tx.get("session", input.sessionId)
+        ?? (allowEphemeral ? await store.ephemeral.get("session", input.sessionId) : null);
     if (current == null || current.state !== "open") {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} from a session that is not open`,
         { sessionId: input.sessionId });
@@ -65,63 +67,66 @@ export function createClaimService(ports, sessions) {
     });
   }
 
-  async function acquireClaim(input) {
+  async function acquire(input, resources, batch) {
     const session = await requireOwner(input, "claim");
-    // One name for one file, decided here rather than at each surface, so a
-    // claim taken over MCP and one taken from the CLI mean the same thing - and
-    // a shape that could never match is refused rather than stored.
-    assertMatchableResource(input.resource, message => {
-      throw new AccError(EXIT.USAGE, message, { resource: input.resource });
-    });
-    const resource = normaliseResource(input.resource);
+    resources = claimResources(resources);
     const workspaceId = session.workspaceId;
     await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
       reason: "durable_object" });
-    const now = clock.now();
-    const expiresAt = new Date(Date.parse(now) + (input.leaseSeconds ?? 1800) * 1000)
-      .toISOString();
-    // Only to name the owner of a conflicting claim in the error.
-    const snapshot = await store.snapshot(workspaceId, { kinds: ["session"] });
-
-    let record = null;
-    await store.transaction(async tx => {
+    return store.transaction(async tx => {
       await requireOwner(input, "claim", tx);
-      const live = tx.list("claim", claim => isLive(claim, now));
-      // This session's own claim on this resource, live or lapsed. Looking only
-      // among the live ones left the expired record behind and made a fresh one
-      // beside it, so taking a resource back after a lease ran out reported
-      // success while the workspace still held a dead claim saying otherwise -
-      // and the owner went on being told its claim had run out.
-      const mine = tx.list("claim", claim => claim.ownerSessionId === session.sessionId
-        && claim.resource === resource).at(0);
-      const blocking = live.find(claim => overlaps(claim.resource, resource)
-        && claim.ownerSessionId !== session.sessionId
-        && (claim.mode === "exclusive" || input.mode === "exclusive"));
-      if (blocking !== undefined) throw conflictWith(blocking, session, now, snapshot.sessions);
-
-      const claimId = mine?.claimId ?? createId("claim");
-      record = validateRecord("claim", {
-        schemaVersion: SCHEMA_VERSION,
-        claimId,
-        workspaceId,
-        ownerSessionId: session.sessionId,
-        resource,
-        mode: input.mode ?? "exclusive",
-        enforcement: input.enforcement ?? "advisory",
-        reason: input.reason,
-        // A lapsed claim taken again is a new period of holding it, not a
-        // continuation of one that ended.
-        acquiredAt: mine !== undefined && isLive(mine, now) ? mine.acquiredAt : now,
-        expiresAt,
-        generation: ids.next("generation"),
+      const now = clock.now();
+      const expiresAt = new Date(Date.parse(now) + (input.leaseSeconds ?? 1800) * 1000)
+        .toISOString();
+      const existing = tx.list("claim");
+      const live = existing.filter(claim => isLive(claim, now));
+      const mode = input.mode ?? "exclusive";
+      const conflicts = resources.flatMap(resource => live
+        .filter(claim => overlaps(claim.resource, resource)
+          && claim.ownerSessionId !== session.sessionId
+          && (claim.mode === "exclusive" || mode === "exclusive"))
+        .map(claim => ({ requestedResource: resource,
+          ...conflictWith(claim, session, now, tx.list("session")).details })));
+      if (conflicts.length > 0) {
+        if (!batch) {
+          const { requestedResource, ...details } = conflicts[0];
+          throw new AccError(EXIT.CONFLICT, "the resource is already claimed", details);
+        }
+        const message = "batch claim conflicts:\n" + conflicts.map(conflict =>
+          `${conflict.requestedResource} overlaps ${conflict.resource}, held by ${conflict.ownerSessionId}`)
+          .join("\n");
+        throw new AccError(EXIT.CONFLICT, message, { conflicts });
+      }
+      // Validate every record before staging a write, including renewals.
+      const records = resources.map(resource => {
+        const mine = existing.find(claim => claim.ownerSessionId === session.sessionId
+          && claim.resource === resource);
+        const claimId = mine?.claimId ?? createId("claim");
+        return { mine, record: validateRecord("claim", {
+          schemaVersion: SCHEMA_VERSION,
+          claimId,
+          workspaceId,
+          ownerSessionId: session.sessionId,
+          resource,
+          mode,
+          enforcement: input.enforcement ?? "advisory",
+          reason: input.reason,
+          // Reuse a lapsed record, but start a new period of holding it.
+          acquiredAt: mine !== undefined && isLive(mine, now) ? mine.acquiredAt : now,
+          expiresAt,
+          generation: ids.next("generation"),
+        }) };
       });
-      tx.put("claim", claimId, record, tx.generationOf("claim", claimId));
-      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
-        actorSessionId: session.sessionId, type: mine === undefined ? "claim.acquired"
-          : "claim.renewed", occurredAt: now,
-        payload: { claimId, resource, mode: record.mode } });
+      for (const { mine, record } of records) {
+        const { claimId, resource } = record;
+        tx.put("claim", claimId, record, tx.generationOf("claim", claimId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+          actorSessionId: session.sessionId, type: mine === undefined ? "claim.acquired"
+            : "claim.renewed", occurredAt: now,
+          payload: { claimId, resource, mode: record.mode } });
+      }
+      return records.map(item => item.record);
     }, { kinds: ["session", "claim"] });
-    return record;
   }
 
   async function renewClaim(input) {
@@ -146,40 +151,42 @@ export function createClaimService(ports, sessions) {
     return record;
   }
 
-  async function removeClaim(input, { authority, reason }) {
+  async function removeClaims(input, selectors, { authority = null, reason = null } = {}) {
     const session = await requireOwner(input, "release");
-    const now = clock.now();
-    await store.transaction(async tx => {
-      await requireOwner(input, "release", tx);
-      const existing = tx.get("claim", input.claimId);
-      if (existing === null) {
-        throw new AccError(EXIT.CONFLICT, "the claim does not exist", { claimId: input.claimId });
+    return store.transaction(async tx => {
+      await requireOwner(input, "release", tx, true);
+      const now = clock.now();
+      const selected = selectReleaseClaims(tx, selectors, session.sessionId);
+      for (const existing of selected) {
+        const owned = existing.ownerSessionId === session.sessionId;
+        if (!owned && authority !== "human" && authority !== "policy") {
+          throw new AccError(EXIT.CONFLICT,
+            "force release requires human or policy authority",
+            { claimId: existing.claimId, authority });
+        }
       }
-      const owned = existing.ownerSessionId === session.sessionId;
-      // Force release is an authority decision, not a peer decision. A
-      // coordinator lease does not extend outside its own workstream.
-      if (!owned && authority !== "human" && authority !== "policy") {
-        throw new AccError(EXIT.CONFLICT,
-          "force release requires human or policy authority",
-          { claimId: input.claimId, authority: authority ?? null });
+      for (const existing of selected) {
+        const owned = existing.ownerSessionId === session.sessionId;
+        // Remove the live record; per-resource events retain its history.
+        tx.remove("claim", existing.claimId, tx.generationOf("claim", existing.claimId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+          workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
+          type: owned ? "claim.released" : "claim.force_released", occurredAt: now,
+          payload: { claimId: existing.claimId, authority,
+            reason, replacedGeneration: existing.generation } });
       }
-      // The claim record is removed rather than tombstoned: a released claim is
-      // not a claim, and every consumer of a snapshot would otherwise have to
-      // re-derive liveness. The event log keeps the history.
-      tx.remove("claim", input.claimId, tx.generationOf("claim", input.claimId));
-      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
-        workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
-        type: owned ? "claim.released" : "claim.force_released", occurredAt: now,
-        payload: { claimId: input.claimId, authority: authority ?? null,
-          reason: reason ?? null, replacedGeneration: existing.generation } });
+      return selected;
     }, { kinds: ["session", "claim"] });
   }
 
   return {
-    acquireClaim,
+    acquireClaim: async input => (await acquire(input, [input.resource], false))[0],
+    acquireClaims: input => acquire(input, input.resources, true),
     renewClaim,
-    releaseClaim: input => removeClaim(input, { authority: null, reason: null }),
-    forceReleaseClaim: input => removeClaim(input,
-      { authority: input.authority, reason: input.reason }),
+    releaseClaims: async input => removeClaims(input, releaseSelectors(input)),
+    releaseClaim: async input => { await removeClaims(input, { claimIds: [input.claimId] }); },
+    forceReleaseClaim: async input => { await removeClaims(input, { claimIds: [input.claimId] },
+      { authority: input.authority, reason: input.reason });
+    },
   };
 }

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

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

package/node_modules/@agents-can-communicate/delivery-router/src/refresh-binding.mjs

@@ -1,6 +1,7 @@
 import { validateNativeHandshake } from "@agents-can-communicate/adapter-sdk";
 
 const MAX_REFRESH_LEASE_MS = 120_000;
+const refused = (errorCode = "recipient_unavailable") => ({ refreshed: false, errorCode });
 
 function sameBinding(current, expected, leaseUntil) {
   return current !== null && current !== undefined
@@ -15,24 +16,26 @@ function sameBinding(current, expected, leaseUntil) {
 
 export async function refreshExpiredBinding({ service, adapter, binding, runtimeDir,
   clock, timeoutMs = 750 }) {
-  if (typeof adapter?.refreshNativeSession !== "function") return false;
+  if (typeof adapter?.refreshNativeSession !== "function") return refused();
   const now = Date.parse(clock.now());
-  if (!Number.isFinite(now)) return false;
+  if (!Number.isFinite(now)) return refused();
   try {
     const handshake = await adapter.refreshNativeSession({ binding, runtimeDir, timeoutMs });
     const validated = validateNativeHandshake(adapter, {
       clientVersion: binding.clientVersion, handshake,
     });
-    if (!validated.ok || validated.opaqueEndpointRef !== binding.opaqueEndpointRef) return false;
+    if (!validated.ok) return refused(validated.reasonCode === "transport_permission_denied"
+      ? "transport_permission_denied" : "recipient_unavailable");
+    if (validated.opaqueEndpointRef !== binding.opaqueEndpointRef) return refused();
     const requestedLease = Date.parse(validated.leaseUntil);
-    if (!Number.isFinite(requestedLease) || requestedLease <= now) return false;
+    if (!Number.isFinite(requestedLease) || requestedLease <= now) return refused();
     const leaseUntil = new Date(Math.min(requestedLease,
       now + MAX_REFRESH_LEASE_MS)).toISOString();
     await service.refreshDeliveryBinding({ sessionId: binding.sessionId,
       generation: binding.generation, leaseUntil });
     const current = await service.store?.ephemeral?.get("deliveryBinding", binding.sessionId);
-    return sameBinding(current, binding, leaseUntil);
+    return sameBinding(current, binding, leaseUntil) ? { refreshed: true, errorCode: null } : refused();
   } catch {
-    return false;
+    return refused();
   }
 }

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

@@ -1,12 +1,10 @@
-import { NATIVE_REASON_CODES, evaluateVersionContract, isLaunchOption }
+import { NATIVE_REASON_CODES, evaluateVersionContract, isLaunchOption, OFFER_ERRORS, storeOfferObservation }
   from "@agents-can-communicate/adapter-sdk";
 
 import { lastNativeReason } from "./native-reason.mjs";
 import { refreshExpiredBinding } from "./refresh-binding.mjs";
 
-const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
-  "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected", "transport_permission_denied",
-  "unsupported_client_version"]);
+const SAFE_ERRORS = new Set(OFFER_ERRORS);
 const NAMED_LIVE_TRANSPORTS = new Set(["claude-inbox", "codex-app-server"]);
 
 const adaptersById = adapters => adapters instanceof Map
@@ -50,6 +48,14 @@ function safeTransport(value, opaqueEndpointRef) {
 export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
   readNativeReason = input => lastNativeReason({ runtimeDir: service.store?.root, ...input }) }) {
   const registry = adaptersById(adapters);
+  const observeOffer = (binding, reasonCode = null) => {
+    // Capture time and order now, but never await optional diagnostic I/O on
+    // the delivery path. The SDK bounds its own lifetime for short-lived CLIs.
+    void storeOfferObservation({
+      runtimeDir: service.store?.root, workspaceId: service.store?.workspaceId,
+      sessionId: binding.sessionId, generation: binding.generation, at: clock.now(),
+      state: reasonCode === null ? "active" : "degraded", reasonCode }).catch(() => {});
+  };
 
   // A session that bound no live transport may have said why: the reason its
   // own last native attempt recorded, from the closed vocabulary only, and the
@@ -82,6 +88,7 @@ export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
       targetGeneration: binding.generation,
       transport: safeTransport(transport, binding.opaqueEndpointRef), adapterId: binding.adapterId,
       clientVersion: binding.clientVersion, safeErrorCode }).catch(() => null);
+    observeOffer(binding, safeErrorCode);
   }
 
   async function offerTo(message, participantId, now) {
@@ -132,7 +139,12 @@ export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
     if (Date.parse(binding.leaseUntil) <= Date.parse(now)) {
       const refreshed = await refreshExpiredBinding({ service, adapter, binding,
         runtimeDir: service.store?.root, clock });
-      if (!refreshed) return durable(participantId, "recipient_unavailable");
+      if (!refreshed.refreshed) {
+        if (refreshed.errorCode === "transport_permission_denied") {
+          await recordFailure(binding, message, participantId, "live-adapter", refreshed.errorCode);
+        } else observeOffer(binding, refreshed.errorCode);
+        return durable(participantId, refreshed.errorCode);
+      }
       const current = (await service.listDeliveryBindings({
         participantId, now: clock.now() })).filter(item => item.sessionId === binding.sessionId
           && item.generation === binding.generation
@@ -211,6 +223,7 @@ export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
     // shown and leave it out of the very turn the wake started. The receipt
     // stays queued; the hook records the offer once its stdout carried the body.
     if (adapter.nativeDelivery?.offerKind === "wake") {
+      observeOffer(binding, response.pendingApproval === true ? "inbound_approval_required" : null);
       // The client took the wake but holds it for its user's approval.
       return { recipientParticipantId: participantId, outcome: "woken", transport,
         ...(response.pendingApproval === true ? { pendingApproval: true } : {}) };
@@ -224,6 +237,7 @@ export function createDeliveryRouter({ service, adapters, clock, readLivePolicy,
       await recordFailure(binding, message, participantId, transport, "transport_error");
       return durable(participantId, "transport_error");
     }
+    observeOffer(binding);
     return { recipientParticipantId: participantId, outcome: "offered", transport };
   }
 

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

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

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

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

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

@@ -39,6 +39,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         const createdDirectories = await missingArtifactParents({ home: context.home,
           artifacts: operation.artifacts });
         const installContext = { ...context,
+          indicator: operation.indicator,
           clientVersion: operation.clientVersion, platform: operation.platform,
           requestedLivePolicy: operation.livePolicy ?? "off",
           livePolicy: operation.configuredLivePolicy ?? operation.effectiveLivePolicy ?? "off" };
@@ -71,10 +72,12 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           version: operation.clientVersion ?? null, accVersion,
           artifacts: operation.artifacts, createdDirectories,
           deliveryPolicy: operation.livePolicy, deliveryDecision: operation.deliveryDecision,
+          indicator: operation.indicator,
           nativeActivation: native });
         results.operations.push({ ...operation, applied: true,
           needsAction: outcome.needsAction ?? [],
           changes: outcome.changes ?? [], diagnostics: [
+            ...(operation.indicatorDiagnostic === undefined ? [] : [operation.indicatorDiagnostic]),
             ...(operation.deliveryDiagnostic === undefined
               ? [] : [operation.deliveryDiagnostic]),
             ...(outcome.diagnostics ?? []),

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

@@ -10,6 +10,7 @@ const REASONS = Object.freeze({
   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",
+  transport_permission_denied: "the calling process lacks permission to access the local delivery channel",
   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",

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

@@ -121,7 +121,7 @@ async function saveOwnership({ dataHome, record }) {
  */
 export async function recordInstall({ dataHome, adapterId, version, accVersion = null,
   artifacts, createdDirectories = [], deliveryPolicy, deliveryDecision,
-  nativeActivation = null }) {
+  nativeActivation = null, indicator }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -141,6 +141,7 @@ export async function recordInstall({ dataHome, adapterId, version, accVersion =
       { adapterId, version, accVersion, artifacts: stamped,
         ...(directories.length === 0 ? {} : { createdDirectories: directories }),
         ...(deliveryPolicy === undefined ? {} : { deliveryPolicy }),
+        ...(indicator === undefined ? {} : { indicator }),
         ...(retainedDeliveryDecision === undefined ? {} : {
           deliveryDecision: retainedDeliveryDecision,
         }),