@sema-agent/core 5.20.0 → 5.21.1

package/dist/engine/lsp/node-lsp-manager.d.ts

@@ -2,17 +2,43 @@ import { type SessionWarmup } from "../../core/lsp-session.js";
 import { type LspChildProcess } from "./stdio-lsp-transport.js";
 import { type LspServerManager, type LspSession, type LspReadText } from "../../core/lsp.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/**
+ * Default language → server command table (the DETERMINED supported set). Each value is a `command [args…]`
+ * whose binary must be on the host `PATH`; absent ⇒ that language degrades. Mirrors the servers service bakes
+ * into its sandbox templates (so TOC & TOB expose the SAME languages when installed), plus the common
+ * rust/c/cpp servers a local dev box usually has. Override/extend via {@link NodeLspManagerOptions.servers}
+ * (a `null` value disables a language). All of these speak LSP over stdio by default.
+ */
 export declare const DEFAULT_LSP_SERVERS: Readonly<Record<string, string>>;
+/** Spawn a child (default). Resolves the child on a successful `spawn`, or `undefined` on `error` (ENOENT =
+ *  server not installed → the manager degrades that language). Waiting for the 'spawn'/'error' race before use
+ *  is CRITICAL: `spawn()` returns synchronously but ENOENT fires 'error' asynchronously (CC's LSPClient §1.5). */
 export type LspSpawn = (command: string, args: string[], cwd: string, signal?: AbortSignal) => Promise<LspChildProcess | undefined>;
 export interface NodeLspManagerOptions {
+    /** Override/extend {@link DEFAULT_LSP_SERVERS} (merged over it; a `null` value disables that language). */
     servers?: Record<string, string | null>;
+    /** Injectable spawn (tests supply a fake server; default = {@link defaultLspSpawn} over `child_process.spawn`). */
     spawn?: LspSpawn;
+    /** Read a file's CURRENT text for the session's didOpen/didChange re-sync (default = local `fs.readFile` utf8). */
     readText?: LspReadText;
+    /** Resolve the server `cwd`/`rootUri` for a file (default = env.cwd ?? nearest project marker ?? file dir). */
     resolveRoot?: (filePath: string, env?: ExecutionEnv) => string;
+    /** Observability hook (open/heal/degrade/evict events). */
     log?: (event: string, fields: Record<string, unknown>) => void;
+    /** Warm-up window override (see {@link TransportLspSession}); default 10s/1s. */
     warmup?: SessionWarmup;
+    /** Max concurrently-cached language servers before LRU eviction (default 16, min 1). A safety net bounding
+     *  the cache when a deployment can't call {@link NodeLspManager.evict} at task-end (e.g. ephemeral/worktree
+     *  roots). Each cached server is a real process (jdtls = a JVM), so keep this modest. */
     maxSessions?: number;
+    /** Idle-TTL (ms) after which an unused server is auto-reclaimed by a background sweep (default 600_000 = 10
+     *  min; 0 disables). Self-healing complement to {@link NodeLspManager.evict}: a deployment that can't call
+     *  `evict` at task-end still won't leak — an abandoned server dies on its own. An actively reused server never
+     *  goes idle (its last-used stamp refreshes on every lookup), so a modest TTL doesn't churn the happy path. */
     idleTtlMs?: number;
+    /** design/121: the workspace diagnostics registry every session feeds from publishDiagnostics.
+     *  WORKSPACE-scoped, not server-scoped — it survives heal/evict (diagnostics belong to files, not to a
+     *  server instance). Absent ⇒ notifications stay dropped (pre-121 behavior byte-for-byte). */
     diagnostics?: import("../../core/lsp-diagnostics.js").LspDiagnosticsRegistry;
 }
 export declare class NodeLspManager implements LspServerManager {
@@ -22,33 +48,114 @@ export declare class NodeLspManager implements LspServerManager {
     private readonly resolveRootFn;
     private readonly log;
     private readonly warmup?;
+    /** design/121: the workspace diagnostics registry (see {@link NodeLspManagerOptions.diagnostics}) —
+     *  public so the Runner drains it at turn boundaries via {@link LspServerManager.diagnostics}. */
     readonly diagnostics: import("../../core/lsp-diagnostics.js").LspDiagnosticsRegistry;
     private readonly maxSessions;
     private readonly idleTtlMs;
     private sweepTimer?;
+    /** `<language> <root>` → the live session + its root + last-used stamp (reused across ops; healed when its
+     *  transport dies; idle-TTL swept; LRU-evicted over {@link maxSessions}; `evict(root)` drops a task's servers
+     *  at task-end). Space-separated key is unambiguous — a languageId never contains a space. */
     private readonly cache;
+    /** In-flight opens (concurrent ops on the same language+root share ONE spawn/initialize). Tracks each open's
+     *  `root` + a `cancelled` flag so {@link evict}/{@link dispose} can reclaim a server whose open resolves AFTER
+     *  the teardown already ran (else its `.then` caches a live child that nothing reclaims — permanently after
+     *  dispose, since the sweep timer is cleared). */
     private readonly opening;
+    /** RB-376 — the NEGATIVE spawn cache, the missing twin of {@link cache}: a `(language, root)` key
+     *  whose real `spawn()` already failed (binary not on PATH). Without it, every successful
+     *  Edit/Write/NotebookEdit re-triggered a full spawn attempt for the same missing server — a
+     *  production leg recorded 205 `lsp_spawn_degraded` events with the model never calling LSP once.
+     *  Same key construction as the positive cache. NO TTL by design: a missing binary does not appear
+     *  mid-task, and a time-based retry would just resume the re-spawn storm — {@link clearFailed} is
+     *  the explicit recovery valve. `attempts` counts suppressed hits (first failure logs once via
+     *  `lsp_spawn_degraded`; cache hits stay silent; the count surfaces on the cleared log line). */
     private readonly failed;
+    /** HRD-LSP-14: consecutive `initialize` failures per key, BEFORE the latch (see {@link INIT_FAILURE_LATCH}). */
     private readonly initFailures;
+    /** Set by {@link dispose}: an in-flight open that resolves after dispose self-closes instead of caching. */
     private disposed;
     constructor(opts?: NodeLspManagerOptions);
+    /** Close + drop every server idle past {@link idleTtlMs}. Runs on a timer; best-effort. */
     private sweepIdle;
     sessionFor(filePath: string, signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;
+    /** Spawn + initialize a fresh session for `key`, deduping concurrent opens. `carry` = files to re-open
+     *  before the session becomes visible (heal). */
     private open;
+    /** LRU-evict (close) the least-recently-used server(s) until there is room for one more under {@link maxSessions}.
+     *  A safety net: without an explicit {@link evict}, a long-lived process spawning tasks with EPHEMERAL roots
+     *  (worktree / per-task cwd) would otherwise leak one heavyweight language server per (task × language). */
     private evictOverCap;
+    /**
+     * Evict + kill every cached language server rooted at `root`. Call this at TASK-END for an ephemeral/worktree
+     * cwd so a heavyweight server (e.g. a jdtls JVM) doesn't outlive the task that spawned it — the deterministic
+     * complement to the LRU cap. `root` must match what `resolveRoot` produced for the task (the host lane uses the
+     * task's `env.cwd`). Best-effort + idempotent (an unknown/already-evicted root is a no-op).
+     */
     evict(root: string): Promise<void>;
+    /**
+     * RB-376 — drop negative spawn-cache entries so the NEXT op may retry the real spawn: the explicit
+     * recovery valve for "I just installed that language server" (the entries deliberately have no TTL —
+     * see the `failed` field doc). No arg ⇒ clear everything; `root` ⇒ only that root's entries (the
+     * {@link evict} shape). Each cleared entry logs its suppressed-attempt count (evict-log parity).
+     * Idempotent; an unknown root is a no-op.
+     */
     clearFailed(root?: string): void;
+    /**
+     * HRD-LSP-14 (optional {@link LspServerManager} member): WHY the last `sessionFor` for this file degraded.
+     * `openSession` collapses three very different situations into one `undefined` — the language has no
+     * server configured, the binary is not installed, or the server IS installed and failed to initialize —
+     * and the tool rendered the same "no language server for its language in this environment" for all of
+     * them. The first is a fact about the deployment; the third is an incident the operator can fix, and
+     * telling the model (and the transcript) they are the same thing is how "we have no LSP for Go" survives
+     * for months in an environment where gopls is installed and crashing.
+     */
     unavailableReason(filePath: string, env?: ExecutionEnv): string | undefined;
     private openSession;
     private serverCmd;
+    /** Kill every running server + stop the idle sweep (call on runner/deployment shutdown). Best-effort. */
     dispose(): Promise<void>;
 }
+/** Resolve a file path to a languageId via its extension (undefined = no mapping → degrade). */
 export declare function languageFor(filePath: string): string | undefined;
+/** CC 2.1.220's LSP file cap — single-sourced in core (`src/core/lsp.ts`), where the tool-layer check
+ *  enforces it model-visibly; re-exported here so engine-path importers keep working. */
 export { MAX_LSP_FILE_BYTES } from "../../core/lsp.js";
+/**
+ * RB-232(黑板 [1937]): the local default {@link LspReadText}, hardened with a stat-first precondition (CC
+ * 2.1.220 validateInput does the same before ever reading — "Path is not a file", pretty220.js ~474700).
+ * The stat check is the LOAD-BEARING part, do not "simplify" it away: a plain `readFile` on a FIFO/socket
+ * blocks forever on the FIRST read and PINS a libuv threadpool thread (default pool = 4) for the process
+ * lifetime — measured: `readFile(fifo, { signal })` with an abort fired at 2s was still unsettled at 10s,
+ * because Node only checks the signal between chunk reads. `{ signal }` is kept as a bonus for regular
+ * files; it cannot rescue the FIFO case on its own. (The tool layer additionally rejects such paths via
+ * `env.fileInfo` before any read — this is defense in depth for direct/embedder callers.)
+ */
 export declare const defaultLspReadText: LspReadText;
+/** service [377] ask ②: on Windows, npm-global language servers materialize as `.cmd` shims and
+ *  Node 20+ `spawn(cmd, args)` without a shell rejects them (EINVAL, CVE-2024-27980 hardening) —
+ *  every DEFAULT_LSP_SERVERS entry would silently degrade to "no LSP". `shell:true` routes through
+ *  cmd.exe so PATHEXT/.cmd resolution works. Injection surface: `command`/`args` come from
+ *  LspServerSpec (deployment configuration, trusted) or DEFAULT_LSP_SERVERS constants — never from
+ *  the model. Exported as a pure function so the win32 branch is testable off-platform. */
 export declare function lspSpawnOptions(cwd: string): {
     cwd: string;
     stdio: ["pipe", "pipe", "ignore"];
     shell?: boolean;
 };
+/**
+ * Default spawn over `child_process.spawn`, resolving on 'spawn' / `undefined` on 'error' (ENOENT = degrade)
+ * / REJECTING with the errno error for any other spawn failure (see {@link NodeLspManager}'s `failed` map:
+ * "not installed" is permanent and worth caching, EACCES/EMFILE/a transient cwd is not — HRD-LSP-15).
+ *
+ * 🔴 HRD-LSP-4 — the ABSORBER below is load-bearing, do not "simplify" it away. `ChildProcess` is an
+ * `EventEmitter`, and an 'error' emitted with ZERO 'error' listeners is re-thrown by Node as an uncaught
+ * exception — in a library that means TAKING THE HOST PROCESS DOWN. `spawn()` returns synchronously while
+ * ENOENT arrives asynchronously (CC's LSPClient §1.5), so every path that removes our own listener before
+ * that event lands is a live crash: `onAbort` (cancel a spawn that is about to fail = a routine task
+ * cancellation) and `onSpawn` (the window between resolving and `StdioLspTransport`'s constructor attaching
+ * its handler). A permanent no-op listener, attached before anything can fire and never removed, makes the
+ * emitter unable to throw; the transport's own handler still receives every runtime error afterwards.
+ */
 export declare const defaultLspSpawn: LspSpawn;

package/dist/engine/lsp/stdio-lsp-transport.d.ts

@@ -1,4 +1,5 @@
 import { type LspTransport } from "../../core/lsp.js";
+/** The slice of a spawned child process the transport uses (so a test can drive a fake duplex — no real spawn). */
 export interface LspChildProcess {
     stdin: {
         write(data: Buffer): void;
@@ -9,6 +10,7 @@ export interface LspChildProcess {
     };
     on(event: "exit" | "error", cb: (arg?: unknown) => void): void;
     kill(signal?: string): void;
+    /** Present on a real child process; used on win32 (shell:true shim) to tree-kill on close. */
     pid?: number;
 }
 export declare class StdioLspTransport implements LspTransport {
@@ -18,11 +20,16 @@ export declare class StdioLspTransport implements LspTransport {
     private readonly pending;
     private isClosed;
     private readonly decode;
+    /** design/121: server→client notification subscribers (publishDiagnostics, …). Empty = pre-121 behavior. */
     private readonly notificationHandlers;
     constructor(child: LspChildProcess, requestTimeoutMs?: number);
+    /** Manager-visible liveness: evict + reopen instead of reusing a dead server (crashed / killed). */
     get closed(): boolean;
     private onMessage;
+    /** design/121 {@link LspTransport.onNotification}: subscribe to server notifications; returns unsubscribe. */
     onNotification(handler: (method: string, params: unknown) => void): () => void;
+    /** RB-232: every failAll caller — child exit, child error, AND deliberate close() — means "server is
+     *  gone" to the model, so all are branded `server_terminated` alike (no exit-vs-close distinction). */
     private failAll;
     private send;
     request(method: string, params: unknown, signal?: AbortSignal): Promise<unknown>;

package/dist/engine/session/import-validate.d.ts

@@ -1,18 +1,45 @@
 import { type SessionTreeEntry } from "../harness/types.js";
+/** Options for {@link StreamingImportValidator} / {@link validateEntriesForImport}. */
 export interface ImportValidatorOptions {
+    /**
+     * design/171 §6.4 — the import door's SECOND WRITE GATE for `UserMessage.actor`. Default `false`
+     * (fail-closed): imported history has its `actor` assertions STRIPPED — an importer must never
+     * re-assert who spoke in a history it did not witness (`hostAsserted:true` is an ingress-derived
+     * claim, and import is not an ingress). `true` = the operator DECLARES the source trusted
+     * (e.g. a same-deployment backend migration) and well-formed assertions are preserved verbatim;
+     * shape-poisoned ones are still stripped like the sibling metadata fields.
+     */
     preserveActorAssertions?: boolean;
 }
 export declare class StreamingImportValidator {
     private readonly seen;
+    /** RB-129: entry id → parentId, so the compaction floor check can walk ANCESTRY rather than stream order. */
     private readonly parentOf;
     private rootCount;
     private runningLeaf;
     private done;
+    /** design/171 — see {@link ImportValidatorOptions.preserveActorAssertions}. */
     private readonly preserveActorAssertions;
     constructor(options?: ImportValidatorOptions);
+    /** Validate ONE entry, in oldest-first order. Throws `SessionError("invalid_session")` on the first violation
+     *  (duplicate id, or a parent/structural reference not stepped before this entry). */
     step(entry: SessionTreeEntry): void;
+    /** Finalize the stream: exactly one root (for a non-empty log) + the derived leaf resolves to a stepped entry.
+     *  Returns the resolved leaf id (null for an empty session). Throws on violation; single-use. */
     finish(): {
         leafId: string | null;
     };
 }
+/**
+ * Validate a verbatim session-entry log for cross-backend IMPORT (2c session-sync, service [266]②). The ARRAY
+ * form of {@link StreamingImportValidator} (ONE source of truth — this just drives step()/finish() over the
+ * array, kept for `fork`/tests that already hold the whole log). Fail-CLOSED: any violation throws
+ * `SessionError("invalid_session")` and nothing is written.
+ *
+ * Returns the validated log with ids/parents/timestamps preserved (the imported session is
+ * byte-identical to the source; only the owner is re-stamped by the caller, not here), modulo the
+ * single engine-provenance normalization carve-out ([c209-C] R4 double-stamp + R5 shape + design/171
+ * actor gate) documented on {@link StreamingImportValidator} — applied to a PROTECTED COPY of each
+ * message entry, never to the caller's shared objects (see the clone note in the body).
+ */
 export declare function validateEntriesForImport(entries: SessionTreeEntry[], options?: ImportValidatorOptions): SessionTreeEntry[];

package/dist/engine/session/log-digest.d.ts

@@ -1,5 +1,98 @@
 import type { SessionTreeEntry } from "../harness/types.js";
+/**
+ * [1701] session-sync — the SHARED content digest for a session entry log.
+ *
+ * ## The gap this closes
+ * `classifySyncRelationshipByIds` compares only the SET of entry ids. Entry ids are uuidv7, not content
+ * addresses, so "same ids, different payload" is structurally ordinary — and the wire accepts whatever
+ * entries a client sends. The measured consequences were: an `identical` 200 returned while the destination
+ * still holds different text; a `fast_forward` classified "clean append, safe to apply" while it destroys
+ * corrections on the destination without the 409 that promise depends on.
+ *
+ * ## Why RE-computing a canonical form on both sides is safe HERE (and is not, elsewhere)
+ * There is a load-bearing ruling against exactly this pattern — design/80 r3, "绝不让两个运行时各算
+ * canonical-JSON" — which is why `boundInputHash` is minted once and treated as opaque by every consumer,
+ * and why `canonicalize` is not exported from the package index. Read at the source rather than through its
+ * paraphrase in `canonical-json.ts`, that ruling rests on TWO legs, and only one of them still stands:
+ *
+ *  1. **There was no vetted canonical serializer.** The verbatim reasoning is "deps 只 typebox+MCP、core 无
+ *     canonical/stable JSON serializer、JS JSON.stringify 非规范". The remedy prescribed in the same
+ *     sentence was "ship 一个 vetted canonical serializer" — which shipped as `canonical-json.ts`. This leg
+ *     described the state of the codebase at the time, and it no longer holds.
+ *  2. **The blast radius of a false mismatch**: "false-mismatch 会 fail-closed 拒掉合法审批". A serializer
+ *     divergence on the approval path DENIES a legitimate human decision. This leg stands, and it is the
+ *     one that decides whether the ruling transfers to a new use.
+ *
+ * Here the blast radius is inverted, and deliberately so:
+ *  - digests EQUAL   ⇒ short-circuit as `identical`;
+ *  - digests DIFFER  ⇒ **do not short-circuit** — run the full sync path.
+ *
+ * So a serializer divergence between two core versions costs extra work (a sync that would have short-
+ * circuited now runs), never a wrong answer and never a refusal. That asymmetry is the whole reason this
+ * function may be exported while `canonicalize` itself stays internal. **Consumers must preserve it**: a
+ * digest mismatch may never be turned into an error, a 409, or a refusal to sync — only into "compare
+ * properly instead of trusting the ids".
+ *
+ * ## Versioning
+ * `test/session-log-digest.test.ts` freezes the digest of a fixture that exercises every value shape the
+ * serializer distinguishes. If a change moves a frozen value, the documented response is to ADD a row for a
+ * new {@link SESSION_LOG_DIGEST_SCHEME} — never to edit a frozen value in place, because peers on different
+ * core versions compare these strings to each other and the old row records what was on the wire.
+ *
+ * A scheme mismatch is reported as "not comparable", which — by the rule above — degrades to the full sync
+ * path, exactly like a value mismatch.
+ *
+ * ## What is hashed, and why not the engine's canonical serializer
+ * v1 hashed `canonicalize` (the approval-binding serializer). An adversarial review of the shipped v1 found
+ * that choice unsound for a WIRE digest, on four counts that all trace to the same root — that serializer is
+ * built for a single runtime comparing a value to ITSELF, not for two runtimes comparing what they hold:
+ *
+ *  - It distinguishes `{a: undefined}` from `{}` by design. On a wire there is no such distinction, and core
+ *    itself produces own-keys-set-to-undefined routinely (clearing a label; a custom entry with no data). So
+ *    the SAME log digested different on an in-memory backend than after a JSON round-trip — measured end to
+ *    end — and the short-circuit this whole mechanism exists for would simply never have fired.
+ *  - Its number token has no terminator, so a numeric value can run into the following key: two genuinely
+ *    different payloads produced one canonical form (demonstrated).
+ *  - It collapses every host object to `o0:{}` (any two Dates, any two Maps) and everything past a depth
+ *    limit to one sentinel — acceptable when the alternative is refusing an approval, not acceptable when the
+ *    consequence is "these two logs are the same, skip the sync".
+ *  - Lone surrogates became U+FFFD at the UTF-8 hashing step, so a payload that survived one byte round-trip
+ *    on one peer collided with the original on the other.
+ *
+ * v2 hashes a **stable JSON serialization of the JSON-representable form** instead: each entry goes through
+ * `JSON.stringify`/`parse` (so both peers digest the same thing the wire carries), then a key-sorted
+ * serializer. JSON's own grammar is unambiguous — strings are quoted, numbers are delimited — so the
+ * adhesion above cannot occur; `JSON.stringify` escapes lone surrogates as `\uXXXX`; depth is unlimited; and
+ * a Date/Map has already become its wire form before hashing. It also means this module no longer shares a
+ * serializer with the approval path at all, which removes the tension with that path's ruling at the root
+ * rather than arguing about its blast radius.
+ *
+ * ## What is covered
+ * Every field of every entry that survives to JSON, in the order given — id, parentId, type, timestamp and
+ * the whole payload. Key ORDER within an entry is not (that is what the sort is for); entry order is (a
+ * reordered log is a different log — one of the three measured failure shapes).
+ */
 export declare const SESSION_LOG_DIGEST_SCHEME = "sema-log-v3";
+/** Digest of ONE entry (same scheme and rules as {@link sessionLogDigest}; useful for per-entry reporting). */
 export declare function sessionEntryDigest(entry: SessionTreeEntry): string;
+/**
+ * Digest of an ORDERED entry log. Two logs with the same digest hold the same entries, in the same order,
+ * with the same payloads and the same parent structure — as far as JSON can express them.
+ *
+ * Length-prefixing each entry's serialized form keeps concatenation unambiguous (without it, two adjacent
+ * entries could be re-partitioned into a different pair with the same bytes). The domain tag (`log` vs
+ * `entry`) keeps the two digest families from ever being equal by accident.
+ */
 export declare function sessionLogDigest(entries: readonly SessionTreeEntry[] | null | undefined): string;
+/**
+ * Are two digests comparable at all? False for a different scheme version, an absent value, or anything that
+ * is not a well-formed digest string.
+ *
+ * Every rejection path returns `false` rather than throwing. That is load-bearing: this function sits on the
+ * classification path, and the contract it serves says a digest problem must degrade to "do the full sync",
+ * never to an error. v1 guarded only `undefined` — but JSON has no `undefined`, so "the peer sent no digest"
+ * arrives as `null`, which threw. v1 also derived the scheme with `slice(0, indexOf(":sha256:"))`, and a
+ * missing separator yields -1, so any string shaped like the scheme plus one character passed as a valid
+ * digest of that scheme — two peers holding the same truncated non-digest would have compared equal.
+ */
 export declare function sessionLogDigestsComparable(a: string | null | undefined, b: string | null | undefined): boolean;

package/dist/engine/session/memory-repo.d.ts

@@ -10,7 +10,13 @@ export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata,
     list(): Promise<SessionMetadata[]>;
     delete(metadata: SessionMetadata): Promise<void>;
     fork(sourceMetadata: SessionMetadata, options: SessionForkOptions): Promise<Session>;
+    /** 2c session-sync ([266]②): the FULL log for export. InMemory holds everything (no F3 floor), so
+     *  `getEntries()` IS the full oldest-first log with `id`/`parentId` verbatim. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
+    /** 2c session-sync ([266]②): import a verbatim log into `sessionId`. The single invariant gate runs first
+     *  ({@link validateEntriesForImport}, fail-closed); `owner` is a durable multi-tenant concept that the local
+     *  in-memory backend has no field for, so it is accepted but unused here. design/171: the operator's
+     *  trusted-import flag is forwarded to the gate that persists — see SessionRepo.importEntries. */
     importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
         preserveActorAssertions?: boolean;
     }): Promise<void>;

package/dist/engine/session/memory-storage.d.ts

@@ -1,9 +1,11 @@
 import type { SessionMetadata, SessionTreeEntry, SessionWriteOptions } from "../harness/types.js";
 import { BaseSessionStorage } from "./storage-base.js";
+/** Volatile session storage used by tests and in-process harness callers. */
 export declare class InMemorySessionStorage<TMetadata extends SessionMetadata = SessionMetadata> extends BaseSessionStorage<TMetadata> {
     constructor(options?: {
         entries?: SessionTreeEntry[];
         metadata?: TMetadata;
+        /** Branch floor for a bounded-window load (F3); the entries must start at this id. */
         floorEntryId?: string | null;
     });
     setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;

package/dist/engine/session/session.d.ts

@@ -3,7 +3,15 @@ import type { AgentMessage } from "../loop/types.js";
 import type { Session, SessionContext, SessionMetadata, SessionStorage, SessionTreeEntry, WorkspaceState } from "../harness/types.js";
 import type { BuildContextOptions } from "../harness/types.js";
 import type { PromptEpochDescriptor } from "../../prompt-assembly/epoch.js";
+/** Build model context from the active session branch and its latest state markers.
+ *  `opts` (window awareness, see {@link BuildContextOptions}): when the caller declares the
+ *  consuming model's window, the compaction summary's retained invoked-skills area is defensively
+ *  re-clamped so 「summary + retained area」 can never push the rebuilt context out of that window
+ *  on its own. Absent ⇒ byte-identical legacy rendering. */
 export declare function buildSessionContext(pathEntries: SessionTreeEntry[], opts?: BuildContextOptions): SessionContext;
+/** High-level session API backed by pluggable tree storage. Implements the vendored `Session` CONTRACT
+ *  (`SessionContract`) the harness consumes — dependency inversion so the vendored substrate needs no
+ *  `import` of this concrete class (de-vendoring prep); `implements` makes the contract drift caught here. */
 export declare class StoredSession<TMetadata extends SessionMetadata = SessionMetadata> implements Session<TMetadata> {
     private storage;
     constructor(storage: SessionStorage<TMetadata>);
@@ -20,23 +28,90 @@ export declare class StoredSession<TMetadata extends SessionMetadata = SessionMe
     appendMessage(message: AgentMessage): Promise<string>;
     appendThinkingLevelChange(thinkingLevel: string): Promise<string>;
     appendModelChange(provider: string, modelId: string): Promise<string>;
+    /**
+     * Campaign S3 (prompt-assembly §9.2): persist the session's prompt-epoch pin as a first-class
+     * typed entry. Written at session start (BEFORE the first conversation entry — the resume path
+     * must never see user entries with no pin) and on legacy migration; compactions restate the pin
+     * in their own `details.promptEpoch` instead (same-CAS with the new baseline).
+     */
     appendPromptEpoch(descriptor: PromptEpochDescriptor): Promise<string>;
+    /**
+     * design/150 (RB-25): persist the listing announced name-sets as a first-class typed entry.
+     * Called best-effort at every listing COMMIT point (the run loop's announce mirror sites) —
+     * an append failure degrades to the checkpoint-mirror/transcript-probe rungs, never fails the run.
+     */
     appendAnnouncedListing(snapshot: {
         agents?: readonly string[];
         skills?: readonly string[];
         models?: readonly string[];
     }): Promise<string>;
+    /**
+     * design/155 (cli [1580]): persist the settle-time workspace state (tracked cwd + active
+     * EnterWorktree session) as a first-class typed entry. Called best-effort at task settle when the
+     * state changed — an append failure degrades to "the next turn starts at the task root", exactly
+     * the pre-155 behavior, never fails the run. The same shape gate guards append, read, and the
+     * import door (self-generated data must round-trip its own validator).
+     */
     appendWorkspaceState(state: WorkspaceState): Promise<string>;
+    /**
+     * design/155: recover the workspace-state snapshot for the ACTIVE branch — the nearest
+     * `workspace_state` entry walking back from the leaf (SNAPSHOT semantics: first hit wins; a CLEAR
+     * snapshot — no cwd, no worktree — is a real hit that shadows older state). Malformed entries are
+     * skipped (defense in depth behind the import door). Undefined ⇒ no snapshot VISIBLE on this
+     * branch: a fresh session, a pre-155 session, or a bounded-tail backend whose load floor cut every
+     * snapshot — all degrade to fresh defaults (the task root), the pre-155 behavior. Rewind gets the
+     * correct semantics for free: the branch path ends at the cut, so the walk finds the state that
+     * was current THEN.
+     */
     getWorkspaceState(): Promise<WorkspaceState | undefined>;
+    /**
+     * design/150 (RB-25): recover the announced listing snapshot for the ACTIVE branch — the nearest
+     * carrier walking back from the leaf (an `announced_listing` entry or a compaction's
+     * `details.announcedListings` restatement; SNAPSHOT semantics: first hit wins). Malformed
+     * carriers are skipped (defense in depth behind the import door), never returned.
+     * Undefined ⇒ no carrier VISIBLE on this branch — callers fall back to the checkpoint mirror /
+     * transcript probe. Honest bound (codex 1358 F2, RB-33): a bounded-tail backend whose load floor
+     * cut every carrier (and a rewind cut between the floor and the newest compaction) also returns
+     * undefined — the ladder degrades to the lower rungs (worst case a duplicate re-announce, never a
+     * loss). A floor-anchor seam (the getEpochAnchor analog) is deliberately deferred until a real
+     * deployment hits that window.
+     */
     getAnnouncedListing(): Promise<{
         agents?: string[];
         skills?: string[];
         models?: string[];
     } | undefined>;
+    /**
+     * Recover the pinned prompt epoch for the ACTIVE branch (campaign S3). Walks the branch from the
+     * leaf backwards: the nearest `compaction` entry's `details.promptEpoch` restatement wins (the
+     * bounded-tail/F3 floor may have cut everything older); else the nearest `prompt_epoch` entry
+     * (root pin / legacy migration). Undefined ⇒ pre-epoch session (upgrade-in-place migration path).
+     * Rewind/resumeAt legs get the SAME semantics for free: the branch path already ends at the
+     * historical cut point, so the walk finds the pin that was current THEN, not the latest.
+     */
     getPromptEpoch(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
+    /**
+     * RB-103 (2026-07-25, defect probe): the compaction entry CARRIES the branch's derived conversation
+     * state — thinking level and active model — restated automatically here.
+     *
+     * Both are reconstructed by scanning path entries ({@link buildSessionContext}), so a bounded-tail (F3)
+     * wake that loads only `[firstKeptEntryId .. leaf]` cannot see a `thinking_level_change` /
+     * `model_change` that sits below the floor: the user's chosen thinking level silently reverted to "off"
+     * and the model to null. Until RB-95 the compaction cut point's back-off loop happened to drag those
+     * entries above the floor much of the time — an accident, not a mechanism, and one that broke the
+     * floor's own "always a user/assistant message" contract to do it.
+     *
+     * Unlike `promptEpoch` / `announcedListings` — which the CALLER restates because selecting them needs
+     * caller-side logic — these two are derived from this session's own branch, so the session computes
+     * them itself and every caller of `appendCompaction` gets the carry for free. A caller-supplied
+     * `details` still wins if it names the same keys (explicit intent beats the automatic restatement).
+     */
     appendCompaction(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: unknown, fromHook?: boolean): Promise<string>;
+    /** Append a non-LLM transcript marker for harness-specific state. */
     appendCustomEntry(customType: string, data?: unknown): Promise<string>;
+    /** Append harness-specific content that can also be replayed into model context. */
     appendCustomMessageEntry(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: unknown): Promise<string>;
+    /** Record or clear the display label for an existing session entry. */
     appendLabel(targetId: string, label: string | undefined): Promise<string>;
     appendSessionName(name: string): Promise<string>;
 }

package/dist/engine/session/storage-base.d.ts

@@ -1,4 +1,5 @@
 import { type LeafEntry, type SessionMetadata, type SessionStorage, type SessionTreeEntry, type SessionWriteOptions } from "../harness/types.js";
+/** Return the effective branch leaf after applying a session tree entry. */
 export declare function leafIdAfterEntry(entry: SessionTreeEntry): string | null;
 export declare abstract class BaseSessionStorage<TMetadata extends SessionMetadata = SessionMetadata> implements SessionStorage<TMetadata> {
     private readonly metadata;
@@ -10,11 +11,18 @@ export declare abstract class BaseSessionStorage<TMetadata extends SessionMetada
     protected constructor(metadata: TMetadata, entries: SessionTreeEntry[], leafId?: string | null, opts?: {
         floorEntryId?: string | null;
     });
+    /** The bounded-window root this storage was woken with, or null for a full-tree load (F3). */
     getFloorId(): string | null;
     getMetadata(): Promise<TMetadata>;
     getLeafId(): Promise<string | null>;
     protected createLeafEntry(leafId: string | null): LeafEntry;
     createEntryId(): Promise<string>;
+    /**
+     * Optimistic-lock check (F2). Throws `SessionError("conflict")` when `opts.expectedLeafId` is
+     * provided and does not match the current in-memory leaf. Concrete `appendEntry`/`setLeafId`
+     * implementations call this before persisting; durable backends should instead perform the same
+     * check atomically against shared state (a conditional write) so concurrent instances can't fork.
+     */
     protected assertExpectedLeaf(opts?: SessionWriteOptions): void;
     protected recordEntry(entry: SessionTreeEntry): void;
     getEntry(id: string): Promise<SessionTreeEntry | undefined>;

package/dist/fixtures/index.d.ts

@@ -1,7 +1,43 @@
+/**
+ * `@sema-agent/core/fixtures` — GOLDEN SHAPE fixtures for downstream consumers (server/SDK/cli),
+ * the L2 layer of the [1549] anti-drift defense: downstream tests consume THESE shapes instead of
+ * hand-building requests/frames, so an upstream shape change breaks a test instead of shipping a
+ * silent mismatch (the [1546] "bare req = false-green pins" class).
+ *
+ * CONTRACT — shape truth, not value truth:
+ *  - Every volatile value is NORMALIZED to an angle-bracket placeholder (`"<issuing-session-id>"`,
+ *    `"<tool-call-id>"`, …). Downstream asserts KEY SETS and SHAPES (optionality, nesting, enum
+ *    membership), never placeholder values.
+ *  - Each fixture is PINNED against the live engine by test/fixtures-golden.test.ts: the pin runs
+ *    the real code path (a real gate, a real delegated child), captures the real object, applies
+ *    the same normalization, and requires deep equality with the fixture. A shape change upstream
+ *    turns THAT pin red first — the fixture can never drift from the engine.
+ *  - Additions here are additive API: removing/renaming a fixture key is a downstream-visible
+ *    BREAKING change and belongs in the release notes' frame-shape section ([1552] L1.5).
+ */
 import type { AskRequest } from "../core/tool-policy.js";
+/** The normalization placeholders used across all fixtures (downstream may match on the form). */
 export declare const FIXTURE_PLACEHOLDER_RE: RegExp;
+/**
+ * AskRequest, HOST form — the shape a live `onAsk` approver receives when the HOST task's own
+ * gate raises a permission ask. Key facts downstream must not re-derive by guessing ([1546] MED-1):
+ *  - `sourceTaskId` is PRESENT on host asks too (always the issuing task's session id) — it is
+ *    NOT a subagent discriminator;
+ *  - `fromSubagent` / `sourceAgentName` are ABSENT on host asks (design/153 §1: `fromSubagent`
+ *    is THE discriminator);
+ *  - `principal` is absent unless the deployment sets TaskSpec.principal.
+ */
 export declare const ASK_REQUEST_HOST: AskRequest;
+/**
+ * AskRequest, DELEGATED-SUBAGENT form — the shape the approver receives when a delegated child's
+ * gate raises the ask (bubbled through the inherited chain or the child's own caller slot):
+ *  - `fromSubagent: true` — the explicit, unforgeable discriminator (1.378);
+ *  - `sourceAgentName` — display identity (UNTRUSTED-for-display; redact + bound before render);
+ *    present only when the spawn named the child (an unnamed child omits it);
+ *  - `sourceTaskId` — the CHILD's session id (≠ the host's).
+ */
 export declare const ASK_REQUEST_SUBAGENT: AskRequest;
+/** Both AskRequest forms, keyed for iteration in downstream key-set diff gates. */
 export declare const ASK_REQUEST_FIXTURES: {
     readonly host: AskRequest;
     readonly subagent: AskRequest;

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * sema-core — a stateless, task-oriented AI agent core distilled from openclaw.
+ *
+ * Bring your own brain (an OpenAI-compatible model gateway), define tools / MCP servers
+ * per task, and run single-agent tasks against in-memory sessions with zero-config
+ * auto-compaction.
+ */
 export { Runner, runTask } from "./core/runner/runtask.js";
 export { resolveTaskLimits } from "./core/runner/prepare-task.js";
 export type { BudgetAxis } from "./core/runner/assemble-result.js";
@@ -33,7 +40,6 @@ export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf, type CacheFamily
 export { emitTrace, type ToolDisclosureManifest, type TraceEvent, type TracerHook } from "./core/trace.js";
 export { InMemoryStrategyStore, type StrategyStore, type StoredStrategy } from "./core/strategy-store.js";
 export { createSqlTool, validateReadOnlySql, type SqlToolOptions } from "./tools/sql.js";
-export { createGiteaIssueTool, type GiteaIssueToolOptions } from "./tools/gitea-issue.js";
 export { runWithTeacher, parseTeacherAdvice, TEACHER_PROMPT, type TeacherConfig, type TeacherAdvice, type EscalationRecord, type EscalationTrigger, type TeacherRunResult, } from "./agents/teacher.js";
 export { runWithVerification, resumeWithVerification, verifyCompleted, runDeveloperTask, VERIFICATION_PROMPT, STATIC_VERIFICATION_PROMPT, VerdictSchema, type Verdict, type VerifyConfig, type UnverifiedReason, type VerificationOutcome, type VerificationResult, type DeveloperTaskConfig, } from "./agents/verify.js";
 export { runRepairLoop, terminalForTier, repairBundleFromCheckpoint, isolationPermitsAutoAccept, type OracleTier, type RepairTerminal, type OracleResult, type RepairOracle, type RepairBundle, type RepairLoopConfig, type RepairResult, } from "./agents/repair-loop.js";
@@ -127,6 +133,15 @@ export { parseAutoModeResponse, createAutoModeDecider, type AutoModeVerdict, typ
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, type AutoModeRules, type BuildAutoModePromptOptions, type AutoModeWindowOptions, } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";
 export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRule, wildcardMatch, type PermissionRule, type ParsedPermissionRule, type PermissionRuleIssue, type PermissionRuleCaps, type PermissionRulePolicyOptions, } from "./core/permission-rules.js";
+/**
+ * design/179 — persisted ALLOW rules: the standing form of approvals a person already gave.
+ *
+ * Note what is NOT here. `PermissionRuleWriter` is core-private and never exported, so a deployment has
+ * no API path that puts a rule in the store; every rule that enters through the engine comes out of the
+ * consent protocol below (a durable approval record, an authenticated confirmation, a principal-bound
+ * redemption). Removal is exported without that ceremony, because narrowing on a user's behalf is allowed
+ * and widening is not.
+ */
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedAllowRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleSuggestion, type RuleReject, type RuleRejectCode, type ParsedAllowRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, } from "./core/permission-rule-store.js";
 export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";

package/dist/index.js

@@ -29,7 +29,6 @@ export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf } from "./core/run
 export { emitTrace } from "./core/trace.js";
 export { InMemoryStrategyStore } from "./core/strategy-store.js";
 export { createSqlTool, validateReadOnlySql } from "./tools/sql.js";
-export { createGiteaIssueTool } from "./tools/gitea-issue.js";
 export { runWithTeacher, parseTeacherAdvice, TEACHER_PROMPT, } from "./agents/teacher.js";
 export { runWithVerification, resumeWithVerification, verifyCompleted, runDeveloperTask, VERIFICATION_PROMPT, STATIC_VERIFICATION_PROMPT, VerdictSchema, } from "./agents/verify.js";
 export { runRepairLoop, terminalForTier, repairBundleFromCheckpoint, isolationPermitsAutoAccept, } from "./agents/repair-loop.js";

package/dist/internal/harness-types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Pure-type re-exports split out of harness.ts (S1, design/157) — see harness.ts for the full
+ * design/33 + design/118 facade narrative. This file exists to break an engine-import SCC: consumers
+ * that only need harness types (not the NodeExecutionEnv value export) import from here instead, so
+ * their compile-time dependency graph never has to reach the value side of the facade.
+ */
 export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/compaction/compaction.js";
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";

package/dist/internal/harness.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Internal boundary to the engine's harness layer (design/33; de-vendored by design/118). Everything
+ * in `src/` (outside `src/internal/`) imports these symbols from HERE, never via a deep
+ * `../engine/...` path — one auditable coupling point (CI-guarded by test/vendor-insulation.test.ts).
+ * The vendored tree this facade used to front is fully retired (design/118 ⓪-⑤); the facade stays so
+ * consumers never notice which module a symbol lives in.
+ *
+ * Pure-type re-exports live in ./harness-types.js (S1, design/157) — split out to break an
+ * engine-import SCC for type-only consumers. Re-exported here too so existing `harness.js` imports
+ * keep working unchanged.
+ */
 export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";

package/dist/internal/llm.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Internal boundary to the llm layer (design/33). Everything in `src/` (outside `src/internal/`)
+ * imports these symbols from HERE, never via a deep path — one auditable coupling point (CI-guarded).
+ * design/118 ①②: the layer is now first-party (`src/engine/llm/`, naturalized out of the vendored
+ * llm-core); the facade stays so consumers never notice which side a symbol lives on.
+ */
 export { createAssistantMessageEventStream, snapshotActorAssertion, stripEngineMetadata } from "../engine/llm/index.js";
 export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";