@sema-agent/core 5.27.0 → 5.28.0

package/dist/core/types.d.ts

@@ -1734,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[];
     /**
@@ -2750,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.
      *
@@ -3265,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;
     /**
@@ -4161,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;
@@ -4797,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/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, toolResultContentSegment, 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";

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.27.0",
+  "version": "5.28.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",