@sema-agent/core 7.1.0 → 7.3.0

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

@@ -0,0 +1,208 @@
+/** The row schema version this engine writes and fully understands. A row carrying a HIGHER version
+ *  is a newer engine's row: it is skipped as `schema_newer` (capability negotiation — the row is not
+ *  garbage, this engine simply cannot judge it), never treated as a malformed value. */
+export declare const PEER_SESSION_RECORD_SCHEMA_VERSION = 1;
+/** CC `Fa(s, 262144)` — the read cap of one registration file. */
+export declare const PEER_SESSION_RECORD_MAX_BYTES = 262144;
+export type PeerSessionLiveness = "live" | "dead" | "deleted";
+export type PeerSessionTempo = "active" | "idle" | "blocked";
+/** The registration row. Field set = CC's load-bearing subset + sema's `scope` axis + the sema-only
+ *  liveness/tombstone members. A host writes it; every terminal reads it through {@link readPeerSessionRecord}. */
+export interface PeerSessionRecord {
+    schemaVersion: number;
+    /** The session's durable identity: its box address is `session.<sessionId>` ({@link peerSessionBoxHandle}). */
+    sessionId: string;
+    /** sema axis — the principal scope the row belongs to. A reader filters by the ACCESSOR's scope
+     *  before anything else (the mechanical seat of the cross-principal wall). */
+    scope: string;
+    /** Display name (raw). Matching is on {@link normalizePeerName} of it, never on the raw string. */
+    name: string;
+    nameSource?: "auto" | "flag" | "rename";
+    formerNames?: readonly string[];
+    pid?: number;
+    /** Process start time (ms) — paired with `pid` against PID reuse. */
+    procStartMs?: number;
+    cwd?: string;
+    startedAt: number;
+    updatedAt: number;
+    liveness: PeerSessionLiveness;
+    /** Present iff `liveness !== "live"`: when the row was marked dead (or the tombstone was written). */
+    diedAt?: number;
+    tempo?: PeerSessionTempo;
+    entrypoint?: string;
+    peerProtocol?: number;
+    /** CC capability bits (`/^[a-z0-9_]{1,32}$/`, ≤16); `sema_mailbox_v1` marks a store-lane peer. */
+    peerFeatures?: readonly string[];
+    sockPath?: string;
+    /** CC `cross_session_inbound: available|unavailable` — the session's SELF-REPORTED inbound posture.
+     *  `"unavailable"` lets a sender refuse synchronously (degraded, best-effort); absent/stale means the
+     *  drain point decides. */
+    inboundPosture?: "available" | "unavailable";
+}
+/** 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.";
+/** The grammar, spelled for a refusal message. */
+export declare const PEER_SESSION_ID_GRAMMAR = "^[A-Za-z0-9_-]{1,80}$";
+/** Is this session id addressable on the peer lane (spellable as a `session.<id>` box handle)? The
+ *  lane mount asks this BEFORE binding a drain: a host-minted id outside the grammar refuses the lane
+ *  by name instead of throwing out of {@link peerSessionBoxHandle} mid-prepare. */
+export declare function isPeerSessionId(sessionId: string): boolean;
+/** The mailbox handle of a session's own box. Folded to lower case: both bundled backends key boxes
+ *  case-insensitively, and the address form is spelled lower-case. */
+export declare function peerSessionBoxHandle(sessionId: string): string;
+/** Is `text` spelled as an explicit session address? Returns the (lower-cased) session id, or
+ *  `undefined` when the text is not an address at all. An address is NEVER a name: the resolution
+ *  ladder ranks this arm beside the precise a* id, ahead of every name rung. */
+export declare function parsePeerSessionAddress(text: string): string | undefined;
+export type PeerSessionRecordRefusal = "not_an_object" | "schema_missing" | "schema_newer" | "session_id_invalid" | "scope_invalid" | "name_invalid" | "liveness_invalid" | "field_invalid";
+export type PeerSessionRecordRead = {
+    ok: true;
+    record: PeerSessionRecord;
+} | {
+    ok: false;
+    reason: PeerSessionRecordRefusal;
+    field?: string;
+};
+/**
+ * Validate one raw row (parsed JSON, a store row, a wire object) into a typed record — a DETACHED copy
+ * (only the declared members are carried; unknown keys are dropped, a newer schema is refused as
+ * `schema_newer`, a malformed member names its field). A reader SKIPS a refused row loudly (the host
+ * logs the reason) and never adopts a partial one — a half-typed row would let the resolver judge on
+ * fabricated liveness.
+ */
+export declare function readPeerSessionRecord(raw: unknown): PeerSessionRecordRead;
+/** What a liveness judgment needs from the OS — injectable so a test never has to spawn a process. */
+export interface PeerLivenessProbe {
+    /** Does a process with this pid exist (signal 0 semantics)? */
+    processExists(pid: number): boolean;
+    /** The process's start time in ms, or `undefined` when the platform cannot say. */
+    processStartMs?(pid: number): number | undefined;
+}
+/** The bundled probe: `process.kill(pid, 0)` for existence (EPERM counts as existing — a process this
+ *  uid may not signal is still a process), no start-time source (the host adapter supplies a platform
+ *  one; without it the start-time arm is skipped, which is the honest weaker judgment). */
+export declare const defaultPeerLivenessProbe: PeerLivenessProbe;
+/**
+ * Is the row's process alive? `false` when the pid is gone, OR when the probe knows a start time and it
+ * disagrees with the row's (PID reuse — a different process wears the number). A row with no pid has
+ * no process to probe and is judged by its declared liveness alone.
+ */
+export declare function isPeerSessionProcessAlive(record: Pick<PeerSessionRecord, "pid" | "procStartMs" | "liveness">, probe?: PeerLivenessProbe): boolean;
+export interface PeerDirectoryAccess {
+    /** The accessor's scope — rows of any other scope are never returned (§10 wall). */
+    scope: string;
+}
+/**
+ * The discovery contract (RunnerDeps `peerDirectory`; no seat = the cross-session lane is absent and
+ * every face of it stays byte-identical to a pre-385 build). ONE read face: every row the accessor may
+ * see — live, dead AND deleted — because the resolution set is the FULL set (a ref minted over the
+ * visible-only list would not be unique against a same-named dead row). The engine resolves over the
+ * returned rows with {@link resolvePeerSessions}; a host that can resolve server-side may still hand
+ * back the full list (the engine's ref minting needs it). Rows a host cannot vouch for (foreign owner,
+ * group/world-writable file, newer schema) are SKIPPED by the host's reader, never returned partially.
+ */
+export interface PeerDirectory {
+    listPeerSessions(access: PeerDirectoryAccess): readonly PeerSessionRecord[] | Promise<readonly PeerSessionRecord[]>;
+    /**
+     * design/385 §2.1 (the sweep race, send-side backstop) — restore a row ONLY IF ABSENT (CAS-on-absent:
+     * a live row a concurrent registration wrote is never overwritten). The sweep predicate (box empty ⇒
+     * remove the dead row) is not transactional with `append`: a sender can resolve a dead row, the sweep
+     * can remove it, the append then lands in a box no row addresses. The message is never lost (the
+     * recipient drains its box by its OWN session id, and re-registers its row on its next start); what
+     * breaks is NAME addressing until then — and this call closes that window: SendMessage re-reads the
+     * directory after every append and, when the target row is gone, restores the row it resolved.
+     * Optional: a directory that cannot write (a server session table the engine only reads) omits it,
+     * and the residual window is disclosed in the receipt instead.
+     */
+    restorePeerSession?(record: PeerSessionRecord): boolean | Promise<boolean>;
+}
+export interface PeerSessionCandidate {
+    record: PeerSessionRecord;
+    /** The listing-minted ref (6..12 hex) of this row — stable across the live/dead filter because it is
+     *  minted over the FULL set. */
+    ref: string;
+}
+export type PeerSessionResolution = {
+    status: "found";
+    candidate: PeerSessionCandidate;
+    rung: "address" | "name" | "ref";
+} | {
+    status: "deleted";
+    candidate: PeerSessionCandidate;
+} | {
+    status: "self";
+} | {
+    status: "ambiguous";
+    candidates: readonly PeerSessionCandidate[];
+    message: string;
+}
+/** A ref was supplied but matches no row of the current set (peer set moved on) — re-list. */
+ | {
+    status: "stale_ref";
+    ref: string;
+} | {
+    status: "not_found";
+};
+/** Mint refs for every row of the directory's full set (self participates in disambiguation). */
+export declare function mintPeerSessionCandidates(records: readonly PeerSessionRecord[], self?: {
+    sessionId: string;
+}): PeerSessionCandidate[];
+/**
+ * Resolve `to` against the directory's full set. Order (design/385 §2.2): an explicit `session.<id>`
+ * ADDRESS resolves directly (only to a KNOWN row — the phantom-box defense: an address nobody
+ * registered is `not_found`, never an append target); otherwise `name [ref]` — a ref must match its
+ * name's row exactly (a ref that resolves nowhere is `stale_ref`: "re-run ListAgents"); a bare name
+ * that matches ONE row (live or dead) resolves, several ⇒ `ambiguous` with every candidate's ref (the
+ * dead ones marked offline — CC's second ref source, the disambiguation error). A `deleted` row is
+ * returned as `deleted` on every rung so the caller refuses with `invalid_target`; the caller's own
+ * session is `self`.
+ */
+export declare function resolvePeerSessions(records: readonly PeerSessionRecord[], to: string, self?: {
+    sessionId: string;
+}): PeerSessionResolution;
+export interface InMemoryPeerDirectory extends PeerDirectory {
+    /** Write or replace a row (keyed by scope + sessionId). A name that spells an address is refused by
+     *  the caller's own `reservedPeerNameReason` check — this store trusts its writer. */
+    upsert(record: PeerSessionRecord): void;
+    /** §2.1 dead-row posture: mark, keep (the name stays resolvable for offline delivery). */
+    markDead(scope: string, sessionId: string, diedAt?: number): boolean;
+    /** §1.2⑤ tombstone: the deletion cascade flips the row BEFORE dropping the box. */
+    markDeleted(scope: string, sessionId: string, at?: number): boolean;
+    /** §2.1 sweep predicate: a non-live row is removable ONLY while its box is EMPTY (the box-empty
+     *  predicate is the caller's — it reads the mailbox). Returns the swept session ids. */
+    sweep(scope: string, boxEmpty: (sessionId: string) => boolean | Promise<boolean>): Promise<string[]>;
+    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. */
+export type PeerRegistryDirectoryRefusal = "not_absolute" | "missing" | "symlink" | "not_directory" | "foreign_owner" | "group_or_world_writable";
+export type PeerRegistryDirectoryVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    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). */
+export declare function vetPeerRegistryDirectory(dir: string, opts?: {
+    uid?: number;
+    stopAt?: string;
+}): Promise<PeerRegistryDirectoryVerdict>;
+/** §2.1 ③ — the read-side judgment on ONE registration file's stat facts (pure; the reader supplies
+ *  the stat): owner must be this uid, mode must carry no group/world write bit, and it must be a
+ *  regular file under the read cap. A refused file is skipped LOUDLY by the reader. */
+export declare function judgePeerRecordFile(stat: {
+    uid?: number;
+    mode: number;
+    isFile: boolean;
+    size: number;
+}, selfUid: number | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    code: "not_regular" | "foreign_owner" | "group_or_world_writable" | "too_large";
+};

package/dist/agents/peer-directory.js

@@ -0,0 +1,272 @@
+import { lstat } from "node:fs/promises";
+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";
+export const PEER_SESSION_RECORD_SCHEMA_VERSION = 1;
+export const PEER_SESSION_RECORD_MAX_BYTES = 262_144;
+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}$";
+export function isPeerSessionId(sessionId) {
+    return SESSION_ID_RE.test(sessionId);
+}
+const SESSION_ADDRESS_RE = /^session\.([A-Za-z0-9_-]{1,80})$/i;
+export function peerSessionBoxHandle(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId))
+        throw new Error(`peerSessionBoxHandle: session id ${JSON.stringify(sessionId)} is outside the address grammar ^[A-Za-z0-9_-]{1,80}$`);
+    return `${SESSION_BOX_PREFIX}${sessionId.toLowerCase()}`;
+}
+export function parsePeerSessionAddress(text) {
+    const m = SESSION_ADDRESS_RE.exec(text.trim());
+    return m === null ? undefined : m[1].toLowerCase();
+}
+function optNumber(v) {
+    return v === undefined || (typeof v === "number" && Number.isFinite(v));
+}
+function optString(v) {
+    return v === undefined || typeof v === "string";
+}
+function optStringArray(v) {
+    return v === undefined || (Array.isArray(v) && v.every((x) => typeof x === "string"));
+}
+export function readPeerSessionRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { ok: false, reason: "not_an_object" };
+    const r = raw;
+    if (typeof r["schemaVersion"] !== "number" || !Number.isInteger(r["schemaVersion"]) || r["schemaVersion"] < 1)
+        return { ok: false, reason: "schema_missing" };
+    if (r["schemaVersion"] > PEER_SESSION_RECORD_SCHEMA_VERSION)
+        return { ok: false, reason: "schema_newer" };
+    if (typeof r["sessionId"] !== "string" || !SESSION_ID_RE.test(r["sessionId"]))
+        return { ok: false, reason: "session_id_invalid" };
+    if (typeof r["scope"] !== "string" || r["scope"] === "")
+        return { ok: false, reason: "scope_invalid" };
+    if (typeof r["name"] !== "string" || normalizePeerName(r["name"]) === "")
+        return { ok: false, reason: "name_invalid" };
+    const liveness = r["liveness"];
+    if (liveness !== "live" && liveness !== "dead" && liveness !== "deleted")
+        return { ok: false, reason: "liveness_invalid" };
+    const bad = (field) => ({ ok: false, reason: "field_invalid", field });
+    if (!optNumber(r["startedAt"]) || r["startedAt"] === undefined)
+        return bad("startedAt");
+    if (!optNumber(r["updatedAt"]) || r["updatedAt"] === undefined)
+        return bad("updatedAt");
+    if (!optNumber(r["pid"]))
+        return bad("pid");
+    if (!optNumber(r["procStartMs"]))
+        return bad("procStartMs");
+    if (!optNumber(r["diedAt"]))
+        return bad("diedAt");
+    if (!optNumber(r["peerProtocol"]))
+        return bad("peerProtocol");
+    if (!optString(r["cwd"]))
+        return bad("cwd");
+    if (!optString(r["entrypoint"]))
+        return bad("entrypoint");
+    if (!optString(r["sockPath"]))
+        return bad("sockPath");
+    if (!optStringArray(r["formerNames"]))
+        return bad("formerNames");
+    if (!optStringArray(r["peerFeatures"]))
+        return bad("peerFeatures");
+    const nameSource = r["nameSource"];
+    if (nameSource !== undefined && nameSource !== "auto" && nameSource !== "flag" && nameSource !== "rename")
+        return bad("nameSource");
+    const tempo = r["tempo"];
+    if (tempo !== undefined && tempo !== "active" && tempo !== "idle" && tempo !== "blocked")
+        return bad("tempo");
+    const inboundPosture = r["inboundPosture"];
+    if (inboundPosture !== undefined && inboundPosture !== "available" && inboundPosture !== "unavailable")
+        return bad("inboundPosture");
+    const record = {
+        schemaVersion: r["schemaVersion"],
+        sessionId: r["sessionId"],
+        scope: r["scope"],
+        name: r["name"],
+        ...(nameSource !== undefined ? { nameSource } : {}),
+        ...(r["formerNames"] !== undefined ? { formerNames: [...r["formerNames"]] } : {}),
+        ...(r["pid"] !== undefined ? { pid: r["pid"] } : {}),
+        ...(r["procStartMs"] !== undefined ? { procStartMs: r["procStartMs"] } : {}),
+        ...(r["cwd"] !== undefined ? { cwd: r["cwd"] } : {}),
+        startedAt: r["startedAt"],
+        updatedAt: r["updatedAt"],
+        liveness,
+        ...(r["diedAt"] !== undefined ? { diedAt: r["diedAt"] } : {}),
+        ...(tempo !== undefined ? { tempo } : {}),
+        ...(r["entrypoint"] !== undefined ? { entrypoint: r["entrypoint"] } : {}),
+        ...(r["peerProtocol"] !== undefined ? { peerProtocol: r["peerProtocol"] } : {}),
+        ...(r["peerFeatures"] !== undefined ? { peerFeatures: [...r["peerFeatures"]] } : {}),
+        ...(r["sockPath"] !== undefined ? { sockPath: r["sockPath"] } : {}),
+        ...(inboundPosture !== undefined ? { inboundPosture } : {}),
+    };
+    return { ok: true, record };
+}
+export const defaultPeerLivenessProbe = {
+    processExists(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM";
+        }
+    },
+};
+export function isPeerSessionProcessAlive(record, probe = defaultPeerLivenessProbe) {
+    if (record.liveness !== "live")
+        return false;
+    if (record.pid === undefined)
+        return true;
+    if (!probe.processExists(record.pid))
+        return false;
+    if (record.procStartMs !== undefined && probe.processStartMs !== undefined) {
+        const started = probe.processStartMs(record.pid);
+        if (started !== undefined && Math.abs(started - record.procStartMs) > 2_000)
+            return false;
+    }
+    return true;
+}
+export function mintPeerSessionCandidates(records, self) {
+    const entries = records.map((record) => ({ kind: "session", id: record.sessionId.toLowerCase(), record }));
+    const selfEntry = self !== undefined && !records.some((r) => r.sessionId.toLowerCase() === self.sessionId.toLowerCase()) ? { kind: "session", id: self.sessionId.toLowerCase() } : undefined;
+    return mintPeerRef(entries, selfEntry).map((e) => ({ record: e.record, ref: e.ref }));
+}
+function describeCandidate(c) {
+    const state = c.record.liveness === "live" ? "" : c.record.liveness === "dead" ? " (offline)" : " (deleted)";
+    return `${formatPeerNameRef(inlineUntrusted(c.record.name, 64), c.ref)}${state} → ${peerSessionBoxHandle(c.record.sessionId)}`;
+}
+export function resolvePeerSessions(records, to, self) {
+    const candidates = mintPeerSessionCandidates(records, self);
+    const selfId = self?.sessionId.toLowerCase();
+    const settle = (c, rung) => {
+        if (selfId !== undefined && c.record.sessionId.toLowerCase() === selfId)
+            return { status: "self" };
+        if (c.record.liveness === "deleted")
+            return { status: "deleted", candidate: c };
+        return { status: "found", candidate: c, rung };
+    };
+    const address = parsePeerSessionAddress(to);
+    if (address !== undefined) {
+        if (selfId !== undefined && address === selfId)
+            return { status: "self" };
+        const hit = candidates.find((c) => c.record.sessionId.toLowerCase() === address);
+        return hit === undefined ? { status: "not_found" } : settle(hit, "address");
+    }
+    const nameRef = parsePeerNameRef(to);
+    const rawName = nameRef?.name ?? to;
+    const key = normalizePeerName(rawName);
+    if (key === "")
+        return { status: "not_found" };
+    const byName = candidates.filter((c) => normalizePeerName(c.record.name) === key);
+    if (nameRef !== undefined) {
+        const hit = byName.find((c) => c.ref === nameRef.ref) ?? (PEER_REF_RE.test(nameRef.ref) ? candidates.find((c) => c.ref === nameRef.ref && normalizePeerName(c.record.name) === key) : undefined);
+        if (hit === undefined)
+            return { status: "stale_ref", ref: nameRef.ref };
+        return settle(hit, "ref");
+    }
+    if (byName.length === 0)
+        return { status: "not_found" };
+    if (byName.length === 1)
+        return settle(byName[0], "name");
+    const sorted = [...byName].sort((a, b) => (a.record.liveness === b.record.liveness ? b.record.updatedAt - a.record.updatedAt : a.record.liveness === "live" ? -1 : 1));
+    return {
+        status: "ambiguous",
+        candidates: sorted,
+        message: `"${inlineUntrusted(rawName, 64)}" matches ${sorted.length} sessions — re-send with the name and ref of the one you mean: ${sorted.map(describeCandidate).join("; ")}`,
+    };
+}
+export function createInMemoryPeerDirectory() {
+    const rows = new Map();
+    const key = (scope, sessionId) => JSON.stringify([scope, sessionId.toLowerCase()]);
+    return {
+        listPeerSessions(access) {
+            return [...rows.values()].filter((r) => r.scope === access.scope).map((r) => ({ ...r }));
+        },
+        upsert(record) {
+            const read = readPeerSessionRecord(record);
+            if (!read.ok)
+                throw new Error(`InMemoryPeerDirectory.upsert: refused row (${read.reason}${read.field !== undefined ? `: ${read.field}` : ""})`);
+            rows.set(key(record.scope, record.sessionId), read.record);
+        },
+        markDead(scope, sessionId, diedAt = Date.now()) {
+            const r = rows.get(key(scope, sessionId));
+            if (r === undefined || r.liveness !== "live")
+                return false;
+            rows.set(key(scope, sessionId), { ...r, liveness: "dead", diedAt, updatedAt: diedAt });
+            return true;
+        },
+        markDeleted(scope, sessionId, at = Date.now()) {
+            const r = rows.get(key(scope, sessionId));
+            if (r === undefined)
+                return false;
+            rows.set(key(scope, sessionId), { ...r, liveness: "deleted", diedAt: r.diedAt ?? at, updatedAt: at });
+            return true;
+        },
+        restorePeerSession(record) {
+            const k = key(record.scope, record.sessionId);
+            if (rows.has(k))
+                return false;
+            const read = readPeerSessionRecord(record);
+            if (!read.ok)
+                return false;
+            rows.set(k, read.record);
+            return true;
+        },
+        async sweep(scope, boxEmpty) {
+            const swept = [];
+            for (const [k, r] of [...rows.entries()]) {
+                if (r.scope !== scope || r.liveness === "live")
+                    continue;
+                if (await boxEmpty(r.sessionId)) {
+                    if (rows.get(k) !== r)
+                        continue;
+                    rows.delete(k);
+                    swept.push(r.sessionId);
+                }
+            }
+            return swept;
+        },
+    };
+}
+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 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)
+                return { ok: false, code: "foreign_owner", path: cursor };
+            if ((st.mode & 0o022) !== 0)
+                return { ok: false, code: "group_or_world_writable", path: cursor };
+        }
+        if (isRoot)
+            return { ok: true };
+        cursor = parent;
+    }
+}
+export function judgePeerRecordFile(stat, selfUid) {
+    if (!stat.isFile)
+        return { ok: false, code: "not_regular" };
+    if (selfUid !== undefined && stat.uid !== undefined && stat.uid !== selfUid)
+        return { ok: false, code: "foreign_owner" };
+    if ((stat.mode & 0o022) !== 0)
+        return { ok: false, code: "group_or_world_writable" };
+    if (stat.size > PEER_SESSION_RECORD_MAX_BYTES)
+        return { ok: false, code: "too_large" };
+    return { ok: true };
+}

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

@@ -0,0 +1,159 @@
+import { type MailboxCrossProcessVerdict, type MailboxStore } from "../core/mailbox-store.js";
+import type { SystemInjectionPriority, TaskNotificationPayload } from "../core/task-notification.js";
+import { type EngineNotice, type RunnerDeps } from "../core/types.js";
+import { type PermissionModeClass } from "./cross-session-envelope.js";
+import { type CrossSessionInboundSettingLayers } from "./cross-session-judge.js";
+import { type PeerAdmissionConfig } from "./peer-admission.js";
+import { type PeerDirectory } from "./peer-directory.js";
+import { createListAgentsTool } from "./list-agents-tool.js";
+import type { AskEffective } from "../core/wiring-manifest.js";
+import type { SendMessageToolOptions } from "./send-message-tool.js";
+/** design/385 §1.2④ — the drain lease TTL. Same sizing law as the tier-3 revive lease: well under the
+ *  store's stale-row floor, long enough to cover one turn (a longer turn renews on the same owner at
+ *  its next boundary; an expired lease re-serves the batch — at-least-once). */
+export declare const PEER_DRAIN_LEASE_TTL_MS: number;
+/** The lane-mount refusal for a run whose own session id cannot be spelled as a peer address. */
+export declare const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
+/** The lane's mount verdict: the mailbox declaration's verdict, or this leg's own address refusal. */
+export type PeerLaneMountVerdict = MailboxCrossProcessVerdict | {
+    ok: false;
+    code: typeof PEER_SESSION_ID_UNGRAMMATICAL_CODE;
+    reason: string;
+};
+/**
+ * design/385 §1.2⑥ / §5.1 — may the cross-session lane mount on this deployment? `undefined` = no
+ * directory seat (no lane, nothing to say). A directory with no mailbox, or over a mailbox that does not
+ * declare cross-process safety, is REFUSED with a named reason (bad-value loudness: several terminals
+ * sharing one box on luck is exactly what the declaration exists to forbid). With a `sessionId`, the
+ * leg's OWN address is judged too: a host-minted session id outside the peer address grammar has no
+ * session box to drain and no address a peer could send to, so the lane refuses by name — the
+ * alternative was `peerSessionBoxHandle` throwing out of prepare and failing the whole run over an
+ * optional feature.
+ */
+export declare function judgePeerLaneMount(deps: {
+    peerDirectory?: PeerDirectory;
+    mailboxStore?: MailboxStore;
+}, sessionId?: string): PeerLaneMountVerdict | undefined;
+export interface PeerSessionDrainOptions {
+    mailbox: MailboxStore;
+    /** This session (the box owner) and this leg's cycle id (the lease owner). */
+    sessionId: string;
+    runId: string;
+    /** The registry/mailbox scope this run mounts in. */
+    scope: string;
+    /** The run's own notification injector (the task-notification lane; `next` tier). */
+    inject: (notification: TaskNotificationPayload, opts?: {
+        priority?: SystemInjectionPriority;
+    }) => void;
+    /** Deployment tuning of the admission gate (the same seat SendMessage reads). */
+    admission?: Partial<PeerAdmissionConfig>;
+    /** The recipient's self-token set for the hop check, read live (the run's peer identity ref). */
+    ownTokens: () => readonly string[];
+    /** The recipient's `crossSessionInbound` layers, read at every drain. */
+    settingLayers: () => CrossSessionInboundSettingLayers | undefined;
+    /** The recipient's own permission-mode class, read at every drain (the manifest's ask fold). */
+    selfModeClass: () => PermissionModeClass | "unknown";
+    onNotice?: (notice: EngineNotice) => void;
+    onError?: (error: unknown, ctx: {
+        phase: "degraded";
+        sessionId: string;
+        classification: string;
+    }) => void;
+    leaseTtlMs?: number;
+}
+export interface PeerSessionDrain {
+    /** One drain round (serialized: a boundary never overlaps a still-running round). */
+    drain(): Promise<void>;
+    /** Run end: ack the last batch and release the lease so the session's next cycle claims at once. */
+    finish(): Promise<void>;
+}
+export declare function createPeerSessionDrain(opts: PeerSessionDrainOptions): PeerSessionDrain;
+/** The lane's late-bound facts: the ask fold resolves after the manifest derivation, the mount runs
+ *  before it — both read this one cell. */
+export interface PeerLaneRefs {
+    askEffective?: AskEffective;
+}
+/**
+ * The mount verdict + its loud half: `true` = the lane mounts on this leg; `false` = no seat, or the
+ * seat was refused — the refusal is announced ONCE per leg as `config.peer_lane_unmounted` naming the
+ * reason (never mounted on luck, never silently inert).
+ */
+export declare function announcePeerLaneMount(deps: {
+    peerDirectory?: PeerDirectory;
+    mailboxStore?: MailboxStore;
+    onNotice?: (n: EngineNotice) => void;
+}, leg: {
+    sessionId: string;
+    runId: string;
+}): boolean;
+/** The SendMessage seats of the lane (design/385 §2): the directory (address arm + last name rung) and
+ *  this session's identity/attestation, whose mode class folds LIVE off the manifest's ask derivation. */
+export declare function peerLaneSendMessageSeats(args: {
+    peerDirectory: PeerDirectory;
+    sessionId: string;
+    scope: string;
+    name?: string;
+    refs: PeerLaneRefs;
+    listingMounted?: boolean;
+}): Pick<SendMessageToolOptions, "peerDirectory" | "peerSelfSession" | "peerListingMounted">;
+/**
+ * design/385 §5.1 — THE ListAgents mount predicate, single source: the built-in mounts only when the
+ * face does not exclude it and no caller tool owns either spelling (`ListAgents` / `ListPeers`) as its
+ * name OR as an alias. Every reader of "is ListAgents on this roster?" — the mount itself and the
+ * SendMessage face's listing phrase — calls this one predicate, so a face can never name a tool the
+ * roster does not carry (a second, inline copy of the rule drifted on exactly the alias arms).
+ */
+export declare function listAgentsMountable(face: {
+    exclude: readonly string[] | undefined;
+    specTools: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+    }>;
+}): boolean;
+/** design/385 §5.1 — the ListAgents mount (alias ListPeers): read-only, concurrency-safe, on the peer
+ *  seat's own arm beside SendMessage; a caller-supplied tool of the same name wins (skip, not throw). */
+export declare function mountListAgents(args: {
+    peerDirectory: PeerDirectory;
+    sessionId: string;
+    scope: string;
+    hostTaskId: string;
+    /** The delegated child's trusted parent pair (RunInternals), when this run is a child. */
+    parentTaskId?: string;
+    parentSessionId?: string;
+    registry: ListAgentsToolRegistry;
+    roster?: NonNullable<Parameters<typeof createListAgentsTool>[0]["roster"]>;
+    specTools: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+    }>;
+    toolEffects: Map<string, "read" | "write" | "idempotent">;
+}): ReturnType<typeof createListAgentsTool> | undefined;
+type ListAgentsToolRegistry = NonNullable<Parameters<typeof createListAgentsTool>[0]["registry"]>;
+/** The harness surface the binding needs (structural — the machine itself never sees the harness). */
+export interface PeerDrainHarness {
+    on(type: "turn_boundary" | "before_agent_start", handler: () => Promise<undefined>): unknown;
+    subscribe(listener: (event: {
+        type: string;
+    }) => void | Promise<void>): unknown;
+}
+/**
+ * Bind the drain to a leg: the run's own injector at the `next` tier, run open (the loop's first
+ * steering drain follows the `before_agent_start` hook) + every turn boundary, and the run-end
+ * ack/release on `agent_end`.
+ */
+export declare function bindPeerSessionDrain(harness: PeerDrainHarness, opts: PeerSessionDrainOptions): PeerSessionDrain;
+/**
+ * The leg-side spelling of {@link bindPeerSessionDrain}: the deployment seats the drain reads
+ * (`mailboxStore` / `peerAdmission` / `crossSessionInbound` / the two sinks) come straight off deps, the
+ * recipient's mode class folds off the lane refs — one binding call per leg, no per-seat plumbing.
+ */
+export declare function bindPeerLaneDrain(harness: PeerDrainHarness, args: {
+    deps: Pick<RunnerDeps, "mailboxStore" | "peerAdmission" | "crossSessionInbound" | "onNotice" | "onError">;
+    sessionId: string;
+    runId: string;
+    scope: string;
+    inject: PeerSessionDrainOptions["inject"];
+    ownTokens: () => readonly string[];
+    refs: PeerLaneRefs;
+}): PeerSessionDrain;
+export {};