negotium 0.19.2 → 0.20.0

package/dist/runtime/src/runtime/actor-topic-reach.ts

@@ -0,0 +1,85 @@
+import {
+  getTopic,
+  listSubagentChildTopicIds,
+  listSubagentTellTargetIds,
+} from "#storage/api-topics";
+import type { ActorTopicScope } from "#types";
+
+/**
+ * Rooms a turn may reach because of lineage this node itself recorded, not
+ * because a person is in them: a subagent's direct parent and the targets an
+ * ancestor granted it, and a room's own subagent workers.
+ *
+ * Lineage stands in for an assertion only when there is none — the turns that
+ * manage subagents (the spawn, the report back, the follow-up) are turns no
+ * person started, they carry no `actorTopicScope`, and cutting them off would
+ * break delegation the moment it began. A turn that *does* carry an assertion
+ * never gets lineage on top of it: the hub mirrors a subagent room with its
+ * parent's roster, so an owner of the parent is asserted as owner of the child
+ * and needs no exception, while a member who is not the owner — or a person
+ * speaking from a subagent room an ancestor granted rooms outside that
+ * person's own — must not inherit authority the hub did not assert.
+ * `canSubagentTellTarget` still applies its own rules on top (status-only,
+ * grants).
+ */
+export function subagentLineageTopicIds(currentTopicId: string | undefined): {
+  reachable: Set<string>;
+  children: Set<string>;
+} {
+  const reachable = new Set<string>();
+  const children = new Set<string>();
+  if (!currentTopicId) return { reachable, children };
+  const current = getTopic(currentTopicId);
+  if (current?.isSubagent && current.parentTopicId) {
+    reachable.add(current.parentTopicId);
+    for (const id of listSubagentTellTargetIds(currentTopicId)) reachable.add(id);
+  }
+  for (const id of listSubagentChildTopicIds(currentTopicId)) {
+    reachable.add(id);
+    children.add(id);
+  }
+  return { reachable, children };
+}
+
+/**
+ * The rooms cross-room tools may name for this turn.
+ *
+ * Off the `otium` surface the node owns membership, so nothing narrows the
+ * caller's own rooms. On `otium` the hub does, and its assertion is
+ * authoritative: with one, exactly the current room plus the asserted visible
+ * rooms are reachable — no lineage. Without one (an older hub, or a turn no
+ * person started) only the current room and its subagent lineage are
+ * reachable (fail-closed).
+ */
+export function actorReachableTopicIds(input: {
+  surface: string | undefined;
+  currentTopicId: string | undefined;
+  actorTopicScope: ActorTopicScope | undefined;
+}): ReadonlySet<string> | null {
+  if (input.surface !== "otium") return null;
+  const ids = new Set<string>();
+  if (input.currentTopicId) ids.add(input.currentTopicId);
+  if (input.actorTopicScope) {
+    for (const id of input.actorTopicScope.visibleNodeTopicIds) ids.add(id);
+    return ids;
+  }
+  for (const id of subagentLineageTopicIds(input.currentTopicId).reachable) ids.add(id);
+  return ids;
+}
+
+/**
+ * Rooms the actor may abort/restart/delete. With an assertion: exactly the
+ * rooms the hub says the actor owns (a parent's subagent workers are among
+ * them only if the hub asserted so). Without one: the current room's own
+ * subagent workers (a room controls what it delegated), nothing else. Same
+ * surface rule as {@link actorReachableTopicIds}.
+ */
+export function actorOwnedTopicIds(input: {
+  surface: string | undefined;
+  currentTopicId?: string | undefined;
+  actorTopicScope: ActorTopicScope | undefined;
+}): ReadonlySet<string> | null {
+  if (input.surface !== "otium") return null;
+  if (input.actorTopicScope) return new Set(input.actorTopicScope.ownedNodeTopicIds);
+  return subagentLineageTopicIds(input.currentTopicId).children;
+}

package/dist/runtime/src/runtime/actor-topic-scope.ts

@@ -0,0 +1,175 @@
+import type { ActorTopicScope } from "#types";
+
+/**
+ * Hard caps on a hub-supplied room assertion.
+ *
+ * The assertion is not stored and forgotten: it rides the signed per-turn MCP
+ * token, which every hosted built-in MCP server receives in the URL query
+ * (`?token=`) of an `http://127.0.0.1` request, and — with
+ * `NEGOTIUM_BUILTIN_MCP_TRANSPORT=stdio` — one base64url argv entry of the
+ * session-comm child. The transport, not the database, is the tight bound:
+ *
+ * - `Bun.serve` answers 431 once the request line is too long (Bun 1.3.14:
+ *   a 16,205-character URL is served, 16,305 is refused). These caps alone
+ *   do not bound the URL — the token carries other fields — so the whole URL
+ *   is budgeted at `MCP_URL_BUDGET_CHARS` (14 KiB) in `runtime-spec.ts`,
+ *   where the numbers live. The 8 KiB assertion below becomes 10,924
+ *   base64url characters at most; with every other runtime-token field at
+ *   its largest (the prompt itself is not in the token — only the derived
+ *   `explicitAgentSwitchTargets`, at most three agent names) the URL is
+ *   ≤ ~13.4 KB.
+ * - argv: `encodeActorTopicScopeArg` is the assertion alone, ≤ 10,924
+ *   characters, far below Linux `MAX_ARG_STRLEN` (128 KiB) for one argument
+ *   and macOS `ARG_MAX` (1 MiB) overall. The encoder re-validates before it
+ *   encodes, so an in-process caller that bypassed the gateway parser cannot
+ *   put an unbounded object into argv either.
+ *
+ * With UUID room ids (39 bytes each serialized) the byte cap admits roughly
+ * 208 ids across both lists; the per-list count cap bounds the work done on
+ * an assertion before its size is known, and the id length cap keeps a single
+ * id from being the whole budget. Raising these means moving the assertion
+ * out of the token (server-side per-turn context), not editing the numbers.
+ */
+export const ACTOR_TOPIC_SCOPE_LIMITS = Object.freeze({
+  /** Ids per list, counted before de-duplication. */
+  maxIdsPerList: 200,
+  /** Characters per id, after trimming. */
+  maxIdLength: 128,
+  /** UTF-8 bytes of the normalized assertion as JSON. */
+  maxSerializedBytes: 8 * 1024,
+});
+
+const SCOPE_KEYS = ["visibleNodeTopicIds", "ownedNodeTopicIds"] as const;
+
+export type ActorTopicScopeValidation =
+  | { ok: true; scope: ActorTopicScope | undefined }
+  | { ok: false; error: string };
+
+function idList(value: unknown, name: string): string[] | string {
+  if (!Array.isArray(value)) return `${name} must be an array of topic ids`;
+  if (value.length > ACTOR_TOPIC_SCOPE_LIMITS.maxIdsPerList) {
+    return `${name} has ${value.length} ids; at most ${ACTOR_TOPIC_SCOPE_LIMITS.maxIdsPerList} are allowed`;
+  }
+  const ids = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") return `${name} must contain only strings`;
+    const id = item.trim();
+    if (!id) return `${name} must not contain empty ids`;
+    if (id.length > ACTOR_TOPIC_SCOPE_LIMITS.maxIdLength) {
+      return `${name} contains an id longer than ${ACTOR_TOPIC_SCOPE_LIMITS.maxIdLength} characters`;
+    }
+    ids.add(id);
+  }
+  return [...ids];
+}
+
+/**
+ * Validate a hub-supplied room assertion and say why it failed.
+ *
+ * `undefined` in means `undefined` out (no assertion, fail-closed downstream);
+ * anything else must be exactly `{ visibleNodeTopicIds, ownedNodeTopicIds }`
+ * — a plain object with those two own keys and nothing else (so a stray
+ * `__proto__` or `constructor` key is a rejection, not a property), each a
+ * list of non-empty strings within {@link ACTOR_TOPIC_SCOPE_LIMITS} — or it is
+ * rejected, so a malformed assertion can never be read as "everything".
+ */
+export function validateActorTopicScope(value: unknown): ActorTopicScopeValidation {
+  if (value === undefined) return { ok: true, scope: undefined };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      error:
+        "actorTopicScope must be { visibleNodeTopicIds: string[], ownedNodeTopicIds: string[] }",
+    };
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    return { ok: false, error: "actorTopicScope must be a plain object" };
+  }
+  const keys = Object.keys(value);
+  const unknown = keys.filter((key) => !(SCOPE_KEYS as readonly string[]).includes(key));
+  if (unknown.length || keys.length !== SCOPE_KEYS.length) {
+    return {
+      ok: false,
+      error: unknown.length
+        ? `actorTopicScope has unexpected key(s): ${unknown.join(", ")}`
+        : "actorTopicScope must have both visibleNodeTopicIds and ownedNodeTopicIds",
+    };
+  }
+  const record = value as Record<string, unknown>;
+  const visible = idList(record.visibleNodeTopicIds, "actorTopicScope.visibleNodeTopicIds");
+  if (typeof visible === "string") return { ok: false, error: visible };
+  const owned = idList(record.ownedNodeTopicIds, "actorTopicScope.ownedNodeTopicIds");
+  if (typeof owned === "string") return { ok: false, error: owned };
+  const scope: ActorTopicScope = { visibleNodeTopicIds: visible, ownedNodeTopicIds: owned };
+  const bytes = Buffer.byteLength(JSON.stringify(scope), "utf-8");
+  if (bytes > ACTOR_TOPIC_SCOPE_LIMITS.maxSerializedBytes) {
+    return {
+      ok: false,
+      error: `actorTopicScope is ${bytes} bytes serialized; at most ${ACTOR_TOPIC_SCOPE_LIMITS.maxSerializedBytes} are allowed`,
+    };
+  }
+  return { ok: true, scope };
+}
+
+/**
+ * Validate a hub-supplied room assertion.
+ *
+ * `undefined` in means `undefined` out (no assertion, fail-closed downstream);
+ * anything else must pass {@link validateActorTopicScope} or it is rejected
+ * with `null`. Every path an assertion can enter by — the gateway body, the
+ * signed MCP tokens, the stdio argv — goes through this one parser, so the
+ * limits cannot drift between them.
+ */
+export function parseActorTopicScope(value: unknown): ActorTopicScope | undefined | null {
+  const validated = validateActorTopicScope(value);
+  return validated.ok ? validated.scope : null;
+}
+
+export function isActorTopicScope(value: unknown): value is ActorTopicScope {
+  return parseActorTopicScope(value) != null;
+}
+
+/**
+ * Read a validated assertion out of a persisted or signed context. Anything
+ * that does not validate collapses to "no assertion" rather than throwing, so
+ * a stale row cannot break a turn — it only narrows it to what a turn without
+ * an assertion reaches: the current room plus its own subagent lineage.
+ */
+export function actorTopicScopeFrom(value: unknown): ActorTopicScope | undefined {
+  return parseActorTopicScope(value) ?? undefined;
+}
+
+/**
+ * The strictest assertion two requests agree on: an id is kept only when both
+ * assert it, and a request without an assertion leaves the result without one
+ * (fail-closed). Used when several pending requests of one actor fold into a
+ * single turn, so the merged turn never reaches a room one of them could not.
+ */
+export function intersectActorTopicScopes(
+  scopes: ReadonlyArray<ActorTopicScope | undefined>,
+): ActorTopicScope | undefined {
+  if (scopes.length === 0 || scopes.some((scope) => scope === undefined)) return undefined;
+  const [first, ...rest] = scopes as ActorTopicScope[];
+  const keep = (key: keyof ActorTopicScope) =>
+    first[key].filter((id) => rest.every((scope) => scope[key].includes(id)));
+  return {
+    visibleNodeTopicIds: keep("visibleNodeTopicIds"),
+    ownedNodeTopicIds: keep("ownedNodeTopicIds"),
+  };
+}
+
+/**
+ * Argv-safe encoding for the stdio session-comm server (`--actor-topic-scope=`).
+ * Bounded by {@link ACTOR_TOPIC_SCOPE_LIMITS}: 8,192 bytes of JSON become at
+ * most 10,924 base64url characters, see there. The input is put through
+ * {@link validateActorTopicScope} first and an invalid or oversized assertion
+ * throws — it is never truncated (which would narrow the turn silently) nor
+ * passed on (which would let a typed in-process caller overflow argv).
+ */
+export function encodeActorTopicScopeArg(scope: ActorTopicScope): string {
+  const validated = validateActorTopicScope(scope);
+  if (!validated.ok) throw new Error(validated.error);
+  if (!validated.scope) throw new Error("actorTopicScope is required");
+  return Buffer.from(JSON.stringify(validated.scope), "utf-8").toString("base64url");
+}

package/dist/runtime/src/runtime/ask-callbacks.ts

@@ -9,7 +9,12 @@
  * (the ask/tell REST routes stayed in the host).
  */
 
-import { deliverPeerReply, type RemoteReplyRoute } from "#mcp/session-comm/peer-forward";
+import {
+  deliverPeerReply,
+  isHubRemoteReplyRoute,
+  parseHubRemoteReplyRoute,
+  type RemoteReplyRoute,
+} from "#mcp/session-comm/peer-forward";
 import { db } from "#storage/forum-db";
 import { PENDING_ASK_TTL_MS, type PendingAskUserId } from "#storage/session-asks";
 import { registerStorageSchemaInitializer } from "#storage/storage-host";
@@ -31,6 +36,13 @@ registerStorageSchemaInitializer((database) => {
       created_at INTEGER NOT NULL
     )
   `);
+  // Hub-routed asks keep their whole route here; the legacy columns are
+  // blank for them. Added after the table existed, so guarded.
+  try {
+    database.exec("ALTER TABLE remote_ask_callbacks ADD COLUMN route_json TEXT");
+  } catch {
+    // Column already present.
+  }
 });
 
 interface PendingAskIdentity {
@@ -65,25 +77,29 @@ const MAX_ASK_AGE_MS = PENDING_ASK_TTL_MS;
 export function registerAskCallback(entry: AskPending): void {
   pendingAsks.set(entry.targetQueryId, entry);
   if (entry.remoteReply) {
+    const route = entry.remoteReply;
+    const hub = isHubRemoteReplyRoute(route);
     db.query(
       `INSERT INTO remote_ask_callbacks
-       (target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
+       (target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, created_at, route_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(target_query_id) DO UPDATE SET
          request_id = excluded.request_id,
          node_name = excluded.node_name,
          node_cell_id = excluded.node_cell_id,
          topic_id = excluded.topic_id,
          user_id = excluded.user_id,
-         created_at = excluded.created_at`,
+         created_at = excluded.created_at,
+         route_json = excluded.route_json`,
     ).run(
       entry.targetQueryId,
-      entry.remoteReply.requestId,
-      entry.remoteReply.nodeName,
-      entry.remoteReply.nodeCellId,
-      entry.remoteReply.topicId,
-      entry.remoteReply.userId,
+      route.requestId,
+      route.nodeName,
+      hub ? "" : route.nodeCellId,
+      route.topicId,
+      hub ? "" : route.userId,
       entry.createdAt,
+      hub ? JSON.stringify(route) : null,
     );
   }
 }
@@ -99,10 +115,23 @@ export function resolveAskCallback(queryId: string): AskPending | null {
     entry.timedOut = true;
   }
   pendingAsks.delete(queryId);
-  db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(queryId);
+  // A hub-routed callback keeps its durable row until the answer is in the
+  // reply outbox: `deliverHubRemoteReply` deletes it in the same transaction
+  // as the outbox insert, so a crash between resolve and enqueue still leaves
+  // the row for the startup pass to fail explicitly instead of losing both.
+  if (!entry.remoteReply || !isHubRemoteReplyRoute(entry.remoteReply)) {
+    db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(queryId);
+  }
   return entry;
 }
 
+/** The hub-routed answer is durably queued: the callback row has served its purpose. */
+export function deleteHubRemoteAskCallbackRow(requestId: string): void {
+  db.query("DELETE FROM remote_ask_callbacks WHERE request_id = ? AND route_json IS NOT NULL").run(
+    requestId,
+  );
+}
+
 /** Clean up stale asks that outlived their TTL (periodic, lightweight). */
 export function purgeStaleAsks(now: number = Date.now()): void {
   for (const [id, entry] of pendingAsks) {
@@ -130,28 +159,52 @@ interface DurableRemoteAskCallbackRow {
   node_cell_id: string;
   topic_id: string;
   user_id: string;
+  route_json: string | null;
+}
+
+function durableRoute(row: DurableRemoteAskCallbackRow): RemoteReplyRoute | null {
+  if (row.route_json) {
+    try {
+      return parseHubRemoteReplyRoute(JSON.parse(row.route_json));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    nodeName: row.node_name,
+    nodeCellId: row.node_cell_id,
+    topicId: row.topic_id,
+    userId: row.user_id,
+    requestId: row.request_id,
+  };
 }
 
 /** Fail remote asks whose target turn was interrupted by the previous process.
- *  Call once during startup after the peer session bridge is registered. */
-export async function failInterruptedRemoteAskCallbacks(): Promise<number> {
+ *  Call once during startup after the peer session bridge is registered.
+ *  `routes: "hub"` limits the pass to hub-routed asks, which need no adapter
+ *  bridge and are therefore failed by the node itself at startup. */
+export async function failInterruptedRemoteAskCallbacks(
+  options: { routes?: "all" | "hub" } = {},
+): Promise<number> {
   const rows = db
     .query(
-      `SELECT target_query_id, request_id, node_name, node_cell_id, topic_id, user_id
+      `SELECT target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, route_json
        FROM remote_ask_callbacks
        ORDER BY created_at ASC`,
     )
     .all() as DurableRemoteAskCallbackRow[];
   let failed = 0;
   for (const row of rows) {
+    const route = durableRoute(row);
+    if (!route) {
+      db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(
+        row.target_query_id,
+      );
+      continue;
+    }
+    if (options.routes === "hub" && !isHubRemoteReplyRoute(route)) continue;
     const delivered = await deliverPeerReply(
-      {
-        nodeName: row.node_name,
-        nodeCellId: row.node_cell_id,
-        topicId: row.topic_id,
-        userId: row.user_id,
-        requestId: row.request_id,
-      },
+      route,
       "peer",
       "The remote worker restarted before this ask completed. Please retry the request.",
       "error",

package/dist/runtime/src/runtime/gateway-capabilities.ts

@@ -0,0 +1,22 @@
+/**
+ * Extra `GET /health` capability strings contributed by whatever is loaded
+ * alongside the node — an adapter that forwards a new gateway route over its
+ * relay, for instance. The core route list is fixed in `control.ts`; this
+ * registry lets a host advertise a capability only when the piece that makes
+ * it true is actually present, so a hub can tell "the node supports it" from
+ * "the node *and* its relay support it".
+ */
+const registered = new Set<string>();
+
+export function registerRuntimeGatewayCapability(name: string): () => void {
+  const capability = name.trim();
+  if (!capability) throw new Error("capability name is required");
+  registered.add(capability);
+  return () => {
+    registered.delete(capability);
+  };
+}
+
+export function listRuntimeGatewayCapabilities(): string[] {
+  return [...registered].sort();
+}

package/dist/runtime/src/runtime/remote-session-grant.ts

@@ -0,0 +1,221 @@
+import type { RemoteSessionGrant } from "#types";
+
+/**
+ * Hard caps on a hub-supplied remote-session grant.
+ *
+ * Like the actor room assertion (`actor-topic-scope.ts`), the grant rides the
+ * signed per-turn `session-comm` MCP token in a URL query and — with
+ * `NEGOTIUM_BUILTIN_MCP_TRANSPORT=stdio` — one base64url argv entry, so the
+ * transport bounds it, not the database. A capability is ≈330–440 characters
+ * (`rsc1.<base64url JSON>.<base64url HMAC>`) and adds ≈680 URL characters
+ * beside the maximal 8 KiB assertion (12,800 of the 14,336 budget, measured
+ * in `hosted-runtime-spec.test.ts`). The caps below leave a hub room to grow
+ * the payload, but a grant at both caps (≈3,475 URL characters) does not fit
+ * beside the *maximal* assertion — `MCP_URL_BUDGET_CHARS` is the backstop and
+ * refuses that mint loudly rather than dropping a field. A capability up to
+ * ≈1,590 characters always fits.
+ */
+export const REMOTE_SESSION_GRANT_LIMITS = Object.freeze({
+  /** Characters of `hubUrl`, after trimming. */
+  maxHubUrlLength: 512,
+  /** Characters of `capability`, after trimming. */
+  maxCapabilityLength: 2 * 1024,
+  /** The only capability format this node forwards. */
+  capabilityPrefix: "rsc1.",
+});
+
+const GRANT_KEYS = ["hubUrl", "capability"] as const;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
+
+export type RemoteSessionGrantValidation =
+  | { ok: true; grant: RemoteSessionGrant | undefined }
+  | { ok: false; error: string };
+
+/**
+ * Normalize a hub URL the node may present a bearer to: loopback `http://`
+ * or any `https://` origin, ≤ 512 characters, no credentials, no query or
+ * fragment. Returns the canonical string (trailing slash dropped) or the
+ * reason it is refused. The one rule for every hub URL the node stores — the
+ * turn grant's `hubUrl` and an ask's `remoteReply.hubUrl` alike — so a
+ * bearer can never be steered to an attacker-chosen host.
+ */
+export function normalizeHubUrl(
+  raw: string,
+  name = "remoteSession.hubUrl",
+): { url: string } | { error: string } {
+  if (raw.length > REMOTE_SESSION_GRANT_LIMITS.maxHubUrlLength) {
+    return {
+      error: `${name} is longer than ${REMOTE_SESSION_GRANT_LIMITS.maxHubUrlLength} characters`,
+    };
+  }
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { error: `${name} must be an absolute URL` };
+  }
+  if (url.username || url.password) {
+    return { error: `${name} must not carry credentials` };
+  }
+  if (url.search || url.hash || raw.includes("?") || raw.includes("#")) {
+    return { error: `${name} must not carry a query or fragment` };
+  }
+  if (url.protocol === "http:") {
+    if (!LOOPBACK_HOSTS.has(url.hostname)) {
+      return { error: `${name} must be https:// or a loopback http:// origin` };
+    }
+  } else if (url.protocol !== "https:") {
+    return { error: `${name} must be https:// or a loopback http:// origin` };
+  }
+  return { url: url.toString().replace(/\/+$/, "") };
+}
+
+/** Shape of the hub's one-shot `rsr1` reply token; the node never verifies it. */
+export const REMOTE_SESSION_REPLY_TOKEN_PATTERN = /^rsr1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/** Same cap as the capability: the hub's tokens are ≈200 characters. */
+export const MAX_REMOTE_SESSION_REPLY_TOKEN_LENGTH =
+  REMOTE_SESSION_GRANT_LIMITS.maxCapabilityLength;
+
+/**
+ * Validate a hub-supplied remote-session grant and say why it failed.
+ *
+ * `undefined` in means `undefined` out (no grant: remote session-comm stays
+ * fail-closed on `otium`); anything else must be exactly
+ * `{ hubUrl, capability }` — a plain object with those two own keys — with a
+ * callable hub URL and an opaque `rsc1.` capability within
+ * {@link REMOTE_SESSION_GRANT_LIMITS}. The node never decodes or verifies the
+ * capability: it is a bearer the hub issued and only the hub can check.
+ */
+export function validateRemoteSessionGrant(value: unknown): RemoteSessionGrantValidation {
+  if (value === undefined) return { ok: true, grant: undefined };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: "remoteSession must be { hubUrl: string, capability: string }" };
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    return { ok: false, error: "remoteSession must be a plain object" };
+  }
+  const keys = Object.keys(value);
+  const unknown = keys.filter((key) => !(GRANT_KEYS as readonly string[]).includes(key));
+  if (unknown.length || keys.length !== GRANT_KEYS.length) {
+    return {
+      ok: false,
+      error: unknown.length
+        ? `remoteSession has unexpected key(s): ${unknown.join(", ")}`
+        : "remoteSession must have both hubUrl and capability",
+    };
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.hubUrl !== "string" || !record.hubUrl.trim()) {
+    return { ok: false, error: "remoteSession.hubUrl must be a non-empty string" };
+  }
+  const hubUrl = normalizeHubUrl(record.hubUrl.trim());
+  if ("error" in hubUrl) return { ok: false, error: hubUrl.error };
+  if (typeof record.capability !== "string" || !record.capability.trim()) {
+    return { ok: false, error: "remoteSession.capability must be a non-empty string" };
+  }
+  const capability = record.capability.trim();
+  if (capability.length > REMOTE_SESSION_GRANT_LIMITS.maxCapabilityLength) {
+    return {
+      ok: false,
+      error: `remoteSession.capability is ${capability.length} characters; at most ${REMOTE_SESSION_GRANT_LIMITS.maxCapabilityLength} are allowed`,
+    };
+  }
+  if (!capability.startsWith(REMOTE_SESSION_GRANT_LIMITS.capabilityPrefix)) {
+    return {
+      ok: false,
+      error: `remoteSession.capability must start with "${REMOTE_SESSION_GRANT_LIMITS.capabilityPrefix}"`,
+    };
+  }
+  // Three dot-separated base64url parts and nothing else, so a value that
+  // is not even shaped like a capability never reaches the hub.
+  if (!/^rsc1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(capability)) {
+    return { ok: false, error: "remoteSession.capability is malformed" };
+  }
+  return { ok: true, grant: { hubUrl: hubUrl.url, capability } };
+}
+
+/** {@link validateRemoteSessionGrant} collapsed to `null` on failure. */
+export function parseRemoteSessionGrant(value: unknown): RemoteSessionGrant | undefined | null {
+  const validated = validateRemoteSessionGrant(value);
+  return validated.ok ? validated.grant : null;
+}
+
+export function isRemoteSessionGrant(value: unknown): value is RemoteSessionGrant {
+  return parseRemoteSessionGrant(value) != null;
+}
+
+/**
+ * Read a validated grant out of a persisted or signed context. Anything that
+ * does not validate collapses to "no grant" rather than throwing: a stale row
+ * only loses remote reach, it never breaks the turn.
+ */
+export function remoteSessionGrantFrom(value: unknown): RemoteSessionGrant | undefined {
+  return parseRemoteSessionGrant(value) ?? undefined;
+}
+
+/**
+ * Best-effort peek at the capability's expiry (`e`, epoch seconds), used only
+ * to order grants when several requests fold into one turn. Untrusted: the
+ * node never decides validity from it — the hub does.
+ */
+export function remoteSessionGrantExpiry(grant: RemoteSessionGrant): number | null {
+  const payload = grant.capability.split(".")[1];
+  if (!payload) return null;
+  try {
+    const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8")) as unknown;
+    const exp = (decoded as { e?: unknown } | null)?.e;
+    return typeof exp === "number" && Number.isFinite(exp) ? exp : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The grant a merged turn runs with: symmetric to `intersectActorTopicScopes`
+ * — a request without a grant leaves the batch without one (fail-closed), and
+ * a batch of grants for one hub keeps the one that expires last so the merged
+ * turn is not cut short by the oldest message's capability. Grants naming
+ * different hubs never merge (the batch runs with none). The caller has
+ * already ensured the folded requests speak for the same actor.
+ */
+export function mergeRemoteSessionGrants(
+  grants: ReadonlyArray<RemoteSessionGrant | undefined>,
+): RemoteSessionGrant | undefined {
+  if (grants.length === 0 || grants.some((grant) => grant === undefined)) return undefined;
+  const present = grants as RemoteSessionGrant[];
+  const hubUrl = present[0]!.hubUrl;
+  if (present.some((grant) => grant.hubUrl !== hubUrl)) return undefined;
+  let chosen = present[present.length - 1]!;
+  let chosenExpiry = remoteSessionGrantExpiry(chosen);
+  for (const grant of present) {
+    const expiry = remoteSessionGrantExpiry(grant);
+    if (expiry !== null && (chosenExpiry === null || expiry > chosenExpiry)) {
+      chosen = grant;
+      chosenExpiry = expiry;
+    }
+  }
+  return chosen;
+}
+
+/**
+ * Argv-safe encoding for the stdio session-comm server
+ * (`--remote-session-grant=`). Re-validated before encoding, so an in-process
+ * caller cannot put an unbounded or malformed grant into argv.
+ */
+export function encodeRemoteSessionGrantArg(grant: RemoteSessionGrant): string {
+  const validated = validateRemoteSessionGrant(grant);
+  if (!validated.ok) throw new Error(validated.error);
+  if (!validated.grant) throw new Error("remoteSession is required");
+  return Buffer.from(JSON.stringify(validated.grant), "utf-8").toString("base64url");
+}
+
+/** Inverse of {@link encodeRemoteSessionGrantArg}; `null` when malformed. */
+export function decodeRemoteSessionGrantArg(value: string): RemoteSessionGrant | null {
+  try {
+    const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf-8")) as unknown;
+    return parseRemoteSessionGrant(decoded) ?? null;
+  } catch {
+    return null;
+  }
+}