@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/official/adapter.d.ts

@@ -0,0 +1,88 @@
+import type { SeamContextWithDirectory } from "../seams/context.js";
+import type { OfficialAdapter, OfficialLaunchPlan, OfficialResumePlan, OfficialSession, OptionsTemplateInput } from "../seams/official-adapter.js";
+import { type OfficialPermissionMode } from "./callbacks.js";
+import { type ContainmentPolicy } from "./containment.js";
+import { type ContainmentBreach } from "./sweep.js";
+import { type OfficialEnvInput, type OfficialEnvPolicy } from "./env-allowlist.js";
+import { type OptionsTemplatePolicy } from "./options-template.js";
+import type { OfficialContainmentBreachError } from "./errors.js";
+import { type SpawnChild, type SpawnObservation, type SpawnRecordSink, type SupervisedSpawnProxy, type TranscriptReconcile } from "./spawn-proxy.js";
+import type { OfficialBranchError } from "./errors.js";
+/** Everything the adapter needs that is neither a seam nor a per-launch value. */
+export interface OfficialAdapterPolicy {
+    /** Per-launch template policy: an object, or a function of the template input. */
+    options?: OptionsTemplatePolicy | ((input: OptionsTemplateInput) => OptionsTemplatePolicy);
+    env?: OfficialEnvPolicy;
+    /** Where §6 rule 2's record goes. Default: nowhere durable, and `launch` says so if it matters. */
+    sink?: SpawnRecordSink;
+    /** §6 rule 3's collaborator (the store lane's). Default: a no-op that still runs at the right moment. */
+    reconcile?: TranscriptReconcile;
+    /** §6 rule 5. Default: `undefined` → cleanup is treated as verified (an in-memory sink has nothing to verify). */
+    verifyCleanup?: (observation: SpawnObservation) => Promise<boolean> | boolean;
+    /** Injected for tests; production uses Node's own spawn with the brand's process label as argv0. */
+    spawnChild?: SpawnChild;
+    onCrash?: (error: OfficialBranchError) => void;
+    /** §8's post-hoc sweep found a vendor-named path a call created (review r2, NEW-3). */
+    onContainmentBreach?: (breach: ContainmentBreach, error: OfficialContainmentBreachError) => void;
+    /** §8's dispositions, threaded into the floor this adapter installs on every launch. */
+    containment?: ContainmentPolicy;
+    /** The session's permission mode, for the bridge the adapter installs when the caller supplied none. */
+    permissionMode?: OfficialPermissionMode;
+    now?: () => Date;
+}
+/** A live official generation, plus the two handles the seam's shape cannot carry. */
+export interface OfficialSessionHandle extends OfficialSession {
+    /** Resolves with the OBSERVED root once the child has spawned (§1's authoritative value). */
+    whenObserved(): Promise<string>;
+    /** WS-14 §9: stops the foreground turn, preserving background agents (`perTaskStopAffordance`). */
+    interrupt(): Promise<unknown>;
+    /** The generation's proxy — its stderr tail, its record, its exit gate. */
+    readonly supervisor: SupervisedSpawnProxy;
+    /** §8's post-hoc sweep findings for this session (review r2, NEW-3). Empty is the normal case. */
+    readonly containmentBreaches: readonly ContainmentBreach[];
+}
+export interface OfficialAdapterHandle extends OfficialAdapter {
+    launch(plan: OfficialLaunchPlan): OfficialSessionHandle;
+    resume(plan: OfficialResumePlan): OfficialSessionHandle;
+    /**
+     * The seam's `buildChildEnv`, widened to the input the env builder actually accepts.
+     *
+     * `OfficialEnvInput` extends the spine's `EnvInput` with §3's two per-session vendor variables
+     * (the transcript project key and the shared temp root), which the seam does not name. Method
+     * parameters are bivariant, so this stays assignable to the seam while letting a caller that HAS
+     * those values pass them without a cast.
+     */
+    buildChildEnv(input: OfficialEnvInput): Record<string, string>;
+    /** Prepares the default child starter. Idempotent; a test injecting `spawnChild` never needs it. */
+    ready(): Promise<void>;
+}
+/** §5's health facts a handoff decision is made from. */
+export interface OfficialSessionHealth {
+    /** WS-14 §6: "any session advertising cross-runtime handoff MUST launch through this proxy from its FIRST generation". */
+    launchedThroughProxy: boolean;
+    /** §1's recorded active local-write root, as observed. Absent for a default-spawn session. */
+    recordedLocalWriteRoot?: string;
+    /** §5: `mirror_error` sets `repair-required` and blocks handoff until the store is reconciled. */
+    transcriptHealth: "ok" | "repair-required";
+}
+export type HandoffEligibility = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: "default-spawn-mirror-error" | "repair-required" | "no-recorded-root";
+    detail: string;
+};
+/**
+ * §5's handoff refusals, as one decision (WS-17 row 15's "default-spawn `mirror_error` handoff
+ * refusal").
+ *
+ * THE DEFAULT-SPAWN CASE IS THE INTERESTING ONE and it is a REFUSAL, not a fallback: "a resumed
+ * default-spawn session with `mirror_error` keeps the official owner or stays `repair-required`;
+ * SCANNING TEMP DIRECTORIES BY RECENCY IS FORBIDDEN". A session that did not launch through the proxy
+ * has no recorded root, and the only other way to find its `claude-resume-*` staging directory is to
+ * guess by mtime — which is how a reconciler ends up merging a DIFFERENT session's transcript into
+ * this one. There is no safe answer, so the answer is no.
+ */
+export declare function officialHandoffEligibility(health: OfficialSessionHealth): HandoffEligibility;
+/** Builds the adapter. `context` is the spine's one seam context — see `src/seams/context.ts`. */
+export declare function createOfficialAdapter(context: SeamContextWithDirectory, policy?: OfficialAdapterPolicy): OfficialAdapterHandle;

package/dist/official/aliases.d.ts

@@ -0,0 +1,48 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/** The two built-ins WS-14 §7 redirects, and the canonical tool each resolves to. */
+export declare const ALIASED_BUILTINS: readonly [{
+    readonly builtin: "SendMessage";
+    readonly tool: "send_message";
+}, {
+    readonly builtin: "ListAgents";
+    readonly tool: "list_agents";
+}];
+export type AliasedBuiltin = (typeof ALIASED_BUILTINS)[number]["builtin"];
+/** §2's `toolAliases` value: `{ SendMessage: "mcp__<server>__send_message", … }`. */
+export declare function officialToolAliases(brand: Pick<BrandProfile, "mcpServerName">): Record<string, string>;
+/** The canonical name one aliased built-in resolves to (single hop — never a chain). */
+export declare function aliasTargetFor(builtin: AliasedBuiltin, brand: Pick<BrandProfile, "mcpServerName">): string;
+export { LIST_AGENTS_FIELD_MAX, NATIVE_LIST_AGENTS_OUTPUT_SCHEMA, NATIVE_LIST_AGENTS_SCHEMA, NATIVE_SEND_MESSAGE_SCHEMA, SEND_MESSAGE_SUMMARY_MAX, SEND_MESSAGE_TO_MAX, acceptNativeListAgentsArgs, acceptNativeSendMessageArgs, } from "../native-args.js";
+export type { NativeArgsResult, NativeListAgentsArgs, NativeSendMessageArgs } from "../native-args.js";
+/**
+ * How the canonical duplicates are exposed (§7's "SHOULD be deferred/hidden").
+ *
+ * `deferred` and not `hidden`: a hidden tool is unreachable by name, and the canonical name is
+ * exactly what a HOST-INTERNAL caller (and the router's own cross-runtime path) addresses. Deferring
+ * keeps it addressable while keeping it out of the default advertised set — which is the behaviour
+ * the Winter branch's own canonical twin already declares at its source.
+ *
+ * ON THE OFFICIAL BRANCH THIS IS AN INTENT, NOT AN ENFORCEMENT, and the distinction is recorded
+ * rather than papered over: the pinned runtime decides MCP-tool visibility itself, and the capture
+ * above shows both duplicates advertised in a session with no Tool Search active. WS-17 row 2 asks
+ * for exactly that measurement ("canonical MCP duplicate deferred/hidden visibility; behaviour
+ * without Tool Search"), and `test/official/runtime-aliases.test.ts` records what 0.3.250 does rather
+ * than asserting what we wish it did.
+ */
+export declare const CANONICAL_DUPLICATE_EXPOSURE: "deferred";
+/**
+ * BOTH NAMES A DENY RULE MUST CARRY — and this is a MEASUREMENT, not a belt-and-braces habit.
+ *
+ * Driven against the pinned 0.3.250 runtime (`test/official/runtime-aliases.test.ts`, row 3):
+ *
+ *   `disallowedTools: ["SendMessage"]`                       → the model emits `SendMessage`, the
+ *                                                              alias resolves, AND THE HANDLER RUNS.
+ *   `disallowedTools: [<the canonical target>]`              → the call is blocked.
+ *
+ * So the deny check happens AFTER alias resolution, against the resolved name. A host that denied
+ * only the built-in — the obvious reading of "deny `SendMessage`" — would have a deny rule that does
+ * nothing at all, silently, on this branch only. §7's "aliases are NOT a security boundary" is
+ * exactly this fact, and this function is how a caller stops tripping over it: one built-in in, both
+ * names out.
+ */
+export declare function aliasDenyNames(builtin: AliasedBuiltin, brand: Pick<BrandProfile, "mcpServerName">): readonly string[];

package/dist/official/auth.d.ts

@@ -0,0 +1,117 @@
+import type { CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+import type { KeychainSeam } from "../seams/keychain.js";
+import type { RuntimeSelection } from "../selection/runtime-selection.js";
+/** `RuntimeSelection.authFamily` — restated as a local alias so the tables below read as tables. */
+export type AuthFamily = RuntimeSelection["authFamily"];
+/**
+ * The credential-shaped variables ONE auth family may set, per §12's table.
+ *
+ * `cloud-credential-chain` is deliberately split by provider: Bedrock and Vertex are two different
+ * variable sets and a session is on one of them, never both. The split key is `providerId`, which is
+ * the persisted selection's own field — never an ambient scan of the environment (WS-14's Phase 6
+ * amendment: "a pinned alias resolves to the `anthropic` provider ONLY when a credential ref for it
+ * is configured, and never by ambient environment scan").
+ */
+export declare const AUTH_FAMILY_VARIABLES: {
+    readonly "api-key": readonly ["ANTHROPIC_API_KEY"];
+    /**
+     * A bearer credential (Console OAuth, or an approved gateway).
+     *
+     * THE FULL PAIR, ALWAYS — §12's gateway caveat: "an explicit gateway credential replaces
+     * subscription login, but `ANTHROPIC_BASE_URL` alone can leave a stored OAuth credential active;
+     * gateway configs MUST set the full credential pair." So the endpoint is part of this family's set
+     * rather than a separate knob, and the validator below refuses a base URL with no token.
+     */
+    readonly "console-oauth": readonly ["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL"];
+    readonly bedrock: readonly ["CLAUDE_CODE_USE_BEDROCK", "AWS_REGION", "AWS_PROFILE", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_BEARER_TOKEN_BEDROCK", "ANTHROPIC_BEDROCK_BASE_URL"];
+    readonly vertex: readonly ["CLAUDE_CODE_USE_VERTEX", "ANTHROPIC_VERTEX_PROJECT_ID", "CLOUD_ML_REGION", "GOOGLE_APPLICATION_CREDENTIALS", "ANTHROPIC_VERTEX_BASE_URL"];
+    /**
+     * §12's last row: NONE. "Claude OAuth (D14-gated) — stored subscription credentials live inside the
+     * spool namespace; no env credential injected." The empty set is the rule, not an oversight.
+     */
+    readonly "claude-oauth": readonly [];
+    /** A runtime with no credential at all (a local endpoint). Nothing to inject. */
+    readonly "local-none": readonly [];
+};
+export type AuthVariableSetKey = keyof typeof AUTH_FAMILY_VARIABLES;
+/**
+ * WHAT "CREDENTIAL-BEARING" MEANS, as a SHAPE rather than as a list (review r2, NEW-2).
+ *
+ * The family tables above are sixteen names. The pinned runtime reads thirty-odd, and eight of the
+ * ones it reads were measured travelling through `configuredExtras` into an `api-key` session —
+ * including a complete second provider family (`CLAUDE_CODE_USE_FOUNDRY` + `ANTHROPIC_FOUNDRY_API_KEY`),
+ * an `Authorization: Bearer` header injected wholesale through `ANTHROPIC_CUSTOM_HEADERS`, and
+ * `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`, which walks around D14's "the Claude OAuth family injects NO
+ * credential variable" because `NEVER_INJECTED_AUTH_VARIABLES` names exactly one variable.
+ *
+ * A list can only ever refuse what someone already thought of; the runtime's own precedence order is
+ * what makes that fatal (cloud-provider credentials resolve ABOVE the token and the key, so one
+ * variable re-points billing, rate-limits and audit at an account the persisted selection does not
+ * name). So the universe is a SHAPE: every vendor/cloud auth prefix the artifact uses, plus the
+ * generic credential suffixes. Anything matching it is refused from the extras door unless it is a
+ * variable this session's own family sets.
+ */
+export declare const AUTH_SHAPED_RE: RegExp;
+/** True when a name is credential-bearing by shape, whatever table it is or is not in. */
+export declare function isAuthShapedVariable(name: string): boolean;
+/** Every credential-shaped name any family may set — the env allowlist's auth section. */
+export declare const ALL_AUTH_VARIABLES: readonly string[];
+/**
+ * NEVER INJECTED, on any branch, in any family (§3, §5.1, §12; WS-01 §2.5).
+ *
+ * The subscription OAuth token is the one credential the runtime can pick up from the environment
+ * that Winter must never place there: D14 gates the OAuth branch entirely, and the supported flow
+ * puts its stored credentials INSIDE THE SPOOL rather than in a variable.
+ */
+export declare const NEVER_INJECTED_AUTH_VARIABLES: readonly string[];
+/** Which variable set a selection's family uses, `providerId` deciding the cloud split. */
+export declare function authVariableSetKey(selection: Pick<RuntimeSelection, "authFamily" | "providerId">): AuthVariableSetKey | "custom";
+/**
+ * The names this session's family is allowed to set.
+ *
+ * `custom` returns `undefined` rather than a set: a host that declares a custom auth family is saying
+ * "I name these variables myself", and the env builder validates them against the FORBIDDEN list
+ * instead of an allowlist. That is a deliberate hole with a fence around it — §3's "anything else is
+ * a deliberate, documented addition" — and it is the only family for which the set is open.
+ */
+export declare function allowedAuthVariables(selection: Pick<RuntimeSelection, "authFamily" | "providerId">): readonly string[] | undefined;
+/** D14's ship gate: the OAuth branch is built but publicly gated pending written approval. */
+export interface ClaudeOauthGate {
+    /** Default FALSE everywhere. "Until approval exists, the shippable branch uses API-key/cloud/gateway auth only." */
+    approved: boolean;
+}
+/**
+ * Validates the credential material a caller assembled for this session, before it reaches a child.
+ *
+ * Four refusals, each naming a real way the "exactly one family" rule breaks:
+ *   1. a variable outside the family's set (two families at once, decided silently by precedence);
+ *   2. `CLAUDE_CODE_OAUTH_TOKEN`, ever;
+ *   3. a bearer family with a base URL and no token (the §12 gateway caveat's exact failure: the
+ *      endpoint moves and a STORED subscription credential stays active behind it);
+ *   4. `claude-oauth` while the D14 gate is closed, or with any variable at all (that family injects
+ *      none by definition).
+ */
+export declare function validateAuthEnvironment(args: {
+    selection: Pick<RuntimeSelection, "authFamily" | "providerId">;
+    credentials: Readonly<Record<string, string>>;
+    gate: ClaudeOauthGate;
+    branchLabel: string;
+}): void;
+/** One variable's credential source: the name to set, and the ref whose material fills it. */
+export interface AuthCredentialPlan {
+    variable: string;
+    ref: CredentialRef;
+}
+/**
+ * Fetches this session's credential material AT SPAWN (§12) and returns it for immediate injection.
+ *
+ * THE ONLY KEYCHAIN READ IN THIS PACKAGE, and it returns rather than stores. A missing ref is a
+ * TYPED refusal and not a silent omission: a child launched with an empty auth family falls through
+ * the runtime's precedence table to whatever the spool happens to hold, which is the accident §12
+ * exists to prevent.
+ */
+export declare function fetchAuthCredentials(args: {
+    plan: readonly AuthCredentialPlan[];
+    keychain: KeychainSeam;
+    branchLabel: string;
+}): Promise<Record<string, string>>;

package/dist/official/branding.d.ts

@@ -0,0 +1,31 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * The internal diagnostics label for this branch (WS-14 §14, WS-01 §5).
+ *
+ * `<processLabel>-claude-agent` — the Winter-owned half comes from the profile, the Claude-mirroring
+ * half is fixed (WS-01 §5/D16: vendor literals are never rebranded, because renaming them would be a
+ * lie about which runtime is executing).
+ */
+export declare function officialBranchLabel(brand: Pick<BrandProfile, "processLabel">): string;
+/** One disclosed vendor-named artifact: what it is, where it shows up, and why it cannot be renamed. */
+export interface OfficialDisclosure {
+    /** A stable id so a capability matrix can key rows off it rather than off prose. */
+    id: "signed-binary-identity" | "spool-config-file" | "nested-engine-temp" | "resume-staging" | "vendor-telemetry-defaults" | "extraction-cache";
+    /** The vendor literal a user or an operator will actually see. */
+    literal: string;
+    /** Where it appears. */
+    where: string;
+    /** Why Winter does not and must not rename it. */
+    why: string;
+}
+/**
+ * WS-14 §14's disclosure set, as data.
+ *
+ * Every entry is a place the official branch is visibly Anthropic's, and the honest caveat D12
+ * attaches to the process label ("the Mach-O stays signed `com.anthropic.claude-code`; some process
+ * viewers, crash reports and code-signing displays reveal the real identity") is the first row. The
+ * last row is the one that is disclosed as AVOIDED rather than present, because WS-02 ships the
+ * native package as a normal resource and a disclosure that quietly dropped it would read, later, as
+ * a claim that the cache never existed.
+ */
+export declare const OFFICIAL_DISCLOSURES: readonly OfficialDisclosure[];

package/dist/official/callbacks.d.ts

@@ -0,0 +1,143 @@
+import type { BrandProfile, PermissionResult, PermissionUpdate } from "@yanlinglabs/winter-agent-sdk";
+import { type ContainmentPolicy } from "./containment.js";
+/** The permission modes a host session can be in. Mirrors the pinned runtime's own vocabulary. */
+export type OfficialPermissionMode = "default" | "plan" | "acceptEdits" | "bypassPermissions" | "dontAsk";
+/** Everything the pinned `CanUseTool` hands a callback, carried through to the broker unchanged. */
+export interface ApprovalRequest {
+    toolName: string;
+    input: Record<string, unknown>;
+    signal: AbortSignal;
+    requestId: string;
+    toolUseID: string;
+    agentID?: string;
+    suggestions?: PermissionUpdate[];
+    blockedPath?: string;
+    decisionReason?: string;
+    title?: string;
+    displayName?: string;
+    description?: string;
+    matchedAskRule?: {
+        source: string;
+        toolName: string;
+        ruleContent?: string;
+    };
+}
+/** The host's broker (WS-15 §7 / Phase 8). It answers with a typed result — never `null`, ever. */
+export type ApprovalBroker = (request: ApprovalRequest) => Promise<PermissionResult>;
+/** The bridge itself: assignable to either SDK's `canUseTool`, and strictly narrower than both. */
+export type OfficialApprovalBridge = (toolName: string, input: Record<string, unknown>, options: Omit<ApprovalRequest, "toolName" | "input">) => Promise<PermissionResult>;
+export interface ApprovalBridgeOptions {
+    broker: ApprovalBroker;
+    brand: Pick<BrandProfile, "projectDirName" | "processLabel">;
+    /** The session's mode. `dontAsk` never reaches the broker (§10). */
+    mode: OfficialPermissionMode;
+    /** §8's dispositions. The floor reads them; `projectDirName` is filled from `brand` if absent. */
+    containment?: ContainmentPolicy;
+    /** Called with every decision, so a host can log or count without wrapping the broker. */
+    onDecision?: (decision: {
+        request: ApprovalRequest;
+        result: PermissionResult;
+        source: DecisionSource;
+    }) => void;
+}
+/** Where a decision came from — what a row-14 tally is built out of. */
+export type DecisionSource = "containment-floor" | "broker" | "dont-ask" | "broker-approval-stripped";
+/**
+ * Builds `Options.canUseTool` for the official branch.
+ *
+ * ORDER: containment floor → mode → broker. Every arm returns a typed result, and the function's own
+ * return type is what guarantees it.
+ */
+export declare function createApprovalBridge(options: ApprovalBridgeOptions): OfficialApprovalBridge;
+/**
+ * THE MARKS THAT MAKE THE FLOOR VISIBLE (review r2, NEW-1) — visible, and no longer PROOF.
+ *
+ * `assertOptionsInvariants` has to be able to answer "does this options object carry the floor?" for
+ * an object it did not build — that is the whole point of a function whose doc says it validates what
+ * `launch()` is HANDED. A structural guess ("some PreToolUse matcher exists") would pass for any hook
+ * at all, so the floor's own callback and the approval bridge each carry a symbol — `Symbol.for`, so a
+ * host reading an options object can recognise the two by name whichever copy of this package stamped
+ * them.
+ *
+ * WHAT A MARK IS NOW (review r3 NEW-11, review r4 NEW-18): a LABEL. It is an exported `Symbol.for` key,
+ * so any caller can stamp it, and both marks have been measured being stamped to some effect. The
+ * answer to "is this the floor / the bridge" is the identity check further down, never the mark.
+ */
+export declare const CONTAINMENT_FLOOR_MARK: unique symbol;
+export declare const APPROVAL_BRIDGE_MARK: unique symbol;
+/** True when this function carries the mark — a label a host can read, NOT proof that this package made it. */
+export declare function carriesMark(value: unknown, mark: symbol): boolean;
+export declare function isOurApprovalBridge(value: unknown): value is OfficialApprovalBridge;
+/** True only for a hook `createContainmentHooks` built. A hook merely stamped with the mark is NOT the floor. */
+export declare function isOurContainmentHook(value: unknown): boolean;
+/** The subset of the hook contract this needs, declared structurally (the peer is never imported). */
+export interface PreToolUseHookInput {
+    hook_event_name?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+}
+export type OfficialHookOutput = {
+    hookSpecificOutput?: {
+        hookEventName: "PreToolUse";
+        permissionDecision?: "allow" | "deny" | "ask" | "defer";
+        permissionDecisionReason?: string;
+    };
+    decision?: "block";
+    stopReason?: string;
+};
+export interface ContainmentHooksOptions {
+    brand: Pick<BrandProfile, "projectDirName">;
+    containment?: ContainmentPolicy;
+    onDecision?: (decision: {
+        tool: string;
+        target: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * The `hooks` value §8's containment needs: one `PreToolUse` matcher applying the same floor.
+ *
+ * A DENY HERE IS THE STRONGEST ONE THE RUNTIME OFFERS: `permissionDecision: "deny"` stops the call
+ * before it runs and returns the reason to the model, and unlike the callback it is invoked for every
+ * tool — including the ones that skip `canUseTool` entirely.
+ */
+export declare function createContainmentHooks(options: ContainmentHooksOptions): Record<string, Array<{
+    hooks: Array<(input: unknown) => Promise<OfficialHookOutput>>;
+}>>;
+/** A decision that was made before a restart, replayed against the session it was made for. */
+export interface ResumedDecision {
+    requestId: string;
+    toolUseID: string;
+    sessionId: string;
+    /** The mode/policy version the decision was made under. */
+    policyVersion: string;
+    /** Paths the decision covered, already normalized by the host. */
+    normalizedPaths: readonly string[];
+    /** Which runtime owned the session when the decision was made (WS-05 §12's writer lease). */
+    runtimeOwner: string;
+}
+/** The live facts a resumed decision is revalidated against. */
+export type DecisionContext = Omit<ResumedDecision, "requestId">;
+/**
+ * §10's revalidation, as a predicate.
+ *
+ * "A decision resumed after restart revalidates SESSION, TOOL CALL, MODE/POLICY VERSION, NORMALIZED
+ * PATHS, and RUNTIME OWNERSHIP before executing." All five, and the list is why this is a function
+ * rather than an `===`: four-out-of-five is an approval for a call the user never saw.
+ */
+export declare function revalidateResumedDecision(decision: ResumedDecision, live: DecisionContext): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * "FIRST RESPONSE WINS" — a one-shot latch per `requestId`.
+ *
+ * A broker that answers twice (a user click plus a restored decision, say) must not produce two
+ * control responses: the second is dropped, and the latch says so rather than silently discarding.
+ */
+export declare function createFirstResponseWins(): {
+    claim(requestId: string): boolean;
+    claimed(): readonly string[];
+};

package/dist/official/containment.d.ts

@@ -0,0 +1,130 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type AliasedBuiltin } from "./aliases.js";
+/** The three vendor-named targets nothing may create (WS-17 row 14). */
+export declare const FORBIDDEN_TARGETS: {
+    readonly instructionsFile: "CLAUDE.md";
+    readonly projectDir: ".claude";
+    readonly userPlansDir: ".claude/plans";
+};
+/** Where each native writer is redirected — the product's own project directory (§8's table). */
+export interface ContainmentPaths {
+    worktrees: string;
+    workflows: string;
+    plans: string;
+    localSettings: string;
+}
+export declare function containmentPaths(brand: Pick<BrandProfile, "projectDirName">): ContainmentPaths;
+/** One row of §8's disposition table, as data a capability matrix can render. */
+export interface ContainmentDisposition {
+    writer: string;
+    claudeNamedTarget: string;
+    /** What §8 SAYS should happen to this writer. */
+    disposition: "redirect" | "disable" | "owned-by-product" | "deny";
+    target?: string;
+    /**
+     * What THIS PACKAGE actually does about it (review r1, M2).
+     *
+     * The distinction is the finding: a row can say `redirect` while the router — which implements no
+     * tools — has nothing to redirect to, and a reader of the table alone would believe the writer was
+     * handled. `floor-deny` means the permission floor refuses the call; `deny-list` means the name is
+     * in `disallowedTools`; `approval-stripped` means the durable permission update is dropped at the
+     * bridge; `host-implementation` means the host installed the replacement and owns it from there.
+     */
+    enforcement: "floor-deny" | "deny-list" | "approval-stripped" | "host-implementation" | "host-ui";
+    note: string;
+}
+/**
+ * §16 open question 2, FIXED HERE WITH ITS REASON RECORDED.
+ *
+ * "Saved `WebFetch` approvals: redirect versus disable is left open until WS-07 decides whether
+ * durable approvals on this branch share the product's rules store or the project settings file;
+ * either way the `.claude/` write is denied."
+ *
+ * `disable` IS THE ONLY VALUE THIS BRANCH CAN HONOUR, and that is a measurement rather than a
+ * preference (review r3, NEW-11). `redirect` was documented as "durable approvals are routed into the
+ * product's own project settings file" — and nothing routed them: the branch has no way to make the
+ * runtime write elsewhere, so passing the durable update through means the RUNTIME writes
+ * `<cwd>/.claude/settings.local.json`. Measured, with an ordinary host broker and no forgery: that
+ * file was created and the product's own never was. §8's own sentence is "either way the `.claude/`
+ * write is denied", so the value that cannot deny it is refused with a typed error until a host
+ * replacement exists — `disable` still keeps the approval for the session's lifetime and leaves
+ * WS-07's open question open.
+ */
+export type SavedApprovalDisposition = "disable" | "redirect";
+export interface ContainmentPolicy {
+    savedWebFetchApprovals?: SavedApprovalDisposition;
+    /**
+     * The two §8 rows whose disposition is REDIRECT, and the honest fact about who can perform one.
+     *
+     * REVIEW r1, M2 — MEASURED. `EnterWorktree`, `Agent`/`Task` with `isolation: "worktree"` and named
+     * `Workflow` resolution were all reaching the floor and being ALLOWED: the router implements no
+     * tools, so it has nothing to redirect them TO, and the disposition table said "redirect" while the
+     * code did nothing. In a non-git working directory they then failed for an unrelated reason and the
+     * proof read as containment.
+     *
+     * So the router's own enforcement is a DENY until the host installs the schema-compatible
+     * replacement §8 describes — `"host-replacement"` is the host saying it has, and only then does the
+     * vendor's own writer become the host's problem rather than a vendor-named write.
+     */
+    worktrees?: "deny" | "host-replacement";
+    workflows?: "deny" | "host-replacement";
+    /** The product's project directory, so a refusal can NAME where the replacement lives. */
+    projectDirName?: string;
+    /**
+     * Aliased built-ins this deployment denies.
+     *
+     * Each expands to BOTH names, because the pinned runtime checks the deny list AFTER alias
+     * resolution — see `aliasDenyNames` for the measurement. A host that listed only the built-in would
+     * have a rule that does nothing.
+     */
+    deniedAliasedBuiltins?: readonly AliasedBuiltin[];
+}
+/**
+ * The saved-approval disposition, refusing the value the branch cannot honour (review r3, NEW-11).
+ *
+ * A typed refusal rather than a silent downgrade: a host that asked for `redirect` asked for a
+ * behaviour, and quietly giving it `disable` would leave it believing durable approvals are being
+ * persisted somewhere.
+ */
+export declare function resolveSavedApprovalDisposition(policy: ContainmentPolicy, branchLabel: string): SavedApprovalDisposition;
+export declare function containmentDispositions(brand: Pick<BrandProfile, "projectDirName" | "productName">, policy?: ContainmentPolicy): readonly ContainmentDisposition[];
+/**
+ * Tools whose NAME-based route is closed on this branch (§7's `disallowedTools`).
+ *
+ * A SHORT LIST ON PURPOSE. `disallowedTools` covers the paths aliases miss, but it is still a name
+ * mechanism: the floor below is what actually holds. What is listed here are the writers whose whole
+ * PURPOSE is a vendor-named path and which have no redirected equivalent on this branch.
+ */
+export declare function officialDisallowedTools(policy?: ContainmentPolicy, brand?: Pick<BrandProfile, "mcpServerName">): readonly string[];
+/** A decision from the containment floor. `deny` carries the sentence the model is shown. */
+export type ContainmentDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+    target: string;
+};
+/**
+ * Does this path create or write one of the three forbidden targets?
+ *
+ * SEGMENT MATCHING, never substring: `.claude` must not match `.claude-backup`, and `CLAUDE.md` must
+ * not match `MY_CLAUDE.mdx`. The user-level plans directory is matched anywhere (it is an absolute
+ * path under the vendor home, which §3 already keeps out of the environment — this is the belt).
+ * Every comparison goes through `fold` — see its own note for the measurement that made that
+ * mandatory.
+ */
+export declare function targetsForbiddenPath(rawPath: string): {
+    forbidden: boolean;
+    target: string;
+};
+/**
+ * THE ONE DEFINITION OF "the vendor's user-level home" IN THIS PACKAGE (review r2, NEW-4).
+ *
+ * It lived in three places and C1 folded only one of them, so `/Users/dev/.Claude/ca.pem` passed the
+ * env value check, a `PATH` entry under `~/.Claude/plugins/.../bin` survived the sanitizer, and
+ * `/tmp/.Claude/claude-resume-abc` was accepted as a staging root — all on the filesystem where those
+ * ARE the same directory. Case-insensitive, exported, and imported by `env-allowlist.ts` and
+ * `spool.ts` rather than re-spelled.
+ */
+export declare const VENDOR_HOME_SEGMENT_RE: RegExp;
+export declare function containmentDecisionFor(toolName: string, input: Record<string, unknown>, policy?: ContainmentPolicy): ContainmentDecision;