agents-can-communicate 0.10.4 → 0.11.1

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

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { assertPortableId } from "@agents-can-communicate/protocol";
+import { effectiveCapabilities, loadNativeAttempt, loadSessionBinding, loadOfferObservation }
+  from "@agents-can-communicate/adapter-sdk";
+import { readDeliveryBindingRecord, readSessionRecord } from "@agents-can-communicate/storage-filesystem";
+import { readInstalledLivePolicyState } from "@agents-can-communicate/installer/live-policy";
+import { loadAdapter } from "./adapter-catalog.mjs";
+import { canonicalManagerRoot, managedDirectory, readManagedJson } from "./managed-runtime/state.mjs";
+import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
+
+const receptionText = {
+  automatic: "This chat can receive addressed requests without another user prompt. A busy client may queue them.",
+  turn: "Messages reach this chat on its next normal turn.",
+  inbox: "Messages are available when the agent reads acc inbox; no polling schedule is implied.",
+};
+
+function result({ health = "ready", reception = null, reasonCode = null,
+  detail, action = null, leaseCurrent = null }) {
+  const qualifier = reception && reception !== "automatic" ? ` · ${reception}` : "";
+  return { health, reception, reasonCode, leaseCurrent,
+    label: `ACC ${health === "ready" ? "●" : "!"}${qualifier}`,
+    detail: [detail, receptionText[reception]].filter(Boolean).join(" "), action };
+}
+
+export const indicatorFailure = (reasonCode = "state_unreadable") => result({
+  health: "problem", reasonCode,
+  detail: reasonCode === "not_registered" ? "This chat is not registered with ACC."
+    : "ACC could not read this chat's local integration state.",
+  action: reasonCode === "not_registered"
+    ? "Send a prompt to run the session hooks. If ACC is still absent, run acc doctor and check the plugin is enabled."
+    : "Run acc doctor in this project to identify and repair the local state problem.",
+});
+
+const actions = {
+  client_session_embedded: "This session has no shared delivery service. Run acc doctor to see the launch option and how to open a supported session.",
+  client_process_unknown: "Send a prompt: each prompt looks for the client process again. If this stays, run acc doctor.",
+  transport_permission_denied: "Allow the sending command to access the local delivery channel; acc doctor shows the affected session.",
+  handshake_version_mismatch: "Update the client's delivery service to a supported version; acc doctor shows the version in use.",
+  native_policy_off: "Automatic delivery is disabled in ACC settings. Run acc install --delivery actionable to enable it.",
+  inbound_approval_required: "Approve the pending inbound request in the receiving client, or review its incoming-message setting.",
+};
+
+/** A display observation, never CLI ownership. Native ids select one saved room
+ * and one binding; there is no roster scan, Git probe, store open, socket probe,
+ * lease refresh, heartbeat, update worker or managed-runtime process lease. */
+export async function readIndicator({ adapterId, nativeSessionId,
+  dataHome = platformDataHome(), now = new Date().toISOString() }) {
+  try {
+    const adapter = await loadAdapter(adapterId);
+    if (!adapter || typeof nativeSessionId !== "string" || !nativeSessionId
+      || nativeSessionId.length > 4096) return indicatorFailure("not_registered");
+    const key = createHash("sha256").update(JSON.stringify([adapterId, nativeSessionId])).digest("hex");
+    const accRoot = await canonicalManagerRoot(path.join(dataHome, "acc"));
+    const rooms = path.join(accRoot, "native-workspaces");
+    if (!await managedDirectory(rooms)) return indicatorFailure("not_registered");
+    const room = await readManagedJson(path.join(rooms, `${key}.json`));
+    if (!room) return indicatorFailure("not_registered");
+    if (room.schemaVersion !== 1 || room.adapterId !== adapterId
+      || room.nativeSessionId !== nativeSessionId) throw new Error("invalid room");
+    assertPortableId(room.workspaceId, "workspace id");
+    const root = runtimePaths({ dataHome: path.dirname(accRoot), workspaceId: room.workspaceId }).root;
+    const owner = await loadSessionBinding({ runtimeDir: root, harnessSessionId: nativeSessionId });
+    if (!owner) return indicatorFailure("not_registered");
+    const input = { root, workspaceId: room.workspaceId, sessionId: owner.accSessionId };
+    const session = await readSessionRecord(input);
+    if (session?.state !== "open" || session.generation !== owner.generation
+      || session.harness !== adapterId) return indicatorFailure("not_registered");
+    const [binding, handshake, policy, offer] = await Promise.all([
+      readDeliveryBindingRecord(input),
+      loadNativeAttempt({ runtimeDir: root, harnessSessionId: nativeSessionId, ...owner }),
+      readInstalledLivePolicyState({ dataHome: path.dirname(accRoot), adapterId }),
+      loadOfferObservation({ runtimeDir: root, sessionId: owner.accSessionId, generation: owner.generation }),
+    ]);
+    const attempt = offer && (!handshake || Date.parse(offer.at) >= Date.parse(handshake.at)) ? offer : handshake;
+    const current = await readSessionRecord(input);
+    if (current?.state !== "open" || current.generation !== owner.generation) {
+      return indicatorFailure("not_registered");
+    }
+    const capabilities = effectiveCapabilities(adapter, {
+      clientName: owner.clientName ?? adapter.client.certificationName,
+      clientVersion: owner.clientVersion, platform: owner.platform,
+    });
+    const fallback = capabilities.delivery.nextTurn ? "turn" : "inbox";
+    const bound = binding?.generation === owner.generation && binding.adapterId === adapterId
+      && binding.retiredAt == null && binding.availableModes.includes("livePush");
+    const leaseCurrent = bound ? Date.parse(binding.leaseUntil) > Date.parse(now) : null;
+    if (["missing", "invalid", "unavailable"].includes(policy.policyStatus)) {
+      return result({ health: "problem", reception: fallback, reasonCode: "installation_unavailable",
+        detail: "ACC cannot find a valid delivery setting for this integration.",
+        action: `Run acc install --adapter ${adapterId} to repair the integration.`, leaseCurrent });
+    }
+    if (policy.policy === "off") return result({ reception: fallback, reasonCode: "native_policy_off",
+      detail: "Automatic delivery is disabled in ACC settings.", leaseCurrent });
+    if (attempt?.state === "degraded") return result({ health: "problem", reception: fallback,
+      reasonCode: attempt.reasonCode ?? "handshake_failed", leaseCurrent,
+      detail: "ACC could not establish automatic delivery for this chat.",
+      action: actions[attempt.reasonCode]
+        ?? "Run acc doctor in this project for the channel failure and the client's recovery steps.",
+    });
+    // Lease expiry alone is neither disconnection nor an operation in progress.
+    // The delivery router verifies the endpoint and renews it on the next send.
+    if (bound && binding.livePolicy !== "off") return result({ reception: "automatic", leaseCurrent });
+    if (attempt?.state === "unsupported" || !capabilities.delivery.livePush) {
+      return result({ reception: fallback, reasonCode: "native_delivery_unsupported",
+        detail: "This client session does not support automatic wake-up." });
+    }
+    return result({ health: "problem", reception: fallback, reasonCode: "native_unbound",
+      detail: "This chat has no automatic delivery channel.",
+      action: "Send a prompt to let ACC establish the channel; if it remains unavailable, run acc doctor." });
+  } catch { return indicatorFailure(); }
+}

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

@@ -224,6 +224,9 @@ export function actedOn(result) {
 }
 
 export async function runInstallCommand({ options, runtime, action = "install" }) {
+  if (options.indicator !== undefined && !["on", "off"].includes(options.indicator)) {
+    throw new AccError(EXIT.USAGE, "--indicator must be on or off");
+  }
   const adapters = selectAdapters(options.adapter);
   const home = options.home ?? runtime.env?.HOME ?? homedir();
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
@@ -261,6 +264,7 @@ export async function runInstallCommand({ options, runtime, action = "install" }
     ? await decideDelivery({ options, detected, recorded, runtime, dryRun })
     : { deliveryByAdapter: {}, asked: [], notes: [] };
   const plan = planInstallation({ adapters, detected, context, action, recorded,
+    indicator: options.indicator,
     accVersion, allowDowngrade: options.downgrade === true, requested,
     deliveryByAdapter: decided.deliveryByAdapter,
     deliveryDecisionByAdapter: decided.deliveryDecisionByAdapter,

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

@@ -5,10 +5,6 @@
 import { AccError, CONFIG_FILENAME, EXIT, GENERIC_MESSAGE_KINDS, VALID_OBLIGATIONS,
   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";
 
 import { parseArgs, positiveNumber } from "./args.mjs";
 
@@ -16,54 +12,13 @@ import { parseArgs, positiveNumber } from "./args.mjs";
 // with the argument already half-applied.
 const usage = message => new AccError(EXIT.USAGE, message);
 import { commandHelpText, describeCommand, describeCommands, helpText } from "./help.mjs";
-import { runUpdateCommand } from "./update-command.mjs";
-import { runConfigCommand } from "./config-command.mjs";
-import { ALL_ADAPTERS, runInstallCommand } from "./install-command.mjs";
-import { runDoctor } from "./doctor-command.mjs";
-import { runManagementDoctor } from "./managed-runtime/diagnostics.mjs";
-import { runStoreMigration } from "./store-migration-command.mjs";
+import { loadAdapters } from "./adapter-catalog.mjs";
 import { createGitProbe } from "./git-probe.mjs";
-import { canonicalClaim } from "./claim-spelling.mjs";
 import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
 import { resolveOwner } from "./session-owner.mjs";
-import { discoverWorkspace } from "./workspace-discovery.mjs";
-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.
  *
@@ -72,6 +27,10 @@ async function claimOn(options, context) {
  * looking is safe.
  */
 async function locateContext(options, runtime) {
+  // Workspace discovery reads through the store's no-follow opens, so it is
+  // loaded by the commands that use a workspace, never by `version` (#270).
+  const [{ discoverWorkspace }, { resolveSavedHookWorkspace }] = await Promise.all([
+    import("./workspace-discovery.mjs"), import("./hook-workspace.mjs")]);
   const dataHome = runtime.dataHome ?? platformDataHome({ platform: runtime.platform,
     env: runtime.env });
   const discovery = {
@@ -92,6 +51,10 @@ async function locateContext(options, runtime) {
 }
 
 async function withService({ descriptor, paths, dataHome }, runtime) {
+  // Loaded here rather than at the top: `version`, `help` and the commands
+  // that work on a machine never open a store (#270).
+  const [{ openFilesystemStore }, { createCoordinationService }] = await Promise.all([
+    import("@agents-can-communicate/storage-filesystem"), import("@agents-can-communicate/core")]);
   const store = await openFilesystemStore({ root: paths.root, clock: runtime.clock,
     ids: runtime.ids, workspaceId: descriptor.id });
   const service = createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids });
@@ -153,35 +116,10 @@ function obligationFor(kind, explicit, addressed) {
   return obligation;
 }
 
-export function recordedText(message, delivery) {
-  const diagnostics = delivery.map(item => item.outcome === "offered"
-    ? `live offered to ${item.recipientParticipantId} via ${item.transport}`
-    : item.outcome === "woken" && item.pendingApproval === true
-      ? `sent a wake to ${item.recipientParticipantId} via ${item.transport}, which its session holds `
-        + "for approval because it bypasses permission prompts; the message arrives with its next turn"
-    : item.outcome === "woken"
-      ? `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; 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,
-              { launchOption: item.nativeLaunchOption })})` : ""}`
-            + "; the message waits in its inbox"
-        : item.errorCode === "recipient_offline" && item.endReason === "clear"
-          ? `${item.recipientParticipantId}'s conversation was cleared (/clear); the message waits `
-            + "until that conversation resumes"
-        : item.errorCode === "recipient_offline"
-          ? `${item.recipientParticipantId} has no open session; the message waits until it starts `
-            + "or resumes one"
-          : `live offer unavailable (${item.errorCode ?? "durable_fallback"})`
-      : `delivery already ${item.outcome}`);
-  return [`recorded ${message.messageId}`, ...diagnostics].join("; ");
-}
+// What a sent message met, in words. Its diagnostics load with the first
+// message a command sends, not with `acc version` (#270).
+const describeRecorded = async (message, delivery) =>
+  (await import("./recorded-text.mjs")).recordedText(message, delivery);
 
 export async function recordAndOffer({ record, router, selectMessage = value => value }) {
   const recorded = await record();
@@ -212,7 +150,7 @@ export async function recordAndOffer({ record, router, selectMessage = value =>
  * A live binding wakes on the router's own rule: a current lease, or a lapsed
  * one the adapter can re-verify. Without that the next send is durable.
  */
-export function presenceBreakdown(participants = [], adapters = ALL_ADAPTERS()) {
+export function presenceBreakdown(participants = [], adapters = []) {
   const nextTurn = new Set(adapters.filter(adapter => adapter.capabilities?.delivery?.nextTurn === true)
     .map(adapter => adapter.id));
   const refreshes = new Set(adapters.filter(adapter => typeof adapter.refreshNativeSession === "function")
@@ -245,13 +183,13 @@ export function describePresence({ live = 0, stale = 0 } = {},
   return `${live} live (${parts.join("; ")})`;
 }
 
-export function describeStatus(status) {
+export function describeStatus(status, adapters = []) {
   // `live` counts everyone present, which includes sessions gone stale - a
   // client that exited without its session being closed keeps a record that
   // stops being answered but does not disappear. Printing the number alone
   // said "1 live" about a workspace where the last agent had left minutes
   // before, which is the one thing a person reads this line to find out.
-  const line = `${describePresence(status.counts, presenceBreakdown(status.participants))}; `
+  const line = `${describePresence(status.counts, presenceBreakdown(status.participants, adapters))}; `
     + `${status.counts.claims} claim(s); `
     + `protection ${status.protection}`;
   // A transport accepting a message is not a model reading it. Said only when
@@ -327,25 +265,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: async input => (await import("./claim-command.mjs")).runClaimCommand(input),
+  release: async input => (await import("./claim-command.mjs")).runReleaseCommand(input),
 
   message: async ({ options, context }) => {
     const kind = options.type ?? "note";
@@ -360,7 +281,7 @@ const HANDLERS = Object.freeze({
       subject: options.subject, body: options.body, descriptor: context.descriptor }) });
     const message = routed.recorded;
     return { data: { message, delivery: routed.delivery },
-      text: recordedText(message, routed.delivery) };
+      text: await describeRecorded(message, routed.delivery) };
   },
 
   inbox: async ({ options, context }) => {
@@ -387,7 +308,7 @@ const HANDLERS = Object.freeze({
       subject: options.subject, clientMessageId: clientMessageId(options, context) }) });
     const result = routed.recorded;
     return { data: { message: result.reply, receipt: result.receipt, delivery: routed.delivery },
-      text: `${recordedText(result.reply, routed.delivery)}; acknowledged ${result.receipt.messageId}` };
+      text: `${await describeRecorded(result.reply, routed.delivery)}; acknowledged ${result.receipt.messageId}` };
   },
 
   request: async ({ options, context }) => {
@@ -405,7 +326,7 @@ const HANDLERS = Object.freeze({
     }) });
     const message = routed.recorded;
     return { data: { message, delivery: routed.delivery },
-      text: recordedText(message, routed.delivery) };
+      text: await describeRecorded(message, routed.delivery) };
   },
 
   ack: async ({ options, context }) => {
@@ -424,17 +345,20 @@ const HANDLERS = Object.freeze({
       remaining: options.remaining ?? [], blockers: options.blocker ?? [] }) });
     const handoff = routed.recorded;
     return { data: { message: handoff.message, delivery: routed.delivery },
-      text: recordedText(handoff.message, routed.delivery) };
+      text: await describeRecorded(handoff.message, routed.delivery) };
   },
 
   status: async ({ options, context, runtime }) => {
     await registerNativeSessions(runtime, context);
     const status = await context.service.collectStatus({
       participantId: options.participant, all: options.all === true });
-    return { data: status, text: describeStatus(status) };
+    // Only the clients present here say how their idle sessions are reached.
+    const adapters = await loadAdapters((status.participants ?? []).map(item => item.harness));
+    return { data: status, text: describeStatus(status, Object.values(adapters)) };
   },
 
   config: async ({ options, runtime }) => {
+    const { runConfigCommand } = await import("./config-command.mjs");
     const result = await runConfigCommand({ subcommand: options.subcommand,
       cwd: options.cwd ?? runtime.cwd,
       // A pipe is not a person. Without a TTY there is nobody to answer, so the
@@ -461,11 +385,11 @@ const HANDLERS = Object.freeze({
       text: result.written ? `wrote ${result.file}` : `not written: ${result.file}` };
   },
 
-  install: async ({ options, runtime }) =>
-    runInstallCommand({ options, runtime, action: "install" }),
+  install: async ({ options, runtime }) => (await import("./install-command.mjs"))
+    .runInstallCommand({ options, runtime, action: "install" }),
 
-  uninstall: async ({ options, runtime }) =>
-    runInstallCommand({ options, runtime, action: "uninstall" }),
+  uninstall: async ({ options, runtime }) => (await import("./install-command.mjs"))
+    .runInstallCommand({ options, runtime, action: "uninstall" }),
 
   prune: async ({ options, context }) => {
     const result = await context.service.prune({
@@ -485,9 +409,12 @@ const HANDLERS = Object.freeze({
     return { data: result, text };
   },
 
-  doctor: async input => input.options.migrateStore ? runStoreMigration(input) : runDoctor(input),
+  doctor: async input => input.options.migrateStore
+    ? (await import("./store-migration-command.mjs")).runStoreMigration(input)
+    : (await import("./doctor-command.mjs")).runDoctor(input),
 
-  update: async ({ options, runtime }) => runUpdateCommand({ options, runtime }),
+  update: async ({ options, runtime }) => (await import("./update-command.mjs"))
+    .runUpdateCommand({ options, runtime }),
 
   help: async ({ options }) => {
     if (options.helpCommand === undefined) {
@@ -549,8 +476,9 @@ export async function main(argv, runtime) {
     const options = context === null ? parsed.options
       : await resolveOwner({ command: parsed.command, options: parsed.options,
         context, env: runtime.env });
-    const { data, text, error: outcome } = await (managementDoctor ? runManagementDoctor : HANDLERS[parsed.command])(
-      { options, context, runtime });
+    const handler = managementDoctor
+      ? (await import("./managed-runtime/diagnostics.mjs")).runManagementDoctor : HANDLERS[parsed.command];
+    const { data, text, error: outcome } = await handler({ options, context, runtime });
     // A handler may have done real work and still failed: `acc install` writes
     // for the clients it could and reports the one it could not. The data is
     // printed either way, and the command still fails.

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

@@ -99,7 +99,7 @@ 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",
+  client_process_unknown: "the client process could not be identified; the next prompt looks for it again",
   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",
   // Since the contract gate shipped, this reason means the version now serving

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

@@ -0,0 +1,32 @@
+import { shellQuote } from "@agents-can-communicate/adapter-sdk";
+import { describeNativeReason } from "@agents-can-communicate/installer";
+
+export function recordedText(message, delivery) {
+  const diagnostics = delivery.map(item => item.outcome === "offered"
+    ? `live offered to ${item.recipientParticipantId} via ${item.transport}`
+    : item.outcome === "woken" && item.pendingApproval === true
+      ? `sent a wake to ${item.recipientParticipantId} via ${item.transport}, which its session holds `
+        + "for approval because it bypasses permission prompts; the message arrives with its next turn"
+    : item.outcome === "woken"
+      ? `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; 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,
+              { launchOption: item.nativeLaunchOption })})` : ""}`
+            + "; the message waits in its inbox"
+        : item.errorCode === "recipient_offline" && item.endReason === "clear"
+          ? `${item.recipientParticipantId}'s conversation was cleared (/clear); the message waits `
+            + "until that conversation resumes"
+        : item.errorCode === "recipient_offline"
+          ? `${item.recipientParticipantId} has no open session; the message waits until it starts `
+            + "or resumes one"
+          : `live offer unavailable (${item.errorCode ?? "durable_fallback"})`
+      : `delivery already ${item.outcome}`);
+  return [`recorded ${message.messageId}`, ...diagnostics].join("; ");
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "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];
+  });
+}