@sema-agent/core 7.17.7 → 7.19.0

package/dist/core/skill-listing-budget.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The skills-listing BUDGET SEAT as vocabulary: the two knobs a deployment may declare
+ * (`TaskSpec.skillListingBudgetFraction` / `TaskSpec.skillListingMaxDescChars`), the ONE reader that
+ * lowers them to the numbers the renderer measures against, and the disclosure announced when the
+ * budget costs a skill its description. The reader is pure; the announcer's only effect is the notice.
+ * `runner/synthetic-tools.ts` owns the renderer that consumes the numbers.
+ *
+ * Sibling of `tool-search-setting.ts` in shape and in posture: a value outside its domain REFUSES
+ * loudly rather than folding back to the default, because a knob that is silently dropped reads to the
+ * deployment as a knob that took effect.
+ */
+import { type EngineNotice } from "./engine-notice.js";
+/** Fraction of the model's context window the listing may spend when the deployment declares nothing. */
+export declare const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+/** Per-skill description cap (code units, ellipsis included) when the deployment declares nothing. */
+export declare const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1536;
+/** Context window assumed for a model that declares none. */
+export declare const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200000;
+/**
+ * The token→byte exchange rate this budget allocates at.
+ *
+ * @contract skills.listing_budget_exchange_rate — deliberately NOT `DEFAULT_CHARS_PER_TOKEN` (3), and
+ * the difference is directional, not an inconsistency. That constant serves the compaction/context
+ * estimators, which convert bytes→tokens and must OVER-estimate the token count to stay inside a
+ * window; a low rate is the conservative choice there. This seat converts tokens→a byte ALLOWANCE,
+ * where a low rate silently SHRINKS what the deployment may spend. Two directions, two numbers, both
+ * named. At 3 the default allowance would be 6 000 bytes rather than 8 000 — a quarter of every
+ * default deployment's listing, removed by an estimator's safety margin.
+ */
+export declare const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+/**
+ * The hard ceiling on the rendered `<skills>` block, in UTF-8 bytes.
+ *
+ * @contract skills.listing_budget_ceiling — this is a STRUCTURAL property of the delivery lane, not a
+ * policy choice and not a superset optimization. The block is not part of the system prompt: it is the
+ * body of the `skills_listing` turn attachment, and every attachment bundle is capped at
+ * `ATTACHMENT_BYTE_CAP` (8 KiB) by the boundary's `capAttachments`, which CLIPS anything over. A
+ * clipped skills frame never satisfies the run loop's intact-survival commit predicate, so the
+ * announced set never advances and the frame is re-rendered and re-clipped at every subsequent
+ * boundary — permanently. The cap is therefore enforced byte-exact over the WHOLE render (fences,
+ * headers, markers, joiners included) and MUST stay ≤ `ATTACHMENT_BYTE_CAP`; the renderer's module
+ * pins that relation, since importing the attachment module here would invert the dependency.
+ *
+ * The consequence is a one-way knob: {@link resolveSkillListingBudget} clamps the declared budget to
+ * this number, so a raised fraction (or a model with a very large window) can LOWER the listing budget
+ * but can never raise it above this ceiling. When the clamp costs a description, both numbers ride the
+ * disclosure ({@link announceSkillListingTruncation}), so the deployment reads what it asked for beside
+ * what it got instead of inferring the ceiling from a short listing.
+ */
+export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
+/** The typed refusal a budget seat outside its domain raises: a bad value never selects a smaller
+ *  listing silently, and never folds back to the default budget. */
+export declare const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+/** The notice code minted when the budget cost at least one skill its description or its line. */
+export declare const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+/** The lowered seat: the two numbers the renderer measures against, plus what was asked for. */
+export interface ResolvedSkillListingBudget {
+    /** The budget the renderer enforces over the whole block, in UTF-8 bytes — already clamped to
+     *  {@link SKILLS_BLOCK_MAX_BYTES}. */
+    blockMaxBytes: number;
+    /** What the declared fraction asked for BEFORE the structural clamp. Equal to `blockMaxBytes`
+     *  whenever the ceiling did not bind; strictly greater when it did. */
+    requestedBytes: number;
+    /** Per-skill description cap in code units, ellipsis included. */
+    descMaxChars: number;
+}
+/**
+ * The ONE reader of the two listing-budget seats.
+ *
+ * `skillListingBudgetFraction` must be a finite number in `(0, 1]` — zero is excluded deliberately: a
+ * zero budget is not "spend nothing", it is a listing every skill loses its description to, which the
+ * deployment expresses by declaring fewer skills. `skillListingMaxDescChars` must be a positive safe
+ * integer. Both absent ⇒ the documented defaults, which reproduce the pre-seat render byte for byte
+ * (`200 000 × 4 × 0.01` = 8 000 = {@link SKILLS_BLOCK_MAX_BYTES}).
+ *
+ * The window is `contextTokens ?? contextWindow`, the same physical coordinate the deferral gate
+ * measures against. A window that is absent OR unusable (non-finite, non-positive) reads as
+ * {@link SKILL_LISTING_DEFAULT_CONTEXT_TOKENS}: one rule, not a case per bad shape — a model's own
+ * declaration is judged by the model doors, and this seat must still produce a number a renderer can
+ * compare against.
+ */
+export declare function resolveSkillListingBudget(opts: {
+    fraction?: unknown;
+    maxDescChars?: unknown;
+    model?: {
+        contextTokens?: number;
+        contextWindow?: number;
+    } | undefined;
+}): ResolvedSkillListingBudget;
+/**
+ * Announce a listing the budget degraded — delivered only when a skill actually lost its description
+ * (`nameOnly`) or its line (`dropped`), so a deployment whose roster fits hears nothing.
+ *
+ * Called from the two lanes that DELIVER a listing frame (the leg's first-frame producer and the turn
+ * boundary), never from the config door: the door cannot see the deployment's
+ * `attachments.skillsListing` switch (resolved at run start), it runs per prepared task rather than per
+ * delivered listing, and a resume leg reaches only the boundary.
+ *
+ * Audience is `operator`: the person who can raise the fraction, shorten a description or remove a
+ * skill runs the deployment, not the session. `requestedBudgetBytes` rides beside `budgetBytes`
+ * precisely so the structural ceiling ({@link SKILLS_BLOCK_MAX_BYTES}) is legible at the moment it
+ * costs something — the two differ only when the clamp bound.
+ */
+export declare function announceSkillListingTruncation(onNotice: ((notice: EngineNotice) => void) | undefined, opts: {
+    /** The denominator: how many skills the DELIVERED frame set out to list — the whole roster on an
+     *  initial block, the newly announced set on a drift frame. Read off that frame's own render. */
+    total: number;
+    nameOnly: readonly string[];
+    dropped: readonly string[];
+    budget: ResolvedSkillListingBudget;
+    sessionId?: string | undefined;
+}): void;

package/dist/core/skill-listing-budget.js

@@ -0,0 +1,58 @@
+import { deliverEngineNotice } from "./engine-notice.js";
+import { describeRejectedValue } from "./tool-search-setting.js";
+export const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+export const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1_536;
+export const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200_000;
+export const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+export const SKILLS_BLOCK_MAX_BYTES = 8_000;
+export const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+export const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+function budgetRefusal(problem) {
+    const e = new Error(`TaskSpec.${problem}; a bad value refuses loudly, nothing falls back to the default listing budget.`);
+    e.code = SKILL_LISTING_BUDGET_INVALID_CODE;
+    return e;
+}
+export function resolveSkillListingBudget(opts) {
+    const { fraction, maxDescChars } = opts;
+    if (fraction !== undefined && (typeof fraction !== "number" || !Number.isFinite(fraction) || fraction <= 0 || fraction > 1)) {
+        throw budgetRefusal(`skillListingBudgetFraction: invalid value ${describeRejectedValue(fraction)} — expected a finite fraction in (0, 1]`);
+    }
+    if (maxDescChars !== undefined && (typeof maxDescChars !== "number" || !Number.isSafeInteger(maxDescChars) || maxDescChars <= 0)) {
+        throw budgetRefusal(`skillListingMaxDescChars: invalid value ${describeRejectedValue(maxDescChars)} — expected a positive integer`);
+    }
+    const declaredWindow = opts.model?.contextTokens ?? opts.model?.contextWindow;
+    const windowTokens = typeof declaredWindow === "number" && Number.isFinite(declaredWindow) && declaredWindow > 0
+        ? declaredWindow
+        : SKILL_LISTING_DEFAULT_CONTEXT_TOKENS;
+    const requestedBytes = Math.max(1, Math.floor(windowTokens * SKILL_LISTING_BYTES_PER_TOKEN * (fraction ?? SKILL_LISTING_BUDGET_FRACTION_DEFAULT)));
+    return {
+        blockMaxBytes: Math.min(requestedBytes, SKILLS_BLOCK_MAX_BYTES),
+        requestedBytes,
+        descMaxChars: maxDescChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+    };
+}
+export function announceSkillListingTruncation(onNotice, opts) {
+    const { total, nameOnly, dropped, budget } = opts;
+    if (nameOnly.length === 0 && dropped.length === 0)
+        return;
+    const clamped = budget.requestedBytes > budget.blockMaxBytes;
+    deliverEngineNotice(onNotice, {
+        code: SKILL_LISTING_TRUNCATED_CODE,
+        message: `The skills listing does not fit its ${budget.blockMaxBytes}-byte budget` +
+            (clamped ? ` (${budget.requestedBytes} bytes were declared; the listing's delivery lane caps it at ${SKILLS_BLOCK_MAX_BYTES})` : "") +
+            `: ${nameOnly.length} of ${total} are listed name-only` +
+            (dropped.length > 0 ? `, and ${dropped.length} did not fit the listing at all` : "") +
+            `. The \`Skill\` tool still serves every one of them. Raise skillListingBudgetFraction, lower` +
+            ` skillListingMaxDescChars, or declare fewer skills.`,
+        detail: {
+            budgetBytes: budget.blockMaxBytes,
+            requestedBudgetBytes: budget.requestedBytes,
+            descMaxChars: budget.descMaxChars,
+            total,
+            kept: total - nameOnly.length - dropped.length,
+            nameOnly: [...nameOnly],
+            dropped: [...dropped],
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        },
+    });
+}

package/dist/core/swappable-deps.d.ts

@@ -38,12 +38,14 @@ import type { RunnerDeps } from "./runner-deps.js";
  *                 current bindings are re-applied over the new catalog; present (including `undefined`)
  *                 ⇒ replaced.
  *  - `readFace` — the deployment's read-face declaration ({@link RunnerDeps.readFace}); screened by the
- *                 same value gate every prepare applies (`assertReadFaceValue`: `"open"` | `"roots"`
+ *                 same value gate every prepare applies (`assertContainmentFaceValue`: `"open"` | `"roots"`
  *                 | absent, anything else refused loudly). The RESOLVED face of a leg is still the
  *                 resolver's business (task seat, governance, the read-only mount); the swap changes the
  *                 deployment seat that resolution reads.
+ *  - `writeFace` — the deployment's write-face declaration ({@link RunnerDeps.writeFace}); the read seat's
+ *                 twin (same value gate, same in-flight snapshot rule, its own notice) and independent of it.
  */
-export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace"];
+export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace", "writeFace"];
 export type SwappableDepSeat = (typeof SWAPPABLE_DEP_SEATS)[number];
 /** The candidate a swap takes: the swappable seats of {@link RunnerDeps}, each optional (presence = instruction). */
 export type SwappableDeps = Pick<RunnerDeps, SwappableDepSeat>;
@@ -52,12 +54,13 @@ export declare function isSwappableDepSeat(k: unknown): k is SwappableDepSeat;
 /**
  * Which notice a seat's successful swap is announced under — the disposition table over the set (a seat
  * with no row does not compile: {@link SwapNoticeTableCoversEverySeat}). `models` and `tiers` share the
- * catalog-generation line (one swap, one line, both counts); the read face has its own.
+ * catalog-generation line (one swap, one line, both counts); each containment face has its own.
  */
 export declare const SWAP_SEAT_NOTICE: {
     readonly models: "config.models_swapped";
     readonly tiers: "config.models_swapped";
     readonly readFace: "config.read_face_swapped";
+    readonly writeFace: "config.write_face_swapped";
 };
 /** The fence over the notice table: `never` while every seat has a row. */
 export type SwapNoticeTableCoversEverySeat = AssertAllKeysHandled<Exclude<SwappableDepSeat, keyof typeof SWAP_SEAT_NOTICE>>;
@@ -66,7 +69,7 @@ export type SwapNoticeTableCoversEverySeat = AssertAllKeysHandled<Exclude<Swappa
 export interface ScreenedSwappableDeps {
     readonly seats: readonly SwappableDepSeat[];
     /** A fresh plain object: the screened value of every present seat (`models`/`tiers` shallow-copied,
-     *  `readFace` the screened word; an explicit `undefined` is kept as a PRESENT own key so the door can
+     *  `readFace`/`writeFace` the screened word; an explicit `undefined` is kept as a PRESENT own key so the door can
      *  tell "clear this seat" from "not named"). */
     readonly candidate: SwappableDeps;
 }
@@ -83,8 +86,7 @@ export interface ScreenedSwappableDeps {
  * announcement, which runs AFTER the write — a throw there would have left a half-announced swap in
  * force). The prepare doors read their deps seats the same way.
  *
- * The per-seat gate is the SAME one the seat's prepare-time reader applies (`readFace` ⇒
- * `assertReadFaceValue` with the deployment-seat name a prepare door uses — one value, one loudness, one
- * seat name on every leg), so a value the door admits is a value every later prepare admits.
+ * The per-seat gate is the SAME one the seat's prepare-time reader applies (both face seats ⇒
+ * `assertContainmentFaceValue`), so a value the door admits is a value every later prepare admits.
  */
 export declare function screenSwappableDeps(next: unknown): ScreenedSwappableDeps;

package/dist/core/swappable-deps.js

@@ -1,5 +1,5 @@
-import { assertReadFaceValue } from "../tools/fs/read-face.js";
-export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace"];
+import { assertContainmentFaceValue } from "../tools/fs/containment-face.js";
+export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace", "writeFace"];
 const SWAPPABLE_DEP_SEAT_SET = new Set(SWAPPABLE_DEP_SEATS);
 export function isSwappableDepSeat(k) {
     return SWAPPABLE_DEP_SEAT_SET.has(k);
@@ -8,6 +8,7 @@ export const SWAP_SEAT_NOTICE = {
     models: "config.models_swapped",
     tiers: "config.models_swapped",
     readFace: "config.read_face_swapped",
+    writeFace: "config.write_face_swapped",
 };
 export function screenSwappableDeps(next) {
     if (next === null || typeof next !== "object" || Array.isArray(next)) {
@@ -43,7 +44,10 @@ export function screenSwappableDeps(next) {
                 candidate.tiers = v === undefined ? undefined : { ...v };
                 break;
             case "readFace":
-                candidate.readFace = assertReadFaceValue(v, "readFace (deployment seat)");
+                candidate.readFace = assertContainmentFaceValue(v, "read", "deps");
+                break;
+            case "writeFace":
+                candidate.writeFace = assertContainmentFaceValue(v, "write", "deps");
                 break;
             default: {
                 const _exhaustive = seat;

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

@@ -89,24 +89,19 @@ export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "c
 /**
  * WHY a retry wait is happening, as a closed, provider-NEUTRAL bucket — the companion to
  * {@link BrainStatusPhase}, which says what the brain is doing about it. A consumer rendering an
- * unattended progress line ("no answer for three minutes") needs the reason, and until this existed the
- * only carriers of it were the HTTP status and the syscall code, neither of which crossed this channel
- * at the time. (The status has since gained its own seat, {@link BrainStatus.errorStatus}; this bucket
- * remains the reason a consumer RENDERS, and it is the only carrier for the transport classes, which
- * have no status at all.) Values are about the SHAPE of the failure, never its provider taxonomy:
+ * unattended progress line ("no answer for three minutes") needs the reason. (The status has its own seat,
+ * {@link BrainStatus.errorStatus}; this bucket is the reason a consumer RENDERS and the only carrier for the
+ * transport classes, which have no status at all.) Values are about the SHAPE of the failure, never its
+ * provider taxonomy:
  *  - `connect_refused` — the attempt got a definite negative about the target itself (nothing accepts
  *    at that address, or the name has no address). This is the class the SHORT retry lane serves.
  *  - `transport`      — any other transport-level failure: a connect timeout, a reset, a mid-stream
  *    tear. No verdict about the target; the full ladder applies.
  *  - `stall`          — no failure was observed on the link at all: THIS process cancelled its own
  *    request because one of its stall watchdogs reached its deadline while the stream produced
- *    nothing. The distinction from `transport` is WHO GAVE UP, and nothing more: a `transport` frame
- *    reports something that happened to the call, a `stall` frame reports a local deadline. It is not
- *    a verdict on the remedy — a blackholed connection (no reset, no close) produces silence, and
- *    silence is what a watchdog measures, so a `stall` can still turn out to be a network fault; what
- *    it always tells you truthfully is that the request was cancelled here, at a configured deadline,
- *    rather than lost out there. Reporting these as `transport` asserted the opposite — that the link
- *    had dropped — when nothing about the link was known at all.
+ *    nothing. The distinction from `transport` is WHO GAVE UP: a `transport` frame reports something
+ *    that happened to the call, a `stall` frame reports a local deadline. It is not a verdict on the
+ *    remedy — a blackholed connection produces silence too, and silence is what a watchdog measures.
  *  - `rate_limit`     — the provider asked the caller to slow down.
  *  - `server`         — the provider reported a failure on its own side.
  *  - `http`           — a response the status predicate calls terminal, retried anyway because the
@@ -138,15 +133,12 @@ export interface BrainStatus {
      * output-cap re-send, which takes no backoff).
      *
      * WHY IT IS PRODUCED HERE rather than derived by the consumer: `Date.now() + retryInMs` is only
-     * correct for a reader that received the frame instantly. A consumer several process hops away
-     * (serving layer → client) recomputes a deadline already shifted by the transit, so a countdown
-     * built that way restarts on every re-announced slice instead of converging. The producer is the
-     * only party that can state the instant, so it does.
+     * correct for a reader that received the frame instantly, so a countdown built several process hops
+     * away restarts on every re-announced slice instead of converging.
      *
-     * CLOCK DOMAIN, stated to remove the ambiguity: WALL CLOCK (`Date.now()`, epoch ms), NOT a
-     * monotonic reading. A consumer must not compare it against its own monotonic timers, and must
-     * treat it as approximate across a clock adjustment or a machine boundary — {@link retryInMs} stays
-     * the authoritative RELATIVE quantity, and this seat is the absolute convenience derived from it.
+     * CLOCK DOMAIN, stated to remove the ambiguity: WALL CLOCK (`Date.now()`, epoch ms), NOT a monotonic
+     * reading. A consumer must not compare it against its own monotonic timers, and must treat it as
+     * approximate across a clock adjustment — {@link retryInMs} stays the authoritative RELATIVE quantity.
      */
     retryAtMs?: number;
     /** On a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
@@ -261,13 +253,10 @@ export type TaskEvent = ({
     /**
      * The assistant's streaming PROSE SEGMENT is COMPLETE: the model closed the text content
      * block whose bytes just streamed as `text_delta`s. This is the explicit segment boundary a
-     * REMOTE consumer needs so it never has to guess segment ends from wire silence (the idle-flush
-     * heuristic this retires cut one slow-model reply into N fragments). CC-aligned: CC's agent
-     * stream yields each finished content block as its own assistant-message unit at the provider's
-     * `content_block_stop` — block completion IS the segmentation signal there; a single-process
-     * consumer reads it off the provider stream natively, and this event is that same boundary
-     * surfaced on the TaskEvent wire (CC pays the byte cost of re-carrying the block at the stop;
-     * so does this event's `content`).
+     * REMOTE consumer needs so it never has to guess segment ends from wire silence. CC-aligned: block
+     * completion IS the segmentation signal there (CC's agent stream yields each finished content block at
+     * the provider's `content_block_stop`), and this event is that same boundary surfaced on the TaskEvent
+     * wire.
      *
      * `content` = the authoritative FULL text of the completed segment (byte-equal to that
      * segment's accumulated deltas, from the brain's own accumulation) — a consumer commits the
@@ -292,6 +281,61 @@ export type TaskEvent = ({
     toolName: string; /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
     label?: string;
     args: unknown;
+} & TaskEventIdentity) | ({
+    /**
+     * A LIVENESS TICK for a tool call that is still running. Emitted on the run's own queue between this
+     * call's `tool_start` and `tool_end`, under the same ordering law as every other content frame, and
+     * forwarded to a parent's display sink under the SAME opt-in as those two
+     * (`TaskSpec.forwardSubagentEvents`).
+     *
+     * ONE FRAME, not two: CC 2.1.259 splits this into a per-tool `tool_heartbeat` plus Bash's own
+     * `bash_progress`; this engine mints the single shape and lets the OUTPUT KEYS be what is conditional.
+     * Registered divergence.
+     *
+     * @contract tool_progress.cadence — AT MOST one frame per second per tool call, enforced at the mint over
+     * ALL producers rather than inside each one (a producer's own timer is a sampling clock, not the contract),
+     * and a call's first frame is never earlier than one interval after it entered execution. A call that
+     * finishes inside one interval emits NO frame at all — this frame's absence is never evidence that a call
+     * did not run, and a consumer must not expect one per `tool_start`.
+     *
+     * @contract tool_progress.ephemeral — LIVE ONLY, like `task_progress`/`status`: core never persists this
+     * frame (no session-tree entry, no checkpoint state, no resume replay), and a resumed leg re-ticks from
+     * its own clock. A consumer wanting a DURABLE record of a long call keeps {@link elapsedTimeSeconds} —
+     * never {@link output}, untrusted process bytes bounded for a pane (the tool's result is the kept face).
+     *
+     * Additive and ignorable: a consumer switching on event type and dropping unknown members is unchanged,
+     * and no gate, policy, memory or model-context path reads this frame.
+     */
+    type: "tool_progress";
+    /** The still-running call's id — the join key to its own `tool_start`/`tool_end`. */
+    toolCallId: string;
+    /** The running tool's name (the `tool_start` value verbatim). */
+    toolName: string;
+    /** Whole seconds this tool call has been running, floored and MONOTONIC across its frames. ONE ORIGIN per
+     *  call, stamped by the mint rather than by whichever producer emitted — the call's entry into execution,
+     *  earlier than a shell command's spawn. It does NOT equal the `tool_end` duration. */
+    elapsedTimeSeconds: number;
+    /**
+     * The TAIL of what the command has written so far (stdout and stderr interleaved in arrival order),
+     * bounded by the mint to a small number of trailing lines — a live pane, never a log.
+     *
+     * UNTRUSTED RAW, exactly as `tool_end.output`: process output that may carry secrets, paths or PII;
+     * core bounds only its SIZE, and a consumer MUST redact before persisting or displaying it. Never
+     * re-feed it to a model — it is a moving, truncated window.
+     *
+     * ABSENT, together with {@link totalLines} and {@link totalBytes}, exactly when the call has produced
+     * NO output through this environment — it printed nothing (`sleep 3`), or the environment does not
+     * stream (a buffered remote `exec` never invokes the output callbacks). The three ride or stay away
+     * together: present = "output has been observed", absent = "none has been observed", never
+     * "unchanged since the last frame".
+     */
+    output?: string;
+    /** Newlines observed in the command's output so far (≥ the line count of {@link output}, which is
+     *  only its tail). Rides iff {@link output} does — see its absence law. */
+    totalLines?: number;
+    /** Bytes observed in the command's output so far, counted BEFORE the tail bound, so it keeps
+     *  growing after {@link output} stops being able to. Rides iff {@link output} does. */
+    totalBytes?: number;
 } & TaskEventIdentity) | ({
     type: "tool_end";
     toolCallId: string;
@@ -433,8 +477,7 @@ export type TaskEvent = ({
      * faces — so a renderer never branches on prose to tell "a person refused" from "the window closed".
      *
      * WHERE IT COMES FROM — never inferred here: the gate mints it at its exit, the decide lane mints it
-     * from the host's decision facts joined with the row's persisted origin. Core does not derive it
-     * from `isError`, from the result, or from anything a tool or a post-tool hook can write.
+     * from the host's decision facts joined with the row's persisted origin.
      *
      * ABSENT on every frame of a call the gate never saw (a tool call on an unarmed gate, a deferred
      * re-issue, a reconcile-recovered orphan). A gated call's frame ALWAYS carries it — an absence is
@@ -485,6 +528,14 @@ export type TaskEvent = ({
     usedTokens: number;
     windowTokens: number;
     compactAtTokens: number;
+    /**
+     * Additive — the leg's system prompt broken down by pack SECTION. Meaning, and the readings it
+     * forbids, are owned by `contextUsageSections` (`prompt-assembly/section-usage.ts`, `@contract
+     * context_usage.sections`): PREPARE-TIME estimates in a different coordinate from {@link usedTokens},
+     * never compared to {@link compactAtTokens}. Absent when the leg assembled no section IR — "no section
+     * view", never "the sections weigh nothing".
+     */
+    sections?: readonly import("../prompt-assembly/section-usage.js").ContextUsageSection[];
 } & TaskEventIdentity) | ({
     type: "turn_end";
     /**
@@ -907,6 +958,22 @@ export type TaskEvent = ({
      */
     type: "tool_roster_delta";
     delta: import("./tool-roster.js").ToolRosterDelta;
+} & TaskEventIdentity) | ({
+    /**
+     * This leg's DEFERRAL CENSUS: which mounted tools ship as name-only placeholders, which the model has activated, and the policy
+     * (`RunnerDeps.toolSearch`) that decided it — meaning owned by `ToolDisclosureSnapshot` (`runner/tool-disclosure.ts`). EXISTS ONLY ON A LEG THAT
+     * DEFERS SOMETHING: an empty deferred set emits no frame, and that absence reads as "nothing was deferred here", never "no disclosure in this build"
+     * and never "unknown". First frame = the leg-start census, right after `wiring_manifest` — `activated` is EMPTY on a fresh leg and, on a RESUMED one,
+     * whatever the engine reseeded (never read a non-empty first census as "this leg activated them"); every later frame = a census that CHANGED, i.e. an
+     * activation landed (either lane — one section, one census). WHOLE SNAPSHOT: replace your copy. `deferred` is frozen at prepare; lists sorted.
+     */
+    type: "tool_disclosure";
+    policy: import("./tool-search-setting.js").ToolSearchPolicy;
+    /** Meaning owned by `ToolDisclosureSnapshot.thresholdPercent`: absent under `always` / `never`, where
+     *  no threshold was consulted, and an absence must not be read as "the default percent". */
+    thresholdPercent?: number;
+    deferred: readonly string[];
+    activated: readonly string[];
 } & TaskEventIdentity) | {
     type: "done";
     result: TaskResult;

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

@@ -118,18 +118,14 @@ export interface TaskNotificationPayload {
      *  preconditions, so the claim and the next SendMessage agree. Lets the parent decide
      *  continue-vs-restart without trial-and-error. Background-agent lane only. */
     resumable?: boolean;
-    /** A cross-channel correlation key for
-     *  ONE completion event. The same task's completion fans out across several independent read faces
-     *  today (this live notification frame, a durable inbox entry, and the `TaskOutput` poll projection)
-     *  — a consumer previously had to reconstruct "are these the same completion?" from weaker signals
-     *  (task_id + status + timing). Minted ONCE per completion, fill-once (first writer wins), on the
+    /** A cross-channel correlation key for ONE completion event — the same task's completion fans out
+     *  across several independent read faces (this live notification frame, a durable inbox entry, and the
+     *  `TaskOutput` poll projection). Minted ONCE per completion, fill-once (first writer wins), on the
      *  same task-registry handle/record every read face serves from — see
      *  {@link "./task-registry.js".UnifiedTaskOutput.completionId} for the shared contract (open-shape
      *  `string`, absent until terminal settle, absent on a pre-P1-3 core build). Deliberately ABSENT on
-     *  the `"external"` lane (`TaskStream.notify()`) — that lane has its own caller-supplied `seq`
-     *  correlation key (confirmed posture) and no registry-side settle point to
-     *  mint this from; core-minting one there would create two competing correlation keys on the same
-     *  frame. */
+     *  the `"external"` lane (`TaskStream.notify()`): that lane has its own caller-supplied `seq`
+     *  correlation key and no registry-side settle point to mint this from. */
     completionId?: string;
     /** design/176 — the peer-message marker + hop-chain carrier, present ONLY on payloads minted by
      *  the SendMessage delivery legs (the engine's single peer-carrier producer). Three uses: it
@@ -331,13 +327,12 @@ export declare function renderCrossSessionMessageFrame(frame: NonNullable<TaskNo
 export declare function renderCrossSessionNoticeLine(notice: NonNullable<TaskNotificationPayload["crossSessionNotice"]>): string;
 export declare function renderTaskNotificationXml(n: TaskNotificationPayload): string;
 /**
- * The BETWEEN-TURNS pending lane. A task notification born while NO turn is
- * live (the run's notification lane is torn down, or the harness rejected the injection because the agent
- * was already idle) used to be silently unreachable: the Monitor main use-case (long-watch events between
- * turns) and the stoppedBy notifications (a killed-evicted child whose registry row is already gone)
- * both land exactly in that window. This store parks them PER SESSION; the session's next run drains it at
- * start and rides the payloads down the SAME notification lane (steer at the next turn boundary), so
- * in-turn and between-turn events keep one shape.
+ * The BETWEEN-TURNS pending lane. A task notification born while the session has NO live lane at all
+ * (every run of it is over, or the one that is live rejected the injection because its agent was
+ * already idle) is parked PER SESSION; the session's next run drains it at start and rides the payloads
+ * down the SAME notification lane (steer at the next turn boundary), so in-turn and between-turn events
+ * keep one shape. A frame whose session DOES have a live lane never reaches this store —
+ * {@link SessionLiveNotificationLanes} takes it to that run's next turn boundary.
  *
  * Bounds (1.254 F4 家族纪律): per-task cap + per-session cap + session-count cap, oldest dropped first —
  * preferring NON-terminal victims (an exit/killed terminal is the single most load-bearing notification of
@@ -416,8 +411,108 @@ export interface DrainedPendingNotifications {
      */
     droppedWholeSession?: number;
 }
+/**
+ * One run's seat in {@link SessionLiveNotificationLanes}: hand this payload to that run's live
+ * injection queue. Four answers:
+ *  · `"taken"` — newly enqueued on that run's lane; `onDisposition` (when supplied) is settled by the
+ *    queue with the real outcome. Nothing is DELIVERED yet: the boundary can still refuse it;
+ *  · `"pending"` — that lane already holds this exact key IN FLIGHT. `onDisposition` is NOT settled
+ *    here: the in-flight entry owns the OUTCOME and this copy is no delivery;
+ *  · `"duplicate"` — that stream has already DELIVERED this exact frame: nothing to enqueue, nothing
+ *    to park; `onDisposition` is NOT settled, the word belongs to the caller;
+ *  · `"unavailable"` — the lane can no longer take anything; the caller tries the next lane, and
+ *    finally the parked store.
+ */
+export type LiveNotificationLane = (payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: "queued" | "parked") => void) => "taken" | "pending" | "duplicate" | "unavailable";
+/** One run's seat: its two entry points, plus the two bookkeeping verbs its owner drives. */
+export interface LiveNotificationLaneSeat {
+    /**
+     * The entry for THIS run's OWN producers. It accepts whenever the lane is live: the frame is
+     * enqueued (so the queue's own dedup folds a retry), the wire event goes out, and if the agent turns
+     * out to be idle the steer's rejection parks it. No route-specific condition is allowed onto it.
+     */
+    readonly take: LiveNotificationLane;
+    /**
+     * The entry {@link SessionLiveNotificationLanes} holds (stable identity for register/withdraw) — a
+     * frame ANOTHER run of the session is offering. It additionally requires that this lane can deliver
+     * at this instant: accepting a foreign frame and then refusing it asynchronously strands it behind
+     * this run's own parked-store intake, whereas declining hands it straight back to the router.
+     */
+    readonly takeAsDestination: LiveNotificationLane;
+    /**
+     * Record that this lane HANDED this frame to the session route: it accepted the frame and then
+     * could not deliver it (its agent was already idle). The key must never come back — the queue's
+     * dedup set keeps it, so a second enqueue would be reported as ACCEPTED while nothing delivers or
+     * parks it. Remembered per LANE rather than per delivery, so a route of any length terminates on the
+     * parked store. A lane that is no longer live records NOTHING (it already answers "unavailable" by
+     * liveness). What IS remembered is bounded exactly like the queue's own dedup set — same cap, same
+     * insertion-order eviction, and an evicted key is as re-deliverable here as it is there.
+     */
+    handOff(payload: TaskNotificationPayload): void;
+    /** Drop that memory when the lane stops; every later answer is "unavailable" by liveness anyway. */
+    release(): void;
+}
+/**
+ * Build one run's lane seat over its injection queue: the SINGLE enqueue site a frame reaches,
+ * whether the run produced it or another run of the same session routed it here — so the tier
+ * routing, the dedup key and the already-delivered fold cannot fork between the two arrivals.
+ */
+export declare function createLiveNotificationLane(seat: {
+    /** The run's injection queue; its subscriber is what routes an accepted frame by tier. */
+    queue: SystemInjectionQueue;
+    /**
+     * Is the agent in a turn, so the boundary a frame would ride actually exists? Read LIVE, and read
+     * ONLY by {@link LiveNotificationLaneSeat.takeAsDestination}.
+     */
+    canTakeNow: () => boolean;
+    /**
+     * Has this lane NOT been torn down? The gate for this run's own producers, and the gate on
+     * remembering a handoff: a lane merely BETWEEN turns may take again in a moment, so what it handed
+     * away must still be remembered; a lane that is over will never take anything.
+     */
+    isLive: () => boolean;
+    /** Keys this run's stream already delivered at turn-open (the cross-layer double-park fold). */
+    alreadyDelivered: (dedupKey: string) => boolean;
+}): LiveNotificationLaneSeat;
+/**
+ * The per-session LIVE LANE registry — the destination half of {@link PendingSessionNotifications}.
+ * A run registers its injection lane once its session anchor is bound and withdraws it the moment the
+ * lane stops accepting (a clean end, a throw, an abort — the run's own teardown), so an entry's
+ * lifetime is exactly the lane's liveness.
+ *
+ * The key is the session the producing lane is ANCHORED to, so this is never a cross-session route: a
+ * peer session's live run is not a destination, and a delegated child's own session is not its
+ * parent's. A session with no live lane keeps the parked form unchanged.
+ *
+ * Several lanes may sit under one key: the NEWEST registration is tried first — "the session's current
+ * run" — and every lane is tried once, so a lane that has stopped, or that has already handed this very
+ * frame away, is passed over rather than swallowing it. A lane that refused a frame therefore cannot be
+ * reached by it again, which is what makes a route of any length terminate on the parked store.
+ */
+export declare class SessionLiveNotificationLanes {
+    private readonly lanes;
+    register(sessionId: string, lane: LiveNotificationLane): void;
+    /** Idempotent (a lane withdraws at its stop AND again at its outermost teardown). The key is dropped
+     *  with its last lane so an idle process holds no per-session entry. */
+    unregister(sessionId: string, lane: LiveNotificationLane): void;
+    /**
+     * Offer the payload to the session's live lanes, newest first. The caller's OWN lane is not
+     * special-cased: a lane that just refused this frame reports `"unavailable"` for it from then on.
+     */
+    deliver(sessionId: string, payload: TaskNotificationPayload, priority: SystemInjectionPriority, opts?: {
+        onDisposition?: (d: "queued" | "parked") => void;
+    }): "taken" | "pending" | "duplicate" | "unavailable";
+    /** Sessions holding at least one live lane (observability + the tests' rollback detector). */
+    get size(): number;
+}
 export declare class PendingSessionNotifications {
     private readonly sessions;
+    /**
+     * The LIVE half of the same question this store answers. Together they are one seat — "where does a
+     * notification addressed to session S go?" — with two answers: the session's live lane when it has
+     * one, this parked queue when it does not. One object, one lifetime, one key (the session id).
+     */
+    readonly liveLanes: SessionLiveNotificationLanes;
     /** Whole sessions evicted by {@link MAX_PENDING_SESSIONS} (their pendings were never delivered). */
     droppedSessions: number;
     /**
@@ -438,8 +533,39 @@ export declare class PendingSessionNotifications {
      *  design/373 §3.5: the batch comes out PRIORITY-MAJOR (stable sort — pend order within a class;
      *  a no-priority record ranks as later), the idle-dequeue min-value-first form. */
     drain(sessionId: string): DrainedPendingNotifications | undefined;
+    /**
+     * Keys a live lane of this session has already put in front of a model (the delivered half of the
+     * ledger below). Kept beside the parked keys because the WINDOW is the session's, not any one run's:
+     * the destination run's own queue dedup dies with it. Released at {@link drain}, exactly like the
+     * parked keys. Bounded like everything else here; an evicted key only ever costs a duplicate in the
+     * extreme, never a loss.
+     */
+    private readonly routed;
+    /**
+     * Does this session ALREADY own this exact frame — parked, or routed onto a live lane? Only one of
+     * the two may hold a key: a producer retrying a frame the session has already taken must FOLD rather
+     * than be handed to whichever run has since gone live, which would deliver it there and again at the
+     * next drain. Callers ask BEFORE routing and BEFORE parking.
+     */
+    holdsKey(sessionId: string, dedupKey: string): boolean;
+    /** Record that this session has DELIVERED this frame — see {@link routed}. Written at ONE place, the
+     *  harness's consumption sink (the step where a queued frame enters the model's input), so the record
+     *  can never run ahead of the delivery it claims. */
+    markDelivered(sessionId: string, dedupKey: string): void;
     get size(): number;
 }
+/**
+ * WHERE A FRAME ADDRESSED TO ONE SESSION GOES — the single decision, so the two addresses that ask it
+ * (a run's own session, and the delegation tree's root anchor) cannot drift apart. Three outcomes:
+ *  · the session ALREADY OWNS the key (parked, or routed onto a live lane) ⇒ fold — neither route it
+ *    nor park a second copy; `"parked"` is the word a folded repeat has always been given;
+ *  · a live lane takes it ⇒ it rides that run's next turn boundary. This decision records NOTHING in
+ *    the ledger: a destination that ACCEPTED a frame can still refuse it at its boundary and park it
+ *    then, so only the lane that actually delivers writes ownership
+ *    ({@link LiveNotificationLaneSeat.markDelivered});
+ *  · nothing can take it ⇒ park, carrying the tier, for the session's next run.
+ */
+export declare function routeOrParkNotification(store: PendingSessionNotifications, sessionId: string, payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: "queued" | "parked") => void): void;
 /**
  * Delivery-side overflow disclosure: fold the per-task drop counts into the drained payloads. Two
  * carrier shapes, chosen per survivor: