@sema-agent/core 5.19.0 → 5.21.0

package/dist/agents/roster-store.d.ts

@@ -1,34 +1,128 @@
+/** One persisted name→agent binding (the CC roster `members[{name, agentId}]` shape + sema access axes). */
 export interface RosterEntry {
+    /** The verbatim spawn name (display form; resolution runs over {@link normalizeAgentName}). */
     name: string;
+    /** The background agent's task id (`a…`). */
     agentId: string;
+    /** The retained child session id, when known — the cross-run resume address. */
     sessionId?: string;
+    /** The spawn's parent tool-call id (retain-ledger key), when known. */
     toolUseId?: string;
+    /** δ 批 [1498]⑦ — the ROOT host session of the delegation tree at spawn (recovery-face grouping
+     *  key; equals the spawner's session at depth 1). Stored verbatim; no predicate arm consumes it
+     *  yet (enumeration/recovery is the reader). */
     rootSessionId?: string;
+    /** design/151 S3b — the RESOLVED model id at spawn (revival lookup key; display/model-routing
+     *  hints only, never a serialized spec). */
     model?: string;
+    /** Ruled 2026-08-05: the spawn requested a model word that did not bind — the row runs on its
+     *  inherited default. Closed set, single member today; absent = bound normally (or no word). */
     modelFallback?: "inherit_no_tier_binding";
+    /** Spawn owner (task/session id) — consumers re-apply access checks against these two axes.
+     *  β 批 A-2: REQUIRED (default-deny predicate; an axis-less row would be unreachable). */
     owner: string;
+    /** Spawn principal scope. β 批 A-2: REQUIRED (`"default"` is the single-tenant spelling). */
     scope: string;
+    /** codex R3 — mirrors the live registry's explicit session-scoping flag: session-ID owner matching
+     *  is permitted ONLY when the spawn was session-scoped (TaskRegistry.canAccess parity — without
+     *  the flag, a task-scoped agent that fell out of the live registry would become visible through
+     *  the durable fallback to same-session callers the registry itself rejects). */
     sessionScoped?: boolean;
+    /** Registration wall-clock ms (latest-wins tiebreak, matching registry layer 0). */
     createdAt: number;
 }
+/**
+ * The caller's access axes for a roster read — the SAME predicate the live task registry applies
+ * (`canAccess`): scope mismatch = invisible; then owner match, or session match. codex F3 (S1
+ * review): resolution MUST filter the candidate pool by access BEFORE the latest-wins reduce —
+ * reduce-then-check lets one tenant's newer same-name entry shadow (and thereby suppress) another
+ * tenant's older authorized binding. Implementations (incl. pg/tidb) apply this in the query.
+ */
 export interface RosterAccess {
     owner?: string;
     scope?: string;
     sessionId?: string;
 }
+/** β 批 A-2 (clay 裁定 2026-07-22): DEFAULT-DENY both axes (TaskRegistry.canAccess byte-parity —
+ *  the polarity split was the defect). Entries are written with both axes (spawn chain guarantees
+ *  it; {@link RosterEntry} requires them), so a missing axis is a broken row, answered with a miss. */
 export declare function entryAccessible(e: RosterEntry, access: RosterAccess): boolean;
+/**
+ * The roster persistence seam. All methods MAY be async (a pg-backed store is); core's two bundled
+ * implementations are synchronous. Implementations are ADVISORY infrastructure: a throwing store
+ * must never fault a spawn — callers wrap writes in try/catch and treat read errors as a miss.
+ *
+ * v1 honesty contract (RB-23): writes are FIRE-AND-FORGET from the spawn path — a named-spawn
+ * receipt does NOT acknowledge roster persistence, and a failed/lost async write degrades to a
+ * later `not_found`/`roster_only` miss (never a wrong answer). Acknowledged writes (outbox) are the
+ * DEPLOYMENT'S half: they need a durable spool + retry scheduling, which belongs to whoever owns
+ * the database connection lifecycle — core's advisory contract above is the library-side final form.
+ *
+ * RB-23② release semantics (settled): a roster row's lifetime follows ADDRESSABILITY — the durable
+ * session data behind `sessionId` — NOT the agent's running state and NOT the parent-run retain
+ * ledger. Core deliberately wires NO terminal-cleanup or retain-evict call into {@link
+ * RosterStore.releaseAgent}: retain is a parent-run-scoped cache (disposed with the run), while the
+ * roster exists precisely to outlive it; releasing at terminal would kill cross-run resolution, the
+ * store's whole purpose. The correct trigger is durable session DELETION, which happens on the
+ * deployment side — a deployment's session GC calls `releaseAgent` (or joins roster rows against
+ * session liveness in SQL). A stale row left behind costs only an honest downstream failure on
+ * resume (miss / `resume.evicted`-class error — never a wrong answer); {@link RosterGcOptions}
+ * `maxAgeMs` is the bounded-staleness backstop for deployments that want one (RB-23③), and
+ * {@link RosterGcOptions.maxEntries} the bounded-SIZE one (HRD-AGO-11). Both are OFF by default: a bundled
+ * store keeps every live (name, owner, scope) binding forever, so a deployment that spawns under a fresh owner
+ * per run grows one permanent row per spawn until it opts into a bound. That default is deliberate — an
+ * evicted row is a durable ADDRESS a caller can no longer reach — but it is the deployment's to change.
+ */
 export interface RosterStore {
+    /** Record (or supersede — latest-wins per normalized name is applied at READ time) a binding. */
     record(entry: RosterEntry): void | Promise<void>;
+    /** Resolve a name for a CALLER: filter by {@link RosterAccess} FIRST, then latest `createdAt`
+     *  wins within the authorized pool (codex F3 filter-before-reduce). Undefined = miss. */
     resolve(name: string, access: RosterAccess): RosterEntry | undefined | Promise<RosterEntry | undefined>;
+    /** All live entries (diagnostics / deployment listing; order unspecified). */
     list(): RosterEntry[] | Promise<RosterEntry[]>;
+    /** Drop every binding for an agent id (agent stopped and unaddressable / deployment GC). */
     releaseAgent(agentId: string): void | Promise<void>;
 }
+/**
+ * RB-23③ (settled): optional bounded-staleness GC for the bundled stores. `maxAgeMs` is a
+ * DEPLOYMENT knob because the right value is the deployment's durable-session retention horizon
+ * (align the two and a roster row can never outlive the address it points at) — core cannot know
+ * it, so the default is NO TTL (current behavior; the file store's upsert already bounds growth by
+ * live name cardinality, not spawn count). Semantics: an expired row is a MISS on every read
+ * (resolve/list) and is opportunistically dropped on the next write — same honesty class as every
+ * other degradation here (expired ⇒ miss, never a wrong answer). A pg-backed store implements the
+ * same two arms in SQL (`WHERE created_at > now() - ttl` + periodic delete).
+ */
 export interface RosterGcOptions {
+    /** RB-473 — disclosure channel for CONTAINED host-callback failures in this scope (the RB-463
+     *  isolation primitive's bounded first-failure per site). Absent ⇒ failures are counted only. */
     onNotifyError?: (failure: import("../core/safe-notify.js").SafeNotifyFailure) => void;
     maxAgeMs?: number;
+    /**
+     * HRD-AGO-11 (opt-in) — hard cap on live rows in a bundled store. **Default: UNBOUNDED**, and deliberately
+     * so: the upsert domain is (normalized name, owner, scope), which bounds growth by LIVE NAME CARDINALITY
+     * only — a deployment that spawns `worker` under a FRESH owner per run (a per-task owner id is the common
+     * shape) accumulates one permanent row per spawn, and the file store rewrites the whole document on every
+     * write, so the cost is O(n²) over a deployment's lifetime. A blind default cap would be worse than the
+     * leak: a roster row IS a durable ADDRESS, and silently evicting one turns a live agent unaddressable
+     * (`not_found` on a name the caller legitimately holds). So the bound is the DEPLOYMENT's call — it is the
+     * only party that knows how many live addresses it needs — and this is how it says so.
+     *
+     * Policy when set: after each write, while the row count exceeds `maxEntries`, drop the row with the
+     * SMALLEST `createdAt` (oldest binding first; the row just written is by construction the newest, so a
+     * write never evicts itself). Every dropped row is reported to {@link onEvicted} — an evicted address is a
+     * capability the deployment loses, so it is never dropped in silence. Reads are unaffected (an evicted row
+     * is simply gone: an honest miss, never a wrong answer — the same honesty class as `maxAgeMs`).
+     *
+     * A pg/tidb-backed store implements the same shape in SQL (a windowed delete keyed on `created_at`).
+     */
     maxEntries?: number;
+    /** HRD-AGO-11 — called with each row dropped by the {@link maxEntries} cap (never for a normal upsert
+     *  supersede). A throwing sink is swallowed: roster writes are advisory and must never fault a spawn. */
     onEvicted?: (entry: RosterEntry) => void;
 }
+/** In-memory roster (the default): cross-turn within one process, gone on restart. */
 export declare class MemoryRosterStore implements RosterStore {
     private entries;
     private readonly maxAgeMs;
@@ -50,7 +144,14 @@ export declare class FileRosterStore implements RosterStore {
             reason: string;
         }) => void;
     });
+    /** RB-482 #25 (baggage class-4 ruling): the LENIENT read grade's swallow stays (a store fault must read as a
+     *  miss on resolve/list — advisory layer), but it is no longer SILENT: an IO failure or corrupt
+     *  document was indistinguishable from an honestly empty roster. Never fires on plain ENOENT. */
     private discloseCorrupt;
+    /** codex F4 — two read grades: MISSING file (ENOENT) is an honest empty roster, but a corrupt or
+     *  transiently unreadable file must THROW on the mutation path — treating it as empty would let
+     *  the next `record` atomically REPLACE the existing file with just one row (silent data loss).
+     *  Read paths (resolve/list) degrade the throw to a miss via `lenient`. */
     private read;
     private write;
     record(entry: RosterEntry): void;
@@ -58,4 +159,8 @@ export declare class FileRosterStore implements RosterStore {
     list(): RosterEntry[];
     releaseAgent(agentId: string): void;
 }
+/** design/147 S1c — advisory durable-roster write for a NAMED background spawn: never throws and never
+ *  unhandled-rejects (sync or async store alike); a roster fault must not fault the spawn.
+ *  design/157 A7 — moved from `agents/subagent.ts`: the semantics are roster's, not the delegation
+ *  tool's (the signature already value-imports `RosterStore`/`RosterEntry` from this module). */
 export declare function recordRosterSpawn(roster: RosterStore | undefined, entry: RosterEntry, onError?: (err: unknown) => void): void;

package/dist/agents/roster-store.js

@@ -1,4 +1,5 @@
 import { mkdirSync, readFileSync } from "node:fs";
+import { assertRetentionPolicy } from "../core/retention-policy.js";
 import { atomicWriteFile } from "../stores/file/fs-atomic.js";
 import { dirname } from "node:path";
 import { normalizeAgentName } from "../core/task-registry.js";
@@ -50,6 +51,7 @@ export class MemoryRosterStore {
     maxAgeMs;
     gc;
     constructor(opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;
     }
@@ -78,6 +80,7 @@ export class FileRosterStore {
     gc;
     onCorruptRead;
     constructor(path, opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.path = path;
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;

package/dist/agents/send-message-tool.d.ts

@@ -5,29 +5,76 @@ import { type ToolCtxEnricher } from "../core/tools.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerAdmissionConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
+/** Model-facing name of the background-agent continuation tool (CC 2.1.2xx `SendMessage`). */
 export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 export interface SendMessageToolOptions {
+    /** Runner used to execute the resumed child run (the design/122 resume face's delegation runner). */
     runner: Runner;
+    /** The unified task registry the background Agent lane registered its a* handles in. */
     registry: import("../core/task-registry.js").TaskRegistry;
+    /** design/122 D1 — the parent run's retain ledger (present only when `TaskSpec.retainSubagentSessions`
+     *  opted in). Absent ⇒ the tool stays mounted but every call returns the honest not-retained text. */
     retain?: SubagentRetainLedger;
+    /** Registry access identity (mirrors TaskOutput's closure identity — the mount fills these). */
     owner?: string;
     scope?: string;
     sessionId?: string;
+    /** Deployment-level background-notify sink — the resumed run's completion rides the existing chain. */
     notify?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
+    /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
     sink?: (handle: SubagentSteerHandle) => void;
+    /**
+     * design/147 S1a — the PARENT run's notification injector (RunInternals.parentNotify), present only
+     * when THIS run is a delegated child. Enables the "main" uplink: SendMessage("main", …) lands in the
+     * parent's injection queue as a `background_agent`/`event` frame at a turn boundary. Absent ⇒ the
+     * honest placeholder text stays.
+     */
     uplink?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
+    /** design/147 S1a — this run's own spawn name (teammate identity) for uplink attribution. */
     senderName?: string;
+    /** design/147 S1c — the deployment's durable roster, consulted after the live registry misses. */
     roster?: import("./roster-store.js").RosterStore;
+    /** design/147 S3a (codex F2) — the PARENT run's retain ledger (RunInternals.parentRetainLedger):
+     *  the sibling leg's retain entries live there. Consulted AFTER the own-run and session ledgers. */
     siblingRetain?: SubagentRetainLedger;
+    /** RB-390 — the SPAWNING run's taskId when THIS run is a delegated child (RunInternals.parentTaskId,
+     *  mount-filled from the trusted internals chain — never a model argument). Historically the ONLY
+     *  way this fact could reach a first-party mount: the adapter handed a `defineTool` product's body
+     *  just `{toolCallId, signal}`, so `ctx.parentTaskId` never arrived and the design/147 S3a sibling
+     *  legs (byName parent-view retry, tier-3 parent view) were dead on every auto-mounted child run —
+     *  teammates could not reach each other by name ("no agent matches" while the parent's view
+     *  resolved fine). RB-409 opened the ctx route as well ({@link enrichCtx}), and the Runner mount
+     *  fills BOTH from the same internals chain; this seat remains the fallback (and the only route for
+     *  a host that wires the tool itself). A `ctx.parentTaskId` wins when present. SendMessage ONLY —
+     *  the TaskStop/TaskOutput mounts deliberately have no such seat (no widening of the kill/read
+     *  surface). */
     parentTaskId?: string;
+    /** RB-390 — companion session axis of {@link parentTaskId} (RunInternals.parentSessionId): a
+     *  session-scoped sibling registers with owner = the parent's sessionId, which the parent's
+     *  taskId alone cannot satisfy when the two differ (same rationale as ToolExecuteContext.parentSessionId). */
     parentSessionId?: string;
+    /** [1358] the process-level background-child observer (RunnerDeps.onBackgroundChildEvent) — the
+     *  mount fills this so a SendMessage resume re-emits the spawn→tick→terminal family (fleet row
+     *  revival). Rides the OPTS closure like notify; RB-409's {@link enrichCtx} feeds the ctx twin. */
     onBackgroundChildEvent?: (event: import("../core/types.js").BackgroundChildEvent) => void;
+    /** design/151 §7 S3c — the durable execution-row ledger ({@link RunnerDeps.backgroundAgentStore}):
+     *  the tier-3 resolution rung (exact a* handle / roster name → durable row) and the claim-CAS
+     *  target. Tier-3 activates only when THIS + {@link mailbox} + {@link reviveSpawn} are all
+     *  present; anything less keeps the pre-S3c honest refusal texts byte for byte. */
     agentStore?: import("../core/background-agent-store.js").BackgroundAgentStore;
+    /** design/151 §7.1 — the durable mailbox ({@link RunnerDeps.mailboxStore}): a message is parked
+     *  here ONLY on the claim-winner path (append after the row CAS is won), consumed via
+     *  claim/lease + ack at spawn success — never a destructive drain. */
     mailbox?: import("../core/mailbox-store.js").MailboxStore;
+    /** design/151 §6.3 案 B — the trusted revival spawner: prepare-task wraps the MOUNTED delegation
+     *  tool's execute (object identity via the `agentListing` marker — never wire-name lookup, so a
+     *  caller's same-named shadow tool can never receive the trusted claim) with a fresh toolCallId
+     *  and `ctx.reviveClaim`. The revival is thereby the FULL spawn chain (observer frames, durable
+     *  lane re-arm, notify, park semantics) — nothing re-implemented here. */
     reviveSpawn?: (req: {
         row: import("../core/background-agent-store.js").BackgroundAgentRecord;
         rev: number;
@@ -40,14 +87,59 @@ export interface SendMessageToolOptions {
         content: string;
         details?: unknown;
     }>;
+    /** RB-473 batch 2b — bounded disclosure for a deployment sink throwing inside the resume face's
+     *  isolation scope (threaded into {@link createSubagentResume}); absent = counted only. */
     onNotifyError?: (failure: import("../core/safe-notify.js").SafeNotifyFailure) => void;
+    /**
+     * RB-409 — the mount's per-call ctx builder, forwarded to {@link defineTool} (see
+     * {@link ToolCtxEnricher}). This tool is a `defineTool` PRODUCT, so before this seat existed its
+     * body could only ever see `{toolCallId, signal}` and every `ctx.*` read below fell to its `opts`
+     * fallback — the ctx-first arms were structurally dead on the first-party mount. The Runner mount
+     * now passes its own trusted ctx builder here (the SAME one it applies to `spec.tools` tools), so
+     * the two sources agree by construction rather than by a copied table. Absent ⇒ unchanged
+     * behavior: the opts closure alone supplies the identity axes.
+     */
     enrichCtx?: ToolCtxEnricher;
+    /** design/176 — caller tuning for the always-on peer-message admission gate (per-field
+     *  range-validated; out-of-range values fall back to that field's default; there is no off
+     *  switch). The Runner mount threads {@link import("../core/types.js").RunnerDeps.peerAdmission}
+     *  here. Read per call — a changed value governs the next message. */
     admission?: Partial<PeerAdmissionConfig>;
+    /** design/176 — the SENDING run's peer-identity carrier (trusted internals chain; ctx twin
+     *  {@link import("../core/types.js").ToolExecuteContext.peerSelfRef} wins when present). Supplies
+     *  the sender's bucket key and the hop token appended to every outbound chain. A direct mount
+     *  without it degrades to axis synthesis from `sessionId`/`owner`; with no axes at all the sender
+     *  is identity-less (rate/dedup skipped — hop and queue bounds still apply). */
     peerSelf?: PeerSelfRef;
+    /** design/176 — the SENDING run's inbound peer-chain ref (ctx twin wins): the chain of the most
+     *  recently consumed peer message, which this run's outbound sends extend. */
     peerInbound?: PeerInboundChainRef;
+    /** design/176 — the RECIPIENT identity of the {@link uplink} callback, PAIR-MINTED at the same
+     *  trust point that bound the callback (spawn internals assembly / the resume face's
+     *  currentParentNotify replacement): `uplink` is an opaque void callback and the parent axes
+     *  deliberately keep the ORIGINAL spawner on the revive arm while the callback points at the
+     *  WAKER — so the uplink's admission identity can only travel WITH the binding, never be derived.
+     *  A direct mount that wires `uplink` without this leaves L1 ungated (recorded honest boundary:
+     *  the library does not fabricate an identity on the host's behalf). */
     uplinkRecipient?: PeerSelfRef;
 }
+/** RB-382 — max chars of the `summary` arg (the short recap label, distinct from `message`'s much
+ *  larger {@link UPLINK_RESULT_MAX}) before ITS OWN truncation. Exported for direct unit-testing only
+ *  (module-internal path, same convention as MONITOR_SPILL_CAP_BYTES — not part of the src/index.ts
+ *  public surface): the tool's OWN schema already declares `summary: Type.String({ maxLength: 200 })`,
+ *  so a call arriving through the normal `AgentTool.execute` gate (`defineTool`'s `Value.Check`, see
+ *  core/tools.ts) can never carry a summary longer than this — the clip below is a defense-in-depth
+ *  belt for any caller that reaches this function body without going through that gate, not a live
+ *  truncation a model-facing call can trigger today. */
 export declare const SEND_MESSAGE_SUMMARY_MAX = 200;
+/** RB-382 — clip a trimmed, non-empty `summary` to {@link SEND_MESSAGE_SUMMARY_MAX} chars, appending
+ *  the SAME "[… truncated: N chars total]" marker style every `message` truncation site in this file
+ *  already uses (the four delivery legs each silently did `slice(0, 200)` with no marker at all — a
+ *  double standard against `message`'s disclosed truncation in the same file, at least on paper — see
+ *  this constant's own doc comment for why the schema gate makes the branch unreachable in practice
+ *  today). The cap itself is unchanged; only the missing disclosure is added. RB-419 then folded those
+ *  four re-derivations into a SINGLE call site, immediately after the gate that makes the argument
+ *  non-empty — so this helper now has exactly one caller in the tool body. */
 export declare function clipSendMessageSummary(raw: string): string;
 export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
     to: Type.TString;

package/dist/agents/session-util.d.ts

@@ -1,2 +1,7 @@
 import type { Runner } from "../core/runner/runtask.js";
+/**
+ * Release a throwaway session, swallowing errors — best-effort cleanup for the verifier/cascade-rung
+ * sessions that agents spin up and discard. Always call this in a `finally` so a throwing `runTask`
+ * result handler or caller hook (`onRung`/`onRound`) can't leak the session.
+ */
 export declare function releaseSession(runner: Runner, sessionId: string): Promise<void>;

package/dist/agents/subagent-steps.d.ts

@@ -1,15 +1,53 @@
+/**
+ * Sub-agent residual-observability recorder (lanes A/B/D — CC harness parity).
+ *
+ * A parent observing a child agent — especially one that was stopped mid-flight by a stream drop or
+ * TaskStop — needs more than final text + terminal status to write a PRECISE resume prompt ("you
+ * stopped at file X, step Y"). CC's harness feeds the parent a compact step tail + the child's edited
+ * files + a one-line "currently doing" progress string. This recorder derives those three from the
+ * child's live `TaskEvent` stream (the same `onForwardEvent` sink the display/tick lanes already tap),
+ * so no new engine plumbing is needed — it is a pure observer.
+ *
+ * Scope: ONE direct child. A child that itself spawns a grandchild re-threads the same forward sink,
+ * so grandchild events bubble through here too. Scoping is EXPLICIT, not first-come-first-served
+ * (CORE-2 — the old "first `sourceTaskId` seen" lock assumed direct-child content always precedes
+ * any grandchild frame, an ordering the shared sink does not guarantee):
+ *   1. the spawn site calls {@link SubagentStepRecorder.lockTo} the moment the child's taskId is known
+ *      (fork lanes: the forked sessionId; retained lanes: the pre-minted child sessionId) — after that,
+ *      only `sourceTaskId === lockedSource` frames are recorded;
+ *   2. lanes where the child id is minted inside `runTask` (plain sync / non-retained background) anchor
+ *      by FRAME PAIRING instead: the runner stamps `sourceTaskId` + `parentToolCallId` together on every
+ *      child content event, and the DIRECT child's `parentToolCallId` is THIS delegation's own tool-call
+ *      id (a grandchild's frames carry the child's delegation id) — so the provisional lock only seeds
+ *      from a matching frame;
+ *   3. without either anchor (bare construction — tests/legacy), the first-source lock applies as before.
+ * Everything is BOUNDED (step ring ≤ {@link STEP_CAP}, fields truncated) so a pathological child can't
+ * balloon the parent's notification/report.
+ */
 import type { TaskEvent } from "../core/types.js";
+/** One completed tool step in the child's tail — enough for the parent to say "you stopped at X". */
 export interface SubagentStep {
+    /** Tool name (or its distinct {@link ToolSpec.label} when set). */
     tool: string;
+    /** The step's primary argument, one line: file path / command / pattern. May be "". */
     target: string;
+    /** Result first line — or `error: …` when the tool failed. May be "". */
     outcome: string;
 }
+/** A file the child mutated, with how many times (Write/Edit/MultiEdit/NotebookEdit). */
 export interface SubagentEditedFile {
     path: string;
     edits: number;
 }
+/** Keep the last N tool steps (CC's tail is ~this deep; older steps are rarely load-bearing for resume). */
 export declare const STEP_CAP = 10;
+/** The tool's primary argument as a single short line (best-effort; unknown shapes → a compact JSON head). */
 export declare function extractTarget(args: unknown): string;
+/**
+ * Observes a single child's forwarded `TaskEvent`s and derives the residual-observability projection.
+ * Feed it every event via {@link record}; read {@link recentSteps}/{@link editedFiles}/{@link currentAction}
+ * at report/notify/tick time. Swallow-safe: `record` never throws (an observer must never fault a run).
+ */
 export declare class SubagentStepRecorder {
     private lockedSource;
     private lockedResolved;
@@ -20,17 +58,45 @@ export declare class SubagentStepRecorder {
     private action;
     private actionTool;
     private actionTarget;
+    /**
+     * @param parentToolCallId THIS delegation's own tool-call id (`ctx.toolCallId` — the exact value the
+     *   spawn threads as `RunInternals.parentToolCallId`, which the runner stamps back onto every direct-child
+     *   content event). Used to seed the provisional lock ONLY from a direct-child frame while no explicit
+     *   {@link lockTo} anchor is set. Optional: absent falls back to the legacy first-source lock.
+     */
     constructor(parentToolCallId?: string);
+    /**
+     * CORE-2 — explicitly anchor the observed DIRECT child by its taskId (= its sessionId on every
+     * delegation lane: `buildChildSpec` never sets `spec.taskId`). Call as soon as the id is known at the
+     * spawn site. If events arrived BEFORE the anchor and the provisional lock caught a DIFFERENT source
+     * (a grandchild racing through the shared sink), everything recorded so far belongs to the wrong
+     * descendant — reset it and re-lock, so the projection never mixes generations.
+     */
     lockTo(taskId: string): void;
+    /** Drop everything recorded under a mis-locked source (see {@link lockTo}). */
     private resetRecorded;
+    /** True when the event belongs to the observed direct child (see the class doc for the 3-tier anchor). */
     private inScope;
     record(e: TaskEvent): void;
+    /** The child's last ≤{@link STEP_CAP} completed tool steps; undefined if none observed. */
     recentSteps(): SubagentStep[] | undefined;
+    /** Files the child mutated with edit counts; undefined if none. */
     editedFiles(): SubagentEditedFile[] | undefined;
+    /** The child's most recent tool intent as one human line ("Bash npm test", "Edit src/x.ts"); undefined if none. */
     currentAction(): string | undefined;
+    /** [1828] (server cross-repo): {@link currentAction} pre-formatted into a fleet-view Progress-section
+     *  shape — the SAME `{tool, target}` pair `currentAction` already concatenates into one line, exposed
+     *  separately so a consumer can look the tool up in its own registry instead of parsing prose.
+     *  Undefined if none observed (mirrors {@link currentAction}'s own undefined case exactly). */
     currentActionStructured(): {
         toolName: string;
         target?: string;
     } | undefined;
 }
+/**
+ * Residual lane C — derive the last `lastN` tool steps from a session's PERSISTED messages (the pull-model
+ * `AgentTranscript` read face). Mirrors {@link SubagentStepRecorder} but sources from committed history
+ * instead of the live event stream, so a parent can retrospectively read a child's tail on demand. Walks
+ * assistant `toolCall`s paired with the following `toolResult`, oldest→newest, then keeps the last N.
+ */
 export declare function stepsFromMessages(messages: readonly unknown[], lastN: number): SubagentStep[];