@sema-agent/core 7.2.0 → 7.3.0

package/dist/core/mailbox-store.d.ts

@@ -12,7 +12,54 @@ export interface MailboxMessage {
      *  has other writers): such records deliver with an empty chain and are never retro-admitted —
      *  cross-engine records sit outside the guard's promise domain by ruling. */
     hopChain?: string[];
+    /** design/385 — typed peer metadata the drain point's authoritative judgments read (from-mode parity,
+     *  reply routing, admission sender key, record kind, the cross-principal trust anchors). Typed side
+     *  channel, never model-facing text — encoding it into `content` would let text reach authority.
+     *  ABSENT = a pre-385 or foreign record (same semantics as an absent `hopChain`): the drain treats it
+     *  as foreign, never retro-admits it. Validated at `append` ({@link readMailboxPeerMeta}). */
+    peerMeta?: MailboxPeerMeta;
 }
+/** design/385 — the typed peer-metadata record on a parked message. ONE optional object, one-time
+ *  contract extension; every field optional. Bundled backends persist it verbatim and hand back a
+ *  detached copy. */
+export interface MailboxPeerMeta {
+    /** The sending session's id (reply routing). */
+    fromSession?: string;
+    /** The sender's permission-mode class at send time — the drain judges parity against the RECEIVER. */
+    fromMode?: MailboxPeerFromMode;
+    /** The admission gate's sender key (rate/dedup axis). */
+    senderKey?: string;
+    /** Record kind: a peer message runs the parity judgment; notices bypass it and land on the notice face. */
+    kind?: MailboxPeerRecordKind;
+    /** Cross-principal delivery only — the SENDER's scope, the typed trust anchor for attribution. */
+    fromScope?: string;
+    /** Cross-principal delivery only — the delivery gate's receipt id (audit back-reference). */
+    gateReceiptId?: string;
+}
+export declare const MAILBOX_PEER_FROM_MODES: readonly ["bypass", "prompting"];
+export type MailboxPeerFromMode = (typeof MAILBOX_PEER_FROM_MODES)[number];
+export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice"];
+export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
+/** The `append` refusal code for a malformed `peerMeta` (design/385): a garbage record is refused up
+ *  front with this code, never silently stripped or stored — a drain that reads a half-typed record
+ *  would judge on fabricated inputs. */
+export declare const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
+/** The lane-mount refusal code: the cross-session lane asked for a backend that does not declare
+ *  cross-process safety ({@link mailboxCrossProcessMountVerdict}). */
+export declare const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
+/**
+ * Validate + detach an appended `peerMeta`. `undefined` ⇒ `undefined` (absent record). Anything else
+ * must be a plain object whose keys are all known, whose present values are non-empty strings, with
+ * `fromMode`/`kind` drawn from their closed sets; an `undefined`-valued key counts as absent. Any other
+ * shape throws {@link MailboxStoreError} with {@link MAILBOX_INVALID_PEER_META_CODE} — every bundled
+ * backend calls this BEFORE touching storage, so a refused append has zero side effects. Unknown keys
+ * are refused on purpose: the object is the contract's one typed slot, and a key nobody declared is
+ * either a typo or a newer schema this engine cannot judge on — both are loud, not silent.
+ */
+export declare function readMailboxPeerMeta(raw: unknown): MailboxPeerMeta | undefined;
+/** A detached copy of a persisted record's `peerMeta` (absent stays absent) — the read-side twin of
+ *  {@link readMailboxPeerMeta}, so a lease consumer's mutation never reaches the stored record. */
+export declare function cloneMailboxPeerMeta(meta: MailboxPeerMeta | undefined): MailboxPeerMeta | undefined;
 /** The enqueue refusal code of the pre-delete clause (see {@link MailboxStore} and
  *  {@link MailboxStoreError}) — the ONE place it is spelled, so an out-of-repo store twin imports it
  *  instead of value-copying the string (same posture as `STALE_RUNNING_REAP_ATTRIBUTION`: a shared
@@ -31,9 +78,10 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
  */
+export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
 export declare class MailboxStoreError extends Error {
-    readonly code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE;
-    constructor(code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE, message: string);
+    readonly code: MailboxStoreErrorCode;
+    constructor(code: MailboxStoreErrorCode, message: string);
 }
 /** A leased batch: the messages a claim winner owns for delivery, plus the ack cursor. */
 export interface MailboxLease {
@@ -49,6 +97,8 @@ export interface MailboxAppendMessage {
     sentAt: number;
     /** design/176 — see {@link MailboxMessage.hopChain}. */
     hopChain?: string[];
+    /** design/385 — see {@link MailboxMessage.peerMeta}; validated by {@link readMailboxPeerMeta}. */
+    peerMeta?: MailboxPeerMeta;
 }
 /**
  * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
@@ -92,8 +142,25 @@ export interface MailboxAppendMessage {
  *   lifecycle (the two bundled ones, the CC inbox adapter) has nothing to refuse and keeps accepting
  *   — the clause fixes the SPELLING of the refusal, so a deployment reads one code instead of a
  *   per-backend dialect. Acceptance kit: `mailboxTombstonedRecipientContract`.
+ * - PEER METADATA (design/385, additive): `append` takes an optional typed `peerMeta`; a backend
+ *   persists it and hands it back on `claimLease` byte-for-byte (a detached copy), absent stays absent,
+ *   and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
+ *   (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
+ *   `mailboxStoreContract` cover the round trip, the refusal and the aliasing.
+ * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
+ *   drain shares ONE box between several OS processes. A backend that is correct under that sharing —
+ *   seq minted once across processes, lease/ack never crossing, one process's housekeeping never
+ *   discarding another's durable append — declares `crossProcessSafe: true` AFTER passing
+ *   `mailboxCrossProcessContract` (the T2 kit that pins the whole set, not "has a lock"). A backend
+ *   that does not declare it is refused by the lane at mount time with a named reason
+ *   ({@link mailboxCrossProcessMountVerdict}) — never silently mounted on luck.
  */
 export interface MailboxStore {
+    /** design/385 — cross-process safety declaration (see the interface notes). `true` = this backend
+     *  passed `mailboxCrossProcessContract` over real OS processes; `false` = deliberately process-local
+     *  (the in-memory reference); absent = undeclared (the CC inbox adapter). Read by
+     *  {@link mailboxCrossProcessMountVerdict}; any other value is a malformed declaration and refuses. */
+    readonly crossProcessSafe?: boolean;
     /** Durably park one message. Refuses `"mailbox.recipient_tombstoned"` when the backend can see
      *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
@@ -110,6 +177,21 @@ export interface MailboxStore {
         maxAgeMs?: number;
     }): Promise<number>;
 }
+/** The lane-mount verdict on a backend's cross-process declaration. */
+export type MailboxCrossProcessVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    code: typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
+    reason: string;
+};
+/**
+ * design/385 — may the cross-session lane (several OS processes draining one session box) mount over
+ * this backend? `ok` only for an explicit `crossProcessSafe: true`. Every other shape refuses with a
+ * named reason so the host can print it: absent (undeclared), `false` (process-local by design), or a
+ * value of the wrong type (a malformed declaration is refused, not read as "probably fine").
+ */
+export declare function mailboxCrossProcessMountVerdict(store: MailboxStore): MailboxCrossProcessVerdict;
 /** RB-250② (2026-07-28) class fix — the box age for `reap` is the MAX `sentAt`, not the
  *  last array element: `sentAt` is caller-supplied, so append order need not be time order, and taking
  *  the tail let a box whose freshest message was mid-array be swept — both bundled backends discarded
@@ -118,12 +200,17 @@ export interface MailboxStore {
  *  adapter's documented posture — treating it as very old would let a malformed row delete a live
  *  box). Module-level export only; NOT re-exported from src/index.ts. */
 export declare function newestSentAt(messages: readonly MailboxMessage[]): number | undefined;
+/** A lease-facing copy of a stored record: every mutable member (hopChain, peerMeta) detached, so a
+ *  consumer's mutation can never reach the record a redelivery serves. Shared by the bundled backends. */
+export declare function detachMailboxMessage(m: MailboxMessage): MailboxMessage;
 /**
  * In-process reference implementation (single-instance / tests). Same posture as
  * {@link import("./background-agent-store.js").InMemoryBackgroundAgentStore}: not default-mounted,
  * detached copies at both boundaries, single-event-loop atomicity.
  */
 export declare class InMemoryMailboxStore implements MailboxStore {
+    /** Process-local by construction (a Map): never a cross-process box, said so explicitly. */
+    readonly crossProcessSafe = false;
     private boxes;
     private key;
     private box;

package/dist/core/mailbox-store.js

@@ -1,4 +1,52 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
+export const MAILBOX_PEER_FROM_MODES = ["bypass", "prompting"];
+export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice"];
+export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
+export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
+const PEER_META_STRING_KEYS = ["fromSession", "senderKey", "fromScope", "gateReceiptId"];
+export function readMailboxPeerMeta(raw) {
+    if (raw === undefined)
+        return undefined;
+    const refuse = (why) => {
+        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore.append: peerMeta ${why}`);
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return refuse("must be a plain object");
+    const proto = Object.getPrototypeOf(raw);
+    if (proto !== Object.prototype && proto !== null)
+        return refuse("must be a plain object (a class instance, Date, Map or similar is not)");
+    const out = {};
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== "string")
+            return refuse("carries a symbol-keyed member");
+        const k = key;
+        const v = raw[k];
+        if (v === undefined)
+            continue;
+        if (k === "fromMode") {
+            if (!MAILBOX_PEER_FROM_MODES.includes(v))
+                return refuse(`fromMode must be one of ${MAILBOX_PEER_FROM_MODES.join("|")}`);
+            out.fromMode = v;
+        }
+        else if (k === "kind") {
+            if (!MAILBOX_PEER_RECORD_KINDS.includes(v))
+                return refuse(`kind must be one of ${MAILBOX_PEER_RECORD_KINDS.join("|")}`);
+            out.kind = v;
+        }
+        else if (PEER_META_STRING_KEYS.includes(k)) {
+            if (typeof v !== "string" || v === "")
+                return refuse(`${k} must be a non-empty string`);
+            out[k] = v;
+        }
+        else {
+            return refuse(`carries an unknown key ${JSON.stringify(k)}`);
+        }
+    }
+    return out;
+}
+export function cloneMailboxPeerMeta(meta) {
+    return meta === undefined ? undefined : { ...meta };
+}
 export const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
 export class MailboxStoreError extends Error {
     code;
@@ -8,6 +56,17 @@ export class MailboxStoreError extends Error {
         this.name = "MailboxStoreError";
     }
 }
+export function mailboxCrossProcessMountVerdict(store) {
+    const declared = store.crossProcessSafe;
+    if (declared === true)
+        return { ok: true };
+    const reason = declared === undefined
+        ? "the mailbox backend does not declare cross-process safety (crossProcessSafe is absent): several terminal sessions would share one session box on luck"
+        : declared === false
+            ? "the mailbox backend declares crossProcessSafe: false (process-local by design): it cannot serve a session box shared across OS processes"
+            : `the mailbox backend's crossProcessSafe declaration is malformed (${typeof declared}, expected a boolean)`;
+    return { ok: false, code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE, reason };
+}
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {
@@ -18,7 +77,15 @@ export function newestSentAt(messages) {
     }
     return newest;
 }
+export function detachMailboxMessage(m) {
+    return {
+        ...m,
+        ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}),
+        ...(m.peerMeta !== undefined ? { peerMeta: cloneMailboxPeerMeta(m.peerMeta) } : {}),
+    };
+}
 export class InMemoryMailboxStore {
+    crossProcessSafe = false;
     boxes = new Map();
     key(scope, handle) {
         if (handle.includes("\u0000")) {
@@ -38,9 +105,17 @@ export class InMemoryMailboxStore {
     async append(scope, handle, msg) {
         if (scope === undefined || scope === "")
             throw new Error("MailboxStore.append: refusing a message without a scope");
+        const peerMeta = readMailboxPeerMeta(msg.peerMeta);
         const b = this.box(scope, handle);
         const seq = b.nextSeq++;
-        b.messages.push({ seq, ...(msg.from !== undefined ? { from: msg.from } : {}), content: msg.content, sentAt: msg.sentAt, ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}) });
+        b.messages.push({
+            seq,
+            ...(msg.from !== undefined ? { from: msg.from } : {}),
+            content: msg.content,
+            sentAt: msg.sentAt,
+            ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
+            ...(peerMeta !== undefined ? { peerMeta } : {}),
+        });
         return seq;
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
@@ -51,7 +126,7 @@ export class InMemoryMailboxStore {
             return null;
         const maxSeq = b.messages[b.messages.length - 1].seq;
         b.lease = { owner, expiresAt: now + ttlMs, maxSeq };
-        return { messages: b.messages.map((m) => ({ ...m, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}) })), maxSeq };
+        return { messages: b.messages.map((m) => detachMailboxMessage(m)), maxSeq };
     }
     async ack(scope, handle, owner, upToSeq) {
         const b = this.boxes.get(this.key(scope, handle));

package/dist/core/permission-rule-model.d.ts

@@ -331,6 +331,15 @@ export declare const SUGGESTION_LEXICON: readonly string[];
  * through, so an ordinary rule text reads normally. The result is length-bounded.
  */
 export declare function escapeForDisclosure(value: unknown): string;
+/**
+ * The zero-width half of {@link renderUntrustedCommandText} on its own: every `\p{Cf}` character
+ * REMOVED, nothing else touched. Exposed for a seat that must run a PATTERN pass (a secret scanner)
+ * before the display render — a credential the text splits with a format character is invisible to
+ * the scanner while it runs, and the render's own strip would then glue it back together in clear
+ * AFTER the scanner missed it. Strip first, scan, then render: the render's strip is idempotent over
+ * text this already stripped, so the final bytes are the same as a single render, minus the leak.
+ */
+export declare function stripFormatCharacters(text: string): string;
 /**
  * Render raw, untrusted COMMAND text for a display surface — the minimal safe baseline for the seats
  * that carry post-rewrite command bytes verbatim ({@link SegmentRuleSuggestion.segment} is the

package/dist/core/permission-rule-model.js

@@ -171,6 +171,9 @@ export function escapeForDisclosure(value) {
     return escaped.length <= DISCLOSED_RULE_TEXT_MAX_CHARS ? escaped : `${escaped.slice(0, DISCLOSED_RULE_TEXT_MAX_CHARS)}…`;
 }
 const DISPLAY_STRIP_FORMAT_RE = /\p{Cf}/gu;
+export function stripFormatCharacters(text) {
+    return text.replace(DISPLAY_STRIP_FORMAT_RE, "");
+}
 export function renderUntrustedCommandText(text, maxLen = DISCLOSED_RULE_TEXT_MAX_CHARS) {
     let raw;
     try {
@@ -179,7 +182,7 @@ export function renderUntrustedCommandText(text, maxLen = DISCLOSED_RULE_TEXT_MA
     catch {
         return "<unprintable>";
     }
-    return inlineUntrusted(raw.replace(DISPLAY_STRIP_FORMAT_RE, ""), maxLen);
+    return inlineUntrusted(stripFormatCharacters(raw), maxLen);
 }
 export function hasUnrenderableCharacters(text) {
     return CONTROL_CHARS_RE.test(text);

package/dist/core/runner/prepare-task.d.ts

@@ -41,6 +41,13 @@ export declare function __resetMaterializeEnvAnnouncements(): void;
  *  seam below (console latch only): tests here legitimately reuse ONE sink across prepares to pin
  *  the per-sink dedup itself, so the seam must be able to re-arm a still-referenced sink. */
 export declare function __resetToolModelGateAnnouncements(): void;
+/**
+ * The model gate's per-session READ face ({@link WiringManifest.modelGate}) — projected from the SAME
+ * gate decision {@link announceToolModelGate} reads (one source; the notice is the operator-sink
+ * dialect, this the manifest dialect). `undefined` when no default-mounted tool was trimmed on this
+ * run. The restore sentence is the notice's, verbatim.
+ */
+export declare const TOOL_MODEL_GATE_RESTORE_SENTENCE = "restore via TaskSpec.restoreGatedTools, SEMA_TOOL_MODEL_GATE=off, or RunnerDeps.toolModelGate: false";
 export { __resetReadFaceClampAnnouncement } from "./prepare-hands-readface.js";
 /**
  * design/164 件四 — how long before an execution environment's declared `lifetimeMs` expires the engine
@@ -1177,6 +1184,19 @@ export interface InheritedGate {
     }>;
     /** The chain's effective shell-gate doctrine — the child folds it by max-rank with its own spec. */
     shellGate?: "off" | "always" | "classify";
+    /**
+     * The chain's AUTO-MODE INTENT (`TaskSpec.autoModeRequested`, session-wide like a permission mode):
+     * emitted when the spawning task carried the intent itself or inherited it, so an engine-spawned
+     * child of an auto-mode task arms its OWN per-run classifier exactly as its parent did — the
+     * intent half only; the child's deny bit (`RuntimeCaps.autoMode === false`) and deployment face
+     * (`RunnerDeps.autoMode`) are evaluated for the child. Trusted chain data (Runner-assembled, never a
+     * model-authored argument); absent ⇒ the child is an auto-mode task only if its own spec says so.
+     * Persists on the checkpoint's data half (`CheckpointState.inheritedGate.autoModeRequested`) so a
+     * redemption in another process — no seat re-passed, no waking chain — reads the same intent the
+     * suspend leg had; the intent folds by OR across seat, live chain and seed, while the deny bit and
+     * the deployment face stay per-leg.
+     */
+    autoModeRequested?: true;
     /**
      * Org-memory admission freeze (ruled 2026-08-05): the spawning chain's FROZEN admitted org-scope
      * set — every org memory scope the parent actually mounted (deployment-origin + admitted request).