@sema-agent/core 5.64.0 → 6.0.0

package/dist/orchestration/run-workflow-tool.d.ts

@@ -230,6 +230,22 @@ export interface RunWorkflowToolDeps {
      *  reason `forwardEvent`/`inheritedGateForChildren` ride deps); `ctx.interactionPosture` still
      *  wins when a wrapping path provides it. */
     parentInteractionPosture?: "interactive" | "headless";
+    /**
+     * design/383 §2.5 (rescan post-6.0.0-RC) — the HOST session's live capture opt-out state,
+     * threaded as a MOUNT dep for the same unenriched-auto-mount reason as the posture seat above.
+     * A call-time GETTER on purpose (`ctx.memoryCaptureOptedOut` is live — a mid-run flip must
+     * floor agents the workflow spawns after it); the enriched-ctx getters win when a wrapping
+     * mount provides them. Rides `RunWorkflowOptions.parentMemoryCaptureState` into both spawn legs.
+     */
+    parentMemoryCaptureState?: () => {
+        optedOut: boolean;
+        indeterminate: boolean;
+        controlDir?: string;
+        ancestors?: ReadonlyArray<{
+            sessionId: string;
+            controlDir?: string;
+        }>;
+    };
     /** TRUSTED nesting depth from the run's internals (NOT a tool param) — passed to `startWorkflow` so a
      *  cross-process child workflow is rejected by the one-level guard. */
     workflowDepth?: number;
@@ -317,8 +333,10 @@ export interface RunWorkflowToolDeps {
     parentCheckpointStoreDisabled?: boolean;
     /** #235 — the deployment's structured notice sink (`RunnerDeps.onNotice`), forwarded into the governed
      *  build so the fields a script's agent spec wrote that did NOT reach the child are announced instead of
-     *  vanishing (`workflow.governance_key_stripped`). A dep for the same reason as the seats above: this
-     *  auto-mount's execute ctx is minimal. Absent ⇒ the historic `console.warn` loudness. */
+     *  vanishing (`workflow.governance_key_stripped`). #505 ① — the same seat now also carries the OPTIONS
+     *  membrane's twin announcement (`workflow.agent_option_ignored`: keys of `agent(spec, opts)`'s second
+     *  argument that did not apply). A dep for the same reason as the seats above: this auto-mount's execute
+     *  ctx is minimal. Absent ⇒ the historic `console.warn` loudness. */
     onNotice?: (n: import("../core/types.js").EngineNotice) => void;
     /** Twin of the above for design/148 S1's center-artifact inheritance (see the `ctx.centerArtifactDigest`/
      *  `ctx.centerSourceRevision` reads at the `startWorkflow` options site) — `centerAdoption` resolves

package/dist/orchestration/run-workflow-tool.js

@@ -330,8 +330,12 @@ export async function createRunWorkflowTool(d) {
             "until the next phase() call. Scoped — await phase('Fix', async () => { ...agents... }); groups just the " +
             "body (equivalently, pass { phase: 'Fix' } in an agent's opts). Give each stage a phase so progress " +
             "renders as stage groups; use the same titles you declared in meta.phases.\n" +
-            "• spec.modelName works only when the deployment configured a workflow model allowlist; if unsure, omit " +
-            "modelName and the agent runs on the deployment's default role.\n" +
+            "• spec.modelName works only when the deployment configured a workflow model allowlist, and its legal " +
+            "values are that deployment's own model CATALOG KEYS — not generic tier words (a bare 'opus'/'sonnet'/" +
+            "'haiku' is a name the catalog almost certainly does not hold, and is refused rather than approximated). " +
+            "It also goes on the SPEC (the first argument), never in an agent()'s options object; `model` is accepted " +
+            "there as an alias for the same field. If unsure, omit it and the agent runs on the deployment's default " +
+            "role.\n" +
             "\n" +
             "Don't race. After launching, you know nothing about what the workflow found. Never fabricate or predict its " +
             "results in any format — not as prose, summary, or structured output. When a completion notifier is wired " +
@@ -507,6 +511,19 @@ export async function createRunWorkflowTool(d) {
                     parentToolCallId: ctx.toolCallId,
                     ...(sourceTaskId !== undefined ? { parentTaskId: sourceTaskId } : {}),
                     ...((ctx.interactionPosture ?? d.parentInteractionPosture) !== undefined ? { interactionPosture: (ctx.interactionPosture ?? d.parentInteractionPosture) } : {}),
+                    ...(() => {
+                        if ("memoryCaptureOptedOut" in ctx) {
+                            return {
+                                parentMemoryCaptureState: () => ({
+                                    optedOut: ctx.memoryCaptureOptedOut === true,
+                                    indeterminate: ctx.memoryCaptureIndeterminate === true,
+                                    ...(ctx.memoryCaptureControlDir !== undefined ? { controlDir: ctx.memoryCaptureControlDir } : {}),
+                                    ...(ctx.memoryCaptureAncestors !== undefined ? { ancestors: ctx.memoryCaptureAncestors } : {}),
+                                }),
+                            };
+                        }
+                        return d.parentMemoryCaptureState !== undefined ? { parentMemoryCaptureState: d.parentMemoryCaptureState } : {};
+                    })(),
                     ...(d.parentModel !== undefined ? { defaultModel: d.parentModel } : {}),
                     ...(d.parentGetApiKeyAndHeaders !== undefined ? { defaultGetApiKeyAndHeaders: d.parentGetApiKeyAndHeaders } : {}),
                     ...(parentCenterArtifactDigest !== undefined ? { parentCenterArtifactDigest } : {}),
@@ -607,12 +624,14 @@ export async function createRunWorkflowTool(d) {
                     .catch(() => { });
             }
             return {
-                details: { type: "workflow-run", status: "backgrounded", workflowRunId: runId },
+                details: { type: "workflow-run", status: "backgrounded", workflowRunId: runId, task_id: runId },
                 content: JSON.stringify({
                     runId,
                     task_id: runId,
                     status: "started",
                     ...(persistedScriptPath !== undefined ? { scriptPath: persistedScriptPath } : {}),
+                    handling: "This tool result is internal metadata — never quote or paste any part of it (the ids above, and scriptPath when present) into a user-facing reply. " +
+                        "In your own words, briefly tell the user what you launched; do not echo this result.",
                     note: (() => {
                         const pollExpr = d.taskRegistry ? `TaskOutput({ task_id: "${runId}" })` : undefined;
                         const blockingPollExpr = d.taskRegistry ? `TaskOutput({ task_id: "${runId}", block: true })` : undefined;

package/dist/orchestration/workflow-governance.d.ts

@@ -37,6 +37,14 @@ export declare class WorkflowModelNotAllowedError extends Error {
  */
 export interface WorkflowAgentSpec {
     objective: string;
+    /**
+     * The canonical spelling, and the only one this type expresses. At RUNTIME the spec ALSO accepts
+     * `model` as an alias for this field (see {@link SPEC_KEY_ALIASES}) — the same axis is spelled
+     * `model` by the Agent tool and by agents frontmatter, and a script author who reaches for the
+     * spelling those two taught should not silently get the deployment's default model instead. The
+     * alias carries a NAME exactly like this field does; a `Model` OBJECT is refused under either
+     * spelling.
+     */
     modelName?: string;
     thinking?: ThinkingLevel;
     systemPrompt?: string;
@@ -83,6 +91,28 @@ export interface WorkflowAgentSpec {
  * for a BREAKING window.
  */
 export declare const WHITELIST_KEYS: readonly ["objective", "modelName", "thinking", "systemPrompt", "images", "limits", "readFace", "readDenyPatterns"];
+/**
+ * #505 ② — ACCEPTED ALIAS SPELLINGS on the spec: `alias → the {@link WHITELIST_KEYS} member it means`.
+ *
+ * One axis, three faces, two words: the Agent tool takes `model`, agents frontmatter takes `model`, and
+ * this seam takes `modelName` (the name is not free to change here — `model` on a `TaskSpec` is the
+ * resolved `Model` OBJECT, and the phases meta of the workflow tool already spends the word too). Renaming
+ * across three surfaces buys uniformity at the price of a breaking churn in two of them; MUTUAL
+ * RECOGNITION buys the same authoring outcome for the price of this map. So the alias is normalized here,
+ * at the single door untrusted spec objects come through, and NOTHING downstream of {@link pickWhitelist}
+ * ever sees the alias spelling — the rest of this module, `buildGovernedChildSpec` and `resolveModelName`
+ * included, keeps reading exactly one field.
+ *
+ * An alias is NOT a whitelist key: `WHITELIST_KEYS` stays the closed set of fields that map onto `TaskSpec`,
+ * so the "no control-plane key on the whitelist" property is untouched and a `Model` object written as
+ * `model` is still structurally unable to reach the child (it is type-refused, not copied — see the
+ * normalization at the foot of `pickWhitelist`).
+ *
+ * A test pins that this map has exactly ONE member, because the normalization arm below is written for that
+ * one member by name: reading it generically would mean re-reading `s[canonical]` a second time, and the
+ * single-read discipline every other field in this file follows is worth more than a loop over one entry.
+ */
+export declare const SPEC_KEY_ALIASES: ReadonlyMap<string, string>;
 /**
  * One field of an untrusted agent spec that did NOT reach the child, and why.
  *  - `not_whitelisted` — the field is outside {@link WHITELIST_KEYS}: a control-plane field, a work field
@@ -99,8 +129,36 @@ export interface StrippedSpecKeyNote {
 /** The {@link EngineNotice} family for the strip announcement (see {@link WHITELIST_KEYS}). ONE notice per
  *  governed build, listing every field that did not cross the seam — a governed script can carry an
  *  arbitrary number of unrecognized fields, and a per-field notice would turn one authoring mistake into a
- *  flood. Not de-duplicated across builds: each spawn is a distinct fact about a distinct spec. */
+ *  flood. Not de-duplicated across builds: each spawn is a distinct fact about a distinct spec — and
+ *  `detail.occurrenceId` (#495) is what makes that sentence checkable by a consumer, which otherwise saw
+ *  two builds of one spec as one repeated notice with every key equal. */
 export declare const STRIPPED_KEYS_NOTICE_CODE = "workflow.governance_key_stripped";
+/**
+ * #505 ① — the OPTIONS-side twin of {@link STRIPPED_KEYS_NOTICE_CODE}. `agent(spec, opts)`'s SECOND
+ * argument crosses its own membrane (`safeAgentOptions` in workflow-primitives.ts), which copies a small
+ * accepted set and dropped everything else in silence — a mistyped `lable`, an option that belongs on
+ * another seam, or a known option carrying a value its type check rejects (`label: 42`) all vanished with
+ * the call still succeeding.
+ *
+ * A SEPARATE code from the spec-side strip on purpose: the two membranes accept different key sets and the
+ * message names the set, so an operator reading `workflow.governance_key_stripped` about an OPTIONS key
+ * would look for it in the spec whitelist and correctly not find it. The severe half of this family — a
+ * SPEC field written on the options object — is not announced at all but REFUSED at the membrane (a
+ * silently ignored `model` runs the child on the deployment default, which is a different agent than the
+ * author asked for); this notice covers only the residue that is genuinely just ignored.
+ */
+export declare const IGNORED_AGENT_OPTIONS_NOTICE_CODE = "workflow.agent_option_ignored";
+/** The announcement budget, shared with the spec-side survey: one bound, one renderer, one place. Exported
+ *  so the surveying caller can stop COLLECTING at the same number this emitter would render. */
+export declare const MAX_ANNOUNCED_KEYS = 20;
+/**
+ * Announce the ignored option keys — one aggregated notice per `agent()` call, never one per key (an
+ * options object's key count is the script's to choose). `sample` is expected pre-bounded by the caller to
+ * {@link MAX_ANNOUNCED_KEYS}; `total` is exact. Key names are script-authored text landing on an operator
+ * surface, so they cross {@link renderStrippedKey} — the same scrubber the spec-side line uses, never a
+ * second one — and the caller quotes nothing itself.
+ */
+export declare function emitIgnoredAgentOptionsNotice(total: number, sample: readonly string[], accepted: readonly string[], onNotice?: (n: EngineNotice) => void): void;
 /** Per-child workflow ceilings the engine forces onto every spawned agent (design/98 §D.6), independent of
  *  what the script asks for. The child's effective limits = min(script, baseline, these). */
 export interface WorkflowChildCaps {

package/dist/orchestration/workflow-governance.js

@@ -3,6 +3,7 @@ import { tightenTaskSpec } from "../core/tighten-task-spec.js";
 import { sanitizeUntrustedText } from "../core/untrusted-text.js";
 import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
+import { uuidv7 } from "../engine/session/uuid.js";
 export class WorkflowModelNotAllowedError extends Error {
     modelName;
     code = "workflow.model_not_allowed";
@@ -23,6 +24,7 @@ export const WHITELIST_KEYS = [
     "readDenyPatterns",
 ];
 const WHITELIST_KEY_SET = new Set(WHITELIST_KEYS);
+export const SPEC_KEY_ALIASES = new Map([["model", "modelName"]]);
 export const STRIPPED_KEYS_NOTICE_CODE = "workflow.governance_key_stripped";
 const MAX_STRIPPED_KEYS_ANNOUNCED = 20;
 const MAX_STRIPPED_KEY_CHARS = 64;
@@ -50,7 +52,27 @@ function emitStrippedKeysNotice(survey, onNotice) {
         deliverEngineNotice(onNotice, {
             code: STRIPPED_KEYS_NOTICE_CODE,
             message,
-            detail: { total: survey.total, stripped: shown, ...(omitted > 0 ? { omitted } : {}) },
+            detail: { total: survey.total, stripped: shown, ...(omitted > 0 ? { omitted } : {}), occurrenceId: uuidv7() },
+        });
+    }
+    catch {
+    }
+}
+export const IGNORED_AGENT_OPTIONS_NOTICE_CODE = "workflow.agent_option_ignored";
+export const MAX_ANNOUNCED_KEYS = MAX_STRIPPED_KEYS_ANNOUNCED;
+export function emitIgnoredAgentOptionsNotice(total, sample, accepted, onNotice) {
+    const shown = sample.map(renderStrippedKey);
+    const omitted = total - shown.length;
+    const list = shown.map((k) => JSON.stringify(k)).join(", ") + (omitted > 0 ? `, +${omitted} more` : "");
+    const message = `workflow: ${total} key(s) of an \`agent(spec, opts)\` OPTIONS object (the SECOND argument) were not applied (${list}). ` +
+        `The options object accepts only: ${accepted.join(", ")} — an unrecognized key, or a known one carrying a value its ` +
+        `option does not accept, is ignored and the agent runs without it. Everything about the CHILD's behavior belongs on ` +
+        `the spec (the first argument).`;
+    try {
+        deliverEngineNotice(onNotice, {
+            code: IGNORED_AGENT_OPTIONS_NOTICE_CODE,
+            message,
+            detail: { total, ignored: shown, ...(omitted > 0 ? { omitted } : {}), occurrenceId: uuidv7() },
         });
     }
     catch {
@@ -177,17 +199,38 @@ function pickWhitelist(scriptSpec) {
     }
     const s = scriptSpec;
     const stripped = { total: 0, sample: [] };
+    let canonicalIsOwn = false;
+    let aliasIsOwn = false;
     for (const k of Object.keys(s)) {
-        if (WHITELIST_KEY_SET.has(k))
+        if (k === "modelName")
+            canonicalIsOwn = true;
+        else if (k === "model")
+            aliasIsOwn = true;
+        if (WHITELIST_KEY_SET.has(k) || SPEC_KEY_ALIASES.has(k))
             continue;
         stripped.total++;
         if (stripped.sample.length < MAX_STRIPPED_KEYS_ANNOUNCED)
             stripped.sample.push({ key: k, reason: "not_whitelisted" });
     }
+    const canonicalDesc = Object.getOwnPropertyDescriptor(s, "modelName");
+    const aliasDesc = Object.getOwnPropertyDescriptor(s, "model");
+    if ((canonicalIsOwn && canonicalDesc === undefined) || (aliasIsOwn && aliasDesc === undefined)) {
+        throw new WorkflowScriptError("agent(spec): this spec reports its own properties inconsistently between two reads of the same object — " +
+            "the model field cannot be resolved from a shape that changes while it is being read. Pass a plain object.");
+    }
+    const hiddenOwnSpelling = !canonicalIsOwn && canonicalDesc !== undefined ? "modelName" : !aliasIsOwn && aliasDesc !== undefined ? "model" : undefined;
+    if (hiddenOwnSpelling !== undefined) {
+        throw new WorkflowScriptError(`agent(spec): \`${hiddenOwnSpelling}\` is an OWN property of this spec that its own-key enumeration does not report ` +
+            `(a non-enumerable own key, or an object that answers differently across two reads). A model spelling the spec ` +
+            `hides from its own shape is refused rather than read as an inherited default — write it as an ordinary property.`);
+    }
+    const valueOfSnapshot = (d) => (d === undefined ? undefined : d.get !== undefined ? d.get.call(s) : d.value);
+    const modelNameInheritedRaw = canonicalIsOwn ? undefined : s.modelName;
+    const modelNameOwnRaw = valueOfSnapshot(canonicalDesc);
+    const modelAliasRaw = valueOfSnapshot(aliasDesc);
     const objective = s.objective;
     const thinking = s.thinking;
     const systemPrompt = s.systemPrompt;
-    const modelNameRaw = s.modelName;
     if (typeof objective !== "string" || objective.length === 0) {
         throw new WorkflowScriptError("agent(spec): `objective` is required and must be a non-empty string");
     }
@@ -257,12 +300,22 @@ function pickWhitelist(scriptSpec) {
         }
         safe.readDenyPatterns = entries;
     }
-    let modelName;
-    if (modelNameRaw !== undefined) {
-        if (typeof modelNameRaw !== "string")
-            throw new WorkflowScriptError("agent(spec): `modelName` must be a string (a model NAME, never a Model object)");
-        modelName = modelNameRaw;
+    const readModelName = (raw, spelling) => {
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== "string") {
+            throw new WorkflowScriptError(`agent(spec): \`${spelling}\` must be a string (a model NAME, never a Model object)` +
+                (spelling === "modelName" ? "" : ` — \`${spelling}\` is accepted as an alias for \`modelName\`, and carries a name just like it`));
+        }
+        return raw;
+    };
+    const authoredCanonical = readModelName(modelNameOwnRaw, "modelName");
+    const aliasModelName = readModelName(modelAliasRaw, "model");
+    if (authoredCanonical !== undefined && aliasModelName !== undefined && authoredCanonical !== aliasModelName) {
+        throw new WorkflowScriptError(`agent(spec): \`modelName\` and \`model\` are two spellings of ONE field but name DIFFERENT models ` +
+            `("${authoredCanonical}" vs "${aliasModelName}") — write exactly one of them (\`modelName\` is the canonical spelling).`);
     }
+    const modelName = authoredCanonical ?? aliasModelName ?? readModelName(modelNameInheritedRaw, "modelName");
     return { safe, modelName, stripped };
 }
 function clampResourceLimits(safe, base, caps) {

package/dist/orchestration/workflow-meta.d.ts

@@ -12,8 +12,10 @@
  * "fix your meta" error BEFORE the (hard) sandbox ever runs the body.
  */
 import type { WorkflowMeta } from "./workflow-script-runner.js";
-/** Thrown when an LLM-authored workflow script is malformed at the static layer (bad meta, oversized source,
- *  a forbidden construct). Carries a `code` so the tool can return a structured error the model can act on. */
+/** Thrown when a workflow script is the party at fault: malformed at the static layer (bad meta, oversized
+ *  source, a forbidden construct), or — at RUN time — calling a primitive with a shape it cannot run (a
+ *  host-API stub in the sandbox, an unusable agent spec, a `parallel`/`pipeline` member that is not a
+ *  function). Carries a `code` so the tool can return a structured error the model can act on. */
 export declare class WorkflowScriptError extends Error {
     readonly code = "workflow.script_error";
     constructor(message: string);

package/dist/orchestration/workflow-primitives.js

@@ -1,21 +1,64 @@
 import { assertSupportedAgentIsolation } from "./workflow.js";
-import { buildGovernedChildSpec, overlayWorktreeBaseline } from "./workflow-governance.js";
-function safeAgentOptions(opts) {
+import { WorkflowScriptError } from "./workflow-meta.js";
+import { buildGovernedChildSpec, emitIgnoredAgentOptionsNotice, overlayWorktreeBaseline, MAX_ANNOUNCED_KEYS, SPEC_KEY_ALIASES, WHITELIST_KEYS, } from "./workflow-governance.js";
+const ACCEPTED_AGENT_OPTION_KEYS = ["label", "phase", "schema", "agentType", "isolation"];
+const ACCEPTED_AGENT_OPTION_KEY_SET = new Set(ACCEPTED_AGENT_OPTION_KEYS);
+const SPEC_KEYS_MISPLACED_ON_OPTIONS = new Map([
+    ...WHITELIST_KEYS.map((k) => [k, k]),
+    ...SPEC_KEY_ALIASES,
+    ["effort", "thinking"],
+]);
+function safeAgentOptions(opts, onNotice) {
     if (typeof opts !== "object" || opts === null)
         return {};
     const o = opts;
+    const names = Object.keys(o);
+    for (const name of names) {
+        const spelling = SPEC_KEYS_MISPLACED_ON_OPTIONS.get(name);
+        if (spelling === undefined || o[name] === undefined)
+            continue;
+        throw new WorkflowScriptError(`agent(spec, opts): \`${name}\` is a SPEC field written on the OPTIONS object (the SECOND argument), where nothing ` +
+            `reads it — move it into the spec (the FIRST argument)${name === spelling ? "" : `, spelled \`${spelling}\``}. ` +
+            `The options object accepts only: ${ACCEPTED_AGENT_OPTION_KEYS.join(", ")}. The agent was NOT started: silently ` +
+            `ignoring \`${name}\` would have run a different child than the one asked for.`);
+    }
     const out = {};
-    if (typeof o.label === "string")
-        out.label = o.label;
-    if (typeof o.phase === "string")
-        out.phase = o.phase;
-    if (o.schema !== undefined)
-        out.schema = o.schema;
-    if (typeof o.agentType === "string")
-        out.agentType = o.agentType;
-    assertSupportedAgentIsolation(o.isolation);
-    if (o.isolation === "worktree")
+    const rejected = new Set();
+    const label = o.label;
+    if (typeof label === "string")
+        out.label = label;
+    else if (label !== undefined)
+        rejected.add("label");
+    const phase = o.phase;
+    if (typeof phase === "string")
+        out.phase = phase;
+    else if (phase !== undefined)
+        rejected.add("phase");
+    const schema = o.schema;
+    if (schema !== undefined)
+        out.schema = schema;
+    const agentType = o.agentType;
+    if (typeof agentType === "string")
+        out.agentType = agentType;
+    else if (agentType !== undefined)
+        rejected.add("agentType");
+    const isolation = o.isolation;
+    assertSupportedAgentIsolation(isolation);
+    if (isolation === "worktree")
         out.isolation = "worktree";
+    else if (isolation !== undefined)
+        rejected.add("isolation");
+    let total = 0;
+    const sample = [];
+    for (const name of names) {
+        if (ACCEPTED_AGENT_OPTION_KEY_SET.has(name) && !rejected.has(name))
+            continue;
+        total++;
+        if (sample.length < MAX_ANNOUNCED_KEYS)
+            sample.push(name);
+    }
+    if (total > 0)
+        emitIgnoredAgentOptionsNotice(total, sample, ACCEPTED_AGENT_OPTION_KEYS, onNotice);
     return out;
 }
 function formatResourceClampNote(notes) {
@@ -26,7 +69,7 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
     const agent = (spec, opts) => {
         if (typeof spec === "string")
             spec = { objective: spec };
-        const agentOpts = safeAgentOptions(opts);
+        const agentOpts = safeAgentOptions(opts, governance?.onNotice);
         const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase != null ? { ...b, base: overlayWorktreeBaseline(b.base, b.worktreeBase) } : b;
         const childSpec = governance
             ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)), governance.onNotice)

package/dist/orchestration/workflow-types.d.ts

@@ -88,13 +88,60 @@ export interface WorkflowAgentRun {
     /** F5/B4: total attempts this call made (set only when > 1 — stall/throttle retries happened). The record's
      *  `stats` are the FINAL attempt's; burned retry spend rolls into `run.stats`/budget (CC semantics). */
     attempts?: number;
-    /** F5/B4: why the LAST retry happened — "stalled" (progress watchdog) or "throttled" (degraded response). */
+    /** F5/B4: why the LAST retry happened — "stalled" (progress watchdog), "throttled" (degraded response),
+     *  or (#481) "awaiting_approval": the watchdog fired while this leg had an outstanding human approval, so
+     *  the retry happened but was NOT charged against the stall budget. Kept a free-form `string` (it always
+     *  was) — a consumer that switched on the first two words must treat an unknown word as "some retry
+     *  happened", which is what the field has always meant. */
     lastAttemptReason?: string;
+    /** #481 — the leg's outstanding human approvals as the DEPLOYMENT's approval plane last reported them
+     *  (verbatim from {@link TaskResult.pendingApproval}: core mints no ask ids and estimates nothing). Written
+     *  LAST-WINS on every attempt terminal and on the leg's own terminal, and REMOVED when a later report
+     *  carries none — so a settled leg never keeps advertising a wait that has since been decided. Absent
+     *  whenever the deployment does not report it, which is the ordinary world. */
+    pendingApproval?: {
+        askIds: readonly string[];
+        oldestCreatedAtMs: number;
+    };
+    /** #485 — how long this leg spent BLOCKED on human approvals, in ms, as the deployment's approval plane
+     *  measured it ({@link TaskResult.approvalWaitedMs}, carried verbatim). The engine starts no approval
+     *  clock and does no arithmetic on this: a receipt's figure is already that leg's cumulative wait, so a
+     *  later receipt SUPERSEDES an earlier one (last-wins) and is never added to it — summing successive
+     *  reports of one cumulative counter double-counts. Absent when the deployment does not report it.
+     *
+     *  A REPLAYED leg ({@link replayed}) never carries this, nor {@link pendingApproval}, even when the
+     *  journaled result it was minted from did. The wait was paid by the run that actually made the call; a
+     *  resume that served the answer from cache waited for nobody, and copying the figure forward would let
+     *  this run's total-timeout disclosure report a wait it never experienced. */
+    approvalWaitedMs?: number;
     /** design/114 — the session id of this agent's run (= its `TaskResult.sessionId`). Surfaces the conversation
      *  handle to the observation layer so an external initiator can WARM-resume a failed/timed-out agent
      *  (`fork(sessionId)→runTask`, or `runTask({sessionId})`) instead of a fresh re-run. An opaque id (not
      *  content) → scope-gated via `getWorkflowRun`, no redaction needed. Absent for a stub run that minted none. */
     sessionId?: string;
+    /**
+     * #499 — the ENGINE-minted identity of the task run behind this record (= its `TaskResult.runId`).
+     *
+     * Named `taskRunId`, NOT `runId`: in this file and in every `WorkflowEvent`, `runId` already means
+     * the WORKFLOW run's id, and two different runs wearing one field name on sibling objects is the
+     * "同名异形" hazard {@link WorkflowRun} documents elsewhere. This one names the CHILD leg's engine run.
+     *
+     * Why it is not covered by {@link sessionId}: retry attempts of one leg REUSE the session
+     * (the attempt spec carries the same `sessionId`), so a record whose {@link attempts} > 1 cannot be
+     * attributed to a specific attempt by session — and the last-wins seats beside it
+     * ({@link pendingApproval} / {@link approvalWaitedMs}) are reported per attempt. This is the axis
+     * that says WHICH run produced the values on this row.
+     *
+     * Written LAST-WINS at four folds: the leg's terminal, the salvaged stall-exhaustion tail, the
+     * REPLAYED path (where — like the session handle beside it — it names the ORIGINAL run that produced
+     * the cached result, a true and joinable fact about where those bytes came from), and each RETRY
+     * ATTEMPT's report. The last one is load-bearing rather than tidy: the attempt fold writes
+     * {@link pendingApproval} / {@link approvalWaitedMs} from a specific attempt and persists the row
+     * immediately, so while an approval is outstanding the durable row holds one run's figures — and
+     * without this it held them under no id able to name that run. Absent whenever the underlying result
+     * carried none (a stub run, or a leg whose prepare was never entered).
+     */
+    taskRunId?: string;
     /** RB-393① — the WORKTREE directory this agent ran in, present ONLY for an
      *  `isolation: "worktree"` agent whose worktree the engine actually minted (reported by the runner's
      *  workspace-observation seam and folded on while the agent is still RUNNING, so an interrupted run's
@@ -192,6 +239,70 @@ export interface WorkflowRun {
         spentTokens: number;
         unsettledTokens?: number;
     };
+    /** The run's TERMINAL total-timeout interruption — present ONLY when the `totalTimeoutMs` deadline had
+     *  FIRED by the time this run reached its (failed) terminal, absent on every other run: one that finished
+     *  inside its deadline, one that failed for its own reason before the deadline, and one that armed no
+     *  deadline at all. Same ADDITIVE-observation contract as {@link agentFailures} and
+     *  {@link budgetOvershoot} (never a gate input, never re-read by the engine, status enums untouched).
+     *
+     *  WHY IT EXISTS: the deadline abandons the script body, so the run finalizes `failed` carrying the
+     *  deadline's own message — and that is ALL any downstream face had to go on. A run whose agents had in
+     *  fact answered (their outputs already on the record, inlined as `partial_results` on a poll) read as a
+     *  total loss. This seat is the missing distinction: it states that the deadline is what ended the run,
+     *  and what the run had ACHIEVED at that moment. Extending {@link WorkflowRunStatus} with a separate
+     *  terminal word would say the same thing at the cost of a wire contract every consumer switches on, so
+     *  the fact rides an optional member instead.
+     *
+     *  `timeoutMs` is the deadline that fired (the run's configured `totalTimeoutMs`), so a reader can raise
+     *  it deliberately rather than guess it.
+     *
+     *  ⚠️ THE COUNTS ARE A POINT-IN-TIME SNAPSHOT, taken BEFORE the terminal fold that closes abandoned
+     *  agents. That is the whole point (it reports what the deadline INTERRUPTED), and it is also why
+     *  `agentsFailed` here is NOT {@link agentFailures}: the terminal fold marks every still-running agent
+     *  `failed`, so the record's tally counts them and this member does not. The two are different questions
+     *  about the same run — "how many had failed on their own when the clock ran out" versus "how many agent
+     *  records ended failed" — and a consumer that swaps one for the other reports abandoned work as failed
+     *  work. `agentsInFlight` counts records still `running` at that moment, which includes calls still
+     *  QUEUED for a concurrency slot (they had not been refused, they had not finished).
+     *
+     *  The seat is an OBJECT rather than a flat pair of members so a later disclosure about the same terminal
+     *  (how much of the deadline was spent waiting on something outside the run, say) joins it additively with
+     *  no shape change on any of the three faces. `approvalWaitedMs` is that later disclosure, landed:
+     *
+     *  #481/#485 `approvalWaitedMs` — the LARGEST single leg's `WorkflowAgentRun.approvalWaitedMs`, i.e. the
+     *  longest any one agent spent blocked on a human approval, as the deployment's approval plane itself
+     *  measured it. It answers the one question the four counts above cannot: was this run SLOW, or was it
+     *  WAITING? A value near `timeoutMs` says the window went on a person, not on work — raise the deadline
+     *  and you buy nothing; get the approval answered faster and you buy the whole run.
+     *
+     *  Read it as a LOWER BOUND on the window spent blocked, never as a total. It is deliberately the MAX and
+     *  never a SUM: legs wait in parallel, so summing would report more waiting than the window contains and
+     *  break the only comparison the number is for. Every figure is the deployment's own — core starts no
+     *  approval clock and does no arithmetic on the values it is handed (see
+     *  {@link WorkflowAgentRun.approvalWaitedMs}).
+     *
+     *  ABSENT when no leg reported one, which includes every deployment that does not report at all. Absence
+     *  is NOT zero: "this deployment does not supply the fact" and "nobody waited" are different states and a
+     *  zero would collapse them.
+     *
+     *  ⚠️ SAME POINT-IN-TIME DISCIPLINE AS THE COUNTS, and it has a real edge worth stating plainly: only
+     *  figures ALREADY ON the agent records when the deadline fired can contribute. A leg still IN FLIGHT at
+     *  that moment is abandoned — its final receipt reaches the finalized-run guard and is never folded — so
+     *  it contributes the LAST figure it reported, not its closing one. In practice a leg that is waiting
+     *  reports once per stall window (each aborted attempt's receipt folds, see
+     *  `WorkflowAgentRun.approvalWaitedMs`), so the seat carries a figure that lags by at most one window;
+     *  a deployment with the progress watchdog disabled, or a deadline that fires inside the first window,
+     *  can leave it absent while a person was in fact being waited on. This is why the member is documented
+     *  as a LOWER BOUND and never as an accounting of the window. Folding an abandoned leg's closing receipt
+     *  instead would mean the deadline waiting on the very work it exists to abandon, and would make these
+     *  five members describe a moment that never existed. */
+    timeoutInterruption?: {
+        timeoutMs: number;
+        agentsCompleted: number;
+        agentsFailed: number;
+        agentsInFlight: number;
+        approvalWaitedMs?: number;
+    };
     phases: WorkflowPhase[];
     agents: WorkflowAgentRun[];
     /** design/97 CORE-3: nested `ctx.workflow` sub-groups (the persisted group tree). Empty when the script

package/dist/orchestration/workflow-types.js

@@ -67,11 +67,11 @@ export class WorkflowMaxAgentsError extends Error {
                 `Add a hard iteration cap to the loop, or pass a token budget.`
             : spentTokens !== undefined && spentTokens > budgetTotal
                 ? `Workflow agent() call cap reached (${max}), and the token budget is ALREADY EXCEEDED ` +
-                    `(${spentTokens.toLocaleString()} spent / ${budgetTotal.toLocaleString()} output tokens): agents already in flight when ` +
+                    `(${spentTokens.toLocaleString()} spent / ${budgetTotal.toLocaleString()} total tokens): agents already in flight when ` +
                     `the ceiling was reached are not bound by the per-call gate, so their spend landed on top of it. BOTH bounds are ` +
                     `binding — raising maxAgents alone would only buy more overshoot. Fan out over fewer items, or lower concurrency ` +
                     `(it bounds the overshoot) and raise the token budget deliberately.`
-                : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} output tokens), ` +
+                : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} total tokens), ` +
                     `so this is the CALL-COUNT cap, not the token ceiling: the script asked for more than ${max} agent() calls. ` +
                     `Fan out over fewer items, or raise maxAgents.`);
         this.max = max;

package/dist/orchestration/workflow.d.ts

@@ -386,6 +386,26 @@ export interface RunWorkflowOptions {
      *  spec) so a root's per-run posture override governs its workflow children too. Set by the
      *  `run_workflow` tool wiring from `ToolExecuteContext.interactionPosture`. */
     interactionPosture?: "interactive" | "headless";
+    /**
+     * design/383 §2.5 (rescan post-6.0.0-RC) — the HOST session's capture opt-out state, read AT
+     * EACH SPAWN (call-time getter, deliberately not a launch snapshot: `optedOut` is live — a
+     * mid-run `optOutMemoryCapture` flip must floor agents spawned after it). Threaded onto both
+     * spawn legs' internals as the same floor/indeterminate/queryDir/ancestor seats the subagent
+     * lane forwards, so a workflow child of an opted-out host commits nothing — the design's ruled
+     * disposition for the workflow HOST lane. Set by the `run_workflow` tool wiring (enriched ctx
+     * getters, else the auto-mount dep). Absent ⇒ no capture seat rides (a direct `runWorkflow`
+     * caller with no memory-mounted host — `originatingSessionId` still rides as `parentSessionId`
+     * for the record-query leg).
+     */
+    parentMemoryCaptureState?: () => {
+        optedOut: boolean;
+        indeterminate: boolean;
+        controlDir?: string;
+        ancestors?: ReadonlyArray<{
+            sessionId: string;
+            controlDir?: string;
+        }>;
+    };
     /** Call-time getter for the HOST run's RESOLVED Model object. A spawned agent whose
      *  fold chain (script spec → agentType → governance baseline) produced NO model inherits the
      *  parent's full object — baseUrl/key routing included — instead of falling to a string/role