@sema-agent/core 5.26.0 → 5.28.0

package/dist/core/tool-result-store.d.ts

@@ -48,8 +48,10 @@ export interface ToolResultStore {
      *     (session, tool call) is legitimately written by two different tasks of one session — the
      *     Runner shares one store across its tasks on purpose, and a BYOM brain may mint the same
      *     tool-call id in both — so stamping a `taskId` there would turn a designed sharing case into a
-     *     refusal. Write sites whose ref carries the task (the background-agent and monitor spills key
-     *     on the handle id) state it; the offload/budget/projection sites state the session only;
+     *     refusal. Every engine write site therefore states the session only (#167) — including the
+     *     background-agent and monitor spills, whose ref DOES carry the registry handle id: that id is
+     *     an addressing segment of the ref, not an ownership coordinate a read-face caller can present
+     *     (see {@link ToolResultProvenance.taskId} for the namespace rule);
      *   - an entry stored **without** provenance (written by an older engine, or by a call site that has
      *     none) stays UNOWNED: `put` never back-fills an owner onto it (that would be adoption by a party
      *     that cannot prove it wrote it) and {@link ownerOf} keeps answering `undefined`, which a read face
@@ -72,12 +74,77 @@ export interface ToolResultStore {
      * that cannot answer this cannot back a host read face at all.
      */
     ownerOf?(ref: string): Promise<ToolResultProvenance | undefined> | ToolResultProvenance | undefined;
+    /**
+     * Erase every entry this store recorded as belonging to `sessionId` — the DELETE half of the same
+     * ownership coordinate {@link ownerOf} answers on. Without it a durable backend keeps a deleted
+     * session's offloaded and spilled results on its media indefinitely: `put`/`get` alone give a
+     * deployment no way to complete a session deletion, and the engine ships no scheduler that would
+     * eventually collect them.
+     *
+     * Rules every implementation follows:
+     *   - **selection is by RECORDED PROVENANCE, never by parsing the ref.** A ref is an opaque handle:
+     *     its session segment may be folded ({@link buildToolResultRef}), refs minted before the
+     *     injective form decompose two ways (`tr_team_blue_x` is both ("team","blue_x") and
+     *     ("team_blue","x")), and a caller may mint its own. Prefix-matching a ref therefore both
+     *     misses rows and reaches rows of a NEIGHBOURING session, and over-deletion here destroys a
+     *     live session's readable bytes. The owner recorded at the winning write is the one coordinate
+     *     that means exactly one thing, and it is the same one a read face authorizes against;
+     *   - **`taskId` is ignored in the match.** A stored `{sessionId, taskId}` is a NARROWING of the
+     *     same session, not a different owner — write sites stamped one before the namespace rule
+     *     settled the shape (#167), and such rows still belong to the session being deleted;
+     *   - **an UNOWNED entry is never deleted.** A row whose write stated no provenance (an older
+     *     engine, a call site that has none, or a two-object backend interrupted between publishing
+     *     content and owner) belongs to no session this sweep can name, and it is still READABLE via
+     *     `get` — deleting it on a guess would destroy another session's output. It is counted instead
+     *     ({@link ToolResultDeletionReport.unattributable}) so the caller learns the deletion was
+     *     incomplete rather than being told a clean "done";
+     *   - **idempotent**: deleting a session with no entries is a no-op, and a repeat call after a
+     *     partial (loudly failed) sweep resumes it;
+     *   - **concurrency-tolerant**: an entry that disappears between enumeration and removal is honest
+     *     absence, not an error.
+     *
+     * Typed OPTIONAL, and deliberately NOT part of the published contract kit
+     * (`toolResultStoreContract`): unlike `ownerOf`, a backend that cannot enumerate by owner is still
+     * a usable offload store, so its absence must stay a checkable fact rather than a contract breach.
+     * Present ⇒ the store can complete a session deletion; absent ⇒ the deployment owns that gap.
+     *
+     * Implementing it does NOT make a store `retention: "managed"` — that declaration promises the whole
+     * {@link import("./retention.js").ManagedRetentionCapability} (domain enumeration, tombstones,
+     * audit receipts, scheduled execution), of which this is one caller-driven erase.
+     */
+    deleteBySession?(sessionId: string): Promise<ToolResultDeletionReport> | ToolResultDeletionReport;
+}
+/**
+ * What a {@link ToolResultStore.deleteBySession} sweep actually did. A count, not a `void`, because the
+ * sweep has a documented INCOMPLETE outcome (unowned entries it must not delete) and a caller running a
+ * session-deletion face has to be able to tell "the session's results are gone" from "some rows survive
+ * that no session can clear".
+ */
+export interface ToolResultDeletionReport {
+    /** Entries removed by THIS call. A retry of an already-swept session reports `0`, not an error. */
+    readonly deleted: number;
+    /**
+     * Entries the sweep could not attribute to ANY session and therefore left in place: stored without
+     * provenance, or with an owner record that is present but unreadable. Store-wide, not
+     * session-specific — an unowned row may or may not have been this session's, which is precisely why
+     * it cannot be deleted — so the same figure recurs on every session's sweep until a migration or an
+     * operator clears those rows.
+     */
+    readonly unattributable: number;
 }
 /**
  * Backlog #119 — WHO a stored tool result belongs to. Structured (not a single opaque string) because
  * the read face authorizes by COMPARING fields it already knows; `taskId` is present when the write site
  * has one (it is a narrowing of the session, never a substitute for it).
  *
+ * #167 (namespace rule): a stamped `taskId` must name a coordinate the read face's CALLER presents —
+ * the host's own task/run id — never an engine-internal registry handle id. A handle id lives in a
+ * namespace only the engine's in-memory registry can resolve, so an owner stamped with one compares
+ * unequal to every caller coordinate forever: the entry becomes readable by NOBODY across the wire
+ * (fail-closed, but pointlessly — the disclosure text tells the caller to read it back). The engine's
+ * own write sites all state the session only; the handle id, where a ref needs it, is an ADDRESSING
+ * segment of the ref, not part of the owner.
+ *
  * Deliberately NOT part of it: `toolCallId`. It is a retention/addressing coordinate, not an ownership
  * one — two different tool calls in one session are the same owner.
  */
@@ -262,6 +329,12 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
     /** #119 — the owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
      *  which a read face treats identically (fail-closed). */
     ownerOf(ref: string): ToolResultProvenance | undefined;
+    /** Erase this session's entries, selected on the owner recorded at the winning write (the interface
+     *  states the rules). Implemented here as well as on the durable backends so the bundled pair does
+     *  not answer the same operation two ways: the entry holds content and owner as ONE value, so the
+     *  same provenance match applies with none of the file backend's two-object bookkeeping. Deleting
+     *  from a Map while iterating it is defined (a removed key is simply not revisited). */
+    deleteBySession(sessionId: string): ToolResultDeletionReport;
     /** design/80 D-2: true when NOTHING has been offloaded — a durable suspend can then proceed safely even on
      *  this in-memory store, because a cross-replica resume has no offloaded result to deref to null. */
     isEmpty(): boolean;
@@ -316,12 +389,35 @@ export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
 /**
  * RB-469-d — the runner's clear-with-offload persist, as ONE construction point (the closure used to
- * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously),
- * but a failed put no longer strands the model with a ref pointing at nothing: a tiny lost-marker is
- * written under the same ref so the page-back face reports the true cause (C6 — "lost at write" and
- * "expired" are different answers). If the marker write fails too, the generic miss remains.
+ * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously).
+ *
+ * #167 (A-025.17) — a failed put REPORTS the loss, it never writes under the ref. The previous arm
+ * wrote a lost-marker row under the SAME ref "so the page-back face reports the true cause", and that
+ * one write carried two defects:
+ *   - **revival**: the put and a session purge can race. When the put loses, the marker write lands
+ *     AFTER the purge — re-inserting a row into a session the deployment just deleted, alive until the
+ *     backend's own TTL. A failure arm must not be able to out-write a deletion;
+ *   - **retry poisoning**: the per-request re-clear legitimately re-invokes this persist with the same
+ *     (toolCallId, fullText) — the write-once retry path. With a marker occupying the ref, that
+ *     retry's put of the REAL bytes hit the write-once no-op (same owner ⇒ keep what is there), so a
+ *     transient first failure served the marker forever even though the full text was still in hand.
+ * Now the failure arm writes NOTHING (a later persist call retries the real bytes against an empty
+ * ref) and announces the failed write loudly instead: through the deployment's structured notice sink
+ * when one is wired, else `console.warn` (the loud-bad-value announcement dialect — a silent catch
+ * here would be a silent data loss). The announcement claims only what this arm can know: THIS
+ * attempt stored nothing — the same (toolCallId, fullText) persist recurs per request (write-once
+ * idempotent re-put), so an EARLIER attempt may already have landed the row and a rejected re-put is
+ * then no loss at all; declaring "the ref is empty" here would fabricate a data-loss incident on a
+ * transient outage. Page-back of a ref no attempt ever landed serves the generic miss, which is
+ * honest: nothing is stored under it.
  */
-export declare function createOffloadPersist(store: ToolResultStore, sessionId: string): (toolCallId: string, fullText: string) => string;
+export declare function createOffloadPersist(store: ToolResultStore, sessionId: string, 
+/** Structured sink for the loss announcement, delivered through the shared guarded form
+ *  (`deliverEngineNotice`, #170): a wired FUNCTION seat REPLACES the console line, swallow-guarded
+ *  (a throwing/rejecting sink never turns an announcement into a failure); a present NON-function
+ *  seat falls back to `console.warn` plus the once-per-process seat-defect announcement; absent ⇒
+ *  `console.warn`. */
+onNotice?: (notice: import("./types.js").EngineNotice) => void): (toolCallId: string, fullText: string) => string;
 /** Backlog #119 — build the provenance a write site records, from the two coordinates every write site
  *  already has in hand. `taskId` is omitted (not `undefined`-valued) when the run declares none, so the
  *  stored shape compares equal across a durable round-trip. */
@@ -388,6 +484,11 @@ export declare function buildPreview(full: string, ref: string, sizes?: {
  * wake needs a durable store (the default in-memory store loses the full text — the preview still stands).
  * Image blocks are left untouched; only text is offloaded. Forwards the `onUpdate` progress callback so a
  * wrapped (e.g. MCP) streaming tool isn't broken.
+ *
+ * Backlog #175 — a failing store NEVER turns the wrapped tool's success into a failure: the content face
+ * falls back to the original (un-offloaded) result, and the `details` walk to a ref-free notice per lost
+ * member (see the two arms for why the degrades differ). The wrapper adds a storage step to a tool that
+ * has already run; it must not be able to invalidate that run.
  */
 export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, 
 /** RB-374① — LIVE accessor for the session's currently CALLABLE tool set (evaluated per offload,

package/dist/core/tool-result-store.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { deliverEngineNotice } from "./types.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
@@ -94,6 +95,22 @@ export class InMemoryToolResultStore {
     ownerOf(ref) {
         return this.map.get(ref)?.provenance;
     }
+    deleteBySession(sessionId) {
+        let deleted = 0;
+        let unattributable = 0;
+        for (const [ref, entry] of this.map) {
+            if (entry.provenance === undefined) {
+                unattributable++;
+                continue;
+            }
+            if (entry.provenance.sessionId !== sessionId)
+                continue;
+            this.map.delete(ref);
+            this.totalChars -= entry.content.length;
+            deleted++;
+        }
+        return { deleted, unattributable };
+    }
     isEmpty() {
         return this.map.size === 0;
     }
@@ -152,14 +169,23 @@ export function isVolatileOffloadStore(store) {
     return store instanceof InMemoryToolResultStore;
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
-export function createOffloadPersist(store, sessionId) {
+export function createOffloadPersist(store, sessionId, onNotice) {
     const provenance = toolResultProvenanceOf(sessionId);
     return (toolCallId, fullText) => {
         const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(fullText));
-        void Promise.resolve(store.put(ref, fullText, provenance)).catch((err) => {
+        const reportFailedWrite = (err) => {
             const cause = err instanceof Error ? err.message : String(err);
-            void Promise.resolve(store.put(ref, `[offload LOST at write time: ${cause} — the inline preview is all that survived]`, provenance)).catch(() => undefined);
-        });
+            const message = `tool-result offload: persisting ref "${ref}" failed (${cause}) — this write attempt stored nothing; ` +
+                `unless an earlier attempt already stored this ref, the inline preview is all that survived. ` +
+                `A later re-clear of the same result retries the write.`;
+            deliverEngineNotice(onNotice, { code: "tool_result.offload_put_failed", message, detail: { ref, sessionId, cause } });
+        };
+        try {
+            void Promise.resolve(store.put(ref, fullText, provenance)).catch(reportFailedWrite);
+        }
+        catch (err) {
+            reportFailedWrite(err);
+        }
         return ref;
     };
 }
@@ -236,7 +262,12 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
             return withDetails(res);
         const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(full));
-        await store.put(ref, full, provenance);
+        try {
+            await store.put(ref, full, provenance);
+        }
+        catch {
+            return withDetails(res);
+        }
         const images = res.content.filter((b) => b.type !== "text");
         return withDetails({ ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] });
     };
@@ -249,19 +280,34 @@ export function isOffloadedDetailReplacement(s) {
     return s.includes(`\n${OFFLOADED_DETAIL_NOTICE_PREFIX}`);
 }
 async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId, provenance) {
-    const puts = [];
-    const onStack = new Set();
     const isPlainObject = (v) => {
         if (typeof v !== "object" || v === null)
             return false;
         const p = Object.getPrototypeOf(v);
         return p === Object.prototype || p === null;
     };
+    const onStack = new Set();
+    const pending = [];
+    const rebuilt = new Set();
     const replace = (full, path) => {
         const detailRef = buildToolResultRef(sessionId, toolCallId, path, toolResultContentSegment(full));
-        puts.push(Promise.resolve(store.put(detailRef, full, provenance)));
-        return (`${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n` +
-            `${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`);
+        let done;
+        try {
+            done = Promise.resolve(store.put(detailRef, full, provenance));
+        }
+        catch (err) {
+            done = Promise.reject(err);
+        }
+        const marker = {};
+        pending.push({
+            marker,
+            done,
+            render: (stored) => `${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ` +
+                (stored
+                    ? `ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`
+                    : `persisting the remainder to this run's tool-result store failed or went unconfirmed, so no ref is offered — the text above is all this field carries]`),
+        });
+        return marker;
     };
     const memo = new Map();
     const walk = (v, segs) => {
@@ -275,14 +321,21 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
                 return done;
             onStack.add(v);
             let changed = false;
-            const next = v.map((item, i) => {
+            const len = v.length;
+            const next = new Array(len);
+            for (let i = 0; i < len; i++) {
+                if (!(i in v))
+                    continue;
+                const item = v[i];
                 const w = walk(item, [...segs, i]);
                 if (w !== item)
                     changed = true;
-                return w;
-            });
+                Object.defineProperty(next, i, { value: w, enumerable: true, writable: true, configurable: true });
+            }
             onStack.delete(v);
             const result = changed ? next : v;
+            if (changed)
+                rebuilt.add(next);
             memo.set(v, result);
             return result;
         }
@@ -303,14 +356,41 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
             }
             onStack.delete(v);
             const result = changed ? next : v;
+            if (changed)
+                rebuilt.add(next);
             memo.set(v, result);
             return result;
         }
         return v;
     };
     const value = walk(details, []);
-    await Promise.all(puts);
-    return { value };
+    const settled = await Promise.allSettled(pending.map((p) => p.done));
+    const notices = new Map();
+    pending.forEach((p, i) => void notices.set(p.marker, p.render(settled[i].status === "fulfilled")));
+    const seen = new Set();
+    const finalize = (node) => {
+        if (typeof node !== "object" || node === null)
+            return node;
+        const notice = notices.get(node);
+        if (notice !== undefined)
+            return notice;
+        if (!rebuilt.has(node) || seen.has(node))
+            return node;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                if (!Object.hasOwn(node, i))
+                    continue;
+                Object.defineProperty(node, i, { value: finalize(node[i]), enumerable: true, writable: true, configurable: true });
+            }
+            return node;
+        }
+        const obj = node;
+        for (const k of Object.keys(obj))
+            Object.defineProperty(obj, k, { value: finalize(obj[k]), enumerable: true, writable: true, configurable: true });
+        return node;
+    };
+    return { value: finalize(value) };
 }
 export function createReadToolResultTool(store) {
     return defineTool({

package/dist/core/types.d.ts

@@ -855,8 +855,11 @@ export interface ToolExecuteContext {
      * `RunInternals.onForwardEvent`) to receive a SUBAGENT's live `task_progress` ticks that otherwise stay in the
      * child's ISOLATED stream. A delegation tool threads it to the child so nested progress bubbles to one sink. This
      * is a DISPLAY channel ONLY — the child stream is NEVER merged into the parent's MODEL context, and nothing
-     * security-relevant consumes a forwarded event. Present ONLY when the deployment opted in; the Runner filters it
-     * to `task_progress` (a tool cannot push other event types). ⚠️ Forwarded ticks are UNTRUSTED display hints — any
+     * security-relevant consumes a forwarded event. Present ONLY when the deployment opted in. The tool-ctx wrapper
+     * passes `task_progress` unconditionally and — when the deployment sets `forwardSubagentEvents: true` — the
+     * transcript classes too (text_delta/reasoning_delta/tool_start/tool_end); other event types never cross it.
+     * The delegation lane's OWN tap is trusted and forwards the child's FULL event stream (bg frames tagged
+     * with bgAgentId). ⚠️ Forwarded ticks are UNTRUSTED display hints — any
      * tool holding this ctx could forge one, so a consumer validates `parentTaskId` against its known runs.
      */
     forwardEvent?: (event: TaskEvent) => void;
@@ -1731,6 +1734,11 @@ export interface TaskSpec {
      * surfaced to the operator as a config-phase warning. Protocol tools (MCP/A2A) can never collide
      * here: their wire names are namespaced (`mcp__<server>__…`) and a caller name containing `__`
      * is rejected at prepare.
+     *
+     * Mount point: the roster (with `defer`/`excludeTools`/`deferTools`) lives on this PER-TASK spec —
+     * the Runner constructor's deps carry no tool roster. Plain-JS callers beware: an unrecognized key
+     * passed to the constructor is dropped by ordinary object semantics (TypeScript callers get an
+     * excess-property error), so a roster placed there never mounts and its `defer` flags never apply.
      */
     tools?: ToolSpec[];
     /**
@@ -1871,7 +1879,9 @@ export interface TaskSpec {
      * write-capable fs tools (CC's same gate); zero cost/behavior change otherwise. `false` opts out.
      */
     lspDiagnostics?: boolean;
-    /** In-process hooks (PreToolUse/PostToolUse/UserPromptSubmit) for this task. Overrides `RunnerDeps.hooks`. */
+    /** In-process hooks for this task — the full `Hooks` lifecycle seam (tool pre/post/failure/batch
+     *  interception, prompt gating, stop pushback, compaction taps, permission-denied observation; each
+     *  member's contract is on the interface). Overrides `RunnerDeps.hooks`. */
     hooks?: import("./hooks.js").Hooks;
     /**
      * design/45 **durable suspend-on-approval** (F4). When set AND a `CheckpointStore` is wired
@@ -2745,9 +2755,11 @@ export interface TaskResult {
      * How long (milliseconds) until the deployment usage window that stopped this task frees up — the wait
      * hint a scheduler needs to decide WHEN to re-submit, rather than polling.
      *
-     * **In-presence condition:** set on exactly one terminal — `errorCode === "usage.window_exhausted"`
-     * (either moment: the entry refusal that ran nothing, or the running terminal that could not suspend).
-     * Absent everywhere else, INCLUDING when a usage window did stop the run but a higher-ranked terminal
+     * **In-presence condition:** set on exactly two terminals — `errorCode === "usage.window_exhausted"`
+     * (either moment: the entry refusal that ran nothing, or the running terminal that could not suspend)
+     * and `errorCode === "memory.admission_required"` (the prepare-throw path sets it there too — see
+     * assemble-result's accepted-code pair). Absent everywhere else, INCLUDING when a usage window did
+     * stop the run but a higher-ranked terminal
      * named the result (a budget ceiling crossed on the same turn): the reported cause is then that other
      * code, and a wait filed under it would describe something the code does not name.
      *
@@ -3260,13 +3272,16 @@ export type TaskEvent = ({
      */
     structured?: unknown;
     /**
-     * Present iff {@link isError} is true AND the harness result's `details` carried a string `code` —
-     * a machine-readable discriminator for error frames, lifted so a consumer never has to parse the
-     * (contract-stable) result text. Engine-minted vocabulary today: `"tool.not_found"` (unknown tool
-     * name) and `"gate.parked"` (an abort short-circuit poisoned this call because a durable gate
-     * parked the batch — the "Operation aborted" family). A tool's own error `details.code` (string)
-     * rides the same lift. Additive: absent on every error frame minted before this field existed,
-     * and on error results whose details carry no string code.
+     * Present iff {@link isError} is true AND the harness result's `details` carried a string
+     * discriminator — read as `details.code` first, falling back to `details.errorKind` (each must be
+     * a string; `code` wins when both are present, as the deliberate tool-chosen spelling). The
+     * `errorKind` leg is what makes a LOOP-THROWN error's frame classifiable: the loop's thrown-error
+     * fold and the resume legs write the discriminator under that name. Lifted so a consumer never
+     * has to parse the (contract-stable) result text. Engine-minted vocabulary today includes
+     * `"tool.not_found"` (unknown tool name) and `"gate.parked"` (an abort short-circuit poisoned
+     * this call because a durable gate parked the batch — the "Operation aborted" family). Additive:
+     * absent on error frames minted before this field existed, and on error results whose details
+     * carry no string discriminator under either name.
      */
     errorCode?: string;
     /**
@@ -4156,6 +4171,51 @@ export interface ProjectMemoryLoad {
         contentHash: string | null;
     }>;
 }
+/**
+ * A structured operator-facing notice ({@link RunnerDeps.onNotice}) — a fact the engine announces that
+ * is neither an error nor part of the task result: today, a configured value that was discarded in
+ * favor of another (the loud-bad-value discipline's announcement dialect). Structured so a host can
+ * FORWARD it to its own user surface instead of losing it in process stderr.
+ */
+export interface EngineNotice {
+    /** Stable machine-readable family, dot-namespaced. Current families:
+     *  - `"config.env_timeout_discarded"` — a Bash timeout knob (option or env) held a value that is not
+     *    the value in force; `detail: { knob, raw, usedMs }`.
+     *  - `"config.materialize_env_discarded"` — `SEMA_TOOL_MATERIALIZE_STRATEGY` held a value outside the
+     *    closed set in a seat where it is not in force; `detail: { raw, specStrategy? }`.
+     *  - `"tool_result.offload_put_failed"` (#167) — a clear-with-offload persist's fire-and-forget put
+     *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
+     *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so
+     *    the notice claims a failed write, not an empty ref; `detail: { ref, sessionId, cause }`.
+     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact. */
+    code: string;
+    /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
+    message: string;
+    /** Machine-readable facts of the notice (knob names, arriving values, values in force). */
+    detail?: Record<string, unknown>;
+}
+/** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
+export declare function __resetMalformedNoticeSeatAnnouncement(): void;
+/**
+ * The ONE delivery form behind every {@link RunnerDeps.onNotice} emission point (#170: the form was
+ * triplicated across the emission stations, and every copy judged the seat with `!== undefined` — so a
+ * PRESENT non-function seat (null, a config typo, an untyped host's JSON wiring) entered the wired arm,
+ * threw `TypeError` on the call, and the swallow guard silenced BOTH channels at once). Contract:
+ *  · a FUNCTION seat REPLACES the console line (a host forwarding notices to its own surface must not
+ *    show every fact twice), swallow-guarded against both failure shapes the void-typed seat admits —
+ *    a synchronous throw and an async sink's rejected promise (unhandled, that rejection is a
+ *    process-level fault): a notice sink must never turn an announcement into a failure. Deliberately
+ *    NO console fallback on sink failure: loudness ownership transfers with the wiring, and a console
+ *    echo of a transient sink failure would double-send the fact. Corollary kept as-is: stations that
+ *    de-duplicate ledger the line BEFORE this call, so a true-function sink that throws can in
+ *    principle lose a ledgered line for the process lifetime — un-ledgering after the fact would race
+ *    an async sink's late rejection and re-announce (double-send) on transient failures.
+ *  · a PRESENT NON-function seat is a bad deployment value, and #123 (loud-bad-value law) forbids
+ *    folding it to silence: the notice itself falls back to `console.warn` (no line is lost), and the
+ *    seat defect — the one fact every fallback would otherwise repeat — is announced once per process.
+ *  · an ABSENT seat prints the historic `console.warn` line verbatim (byte-compat loudness).
+ */
+export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) => void) | undefined, notice: EngineNotice): void;
 /** Runtime dependencies shared across tasks. */
 export interface RunnerDeps {
     brain: Brain;
@@ -4729,10 +4789,15 @@ export interface RunnerDeps {
      *  task's own `lspManager` overrides this. Unset ⇒ no `lsp` tool. */
     lspManager?: import("./lsp.js").LspServerManager;
     /**
-     * Default in-process hooks for all tasks (design/37): PreToolUse (rewrite/restrict args + inject
-     * context), PostToolUse (rewrite output + inject context), UserPromptSubmit (block/inject before the
-     * objective becomes a message). A task's own `hooks` overrides this. A PreToolUse hook's `allow`
-     * never bypasses `toolPolicy` — the policy is always the final say.
+     * Default in-process hooks for all tasks (design/37) — the FULL lifecycle seam of the `Hooks`
+     * interface, not just the tool-call trio: `preToolUse` (rewrite/restrict args + inject context),
+     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (block/inject before the
+     * objective becomes a message), plus `stop` (push back when the run would otherwise end and continue
+     * it), `postToolUseFailure` / `postToolBatch` / `permissionDenied` (failure, batch-boundary and
+     * deny observers), `preCompact` / `postCompact` (compaction gate + observer), `stopFailure`
+     * (API-error terminal observer) and the `preToolUseObservational` declaration flag — each member's
+     * contract is documented on the `Hooks` interface itself. A task's own `hooks` overrides this. A
+     * PreToolUse hook's `allow` never bypasses `toolPolicy` — the policy is always the final say.
      */
     hooks?: import("./hooks.js").Hooks;
     /**
@@ -4750,12 +4815,30 @@ export interface RunnerDeps {
      * - `"prompt-constitution"` — a `stableSystem` provider returned an ALREADY-assembled prompt
      *   (constitution anchor found); core passed it through un-doubled. Upgrade the provider to return
      *   only the role base (or set `replaceAll: true` to own the whole base).
+     * - `"degraded"` — the task kept running with a capability quietly reduced: a question auto-answered
+     *   with no human present, a skipped env git snapshot, a lost checkpoint-put confirmation, an
+     *   unroutable descendant notification, and similar best-effort arms. The run proceeds; the reduced
+     *   arm is what is being disclosed (`classification` names it).
+     * - `"config"` — a deployment-wiring problem detected while preparing or tearing down a task: tool
+     *   mount conflicts, refused/ignored knob values, gate-off notices, store/env teardown legs. The
+     *   broadest class by call-site count — most misconfigurations announce here rather than failing
+     *   the task.
      * - `"memory"` — a post-task memory-consolidation pass failed or skipped a malformed reconcile
      *   decision (design/41). Best-effort: the notes the model saved are kept; the task still succeeds.
      * - `"mcp"` — an MCP server failed to connect / list its tools and was skipped (fail-open, design/29);
      *   the task runs with the remaining servers' tools. One call per failed server.
      * - `"a2a"` — the A2A sibling of `"mcp"`: a declared peer's agent card could not be fetched/read, or it
      *   advertises no transport this client speaks, so the peer was skipped. One call per skipped peer.
+     * - `"interrupt-reconcile"` — repairing an interrupted session's transcript on re-entry (synthesizing
+     *   tool results for orphaned calls, flushing held session writes) failed; the run proceeds on the
+     *   unrepaired transcript.
+     * - `"suggestions"` — the best-effort follow-up-suggestions pass failed or timed out; the result
+     *   simply carries no suggestions.
+     * - `"rewind"` — the per-turn working-tree snapshot backing file rewind failed or was skipped (e.g. a
+     *   too-large root inside its cooldown window); turns without a snapshot cannot be rewound to.
+     * - `"hook"` — a deployment hook misbehaved: a callback threw, or returned a verdict it was not
+     *   allowed to (e.g. a declared-observational hook). The engine applies the hook's own documented
+     *   fallback (swallow, or fail-closed deny, per its contract) and reports the fact here.
      */
     onError?: (err: unknown, context: {
         phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "a2a" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
@@ -4769,6 +4852,21 @@ export interface RunnerDeps {
          */
         classification?: string;
     }) => void;
+    /**
+     * Structured sink for operator-facing NOTICES ({@link EngineNotice}) — announcements that are not
+     * errors and do not affect the run, which the engine otherwise prints via `console.warn` (e.g. a
+     * configured timeout/env value discarded in favor of another). When wired, a notice goes HERE
+     * INSTEAD of `console.warn` (structured replaces the console line — a host forwarding notices to
+     * its own surface must not show every fact twice); when absent, the historic `console.warn` line
+     * is printed verbatim, so an unwired build keeps its exact loudness. Swallow-guarded at every
+     * emission point (`onError`/`tracer` posture): neither a throwing sink nor an async sink's
+     * rejected promise ever affects the run. A PRESENT NON-function value (an untyped host wiring
+     * null/junk) is a bad deployment value, not a wired sink: every notice then falls back to the
+     * `console.warn` line and the seat defect itself is announced once per process (#170 — a bad seat
+     * must not silence both channels). Per-process announcement de-duplication is unchanged and
+     * sits BEFORE the sink branch — a deduplicated repeat reaches neither channel.
+     */
+    onNotice?: (notice: EngineNotice) => void;
     /** Best-effort fire-and-forget trace sink (task/turn/brain/tool); `TaskSpec.tracer` overrides per task. */
     tracer?: import("./trace.js").TracerHook;
     /**

package/dist/core/types.js

@@ -1 +1,30 @@
-export {};
+let malformedNoticeSeatAnnounced = false;
+export function __resetMalformedNoticeSeatAnnouncement() {
+    malformedNoticeSeatAnnounced = false;
+}
+export function deliverEngineNotice(onNotice, notice) {
+    if (typeof onNotice === "function") {
+        try {
+            const r = onNotice(notice);
+            if (typeof r?.then === "function") {
+                r.then(undefined, () => {
+                });
+            }
+        }
+        catch {
+        }
+        return;
+    }
+    if (onNotice !== undefined) {
+        if (!malformedNoticeSeatAnnounced) {
+            malformedNoticeSeatAnnounced = true;
+            try {
+                console.warn(`The structured notice sink (RunnerDeps.onNotice) holds ${onNotice === null ? "null" : typeof onNotice} — not a ` +
+                    `function. Notices fall back to console.warn until the wiring is fixed (omit the key, or wire a function).`);
+            }
+            catch {
+            }
+        }
+    }
+    console.warn(notice.message);
+}

package/dist/engine/loop/types.d.ts

@@ -23,7 +23,11 @@ export type ToolExecutionMode = "sequential" | "parallel";
  * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
  *
  * - "all": drain and inject every queued message at that point.
- * - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later drain points.
+ * - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later
+ *   drain points. Exception: when the oldest frame is an engine note (a task-notification sidecar
+ *   payload), every consecutive engine-note frame behind it drains with it as ONE batch, stopping at
+ *   the first non-note frame (e.g. a real user steer) — N buffered completion notices are one
+ *   boundary's worth of frames, not N sequential turns.
  */
 export type QueueMode = "all" | "one-at-a-time";
 /** A single tool call content block emitted by an assistant message. */
@@ -394,8 +398,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 }
 /**
  * Thinking/reasoning level for models that support it.
- * Note: "xhigh" is only supported by selected model families. Use model thinking-level metadata
- * from openclaw/plugin-sdk/llm to detect support for a concrete model.
+ * Note: "xhigh" is only supported by selected model families. Per-model/per-endpoint support is
+ * declared in this package's model metadata (`src/engine/llm/types.ts`): the compat blocks'
+ * accepted-tier sets (`reasoningEffortLevels` on the OpenAI-family compats, `effortLevels` on the
+ * Anthropic Messages compat — a requested tier above the declared set clamps down rather than
+ * erroring), and `Model.thinkingLevelMap`, where `null` marks a level as unsupported.
  */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export interface BashExecutionMessage {

package/dist/index.d.ts

@@ -87,7 +87,7 @@ export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, Ch
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
+export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
@@ -250,7 +250,7 @@ export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";