@yanlinglabs/winter-agent-sdk 0.0.1

package/dist/sessions.d.ts

@@ -0,0 +1,50 @@
+import { type SessionStoreEntry } from "./store/session-store.js";
+import { type BrandProfile } from "./brand.js";
+interface SessionQueryOptions {
+    directory?: string;
+    winterHome?: string;
+    /**
+     * P7a fix wave (item 5, whole-branch review I-1): THE HOST'S OWN BRAND.
+     *
+     * These nine functions run OUTSIDE a query -- no `RuntimeConfig`, no wiring -- so the only way
+     * they can learn which product's store to open is to be told. Without this field `resolveHome`
+     * fell through to `resolveWinterHome()` with NO brand, which reads `WINTER_HOME`, `WINTER_PROFILE`
+     * and `~/.winter`: a D19 tier-1 reuser calling `listSessions()` silently addressed WINTER's store,
+     * and on a machine where Winter is also installed `deleteSession(id)` from the reuser's app
+     * deleted a Winter session.
+     *
+     * `winterHome` still wins outright -- it is an explicit path, and a caller that computed one has
+     * already made this decision. `brand` is what a caller uses INSTEAD of recomputing the path: the
+     * profile is folded onto Winter's defaults by the same `resolveBrand` `query()` uses, so a partial
+     * `{ homeDirName, envPrefix }` is enough and an invalid one refuses here rather than silently
+     * addressing the wrong store.
+     */
+    brand?: Partial<BrandProfile>;
+}
+export declare function listSessions(opts?: SessionQueryOptions): Promise<Array<{
+    sessionId: string;
+    projectKey: string;
+    mtime: number;
+    name?: string;
+    tags?: string[];
+}>>;
+export declare function getSessionInfo(sessionId: string, opts?: SessionQueryOptions): Promise<{
+    sessionId: string;
+    projectKey: string;
+    mtime: number;
+    entryCount: number;
+    name?: string;
+    tags?: string[];
+}>;
+export declare function getSessionMessages(sessionId: string, opts?: SessionQueryOptions): Promise<SessionStoreEntry[]>;
+export declare function renameSession(sessionId: string, name: string, opts?: SessionQueryOptions): Promise<void>;
+export declare function tagSession(sessionId: string, tags: string[], opts?: SessionQueryOptions): Promise<void>;
+export declare function deleteSession(sessionId: string, opts?: SessionQueryOptions): Promise<void>;
+export declare function forkSession(sessionId: string, opts?: SessionQueryOptions): Promise<{
+    sessionId: string;
+}>;
+export declare function listSubagents(sessionId: string, opts?: SessionQueryOptions): Promise<Array<{
+    agentId: string;
+}>>;
+export declare function getSubagentMessages(sessionId: string, agentId: string, opts?: SessionQueryOptions): Promise<SessionStoreEntry[]>;
+export {};

package/dist/settings/model-slots.d.ts

@@ -0,0 +1,33 @@
+import type { ModelSlotSetting } from "../protocol/config.js";
+/**
+ * The catalog questions validation needs, injected.
+ *
+ * `model` in a `ModelSlotSetting` may be a `canonicalModelId` OR a catalog key (both are things a
+ * user has to hand), so validation needs to go both ways: canonical id -> the rows serving it, and
+ * key -> its canonical id.
+ */
+export interface ModelSlotsLookup {
+    rowsForCanonicalId(id: string): Array<{
+        key: string;
+        providerId: string;
+    }>;
+    keyToCanonicalId(key: string): string | undefined;
+}
+export type ModelSlotsValidation = {
+    ok: true;
+    slots: ModelSlotSetting[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a raw `settings.modelSlots` value (WS-13c §5).
+ *
+ * Lane B's obligations, from the spec: 1–4 entries; names match the slot token grammar and are
+ * unique; NO name is a reserved Claude name (D25); every `model` resolves in the catalog; a given
+ * `provider` actually serves it; `description` is ≤ 200 characters and carries no currency amount.
+ *
+ * WHOLE-SET: the first invalid entry (in array order) is where this returns, with a `reason` that
+ * names what failed. It never validates some entries and drops others.
+ */
+export declare function validateModelSlots(raw: unknown, lookup: ModelSlotsLookup): ModelSlotsValidation;

package/dist/settings/resolve.d.ts

@@ -0,0 +1,79 @@
+import { type DetailedResolvedSettings, type ResolvedSettings, type ResolveSettingsDetailedOptions, type ResolveSettingsOptions, type Settings } from "./types.js";
+export declare function validateProjectPlansDirectory(value: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The Winter-side resolver. `resolveSettings` (the pinned export, below) is a thin projection of
+ * this onto the pinned three fields.
+ *
+ * Precedence, highest first (R5-8): managed (server, then programmatic) > flag (inline/sdk) >
+ * local > project > user. `local` above `project` is the pinned ordering capture (1) proves
+ * behaviourally (cell J vs I: only a rule in the LOCAL file silences a prompt).
+ *
+ * `trustedWorkspace` lives on the pinned `ResolveSettingsDetailedOptions` itself (R-6c-16, folded by
+ * the controller after Lane B merged; the lane had widened it by intersection because `types.ts` was
+ * the spine's frozen surface during the phase). `WorkspaceTrustFilterOptions` below carries the
+ * identical field for `applyWorkspaceTrust`. Absent = untrusted (fail-safe); production-wiring
+ * threads the host's RULING P5-A bit.
+ */
+export declare function resolveSettingsDetailed(opts?: ResolveSettingsDetailedOptions): Promise<DetailedResolvedSettings>;
+/**
+ * PINNED EXPORT (`sdk.d.ts:2809`): `resolveSettings(_opts?: ResolveSettingsOptions): Promise<ResolvedSettings>`.
+ *
+ * Task 1's item (a) found this is a MIRROR of a pinned function, not the "disclosed Winter
+ * extension" R5-8 originally described -- one options object (never four positional parameters),
+ * and exactly three result fields. Winter-side detail (per-source raw values, load errors, the
+ * inline/`flag` tier, an explicit `winterHome`) lives on `resolveSettingsDetailed` above, which this
+ * wraps: a caller writing against the pinned surface sees nothing extra.
+ *
+ * WS-03 disclosure: the pinned options object carries no environment/home injection point, so an
+ * omitted `settingSources` (or one including `"user"`) reads the REAL resolved WINTER_HOME. Tests
+ * must therefore either exclude the `user` tier or call `resolveSettingsDetailed` with an explicit
+ * `winterHome`.
+ */
+export declare function resolveSettings(opts?: ResolveSettingsOptions): Promise<ResolvedSettings>;
+/**
+ * PINNED EXPORT (`sdk.d.ts:694`, doc `686-694`): drops `permissions.defaultMode` from the resolved
+ * settings iff it is ESCALATING (`bypassPermissions`/`auto`/`acceptEdits`) AND was set by the
+ * `project` tier -- the repo-committed one. Every other key, including `allow`/`deny`/`ask`, is
+ * returned untouched, and a non-escalating project `defaultMode` (`plan`) survives. Verified against
+ * the pinned runtime in capture (1)'s declared-API table, all four rows.
+ *
+ * The "which tier set it" question is answered by walking `sources`, NOT by reading
+ * `provenance.permissions` -- the two disagree in one observable case, and only one of them is
+ * safe: with an escalating `defaultMode` in project and an `allow` in local, the coarse per-top-
+ * level-key provenance reports `local` (so a provenance-driven filter would RETAIN the escalating
+ * repo-committed mode) while the walk correctly attributes `defaultMode` to `project` and drops it.
+ * That specific combination was not captured against the pinned runtime; the walk is the fail-safe
+ * direction and is what Winter ships. Recorded in the Task 2 report.
+ *
+ * Never mutates its input.
+ */
+export declare function filterEscalatingDefaultMode(resolved: ResolvedSettings): Settings;
+export interface WorkspaceTrustFilterOptions {
+    /** Host-declared workspace trust (RULING P5-A). Default false -- a repository never self-trusts (WS-07 §3.2). */
+    trustedWorkspace?: boolean;
+}
+/**
+ * RULING P5-A, the whole tier filter in one call -- what a lane should use.
+ *
+ * Capture (1)'s finding, verbatim: the pinned SDK's trust is a per-TIER filter on PERMISSIVE rules,
+ * not a per-directory bit. A PROJECT-tier `allow`/`additionalDirectories` LOADS but does not widen;
+ * `local`- and `user`-tier permissive rules do widen; `deny`/`ask` from every tier apply regardless
+ * (cells K/L: a project `deny` is honored and beats a local `allow`).
+ *
+ * Winter layers ONE product extension above that: a host may declare the workspace trusted
+ * (`RuntimeConfig.trustedWorkspace`), which lifts the project-tier restriction. The filter is never
+ * DERIVED from that bit in the other direction -- an untrusted repo's project-tier `deny` stays
+ * enforced, which is the thing capture (1) explicitly forbids losing.
+ *
+ * Also applies the pinned `filterEscalatingDefaultMode`, which is tier-based and therefore fires
+ * even in a trusted workspace: a repo-committed escalating `defaultMode` never survives, trust or
+ * no trust.
+ *
+ * Never mutates its input.
+ */
+export declare function applyWorkspaceTrust(resolved: ResolvedSettings, opts?: WorkspaceTrustFilterOptions): Settings;

package/dist/settings/sources.d.ts

@@ -0,0 +1,29 @@
+import { type BrandProfile } from "../brand.js";
+import { type HomeBrand } from "../paths/home.js";
+import type { Settings, SettingSource } from "./types.js";
+export interface SettingsPathOptions {
+    cwd: string;
+    /** Explicit resolved home root; when omitted it is resolved from `env` and `brand`. */
+    winterHome?: string;
+    env?: Record<string, string | undefined>;
+    /**
+     * P7a (D19): the session's resolved brand profile. Omitted means Winter's own
+     * (`WINTER_BRAND`), so every caller predating the profile keeps exactly today's paths.
+     */
+    brand?: HomeBrand & Pick<BrandProfile, "projectDirName">;
+}
+export declare function settingsPathFor(source: SettingSource, opts: SettingsPathOptions): string;
+export interface LoadedSettingsFile {
+    /** Absent entirely when the file does not exist -- an absent file contributes NO source entry. */
+    present: boolean;
+    loaded: boolean;
+    error?: string;
+    values: Settings;
+}
+/**
+ * Reads one settings file. NEVER throws: a missing file reports `present: false`; anything that
+ * exists but cannot be used (unreadable, unparseable, or a non-object top level) reports
+ * `present: true, loaded: false` with a human-readable `error` and an EMPTY value map, so a
+ * malformed repo-committed file can never silently contribute a partial document.
+ */
+export declare function loadSettingsFile(path: string): Promise<LoadedSettingsFile>;

package/dist/settings/types.d.ts

@@ -0,0 +1,291 @@
+import type { BrandProfile } from "../brand.js";
+/**
+ * P7a (D19): the brand fields the settings cascade needs — the project dot-dir it looks in, and the
+ * env prefix + home dir the user tier resolves through. A `Pick`, not the whole profile, so a
+ * caller can thread three fields rather than construct one.
+ */
+export type SettingsBrand = Pick<BrandProfile, "envPrefix" | "homeDirName" | "projectDirName">;
+import type { ModelSlotSetting } from "../protocol/config.js";
+/** The three settings FILE tiers a session may load. `sdk.d.ts:7917`, verbatim and in pinned order. */
+export type SettingSource = "user" | "project" | "local";
+/** Pinned order (`sdk.d.ts:7917`). Also the value `settingSources: undefined` means (all three). */
+export declare const SETTING_SOURCES: readonly SettingSource[];
+/** `sdk.d.ts:2783`: `SettingSource | 'managed' | 'flag'`. `'flag'` is R5-8's "inline/sdk" position. */
+export type ResolvedSettingSource = SettingSource | "managed" | "flag";
+/** `sdk.d.ts:2310`, verbatim -- how a `managed` value reached this process. */
+export type PolicySettingsOrigin = "helper" | "remote" | "plist" | "hklm" | "file" | "parent" | "hkcu";
+export interface SettingsHookHandler {
+    /** `"command"` is the only shape a settings file can express; see buildHookEntriesFromSettings. */
+    type?: string;
+    command?: string;
+    /** SECONDS (HookCallbackMatcher.timeout's pinned unit) -- converted to ms exactly once, at entry-build time. */
+    timeout?: number;
+}
+export interface SettingsHookMatcherGroup {
+    matcher?: string;
+    hooks?: SettingsHookHandler[];
+}
+/** Open-keyed for the same reason RuntimeHooksConfig is (protocol/config.ts): unknown event names are accepted, preserved and inert. */
+export type SettingsHooksConfig = Partial<Record<string, SettingsHookMatcherGroup[]>>;
+export interface SettingsPermissionsBlock {
+    allow?: string[];
+    ask?: string[];
+    deny?: string[];
+    /** An OPEN string at this layer: a settings file is JSON, so an invalid mode must degrade at the consumer, never be assumed pre-validated. */
+    defaultMode?: string;
+    disableBypassPermissionsMode?: boolean;
+    additionalDirectories?: string[];
+    [key: string]: unknown;
+}
+export interface Settings {
+    permissions?: SettingsPermissionsBlock;
+    hooks?: SettingsHooksConfig;
+    env?: Record<string, string>;
+    apiKeyHelper?: string;
+    /** `sdk.d.ts:7270` */
+    outputStyle?: string;
+    /** `sdk.d.ts:7734` */
+    autoMemoryEnabled?: boolean;
+    /**
+     * `sdk.d.ts:7738`. Its own pinned doc (`7736`) says a PROJECT-set value is ignored for security --
+     * the one per-key project-source restriction the declaration actually states. See OVERLAY_NEVER_KEYS.
+     */
+    autoMemoryDirectory?: string;
+    /** `sdk.d.ts:7693` */
+    plansDirectory?: string;
+    /** `sdk.d.ts:6047`: the value is `string[] | boolean | object`, NOT a boolean map. */
+    enabledPlugins?: Record<string, string[] | boolean | Record<string, unknown>>;
+    /**
+     * `sdk.d.ts:7755`. NEGATIVE sense, one-member literal -- there is NO `autoMode` key in the pinned
+     * declaration (OQ-P5-2). Restrictive, so it is safe from every tier and is NOT an overlay-never key.
+     */
+    disableAutoMode?: "disable";
+    /**
+     * WINTER-DEFINED (disclosed): WS-07 §3.2's "`autoMode` is never taken from project/local" names a
+     * key the pin does not have. Winter keeps the key and the restriction, narrowed per RULING P5-A to
+     * the PROJECT tier only (the pinned analogue at `autoMemoryDirectory` is project-only).
+     */
+    autoMode?: string;
+    /** `sdk.d.ts:5651`. Per-skill visibility: `on` | `name-only` | `user-invocable-only` | `off`; an unrecognised value reads as `on`. */
+    skillOverrides?: Record<string, string>;
+    /** `sdk.d.ts:5657`. Removes the BUILTIN skill tier and nothing else. */
+    disableBundledSkills?: boolean;
+    /** `sdk.d.ts:5988`. `true`, or the areas (`skills`/`agents`/`hooks`/`mcp`) restricted to plugin contributions only. */
+    strictPluginOnlyCustomization?: boolean | string[];
+    /** `sdk.d.ts:5499`. Per-description cap in the model-facing skill listing (default 1536 chars). */
+    skillListingMaxDescChars?: number;
+    /** `sdk.d.ts:5503`. The listing's share of the context window (default 0.01). */
+    skillListingBudgetFraction?: number;
+    /**
+     * A settings-tier MCP server block. Deliberately `Record<string, unknown>` rather than a typed
+     * server union: `settings/loaders/mcp-config.ts` validates each entry and `resolveMcpServerSources`
+     * is the sole authority on the shapes, so a type here would be a second, drift-prone declaration
+     * of a contract that already has one.
+     */
+    mcpServers?: Record<string, unknown>;
+    /**
+     * WINTER-DEFINED (WS-13b R6b-7, disclosed): per-provider enablement, keyed by catalog provider id.
+     *
+     * Its whole reason for existing is the reversion condition. `xai-oauth` ships on prong 2 of the
+     * admission rule -- a vendor's public product client used with an honest Winter identity -- and
+     * WS-13b §4 requires that a vendor rejecting that identity can be answered WITHOUT a release. A
+     * setting is that answer; a compile-time constant is not.
+     *
+     * ABSENT MEANS ENABLED. Silence is not a disablement, so an unlisted provider resolves normally
+     * and only an explicit `enabled: false` refuses.
+     *
+     * RESTRICTIVE-ONLY ACROSS TIERS (RULING R6b-9), enforced by `restrictProviderEnables` in
+     * `resolve.ts` rather than by the ordinary merge: the effective value is `false` if ANY tier says
+     * `false`, and a lower tier's `true` never re-enables what a higher one disabled. Without that,
+     * a cloned repository's PROJECT settings file could put back a provider its operator withdrew —
+     * and this key IS the reversion switch (R6b-7 / WS-13b §4), so a switch a repository can flip back
+     * would not be one.
+     *
+     * NOT an OVERLAY_NEVER_KEY, deliberately: a never-key drops the project tier's value entirely,
+     * which would also drop a project's legitimate `false`. Disabling is a tightening every tier may
+     * make; only the enabling direction is restricted — the same asymmetry `permissions.deny` and
+     * `permissions.allow` already carry.
+     */
+    providers?: Record<string, {
+        enabled?: boolean;
+    }>;
+    /**
+     * WINTER-DEFINED (WS-13c §5, D27, disclosed): the user's OWN four options, with the facing names
+     * that show on the Agent tool and the default model switcher.
+     *
+     * 1–4 entries. Honoured from the USER tier and the TRUSTED project tier only (R13c-7) — an
+     * untrusted project's set is ignored whole and recorded as `modelSlotsIgnored:
+     * "untrusted-project"`. That gate is the point of the key, not a precaution around it: a cloned
+     * repository that could map `cheap` to Astra would be choosing what the user's agent spends.
+     *
+     * Validated WHOLE (never partially): a set with one bad entry is ignored entirely and the failing
+     * entry recorded, because a partially-applied set is a lineup the user did not ask for.
+     */
+    modelSlots?: ModelSlotSetting[];
+    /**
+     * WINTER-DEFINED (WS-13c §4 step 3-ii, disclosed): an ordered list of provider ids, consulted
+     * after the family's own `vendorProviders` and before the admission-tier fallback.
+     *
+     * A PREFERENCE, never an admission: a provider named here still needs a credential and still
+     * obeys `providers.<id>.enabled`. Same tiers and same hot-reload as `modelSlots`.
+     */
+    preferredProviders?: string[];
+    /**
+     * WINTER-DEFINED (D30, WS-06 §4's advisor amendment, disclosed): which model the ADVISOR consults.
+     *
+     * `model` names a slot name, a canonical model id or a catalog key, resolved through WS-13c §4 —
+     * the same path the session model takes, so it obeys credentials, `providers.<id>.enabled` and the
+     * vendor-first order, and an unresolvable value is a typed refusal rather than a substitution.
+     *
+     * SAME TIERS AS `modelSlots`, deliberately: the user tier and the TRUSTED project tier only. The
+     * advisor sends this session's conversation to whatever this names, so a cloned repository that
+     * could set it would be choosing where the user's transcript goes — the identical argument that
+     * gates `modelSlots`, with a higher price for getting it wrong.
+     *
+     * HOT (a Global Constraint of this phase): it takes effect at the next quiescent boundary through
+     * the live settings getter, never at a restart. Unset means the per-family default (D30: a gpt
+     * session -> `astra`, a claude session -> `fable`, any other family -> its slot 1, a family with
+     * no slots -> the session's own model). `Options.advisor.model` outranks it.
+     *
+     * DECLARED AT P7a'S SPINE; the resolution and the trust gate are Lane B's.
+     */
+    advisor?: {
+        model?: string;
+    };
+    /**
+     * DERIVED provenance — written by `resolve.ts` / the runtime, NEVER read from a settings file.
+     *
+     * It records WHY a `modelSlots` set did not take effect, so a host can say so instead of showing
+     * the default lineup with no explanation: the set came from an untrusted project tier, it failed
+     * whole-set validation, or the session's effective main model is a Claude model and D25 pins that
+     * enum. A file that sets this key is stating a conclusion it does not get to draw; the resolver
+     * overwrites it.
+     */
+    modelSlotsIgnored?: "untrusted-project" | "invalid" | "claude-pinned";
+    [key: string]: unknown;
+}
+/**
+ * Narrows `Settings.providers` into the shape selection consumes: every declared id present, with an
+ * explicit boolean.
+ *
+ * ONE narrowing, at one place (the rider-26 pattern the six P5 keys established), so a typo'd key or
+ * a JSON file saying `"enabled": "false"` is handled here rather than at each reader with a cast.
+ *
+ * Total by construction: a settings file is JSON and may say anything. A non-object entry, an empty
+ * provider id and a non-boolean `enabled` are all DROPPED rather than coerced -- coercing `"false"`
+ * to `false` would disable a provider on the strength of a typo, and coercing it to `true` would
+ * pretend the user said something they did not. Only a literal `false` disables.
+ */
+export declare function providerSettingsFrom(settings: Settings | undefined): Record<string, {
+    enabled: boolean;
+}>;
+/** `sdk.d.ts:2413-2419`, verbatim. */
+export interface ProvenanceEntry {
+    source: ResolvedSettingSource;
+    path?: string;
+    policyOrigin?: PolicySettingsOrigin;
+}
+/** One tier's contribution, RAW (never overlay-filtered) -- the pinned `sources` escape hatch (`sdk.d.ts:2764-2767`). */
+export interface ResolvedSettingsSourceEntry {
+    source: ResolvedSettingSource;
+    settings: Settings;
+    path?: string;
+    policyOrigin?: PolicySettingsOrigin;
+}
+/**
+ * `sdk.d.ts:2759-2774`, verbatim three fields.
+ *
+ * `provenance` is per TOP-LEVEL key only (`2762`) -- runtime-confirmed by capture (1): with
+ * `permissions.allow` from project and `permissions.defaultMode` from local, the merged
+ * `effective.permissions` carried both and `provenance.permissions.source` reported `local` alone.
+ * A consumer that needs finer attribution reads `sources` (which this implementation orders
+ * highest-precedence first), exactly as the pinned field's own doc directs.
+ */
+export interface ResolvedSettings {
+    effective: Settings;
+    provenance: Partial<Record<string, ProvenanceEntry>>;
+    sources: ResolvedSettingsSourceEntry[];
+}
+/** `sdk.d.ts:2815-2843`, verbatim four fields -- ONE options object, not four positional parameters. */
+export interface ResolveSettingsOptions {
+    cwd?: string;
+    settingSources?: SettingSource[];
+    /**
+     * Programmatic policy tier. The pinned doc (`2018-2040`) says the pinned runtime filters this tier
+     * RESTRICTIVE-ONLY.
+     *
+     * WINTER DOES NOT APPLY THAT FILTER (Phase 5 fix wave, A-4 -- said plainly here, where the old
+     * one-liner quoted the pin's behaviour in a way a reader could take for Winter's). A managed tier
+     * is merged like any other, at the top of the precedence order, so a managed PERMISSIVE rule
+     * widens where the pin would drop it. That is a DISCLOSED DIVERGENCE, not an oversight: the pinned
+     * filter's exact rule is not stated anywhere in scope, no capture exercised it, and inventing one
+     * would be Winter guessing at a security-relevant transformation. The direction of the divergence
+     * is the permissive one, which is why it is disclosed here rather than buried in a report.
+     */
+    managedSettings?: Settings;
+    /** Remote policy payload -- pinned doc `2838-2839`: explicitly UNfiltered where `managedSettings` is filtered. */
+    serverManagedSettings?: Settings;
+}
+/** A per-tier record carrying what the pinned `sources` entry cannot: whether the file loaded, and why not. */
+export interface DetailedSettingsSourceEntry extends ResolvedSettingsSourceEntry {
+    /** True iff a file/inline value existed AND parsed to a JSON object. */
+    loaded: boolean;
+    /** Present iff `loaded` is false because something existed but could not be used (parse error, wrong shape, unreadable). */
+    error?: string;
+    /** Alias of `settings`, kept under the brief's own field name so lane code can use either. */
+    values: Settings;
+}
+export interface DetailedResolvedSettings extends ResolvedSettings {
+    /** Highest-precedence first, same order as `sources`; a superset of it. */
+    perSource: DetailedSettingsSourceEntry[];
+}
+export interface ResolveSettingsDetailedOptions extends ResolveSettingsOptions {
+    /** RULING P5-A's host-declared workspace-trust bit, threaded by production-wiring. Absent = untrusted (fail-safe): the project tier's `modelSlots`/`preferredProviders` are dropped (WS-13c §5, R-6c-16). */
+    trustedWorkspace?: boolean;
+    /** Explicit resolved home root. Tests MUST pass this rather than mutating process.env (a shared-process `bun test` run would race). */
+    winterHome?: string;
+    /** Injectable environment for home resolution; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /**
+     * P7a (D19): the session's resolved brand profile, which decides the PROJECT tier's directory
+     * (`<cwd>/<projectDirName>/settings.json`) and the env name the user tier's home is read from.
+     * Absent means Winter's own profile — every caller predating it keeps today's paths exactly.
+     */
+    brand?: SettingsBrand;
+    /** The `'flag'` tier -- R5-8's "inline/sdk" position. Unreachable from the pinned options object, which has no inline input. */
+    inline?: Settings;
+}
+/**
+ * Keys that are NEVER taken from PROJECT settings.
+ *
+ * Scope correction vs the Task 2 brief: the brief said "project/local"; RULING P5-A (and the one
+ * pinned per-key restriction this can mirror, `autoMemoryDirectory`'s own doc at `sdk.d.ts:7736`)
+ * make it PROJECT-only. `local` is gitignored and personal -- it carries the same authority as
+ * `user` under the captured per-tier filter; only the repo-committed tier is restricted.
+ *
+ * `disableAutoMode` is deliberately ABSENT: it is restrictive (`'disable'` is its only value), so a
+ * repo-committed file setting it can only ever tighten, which every tier is allowed to do.
+ *
+ * `outputStyle` JOINED IN THE PHASE 5 FIX WAVE (whole-branch m1). RULING P5-G gates a project-tier
+ * style FILE to append-only -- a checked-in project-tier output-style file may add to the prompt but
+ * never replace it. It says nothing about SELECTION, and selection is the other half of the same
+ * power: a project `settings.json` naming one of the USER's own styles -- one the user wrote with
+ * `keep-coding-instructions: false` -- would replace the authored prompt on the strength of a
+ * repository's choice. The style file is the user's; the decision to apply it was not. Same
+ * self-grant shape P5-A closes, arriving through selection rather than through content.
+ *
+ * A host that genuinely wants a per-repository style still has one: `Options.outputStyle`, which is
+ * the host's own configuration and outranks every file tier.
+ */
+export declare const OVERLAY_NEVER_KEYS: readonly string[];
+/**
+ * The permission modes `filterEscalatingDefaultMode` treats as escalating (pinned doc `686-694`).
+ * `plan`/`default` are non-escalating and survive from any tier.
+ */
+export declare const ESCALATING_PERMISSION_MODES: readonly string[];
+/**
+ * PROJECT-tier permission keys that LOAD but never WIDEN in an untrusted workspace (RULING P5-A,
+ * capture (1) cells B/I/O). `deny`/`ask` are deliberately absent: they only ever tighten, and
+ * capture (1) cells K/L prove a project `deny` is honored and beats a local `allow`.
+ */
+export declare const PROJECT_PERMISSIVE_KEYS: readonly string[];

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

@@ -0,0 +1,19 @@
+import { type SessionKey, type SessionStore } from "./session-store.js";
+/**
+ * `resume + forkSession: true` (WS-05 §7) — copies `src`'s entries into a brand-new lowercase
+ * RFC4122 v4 session id, with each copied entry's OWN `sessionId` field rewritten to the fork's
+ * id (uuid/parentUuid/content are otherwise untouched — the fork's conversational identity is
+ * byte-for-byte the source's, just re-owned). `src` is never written to: this only reads it (via
+ * store.load) and appends to the NEW key, so the source stays byte-identical on disk by
+ * construction. No undo/file-history copies (WS-05 §7) — neither exists in this codebase yet, so
+ * there is nothing to carry forward or omit; revisit when either lands.
+ *
+ * Throws `SessionNotFoundError("not_found", ...)` — not resume.ts's ResumeTargetError, which this
+ * primitive no longer has access to post-relocation — when `src` doesn't exist. The public
+ * `forkSession(sessionId, opts)` wrapper in ../sessions.ts already validates existence before
+ * calling this, so that branch is a defensive backstop (a TOCTOU race, or a direct caller) rather
+ * than the primary path a normal caller hits.
+ */
+export declare function forkSessionByKey(store: SessionStore, src: SessionKey): Promise<{
+    sessionId: string;
+}>;

package/dist/store/leases.d.ts

@@ -0,0 +1,15 @@
+export declare class WinterStoreError extends Error {
+    constructor(message: string);
+}
+export declare class WinterStoreLeaseError extends WinterStoreError {
+    readonly heldByPid: number;
+    constructor(message: string, heldByPid: number);
+}
+export interface LeaseInfo {
+    pid: number;
+    startTimeMs: number;
+}
+export declare function isPidAlive(pid: number): boolean;
+export declare function writeAllSync(fd: number, buf: Buffer): void;
+export declare function readLeaseInfo(lockPath: string): LeaseInfo | null;
+export declare function acquireLease(lockPath: string): LeaseInfo;

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

@@ -0,0 +1,111 @@
+export { WinterStoreError, WinterStoreLeaseError } from "./leases.js";
+export type SessionKey = {
+    projectKey: string;
+    sessionId: string;
+    subpath?: string;
+};
+export type SessionStoreEntry = {
+    type: string;
+    uuid?: string;
+    timestamp?: string;
+    [key: string]: unknown;
+};
+export type SessionSummaryEntry = {
+    sessionId: string;
+    entryCount: number;
+    mtime: number;
+    lastEntryType?: string;
+    lastTimestamp?: string;
+    producerRuntime?: "claude-agent" | "winter-agent";
+    producerEngineVersion?: string;
+    dialectFamily?: "claude-code-jsonl";
+    projectDirName?: string;
+    name?: string;
+    tags?: string[];
+    [key: string]: unknown;
+};
+export declare const DIALECT_RECORD_ENTRY_TYPE = "winter_dialect_record";
+/**
+ * The provider-state sidecar's filename suffix (P6 R6-7): `<sessionId>.provider-state.jsonl`.
+ *
+ * DECLARED HERE, imported by the runtime -- one declaration, and this is the package that can own it:
+ * the sdk cannot import the runtime (WS-02 §3's dependency inversion), and `delete()` below must
+ * name the file to remove it. The runtime owns the RECORD SEMANTICS (`store/provider-state.ts`: the
+ * envelope, the write-ahead ordering, the chain); this package owns the sidecar's LIFECYCLE at the
+ * path level, because that is where the deletion transaction lives.
+ */
+export declare const PROVIDER_STATE_FILE_SUFFIX = ".provider-state.jsonl";
+export type SessionStore = {
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    listSessions?(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    listSessionSummaries?(projectKey: string): Promise<SessionSummaryEntry[]>;
+    delete?(key: SessionKey): Promise<void>;
+    listSubkeys?(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+};
+export declare class WinterCompatibilitySessionStore implements SessionStore {
+    private readonly winterHome;
+    constructor(opts: {
+        winterHome: string;
+    });
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    listSessions(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    listSessionSummaries(projectKey: string): Promise<SessionSummaryEntry[]>;
+    delete(key: SessionKey): Promise<void>;
+    listSubkeys(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+    listProjectKeys(): Promise<string[]>;
+    /**
+     * ONE session's folded summary, read by its own path.
+     *
+     * Phase 6 Task 3 (review round 2, M2). `listSessionSummaries` reads and parses EVERY
+     * `*.summary.json` in the project directory, which is O(#sessions) -- fine for enumerating a picker,
+     * wrong for the one question a RESUME asks about ITSELF ("did this session record a provider
+     * identity?"), which a busy project would pay for on every resume.
+     *
+     * Deliberately NOT part of the exported `SessionStore` type -- same posture as `listProjectKeys`/
+     * `mergeSessionMetadata`/`claimWriterLease` above: WS-03 §10 pins that surface as exactly its six
+     * members, and a caller reaches this through a LOCAL intersection type instead. `null` for a session
+     * with no summary yet, which is indistinguishable from one that never existed and is the honest
+     * answer to both.
+     */
+    /**
+     * P6 fix wave (the public `forkSession()` door): copies a session's provider-state sidecar onto a
+     * FORK. Winter-only, on the concrete class like `readSessionSummary`, and generic by design -- the
+     * sdk cannot import the runtime's record codec (WS-02 §3), so this is a LINE rewrite: every parseable
+     * record is re-owned to the fork's `sessionId` and given a FRESH `uuid` (the store's idempotency key;
+     * two sessions sharing record uuids would collide into one upserted row) while its `anchorUuid` stays
+     * -- `forkSessionByKey` keeps entry uuids, which is exactly what makes the copied anchors meaningful.
+     * An unparseable line (a torn tail) is skipped, never fatal; a source with no sidecar copies nothing.
+     * Written with the same 0600 / O_APPEND / O_NOFOLLOW / fsync posture the transcript gets. Returns the
+     * number of records copied.
+     */
+    copyProviderStateForFork(src: SessionKey, dest: SessionKey): Promise<number>;
+    readSessionSummary(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<SessionSummaryEntry | null>;
+    mergeSessionMetadata(key: {
+        projectKey: string;
+        sessionId: string;
+    }, patch: {
+        name?: string;
+        tags?: string[];
+    }): Promise<void>;
+    acquireSessionLease(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<void>;
+}

package/dist/transport.d.ts

@@ -0,0 +1,26 @@
+export interface SpawnedRuntimeProcess {
+    stdin: {
+        write(chunk: string): void;
+        end(): void;
+    };
+    stdout: AsyncIterable<string>;
+    stderr?: AsyncIterable<string>;
+    kill(signal?: string): void;
+    readonly exited: Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    readonly pid: number | null;
+}
+export interface SpawnRuntimeOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    signal?: AbortSignal;
+}
+export type SpawnClaudeCodeProcess = (opts: SpawnRuntimeOptions) => SpawnedRuntimeProcess;
+export declare function resolveRuntimeExecutable(opts: {
+    pathToClaudeCodeExecutable?: string;
+}): string;
+export declare function defaultSpawn(opts: SpawnRuntimeOptions): SpawnedRuntimeProcess;