agents-can-communicate 0.3.1 → 0.4.0

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.1",
+  "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) {
@@ -127,8 +130,8 @@ export function recordMessageInTransaction({ tx, session, input: raw, now, messa
   // 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 = { ...raw,
-    toParticipantIds: resolveAddressees(tx, raw.toParticipantIds ?? [], session) };
+  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 };
@@ -151,6 +154,7 @@ export function recordMessageInTransaction({ tx, session, input: raw, now, messa
     inReplyTo,
     artifacts: input.artifacts ?? [],
     handoff: input.handoff ?? null,
+    ...(input.decisionChange === undefined ? {} : { decisionChange: input.decisionChange }),
     sentAt: now,
   });
   const recipientParticipantIds = addressedRecipients(tx, message, session);
@@ -288,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 };

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

@@ -0,0 +1,36 @@
+import { AccError, EXIT, assertDecisionChange } from "@agents-can-communicate/protocol";
+
+// Resolve inherited recipients before retry comparison. Target messages and
+// their recipient sets are immutable, so receipt advancement cannot alter a retry.
+export function prepareDecisionChange(tx, input, session) {
+  if (input.decisionChange !== undefined) {
+    throw new AccError(EXIT.USAGE, "send a decision change using supersedes or withdraws");
+  }
+  if (input.supersedes === undefined && input.withdraws === undefined) return input;
+  if (input.kind !== "decision" || (input.supersedes !== undefined && input.withdraws !== undefined)) {
+    throw new AccError(EXIT.USAGE, "only decisions accept either supersedes or withdraws, never both");
+  }
+  const decisionChange = assertDecisionChange({
+    action: input.supersedes === undefined ? "withdraw" : "replace",
+    messageIds: input.supersedes ?? input.withdraws,
+  });
+  decisionChange.messageIds = [...decisionChange.messageIds].sort();
+  const targets = decisionChange.messageIds.map(messageId => {
+    const message = tx.get("message", messageId);
+    if (message?.kind !== "decision" || message.workspaceId !== session.workspaceId) {
+      throw new AccError(EXIT.DATA, "a decision change must reference existing decisions in this workspace",
+        { messageId });
+    }
+    return message;
+  });
+  if (new Set(input.toParticipantIds).size !== input.toParticipantIds.length) {
+    throw new AccError(EXIT.USAGE, "a participant may be addressed only once");
+  }
+  const targetIds = new Set(decisionChange.messageIds);
+  const inherited = [...targets.map(message => message.fromParticipantId),
+    ...tx.list("receipt", receipt => targetIds.has(receipt.messageId))
+      .map(receipt => receipt.recipientParticipantId)]
+    .filter(participantId => participantId !== session.participantId);
+  return { ...input, decisionChange,
+    toParticipantIds: [...new Set([...input.toParticipantIds, ...inherited])].sort() };
+}

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

@@ -0,0 +1,42 @@
+// Lifecycle is a read model of explicit peer assertions, never a timestamp
+// winner or a consensus verdict. Iterative traversal avoids recursion limits.
+export function decisionView(messages) {
+  const decisions = new Map(messages.filter(m => m.kind === "decision").map(m => [m.messageId, m]));
+  const neighbours = new Map([...decisions.keys()].map(id => [id, new Set()]));
+  const replaced = new Set();
+  for (const message of decisions.values()) {
+    for (const target of message.decisionChange?.messageIds ?? []) {
+      if (!decisions.has(target)) continue;
+      neighbours.get(target).add(message.messageId);
+      neighbours.get(message.messageId).add(target);
+      replaced.add(target);
+    }
+  }
+  const statuses = new Map();
+  for (const start of decisions.keys()) {
+    if (statuses.has(start)) continue;
+    const group = new Set([start]), pending = [start];
+    while (pending.length > 0) {
+      for (const id of neighbours.get(pending.pop())) {
+        if (!group.has(id)) { group.add(id); pending.push(id); }
+      }
+    }
+    const heads = [...group].filter(id => !replaced.has(id));
+    const hasDecision = heads.some(id => decisions.get(id).decisionChange?.action !== "withdraw");
+    const roots = [...group].filter(id => decisions.get(id).decisionChange === undefined);
+    const groupId = (roots.length > 0 ? roots : [...group]).sort()[0];
+    for (const id of group) {
+      const isHead = !replaced.has(id);
+      statuses.set(id, {
+        state: isHead ? (decisions.get(id).decisionChange?.action === "withdraw" ? "withdrawn" : "current")
+          : (hasDecision ? "superseded" : "withdrawn"),
+        isHead, conflicted: heads.length !== 1, headCount: heads.length,
+        currentMessageId: heads.length === 1 ? heads[0] : null, groupId,
+      });
+    }
+  }
+  return message => statuses.has(message.messageId)
+    ? { ...message, decisionStatus: statuses.get(message.messageId) } : message;
+}
+
+export const isCurrentDecision = message => message.decisionStatus?.isHead !== false;

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

@@ -81,18 +81,24 @@ export function createDeliveryBindingService(ports, sessions) {
   // delete() takes the same mutex, so this is the one atomic form: a stale
   // generation cannot retire a successor's endpoint, and an absent or
   // already-retired binding stays as it is.
+  // A caller that captured an endpoint may also scope retirement to that exact
+  // address. This protects a same-generation re-handshake that publishes while
+  // an older bounded cleanup call is still waiting to enter the writer lock.
   //
   // The retirement is recorded as its own fact rather than as an expired lease.
   // Expiry and retirement used to be the same edit, so a channel still renewing
   // its endpoint could extend a binding the session had already given up.
-  async function clearDeliveryBinding({ sessionId, generation }) {
+  async function clearDeliveryBinding(input) {
+    const { sessionId, generation } = input;
+    const endpointScoped = Object.hasOwn(input, "opaqueEndpointRef");
     await store.ephemeral.update("deliveryBinding", sessionId, async current => {
       if (current === null || current === undefined) return null;
       if (current.generation !== generation) throw conflict(sessionId);
+      if (endpointScoped && current.opaqueEndpointRef !== input.opaqueEndpointRef) return null;
       if (current.retiredAt !== null && current.retiredAt !== undefined) return null;
       const now = clock.now();
       return { ...current, leaseUntil: now, retiredAt: now };
-    });
+    }, { deadlineAt: input.deadlineAt });
   }
 
   /**
@@ -120,9 +126,10 @@ export function createDeliveryBindingService(ports, sessions) {
     });
   }
 
-  async function listDeliveryBindings({ participantId, now }) {
+  async function listDeliveryBindings({ participantId, now, includeExpired = false }) {
     return (await currentBindings(now))
-      .filter(item => item.participantId === participantId && item.reachable)
+      .filter(item => item.participantId === participantId
+        && (includeExpired || item.reachable))
       .map(item => item.binding);
   }
 

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

@@ -2,6 +2,8 @@ import { AccError, EXIT, SCHEMA_VERSION, advanceReceipt }
   from "@agents-can-communicate/protocol";
 
 import { receiptId, recordMessageInTransaction } from "./conversations.mjs";
+import { messagePage, messageSummary } from "./message-pages.mjs";
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
 const listable = (message, receipt) => receipt.state === "queued" || receipt.state === "offered"
   || (receipt.state === "retrieved" && message.obligation !== "none");
@@ -9,14 +11,19 @@ const listable = (message, receipt) => receipt.state === "queued" || receipt.sta
 export function createInboxService(ports, sessions) {
   const { store, clock, ids } = ports;
 
-  async function requireOpen(input, action) {
-    const located = await sessions.locateSession(input.sessionId, input.workspaceId);
-    if (located === null || located.record.state !== "open"
-      || located.record.generation !== input.generation) {
+  async function requireOpen(input, action, tx) {
+    // A solo inbox may have no durable session yet. Inside a transaction the
+    // same writer lock also protects this ephemeral read from replacement.
+    const current = tx === undefined
+      ? (await sessions.locateSession(input.sessionId, input.workspaceId))?.record
+      : tx.get("session", input.sessionId)
+        ?? await store.ephemeral.get("session", input.sessionId);
+    if (current == null || current.state !== "open"
+      || current.generation !== input.generation) {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} from this session generation`,
         { sessionId: input.sessionId });
     }
-    return located.record;
+    return current;
   }
 
   function requireOwnedReceipt(tx, session, messageId) {
@@ -46,19 +53,38 @@ export function createInboxService(ports, sessions) {
     return { message: owned.message, receipt };
   }
 
+  async function listInbox(input) {
+    const session = await requireOpen(input, "list the inbox");
+    return store.transaction(async tx => {
+      await requireOpen(input, "list the inbox", tx);
+      const receipts = new Map(tx.list("receipt", receipt =>
+        receipt.recipientParticipantId === session.participantId)
+        .map(receipt => [receipt.messageId, receipt]));
+      const all = tx.list("message"), view = decisionView(all);
+      const messages = all.filter(message => receipts.has(message.messageId)).map(view);
+      return messagePage(messages, input, {
+        include: message => isCurrentDecision(message) && listable(message, receipts.get(message.messageId)),
+        project: message => ({ message: messageSummary(message),
+          receipt: receipts.get(message.messageId) }),
+      });
+    }, { kinds: ["session", "message", "receipt"] });
+  }
+
   async function readInbox(input) {
     const session = await requireOpen(input, "read the inbox");
     const now = clock.now();
-    return store.transaction(tx => {
-      const messages = new Map(tx.list("message").map(item => [item.messageId, item]));
+    return store.transaction(async tx => {
+      await requireOpen(input, "read the inbox", tx);
+      const all = tx.list("message"), view = decisionView(all);
+      const messages = new Map(all.map(item => [item.messageId, view(item)]));
       let selected = tx.list("receipt", receipt =>
         receipt.recipientParticipantId === session.participantId)
         .filter(receipt => messages.has(receipt.messageId));
       if (input.messageId === undefined) {
-        selected = selected.filter(receipt => listable(messages.get(receipt.messageId), receipt));
+        selected = selected.filter(receipt => listable(messages.get(receipt.messageId), receipt)
+          && isCurrentDecision(messages.get(receipt.messageId)));
       } else {
-        selected = selected.filter(receipt => receipt.messageId === input.messageId
-          && receipt.state !== "acknowledged");
+        selected = selected.filter(receipt => receipt.messageId === input.messageId);
         if (selected.length === 0) {
           throw new AccError(EXIT.CONFLICT,
             "that message is not recoverable by this participant",
@@ -70,17 +96,22 @@ export function createInboxService(ports, sessions) {
         const b = messages.get(right.messageId);
         return a.sentAt.localeCompare(b.sentAt) || a.messageId.localeCompare(b.messageId);
       });
-      return selected.map(receipt => advanceOwned(tx, session, receipt.messageId,
-        "retrieved", now));
-    }, { kinds: ["message", "receipt"] });
+      // An exact read can inspect a resolved message. Inspection must neither
+      // move its receipt backward nor refresh its timestamp or emit an event.
+      return selected.map(receipt => receipt.state === "acknowledged"
+        ? { message: messages.get(receipt.messageId), receipt }
+        : { ...advanceOwned(tx, session, receipt.messageId, "retrieved", now),
+          message: messages.get(receipt.messageId) });
+    }, { kinds: ["session", "message", "receipt"] });
   }
 
   async function acknowledgeMessage(input) {
     const session = await requireOpen(input, "acknowledge a message");
     const now = clock.now();
-    return store.transaction(tx => advanceOwned(tx, session, input.messageId,
-      "acknowledged", now).receipt,
-    { kinds: ["message", "receipt"] });
+    return store.transaction(async tx => {
+      await requireOpen(input, "acknowledge a message", tx);
+      return advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
+    }, { kinds: ["session", "message", "receipt"] });
   }
 
   async function replyToMessage(input) {
@@ -114,5 +145,5 @@ export function createInboxService(ports, sessions) {
     }, { kinds: ["participant", "session", "message", "receipt"] });
   }
 
-  return { readInbox, replyToMessage, acknowledgeMessage };
+  return { listInbox, readInbox, replyToMessage, acknowledgeMessage };
 }