@sema-agent/core 5.19.0 → 5.20.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 5.20.0 — 2026-08-08
+
+### BREAKING
+
+Configuration hygiene sweep. A malformed numeric knob used to be accepted and then quietly do
+something — usually the OPPOSITE of what it was set to. Every seam below now either refuses the
+value at its resolution point or clamps it and says so. Well-formed values in the documented range
+are untouched everywhere; the break is that values which used to be accepted-then-misbehave are
+now rejected, so a deployment carrying one gets a loud failure at wiring time instead of a
+mysterious runtime.
+
+- **MCP millisecond env knobs** (`MCP_TOOL_TIMEOUT`, `MCP_TOOL_TIMEOUT_TOTAL`,
+  `MCP_IDLE_TIMEOUT_STDIO`, `MCP_IDLE_TIMEOUT_HTTP`, `MCP_TIMEOUT`) share one parser, which was
+  `parseInt`-based: `1e9` meant 1ms, `30s` meant 30ms, and `100_000_000` — the way this repo writes
+  the default constant it invites you to copy — meant 100ms. Past 2^31-1 the host timer truncated
+  the delay and fired at once, so widening a watchdog to "basically off" made it abort every call,
+  while the failure text quoted the requested number back. The parser now reads plain digits,
+  scientific notation and digit grouping, refuses anything else, and clamps into
+  **[1000, 2147483647] ms**, warning once on stderr with the knob name, the raw text and the value
+  actually in force. Timeout frames quote the resolved value. `MAX_MCP_OUTPUT_TOKENS` moves onto the
+  same grammar (its `1e5` used to mean a 4-char budget), keeping upstream's unbounded range.
+  Upgrade note (the widening side of this fix): on 5.19.0 and earlier, `1e9` / `1_800_000` — both
+  legal upstream spellings — silently took effect as **1ms**. After upgrading they take effect at
+  face value, so a deployment that wrote one of these will see the knob jump from 1ms to the
+  number it always said.
+- **Millisecond knobs that arm a host timer** are refused above 2147483647ms (~24.8 days), where
+  the timer truncates and fires immediately: the stall watchdogs (`connectTimeoutMs`,
+  `firstTokenTimeoutMs`, `idleTimeoutMs`), `brainCallGuardrailMs`, `runWorkflow`'s `totalTimeoutMs`
+  / `stallMs` / `throttleBackoffMs`, and `createApprovalPolicy`'s `approvalTimeoutMs` — the last of
+  which would otherwise have denied every request instantly, fail-closed and silent. Each already
+  documents `0` / `false` / omission as "off". `limits.maxWalltimeMs` is the exception and keeps
+  its promise of no ceiling: the hard-abort timer now waits in representable chunks.
+- **Retention policies** (`BackgroundAgentStore.reap`, `MailboxStore.reap`, `WorkflowRunStore.reap`,
+  `reapDurableAgents`, both roster stores' constructors) refuse a non-finite or negative bound with
+  `config.retention_policy_invalid`. `keep` is consumed as `slice(Math.max(0, keep))`, where NaN
+  collapses to `slice(0)` and deleted EVERY terminal row in the scope; the roster's `maxAgeMs` made
+  every durable address read as expired. Absent fields keep their "this arm is not applied" meaning.
+  Operational note: this is a refusal, not a sanitize — a deployment with a malformed retention knob
+  will see every reap throw (rows accumulate) until the knob is corrected. Fix the knob before
+  upgrading; nothing is auto-repaired on your behalf.
+- **Web and circuit-breaker knobs**: `timeoutMs` on WebFetch / WebSearch / the Searxng backend fed a
+  bare `setTimeout`, where NaN and Infinity both become 1ms — a budget written as "no limit" aborted
+  every request on arrival and reported "timed out after NaNms". `maxResults` fed `slice(0, max)`,
+  so a NaN or 0 cap emptied every search from a backend that answered. The circuit breaker's
+  `failureThreshold` / `cooldownMs` / `halfOpenProbes` had no validation at all, and `failures >= NaN`
+  is false forever — an unevaluable threshold left the breaker permanently open-loop. All are now
+  resolved at assembly time (`config.web_timeout_invalid`,
+  `config.web_search_max_results_invalid`, `config.circuit_breaker_invalid`). `probeSearchBackend`
+  keeps its documented never-throws contract: a malformed budget comes back as `{ ok: false, error }`.
+
+### Added
+
+- **`Hooks.preToolUseObservational`** — a deployment declares that its PreToolUse face is a pure
+  OBSERVER (a tracer, an audit sink) and never judges. 5.19.0's delegation fold keys on PRESENCE,
+  which cannot tell a tracer from a screener: a deployment that flipped on a default-OFF diagnostic
+  hook thereby added an opaque constraint to every delegated child, and a child that durably parked
+  recorded that count on its row — where an approval redeemed by a leg that cannot re-supply the
+  live screening closure has no recovery path. With the declaration the face contributes **no
+  chain entry**, so `parentConstraintCount` counts only constraints that actually judge; without it,
+  5.19.0 behavior is unchanged. The callback still runs in the installing task's own gate, on every
+  call, with the same crash posture (a throw is still the fail-closed deny) — only the inherited
+  constraint goes away. A declared-observational face that returns something anyway has that return
+  **refused, not obeyed**: the call proceeds as if the face had no opinion (this covers
+  `additionalContext` too) and `onError` is told (`phase:"hook"`, classification
+  `observational-hook-verdict-ignored`), so the declaration cannot become a quiet way to keep a
+  screening face's verdicts while shedding the delegation constraint they belong to. A declared face
+  is also handed a **detached copy of the arguments** (best-effort, same helper and same limits as the
+  other observe-only payloads): the gate reads a rewrite off reference identity, so an in-place edit
+  would be a second channel outliving the dropped return. Two further consequences of "it does not
+  judge": a declared face no longer collapses an ancestor's screening entry that names the same
+  callback (the descendant no longer honors it, so the ancestor's constraint is folded instead), and it
+  no longer counts as an effect-aware gate for the loud ungated-write-surface warning.
+- **`createPreToolUseConstraintPolicy` is now a public export**, and a durable park under an inherited
+  screening constraint says so at PARK time. A checkpoint records only how many opaque constraints its
+  leg ran under; the resume must hand the same chain back. Every entry kind except one is a policy the
+  deployment authored — the screening entry 5.19.0 added is engine-minted, so a hook-wired tree's
+  parked children were redeemable only in the process that spawned them (same-Runner resumes are
+  auto-re-supplied from the in-memory registry and were never affected). The mint is now exported, so a
+  fresh Runner can rebuild the entry — same callback, same installed env — and hand the full chain to
+  `resumeStream(..., internals)`; the recorded-count check is unchanged, so a short or mismatched chain
+  is still refused pre-CAS. And the park itself now announces the requirement once per task on
+  `onError` (`phase:"degraded"`, classification `screening-constraint-in-durable-chain`), naming the
+  recorded count and the ways out, instead of leaving it to be discovered at a redemption that fails.
+
 ## 5.19.0 — 2026-08-10
 
 > Three bundles, each pre-verified two-way by the evaluation line against the 5.18.1 artifact
@@ -14,10 +98,15 @@
   four-axis dedup so a deps-level hook is consulted once per call at any depth). A screening
   `ask` resolves at the installing task's frozen approver; a hook-wired parent with no approver
   denies its children's screened calls fail-closed.
-  **Operational**: `parentConstraintCount` gains a screening entry for hook-wired trees — a
-  pending approval checkpoint minted before this change and resumed after (or the reverse)
-  fails pre-CAS with `resume.parent_constraint_mismatch`. **Drain pending checkpoints across
-  the upgrade.** A delegated child of a hook-wired parent also sets
+  **Operational (corrected per downstream measurement)**: `parentConstraintCount` gains a
+  screening entry for hook-wired trees. Pre-5.19.0 rows (including hook-wired parents) recorded
+  the old count and rebuild legs that supply it keep matching — upgrade and rollback are clean
+  for EXISTING pending checkpoints. The unrecoverable case is a checkpoint **minted on 5.19.0**
+  by a hook-wired parent and redeemed by a rebuild leg that cannot re-supply the live screening
+  entry (cross-replica redemption): it fails pre-CAS with `resume.parent_constraint_mismatch`
+  and stays pending, with no recovery path (the count is written at park time; disabling the
+  hook afterwards does not change it). Same-replica resumes via `resumeStream(..., internals)`
+  are unaffected. A delegated child of a hook-wired parent also sets
   `requiresParentConstraint`, so its durable resume must re-supply the chain via
   `resumeStream(..., internals)`.
 - **Write guards judge the call's live cwd** (P1, host-lane proven bypass). A resident shell's

package/dist/agents/roster-store.js

@@ -1,4 +1,5 @@
 import { mkdirSync, readFileSync } from "node:fs";
+import { assertRetentionPolicy } from "../core/retention-policy.js";
 import { atomicWriteFile } from "../stores/file/fs-atomic.js";
 import { dirname } from "node:path";
 import { normalizeAgentName } from "../core/task-registry.js";
@@ -50,6 +51,7 @@ export class MemoryRosterStore {
     maxAgeMs;
     gc;
     constructor(opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;
     }
@@ -78,6 +80,7 @@ export class FileRosterStore {
     gc;
     onCorruptRead;
     constructor(path, opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.path = path;
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;

package/dist/brain/circuit-breaker.js

@@ -24,10 +24,21 @@ function errorAssistantMessage(model, code, detail, stopReason = "error") {
         timestamp: Date.now(),
     };
 }
+function finiteBreakerKnob(value, knob, fallback, wholeAtLeastOne) {
+    if (value === undefined)
+        return fallback;
+    const ok = wholeAtLeastOne ? Number.isInteger(value) && value >= 1 : Number.isFinite(value) && value >= 0;
+    if (!ok) {
+        const e = new Error(`createCircuitBreakerBrain: ${knob} must be ${wholeAtLeastOne ? "a whole number of 1 or more" : "a finite, non-negative number of milliseconds"} (got ${String(value)}) — an unevaluable knob leaves the breaker permanently open-loop, which is a protection that is silently not there`);
+        e.code = "config.circuit_breaker_invalid";
+        throw e;
+    }
+    return value;
+}
 export function createCircuitBreakerBrain(inner, opts = {}) {
-    const failureThreshold = opts.failureThreshold ?? 5;
-    const cooldownMs = opts.cooldownMs ?? 30_000;
-    const halfOpenProbes = opts.halfOpenProbes ?? 1;
+    const failureThreshold = finiteBreakerKnob(opts.failureThreshold, "failureThreshold", 5, true);
+    const cooldownMs = finiteBreakerKnob(opts.cooldownMs, "cooldownMs", 30_000, false);
+    const halfOpenProbes = finiteBreakerKnob(opts.halfOpenProbes, "halfOpenProbes", 1, true);
     const countCodes = new Set(opts.countCodes ?? ["network", "server", "rate_limit"]);
     const keyOf = opts.key ?? ((m) => `${m.provider}:${m.id}`);
     const state = opts.state ?? new InMemoryBreakerState();

package/dist/brain/timeout.d.ts

@@ -1,4 +1,5 @@
 import type { StreamFn } from "../internal/llm.js";
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
 export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 export declare const STALL_CONNECT_MS = 30000;
 export declare const STALL_FIRST_TOKEN_MS = 120000;

package/dist/brain/timeout.js

@@ -1,3 +1,4 @@
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export function resolveStallTimeoutMs(value, knob) {
     if (value === undefined)
         return undefined;
@@ -6,6 +7,11 @@ export function resolveStallTimeoutMs(value, knob) {
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
+    if (value > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${String(value)}). Pass 0 to disable it.`);
+        e.code = "config.stall_timeout_invalid";
+        throw e;
+    }
     return value;
 }
 export const STALL_CONNECT_MS = 30_000;
@@ -66,6 +72,11 @@ export function resolveBrainCallGuardrailMs(knob) {
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }
+    if (knob > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${String(knob)}). Pass false or 0 to turn the backstop off.`);
+        e.code = "config.brain_call_guardrail_invalid";
+        throw e;
+    }
     return knob;
 }
 function armCallGuardrail(limitMs, outerSignal, ref) {

package/dist/core/background-agent-store.d.ts

@@ -87,6 +87,7 @@ export interface BackgroundAgentReapOptions {
     keep?: number;
     staleRunningMaxAgeMs?: number;
 }
+export declare function assertBackgroundAgentReapOptions(opts: BackgroundAgentReapOptions | undefined): void;
 export interface BackgroundAgentStore {
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;

package/dist/core/background-agent-store.js

@@ -1,4 +1,5 @@
 import { uuidv7 } from "../internal/harness.js";
+import { assertRetentionPolicy } from "./retention-policy.js";
 export const REVIVED_ROW_CLEARED_FIELDS = [
     "settledAt",
     "stoppedBy",
@@ -43,6 +44,9 @@ export function canAccessAgentRecord(record, access) {
     return false;
 }
 export const STALE_RUNNING_REAP_ATTRIBUTION = "the host process was interrupted while this agent was running — its in-process state was lost. Check its worktree / output file for partial work before assuming the task landed (stale running row reaped).";
+export function assertBackgroundAgentReapOptions(opts) {
+    assertRetentionPolicy("BackgroundAgentStore.reap", opts);
+}
 export async function reconcileParkedAgents(stores, scope, now, opts) {
     const out = { failed: 0, rolledBack: 0 };
     const excluded = (row) => (opts?.excludeHandles?.has(row.handle) ?? false) ||
@@ -256,6 +260,7 @@ export class InMemoryBackgroundAgentStore {
         return [...new Set([...this.rows.values()].map((r) => r.scope))].sort();
     }
     async reap(scope, now, opts) {
+        assertBackgroundAgentReapOptions(opts);
         if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
             return 0;
         const flippedKeys = new Set();

package/dist/core/hooks.d.ts

@@ -3,6 +3,7 @@ import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../inter
 import type { PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 export interface Hooks {
     preToolUse?(toolName: string, input: unknown, ctx: HookToolContext): PreToolUseResult | undefined | Promise<PreToolUseResult | undefined>;
+    preToolUseObservational?: true;
     postToolUse?(toolName: string, input: unknown, output: HookToolOutput, ctx: HookToolContext): PostToolUseResult | undefined | Promise<PostToolUseResult | undefined>;
     userPromptSubmit?(prompt: string): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
     stop?(ctx: StopHookContext): StopHookResult | undefined | Promise<StopHookResult | undefined>;

package/dist/core/mailbox-store.js

@@ -1,3 +1,4 @@
+import { assertRetentionPolicy } from "./retention-policy.js";
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {
@@ -65,6 +66,7 @@ export class InMemoryMailboxStore {
         this.boxes.delete(this.key(scope, handle));
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;

package/dist/core/mcp.d.ts

@@ -63,11 +63,15 @@ export declare function gateMcpOutput(content: Array<TextContent | ImageContent>
 export declare function structuredContentErrorLine(structuredContent: unknown, collectedText: string): string | undefined;
 export declare function truncateMcpErrorText(s: string): string;
 export declare const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100000000;
+export declare const MCP_ENV_MS_MIN = 1000;
+export declare const MCP_ENV_MS_MAX = 2147483647;
+export declare function __resetMcpEnvAnnouncements(): void;
 export declare function mcpToolTimeoutMs(): number;
 export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
 export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
+export declare function mcpStartupTimeoutMs(): number | undefined;
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
 export declare function collapseMcpErrorPrefix(message: string): string;
 export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;

package/dist/core/mcp.js

@@ -24,13 +24,18 @@ export function resolveMcpDeclaredResultSize(meta) {
     return Math.min(declared, MCP_META_RESULT_SIZE_CAP);
 }
 function mcpMaxOutputTokens() {
-    const raw = process.env.MAX_MCP_OUTPUT_TOKENS;
-    if (raw) {
-        const n = parseInt(raw, 10);
-        if (Number.isFinite(n) && n > 0)
-            return n;
+    const rawEnv = process.env.MAX_MCP_OUTPUT_TOKENS;
+    if (rawEnv === undefined)
+        return MCP_OUTPUT_TOKENS_DEFAULT;
+    const raw = rawEnv.trim();
+    if (raw === "")
+        return MCP_OUTPUT_TOKENS_DEFAULT;
+    const n = parseWholeNumber(raw);
+    if (n === undefined || n <= 0) {
+        announceMcpEnvKnob(`MAX_MCP_OUTPUT_TOKENS=${rawEnv} was ignored — it is not a positive whole number of tokens. Using ${MCP_OUTPUT_TOKENS_DEFAULT} instead.`);
+        return MCP_OUTPUT_TOKENS_DEFAULT;
     }
-    return MCP_OUTPUT_TOKENS_DEFAULT;
+    return n;
 }
 function mcpTruncationNote(limitTokens) {
     return (`\n\n[OUTPUT TRUNCATED - exceeded ${limitTokens} token limit]\n\n` +
@@ -100,12 +105,54 @@ export function truncateMcpErrorText(s) {
     return out.length < s.length ? out : s;
 }
 export const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100_000_000;
+export const MCP_ENV_MS_MIN = 1_000;
+export const MCP_ENV_MS_MAX = 2_147_483_647;
+const ENV_SCIENTIFIC_RE = /^[+-]?(\d+(\.\d*)?|\.\d+)[eE][+-]?\d+$/;
+const ENV_GROUPED_RE = /^[+-]?\d{1,3}([_,\u00A0\u202F ])\d{3}(?:\1\d{3})*$/;
+const ENV_GROUP_SEPARATORS_RE = /[_,\u00A0\u202F ]/g;
+const ENV_NUMERIC_MAX_LEN = 32;
+function parseWholeNumber(raw) {
+    if (/^[+-]?\d+$/.test(raw)) {
+        const n = Number(raw);
+        return Number.isSafeInteger(n) ? n : undefined;
+    }
+    if (raw.length > ENV_NUMERIC_MAX_LEN)
+        return undefined;
+    if (ENV_SCIENTIFIC_RE.test(raw)) {
+        const n = Number(raw);
+        return Number.isSafeInteger(n) ? n : undefined;
+    }
+    if (ENV_GROUPED_RE.test(raw))
+        return parseInt(raw.replace(ENV_GROUP_SEPARATORS_RE, ""), 10);
+    return undefined;
+}
+const announcedMcpEnvKnobs = new Set();
+function announceMcpEnvKnob(line) {
+    if (announcedMcpEnvKnobs.has(line))
+        return;
+    announcedMcpEnvKnobs.add(line);
+    console.warn(line);
+}
+export function __resetMcpEnvAnnouncements() {
+    announcedMcpEnvKnobs.clear();
+}
 function parseEnvMs(name) {
-    const raw = process.env[name];
-    if (!raw)
+    const rawEnv = process.env[name];
+    if (rawEnv === undefined)
+        return undefined;
+    const raw = rawEnv.trim();
+    if (raw === "")
         return undefined;
-    const n = parseInt(raw, 10);
-    return Number.isFinite(n) && n > 0 ? n : undefined;
+    const n = parseWholeNumber(raw);
+    if (n === undefined || n <= 0) {
+        announceMcpEnvKnob(`${name}=${rawEnv} was ignored — it is not a positive whole number of milliseconds. Using the built-in default instead.`);
+        return undefined;
+    }
+    const clamped = Math.min(Math.max(n, MCP_ENV_MS_MIN), MCP_ENV_MS_MAX);
+    if (clamped !== n) {
+        announceMcpEnvKnob(`${name}=${rawEnv} is outside the range this runtime can honor (${MCP_ENV_MS_MIN}..${MCP_ENV_MS_MAX} ms). Using ${clamped}ms instead.`);
+    }
+    return clamped;
 }
 export function mcpToolTimeoutMs() {
     return parseEnvMs("MCP_TOOL_TIMEOUT") ?? MCP_TOOL_TIMEOUT_DEFAULT_MS;
@@ -150,7 +197,7 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
         },
     };
 }
-function mcpStartupTimeoutMs() {
+export function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
 const MCP_SPEC_ERROR_CODE_NAMES = new Map([

package/dist/core/retention-policy.d.ts

@@ -0,0 +1,7 @@
+export interface RetentionPolicyKnobs {
+    maxAgeMs?: number;
+    keep?: number;
+    staleRunningMaxAgeMs?: number;
+    maxEntries?: number;
+}
+export declare function assertRetentionPolicy(label: string, opts: RetentionPolicyKnobs | undefined): void;

package/dist/core/retention-policy.js

@@ -0,0 +1,21 @@
+function invalidPolicy(label, knob, value, requirement) {
+    const e = new Error(`${label}: ${knob} must be ${requirement} (got ${String(value)}) — a retention bound that cannot be evaluated silently decides what to delete instead of bounding it`);
+    e.code = "config.retention_policy_invalid";
+    throw e;
+}
+export function assertRetentionPolicy(label, opts) {
+    if (opts === undefined)
+        return;
+    for (const knob of ["maxAgeMs", "staleRunningMaxAgeMs"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isFinite(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a finite, non-negative number of milliseconds");
+        }
+    }
+    for (const knob of ["keep", "maxEntries"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isInteger(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a whole number of rows, 0 or more");
+        }
+    }
+}

package/dist/core/runner/prepare-task.js

@@ -1074,7 +1074,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const ownCallerPolicy = lockedPreflight.toolPolicy;
             const durableMandate = runtimeCaps?.forceDurableGate === true ||
                 (spec.durableApproval !== undefined && !isLiveApproverSeat(frozenOnAsk));
-            const ownPreToolUse = hooks?.preToolUse;
+            const ownPreToolUse = preToolUseObservational ? undefined : hooks?.preToolUse;
             const hookConstraint = ownPreToolUse !== undefined &&
                 !(inheritedParentConstraints ?? []).some((pc) => pc.preToolUse === ownPreToolUse &&
                     askApproverIdentity(pc.onAsk) === askApproverIdentity(frozenOnAsk) &&
@@ -2946,6 +2946,24 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const denyNarrowingPolicy = narrowingLayers.length === 0 ? undefined : narrowingLayers.length === 1 ? narrowingLayers[0] : combinePolicies(...narrowingLayers);
         const basePolicyForResumeEdit = lockedPreflight.toolPolicy;
         const hooks = spec.hooks ?? deps.hooks;
+        const preToolUseObservational = hooks?.preToolUse !== undefined && hooks.preToolUseObservational === true;
+        const ownGatePreToolUse = !preToolUseObservational
+            ? hooks?.preToolUse
+            : async (toolName, input, ctx) => {
+                const r = await hooks.preToolUse(toolName, cloneObserverInput(input), ctx);
+                if (r === undefined)
+                    return undefined;
+                try {
+                    const action = typeof r.action === "string" ? r.action : "(non-string action)";
+                    deps.onError?.(new Error(`a PreToolUse hook declared observational (Hooks.preToolUseObservational) returned a decision ("${action}") while screening ` +
+                        `"${toolName}" — the decision was NOT adopted and the call proceeded as if the hook had no opinion. ` +
+                        `A declared-observational face must return undefined; drop the declaration if its verdicts are meant to count ` +
+                        `(they then also travel to delegated children as an inherited screening constraint).`), { phase: "hook", sessionId, classification: "observational-hook-verdict-ignored" });
+                }
+                catch {
+                }
+                return undefined;
+            };
         const sameInstanceAncestorCount = policy === undefined ? 0 : (inheritedParentConstraints ?? []).reduce((n, pc) => (pc.policy === policy ? n + 1 : n), 0);
         const sharedFirstDecision = new Map();
         const SHARED_FIRST_DECISION_CAP = 256;
@@ -3095,6 +3113,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         };
         const parentConstraintWrappers = (inheritedParentConstraints ?? []).map((pc) => pc.preToolUse !== undefined &&
             pc.preToolUse === hooks?.preToolUse &&
+            !preToolUseObservational &&
             pc.durableMandate !== true &&
             askApproverIdentity(pc.onAsk) === askApproverIdentity(frozenOnAsk) &&
             pc.hookEnv === hookEnvSource
@@ -3310,7 +3329,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 return eff === "write" || eff === "idempotent";
             })
             : [];
-        const hasEffectAwareGate = Boolean(policyLayers.length > 0 || hooks?.preToolUse);
+        const hasEffectAwareGate = Boolean(policyLayers.length > 0 || (hooks?.preToolUse !== undefined && !preToolUseObservational));
         const destructiveMcpUngated = mcp.tools.some((t) => !irreversibleTools.has(t.name) && !egressTools.has(t.name) && (toolEffects.get(t.name) ?? "write") !== "read");
         const firstPartyWriteUngated = (spec.tools ?? [])
             .map((t) => t.name)
@@ -3564,6 +3583,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 carried.spentMicroUsd = prior + parkedSpendMicroUsd;
                 return carried;
             };
+            const screeningParkDisclosedRef = { done: false };
             const serializeCheckpointState = (workspaceHandle, parkedSpendMicroUsd) => ({
                 activeTools: [...activeTools],
                 outputRef: { value: outputRef.value, set: outputRef.set },
@@ -3620,6 +3640,22 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     await memoryEngineSession.harvest("checkpoint");
                 try {
                     await checkpointStore.put(token, cp);
+                    const committedCount = cp.state.inheritedGate?.parentConstraintCount;
+                    if (cp.state.inheritedGate?.requiresParentConstraint === true &&
+                        !screeningParkDisclosedRef.done &&
+                        (inheritedParentConstraints ?? []).some((pc) => pc.preToolUse !== undefined)) {
+                        screeningParkDisclosedRef.done = true;
+                        try {
+                            deps.onError?.(new Error(`durable park under an inherited PreToolUse SCREENING constraint: this checkpoint records ` +
+                                `requiresParentConstraint with parentConstraintCount=${committedCount ?? "(unrecorded)"}, and the live ` +
+                                `closures cannot be persisted. A resume on THIS Runner re-supplies them automatically; a resume on a fresh ` +
+                                `Runner (restart / another replica) must hand back the whole chain via resumeStream(..., internals), ` +
+                                `rebuilding the screening entry with createPreToolUseConstraintPolicy(hook, env) — otherwise the row stays ` +
+                                `pending. If the face only observes, declare Hooks.preToolUseObservational and it stops entering the chain.`), { phase: "degraded", sessionId, classification: "screening-constraint-in-durable-chain" });
+                        }
+                        catch {
+                        }
+                    }
                     return { ok: true };
                 }
                 catch (putErr) {
@@ -4152,7 +4188,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         result = await runToolGate({
                             onNotifyError: (f) => emitTrace(deps.tracer, () => ({ kind: "observer.notify_failed", version: 1, taskId: spec.taskId ?? sessionId, site: f.site, message: f.error.message, ts: Date.now() })),
                             event: e,
-                            preToolUse: hooks?.preToolUse,
+                            preToolUse: ownGatePreToolUse,
                             ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}),
                             adjudicate,
                             resolveAsk: resolveAskBound,

package/dist/core/runner/runtask.js

@@ -1357,6 +1357,7 @@ export class Runner {
         const hooks = h
             ? {
                 ...(typeof h.preToolUse === "function" ? { preToolUse: (t, i, c) => h.preToolUse(t, i, c) } : {}),
+                ...(typeof h.preToolUse === "function" && h.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
                 ...(typeof h.postToolUse === "function" ? { postToolUse: (t, i, o, c) => h.postToolUse(t, i, o, c) } : {}),
                 ...(typeof h.userPromptSubmit === "function" ? { userPromptSubmit: (p) => h.userPromptSubmit(p) } : {}),
                 ...(typeof h.stop === "function" ? { stop: (c) => h.stop(c) } : {}),
@@ -4084,14 +4085,28 @@ function startTimeout(harness, abortController, remainingMs, softSuspendable = f
     if (remainingMs !== undefined) {
         const hardMs = Math.max(0, remainingMs + (softSuspendable ? WALLTIME_SUSPEND_GRACE_SEC * 1000 : 0));
         const scheduledAtMs = Date.now() + hardMs;
-        const timer = setTimeout(() => {
+        let leftMs = hardMs;
+        let timer;
+        const armChunk = () => {
+            const chunk = Math.max(0, Math.min(leftMs, MAX_TIMER_DELAY_MS));
+            timer = setTimeout(() => {
+                leftMs -= chunk;
+                if (leftMs > 0) {
+                    armChunk();
+                    return;
+                }
+                fireHardAbort();
+            }, chunk);
+        };
+        const fireHardAbort = () => {
             if (state.fired)
                 return;
             state.fired = true;
             state.latenessMs = Math.max(0, Date.now() - scheduledAtMs);
             abortController.abort();
             void harness.abort();
-        }, hardMs);
+        };
+        armChunk();
         state.clear = () => clearTimeout(timer);
     }
     return state;

package/dist/core/task-registry-agent.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { assertRetentionPolicy } from "./retention-policy.js";
 import { uuidv7 } from "../internal/harness.js";
 import { canAccessAgentRecord, BackgroundAgentStoreError, clearRevivedRowTerminalPayload, REVIVED_ROW_CLEARED_FIELDS, STALE_RUNNING_REAP_ATTRIBUTION, } from "./background-agent-store.js";
 import { shutdownDebug } from "./shutdown-debug.js";
@@ -163,6 +164,7 @@ export function endDurableClaimLane(core, id) {
     core.claimingHandles.delete(id);
 }
 export async function reapDurableAgentsLane(core, scope, deps, policy) {
+    assertRetentionPolicy("reapDurableAgents", policy);
     const now = policy.now ?? Date.now();
     if (policy.staleRunningMaxAgeMs !== undefined) {
         await deps.store.reap(scope, now, { staleRunningMaxAgeMs: policy.staleRunningMaxAgeMs });

package/dist/core/tool-policy.js

@@ -117,6 +117,9 @@ export function createApprovalPolicy(opts) {
     if (opts.approvalTimeoutMs !== undefined && !Number.isFinite(opts.approvalTimeoutMs)) {
         throw new Error(`createApprovalPolicy: approvalTimeoutMs must be a finite number of ms (got ${opts.approvalTimeoutMs}) — omit it to wait indefinitely`);
     }
+    if (opts.approvalTimeoutMs !== undefined && opts.approvalTimeoutMs > 2_147_483_647) {
+        throw new Error(`createApprovalPolicy: approvalTimeoutMs must not exceed 2147483647ms (~24.8 days) (got ${opts.approvalTimeoutMs}) — a host timer truncates a larger delay and fires immediately, denying every request at once; omit it to wait indefinitely`);
+    }
     const need = new Set(opts.requireApproval);
     const deny = new Set(opts.deny ?? []);
     const auto = new Set(opts.autoAllow ?? []);

package/dist/core/workflow-run-store.js

@@ -1,3 +1,4 @@
+import { assertRetentionPolicy } from "./retention-policy.js";
 export function summarizeWorkflowRun(run) {
     const latestPhase = run.phases.at(-1);
     return {
@@ -73,6 +74,7 @@ export class InMemoryWorkflowRunStore {
         return queryWorkflowRuns(this.runs.values(), scope, opts);
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("WorkflowRunStore.reap", opts);
         if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
             return 0;
         const terminal = [...this.runs.values()].filter((r) => r.scope === scope && isTerminalWorkflowStatus(r.status));

package/dist/index.d.ts

@@ -131,7 +131,7 @@ export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmitti
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, } from "./core/permission-rule-store.js";
 export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
-export { formatHookFeedback, runToolGate, createHookEnvCapabilities, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
+export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
 export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";

package/dist/index.js

@@ -116,7 +116,7 @@ export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmitti
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, } from "./core/permission-rule-store.js";
 export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
-export { formatHookFeedback, runToolGate, createHookEnvCapabilities, } from "./core/hooks.js";
+export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, } from "./core/memory.js";
 export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";

package/dist/orchestration/run-spec.js

@@ -102,6 +102,9 @@ export async function runSpec(runner, contract, opts) {
     const userHooks = opts.taskSpec.hooks && deployBaseline?.hooks
         ? {
             preToolUse: (opts.taskSpec.hooks.preToolUse ?? deployBaseline.hooks.preToolUse)?.bind(opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
+            ...((opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks).preToolUseObservational === true
+                ? { preToolUseObservational: true }
+                : {}),
             postToolUse: (opts.taskSpec.hooks.postToolUse ?? deployBaseline.hooks.postToolUse)?.bind(opts.taskSpec.hooks.postToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
             userPromptSubmit: (opts.taskSpec.hooks.userPromptSubmit ?? deployBaseline.hooks.userPromptSubmit)?.bind(opts.taskSpec.hooks.userPromptSubmit ? opts.taskSpec.hooks : deployBaseline.hooks),
             stop: (opts.taskSpec.hooks.stop ?? deployBaseline.hooks.stop)?.bind(opts.taskSpec.hooks.stop ? opts.taskSpec.hooks : deployBaseline.hooks),
@@ -118,6 +121,7 @@ export async function runSpec(runner, contract, opts) {
     let gateAbandoned = false;
     const hooks = {
         ...(userHooks?.preToolUse && { preToolUse: userHooks.preToolUse.bind(userHooks) }),
+        ...(userHooks?.preToolUse && userHooks.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
         ...(userHooks?.postToolUse && { postToolUse: userHooks.postToolUse.bind(userHooks) }),
         ...(userHooks?.userPromptSubmit && { userPromptSubmit: userHooks.userPromptSubmit.bind(userHooks) }),
         ...(userHooks?.postToolUseFailure && { postToolUseFailure: userHooks.postToolUseFailure.bind(userHooks) }),

package/dist/orchestration/workflow.js

@@ -245,6 +245,7 @@ function normalizeConcurrency(c) {
     }
     return Math.floor(c);
 }
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function normalizeWorkflowHardCap(name, v) {
     if (v === undefined)
         return undefined;
@@ -253,12 +254,22 @@ function normalizeWorkflowHardCap(name, v) {
     }
     return v;
 }
+function normalizeWorkflowTimerCap(name, v) {
+    const normalized = normalizeWorkflowHardCap(name, v);
+    if (normalized !== undefined && normalized > MAX_TIMER_DELAY_MS) {
+        throw new Error(`runWorkflow: ${name} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) (got ${v}) — a host timer truncates a larger delay and fires immediately, cancelling the run at once. Omit it for no deadline.`);
+    }
+    return normalized;
+}
 function normalizeWorkflowStallMs(v) {
     if (v === undefined)
         return WORKFLOW_AGENT_STALL_MS;
     if (!Number.isFinite(v)) {
         throw new Error(`runWorkflow: stallMs must be a finite number of milliseconds (got ${v}); 0 or a negative value is the documented explicit "off", not NaN/Infinity`);
     }
+    if (v > MAX_TIMER_DELAY_MS) {
+        throw new Error(`runWorkflow: stallMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) (got ${v}) — a host timer truncates a larger delay and fires immediately, so a watchdog stretched that far would trip on every agent instead of tolerating a long one. Pass 0 to turn it off.`);
+    }
     return v;
 }
 function createSemaphore(max) {
@@ -346,10 +357,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const maxAgents = normalizeWorkflowHardCap("maxAgents", opts.maxAgents);
     const maxLogChars = normalizeWorkflowHardCap("maxLogChars", opts.maxLogChars);
     const maxResultChars = normalizeWorkflowHardCap("maxResultChars", opts.maxResultChars);
-    const totalTimeoutMs = normalizeWorkflowHardCap("totalTimeoutMs", opts.totalTimeoutMs);
+    const totalTimeoutMs = normalizeWorkflowTimerCap("totalTimeoutMs", opts.totalTimeoutMs);
     const stallMs = normalizeWorkflowStallMs(opts.stallMs);
     const agentMaxRetries = normalizeWorkflowHardCap("agentMaxRetries", opts.agentMaxRetries) ?? WORKFLOW_AGENT_MAX_RETRIES;
-    const throttleBackoffMs = normalizeWorkflowHardCap("throttleBackoffMs", opts.throttleBackoffMs) ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
+    const throttleBackoffMs = normalizeWorkflowTimerCap("throttleBackoffMs", opts.throttleBackoffMs) ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
     const timers = opts.timers ?? REAL_WORKFLOW_TIMERS;
     const cancelController = new AbortController();
     const timeoutController = totalTimeoutMs !== undefined ? new AbortController() : undefined;

package/dist/stores/file/background-agent-store.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, queryBackgroundAgents, } from "../../core/background-agent-store.js";
+import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const agentLedgers = new SharedLedgerTable({
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
@@ -113,6 +113,7 @@ export class FileBackgroundAgentStore {
         });
     }
     async reap(scope, now, opts) {
+        assertBackgroundAgentReapOptions(opts);
         if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
             return 0;
         const changed = new Set();

package/dist/stores/file/mailbox-store.js

@@ -1,4 +1,5 @@
 import { join, resolve, sep } from "node:path";
+import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { newestSentAt, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
@@ -176,6 +177,7 @@ export class FileMailboxStore {
         });
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;

package/dist/stores/file/workflow-run-store.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { WorkflowRunStoreError, isTerminalWorkflowStatus, nextWorkflowRunOnUpdate, queryWorkflowRuns, } from "../../core/workflow-run-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const runLedgers = new SharedLedgerTable({
@@ -64,6 +65,7 @@ export class FileWorkflowRunStore {
         return queryWorkflowRuns(this.runs.values(), scope, opts);
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("WorkflowRunStore.reap", opts);
         if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
             return 0;
         const terminal = [...this.runs.values()].filter((r) => r.scope === scope && isTerminalWorkflowStatus(r.status));

package/dist/tools/web.js

@@ -25,6 +25,31 @@ function resolveWebMaxBytes(value) {
     }
     return value;
 }
+function resolveWebTimeoutMs(value, knob, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        const e = new Error(`${knob} must be a positive finite number of milliseconds (got ${String(value)}) — a non-finite or non-positive budget is not "no limit", it aborts every request within a millisecond`);
+        e.code = "config.web_timeout_invalid";
+        throw e;
+    }
+    if (value > 2_147_483_647) {
+        const e = new Error(`${knob} must not exceed 2147483647ms (~24.8 days) (got ${String(value)}) — a host timer truncates a larger delay and fires immediately, so widening the budget past this point aborts every request at once`);
+        e.code = "config.web_timeout_invalid";
+        throw e;
+    }
+    return value;
+}
+function resolveSearchMaxResults(value) {
+    if (value === undefined)
+        return 10;
+    if (!Number.isInteger(value) || value < 1) {
+        const e = new Error(`WebSearch maxResults must be a whole number of 1 or more (got ${String(value)}) — a zero, negative or unevaluable cap returns an empty result set from a backend that answered`);
+        e.code = "config.web_search_max_results_invalid";
+        throw e;
+    }
+    return value;
+}
 export const WEBFETCH_GROUNDING_MIN_TEXT_CHARS = 200;
 const GROUNDING_MIN_TEXT_RATIO = 0.01;
 const GROUNDING_RATIO_MAX_TEXT_CHARS = 2_000;
@@ -230,6 +255,7 @@ async function fetchAllowlisted(doFetch, start, allowHosts, userAgent, signal, o
 }
 export function webFetchToolSpec(config = {}) {
     const maxBytes = resolveWebMaxBytes(config.maxBytes);
+    const fetchTimeoutMs = resolveWebTimeoutMs(config.timeoutMs, "WebFetch timeoutMs", DEFAULT_FETCH_TIMEOUT_MS);
     const doFetch = config.fetchImpl ?? globalThis.fetch;
     const canSummarize = config.summarize !== undefined;
     return {
@@ -276,7 +302,7 @@ export function webFetchToolSpec(config = {}) {
             }
             if (!doFetch)
                 return failure("Error (WebFetch): no fetch implementation available in this environment.");
-            const timeoutMs = config.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+            const timeoutMs = fetchTimeoutMs;
             const ac = new AbortController();
             const timer = setTimeout(() => ac.abort(), timeoutMs);
             const onOuterAbort = () => ac.abort();
@@ -794,7 +820,8 @@ function webSearchResultAllowed(url, allowed, blocked) {
     return true;
 }
 export function createWebSearchTool(config) {
-    const max = config.maxResults ?? 10;
+    const max = resolveSearchMaxResults(config.maxResults);
+    const searchTimeoutMs = resolveWebTimeoutMs(config.timeoutMs, "WebSearch timeoutMs", DEFAULT_SEARCH_TIMEOUT_MS);
     const currentMonthYear = new Date().toLocaleString("en-US", { month: "long", year: "numeric" });
     return {
         name: "WebSearch",
@@ -831,7 +858,7 @@ export function createWebSearchTool(config) {
             if (queryChars > SEARCH_QUERY_MAX_CHARS) {
                 return errorResult(`Error (WebSearch): the query is ${queryChars} characters, over the ${SEARCH_QUERY_MAX_CHARS}-character limit. Shorten it to the terms that matter — an identical retry will fail the same way.`, failCard({ retryable: false }));
             }
-            const timeoutMs = config.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+            const timeoutMs = searchTimeoutMs;
             const ac = new AbortController();
             const timer = setTimeout(() => ac.abort(), timeoutMs);
             const onOuterAbort = () => ac.abort();
@@ -936,7 +963,7 @@ export function createWebSearchTool(config) {
 }
 export function createSearxngSearchBackend(baseUrl, options = {}) {
     const doFetch = options.fetchImpl ?? globalThis.fetch;
-    const timeoutMs = options.timeoutMs ?? 10_000;
+    const timeoutMs = resolveWebTimeoutMs(options.timeoutMs, "createSearxngSearchBackend timeoutMs", 10_000);
     const parsedBase = new URL(baseUrl);
     parsedBase.hash = "";
     parsedBase.pathname = `${parsedBase.pathname.replace(/\/+$/, "")}/search`;
@@ -966,9 +993,9 @@ export function createSearxngSearchBackend(baseUrl, options = {}) {
     };
 }
 export async function probeSearchBackend(search, options) {
-    const budget = options?.timeoutMs ?? 15_000;
     let timer;
     try {
+        const budget = resolveWebTimeoutMs(options?.timeoutMs, "probeSearchBackend timeoutMs", 15_000);
         const results = await Promise.race([
             search("connectivity probe", AbortSignal.timeout(budget)),
             new Promise((_, reject) => {

package/package.json

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