@sema-agent/core 5.64.0 → 6.0.0

package/dist/core/stub-env.d.ts

@@ -8,6 +8,10 @@ import { type ExecResult, type ExecutionEnv, ExecutionError, FileError, type Fil
  */
 export declare class StubExecutionEnv implements ExecutionEnv {
     cwd: string;
+    /** design/380 O9a — declared on the class so the prepare fold can read the optional interface
+     *  member off a `ExecutionEnv | StubExecutionEnv` union; the no-I/O stub produces no target
+     *  content, so it never declares (always `undefined` — the trusted-side default). */
+    readonly externalContentTarget?: boolean;
     constructor(cwd?: string);
     private fsErr;
     absolutePath(path: string): Promise<Result<string, FileError>>;

package/dist/core/stub-env.js

@@ -1,6 +1,7 @@
 import { ExecutionError, FileError, err, } from "../internal/harness.js";
 export class StubExecutionEnv {
     cwd;
+    externalContentTarget;
     constructor(cwd = "/") {
         this.cwd = cwd;
     }

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

@@ -166,6 +166,32 @@ function workflowAgentRow(a, ordinal) {
         ...(a.replayed === true ? { replayed: true } : {}),
     };
 }
+function budgetOvershootNote(overshoot) {
+    if (overshoot === undefined)
+        return "";
+    const unsettled = overshoot.unsettledTokens ?? 0;
+    const total = overshoot.spentTokens + unsettled;
+    return (` token budget OVERSHOT: this run spent ${total.toLocaleString()} total tokens against a ${overshoot.budgetTokens.toLocaleString()} ceiling ` +
+        `(over by ${(total - overshoot.budgetTokens).toLocaleString()}` +
+        `${unsettled > 0 ? `, of which ${unsettled.toLocaleString()} was observed on agents still in flight at the terminal and never settled` : ""}).`);
+}
+function timeoutInterruptionNote(interruption) {
+    if (interruption === undefined)
+        return "";
+    return (` INTERRUPTED by the workflow's total timeout (${interruption.timeoutMs.toLocaleString()}ms): when the deadline fired ` +
+        `${interruption.agentsCompleted} agent(s) had completed, ${interruption.agentsFailed} had failed, and ` +
+        `${interruption.agentsInFlight} were still in flight — the failed run status is the deadline's, not a verdict on those agents.` +
+        (interruption.approvalWaitedMs !== undefined
+            ? ` The longest single agent wait on a human approval reported for this run was ${interruption.approvalWaitedMs.toLocaleString()}ms` +
+                (interruption.approvalWaitedMs > interruption.timeoutMs
+                    ? ` — MORE than the ${interruption.timeoutMs.toLocaleString()}ms window itself, so the deployment's approval clock is` +
+                        ` counting time this run did not (an earlier leg's wait carried forward, or a mis-scaled figure). Read it as` +
+                        ` "waiting dominated", not as a slice of this window.`
+                    : ` — that much of the ${interruption.timeoutMs.toLocaleString()}ms window was one agent BLOCKED on a person` +
+                        ` rather than working (the longest single wait, not a total).`) +
+                ` Raising the timeout only helps if that approval gets answered.`
+            : ""));
+}
 export function formatWorkflowRun(run) {
     const summary = summarizeWorkflowRun(run);
     const done = run.agents.filter((a) => a.status === "completed" || a.status === "failed").length;
@@ -223,7 +249,7 @@ export function formatWorkflowRun(run) {
                         : {}),
                 }
                 : {}),
-            note: run.status === "running"
+            note: (run.status === "running"
                 ? "still running — poll again shortly."
                 : run.status === "completed"
                     ? run.result !== undefined
@@ -231,7 +257,9 @@ export function formatWorkflowRun(run) {
                         : "completed — this run predates result persistence; its result was delivered on the completion notification."
                     : finishedAgents.length > 0
                         ? `failed — see error. ${finishedAgents.length} agent(s) had already completed before the run ended; their outputs are inlined under \`partial_results\`.`
-                        : "failed — see error.",
+                        : "failed — see error.") +
+                timeoutInterruptionNote(summary.timeoutInterruption) +
+                budgetOvershootNote(summary.budgetOvershoot),
         }),
         details: {
             task_id: run.id,

package/dist/core/tool-errors.js

@@ -72,6 +72,7 @@ const EXACT_CODE_CLASS = new Map([
     ["limits.max_walltime_exceeded", "limit"],
     ["memory.admission_required", "config"],
     ["memory.admission_denied", "config"],
+    ["memory.capture_optout_denied", "config"],
     ["env.lifetime_expired", "config"],
 ]);
 const DOTTED_PREFIX_CLASS = [

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

@@ -216,6 +216,15 @@ export type PermissionResult = {
      *  understands (see {@link import("./checkpoint-store.js").ProbeCause}). Engine-stamped and
      *  validated at the irreversibility tighten; same display-only posture as the prose sibling. */
     probeCause?: import("./checkpoint-store.js").ProbeCause;
+    /** #502 (additive): the reversibility probe declared this demotion STRUCTURAL — see
+     *  {@link import("./types.js").ReversibilityVerdict.mandated}. Unlike its two `probe*` neighbours
+     *  this is NOT display metadata: it joins the #144 mandate family, so the persisted-rule lane
+     *  discloses a matching allow rule as shadowed instead of clearing the ask, and the card's
+     *  "stop asking me this" offer is withheld. ENGINE-STAMPED at the irreversibility tighten, which
+     *  constructs this decision wholesale — a policy that self-declares it is overwritten there, and
+     *  in the one direction the stamp cannot reach (a caller composing its own ask) the claim is
+     *  tightening-only: it can make an ask outlive a rule, never turn one into an allow. */
+    probeMandated?: true;
     /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
      *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
      *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
@@ -457,6 +466,28 @@ export declare function checkToolPolicyProjection(projection: Pick<ToolPolicyPro
 export type ConstraintChainEntryMeta = {
     /** True iff the layer carried a frozen auto-mode classifier (`autoMode`). */
     autoModeArmed?: true;
+    /**
+     * #503 — the layer's serializable auto-mode ARMING RECIPE: the criteria half of the frozen classifier
+     * (assembly inputs + knobs + the deployment's settings epoch), recorded so a CROSS-PROCESS redemption
+     * can rebuild an equivalent decider over its own fresh model leg
+     * ({@link import("./auto-mode-arming.js").rebuildAutoModeDecider}) instead of answering `unavailable`
+     * forever and parking the same approval for a human on every redemption.
+     *
+     * OPT-IN and ADDITIVE: present only when the arming deployment asked for it (`RunnerDeps.autoMode.
+     * persistArming`), so an unchanged deployment mints byte-identical entries and every pre-#503 row
+     * (and every row minted without the opt-in) reads as absence = the pre-#503 behavior. Absence is also
+     * what an OPEN BREAKER produces — see {@link constraintChainEntryOfLayer}.
+     *
+     * The digest binds it: a re-supply that DROPS the recorded recipe, or hands back a DIFFERENT one, is
+     * rejected pre-CAS — so the re-supply contract is exactly "hand back what the row carries" (a redeeming
+     * host reads the recipe off this field and passes it straight through). The verify side takes the
+     * PRESENCE of this field from the row, never from the re-supplied layer's live classifier health, so a
+     * row that recorded no recipe does not refuse a re-supply that offers one — the reasoning, and why that
+     * direction cannot be recovered, is recorded on {@link constraintChainEntryOfSuppliedLayer}.
+     * `checkToolPolicyProjection` never reads it: like the other metadata here it exists to be digested,
+     * not to execute.
+     */
+    autoModeArming?: import("./auto-mode-arming.js").AutoModeArmingRecipe;
     durableMandate?: true;
     contentMandate?: true;
 };
@@ -469,6 +500,105 @@ export type ConstraintChainEntry = ConstraintChainEntryMeta & ({
 /** Project one policy into its chain entry (opaque placeholder when it exports no projection),
  *  carrying the layer's decision-chain metadata posture for the digest (round 12). */
 export declare function constraintChainEntryOf(policy: ToolPolicy, meta?: ConstraintChainEntryMeta): ConstraintChainEntry;
+/**
+ * One inherited-chain LAYER as both chain-entry mint sites see it — structurally an
+ * `InheritedGate.parentConstraints[]` element, typed here structurally so this module (which owns the
+ * digest) does not depend on the runner's shapes.
+ */
+export interface ConstraintChainLayerView {
+    policy: ToolPolicy;
+    autoMode?: {
+        decider: {
+            breakerOpen: () => boolean;
+            consecutiveFailures?: () => number;
+        };
+        arming?: unknown;
+    };
+    durableMandate?: boolean;
+    contentMandate?: boolean;
+}
+/**
+ * The WRITE-side mint: the chain entry a durable PARK records for a live inherited layer.
+ *
+ * #503 safety bound ① lives HERE, at the persistence point rather than at arming time: the recipe is
+ * carried only while the layer's breaker is UNTRIPPED AND UNTOUCHED. An open breaker is the ancestor
+ * session's one-way "fell back to non-auto" latch — its arming has been withdrawn, and handing that
+ * arming to a redemption would let the redeemed leg run auto-classified where the ancestor no longer does
+ * (a redemption WIDER than the ancestor it inherits). The latch is read at the moment the row is written,
+ * so an ancestor whose classifier died mid-run parks WITHOUT a recipe even though it was armed when the
+ * chain was assembled.
+ *
+ * `breakerOpen()` alone is NOT the whole latch, and a closed-only test left a real widening: a rebuilt
+ * decider starts a FRESH failure streak, so an ancestor sitting at 2 failures out of 3 — one bad
+ * classification from dropping the whole session to non-auto — would hand a redemption the full budget
+ * again, and the redeemed leg stays auto-classified through failures the ancestor would not have
+ * survived. So the streak must read ZERO as well. A decider that does not expose it at all is UNKNOWN
+ * state, and unknown takes the same arm as tripped: nothing is recorded (which is why a host that hand
+ * rolls a decider cannot use the persisted-arming path — it must mint through `createAutoModeDecider`,
+ * on both the arming and the redeeming side).
+ *
+ * Every read here is guarded, and every failure to read is treated as "withdrawn" — the opposite default
+ * from the gate's demote-to-ask breaker reader, and for the same reason both are right: there, an
+ * unreadable latch must not suppress a tighten; here, it must not license a carry-forward.
+ *
+ * ⚠️ WRITE SIDE ONLY. This gate reads MUTABLE state (a one-way latch, plus a streak that both grows and
+ * resets to zero on any healthy classification). The resume re-supply must NOT re-run it — it samples a
+ * different instant, and the two instants disagree for perfectly ordinary reasons: an ancestor keeps
+ * running while its delegated child sits parked awaiting a human. See
+ * {@link constraintChainEntryOfSuppliedLayer} for the verify side and the full account.
+ *
+ * ⚖️ WHAT THIS BOUND DOES NOT DO (recorded, precise shape). A withdrawn arming leaves the entry at
+ * `autoModeArmed: true` with no recipe — digest-identical to an armed layer whose deployment never opted
+ * in. So the digest does not, and cannot, stop a re-supplier from handing back a FRESH healthy decider of
+ * its own: that is the pre-existing re-supply trust posture (see `resumeStream`'s contract — a caller
+ * able to invoke it already holds full Runner authority, and the chain checks catch shape MISTAKES, not
+ * a hostile trusted caller), and it is unchanged here. What this bound governs is what CORE hands
+ * forward: a withdrawn ancestor's CRITERIA never travel, so a redemption cannot reconstruct the
+ * ancestor's classifier from the row. For a fleet running `persistArming` everywhere, the pair
+ * (`autoModeArmed` present, `autoModeArming` absent) is itself the readable signal that the ancestor's
+ * arming was withdrawn or unrecordable, and such a host should re-supply a refusing decider rather than a
+ * fresh one. Making the WITHDRAWAL itself digest-bound is a coherent stronger design — it needs a new
+ * marker plus a new re-supply obligation to reproduce it (a withdrawn row carries no recipe, so the
+ * marker cannot be derived from one), which is a scope decision for this seam's owner, not a silent
+ * mechanism change.
+ */
+export declare function constraintChainEntryOfLayer(layer: ConstraintChainLayerView): ConstraintChainEntry;
+/**
+ * The VERIFY-side mint: the entry a resume's RE-SUPPLIED layer must reproduce for the row it is
+ * redeeming. Same body as the park mint, with the arming carry taken from the ROW rather than from the
+ * layer's live classifier health — so the digest equality is over bytes the row itself recorded, and
+ * over nothing that can move while the row sits parked.
+ *
+ * WHY THE CARRY CANNOT BE RE-DERIVED HERE. Safety bound ① (see {@link constraintChainEntryOfLayer}) is a
+ * statement about the ancestor at the instant the row was WRITTEN. Re-running it against the same live
+ * layer at redemption time samples a different instant, and both directions of the disagreement strand an
+ * approval a human already granted:
+ *   - the ancestor was healthy at the park (the row carries the recipe) and its breaker opened while the
+ *     child sat parked ⇒ the re-supply mints WITHOUT the recipe, the digests differ, and because the
+ *     latch is ONE-WAY the row is refused `resume.parent_constraint_mismatch` forever;
+ *   - the ancestor was one failure into its streak at the park (the row carries no recipe) and the streak
+ *     cleared on its next healthy classification ⇒ the re-supply mints WITH a recipe the row never
+ *     carried, same refusal.
+ * Neither needs a host mistake: the ancestor and its siblings keep running while the child is parked, and
+ * the same-process `resume()` verb re-supplies the very same live layer objects out of the Runner's own
+ * parked-constraint registry. Nothing about the row changed; only a classifier's health did.
+ *
+ * WHAT THIS COSTS, NAMED. A row that recorded NO recipe no longer refuses a re-supply that hands one
+ * back. That is not a tunable — the re-supply side literally cannot tell "the row withdrew a recipe this
+ * same live layer still declares" (the second bullet above, a legitimate redemption) from "a re-supplier
+ * is putting a recipe onto a row that withdrew one": both are the identical pair of inputs. It is also
+ * thinner than it looks. The recipe is not an enforcement object — the DECIDER classifies, and the
+ * re-supply trust posture already permits handing back a fresh healthy one, which is the capability that
+ * would matter. What the row's absence still means is unchanged and is the property bound ① was written
+ * for: a withdrawn ancestor's criteria never travel ON THE ROW, so no redemption can reconstruct that
+ * ancestor's classifier from the checkpoint.
+ *
+ * WHAT THE DIGEST STILL BINDS. A row that DID record a recipe must have that recipe handed back: the
+ * carry is on, so a re-supply that drops the arming, or hands back a different one, mints a different
+ * entry and is refused pre-CAS exactly as before. That is the whole of the documented re-supply contract
+ * — "hand back what the row carries".
+ */
+export declare function constraintChainEntryOfSuppliedLayer(layer: ConstraintChainLayerView, recorded: ConstraintChainEntry | undefined): ConstraintChainEntry;
 /**
  * Content digest over an ordered constraint chain (F-012 L1) — the durable half's anti-tamper anchor.
  * Binds the chain TOPOLOGY (order, layer boundaries, opaque placeholders) and each projection's full
@@ -900,7 +1030,10 @@ export interface AskRequest {
      * substitution yields NO offer, which is the honest answer rather than an option that would be
      * refused on redemption) AND the ask is one a persisted rule could actually clear — a mandated ask
      * (operator shellGate:"always", the tool's own egress/irreversibility marks, a
-     * `requiresRealApproval` demand) and an ask carrying {@link persistedRuleShadowed} offer none.
+     * `requiresRealApproval` demand, or — #502, the one PER-CALL member of that family — a demotion the
+     * call's own reversibility probe declared structural, which for the built-in shell probe means a read
+     * outside the session's allowed directories) and an ask carrying {@link persistedRuleShadowed} offer
+     * none.
      *
      * CONTRACT — see {@link import("./permission-rule-model.js").RuleOffer} for the closed union, the
      * per-element parse/degrade rules and the original-index-keying obligation. Array order is display
@@ -919,6 +1052,44 @@ export interface AskRequest {
      * from it across a coverage change — harmlessly, since the record is what gets confirmed.
      */
     readonly ruleOffers?: readonly import("./permission-rule-model.js").RuleOffer[];
+    /**
+     * #490 修② — WHY {@link ruleOffers} is absent, when the rule-offer lane is in play and has nothing
+     * to give. A CLOSED set, mutually exclusive with {@link ruleOffers} (never both, never neither once
+     * the lane is in play):
+     *  · `"mandated"` — no persisted rule could ever clear this ask: an org/governance
+     *    `requiresRealApproval` demand, an operator `shellGate:"always"` or the tool's own
+     *    egress/irreversibility marks, a hook-raised ask, an ask whose authority is an ANCESTOR's
+     *    approver rather than this task's rule lane, or (#502) a demotion this CALL's reversibility
+     *    probe declared structural — for the built-in shell probe, a read outside the directories this
+     *    session declared. A surface must NOT point at rule-writing here — "allow rules silence the
+     *    classifier's questions, never a mandated one", so a rule minted in answer to this line would
+     *    never take effect where it was minted. It must not point at a directory GRANT either: the
+     *    out-of-root arm has no clearing configuration in this version, and confirming the call is the
+     *    whole of what a person can do about it;
+     *  · `"shadowed"` — a rule the person already wrote is speaking and does not clear this ask (a
+     *    matching allow rule that the lane refuses to honor here, or their own explicit `ask` rule);
+     *  · `"lane_cannot_speak"` — the lane is armed and this ask IS clearable, but the offer lane
+     *    produced no rule for this command. Usually because the grammar has no text for it (a
+     *    substitution, a subshell, a backgrounded process, or a simple command carrying a redirection —
+     *    a compound is judged per segment, so this arm means EVERY segment was unspeakable, since one
+     *    dirty segment among clean ones yields a batch instead). It also covers the narrower case where a
+     *    text EXISTS but the card's own array-order contract declines to present it alone (a simple
+     *    command whose exact form the validator refuses offers nothing rather than promoting a lone
+     *    prefix to index 0 — see `suggestRulesForCommand`). The seat says "this card has no rule to
+     *    offer you", which is true of both; it does not claim the grammar is empty, and a surface must
+     *    not word it as though no rule could ever be written for the command.
+     *
+     * ABSENT is not a claim, exactly as {@link previewWithheld}'s absence is not: it also covers the
+     * ordinary "there are offers" case and the three STRUCTURAL doors that answer with silence on
+     * purpose (no rule lane wired, a tool the lane does not speak for, a task that cannot hold a rule at
+     * all) — a reason line on every ask of a deployment that never had the feature would be noise about
+     * a lane that does not exist. Read presence, never absence.
+     *
+     * ADVISORY disclosure metadata, never adjudication input: it changes nothing about what is allowed,
+     * and a surface that ignores it renders exactly the card it rendered before. The durable park row
+     * carries the same seat under the same contract, filled by the same one factory.
+     */
+    readonly ruleOffersAbsence?: "mandated" | "lane_cannot_speak" | "shadowed";
     /** The human/model-readable prompt explaining what needs approval. */
     message: string;
     /** Runner-filled source identity (design S1d §1): the end-user {@link AskRequest} issuing task's

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, posix as posixPath, sep, win32 as winPath } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { boundInputHashOf } from "./canonical-json.js";
@@ -85,6 +86,7 @@ export function checkToolPolicyProjection(projection, req) {
 export function constraintChainEntryOf(policy, meta) {
     const m = {
         ...(meta?.autoModeArmed ? { autoModeArmed: true } : {}),
+        ...(meta?.autoModeArming !== undefined ? { autoModeArming: meta.autoModeArming } : {}),
         ...(meta?.durableMandate ? { durableMandate: true } : {}),
         ...(meta?.contentMandate ? { contentMandate: true } : {}),
     };
@@ -93,6 +95,31 @@ export function constraintChainEntryOf(policy, meta) {
         return { opaque: true, ...m };
     return { components: p.components, requiresLiveRemainder: p.requiresLiveRemainder, ...m };
 }
+function chainEntryOfLayerCarrying(layer, carryArming) {
+    const arming = carryArming ? sanitizeAutoModeArmingRecipe(layer.autoMode?.arming) : undefined;
+    return constraintChainEntryOf(layer.policy, {
+        ...(layer.autoMode !== undefined ? { autoModeArmed: true } : {}),
+        ...(arming !== undefined ? { autoModeArming: arming } : {}),
+        ...(layer.durableMandate === true ? { durableMandate: true } : {}),
+        ...(layer.contentMandate === true ? { contentMandate: true } : {}),
+    });
+}
+export function constraintChainEntryOfLayer(layer) {
+    let armingLive = false;
+    if (layer.autoMode?.arming !== undefined) {
+        try {
+            const d = layer.autoMode.decider;
+            armingLive = d.breakerOpen() !== true && typeof d.consecutiveFailures === "function" && d.consecutiveFailures() === 0;
+        }
+        catch {
+            armingLive = false;
+        }
+    }
+    return chainEntryOfLayerCarrying(layer, armingLive);
+}
+export function constraintChainEntryOfSuppliedLayer(layer, recorded) {
+    return chainEntryOfLayerCarrying(layer, recorded?.autoModeArming !== undefined);
+}
 function stableJson(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v) ?? "null";
@@ -354,6 +381,7 @@ export function combinePolicies(...policies) {
             let rewrite;
             let settled;
             let ruleAskText;
+            let probeMandateSeen = false;
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
@@ -381,10 +409,13 @@ export function combinePolicies(...policies) {
                 if (d.action === "ask" && d.matchedAskRule !== undefined && ruleAskText === undefined) {
                     ruleAskText = d.matchedAskRule;
                 }
+                if (d.action === "ask" && d.probeMandated === true)
+                    probeMandateSeen = true;
             }
             if (asked) {
                 const merged = rewrite?.updatedInput;
-                const withMark = ruleAskText !== undefined && asked.matchedAskRule === undefined ? { ...asked, matchedAskRule: ruleAskText } : asked;
+                const withRuleAsk = ruleAskText !== undefined && asked.matchedAskRule === undefined ? { ...asked, matchedAskRule: ruleAskText } : asked;
+                const withMark = probeMandateSeen && withRuleAsk.probeMandated !== true ? { ...withRuleAsk, probeMandated: true } : withRuleAsk;
                 return merged !== undefined ? { ...withMark, updatedInput: merged } : withMark;
             }
             const allowed = rewrite ?? ALLOW;

package/dist/core/tool-result-store.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
+import { uuidv7 } from "../engine/session/uuid.js";
 import { defineTool, errorResult } from "./tools.js";
 import { deliverEngineNotice } from "./types.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
@@ -178,7 +179,7 @@ export function createOffloadPersist(store, sessionId, onNotice) {
             const message = `tool-result offload: persisting ref "${ref}" failed (${cause}) — this write attempt stored nothing; ` +
                 `unless an earlier attempt already stored this ref, the inline preview is all that survived. ` +
                 `A later re-clear of the same result retries the write.`;
-            deliverEngineNotice(onNotice, { code: "tool_result.offload_put_failed", message, detail: { ref, sessionId, cause } });
+            deliverEngineNotice(onNotice, { code: "tool_result.offload_put_failed", message, detail: { ref, sessionId, cause, occurrenceId: uuidv7() } });
         };
         try {
             void Promise.resolve(store.put(ref, fullText, provenance)).catch(reportFailedWrite);

package/dist/core/trace.d.ts

@@ -58,6 +58,23 @@ export type TraceEvent = {
     kind: "task.start";
     version: 1;
     taskId: string;
+    /** #499 (additive) — the ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
+     *  `spec.taskId ?? sessionId`, so two runs of one session that declare no host task id emit two
+     *  task.start frames under ONE id and a consumer pairing start↔end has no way to say which end
+     *  closes which start. Present on every `task.start` (the frame is emitted after prepare, which
+     *  is where the id is minted).
+     *
+     *  PAIRING CONTRACT, stated in full because it is not symmetric: a `task.end` may carry a
+     *  `runId` this frame never announced — a run whose PREPARE threw emits the end and no start
+     *  (there was nothing to start), and that end still names its run because prepare-time
+     *  disclosures already did. So: every start has an end; not every end has a start. A consumer
+     *  building spans must treat an unmatched end as a run that never began, not as a lost start.
+     *
+     *  SCOPE, stated so it is not mistaken for more: only this frame and `task.end` carry the run
+     *  axis today. Every other frame in this union still keys on `taskId` alone, so frames from two
+     *  CONCURRENT runs that share a host `taskId` remain mutually indistinguishable inside their
+     *  windows. Extending the axis across the union is a separate pass. */
+    runId?: string;
     model: string;
     /** R4 (1.285): the engine build (package.json version, runtime-resolved) that produced this
      *  run — binds trace forensics to an exact build. "unknown" if resolution failed. */
@@ -247,6 +264,13 @@ export type TraceEvent = {
     kind: "task.end";
     version: 1;
     taskId: string;
+    /** #499 (additive) — the run this terminal closes; pairs with the `task.start` frame's `runId`
+     *  (see that field for why `taskId` cannot carry the pairing, and for the ASYMMETRY: this frame
+     *  is also emitted on the prepare-throw backstop, where no `task.start` exists — it still names
+     *  its run, because the id is minted at prepare's first statement and prepare-time disclosures
+     *  already carry it). Absent only where prepare was never entered at all, which is the same
+     *  condition its `taskId: "unknown"` states. */
+    runId?: string;
     status: TaskStatus;
     errorCode?: string;
     turns: number;