@sema-agent/core 7.54.1 → 7.55.0

package/dist/agents/peer-directory.d.ts

@@ -60,7 +60,8 @@ export interface PeerSessionRecord {
     intent?: string;
     entrypoint?: string;
     peerProtocol?: number;
-    /** CC capability bits (`/^[a-z0-9_]{1,32}$/`, ≤16); `sema_mailbox_v1` marks a store-lane peer. */
+    /** CC capability bits (`/^[a-z0-9_]{1,32}$/`, ≤16); a `sema_mailbox_v1_<hex>` bit names the mailbox store the
+     *  session drains ({@link semaMailboxFeature}, read by {@link peerSessionLane}). */
     peerFeatures?: readonly string[];
     sockPath?: string;
     /** CC `cross_session_inbound: available|unavailable` — the session's SELF-REPORTED inbound posture.
@@ -68,6 +69,26 @@ export interface PeerSessionRecord {
      *  drain point decides. */
     inboundPosture?: "available" | "unavailable";
 }
+/** The prefix of the capability bit a session of this engine advertises in its row's `peerFeatures`; the
+ *  rest of the bit names the mailbox store the session drains ({@link semaMailboxFeature}). The reference's
+ *  bit grammar is `/^[a-z0-9_]{1,32}$/` and it ignores bits it does not know. */
+export declare const SEMA_MAILBOX_FEATURE_PREFIX = "sema_mailbox_v1_";
+/** The capability bit for a session that drains the store whose `MailboxStore.identity` is `storeIdentity`:
+ *  the prefix and the first 16 hex of the identity's sha-256 (32 characters, within the bit grammar). */
+export declare function semaMailboxFeature(storeIdentity: string): string;
+/** How a message reaches a peer: its durable session box (`store`), or the reference agent's socket
+ *  dialect (`uds` — the message itself crosses the socket, at-most-once). */
+export type PeerSessionLane = "store" | "uds";
+/**
+ * THE lane reading of a directory row, for a sender whose mailbox store is `ownStore`. A row with no socket
+ * has no other lane: the box (the host's directory vouches that its sessions drain the host's store). A row
+ * with a socket is reached through the box only when its bit names the SENDER's store — the one place a
+ * parked message is provably read; every other row with a socket (a reference-agent session, a session of
+ * this engine draining another store, a store that cannot say what it is) is reached over its socket.
+ */
+export declare function peerSessionLane(record: Pick<PeerSessionRecord, "sockPath" | "peerFeatures">, ownStore: {
+    readonly identity?: string;
+} | undefined): PeerSessionLane;
 /** The box-address prefix of a session box (design/385 §2.2 — the dot form: `:` is outside the file
  *  backend's path charset, `.` is inside it and outside the a* handle grammar). */
 export declare const SESSION_BOX_PREFIX = "session.";
@@ -204,9 +225,11 @@ export interface InMemoryPeerDirectory extends PeerDirectory {
     restorePeerSession(record: PeerSessionRecord): boolean;
 }
 export declare function createInMemoryPeerDirectory(): InMemoryPeerDirectory;
-/** The closed refusal set of the registry-directory ancestor-chain vetting. Each ancestor from the
- *  directory up to the filesystem root must be a real directory (no symlink on the chain — a shared
- *  /tmp lets another uid pre-plant one), owned by this uid, and not group/world-writable. */
+/** The closed refusal set of the registry-directory vetting (a shared /tmp lets another uid pre-plant a
+ *  directory or a link on the chain). The reference's nine refusal kinds land on these six: its
+ *  `directory_rule` is `foreign_owner` or `group_or_world_writable` by which half failed, `leaf_shape` is
+ *  `symlink` / `not_directory` / `foreign_owner`, `dangling_link` is `missing`, `symlink_loop` is
+ *  `symlink`, `internal` (a relative path) is `not_absolute`. */
 export type PeerRegistryDirectoryRefusal = "not_absolute" | "missing" | "symlink" | "not_directory" | "foreign_owner" | "group_or_world_writable";
 export type PeerRegistryDirectoryVerdict = {
     ok: true;
@@ -215,11 +238,22 @@ export type PeerRegistryDirectoryVerdict = {
     code: PeerRegistryDirectoryRefusal;
     path: string;
 };
-/** Vet a registry directory and every ancestor. `uid` defaults to the process uid; on a platform with
- *  no uid (win32) the owner arm is skipped. Refuses on the FIRST failing ancestor (closest first).
- *  `platform` (default: this process's) decides whether the permission bits are judged at all
- *  ({@link posixModeBitsMeaningful}): where they are not meaningful the group/world-writable arm is skipped,
- *  and nothing in this verdict says so — the caller that reads it owns any disclosure. */
+/**
+ * Vet a registry (or sockets) directory and every ancestor — the reference's rules (CC 2.1.296, `directory_rule` (cli296.js:274840); sockets-
+ * directory vetting):
+ *  - the directory ITSELF must be a real directory (never a link), owned by this uid, with no group/world
+ *    write bit;
+ *  - every ANCESTOR must be owned by this uid or by root, and be either free of group/world write bits or
+ *    sticky (`/tmp` is root-owned and sticky by design);
+ *  - an ancestor that is a LINK owned by this uid or by root is followed, and its target's chain is judged
+ *    by the same rules (macOS `/var` and `/tmp` are root-owned links); a link anyone else owns refuses,
+ *    and more than {@link VET_MAX_LINK_DEPTH} links is a loop.
+ * `uid` defaults to the process uid; on a platform with no uid (win32) the owner arms are skipped.
+ * Refuses on the FIRST failing component (closest first). `platform` (default: this process's) decides
+ * whether the permission bits are judged at all ({@link posixModeBitsMeaningful}): where they are not
+ * meaningful the mode arms are skipped, and nothing in this verdict says so — the caller that reads it
+ * owns any disclosure. `stopAt` names an ancestor at which the walk ends unjudged.
+ */
 export declare function vetPeerRegistryDirectory(dir: string, opts?: {
     uid?: number;
     stopAt?: string;

package/dist/agents/peer-directory.js

@@ -1,4 +1,6 @@
-import { lstat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { lstat, readlink } from "node:fs/promises";
+import { physicalPathOfAsync } from "../core/physical-path.js";
 import { isAbsolute, dirname, resolve as resolvePath } from "node:path";
 import { formatPeerNameRef, mintPeerRef, normalizePeerName, parsePeerNameRef, PEER_REF_RE } from "./cross-session-ref.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
@@ -17,6 +19,16 @@ export function assertPeerPresenceValue(v) {
     e.code = "config.peer_presence_invalid";
     throw e;
 }
+export const SEMA_MAILBOX_FEATURE_PREFIX = "sema_mailbox_v1_";
+export function semaMailboxFeature(storeIdentity) {
+    return `${SEMA_MAILBOX_FEATURE_PREFIX}${createHash("sha256").update(storeIdentity).digest("hex").slice(0, 16)}`;
+}
+export function peerSessionLane(record, ownStore) {
+    if (record.sockPath === undefined)
+        return "store";
+    const identity = ownStore?.identity;
+    return typeof identity === "string" && identity !== "" && (record.peerFeatures ?? []).includes(semaMailboxFeature(identity)) ? "store" : "uds";
+}
 export const SESSION_BOX_PREFIX = "session.";
 const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;
 export const PEER_SESSION_ID_GRAMMAR = "^[A-Za-z0-9_-]{1,80}$";
@@ -249,37 +261,68 @@ export function createInMemoryPeerDirectory() {
         },
     };
 }
+const VET_MAX_LINK_DEPTH = 16;
 export async function vetPeerRegistryDirectory(dir, opts) {
     if (!isAbsolute(dir))
         return { ok: false, code: "not_absolute", path: dir };
     const uid = opts?.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
     const judgeModeBits = posixModeBitsMeaningful(opts?.platform);
     const stopAt = opts?.stopAt !== undefined ? resolvePath(opts.stopAt) : undefined;
-    let cursor = resolvePath(dir);
-    for (;;) {
-        let st;
-        try {
-            st = await lstat(cursor);
-        }
-        catch {
-            return { ok: false, code: "missing", path: cursor };
-        }
-        if (st.isSymbolicLink())
-            return { ok: false, code: "symlink", path: cursor };
-        if (!st.isDirectory())
-            return { ok: false, code: "not_directory", path: cursor };
-        const parent = dirname(cursor);
-        const isRoot = parent === cursor || (stopAt !== undefined && cursor === stopAt);
-        if (!isRoot) {
-            if (uid !== undefined && st.uid !== uid)
+    const leaf = resolvePath(dir);
+    let st;
+    try {
+        st = await lstat(leaf);
+    }
+    catch {
+        return { ok: false, code: "missing", path: leaf };
+    }
+    if (st.isSymbolicLink())
+        return { ok: false, code: "symlink", path: leaf };
+    if (!st.isDirectory())
+        return { ok: false, code: "not_directory", path: leaf };
+    if (uid !== undefined && st.uid !== uid)
+        return { ok: false, code: "foreign_owner", path: leaf };
+    if (judgeModeBits && (st.mode & 0o022) !== 0)
+        return { ok: false, code: "group_or_world_writable", path: leaf };
+    const ownerOk = (owner) => uid === undefined || owner === uid || owner === 0;
+    const vetAncestors = async (from, depth) => {
+        for (let cursor = from;; cursor = dirname(cursor)) {
+            if (dirname(cursor) === cursor || (stopAt !== undefined && cursor === stopAt))
+                return { ok: true };
+            let a;
+            try {
+                a = await lstat(cursor);
+            }
+            catch {
+                return { ok: false, code: "missing", path: cursor };
+            }
+            if (a.isSymbolicLink()) {
+                if (!ownerOk(a.uid))
+                    return { ok: false, code: "foreign_owner", path: cursor };
+                if (depth >= VET_MAX_LINK_DEPTH)
+                    return { ok: false, code: "symlink", path: cursor };
+                let target;
+                try {
+                    const link = await readlink(cursor);
+                    target = isAbsolute(link) ? link : resolvePath(await physicalPathOfAsync(dirname(cursor)), link);
+                }
+                catch {
+                    return { ok: false, code: "missing", path: cursor };
+                }
+                const followed = await vetAncestors(resolvePath(target), depth + 1);
+                if (!followed.ok)
+                    return followed;
+                continue;
+            }
+            if (!a.isDirectory())
+                return { ok: false, code: "not_directory", path: cursor };
+            if (!ownerOk(a.uid))
                 return { ok: false, code: "foreign_owner", path: cursor };
-            if (judgeModeBits && (st.mode & 0o022) !== 0)
+            if (judgeModeBits && (a.mode & 0o1000) === 0 && (a.mode & 0o022) !== 0)
                 return { ok: false, code: "group_or_world_writable", path: cursor };
         }
-        if (isRoot)
-            return { ok: true };
-        cursor = parent;
-    }
+    };
+    return vetAncestors(dirname(leaf), 0);
 }
 export function judgePeerRecordFile(stat, selfUid, platform) {
     if (!stat.isFile)

package/dist/agents/peer-notices.d.ts

@@ -47,7 +47,7 @@ export declare const PEER_DELIVERY_RECEIPT_STATES: readonly ["held", "denied", "
 export type PeerDeliveryReceiptState = (typeof PEER_DELIVERY_RECEIPT_STATES)[number];
 export declare function isPeerDeliveryReceiptState(v: unknown): v is PeerDeliveryReceiptState;
 /**
- * The drop reasons a `dropped` receipt may carry (CC vocabulary, kept verbatim — the recipient's ingress guard).
+ * The drop reasons a `dropped` receipt may carry (vocabulary kept as is — the recipient's ingress guard).
  *
  * `queue-full` is a member of the set but is NOT minted by this engine today: CC judges "recipient's queue
  * is at its limit" on the recipient's ingress and reports it back as a dropped receipt, whereas here the

package/dist/agents/peer-session-drain.d.ts

@@ -10,6 +10,7 @@ import { createListAgentsTool, type ListAgentsReadSeats } from "./list-agents-to
 import { foldPermissionModeClass } from "./cross-session-judge.js";
 import type { AskEffective } from "../core/wiring-manifest.js";
 import type { SendMessageToolOptions } from "./send-message-tool.js";
+import type { PeerChannel } from "../core/peer-channel.js";
 import { type PeerClock, type PeerHeldQueue } from "./peer-held-queue.js";
 import { type PeerIdleMachine } from "./peer-idle.js";
 /** design/385 §1.2④ — the drain lease TTL. Same sizing law as the tier-3 revive lease: well under the
@@ -232,12 +233,13 @@ export declare function announcePeerLaneMount(deps: {
  *  this session's identity/attestation, whose mode class folds LIVE off the manifest's ask derivation. */
 export declare function peerLaneSendMessageSeats(args: {
     peerDirectory: PeerDirectory;
+    peerChannel?: PeerChannel;
     sessionId: string;
     scope: string;
     name?: string;
     refs: PeerLaneRefs;
     listingMounted?: boolean;
-}): Pick<SendMessageToolOptions, "peerDirectory" | "peerSelfSession" | "peerListingMounted">;
+}): Pick<SendMessageToolOptions, "peerDirectory" | "peerChannel" | "peerSelfSession" | "peerListingMounted">;
 /**
  * design/385 §5.1 — THE ListAgents mount predicate, single source: the built-in mounts only when the
  * leg's tool valve leaves it (`leaves`: the valve's one reading, `valveLeaves`) and no caller tool owns either spelling

package/dist/agents/peer-session-drain.js

@@ -763,6 +763,7 @@ export function announcePeerLaneMount(deps, leg) {
 export function peerLaneSendMessageSeats(args) {
     return {
         peerDirectory: args.peerDirectory,
+        ...(args.peerChannel !== undefined ? { peerChannel: args.peerChannel } : {}),
         ...(args.listingMounted !== undefined ? { peerListingMounted: args.listingMounted } : {}),
         peerSelfSession: {
             sessionId: args.sessionId,

package/dist/agents/read-inbox-tool.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { renderTaskNotificationXml } from "../core/task-notification.js";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 export const READ_INBOX_TOOL_NAME = "ReadInbox";
 export const READ_INBOX_MAX_LIMIT = 50;
 export const READ_INBOX_RESULT_BUDGET_CHARS = 20_000;
@@ -9,6 +9,7 @@ export function createReadInboxTool(opts) {
     return defineTool({
         name: READ_INBOX_TOOL_NAME,
         ...toolFace("read-inbox"),
+        ruleFace: mountRuleFace("read-inbox"),
         ...(opts.coversPrincipalInbox === true ? { contentOrigin: "external" } : {}),
         isConcurrencySafe: () => false,
         description: `Read the cross-session messages waiting in this session's inbox now, instead of waiting for them to arrive at your next turn boundaries. ` +

package/dist/agents/retain-ledger.d.ts

@@ -67,7 +67,7 @@ export interface SubagentRetainEntry {
     };
     /** The in-flight resume run's abort controller (parent-terminal cleanup aborts it — r1-M2). */
     activeAbort?: AbortController;
-    /** Unpin + explicitly release the retained session (best-effort; the TTL reaper is the backstop). */
+    /** Unpin + explicitly release the retained session (best-effort: a release that rejects leaves the session standing and nothing retries it — a detached eviction's rejection reaches `RetainLedgerHooks.onEvictionError`; a damaged placed row needs manual cleanup, see TtlSessionStore.release). */
     release: () => Promise<void>;
 }
 /**

package/dist/agents/roster-store.d.ts

@@ -15,7 +15,7 @@ export interface RosterEntry {
     rootSessionId?: string;
     /** design/151 S3b — the model RECORD KEY at spawn (revival lookup key; display/model-routing hints
      *  only, never a serialized spec). NOT the resolved model id: a spawn that named a model in WORDS
-     *  records the caller's spelling VERBATIM (a catalog key, tier word or CC alias), because a revival
+     *  records the caller's spelling as given (a catalog key, tier word or alias), because a revival
      *  re-resolves this value against the catalog in force at WAKE time and a resolved id would only
      *  ever resolve again on deployments whose catalog keys happen to equal model ids. A spawn that
      *  carried a Model OBJECT (definition/tool-level/inherited ref) records that object's id, which on

package/dist/agents/send-message-tool.d.ts

@@ -5,6 +5,7 @@ import { type ToolCtxEnricher } from "../core/tools.js";
 import { type TaskAccess } from "../core/task-registry.js";
 import type { PermissionModeClass } from "./cross-session-envelope.js";
 import { type PeerDirectory } from "./peer-directory.js";
+import type { PeerChannel } from "../core/peer-channel.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerLaneConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
@@ -192,6 +193,15 @@ export interface SendMessageToolOptions {
      * "no agent matches"). Absent ⇒ byte-identical pre-385 behavior.
      */
     peerDirectory?: PeerDirectory;
+    /**
+     * The socket channel ({@link import("../core/types.js").RunnerDeps.peerChannel}). The
+     * peer leg reads each resolved row's lane against {@link mailbox} ({@link peerSessionLane}): a row whose
+     * bit names this store keeps the box append and then gets a content-free doorbell on its socket (when it is
+     * live); any other row with a socket gets the message itself over the socket, at-most-once
+     * (`via: "uds"`). Absent: such a row refuses `peer_send.not_reachable` — no box append for a session that
+     * does not drain this store; a row without a socket is unchanged.
+     */
+    peerChannel?: PeerChannel;
     /**
      * design/385 — THIS session's own identity on the cross-session lane: its session id (the sender's
      * `from-session` / reply address, and the self-target guard), the scope its directory rows live in,

package/dist/agents/send-message-tool.js

@@ -6,7 +6,7 @@ import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord, clearRevivedR
 import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE, mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
 import { peerSendVerdictSeverity } from "./cross-session-judge.js";
-import { parsePeerSessionAddress, peerSessionBoxHandle, resolvePeerSessions } from "./peer-directory.js";
+import { parsePeerSessionAddress, peerSessionBoxHandle, peerSessionLane, resolvePeerSessions } from "./peer-directory.js";
 import { peerIdleMachineFor } from "./peer-idle.js";
 import { PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS, peerIdleNoticeLabel } from "./peer-notices.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
@@ -15,7 +15,7 @@ import { neutralizePeerBody } from "./cross-session-envelope.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerLaneConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
 import { assertNoRetiredKeys } from "../core/retired-keys.js";
 import { sliceHeadSafe } from "../core/surrogate-safe-slice.js";
@@ -163,6 +163,7 @@ export function createSendMessageTool(opts) {
     return defineTool({
         name: SEND_MESSAGE_TOOL_NAME,
         ...toolFace("send-message"),
+        ruleFace: mountRuleFace("send-message"),
         executionMode: "parallel",
         description: `Send a follow-up message to a previously spawned background agent. ` +
             `Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages addressed to you are delivered automatically; you don't check an inbox. ` +
@@ -187,7 +188,7 @@ export function createSendMessageTool(opts) {
                     : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
                         `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`) +
             (peerLane.active
-                ? ` Peer SESSIONS — other sessions of this engine for the same user${opts.peerListingMounted === false ? "" : opts.peerListingMounted === true ? " (list them with ListAgents)" : " (list them with ListAgents where that tool is mounted)"} — are addressed by name, by \`name [ref]\` when a name is ambiguous, or by their \`session.<id>\` address. A message to a peer is parked durably in its session box and read at its next turn boundary (an offline peer reads it when it next runs); the receipt confirms the box accepted it, not that the peer acted on it.`
+                ? ` Peer SESSIONS — other sessions of this engine for the same user${opts.peerListingMounted === false ? "" : opts.peerListingMounted === true ? " (list them with ListAgents)" : " (list them with ListAgents where that tool is mounted)"} — are addressed by name, by \`name [ref]\` when a name is ambiguous, or by their \`session.<id>\` address. A message to a peer is parked durably in its session box and read at its next turn boundary (an offline peer reads it when it next runs); the receipt confirms the box accepted it, not that the peer acted on it.${opts.peerChannel !== undefined ? " A peer whose box is not in this host's mailbox store — a Claude Code session, or a session of this engine on another store — is reached over its socket instead: nothing is parked for it, the message is sent once and only while it runs, and its receipt says so." : ""}`
                 : ""),
         parameters: sendMessageParameters,
         execute: async (args, ctx) => {
@@ -282,6 +283,8 @@ export function createSendMessageTool(opts) {
                 }
                 const modeClass = opts.peerSelfSession?.modeClass?.();
                 const now = Date.now();
+                if (peerSessionLane(record, opts.mailbox) === "uds")
+                    return deliverOverSocket(record, peerLabel, modeClass);
                 let boxFull = false;
                 try {
                     boxFull = (await opts.mailbox.peekCount(peerScope, handle)) >= admissionConfig.maxQueuedPeerMessages;
@@ -343,6 +346,7 @@ export function createSendMessageTool(opts) {
                         }
                     }
                 }
+                const doorbell = opts.peerChannel !== undefined && record.sockPath !== undefined && record.liveness === "live" && (seq !== undefined || subscriptionSeq !== undefined) ? await opts.peerChannel.nudge(record.sockPath).catch(() => false) : undefined;
                 let rowRestored = "present";
                 try {
                     const rowsNow = await opts.peerDirectory.listPeerSessions({ scope: peerScope });
@@ -372,7 +376,7 @@ export function createSendMessageTool(opts) {
                     }
                     return {
                         content: `Idle subscription recorded for ${peerLabel} (record seq ${subscriptionSeq}): you will get ONE automated notice when that session next goes idle or exits (one-shot; it expires unheard after ${PEER_IDLE_SUBSCRIPTION_TTL_MS / 3_600_000} h). No message was sent. Do not poll for it; continue with your task.${rowNote}`,
-                        details: { type: "send-message", status: "peer_idle_subscribed", to, address: handle, subscription, ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
+                        details: { type: "send-message", status: "peer_idle_subscribed", to, address: handle, subscription, ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}), ...(doorbell !== undefined ? { doorbell } : {}) },
                     };
                 }
                 const verdict = { ok: true, disposition: offline ? "parked_offline" : "queued", via: "store" };
@@ -380,7 +384,32 @@ export function createSendMessageTool(opts) {
                     content: offline
                         ? `Message parked for ${peerLabel}: that session is offline, so the message was parked durably in its session box (seq ${seq}) and will be delivered when it next runs — subject to the deployment's mailbox retirement policy, which does not notify you. Continue with your task; do not resend the same content.${subscriptionNote}${rowNote}`
                         : `Message queued for ${peerLabel} (seq ${seq}): it is parked durably in that session's box and will be read at its next turn boundary. This receipt confirms acceptance into the box, not the peer's judgment of the message. Continue with your task; do not resend the same content.${subscriptionNote}${rowNote}`,
-                    details: { type: "send-message", status: offline ? "peer_parked_offline" : "peer_queued", to, address: handle, seq, verdict, ...(subscription !== undefined ? { subscription } : {}), ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
+                    details: { type: "send-message", status: offline ? "peer_parked_offline" : "peer_queued", to, address: handle, seq, verdict, ...(subscription !== undefined ? { subscription } : {}), ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}), ...(doorbell !== undefined ? { doorbell } : {}) },
+                };
+            };
+            const deliverOverSocket = async (record, peerLabel, modeClass) => {
+                if (notifyWhenIdle)
+                    return peerRefusal("peer_send.invalid_target", `notify_when_idle is only supported for peer sessions that drain this host's mailbox store, and ${peerLabel} is reached over its socket. Nothing was sent.`);
+                if (opts.peerChannel === undefined)
+                    return peerRefusal("peer_send.not_reachable", `${peerLabel} does not drain this host's mailbox store (a Claude Code session, or a session of this engine on another store), so a message parked here would never be read, and no socket channel is wired here to reach it (RunnerDeps.peerChannel). Nothing was sent.`);
+                if (record.liveness !== "live")
+                    return peerRefusal("peer_send.not_reachable", `${peerLabel} is reached only over its socket and is not running; nothing holds a message for it while it is down. Nothing was sent.`);
+                const recipientKey = peerAxisToken(peerScope, "s", record.sessionId);
+                const sendVerdict = judgePeerAdmission(peerScope, recipientKey, { senderKey, body: message, prospectiveChain, ownTokens: [recipientKey] }, admissionConfig, undefined, "send");
+                if (!sendVerdict.ok)
+                    return admissionRefusal(sendVerdict.reason, peerLabel);
+                const verdict = await opts.peerChannel.dial(record.sockPath, {
+                    body: message,
+                    ...(peerSelfSessionId !== undefined ? { fromSession: peerSelfSessionId } : {}),
+                    fromName: ownRowName ?? opts.peerSelfSession?.name ?? senderLabel,
+                    ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
+                    hopChain: prospectiveChain,
+                });
+                if (!verdict.ok)
+                    return peerRefusal(verdict.code, `${peerLabel} could not be reached over its socket — ${verdict.message}.${verdict.code === "peer_send.send_uncertain" ? " It may have arrived: do not resend the same content blindly." : " Nothing was delivered."}`);
+                return {
+                    content: `Message sent to ${peerLabel} over its socket: it does not drain this host's mailbox store, so nothing is parked here, and the socket answers no acknowledgement — the message was written to its socket once and the connection closed cleanly, which is all this receipt confirms (not that its session took it in, nor that its model read it). Continue with your task; do not resend the same content.`,
+                    details: { type: "send-message", status: "peer_delivered", to, address: peerSessionBoxHandle(record.sessionId), verdict },
                 };
             };
             const settlePeerResolution = async (r) => {

package/dist/agents/subagent.d.ts

@@ -65,7 +65,7 @@ interface ReviewSample {
 /** Layered head/middle/tail sample of `text` under `budget`, with each skipped span marked in band so the
  *  reader can see that the material is discontinuous. Exported for tests (window determinism). */
 export declare function layeredReviewSample(text: string, budget?: number, windows?: number): ReviewSample;
-/** Default model-facing name of the delegation tool (CC 2.1.187 `Agent`; legacy alias `Task`). */
+/** Default model-facing name of the delegation tool (`Agent`; legacy alias `Task`). */
 export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
 /**
  * extraTools 快审 S4 — per-root-spawn-tree cap on `extraTools` factory evaluations. The factory runs
@@ -77,8 +77,8 @@ export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
  * runs) with the same generic-note + host-sink disclosure as a factory failure (S3 posture).
  */
 export declare const EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE = 64;
-/** RB-292 — default delegation nesting depth. CC 2.1.220 `bee()` @272064 falls back to `aHu = 3`
- *  @272076 (cli250.js:37597); the previous value 5 was CC 2.1.201's `Y4t` and is a stale anchor. Semantics (off-by-one)
+/** RB-292 — default delegation nesting depth: 3, the reference's own default (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, cli296.js:245773).
+ *  Semantics (off-by-one)
  *  are pinned on {@link SubagentToolOptions.maxDepth}. */
 export declare const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
 /**
@@ -91,31 +91,17 @@ export declare const EXTRA_TOOLS_FAILED_NOTE = "note: extraTools evaluation fail
 /** extraTools 快审 S4 — the fixed model-facing disclosure for a budget-exhausted (skipped) evaluation. */
 export declare const EXTRA_TOOLS_BUDGET_NOTE = "note: extraTools evaluation was skipped \u2014 this spawn tree exhausted its factory-call budget (64); no dynamic tools were injected for this spawn.";
 /**
- * CC206-B 欠账 — the Agent completed card's structured `toolStats` (CC 206:541193-541201 `sfd` schema:
- * seven counters, `.optional()`; counting logic 206:540431-540491 `_my`). CC derives the counts from the
- * child's transcript (assistant `tool_use` blocks) and FOLDS nested delegations' toolStats in via each
- * user message's `toolUseResult.toolStats`; sema counts on the shared forward-event sink instead — the
- * sink re-threads DESCENDANT events too (grandchildren bubble through, see subagent-steps.ts header), so
- * the cumulative semantics match without a fold step. Delegation calls themselves are excluded from every
- * bucket (CC excludes `gi`=Agent and `yU`=Task, 206:540453-540455). `linesAdded`/`linesRemoved` mirror CC
- * `i3r` (206:399357-399375): LINE COUNTS OF THE EDIT ARGUMENTS (new/old_string, Write content, NotebookEdit
- * new_source) — not a real diff; honest to CC's own approximation.
+ * The Agent completed card's structured `toolStats`: seven counters, each `.optional()`. sema counts them on the
+ * shared forward-event sink — the sink re-threads DESCENDANT events too (grandchildren bubble through, see
+ * subagent-steps.ts header), so nested delegations are counted without a separate fold step. Delegation calls
+ * themselves are excluded from every bucket. `linesAdded`/`linesRemoved` are LINE COUNTS OF THE EDIT ARGUMENTS
+ * (new/old_string, Write content, NotebookEdit new_source) — not a real diff.
  *
- * RB-303 — ANCHOR REFRESHED to CC 2.1.220 (schema @409081-409090, counting `U2_` @408252-408312).
- * The seven counters below are byte-for-byte the same seven, and the counting rules are unchanged
- * (Agent/Task excluded; nested folds via each user message's `toolUseResult.toolStats`). Two 220
- * facts the 206 anchor predates:
- *  • 220 declares an EIGHTH, optional field: `frameCount`. It counts calls to CC's Artifact tool
- *    (`F2_ = ARTIFACT_TOOL_NAME` @409045) with `input.action !== "list"`, and it is the one counter
- *    that also joins the "did this child do anything at all" sum (@408306-408312). sema has no
- *    Artifact tool, so there is no call to count: the field is deliberately NOT added (an
- *    always-absent counter is noise on every consumer). Registered as a divergence candidate — if a
- *    deployment ever mounts an artifact-shaped tool, this is where it lands.
- *  • 220's Agent result carries `modelsUsed` (ordered distinct models, emitted only when length > 1
- *    @408398) and `resolvedModel` (@466120-466127) beside toolStats. sema reports the resolved model
- *    through `TaskResult.model` and has no mid-run swap history on the delegation card. Also
- *    registered rather than added: the swap list needs a per-turn model ledger sema does not keep,
- *    and inventing a one-element array would be a face without a mechanism.
+ * Two fields of the reference's card are deliberately NOT carried, each registered as a divergence candidate:
+ *  • `frameCount` (cli296.js:34029), a count of artifact-tool calls.
+ *  • `modelsUsed` (cli296.js:54014), the ordered distinct models: sema reports the resolved model through
+ *    `TaskResult.model` and has no mid-run swap history on the delegation card; the swap list needs a per-turn
+ *    model ledger sema does not keep, and inventing a one-element array would be a face without a mechanism.
  */
 export interface SubagentToolStats {
     readCount: number;
@@ -134,9 +120,9 @@ export interface SubagentToolStats {
  */
 export declare const FORK_SUBAGENT_TYPE = "fork";
 /**
- * The BUILT-IN "general-purpose" `subagent_type` alias (CC 2.1.207 parity — 锚 pretty.js:459482 `oje`:
+ * The BUILT-IN "general-purpose" `subagent_type` alias (the reference ships the same built-in definition:
  * CC's agent registry always contains a built-in `general-purpose` definition with `tools: ["*"]`, and an
- * OMITTED `subagent_type` defaults to it, :492377 `t ?? oje.agentType`). CC-ecosystem prompts/skills
+ * OMITTED `subagent_type` defaults to it). CC-ecosystem prompts/skills
  * therefore hardcode `subagent_type: "general-purpose"` freely. sema's equivalent of that built-in is the
  * plain clean-context delegation (full tool pool, SUBAGENT_PROMPT persona) — so the literal FOLDS to the
  * omitted-type path instead of bouncing as an unknown type. A deployment (or builtin) agent definition of
@@ -568,10 +554,7 @@ export interface SubagentToolOptions {
      * `WiringManifest.fleet.subagentTranscripts` is the ADDRESSABILITY tier and folds to `"none"` on
      * the absent-row-store arm before it looks at a session store, so it cannot separate the first
      * shape above from the third. What DOES answer it is this runner's store's own pair of
-     * declarations — `sessions.durability` and its release/evict policy — read together. Upstream
-     * (CC 2.1.250) writes a sub-agent transcript unconditionally to its own file beside the parent
-     * session, so "the child conversation is readable afterwards" is never conditional on a store
-     * tier there.
+     * declarations — `sessions.durability` and its release/evict policy — read together.
      */
     runner: RunnerSelfSeat;
     /**
@@ -644,8 +627,7 @@ export interface SubagentToolOptions {
      */
     agents?: AgentDefinition[];
     /**
-     * F1 (CC 2.1.198 parity): offer the BUILT-IN read-only `Explore`/`Plan` agent types (CC `HCe`
-     * registry, GA default-on — pretty.js:487221-487240 + iAt :487127). Default `true` (CC posture);
+     * F1: offer the BUILT-IN read-only `Explore`/`Plan` agent types, on by default. Default `true`;
      * `false` removes them (the config-driven analog of CC's `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`).
      * A deployment definition named "Explore"/"Plan" SHADOWS the built-in of the same name (definition
      * wins — fork-shadowing precedent).
@@ -690,7 +672,7 @@ export interface SubagentToolOptions {
     allowTools?: string[];
     /** Tool-level denylist (design/38 1A), used when no `agent` is selected: the denied half of the child's own selector layer (a deny wins). */
     denyTools?: string[];
-    /** System prompt / persona for the child. Default (1.259.0, CC 198 parity): the LEAN
+    /** System prompt / persona for the child. Default (since 1.259.0): the LEAN
      *  {@link SUBAGENT_PROMPT} (agent persona + return contract), NOT the full default constitution role
      *  base — pass `DEFAULT_SYSTEM_PROMPT` here explicitly to restore the pre-1.259 behavior. */
     systemPrompt?: string;
@@ -704,11 +686,9 @@ export interface SubagentToolOptions {
      * Max nesting depth of delegation. A child at depth `d` only receives a delegation tool when
      * `d + 1 < maxDepth`, so it cannot recurse past the limit.
      *
-     * Default 3 (RB-292) — CC 2.1.220 parity: `bee()` @272064 returns `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`
-     * when set, else a remote-config value, else the constant `aHu = 3` @272076 (cli250.js:37597). The old default of 5 was
-     * anchored on CC 2.1.201's `Y4t` and upstream has since moved; 5 is a stale anchor, not a sema choice.
+     * Default 3 (RB-292): the same default as the reference (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, cli296.js:245773).
      * sema exposes the override as THIS option rather than an env var (deployments configure the tool, not
-     * the process), so the env/remote-config half of `bee()` has no sema counterpart to keep in sync.
+     * the process), so the env/remote-config half of that lookup has no sema counterpart to keep in sync.
      *
      * Semantics pin (off-by-one checked): with the default, the main agent + children at depths 1-2 all
      * carry a delegation tool, the depth-3 child is the STRUCTURAL leaf (no delegation tool mounted —
@@ -814,56 +794,32 @@ export interface SubagentSpawnContext {
     /** Delegation depth of the SPAWNING tool (0 = the main agent's Agent tool; a grandchild spawn sees 1, …). */
     depth: number;
 }
-/**
- * "general-purpose" alias fold (CC 2.1.207 parity — see {@link GENERAL_PURPOSE_SUBAGENT_TYPE}): rewrite
- * `subagent_type: "general-purpose"` to the OMITTED form so it takes the plain clean-context delegation
- * path (sema's built-in general-purpose equivalent: full tool pool + SUBAGENT_PROMPT persona). Wired both
- * as the tool's `prepareArguments` pre-validation shim (the declared `subagent_type` enum lists only
- * DEFINED agent names, so the literal must rewrite BEFORE the schema check) AND inside execute (direct
- * ToolSpec.execute callers). Idempotent; identity when `shadowed` (a deployment/builtin definition of the
- * same name wins — the literal then resolves as a normal agent lookup, never this fold). This is a LIVE
- * cross-vocabulary mapping, not a compatibility arm (RB-479-A③ retired the Fork `{directive}` adapter
- * that used to share this wiring).
- */
-/**
- * RB-293 — subagent_type fold, CC 2.1.220 `ulr` @317317 verbatim:
- * `e.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "")`.
- *
- * Deliberately lossy and deliberately NOT a resolver: it exists only to decide whether two spellings
- * denote the same roster entry AFTER an exact match has already failed. `\p{Pd}` is the dash punctuation
- * class (so an en-dash paste folds like a hyphen), `\p{White_Space}` covers NBSP and friends, and NFKC
- * folds fullwidth/compatibility forms — the three ways a name gets mangled between a listing line and a
- * tool call. Note it can map DISTINCT roster names onto one key ("code-review" / "code_review"), which
- * is exactly why the caller must treat a multi-hit as ambiguous rather than picking a winner.
- */
-export declare function normalizeSubagentType(value: string): string;
+export { normalizeSubagentType } from "../core/permission-rule-model.js";
 /**
  * A system-prompt note you can append to the PARENT task so the model knows delegation exists.
  * (The tool description below is the primary "explicit instruction"; this is an optional reinforcement.)
  */
 export declare const SUBAGENT_SYSTEM_NOTE: string;
 /**
- * G4 (CC 2.1.198 parity — 锚 pretty.js:225024 `Z4t` fork-boilerplate): the MESSAGE-LAYER instruction
- * frame prepended to a fork child's directive. 198 keeps the fork's SYSTEM prompt byte-identical to the
+ * G4: the MESSAGE-LAYER instruction
+ * frame prepended to a fork child's directive. The fork's SYSTEM prompt stays byte-identical to the
  * parent (prompt-cache) and carries the fork behavior contract in the messages instead — same posture
  * here: this frame wraps the `prompt` (the child's objective/user turn) and never touches systemPrompt.
- * 198-faithful verbatim (2026-07-10 realignment): the no-spawn line is now the full 198 text — the tool
- * name matches (198 `is`="Agent" = our DEFAULT_SUBAGENT_TOOL_NAME) and our tool card carries its own
- * fork guidance (:939) for the referent. An earlier adaptation dropped the "default to forking" clause
+ * The no-spawn line is the full text — the tool
+ * name matches our DEFAULT_SUBAGENT_TOOL_NAME and our tool card carries its own
+ * fork guidance for the referent. An earlier adaptation dropped the "default to forking" clause
  * as CC-specific; a live identity-confusion incident (a fork reading the parent's delegation record as
  * "someone else is on it" and stopping) showed the parent/fork disambiguation clause is load-bearing —
- * keep the anchor whole. (NOT the 88-era frame — 88's "STOP. READ THIS
- * FIRST… Scope:/Result/Key files" format was rewritten shorter and softer in 198; parity follows 198.)
- * Frame TAIL = the literal directive prefix `Your directive: ` (198 `ZDt`, pretty.js:35621; the Z4t
- * assembly is `…</fork-boilerplate>\n\n${ZDt}${directive}`, :225038, and 198 strips the SAME prefix on
- * read-back, :415673). 1.259.0 合车复审修①: an earlier transcription invented a `<directive-prefix>`
- * tag here — that tag does not exist in 198; the anchor is the plain-text prefix.
+ * keep the frame whole.
+ * Frame TAIL = the literal plain-text directive prefix `Your directive: ` (no `<directive-prefix>` tag exists;
+ * the assembly is `…</fork-boilerplate>\n\n${prefix}${directive}`, and the SAME prefix is stripped on
+ * read-back).
  */
 export declare const FORK_DIRECTIVE_FRAME = "<fork-boilerplate>\nYou are a worker fork. The transcript above is the parent's history \u2014 inherited reference, not your situation. You are NOT a continuation of that agent. Execute ONE directive, then stop.\n\nHard rules:\n- Do NOT spawn subagents with the Agent tool. The \"default to forking\" guidance is for the parent; you ARE the fork, execute directly.\n- One shot: report once and stop. No follow-up questions, no proposed next steps, no waiting for the user.\n\nGuidelines (your directive may override any of these):\n- Stay in scope. Other forks may be handling adjacent work; if you spot something outside your directive, note it in a sentence and move on.\n- Open with one line restating your task, so the parent can spot scope drift at a glance.\n- Be concise \u2014 as short as the answer allows, no shorter. Plain text, no preamble, no meta-commentary.\n- If you committed changes, list the paths and commit hashes in your report.\n</fork-boilerplate>\n\nYour directive: ";
 /**
- * RB-295 (CC 2.1.220 `Kus` @273133 — verbatim modulo the two interpolations): the path-translation note
+ * RB-295: the path-translation note
  * a FORK gets when it also runs under `isolation: "worktree"`. Upstream pushes it as its own message
- * appended AFTER the fork's directive messages (@466667: `if (L && Le) de.push(zr({content: Kus(…)}))`)
+ * appended AFTER the fork's directive messages
  * — it exists precisely because a fork INHERITS the parent's transcript, and every absolute path in that
  * transcript points at the parent's working copy while the fork's tools now resolve inside the worktree.
  * A non-fork worktree child has no inherited paths and gets no note, exactly as upstream.
@@ -874,7 +830,7 @@ export declare const FORK_DIRECTIVE_FRAME = "<fork-boilerplate>\nYou are a worke
  */
 export declare function forkWorktreeTranslationNote(parentCwd: string | undefined, worktreeDir: string): string;
 /**
- * RB-291 — the `async_launched` tool-result card, rebuilt from the CC 2.1.220 anchor (@467305-467320)
+ * RB-291 — the `async_launched` tool-result card, rebuilt from the reference's card
  * and shared by both background lanes (Agent bg + fork bg) so the two copies cannot drift apart again.
  * Three drifts were repaired against the anchor:
  *  ① the closing instruction had inverted the anchor's meaning — sema said "end your response. Do not
@@ -936,8 +892,7 @@ export declare function agentToolsNote(def: {
     denyTools?: string[];
 }): string;
 /**
- * F4 (CC 2.1.198 `tIl` selection half — 锚 pretty.js:453029 `(t && e.whenToUseLean) || e.whenToUse`,
- * `t = yg(mainLoopModel)` :479504): pick the roster guidance text for one agent definition. CC keys
+ * F4: pick the roster guidance text for one agent definition. CC keys
  * `lean` on its simple-system-prompt model predicate; sema runs the CC lean-prompt arm wholesale
  * (provider-neutral engine, web.ts lean-card precedent), so every call site passes the default
  * `lean = true` — a definition WITH `whenToUseLean` shows the lean text (exactly what modern CC main