agents-can-communicate 0.5.4 → 0.5.5

package/docs/ARCHITECTURE.md

@@ -174,7 +174,12 @@ The CLI owns installation generations under `<dataHome>/acc/runtime`, outside wo
 All five launch paths select a generation and publish an actual-process lease under one
 admission mutex before loading workspace-capable code. Immutable launcher modules and
 runtime directories preserve in-progress imports. Leases survive `main()` returning and
-are removed only after confirmed process death. A session is also pinned to the generation
+are removed only after confirmed process death. Older updaters can omit the store contract
+when publishing a newer generation. The reader recovers missing contracts only from the
+referenced generation, after checking its package identity and content hash, including file
+modes. It preserves explicit declarations and does not rewrite live leases. Missing or
+changed generation files and unknown native bindings remain unverified holds.
+A session is also pinned to the generation
 it started with: its hooks delegate to that generation while the pin declares the same
 store contract this one does, and run the active generation otherwise. A generation
 directory is reclaimed once no control pointer, live lease, live pin or staging hold names

package/docs/TROUBLESHOOTING.md

@@ -238,8 +238,9 @@ Next: [Getting started](GETTING_STARTED.md) · [Capabilities](CAPABILITIES.md)
 
 Run `acc doctor` to see the update policy and pending notice. A hold keeps an update
 pending only while the store contract it declares differs from the incoming version's or
-is unknown; records written before 0.5.0 declare none, so the first update after upgrading
-still waits for all of them. `acc update` names each remaining hold with its process and
+is unknown. ACC can recover a missing contract from the process's unchanged managed
+generation when that generation declares one. A generation that predates the declaration
+still needs its processes to exit. `acc update` names each remaining hold with its process and
 its declared contract. ACC process leases, including persistent MCP servers, end on
 confirmed process exit. Native bindings clear on observed SessionEnd or confirmed process
 death; a vendor daemon may remain alive after SessionEnd. Unknown PIDs remain holds until
@@ -250,6 +251,21 @@ unrelated holds still require lifecycle cleanup or confirmed process exit; safet
 do not expire merely by elapsed time. See
 [maintenance and recovery](UPGRADING.md#confirmed-client-service-maintenance).
 
+If ACC 0.5.3 or 0.5.4 reports `acc-claude-channel; contract unknown` after an earlier
+0.4.x upgrade, its active pointer may have lost the contract field. This can affect newly
+opened Channels too. A pending old updater retries its downloaded release without looking
+for a newer fix. Install the current global CLI, then use that CLI to complete the update:
+
+```bash
+npm install -g agents-can-communicate@latest
+acc update
+acc doctor
+```
+
+The new reader can activate a compatible release while those Channels remain open.
+It still waits for different contracts, unknown native bindings, or generation files it
+cannot verify. See [legacy contract recovery](UPGRADING.md#recover-missing-runtime-contracts).
+
 Use `acc update` to retry a failed download or finish an interrupted integration refresh.
 A download failure keeps the working version. A partial integration refresh blocks
 workspace commands until recovery completes, while hooks let the client continue without

package/docs/UPGRADING.md

@@ -1,5 +1,31 @@
 # Upgrading to 0.5.0
 
+## Recover missing runtime contracts
+
+ACC 0.5.5 fixes an upgrade defect that can leave 0.5.3 or 0.5.4 waiting for
+`acc-claude-channel` processes with `contract unknown`. The 0.4.x updater can activate
+a newer generation without copying its store contract into the active pointer. Channels
+started afterward copy that incomplete pointer even though their runtime declares a contract.
+
+For an installation already waiting on an older pending release, run:
+
+```bash
+npm install -g agents-can-communicate@latest
+acc update
+acc version
+acc doctor
+```
+
+The global CLI supplies the new management reader before runtime activation. This step is
+needed because the older updater retries its pending release before checking npm for another
+version. If a version pin selects an older release, clear it or select 0.5.5 first.
+
+The reader verifies the referenced generation's package identity, complete contents and
+file modes before recovering a missing contract. Compatible Channels can keep running on
+their original generation during activation. Explicit differing contracts and unknown
+native bindings still block. A generation without a contract, missing files, or changed
+contents remains unknown. ACC does not terminate these processes or edit their lease records.
+
 ## From 0.4.4, 0.4.3, 0.4.2, 0.4.1 or 0.4.0
 
 This release keeps the existing workspace data format. It changes when an update is
@@ -56,17 +82,17 @@ only two kinds keep an update pending:
 - A hold whose declared store contract differs from the incoming version's. This is the
   case the gate exists for, and a release that changes the store contract still needs
   every live process to exit.
-- A hold that declares no contract, which includes every record written by a release
-  before this one. Unknown cannot be compared, so it stays a conservative wait.
+- A hold with no verifiable contract. Older native bindings and generations that predate
+  the declaration remain unknown. A missing field can be recovered when the referenced
+  managed generation declares its contract and passes integrity verification.
 
 A hold declaring the same store contract as the incoming version proceeds. Several open
 Claude Code sessions, a Codex daemon and an idle ACC MCP server no longer have to be
 closed together to move between releases that share a contract.
 
-The first update after installing this release still waits for every process, because the
-holds it has to judge were written before the contract field existed. Close the relevant
-clients and persistent ACC processes once, or accept the eligible Codex service
-maintenance offer described below. Updates after that do not need it.
+Processes still running a generation from before the contract field existed must exit once.
+Close the relevant clients and persistent ACC processes, or accept the eligible Codex service
+maintenance offer described below. Later compatible runtimes do not require that restart.
 
 `acc update` names each remaining hold with its process and its declared contract, so a
 wait now states its reason rather than only the PID. `acc doctor` reports the same

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-grok",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "private": true,
   "type": "module",
   "exports": {

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

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

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

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

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

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+export async function collectFile(source, relative, collected) {
+  const stat = await lstat(source);
+  if (stat.isSymbolicLink()) throw new Error(`symbolic link inside runtime files: ${relative}`);
+  if (stat.isDirectory()) {
+    for (const entry of (await readdir(source)).sort()) {
+      await collectFile(path.join(source, entry), path.posix.join(relative, entry), collected);
+    }
+  } else if (stat.isFile()) {
+    collected.set(relative, { bytes: await readFile(source), mode: stat.mode & 0o777 });
+  } else throw new Error(`unsupported runtime file: ${relative}`);
+}
+
+/** This format also names existing generations; keep it stable across upgrades. */
+export function fingerprint(files) {
+  const hash = createHash("sha256");
+  for (const [name, file] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(JSON.stringify([name, file.mode, file.bytes.length]));
+    hash.update(file.bytes);
+  }
+  return hash.digest("hex");
+}

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

@@ -1,8 +1,8 @@
-import { createHash } from "node:crypto";
 import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm }
   from "node:fs/promises";
 import path from "node:path";
 
+import { collectFile, fingerprint } from "./generation-files.mjs";
 import { attachStagingTemp, holdStagedGeneration, releaseStagingHold } from "./staging.mjs";
 
 const NAME = "agents-can-communicate";
@@ -37,18 +37,6 @@ function declaredPath(value) {
   return value.replace(/\/+$/, "");
 }
 
-async function collectFile(source, relative, collected) {
-  const stat = await lstat(source);
-  if (stat.isSymbolicLink()) throw new Error(`symbolic link inside runtime files: ${relative}`);
-  if (stat.isDirectory()) {
-    for (const entry of (await readdir(source)).sort()) {
-      await collectFile(path.join(source, entry), path.posix.join(relative, entry), collected);
-    }
-  } else if (stat.isFile()) {
-    collected.set(relative, { bytes: await readFile(source), mode: stat.mode & 0o777 });
-  } else throw new Error(`unsupported runtime file: ${relative}`);
-}
-
 async function checkDeclaredComponents(source, relative) {
   let current = source;
   for (const component of relative.split("/")) {
@@ -84,15 +72,6 @@ async function collectPackage(source, prefix, collected, expectedName, version)
   return manifest;
 }
 
-function fingerprint(files) {
-  const hash = createHash("sha256");
-  for (const [name, file] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
-    hash.update(JSON.stringify([name, file.mode, file.bytes.length]));
-    hash.update(file.bytes);
-  }
-  return hash.digest("hex");
-}
-
 async function existingMatches(target, files) {
   try {
     const actual = new Map();

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import { ENTRY_KINDS } from "./entry.mjs";
 import { managedDirectory, syncDirectory } from "./state.mjs";
 
-const MODULES = ["entry.mjs", "state.mjs", "mutex.mjs", "leases.mjs", "schedule.mjs", "policy.mjs"];
+const MODULES = ["entry.mjs", "state.mjs", "generation-files.mjs", "mutex.mjs", "leases.mjs", "schedule.mjs", "policy.mjs"];
 async function durableFile(file, bytes, mode = 0o600) {
   const handle = await open(file, "wx", mode);
   try { await handle.writeFile(bytes); await handle.sync(); }

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

@@ -49,11 +49,11 @@ export async function listRuntimeHolds(root, { pidIsAlive = defaultPidIsAlive }
       || typeof lease.token !== "string" || name !== `${lease.token}.json`
       || typeof lease.kind !== "string" || !lease.kind
       || !Number.isFinite(Date.parse(lease.createdAt))) throw new Error("invalid runtime lease");
-    await validateRuntime(root, lease.runtime);
+    const runtime = await validateRuntime(root, lease.runtime);
     if (await confirmedDead(lease.pid, pidIsAlive)) {
       await rm(file, { force: true });
       removed = true;
-    } else holds.push(lease);
+    } else holds.push({ ...lease, runtime });
   }
   if (removed) await syncDirectory(directory);
   return holds;

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
 import path from "node:path";
+import { collectFile, fingerprint } from "./generation-files.mjs";
 
 /** Resolve existing ancestors without creating an uninitialized manager. */
 export async function canonicalManagerRoot(root) {
@@ -74,6 +75,25 @@ export async function writeManagedJson(file, value) {
 const nonempty = value => typeof value === "string" && value.length > 0;
 const nullableString = value => value === null || nonempty(value);
 
+/** Older updaters dropped the contract while publishing a newer generation.
+ * Recover only from that exact, unchanged generation, never from the active
+ * version or a loose manifest. Explicit lease declarations remain historical
+ * facts. Missing or damaged files leave an unknown hold without failing hooks.
+ */
+async function recoverStoreVersion(generations, runtime) {
+  if (path.dirname(runtime.root) !== generations
+    || !/^\d+\.\d+\.\d+-[a-f0-9]{24}$/.test(path.basename(runtime.root))) return null;
+  try {
+    const files = new Map();
+    await collectFile(runtime.root, "", files);
+    if (path.basename(runtime.root) !== `${runtime.version}-${fingerprint(files).slice(0, 24)}`) return null;
+    const manifest = JSON.parse(files.get("package.json")?.bytes.toString("utf8"));
+    return manifest.name === "agents-can-communicate" && manifest.version === runtime.version
+      && Number.isSafeInteger(manifest.accStoreVersion) && manifest.accStoreVersion > 0
+      ? manifest.accStoreVersion : null;
+  } catch { return null; }
+}
+
 export async function validateRuntime(root, runtime) {
   if (!runtime || !nonempty(runtime.version) || typeof runtime.root !== "string"
     || !path.isAbsolute(runtime.root)) throw new Error("invalid control generation");
@@ -95,7 +115,9 @@ export async function validateRuntime(root, runtime) {
   if (await managedDirectory(generations)) {
     if (await realpath(generations) !== generations) throw new Error("invalid control generations directory");
   }
-  return { version: runtime.version, root: resolved, storeVersion: runtime.storeVersion ?? null };
+  const normalized = { version: runtime.version, root: resolved, storeVersion: runtime.storeVersion ?? null };
+  normalized.storeVersion ??= await recoverStoreVersion(generations, normalized);
+  return normalized;
 }
 
 async function validateControl(root, value) {

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "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.5.4",
+  "version": "0.5.5",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "accManagedUpdateProtocol": 2,
   "accStoreVersion": 6,
   "type": "module",