@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/session-policy-store.d.ts

@@ -1,35 +1,126 @@
+/**
+ * design/99 §E6 — per-session permission rules: a durable, session-scoped policy narrowing folded into the
+ * task-time {@link import("./tool-policy.js").ToolPolicy} (see {@link import("./runner/session-rule-policy.js").createSessionRulePolicy}).
+ *
+ * Why core-owned (not a parallel service store): the rules must be ENFORCED by the same policy fold that runs
+ * every tool call, so storage and enforcement can't drift (the [210] capability-token invariant). core defines
+ * the seam + an InMemory default; a deployment supplies a DURABLE cross-replica backend (its CAS-rev semantics
+ * must match this InMemory one byte-for-byte — a cross-backend equivalence test is the contract).
+ *
+ * Safety model:
+ * - **tighten-only by default**: a NORMAL write may only ADD denies / NARROW allowlists / NARROW allowDirs. A
+ *   write that LOOSENS (removes a deny, widens an allowlist/allowDirs) is REFUSED unless it is an OPERATOR
+ *   write. core has NO role system — `operator` is a boolean the caller FREEZES from a verified principal
+ *   (mirrors `steer.trusted`); core never adjudicates operator-ness, it only honors the flag.
+ * - **CAS rev** (optimistic concurrency): a `putRules` with a stale `expectedRev` is rejected, so two replicas
+ *   can't lose an update (mirrors the checkpoint store's `resolve` OCC).
+ * - **structured fields only**: core interprets `toolAllow/Deny`, `allowDirs`, `commandAllow/Deny` (argv[0]
+ *   names). A richer rule DSL is the service's/profile's job — core grows no rule interpreter.
+ * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` bypass);
+ *   the real isolation boundary is the executionEnv, never these rules.
+ */
+/** The structured per-session rules. All optional; an absent field imposes no constraint of that kind. */
 export interface SessionPermissionRules {
+    /** If set, ONLY these tool names are allowed (others denied). A narrowing allowlist. */
     toolAllow?: string[];
+    /** Tool names always denied (deny wins). */
     toolDeny?: string[];
+    /** If set, WRITE tools (`write_file`/`edit_file`) may only target paths within these dirs; a write-capable
+     *  tool that can't be path-confined (e.g. `bash`) is denied while this is set. Stored RAW; resolved at run time. */
     allowDirs?: string[];
+    /** If set, ONLY these `bash` command names (argv[0]) are allowed. */
     commandAllow?: string[];
+    /** `bash` command names (argv[0]) always denied. */
     commandDeny?: string[];
 }
+/** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
 }
+/** Options for {@link SessionPolicyStore.putRules}. */
 export interface PutRulesOptions {
+    /** CAS: reject the write if the stored `rev` is not this (optimistic concurrency). Omit to skip the check. */
     expectedRev?: number;
+    /** When true, this write MAY loosen the rules (remove a deny / widen an allowlist or allowDirs). A NORMAL
+     *  (non-operator) write is TIGHTEN-ONLY. core does NOT verify operator-ness — the caller (service) FREEZES
+     *  this from a verified, role-checked principal (mirrors `steer.trusted`). */
     operator?: boolean;
 }
+/** Typed error from {@link SessionPolicyStore.putRules}. `conflict` = stale `expectedRev`; `loosen_forbidden`
+ *  = a non-operator write tried to relax the rules. */
 export declare class SessionPolicyError extends Error {
     readonly code: "conflict" | "loosen_forbidden";
     constructor(code: "conflict" | "loosen_forbidden", message: string);
 }
+/**
+ * The seam a deployment implements for DURABLE, cross-replica per-session rules. Unset on `RunnerDeps` ⇒ the
+ * feature is OFF (no rules read, zero behavior change). Keyed on `(sessionId, principal-owner)`: core passes
+ * the running task's `principal` as the owner key; ownership/operator AUTHORIZATION is the implementation's job
+ * (core has no identity system). `getRules` returns the rules to ENFORCE for a task; `putRules` writes them.
+ */
+/** A (principal, rules) pair for one session — the unit {@link SessionPolicyStore.listBySession} returns. */
 export interface SessionRulesRecord {
+    /** The principal these rules apply to (undefined = the session-wide default). */
     principal: string | undefined;
     rules: StoredSessionRules;
 }
 export interface SessionPolicyStore {
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
+    /**
+     * 2c session-sync ([271]): every (principal, rules) record for `sessionId` across ALL principals — `getRules`
+     * is per-(sessionId, principal), but a cross-backend session EXPORT must bundle the WHOLE session's policy.
+     * The importer replays each via `putRules(sessionId, record.principal, record.rules)`. Optional — a backend
+     * that supports cross-backend policy export implements it (local backend uses the in-memory/file impl).
+     */
     listBySession?(sessionId: string): Promise<SessionRulesRecord[]>;
+    /**
+     * 2c session-sync, the ERASE half (server C1b, 2026-07-26): remove EVERY (principal, rules) record for
+     * `sessionId`. An importer that OVERWRITES a session must be able to erase the abandoned branch's policy
+     * rows — without this seam they survive the overwrite and keep enforcing the old branch's rules against
+     * the new content. Optional like {@link listBySession} (a sync-capable backend implements both); the two
+     * bundled impls do. Idempotent: deleting a session with no records is a no-op.
+     */
     deleteBySession?(sessionId: string): Promise<void>;
 }
+/**
+ * LEXICAL path containment for the tighten gate. **Must agree with the runtime's view of what a dir IS** (the
+ * runtime resolves `..`/`.`/`//` via `canonicalizeTarget`): both args are `posix.normalize`d FIRST so a
+ * non-operator can't smuggle a write-confinement OUTSIDE the prior dir by writing `<prior>/../etc` — which is
+ * lexically "within `<prior>`" by a naive `startsWith` but canonicalizes to `/etc` at run time (the tighten
+ * gate must never UNDER-report a loosening).
+ *
+ * The `..`-resolving `posix.normalize` pass is THIS function's own job (the tighten gate's `..`-smuggling
+ * defense above) and is NOT shared with the runtime's `isWithin` (session-rule-policy.ts), which compares
+ * already-canonicalized keys and never resolves `..` itself — the two functions agree on every OTHER input
+ * (same win-family fold, same prefix semantics) but diverge on inputs that still carry an unresolved `..`,
+ * which is exactly the tighten-gate-only case this function exists to catch.
+ *
+ * RESIDUAL (documented, bounded): the gate is LEXICAL and cannot follow symlinks at write time, while the
+ * runtime IS symlink-aware. A stored allowDir whose LAST component is a pre-existing symlink to outside the
+ * prior set would be seen as "within" by this gate yet resolve elsewhere at run time. This is bounded: while an
+ * `allowDirs` confinement is active the runtime DENIES `bash` (non-path-confinable), so a confined non-operator
+ * cannot CREATE such a symlink — it must pre-exist on the deployment's filesystem. Operators / the durable
+ * backend should keep `allowDirs` to real directories; a future symlink-aware write-time canonicalize closes it.
+ */
 declare function lexWithin(root: string, p: string): boolean;
+/** Normalize a rules object's `allowDirs` (lexical `posix.normalize`) so stored rules are `..`-free and the
+ *  tighten diff compares the same canonical-ish form the runtime resolves. */
 export declare function normalizeRules(rules: SessionPermissionRules): SessionPermissionRules;
+/**
+ * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op).
+ * Direction per field — deny-lists: removing an entry loosens. allowlists: removing the list (→ everything
+ * allowed) or adding an entry outside the prior set loosens; prior-undefined → any defined next only narrows.
+ * allowDirs: removing confinement, or adding a dir not within some prior dir, loosens (coarse raw containment).
+ */
 export declare function loosenReasons(prior: SessionPermissionRules, next: SessionPermissionRules): string[];
+/** strip any caller-passed `rev` from a rules object so the store is the sole authority on it. */
 export declare function stripRev(rules: SessionPermissionRules): SessionPermissionRules;
+/**
+ * In-process default {@link SessionPolicyStore} (single-replica). A deployment that needs cross-replica
+ * durability supplies its own backend with the SAME CAS-rev + tighten-only semantics. Single-threaded JS makes
+ * the read-check-write trivially atomic here; a durable backend folds it into a CAS WHERE clause.
+ */
 export declare class InMemorySessionPolicyStore implements SessionPolicyStore {
     private readonly map;
     private key;
@@ -38,6 +129,9 @@ export declare class InMemorySessionPolicyStore implements SessionPolicyStore {
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
     deleteBySession(sessionId: string): Promise<void>;
 }
+/** Test-only escape hatch for the module-private tighten-gate containment predicate (mirrors the
+ *  `__testables` convention in file-snapshot-store.ts) — lets a regression pin the fold's win-family
+ *  conditionality directly rather than only through `loosenReasons`'s allowDirs branch. */
 export declare const __testables: {
     lexWithin: typeof lexWithin;
 };

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

@@ -1,19 +1,99 @@
 import type { AgentMessage } from "../internal/harness-types.js";
 import type { Session } from "./session.js";
 import type { ToolEffect } from "./types.js";
+/**
+ * Wake/resume side-effect reconciliation.
+ *
+ * Problem (design/07 · C3): a task can be interrupted (crash, kill, timeout, lost instance) in the
+ * window between an assistant message with tool calls being persisted and that turn's tool results
+ * being flushed. The session event log then ends with one or more **orphan tool calls** — a tool
+ * call with no matching `toolResult`. On wake this is two bugs at once:
+ *   1. Most chat APIs reject a request whose assistant tool_call is not followed by a tool result.
+ *   2. The tool's `execute` may already have run (the side effect happened) — or may not have. The
+ *      outcome is genuinely unknown.
+ *
+ * Contract enforced here:
+ *   - **Never auto-replay a tool.** Reconstruction (`buildSessionContext`) already does not re-run
+ *     tools; this guarantees we also never synthesize a "success" that hides an unknown outcome.
+ *   - For each orphan, append a synthetic `toolResult` (isError) that tells the model the call was
+ *     interrupted and its outcome is unknown — making the transcript API-valid AND handing the
+ *     decision to the model under its verification discipline.
+ *   - Use the tool's {@link ToolEffect} to tune the message: `read` carries no risk at all; `idempotent`
+ *     is replayable (re-issuing converges the state, but the interrupted attempt may have partially
+ *     landed — RB-221 [1937]); `write` (and unknown tools, conservatively) must be verified/confirmed
+ *     before repeating.
+ *
+ * This runs on `acquire` of a resumed session, before the next turn starts. New/empty sessions and
+ * cleanly-finished sessions have no orphans and are left untouched.
+ */
+/** One broken half of a tool call/result pair in the active branch (see {@link OrphanToolCall.kind}). */
 export interface OrphanToolCall {
     toolCallId: string;
     toolName: string;
+    /**
+     * RB-398-a part 2 (blackboard [2105]): which half of the pair is missing.
+     * - absent (the historical shape) = a **call-orphan**: an assistant `toolCall` with no matching
+     *   `toolResult` — the reconcile-actionable kind ({@link reconcileInterruptedSession} closes it
+     *   with a synthetic interrupted result).
+     * - `"result"` = a **result-orphan**: a `toolResult` with no matching assistant `toolCall` — a
+     *   protocol-invalid context every mainstream chat API rejects. The oracle used to walk only
+     *   assistant→result, so it reported a context in exactly this state as clean while the
+     *   request-time sweeper (`context-guard`'s `dropOrphanToolResults`) was silently deleting the
+     *   result. NOT reconcile-actionable (appending another result would not repair it); consumers
+     *   deciding on repair must filter on this field.
+     * Additive: absent = call-orphan, so pre-existing consumers and persisted expectations are
+     * byte-identical for the historical direction.
+     */
     kind?: "result";
 }
+/** The machine-readable discriminator on a reconcile-appended result — `details.errorKind` on the persisted
+ *  message and `errorCode` on the synthetic `tool_end` frame, so a consumer never parses the text. Two-valued
+ *  (a third value needs a cross-repo slip, see {@link reconcileInterruptedSession}). */
 export type ReconciledErrorKind = "interrupted_never_started" | "interrupted_outcome_unknown";
+/** One orphan closed by {@link reconcileInterruptedSession}, with everything the caller needs to mint the
+ *  matching stream frame WITHOUT re-reading the session. */
 export type RecoveredOrphan = OrphanToolCall & {
+    /** The persisted toolResult entry id (message-identity Phase 1). */
     entryId: string;
+    /** The model-facing text that was persisted — the synthetic `tool_end`'s `output` body. Handed back
+     *  because the caller's frame is otherwise BODY-LESS: a consumer rendering tool output from frames saw an
+     *  empty result for every interrupted call, while the model-facing transcript carried the full
+     *  `[INTERRUPTED]` explanation (the two faces disagreed about the same call). */
     text: string;
+    /** Which of the two honest states this orphan was closed in — the frame's `errorCode`. */
     errorKind: ReconciledErrorKind;
 };
+/** Outcome of reconciling a resumed session. */
 export interface ReconcileReport {
+    /** Orphan calls that were closed with a synthetic interrupted result (empty when nothing to do). `entryId` =
+     *  the persisted toolResult entry id — message-identity Phase 1: the caller emits a `message_committed` for each
+     *  so a consumer's `entryId → message` map stays complete for these reconcile-appended results (they render a
+     *  `tool_end`). They are never a compaction floor (`toolResult` is excluded from cut points), so this is map
+     *  completeness, not `preserved_segment` correctness. */
     recovered: RecoveredOrphan[];
 }
+/**
+ * Find assistant tool calls in `messages` that have no matching `toolResult`.
+ * Order follows first appearance in the transcript (orphans are normally only at the tail).
+ *
+ * `suspendedBatch` (design/45 §15.2 net-add #7): the set of tool-call ids belonging to a **deliberately
+ * suspended** batch (the pending + not-yet-started calls of a durable-checkpoint suspension). These are
+ * NOT orphans — they are waiting to be resumed via `runner.resume()`, not crash-interrupted. Wake-path
+ * reconcile must skip them, or it would append `[INTERRUPTED]` results and **destroy the suspended
+ * batch** (the bug this guard fixes: the wake/resume naming overload became real data destruction).
+ * `runner.resume()` uses a checkpoint-aware entry that bypasses this reconcile entirely for those calls.
+ */
 export declare function findOrphanToolCalls(messages: AgentMessage[], suspendedBatch?: ReadonlySet<string>): OrphanToolCall[];
+/**
+ * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic
+ * interrupted `toolResult` (never re-running the tool). Returns what was recovered.
+ *
+ * @param toolEffects optional name→effect map (from the task's tools). Unknown names are treated as
+ *   `write` — the conservative default, so an unrecognized interrupted call is never said to be safe.
+ * @param startedToolCallIds optional set of tool-call ids whose execution START the caller observed
+ *   during the run being reconciled (the live-abort caller has this knowledge; the wake/crash path
+ *   does not — the previous process is gone). When provided, an orphan absent from the set provably
+ *   never started: it is closed with a "never executed — safe to re-issue" result instead of the
+ *   conservative unknown-outcome wording. When omitted, every orphan keeps the conservative texts.
+ */
 export declare function reconcileInterruptedSession(session: Session, toolEffects?: Map<string, ToolEffect>, suspendedBatch?: ReadonlySet<string>, startedToolCallIds?: ReadonlySet<string>): Promise<ReconcileReport>;

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

@@ -3,41 +3,126 @@ import { type AcquiredSession, type SessionStore, type SessionStoreSummary } fro
 import type { StoreDurability } from "./checkpoint-store.js";
 import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
 export { SESSION_DEFAULT_TTL_DAYS };
+/** What idle-eviction and `release` do to the underlying repo. */
 export type EvictPolicy = "delete" | "forget";
 export interface TtlSessionStoreOptions {
+    /** Idle TTL before a cached session is evicted. Default 7 days. */
     defaultTtlDays?: number;
+    /** Optional background sweep interval (ms). Off by default (sweeps opportunistically on acquire). */
     sweepIntervalMs?: number;
+    /**
+     * Backing session repo. Default `InMemorySessionRepo` (process-only, lost on restart). Supply a
+     * **durable** repo (e.g. a TiDB-backed `SessionRepo`, or the vendored file repo) to persist
+     * sessions: `acquire` then **resumes** an existing session via `repo.open`, so any stateless
+     * runner instance — even after a restart or on another replica — continues the same conversation.
+     */
     repo?: SessionRepo;
+    /**
+     * What idle-eviction and `release` do to the repo:
+     * - `"delete"` — remove the session from the repo too (correct for the throwaway in-memory repo).
+     * - `"forget"` — only drop the in-memory cache; the **durable** backend keeps the history so it can
+     *   be resumed later (the backend runs its own retention/GC).
+     *
+     * Defaults to `"delete"` for the built-in in-memory repo and `"forget"` when a custom `repo` is
+     * supplied — so a durable store never silently deletes history on an idle timer.
+     */
     evict?: EvictPolicy;
+    /**
+     * design/173 §2.3 — the store's {@link StoreDurability} declaration. This cache layer cannot
+     * inspect whether the injected {@link repo} persists across processes, so the DEPLOYMENT that
+     * wired the repo states the fact (e.g. `FileStorageBackend` passes `"durable"`). Defaults:
+     * without a custom `repo` the truth is knowable — `"process-local"` is declared; with a custom
+     * `repo` and no explicit value the store declares NOTHING, which the wiring manifest reads
+     * fail-closed as process-local (under-promise, never over-promise).
+     */
     durability?: StoreDurability;
 }
+/**
+ * TTL-cached {@link SessionStore} over a pluggable {@link SessionRepo}.
+ *
+ * Sessions are cached in process memory and evicted after `defaultTtlDays` of inactivity. With the
+ * default in-memory repo they live only in this process (lost on restart). Supply a **durable** repo
+ * and the same caching/concurrency logic becomes a "session center": on `acquire`, a session not in
+ * the live cache is **resumed from the repo** (`repo.open`) rather than recreated — so a stateless
+ * runner resumes a conversation after a restart or across replicas. The optimistic-lock seam
+ * (`SessionWriteOptions.expectedLeafId` → `SessionError("conflict")`) keeps two replicas writing the
+ * same session safe; the Runner reconciles a lost CAS and retries.
+ *
+ * See `design/10-会话持久化与会话中心.md` for the durable-backend (TiDB) contract.
+ */
 export declare class TtlSessionStore implements SessionStore {
+    /** Managed-retention declaration (ruled 2026-08-05, retention.ts): with a custom repo the default
+     *  evict policy is `forget` — cache eviction only, the durable rows live on — and there is no
+     *  tenant-scoped scheduled-deletion contract on any arm. Honestly `"none"`: a deployment with a
+     *  LOCKED retention policy refuses to start over this store. (The `SessionStore` interface itself
+     *  is declaration-agnostic; the retention face is the structural `RetentionDeclaring` shape.) */
     readonly retention: "none";
+    /** design/173 §2.3 — see {@link TtlSessionStoreOptions.durability} for the declaration rules. */
     readonly durability?: StoreDurability;
     private repo;
     private entries;
+    /** Session-ownership rows (the multi-tenant admission capability face — see SessionStore.ownerOf).
+     *  Deliberately NOT part of `entries`: an evicted-but-durable session (`forget` / evict:"forget")
+     *  still EXISTS, and its ownership row outliving the cache entry is what keeps a live session from
+     *  reading as `undefined` (= re-claimable by anyone). Rows die only when the repo's history does. */
     private owners;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) share one session. */
     private pending;
+    /** Sessions pinned by a design/45 checkpoint — skipped by idle sweep until unpinned (B6/§5). */
     private pinned;
     private defaultTtlMs;
     private evictPolicy;
     private sweepTimer?;
     constructor(opts?: TtlSessionStoreOptions);
+    /** Get an existing session by id (resuming from the repo if needed), or create one. */
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
+    /** Resume an existing session from the repo, or create it if the backend has no such id (unless
+     *  `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
     private openOrCreate;
     private createAndStore;
+    /** Refresh the idle timer for a session. */
     touch(sessionId: string): void;
+    /** Record the most recent task run on a cached session (the `/resume` `lastRunId`); also bumps the idle
+     *  timer. Best-effort — a no-op if the session isn't cached here (the run will still be re-attachable via
+     *  its checkpoint). */
     noteTaskRun(sessionId: string, taskId: string): void;
+    /** List the live cache as {@link SessionStoreSummary} projections, newest-first by `lastActiveAt` (so a
+     *  shell's `/resume` shows recent sessions + their last run first). The in-memory store lists only its
+     *  live cache, not evicted/durable history — a durable backend overrides this to list persisted sessions. */
     list(): Promise<SessionStoreSummary[]>;
+    /**
+     * design/110 (F3) — FORK a session: copy `sourceId`'s committed history into a NEW session and return its id
+     * (or `null` when the source doesn't exist). Delegates to the backing repo's `fork`, so a durable repo persists the
+     * branch; the in-memory repo holds it in-process. Registering the result in this cache makes `acquire(forkedId)`
+     * hit immediately — the synchronous child run that `Agent(subagent_type:"fork")` launches resumes the fork without a repo round-trip.
+     *
+     * Adding this method is what makes {@link hasSessionFork} true for a `TtlSessionStore` wrapping ANY repo, so the
+     * fork capability mounts (it was INERT before — the durable repo had `fork` but the store never exposed it).
+     */
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** Drop a session from the live set. With a durable repo (`evict: "forget"`) the history is kept. */
     release(sessionId: string): Promise<void>;
+    /** Drop only the cached view — the repo keeps the session regardless of `evictPolicy`, so a re-acquire
+     *  re-opens the SAME history (B-17: the reconcile retry / prepare-throw paths must never delete). Cost
+     *  on the default in-memory repo: ONE retained session object **per forgotten id** until process end
+     *  (invisible to `size`/`sweep`, which track the cache) — accumulation across many distinct forgotten
+     *  ids is the accepted trade-off vs silent history loss; deployments with churn use a durable repo,
+     *  where retention is the backend's normal job. A pinned id stays pinned (a forget must never expose a
+     *  suspended task's session to sweep eviction). */
     forget(sessionId: string): void;
+    /** Pin a session so idle sweep can't evict it while a design/45 checkpoint awaits resume (§5). */
     pin(sessionId: string): void;
+    /** Release a design/45 pin (on resume or checkpoint expiry); the session resumes normal idle eviction. */
     unpin(sessionId: string): void;
+    /** Multi-tenant admission capability (see the SessionStore contract for the three-state semantics
+     *  and the first-write-wins requirement — both are load-bearing for the deployment's owner gate). */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
+    /** First-write-wins idempotent upsert; a synchronous Map write is atomic per the contract. Makes no
+     *  authorization decision — the authorizer re-reads {@link ownerOf} and judges there. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** Evict idle-expired sessions from the cache. Deletes durable history only when `evict: "delete"`. */
     sweep(now?: number): void;
     get size(): number;
     dispose(): void;

package/dist/core/session.d.ts

@@ -7,39 +7,192 @@ export { SessionError } from "../internal/harness.js";
 export type { SessionWriteOptions } from "../internal/harness.js";
 import type { Session } from "../internal/harness.js";
 import type { SessionTreeEntry } from "../internal/harness.js";
+/** True when `err` is a session optimistic-lock conflict (a concurrent writer won the branch leaf). */
 export declare function isSessionConflict(err: unknown): boolean;
+/** A session handed back by a {@link SessionStore}: the harness `Session` plus its resolved id. */
 export interface AcquiredSession {
     session: Session;
     sessionId: string;
 }
+/**
+ * A lightweight, read-only projection of one session for a `/resume` list (shell K-5 — re-attach without an
+ * N+1 walk). Returned in bulk by {@link SessionStore.list}, newest-first by `lastActiveAt` by convention.
+ * `lastTaskId` is the engine's term for what the service/wire surfaces as the session's **`lastRunId`** — the
+ * most recent task run on this session, so a shell re-attaches in ONE hop.
+ *
+ * Named `*StoreSummary` (not the bare `SessionSummary` an earlier version used) because that name collided
+ * with an unrelated, differently-shaped `SessionSummary` downstream (the SDK's wire GET /v1/sessions row) —
+ * same name, two shapes, the exact "同名异形" pattern a cross-repo cleanup was independently eradicating
+ * elsewhere (黑板 [1912]/[1913]/[1914]). This type is this store interface's own projection, never itself
+ * serialized onto the wire — a service backend re-projects/renames its fields (`lastTaskId` → `lastRunId`)
+ * when building the actual wire response.
+ */
 export interface SessionStoreSummary {
+    /** The session id. */
     sessionId: string;
+    /** When the session was created ({@link SessionMetadata.createdAt}, ISO string); absent when the backend's
+     *  cache view doesn't carry it. */
     createdAt?: string;
+    /** Epoch ms the session was last acquired / touched / ran — the newest-first sort key for "recent sessions". */
     lastActiveAt: number;
+    /** The most recent task run on this session (core's `taskId`; the service projects it as `lastRunId`).
+     *  Absent until a task has run on the session (recorded via {@link SessionStore.noteTaskRun}). */
     lastTaskId?: string;
+    /** F7 fork-GC seam: the parent session this one was forked from ({@link SessionMetadata.forkedFrom}).
+     *  Lets a consumer render/reap fork lineage; absent on non-forked sessions and on cache views that
+     *  predate the fork. The durable source of truth is the repo's persisted metadata. */
     forkedFrom?: string;
 }
+/**
+ * The session lifecycle/caching layer the {@link Runner} depends on.
+ *
+ * `TtlSessionStore` is the default (in-memory, 7-day idle TTL). Provide a custom implementation
+ * to back sessions with durable, external storage (the "Session center"): `acquire` reconstructs
+ * a session from the persisted event log so any stateless runner instance can resume it.
+ *
+ * Implementations must be safe under concurrent `acquire` of the same id (return one session).
+ */
 export interface SessionStore {
+    /**
+     * design/173 §2.3 — durability declaration (see
+     * {@link import("./checkpoint-store.js").StoreDurability}): whether sessions this store accepts
+     * SURVIVE A PROCESS RESTART. That is the whole claim of this axis — multi-replica
+     * coordination/concurrency is a separate backend property this field does not license (review
+     * fold r1-F2/r2-F3; a single-instance file-backed store declares `"durable"` honestly).
+     * Declaration, never duck-typing (the wiring manifest relays it verbatim — it never sniffs class
+     * names); ABSENT is read fail-closed as `"process-local"` (under-promise, never over-promise).
+     * `TtlSessionStore` over a durable {@link SessionRepo} declares via its `durability` option — the
+     * store cannot inspect the repo's persistence, so the DEPLOYMENT that wired the repo states the
+     * fact.
+     */
     readonly durability?: import("./checkpoint-store.js").StoreDurability;
+    /** Get an existing session by id, or create one (optionally with a caller-supplied id). design/114 Phase3:
+     *  `opts.requireExisting` ⇒ a store MUST fail loud (throw a `not_found` {@link SessionError}) on a genuinely
+     *  missing id rather than create-on-miss — so a reuse-style warm-resume of a gone session errors instead of
+     *  silently starting a fresh empty run. A store that cannot honor it MUST still not silently create (either
+     *  implement the check or reject the option). */
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
+    /** Mark a session recently active (resets idle TTL where applicable). May be async for durable stores. */
     touch(sessionId: string): void | Promise<void>;
+    /** Drop a session from the live set (e.g. a throwaway task). Durable history may be retained by the backend. */
     release(sessionId: string): Promise<void>;
+    /**
+     * Drop only the CACHED view of a session — **never** deletes history (unlike `release`, which with the
+     * in-memory `TtlSessionStore`'s default `evict: "delete"` policy removes the session from the repo too).
+     * The Runner uses this where the intent is "discard a stale view and re-wake", and on a prepare-phase
+     * throw after acquire (audit B-17 + the 1.93.0 throw-cleanup contract gap: calling `release` there
+     * silently DELETED an existing session's whole history on the default store — the re-acquire then
+     * continued on an empty same-id session). **Optional, but custom stores SHOULD implement it**: when
+     * absent the Runner performs NO fallback (it never substitutes `release`, whose contract permits
+     * deletion — B-17 council) — the cached view is simply not dropped, so a persistent reconcile conflict
+     * exhausts its retry budget and propagates instead of risking history. A store whose `release` is
+     * already history-safe can implement `forget = release`.
+     */
     forget?(sessionId: string): void | Promise<void>;
+    /**
+     * Protect a session from idle eviction while a design/45 checkpoint references it (a suspended task
+     * must still be resumable). `pin` before suspend, `unpin` on resume/expiry. **Optional**: a durable
+     * backend that never idle-GCs sessions (service's `tidb-session-store`) implements both as no-ops and
+     * is still safe; only the in-memory `TtlSessionStore` needs a real pin (its `sweep` skips pinned ids).
+     * See design/45 §5 / M3.
+     */
     pin?(sessionId: string): void | Promise<void>;
     unpin?(sessionId: string): void | Promise<void>;
+    /**
+     * Record that a task run STARTED on a session (the Runner calls this at task start, when both ids are
+     * known) so the store can surface it as {@link SessionStoreSummary.lastTaskId} — letting a `/resume` list
+     * re-attach to the most recent run, even one still in-flight or suspended. **Optional + best-effort**: a
+     * store that surfaces no session list may ignore it; it MUST NOT throw. The engine's `taskId` is the
+     * service's `lastRunId`.
+     */
     noteTaskRun?(sessionId: string, taskId: string): void | Promise<void>;
+    /**
+     * Enumerate known sessions as lightweight {@link SessionStoreSummary} projections (newest-first by
+     * `lastActiveAt`) so a shell's `/resume` lists sessions + their last run in ONE call. **Optional**: the
+     * in-memory `TtlSessionStore` lists its live cache; a durable backend lists persisted sessions. A store
+     * that cannot enumerate omits this (the shell then has no session-list affordance — honest degrade).
+     */
     list?(): Promise<SessionStoreSummary[]>;
+    /**
+     * design/110 — FORK a session: copy `sourceId`'s durable history (root→leaf) into a NEW session and return its
+     * id (or `null` if the source doesn't exist). The forked session is independent (writes to it don't touch the
+     * source). Backs CC `/fork` (continue with the parent's full context) AND the inheriting-context subagent fork
+     * (run a child on the fork so it inherits the parent context + shares the prompt-cache prefix). **Optional**:
+     * a store implements it only if it can replay history. `TtlSessionStore` DOES — it delegates to its
+     * {@link SessionRepo} (so {@link hasSessionFork} is true) — BUT the fork is only as durable as that repo:
+     * an in-memory repo forks IN-PROCESS yet loses the copy on restart, while a durable repo (file/pg) makes the
+     * fork survive restart/replica. **Capability presence ≠ durability** — a cross-replica consumer (design/114
+     * warm-resume) MUST wire a durable repo; core cannot verify durability, only fail-loud on a missing source at
+     * fork time (returns `null`). `owner` (if given) scopes the new session for multi-tenant stores, and a store that
+     * also implements {@link register} MUST make the fork's ownership row agree with it — a fork COPIES the source's
+     * history, so the copy must never be weaker than the original: with no `owner` argument the fork inherits the
+     * SOURCE's row (a source with no row mints none, keeping the authorizer's claim branch intact). An EXPLICIT
+     * `owner: null` follows the same inheritance, deliberately: "anonymous" on a copy of an OWNED source would
+     * make that history claimable by anyone — a downgrade this face exists to prevent — so `null` only takes
+     * effect when the source itself is unowned/anonymous. MUST copy the COMMITTED leaf (an in-flight
+     * uncommitted turn of an active source is not included — a fork is a snapshot at the fork point).
+     */
     fork?(sourceId: string, owner?: string | null): Promise<string | null>;
+    /**
+     * Session-ownership capability face (multi-tenant admission — the deployment's authorizer probes for
+     * BOTH methods and runs its owner gate only when they exist; a store without them forces the
+     * deployment into its fail-closed arm, refusing caller-supplied session ids under multi-tenancy).
+     *
+     * `ownerOf` is THREE-state and the states must never collapse:
+     *  - `undefined` — the session has NO ownership row (unknown id): the authorizer claims it for the
+     *    calling principal (or 404s under require-existing).
+     *  - `null` — the session EXISTS and is anonymous (unowned): admitted (single-tenant/dev sharing).
+     *  - `string` — owned: a different principal is refused.
+     *  Collapsing `undefined` into `null` breaks the gate in both directions at once (an unknown id
+     *  reads as an admissible anonymous session; an anonymous session reads as claimable).
+     */
     ownerOf?(sessionId: string): Promise<string | null | undefined>;
+    /**
+     * Idempotent ownership upsert, FIRST-WRITE-WINS and atomic: the first registered owner is kept,
+     * later calls neither overwrite nor throw. Deliberately makes NO authorization decision — the
+     * caller re-reads {@link ownerOf} after registering and judges there (which is exactly why the
+     * first-write-wins read-back must be atomic: a concurrent loser has to SEE the winner's owner on
+     * re-read, or it silently attaches to the winner's session). In-memory synchronous writes satisfy
+     * this trivially; durable implementations need a real uniqueness guarantee, not read-then-write.
+     * The ownership row must never expire BEFORE its session (a live session reading as `undefined`
+     * would be re-claimable by anyone); same-lifetime or longer both satisfy the contract — so a store that
+     * deletes the row when it deletes the history must gate that on the history delete having SUCCEEDED.
+     * An implementation must never store a value that {@link ownerOf} reads back as `undefined` (a row that
+     * EXISTS yet reads as "no row" is permanently claimable and never ownable): a FIRST write whose `owner` is
+     * neither a string nor `null` is refused loudly instead — the no-overwrite-no-throw rule above governs
+     * LATER calls, which stay silent no-ops whatever they carry.
+     */
     register?(sessionId: string, owner: string | null): Promise<void>;
+    /** Number of live/cached sessions (best-effort). */
     readonly size: number;
+    /** Release resources (timers, connections). Best-effort; must not throw. */
     dispose(): void | Promise<void>;
 }
+/** Structural detection: does this store expose the optional {@link SessionStore.fork}? Mounts the fork
+ *  capability only when true (INERT otherwise — mirrors `hasScheduler`/`hasBackgroundShell`). */
 export declare function hasSessionFork(store: SessionStore): store is SessionStore & {
     fork: NonNullable<SessionStore["fork"]>;
 };
+/**
+ * F3 bounded-wake recipe, packaged. Given the **path-ordered** entries of a branch
+ * (root→leaf, e.g. `await session.getBranch(leafId)` or a durable store's leaf-walk),
+ * returns the smallest self-contained tail a stateless runner needs to resume:
+ *
+ *  - `floorEntryId` = the **latest** compaction's `firstKeptEntryId` (null if never compacted),
+ *  - `tail` = entries from that floor to the leaf — i.e. the surviving compaction summary
+ *    plus every message kept after it. Everything before the floor is already folded into
+ *    that summary, so it can stay cold in durable storage.
+ *
+ * Hand the result straight to a floored storage:
+ * `new InMemorySessionStorage({ entries: tail, floorEntryId })` (or your durable equivalent).
+ * `buildContext()` on that is identical to waking from the full tree — see `session-floor.test.ts`.
+ *
+ * Pure and allocation-light: it scans for the last compaction and slices. If the tree was never
+ * compacted (or the floor isn't on this path — shouldn't happen for a real branch) it returns the
+ * full input unchanged with `floorEntryId: null`, so callers can always use the result verbatim.
+ */
 export declare function boundedTail(pathEntries: readonly SessionTreeEntry[]): {
     tail: SessionTreeEntry[];
     floorEntryId: string | null;

package/dist/core/shared-memory/contract.d.ts

@@ -1,4 +1,24 @@
+/**
+ * design/177 — the SharedMemoryStoreProvider conformance suite: the cross-repo acceptance contract a
+ * third-party / deployment-authored provider runs against itself. Same shape as the memory-backend
+ * suite it is modeled on — runner-agnostic (node:assert, zero vitest), a FRESH instance per case, and
+ * an optional `runAssertion` wrapper so a vitest consumer can turn each case into an `it`.
+ *
+ * FIXTURES ARE HANDED IN, not written through the seam. Unlike the entry-transactional backend suite
+ * (which can seed itself through its own patch face), this seam is read-only and has no public write
+ * port at all, so `make` receives the intended contents and returns a provider that reads them back.
+ *
+ * NO CROSS-INSTANCE / CAS CASE — a DECLARED absence, not an omission: a compare-and-set case exists to
+ * cover a write-race axis, and a face with no write channel has no such axis. There is consequently no
+ * skip hook either: every case below is mandatory, so a passing run never means "most of it passed".
+ *
+ * WHAT IS ASSERTED. Only the PROVIDER's own obligations — faithfulness, absence-as-a-value, prefix
+ * completeness, cancellation, isolation. Rendering, pagination, sanitizing and refusal wording are the
+ * engine's job and are covered by the engine's own tests; asserting them here would make a third party
+ * responsible for behavior it does not implement.
+ */
 import type { SharedMemorySnapshot, SharedMemoryStoreInfo, SharedMemoryStoreProvider } from "./types.js";
+/** What an implementation must load into its own storage before returning a provider over it. */
 export interface SharedMemoryFixture {
     state: SharedMemorySnapshot["state"];
     stores: Array<{
@@ -12,6 +32,8 @@ export interface SharedMemoryFixture {
 }
 export interface SharedMemoryStoreContractHooks {
     make: (fixture: SharedMemoryFixture) => Promise<SharedMemoryStoreProvider> | SharedMemoryStoreProvider;
+    /** Wrap each case (vitest `it`, sequential chaining, …). Default: run them sequentially. */
     runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
 }
+/** Run the full conformance suite. Throws (assert) on the first violated clause. */
 export declare function sharedMemoryStoreContract(hooks: SharedMemoryStoreContractHooks): Promise<void>;