@yanlinglabs/winter-runtime-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanlingLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# winter-runtime-sdk
+
+One door over two agent runtimes. A host that wants both the Winter Agent SDK and the official
+Claude Agent SDK talks to this package as a single SDK: the same `query()`, the same `Options`, the
+same closed `SDKMessage` union — plus runtime-selection inputs.
+
+Decision record: WS-00 D19 (2026-09-05). Boundaries that do not move:
+
+- `@yanlinglabs/winter-agent-sdk` stands alone for Winter-only hosts and never learns this package
+  or the official runtime exists.
+- This package is a selector and an adapter, never a translation layer: Options and the message
+  stream pass through verbatim. It owns runtime selection (the D13 rule), the official-SDK adapter
+  (Options template, spool env, supervised spawn proxy, mirror errors, tool aliases and deny floor,
+  builtin-path containment, Winter MCP plugin registration), shared session-store wiring, the
+  cross-runtime handoff barrier with the materialized-resume decoration doors, and the runtime
+  directory plus cross-runtime messaging router.
+- The host vendors all three packages directly (`winter-runtime-sdk`, `winter-agent-sdk`,
+  `claude-agent-sdk`); this package declares the two SDKs as peer dependencies and receives their
+  module instances by injection, so a host that never creates a Claude session never loads the
+  official runtime and no SDK is ever instantiated twice.
+- A `brand` profile flows through unchanged (Winter defaults); Claude Code's own literals stay fixed.
+
+Status: Phase 7b, all four lanes landed and the door routed. The spine (the package scaffold, the
+contract re-export, the `createRuntimeSdk` constructor with its version matrix, the seams, the test
+harness and CI) and the four lanes behind those seams — the official-SDK adapter, the runtime
+directory and messaging router, the store wiring and handoff barrier, and runtime selection — are on
+`main`, with WS-17's eighteen router-owned rows proven and cited in `docs/conformance-rows.md`. See
+`docs/architecture.md` for the ownership map, the pinned interfaces and how this package consumes the
+Winter SDK before its first publish.
+
+---
+
+## The door: `query()` over both runtimes
+
+`RuntimeSdk.query()` routes by the session's DECIDED `RuntimeSelection`, and each leg returns its own
+runtime's handle untouched.
+
+```ts
+// The Winter leg: exactly what it always was. No runtime input, so nothing is decided and nothing
+// is stripped — the caller's own `options` object is forwarded by reference.
+for await (const message of sdk.query({ prompt: "hello" })) { /* SdkMessage */ }
+
+// The official leg: a `claude-agent` selection, plus what only a host can answer.
+const query = sdk.query({
+  prompt: turns,                                  // string, or an AsyncIterable<string>
+  options: {
+    cwd: "/work/repo",
+    provider: { providerId: "anthropic", authRef: { kind: "keychain", account: "anthropic:default" } },
+    runtime: {
+      selection,                                  // the session's PERSISTED choice (D13)
+      official: {
+        sessionId: "s-42",                        // its directory row is `session:s-42`
+        base: minimalOsEnvironmentFrom(process.env),
+        mcpServers: officialMcpServers({ /* … */ }),
+      },
+    },
+  },
+});
+```
+
+**What the host passes, and why the Winter leg needs none of it.** A `winter-agent` session is served
+in-process by an SDK that already reads everything it needs from `Options`. A `claude-agent` session is
+a supervised CHILD PROCESS with a durable row of its own, so the door needs three things `Options` has
+no field for: the **session id** its directory row is addressed by (WS-14 §6 rule 2's record is written
+onto that address, and the messaging registry attaches under it), the **minimal OS environment**
+(WS-14 §3's child env is a REPLACEMENT built from an allowlist — nothing inherits, so nothing is read
+from `process.env` by this package, and a `base` without `HOME` is **refused**, because the runtime
+resolves `os.homedir()` through the OS user database when it is missing and `CLAUDE_CONFIG_DIR` cannot
+scope that), and the **vendored runtime path** (§5.1: never the user's
+installed binary; give it once as `createRuntimeSdk({ vendoredOfficialRuntime })` or per query as
+`options.pathToClaudeCodeExecutable`). Everything else has a default that is either derived from the
+brand or read from the pinned contract you already fill in: credentials come from
+`options.provider.authRef` through your own `KeychainSeam`, the spool from the resolved Winter home,
+the session store from the one shared instance both branches use.
+
+**What `SessionKey` a door-opened session has.** `sdk.handoff(session, to)` and every store-facing API
+take a `SessionKey`, and both halves of it are chosen by the door rather than by you: `projectKey` is
+the transcript project key the door set on the child (see "the transcript key" below) and `sessionId`
+is the **backend uuid the vendor allocated**, not `runtime.official.sessionId`. The door records that
+uuid on the session's directory row as `backendSessionId` the moment the runtime reports it at
+`system/init`, so
+`sdk.handoff({ projectKey, sessionId: (await sdk.directory.get("session:s-42"))!.backendSessionId! }, "winter-agent")`
+is the route. WS-15 §6.2's cold resume of an exited official session reads the same field.
+
+**The transcript key** (R-7b-13). The official child is given
+`CLAUDE_CODE_PROJECT_DIR_NAME`, and it defaults to the Winter SDK's own
+`transcriptProjectKey(options.cwd)` — read off the peer you injected, never re-derived — so both
+branches write under one project directory for one working directory, and the auto-memory directory
+(WS-14 §2's ONE shared directory) derives from the same key. It is also the `projectKey` half of the
+`SessionKey` above. **The pinned runtime validates that variable against `^[A-Za-z0-9_-]{1,64}$` and
+silently substitutes its own cwd-derived name when it does not match**, so the door refuses a key it
+would reject — including its own default — rather than letting the row, the environment and the memory
+directory name a transcript that is somewhere else. Two consequences for a host: a deep working
+directory (a sanitized path over 64 characters) needs an explicit short `runtime.official.projectKey`,
+and the vendor's own fallback key is built from the **realpath** of `cwd` (`/private/var/…` on macOS)
+while `transcriptProjectKey` takes the path as given — so pass the key explicitly rather than relying
+on either default when the two could differ.
+
+**What the persisted selection means.** `runtime.selection` is "what this session's record says", so a
+selection that DISAGREES with the record is a request to change runtime — and D13 answers that with
+the certified handoff (`sdk.handoff(session, to)`) or a visible fork, never by serving the new runtime
+on the old transcript. The door refuses with `RuntimeHandoffRequiredError`: in-process on both legs
+(pass `runtime.sessionId` so it can hold you to it) and, on the official leg, against the DURABLE
+directory row before a credential is read or a child spawns. On a session with no record yet, the
+decided selection is PERSISTED at creation, by the door.
+
+**What each leg returns.** The Winter peer's `Query` on one side and the official SDK's own `Query` on
+the other — verbatim, both of them. They are different types (the Winter handle carries `messaging`
+and `listModelFamilies`; the official one carries a dozen members this package deliberately never
+names on its published surface), so `query()` is overloaded: a call with **no** `options.runtime` can
+only reach the Winter leg and is typed `Query`, and a call that passes one is typed
+`Query | OfficialQuery`. `isOfficialQuery(handle)` narrows it. On the official leg the launch happens
+at the FIRST PULL — the same lazy spawn the vendor's own `query()` performs — because WS-14 §12's
+"credentials are fetched at spawn" is asynchronous and `query()` returns a handle rather than a
+promise for one; `close()` before the first pull starts nothing at all.
+
+**A live session's input stream is how messages reach it.** R-7b-4: delivery into a live session of
+either runtime is a push into that session's input stream. Pass an `AsyncIterable<string>` prompt and
+the door owns that stream — your turns and the router's deliveries interleave in order, with your own
+backpressure preserved — and the session is attached to `sdk.messaging` as a live receiver. Pass a
+**string** prompt and the vendor runs one turn and exits: the session is still recorded in the
+directory, but there is nothing to push into, so it is not attached and delivery to it answers
+`unavailable` rather than pretending.
+
+**A session's END is recorded too**, and it changes what a delivery gets. When the message stream
+completes (or `close()` runs) the door detaches the handle, closes the stream and records the row
+`exited` — `unavailable` on a stream that ended in a fault. So a streaming session whose input has
+ended answers **`unavailable` (non-retryable)** exactly like a string-prompted one, never
+`delivery_uncertain`: "the write may have landed" is not an honest answer for a session where nothing
+can land. `sdk.messaging.listReachable` stops listing a session at the same moment (WS-10 §10.2: a
+listing does not enumerate exited transcripts), and a launch that refuses synchronously leaves no row
+at all.
+
+**The official branch disables the runtime's remote feature configuration by default** (R-7b-11).
+Every official child gets `TRAFFIC_OPT_OUT_VARIABLES` — the four names are exported, so read them
+rather than trusting this sentence. Measured on the pin, same binary and same options: 25 advertised
+tools with the fetch, 21 without; `DesignSync`, `Monitor`, `PushNotification` and
+`advisor_20260301:advisor` appear only when a CDN answers. A tool surface that moves with no version
+moving is not a pinned artifact, so this is on unless you say otherwise: `remoteConfig: "allow"` (per
+query on `runtime.official`, or deployment-wide on `createRuntimeSdk({ official: { env: { … } } })`)
+opts back in, and the choice is recorded on the session's directory row as
+`RuntimeDirectoryEntry.remoteConfig`.
+
+**The materialized-resume PREFERRED door is open for the pinned runtime, by measurement** (R-7b-12).
+WS-17 §8's four probes pass against 0.3.250 on darwin-arm64 and linux-x64, so a handle over that peer
+decorates the materialized copy and leaves the canonical file byte-pure; any other version — or no
+official peer — gets the always-available FALLBACK door (one labelled entry appended after the
+destination confirms). The verdict is data (`materializedResumeReportForPin`), keyed by version and
+re-derived in CI against the real artifact, so a pin bump is a reviewed event rather than an inherited
+answer. A host that measured its own pin passes `handoff: { decorationReport }` and wins.
+
+---
+
+## What a host needs to know before wiring this
+
+Each of these is behaviour you cannot discover from the type signatures, and each has a test behind
+it. They are stated here because a host that learns them from an incident learns them expensively.
+
+**Inbound messaging to an official session is FAIL-CLOSED until you wire a permission class.** WS-10
+§13 decides delivery from the sender's and receiver's permission classes, and the official runtime
+exposes no way to read its own. So `official.permissionClass` — passed as
+`createRuntimeSdk({ messaging: { messaging: { official: { permissionClass } } } })` — is the ONLY way
+that class is ever known, and without it **every message to every official session is HELD**, never
+delivered. The hold is *default-kind*: it is released the moment the class becomes knowable, and it
+expires under §13's five-minute dialog window. Two things follow that you should design for: **the
+expiry sweep is LAZY** — a held message's receipt is rewritten to `refused` when something next
+addresses that receiver, not on a timer of its own, so between the fifth minute and the next send the
+receipt still reads `held`; and **a hook that throws is an answer, not a crash** — it falls through to
+`unknown`, which holds.
+
+**Session-name leases are global by construction.** A display name that has been used is remembered
+after the object is gone, so addressing it earns "that referred to something that has gone" rather
+than "no such agent" (WS-10 §11 rule 5). Rule 5 governs children within their owning conversation;
+sessions are global. Nothing forgets by itself: `RuntimeDirectoryOptions.retention` is where you set
+how long a released lease and a receipted delivery record survive, and **absent means forever**,
+because forgetting a lease changes what a model is told about a name it can no longer reach.
+
+**The containment floor is a scan, not a sandbox.** The pre-hoc permission floor refuses any call
+whose ARGUMENTS name a forbidden target (`CLAUDE.md`, `.claude/`, `~/.claude/plans`), case-folded and
+NFKC-normalized for path fields and quote-stripped for command text. **Shell-escape and constructed
+name spellings are caught POST-HOC**, by a sweep registered on `PostToolUse`, `PostToolUseFailure`
+and `PostToolBatch` that snapshots the forbidden names under the session's cwd and the child's HOME,
+removes what APPEARED under its roots during the call, records a typed breach and ends the turn — its
+diff is TIME-BASED rather than causal, so under the child's HOME a vendor home created by something
+else during a long call is removed and attributed to that call (narrow: an existing one is in every
+baseline and is never touched). The sweep walks both
+roots to a bounded depth (6 by default) around every filesystem-touching call, so **it costs a walk
+per call**: on a large tree that is the dominant cost of the floor, and an incremental/fs-events
+design is the follow-up. It sees the synchronously-visible effects of the call it brackets; a
+background write that lands later is caught opportunistically by the next swept call.
+
+**A host `PreToolUse` hook that answers `allow` makes 0.3.250 skip `canUseTool` for that call.** The
+floor runs first and any deny wins, so containment is unaffected — but your broker will not see that
+call, which matters if you were counting on it for audit.
+
+**The extras door is a positive allowlist with two closed escape hatches.** `configuredExtras` admits
+only names the pinned artifact's own environment registry declares AND that an independent rule
+classifies as non-credential; anything auth-shaped is refused with a sentence naming why, and a
+deployment that has REVIEWED a specific credential-shaped variable names it in
+`reviewedCredentialShapedExtras` — one name at a time, never a wildcard.
+
+A second class is refused **by name**, and the set is exported so you can read it rather than trust a
+description: `EXECUTION_INDIRECTION_ENV_NAMES` and `EXECUTION_INDIRECTION_ENV_PREFIXES`
+(`src/official/`). It is the **pinned artifact's own scrub list** — the environment the runtime strips
+before running its policy helper, so the definition of "changes how the child executes code" is the
+vendor's rather than ours — plus that runtime's own doors: `CLAUDE_CODE_SHELL` (the Bash tool's
+shell), `CLAUDE_ENV_FILE` (sourced into every Bash call), the settings paths and plugin directories
+(settings carry `hooks`, `apiKeyHelper` and `env`; plugins are code), the package-manager config files,
+and the binary paths it executes. Whole prefixes are refused where a closed list cannot work:
+`LD_*`, `DYLD_*`, `BASH_FUNC_*`, `PYTHON*`, `PERL5*`, `RUBY*`, `LUA_*`, `DOTNET_*`, `COR*`,
+`APPDOMAIN_MANAGER_*` and **all of `GIT_*`** (git reads `GIT_CONFIG_*` for a `credential.helper` and
+runs `GIT_SSH_COMMAND`, `GIT_EXTERNAL_DIFF` and `GIT_ASKPASS`).
+
+Neither of the other two rules can see this class: these names are not credential-SHAPED, and the
+pinned registry legitimately declares many of them, because the runtime really does read them — which
+is why "the registry declares it" cannot be the whole test. Two of them were measured on the pin doing
+exactly what the class describes before they were refused (a planted `CLAUDE_CODE_SHELL` ran as the
+Bash tool's shell 114 times in one session; a planted `CLAUDE_ENV_FILE` was sourced into every Bash
+call — `BASH_ENV` by another door). The reviewed door for this class is `reviewedExecutionExtras`,
+again one name at a time, and a drift gate fails the suite when a pin bump adds a registry name of
+this shape that nothing has classified.
+
+**The approval bridge is fail-closed when no broker is configured.** A host MUST supply a broker: with
+none, every call that reaches the bridge is denied. That is deliberate — the alternative is a session
+that approves its own tool calls — and it means "I did not wire a broker yet" behaves like "deny", not
+like "allow".
+
+**`interrupt()` stops the turn.** On a streaming turn it ends the generation by throwing, which is
+what a projector (Phase 8) must expect: an interrupted session's stream terminates with an error
+rather than a result.
+
+**A handoff will not check that the destination can serve the session unless you give it a catalog.**
+`HandoffPlan.selection` reports `unreviewed` by default, because only the host holds the model catalog
+and the credential map. Passing `createRuntimeSdk({ handoff: { selectionInputFor } })` turns it on:
+`plan()` then asks the selector whether the RECORDED row is still servable and whether the destination
+branch can serve it, and a plan that cannot be served carries a typed refusal instead — `execute()`
+offers the lossy fork before the lease is taken, rather than after the drain and the staged copy.
+
+**A handoff can deliberately leak one staging directory.** If the destination confirms init and the
+producer record then fails to write, or if the destination throws while starting against the copy it
+was handed, the `claude-resume-<uuid>` staging root SURVIVES — the destination may be reading it, and
+deleting a live child's `CLAUDE_CONFIG_DIR` is worse than leaving a directory behind. It is locatable
+at `outcome.target.stagingRoot` and belongs to your retention pass.
+
+**"Exactly one runtime owns a session" is a convention here, not a mechanism.** The barrier moves
+ownership only after the destination confirms, and the transcript's producer record is authoritative —
+but the store's writer lease is re-entrant per pid and this router hosts both branches in one process,
+so a determined host can still write from the source after a handoff. A real guard needs a
+writer-lease generation the SDK store does not have; it is on the SDK's list.

package/dist/directory/directory.d.ts

@@ -0,0 +1,55 @@
+import type { ChildLike } from "@yanlinglabs/winter-agent-sdk/messaging";
+import type { SeamContext } from "../seams/context.js";
+import type { DirectoryResolution, DirectoryResolutionContext, RuntimeDirectory } from "../seams/directory.js";
+import type { RuntimeDirectoryEntry } from "../seams/directory-store.js";
+import type { DeliveryOutcome, GlobalAgentMessage, ListedRuntimeObject, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+import { type RuntimeDirectoryRecoveryHooks, type RuntimeDirectoryRetention } from "./recovery.js";
+/** What a caller may configure. Every field has an answer that is correct when it is absent. */
+export interface RuntimeDirectoryOptions extends RuntimeDirectoryRecoveryHooks {
+    /** Injected so a test never races a real clock. */
+    now?: () => number;
+    /**
+     * How a `ChildLike` built from a directory row delivers, for the two doors that interface requires.
+     *
+     * The router core never uses them (it calls `adapter.steerChild`/`resumeChild` and reads `ChildLike`
+     * only for `status()` and its record) — see `entryToChildLike`. Absent means those two doors answer
+     * a typed non-retryable `unavailable` rather than throwing, so a caller that used the interface it
+     * was handed gets an outcome instead of a crash.
+     */
+    deliverToChild?: (entry: RuntimeDirectoryEntry, message: GlobalAgentMessage) => Promise<DeliveryOutcome>;
+    /**
+     * WS-10 §13's caps on the two durable sinks, applied by `recover()` at step 6 (Lane B fix r1, n3).
+     *
+     * ABSENT MEANS BOTH SINKS KEEP EVERYTHING — see `RuntimeDirectoryRetention`: forgetting a released
+     * name lease changes what a model is told about a name it can no longer reach, so the router will
+     * not choose a horizon for a host that did not state one.
+     */
+    retention?: RuntimeDirectoryRetention;
+}
+/**
+ * The directory, plus the two views the messaging router needs and the seam does not name.
+ *
+ * `RuntimeDirectory` is what `RuntimeSdk.directory` exposes; a host needs nothing more. The router
+ * lives in the same package and needs the SAME snapshot resolution used, or its listing and its
+ * resolution could disagree about a row that changed between two `load()` calls.
+ */
+export interface RuntimeDirectoryHandle extends RuntimeDirectory {
+    /** One consistent read of the store, with the caller-scoped views built from it. */
+    snapshot(caller: {
+        owningSessionId: string;
+    }): Promise<DirectorySnapshot>;
+    /** Resolve against an ALREADY-TAKEN snapshot — the router resolves and delivers over one read. */
+    resolveIn(snapshot: DirectorySnapshot, to: string, context: DirectoryResolutionContext): Promise<DirectoryResolution>;
+}
+export interface DirectorySnapshot {
+    /** Every entry the store held at the moment of the read. */
+    readonly entries: readonly RuntimeDirectoryEntry[];
+    readonly byAddress: ReadonlyMap<SerializedRuntimeAddress, RuntimeDirectoryEntry>;
+    /** WS-10 §11's resolution input: this caller's own children, as the shared `ChildLike` boundary. */
+    readonly children: readonly ChildLike[];
+    /** Every object this caller may ADDRESS (includes exited sessions — WS-15 §6.2 has a row for them). */
+    readonly resolvable: readonly ListedRuntimeObject[];
+    /** Every object a listing may SHOW (WS-10 §10.2 — never an exited session). */
+    readonly listable: readonly ListedRuntimeObject[];
+}
+export declare function createRuntimeDirectory(context: SeamContext, options?: RuntimeDirectoryOptions): RuntimeDirectoryHandle;

package/dist/directory/entries.d.ts

@@ -0,0 +1,82 @@
+import type { ChildLike } from "@yanlinglabs/winter-agent-sdk/messaging";
+import type { RuntimeDirectoryEntry } from "../seams/directory-store.js";
+import type { DeliveryOutcome, GlobalAgentMessage, ListedRuntimeObject, RuntimeAddress, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+/**
+ * The session that OWNS an address (WS-10 §10.3, §11 rule 2).
+ *
+ * For a session that is the session itself; for an agent it is the parent, never the child — "a child
+ * is only addressable within its owning parent", and every fence in this package is that one
+ * sentence applied to a concrete pair of ids.
+ */
+export declare function owningSessionIdOf(address: RuntimeAddress): string;
+/** WS-10 §11's listing row for one entry. The row IS the directory record — nothing is inferred. */
+export declare function entryToListedRuntimeObject(entry: RuntimeDirectoryEntry): ListedRuntimeObject;
+/** `starting`/`running` are live for resolution's purposes; everything else is terminal or worse. */
+export declare function isLiveStatus(status: RuntimeDirectoryEntry["status"]): boolean;
+/**
+ * WS-10 §10.2's LISTING eligibility — deliberately narrower than resolution's.
+ *
+ * "It lists what `SendMessage` can currently reach — children of this parent, teammates, eligible
+ * LIVE peer sessions — and does NOT enumerate exited transcripts on disk." A terminal CHILD is still
+ * listed (it is resumable through its owner, and the subpath's own child row says so with
+ * `capabilities.resume`); an exited SESSION is not, because listing one is the enumeration that
+ * sentence forbids. Resolution still reaches an exited session by canonical address — WS-15 §6.2's
+ * routing table has a row for delivering to one — which is exactly why these are two functions and
+ * not one.
+ */
+export declare function isListableFrom(entry: RuntimeDirectoryEntry, callerOwningSessionId: string): boolean;
+/**
+ * What RESOLUTION may see: every non-archived object this caller could legitimately address.
+ *
+ * An archived session "refuses until a deliberate user/product resume unarchives it" (WS-15 §6.2), so
+ * it is not resolvable at all — the refusal belongs at the delivery door only for objects a caller can
+ * name, and an archived row is not one of them.
+ */
+export declare function isResolvableFrom(entry: RuntimeDirectoryEntry, callerOwningSessionId: string): boolean;
+/**
+ * A `ChildLike` view of a child entry, so WS-10 §11's SHARED resolution runs over directory rows.
+ *
+ * `steer`/`resume` are the two doors `ChildLike` requires. The router never calls them — the core's
+ * own `deliverEnvelope` calls `adapter.steerChild`/`adapter.resumeChild` and uses `ChildLike` only
+ * for `status()` and the three `record` fields — so they are wired to the caller's own delivery
+ * function rather than left as throws: a `ChildLike` that threw would be a trap for any future caller
+ * that reasonably used the interface it was handed.
+ *
+ * `permission.effectiveMode` is the one member with no source on a directory row, and it is
+ * UNOBSERVABLE by construction: the only place the subpath reads it is
+ * `childToListedRuntimeObject`'s `mode`, and this package never renders a child through that function
+ * — `resolve()` maps every candidate back to `entryToListedRuntimeObject`, which reads the entry's own
+ * `mode`. It is stated here rather than left to be discovered, because a future caller that DID
+ * render a `ChildLike` directly would otherwise show every child the same made-up mode.
+ */
+export declare function entryToChildLike(entry: RuntimeDirectoryEntry, deliver: (entry: RuntimeDirectoryEntry, msg: GlobalAgentMessage) => Promise<DeliveryOutcome>): ChildLike;
+/**
+ * THE ONE FIELD-LEVEL MERGE RULE IN THIS PACKAGE, and it exists because two lanes write one row.
+ *
+ * Lane A's supervised spawn proxy records WS-14 §6 rule 2's observed `CLAUDE_CONFIG_DIR` and §9's
+ * pid-plus-start-identity onto the LAUNCHED SESSION's own directory entry, through the store's
+ * `upsert` — which is a full REPLACE. A host that later records a status change through
+ * `RuntimeDirectory.record()` builds its entry from what IT knows, which is never those two fields:
+ * a plain `upsert` would drop them, and WS-15 §6.4 step 2 (revalidate process identity) plus §6 rule
+ * 5 (clear the recorded root only after verified cleanup) would then be reading a row that lost its
+ * evidence — silently, with nothing failing at the time.
+ *
+ * SO THE RULE IS NARROW AND STATED: exactly the two ADAPTER-OWNED fields are carried forward when the
+ * incoming entry omits them. Everything else is the caller's, including a caller's `undefined` for a
+ * field it owns, because a merge that preserved every absent field would make a display name or a
+ * parent impossible to clear. Lane A's own `clear()` writes through the STORE (not through this
+ * door), so rule 5's clearing still works exactly as it did.
+ */
+export declare function mergeAdapterOwnedFields(incoming: RuntimeDirectoryEntry, existing: RuntimeDirectoryEntry | undefined): RuntimeDirectoryEntry;
+/** Many rows, one mapping — so no caller ever writes the `.map(entryToListedRuntimeObject)` itself. */
+export declare function entryToListedRuntimeObjectList(entries: readonly RuntimeDirectoryEntry[]): ListedRuntimeObject[];
+/**
+ * The parent's canonical address for a child entry.
+ *
+ * `parentAddress` is optional on the record, so the fallback derives it from the child's own parsed
+ * address — through the SUBPATH's serializer, never a template literal, so this package has exactly
+ * one spelling of WS-10 §11's serialization.
+ */
+export declare function parentAddressOf(entry: RuntimeDirectoryEntry): SerializedRuntimeAddress | undefined;
+/** The canonical address of a session id — the same one spelling. */
+export declare function sessionAddressOf(winterSessionId: string): SerializedRuntimeAddress;

package/dist/directory/recovery.d.ts

@@ -0,0 +1,49 @@
+import type { RuntimeDirectoryRecovery } from "../seams/directory.js";
+import type { RuntimeDirectoryEntry, RuntimeDirectoryStore } from "../seams/directory-store.js";
+export interface RuntimeDirectoryRecoveryHooks {
+    /**
+     * WS-15 §6.4 step 2 / WS-14 §9: is the recorded `{pid, startedAt}` still that same process?
+     *
+     * A BARE PID IS NEVER ENOUGH — an OS recycles them — so an implementation must compare the start
+     * identity too, which is why the field is a pair. Absent: nothing revalidates.
+     */
+    revalidateProcessIdentity?: (entry: RuntimeDirectoryEntry) => Promise<boolean> | boolean;
+    /**
+     * WS-15 §6.4 step 3: "where policy permits" — the host's call, never the router's.
+     *
+     * THIS HOOK IS THE READER OF §6 RULE 2's DURABLE ROOT (whole-branch review, F-5). `entry.configDir`
+     * is the `CLAUDE_CONFIG_DIR` the child was OBSERVED to get — for a store-backed resume, a
+     * `claude-resume-<uuid>` staging root that "the default spawner exposes no post-cleanup lookup
+     * for". The field exists precisely for the case where the process that knew it is gone, which is
+     * this one, and nothing inside this package can act on it: reconciling or cleaning a vendor root
+     * after a crash is a policy decision (WS-05 §12's barrier does it for a live handoff; a restart is
+     * the host's). So it travels on the entry, the step's own report counts the rows that carry one,
+     * and a host that reattaches is expected to read it.
+     */
+    reattachSupervised?: (entry: RuntimeDirectoryEntry) => Promise<"reattached" | "skipped"> | "reattached" | "skipped";
+}
+/**
+ * How long the two durable sinks REMEMBER, in milliseconds (Lane B fix r1, n3).
+ *
+ * BOTH DEFAULT TO "FOREVER" (`undefined`), and that is deliberate rather than lazy: forgetting is a
+ * product decision with a visible model-facing consequence, so the router will not make it for a host
+ * that did not ask. `nameLeases` in particular is exactly how long a stale name keeps answering "that
+ * referred to something that has gone" instead of "no such agent" (WS-10 §11 rule 5).
+ *
+ * Neither number can delete evidence: a claimed-but-unreceipted delivery (WS-15 §6.4 step 5) and a
+ * HELD lease are excluded by the stores' own doors, at every retention.
+ */
+export interface RuntimeDirectoryRetention {
+    /** Receipted delivery records older than this are dropped at recovery. Absent = kept forever. */
+    deliveries?: number;
+    /** Released name leases released longer ago than this are dropped. Absent = kept forever. */
+    nameLeases?: number;
+}
+export interface RecoverDirectoryInput {
+    store: RuntimeDirectoryStore;
+    now: () => number;
+    hooks: RuntimeDirectoryRecoveryHooks;
+    /** WS-10 §13's caps, applied at step 6. Absent = both sinks keep everything. */
+    retention?: RuntimeDirectoryRetention;
+}
+export declare function recoverDirectory(input: RecoverDirectoryInput): Promise<RuntimeDirectoryRecovery>;