@sema-agent/core 7.3.0 → 7.4.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 7.4.0 — 2026-09-04
+
+Bug-fix release. No exports removed, no wire key removed; every narrowing is named below.
+
+### Fixed — #548 auto-mode classifier denial limit escalates to a person (CC 2.1.250 `FO`/`Wie`/`eme`/`yR`/`tme`)
+- `createAutoModeDenialTracker`: per run, count-then-judge (`consecutive >= 3 || total >= 20`, defaults `AUTO_MODE_DENIAL_LIMIT_DEFAULTS`); reset on a classifier allow or a person's allow (CC `yR` call sites), not on tool success. Knob `RunnerDeps.autoMode.denialLimit { maxConsecutive, maxTotal, autoDenyAfterMs }` — bad values throw at prepare (loud).
+- The block that trips the limit is minted as an **ask** (`decisionReason: "classifier"`) carrying the additive member `denialLimitFallback { consecutive, total, limit, autoDenyAfterMs }` and `requiresRealApproval: true`; the sandbox-admission, inherited-wrapper and blanket-`onAsk` lanes cannot consume it (pinned per lane). A non-tripping block stays a byte-identical deny.
+- **Narrowing, named**: the CONSECUTIVE-bound fallback ask auto-denies after 120 s with no answer (`ResolvedAsk.autoDenied` / `PermissionDeniedPayload.autoDenied`, additive; CC's timed shape); the TOTAL-bound card is never timed (CC form: it waits for a person). `autoDenyAfterMs: 0` disarms the window. Only fallback asks are timed; ordinary asks arm no timer. Parked (durable) fallback asks are still timed in this version — #559.
+- **Narrowing, named**: headless (no ask channel) — the third consecutive block stops the run with `TaskResult.errorCode = "classifier.denial_limit"` (new terminal member) plus a same-code notice; previously the run kept being denied without limit. `ENGINE_NOTICE_CODES` + `classifier.denial_limit` (audience `user`).
+- Not carried: the persisted arming recipe does not carry the denial-limit bounds (#556); the durable park record does not carry `denialLimitFallback` (#557, server/cli seam).
+
+### Fixed — #549 the sensitive-path write guard knew one spelling of the agent's own config root
+- `RECOMMENDED_SENSITIVE_PATTERNS` + `.sema`, `.sema.*`, `.sema-notifier-build` (three exact entries, not a namespace glob — `.semaphore/`, `.semantic/` and the engine's own `.sema-worktrees/` parent are untouched; a `.sema-*` family entry was tried and withdrawn before release because it hard-denied every fs-hand write inside an isolated worktree); the shell's `~/.sema/settings.json` / `~/.sema.json` are now guarded like their `.claude*` twin, closing a self-authorization write through Write/Edit.
+- **Data-root passthrough (new, load-bearing)**: `createSensitivePathPolicy` gains `dataRoot?: string` (default `$AGENT_DATA_DIR ?? ~/.ai-agent`, same caliber as `createTranscriptIntegrityPolicy`). A target inside the engine data root is judged on its sub-path only — the root's own ancestors (e.g. `.sema` when the shell sites the root at `~/.sema/engine-data`) never deny it — while a sensitive segment inside the root still denies. Root compared in two views (canonical via the same `canonicalizeTarget`, lexical fallback), every view anchored. Without this the memory library the engine tells the model to Write into would have been hard-denied on the shell deployment.
+- `PATH_NOT_IN_ROOT_ESCAPE_HINT` drops its closing sentence naming Bash as unconfined by the fence (a live retest showed the model taking it as the next step); the card offers the sanctioned widening only.
+- `expandHomeTilde` now lives in `src/tools/fs/safety.ts` (path-family home).
+
+### Fixed — #551 peer-admission out-of-range values fell back silently
+- A `peerAdmission` field outside its window (or not a finite number) still falls back to that field's default, and now announces `config.peer_admission_out_of_range` (audience `operator`; `detail { field, given, default, range: [lo, hi], reason: "out_of_range" | "not_a_finite_number" }`) once per field per structurally distinct configuration. `ENGINE_NOTICE_CODES` + 1.
+
+### Fixed — #535 a delegated child's file edits belong to the ROOT session's file history
+- The root run exposes a file-history lineage `{ scope, root, fs }` on `ToolExecuteContext.fileHistoryLineage`; the Agent tool threads it verbatim into every fresh spawn leg (`RunInternals.fileHistoryLineage`, never the revive arm). A child whose canonical root and filesystem identity equal the lineage's records its first-touch edits (and the #491 retraction) into the root scope, mints no boundary of its own, and skips the fork carry; fixed point at any depth. A child on another tree (worktree isolation, explicit cwd, unattested env) keeps its own scope.
+- **Narrowing, named**: a restore request (`rewindFilesTo` / `resumeAt + restoreFiles`) on a child recording into its root scope is refused with prepare-throw code `rewind.child_scope_unsupported` (previously converged silently on an empty child scope). A delegated fork on another tree starts empty instead of carrying the source scope.
+- Not carried: revive/`resume(token)` legs (checkpoint has no lineage seat), workflow/team spawn legs, root-vs-background-child restore concurrency — listed on #535.
+
+### Also in this version (landed earlier on main, first published here)
+- design/385 slice 4 (cross-session messaging, held queue): the cross-session NOTICE vocabulary and its store/carrier seats; the HELD QUEUE machine (a peer `hold` becomes held-queue-and-ACK instead of park-and-block, `held_settled` outcome, review deadline follows the cause, idle-distance cap, unavailable ⇒ roll back the newest); the IDLE SUBSCRIPTION machine and SendMessage `notify_when_idle` (declared in the schema only when the lane is mounted, CC form); `fromSession` grammar guard; receiving-round fixes (hold dedup, approve-throw keeps the entry held, released entries never re-arm the deadline). Wire: `docs/sdk/07-multi-agent.md` §Slice 4. Server S-109 window opens here.
+- #533 workflow journal writes strip `errorMessage` on non-completed rows; replay re-issues only completed rows.
+- #534 `TaskResult.editedFiles` (additive): canonical paths first-touched by fs write tools, three-valued law (landed / ambiguous / thrown counted; proven-unwritten not), cap 1000.
+- #550 checkpoint risk descriptor: scan-then-strip order (`stripFormatCharacters(redactSecrets(x))`) at both summary arms.
+- Consumer smoke probe registers the 385 slice-2b/4 peer-family exports (45 entries).
+
+### Export surface
+- +9 exports (#548 tracker/knob/message family), +0 removed; `test/export-surface.snapshot.json` 2039 → 2048.
+
+## 7.3.1 — 2026-09-03
+
+### Changed (narrowing, named) — #531 Edit validates BEFORE it asks
+- **`ToolSpec.validateInput?(args, ctx)`** — a pure input pre-validation hook the loop runs BEFORE the permission gate (CC parity: `validateInput` precedes the permission prompt; a refusal is a typed tool result, not a card). Edit / Write-on-existing / NotebookEdit implement it with the same `requireRead` + path checks the execute path keeps (double-checked; TOCTOU-safe). **Narrowing**: an Edit of a file the model never Read no longer raises an approval card — the model receives the read-first refusal directly (the auto classifier is not consulted); a Read-then-Edit still asks exactly as before. A throwing validator reads as "no verdict" (the call proceeds to the gate; one `onError` hook-phase disclosure).
+
+### Added — #530 `waiting_first_token` status phase (closed set 6 → 7)
+- `BrainStatusPhase` +`"waiting_first_token"`: with an armed first-token watchdog (`firstTokenTimeoutMs` > 30s), a `status` frame is emitted once the first token has been awaited 30s and every 30s after (`elapsedMs`, `timeoutMs`; no `retryAtMs`); cleared by the token, the watchdog or the call's end. An announced wait closes with the terminal frame (`recovered`, detail `first token arrived`) — never a retry's wording. Constants `WAITING_FIRST_TOKEN_AFTER_MS` / `WAITING_FIRST_TOKEN_EVERY_MS` exported. **Consumers pinning the six-member phase set must widen** (cli client-core retry-status closed set; server status projection is a pass-through).
+
+### Added — #529 `WiringManifest.autoMode { armed, reason }`
+- Minted on every leg (effective half; fingerprinted like `modelGate`): `reason ∈ armed | no_intent | no_face | denied | resolver_fault | latch_open` (`AUTO_MODE_ARM_REASONS`), `armed ⇔ reason === "armed"`. The per-leg READ face of the #521 arming decision.
+
+### Fixed — #532 format characters inside / around a secret (family fix of A-087 root C)
+- The format-free scanning view sinks into `runRedactionPasses`, so BOTH entries (`scrubSecrets`, `redactSecrets`) and every consumer (`primaryActivityArg` → `TaskResult.stats.humanReview.gates[].toolArg`, previews, error text) redact a key split by U+200B / U+00AD / U+FEFF as one marker; the raw scan and one suffix scan per format slot are unioned in so a format character used as the BOUNDARY before a key (`x<ZWSP>sk-…`) is still found; past 64 format slots the input is replaced whole (over-strip, never a leak). Format characters outside a secret are preserved; format-free input is byte-identical.
+
 ## 7.3.0 — 2026-09-03
 
 ### Added — design/385 slice 2a + 2b (cross-session peer messaging: mailbox contract, file backend, agents domain; +40 exports, 0 removed)

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

@@ -1,3 +1,4 @@
+import { type EngineNotice } from "../core/types.js";
 /** Hop-chain axis tags: durable a* handle / sessionId / taskId. Order IS the key-preference order. */
 export type PeerAxisTag = "h" | "s" | "t";
 /** The five-code closed refusal set (`details.error` values). The first four are gate verdicts;
@@ -29,9 +30,23 @@ export interface PeerAdmissionConfig {
 }
 /** Upstream defaults, adopted verbatim (anchored; deviation would need evidence sema does not have). */
 export declare const PEER_ADMISSION_DEFAULTS: Readonly<PeerAdmissionConfig>;
-/** Resolve a caller's partial config against the defaults, per-field range-clamped-to-default.
- *  There is no off switch: the guard is always on; the ranges ARE the host's tuning space. */
-export declare function resolvePeerAdmissionConfig(overrides?: Partial<PeerAdmissionConfig>): PeerAdmissionConfig;
+/** Test seam (mirrors `__resetMaterializeEnvAnnouncements`); never called by production code.
+ *  Re-arms BOTH arms (a WeakMap has no clear — it is re-minted). */
+export declare function __resetPeerAdmissionRangeAnnouncements(): void;
+/**
+ * Resolve a caller's partial config against the defaults, per-field range-clamped-to-default.
+ * There is no off switch: the guard is always on; the ranges ARE the host's tuning space.
+ *
+ * A field the resolver cannot use falls back to ITS default (never a clamp to the nearest edge, and
+ * never a whole-config reject) — and, since #551, says so: one `config.peer_admission_out_of_range`
+ * notice PER FIELD carrying `{ field, given, default, range, reason }`. Both silent arms are covered:
+ * a value outside the legal window, and a value that is not a finite number at all (a string off an
+ * untyped host's JSON wiring, `NaN`, `Infinity`). Two bad fields in one call are two notices — the
+ * operator has two things to fix and folding them into one line would hide the second. `onNotice` is
+ * the deployment's sink; absent, the announcement still reaches `console.warn` through the shared
+ * delivery throat (an unwired host is not a silent one).
+ */
+export declare function resolvePeerAdmissionConfig(overrides?: Partial<PeerAdmissionConfig>, onNotice?: (notice: EngineNotice) => void): PeerAdmissionConfig;
 /** Hop-chain carrier sliding window: a chain keeps its most recent entries (upstream `Xbr`=32).
  *  The chain grows ONLY at send time (the sender appends its own token); delivery/replay never
  *  appends — a message-driven revival is not a hop. */

package/dist/agents/peer-admission.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { deliverEngineNotice } from "../core/types.js";
 export const PEER_ADMISSION_DEFAULTS = Object.freeze({
     bucketCapacity: 30,
     refillPerSecond: 0.5,
@@ -19,21 +20,95 @@ const CONFIG_RANGES = Object.freeze({
     maxQueuedPeerMessages: [10, 5_000],
     maxTrackedRecipients: [16, 100_000],
 });
-export function resolvePeerAdmissionConfig(overrides) {
+let announcedOutOfRangeBySink = new WeakMap();
+const announcedOutOfRangeConsole = new Set();
+function peerAdmissionRangeLedger(onNotice) {
+    if (typeof onNotice !== "function")
+        return announcedOutOfRangeConsole;
+    let lines = announcedOutOfRangeBySink.get(onNotice);
+    if (lines === undefined) {
+        lines = new Set();
+        announcedOutOfRangeBySink.set(onNotice, lines);
+    }
+    return lines;
+}
+export function __resetPeerAdmissionRangeAnnouncements() {
+    announcedOutOfRangeBySink = new WeakMap();
+    announcedOutOfRangeConsole.clear();
+}
+export function resolvePeerAdmissionConfig(overrides, onNotice) {
     const out = { ...PEER_ADMISSION_DEFAULTS };
     if (overrides === undefined)
         return out;
     for (const k of Object.keys(CONFIG_RANGES)) {
         const v = overrides[k];
-        if (typeof v !== "number" || !Number.isFinite(v))
+        if (v === undefined)
             continue;
         const [lo, hi] = CONFIG_RANGES[k];
-        if (v < lo || v > hi)
+        const reason = typeof v !== "number" || !Number.isFinite(v)
+            ? "not_a_finite_number"
+            : v < lo || v > hi
+                ? "out_of_range"
+                : undefined;
+        if (reason === undefined) {
+            out[k] = v;
             continue;
-        out[k] = v;
+        }
+        announcePeerAdmissionFallback(k, v, reason, lo, hi, onNotice);
     }
     return out;
 }
+function renderConfigValue(v) {
+    try {
+        return String(v);
+    }
+    catch {
+        return `[unrenderable ${typeof v}]`;
+    }
+}
+function nonFiniteMarker(marks) {
+    let ordinal = 0;
+    return (_key, v) => {
+        ordinal += 1;
+        const n = typeof v === "number" ? v : Object.prototype.toString.call(v) === "[object Number]" ? Number(v) : undefined;
+        if (n !== undefined && !Number.isFinite(n))
+            marks.push(`${ordinal}:${String(n)}`);
+        return v;
+    };
+}
+function configValueKey(v) {
+    try {
+        const marks = [];
+        const j = JSON.stringify(v, nonFiniteMarker(marks));
+        if (j !== undefined)
+            return JSON.stringify([j, marks]);
+    }
+    catch {
+    }
+    return renderConfigValue(v);
+}
+function announcePeerAdmissionFallback(field, given, reason, lo, hi, onNotice) {
+    const fallback = PEER_ADMISSION_DEFAULTS[field];
+    const shown = renderConfigValue(given);
+    const key = JSON.stringify([field, typeof given, configValueKey(given)]);
+    const ledger = peerAdmissionRangeLedger(onNotice);
+    if (ledger.has(key))
+        return;
+    ledger.add(key);
+    deliverEngineNotice(onNotice, {
+        code: "config.peer_admission_out_of_range",
+        message: `Peer-admission setting ${field}=${shown} is ` +
+            (reason === "out_of_range" ? `outside its legal range [${lo}, ${hi}]` : `not a finite number`) +
+            `; that field falls back to its default (${fallback}). Every other field is unaffected.`,
+        detail: {
+            field,
+            given: typeof given === "number" || typeof given === "string" || typeof given === "boolean" ? given : shown,
+            default: fallback,
+            range: [lo, hi],
+            reason,
+        },
+    });
+}
 export const PEER_HOP_CHAIN_WINDOW = 32;
 export function peerAxisToken(scope, axis, value) {
     return JSON.stringify([scope ?? "", axis, value]);

package/dist/agents/peer-held-queue.d.ts

@@ -0,0 +1,101 @@
+import type { MailboxPeerMeta } from "../core/mailbox-store.js";
+import type { CrossSessionHoldCause, CrossSessionInboundVerdict } from "./cross-session-judge.js";
+import { type PeerDeliveryReceiptState } from "./peer-notices.js";
+/** The `cause` vocabulary of a `peer.inbound_disposition{disposition:"held"}` notice: the parity
+ *  judge's causes plus the drain-stage gate's TRANSIENT `rate_limited` (a bucket-wait, not a review
+ *  hold — it never enters the held queue; the drain stops at that seq and re-judges next round). */
+export type PeerInboundHoldCause = CrossSessionHoldCause | "rate_limited";
+export interface PeerHeldEntry {
+    /** The recipient box seq of the held record (its identity for the review face). */
+    readonly seq: number;
+    /** The recipient's box handle. */
+    readonly box: string;
+    /** The stored body (`[summary] message`, the canonical stored form). */
+    readonly content: string;
+    /** The sender's display name as the record carried it (display only). */
+    readonly from?: string;
+    readonly sentAt: number;
+    readonly hopChain?: readonly string[];
+    /** The typed record — reply routing (`fromSession`) and the attestation the re-judgment reads. */
+    readonly peerMeta?: MailboxPeerMeta;
+    readonly heldAt: number;
+    /** The cause last announced for this entry (re-judgment may move it). */
+    cause: CrossSessionHoldCause;
+    /** Approved by the review face while no run of the session was live: delivered at the next flush
+     *  (a re-judgment that now refuses still wins — CC `l0e`'s approve arm re-checks policy). */
+    released?: boolean;
+}
+export type PeerHeldSettlement = "expired" | "delivered" | "refused" | "denied" | "dropped";
+export type PeerHeldSettleReason = "evicted" | "deadline" | "shutdown" | "rejudge" | "approved" | "denied" | "cancelled" | "inject_failed";
+/** The clock/timer seam (tests inject a virtual one). Handles are opaque. */
+export interface PeerClock {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare const realPeerClock: PeerClock;
+/** The live seats a bound run gives the queue. `inject` is the ONLY member that is run-scoped (a run's
+ *  own injection lane); the others survive the run (the receipt route rides the mailbox, the judge
+ *  reads the deployment's settings getter) and are what a headless deadline settles through. */
+export interface PeerHeldQueueSink {
+    /** Re-judge an entry against the recipient's CURRENT settings and mode class (CC `M`). */
+    judge: (entry: PeerHeldEntry) => CrossSessionInboundVerdict;
+    /** Deliver a released entry into the live run's model context. Absent ⇒ no run is live. Throws ⇒
+     *  the lane refused the frame (settled `dropped`, receipt sent). */
+    inject?: (entry: PeerHeldEntry) => void;
+    /** The receipt to the sender (the binding routes it into the sender's box). */
+    receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => void;
+    /** Announce an entry entering the queue (or its cause changing on re-judgment). */
+    onHeld?: (entry: PeerHeldEntry, heldCount: number, cause: CrossSessionHoldCause, reannounce: boolean) => void;
+    /** Announce an entry leaving the queue. */
+    onSettled?: (entry: PeerHeldEntry, settlement: PeerHeldSettlement, reason: PeerHeldSettleReason, heldCount: number) => void;
+}
+export interface PeerHeldQueueConfig {
+    sink: PeerHeldQueueSink;
+    /** The resolved `dialogExpiry`: ms before a REVIEW-cause hold expires; `null` = never. */
+    dialogExpiryMs: number | null;
+}
+export type PeerHeldSettleOutcome = "gone" | "delivered" | "released_pending" | "dropped" | "dropped_by_policy" | "denied" | "expired";
+export interface PeerHeldQueue {
+    /** The registry key (scope + box). */
+    readonly key: string;
+    /** Bind (or re-bind) the live seats. Idempotent per run; a later bind replaces an earlier one. */
+    configure(cfg: PeerHeldQueueConfig): void;
+    /** The bound run ended: approvals now park as `released`; deadlines and receipts keep working. */
+    detachLeg(): void;
+    /** `true` once {@link configure} ran at least once (the queue can route receipts). */
+    configured(): boolean;
+    /** Park a message (CC `v` hold arm): evict-oldest when full, arm the deadline for a review cause,
+     *  announce, receipt `held`. */
+    hold(entry: Omit<PeerHeldEntry, "heldAt" | "released">): void;
+    /** Re-judge every entry against current settings (CC `D`): released ⇒ delivered (or parked
+     *  `released` with no live run), refused ⇒ refused with a receipt, still held ⇒ re-announced only
+     *  when the cause moved. */
+    rejudge(): {
+        released: number;
+        refused: number;
+        held: number;
+    };
+    /** The review face (CC `l0e`): approve re-judges then delivers (or parks `released` with no live
+     *  run), deny/cancel drop with the matching receipt. `"gone"` when nothing is held under that seq. */
+    settle(seq: number, decision: "approve" | "deny" | "cancel"): PeerHeldSettleOutcome;
+    list(): readonly PeerHeldEntry[];
+    size(): number;
+    /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts. */
+    shutdown(): void;
+}
+export declare function createPeerHeldQueue(key: string, opts?: {
+    cap?: number;
+    clock?: PeerClock;
+}): PeerHeldQueue;
+export declare function peerHeldQueueKey(scope: string, sessionId: string): string;
+/** The held queue of a session (created on first use). `clock` is honored only at creation. */
+export declare function peerHeldQueueFor(scope: string, sessionId: string, opts?: {
+    cap?: number;
+    clock?: PeerClock;
+}): PeerHeldQueue;
+/** The held queue of a session if one exists in this process (a host review face reads through this
+ *  without creating state for sessions that never held anything). */
+export declare function peerHeldQueueIfAny(scope: string, sessionId: string): PeerHeldQueue | undefined;
+/** Test seam: drop every queue (timers cleared, NO receipts — the crash form). Never called by production code. */
+export declare function resetPeerHeldQueuesForTests(): void;

package/dist/agents/peer-held-queue.js

@@ -0,0 +1,229 @@
+import { PEER_HELD_QUEUE_CAP, PEER_HELD_REVIEW_CAUSES } from "./peer-notices.js";
+import { peerSessionBoxHandle } from "./peer-directory.js";
+export const realPeerClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => {
+        const h = setTimeout(fn, ms);
+        h.unref?.();
+        return h;
+    },
+    clearTimeout: (h) => clearTimeout(h),
+};
+const crashHandlers = new WeakMap();
+export function createPeerHeldQueue(key, opts = {}) {
+    const cap = opts.cap ?? PEER_HELD_QUEUE_CAP;
+    const clock = opts.clock ?? realPeerClock;
+    const entries = [];
+    const deadlines = new Map();
+    let cfg;
+    const sinkOrThrow = () => {
+        if (cfg === undefined)
+            throw new Error("PeerHeldQueue: not configured — bind a run (configure) before holding messages");
+        return cfg.sink;
+    };
+    const safe = (f) => {
+        try {
+            f?.();
+        }
+        catch {
+        }
+    };
+    const clearDeadline = (seq) => {
+        const h = deadlines.get(seq);
+        if (h !== undefined) {
+            clock.clearTimeout(h);
+            deadlines.delete(seq);
+        }
+    };
+    const remove = (entry) => {
+        const i = entries.indexOf(entry);
+        if (i !== -1)
+            entries.splice(i, 1);
+        clearDeadline(entry.seq);
+    };
+    const settleOut = (entry, settlement, reason, receipt) => {
+        const sink = sinkOrThrow();
+        remove(entry);
+        if (receipt !== undefined)
+            safe(() => sink.receipt(entry, receipt));
+        safe(() => sink.onSettled?.(entry, settlement, reason, entries.length));
+    };
+    const armDeadline = (entry) => {
+        if (cfg === undefined || cfg.dialogExpiryMs === null || deadlines.has(entry.seq))
+            return;
+        if (entry.released === true)
+            return;
+        if (!PEER_HELD_REVIEW_CAUSES.includes(entry.cause))
+            return;
+        const h = clock.setTimeout(() => {
+            deadlines.delete(entry.seq);
+            if (!entries.includes(entry))
+                return;
+            rejudge();
+            if (!entries.includes(entry))
+                return;
+            settleOut(entry, "expired", "deadline", "expired");
+        }, cfg.dialogExpiryMs);
+        deadlines.set(entry.seq, h);
+    };
+    const tryDeliver = (entry, reason) => {
+        const sink = sinkOrThrow();
+        if (sink.inject === undefined)
+            return "no_leg";
+        try {
+            sink.inject(entry);
+        }
+        catch {
+            settleOut(entry, "dropped", "inject_failed", "dropped");
+            return "dropped";
+        }
+        settleOut(entry, "delivered", reason, "delivered");
+        return "delivered";
+    };
+    const rejudge = () => {
+        const sink = sinkOrThrow();
+        let released = 0;
+        let refused = 0;
+        const reannounce = [];
+        for (const entry of [...entries]) {
+            let verdict;
+            try {
+                verdict = sink.judge(entry);
+            }
+            catch {
+                continue;
+            }
+            if (verdict.verdict === "refuse") {
+                settleOut(entry, "refused", "rejudge", "refused");
+                refused += 1;
+                continue;
+            }
+            if (verdict.verdict === "deliver" || entry.released === true) {
+                const r = tryDeliver(entry, entry.released === true ? "approved" : "rejudge");
+                if (r === "no_leg")
+                    entry.released = true;
+                else if (r === "delivered")
+                    released += 1;
+                continue;
+            }
+            if (verdict.cause !== entry.cause) {
+                entry.cause = verdict.cause;
+                reannounce.push([entry, verdict.cause]);
+                clearDeadline(entry.seq);
+                armDeadline(entry);
+            }
+        }
+        for (const [entry, cause] of reannounce)
+            safe(() => sink.onHeld?.(entry, entries.length, cause, true));
+        return { released, refused, held: entries.length };
+    };
+    const queue = {
+        key,
+        configure(next) {
+            cfg = next;
+            for (const entry of entries) {
+                if (next.dialogExpiryMs === null)
+                    clearDeadline(entry.seq);
+                else
+                    armDeadline(entry);
+            }
+        },
+        detachLeg() {
+            if (cfg === undefined)
+                return;
+            const { inject: _inject, ...rest } = cfg.sink;
+            void _inject;
+            cfg = { ...cfg, sink: rest };
+        },
+        configured: () => cfg !== undefined,
+        hold(input) {
+            const sink = sinkOrThrow();
+            if (entries.some((e) => e.box === input.box && e.seq === input.seq))
+                return;
+            const entry = { ...input, heldAt: clock.now() };
+            if (entries.length >= cap) {
+                const oldest = entries[0];
+                settleOut(oldest, "expired", "evicted", "expired");
+            }
+            entries.push(entry);
+            armDeadline(entry);
+            safe(() => sink.onHeld?.(entry, entries.length, entry.cause, false));
+            safe(() => sink.receipt(entry, "held"));
+        },
+        rejudge,
+        settle(seq, decision) {
+            const sink = sinkOrThrow();
+            const entry = entries.find((e) => e.seq === seq);
+            if (entry === undefined)
+                return "gone";
+            if (decision === "deny") {
+                settleOut(entry, "denied", "denied", "denied");
+                return "denied";
+            }
+            if (decision === "cancel") {
+                settleOut(entry, "expired", "cancelled", "expired");
+                return "expired";
+            }
+            let verdict;
+            try {
+                verdict = sink.judge(entry);
+            }
+            catch {
+                entry.released = true;
+                return "released_pending";
+            }
+            if (verdict.verdict === "refuse") {
+                settleOut(entry, "refused", "approved", "refused");
+                return "dropped_by_policy";
+            }
+            const r = tryDeliver(entry, "approved");
+            if (r === "no_leg") {
+                entry.released = true;
+                clearDeadline(entry.seq);
+                return "released_pending";
+            }
+            return r;
+        },
+        list: () => entries.map((e) => ({ ...e, ...(e.hopChain !== undefined ? { hopChain: [...e.hopChain] } : {}), ...(e.peerMeta !== undefined ? { peerMeta: { ...e.peerMeta } } : {}) })),
+        size: () => entries.length,
+        shutdown() {
+            if (cfg === undefined) {
+                entries.length = 0;
+                for (const h of deadlines.values())
+                    clock.clearTimeout(h);
+                deadlines.clear();
+                return;
+            }
+            for (const entry of [...entries])
+                settleOut(entry, "expired", "shutdown", "expired");
+        },
+    };
+    crashHandlers.set(queue, () => {
+        entries.length = 0;
+        for (const h of deadlines.values())
+            clock.clearTimeout(h);
+        deadlines.clear();
+    });
+    return queue;
+}
+const heldQueues = new Map();
+export function peerHeldQueueKey(scope, sessionId) {
+    return JSON.stringify([scope, peerSessionBoxHandle(sessionId)]);
+}
+export function peerHeldQueueFor(scope, sessionId, opts = {}) {
+    const key = peerHeldQueueKey(scope, sessionId);
+    let q = heldQueues.get(key);
+    if (q === undefined) {
+        q = createPeerHeldQueue(key, opts);
+        heldQueues.set(key, q);
+    }
+    return q;
+}
+export function peerHeldQueueIfAny(scope, sessionId) {
+    return heldQueues.get(peerHeldQueueKey(scope, sessionId));
+}
+export function resetPeerHeldQueuesForTests() {
+    for (const q of heldQueues.values())
+        crashHandlers.get(q)?.();
+    heldQueues.clear();
+}

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

@@ -0,0 +1,109 @@
+import type { MailboxPeerFromMode } from "../core/mailbox-store.js";
+import type { CrossSessionInboundVerdict } from "./cross-session-judge.js";
+import { type PeerIdleNoticeKind } from "./peer-notices.js";
+import { type PeerClock } from "./peer-held-queue.js";
+export interface PeerIdleSubscriber {
+    /** The requester's session id (reply routing). */
+    readonly requester: string;
+    /** The requester's display name as its record carried it (display only). */
+    readonly requesterName?: string;
+    /** The requester's self-attested mode class (gates the detail line through the parity judge). */
+    readonly fromMode?: MailboxPeerFromMode;
+    readonly selfSent: boolean;
+    readonly requestedAt: number;
+}
+export interface PeerIdleTargetNotice {
+    kind: Exclude<PeerIdleNoticeKind, "expired">;
+    finishedAt?: number;
+    /** `idle` only, and only when the parity judge DELIVERS for that subscriber (CC gates it on a
+     *  pid-verified registry match + parity; sema has parity alone, §7). */
+    detail?: string;
+}
+export interface PeerIdleTargetSink {
+    /** Route one notice to one subscriber (the binding appends it to the requester's box). */
+    notify: (sub: PeerIdleSubscriber, notice: PeerIdleTargetNotice) => void;
+    /** The parity judge over the subscriber's attestation (detail gate, CC `p(d)`). */
+    judge: (sub: PeerIdleSubscriber) => CrossSessionInboundVerdict;
+    /** The held buffer's size: while > 0 the session is NOT idle to a subscriber (CC `c0e`). */
+    heldCount?: () => number;
+    /** The last turn's text, for the one-line detail (CC `getLastTurnText`). */
+    lastTurnText?: () => string | undefined;
+    /** Host announce: a subscription was recorded/refreshed (CC `onSubscribed`). */
+    onSubscribed?: (sub: PeerIdleSubscriber, outcome: "recorded" | "refreshed", live: number) => void;
+}
+export type PeerIdleSubscribeOutcome = "recorded" | "refreshed" | "full";
+export interface PeerIdleTarget {
+    configure(sink: PeerIdleTargetSink): void;
+    configured(): boolean;
+    /** CC `tYt` (sans pid classes): same requester ⇒ refresh; table full ⇒ `"full"` (the caller answers
+     *  `unavailable`). Already idle ⇒ the fire is (re)scheduled so a late subscriber hears it. */
+    subscribe(sub: PeerIdleSubscriber): PeerIdleSubscribeOutcome;
+    /** CC `A`: drop subscribers older than the TTL, silently. Returns how many. */
+    sweep(now?: number): number;
+    /** The session started working (a run began): cancel a pending fire. */
+    busy(): void;
+    /** The session's run ended with nothing queued: schedule the one-shot `idle` fire (debounced; parked
+     *  while the held buffer is non-empty and re-checked). `finishedAt` = when the turn ended. */
+    idle(finishedAt: number): void;
+    /** A graceful session end: fire `exited` (or `idle`, when the session was in fact idle — CC `$Rt`). */
+    exited(finishedAt?: number): void;
+    list(): readonly PeerIdleSubscriber[];
+    size(): number;
+}
+export declare function createPeerIdleTarget(opts?: {
+    clock?: PeerClock;
+    tableCap?: number;
+    ttlMs?: number;
+}): PeerIdleTarget;
+export interface PeerIdleOutstanding {
+    /** The target's session id. */
+    readonly target: string;
+    /** The target's label as the requester knew it at request time (bounded by the producer). */
+    readonly label: string;
+    readonly requestedAt: number;
+}
+export interface PeerIdleRequesterSink {
+    /** The 12 h timer fired with no newer ask to the same target: the requester answers itself `expired`. */
+    expired: (o: PeerIdleOutstanding) => void;
+}
+export interface PeerIdleRequester {
+    configure(sink: PeerIdleRequesterSink): void;
+    configured(): boolean;
+    /** CC `rYt`: record an outstanding ask (keeps the last 3 per target; the table caps at 32 across
+     *  targets — `cap` is the degraded send verdict). */
+    request(target: string, label: string): {
+        ok: true;
+        priors: number;
+    } | {
+        ok: false;
+        reason: "cap";
+    };
+    /** CC `oYt`: a notice arrived for a target — `idle`/`exited`/`expired` clear every ask to it,
+     *  `unavailable` clears the oldest one. Returns the label the requester knew, for rendering. */
+    settle(target: string, kind: PeerIdleNoticeKind): {
+        cleared: number;
+        label?: string;
+    };
+    labelFor(target: string): string | undefined;
+    list(): readonly PeerIdleOutstanding[];
+    size(): number;
+}
+export declare function createPeerIdleRequester(opts?: {
+    clock?: PeerClock;
+    cap?: number;
+    priorsKept?: number;
+    ttlMs?: number;
+}): PeerIdleRequester;
+export interface PeerIdleMachine {
+    readonly key: string;
+    readonly target: PeerIdleTarget;
+    readonly requester: PeerIdleRequester;
+}
+export declare function peerIdleMachineKey(scope: string, sessionId: string): string;
+/** The idle machine of a session (created on first use; `clock` honored at creation). */
+export declare function peerIdleMachineFor(scope: string, sessionId: string, opts?: {
+    clock?: PeerClock;
+}): PeerIdleMachine;
+export declare function peerIdleMachineIfAny(scope: string, sessionId: string): PeerIdleMachine | undefined;
+/** Test seam: forget every machine (timers are NOT settled — the crash form). Never called by production code. */
+export declare function resetPeerIdleMachinesForTests(): void;