@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/store/handoff-barrier.d.ts

@@ -0,0 +1,238 @@
+import { type SessionKey } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+import type { SeamContextWithDirectory } from "../seams/context.js";
+import type { RuntimeDirectoryEntry } from "../seams/directory-store.js";
+import type { HandoffBarrier, HandoffOutcome, HandoffPlan, HandoffStepNumber } from "../seams/handoff.js";
+import type { MaterializedResumeDoor, MaterializedResumeProbeReport } from "../seams/materialized-resume.js";
+import type { SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+import type { RuntimeKind, RuntimeSelection, SelectionInput } from "../selection/runtime-selection.js";
+import { type MaterializedResumeDecoratorHandle } from "./materialized-resume.js";
+import { type EngineTempLayout } from "./temp-continuity.js";
+import { type SharedSessionStore } from "./wiring.js";
+/** WS-05 §5.4's advertised levels. "Never silently downgrade an advertised level." */
+export type CompatibilityLevel = "conversation" | "agent-state" | "full-filesystem";
+/** WS-05 §12's eight steps, named once so a plan, an outcome and a test all read the same words. */
+export declare const HANDOFF_STEPS: ReadonlyArray<{
+    step: HandoffStepNumber;
+    name: string;
+}>;
+/**
+ * A step's own answer. `ok: false` is "not proven", which is what makes a fork the honest offer.
+ *
+ * `producer` is step 8's only extra: WS-05 §5.4's `producerSdkVersion`/`producerEngineVersion` describe
+ * the runtime that will WRITE the session from now on, and only that runtime knows them (review r2,
+ * F11). A destination that does not report them leaves the fields OUT of the record, which is the one
+ * honest alternative — the first version wrote the SOURCE's versions under the destination's name.
+ */
+export type HandoffStepReport = {
+    ok: true;
+    detail?: string;
+    producer?: {
+        sdkVersion?: string;
+        engineVersion?: string;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+/** Structurally Lane A's `OfficialSessionHealth` (`src/official/adapter.ts`), never imported from it. */
+export interface HandoffOwnerHealth {
+    launchedThroughProxy: boolean;
+    recordedLocalWriteRoot?: string;
+    transcriptHealth: "ok" | "repair-required";
+}
+/** Structurally Lane A's `HandoffEligibility` — its `officialHandoffEligibility()` produces one. */
+export type HandoffEligibilityLike = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: string;
+    detail: string;
+};
+/**
+ * The live runtime that owns the session today.
+ *
+ * EVERY MEMBER IS OPTIONAL EXCEPT THE THREE DRAINS, and an ABSENT owner is a supported case: an exited
+ * session has nothing to drain and nothing to close, which is a cold handoff rather than a failure. What
+ * an absent owner cannot do is REPORT — so a session with no owner also has no recorded local-write root,
+ * and step 4 falls back to comparing the canonical file against itself (see `compareAgainstLocalRoot`).
+ */
+export interface HandoffSourceOwner {
+    readonly runtimeKind: RuntimeKind;
+    /** WS-14 §5/§6's session health. */
+    health?(): HandoffOwnerHealth | Promise<HandoffOwnerHealth>;
+    /** Lane A's `officialHandoffEligibility(health)`, when the owner is an official session. */
+    eligibility?(): HandoffEligibilityLike | Promise<HandoffEligibilityLike>;
+    /** §12 step 1's second half. */
+    stopNewTurns?(): void | Promise<void>;
+    /** §12 step 2. */
+    drainToIdleBoundary(): HandoffStepReport | Promise<HandoffStepReport>;
+    /** §12 step 3's SDK-stream half; the append barrier is the store's. */
+    drainStream(): HandoffStepReport | Promise<HandoffStepReport>;
+    /** §12 step 6's "close the owner gracefully". */
+    close(): HandoffStepReport | void | Promise<HandoffStepReport | void>;
+    /** `RuntimeSessionRecord.effectiveTempDir` as the source recorded it (WS-16 §4). */
+    readonly effectiveTempDir?: string;
+}
+/** What step 8 hands the destination runtime. */
+export interface HandoffResumeTarget {
+    /**
+     * REQUIRED (review r4, Lane C nit 1). It was optional because an early draft could build a target
+     * before the directory row was read; `execute()` has read it since step 1 for several rounds, every
+     * construction site sets it, and a destination that cannot be told WHICH row it now owns cannot
+     * record anything against it.
+     */
+    address: SerializedRuntimeAddress;
+    runtimeKind: RuntimeKind;
+    /** §12 step 8: "resume the SAME backend UUID and project key". */
+    backendSessionId: string;
+    projectKey: string;
+    /** §12 step 8: init must confirm the same session AND level. */
+    compatibilityLevel: CompatibilityLevel;
+    /** The transcript the destination reads: the materialized copy, or the canonical file. */
+    resumePath: string;
+    /**
+     * The `<tmpdir>/claude-resume-<uuid>` root a `store-backed-resume` launch needs — it IS that
+     * generation's `CLAUDE_CONFIG_DIR` (WS-14 §1). Present for a `claude-agent` destination, absent for
+     * a Winter one, which reads the canonical store directly.
+     */
+    stagingRoot?: string;
+    /** WS-14 §1's two launch profiles, as the destination's own plan will declare it. */
+    profile?: "fresh-spool" | "store-backed-resume";
+    /** WS-05 §9.1's post-handoff `effectiveTempDir`. */
+    effectiveTempDir: string;
+    door: MaterializedResumeDoor;
+    selection: RuntimeSelection;
+}
+/** The runtime that will own the session after the barrier. */
+export interface HandoffDestinationRuntime {
+    readonly runtimeKind: RuntimeKind;
+    /** §12 step 8. `ok: false` keeps the source owner and offers the fork. */
+    confirmInit(target: HandoffResumeTarget): HandoffStepReport | Promise<HandoffStepReport>;
+}
+/** Who is on each end. Both are optional; see `HandoffSourceOwner` and step 8's default. */
+export interface HandoffParticipants {
+    source?(session: SessionKey, from: RuntimeKind): Promise<HandoffSourceOwner | undefined> | HandoffSourceOwner | undefined;
+    destination?(session: SessionKey, to: RuntimeKind): Promise<HandoffDestinationRuntime | undefined> | HandoffDestinationRuntime | undefined;
+}
+/** A `plan()` that cannot be built at all — the session is unknown, so nothing about it can be planned. */
+export declare class HandoffPlanError extends RuntimeSdkError {
+    constructor(session: SessionKey, reason: string);
+}
+/** The outcome, widened with the detail the pinned union has no room for. Assignable to it. */
+export type DetailedHandoffOutcome = HandoffOutcome & {
+    /** The step the barrier reached. Present on every arm, including `resumed` (always 8). */
+    step: HandoffStepNumber;
+    detail: string;
+    /** Everything step 8 handed the destination — a host renders the resume from this. */
+    target?: HandoffResumeTarget;
+    steps: Array<{
+        step: HandoffStepNumber;
+        name: string;
+        ok: boolean;
+        detail: string;
+    }>;
+};
+export interface HandoffBarrierDeps {
+    /** The one shared store. Built lazily from the peer + `winterHome` when a host does not pass one. */
+    shared?: SharedSessionStore;
+    /** Defaults to the peer's own `resolveWinterHome()` — the production answer, resolved at first use. */
+    winterHome?: string;
+    /**
+     * A decorator to use instead of the barrier's own.
+     *
+     * IT MUST BE OVER THE SAME STORE, and the barrier checks (review r1, F2) rather than trusting: two
+     * stores over one home means two decoration registries, and a decoration registered in one washes
+     * back through the other's canonical append gate. A host wiring both seams should take
+     * `barrier.decorator` instead of building a second one.
+     */
+    decorator?: MaterializedResumeDecoratorHandle;
+    /**
+     * R-7b-12: the pin's own probe report, which is what opens the PREFERRED door.
+     *
+     * Passed to the decorator the barrier BUILDS, so the one-store invariant above is untouched — a host
+     * that wanted PREFERRED used to have to construct a second decorator, which is exactly the wiring
+     * mistake `decorator` refuses. `createRuntimeSdk` fills it from
+     * `materializedResumeReportForPin(<the injected official peer's version>)`; absent, or a version with
+     * no recorded report, means `fallback`.
+     */
+    decorationReport?: MaterializedResumeProbeReport;
+    participants?: HandoffParticipants;
+    /** Where the handoff leases live. Defaults to `<winterHome>/runtimes/handoff-leases`. */
+    leaseRoot?: string;
+    /** Overrides the staging root a `claude-agent` destination resumes from (tests point it at a tmpdir). */
+    stagingRootFor?: (uuid: string) => string;
+    /** The temp layout for a session. Defaults to D18's derivation from the resolved brand. */
+    tempLayoutFor?: (entry: RuntimeDirectoryEntry, session: SessionKey) => EngineTempLayout;
+    /**
+     * The catalog and credentials a FRESH selection decision needs, so `plan()` can ask Lane D whether
+     * the destination branch can actually serve this session (fix wave, item 20).
+     *
+     * ABSENT MEANS UNREVIEWED, NOT ASSUMED-FINE. Only the host has the model catalog and the credential
+     * presence map; the barrier will not synthesise them, and a plan built without them says
+     * `selection.kind === "unreviewed"` in so many words rather than implying a check that never ran.
+     */
+    selectionInputFor?: (args: {
+        session: SessionKey;
+        from: RuntimeKind;
+        to: RuntimeKind;
+        persisted: RuntimeSelection;
+    }) => SelectionInput | Promise<SelectionInput>;
+    /** The handoff note's text. The host owns the wording; this is the default. */
+    noteText?: (args: {
+        from: RuntimeKind;
+        to: RuntimeKind;
+        session: SessionKey;
+    }) => string;
+    now?: () => Date;
+}
+export interface HandoffBarrierHandle extends HandoffBarrier {
+    execute(plan: HandoffPlan): Promise<DetailedHandoffOutcome>;
+    /** The shared store this barrier writes through — the same object both branches were given. */
+    readonly shared: SharedSessionStore;
+    /** The decorator, over that same store. The spine wires `decorator: barrier.decorator`. */
+    readonly decorator: MaterializedResumeDecoratorHandle;
+}
+/** A barrier and a decorator that do not share one store — a wiring mistake, refused rather than run. */
+export declare class HandoffWiringError extends RuntimeSdkError {
+    constructor(reason: string);
+}
+/**
+ * WS-05 §12's mechanics. Lane C's implementation of the spine's seam.
+ *
+ * THE DIRECTORY IS READ THROUGH THE STORE SEAM, not through `context.directory`. Both are the same
+ * data; the difference is that `RuntimeDirectoryStore` is implemented (the spine ships an in-memory
+ * default) while `RuntimeDirectory` is Lane B's policy layer over it. A barrier that reached for the
+ * policy layer would be unable to run until another lane landed, for no gain: everything the barrier
+ * needs is a record, not a resolution.
+ */
+export declare function createHandoffBarrier(context: SeamContextWithDirectory, deps?: HandoffBarrierDeps): HandoffBarrierHandle;
+export type TranscriptValidation = {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * §12 step 5: "validate JSONL framing, UUID uniqueness, parent-chain reachability, tool_use/result
+ * pairing, compaction boundary, subkeys, declared adjacent stores".
+ *
+ * FRAMING IS CHECKED ON THE BYTES, everything else on what `load()` returns — because framing is the one
+ * property `load()` REPAIRS (the concrete store quarantines a torn tail), so a check that ran only on the
+ * loaded entries would report clean on a file it had just truncated.
+ */
+export declare function validateSessionTranscript(shared: SharedSessionStore, session: SessionKey, winterHome: string): Promise<TranscriptValidation>;
+/** The producer record — the barrier's one authoritative write — did not reach the store. */
+export declare class HandoffCommitError extends RuntimeSdkError {
+    constructor(reason: string);
+}
+interface HandoffLease {
+    path: string;
+}
+export declare function acquireHandoffLease(leaseRoot: string, session: SessionKey): HandoffLease;
+export declare function releaseHandoffLease(lease: HandoffLease): void;
+export declare class HandoffLeaseError extends RuntimeSdkError {
+    constructor(path: string, reason: string);
+}
+export {};

package/dist/store/index.d.ts

@@ -0,0 +1,11 @@
+export { assertOneSharedStore, lazySharedSessionStore, assertStoreCompatibleOptions, BlindStoreImportError, createDecorationRegistry, createSharedSessionStore, DEFAULT_MIRROR_POLICY, SharedStoreOptionsError, SharedStoreUnavailableError, stripDecorations, } from "./wiring.js";
+export type { CanonicalSessionStore, CanonicalSessionStoreConstructor, DecorationRegistry, MirrorErrorRecord, MirrorPolicy, SessionMirrorHealth, SettleReport, SharedSessionStore, SharedStoreIdentity, StoreBearingOptions, StripDecorationsResult, TranscriptHealth, } from "./wiring.js";
+export { canonicalTranscriptPath, compareTranscriptTail, createTranscriptReconciler, guardedImportSessionToStore, isFile, isTranscriptPath, localTranscriptPath, reconcileLocalWriteRoot, scanLocalWriteRoot, TranscriptReconcileError, } from "./reconcile.js";
+export type { LocalTranscript, ReconcileReport, TailComparison, TranscriptReconcileHook, TranscriptReconciler, TranscriptReconcileOutcome } from "./reconcile.js";
+export { materializeTempContinuity, resolveEngineTempLayout, sessionTempDirFor, tempContinuityDisclosure, tempContinuityModeFor, TempContinuityError, VENDOR_ENGINE_DIR_PREFIX, } from "./temp-continuity.js";
+export type { EngineTempLayout, EngineTempLayoutInput, TempContinuityDisclosure, TempContinuityInput, TempContinuityResult } from "./temp-continuity.js";
+export { classifyCrashPairs, createMaterializedResumeDecorator, HANDOFF_ENTRY_LABEL, materializedTranscriptPath, MaterializedResumeError, PROVIDER_STATE_SUFFIX, } from "./materialized-resume.js";
+export type { CrashPairClassification, StagedResumeResult, MaterializedResumeDecoratorHandle, MaterializedResumeDeps, MaterializedResumeProbeDetail, MaterializedResumeProbeLeg, PinnedRuntimeProbeLegs, } from "./materialized-resume.js";
+export { MATERIALIZED_RESUME_PROBE_REPORTS, materializedResumeReportForPin } from "./pinned-probes.js";
+export { acquireHandoffLease, createHandoffBarrier, HANDOFF_STEPS, HandoffCommitError, HandoffLeaseError, HandoffPlanError, HandoffWiringError, releaseHandoffLease, validateSessionTranscript } from "./handoff-barrier.js";
+export type { CompatibilityLevel, DetailedHandoffOutcome, HandoffBarrierDeps, HandoffBarrierHandle, HandoffDestinationRuntime, HandoffEligibilityLike, HandoffOwnerHealth, HandoffParticipants, HandoffResumeTarget, HandoffSourceOwner, HandoffStepReport, TranscriptValidation, } from "./handoff-barrier.js";

package/dist/store/materialized-resume.d.ts

@@ -0,0 +1,100 @@
+import type { SessionKey, SessionStoreEntry } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+import type { SeamContext } from "../seams/context.js";
+import type { MaterializedResumeDecorator, MaterializedResumeInput, MaterializedResumeProbeReport, MaterializedResumeProbeResult, MaterializedResumeResult } from "../seams/materialized-resume.js";
+import { type SharedSessionStore } from "./wiring.js";
+/** The provider-state sidecar's suffix (WS-05 §13). Named here only so the probes can leave it alone. */
+export declare const PROVIDER_STATE_SUFFIX = ".provider-state.jsonl";
+/** The label every barrier-injected entry carries, so it can never read as an ordinary message. */
+export declare const HANDOFF_ENTRY_LABEL = "handoff";
+/** A decoration that cannot be produced — the transcript has nothing to anchor a note to. */
+export declare class MaterializedResumeError extends RuntimeSdkError {
+    constructor(reason: string);
+}
+/** Where inside a staging root the destination runtime reads this session's transcript. */
+export declare function materializedTranscriptPath(stagingRoot: string, key: SessionKey): string;
+/**
+ * The legs only the pinned official runtime can answer.
+ *
+ * INJECTED, NEVER IMPORTED. This lane's probes must be runnable in a tree where the official adapter is
+ * not present, and the bed that CAN drive 0.3.250 lives in the official lane's tests. A probe with no
+ * bed records "unexercised" and the door stays shut.
+ */
+export interface PinnedRuntimeProbeLegs {
+    /**
+     * Resumes `key` on the pinned runtime from `resumePath`'s staging root, with `store` attached as the
+     * session store, and returns once the generation has ended.
+     */
+    freshProcessResume(args: {
+        home: string;
+        stagingRoot: string;
+        key: SessionKey;
+        shared: SharedSessionStore;
+    }): Promise<void>;
+    /** A short human name for the bed, recorded in the probe evidence. */
+    readonly label: string;
+}
+export interface MaterializedResumeDeps {
+    /** The one shared store. Omitted = resolved on first use from the peer (see `lazySharedSessionStore`). */
+    shared?: SharedSessionStore | (() => SharedSessionStore);
+    /** A report recorded on a previous run — `docs/probes/materialized-resume.md`'s content. */
+    report?: MaterializedResumeProbeReport;
+    /** The pinned runtime's legs, when a bed can supply them. */
+    runtimeLegs?: PinnedRuntimeProbeLegs;
+    /** Fields for the note when the transcript has no entry to read them from. */
+    anchor?: {
+        cwd: string;
+        version: string;
+    };
+    now?: () => Date;
+}
+/**
+ * The pinned result, widened with the entry the FALLBACK door owes the canonical file.
+ *
+ * THE DECORATOR NEVER WRITES TO THE CANONICAL STORE (review r1, F1/F2). Under FALLBACK the note still
+ * belongs there — §8.2 calls it "the sole case where injected handoff content enters the canonical
+ * file" — but WHEN it goes in is the barrier's business, and the answer is "after the destination
+ * confirms init". A note appended before that leaves a durable, model-visible sentence saying the
+ * conversation continues on a runtime that never started.
+ */
+export interface StagedResumeResult extends MaterializedResumeResult {
+    /** Present only under FALLBACK: the labelled entry the barrier commits once step 8 confirms. */
+    note?: SessionStoreEntry;
+}
+export interface MaterializedResumeDecoratorHandle extends MaterializedResumeDecorator {
+    /** The last report — from `deps.report` until `probe()` runs. */
+    readonly report: MaterializedResumeProbeReport | undefined;
+    /**
+     * The store this decorator writes its registry into.
+     *
+     * EXPOSED so the barrier can ASSERT the two share one instance (review r1, F2): two stores over one
+     * home means two decoration registries, and a decoration registered in one is invisible to the
+     * other's canonical append gate — which is a wash-back caused by wiring rather than by the vendor.
+     */
+    readonly shared: SharedSessionStore;
+    decorate(input: MaterializedResumeInput): Promise<StagedResumeResult>;
+}
+/** WS-13 §8.2's doors. Lane C's implementation of the spine's seam. */
+export declare function createMaterializedResumeDecorator(context: SeamContext, deps?: MaterializedResumeDeps): MaterializedResumeDecoratorHandle;
+export interface MaterializedResumeProbeLeg {
+    name: string;
+    passed: boolean;
+    /** True when only the pinned official runtime can answer this leg. */
+    requiresPinnedRuntime: boolean;
+    evidence: string;
+}
+/** The pinned result shape, widened with the legs that produced it. */
+export interface MaterializedResumeProbeDetail extends MaterializedResumeProbeResult {
+    legs: MaterializedResumeProbeLeg[];
+}
+/** WS-05 §13's write-ahead pairing, as a classification a collector can act on. */
+export interface CrashPairClassification {
+    /** A sidecar record whose anchoring transcript entry never landed — garbage-collectable. */
+    collectable: string[];
+    /** A transcript entry whose sidecar record never landed — native resume degrades to summary level. */
+    degraded: string[];
+}
+export declare function classifyCrashPairs(args: {
+    entryUuids: readonly string[];
+    anchorUuids: readonly string[];
+}): CrashPairClassification;

package/dist/store/pinned-probes.d.ts

@@ -0,0 +1,17 @@
+import type { MaterializedResumeProbeReport } from "../seams/materialized-resume.js";
+/**
+ * The recorded verdict per pinned official-runtime version.
+ *
+ * The evidence sentences are the probes' own, trimmed to what a reader of a handoff outcome needs;
+ * `docs/probes/materialized-resume.md` carries the full run, both platforms, and the two withdrawn
+ * earlier readings.
+ */
+export declare const MATERIALIZED_RESUME_PROBE_REPORTS: Readonly<Record<string, MaterializedResumeProbeReport>>;
+/**
+ * The report for a pin, or `undefined` — which is what keeps a bump honest.
+ *
+ * `undefined` means `fallback`: the decorator opens PREFERRED only when it is GIVEN a passing report,
+ * so an unrecorded version, a host with no official peer at all, and a peer whose version could not be
+ * read all land on the same always-available door.
+ */
+export declare function materializedResumeReportForPin(version: string | undefined): MaterializedResumeProbeReport | undefined;

package/dist/store/reconcile.d.ts

@@ -0,0 +1,157 @@
+import type { SessionKey, SessionStoreEntry } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+import type { SharedSessionStore } from "./wiring.js";
+/** One transcript found under a local-write root, with the store key it mirrors to. */
+export interface LocalTranscript {
+    path: string;
+    key: SessionKey;
+}
+/**
+ * Every transcript under a recorded local-write root.
+ *
+ * NOT A GLOB AND NOT A RECURSIVE WALK: exactly two shapes are transcripts (the session's own file and
+ * its `subagents/` children), and everything else in that tree — the vendor's settings, its caches,
+ * its lock files — is out of scope by construction rather than by a filter someone has to maintain.
+ * A missing root is an empty list, not an error: a session that never spawned has nothing to mirror.
+ */
+export declare function scanLocalWriteRoot(root: string): LocalTranscript[];
+/** WS-05 §12 step 4's four possible answers. */
+export type TailComparison = {
+    kind: "match";
+    lines: number;
+} | {
+    kind: "canonical-behind";
+    lines: number;
+    missing: SessionStoreEntry[];
+}
+/** The canonical file disagrees with the local root at a line both of them have. */
+ | {
+    kind: "diverged";
+    atLine: number;
+    reason: string;
+}
+/** The canonical file has entries the local root does not — they are not the same history. */
+ | {
+    kind: "canonical-ahead";
+    extra: number;
+};
+/**
+ * WS-05 §12 step 4: "compare canonical tail vs the recorded local-write root".
+ *
+ * The canonical file MUST be a prefix of the local one. It is a mirror: the local write happens first
+ * (WS-14 §5), so the canonical side can only ever be equal or behind. Anything else is a statement
+ * that the two files are not the same history, and this function says so rather than repairing it.
+ */
+export declare function compareTranscriptTail(args: {
+    localPath: string;
+    canonicalLines: readonly string[];
+    isDecoration?: (uuid: string) => boolean;
+}): TailComparison;
+export interface TranscriptReconcileOutcome {
+    key: SessionKey;
+    localPath: string;
+    comparison: TailComparison;
+    appended: number;
+}
+export interface ReconcileReport {
+    root: string;
+    /** `reconciled` — every transcript now matches. `diverged` — at least one cannot be, safely. */
+    status: "reconciled" | "nothing-to-do" | "diverged";
+    transcripts: TranscriptReconcileOutcome[];
+    appended: number;
+    /** The sessions whose health was cleared, i.e. those that were behind and are now level. */
+    cleared: SessionKey[];
+}
+/** A reconciliation that cannot proceed because the canonical store's own state forbids it. */
+export declare class TranscriptReconcileError extends RuntimeSdkError {
+    readonly root: string;
+    constructor(root: string, reason: string);
+}
+export interface TranscriptReconcilerInput {
+    shared: SharedSessionStore;
+    /** Restricts reconciliation to one session; omitted = every transcript under the root. */
+    only?: {
+        projectKey: string;
+        sessionId: string;
+    };
+}
+/**
+ * Reconciles the canonical store against one local-write root.
+ *
+ * THE ORDER IS DELIBERATE: settle first (so the comparison is not racing the mirror's own pending
+ * batch), then compare, then append only the suffix, then settle again and re-read to confirm. A
+ * reconciliation that reported success without re-reading would be reporting its own intention.
+ */
+export declare function reconcileLocalWriteRoot(root: string, input: TranscriptReconcilerInput): Promise<ReconcileReport>;
+/**
+ * The shape of WS-14 §6 rule 3's reconcile hook, as `src/official/spawn-proxy.ts` declares it.
+ *
+ * DECLARED STRUCTURALLY HERE rather than imported, for the same reason the seams declare the official
+ * module structurally: this lane must not depend on that lane's module graph to be buildable.
+ *
+ * ASSIGNABLE IN ONE DIRECTION, AND THAT IS THE DIRECTION PRODUCTION USES (review r4, N14 — the
+ * previous sentence claimed "mutually assignable", which is measurably false). This hook accepts LESS
+ * than `SpawnObservation` carries, so Lane C's `createTranscriptReconciler().hook` drops straight into
+ * `createSupervisedSpawnProxy({ reconcile })`; the reverse fails, because a `TranscriptReconcile` is
+ * handed the whole observation (`processIdentity`, `command`, `args`) and this type does not promise
+ * to supply it. Nothing needs the reverse. `test/store/reconcile.test.ts` now actually pins the
+ * forward direction — the comment promised a test that did not exist, which is how a structural
+ * declaration drifts from the thing it mirrors without anything noticing.
+ */
+export type TranscriptReconcileHook = (input: {
+    observation: {
+        root: {
+            configDir: string;
+        };
+    };
+    exit: {
+        code: number | null;
+        signal: string | null;
+    };
+}) => Promise<void>;
+export interface TranscriptReconciler {
+    /** Reconcile one recorded local-write root. */
+    reconcile(root: string, only?: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<ReconcileReport>;
+    /** The collaborator handed to `createSupervisedSpawnProxy({ reconcile })`. */
+    hook: TranscriptReconcileHook;
+    /** Every report this reconciler produced, newest last — the supervised-run evidence. */
+    readonly reports: readonly ReconcileReport[];
+}
+/**
+ * Builds the reconciler and its proxy hook.
+ *
+ * THE HOOK NEVER THROWS. WS-14 §6 rule 3 delays the synthetic `exit` until reconciliation completes;
+ * a hook that threw would either strand the process or (as Lane A's proxy actually does) be caught and
+ * the exit forwarded anyway — and in both readings the FAILURE would be the thing that disappears. So
+ * a failed reconciliation is recorded as a `diverged` report, which leaves the session's
+ * `repair-required` flag standing and the handoff blocked. That is the outcome §5 asks for.
+ */
+export declare function createTranscriptReconciler(input: TranscriptReconcilerInput): TranscriptReconciler;
+/**
+ * WS-14 §5's forbidden door, guarded.
+ *
+ * A HOST STILL HAS `importSessionToStore()` — it is the official SDK's own function, and the router
+ * cannot take it away. What the router CAN do is give the host one call site that refuses to run it
+ * while the mirror is unhealthy, so the ban is a mechanism rather than a sentence in a document.
+ */
+export declare function guardedImportSessionToStore<T>(args: {
+    shared: SharedSessionStore;
+    key: SessionKey;
+    importer: () => Promise<T>;
+}): Promise<T>;
+/**
+ * The canonical transcript's own path under a Winter home.
+ *
+ * THE SAME SHAPE AS A LOCAL-WRITE ROOT'S, and that is not a coincidence: WS-05 §6's key mapping is the
+ * vendor's own `<configDir>/projects/<projectKey>/<sessionId>.jsonl` layout, which is what makes the
+ * canonical file and the local file comparable line for line in the first place.
+ */
+export declare function canonicalTranscriptPath(winterHome: string, key: SessionKey): string;
+/** The transcript file a local-write root holds for one session key, whether or not it exists. */
+export declare function localTranscriptPath(root: string, key: SessionKey): string;
+export declare function isTranscriptPath(path: string, kind?: "session" | "subagent"): boolean;
+/** Whether a path exists and is a regular file — used by the probes' byte-for-byte assertions. */
+export declare function isFile(path: string): boolean;

package/dist/store/temp-continuity.d.ts

@@ -0,0 +1,92 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+import type { RuntimeKind } from "../selection/runtime-selection.js";
+/** The official engine's own hard-coded directory prefix beneath the shared root (WS-05 §9, WS-14 §1). */
+export declare const VENDOR_ENGINE_DIR_PREFIX = "claude-";
+/** A temp layout that could not be established, or one whose destination failed re-validation. */
+export declare class TempContinuityError extends RuntimeSdkError {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+export interface EngineTempLayout {
+    /** `realpath(<PREFIX>TMPDIR | /tmp)`. */
+    base: string;
+    /** The shared per-user root — the value a spawned official child gets as `CLAUDE_CODE_TMPDIR`. */
+    sharedRoot: string;
+    winterEngineDir: string;
+    vendorEngineDir: string;
+    winterSessionDir: string;
+    vendorSessionDir: string;
+    uid: number;
+    tempProjectKey: string;
+    backendUuid: string;
+}
+export interface EngineTempLayoutInput {
+    brand: Pick<BrandProfile, "envPrefix" | "tempRootName">;
+    tempProjectKey: string;
+    backendUuid: string;
+    /** Injectable so a hermetic test never reads the real environment. */
+    env?: Record<string, string | undefined>;
+    /** The REAL process uid by default. A fixed suffix would lock every other user out of a 0700 root. */
+    uid?: number;
+}
+/**
+ * D18's paths, derived rather than spelled.
+ *
+ * THE BASE IS REALPATH'D ONCE, up front (macOS `/tmp` → `/private/tmp`), and no level beneath it ever
+ * is: resolving a deeper level would follow a symlink an attacker could have planted there, which is
+ * exactly what §9's "validate without following symlinks" forbids.
+ */
+export declare function resolveEngineTempLayout(input: EngineTempLayoutInput): EngineTempLayout;
+/** WS-05 §12 step 7 / §9.1's two directions, by DESTINATION runtime. */
+export declare function tempContinuityModeFor(to: RuntimeKind): "adopt" | "clone-copy";
+/** The canonical session temp dir for a runtime, under one layout. */
+export declare function sessionTempDirFor(to: RuntimeKind, layout: EngineTempLayout): string;
+export interface TempContinuityResult {
+    mode: "adopt" | "clone-copy";
+    /** `RuntimeSessionRecord.effectiveTempDir` after the handoff (WS-16 §4). */
+    effectiveTempDir: string;
+    /** The Winter-side dir a clone-copy superseded. Retained; named so retention can find it. */
+    supersededDir?: string;
+    filesCopied: number;
+    /** §9.1's "Round trips" row: the recorded dir already IS the destination's computed path. */
+    stabilized: boolean;
+    /** §9.1's last row: the recorded dir was gone, so a fresh one was created at the canonical path. */
+    recreated: boolean;
+}
+export interface TempContinuityInput {
+    to: RuntimeKind;
+    layout: EngineTempLayout;
+    /**
+     * `RuntimeSessionRecord.effectiveTempDir` — the dir the session is ACTUALLY using, whichever engine
+     * dir it lives under. Absent for a session that has no recorded dir yet.
+     */
+    recordedTempDir?: string;
+}
+/**
+ * WS-05 §12 step 7.
+ *
+ * EVERY BRANCH RE-VALIDATES THE DESTINATION (ownership, directory-ness, no symlink, `0700`) and
+ * refuses rather than repairing — the destination of a temp materialization is a directory another
+ * process could have planted, and §9's own rule is "validate the per-user root without following
+ * symlinks: ownership, directory-ness, traversal, permissions; reject substitution".
+ */
+export declare function materializeTempContinuity(input: TempContinuityInput): TempContinuityResult;
+/**
+ * What this module discloses about where a session's scratch actually lives (WS-17 row 15's "vendor
+ * temp roots reported honestly").
+ *
+ * The official adapter discloses the roots a SPAWN observes; this is the continuity half — the two
+ * engine dirs, which one the session is on now, and the one a clone-copy left behind. A report that
+ * named only the Winter dir would be the dishonest version: after one Claude generation the session's
+ * scratch is in the vendor's directory, and a user asking "where are my files" needs that answer.
+ */
+export interface TempContinuityDisclosure {
+    sharedRoot: string;
+    winterEngineDir: string;
+    vendorEngineDir: string;
+    effectiveTempDir: string;
+    supersededDir?: string;
+    note: string;
+}
+export declare function tempContinuityDisclosure(layout: EngineTempLayout, result: TempContinuityResult): TempContinuityDisclosure;