@sema-agent/core 7.28.1 → 7.30.0

package/dist/agents/child-model-seat.d.ts

@@ -62,15 +62,17 @@ export declare function childThinkingSeat(explicit: ThinkingLevel | undefined, d
 export declare function deploymentSubagentTierModel(deps: {
     models?: Record<string, Model>;
     roles?: ModelRoles;
-} | undefined): Model | undefined;
+} | undefined): InheritedModelPick | undefined;
 /**
  * The child run's model seat — ONE rule for every engine-spawned run (the delegation child at
  * `buildChildSpec`, the observer sidecar, the workflow launch site): an EXPLICIT model for this spawn wins
  * (per-call `model`, the agent definition's `model`, the tool-level `model`); else a deployment that STATED
  * a subagent tier gets it (no model on the seat — the role chain resolves the stated entry, `select` forms
- * included); else the child runs on the PARENT run's effective model (the caller's current `Model` object,
- * so per-model routing/credentials ride along); else — no parent model readable, which only happens outside
- * a Runner-enriched ctx — the bare role, whose chain ends at the deployment default.
+ * included); else the child runs on the PARENT run's effective model — taken as the REF that chose it and
+ * resolved against the catalog generation in force at THIS spawn ({@link inheritedParentModel}), so
+ * per-model routing/credentials ride along and a hot-swapped catalog reaches the child; else — no parent
+ * model readable, which only happens outside a Runner-enriched ctx — the bare role, whose chain ends at the
+ * deployment default.
  *
  * THE ROLE IDENTITY IS CONSTANT: every seat carries `modelRole: "subagent"`, the explicit-model seat too.
  * `resolveTaskModel` keys the role's `systemPrompt` / `thinking` presets on `modelRole` in BOTH of its
@@ -93,7 +95,57 @@ export type ChildModelSeat = {
     modelRole: "subagent";
     model?: ModelRef;
 };
-export declare function childModelSeat(explicit: ModelRef | undefined, deploymentStated: boolean, parent: Model | undefined): ChildModelSeat;
+/**
+ * The PARENT rung's value, resolved at THIS spawn tick. The parent leg travels as the REF that chose its
+ * model (`ToolExecuteContext.modelRef`), not as the object it has been holding since its own prepare, so:
+ *  · a catalog word resolves against the catalog generation in force NOW — a child spawned after a hot
+ *    swap runs on the generation its own prepare would have seen, which is what the swap law already
+ *    promises every string ref ("resolves against the new catalog at the next prepare");
+ *  · a word the swap RETIRED throws here, loudly, under the same unknown-ref policy a caller-written
+ *    retired word meets — never a silent fall back to the retired object, which is the shape that let a
+ *    child run for its whole life on a generation the deployment had withdrawn;
+ *  · a `Model` OBJECT is its own ref and passes through pinned, the swap law's other existing arm.
+ * Resolved lazily by {@link childModelSeat}, on the arm actually taken: a spawn that names its own model,
+ * or a deployment that stated a subagent tier, never consults the parent rung and so never inherits its
+ * refusal. A word with NO catalog to ask refuses under that same policy rather than travelling on as a
+ * word: a seat that cannot name the model it seats is not a seat, and the caller learns it here.
+ *
+ * @contract child_seat.parent_model_travels_as_its_catalog_word — an engine-spawned run that inherits its
+ * parent's model inherits the parent's CURRENT model BY THE REF THAT CHOSE IT, resolved once against the
+ * catalog generation in force at the child's own spawn: a catalog word therefore lands the child on the
+ * generation its own prepare would have seen (and refuses loudly, under the shared unknown-ref policy, when
+ * the word has been retired), while a parent whose model is a `Model` object travels as that object and is
+ * never re-resolved. The resolution happens at the spawn, not in the child's prepare, so the model the spawn
+ * frames name and the model the child runs on stay one value.
+ */
+export declare function inheritedParentModel(parent: ModelRef | undefined, catalog: Record<string, Model> | undefined): Model | undefined;
+/**
+ * What a spawn seats, and WHICH catalog word chose it.
+ *
+ * The two travel on different channels ON PURPOSE. `seat` is spread onto the child SPEC and carries the
+ * RESOLVED object, so the model the spawn frames name is the model the child runs — nothing re-resolves
+ * between the judgement and the child's prepare. `modelRef` is the word that object came from, and it rides
+ * the TRUSTED internals channel (`RunInternals.inheritedModelRef`) so the child is not silently PINNED by
+ * having been handed an object: its own children inherit the word in turn, and the deployment's per-model
+ * window overlay — which is keyed by word — still reaches it. Absent `modelRef` = there is no word (an
+ * object the caller pinned, a `select` criteria), and a leg with no word is never re-resolved and never
+ * overlaid, which is exactly what pinning means.
+ */
+/** A resolved model together with the catalog WORD that chose it — the shape a lane hands its launch site
+ *  when the two travel separately (the object onto the child spec, the word onto its trusted channel). */
+export interface InheritedModelPick {
+    readonly model: Model;
+    readonly modelRef?: ModelRef;
+}
+export interface ChildModelSeatPick<S> {
+    readonly seat: S;
+    readonly modelRef?: ModelRef;
+}
+export declare function childModelSeat(explicit: ModelRef | undefined, deploymentStated: boolean, parent: ModelRef | undefined, catalog?: Record<string, Model>, 
+/** The word the CALLER resolved `explicit` from, when the caller resolved one (a per-call model word a
+ *  delegation gate judged into an object before the seat ever saw it). An explicit STRING needs none — it
+ *  travels as itself and the child's own prepare resolves it, which already leaves the child its word. */
+explicitRef?: ModelRef): ChildModelSeatPick<ChildModelSeat>;
 /**
  * The FORK's model seat — the caller CONTINUED, not a subagent to the role chain. A fork always runs on the
  * caller's model (the caller's current `Model`, else the delegation tool's own `model`), and it carries NO
@@ -103,6 +155,6 @@ export declare function childModelSeat(explicit: ModelRef | undefined, deploymen
  * stated for its workers). No caller model readable (only outside a Runner-enriched ctx) ⇒ an empty seat: the
  * role chain's `default` start, exactly what a caller run with no `modelRole` of its own resolves.
  */
-export declare function forkModelSeat(callerModel: ModelRef | undefined): {
+export declare function forkModelSeat(callerModel: ModelRef | undefined, inheritedRef?: ModelRef, catalog?: Record<string, Model>): ChildModelSeatPick<{
     model?: ModelRef;
-};
+}>;

package/dist/agents/child-model-seat.js

@@ -1,4 +1,4 @@
-import { resolveTaskModel } from "../core/roles.js";
+import { resolveModel, resolveTaskModel } from "../core/roles.js";
 export function runnerRoleMap(runner) {
     try {
         return runner?.agentCatalog?.roles;
@@ -39,12 +39,38 @@ export function childThinkingSeat(explicit, deploymentStated, parent) {
     return level !== undefined ? { thinking: level } : {};
 }
 export function deploymentSubagentTierModel(deps) {
-    return deps !== undefined && deploymentStatesSubagentModel(deps.roles) ? resolveTaskModel({ modelRole: "subagent" }, deps).model : undefined;
+    if (deps === undefined || !deploymentStatesSubagentModel(deps.roles))
+        return undefined;
+    const resolved = resolveTaskModel({ modelRole: "subagent" }, deps);
+    return { model: resolved.model, ...(inheritableRef(resolved.modelRef, resolved.model, deps.models) !== undefined ? { modelRef: resolved.modelRef } : {}) };
+}
+export function inheritedParentModel(parent, catalog) {
+    return typeof parent === "string" ? resolveModel(parent, catalog) : parent;
+}
+function inheritableRef(word, seated, catalog) {
+    if (typeof word !== "string")
+        return undefined;
+    try {
+        return resolveModel(word, catalog) === seated ? word : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-export function childModelSeat(explicit, deploymentStated, parent) {
-    const model = explicit ?? (deploymentStated ? undefined : parent);
-    return { modelRole: "subagent", ...(model !== undefined ? { model } : {}) };
+export function childModelSeat(explicit, deploymentStated, parent, catalog, explicitRef) {
+    const inheritArm = explicit === undefined && !deploymentStated;
+    const model = explicit ?? (inheritArm ? inheritedParentModel(parent, catalog) : undefined);
+    const word = inheritArm ? parent : typeof explicit === "string" ? undefined : explicitRef;
+    const modelRef = model !== undefined && typeof model !== "string" ? inheritableRef(word, model, catalog) : undefined;
+    return {
+        seat: { modelRole: "subagent", ...(model !== undefined ? { model } : {}) },
+        ...(modelRef !== undefined ? { modelRef } : {}),
+    };
 }
-export function forkModelSeat(callerModel) {
-    return callerModel !== undefined ? { model: callerModel } : {};
+export function forkModelSeat(callerModel, inheritedRef, catalog) {
+    const modelRef = callerModel !== undefined && typeof callerModel !== "string" ? inheritableRef(inheritedRef, callerModel, catalog) : undefined;
+    return {
+        seat: callerModel !== undefined ? { model: callerModel } : {},
+        ...(modelRef !== undefined ? { modelRef } : {}),
+    };
 }

package/dist/agents/cross-session-judge.d.ts

@@ -1,10 +1,27 @@
 import type { AskEffective } from "../core/wiring-manifest.js";
 import { type PermissionModeClass } from "./cross-session-envelope.js";
-/** The explicit values of `crossSessionInbound`. The UI's fourth spelling `"default"` means UNSET
- *  (mode parity) and is folded to `undefined` by the resolver — it is not a distinct policy. */
-export type CrossSessionInboundSetting = "accept" | "hold" | "refuse";
+/**
+ * The explicit values of `crossSessionInbound`, loosest first: `wake` (deliver, and the HOST may start
+ * a turn on this session when its box grows), `next-turn` (deliver at the session's next turn
+ * boundary — the value the pre-7.30 spelling `accept` named), `hold` (park for a human), `refuse`.
+ * The UI's spelling `"default"` means UNSET (mode parity) and is folded to `undefined` by the resolver
+ * — it is not a distinct policy.
+ *
+ * @contract cross_session.wake_is_the_hosts_leg — `wake` is judged exactly as `next-turn` at the drain
+ * (deliver); what it adds is the HOST's leg: a host that observes a `peer_message` or `engine_frame`
+ * record appended to a session whose setting resolves to `wake` may start ONE turn on that session,
+ * bounded by `maxWakesPerHour`, and the engine promises that the turn's first drain pass ATTEMPTS the
+ * box (a claim that loses, a setting a host cannot read, an admission stop or the pass budget can
+ * still leave the record for a later boundary — every such outcome is observable, none is silent).
+ * With the budget spent, or on a host that starts no turns, `wake` degrades to `next-turn`: the record
+ * stays in the box and the next user turn reads it. The engine never starts a turn itself.
+ */
+export type CrossSessionInboundSetting = "wake" | "next-turn" | "hold" | "refuse";
 export declare const CROSS_SESSION_INBOUND_SETTINGS: readonly CrossSessionInboundSetting[];
 export declare function isCrossSessionInboundSetting(value: unknown): value is CrossSessionInboundSetting;
+/** The pre-7.30 spelling and the word it now means. A layer carrying the old spelling is READ as the
+ *  new word (never held, never invalid) and reported in `deprecatedLayers` so a host can say so once. */
+export declare const CROSS_SESSION_INBOUND_DEPRECATED_SPELLINGS: Readonly<Record<string, CrossSessionInboundSetting>>;
 /** Which layer decided the effective value. `"invalid"` = an unrecognized value was found in some
  *  layer and the fail-closed rule forced `hold` (the loud arm). */
 export type CrossSessionSettingSource = "managed" | "user" | "repo" | "invalid";
@@ -16,8 +33,9 @@ export interface CrossSessionInboundSettingLayers {
     /** The user's own layer (CC `userSettings`/`flagSettings`): consulted after managed. */
     user?: unknown;
     /** Repository layers (CC `localSettings`/`projectSettings`), in precedence order. A repo layer can
-     *  only TIGHTEN the standing value (accept < hold < refuse), whichever layer set it; it can never
-     *  loosen it. */
+     *  only TIGHTEN the standing value (wake < next-turn < hold < refuse), whichever layer set it; it can
+     *  never loosen it — so `wake` written in a repo layer never takes effect (the unset baseline is
+     *  `next-turn`, and a repo layer cannot loosen past it). */
     repo?: readonly unknown[];
 }
 export interface ResolvedCrossSessionInboundSetting {
@@ -28,6 +46,10 @@ export interface ResolvedCrossSessionInboundSetting {
      *  ⇒ the resolver applied the fail-closed rule (see `decidedBy: "invalid"`) unless the effective
      *  value was already at least as tight as `hold`. Reported so a host can warn — never swallowed. */
     invalidLayers: Array<"managed" | "user" | "repo">;
+    /** Layers that spelled a value the pre-7.30 way (`accept`): read as its current word, and reported
+     *  here so the drain announces the spelling ONCE per leg — the value in force is never silently
+     *  different from the value written. Absent from the object when empty. */
+    deprecatedLayers?: Array<"managed" | "user" | "repo">;
 }
 /**
  * CC `I` transcribed: managed beats user; repo layers may only tighten the standing value — including a

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;