@sema-agent/core 7.29.0 → 7.30.0

package/dist/agents/cross-session-judge.js

@@ -1,53 +1,63 @@
 import { isPermissionModeClass } from "./cross-session-envelope.js";
-export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["accept", "hold", "refuse"]);
+export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["wake", "next-turn", "hold", "refuse"]);
 export function isCrossSessionInboundSetting(value) {
     return typeof value === "string" && CROSS_SESSION_INBOUND_SETTINGS.includes(value);
 }
-const RANK = { accept: 0, hold: 1, refuse: 2 };
+export const CROSS_SESSION_INBOUND_DEPRECATED_SPELLINGS = Object.freeze({ accept: "next-turn" });
+const RANK = { wake: 0, "next-turn": 1, hold: 2, refuse: 3 };
+const UNSET_BASELINE = "next-turn";
 function readLayer(v) {
     if (v === undefined || v === null || v === "default")
-        return undefined;
-    return isCrossSessionInboundSetting(v) ? v : "invalid";
+        return { value: undefined };
+    if (isCrossSessionInboundSetting(v))
+        return { value: v };
+    const migrated = typeof v === "string" && Object.hasOwn(CROSS_SESSION_INBOUND_DEPRECATED_SPELLINGS, v) ? CROSS_SESSION_INBOUND_DEPRECATED_SPELLINGS[v] : undefined;
+    return migrated !== undefined ? { value: migrated, deprecated: true } : { value: "invalid" };
 }
 export function resolveCrossSessionInboundSetting(layers) {
     const invalidLayers = [];
+    const deprecatedLayers = [];
     let value;
     let decidedBy;
     for (const [name, raw] of [
         ["managed", layers.managed],
         ["user", layers.user],
     ]) {
-        const v = readLayer(raw);
+        const { value: v, deprecated } = readLayer(raw);
         if (v === "invalid") {
             invalidLayers.push(name);
             continue;
         }
+        if (deprecated === true)
+            deprecatedLayers.push(name);
         if (v !== undefined && value === undefined) {
             value = v;
             decidedBy = name;
         }
     }
     for (const raw of layers.repo ?? []) {
-        const v = readLayer(raw);
+        const { value: v, deprecated } = readLayer(raw);
         if (v === "invalid") {
             invalidLayers.push("repo");
             continue;
         }
+        if (deprecated === true)
+            deprecatedLayers.push("repo");
         if (v === undefined)
             continue;
-        if (RANK[v] > RANK[value ?? "accept"]) {
+        if (RANK[v] > RANK[value ?? UNSET_BASELINE]) {
             value = v;
             decidedBy = "repo";
         }
-        else if (v !== "accept" && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
+        else if (v !== UNSET_BASELINE && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
             decidedBy = "repo";
         }
     }
-    if (invalidLayers.length > 0 && RANK[value ?? "accept"] < RANK.hold) {
+    if (invalidLayers.length > 0 && RANK[value ?? UNSET_BASELINE] < RANK.hold) {
         value = "hold";
         decidedBy = "invalid";
     }
-    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers };
+    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers, ...(deprecatedLayers.length > 0 ? { deprecatedLayers } : {}) };
 }
 export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
     "mode-mismatch",
@@ -71,7 +81,7 @@ export function describeCrossSessionHoldCause(cause) {
         case "managed-setting":
             return `Your organization's managed settings set "crossSessionInbound" to "hold".`;
         case "repo-setting":
-            return `This repository's settings set "crossSessionInbound" to "hold" (your own "accept" cannot override a repo tightening).`;
+            return `This repository's settings set "crossSessionInbound" to "hold" (your own "next-turn" cannot override a repo tightening).`;
         case "invalid-setting":
             return 'A settings file has an unrecognized "crossSessionInbound" value (see the settings warning), so messages are held while it is present.';
         case "bypass-default":
@@ -121,7 +131,8 @@ export function judgeCrossSessionInbound(input) {
     const { setting, selfModeClass, sender } = input;
     if (setting.value !== undefined) {
         switch (setting.value) {
-            case "accept":
+            case "wake":
+            case "next-turn":
                 return { verdict: "deliver" };
             case "refuse":
                 return { verdict: "refuse", cause: "opt-out" };

package/dist/agents/list-agents-tool.d.ts

@@ -1,14 +1,27 @@
 import { Type } from "typebox";
 import type { TaskAccess } from "../core/task-registry.js";
 import { type RosterEntry } from "./roster-store.js";
-import { type PeerDirectory } from "./peer-directory.js";
+import { type PeerDirectory, type PeerPresence, type PeerSessionRecord } from "./peer-directory.js";
 export declare const LIST_AGENTS_TOOL_NAME = "ListAgents";
 export declare const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
 /** CC `maxResultSizeChars` for this tool. */
 export declare const LIST_AGENTS_MAX_RESULT_CHARS = 10000;
+/** The default freshness window (24 h) — one source, the peer lane's knob table. */
+export declare const PEER_LISTING_FRESH_WINDOW_MS: number;
+/**
+ * THE freshness predicate: a peer row is listed by default iff it is live AND (its host says it is
+ * working — `tempo` active/blocked — OR it changed within the window). One rule over rendering
+ * visibility only: refs are minted and names resolve over the FULL set, so a row hidden here is still
+ * addressable by name. Dead and stale rows are what `includeAll` adds.
+ */
+export declare function isFreshPeerRow(r: Pick<PeerSessionRecord, "liveness" | "tempo" | "updatedAt">, now: number, windowMs?: number): boolean;
+/** `Ns` / `Nm` / `Nh` / `Nd` — a bounded age word for a listing row; a future stamp reads as `0s`. */
+export declare function formatAgo(ms: number): string;
+/** The last two path segments of a working directory (what a person recognizes a project by). */
+export declare function cwdTail(cwd: string): string;
 export interface ListAgentsToolOptions {
-    /** The peer-session directory (the mount reason; without it the tool is not mounted). */
-    peerDirectory: PeerDirectory;
+    /** The peer-session directory. Absent ⇒ no peer rows (the two agent lanes still list). */
+    peerDirectory?: PeerDirectory;
     /** This session's own identity — excluded from the peer listing, included in ref disambiguation. */
     self: {
         sessionId: string;
@@ -40,8 +53,10 @@ export interface ListAgentsToolOptions {
     roster?: {
         list(): RosterEntry[] | Promise<RosterEntry[]>;
     };
-    /** Include dead (offline) peer sessions in the listing. Default false (CC observable form). */
-    includeOffline?: boolean;
+    /** The resolved freshness window ({@link isFreshPeerRow}); absent ⇒ {@link PEER_LISTING_FRESH_WINDOW_MS}. */
+    freshWindowMs?: number;
+    /** The clock (tests). */
+    now?: () => number;
 }
 /** One rendered row. `kind` names the lane; `address` is what SendMessage accepts. */
 export interface ListAgentsRow {
@@ -49,6 +64,14 @@ export interface ListAgentsRow {
     name: string;
     /** Peer rows only: the listing-minted ref. */
     ref?: string;
+    /** Peer rows, live: when the row last changed (rendered `active <N> ago`). */
+    lastActiveAt?: number;
+    /** Peer rows, dead: when the host marked it (rendered `offline <N> ago`); a dead row with no stamp renders `offline`. */
+    offlineAt?: number;
+    /** Peer rows: the last two segments of the session's working directory, when the row carries one. */
+    cwd?: string;
+    /** Peer rows: the session's self-reported presence, when it reported any. */
+    presence?: PeerPresence;
     /** What SendMessage accepts: on both AGENT lanes the registry `task_id` VERBATIM (no prefixing or
      *  re-minting), never the child's session id — a different domain, tabled in INTEGRATION-CORE §1.6a.
      *  Peer rows carry the `session.<id>` box handle instead. */
@@ -59,4 +82,6 @@ export interface ListAgentsRow {
      *  COMPLETED and nothing else: a model applies the continuable rule to that word. */
     state: "busy" | "idle" | "offline" | "running" | "parked" | "finished" | "failed" | "killed" | "cancelled" | "unknown";
 }
-export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{}>, unknown>;
+export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{
+    includeAll: Type.TOptional<Type.TBoolean>;
+}>, unknown>;

package/dist/agents/list-agents-tool.js

@@ -3,12 +3,38 @@ import { defineTool } from "../core/tools.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { formatPeerNameRef } from "./cross-session-ref.js";
 import { entryAccessible } from "./roster-store.js";
-import { mintPeerSessionCandidates, peerSessionBoxHandle } from "./peer-directory.js";
+import { mintPeerSessionCandidates, PEER_PRESENCE_MAX_CHARS, peerSessionBoxHandle } from "./peer-directory.js";
+import { PEER_LANE_DEFAULTS } from "./peer-admission.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
+import { assertNoRetiredKeys } from "../core/retired-keys.js";
 export const LIST_AGENTS_TOOL_NAME = "ListAgents";
 export const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
 export const LIST_AGENTS_MAX_RESULT_CHARS = 10_000;
+export const PEER_LISTING_FRESH_WINDOW_MS = PEER_LANE_DEFAULTS.listingFreshWindowMs;
+export function isFreshPeerRow(r, now, windowMs = PEER_LISTING_FRESH_WINDOW_MS) {
+    if (r.liveness !== "live")
+        return false;
+    if (r.tempo === "active" || r.tempo === "blocked")
+        return true;
+    return now - r.updatedAt <= windowMs;
+}
+export function formatAgo(ms) {
+    const sec = Math.max(0, Math.floor(ms / 1000));
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const h = Math.floor(min / 60);
+    if (h < 48)
+        return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+}
+export function cwdTail(cwd) {
+    const parts = cwd.split(/[\\/]+/).filter((p) => p !== "");
+    return parts.slice(-2).join("/");
+}
 const AGENT_ROW_STATE = {
     pending: "running",
     running: "running",
@@ -32,26 +58,46 @@ function peerRowState(r) {
     const tempo = r.tempo;
     return tempo !== undefined && Object.hasOwn(PEER_ROW_STATE, tempo) ? PEER_ROW_STATE[tempo] : "unknown";
 }
+function renderPresence(p) {
+    const parts = [...(p.agent !== undefined ? [`agent=${inlineUntrusted(p.agent, PEER_PRESENCE_MAX_CHARS)}`] : []), ...(p.intent !== undefined ? [`intent=${inlineUntrusted(p.intent, PEER_PRESENCE_MAX_CHARS)}`] : [])];
+    return `self: ${parts.join(", ")}`;
+}
+const RETIRED_LIST_AGENTS_OPTION_KEYS = {
+    includeOffline: "the model asks for stale and offline rows per call with the `includeAll` tool parameter (a superset: stale + offline)",
+};
 export function createListAgentsTool(opts) {
+    assertNoRetiredKeys(opts, RETIRED_LIST_AGENTS_OPTION_KEYS, "ListAgentsToolOptions");
+    const peers = opts.peerDirectory !== undefined;
+    const windowMs = opts.freshWindowMs ?? PEER_LISTING_FRESH_WINDOW_MS;
     return defineTool({
         name: LIST_AGENTS_TOOL_NAME,
         ...toolFace("list-agents"),
         isConcurrencySafe: () => true,
-        description: `List the agents and peer sessions you can message with SendMessage. Peer sessions are other sessions of this ` +
-            `engine running for the same user on this machine, shown as \`name [ref]\`; send to one with its name (or \`name [ref]\` ` +
-            `when a name is ambiguous, or its \`session.<id>\` address). A peer that is offline still accepts messages — they are parked ` +
-            `durably in its session box and delivered when it next runs. Background agents you spawned are listed with their task_id. ` +
+        description: `List the agents${peers ? " and peer sessions" : ""} you can message with SendMessage. ` +
+            (peers
+                ? `Peer sessions are other sessions of this engine running for the same user, shown as \`name [ref] · state · active <N> ago · <directory> · self: agent=…, intent=…\`; send to one with its name (or \`name [ref]\` ` +
+                    `when a name is ambiguous, or its \`session.<id>\` address). By default only FRESH peers are listed (working now, or active within the last ${formatAgo(windowMs)}); ` +
+                    `pass includeAll: true to also list stale and offline ones. A peer that is offline or unlisted still accepts messages — they are parked ` +
+                    `durably in its session box and delivered when it next runs. `
+                : `Peer sessions of this engine are not addressable on this mount (no session directory). `) +
+            `Background agents you spawned are listed with their task_id. ` +
             `A ref is only valid against the listing (or disambiguation error) you read it from — do not invent one.`,
-        parameters: Type.Object({}),
-        execute: async () => {
+        parameters: Type.Object({
+            includeAll: Type.Optional(Type.Boolean({ description: "Also list stale (no activity within the freshness window) and offline peer sessions. Default false." })),
+        }),
+        execute: async (args) => {
+            const includeAll = args.includeAll === true;
+            const now = opts.now?.() ?? Date.now();
             const rows = [];
             let peerRows = [];
             let directoryFault;
-            try {
-                peerRows = await opts.peerDirectory.listPeerSessions({ scope: opts.self.scope });
-            }
-            catch (e) {
-                directoryFault = thrownText(e);
+            if (opts.peerDirectory !== undefined) {
+                try {
+                    peerRows = await opts.peerDirectory.listPeerSessions({ scope: opts.self.scope });
+                }
+                catch (e) {
+                    directoryFault = thrownText(e);
+                }
             }
             for (const c of mintPeerSessionCandidates(peerRows, { sessionId: opts.self.sessionId })) {
                 const r = c.record;
@@ -59,14 +105,18 @@ export function createListAgentsTool(opts) {
                     continue;
                 if (r.liveness === "deleted")
                     continue;
-                if (r.liveness === "dead" && opts.includeOffline !== true)
+                if (!includeAll && !isFreshPeerRow(r, now, windowMs))
                     continue;
+                const presence = { ...(r.agent !== undefined ? { agent: r.agent } : {}), ...(r.intent !== undefined ? { intent: r.intent } : {}) };
                 rows.push({
                     kind: "peer_session",
                     name: r.name,
                     ref: c.ref,
                     address: peerSessionBoxHandle(r.sessionId),
                     state: peerRowState(r),
+                    ...(r.liveness === "live" ? { lastActiveAt: r.updatedAt } : r.diedAt !== undefined ? { offlineAt: r.diedAt } : {}),
+                    ...(r.cwd !== undefined ? { cwd: cwdTail(r.cwd) } : {}),
+                    ...(presence.agent !== undefined || presence.intent !== undefined ? { presence } : {}),
                 });
             }
             let registryCapped = false;
@@ -101,7 +151,9 @@ export function createListAgentsTool(opts) {
             }
             const lines = rows.map((r) => {
                 const label = r.kind === "peer_session" ? formatPeerNameRef(inlineUntrusted(r.name, 64), r.ref) : inlineUntrusted(r.name, 64);
-                return `${label}  ·  ${r.state}  ·  ${r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? "agent (durable record)" : "agent"}  ·  ${r.address}`;
+                const age = r.kind !== "peer_session" ? undefined : r.lastActiveAt !== undefined ? `active ${formatAgo(now - r.lastActiveAt)} ago` : r.offlineAt !== undefined ? `offline ${formatAgo(now - r.offlineAt)} ago` : "offline";
+                const cols = [label, r.state, age, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? "agent (durable record)" : "agent", r.address];
+                return cols.filter((c) => c !== undefined).join("  ·  ");
             });
             const finishedCount = rows.filter((r) => r.state === "finished").length;
             const header = rows.length === 0 ? "No agents or peer sessions are listed right now." : `${rows.length} listed:`;

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

@@ -7,7 +7,7 @@ export type PeerAxisTag = "h" | "s" | "t";
 export type PeerRefusalCode = "rate_limited" | "duplicate" | "hop_loop" | "hop_runaway" | "queue_full";
 /** Gate verdict subset of {@link PeerRefusalCode} (what `admit` itself can refuse with). */
 export type PeerAdmissionRefusal = Exclude<PeerRefusalCode, "queue_full">;
-export interface PeerAdmissionConfig {
+export interface PeerLaneConfig {
     /** Per-sender burst budget (bucket size). */
     bucketCapacity: number;
     /** Per-sender steady-state refill rate (tokens per second). */
@@ -27,12 +27,24 @@ export interface PeerAdmissionConfig {
      *  senders restart with full buckets — no correctness debt (the gate holds no state that must
      *  survive across messages). */
     maxTrackedRecipients: number;
+    /** Peer WAKE budget, HOST-enforced: how many times per hour a host may start a turn on a session
+     *  whose `crossSessionInbound` resolves to `wake` because its box grew. The engine spells the
+     *  number and the contract; the host that starts turns is the executor. Integer. */
+    maxWakesPerHour: number;
+    /** Peer delivery budget, ENGINE-enforced: how many box RECORDS one drain pass injects (held
+     *  releases, notice lines, peer messages and engine frames count alike — one counter over every
+     *  record injection); the rest stay leased for the next boundary, and the pass's own `inbox_notice`
+     *  line — which is not a record — says how many. Integer. */
+    maxMessagesPerRound: number;
+    /** The `ListAgents` freshness window: a live row with no activity word is listed by default only
+     *  while `now − updatedAt` is within it (`includeAll` lists the rest). Milliseconds. */
+    listingFreshWindowMs: number;
 }
 /** Upstream defaults, adopted verbatim (anchored; deviation would need evidence sema does not have). */
-export declare const PEER_ADMISSION_DEFAULTS: Readonly<PeerAdmissionConfig>;
+export declare const PEER_LANE_DEFAULTS: Readonly<PeerLaneConfig>;
 /** 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;
+export declare function __resetPeerLaneRangeAnnouncements(): 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.
@@ -46,7 +58,7 @@ export declare function __resetPeerAdmissionRangeAnnouncements(): void;
  * 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;
+export declare function resolvePeerLaneConfig(overrides?: Partial<PeerLaneConfig>, onNotice?: (notice: EngineNotice) => void): PeerLaneConfig;
 /** 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. */
@@ -135,10 +147,10 @@ export interface PeerAdmission {
      *  records the body IN THIS CALL (no rollback protocol — a downstream delivery failure does not
      *  refund; the bucket refills on its own). Refusal has zero side effects. Config is read
      *  per call (state is long-lived, values are current — upstream form). */
-    admit(req: PeerAdmissionRequest, config: PeerAdmissionConfig): PeerAdmissionVerdict;
+    admit(req: PeerAdmissionRequest, config: PeerLaneConfig): PeerAdmissionVerdict;
     /** Hop-only check (the identity-less-sender arm, and any caller that needs the chain verdict
      *  without touching rate/dedup state). */
-    checkHopChain(prospectiveChain: readonly string[], ownTokens: readonly string[], config: PeerAdmissionConfig): PeerAdmissionVerdict;
+    checkHopChain(prospectiveChain: readonly string[], ownTokens: readonly string[], config: PeerLaneConfig): PeerAdmissionVerdict;
     /** Observation face: senders currently tracked by this recipient instance. */
     trackedSenderCount(): number;
     /** Observation face: refusals by reason since this instance was created. */
@@ -149,7 +161,7 @@ export interface PeerAdmissionOptions {
     now?: () => number;
 }
 export declare function createPeerAdmission(options?: PeerAdmissionOptions): PeerAdmission;
-export declare function peerAdmissionFor(scope: string | undefined, recipientKey: string, config: PeerAdmissionConfig, options?: PeerAdmissionOptions): PeerAdmission;
+export declare function peerAdmissionFor(scope: string | undefined, recipientKey: string, config: PeerLaneConfig, options?: PeerAdmissionOptions): PeerAdmission;
 /**
  * The delivery legs' ONE admission entry: registry seat-commit follows the SAME
  * refusal-is-side-effect-free rule as the sender table inside `admit` — the instance is looked up
@@ -166,7 +178,7 @@ export declare function peerAdmissionFor(scope: string | undefined, recipientKey
  *  sent would read the send-point body record and refuse its own message as `duplicate`. Two gate
  *  instances, one per stage; the stage-less key is the pre-385 spelling and stays byte-identical. */
 export type PeerAdmissionStage = "send" | "drain";
-export declare function judgePeerAdmission(scope: string | undefined, recipientKey: string, req: PeerAdmissionRequest, config: PeerAdmissionConfig, options?: PeerAdmissionOptions, stage?: PeerAdmissionStage): PeerAdmissionVerdict;
+export declare function judgePeerAdmission(scope: string | undefined, recipientKey: string, req: PeerAdmissionRequest, config: PeerLaneConfig, options?: PeerAdmissionOptions, stage?: PeerAdmissionStage): PeerAdmissionVerdict;
 /** Test seam ONLY (module-level registry hygiene between test files — same posture as the lane map,
  *  which drains itself; this one is long-lived by design so tests reset it explicitly). */
 export declare function resetPeerAdmissionRegistryForTests(): void;

package/dist/agents/peer-admission.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { deliverEngineNotice } from "../core/types.js";
-export const PEER_ADMISSION_DEFAULTS = Object.freeze({
+export const PEER_LANE_DEFAULTS = Object.freeze({
     bucketCapacity: 30,
     refillPerSecond: 0.5,
     dedupWindowMs: 30_000,
@@ -9,6 +9,9 @@ export const PEER_ADMISSION_DEFAULTS = Object.freeze({
     maxTrackedSenders: 256,
     maxQueuedPeerMessages: 50,
     maxTrackedRecipients: 256,
+    maxWakesPerHour: 6,
+    maxMessagesPerRound: 5,
+    listingFreshWindowMs: 24 * 60 * 60_000,
 });
 const CONFIG_RANGES = Object.freeze({
     bucketCapacity: [5, 500],
@@ -19,10 +22,14 @@ const CONFIG_RANGES = Object.freeze({
     maxTrackedSenders: [16, 100_000],
     maxQueuedPeerMessages: [10, 5_000],
     maxTrackedRecipients: [16, 100_000],
+    maxWakesPerHour: [0, 600],
+    maxMessagesPerRound: [1, 500],
+    listingFreshWindowMs: [60_000, 30 * 24 * 60 * 60_000],
 });
+const INTEGER_FIELDS = new Set(["maxWakesPerHour", "maxMessagesPerRound"]);
 let announcedOutOfRangeBySink = new WeakMap();
 const announcedOutOfRangeConsole = new Set();
-function peerAdmissionRangeLedger(onNotice) {
+function peerLaneRangeLedger(onNotice) {
     if (typeof onNotice !== "function")
         return announcedOutOfRangeConsole;
     let lines = announcedOutOfRangeBySink.get(onNotice);
@@ -32,12 +39,12 @@ function peerAdmissionRangeLedger(onNotice) {
     }
     return lines;
 }
-export function __resetPeerAdmissionRangeAnnouncements() {
+export function __resetPeerLaneRangeAnnouncements() {
     announcedOutOfRangeBySink = new WeakMap();
     announcedOutOfRangeConsole.clear();
 }
-export function resolvePeerAdmissionConfig(overrides, onNotice) {
-    const out = { ...PEER_ADMISSION_DEFAULTS };
+export function resolvePeerLaneConfig(overrides, onNotice) {
+    const out = { ...PEER_LANE_DEFAULTS };
     if (overrides === undefined)
         return out;
     for (const k of Object.keys(CONFIG_RANGES)) {
@@ -49,12 +56,14 @@ export function resolvePeerAdmissionConfig(overrides, onNotice) {
             ? "not_a_finite_number"
             : v < lo || v > hi
                 ? "out_of_range"
-                : undefined;
+                : INTEGER_FIELDS.has(k) && !Number.isInteger(v)
+                    ? "not_an_integer"
+                    : undefined;
         if (reason === undefined) {
             out[k] = v;
             continue;
         }
-        announcePeerAdmissionFallback(k, v, reason, lo, hi, onNotice);
+        announcePeerLaneFallback(k, v, reason, lo, hi, onNotice);
     }
     return out;
 }
@@ -87,18 +96,18 @@ function configValueKey(v) {
     }
     return renderConfigValue(v);
 }
-function announcePeerAdmissionFallback(field, given, reason, lo, hi, onNotice) {
-    const fallback = PEER_ADMISSION_DEFAULTS[field];
+function announcePeerLaneFallback(field, given, reason, lo, hi, onNotice) {
+    const fallback = PEER_LANE_DEFAULTS[field];
     const shown = renderConfigValue(given);
     const key = JSON.stringify([field, typeof given, configValueKey(given)]);
-    const ledger = peerAdmissionRangeLedger(onNotice);
+    const ledger = peerLaneRangeLedger(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`) +
+        message: `Peer-lane setting ${field}=${shown} is ` +
+            (reason === "out_of_range" ? `outside its legal range [${lo}, ${hi}]` : reason === "not_an_integer" ? `not a whole number` : `not a finite number`) +
             `; that field falls back to its default (${fallback}). Every other field is unaffected.`,
         detail: {
             field,

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

@@ -6,6 +6,22 @@ export declare const PEER_SESSION_RECORD_SCHEMA_VERSION = 1;
 export declare const PEER_SESSION_RECORD_MAX_BYTES = 262144;
 export type PeerSessionLiveness = "live" | "dead" | "deleted";
 export type PeerSessionTempo = "active" | "idle" | "blocked";
+/** A session's SELF-REPORTED presence: what it says it is (`agent`) and what it says it is doing
+ *  (`intent`). Labels a peer controls — rendered bounded and prefixed `self:`, never read by any
+ *  permission, routing or wake judgment. The same object rides `TaskSpec.peerPresence`, the wiring
+ *  manifest and the directory row a host copies it into. */
+export interface PeerPresence {
+    agent?: string;
+    intent?: string;
+}
+/** The read cap of one presence label; a longer value refuses the whole row (one rule, `field_invalid`). */
+export declare const PEER_PRESENCE_MAX_CHARS = 120;
+/** THE rule for one presence label, read by the row reader and by prepare's door on `TaskSpec.peerPresence` (a
+ *  spec the directory would refuse is refused where it is written, not when the host files the row). */
+export declare function peerPresenceLabelValid(v: unknown): v is string | undefined;
+/** Prepare's door: `TaskSpec.peerPresence` is a plain object whose `agent` / `intent` each pass {@link peerPresenceLabelValid}
+ *  — else `config.peer_presence_invalid`, naming the field. */
+export declare function assertPeerPresenceValue(v: unknown): void;
 /** The registration row. Field set = CC's load-bearing subset + sema's `scope` axis + the sema-only
  *  liveness/tombstone members. A host writes it; every terminal reads it through {@link readPeerSessionRecord}. */
 export interface PeerSessionRecord {
@@ -24,11 +40,24 @@ export interface PeerSessionRecord {
     procStartMs?: number;
     cwd?: string;
     startedAt: number;
+    /** When the row last changed (the host's `lastActivityAt` on a server row; `markDead` writes it too). */
     updatedAt: number;
+    /**
+     * @contract peer_directory.dead_is_the_hosts_word — `dead` is the HOST's word: a host marks a row dead
+     * when the session has no leg in flight AND `updatedAt` is older than the host's retention period, and
+     * stamps `diedAt` with the marking time; that retention period is at least the engine's listing
+     * freshness window (`listingFreshWindowMs`), so a row the engine would list as fresh is never dead.
+     * The engine reads `liveness` and `updatedAt`; it never rewrites `liveness` from a row's age.
+     */
     liveness: PeerSessionLiveness;
     /** Present iff `liveness !== "live"`: when the row was marked dead (or the tombstone was written). */
     diedAt?: number;
+    /** The host's activity word. A stale `tempo` is the host's to clear: a row that says `active` is
+     *  listed as fresh regardless of its age. */
     tempo?: PeerSessionTempo;
+    /** Self-reported presence (see {@link PeerPresence}); a host copies it off the session's spec. */
+    agent?: string;
+    intent?: string;
     entrypoint?: string;
     peerProtocol?: number;
     /** CC capability bits (`/^[a-z0-9_]{1,32}$/`, ≤16); `sema_mailbox_v1` marks a store-lane peer. */

package/dist/agents/peer-directory.js

@@ -4,6 +4,18 @@ import { formatPeerNameRef, mintPeerRef, normalizePeerName, parsePeerNameRef, PE
 import { inlineUntrusted } from "../core/untrusted-text.js";
 export const PEER_SESSION_RECORD_SCHEMA_VERSION = 1;
 export const PEER_SESSION_RECORD_MAX_BYTES = 262_144;
+export const PEER_PRESENCE_MAX_CHARS = 120;
+export function peerPresenceLabelValid(v) {
+    return v === undefined || (typeof v === "string" && v.length <= PEER_PRESENCE_MAX_CHARS);
+}
+export function assertPeerPresenceValue(v) {
+    const bad = v === undefined ? undefined : v === null || typeof v !== "object" || Array.isArray(v) ? "peerPresence" : ["agent", "intent"].find((k) => !peerPresenceLabelValid(v[k]));
+    if (bad === undefined)
+        return;
+    const e = new Error(`TaskSpec.${bad === "peerPresence" ? bad : `peerPresence.${bad}`} must be ${bad === "peerPresence" ? "a plain { agent?, intent? } object" : `a string of at most ${PEER_PRESENCE_MAX_CHARS} characters`} — the peer directory refuses such a row whole, so the run would advertise a presence no listing can show`);
+    e.code = "config.peer_presence_invalid";
+    throw e;
+}
 export const SESSION_BOX_PREFIX = "session.";
 const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;
 export const PEER_SESSION_ID_GRAMMAR = "^[A-Za-z0-9_-]{1,80}$";
@@ -61,6 +73,12 @@ export function readPeerSessionRecord(raw) {
         return bad("peerProtocol");
     if (!optString(r["cwd"]))
         return bad("cwd");
+    if (!peerPresenceLabelValid(r["agent"]))
+        return bad("agent");
+    if (!peerPresenceLabelValid(r["intent"]))
+        return bad("intent");
+    const agent = typeof r["agent"] === "string" && r["agent"].trim() !== "" ? r["agent"] : undefined;
+    const intent = typeof r["intent"] === "string" && r["intent"].trim() !== "" ? r["intent"] : undefined;
     if (!optString(r["entrypoint"]))
         return bad("entrypoint");
     if (!optString(r["sockPath"]))
@@ -88,6 +106,8 @@ export function readPeerSessionRecord(raw) {
         ...(r["pid"] !== undefined ? { pid: r["pid"] } : {}),
         ...(r["procStartMs"] !== undefined ? { procStartMs: r["procStartMs"] } : {}),
         ...(r["cwd"] !== undefined ? { cwd: r["cwd"] } : {}),
+        ...(agent !== undefined ? { agent } : {}),
+        ...(intent !== undefined ? { intent } : {}),
         startedAt: r["startedAt"],
         updatedAt: r["updatedAt"],
         liveness,

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

@@ -3,7 +3,7 @@ import type { CrossSessionHoldCause, CrossSessionInboundVerdict } from "./cross-
 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). */
+ *  hold — it never enters the held queue; the drain stops at that seq and re-judges next pass). */
 export type PeerInboundHoldCause = CrossSessionHoldCause | "rate_limited";
 export interface PeerHeldEntry {
     /** The recipient box seq of the held record (its identity for the review face). */
@@ -26,7 +26,7 @@ export interface PeerHeldEntry {
     released?: boolean;
 }
 export type PeerHeldSettlement = "expired" | "delivered" | "refused" | "denied" | "dropped";
-export type PeerHeldSettleReason = "evicted" | "deadline" | "shutdown" | "rejudge" | "approved" | "denied" | "cancelled" | "inject_failed";
+export type PeerHeldSettleReason = "evicted" | "deadline" | "shutdown" | "rejudge" | "approved" | "denied" | "cancelled" | "inject_failed" | "superseded";
 /** The clock/timer seam (tests inject a virtual one). Handles are opaque. */
 export interface PeerClock {
     now(): number;
@@ -41,8 +41,10 @@ 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 lane refused the frame (settled `dropped`, receipt sent). Returns `"deferred"` ⇒ the run is
+     *  live but this pass's delivery budget is spent: the entry stays released and goes at the next
+     *  pass's flush (the same wait a run-less approval takes). */
+    inject?: (entry: PeerHeldEntry) => void | "deferred";
     /** 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). */
@@ -76,6 +78,15 @@ export interface PeerHeldQueue {
         refused: number;
         held: number;
     };
+    /**
+     * #1036 — the box is this queue's durable seat, so an entry whose record is no longer IN the box was
+     * settled by whoever held the lease meanwhile (a takeover acked it, delivered or refused). Called by a
+     * drain right after it claims the lease, with the seqs the claimed snapshot holds (a claim marks EVERY
+     * unacked record, so absence is absence): such entries leave the queue as `expired` / `superseded`,
+     * with no receipt (the owner that settled them sent one) and no decision recorded (there is no record
+     * left to decide about). Returns how many were retired.
+     */
+    reconcile(present: ReadonlySet<number>): 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;
@@ -83,7 +94,23 @@ export interface PeerHeldQueue {
     size(): number;
     /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts. */
     shutdown(): void;
+    /**
+     * #1036 — the TERMINAL DECISIONS this queue has taken about records that are still parked in
+     * the box, seq → the settlement word. Since a held record now stays in its durable box (the box is
+     * this queue's durable seat), a decision taken BETWEEN runs — a human's deny, a deadline, an
+     * eviction — has to survive the run whose ledger recorded it, or the session's next run re-judges
+     * the record from scratch and can deliver a message a person already refused. A decision is kept
+     * only until a drain that holds the lease acks past it ({@link PeerHeldQueue.forgetDecisions}); it
+     * is process-level, like the queue itself, and a crash loses it exactly as it loses the queue.
+     */
+    decisions(): ReadonlyMap<number, PeerHeldSettlement>;
+    /** #1036 — a lease-owning drain acked these seqs out of the box: their decisions are spent. */
+    forgetDecisions(seqs: Iterable<number>): void;
 }
+/** #1036 — how many terminal decisions about still-parked records one box's queue remembers
+ *  (see {@link PeerHeldQueue.decisions}). Several times the queue's own cap: the queue bounds what is
+ *  LIVE, this bounds what has been decided and not yet observed as consumed. */
+export declare const PEER_HELD_DECISION_MEMORY: number;
 export declare function createPeerHeldQueue(key: string, opts?: {
     cap?: number;
     clock?: PeerClock;