@sema-agent/core 5.26.0 → 5.28.0

package/dist/index.js

@@ -68,7 +68,7 @@ export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } 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, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } 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, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } 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, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -229,9 +229,11 @@ export interface RunWorkflowToolDeps {
      *  has inherited this hook since [893]④a; the workflow lane never did — the governance whitelist
      *  rightly blocks SCRIPTS from setting it, but host inheritance is a different lane. */
     parentGetApiKeyAndHeaders?: import("../core/types.js").TaskSpec["getApiKeyAndHeaders"];
-    /** The HOST run's display sink (its `RunInternals.onForwardEvent`, already filtered to `task_progress`
-     *  by the runner's ctx wrapper) — threaded via `startWorkflow` into every spawned agent's trusted
-     *  internals so a workflow child's progress ticks bubble to the deployment's one sink, the same
+    /** The HOST run's display sink (its `RunInternals.onForwardEvent` behind the runner's ctx wrapper:
+     *  `task_progress` always, plus the children's content events — `text_delta`/`reasoning_delta`/
+     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `forwardSubagentEvents: true`) — threaded via `startWorkflow` into every spawned agent's trusted
+     *  internals so a workflow child's events bubble to the deployment's one sink, the same
      *  channel a `createSubagentTool` delegation threads. Display-only; absent ⇒ ticks stay in each
      *  child's own stream. (A dep, not read off the execute ctx: the mounted tool's `AgentTool.execute`
      *  wrapper builds a minimal `{toolCallId, signal}` ctx — the rich-ctx injection only wraps

package/dist/orchestration/workflow.d.ts

@@ -31,8 +31,9 @@ export declare const WORKFLOW_SUBAGENT_APPEND_SCHEMA = "---\n\nNOTE: You are run
  * F4 agentType (CC 198 锚 pretty.js:446608-446627): resolve `opts.agentType` against the registry
  * (deployment SHADOW over built-ins) and fold the definition into the child spec — persona as
  * `systemPrompt` (so {@link withWorkflowChildPersona} composes the return-contract NOTE via the
- * custom-persona APPEND arm = CC `O0m` semantics), model/thinking/maxTurns/skills/memory when the spec
- * didn't pin them, and allow/denyTools as a ToolPolicy (combined deny-wins with any spec policy).
+ * custom-persona APPEND arm = CC `O0m` semantics), model/thinking/maxTurns/skills/memory/
+ * memoryPersistenceCapable when the spec didn't pin them, and allow/denyTools as a ToolPolicy
+ * (combined deny-wins with any spec policy).
  * The definition is DEPLOYMENT-TRUSTED (registry-declared, not script-authored), so its model bypasses
  * the script-facing modelName allowlist by design — same trust tier as the Agent tool's registry.
  */
@@ -382,10 +383,12 @@ export interface RunWorkflowOptions {
      *  from ctx): every spawned agent composes the same closure (codex F2a). */
     parentCenterArtifactDigest?: string;
     parentCenterSourceRevision?: string;
-    /** The launching run's display sink (`RunInternals.onForwardEvent`, already filtered by the runner to
-     *  `task_progress`) — threaded into every spawned agent's trusted internals so the children's progress
-     *  ticks bubble out of their isolated streams to the deployment's one sink (fleet footer/monitor rows).
-     *  Display-only; absent ⇒ ticks stay in each child's own stream. */
+    /** The launching run's display sink (`RunInternals.onForwardEvent` behind the runner's ctx wrapper:
+     *  `task_progress` always, PLUS the children's content events — `text_delta`/`reasoning_delta`/
+     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `forwardSubagentEvents: true`) — threaded into every spawned agent's trusted internals so the
+     *  children's events bubble out of their isolated streams to the deployment's one sink (fleet
+     *  footer/monitor rows). Display-only; absent ⇒ ticks stay in each child's own stream. */
     onForwardEvent?: (event: TaskEvent) => void;
     /** Parent effective-policy inheritance (tighten-only): the HOST task's evaluated gate chain
      *  (`ToolExecuteContext.inheritedGateForChildren()` — its session rules + toolPolicy/frozen onAsk +

package/dist/stores/file/checkpoint-store.d.ts

@@ -1,7 +1,8 @@
 import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
 export interface FileCheckpointStoreOptions {
     /** When false, an `appendLine` for a state transition is NOT fsync'd. The checkpoint COMMIT POINT always
-     *  fsyncs regardless (its crash-safety depends on it); this only affects whether `put` fsyncs. Default true. */
+     *  fsyncs regardless (its crash-safety depends on it); this governs the `put` and `setPendingSteer`
+     *  (steer-append) commits only — `resolve`/`reopen`/`expire` fsync unconditionally. Default true. */
     fsync?: boolean;
     /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;

package/dist/stores/file/index.d.ts

@@ -52,7 +52,7 @@ export interface FileStorageBackendOptions {
     /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
      *  deleted by an idle timer). */
     evict?: EvictPolicy;
-    /** Checkpoint store tuning (fsync cadence for `put`, ledger compaction threshold). */
+    /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold). */
     checkpoint?: FileCheckpointStoreOptions;
     /** design/101 §E19 — file-snapshot enumerator bounds (maxFiles/maxBytes/ignoreDirs). Default
      *  {@link DEFAULT_SNAPSHOT_BOUNDS}. */

package/dist/stores/file/tool-result-store.d.ts

@@ -1,4 +1,4 @@
-import type { ToolResultProvenance, ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
+import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
 /**
  * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
  *
@@ -55,4 +55,44 @@ export declare class FileToolResultStore implements ToolResultStore {
         offset?: number;
         limit?: number;
     }): ToolResultSlice | undefined;
+    /**
+     * Erase every entry owned by `sessionId` (interface: {@link ToolResultStore.deleteBySession}). Without
+     * it a session deletion leaves this store's files on disk for the lifetime of the data root.
+     *
+     * Selection matches on the SIDECAR's `sessionId`, never on the filename. That is not a preference, it
+     * is the only thing available: the mint separates segments with `~`, which is outside this backend's
+     * filename charset, so every engine-minted ref folds to `<base>-<sha256 of the raw ref>` and the
+     * session segment is gone from the name (and the readable base is a lossy, many-to-one prefix, so
+     * matching on it would reach a neighbouring session's files). `taskId`, where an older write site
+     * stamped one, is ignored — it narrows the same session.
+     *
+     * Both namespaces are swept: identity-named files in the store dir (refs a caller minted inside the
+     * filename charset, and everything written before the injective mint) and {@link FOLDED_SUBDIR}.
+     *
+     * Removal order is CONTENT then SIDECAR, and it is load-bearing. Interrupted after the content unlink,
+     * the next sweep still finds the sidecar, matches the same session and converges; interrupted after a
+     * sidecar-first unlink, the content file would be left owner-less — readable, attributable to nobody,
+     * and beyond the reach of every future session sweep. Same reasoning as `put`'s publication order, in
+     * the opposite direction. The pair is then re-examined ONCE after both unlinks, which is what keeps
+     * a `put` racing the two from leaving bytes whose owner this sweep removed — and what keeps that
+     * re-examination from deleting a row a DIFFERENT session claimed in the same window (see the body).
+     *
+     * What the re-examination is NOT is atomic: it reads the owner and then acts, so a writer landing
+     * inside THAT gap is narrowed, not excluded. Stated rather than locked away, because the locking that
+     * would close it is ruled out one layer down — `fs-atomic.ts` §2.4 admits exactly one file lock, the
+     * boot lock, on the premise that a data root has a single writing process (`FileStorageBackend`
+     * acquires it before constructing this store; cross-process correctness is a database backend's job,
+     * as everywhere else in this family). Under that premise there is no gap at all: both `put` and this
+     * sweep are wholly synchronous, so nothing can interleave with either. The narrowing above is what
+     * remains worth doing for a root someone shares anyway, and it costs one `readFileSync`.
+     *
+     * Failure posture: an entry that vanished between `readdir` and the unlink is honest absence (ENOENT
+     * ok, the concurrent sweeper's row). Any OTHER unlink error throws — a deletion face that cannot
+     * delete has to be loud — and because the sweep is idempotent, the retry after the operator clears
+     * the cause resumes where it stopped. A sidecar that cannot be READ (EACCES, torn JSON, a shape that
+     * is not the whole record) is counted `unattributable` and its content is left alone: a file we could
+     * not read carries no evidence about whose it is, and this store's rows stay readable through `get`
+     * even with a damaged owner record, so removing one on a guess would destroy another session's output.
+     */
+    deleteBySession(sessionId: string): ToolResultDeletionReport;
 }

package/dist/stores/file/tool-result-store.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance, } from "../../core/tool-result-store.js";
+import { assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance, ToolResultRefConflictError, } from "../../core/tool-result-store.js";
 import { ensureDir, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 export class FileToolResultStore {
@@ -21,11 +21,11 @@ export class FileToolResultStore {
     }
     pathFor(ref) {
         const { dir, stem } = this.locate(ref);
-        return join(dir, `${stem}.txt`);
+        return join(dir, `${stem}${CONTENT_SUFFIX}`);
     }
     ownerPathFor(ref) {
         const { dir, stem } = this.locate(ref);
-        return join(dir, `${stem}.owner.json`);
+        return join(dir, `${stem}${OWNER_SUFFIX}`);
     }
     put(ref, content, provenance) {
         assertSafeToolResultRef(ref);
@@ -46,7 +46,14 @@ export class FileToolResultStore {
         }
         if (provenance === undefined)
             return;
-        this.writeOwnerFile(ref, provenance);
+        try {
+            this.writeOwnerFile(ref, provenance);
+        }
+        catch (err) {
+            if (err instanceof ToolResultRefConflictError)
+                unlinkIfAbsentOk(this.pathFor(ref));
+            throw err;
+        }
     }
     ownerOf(ref) {
         return this.readOwnerFile(ref, { loud: false });
@@ -63,20 +70,9 @@ export class FileToolResultStore {
                 throw err;
             return undefined;
         }
-        const parsed = (() => {
-            try {
-                return JSON.parse(raw);
-            }
-            catch {
-                return undefined;
-            }
-        })();
-        if (typeof parsed === "object" && parsed !== null) {
-            const { sessionId, taskId } = parsed;
-            if (typeof sessionId === "string" && (taskId === undefined || typeof taskId === "string")) {
-                return taskId === undefined ? { sessionId } : { sessionId, taskId };
-            }
-        }
+        const parsed = parseOwnerRecord(raw);
+        if (parsed !== undefined)
+            return parsed;
         if (opts.loud) {
             throw new Error(`tool-result store: owner record for ref ${JSON.stringify(ref)} is present but unreadable — refusing to write over it`);
         }
@@ -111,6 +107,98 @@ export class FileToolResultStore {
         const content = limit != null ? full.slice(offset, offset + limit) : full.slice(offset);
         return { content, offset, totalChars: full.length };
     }
+    deleteBySession(sessionId) {
+        let deleted = 0;
+        let unattributable = 0;
+        for (const dir of [this.dir, join(this.dir, FOLDED_SUBDIR)]) {
+            let names;
+            try {
+                names = readdirSync(dir);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+            const listed = new Set(names);
+            for (const name of names) {
+                if (!name.endsWith(OWNER_SUFFIX))
+                    continue;
+                const owner = readOwnerAt(join(dir, name));
+                if (owner === "gone")
+                    continue;
+                if (owner === "damaged") {
+                    unattributable++;
+                    continue;
+                }
+                if (owner.sessionId !== sessionId)
+                    continue;
+                const stem = name.slice(0, -OWNER_SUFFIX.length);
+                const sidecarPath = join(dir, name);
+                const contentPath = join(dir, `${stem}${CONTENT_SUFFIX}`);
+                unlinkIfAbsentOk(contentPath);
+                unlinkIfAbsentOk(sidecarPath);
+                const republished = readOwnerAt(sidecarPath);
+                if (republished === "gone") {
+                    unlinkIfAbsentOk(contentPath);
+                }
+                else if (republished === "damaged") {
+                    unattributable++;
+                }
+                else if (republished.sessionId === sessionId) {
+                    unlinkIfAbsentOk(contentPath);
+                    unlinkIfAbsentOk(sidecarPath);
+                }
+                deleted++;
+            }
+            for (const name of names) {
+                if (!name.endsWith(CONTENT_SUFFIX))
+                    continue;
+                if (listed.has(`${name.slice(0, -CONTENT_SUFFIX.length)}${OWNER_SUFFIX}`))
+                    continue;
+                unattributable++;
+            }
+        }
+        return { deleted, unattributable };
+    }
+}
+const CONTENT_SUFFIX = ".txt";
+const OWNER_SUFFIX = ".owner.json";
+function parseOwnerRecord(raw) {
+    const parsed = (() => {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (typeof parsed === "object" && parsed !== null) {
+        const { sessionId, taskId } = parsed;
+        if (typeof sessionId === "string" && (taskId === undefined || typeof taskId === "string")) {
+            return taskId === undefined ? { sessionId } : { sessionId, taskId };
+        }
+    }
+    return undefined;
+}
+function readOwnerAt(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? "gone" : "damaged";
+    }
+    return parseOwnerRecord(raw) ?? "damaged";
+}
+function unlinkIfAbsentOk(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
 }
 const NATIVE_FILENAME_CHARSET = /^[A-Za-z0-9_.-]+$/;
 const FOLDED_SUBDIR = "folded-v2";

package/dist/tools/fs/fs-bash.d.ts

@@ -110,6 +110,10 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     /** RB-370 ② (cli [2088]): override of the `timeout` parameter's engine CEILING, in ms — only-widen
      *  vs the resolved default; see {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs}. */
     bashMaxTimeoutMs?: number;
+    /** Structured sink for this leg's timeout-cap discard announcements — consumed by
+     *  {@link import("./fs-shared.js").resolveBashTimeoutCaps} at mount (see
+     *  {@link import("./index.js").HandsToolkitOptions.onNotice} for the replace-vs-warn contract). */
+    onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
     /**
      * #181-F6 — whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
      * `backgroundTaskToolsActive`; it, not this tool, mounts Monitor). Read by the SR-2 gh rate-limit
@@ -142,6 +146,9 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
      *  legs share runShell's clamp, so both must share the configurable resolution). */
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
+    /** Structured sink for the timeout-cap discard announcements — same seat the full `bash` leg
+     *  takes (both foreground legs share the resolver, so both must share the sink). */
+    onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
     /** RB-413: the extra containment roots the structured file tools got (design/119 `--add-dir`,
      *  canonical). A read this deployment already sanctions for Read/Grep/Glob is equally sanctioned
      *  here — the two faces must not disagree about which directories exist for this session. */

package/dist/tools/fs/fs-shared.d.ts

@@ -3,6 +3,7 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type FsViolation, type ReadFileState } from "./safety.js";
 import { type DecodedTextFile } from "./encoding.js";
 import { type ImageDownsampler } from "../../core/mcp.js";
+import { type EngineNotice } from "../../core/types.js";
 /**
  * The "hand" tool band (design/44 §3) — built per task over an injected {@link ExecutionEnv} and a
  * per-task {@link ReadFileState}, closure-captured (design/44 §11 ruling A: the codebase tool idiom; no
@@ -223,6 +224,10 @@ export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, cap
 export declare function resolveBashTimeoutCaps(opts?: {
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
+    /** Structured seat for the discard announcements below — wired, it REPLACES their `console.warn`
+     *  (same ledger, same lines as `message`); absent, the console line prints verbatim. Threaded from
+     *  the toolkit assembly (ultimately `RunnerDeps.onNotice`); never a global. */
+    onNotice?: (n: EngineNotice) => void;
 }): {
     defaultMs: number;
     maxMs: number;

package/dist/tools/fs/fs-shared.js

@@ -5,6 +5,7 @@ import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
+import { deliverEngineNotice } from "../../core/types.js";
 export const MAX_READ_BYTES = 256 * 1024;
 export const SLICED_READ_MAX_BYTES = 64 * 1024 * 1024;
 export const MAX_EDIT_BYTES = 1024 * 1024 * 1024;
@@ -88,7 +89,10 @@ export function envErrorDetail(message) {
     return trimmed === "" ? "the execution environment reported no reason" : trimmed;
 }
 const announcedTimeoutConfig = new Set();
-function announceDiscardedTimeout(knob, raw, usedMs) {
+function emitTimeoutDiscardNotice(message, detail, onNotice) {
+    deliverEngineNotice(onNotice, { code: "config.env_timeout_discarded", message, detail });
+}
+function announceDiscardedTimeout(knob, raw, usedMs, onNotice) {
     if (typeof raw === "string" && raw === "")
         return;
     const n = typeof raw === "number" ? raw : Number(raw);
@@ -105,7 +109,7 @@ function announceDiscardedTimeout(knob, raw, usedMs) {
     if (announcedTimeoutConfig.has(line))
         return;
     announcedTimeoutConfig.add(line);
-    console.warn(line);
+    emitTimeoutDiscardNotice(line, { knob, raw, usedMs }, onNotice);
 }
 export function bashTimeoutParamDescription(caps, withDefault) {
     const bounds = `${withDefault ? `default ${caps.defaultMs}, ` : ""}min ${MIN_BASH_TIMEOUT_MS}, max ${caps.maxMs}`;
@@ -131,13 +135,13 @@ export function resolveBashTimeoutCaps(opts) {
         BASH_DEFAULT_TIMEOUT_MS;
     const maxMs = Math.max(validTimeoutMs(opts?.bashMaxTimeoutMs) ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS)) ?? BASH_MAX_TIMEOUT_MS, defaultMs);
     if (opts?.bashDefaultTimeoutMs !== undefined)
-        announceDiscardedTimeout("bashDefaultTimeoutMs", opts.bashDefaultTimeoutMs, defaultMs);
+        announceDiscardedTimeout("bashDefaultTimeoutMs", opts.bashDefaultTimeoutMs, defaultMs, opts?.onNotice);
     if (process.env.BASH_DEFAULT_TIMEOUT_MS !== undefined)
-        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", process.env.BASH_DEFAULT_TIMEOUT_MS, defaultMs);
+        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", process.env.BASH_DEFAULT_TIMEOUT_MS, defaultMs, opts?.onNotice);
     if (opts?.bashMaxTimeoutMs !== undefined)
-        announceDiscardedTimeout("bashMaxTimeoutMs", opts.bashMaxTimeoutMs, maxMs);
+        announceDiscardedTimeout("bashMaxTimeoutMs", opts.bashMaxTimeoutMs, maxMs, opts?.onNotice);
     if (process.env.BASH_MAX_TIMEOUT_MS !== undefined)
-        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", process.env.BASH_MAX_TIMEOUT_MS, maxMs);
+        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", process.env.BASH_MAX_TIMEOUT_MS, maxMs, opts?.onNotice);
     const optsCap = validTimeoutMs(opts?.bashMaxTimeoutMs);
     const requestedCap = optsCap ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS));
     if (requestedCap !== undefined && requestedCap < defaultMs) {
@@ -145,7 +149,7 @@ export function resolveBashTimeoutCaps(opts) {
         const line = `${knob}=${requestedCap} is below the resolved default budget (${defaultMs}ms) — the ceiling was raised to ${maxMs}ms (the default always fits under the cap).`;
         if (!announcedTimeoutConfig.has(line)) {
             announcedTimeoutConfig.add(line);
-            console.warn(line);
+            emitTimeoutDiscardNotice(line, { knob, raw: requestedCap, usedMs: maxMs }, opts?.onNotice);
         }
     }
     return { defaultMs, maxMs };

package/dist/tools/fs/index.d.ts

@@ -74,6 +74,12 @@ export interface HandsToolkitOptions {
      *  only-widen semantic: a ceiling below the default is a narrowing intent = invalid, ignored in
      *  favor of the default. Additive: absent ⇒ byte-compat 600s. */
     bashMaxTimeoutMs?: number;
+    /** Structured sink for the timeout-cap discard announcements both shell legs emit at mount (see
+     *  {@link import("../../core/types.js").EngineNotice} / `RunnerDeps.onNotice`). Wired, it REPLACES
+     *  their `console.warn` line (a forwarding host must not show every fact twice); absent, the
+     *  console line prints verbatim (byte-compat loudness). Threaded per toolkit build — never a
+     *  global. */
+    onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
     /** RB-220 — see createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for
      *  the full contract: this run has no later turn for an async background notification to land in.
      *  Threaded to both the Bash background-launch receipt and (when this band mounts TaskOutput itself,

package/dist/tools/fs/index.js

@@ -41,6 +41,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+                ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
                 ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
@@ -55,6 +56,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 ...(additionalRoots !== undefined ? { additionalRoots } : {}),
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+                ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
                 ...(opts.monitorToolActive !== undefined ? { monitorToolActive: opts.monitorToolActive } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.26.0",
+  "version": "5.28.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",