@sema-agent/core 7.2.0 → 7.3.1

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
+import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
 export const MAILBOX_CONTRACT_SCOPE = "default";
 const msg = (content, sentAt = 1000) => ({ content, sentAt });
@@ -112,6 +112,75 @@ export async function mailboxStoreContract(mk, runAssertion) {
         const after = await s.claimLease(S, "a1", "rival", 60_000, 12_000);
         assert.deepEqual(after?.messages.map((m) => m.seq), [1], "归还后同一条按原 seq 回可见");
     });
+    run("peerMeta 回环:典型 typed 记录逐字节回读;缺席保持缺席(pre-385/foreign 记录语义);空对象也是「在场」", async (make) => {
+        const s = make();
+        const full = {
+            fromSession: "sess_1",
+            fromMode: "prompting",
+            senderKey: "k-1",
+            kind: "peer_message",
+            fromScope: "team/a b",
+            gateReceiptId: "gr-9",
+        };
+        await s.append(S, "a1", { content: "typed", sentAt: 1_000, peerMeta: full });
+        await s.append(S, "a1", { content: "plain", sentAt: 1_001 });
+        await s.append(S, "a1", { content: "empty-meta", sentAt: 1_002, peerMeta: {} });
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.content), ["typed", "plain", "empty-meta"]);
+        assert.deepEqual(lease.messages[0].peerMeta, full, "六字段逐字节回读");
+        assert.equal("peerMeta" in lease.messages[1], false, "未带 peerMeta 的记录回读时该键必须缺席(不是 undefined 值)");
+        assert.deepEqual(lease.messages[2].peerMeta, {}, "空对象=在场但无字段,与缺席区分");
+    });
+    run("peerMeta 坏值响亮:garbage 以具名码拒 append,且零副作用(不入箱、不耗 seq、不动租约)", async (make) => {
+        const s = make();
+        const seqBefore = await s.append(S, "a1", { content: "anchor", sentAt: 1_000 });
+        const held = await s.claimLease(S, "a1", "holder", 60_000, 10_000);
+        assert.equal(held?.messages.length, 1);
+        const codeOf = (e) => e?.code;
+        class Meta {
+            fromSession = "s";
+        }
+        const hiddenKey = { fromSession: "s" };
+        Object.defineProperty(hiddenKey, "bogus", { value: 1, enumerable: false });
+        for (const [label, bad] of [
+            ["fromMode 集外值", { fromMode: "root" }],
+            ["kind 集外值", { kind: "gossip" }],
+            ["未知键", { fromSession: "s", bogus: 1 }],
+            ["空字符串", { senderKey: "" }],
+            ["非字符串", { gateReceiptId: 7 }],
+            ["数组", ["fromSession"]],
+            ["null", null],
+            ["字符串", "fromSession=x"],
+            ["Date", new Date(0)],
+            ["Map", new Map()],
+            ["class 实例", new Meta()],
+            ["symbol 键", { fromSession: "s", [Symbol("hidden")]: 1 }],
+            ["不可枚举的未知键", hiddenKey],
+        ]) {
+            let thrown;
+            try {
+                await s.append(S, "a1", { content: `bad:${label}`, sentAt: 2_000, peerMeta: bad });
+            }
+            catch (e) {
+                thrown = e;
+            }
+            assert.notEqual(thrown, undefined, `${label}:必须拒`);
+            assert.equal(codeOf(thrown), MAILBOX_INVALID_PEER_META_CODE, `${label}:拒必须带码`);
+        }
+        assert.equal(await s.peekCount(S, "a1"), 1, "被拒的 append 不得入箱");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "被拒的 append 不得动活租约");
+        await s.ack(S, "a1", "holder", held.maxSeq);
+        assert.equal(await s.append(S, "a1", { content: "next", sentAt: 3_000 }), seqBefore + 1, "被拒的 append 不得消耗 seq");
+    });
+    run("peerMeta 不串引用:消费者改写租约批里的 peerMeta,不得改到下次投递的记录", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1_000, peerMeta: { fromMode: "bypass", fromSession: "sess_1" } });
+        const first = await s.claimLease(S, "a1", "w1", 1_000, 10_000);
+        first.messages[0].peerMeta.fromSession = "forged";
+        await s.releaseLease(S, "a1", "w1");
+        const again = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
+        assert.deepEqual(again.messages[0].peerMeta, { fromMode: "bypass", fromSession: "sess_1" }, "重投的记录必须是原样");
+    });
     await settle();
 }
 export async function mailboxAckOwnershipContract(mk, runAssertion) {
@@ -192,6 +261,93 @@ export async function mailboxBundledOnlyContract(mk, runAssertion) {
     });
     await settle();
 }
+export async function mailboxCrossProcessContract(hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const run = (name, fn) => runRaw(name, async () => {
+        const pair = await hooks.openPair();
+        try {
+            await fn(pair.local, pair.peer);
+        }
+        finally {
+            await pair.dispose();
+        }
+    });
+    const S = MAILBOX_CONTRACT_SCOPE;
+    const H = "session.shared";
+    const range = (n) => Array.from({ length: n }, (_, i) => i + 1);
+    run("跨进程 seq 单铸:两个进程交错 append N+N ⇒ seq 恰为 1..2N(无重复无空洞),每条消息在任一方视角都可见", async (local, peer) => {
+        const N = 40;
+        const seqs = [];
+        for (let i = 0; i < N; i++) {
+            const [a, b] = await Promise.all([local.append(S, H, msg(`local-${i}`, 1_000 + i)), peer.append(S, H, msg(`peer-${i}`, 2_000 + i))]);
+            seqs.push(a, b);
+        }
+        assert.deepEqual([...seqs].sort((x, y) => x - y), range(2 * N), "两方拿到的回执合起来必须恰是 1..2N");
+        assert.equal(await peer.peekCount(S, H), 2 * N, "对方进程的观察面必须看到本方的 append");
+        assert.equal(await local.peekCount(S, H), 2 * N);
+        const lease = await local.claimLease(S, H, "cycle-1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.seq), range(2 * N), "本方 claim 必须按 seq 序取到全部 2N 条");
+        assert.equal(lease.maxSeq, 2 * N);
+        const contents = new Set(lease.messages.map((m) => m.content));
+        for (let i = 0; i < N; i++) {
+            assert.ok(contents.has(`local-${i}`), `local-${i} 不得丢`);
+            assert.ok(contents.has(`peer-${i}`), `peer-${i} 不得丢`);
+        }
+    });
+    run("lease/ack 不跨进程交叉:一方的活租约 fence 住另一方的 claim;非持有方的 ack 是 no-op;持有方的 ack 对另一方立即可见;高水位跨对方的 ack 存活", async (local, peer) => {
+        await local.append(S, H, msg("m1", 1));
+        await peer.append(S, H, msg("m2", 2));
+        const held = await peer.claimLease(S, H, "cycle-peer", 60_000, 10_000);
+        assert.deepEqual(held.messages.map((m) => m.seq), [1, 2]);
+        assert.equal(await local.claimLease(S, H, "cycle-local", 60_000, 11_000), null, "对方进程的活租约必须 fence 住本方");
+        await local.ack(S, H, "cycle-local", held.maxSeq);
+        assert.equal(await peer.peekCount(S, H), 2, "非持有方的 ack 不得动持有方手上的批");
+        await peer.ack(S, H, "cycle-peer", held.maxSeq);
+        assert.equal(await local.peekCount(S, H), 0, "持有方的 ack 必须被本方看见");
+        assert.equal(await local.claimLease(S, H, "cycle-local", 60_000, 12_000), null);
+        assert.equal(await local.append(S, H, msg("m3", 3)), 3, "seq 高水位必须跨对方进程的 ack 存活(永不复用)");
+        await peer.append(S, H, msg("m4", 4));
+        const held2 = await peer.claimLease(S, H, "cycle-peer-2", 1_000, 20_000);
+        assert.deepEqual(held2.messages.map((m) => m.seq), [3, 4]);
+        const takeover = await local.claimLease(S, H, "cycle-local-2", 60_000, 30_000);
+        assert.deepEqual(takeover.messages.map((m) => m.seq), [3, 4], "过期租约的接管跨进程成立,seq 原样");
+    });
+    run("一方的 housekeeping 不丢另一方的 append:两进程各自反复压缩/重写期间交错写入 120 条,任一方视角都完整", async (local, peer) => {
+        const N = 60;
+        for (let i = 0; i < N; i++) {
+            await Promise.all([local.append(S, H, msg(`L${i}`, 1_000 + i)), peer.append(S, H, msg(`P${i}`, 2_000 + i))]);
+        }
+        const fromPeer = await peer.claimLease(S, H, "cycle-peer", 60_000, 10_000);
+        assert.deepEqual(fromPeer.messages.map((m) => m.seq), range(2 * N), "对方视角:seq 1..2N 全在");
+        await peer.releaseLease(S, H, "cycle-peer");
+        const fromLocal = await local.claimLease(S, H, "cycle-local", 60_000, 11_000);
+        assert.deepEqual(fromLocal.messages.map((m) => m.seq), range(2 * N), "本方视角:seq 1..2N 全在");
+        const contents = fromLocal.messages.map((m) => m.content).sort();
+        assert.deepEqual(contents, [...range(N).map((i) => `L${i - 1}`), ...range(N).map((i) => `P${i - 1}`)].sort());
+        await local.ack(S, H, "cycle-local", fromLocal.maxSeq);
+        assert.equal(await peer.peekCount(S, H), 0, "本方的 ack 对方可见");
+    });
+    run("reap 看得见对方进程的旧消息,哪怕本方缓存里这个箱是空的(已加载的空缓存不得替对方的旧消息说「没有」)", async (local, peer) => {
+        await local.append(S, H, msg("mine", 1_000));
+        const held = await local.claimLease(S, H, "cycle-local", 60_000, 1_000);
+        await local.ack(S, H, "cycle-local", held.maxSeq);
+        await peer.append(S, H, msg("old-from-peer", 2_000));
+        assert.equal(await local.reap(S, 100_000, { maxAgeMs: 50_000 }), 1, "对方写的过期消息必须被本方 reap 看见并老化");
+        assert.equal(await peer.peekCount(S, H), 0);
+        assert.equal(await peer.append(S, H, msg("after", 200_000)), 3, "高水位跨 reap 存活(对方视角)");
+    });
+    run("reap 与 drop 的 seq 语义跨进程:一方 reap 后另一方继续高水位;一方 drop 后另一方从 1 重铸", async (local, peer) => {
+        await peer.append(S, H, msg("old", 1_000));
+        assert.equal(await local.reap(S, 100_000, { maxAgeMs: 50_000 }), 1, "本方 reap 必须看见对方写的旧消息");
+        assert.equal(await peer.peekCount(S, H), 0);
+        assert.equal(await peer.append(S, H, msg("after-reap", 200_000)), 2, "reap 清箱但保高水位(RB-90 跨进程)");
+        await local.drop(S, H);
+        assert.equal(await peer.peekCount(S, H), 0, "本方 drop 对方可见");
+        assert.equal(await peer.append(S, H, msg("after-drop", 300_000)), 1, "drop 结束箱的一生:对方从 1 重铸");
+        assert.equal(await local.peekCount(S, H), 1);
+    });
+    await settle();
+}
 export async function mailboxTombstonedRecipientContract(mk, hooks) {
     const { run: runRaw, settle } = beginContract(hooks.runAssertion);
     const run = (name, fn) => runRaw(name, () => withStores(mk, fn));

package/dist/core/task-notification.d.ts

@@ -155,23 +155,45 @@ export interface TaskNotificationPayload {
         body: string;
     };
     /**
-     * design/385 §1.4 d1 — the engine-minted PROVENANCE side record of an agent-message frame, a typed
-     * key (never model text) so a host can attribute and correlate the injection on the wire:
-     * `kind` names the lane, `from` is the sender label the frame's attribute spells, `taskId` the
-     * sender's run/agent id, `seq` the producer's per-frame counter (= this payload's `seq`),
-     * `agentType` the sender's resolved agent type when the producer knows it. Present exactly when
-     * {@link agentMessage} is.
+     * design/385 §4.1 — the CROSS-SESSION carrier (a peer session's message drained from this session's
+     * own box). Its PRESENCE is the render discriminator: the model reads a top-level
+     * `<cross-session-message from="…" …>` envelope (design/385 §4.2 model-face codec — from-session /
+     * from-name / from-mode / from-scope as the typed record carried them; the hop chain never appears)
+     * followed by the cross-session discipline block, never a `<task-notification>` shell. The
+     * attributes are a PROJECTION of the store record's typed `peerMeta` — the text is presentation,
+     * the typed side record ({@link _sema_provenance}) is the authority. Minted ONLY by the engine's
+     * session-box drain; an external `notify()` cannot wear it.
+     */
+    crossSessionMessage?: import("../agents/cross-session-envelope.js").CrossSessionEnvelopeFields & {
+        body: string;
+    };
+    /**
+     * design/385 §1.4 d1 / §4.1 — the engine-minted PROVENANCE side record of an engine-injected peer
+     * frame, a typed key (never model text) so a host can attribute and correlate the injection on the
+     * wire. Present exactly when {@link agentMessage} OR {@link crossSessionMessage} is — one record
+     * per carrier, `kind` naming which. Its fields are read per `kind` (see {@link SemaProvenance}):
+     * on the agent-message lane `from` is the sender label the frame's attribute spells, `taskId` the
+     * sender's run/agent id, `seq` the producer's per-frame counter (= this payload's `seq`) and
+     * `agentType` the sender's resolved agent type when the producer knows it; on the cross-session
+     * lane `from` is the sender's ADDRESS, `taskId` the recipient's own box handle, `seq` the box seq,
+     * and the typed peer record rides in `peerMeta`.
      */
     _sema_provenance?: SemaProvenance;
 }
-/** design/385 §1.4 d1 — see {@link TaskNotificationPayload._sema_provenance}. `kind` is a closed set
- *  with one member today; a future lane adds a member, never a second key. */
+/** design/385 §1.4 d1 / §4.1 — see {@link TaskNotificationPayload._sema_provenance}. `kind` is a
+ *  closed set of the two engine lanes that mint the record; a future lane adds a member, never a
+ *  second key. */
 export interface SemaProvenance {
-    kind: "agent_message";
+    /** `agent_message` = the same-process uplink (§1.4 d1); `cross_session_message` = the session-box
+     *  drain (§4.1) — `from` is then the sender's ADDRESS, `taskId` the recipient's own box handle,
+     *  `seq` the box seq, and the typed peer record rides in `peerMeta`. */
+    kind: "agent_message" | "cross_session_message";
     from: string;
     taskId: string;
     seq: number;
     agentType?: string;
+    /** cross_session_message only — the store record's typed peer metadata, verbatim (authority). */
+    peerMeta?: import("./mailbox-store.js").MailboxPeerMeta;
 }
 /**
  * design/144 §2 — the caller-facing input of `TaskStream.notify()`: a STRUCTURED external event to inject
@@ -278,6 +300,13 @@ export declare function renderAgentMessageFrame(frame: {
     from: string;
     body: string;
 }): string;
+/**
+ * design/385 §4.1 — render a drained peer-session message as the model-face envelope (the §4.2
+ * codec: canonical attribute order, neutralized body) followed by the cross-session discipline block
+ * OUTSIDE the envelope. Distinct from {@link renderAgentMessageFrame}: another lane, another trust
+ * level, another block — sharing either would blur the classifier's lane judgment.
+ */
+export declare function renderCrossSessionMessageFrame(frame: NonNullable<TaskNotificationPayload["crossSessionMessage"]>): string;
 export declare function renderTaskNotificationXml(n: TaskNotificationPayload): string;
 /**
  * The BETWEEN-TURNS pending lane. A task notification born while NO turn is

package/dist/core/task-notification.js

@@ -1,6 +1,6 @@
 import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
-import { neutralizePeerBody } from "../agents/cross-session-envelope.js";
+import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
 export const SYSTEM_INJECTION_PRIORITIES = ["now", "next", "later"];
 export function isSystemInjectionPriority(value) {
     return typeof value === "string" && SYSTEM_INJECTION_PRIORITIES.includes(value);
@@ -53,9 +53,15 @@ export function renderAgentMessageFrame(frame) {
     const body = escapeEnvelopeTag(AGENT_MESSAGE_TAG, neutralizePeerBody(frame.body));
     return `<${AGENT_MESSAGE_TAG} from="${attrEscape(frame.from)}">\n${body}\n</${AGENT_MESSAGE_TAG}>\n\n${PEER_MESSAGE_NOTICE}`;
 }
+export function renderCrossSessionMessageFrame(frame) {
+    const { body, ...fields } = frame;
+    return `${buildCrossSessionEnvelope(fields, body)}\n\n${CROSS_SESSION_MESSAGE_NOTICE}`;
+}
 export function renderTaskNotificationXml(n) {
     if (n.agentMessage !== undefined)
         return renderAgentMessageFrame(n.agentMessage);
+    if (n.crossSessionMessage !== undefined)
+        return renderCrossSessionMessageFrame(n.crossSessionMessage);
     const usage = n.usage === undefined
         ? undefined
         : (() => {
@@ -211,7 +217,7 @@ export function discloseDroppedPending(drained) {
         if (dropped === undefined || disclosed.has(lane))
             return [n];
         disclosed.add(lane);
-        if (n.agentMessage !== undefined) {
+        if (n.agentMessage !== undefined || n.crossSessionMessage !== undefined) {
             const line = {
                 task_id: n.task_id,
                 task_type: n.task_type,

package/dist/core/tools.js

@@ -55,6 +55,7 @@ export function defineTool(spec, options) {
         ...(spec.alwaysLoad !== undefined ? { alwaysLoad: spec.alwaysLoad } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
+        ...(spec.validateInput ? { validateInput: spec.validateInput } : {}),
         execute: async (toolCallId, rawParams, signal) => {
             const params = spec.prepareArguments ? spec.prepareArguments(rawParams) : rawParams;
             if (!Value.Check(spec.parameters, params)) {

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { AgentTool, ThinkingLevel } from "../internal/harness.js";
+import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict } from "../internal/harness.js";
 import type { ActorAssertion, CompleteSimpleFn, DocumentContent, ImageContent, Model, ResilienceOptions, StreamFn, TextContent } from "../internal/llm.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 /** A model reference: either a fully-formed Model, or a `"provider/id"` ref resolved via a catalog. */
@@ -241,6 +241,24 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     /** approval display projection (see AgentTool.approvalPreview): pure args→display value
      *  for human approval surfaces; clamped + throw-swallowed by the gate; never adjudication input. */
     approvalPreview?: (args: unknown) => unknown;
+    /**
+     * OPTIONAL input pre-validation — runs BEFORE the permission ask (and before every other tool-call
+     * gate station: PreToolUse hooks, policy, the auto-mode classifier), AFTER schema validation. A
+     * refusal (`{ ok: false, message }`) is returned to the model as a typed error result and NO
+     * approval card is shown for the call; `{ ok: true }` / `undefined` lets the call proceed to the
+     * gate unchanged. Upstream form (CC 2.1.250 `validateInput` → `{result:false, message, errorCode}`,
+     * consulted ahead of the permission prompt): a call the tool would refuse on its own precondition —
+     * an Edit/Write/NotebookEdit whose target file was never Read this session — used to reach the
+     * operator as a card that could only ever fail; the model then retried the same failing call under
+     * auto mode until the turn cap. A validator MUST be pure (read tracking state, path grammar; no
+     * side effects, no writes, nothing the run observes) and MUST refuse with the SAME text its
+     * execution would have produced for that input, so the model sees one refusal either way. A
+     * validator that THROWS is read as "no verdict": the call proceeds to the gate and the fault is
+     * disclosed via `RunnerDeps.onError` (phase `"hook"`) — a broken validator must not refuse tools.
+     * The execution-time check stays in place (validate and execute are two reads; a direct
+     * `AgentTool.execute` caller — durable replay — never passes this seat).
+     */
+    validateInput?: (args: unknown, ctx: ToolInputValidationContext) => Promise<ToolInputVerdict | undefined> | ToolInputVerdict | undefined;
     /**
      * [c209-C] Q4 — the model catalog names (`SubagentToolOptions.models` keys), filled by
      * `createSubagentTool` alongside {@link agentListing}. Rendered as the agent_listing INITIAL frame's
@@ -1032,7 +1050,8 @@ export interface ToolExecuteContext {
     } | undefined;
     /**
      * RB-201 FO-3 (form-one audit, CC 220 `Ipd`/`ein` parity) — the auto-mode classifier decider ARMED
-     * for THIS task (`RuntimeCaps.autoMode === true` AND `RunnerDeps.autoMode` both present; the same
+     * for THIS task (auto-mode intent ∧ `RunnerDeps.autoMode` present ∧ `RuntimeCaps.autoMode !== false`
+     * — see {@link TaskSpec.autoModeRequested}; the same
      * instance `runToolGate`'s per-call ask review already consults, carrying its own live breaker
      * state — not a fresh one built from raw config). Runner-filled, trusted, undefined when auto-mode
      * is not armed or the tool runs outside a Runner task.
@@ -2608,6 +2627,35 @@ export interface TaskSpec {
      * pending call itself runs once, having been adjudicated). Re-pass the same value the original task used.
      */
     shellGate?: "off" | "always" | "classify";
+    /**
+     * The caller's AUTO-MODE INTENT for this task — the "user turned auto on" half of the classifier
+     * arming (CC 2.1.250 polarity: auto mode is something the USER enables at the permission-mode
+     * seat, and something an ORGANIZATION may only DENY; it is never something an organization grants
+     * on a user's behalf). The engine arms its per-run classifier only when ALL THREE hold:
+     *  - this seat is `true` (intent),
+     *  - {@link RunnerDeps.autoMode} is present (the deployment is classifier-capable — the trust gate;
+     *    classifier RULES still enter ONLY through that face, never through this seat), and
+     *  - {@link RuntimeCaps.autoMode} is not `false` (the per-principal DENY bit; ABSENT is NOT a denial).
+     *
+     * **Ownership** — same split as {@link shellGate}: the service layer TRANSLATES the effective
+     * permission mode into this seat (at the same point it translates the mode into `shellGate`);
+     * core only CONSUMES it. Absent ⇒ not an auto-mode task (byte-identical to the pre-seat shape:
+     * asks flow the original chain). Only the literal `true` is a value here: any other present value
+     * (`false`, `"true"`, `1`) is refused at the door (`config.auto_mode_requested_invalid`) rather than
+     * read as either polarity — a marshalled string must never silently arm, or silently disarm, a
+     * classifier.
+     *
+     * **Inheritance**: the intent is session-wide, like a permission mode — an engine-spawned child of
+     * an auto-mode task inherits it through the trusted constraint chain
+     * (`InheritedGate.autoModeRequested`), never through a model-authored argument; the child's own
+     * deny bit and deployment face are still evaluated for the child. **On resume:** the intent the
+     * suspend leg resolved (this seat, or the bit its chain carried) is recorded on the checkpoint's
+     * data half (`CheckpointState.inheritedGate.autoModeRequested`) and read back as one more intent
+     * source, so a redemption in another process arms as the suspend leg did without re-passing the
+     * seat; re-passing it is still honoured (the sources fold by OR). Intent only — the resuming
+     * deployment's face and the resuming principal's deny bit are judged afresh on every leg.
+     */
+    autoModeRequested?: true;
     /** Task-scoped MCP servers, materialized into tools then disposed. */
     mcp?: McpServerSpec[];
     /** Task-scoped A2A peers (remote agents), whose advertised skills mount as `a2a__<peer>__<skill>`
@@ -3964,11 +4012,25 @@ export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "c
  * RB-420-c — TERMINAL frames closing a retry sequence. Without them a consumer that rendered a
  * `rate_limited`/`retrying`/`reconnecting` frame has nothing telling it the wait is over, so the
  * warning row stays pinned until the next unrelated event. Exactly one terminal frame is emitted,
- * and only for a call that actually waited: `recovered` = a later attempt served the call,
- * `gave_up` = the retry budget ran out (or the call was cancelled) and a terminal error follows.
+ * and only for a call that actually waited (a retry wait, or a `waiting_first_token` trail —
+ * #530): `recovered` = the call was served after the wait (a later attempt, or the first token
+ * finally arriving), `gave_up` = the retry budget ran out (or the call was cancelled) and a
+ * terminal error follows.
  * Both mean the same thing to a renderer — stop showing the retry state.
  */
- | "recovered" | "gave_up";
+ | "recovered" | "gave_up"
+/**
+ * #530 — the first-token WAIT, before any failure: a first-token watchdog is armed
+ * (`firstTokenTimeoutMs > 0`) and nothing has arrived yet. Emitted once the wait has lasted
+ * `WAITING_FIRST_TOKEN_AFTER_MS` and re-emitted every `WAITING_FIRST_TOKEN_EVERY_MS` while it goes
+ * on, carrying {@link BrainStatus.elapsedMs} and {@link BrainStatus.timeoutMs}; never carries a
+ * retry countdown (`retryInMs`/`retryAtMs` — no wait is being announced, a wait is being
+ * OBSERVED). CLOSED like a retry trail: once a wait frame went out, the call's terminal frame
+ * follows — `recovered` when the call went on to be served (the first token arrived, on this
+ * attempt or a later one), `gave_up` when it failed for good — so a renderer that pinned the row
+ * has its "stop" signal. No frame at all when no watchdog is armed.
+ */
+ | "waiting_first_token";
 /**
  * WHY a retry wait is happening, as a closed, provider-NEUTRAL bucket — the companion to
  * {@link BrainStatusPhase}, which says what the brain is doing about it. A consumer rendering an
@@ -4023,6 +4085,13 @@ export interface BrainStatus {
      * the authoritative RELATIVE quantity, and this seat is the absolute convenience derived from it.
      */
     retryAtMs?: number;
+    /** #530 — on a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
+     *  moment the frame is emitted (the emitting process's clock; approximate across a hop). Absent on
+     *  every other phase. */
+    elapsedMs?: number;
+    /** #530 — on a `waiting_first_token` frame: the armed first-token watchdog, ms — the wait's ceiling,
+     *  so a consumer can render "45s of 120s". Absent on every other phase. */
+    timeoutMs?: number;
     /** RB-420-c — 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
      *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */
     attempt?: number;
@@ -5248,9 +5317,16 @@ export interface WorkflowGovernanceBaseline {
 /**
  * design/99 §K — the per-principal runtime ENTITLEMENTS the engine enforces server-side, resolved by a
  * deployment via {@link RunnerDeps.runtimeCapsResolver} from center's `GET /api/config/effective?principal=`.
- * Every field is TIGHTEN-ONLY (a cap only ever DENIES or FORCES; `undefined` = no per-principal restriction).
- * Only the two caps the ENGINE can enforce live here; `allowUltracode`/`allowBypassPermissions` are
- * shell-UX / service-settings-layer concerns (see {@link RunnerDeps.runtimeCapsResolver}).
+ * Every field is TIGHTEN-ONLY (a cap only ever DENIES or FORCES) — but the family carries THREE
+ * polarities, and "absent" does not read the same on each:
+ *  · DENY-shaped, `false` denies / absent is no restriction: {@link allowWorkflows}, {@link allowFork},
+ *    {@link autoMode} (the per-principal deny bit of a user-enabled mode), {@link allowMemoryOptOut}
+ *    (the one member whose resolver-FAULT degrade is allow, on the privacy axis);
+ *  · GRANT-shaped, `=== true` opts in / absent is OFF: {@link allowObservers};
+ *  · FORCE-shaped, `true` mandates / absent is the caller's opt-in default: {@link forceDurableGate}
+ *    (binds only where a checkpoint store is wired; announced `config.durable_gate_unavailable` where none is).
+ * These six are the caps the ENGINE enforces; `allowUltracode`/`allowBypassPermissions` are shell-UX /
+ * service-settings-layer concerns (see {@link RunnerDeps.runtimeCapsResolver}).
  */
 export interface RuntimeCaps {
     /** `false` DENIES workflow self-orchestration for this principal server-side — even on a deployment that is
@@ -5279,18 +5355,29 @@ export interface RuntimeCaps {
     /** `true` FORCES this principal's run onto the durable-approval path: the engine synthesizes a
      *  `durableApproval{scope: principal}` so a policy `ask` suspends to the wire (a per-tool CC-faithful gate)
      *  even when the caller did not opt in — center's fleet-wide "interactive runs gate" mandate. A
-     *  caller-supplied `TaskSpec.durableApproval` always wins (it may carry a tighter scope/ttl). */
+     *  caller-supplied `TaskSpec.durableApproval` always wins (it may carry a tighter scope/ttl).
+     *  The mandate binds only where a {@link RunnerDeps.checkpointStore} is wired — the park facility it
+     *  forces the run onto. On a store-less deployment it has no facility: the leg announces
+     *  `config.durable_gate_unavailable` once (before its first ask), every ask resolves on the live chain
+     *  (a live approver / question face in-stream, or the fail-closed deny with none), no durable record
+     *  is written, and a live question face is consulted rather than vetoed (a mandate that cannot park
+     *  must not demote a reachable person into the model answering for them). */
     forceDurableGate?: boolean;
     /**
-     * design/143 批2 (CC 2.1.207 auto mode): route a surviving permission `ask` to the
-     * small-model security CLASSIFIER before any human/durable resolution (allow → run; block → deny
-     * `source:"classifier"`; classifier failure → FAIL-CLOSED back to the original ask chain).
-     * **POLARITY: `=== true` EXPLICIT opt-in, default OFF** (same as {@link allowObservers} — auto mode
-     * hands a model the ask-resolution power for this principal's session; that is never implied).
-     * Arming ALSO requires the deployment to be classifier-capable ({@link RunnerDeps.autoMode} — the
-     * trust gate lives there: classifier RULES enter only through the deployment assembly face, never a
-     * repo-controlled plane; the CC 2.1.207 three-source invariant). `true` on an incapable
-     * deployment resolves to a no-op (asks flow the original chain; no warn — the gate, not a mistake).
+     * The per-principal auto-mode DENY bit (CC 2.1.250 polarity — the mirror of the settings-plane
+     * `permissions.disableAutoMode` ratchet: an organization may only take auto mode AWAY; it is the
+     * USER who turns it on, at the task's intent seat {@link TaskSpec.autoModeRequested}).
+     *
+     * **POLARITY: `=== false` DENIES; ABSENT IS NOT A DENIAL.** This is the family's deny-shaped
+     * member (like {@link allowWorkflows} / {@link allowFork}), NOT a grant-shaped one like
+     * {@link allowObservers}: a deployment with no entitlement source at all resolves `undefined` here
+     * and still arms on intent + capability. `true` is accepted and means the same as absent (no
+     * per-principal restriction) — it is not a grant, and it cannot arm a task whose intent seat is
+     * unset. The arming itself: intent ∧ {@link RunnerDeps.autoMode} present ∧ this bit not `false`
+     * (allow → run; block → deny `source:"classifier"`; classifier failure → FAIL-CLOSED back to the
+     * original ask chain). The trust gate is unchanged: classifier RULES enter only through the
+     * deployment assembly face, never a repo-controlled plane (the CC 2.1.207 three-source invariant).
+     * A denial resolves to a no-op (asks flow the original chain; no warn — the gate, not a mistake).
      */
     autoMode?: boolean;
     /**
@@ -5770,6 +5857,23 @@ export interface EngineNotice {
      *    `onNotice` sink per value (console arm once per process) instead of lying in wait; where the
      *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
      *    fact, one code, two loudness dialects); `detail: { raw }`.
+     *  - `"config.durable_gate_unavailable"` — the per-principal `forceDurableGate` entitlement is in
+     *    force on a leg whose deployment wired NO checkpoint store. The entitlement is a mandate
+     *    ("every interactive ask of this principal gates durably"), and a mandate with no park
+     *    facility cannot be honored: no ask of the leg can suspend, so each one resolves on the LIVE
+     *    chain — a live approver / question face answers in-stream, and with none the ask is denied
+     *    fail-closed — and NO durable approval record is written. The ask routing itself is not
+     *    changed by the notice (a store-less leg never could park); the notice is the loud half of a
+     *    posture that used to degrade silently, disclosed before the first ask of the leg. Audience
+     *    `"user"` (the person whose asks will not be recorded is entitled to that; the operator hears
+     *    it through the sink as always). Once per prepared task leg — a resume or a delegated child
+     *    is its own leg and says so again; `detail: { sessionId, runId, principal?, cause, liveApprover,
+     *    liveQuestionFace }` — `cause` is `"no_deployment_store"` (the deployment wired none) or
+     *    `"task_store_null"` (`TaskSpec.checkpointStore: null`, the per-run off switch, on a leg
+     *    whose deployment may well have a store: the fix is the task's); `liveApprover` /
+     *    `liveQuestionFace`: whether a live seat will EFFECTIVELY answer the leg's permission asks /
+     *    questions in-stream (a delegated child under an inherited content mandate reads `false`
+     *    even with a face wired — the marker withholds the question), or the fail-closed deny will.
      *
      *  - `"task.user_steer_undrained"` / `"task.user_followup_undrained"` (#259) — user steers /
      *    follow-ups whose receipts said "queued" were still in their queue at agent_end: the run
@@ -6021,6 +6125,24 @@ export interface EngineNotice {
      *    disposition table with the error dispositions. The loser MUST NOT retry into the winner's
      *    account. A consumer diffing its own table against the catalog must not add a row for it.
      *
+     *  - `"config.peer_lane_unmounted"` (design/385 §1.2⑥) — `RunnerDeps.peerDirectory` is wired but
+     *    the cross-session lane could not mount on this leg: no `mailboxStore`, or one that does not
+     *    declare `crossProcessSafe: true` (several terminals would share one session box on luck). The
+     *    seat is inert for the run (no ListAgents, peer addresses refuse with the same reason). Once per
+     *    prepared leg; `detail: { reason, code, mailboxWired, sessionId, runId }`. Audience `"operator"`
+     *    (a wiring fact; the fix is the deployment's).
+     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6) — a message parked in THIS session's
+     *    own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is the arm:
+     *    `"refused"` (this session's `crossSessionInbound` setting, or a record whose typed fields
+     *    cannot be rendered canonically), `"admission_refused"` (the drain-stage admission re-check:
+     *    duplicate / hop loop / runaway — `cause` names it), `"notice_unrouted"` (a notice-kind record
+     *    — idle/delivery notice — met a build with no notice face: settled without delivery, never
+     *    ridden through the peer-message envelope), or `"held"` (mode parity held it; the
+     *    held-message review face is not mounted in this build, so the message STAYS PARKED and the
+     *    drain stops at it — disclosed once per seq per leg). `detail: { disposition, cause, seq, box,
+     *    fromSession?, sessionId, runId }`. Audience `"user"`: the session's user is the one who did
+     *    not receive it.
+     *
      *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
      *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
      *    deployment's declared transcript durability is being contradicted by reality. Announced at
@@ -6661,11 +6783,15 @@ export interface RunnerDeps {
      * resolver, or an unset cap) = NO per-principal restriction (TIGHTEN-ONLY: a cap can only ever DENY or
      * FORCE; absence falls back to the deployment-level default). Symmetric with {@link sessionPolicyStore}.
      *
-     * core enforces only the caps it CAN enforce in the engine: `allowWorkflows` (the third stage of the
-     * workflows gate — task opt-in ∧ deployment capability ∧ this) and `forceDurableGate` (forces a run onto
-     * the durable-approval path so a policy `ask` suspends to the wire). `allowUltracode` is a shell/UX concern
-     * (reasoning-tier, not a core primitive); `allowBypassPermissions` is enforced at the service settings-
-     * resolution layer (the engine sees only a resolved policy, never a "this allow came from bypass" signal).
+     * core enforces the six caps it CAN enforce in the engine (polarity per member on {@link RuntimeCaps}):
+     * `allowWorkflows` (the third stage of the workflows gate — task opt-in ∧ deployment capability ∧ this),
+     * `allowFork` (the Agent-fork route), `allowObservers` (explicit opt-in for observer auto-spawn),
+     * `autoMode` (the per-principal deny bit of the user-enabled auto mode), `allowMemoryOptOut` (may this
+     * principal declare a capture opt-out), and `forceDurableGate` (forces a run onto the durable-approval
+     * path so a policy `ask` suspends to the wire — where a checkpoint store is wired; a store-less leg
+     * announces `config.durable_gate_unavailable`). `allowUltracode` is a shell/UX concern (reasoning-tier,
+     * not a core primitive); `allowBypassPermissions` is enforced at the service settings-resolution layer
+     * (the engine sees only a resolved policy, never a "this allow came from bypass" signal).
      */
     runtimeCapsResolver?: (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
     /**
@@ -6734,8 +6860,10 @@ export interface RunnerDeps {
     retentionPolicy?: import("./retention.js").RetentionPolicy;
     /**
      * design/143 批2b — the auto-mode classifier's DEPLOYMENT assembly face. This is the
-     * capability half of the arming AND-gate: a run arms auto mode only when the per-principal
-     * entitlement grants it ({@link RuntimeCaps.autoMode}` === true`) AND this face is present.
+     * CAPABILITY arm of the three-arm arming: a run arms auto mode only when the task carries the
+     * auto-mode INTENT ({@link TaskSpec.autoModeRequested}, or the same bit inherited on the chain by an
+     * engine-spawned child) AND this face is present AND the per-principal DENY bit is not set
+     * ({@link RuntimeCaps.autoMode}` !== false` — absent is not a denial).
      *
      * 🔐 Trust gate (the CC 2.1.207 three-source invariant): classifier RULES enter EXCLUSIVELY
      * here — a deployment-constructed object, never a `TaskSpec` field, never a repo-file plane. The
@@ -6901,6 +7029,28 @@ export interface RunnerDeps {
      *  absent means the default table, not "guard off". Threaded into the auto-mounted SendMessage as
      *  `SendMessageToolOptions.admission`; read per call (a value change governs the next message). */
     peerAdmission?: Partial<import("../agents/peer-admission.js").PeerAdmissionConfig>;
+    /**
+     * design/385 §2.1 / §5.1 — the peer-session DIRECTORY: the discovery truth of the cross-session
+     * lane (other sessions of this engine for the same user). A HOST implements the contract (cli: the
+     * pid-keyed registration files; server: its session table) and writes the rows; the engine only
+     * reads them. Seat semantics = the mailbox seat's: NO seat, NO lane — every face stays byte-identical
+     * to a pre-385 build. With the seat wired the engine (a) mounts `ListAgents` (alias `ListPeers`),
+     * (b) opens SendMessage's `session.<id>` address arm and its last `name [ref]` rung, (c) drains this
+     * session's own `session.<sessionId>` box at every turn boundary (the mailbox contract's third
+     * consumption chain), and (d) splices the cross-session rule into the auto-mode classifier slot.
+     * HARD PRECONDITION (design/385 §1.2⑥): `mailboxStore` must be wired AND declare
+     * `crossProcessSafe: true`; otherwise the lane is REFUSED at prepare with a named
+     * `config.peer_lane_unmounted` notice (never mounted on luck), and the seat is inert for that run.
+     */
+    peerDirectory?: import("../agents/peer-directory.js").PeerDirectory;
+    /**
+     * design/385 §4.4 — this deployment's `crossSessionInbound` setting LAYERS for the drain-point
+     * judgment (managed / user / repo, resolved by `resolveCrossSessionInboundSetting` — explicit value
+     * wins, unset ⇒ mode parity, an unrecognized value forces `hold` loudly). Read at every drain, so a
+     * host that re-reads its settings files hands the current layers through a getter. Absent = unset
+     * everywhere (mode parity, the CC default). Inert without {@link peerDirectory}.
+     */
+    crossSessionInbound?: import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers | (() => import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers);
     /**
      * design/164 件五 — DEPLOYMENT-level usage governance: allowances that span TASKS, evaluated per
      * principal (or once for the whole deployment when a task declares none). A different axis from
@@ -7431,4 +7581,4 @@ export interface RunnerDeps {
      *  3, CC parity). The Runner tracks the consecutive-reuse counter per task across both compaction sites. */
     maxConsecutiveProviderReuse?: number;
 }
-export type { AgentTool, Model, StreamFn, ThinkingLevel };
+export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };