agents-can-communicate 0.4.4 → 0.5.1

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

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { confirmedDead, defaultPidIsAlive } from "./mutex.mjs";
+import { canonicalManagerRoot, managedDirectory, readManagedJson, syncDirectory, writeManagedJson } from "./state.mjs";
+
+const SCHEMA_VERSION = 1;
+
+/** Staging renames a fully-formed generation into place, then runs it as a
+ * spawned process to verify it, before any control pointer, lease, or pin
+ * can reference it - out of the manager lock, since verification can run for
+ * several seconds and holding the lock that long would stall every hook on
+ * the machine. This hold closes that window: the caller writes it for the
+ * generation's final path *before* either the check that may return that
+ * path unchanged, or the rename that makes a freshly staged one visible
+ * there - so the directory can never be observed without it.
+ *
+ * Returns the hold's own file path: an opaque handle for attachStagingTemp
+ * and releaseStagingHold. The caller owns its lifecycle end to end - this
+ * function never releases what it creates. */
+export async function holdStagedGeneration({ root, generationRoot, stagingRoot = null, pid = process.pid }) {
+  const directory = path.join(root, "staging");
+  await managedDirectory(directory, { create: true });
+  const file = path.join(directory, `${randomUUID()}.json`);
+  await writeManagedJson(file, { schemaVersion: SCHEMA_VERSION, generationRoot, stagingRoot, pid,
+    createdAt: new Date().toISOString() });
+  return file;
+}
+
+/** Once mkdtemp names the actual in-flight temp, attach it to the same
+ * record a live hold already protects: a dead owner's abandoned temp is
+ * only ever found by way of this link, since reclaim never otherwise looks
+ * at a dot-prefixed generations entry.
+ *
+ * If the hold has already vanished (readManagedJson returns undefined on
+ * ENOENT), do nothing rather than write `{ stagingRoot }` alone: spreading
+ * an `undefined` record silently produces exactly the schemaVersion-less,
+ * generationRoot-less, pid-less fragment reclaimGenerations reads as a
+ * malformed hold - and reapStagingHolds can never reap it either, since it
+ * has no valid pid to confirm dead. Manufacturing that record would be a
+ * self-inflicted, permanent block on reclamation, not a corruption that
+ * needed an external cause. */
+export async function attachStagingTemp(file, stagingRoot) {
+  const record = await readManagedJson(file);
+  if (record === undefined) return;
+  await writeManagedJson(file, { ...record, stagingRoot });
+}
+
+/** The caller must call this on every exit from its own staging attempt -
+ * success, a failed verify, a timeout, or a thrown error - once the
+ * generation is either published (and so independently protected by the
+ * control pointer) or abandoned. Confirmed-dead reaping is the backstop for
+ * a crash that skips this, never the release mechanism itself. */
+export async function releaseStagingHold(file) {
+  if (typeof file === "string" && file) await rm(file, { force: true });
+}
+
+const nonempty = value => typeof value === "string" && value.length > 0;
+
+/** A staging process that exits without releasing its hold (crash, kill, a
+ * SIGKILL mid-verify) leaves both the hold and, if it had gotten that far,
+ * its in-flight temp behind - the only sweeper either one ever gets. Same
+ * confirmed-death rule as reapPins. The temp is only ever removed alongside
+ * its owning record, and only after it is confirmed to sit directly inside
+ * this root's own `generations`, named the way mkdtemp names one: a corrupt
+ * or foreign path in the record must never turn a reap into an arbitrary
+ * delete. */
+export async function reapStagingHolds({ root, pidIsAlive = defaultPidIsAlive } = {}) {
+  root = await canonicalManagerRoot(root);
+  const directory = path.join(root, "staging");
+  if (!await managedDirectory(directory)) return;
+  const generations = path.join(root, "generations");
+  let removed = false;
+  for (const name of await readdir(directory)) {
+    if (!name.endsWith(".json")) continue;
+    const file = path.join(directory, name);
+    const record = await readManagedJson(file).catch(() => null);
+    const pid = Number.isSafeInteger(record?.pid) ? record.pid : null;
+    if (pid !== null && await confirmedDead(pid, pidIsAlive)) {
+      if (nonempty(record.stagingRoot)) {
+        // Resolved the same way every generations entry is (see
+        // resolveCandidate in activation.mjs): a symlinked data home must
+        // never make a real temp look foreign, or a foreign path look real.
+        const resolved = await canonicalManagerRoot(record.stagingRoot).catch(() => null);
+        if (resolved && path.dirname(resolved) === generations && path.basename(resolved).startsWith(".staging-")) {
+          await rm(resolved, { recursive: true, force: true });
+        }
+      }
+      await rm(file, { force: true });
+      removed = true;
+    }
+  }
+  if (removed) await syncDirectory(directory);
+}

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

@@ -77,6 +77,13 @@ const nullableString = value => value === null || nonempty(value);
 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");
+  // Absent means a pointer written before the contract field existed. Present
+  // but malformed is a corrupt record, and reading it as unknown would let an
+  // incompatible generation past the gate.
+  if (runtime.storeVersion !== undefined && runtime.storeVersion !== null
+    && (!Number.isSafeInteger(runtime.storeVersion) || runtime.storeVersion <= 0)) {
+    throw new Error("invalid control generation");
+  }
   const generations = path.join(root, "generations");
   const resolved = await canonicalManagerRoot(runtime.root);
   const relative = path.relative(generations, resolved);
@@ -88,7 +95,7 @@ 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 };
+  return { version: runtime.version, root: resolved, storeVersion: runtime.storeVersion ?? null };
 }
 
 async function validateControl(root, value) {

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

@@ -2,6 +2,7 @@ import { activatePending } from "./activation.mjs";
 import { downloadRelease, fetchRelease, newerVersion } from "./download.mjs";
 import { withManagerLock } from "./mutex.mjs";
 import { readControl, writeControl } from "./state.mjs";
+import { releaseStagingHold } from "./staging.mjs";
 import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
 import { requestMaintenance } from "./maintenance.mjs";
 
@@ -40,14 +41,23 @@ export async function performUpdate(root, { force = false, check = false, env =
   const checked = { ...data, checked: true, latest: release.version, newer };
   if (check || !newer) return checked;
   const generation = await download(root, release, { env });
-  const published = await withManagerLock(root, async () => {
-    const current = await readControl(root);
-    if (current.phase !== "ready" || current.active.root !== initial.active.root
-      || current.pin !== initial.pin || !force && !current.auto) return false;
-    await writeControl(root, { ...current, pending: generation,
-      notice: `ACC ${generation.version} is downloaded and verified.` });
-    return true;
-  });
+  // generation.hold has protected this candidate since it was staged;
+  // release it once this publish attempt resolves either way - published,
+  // its own control pointer takes over protecting it, and abandoned
+  // (state_changed) it is no longer wanted at all.
+  let published;
+  try {
+    published = await withManagerLock(root, async () => {
+      const current = await readControl(root);
+      if (current.phase !== "ready" || current.active.root !== initial.active.root
+        || current.pin !== initial.pin || !force && !current.auto) return false;
+      await writeControl(root, { ...current, pending: generation,
+        notice: `ACC ${generation.version} is downloaded and verified.` });
+      return true;
+    });
+  } finally {
+    await releaseStagingHold(generation.hold);
+  }
   if (!published) return { ...checked, reason: "state_changed" };
   return { ...checked, pending: generation.version, ...await activate(root, { env, ignorePid }) };
 }

package/node_modules/@agents-can-communicate/cli/src/native-session-diagnostics.mjs

@@ -1,10 +1,45 @@
 import { listSessionBindings, loadNativeAttempt } from "@agents-can-communicate/adapter-sdk";
 import { describeNativeReason } from "@agents-can-communicate/installer";
 
+// One re-verification per bound session, well inside a doctor run's budget.
+const VERIFY_TIMEOUT_MS = 750;
+
+// A lease is not deliverability.
+//
+// Doctor used to answer "local transport active" from the binding record
+// alone: present, policy on, lease not yet expired. All three can hold while
+// every single send falls back to durable, because none of them says the
+// receiver that binding names can still be reached. Measured exactly that way
+// - `Codex CLI live delivery: available; enabled (actionable); local transport
+// active` on a machine where live delivery had never once worked.
+//
+// So ask the adapter the question the router asks: its own bounded
+// re-verification of this exact binding, which resolves the opaque reference
+// to the receiver record, checks the socket, and re-reads the version,
+// protocol, thread and workspace from the process that would actually serve
+// the push. Read-only - it writes no record and renews no lease - and it
+// answers in the closed reason-code vocabulary doctor already speaks. An
+// adapter with no such method gets no verdict and keeps the lease answer.
+async function verifyDelivery(adapter, { binding, runtimeDir }) {
+  if (typeof adapter?.refreshNativeSession !== "function") return null;
+  try {
+    const handshake = await adapter.refreshNativeSession({ binding, runtimeDir,
+      timeoutMs: VERIFY_TIMEOUT_MS });
+    return handshake?.supported === true
+      ? { deliverable: true, reasonCode: null, clientVersion: handshake.clientVersion ?? null }
+      : { deliverable: false, reasonCode: handshake?.reasonCode ?? "handshake_failed",
+        clientVersion: null };
+  } catch {
+    return { deliverable: false, reasonCode: "handshake_failed", clientVersion: null };
+  }
+}
+
 // Session diagnostics are read only here, never projected into agent context.
 // Verify the owner generation against core before attributing any last attempt.
-export async function updateNativeSessions(adapters, { service, status, root, now }) {
+export async function updateNativeSessions(adapters, { service, status, root, now,
+  registry = [] }) {
   const owners = await listSessionBindings({ runtimeDir: root }).catch(() => []);
+  const byAdapterId = new Map((registry ?? []).map(adapter => [adapter.id, adapter]));
   const transports = new Map();
   for (const entry of adapters) {
     const native = entry.nativeDelivery;
@@ -23,13 +58,28 @@ export async function updateNativeSessions(adapters, { service, status, root, no
       const binding = transports.get(peer.participantId).find(b => b.sessionId === peer.sessionId
         && b.generation === current.generation && b.adapterId === entry.adapterId
         && b.availableModes.includes("livePush"));
-      const runtime = native.policySource === "installation-record" && !native.configured
-        ? "inactive" : !binding ? "unbound"
-          : Date.parse(binding.leaseUntil) > Date.parse(now) ? "active" : "degraded";
+      const off = native.policySource === "installation-record" && !native.configured;
+      const leased = binding !== undefined && Date.parse(binding.leaseUntil) > Date.parse(now);
+      // Only where the old rule would have said "active": everywhere else the
+      // answer is already degraded or unbound, and a live check would buy
+      // nothing but a socket round trip.
+      const delivery = off || !leased ? null
+        : await verifyDelivery(byAdapterId.get(entry.adapterId), { binding, runtimeDir: root });
+      const runtime = off ? "inactive"
+        : binding === undefined ? "unbound"
+          : leased && (delivery === null || delivery.deliverable) ? "active" : "degraded";
       native.sessions.push({ sessionId: peer.sessionId, participantId: peer.participantId,
-        presence: peer.presence, runtime,
+        presence: peer.presence, runtime, clientVersion: binding?.clientVersion ?? null, delivery,
         lastAttempt: owner === null ? null : await loadNativeAttempt({ runtimeDir: root, ...owner }) });
     }
+    // The adapter's own line is the one a reader sees first, and it was the
+    // one claiming health while nothing could be delivered. If this adapter
+    // has bound sessions in this workspace and not one of them can take a
+    // push, this is not an active transport.
+    if (native.runtime === "active" && native.sessions.length > 0
+      && !native.sessions.some(session => session.runtime === "active")) {
+      native.runtime = "degraded";
+    }
   }
 }
 
@@ -37,8 +87,15 @@ const failures = {
   client_process_unknown: "the client process could not be identified; start a new client session",
   handshake_failed: "the session handshake failed; check the client's integration/channel setup",
   handshake_timeout: "the session handshake timed out; check the local channel and retry on the next turn",
-  handshake_version_mismatch: "the session and CLI versions differ; start a new client session",
+  // Since the contract gate shipped, this reason means the version now serving
+  // is below the captured minimum - not that two reported versions differ.
+  // A daemon serving an older build than its CLI is ordinary and admitted; the
+  // fix for this one is to restart the service onto the build the CLI has.
+  handshake_version_mismatch: "the version now serving is below the captured native delivery "
+    + "minimum; restart the client's local delivery service",
   session_generation_stale: "the session was replaced during the handshake",
+  workspace_identity_unavailable: "the bound client session is no longer in this workspace; "
+    + "start a new client session here",
 };
 
 function describeAttempt(attempt) {
@@ -56,9 +113,28 @@ function describeAttempt(attempt) {
   return `last attempt ${attempt.at}: ${detail}`;
 }
 
+// The two records this joins are the delivery binding core published and the
+// receiver the adapter privately holds. Naming a difference between them is
+// the point: one that still delivers is information about a service that
+// updated under its binding, and one that does not is the whole reason a send
+// falls back, said where a reader can act on it.
+function describeDelivery(session) {
+  const delivery = session.delivery;
+  if (delivery === null || delivery === undefined) return null;
+  if (!delivery.deliverable) {
+    return "no live delivery: "
+      + (failures[delivery.reasonCode] ?? describeNativeReason(delivery.reasonCode));
+  }
+  return delivery.clientVersion !== null && delivery.clientVersion !== session.clientVersion
+    ? `receiver verified, now serving ${delivery.clientVersion} `
+      + `where this binding recorded ${session.clientVersion}`
+    : "receiver verified";
+}
+
 export function nativeSessionLines(adapters) {
   return adapters.flatMap(entry => (entry.nativeDelivery.sessions ?? []).map(session =>
     `  ${entry.displayName} session ${session.participantId} (${session.sessionId}): `
     + `${session.runtime === "active" ? "local transport active" : session.runtime}; `
-    + describeAttempt(session.lastAttempt)));
+    + [describeDelivery(session), describeAttempt(session.lastAttempt)]
+      .filter(part => part !== null).join("; ")));
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "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.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/delivery-router/src/router.mjs

@@ -1,3 +1,5 @@
+import { evaluateVersionContract } from "@agents-can-communicate/adapter-sdk";
+
 import { refreshExpiredBinding } from "./refresh-binding.mjs";
 
 const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
@@ -19,6 +21,30 @@ const LIVE_POLICIES = new Set(["off", "actionable", "all"]);
 const permits = (policy, kind) => policy === "all"
   || (policy === "actionable" && ACTIONABLE.has(kind));
 
+// A native-delivery contract is captured per platform, and the only platform a
+// router can judge an offer against is the one it is running on - which is why
+// both entrypoints pass exactly this value. Leaving the parameter optional made
+// its absence silently disable every live offer: `undefined` reached the
+// contract check as "platform_not_captured" and the offer was refused as an
+// unsupported client version. Default it here instead, so a router that is
+// handed nothing behaves as the host it runs on. Injection stays available for
+// callers that need to judge against another platform.
+const HOST_PLATFORM = `${process.platform}-${process.arch}`;
+
+// evaluateVersionContract answers two different questions with one field.
+// "below_minimum_version", "known_bad_version", "version_unavailable" and
+// "prerelease_not_captured" are a capture reading the reported version and
+// refusing it. "platform_not_captured" is the opposite: a complete, valid
+// declaration that records nothing for the platform this router runs on. That
+// is not a malformed adapter, it is the ordinary shape of every shipped
+// adapter away from darwin-arm64 - the only platform any of them has captured
+// - so reading it as a refusal disables live delivery on Linux entirely.
+//
+// "native_delivery_unsupported" is absent deliberately: liveCapable already
+// required a nativeDelivery declaration before an offer was attempted, so the
+// contract check is never handed an adapter without one.
+const UNCAPTURED_PLATFORM = "platform_not_captured";
+
 // Compatibility was decided twice already - at bootstrap by the probe and at
 // SessionStart by the generation-bound handshake that published this binding.
 // The router validates binding identity and the adapter's answer; it does not
@@ -42,7 +68,8 @@ function safeTransport(value, opaqueEndpointRef) {
   return opaqueEndpointRef === "live-adapter" ? "native-live" : "live-adapter";
 }
 
-export function createDeliveryRouter({ service, adapters, clock, platform, readLivePolicy }) {
+export function createDeliveryRouter({ service, adapters, clock, platform = HOST_PLATFORM,
+  readLivePolicy }) {
   const registry = adaptersById(adapters);
 
   async function policyFor(adapter, binding) {
@@ -167,7 +194,22 @@ export function createDeliveryRouter({ service, adapters, clock, platform, readL
       await recordFailure(binding, message, participantId, transport, code);
       return durable(participantId, code);
     }
-    if (response.clientVersion !== binding.clientVersion) {
+    // Compatibility was already decided at bind time; a serving version that
+    // still satisfies the adapter's captured contract keeps offering, even
+    // when it differs from the value recorded when the binding was created.
+    // Only a version below the captured minimum or on the denylist refuses.
+    // When the contract captured nothing for this platform there is no
+    // minimum to judge against, so the offer keeps the rule this path had
+    // before the contract gate existed: the version that answered must be the
+    // one the binding recorded. defineAdapter rejecting a partial declaration
+    // does not make this unreachable - a complete, valid contract that names
+    // only darwin-arm64 says nothing about linux-x64, and that is every
+    // shipped adapter on Linux.
+    const versionRule = evaluateVersionContract(adapter, { clientVersion: response.clientVersion, platform });
+    const admitted = versionRule.reasonCode === null
+      || (versionRule.reasonCode === UNCAPTURED_PLATFORM
+        && response.clientVersion === binding.clientVersion);
+    if (!admitted) {
       await recordFailure(binding, message, participantId, transport,
         "unsupported_client_version");
       return durable(participantId, "unsupported_client_version");

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

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

package/node_modules/@agents-can-communicate/hook-runner/src/native-binding.mjs

@@ -75,8 +75,17 @@ export async function establishNativeBinding({ adapter, event, hookBinding, clie
     if (!(lease > now)) return outcome("degraded", "handshake_failed");
     const ceiling = now + 2 * heartbeatCadenceMs;
     const leaseUntil = lease > ceiling ? new Date(ceiling).toISOString() : verdict.leaseUntil;
+    // The binding's clientVersion is the version this binding's live pushes
+    // will be served by, as the handshake reported it and the contract
+    // admitted it - not the version `--version` printed. The two differ
+    // whenever a client's background service has updated under its CLI, and
+    // that is the case native delivery exists to survive. Publishing the
+    // detected CLI version instead made the binding disagree with the
+    // adapter's own endpoint record, which since 0.5.0 carries the serving
+    // version, and every send fell back to durable. The detected CLI version
+    // is not lost: the session-owner record beside this one still carries it.
     await service.publishDeliveryBinding({
-      sessionId, generation, adapterId: adapter.id, clientVersion,
+      sessionId, generation, adapterId: adapter.id, clientVersion: verdict.clientVersion,
       availableModes: [...verdict.modes], livePolicy: policy,
       opaqueEndpointRef: verdict.opaqueEndpointRef, leaseUntil,
     });

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -1,14 +1,15 @@
 import { retireNativeBinding } from "./native-retirement.mjs";
 import { createHash, randomBytes } from "node:crypto";
-import { realpath } from "node:fs/promises";
+import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { clearNativeAttempt, clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
 import { AccError, createId } from "@agents-can-communicate/protocol";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
-import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+import { clearPin, createGitProbe, discoverWorkspace, platformDataHome, runtimePaths, writePin }
   from "@agents-can-communicate/cli";
 
 import { resolveClientPid } from "./client-pid.mjs";
@@ -178,6 +179,38 @@ export function participantFor(adapterId, harnessSessionId, env = {}) {
   return `${adapterId}-${suffix}`;
 }
 
+// The runtime generation this module ships as part of, found by walking up
+// from its own file for the nearest ancestor manifest that declares a store
+// contract. A workspace package's own manifest (this one's included) carries a
+// `version` but never `accStoreVersion` - only the generation's root manifest
+// does - so this cannot stop at the first `package.json` the way a version
+// lookup could. Answers null facts rather than throwing: a binding published
+// without a readable contract is exactly today's unknown-hold behaviour.
+//
+// `version` rides along from the same manifest read, for a pin (below) to name
+// the generation it names by, distinct from `storeVersion`'s contract number.
+async function runtimeFacts(fromUrl) {
+  let directory = path.dirname(fileURLToPath(fromUrl));
+  for (;;) {
+    const manifest = await readFile(path.join(directory, "package.json"), "utf8")
+      .then(JSON.parse).catch(() => null);
+    if (Number.isSafeInteger(manifest?.accStoreVersion)) {
+      return { storeVersion: manifest.accStoreVersion, runtimeRoot: directory,
+        version: typeof manifest.version === "string" ? manifest.version : null };
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return { storeVersion: null, runtimeRoot: null, version: null };
+    directory = parent;
+  }
+}
+
+// Where a pin lives: the managed runtime's own root, sibling of `generations`
+// and `leases`, never this workspace's store. The hook entry point that will
+// read a pin (a later task) has not resolved a workspace yet when it needs to
+// - it only has the data home - so a pin keyed under `paths.root` would be
+// unreachable from there.
+const managerRootFor = dataHome => path.join(dataHome, "acc", "runtime");
+
 async function openContext({ cwd, dataHome, runtime, env, deadline }) {
   assertHookBudget(deadline);
   const descriptor = await discoverWorkspace({ cwd, env: env ?? {},
@@ -307,12 +340,18 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
     readProcessTable, probeClientVersion, platform, deadline }) {
+    // Where this session's pin lives, resolved once and reused at every write
+    // below. Beside `paths.root`, never inside it: see `managerRootFor`.
+    const pinRoot = managerRootFor(context.dataHome);
     // A repeated start refreshes the client's version/platform. Remove the old
     // certified facts before any probe, PID lookup, resume, or open can fail;
     // keep only the generation identity needed for a successful resume.
     if (binding !== null) {
+      const facts = await runtimeFacts(import.meta.url);
       await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
-        accSessionId: binding.accSessionId, generation: binding.generation });
+        accSessionId: binding.accSessionId, generation: binding.generation, ...facts });
+      await writePin({ root: pinRoot, harnessSessionId: event.sessionId, runtimeRoot: facts.runtimeRoot,
+        version: facts.version, storeVersion: facts.storeVersion });
     }
     const clientVersion = await probeClientVersion(adapter,
       { timeoutMs: Math.max(1, Math.min(1_000, deadline - Date.now())) });
@@ -357,8 +396,11 @@ const HANDLERS = {
       if (resumed !== null) {
         const hookBinding = { accSessionId: resumed.sessionId, generation: resumed.generation,
           ...clientFacts, clientPid };
+        const facts = await runtimeFacts(import.meta.url);
         await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
-          ...hookBinding });
+          ...hookBinding, ...facts });
+        await writePin({ root: pinRoot, harnessSessionId: event.sessionId, runtimeRoot: facts.runtimeRoot,
+          version: facts.version, storeVersion: facts.storeVersion, clientPid });
         return { accSessionId: resumed.sessionId, generation: resumed.generation,
           ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
       }
@@ -368,8 +410,11 @@ const HANDLERS = {
     // happened (or it was closed), a retry allocates a NEW pair, never revives it.
     const opening = { sessionId: context.service.ids.next("session"),
       generation: context.service.ids.next("generation") };
+    const openingFacts = await runtimeFacts(import.meta.url);
     await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
-      accSessionId: opening.sessionId, generation: opening.generation });
+      accSessionId: opening.sessionId, generation: opening.generation, ...openingFacts });
+    await writePin({ root: pinRoot, harnessSessionId: event.sessionId, runtimeRoot: openingFacts.runtimeRoot,
+      version: openingFacts.version, storeVersion: openingFacts.storeVersion, clientPid });
     const session = await context.service.openSession({
       ...opening,
       workspaceId: context.descriptor.id,
@@ -387,8 +432,11 @@ const HANDLERS = {
     });
     const hookBinding = { accSessionId: session.sessionId, generation: session.generation,
       ...clientFacts, clientPid };
+    const openedFacts = await runtimeFacts(import.meta.url);
     await storeSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId,
-      ...hookBinding });
+      ...hookBinding, ...openedFacts });
+    await writePin({ root: pinRoot, harnessSessionId: event.sessionId, runtimeRoot: openedFacts.runtimeRoot,
+      version: openedFacts.version, storeVersion: openedFacts.storeVersion, clientPid });
     return { accSessionId: session.sessionId, generation: session.generation,
       ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
   },
@@ -415,6 +463,7 @@ const HANDLERS = {
       await context.service.clearDeliveryBinding(owner);
     }
     await clearSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId });
+    await clearPin({ root: managerRootFor(context.dataHome), harnessSessionId: event.sessionId });
     const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
     if (diagnosticDeadline !== null) {
       await clearNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "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.4.4",
+  "version": "0.5.1",
   "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.4.4",
+  "version": "0.5.1",
   "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.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/src/safe-directory.mjs

@@ -1,11 +1,12 @@
-import { lstat, mkdir, realpath } from "node:fs/promises";
+import { lstat, mkdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 // Ported from the reconciled prototype without semantic change. Every managed
 // path is validated segment by segment against the canonical root, so a
-// symlinked ancestor cannot redirect a read or a publication outside the store.
+// symlinked ancestor cannot redirect a read or a publication - neither outside
+// the store, nor to another directory inside it.
 function invalidDirectory(message, directory, root, cause) {
   return new AccError(EXIT.DATA, message, {
     directory,
@@ -60,17 +61,50 @@ async function inspectManagedDirectory(rootPath, directoryPath, create) {
   let details = await inspectRealDirectory(root, root, create);
   const canonicalRoot = await realpath(root);
   let current = root;
+  // The canonical location of the directory validated so far. Every segment
+  // has to be a child of it, which carries containment in the canonical root
+  // down the whole walk by induction.
+  let canonicalParent = canonicalRoot;
   for (const segment of relative.split(path.sep).filter(Boolean)) {
     current = path.join(current, segment);
     details = await inspectRealDirectory(current, root, create);
-    const expected = path.join(canonicalRoot, path.relative(root, current));
-    if (await realpath(current) !== expected) {
+    // realpath answers with the name the directory carries *now*, which is not
+    // always the name that was asked for: on Darwin it resolves by opening the
+    // path and asking the kernel for that vnode's current path, so a directory
+    // renamed between those two steps comes back under its new name. Renaming
+    // managed directories is ordinary here - the writer lock is granted,
+    // reclaimed and released entirely by rename - so demanding the exact name
+    // back reported an escape for an in-store move, intermittently and only
+    // under load, and took real writes down with it.
+    //
+    // What a move cannot change is where the directory lives. An ancestor
+    // replaced by a symlink after it was checked resolves somewhere else
+    // entirely, so the parent is the thing to hold fixed: this segment must be
+    // a child of the directory the previous one validated. Moving the leaf is
+    // then the only disagreement left, and that one is settled by identity -
+    // a moved directory is the same vnode under another name, while a sibling
+    // swapped in under this name is not. ENOENT on the re-stat means it moved
+    // again between the two calls, which cannot redirect anything: whatever
+    // the caller opens through this path next fails the same way.
+    const resolved = await realpath(current);
+    if (path.dirname(resolved) !== canonicalParent
+      || (path.basename(resolved) !== segment
+        && !await stillTheSameDirectory(details, resolved, current, root))) {
       throw invalidDirectory("managed directory escapes the canonical store root", current, root);
     }
+    canonicalParent = resolved;
   }
   return { directory, stat: details };
 }
 
+async function stillTheSameDirectory(details, resolved, current, root) {
+  const served = await stat(resolved).then(found => found, error => {
+    if (error.code === "ENOENT") return null;
+    throw invalidDirectory("cannot inspect managed directory", current, root, error.message);
+  });
+  return served === null || (served.dev === details.dev && served.ino === details.ino);
+}
+
 export async function assertManagedDirectory(rootPath, directoryPath) {
   return inspectManagedDirectory(rootPath, directoryPath, false);
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "accManagedUpdateProtocol": 2,
+  "accStoreVersion": 6,
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [