agents-can-communicate 0.1.18 → 0.3.0

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

@@ -1,19 +1,10 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { computeAttention } from "./attention.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
-import { overlaps } from "./claims.mjs";
 
 const DEFAULT_LIMIT = 100;
-
-// The shape every event carries, and the only thing a caller may ask to resume
-// from. `null` means the beginning, which is what a session with no cursor yet
-// has.
 const CURSOR = /^[0-9]{16}$/;
-
-// The two a caller may ask for. An unknown one used to become `delta`, so
-// `--scope ful` answered the one question the full scope exists for - "show me
-// everything, I cannot see the rest of the system" - with a delta carrying no
-// snapshot at all, and the agent concluded there was nothing to see.
 const SCOPES = Object.freeze(["delta", "full"]);
 
 function assertScope(scope) {
@@ -27,299 +18,22 @@ function assertCursor(cursor) {
   if (typeof cursor !== "string" || !CURSOR.test(cursor)) {
     throw new AccError(EXIT.USAGE,
       "a cursor is the 16-digit sequence a previous sync returned; "
-      + "leave it out to start from the beginning",
-      { cursor });
-  }
-}
-
-// Attention is computed from explicit rules, never from a hidden classifier.
-// Lower priority sorts first.
-//
-// Exported so a test can prove every kind listed here is reachable. A fifth
-// entry once sat here with no rule behind it, which read as a feature in review
-// and produced nothing at runtime.
-export const ATTENTION_PRIORITY = Object.freeze({
-  direct_request: 1,
-  claim_conflict: 2,
-  task_unblocked: 3,
-  coordinator_missing: 4,
-  request_stalled: 5,
-  claim_expired: 6,
-  claim_contended: 7,
-  unread_note: 8,
-});
-
-function directRequests(snapshot, participantId) {
-  const items = [];
-  for (const receipt of snapshot.receipts ?? []) {
-    if (receipt.recipientParticipantId !== participantId) continue;
-    if (receipt.state === "acknowledged" || receipt.state === "failed") continue;
-    const message = (snapshot.messages ?? []).find(item => item.messageId === receipt.messageId);
-    if (message === undefined || !message.requiresAck) continue;
-    items.push({ kind: "direct_request", priority: ATTENTION_PRIORITY.direct_request,
-      sourceId: message.messageId, summary: message.subject });
-  }
-  return items;
-}
-
-/**
- * A note that was delivered once and then left unanswered.
- *
- * A `note` carries no acknowledgement obligation, so unlike a `requiresAck`
- * message it raises no direct_request and, once injected, drops out of the
- * inbox for good. Agents put decisions in notes anyway, and one delivered that
- * way was missed for three hours because nothing stood behind it. This is the
- * single low-priority breadcrumb that keeps a delivered-but-unacknowledged note
- * recoverable: it fires only while the receipt reads `injected`, so the runner
- * advancing it to `seen` after one showing makes it one-shot rather than a
- * standing nag - the very noise a reader learns to skip. A `queued` note is
- * about to be shown in full this turn and needs no breadcrumb yet.
- *
- * Only the recipient's, and named by message id so `acc inbox --message` or
- * `acc ack --message` can act on it without a workspace-wide lookup.
- */
-function unreadNotes(snapshot, participantId) {
-  const items = [];
-  for (const receipt of snapshot.receipts ?? []) {
-    if (receipt.recipientParticipantId !== participantId) continue;
-    if (receipt.state !== "injected") continue;
-    const message = (snapshot.messages ?? [])
-      .find(item => item.messageId === receipt.messageId);
-    // A requiresAck message already carries a standing direct_request; a second
-    // line here would be two reminders for one obligation.
-    if (message === undefined || message.requiresAck) continue;
-    items.push({ kind: "unread_note", priority: ATTENTION_PRIORITY.unread_note,
-      sourceId: message.messageId,
-      summary: `a note you have not acknowledged - \`acc inbox --message `
-        + `${message.messageId}\` to read it` });
+      + "leave it out to start from the beginning", { cursor });
   }
-  return items;
-}
-
-/**
- * A claim of yours that has run out.
- *
- * A lease lapses on the clock, and nothing said so. Measured: while it held, a
- * peer's write into the file was refused; three seconds later the same write
- * went through, and the holder's turn was identical before and after. It went on
- * working on a file it believed it had reserved, and everyone else was free to
- * change it.
- *
- * Only for the session that took it, and only while that session is the one
- * asking: a lapsed claim is news to its owner and nobody else's business.
- * Re-claiming refreshes the lease and clears this; releasing it clears it too.
- */
-function expiredClaims(snapshot, session, now) {
-  if (session == null) return [];
-  return (snapshot.claims ?? [])
-    .filter(claim => claim.ownerSessionId === session.sessionId
-      && Date.parse(claim.expiresAt) <= Date.parse(now))
-    .map(claim => ({ kind: "claim_expired", priority: ATTENTION_PRIORITY.claim_expired,
-      sourceId: claim.claimId,
-      summary: `${claim.resource} - your claim has run out, and peers can write to it` }));
-}
-
-function claimConflicts(snapshot, session, now) {
-  const mine = (snapshot.intents ?? []).find(intent => intent.sessionId === session?.sessionId);
-  if (mine === undefined) return [];
-  return (snapshot.claims ?? [])
-    .filter(claim => claim.ownerSessionId !== session.sessionId
-      && Date.parse(claim.expiresAt) > Date.parse(now)
-      && mine.resourceHints.some(hint => overlaps(hint, claim.resource)))
-    .map(claim => ({ kind: "claim_conflict", priority: ATTENTION_PRIORITY.claim_conflict,
-      sourceId: claim.claimId,
-      summary: `${claim.resource} is claimed by ${claim.ownerSessionId}` }));
-}
-
-/**
- * A resource I hold that a peer has said they intend to touch.
- *
- * The mirror of `claimConflicts`. That one reads my own intent and warns me when
- * what I mean to touch is already claimed. This one reads a peer's intent and
- * warns me, the holder, that someone is heading for what I claimed. Without it
- * intent's only wired reader faced inward: it protected the one declaring intent
- * and told the claim holder nothing, so a claim was a wall nobody was told they
- * were walking into. A claim is advisory - it does not stop the write - so being
- * told early is the whole of the protection it offers.
- *
- * Only my own claims, and never my own intent against them: declaring intent on
- * what you already hold is not someone reaching for it. The peer is named by
- * participant where the roster knows it, because a session id cannot be used
- * with `--to` and an id a reader cannot act on is the trap the projector warns of.
- */
-function claimContended(snapshot, session, now) {
-  if (session === null || session === undefined) return [];
-  const theirs = (snapshot.intents ?? [])
-    .filter(intent => intent.sessionId !== session.sessionId);
-  const nameOf = sessionId => (snapshot.sessions ?? [])
-    .find(item => item.sessionId === sessionId)?.participantId ?? "a peer";
-  return (snapshot.claims ?? [])
-    .filter(claim => claim.ownerSessionId === session.sessionId
-      && Date.parse(claim.expiresAt) > Date.parse(now))
-    .flatMap(claim => {
-      const eyeing = theirs.find(intent =>
-        (intent.resourceHints ?? []).some(hint => overlaps(hint, claim.resource)));
-      return eyeing === undefined ? [] : [{
-        kind: "claim_contended", priority: ATTENTION_PRIORITY.claim_contended,
-        sourceId: claim.claimId,
-        summary: `${claim.resource} - ${nameOf(eyeing.sessionId)} means to work on what you hold` }];
-    });
-}
-
-/**
- * Work waiting on me.
- *
- * Addressed by participant, so a request survives the recipient restarting -
- * the next session of that agent is told about it. A task already taken by one
- * of my sessions matches too, since that session may have been replaced.
- *
- * Unaddressed tasks are deliberately absent. Anyone may take one, but pushing
- * every open task into every turn is how a coordination layer becomes noise.
- */
-function unblockedTasks(snapshot, session, participantId) {
-  const mine = task => (task.assigneeParticipantId !== null
-    && task.assigneeParticipantId === participantId)
-    || (task.assigneeSessionId !== null && task.assigneeSessionId === session?.sessionId);
-  return (snapshot.tasks ?? [])
-    .filter(task => task.state === "pending" && mine(task))
-    .map(task => ({ kind: "task_unblocked", priority: ATTENTION_PRIORITY.task_unblocked,
-      sourceId: task.taskId, summary: task.title }));
-}
-
-/**
- * Work you asked for that nobody is doing any more.
- *
- * A task taken by a session that then crashed stayed `in_progress` for good:
- * the requester was told nothing and nobody else could take it. Unlike the
- * one-shot answers a request produces, this repeats until it is resolved,
- * because it stays true until someone picks the work back up.
- */
-/**
- * A question nobody is left to answer.
- *
- * The task rule below tells a requester when work they asked for is going
- * nowhere. A `requiresAck` message had no such rule, and a message is the other
- * half of the same act: an agent asked a peer a direct question, the peer's
- * session ended without answering, and the asker's next turn was empty. Not
- * "still waiting" - empty. Measured, with the only other agent gone and an
- * unanswered question standing between them.
- *
- * The same kind as the task case, because it is the same fact about the world:
- * you asked, and there is nobody there.
- */
-function unansweredQuestions(snapshot, participantId, onlineParticipants) {
-  const items = [];
-  for (const receipt of snapshot.receipts ?? []) {
-    if (receipt.state === "acknowledged" || receipt.state === "failed") continue;
-    const message = (snapshot.messages ?? [])
-      .find(item => item.messageId === receipt.messageId);
-    if (message === undefined || !message.requiresAck) continue;
-    if (message.fromParticipantId !== participantId) continue;
-    // Not answered yet by someone who is here is ordinary waiting, and saying so
-    // every turn would be noise the reader learns to skip.
-    if (onlineParticipants.has(receipt.recipientParticipantId)) continue;
-    items.push({ kind: "request_stalled", priority: ATTENTION_PRIORITY.request_stalled,
-      sourceId: message.messageId,
-      summary: `${message.subject} - ${receipt.recipientParticipantId} is not here to answer` });
-  }
-  return items;
-}
-
-function stalledRequests(snapshot, participantId, now, pidIsAlive) {
-  // Classified once per session and reused below, for the same reason
-  // collectStatus takes one reading: classifySessionPresence calls pidIsAlive,
-  // a real process.kill(pid, 0) syscall for a session with a recorded pid, so
-  // it is not pure given `now` any more. A second classifying pass here could
-  // disagree with the first - a client exiting between them would leave `live`
-  // saying "online" while a freshly-computed `onlineParticipants` had already
-  // dropped it, inside one attention computation.
-  const live = new Map((snapshot.sessions ?? [])
-    .map(session => [session.sessionId, classifySessionPresence(session, now, pidIsAlive)]));
-  const onlineParticipants = new Set((snapshot.sessions ?? [])
-    .filter(session => live.get(session.sessionId) === "online")
-    .map(session => session.participantId));
-  const goingNowhere = task => {
-    // Taken by someone who has gone quiet.
-    if (task.state === "in_progress") {
-      return task.assigneeSessionId !== null
-        && live.get(task.assigneeSessionId) !== "online";
-    }
-    // Or waiting on an agent that is not here - including one that closed and
-    // never came back, which leaves the work addressed to nobody at all.
-    return task.state === "pending" && task.assigneeParticipantId !== null
-      && !onlineParticipants.has(task.assigneeParticipantId);
-  };
-  return [
-    ...(snapshot.tasks ?? [])
-      .filter(task => task.requestedByParticipantId === participantId
-        && goingNowhere(task))
-      .map(task => ({ kind: "request_stalled", priority: ATTENTION_PRIORITY.request_stalled,
-        sourceId: task.taskId,
-        summary: `${task.title} - nobody is working on it` })),
-    ...unansweredQuestions(snapshot, participantId, onlineParticipants),
-  ];
-}
-
-function coordinatorGaps(snapshot) {
-  return (snapshot.workstreams ?? [])
-    .filter(workstream => workstream.state === "open"
-      && workstream.coordinatorSessionId === null)
-    .map(workstream => ({ kind: "coordinator_missing",
-      priority: ATTENTION_PRIORITY.coordinator_missing,
-      sourceId: workstream.workstreamId, summary: workstream.title }));
-}
-
-export function computeAttention(snapshot, { session, participantId, now, pidIsAlive }) {
-  // Required unconditionally, not only when there happen to be sessions to
-  // classify: `stalledRequests` reaches `classifySessionPresence` only inside a
-  // map/filter over `snapshot.sessions`, so an empty or absent roster let a
-  // missing probe through with nothing to trip over it - the same silent pass
-  // the classifier's own required parameter exists to close, one layer up.
-  if (typeof pidIsAlive !== "function") {
-    throw new AccError(EXIT.USAGE, "computeAttention requires a pidIsAlive probe", {});
-  }
-  return [
-    ...directRequests(snapshot, participantId),
-    ...unreadNotes(snapshot, participantId),
-    ...claimConflicts(snapshot, session, now),
-    ...claimContended(snapshot, session, now),
-    ...expiredClaims(snapshot, session, now),
-    ...unblockedTasks(snapshot, session, participantId),
-    ...coordinatorGaps(snapshot),
-    ...stalledRequests(snapshot, participantId, now, pidIsAlive),
-  ].sort((left, right) => left.priority - right.priority
-    || left.sourceId.localeCompare(right.sourceId));
 }
 
 export function createSyncService(ports, sessions) {
   const { store, clock, pidIsAlive } = ports;
 
-  /**
-   * Any session may request the full Workspace scope. Peer equality is a
-   * knowledge property: no session receives a reduced
-   * view because of its role. The bounded delta is only the ambient default.
-   */
   async function sync(input = {}) {
-    // A cursor that is not a cursor answered "nothing new", every time, for as
-    // long as it was held. `eventsSince` compares sequences as strings, so
-    // `not-a-cursor` sorts after every event there has ever been - and an
-    // adapter holding a corrupt one, or an agent that invented one, saw a quiet
-    // workspace rather than a mistake. `"0000000000000001; DROP"` was quietly
-    // taken as the sequence it starts with.
     if (input.cursor != null) assertCursor(input.cursor);
     assertScope(input.scope);
     const workspaceId = input.workspaceId ?? store.workspaceId;
     const now = clock.now();
     const located = input.sessionId === undefined
-      ? null
-      : await sessions.locateSession(input.sessionId, workspaceId);
+      ? null : await sessions.locateSession(input.sessionId, workspaceId);
     const session = located?.record ?? null;
-
     const durable = await store.snapshot(workspaceId);
-    // A workspace that has not materialised still has a truthful roster: its
-    // sessions live in the ephemeral area. Reading only the durable snapshot
-    // would make a lone session invisible to itself, and would disagree with
-    // what `status` reports from the same state.
     const snapshot = durable.workspace !== null
       ? durable
       : { ...durable,
@@ -329,7 +43,6 @@ export function createSyncService(ports, sessions) {
       input.limit ?? DEFAULT_LIMIT);
     const attention = computeAttention(snapshot, { session,
       participantId: session?.participantId ?? input.participantId, now, pidIsAlive });
-
     const roster = snapshot.sessions.map(item => ({
       sessionId: item.sessionId,
       participantId: item.participantId,
@@ -338,14 +51,10 @@ export function createSyncService(ports, sessions) {
       branch: item.branch ?? null,
       presence: classifySessionPresence(item, now, pidIsAlive),
     }));
-
-    // Solo zero-overhead: one live session, no claims and
-    // no attention means an empty result, not a "nothing to report" banner.
     const peers = roster.filter(item => item.sessionId !== session?.sessionId
       && item.presence !== "offline");
     const solo = peers.length === 0 && attention.length === 0
       && snapshot.claims.length === 0;
-
     return {
       cursor: page.cursor,
       scope: input.scope === "full" ? "full" : "delta",

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

@@ -0,0 +1,12 @@
+{
+  "name": "@agents-can-communicate/delivery-router",
+  "version": "0.3.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/"
+  ]
+}

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

@@ -0,0 +1 @@
+export { createDeliveryRouter } from "./router.mjs";

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

@@ -0,0 +1,131 @@
+const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
+  "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected",
+  "unsupported_client_version"]);
+const NAMED_LIVE_TRANSPORTS = new Set(["claude-channel", "codex-app-server"]);
+
+const adaptersById = adapters => adapters instanceof Map
+  ? adapters
+  : new Map((Array.isArray(adapters) ? adapters : Object.values(adapters ?? {}))
+    .map(adapter => [adapter.id, adapter]));
+
+// Everything that closes or advances a conversation is actionable: a question
+// or request asks for work, an answer or decision resolves it, a handoff
+// transfers it. A note informs and waits for the next turn. Room messages
+// have no recipient and are never offered live.
+const ACTIONABLE = new Set(["question", "request", "answer", "decision", "handoff"]);
+const permits = (policy, kind) => policy === "all"
+  || (policy === "actionable" && ACTIONABLE.has(kind));
+
+// Compatibility was decided twice already - at bootstrap by the probe and at
+// SessionStart by the generation-bound handshake that published this binding.
+// The router validates binding identity and the adapter's answer; it does not
+// impose a third, exact-version rule that would reject a client the handshake
+// admitted.
+const liveCapable = (adapter, binding) => adapter !== undefined
+  && adapter.capabilities?.delivery?.livePush === true
+  && adapter.nativeDelivery !== undefined
+  && binding.availableModes.includes("livePush");
+
+const durable = (recipientParticipantId, errorCode) => ({ recipientParticipantId,
+  outcome: "queued", transport: "durable", errorCode });
+
+const settled = receipt => ({ recipientParticipantId: receipt.recipientParticipantId,
+  outcome: receipt.state, transport: "durable" });
+
+function safeTransport(value, opaqueEndpointRef) {
+  if (NAMED_LIVE_TRANSPORTS.has(value) && value !== opaqueEndpointRef) return value;
+  // Both markers are fixed router vocabulary. The alternate prevents even a
+  // coincidental endpoint value equal to the primary redaction from escaping.
+  return opaqueEndpointRef === "live-adapter" ? "native-live" : "live-adapter";
+}
+
+export function createDeliveryRouter({ service, adapters, clock }) {
+  const registry = adaptersById(adapters);
+
+  async function recordFailure(binding, message, participantId, transport, safeErrorCode) {
+    await service.recordOfferFailed({ messageId: message.messageId,
+      recipientParticipantId: participantId, targetSessionId: binding.sessionId,
+      targetGeneration: binding.generation,
+      transport: safeTransport(transport, binding.opaqueEndpointRef), adapterId: binding.adapterId,
+      clientVersion: binding.clientVersion, safeErrorCode }).catch(() => null);
+  }
+
+  async function offerTo(message, participantId, now) {
+    const receipt = await service.readReceipt({ messageId: message.messageId,
+      recipientParticipantId: participantId });
+    if (receipt.state !== "queued") return settled(receipt);
+    const liveSessions = await service.listLiveSessions({ participantId, now });
+    if (liveSessions.length === 0) return durable(participantId, "recipient_unavailable");
+    if (liveSessions.length > 1) {
+      return durable(participantId, "ambiguous_recipient_sessions");
+    }
+    const [target] = liveSessions;
+    const bindings = (await service.listDeliveryBindings({ participantId, now }))
+      .filter(binding => binding.sessionId === target.sessionId
+        && binding.generation === target.generation);
+    if (bindings.length === 0) return durable(participantId, "recipient_unavailable");
+    const permitted = bindings.filter(binding => binding.livePolicy !== "off"
+      && permits(binding.livePolicy, message.kind));
+    if (permitted.length === 0) return durable(participantId, "delivery_disabled");
+    const reachable = permitted.filter(binding => binding.availableModes.includes("livePush"));
+    if (reachable.length === 0) return durable(participantId, "recipient_unavailable");
+    const capable = reachable.map(binding => ({ binding,
+      adapter: registry.get(binding.adapterId) }))
+      .filter(({ binding, adapter }) => liveCapable(adapter, binding));
+    if (capable.length === 0) {
+      return durable(participantId, "unsupported_client_version");
+    }
+    if (capable.length > 1) {
+      return durable(participantId, "ambiguous_recipient_sessions");
+    }
+
+    const { binding, adapter } = capable[0];
+    let response;
+    try {
+      // The store root is this workspace's runtime dir; the adapter resolves its
+      // opaque endpoint id under it. Passed as data, never as a leak into core:
+      // the router does not read what the adapter does with it.
+      response = await adapter.offerMessage({ binding, message,
+        runtimeDir: service.store?.root });
+    } catch {
+      await recordFailure(binding, message, participantId, "live-adapter", "transport_error");
+      return durable(participantId, "transport_error");
+    }
+    const transport = safeTransport(response?.transport, binding.opaqueEndpointRef);
+    if (response?.accepted !== true) {
+      const code = SAFE_ERRORS.has(response?.safeErrorCode)
+        ? response.safeErrorCode : "transport_rejected";
+      await recordFailure(binding, message, participantId, transport, code);
+      return durable(participantId, code);
+    }
+    if (response.clientVersion !== binding.clientVersion) {
+      await recordFailure(binding, message, participantId, transport,
+        "unsupported_client_version");
+      return durable(participantId, "unsupported_client_version");
+    }
+    try {
+      await service.recordOfferSucceeded({ messageId: message.messageId,
+        recipientParticipantId: participantId, targetSessionId: binding.sessionId,
+        targetGeneration: binding.generation, transport, adapterId: binding.adapterId,
+        clientVersion: binding.clientVersion });
+    } catch {
+      await recordFailure(binding, message, participantId, transport, "transport_error");
+      return durable(participantId, "transport_error");
+    }
+    return { recipientParticipantId: participantId, outcome: "offered", transport };
+  }
+
+  async function offer(message) {
+    if (!Array.isArray(message?.toParticipantIds) || message.toParticipantIds.length === 0) {
+      return [];
+    }
+    const now = clock.now();
+    const outcomes = [];
+    for (const participantId of message.toParticipantIds) {
+      outcomes.push(await offerTo(message, participantId, now));
+    }
+    return outcomes;
+  }
+
+  return Object.freeze({ offer });
+}

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

@@ -1,10 +1,12 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.1.18",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/runner.mjs"
+    ".": "./src/runner.mjs",
+    "./client-pid": "./src/client-pid.mjs",
+    "./process-table": "./src/process-table.mjs"
   },
   "files": [
     "src/"

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

@@ -0,0 +1,20 @@
+import { execFile } from "node:child_process";
+
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
+
+export function parseClientVersion(output) {
+  return typeof output === "string" ? VERSION.exec(output)?.[1] ?? null : null;
+}
+
+/** Probe the client binary once when its real session starts. */
+export function probeClientVersion(adapter, { timeoutMs = 1_000 } = {}) {
+  return new Promise(resolve => {
+    execFile(adapter.client.command, adapter.client.versionArgs ?? ["--version"], {
+      timeout: timeoutMs,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      if (error !== null) return resolve(null);
+      resolve(parseClientVersion(`${stdout}${stderr}`));
+    });
+  });
+}

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

@@ -0,0 +1,90 @@
+import { validateNativeHandshake } from "@agents-can-communicate/adapter-sdk";
+import { EXIT } from "@agents-can-communicate/protocol";
+
+// The hook side of native delivery: one bounded, fail-open attempt to bind
+// this exact ACC session generation to the vendor session the adapter can
+// reach, then a sanitized binding published for the router. The helper, not
+// the adapter, supplies adapter id, client facts, session id, and generation;
+// the adapter supplies only closed handshake facts. Nothing here throws into
+// the hook path, and no endpoint reference ever leaves through the result.
+
+export const LIVE_POLICIES = Object.freeze(["off", "actionable", "all"]);
+export const NATIVE_BINDING_STATES = Object.freeze(["active", "off", "degraded", "unsupported"]);
+const DEFAULT_TIMEOUT_MS = 750;
+const DEFAULT_CADENCE_MS = 60_000;
+
+// Reasons the static rule refused: the client will not change within the
+// session, so the state is "unsupported" rather than a retryable "degraded".
+const STATIC_REASONS = new Set(["native_delivery_unsupported", "platform_not_captured",
+  "version_unavailable", "prerelease_not_captured", "below_minimum_version",
+  "known_bad_version"]);
+
+// Only the value a successful owned shell bootstrap exported counts; anything
+// else - missing, blank, differently cased, a number - is off.
+export function livePolicyFrom(env) {
+  const value = env?.ACC_NATIVE_DELIVERY_POLICY;
+  return LIVE_POLICIES.includes(value) ? value : "off";
+}
+
+const isPid = value => Number.isInteger(value) && value > 0;
+
+export async function establishNativeBinding({ adapter, event, hookBinding, clientVersion,
+  platform, livePolicy, service, runtimeDir, clock,
+  timeoutMs = DEFAULT_TIMEOUT_MS, heartbeatCadenceMs = DEFAULT_CADENCE_MS }) {
+  const outcome = (state, reasonCode, modes = []) =>
+    Object.freeze({ state, reasonCode, modes: Object.freeze([...modes]) });
+  const sessionId = hookBinding?.accSessionId;
+  const generation = hookBinding?.generation;
+  if (typeof sessionId !== "string" || typeof generation !== "string") return outcome("off", null);
+  const policy = LIVE_POLICIES.includes(livePolicy) ? livePolicy : "off";
+  const clear = () => service.clearDeliveryBinding({ sessionId, generation }).catch(() => null);
+  if (policy === "off") {
+    await clear();
+    return outcome("off", null);
+  }
+  if (adapter?.nativeDelivery === undefined || typeof adapter.bindNativeSession !== "function") {
+    return outcome("unsupported", "native_delivery_unsupported");
+  }
+  const clientPid = hookBinding.clientPid;
+  if (!isPid(clientPid)) {
+    await clear();
+    return outcome("degraded", "client_process_unknown");
+  }
+  // Whatever this generation published before is retired first, so a failed
+  // re-handshake can never leave yesterday's endpoint reachable.
+  await clear();
+  let timer = null;
+  try {
+    const budget = Math.max(1, Math.floor(timeoutMs));
+    const handshake = await Promise.race([
+      adapter.bindNativeSession({ event, clientPid, clientVersion, runtimeDir, timeoutMs: budget }),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(Object.assign(new Error("native handshake timed out"),
+          { code: "ETIMEDOUT" })), budget);
+      }),
+    ]);
+    const verdict = validateNativeHandshake(adapter, { clientVersion, platform, handshake });
+    if (!verdict.ok) {
+      return outcome(STATIC_REASONS.has(verdict.reasonCode) ? "unsupported" : "degraded",
+        verdict.reasonCode);
+    }
+    const now = Date.parse(clock.now());
+    const lease = Date.parse(verdict.leaseUntil);
+    if (!(lease > now)) return outcome("degraded", "handshake_failed");
+    const ceiling = now + 2 * heartbeatCadenceMs;
+    const leaseUntil = lease > ceiling ? new Date(ceiling).toISOString() : verdict.leaseUntil;
+    await service.publishDeliveryBinding({
+      sessionId, generation, adapterId: adapter.id, clientVersion,
+      availableModes: [...verdict.modes], livePolicy: policy,
+      opaqueEndpointRef: verdict.opaqueEndpointRef, leaseUntil,
+    });
+    return outcome("active", null, verdict.modes);
+  } catch (error) {
+    await clear();
+    const reasonCode = error?.code === "ETIMEDOUT" ? "handshake_timeout"
+      : error?.code === EXIT.CONFLICT ? "session_generation_stale" : "handshake_failed";
+    return outcome("degraded", reasonCode);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+}