agents-can-communicate 0.3.1 → 0.4.0

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

@@ -9,24 +9,26 @@ import { isMaterialised } from "./materialisation.mjs";
 export function createIntentService(ports, sessions) {
   const { store, clock, ids } = ports;
 
-  async function requireOwner(sessionId, workspaceId, generation) {
-    const existing = await sessions.locateSession(sessionId, workspaceId);
-    if (existing === null) {
+  async function requireOwner(sessionId, workspaceId, generation, tx) {
+    const current = tx === undefined
+      ? (await sessions.locateSession(sessionId, workspaceId))?.record
+      : tx.get("session", sessionId);
+    if (current == null) {
       throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
     }
-    if (existing.record.generation !== generation) {
+    if (current.generation !== generation) {
       throw new AccError(EXIT.CONFLICT, "intent belongs to a replaced session generation",
-        { sessionId, expected: generation, actual: existing.record.generation });
+        { sessionId, expected: generation, actual: current.generation });
     }
-    if (existing.record.state !== "open") {
+    if (current.state !== "open") {
       throw new AccError(EXIT.CONFLICT, "a closed session cannot publish intent", { sessionId });
     }
-    return existing;
+    return current;
   }
 
   async function setIntent(input) {
     const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
-    const workspaceId = owner.record.workspaceId;
+    const workspaceId = owner.workspaceId;
     const now = clock.now();
     const intent = validateRecord("intent", {
       schemaVersion: SCHEMA_VERSION,
@@ -40,34 +42,52 @@ export function createIntentService(ports, sessions) {
     });
 
     if (!await isMaterialised(store, workspaceId)) {
-      await store.ephemeral.put("intent", input.sessionId, intent);
-      return intent;
+      const written = await store.ephemeral.update("intent", input.sessionId, async () => {
+        // Promotion may have won since the branch above. Never publish a new
+        // ephemeral copy that durable readers cannot see or cleanup could erase.
+        if (await isMaterialised(store, workspaceId)) return null;
+        await requireOwner(input.sessionId, workspaceId, input.generation);
+        return intent;
+      });
+      if (written !== null) return written;
     }
     await store.transaction(async tx => {
+      await requireOwner(input.sessionId, workspaceId, input.generation, tx);
       tx.put("intent", input.sessionId, intent, tx.generationOf("intent", input.sessionId));
       tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
         actorSessionId: input.sessionId, type: "intent.published", occurredAt: now,
         payload: { mode: intent.mode, state: intent.state } });
-    }, { kinds: ["intent"] });
+    }, { kinds: ["session", "intent"] });
     return intent;
   }
 
   async function clearIntent(input) {
     const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
-    const workspaceId = owner.record.workspaceId;
+    const workspaceId = owner.workspaceId;
     if (!await isMaterialised(store, workspaceId)) {
-      await store.ephemeral.delete("intent", input.sessionId);
-      return;
+      let cleared = false;
+      await store.ephemeral.delete("intent", input.sessionId, async () => {
+        if (await isMaterialised(store, workspaceId)) return false;
+        await requireOwner(input.sessionId, workspaceId, input.generation);
+        cleared = true;
+        return true;
+      });
+      if (cleared) return;
+      // A missing intent bypasses the delete guard. A close may have removed
+      // it, or promotion may have moved it to durable storage while we waited.
+      await requireOwner(input.sessionId, workspaceId, input.generation);
+      if (!await isMaterialised(store, workspaceId)) return;
     }
     const now = clock.now();
     await store.transaction(async tx => {
+      await requireOwner(input.sessionId, workspaceId, input.generation, tx);
       const current = tx.get("intent", input.sessionId);
       if (current === null) return;
       tx.put("intent", input.sessionId, { ...current, state: "done", updatedAt: now },
         tx.generationOf("intent", input.sessionId));
       tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
         actorSessionId: input.sessionId, type: "intent.cleared", occurredAt: now, payload: {} });
-    }, { kinds: ["intent"] });
+    }, { kinds: ["session", "intent"] });
   }
 
   return { setIntent, clearIntent };

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

@@ -24,13 +24,15 @@ export async function isMaterialised(store, workspaceId) {
 export async function materialise({ store, clock, ids }, { workspaceId, descriptor, reason }) {
   const now = clock.now();
   const staged = [];
-  for (const entry of EPHEMERAL_KINDS) {
-    staged.push({ ...entry, records: await store.ephemeral.list(entry.kind) });
-  }
-  const actorSessionId = staged.find(entry => entry.kind === "session")?.records.at(-1)?.sessionId
-    ?? "session_bootstrap";
 
   await store.transaction(async tx => {
+    // Ephemeral writers use this same mutex. Reading before taking it could
+    // resurrect a closed owner or replace an intent with an older snapshot.
+    for (const entry of EPHEMERAL_KINDS) {
+      staged.push({ ...entry, records: await store.ephemeral.list(entry.kind) });
+    }
+    const actorSessionId = staged.find(entry => entry.kind === "session")?.records.at(-1)?.sessionId
+      ?? "session_bootstrap";
     // Asked again inside the lock. `ensureMaterialised` asks before taking it,
     // which is a check-then-act across processes: agents starting together in a
     // workspace neither had opened - the ordinary way two agents start - all saw

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

@@ -0,0 +1,75 @@
+import { AccError, EXIT, MESSAGE_KINDS, assertPortableId }
+  from "@agents-can-communicate/protocol";
+
+const DEFAULT_LIMIT = 20;
+const PAGE_BYTES = 12_000;
+const usage = message => { throw new AccError(EXIT.USAGE, message); };
+const newestFirst = (a, b) => b.sentAt.localeCompare(a.sentAt)
+  || b.messageId.localeCompare(a.messageId);
+
+export function assertMessageId(value, label = "message id") {
+  try { assertPortableId(value, label); }
+  catch { usage(`${label} must be a complete message id returned by ACC`); }
+}
+
+function shortSubject(subject) {
+  if (Buffer.byteLength(subject) <= 160) return subject;
+  let text = "";
+  for (const character of subject) {
+    if (Buffer.byteLength(text + character + "…") > 160) break;
+    text += character;
+  }
+  return `${text}…`;
+}
+
+export function messageSummary(message) {
+  // An allowlist keeps artifacts, handoff details, and future peer payload
+  // fields out of discovery. A summary is not a retrieved message body.
+  return {
+    messageId: message.messageId, threadId: message.threadId,
+    fromParticipantId: message.fromParticipantId, fromSessionId: message.fromSessionId,
+    kind: message.kind, obligation: message.obligation,
+    subject: shortSubject(message.subject), sentAt: message.sentAt,
+    inReplyTo: message.inReplyTo, bodyBytes: Buffer.byteLength(message.body),
+    artifactCount: message.artifacts.length, trust: "untrusted peer content",
+    ...(message.decisionStatus === undefined ? {} : { decisionStatus: message.decisionStatus }),
+  };
+}
+
+export function messagePage(messages, input, { include = () => true,
+  project = messageSummary, metadata = {} } = {}) {
+  const limit = input.limit === undefined ? DEFAULT_LIMIT : input.limit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    usage("message list limit must be an integer from 1 to 500");
+  }
+  if (input.kind !== undefined && !MESSAGE_KINDS.includes(input.kind)) {
+    usage(`message type is one of ${MESSAGE_KINDS.join(", ")}`);
+  }
+  let anchor = null;
+  if (input.cursor != null) {
+    assertMessageId(input.cursor, "message cursor");
+    anchor = messages.find(message => message.messageId === input.cursor);
+    if (anchor === undefined || (input.kind !== undefined && anchor.kind !== input.kind)) {
+      usage("message cursor is not in this message list; start again without a cursor");
+    }
+  }
+  // Resolve the anchor before filtering pending state. Reading or resolving
+  // that message between pages must not shift the next page as an offset would.
+  const selected = messages.filter(message => include(message)
+    && (input.kind === undefined || message.kind === input.kind)
+    && (anchor === null || newestFirst(message, anchor) > 0)).sort(newestFirst);
+  const items = [];
+  for (const message of selected.slice(0, limit)) {
+    const item = project(message);
+    // Reserve a complete continuation id even when count, rather than bytes,
+    // eventually ends the page. Never slice a summary or a recovery id in half.
+    const candidate = { ...metadata, items: [...items, item], nextCursor: message.messageId };
+    if (Buffer.byteLength(JSON.stringify(candidate, null, 2)) > PAGE_BYTES) break;
+    items.push(item);
+  }
+  if (selected.length > 0 && items.length === 0) {
+    throw new AccError(EXIT.DATA, "one message summary exceeds the page budget");
+  }
+  return { ...metadata, items, nextCursor: items.length < selected.length
+    ? selected[items.length - 1].messageId : null };
+}

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

@@ -0,0 +1,31 @@
+export async function nextTurnDelivery(store, input = {}) {
+  if (typeof input.participantId !== "string" || input.participantId === "") {
+    return { queuedMessages: [], liveOfferedMessageIds: [], reminderMessageIds: [],
+      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.map(decisionView(snapshot.messages))
+    .filter(message => isCurrentDecision(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),
+    // A missing body is not evidence of delivery: a degraded adapter may have
+    // withheld it. Only this recipient's durable receipt permits a reminder.
+    reminderMessageIds: eligible.filter(message => message.obligation !== "none"
+      && ["offered", "retrieved"].includes(receiptByMessage.get(message.messageId).state))
+      .map(message => message.messageId),
+    roomMessageIds: eligible.filter(message => message.toParticipantIds.length === 0)
+      .map(message => message.messageId),
+  };
+}
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";

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

@@ -0,0 +1,128 @@
+import { AccError, EXIT, SCHEMA_VERSION, assertPortableId, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { isMaterialised, materialise } from "./materialisation.mjs";
+
+const sessionRecord = (input, now, generation) => validateRecord("session", {
+  schemaVersion: SCHEMA_VERSION,
+  sessionId: input.sessionId,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  generation,
+  harness: input.harness,
+  state: "open",
+  parentSessionId: input.parentSessionId ?? null,
+  checkoutRoot: input.checkoutRoot ?? null,
+  branch: input.branch ?? null,
+  pid: input.pid ?? null,
+  // Both default to the weaker reading. A session that declares nothing is a
+  // session nothing intercepts - an MCP client, or a CLI user - and claiming
+  // otherwise would promise enforcement that is not there.
+  enforcement: input.enforcement ?? "advisory",
+  lifecycle: input.lifecycle ?? "manual",
+  heartbeatCadenceMs: input.heartbeatCadenceMs,
+  startedAt: now,
+  heartbeatAt: now,
+});
+
+const participantRecord = (input, now) => validateRecord("participant", {
+  schemaVersion: SCHEMA_VERSION,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  displayName: input.displayName ?? input.participantId,
+  kind: input.participantKind ?? "agent",
+  createdAt: now,
+});
+
+// Opening owns acquisition in both stores. Lifecycle updates remain in sessions.mjs.
+export function createSessionOpener(ports, locate) {
+  const { store, clock, ids, pidIsAlive } = ports;
+
+  function assertReplaceable(existing, probe) {
+    if (existing.record.state === "closed") return;
+    // Presence staleness alone never replaces ownership: an idle-but-open
+    // session may resume at any moment, and a wrong "gone" verdict there
+    // self-corrects the moment that session next takes a turn. A wrong
+    // replacement does not self-correct - it takes the generation, and the
+    // original session's own heartbeats fail with CONFLICT from then on. So
+    // only a pid confirmed dead is authority to replace; "we cannot tell" -
+    // a session with no recorded pid - is never enough, however long the
+    // silence.
+    const live = probe ?? (record => (record.pid ?? null) === null
+      || pidIsAlive(record.pid));
+    if (live(existing.record)) {
+      throw new AccError(EXIT.CONFLICT, "the session id is already live",
+        { sessionId: existing.record.sessionId });
+    }
+  }
+
+  async function openSession(input) {
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    assertPortableId(workspaceId, "workspace id");
+    if (store.workspaceId !== undefined && workspaceId !== store.workspaceId) {
+      throw new AccError(EXIT.CONFLICT, "cannot open a session in a different workspace",
+        { workspaceId, storeWorkspaceId: store.workspaceId });
+    }
+    assertPortableId(input.participantId, "participant id");
+    const sessionId = input.sessionId ?? createId("session");
+    // A caller may persist a fresh owner pair before creation. Such a reserved
+    // generation is insert-only: it must never replace an existing session.
+    const assertAvailable = current => {
+      if (current === null) return;
+      if (input.generation !== undefined) {
+        throw new AccError(EXIT.CONFLICT, "a reserved generation requires a new session id",
+          { sessionId });
+      }
+      assertReplaceable({ record: current }, input.probe);
+    };
+    const existing = await locate(sessionId, workspaceId);
+    assertAvailable(existing?.record ?? null);
+
+    const now = clock.now();
+    const session = sessionRecord({ ...input, workspaceId, sessionId }, now,
+      input.generation === undefined ? ids.next("generation") : input.generation);
+    const participant = participantRecord({ ...input, workspaceId }, now);
+
+    const openDurable = async () => {
+      await store.transaction(async tx => {
+        const current = tx.get("session", sessionId);
+        assertAvailable(current);
+        const replaced = current?.generation ?? null;
+        if (tx.get("participant", participant.participantId) === null) {
+          tx.put("participant", participant.participantId, participant);
+        }
+        tx.put("session", sessionId, session, tx.generationOf("session", sessionId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+          actorSessionId: sessionId, type: "session.opened", occurredAt: now,
+          payload: { replaced } });
+      }, { kinds: ["participant", "session"] });
+      return session;
+    };
+    if (await isMaterialised(store, workspaceId)) return openDurable();
+
+    // Preparing a participant must not rename one that already exists, or
+    // recreate an ephemeral copy after promotion has taken ownership.
+    await store.ephemeral.update("participant", participant.participantId, async current =>
+      await isMaterialised(store, workspaceId) ? null : current ?? participant);
+    const opened = await store.ephemeral.update("session", sessionId, async current => {
+      // Check even when no copy remains: promotion may have retired it while
+      // this opener waited. Only the durable transaction may acquire that id now.
+      if (await isMaterialised(store, workspaceId)) return null;
+      assertAvailable(current);
+      return session;
+    });
+    if (opened === null) return openDurable();
+    // The approved trigger is the SECOND live session, not the first: a lone
+    // session must be able to open and close without leaving a trace.
+    const live = (await store.ephemeral.list("session")).filter(item => item.state === "open");
+    // Another opener may have promoted us after acquisition; completing the
+    // idempotent pass also retires any copies that are still pending cleanup.
+    if (live.length > 1 || await isMaterialised(store, workspaceId)) {
+      await materialise(ports, { workspaceId, descriptor: input.descriptor,
+        reason: "second_live_session" });
+    }
+    return session;
+  }
+
+  return openSession;
+}

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

@@ -1,7 +1,8 @@
-import { AccError, EXIT, SCHEMA_VERSION, assertPortableId, createId, validateRecord }
+import { AccError, EXIT, SCHEMA_VERSION }
   from "@agents-can-communicate/protocol";
 
-import { ensureMaterialised, isMaterialised, materialise } from "./materialisation.mjs";
+import { ensureMaterialised, isMaterialised } from "./materialisation.mjs";
+import { createSessionOpener } from "./session-opening.mjs";
 
 // A hook-only adapter heartbeats only when its harness gives it a turn, so the
 // staleness window is a multiple of the cadence the session itself declared
@@ -50,70 +51,25 @@ export function classifySessionPresence(session, now, pidIsAlive) {
   return age > UNKNOWN_EXPIRY_MS ? "offline" : ageBand(session, age);
 }
 
-const sessionRecord = (input, now, generation) => validateRecord("session", {
-  schemaVersion: SCHEMA_VERSION,
-  sessionId: input.sessionId,
-  participantId: input.participantId,
-  workspaceId: input.workspaceId,
-  generation,
-  harness: input.harness,
-  state: "open",
-  parentSessionId: input.parentSessionId ?? null,
-  checkoutRoot: input.checkoutRoot ?? null,
-  branch: input.branch ?? null,
-  pid: input.pid ?? null,
-  // Both default to the weaker reading. A session that declares nothing is a
-  // session nothing intercepts - an MCP client, or a CLI user - and claiming
-  // otherwise would promise enforcement that is not there.
-  enforcement: input.enforcement ?? "advisory",
-  lifecycle: input.lifecycle ?? "manual",
-  heartbeatCadenceMs: input.heartbeatCadenceMs,
-  startedAt: now,
-  heartbeatAt: now,
-});
-
-const participantRecord = (input, now) => validateRecord("participant", {
-  schemaVersion: SCHEMA_VERSION,
-  participantId: input.participantId,
-  workspaceId: input.workspaceId,
-  displayName: input.displayName ?? input.participantId,
-  kind: input.participantKind ?? "agent",
-  createdAt: now,
-});
-
 export function createSessionService(ports) {
   const { store, clock, ids, pidIsAlive } = ports;
-  const workspaceOf = input => input.workspaceId ?? store.workspaceId;
 
   async function locate(sessionId, workspaceId) {
     const ephemeral = await store.ephemeral.get("session", sessionId);
-    if (ephemeral !== null) return { record: ephemeral, durable: false };
-    const resolved = workspaceId ?? store.workspaceId;
+    const resolved = workspaceId ?? store.workspaceId ?? ephemeral?.workspaceId;
     if (resolved === undefined) return null;
     const durable = (await store.snapshot(resolved, { kinds: ["session"] })).sessions
       .find(session => session.sessionId === sessionId) ?? null;
-    return durable === null ? null : { record: durable, durable: true };
+    if (durable !== null) return { record: durable, durable: true };
+    return ephemeral !== null && ephemeral.workspaceId === resolved
+      ? { record: ephemeral, durable: false } : null;
   }
 
-  function assertReplaceable(existing, probe) {
-    if (existing.record.state === "closed") return;
-    // Presence staleness alone never replaces ownership: an idle-but-open
-    // session may resume at any moment, and a wrong "gone" verdict there
-    // self-corrects the moment that session next takes a turn. A wrong
-    // replacement does not self-correct - it takes the generation, and the
-    // original session's own heartbeats fail with CONFLICT from then on. So
-    // only a pid confirmed dead is authority to replace; "we cannot tell" -
-    // a session with no recorded pid - is never enough, however long the
-    // silence.
-    const live = probe ?? (record => (record.pid ?? null) === null
-      || pidIsAlive(record.pid));
-    if (live(existing.record)) {
-      throw new AccError(EXIT.CONFLICT, "the session id is already live",
-        { sessionId: existing.record.sessionId });
+  function assertGeneration(existing, generation, action, workspaceId) {
+    if (workspaceId !== undefined && existing.record.workspaceId !== workspaceId) {
+      throw new AccError(EXIT.CONFLICT, "session is not open in this workspace",
+        { sessionId: existing.record.sessionId, workspaceId });
     }
-  }
-
-  function assertGeneration(existing, generation, action) {
     if (existing.record.generation !== generation) {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} a replaced session generation`,
         { sessionId: existing.record.sessionId, expected: generation,
@@ -121,66 +77,28 @@ export function createSessionService(ports) {
     }
   }
 
-  async function openSession(input) {
-    const workspaceId = workspaceOf(input);
-    assertPortableId(workspaceId, "workspace id");
-    assertPortableId(input.participantId, "participant id");
-    const sessionId = input.sessionId ?? createId("session");
-    const existing = await locate(sessionId, workspaceId);
-    if (existing !== null) assertReplaceable(existing, input.probe);
-
-    const now = clock.now();
-    const session = sessionRecord({ ...input, workspaceId, sessionId }, now,
-      ids.next("generation"));
-    const participant = participantRecord({ ...input, workspaceId }, now);
-
-    if (await isMaterialised(store, workspaceId)) {
-      await store.transaction(async tx => {
-        const replaced = tx.get("session", sessionId)?.generation ?? null;
-        if (tx.get("participant", participant.participantId) === null) {
-          tx.put("participant", participant.participantId, participant);
-        }
-        tx.put("session", sessionId, session, tx.generationOf("session", sessionId));
-        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
-          actorSessionId: sessionId, type: "session.opened", occurredAt: now,
-          payload: { replaced } });
-      }, { kinds: ["participant", "session"] });
-      return session;
-    }
-
-    await store.ephemeral.put("participant", participant.participantId, participant);
-    await store.ephemeral.put("session", sessionId, session);
-    // The approved trigger is the SECOND live session, not the first: a lone
-    // session must be able to open and close without leaving a trace.
-    const live = (await store.ephemeral.list("session")).filter(item => item.state === "open");
-    // Recheck durable state only after our ephemeral writes. Another process
-    // may have staged the old ephemeral set after our first precheck, committed
-    // materialisation, and retired that set before these puts completed. In
-    // that case this attach is the only ephemeral session left, but it still
-    // has to run the idempotent promotion pass into the now-durable workspace.
-    if (live.length > 1 || await isMaterialised(store, workspaceId)) {
-      await materialise(ports, { workspaceId, descriptor: input.descriptor,
-        reason: "second_live_session" });
-    }
-    return session;
-  }
-
   async function heartbeatSession({ sessionId, workspaceId, generation }) {
-    const existing = await locate(sessionId, workspaceId);
-    if (existing === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
-    assertGeneration(existing, generation, "heartbeat");
-    const beaten = { ...existing.record, heartbeatAt: clock.now() };
-
+    const beat = current => {
+      if (current === null) return null;
+      assertGeneration({ record: current }, generation, "heartbeat", workspaceId ?? store.workspaceId);
+      if (current.state !== "open") {
+        throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+      }
+      return { ...current, heartbeatAt: clock.now() };
+    };
     // Heartbeats never append to the semantic event feed: only open, close, and
-    // presence transitions surface through cursor sync (spec section 6.4).
-    if (!existing.durable) {
-      await store.ephemeral.put("session", sessionId, beaten);
+    // presence transitions surface through cursor sync. Read and validate under
+    // the writer lock, so a pending heartbeat cannot restore an old generation.
+    // Promoted copies may await cleanup; their durable record already owns writes.
+    const ephemeral = await store.ephemeral.update("session", sessionId, async current =>
+      current !== null && !await isMaterialised(store, current.workspaceId) ? beat(current) : null);
+    if (ephemeral !== null) return ephemeral;
+    return store.transaction(tx => {
+      const beaten = beat(tx.get("session", sessionId));
+      if (beaten === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+      tx.put("session", sessionId, beaten, tx.generationOf("session", sessionId));
       return beaten;
-    }
-    await store.transaction(async tx =>
-      tx.put("session", sessionId, beaten, tx.generationOf("session", sessionId)),
-    { kinds: ["session"] });
-    return beaten;
+    }, { kinds: ["session"] });
   }
 
   /**
@@ -196,9 +114,11 @@ export function createSessionService(ports) {
    * not a second agent arriving.
    */
   async function resumeSession({ sessionId, workspaceId, generation, ...metadata }) {
+    const resolvedWorkspace = workspaceId ?? store.workspaceId;
     const resume = current => {
       if (current === null || current.state !== "open"
-        || current.generation !== generation) return null;
+        || current.generation !== generation
+        || resolvedWorkspace !== undefined && current.workspaceId !== resolvedWorkspace) return null;
       return { ...current,
       pid: metadata.pid ?? null,
       checkoutRoot: metadata.checkoutRoot ?? current.checkoutRoot,
@@ -213,13 +133,13 @@ export function createSessionService(ports) {
     // The compare and replacement happen under the ephemeral store's writer
     // lock. A close or a replacement generation can win before this update or
     // after it, but can never be overwritten from a record read beforehand.
-    const ephemeral = await store.ephemeral.update("session", sessionId, resume);
+    const ephemeral = await store.ephemeral.update("session", sessionId, async current =>
+      current !== null && !await isMaterialised(store, current.workspaceId) ? resume(current) : null);
     if (ephemeral !== null) return ephemeral;
 
     // Re-read and validate inside the durable transaction for the same reason.
     // Using generationOf only as the put token is insufficient: it protects
     // the envelope write, not the semantic generation carried by the record.
-    const resolvedWorkspace = workspaceId ?? store.workspaceId;
     if (resolvedWorkspace === undefined) return null;
     return store.transaction(async tx => {
       const current = tx.get("session", sessionId);
@@ -231,27 +151,33 @@ export function createSessionService(ports) {
   }
 
   async function closeSession({ sessionId, workspaceId, generation }) {
-    const existing = await locate(sessionId, workspaceId);
-    if (existing === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
-    assertGeneration(existing, generation, "close");
-    const now = clock.now();
-    const closed = { ...existing.record, state: "closed", heartbeatAt: now };
-
-    if (!existing.durable) {
-      // An ephemeral-only workspace vanishes with its sessions: nothing durable
-      // was written, so nothing has to be cleaned up later.
-      await store.ephemeral.delete("session", sessionId);
-      await store.ephemeral.delete("intent", sessionId);
-      return closed;
+    const close = current => {
+      assertGeneration({ record: current }, generation, "close", workspaceId ?? store.workspaceId);
+      return { ...current, state: "closed", heartbeatAt: clock.now() };
+    };
+    let ephemeral = null;
+    await store.ephemeral.delete("session", sessionId, async current => {
+      if (await isMaterialised(store, current.workspaceId)) return false;
+      ephemeral = close(current);
+      return true;
+    });
+    if (ephemeral !== null) {
+      // Cleanup is a separate locked write; a successor may have appeared since
+      // the close. Its intent must survive the old session's delayed cleanup.
+      await store.ephemeral.delete("intent", sessionId,
+        async () => await store.ephemeral.get("session", sessionId) === null);
+      return ephemeral;
     }
-
-    await store.transaction(async tx => {
+    return store.transaction(tx => {
+      const current = tx.get("session", sessionId);
+      if (current === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+      const closed = close(current);
       tx.put("session", sessionId, closed, tx.generationOf("session", sessionId));
       tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
         workspaceId: closed.workspaceId, actorSessionId: sessionId, type: "session.closed",
-        occurredAt: now, payload: {} });
+        occurredAt: closed.heartbeatAt, payload: {} });
+      return closed;
     }, { kinds: ["session"] });
-    return closed;
   }
 
   async function listLiveSessions({ participantId, workspaceId, now = clock.now() }) {
@@ -269,7 +195,7 @@ export function createSessionService(ports) {
   }
 
   return {
-    openSession,
+    openSession: createSessionOpener(ports, locate),
     resumeSession,
     heartbeatSession,
     closeSession,