agents-can-communicate 0.1.1 → 0.1.3

package/README.md

@@ -75,13 +75,42 @@ npm install -g agents-can-communicate
 
 Then wire up the clients you have:
 
+```bash
+acc install
+```
+
+It names every file it wrote, in your own home-relative paths, and how to undo it. Open your
+clients in the project afterwards — in one directory or in several worktrees — and work
+normally.
+
+If you would rather look before it writes, `acc install --dry-run` prints the same list and
+changes nothing. `acc uninstall` takes it all back out.
+
 <!-- test:command -->
 ```bash
 acc install --dry-run
 ```
 
-This prints every file it would touch. Run `acc install` to apply it, then open your clients
-in the project — in one directory or in several worktrees — and work normally.
+## Keeping it current
+
+```bash
+acc update            # asks npm; --apply installs it and re-wires the clients
+```
+
+An upgrade is two steps, because it lands in two places. `npm install -g` replaces the CLI
+and the hook runtime — a client runs the runtime out of the npm directory rather than a copy
+— and leaves the bundle written into that client alone, including the skills the agents
+read. `acc install` refreshes it, and `acc doctor` says so when the two disagree:
+
+```console
+$ acc doctor
+store healthy; 2 live session(s); protection guarded; 3 of 4 adapter(s) installed
+  acc install --adapter claude_code  # plugin is 0.1.1, acc is 0.2.0
+```
+
+`acc update` is the only command that reaches the network. `acc doctor` reads what it
+remembered and asks at most once a day; nothing on the hook path ever asks, since a hook
+runs on every turn inside a five-second budget. `ACC_NO_UPDATE_CHECK=1` turns both off.
 
 ## Commands
 

package/bin/acc.mjs

@@ -3,7 +3,7 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 
 import { createId } from "@agents-can-communicate/protocol";
-import { main } from "@agents-can-communicate/cli";
+import { askConfirmation, main } from "@agents-can-communicate/cli";
 
 // The composition root is the only place allowed to reach for ambient time and
 // randomness; everything below it receives them as ports.
@@ -15,6 +15,13 @@ const runtime = {
   stderr: process.stderr,
   clock: { now: () => new Date().toISOString() },
   ids: { next: kind => createId(kind, randomBytes) },
+  // Asked only by `acc config init`, and only when stdout is a terminal. There
+  // was no port here at all, so the question went to the fallback that always
+  // answers no: in a real terminal the command printed "not written" and never
+  // said why, and `--yes` - the flag documented for runs with nobody to ask -
+  // was the only way to write the file.
+  confirm: question => askConfirmation(question,
+    { input: process.stdin, output: process.stdout }),
   // Asked for only by `acc version`, so a package missing its own manifest
   // fails that one command rather than every command.
   version: async () => JSON.parse(

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-claude-code/plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Coordinate this Claude Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs."
 }

package/node_modules/@agents-can-communicate/adapter-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Coordinate this Codex session with other AI agent sessions working in the same workspace.",
   "license": "UNLICENSED",
   "keywords": ["coordination", "multi-agent", "claims", "handoff"],

package/node_modules/@agents-can-communicate/adapter-codex/src/install.mjs

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -11,22 +11,35 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 const bundle = fileURLToPath(new URL("../plugin", import.meta.url));
 const PLUGIN_NAME = "agents-can-communicate";
 
-// The marketplace ACC owns. Registering a separate one rather than editing the
-// user's keeps the two apart: uninstall removes a marketplace ACC created and
-// never touches entries someone else put in theirs.
+// The marketplace ACC owns, and its own root inside the agents home.
+//
+// Registering a separate one rather than joining the user's keeps the two
+// apart. ACC used to write into `<home>/.agents/plugins/marketplace.json` -
+// which is the marketplace this client discovers by itself, with no config
+// entry at all, under whatever that manifest calls itself. So ACC merged its
+// entry into someone else's marketplace and then enabled `…@acc-local`, an id
+// this client never forms: `acc install` reported success and `codex plugin
+// list` said `not installed`. Measured against Codex 0.147.0, then measured
+// again to confirm a root of ACC's own is accepted and reported enabled.
 const MARKETPLACE = "acc-local";
 const QUALIFIED = `${PLUGIN_NAME}@${MARKETPLACE}`;
 
-// A marketplace is a directory whose manifest sits at
-// `<root>/.agents/plugins/marketplace.json`, and every `source.path` in that
-// manifest is relative to the manifest's own directory - `./plugins/<name>`,
-// as the client's own entries are written. Resolving the plugin from `root`
-// instead put the files two levels above where the manifest pointed, so the
-// entry named a directory that did not exist and the client loaded nothing.
-const marketplaceDir = root => path.join(root, ".agents", "plugins");
-const marketplacePath = root => path.join(marketplaceDir(root), "marketplace.json");
-const pluginPath = (root, name = PLUGIN_NAME) =>
-  path.join(marketplaceDir(root), "plugins", name);
+// A marketplace is a root holding `.agents/plugins/marketplace.json`, and every
+// `source.path` in that manifest - `./plugins/<name>` - is resolved by this
+// client against the *root*, not against the manifest's directory. Measured:
+// `codex plugin list` prints the path it resolved, and for a plugin the user
+// installed themselves it printed `<root>/plugins/x` from an entry spelled
+// `./plugins/x`. The comment that used to be here said the opposite, and ACC
+// wrote its tree two directories below where the client then looked.
+//
+// The root is under `.agents/` rather than the home itself: `<home>/plugins/`
+// is where this client would put it, and nothing of ACC's belongs at the top of
+// somebody's home.
+const marketplaceRoot = agentsHome => path.join(agentsHome, ".agents", MARKETPLACE);
+const marketplacePath = agentsHome =>
+  path.join(marketplaceRoot(agentsHome), ".agents", "plugins", "marketplace.json");
+const pluginPath = (agentsHome, name = PLUGIN_NAME) =>
+  path.join(marketplaceRoot(agentsHome), "plugins", name);
 const configPath = codexHome => path.join(codexHome, "config.toml");
 // Where `codex plugin add` leaves the copy it actually runs. All three
 // components are ACC's own - the marketplace it created, the plugin name it
@@ -111,6 +124,11 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // plugin tree is laid down that nothing will then be able to remove.
   const existing = await readJson(marketplacePath(agentsHome), { name: MARKETPLACE,
     interface: { displayName: "Agents Can Communicate" }, plugins: [] });
+  // The name in the manifest, which is the one this client forms plugin ids
+  // from. ACC used its own regardless, so on a machine that already had a
+  // marketplace at this root - discovered without any config entry, under
+  // whatever its manifest calls itself - the id ACC enabled was one the client
+  // never forms, and the plugin sat there listed and not installed.
   const before = await readFile(configPath(codexHome), "utf8").catch(() => "");
 
   const target = pluginPath(agentsHome);
@@ -142,7 +160,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
   await writeTomlBlock(config, [
     `[marketplaces.${MARKETPLACE}]`,
     `source_type = "local"`,
-    `source = ${tomlString(agentsHome)}`,
+    `source = ${tomlString(marketplaceRoot(agentsHome))}`,
     "",
     `[plugins.${tomlString(QUALIFIED)}]`,
     "enabled = true",
@@ -156,13 +174,26 @@ export async function installCodexPlugin({ home, agentsHome = home,
   await rm(cached, { recursive: true, force: true });
   await cp(target, cached, { recursive: true });
 
-  // The cache *root* rather than the versioned directory inside it: that is
-  // what ACC owns and what uninstall removes, and reporting the version would
+  // The plugin's own directory in the cache. Not the versioned one inside it,
+  // which goes stale the moment the version changes - and not the marketplace
+  // cache root above it, which belongs to whoever's marketplace this is: that
+  // root holds every plugin installed from it, and removing it took a plugin
+  // the user had installed themselves. Measured, on a real machine.
+  //
+  // The old comment here said the root was "what ACC owns", which was true only
+  // while ACC invented its own marketplace name and so had a root to itself.
   // make the record stale the moment the plugin version changes.
-  return { ok: true, changes: [target, file, config, cacheRoot(codexHome)],
+  return { ok: true, changes: [target, file, config, cachePath(codexHome)],
     diagnostics: ["hooks require explicit trust in Codex before they run"] };
 }
 
+/** Remove each directory that is empty, in the order given. */
+async function removeEmptyDirs(directories) {
+  for (const directory of directories) {
+    await rmdir(directory).catch(() => {});
+  }
+}
+
 export async function uninstallCodexPlugin({ home, agentsHome = home,
   codexHome = path.join(home, ".codex"), keep = [] }) {
   const file = marketplacePath(agentsHome);
@@ -190,8 +221,20 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
       return value?.name === MARKETPLACE && (value.plugins ?? []).length === 0;
     } });
 
-  await removeInstalledTree(cacheRoot(codexHome), keep);
+  await removeInstalledTree(cachePath(codexHome), keep);
   await removeInstalledTree(pluginPath(agentsHome), keep);
+  // The directories ACC made to hold those, once nothing is in them. They are
+  // ACC's own - a marketplace root it created and the cache directory named
+  // after it - and an empty one left behind is litter in a home that did not
+  // have it. Anything the user put inside stops this: the directory is not
+  // empty, and it stays.
+  await removeEmptyDirs([
+    path.join(marketplaceRoot(agentsHome), "plugins"),
+    path.dirname(marketplacePath(agentsHome)),
+    path.dirname(path.dirname(marketplacePath(agentsHome))),
+    marketplaceRoot(agentsHome),
+    cacheRoot(codexHome),
+  ]);
   return { ok: true, changes, diagnostics: [] };
 }
 
@@ -202,7 +245,8 @@ export async function detectCodex({ home, agentsHome = home,
   const config = await readFile(configPath(codexHome), "utf8").catch(() => "");
   const registered = config.includes(`[marketplaces.${MARKETPLACE}]`);
   const enabled = config.includes(`[plugins."${QUALIFIED}"]`);
-  const cached = await stat(cachePath(codexHome)).then(() => true).catch(() => false);
+  const cached = await stat(cachePath(codexHome))
+    .then(() => true).catch(() => false);
   return { ok: true, changes: [], diagnostics: [
     published ? "acc plugin published in the marketplace" : "acc plugin not registered",
     registered && enabled
@@ -228,7 +272,7 @@ export function planCodexInstall({ home, agentsHome = home,
   codexHome = path.join(home, ".codex") }) {
   return [
     { path: pluginPath(agentsHome), kind: "tree" },
-    { path: cacheRoot(codexHome), kind: "tree" },
+    { path: cachePath(codexHome), kind: "tree" },
     { path: marketplacePath(agentsHome), kind: "merge" },
     { path: configPath(codexHome), kind: "merge" },
   ];

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/plugin/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Coordinate this Kimi Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs.",
   "skills": "./skills/",
   "sessionStart": {

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/src/hook-shim.mjs

@@ -87,7 +87,34 @@ export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
     "# Generated by ACC at install time. The paths are pinned deliberately:",
     "# a hook runs with an environment that may carry neither PATH nor a shell",
     "# profile, and a command that cannot be found fails silently on every event.",
-    `exec ${quote(node)} ${quote(runner)} ${adapterId} "$@"`,
+    "#",
+    "# Pinned first, and then asked for, because the pinned pair moves. A node",
+    "# version manager changes both the interpreter and the directory global",
+    "# packages live in, and a shim naming the old ones failed on every event",
+    "# with nothing to read but exit 126 - no presence, no claims, no messages,",
+    "# and nothing anywhere saying why.",
+    `ACC_NODE=${quote(node)}`,
+    `ACC_RUNNER=${quote(runner)}`,
+    'if [ -x "$ACC_NODE" ] && [ -f "$ACC_RUNNER" ]; then',
+    `  exec "$ACC_NODE" "$ACC_RUNNER" ${adapterId} "$@"`,
+    "fi",
+    "# Whatever node is current, if this package is installed under it: `acc-hook`",
+    "# is the binary npm links, so a reinstall is found without knowing where.",
+    "# It needs node too - its shebang is `env node` - and `exec` that fails ends",
+    "# this script where it stands, taking the fallbacks below with it: measured",
+    "# as exit 127 and `env: node: No such file or directory`, in place of the",
+    "# line that says what to do.",
+    "if command -v acc-hook >/dev/null 2>&1 && command -v node >/dev/null 2>&1; then",
+    `  exec acc-hook ${adapterId} "$@"`,
+    "fi",
+    'if [ -f "$ACC_RUNNER" ] && command -v node >/dev/null 2>&1; then',
+    `  exec node "$ACC_RUNNER" ${adapterId} "$@"`,
+    "fi",
+    "# Say so, and let the turn continue. Hooks fail open by design, and a broken",
+    "# install must not be the reason somebody's session stops working.",
+    'echo "acc: the hook runner installed here is gone (node: $ACC_NODE)." >&2',
+    'echo "acc: run \'acc install\' to wire this client to the acc you have now." >&2',
+    "exit 0",
     "",
   ].join("\n"));
   await chmod(target, 0o755);

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -56,11 +56,17 @@ export const COMMANDS = Object.freeze({
   // inside a handler that has already decided what to do.
   config: { required: [], optional: [], flags: ["yes", "force"],
     subcommands: ["init", "validate"] },
-  install: { required: [], optional: ["adapter", "home"], flags: ["dry-run", "yes"] },
+  // No `--yes`: neither of these ever asked, so the flag agreed to nothing. It
+  // was accepted and read by nobody, which is a promise that a confirmation
+  // exists to be skipped.
+  install: { required: [], optional: ["adapter", "home"], flags: ["dry-run"] },
   // `--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
   // client's configuration - including a client that has left the machine.
-  uninstall: { required: [], optional: ["adapter", "home"], flags: ["dry-run", "yes"] },
+  uninstall: { required: [], optional: ["adapter", "home"], flags: ["dry-run"] },
+  // Asking npm whether there is a newer ACC. The one command that touches the
+  // network, and never on the hook path.
+  update: { required: [], optional: [], flags: ["apply"] },
   // The two things a person types first after installing from a registry. The
   // CLI answered neither: `acc --version` and `acc --help` were both "unknown
   // command", and `acc` on its own asked for a command without naming one.

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

@@ -0,0 +1,33 @@
+import { once } from "node:events";
+import { createInterface } from "node:readline/promises";
+
+/**
+ * Ask a yes-or-no question and wait for the answer.
+ *
+ * A port rather than a call to the terminal, so the composition root hands it
+ * in and a test hands in two streams instead. There was no port at all:
+ * `runtime.confirm` fell back to a function that always answered no, so `acc
+ * config init` in a real terminal printed `not written` and never said why -
+ * and `--yes`, documented for runs with nobody to ask, was the only way to
+ * write the file.
+ *
+ * Anything that is not yes is no. A confirmation that reads a stray newline as
+ * agreement is not a confirmation.
+ */
+export async function askConfirmation(question, { input, output }) {
+  const dialogue = createInterface({ input, output });
+  try {
+    const asked = dialogue.question(`${question}\n[y/N] `);
+    // The input closing before an answer arrives is the reader leaving - Ctrl+D,
+    // or a pipe that ended - which is a refusal rather than a failure. Raced
+    // rather than caught: the question simply never settles on a stream that
+    // ends, so waiting for it alone hangs.
+    asked.catch(() => {});
+    const answer = await Promise.race([asked, once(dialogue, "close").then(() => "")]);
+    return /^y(es)?$/i.test(answer.trim());
+  } catch {
+    return false;
+  } finally {
+    dialogue.close();
+  }
+}

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

@@ -1,10 +1,13 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 
-import { detectInstallation, verifyOwned } from "@agents-can-communicate/installer";
+import { detectInstallation, loadOwnership, verifyOwned }
+  from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-import { ALL_ADAPTERS, clientContext } from "./install-command.mjs";
+import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs";
 import { platformPaths } from "./platform-paths.mjs";
+import { noticeUpdate } from "./update-check.mjs";
 import { diagnoseFilesystemStore, repairFilesystemStore }
   from "@agents-can-communicate/storage-filesystem";
 
@@ -13,6 +16,23 @@ import { diagnoseFilesystemStore, repairFilesystemStore }
  * closed: anything blocked or corrupt stops the run rather than being repaired
  * on top of state the tool cannot even read.
  */
+/**
+ * The bundle in a client outlives the package that put it there.
+ *
+ * `npm install -g` replaces this CLI and the hook runtime - the shim runs the
+ * runtime out of the npm directory rather than a copy - and does not touch what
+ * was written into the client: its `hooks.json`, and the skills the agents read.
+ * Measured: after an upgrade the client still had `0.1.0` while `acc --version`
+ * said `0.1.1`, and doctor called it healthy.
+ *
+ * Unknown when the install predates the record carrying it, and then nothing is
+ * said: "your plugin might be old" on every run is not a diagnosis.
+ */
+export function staleInstall({ recorded, running }) {
+  if (typeof recorded !== "string" || typeof running !== "string") return null;
+  return recorded === running ? null : { recorded, running };
+}
+
 async function diagnoseAdapters({ options, runtime }) {
   // The same home `acc install --home` writes to, or the real one. Reading a
   // different home than install wrote to reports every adapter as missing.
@@ -21,7 +41,12 @@ async function diagnoseAdapters({ options, runtime }) {
   const { data: dataHome } = platformPaths({ platform: runtime?.platform,
     env: runtime?.env ?? {} });
   const adapters = ALL_ADAPTERS();
-  const detected = await detectInstallation({ adapters, context: clients });
+  const detected = await detectInstallation({ adapters, context: clients,
+    probeTimeoutMs: probeTimeout(runtime?.env) });
+  const record = await loadOwnership({ dataHome });
+  const running = typeof runtime?.version === "function"
+    ? await runtime.version().catch(() => null)
+    : null;
 
   return Promise.all(detected.map(async entry => {
     // Compared against what ACC recorded writing, so a plugin someone has since
@@ -37,7 +62,15 @@ async function diagnoseAdapters({ options, runtime }) {
     if (owned.missing.length > 0) {
       remediation.push(`acc install --adapter ${entry.adapterId}  # files are missing`);
     }
-    return { ...entry, owned: { modified: owned.modified, missing: owned.missing,
+    const stale = staleInstall({
+      recorded: record.installs.find(install => install.adapterId === entry.adapterId)
+        ?.accVersion ?? null,
+      running });
+    if (stale !== null) {
+      remediation.push(`acc install --adapter ${entry.adapterId}`
+        + `  # plugin is ${stale.recorded}, acc is ${stale.running}`);
+    }
+    return { ...entry, stale, owned: { modified: owned.modified, missing: owned.missing,
       intact: owned.intact.length }, remediation };
   }));
 }
@@ -48,6 +81,14 @@ export async function runDoctor({ options, context, runtime }) {
     ? await repairFilesystemStore({ root, clock: context.service.clock })
     : await diagnoseFilesystemStore({ root });
   const adapters = await diagnoseAdapters({ options, runtime });
+  const { data: dataHome } = platformPaths({ platform: runtime?.platform,
+    env: runtime?.env ?? {} });
+  const running = typeof runtime?.version === "function"
+    ? await runtime.version().catch(() => null)
+    : null;
+  const update = await noticeUpdate({ dataHome, running, env: runtime?.env ?? {},
+    now: Date.parse(context.service.clock.now()), get: runtime?.fetch,
+    io: { readFile, writeFile, mkdir } });
 
   // Before the store is read for anything else. `collectStatus` reads every
   // record, so on the store this command exists to describe it threw first and
@@ -76,10 +117,20 @@ export async function runDoctor({ options, context, runtime }) {
     store: report,
     // Capabilities are reported from what is actually installed, never assumed.
     adapters,
-    remediation: adapters.flatMap(adapter => adapter.remediation),
+    update,
+    remediation: [...adapters.flatMap(adapter => adapter.remediation),
+      // Said here rather than in its own line of prose, because this list is
+      // what a reader acts on and an upgrade is one more thing to run.
+      ...(update.newer ? [`acc update --apply  # ${update.latest} is on npm, `
+        + `you have ${running}`] : [])],
   };
   const installed = adapters.filter(adapter => adapter.installed).length;
-  const text = `store healthy; ${status.counts.live} live session(s); `
-    + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`;
+  // The remediation was computed, put in the data, and never printed: the
+  // command documented as saying "what to run next" said it only to `--json`.
+  // A person running `acc doctor` on a client wired to an older plugin was told
+  // the store was healthy and nothing else.
+  const text = [`store healthy; ${status.counts.live} live session(s); `
+    + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`,
+  ...data.remediation.map(line => `  ${line}`)].join("\n");
   return { data, text };
 }

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

@@ -16,7 +16,7 @@ const GROUPS = Object.freeze([
   ["In a session", ["status", "sync", "work", "claim", "release", "ack", "message",
     "request", "task", "workstream", "decide", "finish"]],
   ["Driven by adapters, not by people", ["attach", "heartbeat", "detach"]],
-  ["About acc", ["help", "version"]],
+  ["About acc", ["help", "version", "update"]],
 ]);
 
 const SUMMARY = Object.freeze({
@@ -41,6 +41,7 @@ const SUMMARY = Object.freeze({
   detach: "close a session",
   help: "this list",
   version: "print the version that is installed",
+  update: "ask npm whether a newer acc exists; --apply installs it",
 });
 
 /** The same list `acc help --json` returns, so a tool can read it too. */

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

@@ -1,6 +1,7 @@
 // Composition root: discovery, runtime locations, and the CLI surface.
 export { main } from "./main.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
 // which binary decides it runs at all.
 export { ALL_ADAPTERS, clientContext } from "./install-command.mjs";

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

@@ -28,6 +28,20 @@ export const clientContext = home => ({
 export const ALL_ADAPTERS = () => [createClaudeCodeAdapter(), createCodexAdapter(),
   createGeminiCliAdapter(), createKimiAdapter()];
 
+/**
+ * How long to wait for a client to say its version.
+ *
+ * Detection spawns the client's own binary, and three seconds is generous on an
+ * idle machine and not always enough on a busy one: a cold start that overruns
+ * it makes an installed client look absent, and the installer skips it saying so
+ * in as many words. Raising it is for the machine that needs it - a loaded CI
+ * runner, a slow disk - rather than a default nobody can change.
+ */
+export function probeTimeout(env) {
+  const asked = Number.parseInt(env?.ACC_PROBE_TIMEOUT_MS ?? "", 10);
+  return Number.isFinite(asked) && asked > 0 ? asked : undefined;
+}
+
 function selectAdapters(requested) {
   const all = ALL_ADAPTERS();
   if (requested === undefined) return all;
@@ -60,11 +74,52 @@ function selectAdapters(requested) {
  * carries one per skipped adapter and the result one per failure - and only
  * `--json` ever showed them.
  */
-export function describeOutcome({ action, acted, failed = [], skipped = [] }) {
+const shorten = (file, home) =>
+  typeof home === "string" && home !== "" && file.startsWith(`${home}/`)
+    ? `~${file.slice(home.length)}`
+    : file;
+
+/**
+ * What one adapter did, path by path.
+ *
+ * `installed 3 adapter(s)` was the whole account of a command that had just
+ * written into three other tools' configuration inside someone's home. The list
+ * existed all along - it is what `--dry-run` prints - and the run that actually
+ * did the work printed a number.
+ *
+ * An install says what it wrote from the plan it carried out, in the same words
+ * the preview uses. An uninstall says what was removed and what was held back,
+ * because those are decided while it runs: bytes that stopped matching what ACC
+ * wrote are someone's now, and are kept.
+ */
+export function describeChanges(operation, home) {
+  const artifacts = operation.artifacts ?? [];
+  const edited = artifacts.filter(artifact => artifact.kind === "merge")
+    .map(artifact => `  edited  ${shorten(artifact.path, home)}`);
+  if (operation.action !== "uninstall") {
+    return [...artifacts.filter(artifact => artifact.kind !== "merge")
+      .map(artifact => `  created ${shorten(artifact.path, home)}`), ...edited];
+  }
+  return [
+    ...(operation.removed ?? []).map(file => `  removed ${shorten(file, home)}`),
+    ...edited,
+    ...(operation.kept ?? [])
+      .map(file => `  kept    ${shorten(file, home)} - changed since ACC wrote it`),
+  ];
+}
+
+export function describeOutcome({ action, acted, failed = [], skipped = [],
+  operations = [], home }) {
   return [`${action}ed ${acted} adapter(s)`
     + (failed.length > 0 ? `; ${failed.length} failed` : ""),
+  ...operations.filter(operation => operation.applied)
+    .flatMap(operation => describeChanges(operation, home)),
   ...skipped.map(entry => `  skip ${entry.adapterId}: ${entry.reason}`),
-  ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`)].join("\n");
+  ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`),
+  // Said once, where it is needed: the reader has just been shown a list of
+  // their own files with ACC's name in them.
+  ...(action === "install" && acted > 0 ? ["", "undo with: acc uninstall"] : []),
+  ].join("\n");
 }
 
 /**
@@ -102,7 +157,8 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
     env: runtime.env ?? {} });
 
-  const detected = await detectInstallation({ adapters, context });
+  const detected = await detectInstallation({ adapters, context,
+    probeTimeoutMs: probeTimeout(runtime.env) });
   // An uninstall is planned from what ACC recorded writing, not only from what
   // is on the machine now. A client can be removed after ACC installed into it,
   // and its configuration directory - with ACC's files in it - stays behind.
@@ -112,7 +168,13 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const plan = planInstallation({ adapters, detected, context, action, recorded });
 
   const dryRun = options.dryRun === true;
-  const result = await applyPlan({ plan, adapters, context, dataHome, dryRun });
+  // Recorded with the install, so a later run can tell that the bundle sitting
+  // in a client is older than the code now running. Updating the npm package
+  // replaces this CLI and the hook runtime and leaves that bundle untouched.
+  const accVersion = typeof runtime.version === "function"
+    ? await runtime.version().catch(() => null)
+    : null;
+  const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
 
   const acted = actedOn(result);
   if (dryRun) {
@@ -123,6 +185,6 @@ export async function runInstallCommand({ options, runtime, action = "install" }
 
   return { data: { ...result, plan, dataHome },
     text: describeOutcome({ action, acted, failed: result.failed,
-      skipped: plan.skipped }),
+      skipped: plan.skipped, operations: result.operations, home }),
     error: failureOf({ action, acted, failed: result.failed }) };
 }

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

@@ -9,6 +9,7 @@ import { parseArgs, positiveNumber } from "./args.mjs";
 // with the argument already half-applied.
 const usage = message => new AccError(EXIT.USAGE, message);
 import { describeCommands, helpText } from "./help.mjs";
+import { runUpdateCommand } from "./update-command.mjs";
 import { runConfigCommand } from "./config-command.mjs";
 import { runInstallCommand } from "./install-command.mjs";
 import { runDoctor } from "./doctor-command.mjs";
@@ -252,7 +253,12 @@ const HANDLERS = Object.freeze({
       // command demands --yes rather than hanging or assuming consent.
       interactive: runtime.stdout?.isTTY === true,
       yes: options.yes === true,
-      confirm: runtime.confirm ?? (async () => false),
+      // Not a silent no. A build that cannot ask says so: falling back to
+      // "declined" is how `acc config init` came to print `not written` in a
+      // terminal where nobody had been asked anything.
+      confirm: runtime.confirm ?? (async () => {
+        throw new AccError(EXIT.DATA, "this build was assembled without a way to ask");
+      }),
       force: options.force === true,
       // Opened lazily and only by `init`: `config validate` has to work on a
       // workspace discovery cannot open, which is what a reader runs it to
@@ -275,6 +281,8 @@ const HANDLERS = Object.freeze({
 
   doctor: async ({ options, context, runtime }) => runDoctor({ options, context, runtime }),
 
+  update: async ({ options, runtime }) => runUpdateCommand({ options, runtime }),
+
   help: async () => ({ data: { commands: describeCommands() }, text: helpText() }),
 
   version: async ({ runtime }) => {
@@ -294,7 +302,8 @@ const HANDLERS = Object.freeze({
 /**
  * @returns {Promise<number>} the process exit code
  */
-const NO_WORKSPACE = Object.freeze(["config", "install", "uninstall", "help", "version"]);
+const NO_WORKSPACE = Object.freeze(["config", "install", "uninstall", "help", "version",
+  "update"]);
 
 export async function main(argv, runtime) {
   const write = (stream, text) => new Promise((resolve, reject) =>

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

@@ -23,11 +23,24 @@ export function runtimePaths({ dataHome, workspaceId, workspaceRoots = [] }) {
   // Enforced here rather than only asserted in a test, because "just put it in
   // .agents next to the project" is the exact regression this design exists to
   // prevent, and it would otherwise look like it works.
+  //
+  // The message names both paths and what to do, because the case a person
+  // actually meets is not the one this was written for. Running `acc` in a home
+  // directory makes that directory the workspace - it is no checkout, so
+  // discovery falls back to where you are - and the platform's own state
+  // directory is inside a home by definition. So `acc status` in `~` answered
+  // "runtime state must not live inside the workspace", which reads as a
+  // misconfiguration and tells the reader nothing they can act on.
   for (const workspaceRoot of workspaceRoots) {
     const relative = path.relative(workspaceRoot, root);
     if (relative === "" || (!path.isAbsolute(relative) && !relative.startsWith(".."))) {
-      throw new AccError(EXIT.USAGE, "runtime state must not live inside the workspace",
-        { root, workspaceRoot });
+      throw new AccError(EXIT.USAGE,
+        // The data home rather than the workspace's own directory inside it:
+        // that is the one a reader can move, and the one the remedy names.
+        `${workspaceRoot} holds ACC's own state at ${path.join(dataHome, "acc")}, `
+        + "so it cannot be a workspace. Run acc inside a project, or point "
+        + "ACC_DATA_HOME outside this directory.",
+        { root, dataHome, workspaceRoot });
     }
   }
   return Object.freeze(Object.fromEntries([["root", root],

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

@@ -0,0 +1,113 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * Asking npm whether there is a newer ACC.
+ *
+ * This is the only part of ACC that touches the network, and it is kept to one
+ * file for that reason. It is never on the hook path: a hook runs every turn
+ * inside a five-second budget and fails open, so a stalled socket there would
+ * cost every turn on the machine something and report nothing. `acc update`
+ * asks, `acc doctor` reads what was cached, and the answer is remembered for a
+ * day so a diagnostic run does not become traffic.
+ *
+ * `ACC_NO_UPDATE_CHECK=1` turns it off entirely, and then it says it is off
+ * rather than saying the version is current.
+ */
+const REGISTRY = "https://registry.npmjs.org/agents-can-communicate/latest";
+const EVERY_MS = 24 * 60 * 60 * 1000;
+const TIMEOUT_MS = 3_000;
+
+const cacheFile = dataHome => path.join(dataHome, "acc", "update-check.json");
+
+export const checkingIsOff = env => {
+  const value = env?.ACC_NO_UPDATE_CHECK;
+  return value !== undefined && value !== "" && value !== "0";
+};
+
+const numbers = version => (typeof version === "string"
+  ? version.trim().split("-", 1)[0].split(".") : [])
+  .map(part => Number.parseInt(part, 10));
+
+/**
+ * Whether `candidate` is a later release than `current`.
+ *
+ * Anything unreadable is not newer. Telling somebody to upgrade because a
+ * version could not be parsed is worse than saying nothing.
+ */
+export function isNewer(candidate, current) {
+  const left = numbers(candidate);
+  const right = numbers(current);
+  if (left.length === 0 || left.some(Number.isNaN)) return false;
+  if (right.length === 0 || right.some(Number.isNaN)) return false;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const one = left[index] ?? 0;
+    const other = right[index] ?? 0;
+    if (one !== other) return one > other;
+  }
+  return false;
+}
+
+/** Whether a remembered answer is old enough to ask again. */
+export function checkDue({ checkedAt, now, everyMs = EVERY_MS }) {
+  const last = Date.parse(checkedAt ?? "");
+  return !Number.isFinite(last) || now - last >= everyMs;
+}
+
+export async function readCachedCheck(dataHome, { readFile }) {
+  try {
+    const cached = JSON.parse(await readFile(cacheFile(dataHome), "utf8"));
+    return { latest: cached.latest ?? null, checkedAt: cached.checkedAt ?? null };
+  } catch {
+    // A missing or unreadable note is the same as never having asked.
+    return { latest: null, checkedAt: null };
+  }
+}
+
+export async function writeCachedCheck(dataHome, entry, { writeFile, mkdir }) {
+  const file = cacheFile(dataHome);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(entry, null, 2)}\n`);
+}
+
+/** Ask the registry. The one network call in the product. */
+export async function fetchLatest({ get = fetch, url = REGISTRY,
+  timeoutMs = TIMEOUT_MS } = {}) {
+  const response = await get(url, { signal: AbortSignal.timeout(timeoutMs),
+    headers: { accept: "application/json" } });
+  if (response?.ok !== true) {
+    throw new AccError(EXIT.DATA, `the registry answered ${response?.status ?? "nothing"}`,
+      { url });
+  }
+  const body = await response.json();
+  if (typeof body?.version !== "string" || numbers(body.version).some(Number.isNaN)) {
+    throw new AccError(EXIT.DATA, "the registry did not answer with a version", { url });
+  }
+  return body.version;
+}
+
+/**
+ * What `acc doctor` says about a newer release, without becoming a network
+ * command.
+ *
+ * The answer is remembered for a day, so running the diagnostic twice does not
+ * ask twice. A registry that cannot be reached changes nothing: doctor is about
+ * this machine, and a network that is down is not a fault in this install.
+ */
+export async function noticeUpdate({ dataHome, running, env, now, get, io }) {
+  if (checkingIsOff(env)) return { checked: false, latest: null, newer: false };
+
+  const cached = await readCachedCheck(dataHome, io);
+  let latest = cached.latest;
+  if (checkDue({ checkedAt: cached.checkedAt, now })) {
+    try {
+      latest = await fetchLatest({ get });
+      await writeCachedCheck(dataHome,
+        { latest, checkedAt: new Date(now).toISOString() }, io);
+    } catch {
+      latest = cached.latest;
+    }
+  }
+  return { checked: true, latest: latest ?? null, newer: isNewer(latest, running) };
+}

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

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { platformPaths } from "./platform-paths.mjs";
+import { checkingIsOff, fetchLatest, isNewer, writeCachedCheck } from "./update-check.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The two commands an upgrade takes, and why it is two.
+ *
+ * `npm install -g` replaces this CLI and the hook runtime, because the shim a
+ * client runs points into the npm directory rather than at a copy. It does not
+ * touch what was written into the client: its hook wiring, and the skills the
+ * agents read. Measured after an upgrade - the client still had `0.1.0` while
+ * `acc --version` said `0.1.1`, and nothing said so.
+ */
+export const upgradeSteps = version => [
+  ["npm", ["install", "--global", `agents-can-communicate@${version}`]],
+  ["acc", ["install"]],
+];
+
+const spell = ([command, argv]) => `  ${command} ${argv.join(" ")}`;
+
+export async function runUpdateCommand({ options, runtime }) {
+  const env = runtime.env ?? {};
+  const { data: dataHome } = platformPaths({ platform: runtime.platform, env });
+  const running = typeof runtime.version === "function"
+    ? await runtime.version().catch(() => null)
+    : null;
+
+  // Off means off, and it says so rather than reporting that nothing is newer -
+  // which is a different fact, and one this run did not establish.
+  if (checkingIsOff(env)) {
+    return { data: { checked: false, running, latest: null },
+      text: "update checking is off (ACC_NO_UPDATE_CHECK); nothing was asked" };
+  }
+
+  // Caught, and then refused rather than degraded. `doctor` and `install` can
+  // carry on without knowing which ACC is running - they say less - but this
+  // command is the comparison, and `isNewer(latest, null)` is false: carrying on
+  // would answer "you have the latest" on the strength of not knowing.
+  if (running === null) {
+    throw new AccError(EXIT.DATA,
+      "cannot read the installed version, so there is nothing to compare against");
+  }
+
+  const latest = await fetchLatest({ get: runtime.fetch });
+  await writeCachedCheck(dataHome, { latest, checkedAt: runtime.clock.now() },
+    { writeFile, mkdir });
+
+  if (!isNewer(latest, running)) {
+    return { data: { checked: true, running, latest, newer: false },
+      text: `acc ${running} is the latest` };
+  }
+
+  const steps = upgradeSteps(latest);
+  const data = { checked: true, running, latest, newer: true,
+    steps: steps.map(([command, argv]) => [command, ...argv].join(" ")) };
+
+  if (options.apply !== true) {
+    return { data, text: [`acc ${latest} is available; you have ${running}`, "",
+      ...steps.map(spell), "", "or run: acc update --apply"].join("\n") };
+  }
+
+  const spawn = runtime.spawn ?? ((command, argv) => execFileAsync(command, argv, { env }));
+  const done = [];
+  for (const [command, argv] of steps) {
+    try {
+      await spawn(command, argv);
+      done.push([command, ...argv].join(" "));
+    } catch (error) {
+      // Named rather than swallowed, and the rest of the commands are printed:
+      // a global install refused for want of permission is the ordinary case,
+      // and the person can finish it by hand from here.
+      return { data: { ...data, applied: done, failed: [command, ...argv].join(" ") },
+        text: [`${command} failed: ${error.message}`, "", "finish it with:",
+          ...steps.slice(done.length).map(spell)].join("\n"),
+        error: undefined };
+    }
+  }
+  return { data: { ...data, applied: done }, text: `updated to ${latest}` };
+}

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

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

@@ -12,7 +12,8 @@ import { recordInstall, removeOwned } from "./ownership.mjs";
  * A failure does not end the run. Someone installing four clients wants the
  * three that work, plus the name of the one that did not.
  */
-export async function applyPlan({ plan, adapters, context, dataHome, dryRun = false }) {
+export async function applyPlan({ plan, adapters, context, dataHome, dryRun = false,
+  accVersion = null }) {
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
   const results = { action: plan.action, dryRun, operations: [], skipped: plan.skipped,
     failed: [] };
@@ -34,7 +35,8 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         // did not happen. The reverse order would leave uninstall trying to
         // remove files nothing created.
         await recordInstall({ dataHome, adapterId: adapter.id,
-          version: operation.clientVersion ?? null, artifacts: operation.artifacts });
+          version: operation.clientVersion ?? null, accVersion,
+          artifacts: operation.artifacts });
         results.operations.push({ ...operation, applied: true,
           changes: outcome.changes ?? [], diagnostics: outcome.diagnostics ?? [] });
       } else {

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

@@ -102,7 +102,14 @@ async function saveOwnership({ dataHome, record }) {
  * second run's record describes what is actually on disk now, and an accumulated
  * one would list artifacts from a layout that no longer exists.
  */
-export async function recordInstall({ dataHome, adapterId, version, artifacts }) {
+/**
+ * @param version the client's version, as detected. `accVersion` is ACC's own,
+ * which is what tells a later run that the plugin in the client is older than
+ * the code now running: updating the npm package replaces the CLI and the hook
+ * runtime, and leaves the bundle inside the client exactly where it was.
+ */
+export async function recordInstall({ dataHome, adapterId, version, accVersion = null,
+  artifacts }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -113,7 +120,7 @@ export async function recordInstall({ dataHome, adapterId, version, artifacts })
   const record = await loadOwnership({ dataHome });
   await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
     installs: [...record.installs.filter(install => install.adapterId !== adapterId),
-      { adapterId, version, artifacts: stamped }] } });
+      { adapterId, version, accVersion, artifacts: stamped }] } });
 }
 
 const installFor = (record, adapterId) =>

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Model- and harness-agnostic coordination for independent AI agent sessions.",
   "keywords": [