@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/human-input-projection.d.ts

@@ -1,12 +1,49 @@
+/**
+ * design/171 §5.2/§6.4 — THE single projection point for human-input speaker envelopes.
+ *
+ * One renderer covers every human-input carrier: the core-side five (objective / live steer /
+ * nextTurn / the resume tail's parked-steer frames / the wake message) and a serving layer's own
+ * carriers through the same contract. The division of labor is fixed (ruled 2026-08-05): the INGRESS
+ * sanitizes text and mints the {@link ActorAssertion}; this module only PROJECTS — it renders the
+ * speaker label ahead of the text, and it never sanitizes, truncates, or rewrites the text itself.
+ *
+ * Envelope contract:
+ *  - no `actor` ⇒ BYTE-IDENTICAL passthrough. Every pre-171 caller and every single-user host
+ *    supplies no actor, so the model-facing bytes of their runs are pinned unchanged.
+ *  - `source: "system"` ⇒ passthrough regardless of actor: machine text (hook wake buses, engine
+ *    notes) is never rendered as human speech.
+ *  - otherwise ⇒ `[from "<id>"]` (plus an explicit `(unverified)` mark when the host did not derive
+ *    the identity from ingress credentials) on its own line ahead of the text. The label is DISPLAY
+ *    ONLY — an attribution, never authority (the normative clause on {@link ActorAssertion}).
+ *
+ * The label goes through the same two neutralizers as the external notification's `from="…"` header
+ * (`inlineUntrusted` + `attrEscape` — one-line, capped, break-out-defused, quote-escaped), so a
+ * hostile id can never close the `[from "…"]` frame, escape an enclosing `<system-reminder>`, or
+ * smuggle a fake `(unverified)`-free identity. The projection runs BEFORE trust framing at every
+ * call site, so the annotation always sits INSIDE the frame it attributes (a trusted frame's
+ * reminder wrapper, an untrusted frame's fence) and can never be separated from its text.
+ */
 import { type ActorAssertion } from "../internal/llm.js";
 import type { HumanInputEvent, HumanInputSource, TaskEventIdentity } from "./types.js";
 export type { HumanInputSource, HumanInputDelivery, HumanInputEvent } from "./types.js";
+/** One human-input frame as the projection point receives it: ingress-sanitized text + the
+ *  ingress-minted assertion (absent = anonymous). */
 export interface HumanInputFrame {
+    /** The input text, ALREADY sanitized by the ingress that accepted it. Returned untouched. */
     text: string;
+    /** Who spoke — absent means the caller supplied no attribution (every pre-171 caller). */
     actor?: ActorAssertion;
     source: HumanInputSource;
 }
+/**
+ * Render the speaker envelope for one human-input frame. Pure; see the module contract above.
+ * Call BEFORE any trust framing (`formatHookFeedback` / `delimitUntrusted`) so the label stays
+ * inside the frame it attributes.
+ */
 export declare function projectHumanInput(frame: HumanInputFrame): string;
+/** design/171 §6.2 — the one constructor for the `human_input` TaskEvent arm: mints the `inputId`
+ *  when the caller has none and materializes NO absent optional keys (absence is the semantic —
+ *  see the three-valued attribution note on the arm in core/types.ts). */
 export declare function buildHumanInputEvent(input: Omit<HumanInputEvent, "type" | "inputId" | keyof TaskEventIdentity> & {
     inputId?: string;
 }): HumanInputEvent;

package/dist/core/human-input-projection.js

@@ -11,7 +11,20 @@ export function projectHumanInput(frame) {
     const mark = frame.actor.hostAsserted ? "" : " (unverified)";
     return `[from "${label}"${mark}]\n${frame.text}`;
 }
+const HANDLED_HUMAN_INPUT_KEYS = {
+    type: "minted-here",
+    inputId: "minted-here",
+    sessionSeq: "forwarded",
+    carrier: "forwarded",
+    source: "forwarded",
+    issuer: "forwarded",
+    actor: "forwarded",
+    delivery: "forwarded",
+    principal: "forwarded",
+    entryId: "forwarded",
+};
 export function buildHumanInputEvent(input) {
+    void HANDLED_HUMAN_INPUT_KEYS;
     return {
         type: "human_input",
         inputId: input.inputId ?? uuidv7(),

package/dist/core/image-downsample.d.ts

@@ -1,23 +1,77 @@
+/**
+ * Generic image downsample/resize pipeline (design/157 S3 — split out of `core/mcp.ts`, which historically
+ * carried this alongside MCP-protocol plumbing even though the pipeline itself has no MCP dependency).
+ * Two consumers share this ONE pipeline + ONE size yardstick: the MCP inline-image bound (`core/mcp.ts`
+ * `boundedImageBlock`) and the Read tool's image branch (`tools/fs/index.ts`). `core/mcp.ts` re-exports
+ * everything below (`export * from "./image-downsample.js"`) so existing importers (`tools/fs/index.ts`,
+ * `core/types.ts`) needed no changes on this car.
+ */
+/**
+ * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value = CC 2.1.187
+ * `API_IMAGE_MAX_BASE64_SIZE` (constants/apiLimits.ts:22, "5 * 1024 * 1024 // 5 MB" — the hard Anthropic API
+ * limit on a base64 image block; CC resizes/compresses down to fit UNDER it, imageResizer.ts). An MCP server
+ * returning a bigger image previously passed straight through = a context/API bomb.
+ */
 export declare const MCP_IMAGE_MAX_BASE64: number;
+/**
+ * 批③ image-pipeline — CC 2.1.x `constants/apiLimits.ts` values, shared by the MCP inline-image bound
+ * AND the Read tool's image branch (tools/fs — internal consistency: ONE yardstick per limit). See also
+ * `tools/fs/index.ts:40-41` ("one limit, two consumers, no drift") — the other consumer of this same
+ * yardstick, which is where this invariant was originally called out.
+ * - `IMAGE_TARGET_RAW_SIZE` (apiLimits.ts:29): raw-byte target that guarantees the base64 encoding stays
+ *   under {@link MCP_IMAGE_MAX_BASE64} (raw × 4/3 = base64 → 3.75MB raw = 5MB base64).
+ * - `IMAGE_MAX_WIDTH/HEIGHT` (apiLimits.ts:42-43): client-side resize box. The API internally resizes
+ *   above 1568px anyway; 2000px preserves a little extra quality while bounding token burn (~3x for a
+ *   full-resolution screenshot vs the box).
+ */
 export declare const IMAGE_TARGET_RAW_SIZE: number;
 export declare const IMAGE_MAX_WIDTH = 2000;
 export declare const IMAGE_MAX_HEIGHT = 2000;
+/**
+ * design/116 W5-1 — bound an inline MCP image. HONEST DELTA vs CC: CC really resizes/downsamples an
+ * oversized image with sharp (utils/imageResizer.ts `maybeResizeAndDownsampleImageBuffer`: ≤2000x2000px,
+ * ≤3.75MB raw = 5MB base64, progressive JPEG/PNG quality ladder). Core deliberately takes NO image-processing
+ * dependency (arch decision — sharp is a native module we won't force on every consumer), so instead of
+ * resizing we BOUND: an image whose base64 exceeds {@link MCP_IMAGE_MAX_BASE64} is spilled to disk and
+ * replaced by an explanatory text block with the size + path; a within-limit image passes through unchanged.
+ */
+/**
+ * Optional image-resize seam (design/116 review CONFIRM-1, clay 拍 2026-07-02 加 seam 保体验): given an
+ * over-limit image, return a smaller re-encoded one — or undefined when it can't. CC resizes with sharp
+ * (imageResizer.ts: fit within 2000x2000, JPEG quality ladder) so the model still SEES a degraded image;
+ * core must not hard-depend on a native image library, so the capability is injected (or auto-detected).
+ */
 export type McpImageResizer = (base64: string, mimeType: string) => Promise<{
     base64: string;
     mimeType: string;
 } | undefined>;
+/**
+ * 批③ image-pipeline — original vs displayed size of a processed image (CC `imageResizer.ts`
+ * `ImageDimensions`). `display*` = what the model actually sees; the Read tool renders the CC coordinate-
+ * mapping meta text from the ratio, so vision coordinate reasoning survives a downsample.
+ */
 export interface ImageDimensions {
     originalWidth: number;
     originalHeight: number;
     displayWidth: number;
     displayHeight: number;
 }
+/** Result of {@link ImageDownsampler}: re-encoded (or passed-through) image + dimensions when known. */
 export interface DownsampledImage {
     base64: string;
+    /** Full mime form (`image/jpeg`), ready for an ImageContent block. */
     mimeType: string;
     dimensions?: ImageDimensions;
 }
+/**
+ * 批③ — buffer-level image downsampler shared by the MCP inline-image bound AND the Read tool's image
+ * branch. Returns undefined when the input can't be processed (corrupt/unsupported) — the caller keeps
+ * its non-sharp path (spill for MCP, original-bytes for Read). A within-limits image passes through
+ * UNCHANGED (with dimensions when known) — pass-through is not a failure.
+ */
 export type ImageDownsampler = (input: Buffer, mimeType: string) => Promise<DownsampledImage | undefined>;
+/** Minimal structural slice of the sharp API the pipeline uses (fresh instance per operation — CC note:
+ *  reusing an instance after toBuffer() silently skips format conversions on some native builds). */
 type SharpFactory = (input: Buffer) => SharpOps;
 interface SharpOps {
     metadata: () => Promise<{
@@ -38,7 +92,27 @@ interface SharpOps {
     }) => SharpOps;
     toBuffer: () => Promise<Buffer>;
 }
+/**
+ * The CC downsample pipeline (imageResizer.ts `maybeResizeAndDownsampleImageBuffer`, called by
+ * FileReadTool.ts:1097 `readImageWithTokenBudget`), ported over an injected sharp factory so the ladder
+ * is unit-testable without the native dependency:
+ *   1. fits already (raw ≤ 3.75MB AND ≤ 2000×2000) → pass through, dimensions attached;
+ *   2. dims fit but bytes over → full-resolution compression first (PNG lossless/palette for PNGs, then
+ *      JPEG quality ladder 80/60/40/20) — preserves resolution when possible;
+ *   3. dims over → constrain to the 2000×2000 box (aspect kept), then the same ladder on the resized
+ *      image if still over; last rung = ≤1000px wide JPEG q20 (returned without a further size check —
+ *      the caller's base64 gate stays the final arbiter, CC-identical shape);
+ *   4. metadata without dimensions → JPEG q80 when over target, else pass through (CC branch).
+ * Exported for tests (fake sharp factory); production entry = {@link sharpImageDownsampler}.
+ */
 export declare function createImageDownsampler(sharp: SharpFactory): ImageDownsampler;
 export declare function sharpImageDownsampler(): Promise<ImageDownsampler | undefined>;
+/**
+ * Default resizer factory: dynamic `import("sharp")` — a turnkey deployment with sharp installed gets the
+ * CC experience automatically; without it this resolves to undefined and the spill path applies. Since
+ * 批③ this is a thin base64 adapter over {@link sharpImageDownsampler} (single pipeline, CC ladder);
+ * the contract is unchanged: undefined when sharp is missing, the input is corrupt, or even the lowest
+ * ladder rung stays over the API limit.
+ */
 export declare function sharpImageResizer(): Promise<McpImageResizer | undefined>;
 export {};

package/dist/core/locked-config.d.ts

@@ -1,6 +1,18 @@
 import type { RunnerDeps, TaskSpec } from "./types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/** The closed set of administratively lockable configuration keys. Adding a member is a deliberate
+ *  edit HERE (tsc forces the registry row), never a free-form string. */
 export type LockedKey = "mcp" | "toolPolicy" | "compliancePosture" | "retentionPolicy";
+/**
+ * The closed locked-key registry: each key names the exact `TaskSpec` fields it guards. Keys whose
+ * field set is EMPTY guard deployment-only surfaces (`compliancePosture` rides
+ * `RunnerDeps.compliancePostureResolver`, `retentionPolicy` rides `RunnerDeps.retentionPolicy`) —
+ * there is structurally no untrusted spec field to refuse, so for those the lock is a declaration
+ * consumed elsewhere (the retention startup validation keys off `retentionPolicy` being locked; the
+ * server control plane reads the declaration for its own sync gate). `satisfies` keeps the row set
+ * and the {@link LockedKey} union in lockstep — tsc refuses a key without a row and a row without a
+ * key.
+ */
 export declare const LOCKED_KEY_REGISTRY: {
     readonly mcp: {
         readonly specFields: readonly ["mcp"];
@@ -15,13 +27,38 @@ export declare const LOCKED_KEY_REGISTRY: {
         readonly specFields: readonly [];
     };
 };
+/** A deployment's lock declaration ({@link RunnerDeps.lockedConfig}). Config-time, trusted. */
 export interface LockedConfig {
+    /** The keys this deployment locks. Wire-validated against {@link LOCKED_KEY_REGISTRY} at the
+     *  preflight door — an unknown member is a loud `config.locked_registry` refusal, never a no-op. */
     keys: readonly LockedKey[];
 }
+/** The preflight's resolved snapshot — the ONLY thing downstream task assembly reads for the
+ *  guarded slots (never the raw `spec.mcp` / `spec.toolPolicy` fields). */
 export interface LockedPreflight {
+    /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
+    /** Effective MCP server list for this task: `spec.mcp` when the key is unlocked; with `mcp`
+     *  locked a spec-supplied value has already been refused, so this is always `undefined` (core has
+     *  no deployment-level MCP seat — a locked deployment mounts no task-supplied servers). */
     mcp: TaskSpec["mcp"];
+    /** Effective caller tool policy: the same `spec.toolPolicy ?? deps.toolPolicy` slot the gate has
+     *  always enforced, resolved ONCE here. With `toolPolicy` locked, the deployment's own
+     *  `deps.toolPolicy` is the whole answer (a spec-supplied policy has already been refused). */
     toolPolicy: ToolPolicy | undefined;
 }
+/**
+ * Validate a deployment's lock declaration against the closed registry. Fail-loud on any unknown
+ * key (`config.locked_registry`): a security control that doesn't parse must refuse to arm, not
+ * degrade to "that key silently unlocked". Exported for deployments that want the check at their
+ * own startup; the task-preparation preflight runs it on every leg regardless (a mis-declared lock
+ * then fails the first prepare instead of silently guarding nothing).
+ */
 export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
+/**
+ * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
+ * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is
+ * silently dropped or merged), and produce the resolved snapshot downstream assembly consumes.
+ * Runs BEFORE any side effect of task preparation.
+ */
 export declare function preflightLockedConfig(spec: TaskSpec, deps: RunnerDeps): LockedPreflight;

package/dist/core/lsp-diagnostics.d.ts

@@ -1,5 +1,23 @@
+/**
+ * design/121 — LSP diagnostics registry + model-facing formatting (CC 2.1.198 parity).
+ *
+ * CC's two diagnostics sources (IDE MCP baseline/diff + passive LSP publishDiagnostics) collapse to
+ * ONE in sema: the passive registry. The "only NEW diagnostics" semantics CC gets from per-file
+ * baselines falls out of the delivered-set here — a diagnostic is injected at most once PER RUN, and a
+ * run editing a file clears its delivered set so a persisting problem can resurface (CC `Fjn` same
+ * behavior). The registry object itself is deployment-scoped, so "per run" is a keyed fact, not an
+ * object lifetime; see {@link LspDiagnosticsRegistry}.
+ *
+ * Volumes and wire format are CC-exact (198:320661 `Njn=10, nqa=30`; 198:320480-320505 summary +
+ * 4000-char cap; severity symbols ✖/⚠/ℹ/★).
+ *
+ * NOT durable: diagnostics regenerate from the language server on the next edit; a suspend/resume
+ * simply starts empty (recorded in design/121 §2).
+ */
+/** One LSP diagnostic, the subset the model/shell needs (LSP `Diagnostic` narrowed). */
 export interface LspDiagnostic {
     message: string;
+    /** LSP severity: 1=Error 2=Warning 3=Information 4=Hint. Absent = unknown (sorted last). */
     severity?: number;
     range?: {
         start: {
@@ -14,18 +32,77 @@ export interface LspDiagnostic {
     code?: string | number;
     source?: string;
 }
+/** One file's new diagnostics, as drained for injection + the wire frame. */
 export interface LspFileDiagnostics {
     uri: string;
     diagnostics: LspDiagnostic[];
 }
+/**
+ * The pending/delivered diagnostics registry.
+ *
+ * **Lifetime, stated honestly:** ONE registry is constructed per `NodeLspManager`, i.e. per DEPLOYMENT —
+ * every task served through `RunnerDeps.lspManager` shares this object. Its two halves scope differently,
+ * and deliberately:
+ *  - `pending` is the language server's own view of the workspace (whole-file replacement per the LSP
+ *    spec) and is therefore deployment-wide, like the servers that feed it;
+ *  - `delivered` — "this was already injected into the transcript" — is a per-RUN fact, so it is keyed by
+ *    the caller's `runIdent`. Without that scope a diagnostic delivered to one run was filtered out of
+ *    every later run's drain for the lifetime of the process, including runs that had never seen it and
+ *    (never having edited that file) had no way to make it resurface. Growth is bounded by the ACTIVE
+ *    runs, because {@link releaseRun} drops a finished run's keys.
+ *
+ * `publish` is called by an LSP session's publishDiagnostics subscription; `drain` is called at the turn
+ * boundary and returns only diagnostics THAT RUN has not been shown, sorted and volume-capped.
+ *
+ * NOT durable: diagnostics regenerate from the language server on the next edit, and a resumed run is a
+ * new run (fresh delivered scope), so a suspend/resume re-delivers rather than losing anything.
+ */
 export declare class LspDiagnosticsRegistry {
+    /** uri → the LAST published full diagnostic set for that file (LSP replace semantics). */
     private readonly pending;
+    /** runIdent → the diagnostic keys already injected into THAT run. Cleared per file when that run edits
+     *  it (the problem may resurface against the new text), and wholesale when the run ends
+     *  ({@link releaseRun}). A Map of Sets rather than one flat prefixed set so that releasing/clearing a
+     *  run can never touch a run whose ident merely starts with the same characters. */
     private readonly delivered;
+    /** Record a `textDocument/publishDiagnostics` payload (already version-checked by the session). */
     publish(uri: string, diagnostics: LspDiagnostic[]): void;
+    /** The run `runIdent` edited `uri` — that run's delivered keys for the file reset, so a still-present
+     *  problem can resurface against the NEW text (CC clears per-file delivered on edit, 198 `Fjn`). Only
+     *  the editing run's view is cleared: another run never saw this edit, and re-showing it a diagnostic
+     *  it is already carrying in its transcript would be duplication, not news. */
     fileEdited(runIdent: string, uri: string): void;
+    /** The run ended — drop its delivered keys. This is what bounds the registry: without it the set grows
+     *  monotonically for the lifetime of the (deployment-scoped) manager. Idempotent; unknown idents are a
+     *  no-op, so a caller may release a run that never drained. */
     releaseRun(runIdent: string): void;
+    /** True when a drain would produce nothing (cheap pre-check for the turn-boundary hook). */
     isEmpty(): boolean;
+    /**
+     * Take the diagnostics `runIdent` has NOT been shown: sorted Error>Warning>Info>Hint within each file,
+     * capped at {@link MAX_PER_FILE}/{@link MAX_TOTAL}, marked delivered FOR THAT RUN. A file whose
+     * diagnostics this run has all seen drops out (until its server publishes again or that run edits it).
+     * "Delivered" is scoped to the run because it means "already in this transcript" — another run's
+     * transcript does not have it, and must be able to see it (see the class note on lifetime).
+     *
+     * HRD-LSP-3: what the caps hold back is REQUEUED, not dropped. The old body capped the take and then
+     * `pending.clear()`-ed unconditionally, so diagnostic #11 of a file — and every file after the 30-item
+     * total ceiling — was neither returned nor marked delivered: it vanished, and no later drain could
+     * recover it unless the server happened to re-publish. Errors ranked first inside a file made that worse,
+     * not better: the highest-severity items were delivered and the REST were the ones destroyed. The
+     * remainder now survives into the next drain (the next turn boundary), which is also what makes the
+     * per-turn volume cap a PACING rule instead of a silent data cap.
+     */
     drain(runIdent: string): LspFileDiagnostics[];
 }
+/**
+ * CC 198 `formatDiagnosticsSummary` (198:320480-320499), verbatim shape:
+ * ```
+ * {basename}:
+ *   {symbol} [Line {line+1}:{col+1}] {message}[ [{code}]][ ({source})]
+ * ```
+ * capped at 4000 chars with an honest `…[truncated]` tail.
+ */
 export declare function formatDiagnosticsSummary(files: LspFileDiagnostics[]): string;
+/** CC 198 model-facing injection block (198:320500-320503), verbatim framing. */
 export declare function formatDiagnosticsBlock(files: LspFileDiagnostics[]): string;

package/dist/core/lsp-protocol.d.ts

@@ -1,9 +1,38 @@
 import type { LspOperation, LspRequestParams, LspResult } from "./lsp.js";
+/**
+ * file:// URI for an absolute path (verified on a Windows host): this serves TWO lanes —
+ * TOC host files (NodeLspManager, host semantics correct) AND remote WS-lane container paths
+ * (E2B/kata sidecar, Linux form). `pathToFileURL` is HOST-platform-semantic: on a win32 host it
+ * parses a remote `/home/user/x.ts` as drive-relative → `file:///C:/home/user/x.ts` → the remote
+ * LSP server gets a nonexistent URI (breaking the remote lane on a win32 host entirely). Structural
+ * form detection instead (same philosophy as the fs-safety dual-family fix — paths come from the
+ * ExecutionEnv and may be of the OTHER family than the host, so never key on process.platform):
+ * POSIX-form absolutes are hand-assembled (percent-encoded per segment, no host path module);
+ * drive-letter form keeps `pathToFileURL` (CC parity for Windows files). On a POSIX host the
+ * hand-assembled branch matches `pathToFileURL(p).href` for typical paths (common characters like
+ * spaces encode identically; exotic characters follow the stricter encodeURIComponent form, and LSP
+ * servers accept both).
+ */
 export declare function pathToUri(p: string): string;
+/**
+ * [K-PLATFORM-SWEEP] MINOR#5: structural inverse of {@link pathToUri} — the naive `file://` prefix strip
+ * left win-form URIs as `/C:/x` (never matching the didOpen keys) and never percent-decoded (a space in a
+ * filename broke the staleness map). Form-detected, never host `fileURLToPath` (cross-family lanes).
+ */
 export declare function uriToPath(uri: string): string;
+/** The follow-up method for the 2-step call ops (issued by the session after prepareCallHierarchy). */
 export declare function callHierarchyMethod(op: "incomingCalls" | "outgoingCalls"): string;
+/** The LSP method + params for an op (incoming/outgoing FIRST issue prepareCallHierarchy — the session 2-steps). */
 export declare function buildRequest(op: LspOperation, params: LspRequestParams): {
     method: string;
     params: unknown;
 } | undefined;
+/**
+ * @param fallbackUri the QUERIED document's URI — required for `documentSymbol`, whose standard reply shape
+ * (`DocumentSymbol[]`: name/range/selectionRange/children, NO uri and NO location) carries no location of its
+ * own. Without it every symbol of that shape was dropped and a perfectly good reply rendered as "No results."
+ * (HRD-LSP-6 — gopls/rust-analyzer/pyright all answer in that shape). Deliberately NOT applied to
+ * `workspaceSymbol`/call-hierarchy: those shapes always carry their own uri, and substituting the queried
+ * file's would attribute a symbol to the wrong file.
+ */
 export declare function parseResult(op: LspOperation, raw: unknown, fallbackUri?: string): LspResult;

package/dist/core/lsp-session.d.ts

@@ -1,6 +1,10 @@
 import type { LspSession, LspOperation, LspRequestParams, LspResult, LspTransport, LspReadText } from "./lsp.js";
 import type { LspDiagnosticsRegistry } from "./lsp-diagnostics.js";
 export interface SessionWarmup {
+    /** Empty results within this window after session creation are retried (a freshly-spawned server answers
+     *  non-blocking ops with EMPTY results while its project is still loading — the model may call
+     *  hover/documentSymbol FIRST and get non-null-but-empty answers; goToDefinition happens to block on load,
+     *  which is why op-order made it look random). 0 disables. */
     windowMs: number;
     retryMs: number;
 }
@@ -8,30 +12,85 @@ export declare class TransportLspSession implements LspSession {
     private readonly transport;
     private readonly languageId;
     private readonly readText;
+    /** Observability hook for swallowed degrades (graceful "none" hides real transport faults otherwise). */
     private readonly log;
     private readonly warmup;
+    /** filePath → the last text SENT to the server (didOpen/didChange) + its document version. */
     private readonly opened;
+    /** HRD-LSP-19: the URI we actually SENT for each opened file → that file's `opened` key. The diagnostics
+     *  staleness guard used to re-derive the key with `uriToPath(publishedUri)`, which normalizes a drive path
+     *  to backslash form regardless of how the caller spelled it — so with any other spelling the lookup missed
+     *  and a stale (older-version) publish sailed through the guard onto the model's screen. Keying on the URI
+     *  we ourselves sent removes the round-trip entirely (`uriToPath` stays the fallback for a server that
+     *  re-spells the URI). */
     private readonly openedUris;
+    /** In-flight per-file syncs — concurrent ops on the same new file share ONE read/didOpen. Each entry owns a
+     *  {@link SharedAbortScope} so ONE caller's abort no longer cancels the read the others are waiting on
+     *  (HRD-LSP-12). */
     private readonly syncing;
     private readonly createdAt;
+    /** HRD-LSP-11: the warm-up barrier as a shared JOB, not a boolean flag set before the await (which let the
+     *  second concurrent first-op skip the barrier entirely, and permanently disabled it whenever the barrier
+     *  request failed or was cancelled). */
     private warmupBarrier?;
     private warmupDone;
     private warmupAttempts;
-    constructor(transport: LspTransport, languageId: string, readText: LspReadText, log?: (event: string, fields: Record<string, unknown>) => void, warmup?: SessionWarmup, diagnostics?: LspDiagnosticsRegistry);
+    constructor(transport: LspTransport, languageId: string, readText: LspReadText, 
+    /** Observability hook for swallowed degrades (graceful "none" hides real transport faults otherwise). */
+    log?: (event: string, fields: Record<string, unknown>) => void, warmup?: SessionWarmup, 
+    /** design/121: when set (and the transport dispatches notifications), the session feeds this
+     *  registry from `textDocument/publishDiagnostics` — with version-staleness protection: a
+     *  notification versioned OLDER than the text this session last SENT for that file is dropped
+     *  (the server is still churning on stale content). Absent ⇒ pre-121 behavior byte-for-byte. */
+    diagnostics?: LspDiagnosticsRegistry);
+    /** HRD-LSP-16: ops in flight on this session. The manager consults it before LRU/idle-evicting a server —
+     *  closing one mid-op turns a healthy answer into `server_terminated` for a caller that did nothing wrong. */
     get inFlight(): number;
     private activeRequests;
     request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
     private requestOnce;
+    /**
+     * HRD-LSP-11: run (or join) this session's ONE warm-up barrier.
+     *
+     * The old form set a boolean BEFORE awaiting the barrier request, so a second concurrent first-op read
+     * `true` and fired its real request into a still-loading project (an empty answer retries, but a PARTIAL
+     * non-empty symbol/reference list is accepted as complete — the silent half). And because the flag was
+     * never cleared, any failure/abort of that one request disabled the barrier for the session's whole life.
+     * Now: joiners await the same job, a failed barrier is re-armed (bounded by {@link WARMUP_MAX_ATTEMPTS}),
+     * and one caller's abort neither cancels the shared barrier nor makes the others wait for it.
+     */
     private warmupBarrierOnce;
+    /** Re-sync every opened file (+ the queried one) with its CURRENT on-disk text, in parallel. Returns the
+     *  QUERIED file's outcome — the one the op's honesty depends on (HRD-LSP-7). */
     private syncOpenedFiles;
+    /** didOpen a new file / didChange (full-text replace) an opened one whose disk content moved. Never throws:
+     *  it REPORTS failure instead (`{ok:false}`) — an unreadable file no longer looks like a clean sync to the
+     *  caller. Concurrent callers share one in-flight sync, each keeping its OWN cancellation (HRD-LSP-12). */
     private syncOne;
+    /** RB-232: structural fallback classification for errors carrying no {@link lspFailureOf} brand (a
+     *  third-party transport, e.g. the TOB WS lane) — abort signal and transport liveness are the only
+     *  transport-neutral facts available; everything else is a server fault. Cannot produce
+     *  "unsupported_operation" until that transport brands its JSON-RPC error codes (cross-repo slip). */
     private static classifyUnbranded;
+    /** Underlying connection gone (e.g. the server crashed / the WS was idle-killed) → the manager evicts + reopens. */
     get closed(): boolean;
+    /** Files didOpen'd on this server — the manager carries them to a HEALED session: a fresh server with no
+     *  project config only "sees" its open files (e.g. tsserver inferred project), so without the carry-over,
+     *  cross-file ops (references/calls) silently degrade to single-file after a heal. */
     openedFiles(): string[];
+    /** Re-open carried files on a fresh session (heal). Best-effort per file (a deleted file just skips).
+     *  Returns how many files did NOT make it, so the manager's heal log can say when a carry-over was lost
+     *  instead of leaving a silently single-file server behind (HRD-LSP-1 disclosure half). */
     warmOpen(filePaths: string[], signal?: AbortSignal): Promise<{
         opened: number;
         failed: number;
     }>;
+    /**
+     * design/121: push the file's CURRENT text to the server WITHOUT an op (didOpen/didChange as
+     * appropriate). The agent's edit/write tools call this fire-and-forget so the server re-analyzes
+     * and pushes publishDiagnostics — the session's normal lazy sync only runs on the next LSP op,
+     * which may never come. Never throws (same best-effort contract as syncOne).
+     */
     notifyFileChanged(filePath: string, signal?: AbortSignal): Promise<void>;
     close(): Promise<void>;
 }