@sema-ai/core 1.275.1

package/dist/core/task-registry.js

@@ -0,0 +1,1751 @@
+import { randomBytes } from "node:crypto";
+import { Type } from "typebox";
+import { defineTool } from "./tools.js";
+import { hasBackgroundShell } from "./background-shell.js";
+import { summarizeWorkflowRun } from "./workflow-run-store.js";
+import { delimitUntrusted } from "./untrusted-text.js";
+import { boundedRedactedSummary } from "./untrusted-egress.js";
+const defaultMonitorTimers = {
+    setInterval: (fn, ms) => {
+        const h = setInterval(() => void fn(), ms);
+        h.unref?.(); // a watcher never keeps the process alive (same as the bash watcher)
+        return h;
+    },
+    clearInterval: (h) => clearInterval(h),
+    now: () => Date.now(),
+};
+const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
+const BLOCK_MAX_TIMEOUT_MS = 600_000; // CC 187 cap (timeout: max(600000))
+const BLOCK_POLL_INTERVAL_MS = 400;
+function blockDeadline(timeoutMs, now) {
+    const t = Math.min(BLOCK_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeoutMs ?? BLOCK_DEFAULT_TIMEOUT_MS)));
+    return now + t;
+}
+/** T2A-7 (2026-07-05 soak): one blocked-poll step, CLAMPED to the caller's deadline — a small timeoutMs
+ *  (e.g. 10ms) must not sleep the full 400ms step (~40× overshoot, and the overshoot window even served a
+ *  late terminal as success). `undefined` deadline keeps the plain step (callers without a deadline). */
+const sleepPollStep = (deadline, signal) => sleepMs(deadline === undefined ? BLOCK_POLL_INTERVAL_MS : Math.max(1, Math.min(BLOCK_POLL_INTERVAL_MS, deadline - Date.now())), signal);
+const sleepMs = (ms, signal) => new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    function done() {
+        clearTimeout(t);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+});
+const TASK_PREFIX = {
+    background_bash: "b",
+    workflow: "w",
+    background_agent: "a",
+    monitor: "m",
+};
+/** design/135 G2 Monitor defaults (CC schema: 200ms batch window; timeout default 5min / max 60min;
+ *  "too many events" auto-stop — threshold is a sema choice, disclosed in the stop notification). */
+export const MONITOR_BATCH_WINDOW_MS = 200;
+export const MONITOR_DEFAULT_TIMEOUT_MS = 300_000;
+export const MONITOR_MAX_TIMEOUT_MS = 3_600_000;
+export const MONITOR_MAX_BATCHES_PER_MINUTE = 50;
+/** Per-event display bound for one batch's joined lines (the notification's `result`). */
+const MONITOR_EVENT_RESULT_CAP = 2_000;
+/**
+ * CC 198 TaskOutput truncation (PARITY-SPOT-USAGE-CONSTANTS 2026-07-10 F3): limit = env
+ * `TASK_MAX_OUTPUT_LENGTH` (`oPm`, pretty.js:458009-458010; `vde` :229475 — unset/invalid → default
+ * `dFo=32000`, above `uFo=160000` → capped). Read per call (CC same), so a deployment can steer it
+ * without a restart.
+ */
+const TASK_OUTPUT_DEFAULT_CHARS = 32_000;
+const TASK_OUTPUT_MAX_CHARS = 160_000;
+// design/136 §2.3: "WorkflowStatus" joined as a live alias when the standalone poll tool was retired —
+// old model-facing calls run verbatim through TaskOutput (the legacy `runId` argument was already accepted).
+const TASK_OUTPUT_ALIASES = ["BashOutput", "AgentOutputTool", "BashOutputTool", "AgentOutput", "WorkflowStatus"];
+const TASK_STOP_ALIASES = ["KillShell", "KillBash"];
+function taskMaxOutputChars() {
+    const raw = process.env.TASK_MAX_OUTPUT_LENGTH;
+    if (!raw)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return TASK_OUTPUT_DEFAULT_CHARS;
+    return Math.min(n, TASK_OUTPUT_MAX_CHARS);
+}
+/**
+ * CC `FHl` shape (pretty.js:458012-458016) when the task has an on-disk output file: TAIL-keep (a
+ * background command's latest output is the valuable end) behind a `[Truncated. Full output: <path>]`
+ * pointer so the model can Read the full spool. Without a file (workflow/agent results), keep the
+ * legacy head+tail middle-omission — there is no path to point at, and the head often carries status.
+ */
+export function clipTaskOutput(s, fullOutputPath) {
+    const limit = taskMaxOutputChars();
+    if (s.length <= limit)
+        return s;
+    if (fullOutputPath !== undefined) {
+        const header = `[Truncated. Full output: ${fullOutputPath}]\n\n`;
+        return header + s.slice(-(limit - header.length));
+    }
+    const half = Math.floor(limit / 2);
+    const omitted = s.length - 2 * half;
+    return `${s.slice(0, half)}\n…[${s.length} chars total, ${omitted} omitted from the middle]…\n${s.slice(s.length - half)}`;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim() !== "")
+            return value.trim();
+    }
+    return undefined;
+}
+function noTask(taskId) {
+    return {
+        content: JSON.stringify({ error: "task not found" }),
+        details: { task_id: taskId, retrieval_status: "not_ready", error: "not_found" },
+    };
+}
+/** CC206-B 欠账 — TaskStop name addressing, CC `XN` verbatim (206:574955-574962): NFKC-normalize, strip
+ *  control/format chars (whitespace-class ones survive), trim, lowercase, whitespace runs → hyphens. Both
+ *  the query and the candidate label go through this, so "Fix Tests" addresses "fix tests". */
+function normalizeAgentName(s) {
+    return s
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, (t) => (/\s/.test(t) ? t : ""))
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+/** CC `gtr` (fable 复审 F1 — 亲核 @16169850: NOT plain Levenshtein but OSA / restricted
+ *  Damerau-Levenshtein, WITH the adjacent-transposition term `o[i][s]=min(o[i][s], o[i-2][s-2]+1)`
+ *  when `e[i-1]===t[s-2] && e[i-2]===t[s-1]`). The transposition matters: a typo like "tset"→"test"
+ *  is distance 1 (CC has a Did-you-mean), plain Levenshtein would call it 2. */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    const d = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            // CC's adjacent-transposition arm (OSA): `ab`↔`ba` costs 1, not 2.
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return d[m][n];
+}
+/** CC `htr` shape (206:519814-519827): candidates within Levenshtein ≤2 (length-diff ≤2 pre-filter),
+ *  best-first; the single best is the "Did you mean" suggestion (`htr(e, keys, 1)[0]`, 206:575196). */
+function closestName(query, candidates) {
+    let best;
+    let bestDist = 3;
+    const seen = new Set();
+    for (const c of candidates) {
+        if (seen.has(c))
+            continue;
+        seen.add(c);
+        if (Math.abs(c.length - query.length) > 2)
+            continue;
+        const dist = editDistance(query, c);
+        if (dist <= 2 && dist < bestDist) {
+            bestDist = dist;
+            best = c;
+        }
+    }
+    return best;
+}
+/** TaskStop not-found — CC 2.1.198 verbatim base (live probe 2026-07-08: `No task found with ID: <id>`),
+ *  CC206-B enrichment (CC `Kws` 206:575251-575258 + `ugo` 206:575227-575243): `. Did you mean: <name>?`
+ *  when a close name exists, then `. Running background agents: <id (description)>, …` over the CALLER's
+ *  running agent rows (sema's access guard already scopes the list; CC filters observers/self there).
+ *  sema has no teammate registry on this face, so CC's `Running teammates:` leg is honestly absent.
+ *  Only the STOP verb has CC probe evidence; TaskOutput keeps the JSON shape (unprobed face). */
+function noTaskForStop(taskId, enrich) {
+    let content = `No task found with ID: ${taskId}`;
+    if (enrich?.suggestion !== undefined)
+        content += `. Did you mean: ${enrich.suggestion}?`;
+    if (enrich?.runningAgents !== undefined && enrich.runningAgents.length > 0)
+        content += `. Running background agents: ${enrich.runningAgents.join(", ")}`;
+    return {
+        content,
+        details: { task_id: taskId, retrieval_status: "not_ready", error: "not_found" },
+    };
+}
+function statusFromBackground(status, exitCode) {
+    if (status === "running")
+        return "running";
+    if (status === "killed")
+        return "killed";
+    if (status === "failed")
+        return "failed";
+    if (status === "exited")
+        return exitCode === 0 ? "completed" : "failed";
+    return "failed";
+}
+/** 飞轮 [511]③ (CC parity): is this monitor a TIMEOUT-anchored watch still inside its window?
+ *  Such a handle must survive every run-scoped teardown sweep (settleKilledForOwner /
+ *  clearBackgroundForOwner / markStopSourceForOwner / the env dispose except-list): CC's
+ *  Monitor(persistent:false) lives to timeout_ms — its ONLY exits are timeout, process exit and
+ *  TaskStop; the parent run ending is not one of them (the between-turns watch is the main use case).
+ *  Reads the handle's INJECTED clock (design/87) so tests drive the window deterministically. */
+function monitorInTimeoutWindow(handle) {
+    return handle.status === "running" && handle.deadlineAt !== undefined && handle.timers.now() < handle.deadlineAt;
+}
+function canAccess(handle, access) {
+    if (handle.scope !== undefined && access.scope !== handle.scope)
+        return false;
+    if (handle.owner === undefined)
+        return true;
+    if (access.owner === handle.owner)
+        return true;
+    // design/129 (codex F1): a session-scoped handle is keyed by the SESSION — a later turn's fresh
+    // per-turn owner still reaches it through the caller's sessionId. Explicit flag only; a task-scoped
+    // handle never matches on session (no widening of the cross-caller access surface).
+    if (handle.sessionScoped && access.sessionId !== undefined && access.sessionId === handle.owner)
+        return true;
+    return false;
+}
+/** design/115 review B1: register-side fail-closed — a handle with NEITHER owner NOR scope would be
+ *  world-readable/killable through {@link canAccess} (both guards skip on undefined). The production
+ *  chain always sets both (hostTaskId + principal-or-"default"); a direct registry caller must too. */
+function assertOwnership(input, site) {
+    if (input.owner === undefined && input.scope === undefined) {
+        throw new Error(`TaskRegistry.${site}: refusing to register a task with neither owner nor scope (would be accessible to every caller)`);
+    }
+}
+function canAccessWorkflowRun(run, access) {
+    if (access.scope === undefined || run.scope !== access.scope)
+        return false;
+    // Fail-closed owner check (design/115 review S-1): when the caller has a known owner, a run WITHOUT a
+    // sourceTaskId is NOT assumed to be theirs — legacy/direct-started runs (pre-design/114 persistence, or
+    // startWorkflow called outside this tool) are denied rather than silently readable by any same-scope task.
+    // design/136 §2.3 (盲点③, accepted): the scope-only WorkflowStatus escape hatch was retired with the tool —
+    // scope+owner fail-closed is now the ONLY poll access posture (S-1 定谳); a same-scope different-task poll
+    // reads not_found, identically to an unknown id.
+    if (access.owner !== undefined && run.sourceTaskId !== access.owner)
+        return false;
+    return true;
+}
+function formatWorkflowRun(run) {
+    const summary = summarizeWorkflowRun(run);
+    const done = run.agents.filter((a) => a.status === "completed" || a.status === "failed").length;
+    const failed = run.agents.filter((a) => a.status === "failed").length;
+    return {
+        content: JSON.stringify({
+            task_id: run.id,
+            runId: run.id,
+            type: "workflow",
+            status: run.status,
+            ...(summary.name ? { name: summary.name } : {}),
+            ...(summary.currentPhase ? { currentPhase: summary.currentPhase } : {}),
+            agents: { done, total: run.agents.length, failed },
+            startedAt: run.startedAt,
+            ...(run.endedAt !== undefined ? { endedAt: run.endedAt, elapsedMs: run.endedAt - run.startedAt } : {}),
+            // 复审 r2 MAJOR: error/result are MODEL-INFLUENCEABLE (agent output / thrown message) — fence them
+            // like every other model-facing TaskOutput body (delimitUntrusted, cf. lines 606/670/779) so a
+            // crafted `</system-reminder>` in the workflow's return value can't break framing. Bounded+redacted
+            // upstream; the fence is the untrust boundary this file's own convention requires.
+            ...(run.status === "failed" && run.error ? { error: delimitUntrusted("workflow error", boundedRedactedSummary(run.error, 500)) } : {}),
+            // 黑板 [409]: a terminal poll must HAND OVER the result — "result via TaskOutput" pointed here,
+            // and this reply previously carried only agent counts (模型按指引取结果→取不到→连环刷).
+            // 黑板 [413] (NH-1): prefer resultFull — when the display bound truncated run.result, inlining the full
+            // text here lets the generic large-result offload persist it under a real read_tool_result ref (the
+            // truncated `…[+N chars]` tail previously had no retrieval path).
+            ...(run.status === "completed" && run.result !== undefined
+                ? { result: delimitUntrusted("workflow result", run.resultFull ?? run.result) }
+                : {}),
+            note: run.status === "running"
+                ? "still running — poll again shortly."
+                : run.status === "completed"
+                    ? run.result !== undefined
+                        ? "completed — `result` above is the workflow's return value."
+                        : "completed — this run predates result persistence; its result was delivered on the completion notification."
+                    : "failed — see error.",
+        }),
+        details: {
+            task_id: run.id,
+            type: "workflow",
+            status: run.status,
+            retrieval_status: "success",
+            details: summary,
+        },
+    };
+}
+export class TaskRegistry {
+    handles = new Map();
+    /** codex 终审 1.255 F1: observers of the design/129 session terminal anchor — `reapSessionBackground`
+     *  fires each hook (swallow-guarded) AFTER reaping, so session-anchored side state (the session-scoped
+     *  subagent retain ledger) releases on the SAME deployment call. Registered idempotently per consumer. */
+    sessionReapHooks = new Set();
+    legacyToTaskId = new Map();
+    mintTaskId(type) {
+        const prefix = TASK_PREFIX[type];
+        for (let i = 0; i < 32; i++) {
+            const id = `${prefix}${randomBytes(8).toString("hex")}`;
+            if (!this.handles.has(id) && !this.legacyToTaskId.has(id))
+                return id;
+        }
+        throw new Error(`TaskRegistry: exhausted task id mint retries for ${type}`);
+    }
+    registerBackgroundBash(input) {
+        assertOwnership(input, "registerBackgroundBash");
+        const id = input.id ?? this.mintTaskId("background_bash");
+        if (this.handles.has(id))
+            throw new Error(`TaskRegistry: task id already registered: ${id}`);
+        const now = input.now ?? Date.now();
+        this.handles.set(id, {
+            id,
+            type: "background_bash",
+            status: "running",
+            ...(input.sessionScoped ? { sessionScoped: true } : {}), // [636]①: explicit-flag lifetime (design/129)
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            env: input.env,
+            shellId: input.shellId,
+            ...(input.onTerminal !== undefined ? { onTerminal: input.onTerminal } : {}), // [506]③: teardown-receipt access
+        });
+        this.legacyToTaskId.set(String(input.shellId), id);
+        if (input.onTerminal)
+            this.startBashWatcher(id, input.onTerminal);
+        return id;
+    }
+    /** design/115 P3: register a background sub-agent run. The CALLER owns driving the child promise and
+     *  calling {@link settleBackgroundAgent} at the end; the registry provides the unified task_id, the
+     *  owner/scope guard, poll/stop dispatch, and terminal GC — exactly like the other two kinds. */
+    registerBackgroundAgent(input) {
+        assertOwnership(input, "registerBackgroundAgent");
+        const id = this.mintTaskId("background_agent");
+        const now = input.now ?? Date.now();
+        this.handles.set(id, {
+            id,
+            type: "background_agent",
+            status: "running",
+            ...(input.sessionScoped ? { sessionScoped: true } : {}),
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            abort: input.abort,
+        });
+        return id;
+    }
+    /** design/134 §3.3 (R3 single-source): record WHO is about to kill `id`, at the initiation site,
+     *  BEFORE the abort()/status flip — the ordering is load-bearing: the guard below refuses markers on a
+     *  non-running handle, so a caller that flips first loses its claim and attribution falls back to
+     *  "system". First-marker-wins: an earlier marker (e.g. a service-wire "user") is never overwritten.
+     *  Applies to background_agent AND background_bash (same class); workflow cancellation is out of scope. */
+    markStopSource(id, source) {
+        const handle = this.handles.get(id);
+        if (!handle || (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor"))
+            return;
+        if (handle.status !== "running" || handle.stopSource !== undefined)
+            return;
+        handle.stopSource = source;
+    }
+    /** design/134 §3.3: narrow terminal read for consumers (subagent sinkEmit/notify) — only a KILLED row
+     *  has an attribution; "system" is the defensive floor for a row that went killed without a landed
+     *  stoppedBy (e.g. legacy flips). Returns undefined for running/completed/failed/evicted rows. */
+    getStopAttribution(id) {
+        const handle = this.handles.get(id);
+        if (!handle || (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor"))
+            return undefined;
+        if (handle.status !== "killed")
+            return undefined;
+        return handle.stoppedBy ?? handle.stopSource ?? "system";
+    }
+    /** Terminal update for a background agent (the spawn-side then/catch calls this exactly once).
+     *  design/129-B: returns the WINNING terminal status — the earlier writer's when this settle is refused
+     *  (first-writer-wins), `undefined` when the handle is gone (evicted). Callers report THIS in their
+     *  notification/terminal event so the push never contradicts the registry row (a completed-notify over a
+     *  killed row — the TaskStop-then-late-resolve race — was an observable incoherence). */
+    settleBackgroundAgent(id, outcome) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return undefined;
+        // codex 1.237 复审 F3/F4 (修类): settle is FIRST-WRITER-WINS — a TaskStop already marked it killed, or a
+        // completed settle already landed; a later settle (the child promise's catch after an abort, or a
+        // rethrown notify-sink error routing the .then into .catch) must not rewrite the terminal state.
+        // design/134: this same guard protects `stoppedBy` — a refused settle never touches attribution either.
+        if (handle.status !== "running")
+            return handle.status === "completed" || handle.status === "failed" || handle.status === "killed" ? handle.status : undefined;
+        handle.status = outcome.status;
+        // design/134 §3.3 (R3): settle is only the FALLBACK filler — the initiation-site marker (stopSource)
+        // is the single source; "system" is the no-one-claimed-it floor (timeout / process teardown).
+        if (outcome.status === "killed" && handle.stoppedBy === undefined) {
+            handle.stoppedBy = outcome.stoppedBy ?? handle.stopSource ?? "system";
+        }
+        if (outcome.result !== undefined)
+            handle.result = outcome.result;
+        if (outcome.error !== undefined)
+            handle.error = outcome.error;
+        handle.updatedAt = Date.now();
+        return outcome.status;
+    }
+    /** Abort every background agent belonging to `access` (parent-task teardown — a finished parent must
+     *  not leave orphan child runs burning tokens; mirrors clearBackgroundForOwner for bash). */
+    abortBackgroundAgentsForOwner(access, opts) {
+        let aborted = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_agent" || handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            // design/129 (codex F2): lifetime is filtered by the EXPLICIT flag, both directions — the parent
+            // teardown skips session-scoped children; the session terminal reaps ONLY them (a task-scoped entry
+            // under the same key value must not be collaterally killed).
+            if (opts?.skipSessionScoped && handle.sessionScoped)
+                continue;
+            if (opts?.sessionScopedOnly && !handle.sessionScoped)
+                continue;
+            // design/134 §3.3: parent-teardown reap = the PARENT stopped it (CC semantics) — mark before abort.
+            this.markStopSource(handle.id, "parent");
+            handle.abort.abort();
+            aborted++;
+        }
+        return aborted;
+    }
+    /** service 黑板 [418]①②: bulk stop-source attribution for one owner — the registry-side primitive that
+     *  replaces the service's `list()+markStopSource` per-row loop, which had TWO holes: ① `list()` didn't
+     *  expose `sessionScoped`, so on the resume leg (canonical taskId==sessionId, rebuilt taskConfig without
+     *  spec.taskId) task-scoped and session-scoped children share the same owner KEY VALUE and can't be told
+     *  apart; ② `list()`'s 500-row display cap silently skipped rows on >500-children runs.
+     *  Same owner-filter semantics as {@link abortBackgroundAgentsForOwner}: {@link canAccess} + the EXPLICIT
+     *  `sessionScoped` flag (design/129 — never inferred from key values), over a DIRECT handle-map walk
+     *  (no list() cap in the path). Covers every markable kind ({@link markStopSource}'s own set:
+     *  background_agent / background_bash / monitor); each row is delegated to `markStopSource`, so the
+     *  running-only + first-marker-wins guards hold unchanged — an existing claim is never overwritten.
+     *  Returns how many rows NEWLY took the marker (already-marked / non-running rows don't count). */
+    markStopSourceForOwner(access, source, opts) {
+        let marked = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_agent" && handle.type !== "background_bash" && handle.type !== "monitor")
+                continue;
+            if (handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            // design/129 (codex F2, same discipline as abortBackgroundAgentsForOwner): lifetime is filtered by
+            // the EXPLICIT flag — the [418]① resume-leg key collision is exactly why value inference is banned.
+            if (opts?.skipSessionScoped && handle.sessionScoped)
+                continue;
+            // 飞轮 [511]③: an in-window non-persistent monitor is not being killed by this run-level stop —
+            // it survives the teardown (see settleKilledForOwner). Marking it here would poison its LATER
+            // legitimate exit's attribution (first-marker-wins: a stray "user" marker would relabel the
+            // eventual timeout terminal as stoppedBy:"user").
+            if (handle.type === "monitor" && monitorInTimeoutWindow(handle))
+                continue;
+            const before = handle.stopSource;
+            this.markStopSource(handle.id, source);
+            if (before === undefined && handle.stopSource !== undefined)
+                marked++;
+        }
+        return marked;
+    }
+    /** 飞轮 [506]③ — the run-teardown KILLED-receipt producer for the SHELL lanes (background_bash + per-run
+     *  monitor). The runner teardown disposes the processes (`disposeBackgroundShells`) and evicts the rows
+     *  (`clearBackgroundForOwner`) — after which NO producer can ever mint the killed notification: the bash
+     *  watcher's next poll sees a vanished shell ("nothing to notify about") or its evicted handle and just
+     *  stops. So a mid-turn abort (or a normal turn end) silently swallowed children the model had been
+     *  promised notifications for ("You will be notified when it completes — do not poll"). The AGENT lane
+     *  already has its producer (the child promise's settle → notify, [496]④); this is the same receipt for
+     *  the shell lanes — call it BEFORE dispose/evict so the sink chain (onTerminal/onEvent → the run's
+     *  notification wrapper, whose lane is already down at teardown) PARKS the receipt on the per-session
+     *  pending store and the session's next run drains it (the [492]② lane, one shape for all producers).
+     *
+     *  Attribution (design/134 §3.3): `markStopSource(source)` first — first-marker-wins, so a deployment's
+     *  earlier explicit mark (e.g. a service-wire "user" on abort) is never overwritten; `stoppedBy` then
+     *  lands from the marker. Rows without a sink still settle (registry truth), they just have no receipt
+     *  to send. Session-scoped rows are skipped under `skipSessionScoped` (they outlive the turn; their
+     *  terminal anchor is `reapSessionBackground`). KNOWN small race, recorded: a child that exited within
+     *  the last watcher-poll interval (~1s) but whose exit the watcher hasn't observed yet still reads
+     *  "running" here and is settled `killed` — the receipt is at worst one status coarser, never silent.
+     *
+     *  codex 1.257.3 review (HIGH): the settle EXECUTES the kill itself (await `killBackground`, Result-typed)
+     *  before minting the receipt — previously the receipt claimed "killed" while the actual kill was left to
+     *  the later `disposeBackgroundShells`, whose failure was swallowed (process alive + registry cleared =
+     *  the receipt lied). A failed kill now mints an HONEST receipt naming the failure (the env dispose is
+     *  still the idempotent backstop). Returns how many rows were settled. */
+    async settleKilledForOwner(access, opts) {
+        const source = opts?.source ?? "parent";
+        const clause = (by) => by === "user" ? "stopped by user" : by === "parent" ? "its parent run ended" : `stopped by ${by}`;
+        let settled = 0;
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_bash" && handle.type !== "monitor")
+                continue;
+            if (handle.status !== "running" || !canAccess(handle, access))
+                continue;
+            // design/129 (codex F2 discipline): lifetime filtered by the EXPLICIT flag, never inferred from keys.
+            // [636]① envDying exception (same rationale as the opus 1.258 monitor arm below): a session-resident
+            // BASH shell on a per-task ISOLATED env dies with the env destroy right after this sweep — exempting
+            // it would leave a running row whose process is already gone (the watcher polls a vanished shell and
+            // goes silent: no receipt, ever). Settle it NOW with the accurate killed receipt instead.
+            if (opts?.skipSessionScoped && handle.sessionScoped && !(opts?.envDying === true && handle.type === "background_bash"))
+                continue;
+            // design/128 T1-1 (TB 2026-07-08 翻红回归,3 题对抗复核确认:configure-git-webserver / hf-model-inference /
+            // kv-store-grpc): a retain-declared env's background children OUTLIVE the run — the deliver-a-living-service
+            // contract. This settle is an AUTO sweep (run teardown), and its `killBackground` is the explicit-kill path
+            // that BYPASSES the dispose-side retain gate, so 1.257.3's kill-before-receipt silently killed every TB
+            // long-lived daemon 0.2s before the verifier probed it (1.249 left them orphaned → PASS; CC live evidence:
+            // the stable set's CC runs pass these daemon tasks, so CC's bg shells survive the agent run too). Skip
+            // ENTIRELY: no kill, no killed-receipt (nothing died — a receipt would lie), row left for the teardown's
+            // clearBackgroundForOwner evict (which clears the watcher and leaves the process alive, the 1.249 shape).
+            // Explicit TaskStop and the per-shell timeout hard-wall are untouched (host-alive semantics, T1-1).
+            // codex 1.258.1 review (MED): NOT when the owned env is about to be destroyed — retain on a dying env
+            // is illusory (destroy reaps the container and the daemon with it, receipt-less). Same rationale as the
+            // opus envDying monitor arm below: settle NOW with the accurate killed receipt instead.
+            if (handle.env.backgroundCapabilities.retainBackgroundProcesses === true && !opts?.envDying)
+                continue;
+            // 飞轮 [511]③ (CC parity): a non-persistent monitor is TIMEOUT-anchored, not run-anchored — the
+            // run teardown is NOT one of its exits (timeout / process exit / TaskStop are). An in-window watch
+            // is left running: its process rides the teardown dispose's except-list, its watcher keeps ticking
+            // on the registry-scoped timers, and its between-turns events/terminal park on the [492]② pending
+            // lane. Only a past-deadline straggler (watcher backlog) still settles here; the bash arm below is
+            // untouched — bash children remain run-scoped and settle killed-with-receipt exactly as before.
+            //
+            // opus 1.258 review (MED): the exemption only holds when the ENV survives the run. On a per-task
+            // owned env the teardown destroys the env right after this sweep (`teardownOwnedEnv`) — the watch
+            // process dies with it and the watcher's next tick would mint a MISLEADING "failed: lost its
+            // process" terminal. `envDying:true` (caller-derived from the teardownOwnedEnv gate) opts the
+            // in-window monitor back INTO the settle: it gets the accurate killed/parent receipt instead.
+            if (handle.type === "monitor" && monitorInTimeoutWindow(handle) && !opts?.envDying)
+                continue;
+            this.markStopSource(handle.id, source);
+            if (handle.type === "background_bash") {
+                if (handle.watcher !== undefined) {
+                    clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                // Kill FIRST (Result-typed, never throws); `not_found` = already dead (exited inside the watcher
+                // window) — that still reads killed-at-teardown here, one status coarser as documented above.
+                const kill = await handle.env.killBackground(handle.shellId);
+                const killFailed = !kill.ok && kill.error.code !== "not_found";
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? source;
+                handle.updatedAt = Date.now();
+                const tail = handle.spool !== undefined ? handle.spool.stdout.slice(-2_000) : "";
+                try {
+                    handle.onTerminal?.({
+                        task_id: handle.id,
+                        task_type: "background_bash",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        status: "killed",
+                        stoppedBy: handle.stoppedBy,
+                        summary: `${(handle.description ?? "background command").slice(0, 200)} — killed before completion (${clause(handle.stoppedBy)})${killFailed ? ` — kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries` : ""}`,
+                        ...(tail.length > 0 ? { result: tail } : {}),
+                    });
+                }
+                catch {
+                    /* a notification sink must never fault the teardown */
+                }
+            }
+            else {
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                // Same kill-before-receipt discipline as the bash arm (codex HIGH).
+                const kill = await handle.env.killBackground(handle.shellId);
+                const killFailed = !kill.ok && kill.error.code !== "not_found";
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? source;
+                handle.updatedAt = Date.now();
+                // Terminal flush parity with the watcher: a pending newline-less line rides the receipt.
+                const lastLines = handle.lineBuf !== "" ? [handle.lineBuf] : [];
+                handle.lineBuf = "";
+                try {
+                    handle.onEvent?.({
+                        task_id: handle.id,
+                        task_type: "monitor",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        status: "killed",
+                        stoppedBy: handle.stoppedBy,
+                        summary: `${(handle.description ?? "monitor").slice(0, 200)} — killed before completion (${clause(handle.stoppedBy)}); watch ended.${killFailed ? ` Kill attempt reported ${kill.ok ? "" : kill.error.code}: the process may still be terminating; the environment teardown retries.` : ""}`,
+                        ...(lastLines.length > 0 ? { lines: lastLines, result: lastLines.join("\n") } : {}),
+                    });
+                }
+                catch {
+                    /* same: sink failures never fault the teardown */
+                }
+            }
+            settled++;
+        }
+        return settled;
+    }
+    /** design/129: the session-scoped children's TERMINAL anchor — call from your session release/sweep.
+     *  Aborts every running session-scoped background child registered under `sessionId` and settles it
+     *  `killed` (the child's own catch/then would also classify the abort as killed; this makes the registry
+     *  state immediate rather than waiting on the child's promise). Idempotent. */
+    reapSessionBackground(sessionId, scope) {
+        const access = { owner: sessionId, ...(scope !== undefined ? { scope } : {}) };
+        let reaped = 0;
+        for (const handle of this.handles.values()) {
+            // design/135 G2: a session-scoped (persistent) MONITOR is reaped at the same terminal anchor —
+            // tear down the watcher first (no post-reap terminal notification), then best-effort kill.
+            if (handle.type === "monitor" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
+                this.markStopSource(handle.id, "system");
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                // design/128 T1-1 (same gate as settleKilledForOwner): session release is an AUTO sweep too — on a
+                // retain-declared env the watched process is left alive (only the WATCH ends here); the handle still
+                // settles because the session, its watcher and its notification lane are gone either way.
+                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
+                    void handle.env.killBackground(handle.shellId).catch(() => undefined);
+                }
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                reaped++;
+                continue;
+            }
+            // 黑板 [636]① — the session-resident BASH shell's terminal anchor (mirrors the monitor arm above):
+            // stop the watcher first (no post-reap terminal notification — the session and its lanes are gone),
+            // then best-effort kill behind the same design/128 T1-1 retain gate (a retain-declared env's
+            // delivered daemons stay alive; only the registry row settles).
+            if (handle.type === "background_bash" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
+                this.markStopSource(handle.id, "system");
+                if (handle.watcher !== undefined) {
+                    clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
+                    void handle.env.killBackground(handle.shellId).catch(() => undefined);
+                }
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                reaped++;
+                continue;
+            }
+            if (handle.type !== "background_agent" || handle.status !== "running" || !handle.sessionScoped)
+                continue;
+            if (!canAccess(handle, access))
+                continue;
+            // design/134 §3.3: session release is nobody's explicit stop — "system" (marked BEFORE the abort).
+            this.markStopSource(handle.id, "system");
+            handle.abort.abort();
+            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            reaped++;
+        }
+        // codex 终审 1.255 F1: fire the session-reap hooks (swallow-guarded) — the session-scoped subagent
+        // retain ledger's anchor ②. Fired even when nothing was running: idle-but-retained rows must release
+        // on session terminal too (a settled child holds a pinned session until this call or its TTL).
+        for (const hook of this.sessionReapHooks) {
+            try {
+                hook(sessionId, scope);
+            }
+            catch {
+                /* an observer bug must not fault the reap */
+            }
+        }
+        return reaped;
+    }
+    /** 黑板 [651] (reap 责任裁定 B) — the FULL-registry reap for the ENGINE's own exit path. TOC form:
+     *  the engine process IS the session terminal (the shell has no line to call — [650] live evidence:
+     *  detached bg children reparent to PID 1 and outlive the engine), so the engine's SIGHUP/SIGTERM/
+     *  normal-exit terminus calls THIS. Enumerates every running session-scoped row's (owner, scope)
+     *  pair (owner = the sessionId by design/129 discipline) and runs the per-session reap on each —
+     *  retain-declared envs keep their processes (rows settle only), exactly like the per-session anchor.
+     *  Timing discipline ([651]①): call at the hardShutdown TERMINUS, never at drain start — an
+     *  in-flight turn may still be TaskOutput-following a bg process. Returns total rows reaped. */
+    reapAllSessionBackground() {
+        const pairs = new Map();
+        for (const handle of this.handles.values()) {
+            if (handle.status !== "running")
+                continue;
+            if (!handle.sessionScoped || handle.owner === undefined)
+                continue;
+            const key = JSON.stringify([handle.owner, handle.scope ?? null]);
+            if (!pairs.has(key))
+                pairs.set(key, { owner: handle.owner, ...(handle.scope !== undefined ? { scope: handle.scope } : {}) });
+        }
+        let reaped = 0;
+        for (const p of pairs.values())
+            reaped += this.reapSessionBackground(p.owner, p.scope);
+        return reaped;
+    }
+    /** codex 终审 1.255 F1 — subscribe to `reapSessionBackground` (the design/129 session terminal anchor).
+     *  Returns an unsubscribe. Hooks are best-effort observers; a throwing hook is swallowed. */
+    onSessionReap(hook) {
+        this.sessionReapHooks.add(hook);
+        return () => void this.sessionReapHooks.delete(hook);
+    }
+    /** G2b watcher (design/116 §7): 1s poll loop that spools increments (rolling bound) and fires ONE
+     *  completion notification at the terminal state. `unref()`d — a watcher never keeps the process alive.
+     *  Stops itself on terminal, on a vanished shell (env disposed), or when the handle is evicted. */
+    startBashWatcher(id, onTerminal) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_bash")
+            return;
+        handle.spool = { stdout: "", stderr: "", rolledChars: 0 };
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS; // 2× the env-cap (not the default): a later poll may raise TASK_MAX_OUTPUT_LENGTH, and rolled-off chars are unrecoverable
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            handle.spool.rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let ticking = false; // re-entrancy guard: a slow env poll must not stack ticks
+        const stop = () => {
+            if (handle.watcher !== undefined) {
+                clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+        };
+        const tick = async () => {
+            if (ticking)
+                return;
+            ticking = true;
+            try {
+                if (this.handles.get(id) !== handle)
+                    return stop(); // evicted (gc / clearBackgroundForOwner)
+                if (handle.status !== "running")
+                    return stop(); // already terminal (TaskStop landed) — never resurrect
+                const r = await handle.env.pollBackground(handle.shellId);
+                // codex 1.254 F1 (same class as the monitor watcher): the poll await is a suspension point —
+                // stopBackgroundBash may have landed "killed" meanwhile; a stale in-flight tick must not overwrite
+                // it back to "running" (the interval is already cleared, so the resurrected status would stick forever).
+                if (this.handles.get(id) !== handle || handle.status !== "running")
+                    return stop();
+                if (!r.ok)
+                    return stop(); // vanished (env disposed / killed elsewhere) — nothing to notify about
+                const spool = handle.spool;
+                spool.stdout = roll(spool.stdout + r.value.stdout);
+                spool.stderr = roll(spool.stderr + r.value.stderr);
+                handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+                // design/134: the env reported killed (TaskStop marked "parent" before killBackground; anything
+                // else — killed out-of-band — has no claimant and lands "system").
+                if (handle.status === "killed" && handle.stoppedBy === undefined)
+                    handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                if (r.value.status !== "running") {
+                    spool.exitCode = r.value.exitCode;
+                    stop();
+                    const tail = spool.stdout.slice(-2_000);
+                    onTerminal({
+                        task_id: id,
+                        task_type: "background_bash",
+                        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                        status: handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed",
+                        ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                        // CC 2.1.198 live verbatim on the happy path (reminders live-capture §6:
+                        // `Background command "<desc>" completed (exit code N)`); non-exit statuses keep the
+                        // sema wording (no CC sample for those faces).
+                        summary: r.value.status === "exited"
+                            ? `Background command "${(handle.description ?? "background command").slice(0, 200)}" completed (exit code ${r.value.exitCode})`
+                            : `${(handle.description ?? "background command").slice(0, 200)} — ${r.value.status}`,
+                        ...(tail.length > 0 ? { result: tail } : {}),
+                    });
+                }
+            }
+            catch {
+                stop(); // a throwing env adapter must not leave a zombie interval
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        handle.watcher = setInterval(() => void tick(), 1_000);
+        handle.watcher.unref?.();
+    }
+    /** design/135 G2: register a spawned background process as a MONITOR — the watcher polls at the batch
+     *  window (200ms), turns each completed stdout line into an event, batches lines within one tick into
+     *  ONE notification, enforces the non-persistent timeout, auto-stops an event storm, and fires exactly
+     *  one terminal notification (exit code / timeout / auto-stop / env-side kill). */
+    /** 飞轮 [492]② — the shells a run teardown must LEAVE ALIVE: running SESSION-scoped monitors of this
+     *  session on THIS env (their whole point is outliving the turn; the env-wide dispose would otherwise
+     *  orphan the watch — handle alive, process dead, watcher reporting a bogus env-death terminal). Env
+     *  identity is part of the match so a shared registry never exempts another env's ids. */
+    sessionResidentShellIds(sessionId, env) {
+        const out = [];
+        for (const handle of this.handles.values()) {
+            // [636]①: session-resident BASH shells ride the same dispose except-list as persistent monitors.
+            if ((handle.type === "monitor" || handle.type === "background_bash") && handle.status === "running" && handle.sessionScoped === true && handle.owner === sessionId && handle.env === env) {
+                out.push(handle.shellId);
+            }
+        }
+        return out;
+    }
+    /** 飞轮 [511]③ — the OTHER shells a run teardown must leave alive: NON-persistent monitors still inside
+     *  their timeout window, on THIS env. CC semantics: Monitor(persistent:false) lives to timeout_ms — the
+     *  parent run ending is not an exit (timeout / process exit / TaskStop are). Deliberately NO owner
+     *  filter: on a shared env an earlier run's (or another session's) in-window watch must survive this
+     *  run's env-wide dispose too. Env identity stays part of the match, same as
+     *  {@link sessionResidentShellIds} (a shared registry never exempts another env's ids). */
+    timeoutResidentShellIds(env) {
+        const out = [];
+        for (const handle of this.handles.values()) {
+            if (handle.type === "monitor" && handle.env === env && monitorInTimeoutWindow(handle)) {
+                out.push(handle.shellId);
+            }
+        }
+        return out;
+    }
+    registerMonitor(input) {
+        assertOwnership(input, "registerMonitor");
+        const id = this.mintTaskId("monitor");
+        const now = input.now ?? Date.now();
+        const timers = input.timers ?? defaultMonitorTimers;
+        const persistent = input.persistent === true;
+        const timeoutMs = persistent
+            ? undefined
+            : Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(input.timeoutMs ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+        const handle = {
+            id,
+            type: "monitor",
+            status: "running",
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            ...(persistent ? { persistent: true } : {}),
+            ...(input.sessionScoped ? { sessionScoped: true } : {}),
+            createdAt: now,
+            updatedAt: now,
+            env: input.env,
+            shellId: input.shellId,
+            spool: { stdout: "", stderr: "", rolledChars: 0 },
+            lineBuf: "",
+            seq: 0,
+            batchTimes: [],
+            batchWindowMs: Math.max(1, Math.floor(input.batchWindowMs ?? MONITOR_BATCH_WINDOW_MS)),
+            maxBatchesPerMinute: Math.max(1, Math.floor(input.maxBatchesPerMinute ?? MONITOR_MAX_BATCHES_PER_MINUTE)),
+            ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt: timers.now() + timeoutMs } : {}),
+            timers,
+            ...(input.onEvent !== undefined ? { onEvent: input.onEvent } : {}),
+        };
+        this.handles.set(id, handle);
+        this.startMonitorWatcher(id);
+        return id;
+    }
+    /** The monitor watcher tick loop. Same zombie-proofing discipline as {@link startBashWatcher}
+     *  (re-entrancy guard / stop on eviction / stop on vanished shell / stop on a throwing adapter),
+     *  plus the three monitor-only exits: watcher-enforced timeout, event-storm auto-stop, and the
+     *  line→batched-event emission path. All time reads go through the INJECTED clock (design/87). */
+    startMonitorWatcher(id) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "monitor")
+            return;
+        const timers = handle.timers;
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS; // 2× the env-cap (not the default): a later poll may raise TASK_MAX_OUTPUT_LENGTH, and rolled-off chars are unrecoverable
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            handle.spool.rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let ticking = false;
+        const stop = () => {
+            if (handle.watcher !== undefined) {
+                timers.clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+        };
+        const emit = (n) => {
+            try {
+                handle.onEvent?.(n);
+            }
+            catch {
+                /* a notification sink must never break the watcher */
+            }
+        };
+        const clipEvent = (s) => s.length <= MONITOR_EVENT_RESULT_CAP ? s : `${s.slice(0, MONITOR_EVENT_RESULT_CAP)}\n…[+${s.length - MONITOR_EVENT_RESULT_CAP} chars truncated]`;
+        /** Drain lineBuf's remainder into the final batch (a terminal flush must not drop a last
+         *  newline-less line — CC reports it with the exit). */
+        const pendingFinalLines = (lines) => {
+            const out = handle.lineBuf !== "" ? [...lines, handle.lineBuf] : lines;
+            handle.lineBuf = "";
+            return out;
+        };
+        const terminal = (status, summary, finalLines) => {
+            handle.updatedAt = Date.now();
+            stop();
+            emit({
+                task_id: id,
+                task_type: "monitor",
+                ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                status,
+                ...(status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${summary}`,
+                ...(finalLines.length > 0 ? { lines: finalLines, result: clipEvent(finalLines.join("\n")) } : {}),
+            });
+        };
+        const tick = async () => {
+            if (ticking)
+                return;
+            ticking = true;
+            try {
+                if (this.handles.get(id) !== handle)
+                    return stop(); // evicted (gc / clearBackgroundForOwner)
+                if (handle.status !== "running")
+                    return stop(); // already terminal (TaskStop/reap landed) — never resurrect
+                const r = await handle.env.pollBackground(handle.shellId);
+                // codex 1.254 F1: the await above is a suspension point — TaskStop/stopMonitor/reapSessionBackground
+                // may have landed a terminal status meanwhile (they tear the interval down, but THIS tick is already
+                // in flight). First-writer-wins, same gate as settleBackgroundAgent: a stale tick must not resurrect
+                // a stopped handle (status/updatedAt writes) nor emit events/terminal over the landed state.
+                if (this.handles.get(id) !== handle || handle.status !== "running")
+                    return stop();
+                if (!r.ok) {
+                    // codex 1.254 F2: an env-side vanish (env disposed / process killed out of band) previously just
+                    // stopped the watcher SILENTLY, leaving the handle "running" forever (and its subscriber waiting
+                    // for a terminal notification that would never come). Land failed + exactly one terminal notify
+                    // (statusFromBackground maps an unknown/vanished state to failed — same family as the bash lane).
+                    handle.status = "failed";
+                    return terminal("failed", `monitor lost its process (${r.error.message}); watch ended.`, pendingFinalLines([]));
+                }
+                const spool = handle.spool;
+                spool.stdout = roll(spool.stdout + r.value.stdout);
+                spool.stderr = roll(spool.stderr + r.value.stderr); // ⑤ stderr: spooled (TaskOutput-readable), never an event
+                // Complete lines only: the partial tail waits in lineBuf for its newline (or the terminal flush).
+                handle.lineBuf += r.value.stdout;
+                const parts = handle.lineBuf.split(/\r?\n/);
+                handle.lineBuf = parts.pop() ?? "";
+                const lines = parts.filter((l) => l !== "");
+                handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+                if (r.value.status !== "running") {
+                    // ③/env-side terminal: exit (code reported), env hard-wall kill, or crash.
+                    spool.exitCode = r.value.exitCode;
+                    if (handle.status === "killed" && handle.stoppedBy === undefined)
+                        handle.stoppedBy = handle.stopSource ?? "system";
+                    const label = r.value.status === "exited"
+                        ? `exited(code ${r.value.exitCode}); watch ended.`
+                        : `${r.value.status}; watch ended.`;
+                    return terminal(handle.status === "completed" ? "completed" : handle.status === "killed" ? "killed" : "failed", label, pendingFinalLines(lines));
+                }
+                const now = timers.now();
+                // ④ watcher-enforced timeout (non-persistent only; the env hard wall is a backstop behind this).
+                if (handle.deadlineAt !== undefined && now >= handle.deadlineAt) {
+                    this.markStopSource(id, "timeout"); // open-enum StopSource (design/134): a timeout is nobody's explicit stop
+                    const k = await handle.env.killBackground(handle.shellId); // Result-typed, never throws
+                    if (this.handles.get(id) !== handle || handle.status !== "running")
+                        return stop(); // F1 gate (kill await = suspension point)
+                    // codex 1.254 F3: an ignored kill failure landed an HONESTY-BREAKING "killed" over a process that
+                    // may still be running. Only a successful kill (or not_found = already gone) earns "killed";
+                    // otherwise land failed with the honest caveat.
+                    if (!k.ok && k.error.code !== "not_found") {
+                        handle.status = "failed";
+                        return terminal("failed", `timed out after ${handle.timeoutMs}ms, but the kill failed (${k.error.message}); the process may still be running. Watch ended.`, pendingFinalLines(lines));
+                    }
+                    handle.status = "killed";
+                    handle.stoppedBy = handle.stopSource ?? "timeout";
+                    return terminal("killed", `timed out after ${handle.timeoutMs}ms; the process was killed and the watch ended.`, pendingFinalLines(lines));
+                }
+                if (lines.length === 0) {
+                    if (r.value.stdout.length > 0 || r.value.stderr.length > 0)
+                        handle.updatedAt = Date.now();
+                    return;
+                }
+                // ⑥ event-storm auto-stop: a monitor spamming batches would drown the model's turn boundaries.
+                const cutoff = now - 60_000;
+                handle.batchTimes = handle.batchTimes.filter((t) => t > cutoff);
+                handle.batchTimes.push(now);
+                if (handle.batchTimes.length > handle.maxBatchesPerMinute) {
+                    this.markStopSource(id, "system");
+                    const k = await handle.env.killBackground(handle.shellId);
+                    if (this.handles.get(id) !== handle || handle.status !== "running")
+                        return stop(); // F1 gate (kill await = suspension point)
+                    if (!k.ok && k.error.code !== "not_found") {
+                        // codex 1.254 F3 (same class as the timeout branch): no honest kill ⇒ no "killed" claim.
+                        handle.status = "failed";
+                        return terminal("failed", `auto-stop triggered (more than ${handle.maxBatchesPerMinute} notification batches within a minute), but the kill failed (${k.error.message}); the process may still be running. Watch ended.`, pendingFinalLines(lines));
+                    }
+                    handle.status = "killed";
+                    handle.stoppedBy = handle.stopSource ?? "system";
+                    return terminal("killed", `auto-stopped: it produced too many events (more than ${handle.maxBatchesPerMinute} notification batches within a minute). ` +
+                        `The process was killed; its full output remains readable via TaskOutput. Restart it with a quieter command (filter its output) if you still need the watch.`, pendingFinalLines(lines));
+                }
+                // ①/② the event path: every stdout line is an event; lines within one 200ms tick batch into ONE notification.
+                handle.seq += 1;
+                handle.updatedAt = Date.now();
+                emit({
+                    task_id: id,
+                    task_type: "monitor",
+                    ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+                    status: "event",
+                    seq: handle.seq,
+                    lines,
+                    summary: `${(handle.description ?? "monitor").slice(0, 200)} — ${lines.length} new output line(s)`,
+                    result: clipEvent(lines.join("\n")),
+                });
+            }
+            catch {
+                stop(); // a throwing env adapter must not leave a zombie interval
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        handle.watcher = timers.setInterval(tick, handle.batchWindowMs);
+    }
+    registerWorkflow(input) {
+        assertOwnership(input, "registerWorkflow");
+        const id = input.runId;
+        if (this.handles.has(id))
+            throw new Error(`TaskRegistry: task id already registered: ${id}`);
+        const now = input.now ?? Date.now();
+        const handle = {
+            id,
+            type: "workflow",
+            status: "running",
+            ...(input.description !== undefined ? { description: input.description } : {}),
+            ...(input.owner !== undefined ? { owner: input.owner } : {}),
+            ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+            createdAt: now,
+            updatedAt: now,
+            runId: id,
+            handle: input.handle,
+            ...(input.store !== undefined ? { store: input.store } : {}),
+            ...(input.onServedTerminal !== undefined ? { onServedTerminal: input.onServedTerminal } : {}),
+        };
+        this.handles.set(id, handle);
+        void input.handle.done.then((res) => {
+            handle.status = "completed";
+            // 复审 r2 MAJOR: capture the bounded return value so a store-less terminal poll carries it (ackServed
+            // then correctly acks a poll that DID hand over the result).
+            // 黑板 [413] (NH-1): prefer the FULL text when the display bound truncated it — the poll reply inlines
+            // it and the generic large-result offload mints a real read_tool_result ref (the truncated tail
+            // previously dead-ended with no retrieval path).
+            const run = res?.run;
+            const r = run?.resultFull ?? run?.result;
+            if (typeof r === "string")
+                handle.result = r;
+            handle.updatedAt = Date.now();
+        }, (err) => {
+            if (handle.status !== "cancelled")
+                handle.status = "failed";
+            // T2A-8 (2026-07-05 soak): keep the failure reason — a store-less terminal poll previously reported
+            // only "failed" with the rejection dropped here, leaving the model no self-correction signal.
+            handle.error = boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500);
+            handle.updatedAt = Date.now();
+        });
+        return id;
+    }
+    async pollTask(id, access, opts = {}) {
+        const taskId = id.trim();
+        const deadline = opts.block ? blockDeadline(opts.timeoutMs, Date.now()) : undefined;
+        const handle = this.resolveInternal(taskId, access);
+        if (handle) {
+            if (handle.type === "background_bash")
+                return this.pollBackgroundBash(handle, taskId, opts.filter, deadline, opts.signal);
+            if (handle.type === "background_agent")
+                return this.pollBackgroundAgent(handle, deadline, opts.signal);
+            if (handle.type === "monitor")
+                return this.pollMonitor(handle, opts.filter, deadline, opts.signal);
+            return this.pollWorkflow(handle, access, deadline, opts.signal);
+        }
+        if (opts.workflowStore) {
+            // Blocked poll over the durable store: re-read until terminal or deadline (no cursor to lose here).
+            for (;;) {
+                const run = await opts.workflowStore.get(taskId);
+                if (!run || !canAccessWorkflowRun(run, access))
+                    break;
+                if (run.status !== "running" || deadline === undefined || Date.now() >= deadline || opts.signal?.aborted) {
+                    const out = formatWorkflowRun(run);
+                    if (run.status === "running" && deadline !== undefined && Date.now() >= deadline)
+                        out.details.retrieval_status = "timeout"; // S5
+                    return out;
+                }
+                await sleepPollStep(deadline, opts.signal);
+            }
+        }
+        return noTask(taskId);
+    }
+    async stopTask(id, access, opts = {}) {
+        const taskId = id.trim();
+        const handle = this.resolveInternal(taskId, access);
+        if (handle) {
+            if (handle.type === "background_bash")
+                return this.stopBackgroundBash(handle);
+            if (handle.type === "background_agent")
+                return this.stopBackgroundAgent(handle);
+            if (handle.type === "monitor")
+                return this.stopMonitor(handle);
+            return this.stopWorkflow(handle);
+        }
+        // CC206-B 欠账 (CC `y1e` 206:575269-575279 → `cgo` 206:575142-575178): id miss ⇒ NAME leg — a background
+        // agent spawned with a name (sema: the Agent call's description label) is stoppable by that name. Unique
+        // match stops; multiple matches list candidates (CC ambiguous posture, `USd` 206:575178+ adapted to the
+        // bg-agent face — sema has no teammate registry here); zero matches fall through to the enriched
+        // not-found below. Owner semantics stay FAIL-CLOSED: CC's `not_owner` ("Task X is owned by Y") reveals a
+        // foreign task's existence — sema's canAccess guard already filtered those rows out of the name pool, so
+        // a non-owner reads not_found (design/115 info-hiding posture, deliberate divergence, recorded here).
+        // fable 复审 F2 (CC ladder invariant): EVERY exact-id resolution precedes the fuzzy NAME leg — the
+        // second exact-id namespace (a durable workflow runId) must resolve BEFORE name matching, or a bg
+        // agent whose description normalizes to that runId would shadow an exact TaskStop(runId) address.
+        if (opts.workflowStore) {
+            const run = await opts.workflowStore.get(taskId);
+            if (run && canAccessWorkflowRun(run, access)) {
+                return {
+                    content: JSON.stringify({
+                        task_id: taskId,
+                        runId: taskId,
+                        status: run.status,
+                        stopped: false,
+                        error: "workflow task is not attached to this process; cannot stop it here",
+                    }),
+                    details: {
+                        task_id: taskId,
+                        type: "workflow",
+                        status: run.status,
+                        retrieval_status: "success",
+                        error: "not_local",
+                    },
+                };
+            }
+        }
+        const byName = this.resolveBackgroundAgentByName(taskId, access);
+        if (byName.status === "found")
+            return this.stopBackgroundAgent(byName.handle);
+        if (byName.status === "ambiguous") {
+            return {
+                content: byName.message,
+                details: { task_id: taskId, retrieval_status: "not_ready", error: "ambiguous" },
+            };
+        }
+        // CC `Kws` enrichment (206:575251-575258): fuzzy suggestion + the caller's running agents, so the model
+        // can self-correct without a TaskList round-trip.
+        return noTaskForStop(taskId, {
+            ...(byName.suggestion !== undefined ? { suggestion: byName.suggestion } : {}),
+            runningAgents: this.runningBackgroundAgentLabels(access),
+        });
+    }
+    /** CC206-B name resolution over the caller-visible background_agent rows (CC `cgo`/`gvy`, 206:575142-575178
+     *  and 206:575199-575210 — sema's single-lane subset: no teammate/name-registry branches). Matching key =
+     *  normalized description (the spawn label that IS the agent's name on this face). Running rows are
+     *  preferred over terminal ones (CC `gvy`: `o.length > 0 ? o : n`), so a re-used label addresses the live
+     *  agent, while a lone terminal match still resolves (stop is then a no-op receipt with its real status). */
+    resolveBackgroundAgentByName(name, access) {
+        const key = normalizeAgentName(name);
+        if (key === "")
+            return { status: "not_found" };
+        // fable 复审 F3 (CC `cgo` exact-name layer, 206:570911 `JTd`): try a VERBATIM description match
+        // first — a unique exact hit resolves even when normalization would collide (labels "build" and
+        // "Build" both present, query "build": CC finds the exact "build", not ambiguous).
+        const exact = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || !canAccess(h, access))
+                continue;
+            if (h.description === name)
+                exact.push(h);
+        }
+        const exactRunning = exact.filter((h) => h.status === "running");
+        const exactPool = exactRunning.length > 0 ? exactRunning : exact;
+        if (exactPool.length === 1)
+            return { status: "found", handle: exactPool[0] };
+        // 三轮复查 (CC `JTd` 206:570911-570930 亲核): exact-layer ambiguity SHORT-CIRCUITS — CC returns
+        // ambiguous over the exact pool without consulting the normalized layer (`if (s.length > 1) return
+        // { status: "ambiguous", candidates }`). Falling through instead could MIS-RESOLVE: with two
+        // terminal rows labeled "build" and one running row labeled "Build", query "build" would skip the
+        // ≥2 verbatim matches and stop the running "Build" — CC answers ambiguous there.
+        if (exactPool.length > 1) {
+            return {
+                status: "ambiguous",
+                message: `Multiple background agents match "${name}": ${exactPool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+            };
+        }
+        const matches = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || !canAccess(h, access))
+                continue;
+            if (h.description !== undefined && normalizeAgentName(h.description) === key)
+                matches.push(h);
+        }
+        const running = matches.filter((h) => h.status === "running");
+        const pool = running.length > 0 ? running : matches;
+        if (pool.length === 1)
+            return { status: "found", handle: pool[0] };
+        if (pool.length > 1) {
+            // CC ambiguous posture (`USd` 206:575178-575180 adapted): list the colliding rows, point at the
+            // unambiguous address (the task ID — sema bg agents have no name@team form).
+            return {
+                status: "ambiguous",
+                message: `Multiple background agents match "${name}": ${pool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+            };
+        }
+        // CC `hvy` (206:575184-575198): the suggestion pool is RUNNING rows' names; distance runs over the
+        // NORMALIZED keys, but the suggested string is the map VALUE — an ADDRESSABLE handle (CC: agentId /
+        // registered name; sema: the raw spawn label, which the name leg re-normalizes on retry).
+        const byKey = new Map();
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access) || h.description === undefined)
+                continue;
+            const k = normalizeAgentName(h.description);
+            if (k !== "" && !byKey.has(k))
+                byKey.set(k, h.description);
+        }
+        const closest = closestName(key, byKey.keys());
+        return { status: "not_found", ...(closest !== undefined ? { suggestion: byKey.get(closest) } : {}) };
+    }
+    /** CC `ugo` (206:575227-575243): `id (description)` rows for the not-found footer — running bg agents the
+     *  CALLER can address (canAccess scopes; CC's self/observer/named exclusions have no counterpart rows here). */
+    runningBackgroundAgentLabels(access) {
+        const out = [];
+        for (const h of this.handles.values()) {
+            if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+                continue;
+            out.push(h.description ? `${h.id} (${h.description})` : h.id);
+        }
+        return out;
+    }
+    lastGcAt = 0;
+    /**
+     * 预清(飞轮 /tasks + footer pill 的数据源正道): list the caller's OWN tasks as a bounded DISPLAY
+     * projection — never the internal handles (no shellId/env/abort). Same owner/scope guard as poll/stop;
+     * a caller only ever sees its own tasks. Sorted newest-first, capped at `limit` (default 50).
+     * CC parity note: CC's /tasks is a UI/SDK surface, NOT an LLM tool — expose this via SDK/service,
+     * do not mount it as a model tool by default.
+     */
+    list(access, opts = {}) {
+        const limit = Math.min(500, Math.max(1, Math.floor(opts.limit ?? 50)));
+        const out = [];
+        for (const h of this.handles.values()) {
+            if (!canAccess(h, access))
+                continue;
+            out.push({
+                task_id: h.id,
+                type: h.type,
+                status: h.status,
+                sessionScoped: h.sessionScoped === true,
+                ...(h.description !== undefined ? { description: h.description } : {}),
+                ...(h.toolUseId !== undefined ? { toolUseId: h.toolUseId } : {}),
+                createdAt: h.createdAt,
+                updatedAt: h.updatedAt,
+            });
+        }
+        out.sort((a, b) => b.createdAt - a.createdAt);
+        return out.slice(0, limit);
+    }
+    /** Throttled {@link gc} for hot-path callers (design/115 review B5): prepare-task runs once per task,
+     *  and a full-map sweep per prepare is pure overhead — sweep at most once per minute. */
+    maybeGc(now = Date.now()) {
+        if (now - this.lastGcAt < 60_000)
+            return 0;
+        this.lastGcAt = now;
+        return this.gc(now);
+    }
+    gc(now = Date.now(), terminalTtlMs = 60 * 60 * 1000) {
+        let deleted = 0;
+        for (const [id, handle] of this.handles) {
+            if (handle.status === "running" || handle.status === "pending")
+                continue;
+            if (now - handle.updatedAt < terminalTtlMs)
+                continue;
+            this.handles.delete(id);
+            if (handle.type === "background_bash") {
+                this.legacyToTaskId.delete(String(handle.shellId));
+                if (handle.watcher !== undefined)
+                    clearInterval(handle.watcher);
+            }
+            if (handle.type === "monitor" && handle.watcher !== undefined) {
+                handle.timers.clearInterval(handle.watcher);
+                handle.watcher = undefined;
+            }
+            deleted++;
+        }
+        return deleted;
+    }
+    clearBackgroundForOwner(access) {
+        let deleted = 0;
+        for (const [id, handle] of this.handles) {
+            // design/135 G2: per-run teardown also evicts this run's MONITOR handles (the underlying process
+            // dies with disposeBackgroundShells anyway) — EXCEPT session-scoped ones, which outlive the turn
+            // and are reaped by reapSessionBackground (design/129 lifetime discipline, mirrors the agent reap).
+            if (handle.type === "monitor" && !handle.sessionScoped && canAccess(handle, access)) {
+                // 飞轮 [511]③ (CC parity): an in-window non-persistent monitor survives the per-run evict too —
+                // evicting it would orphan the watch (the watcher stops on eviction; nobody would be left to
+                // enforce the timeout, park between-turns events, or serve the spool). The row is evicted once
+                // TERMINAL (its own timeout/exit/TaskStop landed) or past its window; until then the terminal
+                // spool stays TaskOutput-readable across turns, which is exactly the CC posture.
+                if (monitorInTimeoutWindow(handle))
+                    continue;
+                this.handles.delete(id);
+                if (handle.watcher !== undefined) {
+                    handle.timers.clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                deleted++;
+                continue;
+            }
+            if (handle.type !== "background_bash" || !canAccess(handle, access))
+                continue;
+            // 黑板 [636]① (mirrors the monitor arm above): a session-scoped bash row outlives the per-run evict —
+            // its watcher keeps ticking on real timers (between-turns terminal parks on the [492]② pending lane)
+            // and its spool stays TaskOutput-readable across turns; reapSessionBackground is its terminal anchor.
+            if (handle.sessionScoped)
+                continue;
+            this.handles.delete(id);
+            this.legacyToTaskId.delete(String(handle.shellId));
+            if (handle.watcher !== undefined)
+                clearInterval(handle.watcher);
+            deleted++;
+        }
+        return deleted;
+    }
+    resolveInternal(id, access) {
+        const taskId = this.handles.has(id) ? id : this.legacyToTaskId.get(id);
+        if (!taskId)
+            return undefined;
+        const handle = this.handles.get(taskId);
+        if (!handle || !canAccess(handle, access))
+            return undefined;
+        return handle;
+    }
+    async pollBackgroundBash(handle, requestedId, filter, deadline, signal) {
+        let rx;
+        if (filter !== undefined) {
+            try {
+                rx = new RegExp(filter);
+            }
+            catch {
+                return {
+                    content: `Error (TaskOutput): invalid filter regex: ${filter}`,
+                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status: "not_ready" },
+                };
+            }
+        }
+        if (!hasBackgroundShell(handle.env))
+            return noTask(requestedId);
+        // Spool mode (design/116 §7 G2b + B5 close-out): with a watcher attached, the registry owns the FULL
+        // accumulated output — TaskOutput serves a RE-READABLE snapshot (CC semantics: repeated polls return the
+        // same task output, not a consume-once increment). Blocked waits just watch handle.status (the watcher
+        // is the only env-cursor consumer, so there is no double-consumption race).
+        if (handle.spool !== undefined) {
+            while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+                await sleepPollStep(deadline, signal);
+            }
+            const spool = handle.spool;
+            const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile); // [K-PLATFORM-SWEEP] MINOR#7: win32 \r\n lines
+            const running = handle.status === "running";
+            const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+            const displayStatus = spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status;
+            const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+            const body = `status: ${displayStatus}\n${rolledNote}--- stdout (full, re-readable) ---\n${shape(spool.stdout) || "(none)"}\n` +
+                `--- stderr ---\n${shape(spool.stderr) || "(none)"}`;
+            return {
+                content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+                details: {
+                    task_id: handle.id,
+                    type: "background_bash",
+                    status: handle.status,
+                    retrieval_status: retrieval,
+                    ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                    details: { status: running ? "running" : handle.status, exitCode: spool.exitCode },
+                },
+            };
+        }
+        // Blocked wait (design/116 W3, CC `block`): loop the incremental poll until terminal/deadline/abort,
+        // ACCUMULATING each round's stdout/stderr — every pollBackground consumes the env cursor, so a wait
+        // that discarded intermediate increments would silently lose output.
+        // Rolling bound (design/116 review B3): the seam allows up to 8MB per increment × 300 rounds — an
+        // unbounded `+=` is a prompt-injection-reachable OOM. Keep head+tail within 2× the final clip cap and
+        // count what rolled off; the terminal marker reports it honestly.
+        const ROLL_CAP = 2 * TASK_OUTPUT_MAX_CHARS; // 2× the env-cap (not the default): a later poll may raise TASK_MAX_OUTPUT_LENGTH, and rolled-off chars are unrecoverable
+        let rolledChars = 0;
+        const roll = (s) => {
+            if (s.length <= ROLL_CAP)
+                return s;
+            const half = Math.floor(ROLL_CAP / 2);
+            rolledChars += s.length - 2 * half;
+            return s.slice(0, half) + s.slice(s.length - half);
+        };
+        let stdout = "";
+        let stderr = "";
+        let dropped = 0;
+        for (;;) {
+            const r = await handle.env.pollBackground(handle.shellId);
+            if (!r.ok) {
+                if (r.error.code === "not_found")
+                    return noTask(requestedId);
+                const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+                // design/116 review S4: a mid-wait poll error must NOT discard output already consumed from the
+                // env cursor (it is gone from the source) — return the error WITH what accumulated so far.
+                const salvaged = stdout.length > 0 || stderr.length > 0
+                    ? `\n--- output accumulated before the error ---\n${clipTaskOutput(stdout, handle.outputFile)}${stderr ? `\n--- stderr ---\n${clipTaskOutput(stderr, handle.outputFile)}` : ""}`
+                    : "";
+                return {
+                    content: `Error (TaskOutput): ${r.error.message}${salvaged}`,
+                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, error: r.error.code },
+                };
+            }
+            stdout = roll(stdout + r.value.stdout);
+            stderr = roll(stderr + r.value.stderr);
+            dropped += r.value.bytesDroppedBeforeCursor ?? 0;
+            handle.status = statusFromBackground(r.value.status, r.value.exitCode);
+            if (handle.status === "killed" && handle.stoppedBy === undefined)
+                handle.stoppedBy = handle.stopSource ?? "system"; // design/134: killed observed via poll (out-of-band kill ⇒ system)
+            handle.updatedAt = Date.now();
+            const running = r.value.status === "running";
+            if (!running || deadline === undefined || Date.now() >= deadline || signal?.aborted) {
+                // design/116 review S5 (CC 187 semantics): a blocked wait that hit the deadline while the task is
+                // STILL RUNNING reports retrieval_status "timeout", not "success" — the model can tell "finished"
+                // from "gave up waiting" without parsing the status line.
+                const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+                const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile); // [K-PLATFORM-SWEEP] MINOR#7: win32 \r\n lines
+                const displayStatus = r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status;
+                const droppedNote = (dropped > 0 ? `[!] ${dropped} earlier byte(s) permanently dropped before this window (8MB buffer evicted)\n` : "") +
+                    (rolledChars > 0 ? `[!] ${rolledChars} accumulated char(s) dropped from the middle during the blocked wait (memory bound)\n` : "");
+                const body = `status: ${displayStatus}\n${droppedNote}--- new stdout ---\n${shape(stdout) || "(none)"}\n` +
+                    `--- new stderr ---\n${shape(stderr) || "(none)"}`;
+                return {
+                    content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+                    details: {
+                        task_id: handle.id,
+                        type: "background_bash",
+                        status: handle.status,
+                        retrieval_status: retrieval,
+                        ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                        details: { status: r.value.status, exitCode: r.value.exitCode, bytesDroppedBeforeCursor: dropped },
+                    },
+                };
+            }
+            await sleepPollStep(deadline, signal);
+        }
+    }
+    /** 黑板 [405]: this poll SERVED the terminal state in-band — fire the (once-only) ack hook so the
+     *  deployment can drop the redundant completion-inbox entry. Swallow-guarded. */
+    fireServedTerminal(handle) {
+        const cb = handle.onServedTerminal;
+        if (!cb)
+            return;
+        handle.onServedTerminal = undefined;
+        try {
+            cb();
+        }
+        catch {
+            /* an ack hook must never break a poll */
+        }
+    }
+    async pollWorkflow(handle, access, deadline, signal) {
+        const store = handle.store;
+        if (store) {
+            for (;;) {
+                const run = await store.get(handle.runId);
+                if (!run || !canAccessWorkflowRun(run, access))
+                    break;
+                if (run.status !== "running" || deadline === undefined || Date.now() >= deadline || signal?.aborted) {
+                    const out = formatWorkflowRun(run);
+                    if (run.status === "running" && deadline !== undefined && Date.now() >= deadline)
+                        out.details.retrieval_status = "timeout"; // S5
+                    else if (run.status !== "running")
+                        this.fireServedTerminal(handle); // [405] terminal actually served
+                    return out;
+                }
+                await sleepPollStep(deadline, signal);
+            }
+        }
+        // In-memory fallback (no store): the handle status flips via the done-promise hooks — block on it too.
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        if (handle.status !== "running")
+            this.fireServedTerminal(handle); // [405] terminal served (in-memory lane)
+        return {
+            content: JSON.stringify({
+                task_id: handle.id,
+                runId: handle.id,
+                type: "workflow",
+                status: handle.status,
+                ...(handle.status === "completed" && handle.result !== undefined
+                    ? { result: delimitUntrusted("workflow result", handle.result) }
+                    : {}),
+                // T2A-8: hand over the captured failure reason (store lane's formatWorkflowRun already does).
+                ...(handle.status === "failed" && handle.error !== undefined
+                    ? { error: delimitUntrusted("workflow error", handle.error) }
+                    : {}),
+                note: handle.status === "running"
+                    ? "still running — poll again shortly."
+                    : handle.status === "completed"
+                        ? handle.result !== undefined
+                            ? "completed — `result` above is the workflow's return value."
+                            : "completed — its result was delivered on the completion notification."
+                        : handle.status === "failed" && handle.error !== undefined
+                            ? "failed — see error."
+                            : "workflow reached a terminal state.",
+            }),
+            details: {
+                task_id: handle.id,
+                type: "workflow",
+                status: handle.status,
+                retrieval_status: handle.status === "running" && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success", // S5
+            },
+        };
+    }
+    async stopBackgroundBash(handle) {
+        if (handle.watcher !== undefined) {
+            clearInterval(handle.watcher);
+            handle.watcher = undefined;
+        }
+        // design/134 §3.3 (R3 MED, 同族同批): TaskStop主路 = parent, marked BEFORE the kill lands — an earlier
+        // marker (service-wire "user") wins. A failed kill leaves only the pending marker (status untouched).
+        this.markStopSource(handle.id, "parent");
+        const r = await handle.env.killBackground(handle.shellId);
+        if (!r.ok) {
+            if (r.error.code === "not_found")
+                return noTask(handle.id);
+            const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+            return {
+                content: `Error (TaskStop): ${r.error.message}`,
+                details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, error: r.error.code },
+            };
+        }
+        if (handle.stoppedBy === undefined)
+            handle.stoppedBy = handle.stopSource ?? "parent";
+        handle.status = "killed";
+        handle.updatedAt = Date.now();
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: { task_id: handle.id, type: "background_bash", status: "killed", retrieval_status: "success", stoppedBy: handle.stoppedBy },
+        };
+    }
+    /** design/135 G2: TaskOutput over a monitor — a RE-READABLE spool snapshot (the watcher owns the env
+     *  cursor, exactly the bash G2b spool posture): repeated polls return the same accumulated output. */
+    async pollMonitor(handle, filter, deadline, signal) {
+        let rx;
+        if (filter !== undefined) {
+            try {
+                rx = new RegExp(filter);
+            }
+            catch {
+                return {
+                    content: `Error (TaskOutput): invalid filter regex: ${filter}`,
+                    details: { task_id: handle.id, type: "monitor", status: handle.status, retrieval_status: "not_ready" },
+                };
+            }
+        }
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        const spool = handle.spool;
+        const shape = (text) => clipTaskOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text, handle.outputFile);
+        const running = handle.status === "running";
+        const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+        const displayStatus = spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : running ? "running" : handle.status;
+        const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)\n` : "";
+        const body = `status: ${displayStatus}\n${rolledNote}--- stdout (full, re-readable) ---\n${shape(spool.stdout) || "(none)"}\n` +
+            `--- stderr ---\n${shape(spool.stderr) || "(none)"}`;
+        return {
+            content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+            details: {
+                task_id: handle.id,
+                type: "monitor",
+                status: handle.status,
+                retrieval_status: retrieval,
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                details: { status: running ? "running" : handle.status, exitCode: spool.exitCode },
+            },
+        };
+    }
+    /** design/135 G2: TaskStop over a monitor — same shape/attribution discipline as stopBackgroundBash
+     *  (mark "parent" BEFORE the kill; an earlier service-wire "user" marker wins; watcher torn down first
+     *  so a racing tick can't fire a duplicate terminal notification after this receipt). */
+    async stopMonitor(handle) {
+        if (handle.watcher !== undefined) {
+            handle.timers.clearInterval(handle.watcher);
+            handle.watcher = undefined;
+        }
+        this.markStopSource(handle.id, "parent");
+        const r = await handle.env.killBackground(handle.shellId);
+        if (!r.ok) {
+            if (r.error.code === "not_found")
+                return noTask(handle.id);
+            const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
+            return {
+                content: `Error (TaskStop): ${r.error.message}`,
+                details: { task_id: handle.id, type: "monitor", status: handle.status, retrieval_status, error: r.error.code },
+            };
+        }
+        if (handle.status === "running") {
+            if (handle.stoppedBy === undefined)
+                handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.status = "killed";
+            handle.updatedAt = Date.now();
+        }
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: {
+                task_id: handle.id,
+                type: "monitor",
+                status: handle.status,
+                retrieval_status: "success",
+                ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            },
+        };
+    }
+    async pollBackgroundAgent(handle, deadline, signal) {
+        while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+            await sleepPollStep(deadline, signal);
+        }
+        const running = handle.status === "running";
+        const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+        const body = running
+            ? `status: running
+The agent is still working — you will be notified when it completes.`
+            : `status: ${handle.status}
+${handle.error ? `error: ${handle.error}
+` : ""}${handle.result ? `--- result ---
+${clipTaskOutput(handle.result, handle.outputFile)}` : "(no result text)"}`;
+        return {
+            content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+            details: {
+                task_id: handle.id,
+                type: "background_agent",
+                status: handle.status,
+                retrieval_status: retrieval,
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            },
+        };
+    }
+    async stopBackgroundAgent(handle) {
+        if (handle.status === "running") {
+            // design/134 §3.3 (R3 BLOCKER): this path flips killed DIRECTLY (bypassing settle, whose
+            // first-writer guard then never runs) — so attribution must land HERE. Order is load-bearing:
+            // mark first (first-marker-wins keeps an earlier service-wire "user"), then abort/flip.
+            this.markStopSource(handle.id, "parent");
+            handle.abort.abort();
+            handle.status = "killed";
+            handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.updatedAt = Date.now();
+        }
+        return {
+            content: `Terminated ${handle.id}.`,
+            details: {
+                task_id: handle.id,
+                type: "background_agent",
+                status: handle.status,
+                retrieval_status: "success",
+                ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            },
+        };
+    }
+    async stopWorkflow(handle) {
+        // T2A-3 (2026-07-05 soak): a stop on an ALREADY-terminal workflow must not rewrite history — the old
+        // unconditional flip turned completed→cancelled, dropped the captured result from every later poll, and
+        // reported stopped:true for work it never stopped (cf. stopBackgroundAgent's running-only guard).
+        // Known microtask race (codex F-5, accepted): if `done` has fulfilled but its hook hasn't run yet, this
+        // still sees `running` → replies stopped:true; the hook then lands completed+result, so the durable state
+        // stays truthful — only that one receipt can be optimistic. cancel() into a finished run is a no-op.
+        if (handle.status !== "running") {
+            return {
+                content: JSON.stringify({
+                    task_id: handle.id,
+                    runId: handle.id,
+                    type: "workflow",
+                    status: handle.status,
+                    stopped: false,
+                    note: `workflow already ${handle.status} — nothing to stop; poll TaskOutput for its final state.`,
+                }),
+                details: { task_id: handle.id, type: "workflow", status: handle.status, retrieval_status: "success" },
+            };
+        }
+        handle.status = "cancelled";
+        handle.updatedAt = Date.now();
+        handle.handle.cancel("TaskStop requested");
+        return {
+            content: JSON.stringify({
+                task_id: handle.id,
+                runId: handle.id,
+                type: "workflow",
+                status: "cancelled",
+                stopped: true,
+                note: "workflow cancellation requested; durable run status maps cancellation to failed when it finalizes.",
+            }),
+            details: { task_id: handle.id, type: "workflow", status: "cancelled", retrieval_status: "success" },
+        };
+    }
+}
+export const defaultTaskRegistry = new TaskRegistry();
+export function createTaskOutputTool(opts) {
+    return defineTool({
+        name: "TaskOutput",
+        aliases: [...TASK_OUTPUT_ALIASES],
+        description: "Retrieve output or status for a background task by task_id. Supports background Bash tasks and workflow " +
+            "tasks returned by RunWorkflow. Returns only the caller's own task scope; unknown and out-of-scope ids are " +
+            "reported the same way. Legacy bash_id and runId arguments are accepted for compatibility.",
+        // CC-parity param surface (design/115 review S-3): canonical schema declares ONLY what CC's TaskOutput
+        // exposes (task_id) plus sema-delta `filter` (design/103). Legacy `bash_id`/`runId` are accepted at
+        // execute-time via the additional-properties pass-through (TypeBox Object is non-strict) but are NOT
+        // advertised to the model — old persisted calls keep working without teaching new models dead params.
+        parameters: Type.Object({
+            task_id: Type.Optional(Type.String({ description: "The task_id returned by Bash(run_in_background) or RunWorkflow." })),
+            // design/116 W3 (CC TaskOutput block/timeout): wait for completion instead of snapshotting. sema
+            // default is false (cursor semantics preserved); CC's default is true — the describe says so to a
+            // CC-trained model, and sending block:true gets the CC behavior.
+            block: Type.Optional(Type.Boolean({ description: "Whether to wait for completion (default true — the call waits until the task finishes or `timeout`, saving re-poll turns). Pass false for an instantaneous snapshot." })),
+            timeout: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds when block is true (default 30000, max 600000)." })),
+            filter: Type.Optional(Type.String({ description: "Optional regex filter for background Bash output (sema extension)." })),
+        }),
+        effect: "read",
+        execute: async (rawArgs, ctx) => {
+            const args = rawArgs;
+            const id = firstString(args.task_id, args.bash_id, args.runId);
+            if (!id)
+                return "Error (TaskOutput): Missing required parameter: task_id";
+            // Identity: two mount paths (design/115 review B2 resolution). Mounted directly by prepare-task,
+            // ctx carries only {toolCallId, signal} → the opts closure (hostTaskId/principal) applies. Mounted
+            // via spec.tools (this factory is a public export), prepare-task's wrapper injects the RUNNING
+            // task's ctx.taskId/ctx.principal — which is the more precise identity, so it wins.
+            const r = await opts.registry.pollTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, // design/129: session dimension for cross-turn poll
+            {
+                workflowStore: opts.workflowStore,
+                filter: typeof args.filter === "string" ? args.filter : undefined,
+                // CC 187 parity (block: default(!0), clay 拍 2026-07-02): block unless explicitly false. A persisted
+                // pre-116 call (no block key) now waits — strictly better for the model (fewer blind re-polls).
+                block: args.block !== false,
+                timeoutMs: typeof args.timeout === "number" ? args.timeout : undefined,
+                signal: ctx.signal,
+            });
+            // [378] flywheel ask: surface the unified output under the discriminant `type:"task-output"` so the
+            // tool_end.structured allowlist passes it (198 renders TaskOutput as an itemized card). The unified
+            // shape's OWN `type` (the task kind: background_bash/agent/workflow) moves to `taskType` — the outer
+            // key is the card discriminant, not the task kind.
+            const { type: taskType, ...rest } = r.details;
+            return { content: r.content, details: { type: "task-output", ...(taskType !== undefined ? { taskType } : {}), ...rest } };
+        },
+    });
+}
+export function createTaskStopTool(opts) {
+    return defineTool({
+        name: "TaskStop",
+        aliases: [...TASK_STOP_ALIASES],
+        // CC206-B 欠账 (CC `Tzc` 206:281520-281527 = 207:240542+ 同文): the named-agent bullet is CC-verbatim;
+        // CC's teammate bullet (`name@team` / bare teammate name) is honestly OMITTED — sema's team face is
+        // in-process (team.ts), not addressable through this registry, and advertising it would be a lie.
+        description: "- Stops a running background task by its ID\n" +
+            "- Takes a task_id parameter identifying the task to stop\n" +
+            "- To stop a background agent spawned with a name, pass that name as task_id\n" +
+            "- Returns a success or failure status\n" +
+            "- Use this tool when you need to terminate a long-running task",
+        // CC-exact param surface (TaskStopTool.ts:12-17): {task_id, shell_id} both optional, presence enforced at
+        // run time. Legacy `runId` is accepted at execute-time via non-strict pass-through, not advertised.
+        parameters: Type.Object({
+            task_id: Type.Optional(Type.String({ description: "The ID of the background task to stop" })),
+            shell_id: Type.Optional(Type.String({ description: "Deprecated: use task_id instead" })),
+        }),
+        effect: "write",
+        execute: async (rawArgs, ctx) => {
+            const args = rawArgs;
+            const id = firstString(args.task_id, args.shell_id, args.runId);
+            if (!id)
+                return "Missing required parameter: task_id";
+            // Identity: ctx wins when the spec.tools wrapper injected it, else the opts closure (see TaskOutput above).
+            const r = await opts.registry.stopTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, { workflowStore: opts.workflowStore });
+            // 18-tool toolUseResult 尾批 ([378] TaskOutput 同款包装): CC 2.1.201 TaskStopOutput is
+            // {message, task_id, task_type, command?} (sema-shell TaskStopTool outputSchema, all three required) —
+            // the raw UnifiedTaskOutput rode `type: background_bash|workflow|background_agent`, which the
+            // tool_end.structured allowlist (correctly) never passed. Outer `type:"task-stop"` is the card
+            // discriminant; `message` = the model-facing line; the unified fields ride along additively.
+            const { type: taskType, ...rest } = r.details;
+            return {
+                content: r.content,
+                details: { type: "task-stop", message: r.content, task_type: taskType ?? "unknown", ...rest },
+            };
+        },
+    });
+}
+//# sourceMappingURL=task-registry.js.map