agents-can-communicate 0.3.0 → 0.4.0

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

@@ -0,0 +1,122 @@
+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";
+
+/** Resolve existing ancestors without creating an uninitialized manager. */
+export async function canonicalManagerRoot(root) {
+  if (typeof root !== "string" || !path.isAbsolute(root)) throw new Error("manager root must be absolute");
+  let current = path.resolve(root);
+  const tail = [];
+  for (;;) {
+    try { return path.join(await realpath(current), ...tail); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+export async function managedDirectory(directory, { create = false } = {}) {
+  if (create) await mkdir(directory, { recursive: true, mode: 0o700 });
+  try {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("managed directory is not a regular directory");
+    if (create) {
+      const handle = await open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try { await handle.chmod(0o700); } finally { await handle.close(); }
+    }
+    return true;
+  } catch (error) {
+    if (!create && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function syncDirectory(directory) {
+  const handle = await open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+/** Internal callers validate every managed parent before opening a record. */
+export async function readManagedJson(file) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!(await handle.stat()).isFile()) throw new Error("managed record must be a regular file");
+    return JSON.parse(await handle.readFile("utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+export async function writeManagedJson(file, value) {
+  const temporary = path.join(path.dirname(file), `.record-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    await handle.writeFile(`${JSON.stringify(value)}\n`);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporary, file);
+    await syncDirectory(path.dirname(file));
+  } finally {
+    await handle?.close();
+    await rm(temporary, { force: true });
+  }
+}
+
+const nonempty = value => typeof value === "string" && value.length > 0;
+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");
+  const generations = path.join(root, "generations");
+  const resolved = await canonicalManagerRoot(runtime.root);
+  const relative = path.relative(generations, resolved);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("control runtime must be inside manager generations");
+  }
+  // An internal symlink can redirect all generations outside the manager even
+  // when a lexical pointer appears contained.
+  if (await managedDirectory(generations)) {
+    if (await realpath(generations) !== generations) throw new Error("invalid control generations directory");
+  }
+  return { version: runtime.version, root: resolved };
+}
+
+async function validateControl(root, value) {
+  if (!value || value.schemaVersion !== 1 || !["ready", "activating"].includes(value.phase)
+    || typeof value.auto !== "boolean" || !nullableString(value.pin)
+    || !nullableString(value.checkedAt) || !nullableString(value.notice)
+    || !nonempty(value.home) || !path.isAbsolute(value.home)
+    || !Array.isArray(value.targets) || !value.targets.every(nonempty)
+    || !(value.pending === null || typeof value.pending === "object")) {
+    throw new Error("invalid managed runtime control");
+  }
+  const active = await validateRuntime(root, value.active);
+  const pending = value.pending === null ? null : await validateRuntime(root, value.pending);
+  return { ...value, active, pending };
+}
+
+export async function readControl(root) {
+  root = await canonicalManagerRoot(root);
+  if (!await managedDirectory(root)) return null;
+  const value = await readManagedJson(path.join(root, "control.json"));
+  return value === undefined ? null : validateControl(root, value);
+}
+
+/** Caller holds withManagerLock for any read-modify-write transaction. */
+export async function writeControl(root, value) {
+  root = await canonicalManagerRoot(root);
+  const validated = await validateControl(root, value);
+  await managedDirectory(root, { create: true });
+  await writeManagedJson(path.join(root, "control.json"), validated);
+  return validated;
+}

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

@@ -0,0 +1,65 @@
+import { activatePending } from "./activation.mjs";
+import { downloadRelease, fetchRelease, newerVersion } from "./download.mjs";
+import { withManagerLock } from "./mutex.mjs";
+import { readControl, writeControl } from "./state.mjs";
+
+import { checkDue, networkDisabled } from "./policy.mjs";
+export { CHECK_INTERVAL_MS, networkDisabled } from "./policy.mjs";
+
+/** One pass. The worker lock owns scheduling; admission is held only for state changes. */
+export async function performUpdate(root, { force = false, check = false, env = process.env,
+  discover = fetchRelease, download = downloadRelease, activate = activatePending,
+  ignorePid = null } = {}) {
+  const initial = await readControl(root);
+  if (initial === null) throw new Error("ACC is not enrolled; run acc install first");
+  const data = { running: initial.active.version, auto: initial.auto, pin: initial.pin,
+    pending: initial.pending?.version ?? null, notice: initial.notice };
+  if (!force && !check && !initial.auto) return { ...data, checked: false, reason: "auto_off" };
+  // Recovery is local; the hard no-network override must not strand a partial refresh.
+  if (initial.pending && !check && (force || !networkDisabled(env))) {
+    return { ...data, ...await activate(root, { env, ignorePid }), checked: false };
+  }
+  if (networkDisabled(env)) return { ...data, checked: false, reason: "network_disabled" };
+  if (!force && !check && !checkDue(initial)) return { ...data, checked: false, reason: "not_due" };
+  if (!check) await withManagerLock(root, async () => {
+    const current = await readControl(root);
+    await writeControl(root, { ...current, checkedAt: new Date().toISOString() });
+  });
+  const release = await discover({ pin: initial.pin, env });
+  const newer = newerVersion(release.version, initial.active.version);
+  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;
+  });
+  if (!published) return { ...checked, reason: "state_changed" };
+  return { ...checked, pending: generation.version, ...await activate(root, { env, ignorePid }) };
+}
+
+/** A single detached worker may wait cheaply for native clients to exit. */
+export async function runWorker(root, { force = false, env = process.env, wait = false, ignorePid = null } = {}) {
+  return withManagerLock(`${root}/worker`, async () => {
+    for (;;) {
+      const result = await performUpdate(root, { force, env, ignorePid });
+      if (!wait || result.reason !== "processes_active") return result;
+      await new Promise(resolve => setTimeout(resolve, 60_000));
+      if (!(await readControl(root))?.auto || networkDisabled(env)) return result;
+    }
+  }, { timeoutMs: 100 });
+}
+
+export async function recordWorkerFailure(root, error) {
+  // A second scheduled worker losing the lock is ordinary, not a failed update.
+  if (/manager lock held/.test(error?.message ?? "")) return;
+  await withManagerLock(root, async () => {
+    const control = await readControl(root);
+    if (control) await writeControl(root, { ...control,
+      notice: "Automatic update could not finish; the previous runtime was kept. Run acc update for details." });
+  }).catch(() => {});
+}

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

@@ -1,126 +1,51 @@
-import { listSessionBindings } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-/**
- * Work out which session is running this command.
- *
- * Every mutating command needs a session id and the generation that proves the
- * caller is that session. Until this existed, both had to be passed on the
- * command line, and the shipped skills told agents to pass
- * `--session "$ACC_SESSION" --generation "$ACC_GENERATION"` - two variables that
- * nothing in the system has ever set. The generation is not printed by `acc
- * status` either, deliberately: it is the proof of ownership, not public
- * information. So the documented workflow could not be carried out by any agent
- * on any client, and the only way through was to read ACC's own files by hand,
- * which the same skill forbids in as many words.
- *
- * The hook runtime already knows both. It writes them into a binding at
- * SessionStart, keyed by the harness's own session id. What was missing was a
- * way for a shell inside that session to find its own binding. Each step below
- * answers that from something the caller demonstrably has.
- */
+// Inbox retrieves bodies and advances receipts, so it needs the same owner
+// proof as a mutation. Public observations never need somebody else's token.
 const NEEDS_OWNER = Object.freeze(new Set(["work", "claim", "release", "message",
-  "inbox", "reply", "request", "ack", "workstream", "task", "finish", "decide"]));
-
-/**
- * Reads that are answers about *you*.
- *
- * Attention is computed per session: what is addressed to you, what has become
- * unblocked for you. Run by hand with nothing identifying the caller, both of
- * these answered for nobody and returned an empty list - so an agent told at the
- * top of its turn that work was waiting could ask `acc status` and be told there
- * was none. They resolve softly: a shell with no session attached still gets the
- * roster and the events, which is what it came for.
- */
+  "inbox", "reply", "request", "ack", "finish"]));
 const WANTS_OWNER = Object.freeze(new Set(["sync", "status"]));
 
 export const needsOwner = command => NEEDS_OWNER.has(command);
 
+const unresolved = command => new AccError(EXIT.USAGE,
+  `${command} could not tell which session is running it. Pass both --session and `
+  + "--generation from this turn's ACC hook header or your own acc attach, or use this "
+  + "session's ACC MCP tools. Do not copy a peer's session from acc status. Native "
+  + "session IDs and a shared checkout do not establish CLI ownership.",
+  { command, reasonCode: "caller_identity_unresolved" });
+
 /**
- * Bindings whose session is still open, carrying the session's own checkout.
+ * Accept caller-supplied credentials; never discover credentials from peers.
  *
- * A binding outlives a crash, so one that names a closed or vanished session is
- * a leftover. Acting as a closed session would fail deeper in the service with a
- * conflict; dropping it here means the *next* candidate can be recognised
- * instead.
+ * A sole binding, a matching checkout, and a public session selector all let an
+ * unbound client adopt another session. Native environment values do too:
+ * nested clients inherit their parent's IDs. Bindings identify hook payloads,
+ * not arbitrary shell callers. ACC_SESSION/ACC_GENERATION remain an explicit
+ * operator-supplied pair, not an assertion that environment provenance is known.
  */
-async function liveCandidates({ context }) {
-  const bindings = await listSessionBindings({ runtimeDir: context.paths.root });
-  if (bindings.length === 0) return [];
-  const status = await context.service.collectStatus({});
-  const live = new Map(status.participants
-    .filter(participant => participant.presence !== "offline")
-    .map(participant => [participant.sessionId, participant]));
-  return bindings
-    .filter(binding => live.has(binding.accSessionId))
-    .map(binding => ({ ...binding, session: live.get(binding.accSessionId) }));
-}
-
-const describe = candidates => candidates
-  .map(candidate => `${candidate.session.participantId} (${candidate.session.harness})`)
-  .join(", ");
-
 export async function resolveOwner({ command, options, context, env = {} }) {
   const soft = WANTS_OWNER.has(command);
   if (!soft && !needsOwner(command)) return options;
-  if (options.session !== undefined && options.generation !== undefined) return options;
-  if (soft && options.participant !== undefined) return options;
-
-  const candidates = await liveCandidates({ context });
-  const take = candidate => ({ ...options, session: candidate.accSessionId,
-    generation: candidate.generation,
-    // `status` filters by participant rather than by session, so it is told who
-    // the caller is in the terms it works in.
-    participant: options.participant ?? candidate.session.participantId });
-
-  // Named a session but not the generation: the id is in `acc status --json`,
-  // so this is what an agent reaches for first, and refusing it would teach the
-  // wrong lesson about which half is secret.
-  if (options.session !== undefined) {
-    // The reads never needed a generation, and a session opened by `acc attach`
-    // has no binding to find one in. Answering for the session it was given is
-    // both what it was asked and what it did before this resolver existed.
+  const explicit = options.session !== undefined && options.generation !== undefined;
+  const configured = typeof env.ACC_SESSION === "string" && typeof env.ACC_GENERATION === "string";
+  if (!explicit && !configured) {
     if (soft) return options;
-    const named = candidates.find(candidate => candidate.accSessionId === options.session);
-    if (named !== undefined) return take(named);
-    throw new AccError(EXIT.USAGE,
-      `no live session ${options.session} in this workspace`,
-      { command, session: options.session });
+    throw unresolved(command);
   }
 
-  // The documented pair, honoured for anyone who has wired it up themselves.
-  if (typeof env.ACC_SESSION === "string" && typeof env.ACC_GENERATION === "string") {
-    return { ...options, session: env.ACC_SESSION, generation: env.ACC_GENERATION };
+  const owner = explicit ? options : { session: env.ACC_SESSION, generation: env.ACC_GENERATION };
+  if (options.session !== undefined && options.session !== owner.session) {
+    // A public observation scope is allowed; it does not request credentials.
+    if (soft) return options;
+    throw unresolved(command);
   }
-
-  // The client's own session id, under whatever name it exports it. Claude Code
-  // sets CLAUDE_CODE_SESSION_ID, measured equal to the `session_id` its hooks
-  // receive; matching on the value rather than the variable name means a client
-  // that names it something else works without ACC knowing the name.
-  const exported = new Set(Object.values(env).filter(value => typeof value === "string"));
-  const byEnvironment = candidates
-    .filter(candidate => exported.has(candidate.harnessSessionId));
-  if (byEnvironment.length === 1) return take(byEnvironment[0]);
-
-  // Two agents in one workspace are the normal case, and each is usually in its
-  // own checkout - that is what the worktree story is. Same repository, so the
-  // same workspace, and the checkout tells them apart.
-  const here = context.descriptor.git?.worktreeRoot;
-  const byCheckout = here === undefined
-    ? []
-    : candidates.filter(candidate => candidate.session.checkoutRoot === here);
-  if (byCheckout.length === 1) return take(byCheckout[0]);
-
-  if (candidates.length === 1) return take(candidates[0]);
-
-  // Guessing between two live sessions would let one agent act as another, which
-  // is exactly what the generation exists to prevent. So this refuses, and says
-  // what it found.
-  if (soft) return options;
-  throw new AccError(EXIT.USAGE, candidates.length === 0
-    ? `${command} could not tell which session is running it: no live session is `
-      + "attached here. An adapter attaches one at SessionStart; `acc status` shows who is."
-    : `${command} could not tell which of ${candidates.length} live sessions is running `
-      + `it (${describe(candidates)}). Pass --session, which \`acc status --json\` lists.`,
-  { command, candidates: candidates.map(candidate => candidate.accSessionId) });
+  // A supplied generation must reach the core unchanged so stale calls fail.
+  const resolved = { ...options, session: owner.session,
+    generation: options.generation ?? owner.generation };
+  if (command === "status" && options.participant === undefined) {
+    const { participants } = await context.service.collectStatus({});
+    resolved.participant = participants.find(item => item.sessionId === owner.session)?.participantId;
+  }
+  return resolved;
 }

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

@@ -7,6 +7,8 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 import { platformPaths } from "./platform-paths.mjs";
 import { checkingIsOff, fetchLatest, isNewer, writeCachedCheck } from "./update-check.mjs";
 
+import { runManagedUpdate, validateUpdateOptions } from "./managed-runtime/command.mjs";
+
 const execFileAsync = promisify(execFile);
 
 /**
@@ -26,6 +28,14 @@ export const upgradeSteps = version => [
 const spell = ([command, argv]) => `  ${command} ${argv.join(" ")}`;
 
 export async function runUpdateCommand({ options, runtime }) {
+  if (options.check === true && options.apply === true) {
+    throw new AccError(EXIT.USAGE, "use either --check or --apply");
+  }
+  validateUpdateOptions(options);
+  if (runtime.managerRoot) return runManagedUpdate({ options, runtime });
+  if (options.auto !== undefined || options.pin !== undefined) {
+    throw new AccError(EXIT.USAGE, "run acc install before configuring automatic updates");
+  }
   const env = runtime.env ?? {};
   const { data: dataHome } = platformPaths({ platform: runtime.platform, env });
   const running = typeof runtime.version === "function"
@@ -61,26 +71,34 @@ export async function runUpdateCommand({ options, runtime }) {
   const data = { checked: true, running, latest, newer: true,
     steps: steps.map(([command, argv]) => [command, ...argv].join(" ")) };
 
-  if (options.apply !== true) {
+  if (options.check === true) {
     return { data, text: [`acc ${latest} is available; you have ${running}`, "",
-      ...steps.map(spell), "", "or run: acc update --apply"].join("\n") };
+      ...steps.map(spell), "", "or run: acc update"].join("\n") };
   }
 
   const spawn = runtime.spawn ?? ((command, argv) => execFileAsync(command, argv, { env }));
   const done = [];
+  let installation = { stdout: "", stderr: "" };
   for (const [command, argv] of steps) {
     try {
-      await spawn(command, argv);
+      const output = await spawn(command, argv);
+      if (command === "acc") {
+        installation = { stdout: String(output?.stdout ?? "").trim(),
+          stderr: String(output?.stderr ?? "").trim() };
+      }
       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.
+      const text = [`${command} failed: ${error.message}`, "", "finish it with:",
+        ...steps.slice(done.length).map(spell)].join("\n");
       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 };
+        text, error: new AccError(EXIT.DATA, text) };
     }
   }
-  return { data: { ...data, applied: done }, text: `updated to ${latest}` };
+  const activation = "Restart all running agent clients to load the updated ACC runtime and skills.";
+  return { data: { ...data, applied: done, installation, activation },
+    text: [`updated to ${latest}`, installation.stdout, installation.stderr, activation]
+      .filter(Boolean).join("\n\n") };
 }

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

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

package/node_modules/@agents-can-communicate/core/src/attention.mjs

@@ -2,6 +2,7 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { overlaps } from "./claims.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
 export const ATTENTION_PRIORITY = Object.freeze({
   reply_required: 1,
@@ -95,6 +96,8 @@ export function computeAttention(snapshot, { session, participantId, now, pidIsA
   if (typeof pidIsAlive !== "function") {
     throw new AccError(EXIT.USAGE, "computeAttention requires a pidIsAlive probe", {});
   }
+  snapshot = { ...snapshot, messages: (snapshot.messages ?? [])
+    .map(decisionView(snapshot.messages ?? [])).filter(isCurrentDecision) };
   return [
     ...obligationItems(snapshot, participantId),
     ...unavailableRecipients(snapshot, participantId, now, pidIsAlive),

package/node_modules/@agents-can-communicate/core/src/claims.mjs

@@ -33,17 +33,19 @@ const isLive = (claim, now) => Date.parse(claim.expiresAt) > Date.parse(now);
 export function createClaimService(ports, sessions) {
   const { store, clock, ids, pidIsAlive } = ports;
 
-  async function requireOwner(input, action) {
-    const existing = await sessions.locateSession(input.sessionId, input.workspaceId);
-    if (existing === null || existing.record.state !== "open") {
+  async function requireOwner(input, action, tx) {
+    const current = tx === undefined
+      ? (await sessions.locateSession(input.sessionId, input.workspaceId))?.record
+      : tx.get("session", input.sessionId);
+    if (current == null || current.state !== "open") {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} from a session that is not open`,
         { sessionId: input.sessionId });
     }
-    if (existing.record.generation !== input.generation) {
+    if (current.generation !== input.generation) {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} with a replaced session generation`,
         { sessionId: input.sessionId });
     }
-    return existing.record;
+    return current;
   }
 
   function conflictWith(existing, owner, now, snapshotSessions) {
@@ -83,6 +85,7 @@ export function createClaimService(ports, sessions) {
 
     let record = null;
     await store.transaction(async tx => {
+      await requireOwner(input, "claim", tx);
       const live = tx.list("claim", claim => isLive(claim, now));
       // This session's own claim on this resource, live or lapsed. Looking only
       // among the live ones left the expired record behind and made a fresh one
@@ -117,7 +120,7 @@ export function createClaimService(ports, sessions) {
         actorSessionId: session.sessionId, type: mine === undefined ? "claim.acquired"
           : "claim.renewed", occurredAt: now,
         payload: { claimId, resource, mode: record.mode } });
-    }, { kinds: ["claim"] });
+    }, { kinds: ["session", "claim"] });
     return record;
   }
 
@@ -128,6 +131,7 @@ export function createClaimService(ports, sessions) {
       .toISOString();
     let record = null;
     await store.transaction(async tx => {
+      await requireOwner(input, "renew", tx);
       const existing = tx.get("claim", input.claimId);
       if (existing === null || existing.ownerSessionId !== session.sessionId) {
         throw new AccError(EXIT.CONFLICT, "only the owning session generation may renew a claim",
@@ -138,7 +142,7 @@ export function createClaimService(ports, sessions) {
       tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
         workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
         type: "claim.renewed", occurredAt: now, payload: { claimId: input.claimId } });
-    }, { kinds: ["claim"] });
+    }, { kinds: ["session", "claim"] });
     return record;
   }
 
@@ -146,6 +150,7 @@ export function createClaimService(ports, sessions) {
     const session = await requireOwner(input, "release");
     const now = clock.now();
     await store.transaction(async tx => {
+      await requireOwner(input, "release", tx);
       const existing = tx.get("claim", input.claimId);
       if (existing === null) {
         throw new AccError(EXIT.CONFLICT, "the claim does not exist", { claimId: input.claimId });
@@ -167,7 +172,7 @@ export function createClaimService(ports, sessions) {
         type: owned ? "claim.released" : "claim.force_released", occurredAt: now,
         payload: { claimId: input.claimId, authority: authority ?? null,
           reason: reason ?? null, replacedGeneration: existing.generation } });
-    }, { kinds: ["claim"] });
+    }, { kinds: ["session", "claim"] });
   }
 
   return {

package/node_modules/@agents-can-communicate/core/src/conversations.mjs

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-
 import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
   from "@agents-can-communicate/protocol";
 
 import { projectReleasedClaim, reconstructFinishRetry } from "./finish-retries.mjs";
 import { ensureMaterialised } from "./materialisation.mjs";
+import { nextTurnDelivery as selectNextTurnDelivery } from "./next-turn-delivery.mjs";
+import { prepareDecisionChange } from "./decision-changes.mjs";
 
 export const receiptId = (messageId, participantId) => `receipt_${createHash("sha256")
   .update(JSON.stringify([messageId, participantId])).digest("base64url")}`;
@@ -19,6 +20,7 @@ const logicalContent = message => ({
   inReplyTo: message.inReplyTo,
   artifacts: message.artifacts,
   handoff: message.handoff,
+  decisionChange: message.decisionChange ?? null,
 });
 
 const normalizedContent = input => logicalContent({
@@ -30,6 +32,7 @@ const normalizedContent = input => logicalContent({
   inReplyTo: input.inReplyTo ?? null,
   artifacts: input.artifacts ?? [],
   handoff: input.handoff ?? null,
+  decisionChange: input.decisionChange,
 });
 
 function existingMessage(tx, session, input) {
@@ -55,6 +58,41 @@ function assertCurrentSession(tx, session, action) {
   }
 }
 
+/**
+ * Turn what the sender typed into participant ids that exist.
+ *
+ * An exact participant id is always taken as written. A name that matches no
+ * participant is tried as a client name - `codex`, `claude_code` - because that
+ * is what an agent knows about its peers: the roster it is handed names the
+ * client, and asking it to first look up `codex-fbqX8o` is a lookup it
+ * routinely skips. Every shipped example taught this form while nothing
+ * implemented it, so an agent following its own skill was refused on its first
+ * attempt to reach anyone.
+ *
+ * One live session of that client resolves. Two refuse and name them, the way
+ * `--session` already refuses to choose between two sessions of one client:
+ * guessing is how a question is answered by a session that never had the
+ * context. The sender's own client is excluded, or the one client an agent is
+ * certain is running becomes the easiest thing to address by accident.
+ */
+function resolveAddressees(tx, requested, session) {
+  const known = new Set(tx.list("participant").map(item => item.participantId));
+  return requested.map(name => {
+    if (known.has(name)) return name;
+    const peers = [...new Set(tx.list("session", item => item.state === "open"
+      && item.harness === name && item.participantId !== session.participantId)
+      .map(item => item.participantId))].sort();
+    if (peers.length === 1) return peers[0];
+    if (peers.length > 1) {
+      throw new AccError(EXIT.USAGE,
+        `could not tell which of ${peers.length} ${name} sessions you meant: `
+        + `${peers.join(", ")}. Name one of them, which \`acc status --json\` lists.`,
+        { client: name, candidates: peers });
+    }
+    return name;
+  });
+}
+
 function addressedRecipients(tx, message, session) {
   if (message.toParticipantIds.length === 0) {
     return [...new Set(tx.list("session", item => item.state === "open"
@@ -86,9 +124,14 @@ function threadFor(tx, messageId, inReplyTo) {
   return parent.threadId;
 }
 
-export function recordMessageInTransaction({ tx, session, input, now, messageId, ids,
+export function recordMessageInTransaction({ tx, session, input: raw, now, messageId, ids,
   action = "send a message" }) {
   assertCurrentSession(tx, session, action);
+  // Resolved before anything else reads the recipients, so the stored message
+  // names real participants and a retry compares against the same content. A
+  // record that kept the client name would address nobody when it is read back.
+  const input = prepareDecisionChange(tx, { ...raw,
+    toParticipantIds: resolveAddressees(tx, raw.toParticipantIds ?? [], session) }, session);
   const existing = existingMessage(tx, session, input);
   if (existing !== undefined) {
     return { message: existing, recipientParticipantIds: [], created: false };
@@ -111,6 +154,7 @@ export function recordMessageInTransaction({ tx, session, input, now, messageId,
     inReplyTo,
     artifacts: input.artifacts ?? [],
     handoff: input.handoff ?? null,
+    ...(input.decisionChange === undefined ? {} : { decisionChange: input.decisionChange }),
     sentAt: now,
   });
   const recipientParticipantIds = addressedRecipients(tx, message, session);
@@ -248,28 +292,8 @@ export function createConversationService(ports, sessions) {
     return (await nextTurnDelivery(input)).queuedMessages;
   }
 
-  async function nextTurnDelivery(input = {}) {
-    if (typeof input.participantId !== "string" || input.participantId === "") {
-      return { queuedMessages: [], liveOfferedMessageIds: [], roomMessageIds: [] };
-    }
-    const snapshot = await store.snapshot(input.workspaceId ?? store.workspaceId,
-      { kinds: ["message", "receipt"] });
-    const receiptByMessage = new Map(snapshot.receipts
-      .filter(item => item.recipientParticipantId === input.participantId)
-      .map(item => [item.messageId, item]));
-    const eligible = snapshot.messages.filter(message => receiptByMessage.has(message.messageId)
-      && message.fromSessionId !== input.exceptSessionId)
-      .sort((left, right) => left.sentAt.localeCompare(right.sentAt)
-        || left.messageId.localeCompare(right.messageId));
-    return {
-      queuedMessages: eligible.filter(message =>
-        receiptByMessage.get(message.messageId).state === "queued"),
-      liveOfferedMessageIds: eligible.filter(message => message.toParticipantIds.length > 0
-        && receiptByMessage.get(message.messageId).state === "offered")
-        .map(message => message.messageId),
-      roomMessageIds: eligible.filter(message => message.toParticipantIds.length === 0)
-        .map(message => message.messageId),
-    };
+  function nextTurnDelivery(input) {
+    return selectNextTurnDelivery(store, input);
   }
 
   return { sendMessage, finishSession, pendingMessages, nextTurnDelivery };