skillscript-runtime 0.34.0 → 0.35.0

package/dist/runtime.js

@@ -6,7 +6,7 @@ import { validateQualifiedDispatch } from "./dispatch-validate.js";
 import { spawn } from "node:child_process";
 import { readFile as fsReadFile, writeFile as fsWriteFile, mkdir as fsMkdir } from "node:fs/promises";
 import { dirname as pathDirname } from "node:path";
-import { OpError, ConnectorNotFoundError, OpTimeoutError, UnsafeShellDisabledError, ShellBinaryNotAllowedError, UnresolvedVariableError, TypeMismatchError, MissingSkillReferenceError, UnconfirmedMutationError, SecuredModeEffectError, FilePathNotAllowedError, messageOf, } from "./errors.js";
+import { OpError, ConnectorNotFoundError, OpTimeoutError, RunDeadlineExceeded, UnsafeShellDisabledError, ShellBinaryNotAllowedError, UnresolvedVariableError, TypeMismatchError, MissingSkillReferenceError, UnconfirmedMutationError, SecuredModeEffectError, FilePathNotAllowedError, messageOf, } from "./errors.js";
 import { isPathUnderAllowedRoot } from "./safe-path.js";
 import { isSecuredMode } from "./approval.js";
 import { classifyMutation, authorizationGranted, buildAuthorizationSuggestion, } from "./mutation-gate.js";
@@ -149,59 +149,141 @@ export async function execute(parsed, initialVars, order, ctx) {
     // v0.9.6 — stash skill identity onto ctx so deep-stack op handlers
     // (notify()) can read for DeliveryMeta without threading `parsed`
     // through every call hop. Internal convention; do not set from outside.
-    ctx = { ...ctx, _currentSkillName: skillName, _currentSkillEventType: parsed.eventType, _currentSkillSecretRequires: parsed.secretRequires };
+    // Run-total deadline (# Deadline:). Resolve ONCE at the root (`ctx.deadlineMs`
+    // undefined) into an absolute wall-clock instant; a child inherits the parent's
+    // instant via this same spread and can only TIGHTEN it with its own
+    // # Deadline: (`min`), never loosen the root bound (Perry decision #2). Opt-in:
+    // no # Deadline: and nothing inherited => undefined => today's per-op behavior.
+    let deadlineMs = ctx.deadlineMs;
+    // Budget (declared duration) + origin travel alongside the absolute instant so
+    // the RunDeadlineExceeded message reports what was set, not an epoch number.
+    // Inherited from the parent by default; overwritten only when a tighter local
+    // bound wins below (so the message names the bound that actually fired).
+    let deadlineBudgetMs = ctx.deadlineBudgetMs;
+    let deadlineSource = ctx.deadlineSource;
+    // Operator ceiling FIRST: it bounds every run, even one with no `# Deadline:`,
+    // so an untrusted author can't evade the bound by omitting it. Keeps the
+    // tighter of it and any inherited/injected deadline. (Harmless to re-apply in a
+    // child — the inherited root bound is always ≤ a fresh child ceiling, so the
+    // `<` never fires there.)
+    if (ctx.maxDeadlineMs !== undefined) {
+        const opMaxInstant = nowMs + ctx.maxDeadlineMs;
+        if (deadlineMs === undefined || opMaxInstant < deadlineMs) {
+            deadlineMs = opMaxInstant;
+            deadlineBudgetMs = ctx.maxDeadlineMs;
+            deadlineSource = "operator ceiling";
+        }
+    }
+    // A skill's own `# Deadline:` can only TIGHTEN — never loosen past the operator
+    // ceiling or the inherited parent bound.
+    if (parsed.deadline !== null) {
+        const budgetMs = resolveIntParam(parsed.deadline, vars, "# Deadline:") * 1000;
+        const candidate = nowMs + budgetMs;
+        if (deadlineMs === undefined || candidate < deadlineMs) {
+            deadlineMs = candidate;
+            deadlineBudgetMs = budgetMs;
+            deadlineSource = "# Deadline";
+        }
+    }
+    ctx = { ...ctx, _currentSkillName: skillName, _currentSkillEventType: parsed.eventType, _currentSkillSecretRequires: parsed.secretRequires, _insideExecute: true, ...(deadlineMs !== undefined ? { deadlineMs } : {}), ...(deadlineBudgetMs !== undefined ? { deadlineBudgetMs } : {}), ...(deadlineSource !== undefined ? { deadlineSource } : {}) };
     const traceBuilder = shouldTraceFire(ctx.trace, triggerId, skillName)
         ? new TraceBuilder(skillName, ctx.skillVersion ?? "unknown", triggerCtx, { agent_id: ctx.agentId }, ctx.preMintedTraceId)
         : null;
-    for (const targetName of order) {
-        const target = parsed.targets.get(targetName);
-        if (!target)
-            continue;
-        let targetLastBound = null;
-        let targetLastValue = undefined;
-        // Fresh mutation-auth state per target. `skillAutonomous` is set from
-        // the parsed header. v0.16.0 retired the `sawConfirm` path with the
-        // `ask` op removal.
-        const authState = {
-            skillAutonomous: parsed.autonomous === true,
-        };
-        try {
-            const r = await execOps(target.ops, vars, emissions, fallbacks, ctx, targetName, parsed.timeout, absoluteTimeoutMs, traceBuilder, authState);
-            targetLastBound = r.lastBoundVar;
-            targetLastValue = r.lastBoundVar !== null ? vars.get(r.lastBoundVar) : r.lastValue;
-        }
-        catch (err) {
-            errors.push(buildExecutionError(err, targetName));
-            if (target.elseBlock !== undefined) {
-                try {
-                    const r = await execOps(target.elseBlock, vars, emissions, fallbacks, ctx, targetName, parsed.timeout, absoluteTimeoutMs, traceBuilder, authState);
-                    targetLastBound = r.lastBoundVar;
-                    targetLastValue = r.lastBoundVar !== null ? vars.get(r.lastBoundVar) : r.lastValue;
-                }
-                catch (innerErr) {
-                    errors.push(buildExecutionError(innerErr, targetName, "else"));
-                }
+    // Run boundary for the deadline. `RunDeadlineExceeded` is uncatchable by any
+    // op/target machinery (each catch re-throws it); it terminates the target loop
+    // here and the run returns whatever it accumulated so far + the effect log —
+    // it is NEVER thrown to the caller. `deadlineExceeded` marks the outcome.
+    let deadlineExceeded = false;
+    const uncertainEffects = [];
+    try {
+        for (const targetName of order) {
+            const target = parsed.targets.get(targetName);
+            if (!target)
+                continue;
+            let targetLastBound = null;
+            let targetLastValue = undefined;
+            // Fresh mutation-auth state per target. `skillAutonomous` is set from
+            // the parsed header. v0.16.0 retired the `sawConfirm` path with the
+            // `ask` op removal.
+            const authState = {
+                skillAutonomous: parsed.autonomous === true,
+            };
+            try {
+                const r = await execOps(target.ops, vars, emissions, fallbacks, ctx, targetName, parsed.timeout, absoluteTimeoutMs, traceBuilder, authState);
+                targetLastBound = r.lastBoundVar;
+                targetLastValue = r.lastBoundVar !== null ? vars.get(r.lastBoundVar) : r.lastValue;
             }
-            else if (parsed.onError !== null && ctx.fallbackSkillExecutor) {
-                try {
-                    const fbResult = await ctx.fallbackSkillExecutor(parsed.onError, Object.fromEntries(vars));
-                    for (const em of fbResult.emissions)
-                        emissions.push(em);
-                    for (const fe of fbResult.errors)
-                        errors.push(fe);
+            catch (err) {
+                // Uncatchable-sweep: the run deadline is run-terminal — it must NOT be
+                // recovered by a target `else:`. Re-throw so it reaches the run boundary.
+                if (err instanceof RunDeadlineExceeded)
+                    throw err;
+                errors.push(buildExecutionError(err, targetName));
+                if (target.elseBlock !== undefined) {
+                    try {
+                        const r = await execOps(target.elseBlock, vars, emissions, fallbacks, ctx, targetName, parsed.timeout, absoluteTimeoutMs, traceBuilder, authState);
+                        targetLastBound = r.lastBoundVar;
+                        targetLastValue = r.lastBoundVar !== null ? vars.get(r.lastBoundVar) : r.lastValue;
+                    }
+                    catch (innerErr) {
+                        if (innerErr instanceof RunDeadlineExceeded)
+                            throw innerErr;
+                        errors.push(buildExecutionError(innerErr, targetName, "else"));
+                    }
+                }
+                else if (parsed.onError !== null && ctx.fallbackSkillExecutor) {
+                    try {
+                        const fbResult = await ctx.fallbackSkillExecutor(parsed.onError, Object.fromEntries(vars));
+                        for (const em of fbResult.emissions)
+                            emissions.push(em);
+                        for (const fe of fbResult.errors)
+                            errors.push(fe);
+                    }
+                    catch (fbErr) {
+                        errors.push(buildExecutionError(fbErr, parsed.onError, "skill-fallback"));
+                    }
+                    break;
                 }
-                catch (fbErr) {
-                    errors.push(buildExecutionError(fbErr, parsed.onError, "skill-fallback"));
+                else {
+                    break;
                 }
-                break;
             }
-            else {
-                break;
+            vars.set(`${targetName}.output`, targetLastValue);
+            if (targetLastBound !== null)
+                lastBoundVar = targetLastBound;
+        }
+    }
+    catch (err) {
+        // Only the run deadline reaches here (targets catch their own op errors).
+        if (err instanceof RunDeadlineExceeded) {
+            // In a composition CHILD, PROPAGATE so the whole tree aborts as one unit —
+            // the parent's execute_skill intercept re-throws it up to the ROOT, which
+            // alone catches it and returns the partial result. This is why a deep gather
+            // can't outlive the root's deadline: the shared instant fires once and
+            // unwinds the entire stack. A run entered via the composition wrapper
+            // (MCP/scheduler) has recursionDepth 1 but IS the root (`_runRoot`) — it must
+            // CONVERT here, not re-throw, else the deadline escaped into mcp-server's
+            // catch-all and dropped deadline_exceeded/uncertain_effects (finding C).
+            if ((ctx.recursionDepth ?? 0) > 0 && ctx._runRoot !== true)
+                throw err;
+            deadlineExceeded = true;
+            errors.push(buildExecutionError(err, err.target ?? "run"));
+            // An external dispatch cut mid-flight has an unknown outcome — record it
+            // (only provably-non-effecting local ops are excluded, cutOp.uncertainWhenCut
+            // false for them). Never auto-retried.
+            if (err.cutOp?.uncertainWhenCut === true) {
+                uncertainEffects.push({
+                    target: err.target,
+                    opKind: err.cutOp.opKind,
+                    op: err.cutOp.label,
+                    reason: "issued, outcome uncertain",
+                    retry: false,
+                });
             }
         }
-        vars.set(`${targetName}.output`, targetLastValue);
-        if (targetLastBound !== null)
-            lastBoundVar = targetLastBound;
+        else {
+            throw err;
+        }
     }
     // Outputs map per `# Output:` declarations. Per-kind value semantics:
     //   - Agent-bound surfaces (`agent:`, `template:`): default to joined
@@ -285,7 +367,9 @@ export async function execute(parsed, initialVars, order, ctx) {
     // capability as the op-level choke. In secured mode an unapproved body cannot
     // deliver to an agent/template, even though its emit-to-transcript ran.
     const deliveryAuthorized = !(isSecuredMode() && ctx.effectsAuthorized !== true);
-    if (ctx.mechanical !== true && deliveryAuthorized) {
+    // Past the deadline is past the deadline: a terminated run does NOT then
+    // dispatch its `# Output: agent:` delivery (that's an effect past the bound).
+    if (ctx.mechanical !== true && deliveryAuthorized && !deadlineExceeded) {
         for (const decl of outputDecls) {
             if (decl.target === undefined)
                 continue;
@@ -347,7 +431,7 @@ export async function execute(parsed, initialVars, order, ctx) {
     // up as op errors; the trace store is an observability surface, not a
     // dispatch dependency).
     if (traceBuilder !== null && ctx.traceStore !== undefined) {
-        const record = traceBuilder.finalize(emissions, outputs, errors);
+        const record = traceBuilder.finalize(emissions, outputs, errors, { deadlineExceeded, uncertainEffects });
         try {
             await ctx.traceStore.write(record);
         }
@@ -375,6 +459,8 @@ export async function execute(parsed, initialVars, order, ctx) {
         targetOrder: order,
         agentDeliveryReceipts,
         agentWakeReceipts,
+        ...(deadlineExceeded ? { deadlineExceeded: true } : {}),
+        ...(uncertainEffects.length > 0 ? { uncertainEffects } : {}),
     };
 }
 async function execOps(ops, vars, emissions, fallbacks, ctx, targetName, skillTimeoutSec, absoluteTimeoutMs, traceBuilder, authState) {
@@ -627,7 +713,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             // Closes Perry's `adc87d52` cold-author-safety finding.
             if (op.argv !== undefined) {
                 const substArgv = op.argv.map((el) => substituteRuntime(el, vars));
-                const shellTimeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars);
+                const shellTimeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars, ctx.deadlineMs, targetName, ctx.deadlineBudgetMs, ctx.deadlineSource);
                 if (ctx.mechanical === true) {
                     const preview = substArgv.join(" ");
                     emissions.push(`Would run shell argv: ${preview} (mechanical: true preview).`);
@@ -658,9 +744,13 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     }
                     const finalArgv = await Promise.all(realArgv.map((el, i) => spliceSecretsAtSink(el, maskedArgv[i].names)));
                     const [bin, ...args] = finalArgv;
-                    stdoutArgv = await execShellCommand(bin, args, shellTimeoutMs);
+                    stdoutArgv = await execShellCommand(bin, args, shellTimeoutMs, ctx.deadlineMs, ctx.deadlineBudgetMs, ctx.deadlineSource);
                 }
                 catch (err) {
+                    if (err instanceof RunDeadlineExceeded) {
+                        err.cutOp ??= { opKind: "shell", label: "shell", uncertainWhenCut: true };
+                        throw err;
+                    }
                     if (shellFallback !== undefined) {
                         return recordShellFallback(shellFallback, redactSecrets(`shell argv failed: ${messageOf(err)}`));
                     }
@@ -682,7 +772,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             const body = op.policy === "unsafe"
                 ? substituteRuntimeUnsafe(op.body, vars)
                 : substituteRuntime(op.body, vars);
-            const shellTimeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars);
+            const shellTimeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars, ctx.deadlineMs, targetName, ctx.deadlineBudgetMs, ctx.deadlineSource);
             if (ctx.mechanical === true) {
                 const label = op.policy === "unsafe" ? "Would run unsafe shell" : "Would run shell";
                 emissions.push(`${label}: ${body} (mechanical: true preview).`);
@@ -726,7 +816,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     // argv/`ps` leak window; vault-era sink-aware injection closes it).
                     // Unsafe shell is operator-gated, so a secret here is deliberate.
                     const finalBody = await spliceSecretsAtSink(realBody, names);
-                    stdout = await execShellCommand("bash", ["-c", finalBody], shellTimeoutMs);
+                    stdout = await execShellCommand("bash", ["-c", finalBody], shellTimeoutMs, ctx.deadlineMs, ctx.deadlineBudgetMs, ctx.deadlineSource);
                 }
                 else {
                     const tokens = tokenizeShellArgs(realBody);
@@ -745,10 +835,14 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     // spaces/quotes stays one argv element and never reaches a shell.
                     const finalTokens = await Promise.all(tokens.map((t) => spliceSecretsAtSink(t, names)));
                     const [bin, ...args] = finalTokens;
-                    stdout = await execShellCommand(bin, args, shellTimeoutMs);
+                    stdout = await execShellCommand(bin, args, shellTimeoutMs, ctx.deadlineMs, ctx.deadlineBudgetMs, ctx.deadlineSource);
                 }
             }
             catch (err) {
+                if (err instanceof RunDeadlineExceeded) {
+                    err.cutOp ??= { opKind: "shell", label: "shell", uncertainWhenCut: true };
+                    throw err;
+                }
                 if (shellFallback !== undefined) {
                     return recordShellFallback(shellFallback, redactSecrets(`shell failed: ${messageOf(err)}`));
                 }
@@ -1041,6 +1135,11 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     return { lastBoundVar: op.outputVar ?? flatKey, lastValue: childResult };
                 }
                 catch (err) {
+                    // Uncatchable-sweep: a child that hit the (shared) run deadline
+                    // propagates `RunDeadlineExceeded` up — the whole tree aborts; this
+                    // intercept must NOT convert it to the parent's `(fallback:)`.
+                    if (err instanceof RunDeadlineExceeded)
+                        throw err;
                     // v0.27.0 — `(fallback:)` now contains a RAISED THROW from the
                     // execute_skill intercept (a child whose execute() escapes a throw —
                     // e.g. its output template references an unset var), not just a
@@ -1084,6 +1183,11 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     parsed = JSON.parse(input);
                 }
                 catch (err) {
+                    // Uncatchable-sweep invariant (defensive — json_parse is local/instant
+                    // so it can't originate a deadline, but every op-catch re-throws fatal
+                    // for the structural guard).
+                    if (err instanceof RunDeadlineExceeded)
+                        throw err;
                     // v0.27.0 — `(fallback:)` contains a json_parse off-shape throw too
                     // (uniform trailer semantics; see the execute_skill intercept above).
                     // The parse-error message is kept in `fallbacks[].reason`.
@@ -1148,7 +1252,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             }
             let rawResult;
             let dispatched = false;
-            const timeoutMs = resolveOpTimeoutMs(perOpTimeoutSec, skillTimeoutSec, absoluteTimeoutMs, vars);
+            const timeoutMs = resolveOpTimeoutMs(perOpTimeoutSec, skillTimeoutSec, absoluteTimeoutMs, vars, ctx.deadlineMs, targetName, ctx.deadlineBudgetMs, ctx.deadlineSource);
             // Op-level fallback (per language reference §9, extended to `$` for
             // cold-agent corpus consistency). On dispatch throw, bind the
             // fallback value to the output var; on missing connector with
@@ -1172,11 +1276,17 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                 }
                 if (ctx.registry.hasMcpConnector(connectorName)) {
                     const connector = ctx.registry.getMcpConnector(connectorName);
-                    rawResult = await dispatchWithTimeout(() => connector.call(toolName, dispatchArgs, ctx.agentId !== undefined ? { agentId: ctx.agentId } : undefined), timeoutMs, "$");
+                    // Pass the connector's bounded cleanup hook so the deadline can invoke
+                    // it on an in-flight cut (outlives-call connectors only; call-bounded
+                    // ones have no onAbort → reserve 0, zero tax).
+                    const onAbort = typeof connector.onAbort === "function"
+                        ? (budgetMs) => connector.onAbort(budgetMs)
+                        : undefined;
+                    rawResult = await dispatchWithTimeout((signal) => connector.call(toolName, dispatchArgs, { ...(ctx.agentId !== undefined ? { agentId: ctx.agentId } : {}), signal }), timeoutMs, "$", ctx.deadlineMs, onAbort, ctx.deadlineBudgetMs, ctx.deadlineSource);
                     dispatched = true;
                 }
                 else if (op.mcpConnector === undefined && ctx.toolDispatch) {
-                    rawResult = await dispatchWithTimeout(() => ctx.toolDispatch(toolName, dispatchArgs), timeoutMs, "$");
+                    rawResult = await dispatchWithTimeout(() => ctx.toolDispatch(toolName, dispatchArgs), timeoutMs, "$", ctx.deadlineMs, undefined, ctx.deadlineBudgetMs, ctx.deadlineSource);
                     dispatched = true;
                 }
                 else {
@@ -1193,6 +1303,13 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                 }
             }
             catch (err) {
+                // Uncatchable-sweep: a mid-flight run-deadline expiry must NOT be
+                // recovered by this op's `(fallback:)` — tag the cut op (for the
+                // uncertain-effect log; deepest op wins via `??=`) and re-throw.
+                if (err instanceof RunDeadlineExceeded) {
+                    err.cutOp ??= { opKind: "$", label: `${connectorLabel}${toolName}`, uncertainWhenCut: dispatchUncertainWhenCut(toolName) };
+                    throw err;
+                }
                 if (dollarFallback !== undefined) {
                     vars.set(flatKey, dollarFallback);
                     if (op.outputVar !== undefined)
@@ -1324,6 +1441,17 @@ function buildExecutionError(err, target, opKindOverride) {
     };
 }
 const DEFAULT_RUNTIME_ABSOLUTE_TIMEOUT_MS = 300_000;
+/**
+ * Cleanup slice reserved from the run budget for an `"outlives-call"` connector's
+ * `onAbort()` when the deadline cuts an in-flight call (Perry spec de11dcc5).
+ * Sized to realistic bounded cleanup (`stop_all_movements` / socket-close /
+ * SIGKILL are sub-second). Reserved PER-OP and only for outlives-call ops
+ * (`onAbort` present), so the call-bounded majority pays zero tax; floored
+ * against remaining-at-dispatch (`min(CLEANUP_CAP, remaining)`) so `effective`
+ * never goes negative and a late outlives-call op fails fast rather than starting
+ * an effect it can't clean in time. Keeps total wall-clock ≤ the deadline.
+ */
+const CLEANUP_CAP_MS = 1_000;
 /**
  * Per-op timeout resolution chain (ERD §6 decision 7) — top wins:
  *   1. Per-op override (`~ ... timeoutSeconds=30 ...`)
@@ -1335,33 +1463,121 @@ const DEFAULT_RUNTIME_ABSOLUTE_TIMEOUT_MS = 300_000;
  * Both per-op and skill-level values are in seconds (per author convention)
  * and converted to milliseconds here.
  */
-function resolveOpTimeoutMs(perOpTimeoutSec, skillTimeoutSec, absoluteTimeoutMs, vars) {
+/**
+ * Bare `$` builtins the runtime can PROVABLY rule out an external effect for — a
+ * read, a pure parse, composition (whose children record their own cut effects),
+ * and a model completion (`$ llm` is prompt→text; a cut one is wasted compute,
+ * not a landed effect). A cut of any of these leaves no uncertain external state,
+ * so recording it would be a guaranteed false positive that pollutes the signal.
+ * (Per Perry's ruling — the boundary is "provably no external effect," which is
+ * why `$ llm` is excluded but a read-NAMED connector tool like `get_status` is
+ * NOT: a connector's effect can't be ruled out from its name; that downgrade is
+ * the explicit per-tool `effect_class` annotation, Phase 2.)
+ */
+const DISPATCH_NON_EFFECTING = new Set(["data_read", "json_parse", "execute_skill", "llm"]);
+/**
+ * Should a `$` dispatch cut mid-flight be logged as "issued, outcome uncertain"?
+ * SAFE DEFAULT: yes — every `$ connector.tool` and `data_write` may have effected
+ * external state we can't confirm once aborted. Only ops the runtime can PROVABLY
+ * rule out an external effect for (the set above) are excluded. Deliberately NOT
+ * `classifyMutation` (a mutating-NAME heuristic): it misses `send_message` and
+ * every un-verbed connector tool — exactly the production mutations — so keying
+ * the uncertain-log on it silently dropped the highest-risk ops (adopter finding
+ * D). Under-recording a cut mutation is dangerous; over-recording is just noise.
+ */
+export function dispatchUncertainWhenCut(toolName) {
+    return !DISPATCH_NON_EFFECTING.has(toolName);
+}
+function resolveOpTimeoutMs(perOpTimeoutSec, skillTimeoutSec, absoluteTimeoutMs, vars, deadlineMs, targetName, deadlineBudgetMs, deadlineSource) {
+    let base;
     if (perOpTimeoutSec !== undefined) {
-        return resolveIntParam(perOpTimeoutSec, vars, "timeoutSeconds") * 1000;
+        base = resolveIntParam(perOpTimeoutSec, vars, "timeoutSeconds") * 1000;
+    }
+    else if (skillTimeoutSec !== null) {
+        base = resolveIntParam(skillTimeoutSec, vars, "# Timeout:") * 1000;
     }
-    if (skillTimeoutSec !== null) {
-        return resolveIntParam(skillTimeoutSec, vars, "# Timeout:") * 1000;
+    else {
+        base = absoluteTimeoutMs;
     }
-    return absoluteTimeoutMs;
+    // Run-total deadline (# Deadline:). This is the PRE-DISPATCH fail-fast + clamp,
+    // and it gates EVERY dispatch path (called for `$` and `shell` alike, in the
+    // main body AND inside `(fallback:)`/`else:` bodies). If the deadline has
+    // already passed, throw the uncatchable `RunDeadlineExceeded` before the op
+    // runs — this is the backstop that makes a *missed* catch-site swallow bounded
+    // to "≤1 more op then re-thrown here" rather than unbounded. Otherwise clamp
+    // the op's own timeout down to what's left of the run.
+    if (deadlineMs !== undefined) {
+        const remaining = deadlineMs - Date.now();
+        if (remaining <= 0)
+            throw new RunDeadlineExceeded(deadlineMs, targetName, deadlineBudgetMs, deadlineSource);
+        return Math.min(base, remaining);
+    }
+    return base;
 }
 /**
- * Race the op against a timer. On timeout, throws `OpTimeoutError`-shaped
- * op-error so the existing else: / # OnError: machinery catches it.
+ * Race the op against a timer. On a per-op timeout, throws `OpTimeoutError`
+ * (catchable by `(fallback:)`/`else:`). On the run deadline, throws the
+ * uncatchable `RunDeadlineExceeded`.
  *
- * v1 caveat: timeout returns control to the executor promptly, but the
- * underlying request may still complete in the background — its result is
- * discarded. v2 should thread AbortSignal through connector contracts so
- * implementations can cancel cleanly.
+ * Cancellation (Perry spec de11dcc5): the timer IS the cut. For an
+ * `"outlives-call"` connector (an `onAbort` was passed), the op is cut a
+ * reserved slice EARLY — `reserve = min(CLEANUP_CAP, remaining)` — and
+ * `onAbort(reserve)` runs (bounded, can't hang) before the deadline rejection,
+ * so its cleanup fits INSIDE the run budget (total wall-clock ≤ deadline). A
+ * late-dispatched outlives-call op gets `effective ≈ 0` → it fails fast rather
+ * than starting an effect it can't clean in time. Call-bounded ops pass no
+ * `onAbort`, reserve 0, and pay zero tax.
  */
-async function dispatchWithTimeout(fn, timeoutMs, opKind) {
+async function dispatchWithTimeout(fn, timeoutMs, opKind, deadlineMs, onAbort, deadlineBudgetMs, deadlineSource) {
+    // Cancellation signal: aborted when the timer cuts this op (deadline OR per-op
+    // timeout). A call-bounded connector that forwards it to its fetch/RPC truly
+    // stops the work instead of race-and-abandon; one that ignores it degrades to
+    // today's behavior.
+    const controller = new AbortController();
+    // Reserve a cleanup slice ONLY for outlives-call ops (onAbort present) — the
+    // majority pays nothing. Floored against remaining-at-dispatch so it never
+    // goes negative (Perry refinement). `cutInstant` is when THIS op must be cut
+    // to leave room for its own cleanup; call-bounded ops cut exactly at the
+    // deadline.
+    const remainingAtDispatch = deadlineMs !== undefined ? Math.max(0, deadlineMs - Date.now()) : 0;
+    const reserveMs = onAbort !== undefined && deadlineMs !== undefined
+        ? Math.min(CLEANUP_CAP_MS, remainingAtDispatch)
+        : 0;
+    const cutInstant = deadlineMs !== undefined ? deadlineMs - reserveMs : undefined;
+    const effectiveMs = cutInstant !== undefined
+        ? Math.min(timeoutMs, Math.max(0, cutInstant - Date.now()))
+        : timeoutMs;
     let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-            reject(new OpTimeoutError(timeoutMs, opKind));
-        }, timeoutMs);
+        timer = setTimeout(async () => {
+            // Signal the connector to stop its in-flight work first (call-bounded
+            // true-cancel), then decide the error class + run any outlives-call cleanup.
+            controller.abort();
+            // If we're at/past this op's cut instant, the timer IS the run deadline
+            // (the clamp made `effectiveMs` land there); otherwise it's a per-op
+            // timeout (`OpTimeoutError`, catchable).
+            if (cutInstant !== undefined && Date.now() >= cutInstant) {
+                if (onAbort !== undefined && reserveMs > 0) {
+                    // Bounded cleanup: give onAbort up to `reserveMs`, never let it hang or
+                    // throw past the budget. (A `< CLEANUP_CAP` window for a late op is the
+                    // documented "cleanup incomplete" case.)
+                    await Promise.race([
+                        (async () => { try {
+                            await onAbort(reserveMs);
+                        }
+                        catch { /* connector cleanup best-effort */ } })(),
+                        new Promise((res) => setTimeout(res, reserveMs)),
+                    ]);
+                }
+                reject(new RunDeadlineExceeded(deadlineMs, undefined, deadlineBudgetMs, deadlineSource));
+            }
+            else {
+                reject(new OpTimeoutError(timeoutMs, opKind));
+            }
+        }, effectiveMs);
     });
     try {
-        return await Promise.race([fn(), timeoutPromise]);
+        return await Promise.race([fn(controller.signal), timeoutPromise]);
     }
     finally {
         if (timer !== undefined)
@@ -1442,7 +1658,7 @@ function scrubbedShellEnv() {
  * spawn both the structured `command=`/`argv=` and the `unsafe=true` (`bash
  * -c`) paths funnel through, so the scrub covers every shell egress.
  */
-async function execShellCommand(bin, args, timeoutMs) {
+async function execShellCommand(bin, args, timeoutMs, deadlineMs, deadlineBudgetMs, deadlineSource) {
     return new Promise((resolve, reject) => {
         const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"], env: scrubbedShellEnv() });
         let stdout = "";
@@ -1474,7 +1690,14 @@ async function execShellCommand(bin, args, timeoutMs) {
         child.on("close", (code) => {
             clearTimeout(timer);
             if (killed) {
-                reject(new OpTimeoutError(timeoutMs, "shell"));
+                // The SIGKILL above IS real cancellation (the process group is dead —
+                // shell is the day-one `honors` cancellation exemplar). When the kill
+                // was the run deadline (timer clamped to remaining, now at/past it),
+                // reject the uncatchable RunDeadlineExceeded so the shell `(fallback:)`
+                // can't swallow it; otherwise it's a per-op timeout.
+                reject(deadlineMs !== undefined && Date.now() >= deadlineMs
+                    ? new RunDeadlineExceeded(deadlineMs, undefined, deadlineBudgetMs, deadlineSource)
+                    : new OpTimeoutError(timeoutMs, "shell"));
                 return;
             }
             if (code !== 0) {