@sema-agent/server 1.322.0 → 2.0.0

package/dist/http/routes/workflows.js

@@ -4,21 +4,35 @@ import { redactSecrets } from "../../trace/redact.js";
 import { HEARTBEAT_MS } from "../../runs.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
-const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/;
+const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/; // S8 self-orchestration runs: list / detail / live SSE
+// SVC-5 (design/97 CORE-5 #6): steer a STILL-RUNNING workflow agent (ctx.agentStream) by runId + label. POST-only,
+// so it never collides with the GET WORKFLOWS_RE above. The label is a non-slash segment (core mints `agent-N`
+// for an unlabelled agent, else the caller's opts.label) — URL-decoded by the handler.
 const WORKFLOW_AGENT_STEER_RE = /^\/v1\/workflows\/([^/]+)\/agents\/([^/]+)\/steer$/;
 export async function handleWorkflows(req, res, url, ctx) {
     const miss = { fell: false };
     await handleWorkflowsReadBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** SVC-5 的 steer 路——`handle()` 里位置在 tasks/runs 之后(鉴权门之后),故是**独立**的域入口。 */
 export async function handleWorkflowAgentSteer(req, res, url, ctx) {
     const miss = { fell: false };
     await handleWorkflowAgentSteerBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { runSessionAcceptOk } = ctx.helpers;
+    // S8 self-orchestration runs (design/97/98): GET /v1/workflows (list) · /v1/workflows/:id (detail) ·
+    // /v1/workflows/:id/stream (live SSE). OWNER-GATED by scope (= the creating principal, prepare-task.js
+    // scope: spec.principal). list/detail need the run store; live stream is in-process (subscribeWorkflow).
+    // 🔐 Identity from gatedPrincipal (direct-door-secure single point — crypto-verified principal JWT when
+    // directDoorActive, transparently `principalFrom` otherwise), NEVER the spoofable x-agent-principal header:
+    // a direct-door worker MUST NOT trust the raw header for a per-tenant owner gate (same bypass class —
+    // parity with the trace owner-gate, the workflow steer POST, and the elicit route). This block returns BEFORE
+    // the service-credential gate below, so the per-tenant gate here is the sole tenant boundary for these reads.
     const wfMatch = req.method === "GET" ? WORKFLOWS_RE.exec(url) : null;
     if (wfMatch) {
         const principal = gatedPrincipal(req, deps.config);
@@ -30,19 +44,29 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
             return;
         }
-        const scope = principal ?? "default";
+        const scope = principal ?? "default"; // matches core's run_workflow scope = spec.principal ?? "default"
         const wfId = wfMatch[1];
         const isStream = wfMatch[2] === "/stream";
         if (!wfId) {
             const q = new URL(req.url ?? "", "http://x").searchParams;
             const statusFilter = q.get("status");
             const limit = Math.min(100, Math.max(1, Number(q.get("limit") ?? 50) || 50));
+            // [1512]§二 交付件接线(1.247 留的 list 缺口):`?session=` 过滤臂 —— present 即按
+            // `originatingSessionId` 严格等值筛。语义是**筛选**非 per-id 的接受拍:无字段行(pre-core-1.210)
+            // 不属于任何会话,筛选下剔除(per-id 面的 absent 放行是访问控制防误伤,两面语义刻意不同);
+            // 空串=无行可匹配=空列表;absent = 全量,字节不变。1.250:筛下推 store 侧(core 1.368 [1516]②
+            // `listByScope.opts.session`,limit **前**应用)——1.249 的「页内筛」升「全量筛」,忙 scope 下
+            // 比 newest-limit 窗口更老的会话行不再漏。直调 store(listWorkflowRuns 是纯透传,其 opts 类型
+            // 未收录 session)。
             const sessionFilter = q.get("session");
             const sessionRuns = await deps.workflowRunStore.listByScope(scope, {
                 ...(statusFilter ? { status: statusFilter } : {}),
                 limit,
                 ...(sessionFilter !== null ? { session: sessionFilter } : {}),
             });
+            // K-2c LIST side (core 1.155 `WorkflowRunSummary` now carries name?/description?/currentPhase? from the
+            // script `meta` — flows via the pin bump): redact the LLM-authored label surfaces for parity with the DETAIL
+            // route (summarizeWorkflowDetail) + the fleet rows. The rest of the summary (status/counts/stats) rides as-is.
             const redacted = sessionRuns.map((r) => ({
                 ...r,
                 ...(r.name !== undefined ? { name: redactSecrets(r.name) } : {}),
@@ -52,18 +76,33 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { workflows: redacted });
             return;
         }
+        // per-id: owner-gate via the persisted run's scope (no existence oracle for non-owners → 404). 1.146:
+        // getWorkflowRun is scope-filtered IN CORE (returns null unless run.scope === scope) — defense-in-depth on
+        // top of our route gate; the `run.scope !== scope` below is now redundant but kept (belt-and-suspenders).
+        // The SSE branch streams ONLY after this gate, so the live stream is owner-gated too (core's subscribeWorkflow
+        // does not self-filter — this gate is its tenant boundary).
         const run = await getWorkflowRun(deps.workflowRunStore, wfId, scope);
         if (!run || run.scope !== scope) {
             sendError(res, 404, "not_found.workflow", "workflow not found");
             return;
         }
+        // [1508] 1.247 — session ACCEPT phase on the workflow per-id faces ([1493]-class sibling: these deliver
+        // conversation-derived content — step prompts/outputs/live events — but were principal-gated only, while
+        // the durable WorkflowRun carries `originatingSessionId` since core 1.210). Same soft phase + helper as
+        // the run faces (present-mismatch → 404; absent → warn-once). The LIST face is NOT gated this拍:
+        // WorkflowRunSummary lacks the field (core ask, γ-batch alignment) — its rows stay redacted summaries.
         if (!runSessionAcceptOk(req, res, { sessionId: run.originatingSessionId ?? null }, wfMatch[2] === "/journal" ? "workflow.journal" : isStream ? "workflow.stream" : "workflow.detail", "workflow not found"))
             return;
         if (wfMatch[2] === "/journal") {
+            // [1402]/[1400]④:per-agent journal 读面(云本地同构——三后端店同契约)。owner 门已过(上方 run
+            // scope 校验);投影=bounded+redact(result 是 LLM 产物,注入面纪律同 fleet 行),ordinal 序稳定。
             if (!deps.workflowJournalStore) {
                 sendError(res, 501, "capability.workflow_store_required", "workflow journal requires the journal store (SELF_ORCHESTRATION_ENABLED + a store backend)");
                 return;
             }
+            // codex R1-H2:hard bounds——limit 默认 20 cap 50(?limit=)、?offset= 游标;SQL 店走 loadPage
+            // (行数 LIMIT/OFFSET + 单行 64KiB LENGTH 门在库端,峰值 ≤50×64KiB);file/in-memory 店(单机形)
+            // 回落全量 load 后同界投影(内存峰值=店内容,记档取舍)。
             const jq = new URL(req.url ?? "", "http://x").searchParams;
             const jLimit = Math.min(50, Math.max(1, Number(jq.get("limit") ?? 20) || 20));
             const jOffset = Math.max(0, Number(jq.get("offset") ?? 0) || 0);
@@ -83,6 +122,7 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
                 const page = await js.loadPage(wfId, scope, { offset: jOffset, limit: jLimit, maxResultBytes: MAX_ROW_BYTES });
                 projected = page.map((row) => {
                     if (row.resultJson === null) {
+                        // 超单行门的条目:诚实标 truncated,不把 64KiB+ 的 TaskResult 拉进进程
                         return { callKey: row.callKey, ordinal: callKeyOrdinal(row.callKey), truncated: true, resultBytes: row.resultBytes };
                     }
                     try {
@@ -94,6 +134,9 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
                 });
             }
             else {
+                // fallback(file/in-memory,单机 TOC 形——多租户 durable 恒 SQL 店=loadPage 覆盖):load 全量的
+                // 内存/事件环成本=用户读自己盘的单机取舍(ARCHITECTURE.md 记档);投影侧与 SQL 店**同一诚实
+                // 语义**——超 64KiB 的行标 truncated/resultBytes,不做静默 2000 字投影(跨后端 API 形一致)。
                 const entries = await deps.workflowJournalStore.load(wfId, scope);
                 projected = entries
                     .sort((a, b) => callKeyOrdinal(a.callKey) - callKeyOrdinal(b.callKey))
@@ -109,35 +152,57 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             return;
         }
         if (isStream)
-            await streamWorkflowRun(req, res, wfId, scope);
+            await streamWorkflowRun(req, res, wfId, scope); // core 1.366 B-3: scope-doored live stream(异 scope=空流,与不存在同形)
         else
-            sendJson(res, 200, summarizeWorkflowDetail(run));
+            sendJson(res, 200, summarizeWorkflowDetail(run)); // SVC-4: structured drill-down (Phases panel + agent list + groups tree)
         return;
     }
     miss.fell = true;
 }
+/** 同上纪律(SVC-5 steer 段)。 */
 async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
+    // SVC-5 (design/97 CORE-5 #6): POST /v1/workflows/:id/agents/:label/steer — STEER a still-running workflow
+    // agent (`ctx.agentStream`) mid-flight. Unlike RUN steer (a whole task run), this targets ONE running agent
+    // inside a workflow, addressed by runId + label. Delivery is replica-local (the steerable handle is an
+    // in-memory bridge to the running TaskStream, like `steerableRuns`):
+    //   • the handle is live on THIS replica → `handle.steer(redacted)` injects + returns the marker → 200.
+    //   • not here but the workflow run is `running` (another replica) → 409 steering.not_running (cross-replica
+    //     live-steer is the same fast-follow seam as RUN steer — single-replica-per-worker today; honest, never
+    //     a silent drop). • terminal / no handle → 409 steering.not_running.
+    // 🔴 HANDLE-VISIBILITY SEAM: core returns a WorkflowAgentHandle ONLY from `WorkflowRunContext.agentStream`,
+    // and that host ctx structurally never enters the script runner (the LLM workflow sees the sterile
+    // `WorkflowPrimitives`, which has `agent` but not `agentStream`). The service runs workflows ONLY via core's
+    // `run_workflow` tool → primitives, so it never holds a handle to register. The registry/redaction/auth here
+    // are production-real (the populated path uses them unchanged); until core hands the deployment the handle
+    // (e.g. an onAgentStream lifecycle sink on run_workflow), the registry is genuinely empty and the route
+    // returns steering.not_running. See workflow-agent-steer.ts. Raised to core (SVC-5).
     const wfSteerMatch = req.method === "POST" ? WORKFLOW_AGENT_STEER_RE.exec(url) : null;
     if (wfSteerMatch) {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return;
+            return; // mutating + steers a running model agent
         if (!deps.workflowRunStore) {
             sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
             return;
         }
+        // Identity from gatedPrincipal (direct-door-secure single point), NEVER the spoofable header — `trusted`
+        // carries operator authority (a supervisor steering any tenant's agent), so deriving it from a header would
+        // be a privilege escalation (parity with RUN steer / preempt; HANDOFF 铁律 + core §3 inv #1).
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
+        // safeDecode (not bare decodeURIComponent): a malformed %-sequence is the CALLER's error → 400, not a 500
+        // (parity with the approvals + session-sync routes' established handling).
         const wfRunId = safeDecode(wfSteerMatch[1]);
         const label = safeDecode(wfSteerMatch[2]);
         if (wfRunId === null || label === null) {
             sendError(res, 400, "request.path_malformed", "malformed workflow path (invalid percent-encoding)");
             return;
         }
+        // Parse + validate the body BEFORE the run lookup (a bad body is the caller's error regardless of state).
         let body;
         try {
             body = (await readJson(req));
@@ -150,21 +215,43 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
             return;
         }
+        // 入参上限(见 `STEER_IN_MAX_REQUEST_CHARS` 旁注):脱敏门是**同步**的,烧的是事件循环 ⇒
+        // 一次超大 steer 卡住的是**整个副本**。**拒**而不是服务端先截 —— 先截会让引擎的
+        // `[+N chars]` 披露低报,而"诚实标记不得低报"是本仓另一条钉守着的性质。
         if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
             sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
             return;
         }
+        // trusted = explicit operator (NOT bare isOperator — its empty-list "true-for-all" would let any caller
+        // steer any tenant's agent). A normal owner steers only their own workflow.
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
-        const ownerScope = principal ?? "default";
+        const ownerScope = principal ?? "default"; // matches run_workflow scope = spec.principal ?? "default"
+        // Owner-gate via the persisted run, now scope-filtered IN CORE (1.146 getWorkflowRun(store, id, scope) →
+        // null unless run.scope === scope). For a NON-operator: a missing/other-tenant run is null → 404 (no
+        // existence oracle). An explicit OPERATOR (supervisor) may steer ANY tenant's workflow — but core's
+        // scope-filtered read can't fetch another tenant's run by the operator's own scope (→ null), so the operator
+        // is NOT gated on `wfRun` existence: its authority is the operator allowlist, and the steer target's
+        // existence+liveness is proven by the registry handle below (no handle → 409, never a wrong-tenant steer).
         const wfRun = await getWorkflowRun(deps.workflowRunStore, wfRunId, ownerScope);
         if (!trusted && !wfRun) {
             sendError(res, 404, "not_found.workflow", "workflow not found");
             return;
         }
+        // [1508] 1.247 — same session accept-phase as the read faces (a steer ACTS on the conversation's
+        // workflow). Gated on the fetched run only: the operator leg (wfRun null by scope-filtered read) keeps
+        // its registry-handle-proven authority below, and runSessionAcceptOk's operator branch covers a
+        // same-scope operator anyway.
         if (wfRun && !runSessionAcceptOk(req, res, { sessionId: wfRun.originatingSessionId ?? null }, "workflow.agent-steer", "workflow not found"))
             return;
         const sendNotRunningWf = (error) => sendError(res, 409, "steering.not_running", error);
+        // STEER-IN REDACTION GATE (SVC-5 信任门): treat the human/leader content as UNTRUSTED — redact host leaks +
+        // size-bound + fence — BEFORE it reaches the worker. core's `handle.steer` fences AGAIN inside its trusted
+        // marker framing (defense in depth). Applied regardless of `trusted`: an operator's copy-pasted steer can
+        // still leak a host path/token, and an authoritative-looking steer must not pose as system instructions.
         const redacted = redactSteerIn(body.content, label);
+        // Same-replica live path: the steerable handle is registered here → inject now, return the marker.
+        // core does not enforce label uniqueness within a run, so resolve() reports the count: >1 = two live agents
+        // share this label → the target is ambiguous, refuse (409) rather than steer an arbitrary one.
         const resolution = deps.workflowAgentRegistry?.resolve(wfRunId, label);
         if (resolution && resolution.count > 1) {
             sendError(res, 409, "steering.ambiguous_label", `${resolution.count} live agents share label '${label}' in this run — steer target is ambiguous`);
@@ -179,13 +266,18 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
             }
             catch (e) {
                 const code = e.code;
+                // The agent settled between the registry lookup and steer() → core rejects steering.not_running.
                 if (code === "steering.not_running") {
                     sendNotRunningWf("agent just finished — no longer accepting steers");
                     return;
                 }
-                throw e;
+                throw e; // unexpected → outer handler 500
             }
         }
+        // No live handle here. The workflow run is either terminal, or `running` on another replica (cross-replica
+        // live-steer = the same fast-follow seam as RUN steer; a workflow agent is in-memory steerable only on its
+        // running replica). Either way: honest 409, never a silent drop. `wfRun` may be null for an OPERATOR steering
+        // a cross-tenant run (core's scope-filtered read returned null) → a generic message (status unknowable here).
         sendNotRunningWf(!wfRun
             ? "workflow agent is not running on this replica (no live handle)"
             : wfRun.status === "running"
@@ -195,14 +287,37 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
+/** SVC-4 v1 — the STRUCTURED drill-down view of one persisted {@link WorkflowRun} (the historical detail the
+ *  Phases panel + agent list + groups tree render, parity with CC's Workflow tool). Pure projection over the
+ *  persisted run — no new source of truth, no gate input (the route already owner-gated by scope before this).
+ *  Three derived shapes:
+ *   - `phases`: each `run.phases` entry + a done/total of the agents that ran under that `phase` title (done =
+ *     terminal status). Plus an `unphased` bucket counting agents with no phase.
+ *   - `agents`: each agent flattened to `{ label, status, callKey, groupId, phase, tokens, turns, durationMs,
+ *     replayed, prompt, output }`. `prompt`/`output` are core-redacted + size-bounded; this is a HUMAN view so
+ *     they are surfaced AT REST WITHOUT a fence (a consumer that re-feeds them to an LLM must fence itself —
+ *     core's `WorkflowAgentRun` doc). `tokens`/`turns`/`costMicroUsd` come from the agent's own `stats`.
+ *   - `groups`: the nested tree rebuilt from `run.groups` (parentGroupId) — each node carries its direct agent
+ *     callKeys so a UI can hang the agent list off the tree. Empty when the script used no `ctx.workflow` nesting.
+ *  `stats` (own + nested, kept separate per core R-5) and the run-level fields pass through unchanged. */
 function summarizeWorkflowDetail(run) {
     const isDone = (s) => s === "completed" || s === "failed";
+    // MF-W queued (core 1.150): a WorkflowAgentRun's `startedAt` is now OPTIONAL — ABSENT while an agent is QUEUED
+    // (waiting on a concurrency slot) or if it was aborted/finalized before it ran. So duration is undefined unless
+    // BOTH ends are present (a queued agent has no running duration — the DoR fix). Phases still always carry startedAt.
     const durationOf = (a) => a.startedAt === undefined || a.endedAt === undefined ? undefined : a.endedAt - a.startedAt;
+    // A real persisted run always carries these arrays; default defensively so a malformed/partial stored row
+    // projects cleanly instead of 500-ing the detail route (the view is read-only — never a gate input).
     const runPhases = run.phases ?? [];
     const runAgents = run.agents ?? [];
     const runGroups = run.groups ?? [];
+    // [review] label-parity: an LLM-authored run_workflow script controls phase titles + agent labels + the per-agent
+    // phase tag (core stores them raw, unbounded), so redact them on EMISSION for the same reason as name/description
+    // (a secret the agent read could land in a label). Filter/bucket on the RAW values (below) so grouping is unchanged;
+    // redactSecrets is deterministic → a secret-bearing title and the matching agent.phase scrub to the SAME string,
+    // so the shell's phase grouping still lines up. (prompt/output are already core-redacted; model is catalog-sourced.)
     const phases = runPhases.map((p) => {
-        const inPhase = runAgents.filter((a) => a.phase === p.title);
+        const inPhase = runAgents.filter((a) => a.phase === p.title); // RAW compare — bucketing key, not emitted
         return {
             title: redactSecrets(p.title),
             status: p.status,
@@ -213,31 +328,50 @@ function summarizeWorkflowDetail(run) {
             total: inPhase.length,
         };
     });
+    // Agents with no phase title, OR a phase title that matches no registered `run.phases` entry (a stray
+    // `opts.phase` with no enclosing `phase()` block) — surfaced so the panel's counts are EXHAUSTIVE (an agent is
+    // in exactly one bucket: its registered phase, or `unphased`). Without the `titleSet` guard a stray-phase agent
+    // would fall into NO bucket (under-count). Empty-string phase is also unphased.
     const phaseTitleSet = new Set(runPhases.map((p) => p.title));
     const unphased = runAgents.filter((a) => a.phase === undefined || a.phase === "" || !phaseTitleSet.has(a.phase));
     const unphasedView = unphased.length > 0
         ? { done: unphased.filter((a) => isDone(a.status)).length, total: unphased.length }
         : undefined;
     const agents = runAgents.map((a) => ({
-        label: redactSecrets(a.label),
+        label: redactSecrets(a.label), // [review] label-parity (LLM-authored, see phases comment)
         status: a.status,
+        // MF-W (1.149 CORE-shared): the canonical display status (running|queued|done|failed|interrupted) via core's
+        // deriveAgentDisplayStatus — the SAME pure fn the shell renders, so the agent-state glyph can't drift between
+        // shells (one source of truth in core). `interrupted` = a non-terminal agent under a terminal run. The live
+        // `idle` overlay (a running agent with no recent activity) stays a SHELL wall-clock concern — since core 1.295
+        // ToolActivity carries `at`, this view exposes the raw timestamps (activity[].at + lastActivityAt below) and
+        // the shell derives idleness against its own clock (a served idleMs would drift on a historical view).
         displayStatus: deriveAgentDisplayStatus(a, run.status),
         taskStatus: a.taskStatus,
         callKey: a.callKey,
         groupId: a.groupId,
-        phase: a.phase !== undefined ? redactSecrets(a.phase) : undefined,
-        model: a.model,
+        phase: a.phase !== undefined ? redactSecrets(a.phase) : undefined, // [review] label-parity; undefined = unphased (kept)
+        model: a.model, // SVC-4 v2 / CORE-8 ①: per-agent model display label ("Opus 4.8 (1M context)" row)
         tokens: a.stats?.tokens,
         turns: a.stats?.turns,
-        toolCalls: a.toolCalls,
+        toolCalls: a.toolCalls, // SVC-4 v2 / CORE-8 ②: total tool calls ("M" in "last N of M tool calls")
+        // SVC-4 v2 / CORE-8 ③: the LAST-N tool-call beats (structural — phase/toolName/ids, no args/output). The live
+        // detail SSE (subscribeWorkflow → streamWorkflowRun) already forwards the per-callKey `agent_activity` events
+        // verbatim for a running drill-down; this is the persisted tail a historical view renders.
+        // [843]④a (core 1.295): each beat now carries `at` (epoch ms, stamped on BOTH start and end) — verbatim
+        // passthrough here, so idle derives shell-side as the FRAME GAP (end.at → next start.at), the [879] ruling.
         activity: a.activity,
+        // [843]④a convenience: the tail beat's timestamp, so a shell can grey a stale agent without walking the
+        // array. TIMESTAMP not a duration on purpose — this detail is a HISTORICAL view, so a served `idleMs`
+        // (Date.now()-derived) would drift on every re-read; the shell owns the clock. Absent for pre-1.295 runs
+        // whose beats carry no `at` (undefined → key omitted by JSON, same back-compat shape as agentFailures).
         lastActivityAt: a.activity && a.activity.length > 0 ? a.activity[a.activity.length - 1].at : undefined,
         durationMs: durationOf(a),
-        queuedAt: a.queuedAt,
-        startedAt: a.startedAt,
+        queuedAt: a.queuedAt, // MF-W queued (1.150): when the agent was ENQUEUED (always set) — a queued agent has queuedAt but no startedAt
+        startedAt: a.startedAt, // now optional (absent while queued / aborted-before-run) — displayStatus already reflects "queued"
         endedAt: a.endedAt,
         replayed: a.replayed,
-        prompt: a.prompt,
+        prompt: a.prompt, // core-redacted + bounded; human view → no fence at rest
         output: a.output,
     }));
     const byId = new Map();
@@ -253,6 +387,9 @@ function summarizeWorkflowDetail(run) {
             children: [],
         });
     }
+    // Walk up `parentGroupId` from `node`; true if the chain LOOPS (self-parent, or a multi-node cycle A→B→A)
+    // rather than terminating at a top-level (`undefined`) or dangling (absent) parent. Bounded by the seen-set, so
+    // a malformed run can neither hang nor build a circular object that `JSON.stringify` would throw 500 on.
     const inCycle = (start) => {
         const seen = new Set();
         let cur = start;
@@ -267,18 +404,27 @@ function summarizeWorkflowDetail(run) {
     const roots = [];
     for (const node of byId.values()) {
         const parent = node.parentGroupId !== undefined ? byId.get(node.parentGroupId) : undefined;
+        // Link to parent ONLY when that can't form a cycle — a self/multi-node cycle member grafts onto root, so the
+        // tree is always acyclic (JSON-safe) and no node is ever dropped.
         if (parent && parent !== node && !inCycle(node))
             parent.children.push(node);
         else
-            roots.push(node);
+            roots.push(node); // top-level, dangling parent, or cycle member → graft onto root (never dropped)
     }
     return {
         id: run.id,
         scope: run.scope,
         status: run.status,
+        // K-2c (shell §K): the workflow header label + subtitle the MF-W detail view needs — from the script's
+        // `export const meta = {name, description}` (core WorkflowRun.name/description). REDACTED for label parity with
+        // the fleet run/subagent names (an LLM-authored meta is task-controlled → could carry a secret shape). Per-phase
+        // title is already on each `phases[].title`. Omitted when absent (back-compat: older runs have neither).
         ...(run.name !== undefined ? { name: redactSecrets(run.name) } : {}),
         ...(run.description !== undefined ? { description: redactSecrets(run.description) } : {}),
         stats: run.stats,
+        // core 1.293: run-level failed-agent count (agents whose status ended "failed"), stamped at run end only
+        // when > 0. A plain number (not task-controlled text) → no redaction. Omitted when absent (back-compat:
+        // pre-1.293 runs / zero failures) — [843]④a: the detail view had no failure count to render.
         ...(run.agentFailures !== undefined ? { agentFailures: run.agentFailures } : {}),
         startedAt: run.startedAt,
         endedAt: run.endedAt,
@@ -286,6 +432,10 @@ function summarizeWorkflowDetail(run) {
         durationMs: durationOf(run),
         rev: run.rev,
         error: run.error,
+        // core 1.234: the script's RETURN VALUE — bounded + redacted AT THE SOURCE (completion-time,
+        // same egress discipline as the notifier), but re-redacted here for defence-in-depth parity with
+        // name/description (this projection's whitelist predates the field — live-dig T8 caught the omission:
+        // TaskOutput carried the result while this detail view silently dropped it). Absent on failed/pre-1.234 runs.
         ...(run.result !== undefined ? { result: redactSecrets(run.result) } : {}),
         phases,
         ...(unphasedView ? { unphased: unphasedView } : {}),
@@ -293,14 +443,25 @@ function summarizeWorkflowDetail(run) {
         groups: roots,
     };
 }
+/** SSE the live progress of a RUNNING workflow (S8). subscribeWorkflow is IN-PROCESS (replica-local): the
+ *  iterable ends when the run's channel closes at run_end, or when the client disconnects. A run with no live
+ *  channel (already finished, or on another replica) yields nothing → the stream ends immediately (the
+ *  historical view is GET /v1/workflows/:id). Owner-gating (run.scope === principal) is done by the caller;
+ *  core 1.366 (B-3) additionally doors the subscription itself on scope — a mismatched scope yields an empty
+ *  stream (same shape as not-found), so the caller passes the SAME scope it owner-gated with. */
 async function streamWorkflowRun(req, res, runId, scope) {
     sseHeaders(res);
     res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, runId })}\n\n`);
     let closed = false;
+    // subscribeWorkflow is a PUSH iterator: a parked `next()` on an idle-but-alive workflow does NOT observe a
+    // `closed` flag, so a disconnected client would leave the subscriber queue registered in core's channels and
+    // publishWorkflowEvent would buffer events for the dead peer forever (a leak). Drive the iterator explicitly so
+    // disconnect can call `it.return()` — which unwinds the parked next() AND runs core's finally to prune the queue.
     const it = subscribeWorkflow(runId, scope)[Symbol.asyncIterator]();
+    // Heartbeat so an idle proxy/mesh doesn't drop the connection (and a dead TCP peer is detected → "close").
     const hb = setInterval(() => {
         if (!res.writableEnded)
-            res.write(`event: heartbeat\ndata: {}\n\n`);
+            res.write(`event: heartbeat\ndata: {}\n\n`); // real frame (not an SSE comment) — a per-frame-parsing BFF drops comments, so downstream saw a zero-frame window; EventSource clients without a heartbeat listener ignore it (zero break)
     }, 15_000);
     if (typeof hb.unref === "function")
         hb.unref();
@@ -309,12 +470,12 @@ async function streamWorkflowRun(req, res, runId, scope) {
             return;
         closed = true;
         clearInterval(hb);
-        void it.return?.(undefined);
+        void it.return?.(undefined); // prune core's subscriber queue (workflow-observe finally) — stop buffering for a dead peer
         if (!res.writableEnded)
             res.end();
     };
     req.on("close", shutdown);
-    res.on("close", shutdown);
+    res.on("close", shutdown); // res close (peer gone) too, not just req — either side ending must prune the queue
     try {
         for (let next = await it.next(); !next.done; next = await it.next()) {
             if (closed || res.writableEnded)

package/dist/http/run-meta.d.ts

@@ -1,4 +1,13 @@
+/**
+ * design/158 A9 装配缝的一片小叶子 —— 提交路径共用的两个纯函数(run 行元数据 + cascade 配置)。
+ *
+ * 为什么单独成文件:`runMeta` 被 tasks 与 runs **两个**域模块调用,`cascadeConfig` 同理(还被测试直接引)。
+ * 挂在任一域模块上都会造出 routes/* 互相值 import 的第二条边;它们又是纯函数(只依赖入参 + redact 叶子),
+ * 所以正确归处是叶子。server.ts 转出口 `cascadeConfig` 以保住既有 import 点。
+ */
 import type { TaskSpec, CascadeConfig } from "@sema-agent/core";
+/** The denormalized run-row metadata captured at submit: correlation (jobId), credential-derived source,
+ *  and a redacted objective glance for lists. One place so the three submit paths can't drift. */
 export declare function runMeta(prepared: {
     jobId?: string;
     spec: TaskSpec;
@@ -7,5 +16,7 @@ export declare function runMeta(prepared: {
     source: string | null;
     objectivePreview: string | null;
 };
+/** Build the cascade config from the operator ladder. Default gate = `status==="completed"` (escalate
+ *  on a cheap-rung failure); cost-ceiling from the task's budget bounds the cold-rerun tax. */
 export declare function cascadeConfig(ladder: readonly string[], maxCostUsd?: number): CascadeConfig;
 //# sourceMappingURL=run-meta.d.ts.map

package/dist/http/run-meta.js

@@ -1,12 +1,18 @@
 import { redactSecrets } from "../trace/redact.js";
+/** The denormalized run-row metadata captured at submit: correlation (jobId), credential-derived source,
+ *  and a redacted objective glance for lists. One place so the three submit paths can't drift. */
 export function runMeta(prepared, source) {
     const obj = prepared.spec.objective ?? "";
     return {
         jobId: prepared.jobId ?? null,
         source,
+        // redactSecrets is best-effort (known key/token shapes only — NOT exhaustive; see redact.ts). Acceptable
+        // here: the preview rides the fleet-token-gated trace surface, not an end-user-readable channel (council #1).
         objectivePreview: obj ? redactSecrets(obj).slice(0, 120) : null,
     };
 }
+/** Build the cascade config from the operator ladder. Default gate = `status==="completed"` (escalate
+ *  on a cheap-rung failure); cost-ceiling from the task's budget bounds the cold-rerun tax. */
 export function cascadeConfig(ladder, maxCostUsd) {
     return {
         ladder: ladder.map((model) => ({ model })),

package/dist/http/send.d.ts

@@ -1,7 +1,26 @@
+/**
+ * design/158 A9 seam — response senders, extracted VERBATIM out of `http/server.ts` so the per-domain route
+ * modules under `http/routes/` can call them without a value edge back into `server.ts` (that edge would close
+ * a runtime import cycle — see `test/module-cycle-gate.test.ts`).
+ *
+ * Pure move: bodies are byte-identical to the ones that lived at `server.ts:9720/9822/9834/9843`. `server.ts`
+ * now imports them from here, so all ~500 existing `sendJson(...)` call sites are unchanged text.
+ */
 import type { ServerResponse } from "node:http";
 export declare function sseHeaders(res: ServerResponse, extra?: Record<string, string>): void;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+/** A6(design/158 lens1 §C3/lens3 §C3a): canonical error-response sender for sites that already carry a
+ *  machine `errorCode` — `errorCode` is a required positional arg (not optional-bag) so a call site
+ *  cannot regress to the "code but no errorCode" shape the error-code-key-gate forbids. Body shape is
+ *  `{ error: message, errorCode, ...extra }`; a site that used to ALSO emit a legacy `code` key keeps it
+ *  by passing `{ code: ... }` inside `extra` — this is a pure call-site migration (zero wire-contract
+ *  change), not a new response shape. Sites where the two machine-code channels genuinely disagree, or
+ *  where `error`/`errorCode` aren't cleanly separable from the rest of the body, are left on raw
+ *  `sendJson` (see the A6 migration notes for the callers still doing that on purpose). */
 export declare function sendError(res: ServerResponse, status: number, errorCode: string, message: string, extra?: Record<string, unknown>): void;
+/** B7(design/158 lens1 §C3):`HttpError` 的兜底 catch-all 站点没有自己的语义分支——`err.code` 在 42 个
+ *  throw 点里只有 3 个带。为了让「errorCode 恒在」在这些站点也成立(而不是靠豁免表放行),按**状态码**
+ *  给一个诚实的粗码:它只声明「这类拒绝」,不冒充比 throw 点更细的语义。带 `code` 的 throw 点原样优先。 */
 export declare function httpErrorCode(status: number, code?: string): string;
 export declare function msg(e: unknown): string;
 //# sourceMappingURL=send.d.ts.map

package/dist/http/send.js

@@ -10,9 +10,20 @@ export function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify(body));
 }
+/** A6(design/158 lens1 §C3/lens3 §C3a): canonical error-response sender for sites that already carry a
+ *  machine `errorCode` — `errorCode` is a required positional arg (not optional-bag) so a call site
+ *  cannot regress to the "code but no errorCode" shape the error-code-key-gate forbids. Body shape is
+ *  `{ error: message, errorCode, ...extra }`; a site that used to ALSO emit a legacy `code` key keeps it
+ *  by passing `{ code: ... }` inside `extra` — this is a pure call-site migration (zero wire-contract
+ *  change), not a new response shape. Sites where the two machine-code channels genuinely disagree, or
+ *  where `error`/`errorCode` aren't cleanly separable from the rest of the body, are left on raw
+ *  `sendJson` (see the A6 migration notes for the callers still doing that on purpose). */
 export function sendError(res, status, errorCode, message, extra) {
     sendJson(res, status, { error: message, errorCode, ...extra });
 }
+/** B7(design/158 lens1 §C3):`HttpError` 的兜底 catch-all 站点没有自己的语义分支——`err.code` 在 42 个
+ *  throw 点里只有 3 个带。为了让「errorCode 恒在」在这些站点也成立(而不是靠豁免表放行),按**状态码**
+ *  给一个诚实的粗码:它只声明「这类拒绝」,不冒充比 throw 点更细的语义。带 `code` 的 throw 点原样优先。 */
 export function httpErrorCode(status, code) {
     if (code)
         return code;