@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/provider/stream-frames.d.ts

@@ -0,0 +1,25 @@
+import type { ProtocolSdkMessage as SdkMessage } from "@yanlinglabs/winter-agent-sdk";
+import type { ProviderStreamSink } from "../engine.js";
+export interface StreamFrameSinkDeps {
+    sessionId: string;
+    /** The pin's own `Options.includePartialMessages`. Absent/false gates `stream_event` OFF and nothing else. */
+    includePartialMessages: boolean;
+    /** Writes one frame. Never throws to the caller -- see the wrapper below. */
+    write: (message: SdkMessage) => void;
+    /** Read LIVE, not captured: a `set_model` between generations changes what `reasoning_summary` should name. */
+    identity: () => {
+        providerId?: string;
+        modelKey?: string;
+    } | undefined;
+    /** The session's CURRENT model, for the same reason. */
+    model: () => string;
+    /** Injected for deterministic `ttft_ms` in tests. */
+    now?: () => number;
+}
+/**
+ * Builds the sink for ONE generation.
+ *
+ * Per generation, not per session, because `ttft_ms` is per generation: capture (F) observed exactly
+ * two frames carrying it across a run -- one per FORWARDED turn, on that turn's `message_start`.
+ */
+export declare function createStreamFrameSink(deps: StreamFrameSinkDeps): ProviderStreamSink;

package/dist/provider/tool-secret.d.ts

@@ -0,0 +1,57 @@
+import type { CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+import type { CredentialStore } from "@yanlinglabs/winter-provider-runtime";
+import type { KeychainSecretReader } from "./keychain-store.js";
+/**
+ * `found`       the key, trimmed.
+ * `missing`     the ref resolves to nothing (no such item, an empty value, `{ kind: "none" }`). The
+ *               ordinary "no key configured" state -- never an error.
+ * `unreadable`  something IS there (or the store failed) and it cannot be used as a key. `code` is
+ *               the store's own vocabulary; `message` names the redacted ref and the reason.
+ */
+export type ToolSecretResult = {
+    status: "found";
+    key: string;
+} | {
+    status: "missing";
+} | {
+    status: "unreadable";
+    code: "io" | "malformed" | "unsupported";
+    message: string;
+};
+/** What an executor is handed. A test fake is a one-line function returning one of the three arms. */
+export type ToolSecretResolver = (ref: CredentialRef) => Promise<ToolSecretResult>;
+export interface ToolSecretResolverDeps {
+    /** Serves every NON-keychain ref (`env`, `inline`, `file`, `none`), and keychain refs too when no raw reader is supplied. */
+    credentials: CredentialStore;
+    /**
+     * The keychain's RAW reader (`createKeychainSecretReader`). When present, a keychain ref is read
+     * through it EXACTLY ONCE and interpreted here -- never through `credentials.get` first, which
+     * would throw `malformed` on a bare key and would cost a second keychain access (each of which can
+     * raise an OS consent prompt). ABSENT for a wiring built over an injected store: a test must never
+     * reach the real keychain, so an injected store means "this is the only source".
+     */
+    readKeychainSecret?: KeychainSecretReader;
+}
+/**
+ * What one stored string means. Exported for its own tests.
+ *
+ * NOTHING FROM THE STORED VALUE EVER APPEARS IN A MESSAGE -- these messages travel into a tool
+ * RESULT, which a model reads. That includes the value of a `kind` field: it is quoted only when it
+ * is one of the kinds this SDK writes, because anything else is content of unknown provenance and
+ * may be the secret itself (an item holding `{"kind":"sk-live-..."}` must not be echoed).
+ *
+ *   JSON `{ "kind": "api-key", "key": "<non-empty>" }`  -> the key
+ *   a JSON string                                       -> that string, held to the bare-key rule
+ *   JSON `null`                                         -> missing (a serialised "no value")
+ *   any other JSON object, array, `true`/`false`        -> unreadable: structured, and not an API key
+ *   text that STARTS like JSON (`{` / `[`) but does not
+ *   parse                                               -> unreadable. It was meant to be structured;
+ *                                                          sending the whole blob as the key header
+ *                                                          would put a broken record on the wire
+ *   any other text                                      -> the trimmed text, if it has no whitespace
+ *
+ * A JSON NUMBER is deliberately a key: one made only of digits parses as a number, and it is still
+ * the key.
+ */
+export declare function interpretToolSecret(raw: string, locator: string): ToolSecretResult;
+export declare function createToolSecretResolver(deps: ToolSecretResolverDeps): ToolSecretResolver;

package/dist/rpc/bridge.d.ts

@@ -0,0 +1,14 @@
+import { type ControlResponseFrame } from "@yanlinglabs/winter-agent-sdk";
+import type { FrameSink } from "../protocol/channel.js";
+export interface RpcBridge {
+    request<T = unknown>(subtype: string, payload: unknown, opts?: {
+        timeoutMs?: number;
+        requestId?: string;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    handleResponse(frame: ControlResponseFrame): boolean;
+    ownsRequest(requestId: string): boolean;
+    rejectAllPending(err: unknown): void;
+    cancel(requestId: string): void;
+}
+export declare function createRpcBridge(output: FrameSink): RpcBridge;

package/dist/rpc/mcp-control.d.ts

@@ -0,0 +1,26 @@
+import type { McpServerState, McpServerStateKind, McpServerStateSource } from "../mcp/state.js";
+import type { McpControlSeam } from "../mcp/control-seam.js";
+export type McpControlResult = {
+    ok: true;
+    payload?: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function toWireMcpStatus(kind: McpServerStateKind): string;
+export declare function mcpServerStatesToWire(states: readonly McpServerState[]): Array<{
+    name: string;
+    status: string;
+    protocolVersion?: string;
+}>;
+export interface McpControlDeps {
+    stateSource?: McpServerStateSource;
+    controlSeam?: McpControlSeam;
+}
+export declare function handleMcpStatus(deps: McpControlDeps): Promise<McpControlResult>;
+export declare function handleMcpReconnect(deps: McpControlDeps, payload: unknown): Promise<McpControlResult>;
+export declare function handleMcpToggle(deps: McpControlDeps, payload: unknown): Promise<McpControlResult>;
+export declare function handleMcpSetServers(deps: McpControlDeps, payload: unknown): Promise<McpControlResult>;

package/dist/runtime.d.ts

@@ -0,0 +1,14 @@
+import type { FrameSource, FrameSink } from "./protocol/channel.js";
+import { type Provider, type ToolExecutor, type SessionPersistence } from "./engine.js";
+export declare function runWinterRuntime(opts: {
+    input: FrameSource;
+    output: FrameSink;
+    provider: Provider;
+    sessionId: string;
+    cwd: string;
+    model: string;
+    permissionMode?: string;
+    maxTurns?: number;
+    tools?: ToolExecutor;
+    store?: SessionPersistence;
+}): Promise<void>;

package/dist/sandbox/profile.d.ts

@@ -0,0 +1,249 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * P7a (D19): the two dot-dir names the seatbelt fences. `homeDirName` anchors the winter root under
+ * the OS home (the run-dir read deny, the backups write deny, the provider-state read deny);
+ * `projectDirName` anchors the per-writable-root control plane (WS-12 §5.2's carve-out).
+ */
+export type SandboxBrand = Pick<BrandProfile, "homeDirName" | "projectDirName">;
+import { type GlobDenyEntry } from "../permissions/file-rules.js";
+export interface SandboxFilesystemSettings {
+    allowWrite?: string[];
+    denyWrite?: string[];
+    allowRead?: string[];
+    denyRead?: string[];
+    /**
+     * Fix round 16, item 2 (claude's own `ag()`, dump-verified: `function ag(){return
+     * pe?.filesystem?.allowGitConfig??!1}`): `sandbox.filesystem.allowGitConfig` in settings.json --
+     * the ONE settings-facing door for `SeatbeltProfileInput.allowGitConfigWrites`/
+     * `RunCommandOptions.allowGitConfigWrites`, which this module and spawn.ts already had (round 15)
+     * but nothing set. Wired through `tools/impl/{bash,monitor}.ts`'s own options-builders (each reads
+     * `ctx.sandboxSettings.filesystem?.allowGitConfig` directly) -- `buildSeatbeltProfile` itself never
+     * reads this field; it is CONSUMED at the caller boundary (spawn.ts's own `allowGitConfigWrites`
+     * param), matching every other filesystem key's own "settings shape carries it, a caller resolves
+     * it into the profile-builder's own dedicated param" pattern in this file.
+     */
+    allowGitConfig?: boolean;
+}
+export interface SandboxNetworkSettings {
+    allowedDomains?: string[];
+    deniedDomains?: string[];
+    [key: string]: unknown;
+}
+export interface SandboxSettings {
+    enabled?: boolean;
+    autoAllowBashIfSandboxed?: boolean;
+    excludedCommands?: string[];
+    allowUnsandboxedCommands?: boolean;
+    filesystem?: SandboxFilesystemSettings;
+    network?: SandboxNetworkSettings;
+}
+export declare const DEFAULT_SANDBOX_SETTINGS: Readonly<SandboxSettings>;
+export declare class SandboxConfigError extends Error {
+    constructor(message: string);
+}
+export declare function resolveNetworkPosture(network: SandboxNetworkSettings | undefined): boolean;
+export declare function canonicalizePath(p: string): string;
+/**
+ * P7a fix r1 (Important-1): render ONE brand token as a case-insensitive, regex-escaped SBPL literal.
+ *
+ * The three any-depth control-plane regexes below used to hard-code `[Ww][Ii][Nn][Tt][Ee][Rr]` while
+ * the per-root LITERAL denies beside them already derived from `brand.projectDirName`. WS-12 §5.2
+ * names those regexes as the closure for the nested-store hole -- a broad writable parent makes
+ * `<parent>/proj/<dot-dir>/settings.json` writable with no literal deny for it -- and §5.2 also
+ * records that the seatbelt is the ONLY enforcement point left for a bash-invoked write to the
+ * permission control plane. Hard-coded, they fenced a directory a reuser's product never reads while
+ * leaving the reuser's own control plane open to `echo x > <root>/<nested>/.acme/settings.json`.
+ *
+ * ESCAPE FIRST, FOLD SECOND, per character: a letter becomes `[Xx]`, and everything else is escaped
+ * exactly as `sbplRegexLiteral` escapes it (the brand grammar admits `-` and, for a dot-dir, the
+ * leading `.` -- which MUST be escaped or it matches any character). Applied to Winter's own dot-dir
+ * it renders `\.[Ww][Ii][Nn][Tt][Ee][Rr]`, byte for byte what the constant it replaces spelled, so
+ * the rendered profile is unchanged under `WINTER_BRAND` (a test diffs the whole profile text).
+ *
+ * Exported so the deny suite can assert the rendering directly rather than by reading the profile.
+ */
+export declare function caseFoldSegment(segment: string): string;
+export interface SeatbeltProfileInput {
+    /** The session's own working directory -- always a writable root. */
+    cwd: string;
+    /** Extra writable subpaths: session scratch (ctx.tempDir), configured filesystem.allowWrite, outputs dir, etc. */
+    writableRoots?: string[];
+    /** WS-12 §5.3: filesystem.denyWrite, layered AFTER the write-allow block (last-match-wins). */
+    denyWritePaths?: string[];
+    /** WS-12 §5.3: filesystem.denyRead, layered AFTER the read-allow block (last-match-wins). */
+    denyReadPaths?: string[];
+    /**
+     * Fix round 11 (claude's `Li`/`Rt`, dump byte 15365905/15282610, pinned 2.1.250): glob-shaped
+     * deny entries, PRE-CONVERTED by the caller to SBPL regex SOURCE TEXT (`permissions/file-rules.ts`'s
+     * `globToSbplRegexSource`/`recursiveGlobToSbplRegexSource`/`splitDenyPathsByGlobShape`) -- this
+     * module has no glob grammar of its own (mirrors `denyWritePaths`/`denyReadPaths`'s own "already
+     * resolved by the caller" posture) and only quotes/renders. Claude's own macOS sandbox profile
+     * builder renders a glob-shaped deny as `(regex ...)` and a plain one as `(subpath ...)` (`Li`); a
+     * `subpath` deny alone -- Winter's pre-round-11 posture -- silently drops a glob-shaped Edit deny
+     * (e.g. a globstar-anchored `.env` pattern) or `denyWrite` entry from the sandbox layer entirely
+     * (the PERMISSION-RULE layer still enforced it for a recognized tool call; a bash-invoked
+     * `tee`/`cp` bypassing that layer did not).
+     */
+    denyWriteRegexes?: string[];
+    denyReadRegexes?: string[];
+    /**
+     * Fix round 12 ("Important" item, claude's own `Ch`/`ed`/`mR`/`pR`, dump byte 15368116/15367994/
+     * 15369065/15368380, pinned 2.1.250): the ancestor-rename-bypass fix. `denyWriteGlobFixedPrefixes`/
+     * `denyReadGlobFixedPrefixes` are the CANONICALIZED fixed-prefix directory of each glob-shaped
+     * denyWrite/denyRead entry (`permissions/file-rules.ts`'s `splitDenyPathsByGlobShape`, its own
+     * `globFixedPrefixes` output) -- this module has no glob grammar of its own, mirrors the other
+     * caller-pre-resolved fields above. Combined with `denyWritePaths`/`denyReadPaths` (the PLAIN
+     * entries, reused directly -- no new field needed for those), `buildAncestorRenameBypassBlock`
+     * below builds a `(deny file-write-unlink file-write-create ...)` clause naming every ANCESTOR of
+     * each denied path/glob-fixed-prefix, PLUS the fixed prefix itself, so a sandboxed `mv <ancestor>
+     * <elsewhere> && <write inside where it used to be> && mv <elsewhere> <ancestor>` cannot rename an
+     * ancestor of a denied path out of the way (and back) to slip a write past the deny.
+     */
+    denyWriteGlobFixedPrefixes?: string[];
+    denyReadGlobFixedPrefixes?: string[];
+    /**
+     * Fix round 13 ("Important" item 1, claude's own `fR`, dump byte 15367091): "keep read-denied
+     * paths inside write roots in place." Winter's read-deny/write-allow sections previously composed
+     * exactly the way claude's OWN `mR`/`pR` alone would -- last-match-wins, and the write-allow
+     * (`(allow file-write* (subpath <root>))`) is emitted AFTER the read-deny section, so it silently
+     * overrides any read-deny's own implicit protection against being UNLINKED (renamed away): with
+     * `Read(.env)` denied and cwd writable, a sandboxed `mv .env x && cat x` renamed the read-denied
+     * file to a new, non-denied name and read the secret through it. claude closes this with a THIRD
+     * section, `fR`, emitted AFTER the write-allow block: for each read-denied path (or glob-shaped
+     * entry, `denyReadGlobEntries` below) that sits inside a write root, denies `file-write-unlink` on
+     * its own recursive clause (minus any write root nested INSIDE it, carved back out) and on every
+     * one of its ancestor directories that is ALSO inside a write root.
+     */
+    denyReadGlobEntries?: GlobDenyEntry[];
+    /** Resolved network posture -- see resolveNetworkPosture's own header for why this is a plain boolean here. */
+    allowNetwork: boolean;
+    /**
+     * The real per-user temp dir (`confstr(_CS_DARWIN_USER_TEMP_DIR)`, exposed by `getconf
+     * DARWIN_USER_TEMP_DIR` -- resolved by spawn.ts, never by this module, to keep profile.ts
+     * platform-free). Omitted entirely -> the mktemp convenience rule is simply not emitted, which is
+     * still a CORRECT (if less ergonomic) profile -- mirrors Norma's own "a profile without this
+     * convenience rule is still a correct profile" comment.
+     */
+    darwinUserTempDir?: string;
+    /**
+     * WS-12 §2: "the sole baseline read denial is `<home>/<homeDirName>/run`, enforced via profile
+     * deny rules layered over allow-read." The daemon's own runtime dir (control socket, PID/lock
+     * files) -- a bash-invoked `cat ~/<homeDirName>/run/core.sock` never passes through a read-tool's own
+     * permission fence at all (reads are otherwise deliberately unrestricted, per this product's own
+     * tool-surface design), so the seatbelt profile is the only enforcement point left. Omitted
+     * entirely -> no baseline deny is emitted, still a correct (if less defended) profile -- mirrors
+     * `darwinUserTempDir`'s own "omitted is still correct" posture; there is no ToolExecutionContext
+     * seam this module can reach into itself (profile.ts stays platform/context-free by design, per
+     * this file's own header), so every caller (spawn.ts -> tools/impl/{bash,monitor}.ts) is
+     * responsible for threading its own `ctx.home` through.
+     */
+    home?: string;
+    /**
+     * Phase 5 fix wave, I1: the RESOLVED winter root (`<PREFIX>HOME` when set), when it differs
+     * from `<home>/<homeDirName>`.
+     *
+     * `home` above is the OS home and this module appends `brand.homeDirName` to it -- correct only
+     * when the resolved root is literally named that. Under a `<PREFIX>HOME` pointing anywhere
+     * else, the run read-deny and the backups write-deny both landed on a directory that does not
+     * exist while the real one stayed open.
+     *
+     * ADDED, NEVER SWAPPED: both anchors are emitted, because the carried WS-12 §5.2 deny corpus and
+     * every default-home session still assume the literal default, and two denies of overlapping scope
+     * cost nothing.
+     */
+    winterHome?: string;
+    /**
+     * WS-21 §3.7/§6.3 item 11: the shared runtime home's durable-paths root (`config.storeHome`),
+     * preferred over `winterHome` for the two DURABLE denies below -- the checkpoint (backups) write
+     * deny and the provider-state read deny, both of which protect `projects/`-rooted content that
+     * lives under the store home once the router links `buildRunHome`, a directory now DISTINCT from
+     * the per-run folder `winterHome` names. The run-dir read deny is left anchored on `winterHome`
+     * unchanged: it protects the daemon's own `run/` (sockets, pidfiles), which is neither the
+     * per-run folder nor the store home in the WS-21 layout, so this module has no better anchor for
+     * it than it already had -- a disclosed, unchanged limitation, not a regression.
+     */
+    storeHome?: string;
+    /**
+     * P7a (D19): the brand whose dot-dir and project dot-dir this profile fences.
+     *
+     * Every winter-owned path segment below is `brand.homeDirName` (the root under the OS home) or
+     * `brand.projectDirName` (the per-writable-root control plane). Omitted = `WINTER_BRAND`, so a
+     * caller that threads none emits byte-identical SBPL -- which is what the carried WS-12 §5.2 deny
+     * corpus and the darwin deny suite assert.
+     */
+    brand?: SandboxBrand;
+    /**
+     * Fix round 15 (claude's own `cR(e=false)` / `mR`'s own `r=false` default parameter): when true,
+     * `.git/config` is NOT added to the default write-protected entries (`buildDefaultWriteProtectionBlock`
+     * above) -- every OTHER default protection (shell/tool config files, editor/agent dot-dirs,
+     * `.git/hooks`) is unaffected; this flag only ever gates `.git/config`, matching `cR`'s own `!e`
+     * guard exactly. Omitted = `false` = protected, matching claude's own default. No caller sets this
+     * true yet -- kept for parity since claude's own signature carries the knob.
+     */
+    allowGitConfigWrites?: boolean;
+}
+/**
+ * Build a macOS Seatbelt (SBPL) profile: deny-by-default, read anywhere (minus configured
+ * denyRead layers and, when `home` is given, the WS-12 §2 baseline `<home>/<homeDirName>/run` denial --
+ * see `SeatbeltProfileInput.home`'s own header), write only under the given roots (minus configured
+ * denyWrite layers), network denied unless explicitly allowed.
+ *
+ * WS-12 §5.2 (verbatim carry, Winter-renamed): EVERY writable root (cwd + each of `writableRoots`)
+ * additionally gets an explicit `(deny <ops> (literal "<root>/<projectDir>/<file>"))` line, for
+ * each of `permissions.local.json`/`settings.json`/`settings.local.json`, unconditionally, with no
+ * opt-in flag to forget -- a bash-invoked `echo x > <projectDir>/permissions.local.json` never passes
+ * through a write/edit TOOL's own permission fence at all, so the seatbelt is the only enforcement
+ * point left for a shell-invoked write to the permission/settings control plane. SBPL evaluates a
+ * profile's rules for a given operation in FILE ORDER, last-match-wins, WITH ONE EMPIRICALLY-VERIFIED
+ * EXCEPTION (fix round 14, `WRITE_OPS_SURVIVING_READ_DENY_REPERMIT`'s own header): a clause naming
+ * `file-write-unlink`/`file-write-create` EXPLICITLY beats one that only reaches them via the
+ * `file-write*` wildcard, independent of file order -- which is why `<ops>` here is
+ * `WRITE_OPS_SURVIVING_READ_DENY_REPERMIT` (`file-write* file-write-unlink file-write-create`), not a
+ * bare `file-write*`, since round 14 added an EARLIER, blanket, explicit-named re-permit
+ * (`buildReadDenyWritePermitBlock`) that a bare-wildcard deny here would no longer survive. Ordinary
+ * last-match-wins still governs every OTHER write operation (`file-write-data`, etc.) and governs
+ * `<ops>` vs. `<ops>` ties among explicit-named clauses -- placing these denies AFTER the
+ * `(allow file-write* (subpath ...))` block carves out exactly these files from an otherwise-writable
+ * subpath, without touching a sibling file or an entire OTHER subdirectory like the MEMDIR.
+ *
+ * A companion `(deny <ops> (regex ...))` per filename, placed after the per-root literals, closes
+ * the NESTED-store hole a literal-only deny misses: a broad `writableRoots` entry makes a nested
+ * `<root>/projB/<projectDir>/settings.json` writable too, with no literal deny naming that exact
+ * path. Case-folded per character (see the module-level regex constants' own comment).
+ */
+export declare function buildSeatbeltProfile(input: SeatbeltProfileInput): string;
+/**
+ * Tight Seatbelt profile for a workflow-worker subprocess (WS-11 §1.7's own consumer -- that phase
+ * has not shipped a real worker yet; this ships the tested mechanism now, verbatim-ported from
+ * Norma's `workflows/sandbox.ts`). Strictly tighter than the ordinary Bash profile:
+ *   - deny file-write* EVERYWHERE (the worker writes nothing; the journal is appended parent-side),
+ *   - deny network*,
+ *   - deny process-fork AND allow process-exec ONLY for the self binary.
+ *
+ * Part B item 2 (fix wave, P3 close-out) -- THE READ-AXIS CARRY IS NOW CLOSED (Phase 5 Task 3,
+ * R5-5: "the P3 worker seatbelt profile PLUS the ledgered run-directory deny"). `opts.home`, when
+ * supplied, emits the same baseline `<home>/<homeDirName>/run` read-deny rule the ordinary Bash profile
+ * carries (buildSeatbeltProfile's own `home` field), making this profile a strict superset of that
+ * one's denials on every axis.
+ *
+ * `opts` is REQUIRED and `opts.home` is `string | undefined` -- NOT an optional property (fix round
+ * 1): "Lane W's spawner must remember to pass it" is exactly the obligation that gets forgotten, and
+ * an optional parameter makes forgetting compile. Making the argument mandatory while allowing an
+ * explicit `undefined` turns the silent gap into a compile error at every call site, and leaves the
+ * genuinely home-less callers (profile.test.ts, the string-shape half of the darwin suite) able to
+ * state that they mean it. A profile built with `{ home: undefined }` is still correct, just less
+ * defended -- exactly as buildSeatbeltProfile documents for its own `home`.
+ *
+ * THE #1 RISK (verified empirically by the Norma original): a blanket `(deny process-exec*)` makes
+ * sandbox-exec's own execvp() of the target fail ("Operation not permitted"), because the
+ * sandbox->target transition is itself an exec checked against the profile. So this allows exec of
+ * EXACTLY `selfExecPath` (canonicalized) and nothing else -- enough for the runtime binary to boot
+ * (it dyld-loads its libs via the allowed file-read*), while a workflow script still cannot exec
+ * /bin/sh etc. Note the operation is `process-fork` (no star) -- `process-fork*` is an unbound
+ * variable that fails to load.
+ */
+export declare function buildWorkflowWorkerSeatbeltProfile(selfExecPath: string, opts: {
+    home: string | undefined;
+    winterHome?: string;
+    brand?: SandboxBrand;
+}): string;

package/dist/sandbox/spawn.d.ts

@@ -0,0 +1,139 @@
+import { type SandboxBrand, type SandboxSettings } from "./profile.js";
+import type { GlobDenyEntry } from "../permissions/file-rules.js";
+export declare function isSandboxAvailable(checkPath?: string): boolean;
+export declare class SandboxUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare function resolveDarwinUserTempDir(): string | null;
+/** Test seam: forget the cached per-user temp dir so a test can observe resolution again. */
+export declare function resetDarwinUserTempDirCacheForTest(): void;
+export type SandboxPosture = "config-disabled" | "override-requested" | "excluded" | "sandboxed" | "unavailable";
+export interface ResolveExecutionPathInput {
+    settings: SandboxSettings;
+    dangerouslyDisableSandbox?: boolean;
+    command: string;
+}
+export interface ExecutionPathDecision {
+    posture: Exclude<SandboxPosture, "unavailable">;
+    /**
+     * WS-12 §4: the call's OWN raw `dangerouslyDisableSandbox` flag, independent of which posture
+     * actually won the first-match-wins table below -- so a result can show "the model asked for the
+     * override" even on the rare path where `enabled: false` already made it moot (row 1 beats row 2).
+     */
+    sandboxOverrideRequested: boolean;
+}
+/**
+ * WS-12 §4.1's own table, first-match-wins:
+ *   1. `sandbox.enabled === false`                                  -> unsandboxed (config-disabled)
+ *   2. `dangerouslyDisableSandbox: true` on the call, UNLESS `allowUnsandboxedCommands === false`
+ *                                                                   -> unsandboxed (override-requested)
+ *   3. command matches `excludedCommands` AND `allowUnsandboxedCommands` -> unsandboxed (excluded)
+ *   4. otherwise                                                    -> sandboxed
+ *
+ * R3-6 (capture-pending, per this task's own brief): `excludedCommands` matching is EXACT-FULL-
+ * COMMAND-STRING equality only -- no trimming, no argv[0] extraction, no prefix rule. WS-12 §12
+ * open question 2 leaves the real matching semantics for a future WS-17 differential capture; this
+ * is the deliberately narrow placeholder until that capture lands.
+ */
+export declare function resolveExecutionPath(input: ResolveExecutionPathInput): ExecutionPathDecision;
+export interface RunCommandOptions {
+    command: string;
+    /**
+     * Task 8 (P3 close-out, "excludedCommands raw-match" MUST): the command string `resolveExecutionPath`
+     * matches against `settings.excludedCommands`, when it differs from `command` above (the string
+     * that actually gets spawned). Defaults to `command` when omitted -- byte-identical to every caller
+     * before this field existed (background execution, Monitor's command half, both of which already
+     * spawn the model's raw command with no wrapper). bash.ts's own foreground path is the one caller
+     * that needs this: it wraps the raw command in a pwd-capture script before spawning (see that
+     * file's own `buildPwdCaptureScript`/`runForeground` header comment, "LATENT TRAP") but must match
+     * `excludedCommands` against what the model/settings author actually wrote, never the wrapper.
+     */
+    matchCommand?: string;
+    /** Real, existing, already-canonicalized directory to spawn the shell in. */
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+    /**
+     * Fires synchronously once the child is spawned, before any output arrives -- the ONLY way a
+     * caller can learn the process-group pid early enough to track/kill it while it is still
+     * running (`RunCommandResult.exitCode` etc. only resolve once the process has already exited).
+     * `run_in_background` callers (tools/impl/bash.ts) need this to register the task BEFORE
+     * awaiting the eventual result; a foreground caller simply omits it.
+     */
+    onSpawned?: (info: {
+        pid: number;
+    }) => void;
+    maxStreamedBytes?: number;
+    settings: SandboxSettings;
+    dangerouslyDisableSandbox?: boolean;
+    /**
+     * TEST-ONLY injection seam: overrides which path the internal `isSandboxAvailable` check probes
+     * for existence, WITHOUT changing the real spawn target (`REAL_SANDBOX_EXEC_PATH` below is always
+     * what actually runs once availability passes). WS-12 §3's typed-unavailability path is otherwise
+     * unreachable on any dev/CI box that genuinely has /usr/bin/sandbox-exec -- which is every darwin
+     * box this product ships on -- so without this seam the throw site below has zero live coverage.
+     * Never read from model input (bash.ts's own BashInput has no such field): a model-controllable
+     * override of its own sandbox-availability check would be a containment hole, not a test seam.
+     */
+    sandboxExecPath?: string;
+    /** Extra writable roots beyond cwd -- session scratch, configured filesystem.allowWrite, outputs dir. */
+    writableRoots?: string[];
+    denyWritePaths?: string[];
+    denyReadPaths?: string[];
+    /**
+     * Fix round 11 (claude's `Li`/`Rt`, dump byte 15365905/15282610): glob-shaped `denyWritePaths`/
+     * `denyReadPaths` entries, PRE-CONVERTED to SBPL regex source by the caller (`permissions/
+     * file-rules.ts`'s `splitDenyPathsByGlobShape`) -- this module stays glob-grammar-free, exactly
+     * like `denyWritePaths`/`denyReadPaths` themselves are already resolved, absolute paths by the
+     * time they reach here.
+     */
+    denyWriteRegexes?: string[];
+    denyReadRegexes?: string[];
+    /**
+     * Fix round 12 ("Important" item, claude's own `Ch`/`ed`): the ancestor-rename-bypass fix -- each
+     * glob-shaped `denyWritePaths`/`denyReadPaths` entry's OWN canonicalized fixed-prefix directory
+     * (see `SeatbeltProfileInput.denyWriteGlobFixedPrefixes`'s own header). Same "caller pre-resolves,
+     * this module stays glob-grammar-free" posture as `denyWriteRegexes`/`denyReadRegexes` above.
+     */
+    denyWriteGlobFixedPrefixes?: string[];
+    denyReadGlobFixedPrefixes?: string[];
+    /**
+     * Fix round 13 ("Important" item 1, claude's own `fR`): the read-deny-keep-in-place fix -- each
+     * glob-shaped `denyReadPaths` entry, PAIRED with its own fixed prefix (see
+     * `SeatbeltProfileInput.denyReadGlobEntries`'s own header). Read-only -- claude's own `fR` is a
+     * read-deny-specific concern.
+     */
+    denyReadGlobEntries?: GlobDenyEntry[];
+    /**
+     * WS-12 §2: the caller's `ctx.home`, threaded straight through to `buildSeatbeltProfile`'s own
+     * `home` field for the baseline `<home>/<homeDirName>/run` read denial -- see that field's own header
+     * for why this module (rather than profile.ts) is where a real `ctx.home` value gets plugged in.
+     * Omitted -> no baseline deny is emitted, same graceful-degradation posture as every other
+     * optional profile input here.
+     */
+    home?: string;
+    /** Phase 5 fix wave, I1: the resolved winter root -- see `SeatbeltProfileInput.winterHome`. */
+    winterHome?: string;
+    /** WS-21 §3.7: the shared runtime home's durable-paths root -- see `SeatbeltProfileInput.storeHome`. */
+    storeHome?: string;
+    /** P7a (D19): the session's brand -- the dot-dir names the profile fences. Omitted = `WINTER_BRAND`. */
+    brand?: SandboxBrand;
+    /** Fix round 15: see `SeatbeltProfileInput.allowGitConfigWrites`'s own header. Omitted = `false`. */
+    allowGitConfigWrites?: boolean;
+}
+export interface RunCommandResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    streamKilled: boolean;
+    posture: Exclude<SandboxPosture, "unavailable">;
+    sandboxOverrideRequested: boolean;
+    /** The generated SBPL profile text, only present when posture === "sandboxed" (debug/test aid). */
+    profile?: string;
+    /** Set when the child never actually launched (Node's "error" event) -- distinct from a signal-killed exit (exitCode null, this unset). */
+    spawnError?: string;
+}
+export declare function runCommand(opts: RunCommandOptions): Promise<RunCommandResult>;

package/dist/settings/env-filter.d.ts

@@ -0,0 +1,52 @@
+export type EnvFilterTier = "user" | "project" | "local" | "flag";
+/**
+ * F17 (V8): what a PROJECT or LOCAL tier's `env` block may never set, on top of
+ * `ALL_TIER_REFUSED_ENV`. `CLAUDE_CODE_PLUGIN_SEED_DIR`/`CLAUDE_CODE_PROCESS_WRAPPER` are claude's
+ * own names (no Winter twin exists); `pluginCacheDirEnvName` is `CLAUDE_CODE_PLUGIN_CACHE_DIR`'s
+ * twin, refused at this tier for the identical reason claude refuses the original.
+ */
+export declare const PROJECT_TIER_REFUSED_ENV: readonly string[];
+/**
+ * F17's "every tier drops" list, plus every variable ONLY the router may set (spec §3.4.4 step 4 /
+ * the Global Constraints list) -- claude-named and Winter-brand-twinned alike. `CLAUDE_CONFIG_DIR`
+ * is explicitly HERE despite F17 saying claude itself never drops it (F17 describes claude's OWN
+ * base rule; Winter's router additionally refuses it from settings because only the router may ever
+ * set the child's config dir -- the Global Constraints list is the authority for that addition).
+ */
+export declare const ALL_TIER_REFUSED_ENV: readonly string[];
+/**
+ * F20: once host-managed provider auth is on, every tier's `env` additionally loses every
+ * provider/auth/proxy/TLS key -- DISCLOSED, not exhaustively pinned against a live capture (F20's
+ * own wording is categorical: "provider, auth, proxy and TLS keys", not a closed name list). Grown
+ * by a fixture the way V19's own repo-read enumeration is, rather than guessed complete here.
+ *
+ * Fix round 1 (Important 3): `/^ANTHROPIC_/` alone caught Anthropic's own `ANTHROPIC_BASE_URL`, but
+ * every OTHER provider's base-URL override (`OPENAI_BASE_URL`, `DEEPSEEK_BASE_URL`, ...) sailed
+ * through -- F20's own wording ("provider... keys") is provider-AGNOSTIC, and a settings `env`
+ * block redirecting ANY provider's endpoint is the identical class of hole a redirected Anthropic
+ * endpoint is. `/^CLAUDE_CODE_USE_/` (+ its Winter-brand twin) closes the PROVIDER-SWITCH class
+ * (claude's own `CLAUDE_CODE_USE_BEDROCK`/`CLAUDE_CODE_USE_VERTEX`-shaped variables): flipping which
+ * backend a host-managed session talks to is an endpoint redirect by another name.
+ */
+export declare const HOST_MANAGED_REFUSED_ENV_PATTERNS: readonly RegExp[];
+/**
+ * `Settings` KEYS (not env vars) that host-managed mode disables (F20: "disables apiKeyHelper/
+ * awsAuthRefresh/awsCredentialExport"). Only `apiKeyHelper` is modelled in Winter's own `Settings`
+ * shape today (`packages/sdk/src/settings/types.ts:95`) -- claude's `awsAuthRefresh`/
+ * `awsCredentialExport` have no Winter field to disable yet, so there is nothing to add for them
+ * until one exists.
+ */
+export declare const HOST_MANAGED_DISABLED_SETTINGS_KEYS: readonly string[];
+/**
+ * Filters one settings tier's `env` block before it reaches the child's process env. `undefined`
+ * input (no `env` block at all) yields `{}`, never a throw.
+ */
+export declare function filterSettingsEnv(env: Record<string, string> | undefined, tier: EnvFilterTier, opts: {
+    hostManaged: boolean;
+}): Record<string, string>;
+/**
+ * F20's settings-KEY half of host-managed mode: strips `HOST_MANAGED_DISABLED_SETTINGS_KEYS` from a
+ * settings-shaped object when `hostManaged` is on. Generic over the object shape (`production-
+ * wiring.ts` applies it to a tier's resolved `Settings`, never re-deriving the key list itself).
+ */
+export declare function applyHostManagedSettingsFilter(settings: Record<string, unknown>, hostManaged: boolean): Record<string, unknown>;

package/dist/settings/loaders/hooks.d.ts

@@ -0,0 +1,44 @@
+import { type HookEntriesFromSettings, type SettingsHookSourceInput } from "../../hooks/from-config.js";
+import type { PluginBundle } from "../../plugins/bundle.js";
+/**
+ * The `HookSource` a plugin's hooks are filed under.
+ *
+ * WAS `sdk`, A DISCLOSED STAND-IN -- Phase 5 Task 8 (rider 19) added the real `plugin` member to
+ * `HookSource`, closing this lane's own NEEDS_CONTEXT 4. The stand-in's visible cost was that a
+ * plugin hook was indistinguishable from an `Options.hooks` registration in an audit record's
+ * `source` field; it now names itself.
+ *
+ * UNGATED by workspace trust, unchanged: a plugin is loaded because a decision was made outside the
+ * repository, so gating it on which directory the session is in is neither the pin's model nor
+ * Winter's (`subagents/definitions.ts` records the identical reasoning for `pluginAgents`). It ranks
+ * LAST in the merge order (`SOURCE_RANK.plugin = 5`, after `sdk`) -- a plugin ships defaults every
+ * more-specific source may override.
+ */
+export declare const PLUGIN_HOOK_SOURCE: "plugin";
+/** The `resolveSettingsDetailed` / pinned `ResolvedSettings` shapes this accepts -- either field. */
+export interface ResolvedSettingsHookInput {
+    perSource?: readonly SettingsHookSourceInput[] | undefined;
+    sources?: readonly SettingsHookSourceInput[] | undefined;
+}
+/**
+ * Project a settings resolution onto `buildHookEntriesFromSettings`' input.
+ *
+ * `perSource` is preferred (it is a superset carrying `loaded`/`error`); the pinned `sources` array
+ * is the fallback so a caller holding only a `ResolvedSettings` can still produce hooks. Both are
+ * already highest-precedence-first, and this preserves that order -- the registry's own stable sort
+ * uses registration order as its within-source tiebreak.
+ */
+export declare function settingsHookSourceInputs(resolved: ResolvedSettingsHookInput | undefined): SettingsHookSourceInput[];
+/**
+ * Turn every loaded plugin's manifest `hooks` block into real entries.
+ *
+ * ONE `buildHookEntriesFromSettings` CALL PER PLUGIN, then the ids are re-stamped with the plugin's
+ * name. That is not tidiness -- it is a correctness requirement. That function derives an id
+ * positionally, `${event}:${source}:${groupIndex}:${hookIndex}`, which is deterministic on both
+ * sides of the wire and therefore IDENTICAL for two different plugins whose blocks have the same
+ * shape. `createCommandHookInvoker` builds `commandsById` as a `Map`, so two colliding ids would
+ * leave the LAST plugin's command answering for both entries -- one plugin's hook silently running
+ * another plugin's shell command. Prefixing with the plugin name also keeps a plugin id disjoint
+ * from every `Options.hooks` id, which shares the same `sdk` source.
+ */
+export declare function pluginHookEntries(bundles: readonly PluginBundle[]): HookEntriesFromSettings;