@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/official/env-allowlist.d.ts

@@ -0,0 +1,237 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { EnvInput, RemoteConfigPolicy } from "../seams/official-adapter.js";
+import type { RuntimeSelection } from "../selection/runtime-selection.js";
+import { AUTH_FAMILY_VARIABLES, allowedAuthVariables, type ClaudeOauthGate } from "./auth.js";
+/**
+ * §3's "smallest set proven required".
+ *
+ * `LC_*` is a FAMILY rather than a name (the locale variables are `LC_ALL`, `LC_CTYPE`, … and a host
+ * legitimately has several), so it is matched by prefix; everything else is exact.
+ */
+export declare const MINIMAL_OS_VARIABLES: readonly string[];
+export declare const MINIMAL_OS_VARIABLE_PREFIXES: readonly string[];
+/** The vendor-named variables this branch sets itself (§1/§3). Claude-mirroring literals (WS-01 §5). */
+export declare const OFFICIAL_RUNTIME_VARIABLES: {
+    readonly configDir: "CLAUDE_CONFIG_DIR";
+    readonly projectDirName: "CLAUDE_CODE_PROJECT_DIR_NAME";
+    readonly tmpdir: "CLAUDE_CODE_TMPDIR";
+};
+/**
+ * Proxy and telemetry variables §3 excludes "unless explicitly configured".
+ *
+ * They are refused by NAME rather than merely omitted because the failure they cause is invisible:
+ * a proxy variable that reached this child routes the runtime's traffic somewhere the host did not
+ * choose and no assertion in a session would ever notice.
+ */
+export declare const PROXY_AND_TELEMETRY_VARIABLES: readonly string[];
+export declare const PROXY_AND_TELEMETRY_PREFIXES: readonly string[];
+/**
+ * R-7b-11: THE FOUR TRAFFIC OPT-OUTS THIS BRANCH SETS ON EVERY CHILD, BY DEFAULT.
+ *
+ * These are not a privacy setting; they are what makes "the pinned artifact" mean one thing. Measured
+ * on 0.3.250 — same binary, same options, same loopback endpoint — the runtime advertises 25 tools
+ * with these unset and 21 with them set; `DesignSync`, `Monitor`, `PushNotification` and
+ * `advisor_20260301:advisor` are present only when its feature-flag CDN answers. A tool surface that
+ * changes with a remote flag under one version defeats WS-02 §6.1's "a new official version is a
+ * reviewed compatibility event": the surface moves with nothing reviewed and nothing versioned.
+ *
+ * WS-14 §3's own words permit this — proxy and telemetry variables reach the child "unless explicitly
+ * configured", and the router configuring them explicitly is that clause, not an exception to it. Two
+ * of the four names (`DISABLE_TELEMETRY`, `DISABLE_ERROR_REPORTING`) are in
+ * `PROXY_AND_TELEMETRY_VARIABLES`, i.e. names this module refuses to let a child INHERIT — which is a
+ * different question from whether this branch SETS them, and the validator below now separates the
+ * two rather than conflating them.
+ *
+ * THEY ARE BRANCH-OWNED, like the config dir: a host may not pass them through `configuredExtras`
+ * (the record would then disagree with the environment), it opts back in with
+ * `OfficialEnvPolicy.remoteConfig: "allow"`, and that choice is recorded on the session's directory
+ * row. A test-only escape hatch is not needed any more — the hermetic beds get this for free.
+ */
+export declare const TRAFFIC_OPT_OUT_VARIABLES: Readonly<Record<string, string>>;
+/** The four names above, for the validator and the drift-gate snapshot. */
+export declare const TRAFFIC_OPT_OUT_VARIABLE_NAMES: readonly string[];
+/** Drops the entries of a path-list value that reach into the vendor's user-level home. */
+export declare function sanitizePathListValue(value: string): string;
+/**
+ * What `buildChildEnv` needs beyond the spine's `EnvInput`.
+ *
+ * TWO FIELDS THE SEAM DOES NOT NAME, and both are per-SESSION rather than per-adapter, so neither
+ * could be answered from the adapter's own configuration:
+ *
+ *   `projectKey`      §3's `CLAUDE_CODE_PROJECT_DIR_NAME` — "Winter's stable transcript key,
+ *                     decoupling the spool's project dir from the legacy encoded-cwd default".
+ *                     MEASURED: with it set, both the spool and the canonical store wrote to
+ *                     `projects/<key>/`; without it, the spool used the encoded absolute cwd.
+ *   `sharedTempRoot`  §3's `CLAUDE_CODE_TMPDIR` — the shared per-user temp root the host derives from
+ *                     `brand.tempRootName`. Passed IN rather than derived here so a test can hand it
+ *                     a `mkdtemp` and so this module spells no product path.
+ *
+ * Declared as an EXTENSION of the pinned seam input rather than as a change to it: a lane may not
+ * edit `src/seams/**`, and structural typing means a host that has these values simply passes the
+ * wider object. The Lane A report carries the two-field diff as the NEEDS_CONTEXT if the spine wants
+ * them named on `EnvInput` itself.
+ */
+export interface OfficialEnvInput extends EnvInput {
+    projectKey?: string;
+    sharedTempRoot?: string;
+}
+/** Host policy for the env builder — §3's "deliberate, documented addition" escape hatch, fenced. */
+export interface OfficialEnvPolicy {
+    /**
+     * Extra variables this deployment deliberately configures (a gateway's proxy, an operator's
+     * telemetry). Named here, they pass the validator; unnamed, they are refused.
+     */
+    configuredExtras?: Readonly<Record<string, string>>;
+    /** Additional env prefixes the HOST owns (its daemon's own product prefix). The brand's is always refused. */
+    hostEnvPrefixes?: readonly string[];
+    /**
+     * Auth-SHAPED variables this deployment has reviewed and needs anyway (review r2, NEW-2).
+     *
+     * The extras door is closed to credential-bearing shapes by default, because the pinned runtime
+     * reads far more of them than any table lists and one of them re-points the whole session. A host
+     * with a real need — a cloud tuning variable its family table does not carry — names it here, which
+     * is §12's own "reviewed compatibility event" rather than a silent addition.
+     */
+    reviewedCredentialShapedExtras?: readonly string[];
+    /**
+     * Execution/indirection variables this deployment has reviewed and needs anyway (item 22, NEW-A).
+     *
+     * The sibling of `reviewedCredentialShapedExtras`, for the other blind spot: names that change how
+     * the child EXECUTES code or authenticates (`BASH_ENV`, `NODE_OPTIONS`, `GIT_ASKPASS`, `LD_*`, …).
+     * They are refused by name even when the pinned registry declares them, because "the artifact reads
+     * it" is exactly why it is dangerous. One name at a time; never a prefix, never a wildcard.
+     */
+    reviewedExecutionExtras?: readonly string[];
+    /**
+     * R-7b-11: `"deny"` (the default) sets `TRAFFIC_OPT_OUT_VARIABLES` on the child; `"allow"` omits
+     * them, letting the runtime fetch its own remote feature configuration.
+     *
+     * ABSENT MEANS DENY, EVERYWHERE — including for a host that never heard of this field, which is the
+     * point: the shipped default must be the one that makes the pin mean one artifact.
+     */
+    remoteConfig?: RemoteConfigPolicy;
+    /** D14's ship gate, threaded to the auth validator. Default: closed. */
+    claudeOauth?: ClaudeOauthGate;
+}
+/**
+ * NAMES THAT CHANGE HOW THE CHILD EXECUTES CODE OR AUTHENTICATES — refused by NAME, always (item 22,
+ * fix-wave re-review NEW-A).
+ *
+ * WHY A LITERAL SET AND NOT A RULE. The extras door already has two rules and BOTH are blind here.
+ * The credential rule is a SHAPE rule (`_KEY`, `TOKEN`, `OAUTH`, …) and none of these names looks
+ * like a credential; the positive-allowlist rule admits any name the pinned artifact's own registry
+ * declares, and all five of the headline names below ARE declared there — the artifact reads them, so
+ * the registry is right to list them, and that is precisely why "the registry declares it" cannot be
+ * the whole test. Measured on the head before this set existed: `BASH_ENV`,
+ * `CLAUDE_CODE_SHELL_PREFIX`, `NODE_OPTIONS`, `GIT_ASKPASS` and `CLAUDE_CODE_GIT_BASH_PATH` were all
+ * ADMITTED through `configuredExtras`, while the README told hosts they were refused.
+ *
+ * WHAT THESE NAMES DO, which is the reason they are one class:
+ *
+ *   * `BASH_ENV` / `ENV` / `CLAUDE_CODE_SHELL_PREFIX` — a file the shell SOURCES on every
+ *     non-interactive start, or a prefix wrapped around every command. Arbitrary code before any
+ *     command the containment floor ever sees.
+ *   * `NODE_OPTIONS` / `LD_PRELOAD` / `LD_*` / `DYLD_*` — loader and runtime hooks. `--require` runs
+ *     a module inside the child before its own entry point.
+ *   * `GIT_ASKPASS` / `SSH_ASKPASS` / `SUDO_ASKPASS` / `GIT_SSH*` / `GIT_CREDENTIAL_HELPER` — programs
+ *     the child EXECUTES to obtain credentials. Not credential-shaped; credential-producing.
+ *
+ * THE SET IS THE ARTIFACT'S OWN, NOT OURS (round 3, NEW-H). The first version named five measured
+ * headline variables and the README described the CLASS — which was wider than the set: nineteen more
+ * registry names of exactly that class rode the door, and two were then measured doing what the class
+ * describes. `CLAUDE_CODE_SHELL` made the runtime run a planted program as the Bash tool's shell (114
+ * invocations in one session, the marker visible in the tool result the model was shown), and
+ * `CLAUDE_ENV_FILE` was sourced into every Bash call — `BASH_ENV` by another door, which made the
+ * `BASH_ENV` refusal decorative. So the list below is the PINNED ARTIFACT'S OWN scrub list (the
+ * environment it strips before running its policy helper — the vendor's definition of this class, and
+ * therefore the pin's rather than our taste) plus the runtime-specific doors that are not on it. The
+ * drift gate in `test/official/env-allowlist.test.ts` fails when a pin bump adds a registry name of
+ * this shape that nothing classifies.
+ *
+ * The exposure was bounded (the `base` door drops these silently, so only a host naming one itself
+ * could pass it), which is why this is a scheduled hardening rather than an incident — but "the
+ * README claims a refusal the code does not make" is the one state that must not ship.
+ *
+ * IT IS STILL A DOOR, NOT A WALL. A deployment that has REVIEWED a specific name and needs it says so
+ * in `reviewedExecutionExtras`, one name at a time — the same shape as the credential hatch, and a
+ * reviewed compatibility event rather than a silent addition.
+ */
+export declare const EXECUTION_INDIRECTION_ENV_NAMES: readonly string[];
+/**
+ * The PREFIXES, which no closed list can enumerate — the artifact's own scrub prefixes plus `DYLD_`.
+ *
+ * `GIT_` IS A WHOLE PREFIX, and that is the vendor's call rather than ours: the artifact scrubs it
+ * entirely before running its policy helper, because `GIT_CONFIG_GLOBAL`/`_SYSTEM`/`_COUNT` name files
+ * git reads for a `credential.helper`, `GIT_SSH_COMMAND`/`GIT_EXTERNAL_DIFF`/`GIT_PAGER` name programs
+ * git RUNS, and `GIT_ASKPASS` supplies credentials. A host that needs one names it in
+ * `reviewedExecutionExtras`.
+ */
+export declare const EXECUTION_INDIRECTION_ENV_PREFIXES: readonly string[];
+/** True for a name that changes how the child executes code or authenticates. Case-insensitive. */
+export declare function isExecutionIndirectionVariable(name: string): boolean;
+/** Picks the minimal OS set out of a caller-supplied source. The host passes `process.env`; we never do. */
+export declare function minimalOsEnvironmentFrom(source: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/**
+ * Builds the child environment: §3's table, in one pass, from an allowlist.
+ *
+ * ORDER IS ALPHABETICAL IN THE RESULT because this object is a golden-capture input and a stable
+ * fixture must not depend on which branch of the builder ran first.
+ */
+export declare function buildOfficialChildEnv(input: OfficialEnvInput, policy?: OfficialEnvPolicy): Record<string, string>;
+/**
+ * §3's MUST-NOT list, as a refusal.
+ *
+ * Every clause is a leak with a name:
+ *   * a product-prefixed variable hands the child the DAEMON's configuration, which is how a spawned
+ *     runtime ends up reading the host's own home directory;
+ *   * `CLAUDE_CODE_OAUTH_TOKEN` is the credential D14 gates and §12 routes through the spool instead;
+ *   * an undeclared proxy or telemetry variable silently redirects or duplicates traffic;
+ *   * a VALUE pointing into the vendor's user-level home is the isolation failure this whole branch
+ *     exists to prevent — and it is a value check, because the variable that carries it can be
+ *     anything at all (WS-17 row 4's "zero visibility into the vendor home").
+ */
+export declare function assertNoForbiddenChildVariables(env: Readonly<Record<string, string>>, args: {
+    brand: Pick<BrandProfile, "envPrefix" | "processLabel">;
+    selection?: Pick<RuntimeSelection, "authFamily" | "providerId">;
+    policy?: OfficialEnvPolicy;
+    branchLabel?: string;
+}): void;
+/**
+ * WS-17's drift-gate input: the allowlist as NAMES, grouped, with the pinned runtime version they
+ * were captured against. Never a value — see this module's header.
+ */
+export interface EnvAllowlistSnapshot {
+    pinnedRuntime: string;
+    runtimeVariables: readonly string[];
+    minimalOsVariables: readonly string[];
+    minimalOsVariablePrefixes: readonly string[];
+    authFamilies: Readonly<Record<string, readonly string[]>>;
+    neverInjected: readonly string[];
+    refusedProxyTelemetry: readonly string[];
+    refusedProxyTelemetryPrefixes: readonly string[];
+    /** R-7b-11: the names this branch SETS by default. A change here is a reviewed compatibility event too. */
+    trafficOptOuts: readonly string[];
+    /** R-7b-13: the shape the pin accepts for the transcript project key — a rejected one is substituted. */
+    projectDirNamePattern: string;
+}
+/** The pinned artifact every name above was captured from (WS-02 §6.1: an upgrade is reviewed). */
+export declare const PINNED_OFFICIAL_RUNTIME = "0.3.250";
+/**
+ * R-7b-13: the shape the PINNED ARTIFACT accepts for `CLAUDE_CODE_PROJECT_DIR_NAME`.
+ *
+ * A PINNED LITERAL, read off 0.3.250 itself, because the consequence of getting it wrong is silent:
+ * the runtime validates the variable against this pattern and, when it does not match, FALLS BACK TO
+ * ITS OWN cwd-derived key. Measured — a 70-character key left the transcript under the vendor's own
+ * realpath-derived name while the directory row, the child environment and the auto-memory directory
+ * all named the host's key. That is "the record and the transcript disagree", which is the class WS-14
+ * §1 exists to prevent, and no assertion downstream would ever notice it.
+ *
+ * So a key this pattern rejects is REFUSED here rather than passed through and quietly ignored. The
+ * drift gate re-checks the literal on every pin bump.
+ */
+export declare const PINNED_PROJECT_DIR_NAME_PATTERN = "^[A-Za-z0-9_-]{1,64}$";
+export declare function officialEnvAllowlistSnapshot(): EnvAllowlistSnapshot;
+/** Every name the snapshot mentions, flattened — what a scan of the pinned artifact is run against. */
+export declare function officialEnvAllowlistNames(): readonly string[];
+/** Re-exported so a caller building a plan has one import site for the family tables. */
+export { AUTH_FAMILY_VARIABLES, allowedAuthVariables };

package/dist/official/env-registry-rule.d.ts

@@ -0,0 +1,12 @@
+/** Segments that make a variable name credential-bearing, whatever else it says. */
+export declare const CREDENTIAL_NAME_KEYWORDS: readonly string[];
+/**
+ * Every env-shaped accessor the pinned artifact declares (`NAME:()=>fn` in its own export map).
+ *
+ * Filtered to env-SHAPED names — an upper- or lower-snake identifier with at least one underscore —
+ * because the same construct carries minified function names, and a registry padded with those would
+ * make the drift gate noisy rather than informative.
+ */
+export declare function extractEnvRegistry(artifact: string): string[];
+/** The independent rule: is this NAME credential-bearing? Case-insensitive, by segment. */
+export declare function isCredentialByName(name: string): boolean;

package/dist/official/env-registry.d.ts

@@ -0,0 +1,3 @@
+export declare const PINNED_ENV_REGISTRY_SIZE = 886;
+/** The non-credential subset of the pinned artifact's own env registry (672 names). */
+export declare const NON_CREDENTIAL_ENV_REGISTRY: readonly string[];

package/dist/official/errors.d.ts

@@ -0,0 +1,250 @@
+import { RuntimeSdkError } from "../errors.js";
+/** The WS-03 §11 classes an official-branch failure maps onto, by exported name. */
+export type WinterErrorClassName = "WinterSDKError" | "CLIConnectionError" | "ProcessError" | "ResultError" | "ProtocolDecodeError" | "AbortError" | "SessionNotFoundError";
+/**
+ * WS-14 §9's crash classes — the failures that describe the CHILD PROCESS rather than the turn.
+ *
+ * `killed` is the fifth member §9 names and the one that is not itself an error condition: a
+ * supervised teardown kills the child on purpose, and the class exists so the projector can tell
+ * "we ended it" from "it died".
+ */
+export type OfficialCrashClass = "executable-not-found" | "connection-failure" | "malformed-protocol" | "nonzero-exit" | "killed" | "stdout-unterminated";
+/** Every code in this taxonomy, in WS-14 §13's own order. Exported so a test can assert completeness. */
+export declare const OFFICIAL_ERROR_CODES: readonly ["official_configuration_invalid", "official_executable_not_found", "official_connection_failure", "official_malformed_protocol", "official_nonzero_exit", "official_killed", "official_agent_result_failure", "official_api_failure", "official_tool_failure", "official_permission_denied", "official_mcp_failure", "official_session_store_failure", "official_session_not_found", "official_invalid_resume", "official_interrupted", "official_stdout_unterminated", "official_containment_breach"];
+export type OfficialErrorCode = (typeof OFFICIAL_ERROR_CODES)[number];
+/**
+ * The base class of the official branch's taxonomy.
+ *
+ * Extends the router's own `RuntimeSdkError` so a host can catch this package's whole family with one
+ * `instanceof`, exactly as `src/errors.ts` promises.
+ */
+export declare abstract class OfficialBranchError extends RuntimeSdkError {
+    abstract readonly code: OfficialErrorCode;
+    abstract readonly winterClass: WinterErrorClassName;
+    /** Present only on the process-lifecycle classes (§9). */
+    readonly crashClass?: OfficialCrashClass;
+    /** WS-14 §14: the internal diagnostics label of this branch, so a log line names the branch. */
+    readonly branch: string;
+    constructor(message: string, branchLabel: string, options?: {
+        cause?: unknown;
+    });
+}
+/** §13.1 — an `Options` combination this branch refuses to build (§5.1's withheld options live here). */
+export declare class OfficialConfigurationError extends OfficialBranchError {
+    readonly code = "official_configuration_invalid";
+    readonly winterClass = "WinterSDKError";
+    /** WHICH option was wrong, so a host can point at a field rather than parse prose. */
+    readonly option: string;
+    constructor(args: {
+        option: string;
+        reason: string;
+        branchLabel: string;
+    });
+}
+/** §13.2 / §9 — the vendored runtime is not where the host said it was. */
+export declare class OfficialExecutableNotFoundError extends OfficialBranchError {
+    readonly code = "official_executable_not_found";
+    readonly winterClass = "CLIConnectionError";
+    readonly crashClass: "executable-not-found";
+    readonly path: string;
+    constructor(args: {
+        path: string;
+        branchLabel: string;
+        cause?: unknown;
+    });
+}
+/** §13.3 / §9 — the child started but the stdio channel never came up. */
+export declare class OfficialConnectionError extends OfficialBranchError {
+    readonly code = "official_connection_failure";
+    readonly winterClass = "CLIConnectionError";
+    readonly crashClass: "connection-failure";
+    constructor(args: {
+        reason: string;
+        branchLabel: string;
+        cause?: unknown;
+    });
+}
+/** §13.4 / §9 — a frame arrived that is not the pinned protocol. */
+export declare class OfficialProtocolError extends OfficialBranchError {
+    readonly code = "official_malformed_protocol";
+    readonly winterClass = "ProtocolDecodeError";
+    readonly crashClass: "malformed-protocol";
+    constructor(args: {
+        reason: string;
+        branchLabel: string;
+    });
+}
+/**
+ * §13.5 / §9 — the child exited nonzero.
+ *
+ * `stderrTail` is here because §6 rule 6 requires stderr to be DRAINED CONTINUOUSLY: the drain has to
+ * put what it saw somewhere, and the exit error is the only place a consumer will look. Bounded by
+ * the proxy (a runaway child must not turn an error message into a memory leak).
+ */
+export declare class OfficialNonzeroExitError extends OfficialBranchError {
+    readonly code = "official_nonzero_exit";
+    readonly winterClass = "ProcessError";
+    readonly crashClass: "nonzero-exit";
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stderrTail: string;
+    constructor(args: {
+        exitCode: number | null;
+        signal: string | null;
+        stderrTail: string;
+        branchLabel: string;
+    });
+}
+/** §9's fifth crash class — a supervised kill. Distinct from a nonzero exit: this one WE caused. */
+export declare class OfficialKilledError extends OfficialBranchError {
+    readonly code = "official_killed";
+    readonly winterClass = "ProcessError";
+    readonly crashClass: "killed";
+    readonly signal: string;
+    constructor(args: {
+        signal: string;
+        reason: string;
+        branchLabel: string;
+    });
+}
+/** §8's post-hoc breach — see `OFFICIAL_ERROR_CODES`. Never a crash class: the process is healthy. */
+export declare class OfficialContainmentBreachError extends OfficialBranchError {
+    readonly code = "official_containment_breach";
+    readonly winterClass = "WinterSDKError";
+    readonly tool: string;
+    readonly created: readonly string[];
+    readonly removed: readonly string[];
+    readonly retained: readonly string[];
+    constructor(args: {
+        toolName: string;
+        created: readonly string[];
+        removed: readonly string[];
+        retained: readonly string[];
+        branchLabel: string;
+    });
+}
+/** M4's sixth crash class: the child exited and its stdout never closed. See `OFFICIAL_ERROR_CODES`. */
+export declare class OfficialStdoutUnterminatedError extends OfficialBranchError {
+    readonly code = "official_stdout_unterminated";
+    readonly winterClass = "ProcessError";
+    readonly crashClass: "stdout-unterminated";
+    readonly graceMs: number;
+    constructor(args: {
+        graceMs: number;
+        branchLabel: string;
+    });
+}
+/**
+ * §13.6 — the TURN failed, and the process is fine.
+ *
+ * The class §9 exists to keep separate from the five above it. `subtype` is the result message's own
+ * subtype, which is what a consumer branches on ("consumers branch on error class AND result
+ * subtype").
+ */
+export declare class OfficialAgentResultError extends OfficialBranchError {
+    readonly code = "official_agent_result_failure";
+    readonly winterClass = "ResultError";
+    readonly subtype: string;
+    constructor(args: {
+        subtype: string;
+        detail?: string;
+        branchLabel: string;
+    });
+}
+/** §13.7 — the provider request failed. Never the same class as a crashed child. */
+export declare class OfficialApiError extends OfficialBranchError {
+    readonly code = "official_api_failure";
+    readonly winterClass = "ResultError";
+    readonly status?: number;
+    constructor(args: {
+        reason: string;
+        status?: number;
+        branchLabel: string;
+    });
+}
+/** §13.8 — one tool call failed; the turn continues. */
+export declare class OfficialToolError extends OfficialBranchError {
+    readonly code = "official_tool_failure";
+    readonly winterClass = "WinterSDKError";
+    readonly tool: string;
+    constructor(args: {
+        tool: string;
+        reason: string;
+        branchLabel: string;
+    });
+}
+/** §13.9 — a permission decision denied the call. A normal outcome, and still its own class. */
+export declare class OfficialPermissionDeniedError extends OfficialBranchError {
+    readonly code = "official_permission_denied";
+    readonly winterClass = "WinterSDKError";
+    readonly tool: string;
+    constructor(args: {
+        tool: string;
+        reason: string;
+        branchLabel: string;
+    });
+}
+/** §13.10 — an MCP server failed to start, connect, or answer. */
+export declare class OfficialMcpError extends OfficialBranchError {
+    readonly code = "official_mcp_failure";
+    readonly winterClass = "WinterSDKError";
+    readonly server: string;
+    constructor(args: {
+        server: string;
+        reason: string;
+        branchLabel: string;
+    });
+}
+/**
+ * §13.11 / §5 — `mirror_error`: the canonical store did not receive everything.
+ *
+ * NON-FATAL TO THE TURN, and the class says so in a field rather than in prose: "MUST NOT
+ * retroactively fail the model turn". What it DOES do is set `transcriptHealth: repair-required` and
+ * block handoff until reconciliation — `recordedLocalWriteRoot` is the root that reconciliation runs
+ * against (§1), which is why it travels with the error.
+ */
+export declare class OfficialSessionStoreError extends OfficialBranchError {
+    readonly code = "official_session_store_failure";
+    readonly winterClass = "WinterSDKError";
+    readonly fatalToTurn = false;
+    readonly transcriptHealth: "repair-required";
+    readonly recordedLocalWriteRoot?: string;
+    constructor(args: {
+        reason: string;
+        recordedLocalWriteRoot?: string;
+        branchLabel: string;
+    });
+}
+/** §13.12 — the backend session id is not resolvable (WS-05 §7's rules decide "not found"). */
+export declare class OfficialSessionNotFoundError extends OfficialBranchError {
+    readonly code = "official_session_not_found";
+    readonly winterClass = "SessionNotFoundError";
+    readonly reason: "not_found" | "ambiguous";
+    constructor(args: {
+        sessionId: string;
+        reason: "not_found" | "ambiguous";
+        branchLabel: string;
+    });
+}
+/** §13.13 — a resume or fork request this branch refuses to make (§5.1's fork rules). */
+export declare class OfficialInvalidResumeError extends OfficialBranchError {
+    readonly code = "official_invalid_resume";
+    readonly winterClass = "WinterSDKError";
+    constructor(args: {
+        reason: string;
+        branchLabel: string;
+    });
+}
+/** §13.14 / §9 — an interrupt or a cancellation. `AbortError` is its Winter counterpart. */
+export declare class OfficialInterruptedError extends OfficialBranchError {
+    readonly code = "official_interrupted";
+    readonly winterClass = "AbortError";
+    /** WS-14 §9's four gestures — which one produced this. */
+    readonly gesture: "interrupt-turn" | "stop-task" | "end-session" | "kill-process";
+    constructor(args: {
+        gesture: OfficialInterruptedError["gesture"];
+        branchLabel: string;
+    });
+}
+/** Narrows anything to this branch's taxonomy — the one `instanceof` a projector needs. */
+export declare function isOfficialBranchError(value: unknown): value is OfficialBranchError;

package/dist/official/index.d.ts

@@ -0,0 +1,31 @@
+export { createOfficialAdapter, officialHandoffEligibility } from "./adapter.js";
+export type { HandoffEligibility, OfficialAdapterHandle, OfficialAdapterPolicy, OfficialSessionHandle, OfficialSessionHealth } from "./adapter.js";
+export { ALIASED_BUILTINS, CANONICAL_DUPLICATE_EXPOSURE, aliasDenyNames, aliasTargetFor, officialToolAliases } from "./aliases.js";
+export type { AliasedBuiltin } from "./aliases.js";
+export { NON_CREDENTIAL_ENV_REGISTRY, PINNED_ENV_REGISTRY_SIZE } from "./env-registry.js";
+export { CREDENTIAL_NAME_KEYWORDS, extractEnvRegistry, isCredentialByName } from "./env-registry-rule.js";
+export { ALL_AUTH_VARIABLES, AUTH_FAMILY_VARIABLES, AUTH_SHAPED_RE, NEVER_INJECTED_AUTH_VARIABLES, allowedAuthVariables, authVariableSetKey, fetchAuthCredentials, isAuthShapedVariable, validateAuthEnvironment } from "./auth.js";
+export type { AuthCredentialPlan, AuthFamily, AuthVariableSetKey, ClaudeOauthGate } from "./auth.js";
+export { OFFICIAL_DISCLOSURES, officialBranchLabel } from "./branding.js";
+export type { OfficialDisclosure } from "./branding.js";
+export { APPROVAL_BRIDGE_MARK, CONTAINMENT_FLOOR_MARK, carriesMark, createApprovalBridge, createContainmentHooks, createFirstResponseWins, isOurApprovalBridge, isOurContainmentHook, revalidateResumedDecision } from "./callbacks.js";
+export type { ApprovalBroker, ApprovalRequest, ApprovalBridgeOptions, ContainmentHooksOptions, DecisionContext, DecisionSource, OfficialApprovalBridge, OfficialHookOutput, OfficialPermissionMode, PreToolUseHookInput, ResumedDecision, } from "./callbacks.js";
+export { FORBIDDEN_TARGETS, VENDOR_HOME_SEGMENT_RE, containmentDecisionFor, containmentDispositions, containmentPaths, officialDisallowedTools, resolveSavedApprovalDisposition, targetsForbiddenPath } from "./containment.js";
+export type { ContainmentDecision, ContainmentDisposition, ContainmentPaths, ContainmentPolicy, SavedApprovalDisposition } from "./containment.js";
+export { MINIMAL_OS_VARIABLES, sanitizePathListValue, MINIMAL_OS_VARIABLE_PREFIXES, OFFICIAL_RUNTIME_VARIABLES, PINNED_OFFICIAL_RUNTIME, PROXY_AND_TELEMETRY_PREFIXES, PROXY_AND_TELEMETRY_VARIABLES, TRAFFIC_OPT_OUT_VARIABLES, TRAFFIC_OPT_OUT_VARIABLE_NAMES, assertNoForbiddenChildVariables, buildOfficialChildEnv, minimalOsEnvironmentFrom, officialEnvAllowlistNames, officialEnvAllowlistSnapshot, } from "./env-allowlist.js";
+export { EXECUTION_INDIRECTION_ENV_NAMES, EXECUTION_INDIRECTION_ENV_PREFIXES, isExecutionIndirectionVariable } from "./env-allowlist.js";
+export type { EnvAllowlistSnapshot, OfficialEnvInput, OfficialEnvPolicy } from "./env-allowlist.js";
+export { OFFICIAL_ERROR_CODES, OfficialStdoutUnterminatedError, OfficialAgentResultError, OfficialApiError, OfficialBranchError, OfficialConfigurationError, OfficialConnectionError, OfficialExecutableNotFoundError, OfficialInterruptedError, OfficialInvalidResumeError, OfficialKilledError, OfficialMcpError, OfficialNonzeroExitError, OfficialPermissionDeniedError, OfficialProtocolError, OfficialSessionNotFoundError, OfficialSessionStoreError, OfficialToolError, isOfficialBranchError, } from "./errors.js";
+export type { OfficialCrashClass, OfficialErrorCode, WinterErrorClassName } from "./errors.js";
+export { OFFICIAL_MATERIALIZATION_DROPS, assertNoAdvisor, canonicalToolNames, materializeOfficialMcpServer, messagingToolDescriptors, officialMcpServers, winterMcpServerDescriptor } from "./mcp-descriptors.js";
+export type { InputShapeFactory, JsonSchemaObject, MessagingHandlers, OfficialMcpModule, WinterMcpHandler, WinterMcpServerDescriptor, WinterMcpToolDescriptor, WinterMcpToolResult } from "./mcp-descriptors.js";
+export { AUTO_MEMORY_LOAD_CAP, DEFAULT_EXCLUDE_DYNAMIC_SECTIONS, PINNED_SYSTEM_PROMPT_PRESET, assertOptionsInvariants, brandedFlagSettings, buildOfficialOptions, captureOptions, mergeHooks } from "./options-template.js";
+export type { OptionsTemplatePolicy } from "./options-template.js";
+export { SPOOL_SEGMENTS, classifyLocalWriteRoot, officialSpoolRoot, validateObservedConfigDir, vendorTempRootReport } from "./spool.js";
+export type { LocalWriteRootKind, ObservedLocalWriteRoot, VendorTempRootReport } from "./spool.js";
+export { createSupervisedSpawnProxy, directoryRecordSink, prepareDefaultSpawn } from "./spawn-proxy.js";
+export type { ProcessIdentity, SpawnChild, SpawnObservation, SpawnRecordSink, SpawnedChildProcess, SupervisedSpawnProxy, SupervisedSpawnProxyOptions, TranscriptReconcile } from "./spawn-proxy.js";
+export { POST_TOOL_EVENTS, SWEPT_TARGETS, SWEPT_TOOLS, createContainmentSweep, forbiddenArtifactsUnder } from "./sweep.js";
+export type { ContainmentBreach, ContainmentSweep, ContainmentSweepOptions } from "./sweep.js";
+export { CANCELLATION_MAPPINGS, DEFAULT_SESSION_QUOTAS, cancellationMappingFor, crashClassOf, interruptionFor, isProcessCrash, revalidateProcessIdentity } from "./supervision.js";
+export type { CancellationGesture, CancellationMapping } from "./supervision.js";