@sema-agent/core 5.7.0 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 5.9.0 (2026-08-04)
+
+### Added
+
+- **A delegated child's permission ask reaches the parent's approval channel.** The parent run's effective approver (`spec.onAsk ?? deps.onAsk`) rides the trusted tool context into every child spec (sync / background / fork lanes share the one construction point), wrapped once with frozen provenance: `AskRequest.delegation` (new, optional, readonly) carries `{ parentToolCallId, depth, agentName? }` so an approval UI can render *which* delegation is asking — the innermost (true-origin) frame wins on grandchildren. New exported type `AskDelegationProvenance`. An approver is consulted once per gated call: the single-frame dedup compares approver identity *through* the wrapper (`askApproverIdentity`), so the provenance wrapper cannot split one consultation into two approval cards. **Consumer flips**: a probe pinning "a child's ask resolves at `deps.onAsk` when the parent supplied `spec.onAsk`" now resolves at the parent's approver; the `delegation` field is additive and ignorable.
+- **`tool_end.errorCode` (new, optional, additive)** — present iff `isError` is true and the harness result's `details` carried a string `code`; a machine-readable discriminator so a consumer never parses the result text. Engine vocabulary today: `"tool.not_found"` and `"gate.parked"` (an abort short-circuit poisoned this call because a durable gate parked the batch — the "Operation aborted" family; a plain user interrupt carries NO marker, pinned both ways). The abort texts are byte-identical to before — an exact-equality anchor on `"Operation aborted"` is unaffected. Frame-shape change, additive: this is the [2513]-process disclosure. Library embedders get the seam directly as `abortResultDetails` on the harness options / loop config.
+
+- `createOpenResponsesBrain` (+ `OpenResponsesBrainConfig`) — a Brain for the Open Responses wire form (`POST /responses`: typed input/output items, an SSE stream terminated by `response.completed` / `response.incomplete` / `response.failed` with no `[DONE]` sentinel). One adapter for the whole family of endpoints that speak it, instead of one per vendor. It is **stateless by contract**: `store` / `previous_response_id` / `conversation` are never sent, cannot be injected through `Model.extraBody` (all three are reserved for this API family), and every turn replays the full transcript — this engine stays the single transcript authority. Reasoning arrives as first-class `reasoning` items and is stored as normal `thinking` blocks (item id in `thinkingSignature`), replayed on tool-call turns. Terminal events map onto the existing vocabulary — no new `errorKind` or brain-error code is minted: a `max_output_tokens` cut with no answer text is `length_empty`, a content-filter cut and a streamed refusal are `[refusal]`, a stream with no terminal event is `[stream_torn]`, and `response.failed` maps by code onto `rate_limit` / `auth` / `invalid_request` / `server`. Because the wire form offers no capability discovery and endpoints have been observed to accept-and-ignore parameters, the adapter audits the `response.created` echo against what it requested and records divergences (state held that was never asked for, a reasoning tier not honored, serialized tool calls) as a `responses_capability` diagnostic on the final message. `StreamOptions.stop` has no field in this wire form and is REFUSED rather than silently dropped. Type-surface correction from the landing review: `OpenAIResponsesCompat` now declares exactly the knobs the adapter consumes (`supportsReasoningEffort` / `reasoningEffortLevels`); its two former fields (`sendSessionIdHeader` / `supportsLongCacheRetention`) had zero consumers anywhere in the engine and are removed — type-level only, no runtime behavior existed behind them.
+
+### BREAKING
+
+- **Declared-only fields removed from the public type surface (type-level only — no runtime behavior existed behind any of them).** A new gate, `gate:field-liveness`, walks every interface reachable from `src/index.ts` (directly exported, or reachable through a field of something that is) and reds on a member no production code under `src/` mentions. Its first run found 59; 34 are removed here. Setting any of them compiled, type-checked, and did nothing.
+  - `OpenAICompletionsCompat`: `supportsStore`, `supportsDeveloperRole`, `supportsUsageInStreaming`, `requiresToolResultName`, `requiresAssistantAfterToolResult`, `requiresThinkingAsText`, `openRouterRouting`, `vercelGatewayRouting`, `zaiToolStream`, `supportsStrictMode`, `cacheControlFormat`, `sendSessionAffinityHeaders`, `supportsLongCacheRetention`. Several documented a "Default: auto-detected from URL" that no code performs. The knobs the completions brain does read are unchanged: `supportsReasoningEffort`, `reasoningEffortLevels`, `maxTokensField`, `requiresReasoningContentOnAssistantMessages`, `thinkingFormat`.
+  - `AnthropicMessagesCompat`: `supportsEagerToolInputStreaming`, `supportsLongCacheRetention`, `sendSessionAffinityHeaders`, `supportsCacheControlOnTools`. The Anthropic brain performs each of those behaviours unconditionally or not at all, so declaring the opposite changed nothing. `thinkingMode`, `effortLevels`, `supportsTemperature`, `contextManagement`, `interleavedThinking` are unchanged.
+  - `OpenRouterRouting` and `VercelGatewayRouting` are removed entirely: both existed only as the types of the two removed routing fields, so nothing they described (fallbacks, ZDR, quantizations, price ceilings, throughput/latency floors, provider order) was ever sent on any request.
+  - `TextContent.textSignature` and its payload type `TextSignatureV1` — no brain wrote it and no replay path read it. The live equivalent is `ThinkingContent.thinkingSignature`.
+  - `ToolCall.thoughtSignature` — Google-specific, and there is no Google brain in this tree.
+  - `Model.mediaInput` — claimed to carry provider media limits "used by attachment preprocessing"; the image pipeline's caps come from `RunnerDeps.mediaByteCapBytes` and the resizer seam.
+  - `TraceEvent` (`kind: "brain.call"`): `callCap` and `capThinkingSkipped`, orphans of the design/130 per-call deadline shrink retired in 5.8.0 — the emitter went with the mechanism, the declaration stayed. `stopReason` is unchanged (its JSDoc no longer instructs consumers to judge cap binding by a field that is never emitted).
+  - `SemaTaskHandle.outputOffset` — never written by the registry and never read by anything.
+  - Migration: setting any removed field is now a compile error at the assignment. There is no runtime change to migrate — the behaviour a consumer sees is exactly what it saw before, because none of these fields ever reached code. The remaining 25 declared-only members are registered with a reason and an owner in `test/field-liveness-allowlist.json` (deployment-implemented adapter contracts, foreign on-disk formats, nominal brand phantoms, and the published recall seam); two of them carry a `PENDING VERDICT` marker with a review date rather than a clearance.
+- `LspDiagnosticsRegistry` is DEPLOYMENT-scoped (one per LSP manager, shared by every task), but its delivered-set had no run boundary: a diagnostic injected into one run was filtered out of every later run's drain for the lifetime of the process — a second session could not see it at all unless it happened to edit that file — and the set grew without bound. The delivered set is now keyed by run: `drain(runIdent)` and `fileEdited(runIdent, uri)` take the run key (both signatures changed), and the new `releaseRun(runIdent)` drops a finished run's keys. The engine passes the session id and releases at the run's terminal; direct callers of the registry must pass a key of their own.
+
+### Changed
+
+- Session permission rules: an `allowDirs` confinement now PATH-CONFINES `NotebookEdit` instead of denying it outright. Previously `createSessionRulePolicy` only knew the `file_path`-keyed write tools, so while `allowDirs` was active every `NotebookEdit` call fell into the "mutating but not path-confinable" arm and was denied — even for a notebook inside an allowed directory — while `createFsWriteGatePolicy` had always confined the same tool by its `notebook_path`. Both faces now share one covered set and one target extractor, so a notebook inside `allowDirs` is allowed, one outside is denied, and a decoy `file_path` never outranks the real `notebook_path` target. **A probe pinning "NotebookEdit is denied under `allowDirs`" will now flip** — re-pin it as a path verdict (in-dir allow / out-of-dir deny). Deliberately unchanged: every other mutating tool that cannot be path-confined (bash, deployment-authored write tools, tools with an unknown effect) is still fail-closed denied under `allowDirs`, and the skill-manifest `allowPaths` face still denies `NotebookEdit` — widening that one is a separate decision.
+
+### Changed
+
+- **A subagent's durable pause is reported as what it is.** The sync and fork report arms minted `status: failed` with "treat this delegation as failed; do not retry" when the child parked at an approval gate — a fabrication that buried the recovery path. They now mint one honest constructor: `status: suspended`, the checkpoint named, the deployment's approval channel named as the only release path, anti-retry guidance kept, `isError: true` now explicit on the report. `details.error` vocabulary: `unexpected.suspended` → `suspended.awaiting_approval`, `unexpected.needs_review` → `suspended.needs_review` (the TaskResult-level `unexpected.*` codes elsewhere are unchanged). The ineligible-background settle keeps its mechanism byte-for-byte but its row/summary/notification faces now say which disposition happened: new `errorCode` values `suspended.awaiting_approval` (checkpoint still pending, resolvable out-of-band) and `suspended.checkpoint_expired` (destroyed by the no-orphans rule — stop waiting). **Consumer flips**: probes pinning the old `status: failed` wording or the `unexpected.*` codes on delegation reports will red; anything pinning a closed set of background-failure `errorCode`s must admit the two new members.
+- Resumed-batch `tool_end` frames (durable-approval resume) carry the result body — `output` / `truncated` / `totalChars` / `structured` from the same projection the live loop uses; the deferred-sibling closes carry the `[DEFERRED]` body the transcript records. A client rendering tool output from frames no longer shows an empty card for every approved call ([2513] W2; zero shape change — these are the frame's existing optional fields, previously absent). The same frames now also carry `eventId` (+ `parentToolCallId`/`sourceTaskId` when running as a subagent) and reach a parent's `forwardSubagentEvents` pane — a child's durable-approved call no longer leaves the parent's viewing pane spinner open forever.
+
+### Fixed
+
+- Workflow resilience knobs (`stallMs` / `agentMaxRetries` / `throttleBackoffMs` / `totalTimeoutMs`) refuse non-finite values loudly instead of silently changing behavior — a NaN used to disarm the stall watchdog, zero the retry budget, or turn the total deadline into an instant abort (`stallMs <= 0` stays the documented explicit-off). `WebFetchConfig.maxBytes` likewise refuses non-finite/non-positive values (`config.web_max_bytes_invalid`) — NaN/Infinity used to disable the byte budget entirely, streaming unbounded into memory (±Infinity gets its own message: the cap cannot be turned off, only widened).
+- The WebFetch binary sniffer consumes the shared magic-byte table (`BINARY_MAGIC_SIGNATURES`) instead of a private eight-format if-chain — one data source; edge behavior tightens slightly (full-length signatures) and labels adopt the table's human-readable names.
+- Platform terminals (`env.lifetime_expired` / `usage.window_exhausted`) now carry `salvagedOutput` like every other salvage-eligible terminal (the eligibility set is one closed construction point) — **a consumer pinning "salvagedOutput is empty on every non-completed result" will flip**. `TaskResult.retryAfterMs` (new, optional) rides a `usage.window_exhausted` terminal with the window's reopen hint; presence condition documented on the field — judge the cause by `errorCode`, never by this field's presence.
+- `assertWorkflowDeterminism` reaches the package root alongside its two conformance siblings (the determinism battery an out-of-repo workflow runner needs; additive).
+
+
+- `runCascade` no longer reaches its tail with nothing dispatched. A non-finite `config.maxEscalations` is refused at the door (`Error.code = "config.cascade_invalid"`) instead of making the iteration bound `NaN` and running zero rungs; a `totalTimeoutMs` already spent at entry returns the cascade's own terminal (`status: "failed"`, `errorCode: "cascade.budget_exhausted"`, empty `attempts`, `finalRung: -1`) instead of throwing a bare `TypeError`. `CascadeRunResult.finalRung` can therefore be `-1` (no rung produced the result).
+
+## 5.8.0 (2026-08-04)
+
+_The limits restructure: time leaves the task-limit axis, tokens become the primary budget, and every default is empty. One release, five construction stages — there is no intermediate version. Old usage fails loudly (compile errors for removed fields; a typed refusal for unknown limit keys at runtime) — nothing is silently ignored._
+
+### BREAKING — task limits (`TaskSpec.limits` is the one budget surface)
+
+- `limits` now holds every budget knob: `maxTokens` (primary, cumulative per-slice window — promoted from report-only to a GATE) / `maxCostUsd` / `maxTurns` / `maxWalltimeMs` (opt-in, per-slice active clock, **milliseconds**) / `maxOutputTokens` (unchanged, per-request shape) / `approachNotice` / `budgetStreamCancel` / `degrade` / `brainCallGuardrailMs`. The former top-level `maxTokens` / `maxCostUsd` / `budgetStreamCancel` / `degrade` fields are gone.
+- `limits.timeoutSec` is REMOVED (unit and semantics changed → `maxWalltimeMs`). An unknown key on `limits` is refused at prepare with `config.limit_unknown_key` naming the replacement and the unit; a non-finite or negative value refuses with `config.limit_invalid`. Never silently ignored.
+- EVERY default is empty: `DEFAULT_MAX_TURNS=1000`, `FORK_DEFAULT_MAX_TURNS=200`, the session-scoped background child's injected 30-minute wall clock, the resource-suspend `maxSlices=100` default, and the workflow per-agent 300s cap are all retired. No limit is armed unless configured. Anti-zombie coverage for session-scoped background children moved to the stale-running reaper (`TaskRegistry.reapStaleSessionBackgroundAgents` — collects by STALL, not by wall age). Honest consequence, stated plainly: a zero-config task with a non-terminating brain loop now has no task-level backstop — the engineering guardrails (brain-call guardrail, stall detection) keep it from wedging silently, and the deployment governance windows are the burn ceiling.
+- To-limit behavior is two-tier: WITHOUT `resourceSuspend`, hitting any limit is a loud terminal failure — `TaskResult.status` loses `"timeout"`; all four axes end as `failed` with `limits.max_tokens_exceeded` / `limits.max_cost_exceeded` / `limits.max_turns_exceeded` / `limits.max_walltime_exceeded` (the code names the AXIS, replacing `limit.timeout` / `limit.max_turns` / `budget.exceeded` / `budget.precall`), salvage attached. WITH `resourceSuspend` (+ checkpoint infrastructure), a per-slice window exhaustion suspends with a checkpoint and resume grants the next window; only the optional frozen totals (`resourceSuspend.totalTokens` / `totalBudgetUsd`) are hard stops. `ResourceLimitReason` splits `"budget"` into `"budget_tokens"` / `"budget_cost"` — consumers pinning either closed set are affected and named here.
+- Priority when several axes trip at one boundary: tokens > cost > turns > walltime (attribution only — every configured axis stays armed).
+- `limits.approachNotice` replaces `deadlineNudge`: one "start converging" frame at ~80% and one "deliver now" at ~95% of the tightest configured budget, measured in BUDGET (tokens/cost/turns), never in clock; one-shot; `stats.mechanisms.approachNoticesSent`; a continuation gate keeps the notice from extending a run the model had already ended.
+
+### BREAKING — retired mechanisms
+
+- The design/128/130 deadline family is gone: `deadlineNudge` / `callCapByDeadline` / `gracefulFinalize`, the write-out cushion mathematics, and the per-call deadline shrink.
+- tool-cut is gone end to end: `stats.mechanisms.{toolCuts,toolCutKills,pendingCutTools,finalizeInjected,nudgesSent,capShrinks,callCutoffs,toolClamps}`, `engineCut:"walltime_writeout"`, the bash exec deadline clamp, and `cut-kill.ts`.
+- The brain soft-cutoff is gone: `errorKind:"walltime_cutoff"`, `WALLTIME_CUTOFF_MESSAGE`, `StreamOptions.callDeadlineMs`, the loop's `walltime_cutoff_recovery`.
+- auto-compaction's walltime gate / abort race / throughput EWMA are gone (`clampReason` loses `"walltime"`).
+- Stall detection (connect / first-token / idle) is DECOUPLED from the retired walltime lane and now arms unconditionally (guardrail class; constants renamed `STALL_*`; knob semantics unchanged).
+- The `ExecutionEnv.exec` `onSpawn` / `onDetachAdopted` seam is retired (its only consumer left with tool-cut; zero producers remained).
+- The Terminal-Bench surface is retired: the `sema-tb` bin, `tb-env`, the `tb/` adapter tree, and all thirteen `TB_*` env knobs. No switch survives.
+
+### BREAKING — checkpoint / ledger / config
+
+- `ResourceLedger.totalWalltimeSec` and `remainingWalltimeMs()` retired; `totalTokens` + `remainingTokens()` added; `spentWalltimeMs` REMAINS (accounting only). Checkpoint version 5 (`TOKEN_CHECKPOINT_VERSION`); a v4 checkpoint carrying the retired wall-clock allocation is refused pre-CAS with `checkpoint.walltime_axis_retired` (the checkpoint stays pending — finish it on the previous release, or start fresh; no silent migration). `resourceSuspend.totalWalltimeSec` → `resourceSuspend.totalTokens`.
+- Config catalog: `limits.{timeoutSec,deadlineNudge,callCapByDeadline,gracefulFinalize}`, `budget.{maxCostUsd,maxTokens,totalWalltimeSec}`, `delegation.{forkMaxTurns,sessionBgTimeoutSec}` retired/moved; `limits.{maxWalltimeMs,approachNotice,maxTokens,maxCostUsd}`, `budget.totalTokens` added. Workflow script `limits` whitelist: `{maxTurns,timeoutSec}` → `{maxTurns,maxWalltimeMs,maxTokens,maxCostUsd}`; `WorkflowChildCaps.perAgentTimeoutSec` → `perAgentMaxWalltimeMs` (no default).
+- Workflow resume journals from 5.7 cache-miss entirely on this version (the spec shape participates in the call identity) — reruns, not errors.
+- Trace: the eight mechanisms fields above are gone; `timerLatenessMs` / `walltimeSyncBackstopFired` REMAIN (the per-slice wall timer survives as `maxWalltimeMs`, so its starvation evidence keeps a producer).
+
+### Fixed
+
+- memory-engine: partition adoption is a single atomic rename (the delete-then-rename window could destroy a concurrently adopted partition and then disclose the opposite of what happened); fileless-scaffolding cleanup uses `rmdir` only, so a peer's files are unremovable by construction. Both control-plane lock waits are bounded and yield every round — a permanent errno can no longer starve the event loop in a silent spin (the fail-open sidecar lock now honors its documented "proceed anyway" by going lockless after three post-deadline steal rounds).
+- cc stores: the mailbox sweep AND `drop` now judge and delete inside the box's cross-process lock (a compliant writer's freshly committed message can no longer be deleted unseen, and another holder's lock directory is never torn down); the cc lockfile's retry bound is read before every round (three `continue` shortcuts skipped it — a permanently failing reclaim spun forever); the lease table's entry keys fold the same way the table itself does (two store instances over one directory via a symlink could each grant the same lease).
+- session policy: the tighten gate's path-containment fold is win-family-conditional, matching the runtime's — a POSIX sibling directory whose literal name embeds backslashes no longer reads as "within" the confined root (a loosening the gate exists to refuse). The transcript-dir gate's write-tool literal gains a mechanical sync pin against `PATH_WRITE_TOOLS`.
+- `tool-name-aliases` docstring named a compile-time enforcement symbol that never existed; it now states the real division of labor (the prepare-time audit escalates, the compile pass deliberately does not).
+
 ## 5.7.0 (2026-08-04)
 
 _Three collected cars: a parked question is answered by the decision itself (behavior face — see the consumer note), a descendant's terminal notification anchors on the delegation tree, and the env scrub stops deleting infrastructure key names (behavior face)._

package/dist/agents/cascade.d.ts

@@ -6,7 +6,7 @@ export type GateVerdict = boolean | {
 };
 export interface CascadeRung {
     model: ModelRef;
-    overrides?: Partial<Pick<TaskSpec, "limits" | "degrade" | "systemPrompt">>;
+    overrides?: Partial<Pick<TaskSpec, "limits" | "systemPrompt">>;
 }
 export interface CascadeConfig {
     onNotifyError?: (failure: import("../core/safe-notify.js").SafeNotifyFailure) => void;

package/dist/agents/cascade.js

@@ -3,6 +3,13 @@ import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
 import { buildCumulativeStats } from "./cumulative-stats.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 const CASCADE_ON_RUNG_SITE = "cascade.onRung";
+const CASCADE_CONFIG_ERROR_CODE = "config.cascade_invalid";
+const CASCADE_NO_DISPATCH_ERROR_CODE = "cascade.budget_exhausted";
+function cascadeConfigError(message) {
+    const e = new Error(message);
+    e.code = CASCADE_CONFIG_ERROR_CODE;
+    return e;
+}
 function createDefaultGate(spec) {
     const requiresStructured = spec.outputSchema != null;
     return (result) => result.status === "completed" && (!requiresStructured || result.structuredOutput !== undefined);
@@ -13,6 +20,9 @@ export async function runCascade(runner, spec, config) {
         throw new Error("runCascade: config.ladder must have at least one rung");
     }
     const maxEscalations = config.maxEscalations ?? ladder.length - 1;
+    if (typeof maxEscalations !== "number" || !Number.isFinite(maxEscalations)) {
+        throw cascadeConfigError(`runCascade: config.maxEscalations must be a finite number (got ${String(config.maxEscalations)}) — an unevaluable escalation ceiling is not a ceiling, and folding it to a default would run the cascade under a bound nobody chose.`);
+    }
     const maxRungs = Math.min(ladder.length, Math.max(0, maxEscalations) + 1);
     const gate = config.gate ?? createDefaultGate(spec);
     const startedAt = Date.now();
@@ -179,6 +189,20 @@ export async function runCascade(runner, spec, config) {
             break;
         }
     }
+    if (lastResult === undefined) {
+        return {
+            taskId: spec.taskId ?? "",
+            sessionId: "",
+            status: "failed",
+            result: `runCascade: the overall wall-clock budget (totalTimeoutMs ${config.totalTimeoutMs}ms) was already spent when the ladder was entered — no rung dispatched`,
+            errorCode: CASCADE_NO_DISPATCH_ERROR_CODE,
+            stats: { tokens: 0, turns: 0, costMicroUsd: 0 },
+            cascadeOutcome: "exhausted",
+            escalated: false,
+            finalRung: -1,
+            attempts,
+        };
+    }
     const base = lastResult;
     const finalRung = attempts.length - 1;
     return {

package/dist/agents/subagent.d.ts

@@ -1,10 +1,10 @@
 import type { Runner } from "../core/runner/runtask.js";
-import type { AgentDefinition, Model, ModelRef, ToolSpec } from "../core/types.js";
+import type { AgentDefinition, Model, ModelRef, TaskLimits, ToolSpec } from "../core/types.js";
 import { type ExecutionEnv } from "../internal/harness.js";
 import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
-import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
-export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
+import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
+export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SubagentRetainLedger } from "./retain-ledger.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
 export declare function notifyResultField(result: string | undefined): string | undefined;
@@ -43,6 +43,9 @@ export declare function classifySubagentError(child: {
     errorKind: SubagentErrorKind;
     retryable: boolean;
 } | undefined;
+export declare const SUBAGENT_SUSPENDED_AWAITING_APPROVAL = "suspended.awaiting_approval";
+export declare const SUBAGENT_SUSPENDED_NEEDS_REVIEW = "suspended.needs_review";
+export declare const SUBAGENT_SUSPENDED_CHECKPOINT_EXPIRED = "suspended.checkpoint_expired";
 export interface SubagentSteerHandle {
     parentToolCallId: string;
     agentName?: string;
@@ -101,10 +104,7 @@ export interface SubagentToolOptions {
     systemPrompt?: string;
     name?: string;
     purpose?: string;
-    limits?: {
-        maxTurns?: number;
-        timeoutSec?: number;
-    };
+    limits?: TaskLimits;
     maxDepth?: number;
     retainFailedSessions?: boolean;
     onObserverError?: (err: unknown, info: {

package/dist/agents/subagent.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
+import { withDelegationProvenance } from "../core/tool-policy.js";
 import { resolveModel, resolveModelDisplayLabel } from "../core/roles.js";
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
@@ -17,7 +18,7 @@ import { addWorktree } from "../core/git-worktree-env.js";
 import { shellQuote } from "../tools/fs/search.js";
 import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { extractErrorCode } from "../brain/errors.js";
-import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
+import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 function rollupDelegatedCost(stats, nested) {
     if (stats.costMicroUsd === undefined)
         return undefined;
@@ -29,7 +30,7 @@ function delegatedCostField(stats) {
     const total = rollupDelegatedCost(stats, stats.nested);
     return total !== undefined ? { costMicroUsd: total } : {};
 }
-export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
+export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { recordRosterSpawn } from "./roster-store.js";
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
@@ -224,20 +225,55 @@ export function classifySubagentError(child) {
         ? "rate_limit"
         : code === "server" && (msg.includes("overloaded") || msg.includes("529"))
             ? "overloaded"
-            : code === "limit.timeout" || ((code === "network" || code === "server") && msg.includes("timeout"))
+            : code === "limits.max_walltime_exceeded" || ((code === "network" || code === "server") && msg.includes("timeout"))
                 ? "timeout"
                 : code === "network" || code === "server"
                     ? "network"
                     : "logic";
     return { errorKind, retryable: errorKind !== "logic" };
 }
+export const SUBAGENT_SUSPENDED_AWAITING_APPROVAL = "suspended.awaiting_approval";
+export const SUBAGENT_SUSPENDED_NEEDS_REVIEW = "suspended.needs_review";
+export const SUBAGENT_SUSPENDED_CHECKPOINT_EXPIRED = "suspended.checkpoint_expired";
+function durablePauseDelegationReport(reportLabel, child) {
+    const needsReview = child.status === "needs_review";
+    const token = child.checkpointToken;
+    return {
+        isError: true,
+        content: `[Sub-agent report${reportLabel}]\n` +
+            `status: suspended\n` +
+            `This delegation is PARKED at an approval gate — it did not fail, and it is not finished. ` +
+            `${needsReview ? "A human review" : "An approval"} it cannot grant itself is pending` +
+            `${token !== undefined ? `, held by checkpoint ${token}` : " (the run reported no checkpoint token)"}. ` +
+            `The gated action has NOT run.\n` +
+            `Only the deployment's approval channel can release it: you cannot approve it from here, and no ` +
+            `result from it will arrive in this turn. Do not re-issue the same approval-gated action — an ` +
+            `identical retry parks again and resolves nothing. Carry on with work that does not depend on ` +
+            `this delegation, or report that it is awaiting approval.`,
+        details: {
+            error: needsReview ? SUBAGENT_SUSPENDED_NEEDS_REVIEW : SUBAGENT_SUSPENDED_AWAITING_APPROVAL,
+            ...(token !== undefined ? { checkpointToken: token } : {}),
+        },
+    };
+}
+function unparkedDurablePauseReason(d) {
+    return d.kind === "no_park_lane"
+        ? `the agent hit an approval gate and paused durably, but this delegation cannot be parked ` +
+            `(parking needs an explicitly named child plus a durable agent row, a checkpoint store and the ` +
+            `durable-session capability). Its checkpoint ${d.checkpointToken} is still committed and the ` +
+            `approval must be resolved through the deployment's approval channel; the gated action never ran.`
+        : `the agent hit an approval gate and paused durably, but the park did not take (` +
+            `${d.cause === "capability_veto" ? "the durable-session capability refused" : "a concurrent stop won the arbitration"}` +
+            `), so its checkpoint was expired under the no-orphans rule. Nothing is pending approval and the ` +
+            `gated action never ran — re-run this delegation with an approver attached.`;
+}
 function errorKindClause(c) {
     return c !== undefined ? ` (error_kind: ${c.errorKind}, retryable: ${c.retryable})` : "";
 }
 const FAILED_SESSION_RETAIN_TTL_MS = 15 * 60 * 1000;
 const PARTIAL_FINDINGS_MAX_CHARS = 1200;
 const BG_NOTIFY_DRAIN_WINDOW_MS = 2_000;
-function createBgActivityBeat(parentToolCallId, emitTick) {
+function createBgActivityBeat(parentToolCallId, emitTick, noteActivity) {
     let beats = 0;
     let starts = 0;
     return (e) => {
@@ -248,6 +284,7 @@ function createBgActivityBeat(parentToolCallId, emitTick) {
         if (e.type === "tool_start")
             starts += 1;
         beats += 1;
+        noteActivity?.();
         if (beats === 1 || beats % RUNNING_AGENT_OBSERVE_EVERY_BEATS === 0)
             emitTick(starts);
     };
@@ -395,7 +432,7 @@ export function createSubagentResume(deps) {
                     ...(currentTool !== undefined ? { currentTool } : {}),
                     usage: { toolUses: toolStarts },
                 });
-            });
+            }, deps.registry !== undefined && deps.taskId !== undefined ? () => deps.registry.noteBackgroundAgentActivity(deps.taskId) : undefined);
             stream = childRunner.runTaskStream(resumeSpec, undefined, {
                 ...entry.internalsSnapshot,
                 ...(true
@@ -1149,11 +1186,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
             const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
-            const childLimits = defMaxTurns !== undefined
-                ? { ...opts.limits, maxTurns: defMaxTurns }
-                : wantsFork && opts.limits?.maxTurns === undefined
-                    ? { ...opts.limits, maxTurns: FORK_DEFAULT_MAX_TURNS }
-                    : opts.limits;
+            const childLimits = defMaxTurns !== undefined ? { ...opts.limits, maxTurns: defMaxTurns } : opts.limits;
             const nextExcluded = def ? new Set([...excluded, def.name]) : excluded;
             const defAllowsDelegation = def === undefined || toolNameAllowed(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME, def.allowTools, def.denyTools);
             if (depth + 1 < maxDepth && defAllowsDelegation) {
@@ -1233,7 +1266,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     enableBlockedReport: false,
                     limits: {
                         maxTurns: typeof observerDef.maxTurns === "number" && Number.isFinite(observerDef.maxTurns) && observerDef.maxTurns > 0 ? observerDef.maxTurns : 8,
-                        timeoutSec: 120,
+                        maxWalltimeMs: 120_000,
                     },
                 });
                 const runObserverLeg = async (spec) => {
@@ -1406,6 +1439,14 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.onSubagentSpawn ? { onSubagentSpawn: ctx.onSubagentSpawn } : {}),
             };
             const childThinking = def?.thinking ?? ctx.thinkingLevel;
+            const provenanceAgentName = agentName ?? def?.name;
+            const childOnAsk = ctx.onAsk !== undefined
+                ? withDelegationProvenance(ctx.onAsk, {
+                    parentToolCallId: ctx.toolCallId,
+                    depth: depth + 1,
+                    ...(provenanceAgentName !== undefined ? { agentName: provenanceAgentName } : {}),
+                })
+                : undefined;
             const buildChildSpec = (signal) => ({
                 objective: prompt,
                 ...(childModel ? { model: childModel } : { modelRole: "subagent" }),
@@ -1415,6 +1456,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(def?.memory ? { memory: def.memory } : {}),
                 ...(def?.skills?.length ? { skills: def.skills } : {}),
                 ...(ctx.principal !== undefined ? { principal: ctx.principal } : {}),
+                ...(childOnAsk !== undefined ? { onAsk: childOnAsk } : {}),
                 ...(ctx.clientContext !== undefined ? { clientContext: ctx.clientContext } : {}),
                 ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),
                 ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
@@ -1722,9 +1764,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     });
                     const forkBgStartedAt = Date.now();
                     const bgForkSpec = { ...buildChildSpec(abort.signal), sessionId: forkedId, requireExistingSession: true, objective: forkObjective };
-                    if (sessionScopedBg && bgForkSpec.limits?.timeoutSec === undefined) {
-                        bgForkSpec.limits = { ...(bgForkSpec.limits ?? {}), timeoutSec: SESSION_BG_DEFAULT_TIMEOUT_SEC };
-                    }
                     const s2ForkNotifyReady = (inject) => {
                         bg.registry.attachAgentNotify(taskId, inject);
                     };
@@ -1744,7 +1783,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(currentTool !== undefined ? { currentTool } : {}),
                             usage: { toolUses: toolStarts },
                         });
-                    });
+                    }, () => bg.registry.noteBackgroundAgentActivity(taskId));
                     const bgForkInternals = bgSink
                         ? {
                             ...forkInternals,
@@ -1977,11 +2016,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     costMicroUsd: rollupDelegatedCost(forkChild.stats, nsf),
                 });
                 if (isDurablePause(forkChild.status)) {
-                    return {
-                        content: `[Sub-agent report · ${FORK_SUBAGENT_TYPE}]\nstatus: failed\nerror: unexpected durable pause (${forkChild.status}, checkpoint ` +
-                            `${String(forkChild.checkpointToken ?? "?")}) — treat this fork as failed; do not retry the same gated action.`,
-                        details: { error: forkChild.status === "needs_review" ? "unexpected.needs_review" : "unexpected.suspended", checkpointToken: forkChild.checkpointToken },
-                    };
+                    return durablePauseDelegationReport(` · ${FORK_SUBAGENT_TYPE}`, forkChild);
                 }
                 const wtLine = await finishWorktree();
                 const forkErr = classifySubagentError(forkChild);
@@ -2195,9 +2230,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(forwardDurableApproval ? { durableApproval: { ...ctx.durableApprovalForChildren } } : {}),
                     ...(reviveRow !== undefined ? { requireExistingSession: true } : {}),
                 };
-                if ((sessionScopedBg || reviveRow !== undefined) && bgSpec.limits?.timeoutSec === undefined) {
-                    bgSpec.limits = { ...(bgSpec.limits ?? {}), timeoutSec: SESSION_BG_DEFAULT_TIMEOUT_SEC };
-                }
                 let reviveAttachedResolve;
                 const reviveAttached = reviveRow !== undefined ? new Promise((r) => (reviveAttachedResolve = r)) : undefined;
                 const s2NotifyReady = (inject) => {
@@ -2222,7 +2254,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(currentTool !== undefined ? { currentTool } : {}),
                         usage: { toolUses: toolStarts },
                     });
-                });
+                }, () => bg.registry.noteBackgroundAgentActivity(taskId));
                 const bgInternals = bgSink
                     ? {
                         ...childInternals,
@@ -2417,6 +2449,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         else
                             bgRetainLedger?.markSettled(ctx.toolCallId);
                     }
+                    let unparkedPause;
                     if (isDurablePause(child.status) && child.checkpointToken !== undefined) {
                         const cpStore = bg.checkpointStore;
                         const expireByStoreScope = async (token2) => {
@@ -2461,14 +2494,27 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 if (parked === "parked")
                                     return;
                                 await expireByStoreScope(token);
+                                unparkedPause = { kind: "checkpoint_expired", cause: attested ? "park_lost" : "capability_veto" };
                             }
                         }
+                        else {
+                            unparkedPause = { kind: "no_park_lane", checkpointToken: child.checkpointToken };
+                        }
                     }
                     const ok = child.status === "completed";
                     const reaped = !ok && abort.signal.aborted;
                     const collateral = reaped && bg.registry.getAccessibleTask(taskId, { ...(bgOwner !== undefined ? { owner: bgOwner } : {}), ...(bgScope !== undefined ? { scope: bgScope } : {}) })?.status === "running";
                     const failedBg = !ok && !reaped;
-                    const errCodeBg = failedBg ? (child.errorCode ?? extractErrorCode(child.errorMessage)) : undefined;
+                    const unparkedPauseReason = unparkedPause !== undefined && failedBg ? unparkedDurablePauseReason(unparkedPause) : undefined;
+                    const errCodeBg = failedBg
+                        ? unparkedPause !== undefined
+                            ? unparkedPause.kind === "no_park_lane"
+                                ? child.status === "needs_review"
+                                    ? SUBAGENT_SUSPENDED_NEEDS_REVIEW
+                                    : SUBAGENT_SUSPENDED_AWAITING_APPROVAL
+                                : SUBAGENT_SUSPENDED_CHECKPOINT_EXPIRED
+                            : (child.errorCode ?? extractErrorCode(child.errorMessage))
+                        : undefined;
                     const errClassBg = failedBg
                         ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
                         : undefined;
@@ -2477,7 +2523,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         status: ok ? "completed" : reaped ? "killed" : "failed",
                         seq: seqAtSettle ?? 1,
                         ...resultSettleFields(child.result),
-                        ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
+                        ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? child.errorMessage ?? String(child.status) } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
                     }) ??
@@ -2495,7 +2541,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     const residual = residualFields();
                     const resumableBg = bgRetain !== undefined && settled !== "killed";
-                    const failReasonBg = settled === "failed" ? child.errorMessage : undefined;
+                    const failReasonBg = settled === "failed" ? unparkedPauseReason ?? child.errorMessage : undefined;
                     const bgTerminalSummary = failReasonBg !== undefined
                         ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
                         : `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${observerNote}`;
@@ -2737,12 +2783,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             if (isDurablePause(child.status)) {
                 if (retainEntry)
                     ctx.subagentRetain?.abandon(ctx.toolCallId);
-                return {
-                    content: `[Sub-agent report${def ? ` · ${def.name}` : ""}]\n` +
-                        `status: failed\nerror: unexpected durable pause (${child.status}, checkpoint ${String(child.checkpointToken ?? "?")}) — ` +
-                        `treat this delegation as failed; do not retry with the same approval-gated action.`,
-                    details: { error: child.status === "needs_review" ? "unexpected.needs_review" : "unexpected.suspended", checkpointToken: child.checkpointToken },
-                };
+                return durablePauseDelegationReport(def ? ` · ${def.name}` : "", child);
             }
             let failureRetained = false;
             if (!retainEntry) {

package/dist/agents/teacher.js

@@ -192,7 +192,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
             ...helperBase(),
             objective: helperObjective,
             enableBlockedReport: false,
-            limits: { maxTurns: 1, timeoutSec: studentSpec.limits?.timeoutSec },
+            limits: { maxTurns: 1, ...(studentSpec.limits?.maxWalltimeMs !== undefined ? { maxWalltimeMs: studentSpec.limits.maxWalltimeMs } : {}) },
             signal: extSignal,
         });
         await runner.sessions.release(r.sessionId).catch(() => undefined);
@@ -341,7 +341,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
             ...teacherModelFields(),
             systemPrompt: teacher.prompts?.teacher ?? TEACHER_PROMPT,
             enableBlockedReport: false,
-            limits: { maxTurns: 4, timeoutSec: studentSpec.limits?.timeoutSec },
+            limits: { maxTurns: 4, ...(studentSpec.limits?.maxWalltimeMs !== undefined ? { maxWalltimeMs: studentSpec.limits.maxWalltimeMs } : {}) },
             signal: extSignal,
         });
         await runner.sessions.release(r.sessionId).catch(() => undefined);
@@ -363,7 +363,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         else if (result.status === "blocked") {
             trigger = "blocked";
         }
-        else if (result.status === "failed" || result.status === "timeout") {
+        else if (result.status === "failed") {
             trigger = "failed";
         }
         else if (!verifyOutput) {

package/dist/agents/team.d.ts

@@ -56,7 +56,7 @@ export interface TeamDiscussionOptions {
     };
     onEvent?: (e: TeamEvent) => void;
     limits?: {
-        timeoutSec?: number;
+        maxWalltimeMs?: number;
         maxTurns?: number;
         maxTokens?: number;
         maxCostUsd?: number;

package/dist/agents/team.js

@@ -63,7 +63,7 @@ export async function runTeamDiscussion(opts) {
             : undefined;
     const memberLimits = opts.limits
         ? {
-            ...(opts.limits.timeoutSec !== undefined ? { timeoutSec: opts.limits.timeoutSec } : {}),
+            ...(opts.limits.maxWalltimeMs !== undefined ? { maxWalltimeMs: opts.limits.maxWalltimeMs } : {}),
             ...(opts.limits.maxTurns !== undefined ? { maxTurns: opts.limits.maxTurns } : {}),
         }
         : undefined;

package/dist/agents/verify.js

@@ -101,7 +101,7 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             handsReadOnly: config.verifierHandsReadOnly ?? true,
             outputSchema: VerdictSchema,
             enableBlockedReport: false,
-            limits: { timeoutSec: specBase.limits?.timeoutSec },
+            limits: { ...(specBase.limits?.maxWalltimeMs !== undefined ? { maxWalltimeMs: specBase.limits.maxWalltimeMs } : {}) },
             getApiKeyAndHeaders: specBase.getApiKeyAndHeaders,
             signal: specBase.signal,
         });