agents-can-communicate 0.10.3 → 0.11.0

package/node_modules/@agents-can-communicate/adapter-sdk/src/toml-scan.mjs

@@ -0,0 +1,99 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+export const unsafe = (reason = "unrecognized TOML declaration") => {
+  throw new AccError(EXIT.CONFLICT, `cannot safely edit status-line TOML: ${reason}; `
+    + "repair ambiguous TOML before retrying", { reason });
+};
+// A bounded lexical scan, not a TOML value parser. Newlines inside strings,
+// arrays and inline tables cannot introduce a header or a managed marker.
+export function* statements(source) {
+  let start = 0, code = "", quote = null;
+  const stack = [];
+  for (let i = 0; i < source.length;) {
+    const char = source[i];
+    if (quote) {
+      if (quote[0] === '"' && char === "\\") {
+        code += source.slice(i, i + 2); i += 2; continue;
+      }
+      if (source.startsWith(quote, i)) {
+        let count = quote.length;
+        if (quote.length === 3) {
+          while (source[i + count] === quote[0]) count++;
+          if (count > 5) unsafe("unsupported string quote delimiter");
+        }
+        code += source.slice(i, i + count); i += count; quote = null; continue;
+      }
+      if (quote.length === 1 && /[\r\n]/.test(char)) unsafe("newline in single-line string");
+      code += char; i++; continue;
+    }
+    if (char === "#") {
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = source.startsWith(char.repeat(3), i) ? char.repeat(3) : char;
+      code += quote; i += quote.length; continue;
+    }
+    if (char === "[" || char === "{") stack.push(char);
+    if (char === "]" || char === "}") {
+      if (stack.pop() !== (char === "]" ? "[" : "{")) unsafe("mismatched collection delimiter");
+    }
+    code += char; i++;
+    if (char === "\n" && stack.length === 0) {
+      yield { raw: source.slice(start, i), code: code.trim(), start, end: i };
+      start = i; code = "";
+    }
+  }
+  if (quote || stack.length) unsafe(quote ? "unclosed string" : "unclosed collection");
+  if (start < source.length) yield { raw: source.slice(start), code: code.trim(), start, end: source.length };
+}
+
+function decodeKey(key) {
+  if (key[0] === "'") return key.slice(1, -1);
+  if (key[0] !== '"') return key;
+  return key.slice(1, -1).replace(/\\(U[\da-fA-F]{8}|u[\da-fA-F]{4}|[btnfr"\\])|\\./g,
+    (match, escape) => {
+      if (!escape) unsafe("unsupported quoted-key escape");
+      if (/^[uU]/.test(escape)) {
+        const point = Number.parseInt(escape.slice(1), 16);
+        if (point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) {
+          unsafe("invalid quoted-key Unicode escape");
+        }
+        return String.fromCodePoint(point);
+      }
+      return ({ b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" })[escape];
+    });
+}
+
+function keyPath(code) {
+  const keys = [];
+  let rest = code.trimStart();
+  for (;;) {
+    const match = /^(?:[A-Za-z0-9_-]+|'[^'\r\n]*'|"(?:[^"\\\r\n]|\\[^\r\n])*")/.exec(rest);
+    if (!match) unsafe("unrecognized TOML key");
+    keys.push(decodeKey(match[0]));
+    rest = rest.slice(match[0].length).trimStart();
+    if (!rest.startsWith(".")) return { keys, rest };
+    rest = rest.slice(1).trimStart();
+  }
+}
+
+export function declaration(code) {
+  const header = code.startsWith("[");
+  const array = header && code.startsWith("[[");
+  const { keys, rest } = keyPath(header ? code.slice(array ? 2 : 1) : code);
+  if (header ? rest !== (array ? "]]" : "]") : !rest.startsWith("=")) unsafe();
+  return { keys, header, array, value: header ? null : rest.slice(1).trim() };
+}
+
+// Resolved declaration paths are only structural facts, never parsed user values.
+export function scanConfig(source) {
+  let table = [];
+  return [...statements(source)].map(item => {
+    if (!item.code) return { ...item, table: [...table], keys: [] };
+    const entry = declaration(item.code);
+    if (entry.header) table = entry.keys;
+    return { ...item, ...entry, table: [...table],
+      keys: entry.header ? entry.keys : [...table, ...entry.keys] };
+  });
+}

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

@@ -1,11 +1,12 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "private": true,
   "type": "module",
   "exports": {
     ".": "./src/index.mjs",
     "./hook-support": "./src/hook-support.mjs",
+    "./indicator": "./src/indicator-command.mjs",
     "./managed-entry": "./src/managed-runtime/entry.mjs",
     "./managed-worker": "./src/managed-runtime/worker.mjs"
   },

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

@@ -18,13 +18,15 @@ export const COMMANDS = Object.freeze({
   work: { required: [], optional: ["session", "generation", "summary", "mode",
     "state"], repeated: ["hint"], flags: ["clear"] },
   claim: { required: ["resource"],
-    optional: ["session", "generation", "mode", "enforcement", "reason", "lease"] },
+    optional: ["session", "generation", "mode", "enforcement", "reason", "lease"],
+    repeated: ["resource"] },
   // Neither is required on its own, because either one names the claim: an id
   // is precise, and a resource is what the caller typed to take it in the first
   // place. Requiring the id meant a round trip through `acc status --json` to
   // look up something the caller never chose.
   release: { required: [],
-    optional: ["claim", "resource", "session", "generation", "authority", "reason"] },
+    optional: ["session", "generation", "authority", "reason"],
+    repeated: ["claim", "resource"], flags: ["all"] },
   message: { required: ["subject", "body"],
     optional: ["session", "generation", "type", "obligation", "client-message-id"],
     repeated: ["to", "supersedes", "withdraws"] },
@@ -57,7 +59,7 @@ export const COMMANDS = Object.freeze({
   // `--downgrade` because an older acc first on PATH will otherwise rewire every
   // client to itself, and the only symptom is a guard behaving like the version
   // it came from.
-  install: { required: [], optional: ["home", "delivery"], repeated: ["adapter"],
+  install: { required: [], optional: ["home", "delivery", "indicator"], repeated: ["adapter"],
     flags: ["dry-run", "downgrade"] },
   // `--dry-run` on both, because the preview was computed for either action and
   // only `install` could ask for it. Removal is the side that reaches into a

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

@@ -0,0 +1,64 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { positiveNumber } from "./args.mjs";
+import { canonicalClaim } from "./claim-spelling.mjs";
+
+const list = value => value === undefined ? undefined : Array.isArray(value) ? value : [value];
+const owner = options => ({ sessionId: options.session, generation: options.generation });
+
+export async function runClaimCommand({ options, context }) {
+  const resources = await Promise.all(list(options.resource)
+    .map(resource => canonicalClaim(resource, context.descriptor)));
+  const input = { ...owner(options), mode: options.mode ?? "exclusive",
+    enforcement: options.enforcement ?? "advisory", reason: options.reason ?? "unspecified",
+    leaseSeconds: options.lease ? positiveNumber(options.lease, "lease") : undefined,
+    descriptor: context.descriptor };
+  if (resources.length === 1) {
+    const claim = await context.service.acquireClaim({ ...input, resource: resources[0] });
+    return { data: claim, text: `claimed ${claim.resource}` };
+  }
+  const claims = await context.service.acquireClaims({ ...input, resources });
+  return { data: { claims }, text: `claimed ${claims.length} resources` };
+}
+
+// Single-item authority keeps its existing lookup and ambiguity rules.
+async function authorityClaim(resource, context) {
+  const { claims } = await context.service.collectStatus({});
+  const matching = claims.filter(claim => claim.resource === resource);
+  if (matching.length === 0) throw new AccError(EXIT.DATA, `no claim on ${resource} to release`,
+    { resource, held: claims.map(claim => claim.resource) });
+  if (matching.length > 1) throw new AccError(EXIT.DATA,
+    `${matching.length} claims on ${resource}; name the one you mean with --claim`,
+    { resource, claims: matching.map(claim => claim.claimId) });
+  return matching[0].claimId;
+}
+
+export async function runReleaseCommand({ options, context }) {
+  const selectors = [options.claim, options.resource, options.all].filter(value => value !== undefined);
+  if (selectors.length !== 1) throw new AccError(EXIT.USAGE,
+    "release needs exactly one of --claim, --resource, or --all");
+  const claimIds = list(options.claim);
+  const resources = options.resource === undefined ? undefined
+    : await Promise.all(list(options.resource).map(resource => canonicalClaim(resource, context.descriptor)));
+  const scalar = options.all !== true && (claimIds ?? resources).length === 1;
+  if (options.authority !== undefined) {
+    if (!scalar) throw new AccError(EXIT.USAGE, "force-release authority requires a single claim");
+    const claimId = claimIds?.[0] ?? await authorityClaim(resources[0], context);
+    await context.service.forceReleaseClaim({ ...owner(options), claimId,
+      authority: options.authority, reason: options.reason });
+    return { data: { claimId }, text: `released ${claimId}` };
+  }
+  if (scalar && claimIds !== undefined) {
+    const claimId = claimIds[0];
+    await context.service.releaseClaim({ ...owner(options), claimId });
+    return { data: { claimId }, text: `released ${claimId}` };
+  }
+  const released = await context.service.releaseClaims({ ...owner(options),
+    ...(options.all === true ? { all: true } : resources !== undefined ? { resources } : { claimIds }) });
+  if (scalar) {
+    const claimId = released[0].claimId;
+    return { data: { claimId }, text: `released ${claimId}` };
+  }
+  return { data: { claimIds: released.map(claim => claim.claimId) },
+    text: `released ${released.length} claims` };
+}

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,