agents-can-communicate 0.10.4 → 0.11.0

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

@@ -33,8 +33,8 @@ const SUMMARY = Object.freeze({
   prune: "report what this workspace no longer needs; --apply to reclaim it",
   sync: "events since a cursor, or bounded message history",
   work: "publish what this session is doing, or --clear when it has stopped",
-  claim: "reserve a resource; exit 5 when someone else already holds it",
-  release: "give a claim back",
+  claim: "reserve resources atomically; exit 5 when a peer holds one",
+  release: "give selected claims back, or --all for this session",
   ack: "acknowledge receipt without accepting work or writing an answer",
   message: "send a typed message to named participants",
   inbox: "list pending message headers; --message reads one complete message",
@@ -72,7 +72,7 @@ const CHOICES = Object.freeze({
   finish: { status: HANDOFF_STATUSES },
   message: { type: GENERIC_MESSAGE_KINDS, obligation: OBLIGATIONS },
   sync: { scope: ["delta", "full", "history"], type: MESSAGE_KINDS },
-  install: { delivery: LIVE_POLICIES, adapter: ADAPTER_IDS },
+  install: { delivery: LIVE_POLICIES, adapter: ADAPTER_IDS, indicator: ["on", "off"] },
   uninstall: { adapter: ADAPTER_IDS },
 });
 
@@ -80,6 +80,7 @@ const NOTES = Object.freeze({
   doctor: ["--repair completes recoverable writes without changing the store contract.",
     "--migrate-store explicitly changes contract 6 to 7 after old clients and unmanaged store users stop; it cannot be combined with --repair."],
   install: ["Without --delivery, one default-No question covers all selected clients that need a decision.",
+    "--indicator on|off controls the compact indicator in supported clients; omission preserves the saved choice (initially off).",
     "--delivery actionable|all gives explicit complete-setup consent; --delivery off disables incoming automatic requests.",
     "A dry run does not prompt, write configuration, or start a service. Service readiness does not establish a session binding."],
   attach: ["Native hooks already manage their own session. Attach only for a manual CLI session.",
@@ -87,8 +88,12 @@ const NOTES = Object.freeze({
     "--cadence is a positive interval in milliseconds."],
   work: ["Provide --summary unless using --clear. Default mode: edit; default state: active."],
   claim: ["--lease is in seconds. Default mode: exclusive; default enforcement: advisory.",
-    "For files, use file:src/a.mjs or file:src/**. A claim may conflict with a peer."],
-  release: ["Provide --claim or --resource. Releasing another owner's claim requires human or policy authority."],
+    "Repeat --resource for an atomic batch. A conflict changes no claims, including existing leases.",
+    "For files, use file:src/a.mjs or file:src/**. Duplicate canonical resources are rejected."],
+  release: ["Choose repeated --claim, repeated --resource, or --all. Never combine selector families.",
+    "Explicit lists succeed completely or change no claims. --all releases only this session's claims and keeps it open.",
+    "An empty --all succeeds. A repeated explicit release of missing claims remains an error.",
+    "Releasing another owner's claim requires human or policy authority and a single selector."],
   message: ["Default type: note. question/request require --to and obligation reply; note uses none.",
     "decision permits none, or acknowledge when addressed. Use reply for answers and finish for handoffs.",
     "For decisions, repeat --supersedes or --withdraws with 1..16 prior decision IDs; never combine the two.",
@@ -148,11 +153,13 @@ export function commandHelpText(command) {
   const lines = [`acc ${name} - ${summary}`, "", `Usage: acc ${name}${suffix} [options]`, ""];
   for (const [key, label] of [["required", "Required"], ["optional", "Optional"],
     ["repeated", "Repeatable"], ["flags", "Flags"]]) {
-    if (command[key].length === 0) continue;
+    const options = command[key].filter(option => key !== "repeated" || !command.required.includes(option));
+    if (options.length === 0) continue;
     lines.push(`${label}:`);
-    for (const option of command[key]) {
+    for (const option of options) {
       const value = key === "flags" ? "" : ` <${choices[option]?.join("|") ?? "value"}>`;
-      lines.push(`  --${option}${value}`);
+      const repeatable = key === "required" && command.repeated.includes(option) ? " (repeatable)" : "";
+      lines.push(`  --${option}${value}${repeatable}`);
     }
     lines.push("");
   }

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

@@ -1,5 +1,6 @@
 // Composition root: discovery, runtime locations, and the CLI surface.
 export { main } from "./main.mjs";
+export { readIndicator } from "./indicator.mjs";
 export { COMMANDS, parseArgs } from "./args.mjs";
 export { askConfirmation } from "./confirm.mjs";
 // Exported so a test can hold every adapter to where it plans to write and

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

@@ -0,0 +1,65 @@
+import { readTomlIndicatorSettings } from "@agents-can-communicate/adapter-sdk";
+import { previousOutput } from "./indicator-previous-command.mjs";
+import { readFile } from "node:fs/promises";
+import { readIndicator, indicatorFailure } from "./indicator.mjs";
+import { ALL_ADAPTERS } from "./install-command.mjs";
+
+function output(report, options, context) {
+  if (options.json) return JSON.stringify(report);
+  if (options.details) return [report.label, report.detail, report.action].filter(Boolean).join("\n");
+  const extension = context.extension;
+  let label = report.label;
+  try { label = extension?.renderText?.(report) ?? label; }
+  catch { /* A display extension cannot prevent the diagnostic. */ }
+  const indicator = label + (report.health === "problem" ? " · acc doctor" : "");
+  try {
+    if (extension?.composeText) return extension.composeText({ ...context, indicator });
+  } catch { /* Keep the diagnostic if the footer cannot be composed. */ }
+  return [context.previous, indicator].filter(Boolean).join("\n");
+}
+
+async function input(stream) {
+  let source = "";
+  for await (const chunk of stream) {
+    source += chunk;
+    if (Buffer.byteLength(source) > 64 * 1024) throw new Error("indicator input too large");
+  }
+  return source;
+}
+
+export async function runIndicator({ argv = process.argv.slice(2), stdin = process.stdin,
+  stdout = process.stdout } = {}) {
+  const options = {}, context = { payload: {}, previous: "", settings: {} };
+  let report = indicatorFailure(), timeout, expired = false;
+  const controller = new AbortController();
+  try {
+    for (let i = 0; i < argv.length; i++) {
+      const flag = argv[i];
+      if (["--json", "--details"].includes(flag)) options[flag.slice(2)] = true;
+      else if (["--adapter", "--native-session", "--previous"].includes(flag)
+        && typeof argv[i + 1] === "string") options[flag.slice(2)] = argv[++i];
+      else throw new Error("invalid indicator option");
+    }
+    context.extension = ALL_ADAPTERS().find(adapter => adapter.id === options.adapter)?.statusIndicator;
+    const plain = options.json || options.details;
+    timeout = setTimeout(() => {
+      expired = true;
+      controller.abort();
+      stdout.write(output(indicatorFailure(), options, context) + "\n", () => process.exit(0));
+    }, plain ? 1500 : context.extension?.budgetMs ?? 1500);
+    const source = options["native-session"] ? "{}" : await input(stdin);
+    context.payload = source.trim() ? JSON.parse(source) : {};
+    report = await readIndicator({ adapterId: options.adapter,
+      nativeSessionId: options["native-session"] ?? (context.extension?.nativeSessionId
+        ? context.extension.nativeSessionId(context.payload)
+        : context.payload.conversation_id ?? context.payload.session_id) });
+    if (options.previous && !plain) {
+      const saved = JSON.parse(await readFile(options.previous, "utf8"));
+      context.settings = await readTomlIndicatorSettings(saved);
+      context.previous = await previousOutput(saved.previous, source,
+        context.extension?.previousTimeoutMs ?? 700, controller.signal);
+    }
+  } catch { /* A status renderer fails open with an actionable diagnostic. */ }
+  finally { clearTimeout(timeout); controller.abort(); }
+  if (!expired) stdout.write(output(report, options, context) + "\n");
+}

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

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LIMIT = 64 * 1024;
+
+function stopTree(child) {
+  if (!Number.isInteger(child?.pid) || child.pid <= 0) return;
+  if (process.platform !== "win32") {
+    // detached creates a new group for this command, never for the host client.
+    try { process.kill(-child.pid, "SIGKILL"); } catch { /* Already gone. */ }
+    return;
+  }
+  // Keep the owned launcher alive until taskkill discovers its descendants.
+  // Killing it first loses that relationship; an exited PID must never be reused.
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  const root = process.env.SystemRoot ?? process.env.SYSTEMROOT ?? "C:\\Windows";
+  return new Promise(resolve => {
+    // Launcher and cleanup must survive the outer deadline: libuv kills
+    // non-detached Windows children when their spawning Node process exits.
+    const killer = spawn(path.win32.join(root, "System32", "taskkill.exe"),
+      ["/pid", String(child.pid), "/T", "/F"], { detached: true, windowsHide: true, stdio: "ignore" });
+    const timer = setTimeout(() => { killer.kill(); resolve(); }, 1000);
+    const done = () => { clearTimeout(timer); resolve(); };
+    killer.once("error", done);
+    killer.once("exit", done);
+    killer.unref();
+  });
+}
+
+// The original command receives the original stdin. Cancellation belongs to
+// the indicator request; its timeout must not leave another polling process.
+export async function previousOutput(previous, payload, timeout, signal) {
+  if (signal?.aborted || previous?.enabled === false
+      || ["builtin", "disabled", "off", "none", "hidden"].includes(previous?.type)
+      || typeof previous?.command !== "string" || !previous.command) return "";
+  return new Promise(resolve => {
+    let child, timer, settled = false, text = "";
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      // Continue draining stdout until Windows has stopped the tree. Closing
+      // it first can make the shell exit before taskkill inspects its children.
+      let cleanup;
+      try { cleanup = stopTree(child); } catch { /* Cleanup must fail open. */ }
+      Promise.resolve(cleanup).catch(() => {}).finally(() => {
+        child?.stdin?.destroy();
+        child?.stdout?.destroy();
+        if (child?.connected) child.disconnect();
+        child?.unref();
+        resolve(text.slice(0, LIMIT).trimEnd());
+      });
+    };
+    try {
+      const windows = process.platform === "win32";
+      child = windows
+        ? spawn(process.execPath, [fileURLToPath(new URL("./indicator-previous-windows.mjs", import.meta.url)), previous.command],
+          { detached: true, stdio: ["pipe", "pipe", "ignore", "ipc"], windowsHide: true })
+        : spawn(previous.command, { shell: true, detached: true,
+          stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+      child.stdout.on("data", chunk => {
+        if (settled) return;
+        text += chunk;
+        if (Buffer.byteLength(text) > LIMIT) finish();
+      });
+      child.stdin.on("error", () => {});
+      child.once("error", finish);
+      child.once("close", finish);
+      signal?.addEventListener("abort", finish, { once: true });
+      // The command budget starts when the Windows launcher starts the shell.
+      // Startup is bounded too; the enclosing indicator deadline can abort both.
+      timer = setTimeout(finish, windows ? 1000 : timeout);
+      if (windows) child.once("message", message => {
+        if (settled || message !== "started") return;
+        clearTimeout(timer);
+        timer = setTimeout(finish, timeout);
+      });
+      child.stdin.end(payload);
+      if (signal?.aborted) finish();
+    } catch { finish(); }
+  });
+}

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

@@ -0,0 +1,8 @@
+import { spawn } from "node:child_process";
+
+// A detached cmd.exe loses its standard handles. Keep the owned Node launcher
+// detached, and let a normal hidden shell inherit its original stdin/stdout.
+const child = spawn(process.argv[2], { shell: true, windowsHide: true, stdio: "inherit" });
+child.once("spawn", () => process.send?.("started", () => {}));
+child.once("error", () => process.exit(0));
+child.once("exit", () => process.exit(0));

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";
+import { ALL_ADAPTERS } from "./install-command.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: "Open a new client session so ACC can identify its process; then 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 = ALL_ADAPTERS().find(item => item.id === 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

@@ -23,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";
@@ -31,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.
  *
@@ -327,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/core/package.json

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