@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/official/mcp-descriptors.d.ts

@@ -0,0 +1,130 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/** A JSON-Schema object, in the subset the descriptors use. */
+export interface JsonSchemaObject {
+    type: "object";
+    properties: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    required?: readonly string[];
+}
+/** What a handler answers with — the MCP content shape, identical on both branches. */
+export interface WinterMcpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * A tool handler, and the vendor's own second argument (item 15).
+ *
+ * `extra` IS FORWARDED, NOT DROPPED — but what it CARRIES is a measurement, not an assumption. The
+ * carry that produced this change asked for it so the official branch could derive WS-10 §12's retry
+ * key (the (session, tool-call id) pair a retry must allocate the SAME message id from), and the
+ * whole-branch review was right to say that must be checked first: the in-process server's `extra` is
+ * the MCP REQUEST CONTEXT — the JSON-RPC request id and `_meta` — which is not the model's
+ * `tool_use_id`. `test/official/runtime-aliases.test.ts` records what the pinned runtime actually
+ * puts there; see that test and this module's own note below for the answer.
+ *
+ * Forwarding it is worth doing either way: it is the only channel the vendor gives a tool for request
+ * context, dropping it is unrecoverable at the handler, and a handler that does not want it simply
+ * declares one parameter.
+ */
+export type WinterMcpHandler = (args: unknown, extra?: unknown) => Promise<WinterMcpToolResult>;
+/** One tool on the standing server. Everything a branch needs to register it, and nothing branch-specific. */
+export interface WinterMcpToolDescriptor {
+    /** The bare tool name (`send_message`); the canonical name is derived from it and the brand. */
+    tool: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    outputSchema?: JsonSchemaObject;
+    annotations?: Readonly<Record<string, unknown>>;
+    /** WS-09 §10's exposure map. The canonical twins of aliased built-ins are deferred (§7). */
+    exposure: "eager" | "deferred" | "hidden";
+    /** The permission identity both branches must agree on (WS-07). */
+    permissionClass: string;
+    handler: WinterMcpHandler;
+}
+/** The standing server, as one descriptor. `name` is the brand's, so `mcp__<name>__<tool>` follows. */
+export interface WinterMcpServerDescriptor {
+    name: string;
+    version: string;
+    tools: readonly WinterMcpToolDescriptor[];
+}
+/** The two messaging handlers §7's aliases resolve to. Their implementations are the router's. */
+export interface MessagingHandlers {
+    sendMessage: WinterMcpHandler;
+    listAgents: WinterMcpHandler;
+}
+/**
+ * The messaging tools, with the NATIVE schemas mirrored (§7: "handlers MUST accept the native
+ * argument schemas exactly").
+ *
+ * `deferred` on both: they are the canonical twins of aliased built-ins, and §7 wants the model to
+ * see one `SendMessage`, not two.
+ */
+export declare function messagingToolDescriptors(handlers: MessagingHandlers): readonly WinterMcpToolDescriptor[];
+/**
+ * §11's refusal: no advisor on this server, on this branch.
+ *
+ * Thrown rather than filtered. A silent filter would leave a host believing its advisor was
+ * registered and wondering why the model never calls it; the whole point of D29's split is that each
+ * branch's advisor has a DIFFERENT backing, and a host that tried to register one here has a
+ * misunderstanding worth surfacing.
+ */
+export declare function assertNoAdvisor(tools: readonly WinterMcpToolDescriptor[], branchLabel: string): void;
+/**
+ * Builds the standing server descriptor for a session.
+ *
+ * The capability plugins (browser, computer, office) are passed IN rather than declared here: WS-06
+ * owns their exact names and schemas, and a copy of them in the router would be a second declaration
+ * to drift. What the router owns is that they are registered under the same canonical names, with the
+ * same identity, on both branches — which is what `canonicalToolNames` below makes checkable.
+ */
+export declare function winterMcpServerDescriptor(args: {
+    brand: Pick<BrandProfile, "mcpServerName">;
+    messaging: MessagingHandlers;
+    capabilities?: readonly WinterMcpToolDescriptor[];
+    version?: string;
+    branchLabel: string;
+}): WinterMcpServerDescriptor;
+/** The canonical names a descriptor registers — the identity both branches must agree on. */
+export declare function canonicalToolNames(descriptor: WinterMcpServerDescriptor, brand: Pick<BrandProfile, "mcpServerName">): readonly string[];
+/** The subset of the injected official module this needs. Duck-typed: the seam declares only `query`. */
+export interface OfficialMcpModule {
+    createSdkMcpServer?: (options: {
+        name: string;
+        version?: string;
+        tools?: unknown[];
+        instructions?: string;
+    }) => unknown;
+    tool?: (name: string, description: string, inputSchema: unknown, handler: (args: unknown, extra: unknown) => Promise<unknown>, extras?: unknown) => unknown;
+}
+/**
+ * Converts a JSON-Schema object into whatever the official in-process server constructor expects.
+ *
+ * INJECTED, NOT IMPLEMENTED HERE — see this module's header. A host writes it once against the
+ * validator it already has as the official SDK's peer.
+ */
+export type InputShapeFactory = (schema: JsonSchemaObject) => unknown;
+/**
+ * Registers the standing server into the official branch, returning the `mcpServers` entry.
+ *
+ * A MISSING CONSTRUCTOR IS A TYPED FAILURE. An injected module without `createSdkMcpServer` is a
+ * module this branch cannot register a server into at all, and continuing would produce a session
+ * whose aliases resolve to a tool that does not exist — the model's `SendMessage` would fail at the
+ * one moment it matters (WS-17 rows 1–2).
+ */
+export declare function materializeOfficialMcpServer(args: {
+    descriptor: WinterMcpServerDescriptor;
+    module: OfficialMcpModule;
+    toInputShape: InputShapeFactory;
+    branchLabel: string;
+}): unknown;
+/** `Options.mcpServers` for this branch: one entry, keyed by the brand's own server name. */
+/** The descriptor fields the official branch's registration cannot carry (review r1, n3). */
+export declare const OFFICIAL_MATERIALIZATION_DROPS: readonly string[];
+export declare function officialMcpServers(args: {
+    descriptor: WinterMcpServerDescriptor;
+    module: OfficialMcpModule;
+    toInputShape: InputShapeFactory;
+    branchLabel: string;
+}): Record<string, unknown>;

package/dist/official/options-template.d.ts

@@ -0,0 +1,110 @@
+import { mcpToolName, type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { OfficialOptions } from "../seams/official-sdk-shapes.js";
+import type { OptionsTemplateInput } from "../seams/official-adapter.js";
+import { type OfficialPermissionMode } from "./callbacks.js";
+import type { OfficialApprovalBridge } from "./callbacks.js";
+import { type ContainmentPolicy } from "./containment.js";
+/** The vendor's own preset name — a Claude-mirroring literal, fixed (WS-01 §5 / D16). */
+export declare const PINNED_SYSTEM_PROMPT_PRESET = "claude_code";
+/**
+ * §2's pinned auto-memory load cap, "kept in the compatibility profile".
+ *
+ * DATA, NOT AN OPTION: the pinned runtime exposes no knob for it, so the cap is something the HOST
+ * applies when it writes the shared memory file. It lives here because this is where a reader looks
+ * for the memory contract, and because a number that exists only in a spec sentence is a number that
+ * gets rounded.
+ */
+export declare const AUTO_MEMORY_LOAD_CAP: {
+    readonly lines: 200;
+    readonly bytes: number;
+};
+/**
+ * §16 OPEN QUESTION 1, FIXED HERE, PER MODE, WITH THE REASON.
+ *
+ * "`excludeDynamicSections` default: report §124 shows `true` in the safe template; dynamic sections
+ * carry env/context blocks the host may want. The per-mode default is left to the mode-host policy
+ * and MUST BE FIXED BEFORE GOLDEN CAPTURES FREEZE."
+ *
+ * FIXED AT `true` FOR EVERY MODE. The argument is §4's, not a preference: "whether project context is
+ * appended to the system prompt or injected as a Winter-owned context message is a single host-wide
+ * choice, and BOTH BRANCHES MUST USE THE SAME CHOSEN SEMANTICS SO THEY AGREE WITH EACH OTHER". The
+ * vendor's dynamic sections are assembled by the vendor runtime from its own view of the environment
+ * and its own project-context conventions; the other branch cannot reproduce them, so leaving them on
+ * makes the two branches disagree in the one place a handoff makes visible — mid-session, to a user
+ * who just switched runtimes. The deterministic append (§4's ordered build) is what carries the
+ * context instead, identically on both.
+ *
+ * A HOST CAN STILL OVERRIDE, per mode, and the golden captures show which value each mode was built
+ * with — so a change is a diff rather than a discovery.
+ */
+export declare const DEFAULT_EXCLUDE_DYNAMIC_SECTIONS: Readonly<Record<OptionsTemplateInput["mode"], boolean>>;
+/** Host policy for the template — everything §2 leaves to the mode host (WS-15) or to the session. */
+export interface OptionsTemplatePolicy {
+    /** §4's deterministically-built instructions, appended to the pinned preset. */
+    systemPromptAppend?: string;
+    /** §16 q1. Absent → `DEFAULT_EXCLUDE_DYNAMIC_SECTIONS` for the mode. */
+    excludeDynamicSections?: boolean;
+    /**
+     * §5: default `"batched"`; sessions that ADVERTISE CROSS-RUNTIME HANDOFF must use `"eager"` — it
+     * narrows the mirror-lag window. Derived from `advertisesHandoff` rather than set directly, so the
+     * rule is expressed once and cannot be half-applied.
+     */
+    advertisesHandoff?: boolean;
+    /** Additional flag-layer settings the host has already checked against the runtime's schema (§2). */
+    settings?: Readonly<Record<string, unknown>>;
+    /** §11's server entry, already materialized. */
+    mcpServers?: Readonly<Record<string, unknown>>;
+    /** §10's bridge. Absent -> a fail-closed one is installed, because the invariants require one. */
+    canUseTool?: OfficialApprovalBridge;
+    /** The session's permission mode, for the fail-closed bridge the template installs. */
+    permissionMode?: OfficialPermissionMode;
+    /** §10's hook bridge (WS-08 owns its contract). */
+    hooks?: unknown;
+    /** §3's built child environment. Built by `buildChildEnv`, because only it has the credentials. */
+    env?: Readonly<Record<string, string>>;
+    /** The creation transaction's pre-allocated backend id (WS-16). */
+    sessionId?: string;
+    /** Resume/fork (§5.1): a fork registers as a NEW record and inherits no handoff certification. */
+    resume?: string;
+    forkSession?: boolean;
+    containment?: ContainmentPolicy;
+    /** §5.1: the ONLY documented `extraArgs` route. Anything else is refused. */
+    appendSystemPromptFile?: string;
+    /** Extra tool names this deployment denies, merged with the containment floor's own list. */
+    additionalDisallowedTools?: readonly string[];
+}
+/** Puts the containment matchers FIRST, then whatever the host installed for the same events. */
+export declare function mergeHooks(ours: Record<string, unknown[]>, hostHooks: unknown): Record<string, unknown[]>;
+/** The settings the flag layer must carry for this branch to behave (see this module's header). */
+export declare function brandedFlagSettings(args: {
+    brand: Pick<BrandProfile, "projectDirName">;
+    autoMemoryDirectory: string;
+    extra?: Readonly<Record<string, unknown>>;
+}): Record<string, unknown>;
+/**
+ * Builds §2's template.
+ *
+ * Nothing here reads ambient state: every value is either an argument, a brand derivation, or a
+ * constant this file declares. That is what makes the golden captures meaningful — two runs of the
+ * same input produce the same object, on any machine.
+ */
+export declare function buildOfficialOptions(input: OptionsTemplateInput, policy?: OptionsTemplatePolicy): OfficialOptions;
+/**
+ * §5.1's withheld options and §2's required ones, as refusals.
+ *
+ * WHY A VALIDATOR AND NOT JUST A CAREFUL BUILDER: `launch()` accepts an options object the CALLER
+ * built (the seam's `OfficialLaunchPlan.options`), so the builder's care protects only the callers who
+ * used it. These are the invariants that must hold for anything this adapter launches.
+ */
+export declare function assertOptionsInvariants(options: OfficialOptions, branchLabel: string): void;
+/**
+ * A golden-capturable view of a built options object (§15's "options-template golden captures").
+ *
+ * FUNCTIONS AND INSTANCES BECOME MARKERS, because their identity is not stable across runs and their
+ * bodies are not what the capture is about. What the capture pins is the SHAPE: which fields are set,
+ * to which literal values, with which brand-derived names — and, for the three things that are
+ * objects with behaviour, that they are present and which one they are.
+ */
+export declare function captureOptions(options: OfficialOptions): Record<string, unknown>;
+/** The canonical name an aliased built-in resolves to — re-exported so a capture reader has one import. */
+export { mcpToolName };

package/dist/official/spawn-proxy.d.ts

@@ -0,0 +1,144 @@
+import type { Readable, Writable } from "node:stream";
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { RuntimeDirectoryEntry, RuntimeDirectoryStore } from "../seams/directory-store.js";
+import type { SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+import type { OfficialLaunchProfile } from "../seams/official-adapter.js";
+import type { OfficialSpawnClaudeCodeProcess, OfficialSpawnOptions } from "../seams/official-sdk-shapes.js";
+import { type OfficialBranchError } from "./errors.js";
+import { type ObservedLocalWriteRoot } from "./spool.js";
+/** WS-14 §9: "PID **plus process start identity** (never bare PID)" — an OS recycles pids. */
+export interface ProcessIdentity {
+    pid: number;
+    /** ISO-8601. The pair is the identity; either half alone revalidates a stranger. */
+    startedAt: string;
+}
+/** What the proxy observed about one generation, and what §6 rule 2 requires to be durable. */
+export interface SpawnObservation {
+    root: ObservedLocalWriteRoot;
+    processIdentity: ProcessIdentity;
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+}
+/**
+ * Where the observation is written durably.
+ *
+ * A SEAM RATHER THAN A DIRECT STORE CALL, because the sink differs by caller: the adapter's default
+ * writes `RuntimeDirectoryEntry.configDir`/`processIdentity` through the spine's directory store
+ * (`directoryRecordSink` below), a host with its own record writes there, and a test records into an
+ * array. `clear` is §6 rule 5's other half and is optional: a sink that cannot forget is still a
+ * legal sink, it just keeps a stale root.
+ */
+export interface SpawnRecordSink {
+    record(observation: SpawnObservation): Promise<void> | void;
+    clear?(observation: SpawnObservation): Promise<void> | void;
+}
+/**
+ * §6 rule 3's collaborator: transcript-only reconciliation (or a quarantine snapshot) of the recorded
+ * root, run BEFORE the exit is forwarded.
+ *
+ * DEFAULT IS A NO-OP, deliberately. The reconciler belongs to the store lane (WS-05 §12's barrier);
+ * the proxy owns only the ORDERING, and an ordering with nothing in the middle is still the correct
+ * ordering. A no-op that runs at the right moment is honest; a proxy that refused to spawn without a
+ * reconciler would make the ordering untestable until another lane lands.
+ *
+ * "Reconciliation touches transcript/subagent files ONLY" (rule 4) — the proxy hands the reconciler
+ * the root and the exit, never the environment it was spawned with.
+ */
+export type TranscriptReconcile = (input: {
+    observation: SpawnObservation;
+    exit: {
+        code: number | null;
+        signal: string | null;
+    };
+}) => Promise<void> | void;
+/** The child process handle the proxy wraps — the members it drives, in Node's own shape. */
+export interface SpawnedChildProcess {
+    readonly pid?: number | undefined;
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    kill(signal?: string): boolean;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: "error", listener: (error: Error) => void): unknown;
+}
+/** How the proxy actually starts a process. Injected so a test never spawns a real binary. */
+export type SpawnChild = (options: OfficialSpawnOptions & {
+    argv0: string;
+}) => SpawnedChildProcess;
+/** The proxy plus the handles a launch needs to read what it observed. */
+export interface SupervisedSpawnProxy {
+    /** The hook itself, in the official runtime's own shape. */
+    readonly spawn: OfficialSpawnClaudeCodeProcess;
+    /** The observation of the most recent spawn, once it has happened. */
+    readonly observation: SpawnObservation | undefined;
+    /** Resolves when §6 rule 2's record has settled (rejects if it failed). */
+    whenRecorded(): Promise<void>;
+    /** Resolves when the exit gate has opened — reconciliation done, cleanup verified, record cleared. */
+    whenSettled(): Promise<void>;
+    /** Everything stderr produced, bounded (§6 rule 6). */
+    readonly stderrTail: string;
+}
+export interface SupervisedSpawnProxyOptions {
+    brand: Pick<BrandProfile, "processLabel" | "envPrefix">;
+    /** Which profile this generation was launched as, and what config dir it was configured with (§1). */
+    profile: OfficialLaunchProfile;
+    configuredConfigDir: string;
+    sink: SpawnRecordSink;
+    reconcile?: TranscriptReconcile;
+    spawnChild?: SpawnChild;
+    /** Verified cleanup (§6 rule 5). Default: the recorded root no longer exists on disk. */
+    verifyCleanup?: (observation: SpawnObservation) => Promise<boolean> | boolean;
+    /** Typed crash classes are handed here as they are classified (§6 rule 6, §9). */
+    onCrash?: (error: OfficialBranchError) => void;
+    /** Bound on the retained stderr (a runaway child must not turn a message into a leak). */
+    stderrTailBytes?: number;
+    /**
+     * How long §6 rule 2's record may take to settle before the generation is ended (review r1, M4).
+     *
+     * The module always handled a record that FAILS; it did not handle one that HANGS, and a hanging
+     * sink left the child alive, silent and unobservable forever — no bytes, no exit, no error. Every
+     * wait in a supervisor is bounded or it is a hang with better manners.
+     */
+    recordTimeoutMs?: number;
+    /**
+     * How long after the child's exit the gate waits for stdout to close (review r1, M4).
+     *
+     * The gate needs BOTH the exit and the stdout end, because a transcript's last frames arrive on the
+     * way out. A child that exits with its pipe held open (a surviving grandchild inherits it) would
+     * otherwise stall the gate forever: reconciliation never running, `whenSettled()` never resolving.
+     * After this grace the exit is forwarded anyway and the `stdout-unterminated` crash class says so.
+     */
+    stdoutGraceMs?: number;
+    now?: () => Date;
+}
+/**
+ * Kept as a no-op-safe warm-up so an existing caller keeps working; nothing REQUIRES it any more.
+ *
+ * A host that wants the resolution cost paid at construction rather than at the first spawn can still
+ * call it, and the adapter does.
+ */
+export declare function prepareDefaultSpawn(): Promise<void>;
+/**
+ * Builds the supervised proxy (§6). One proxy per GENERATION: it holds that generation's observation,
+ * its stderr tail and its exit gate, and none of those are meaningful across two children.
+ */
+export declare function createSupervisedSpawnProxy(options: SupervisedSpawnProxyOptions): SupervisedSpawnProxy;
+/**
+ * The default sink: §6 rule 2's record written onto the directory entry the spine defined for it.
+ *
+ * `RuntimeDirectoryEntry.configDir` and `.processIdentity` exist precisely for this (spine fix round
+ * 2, NEW-1: "WRITTEN BY Lane A's spawn proxy before it returns the process; READ BY Lane B's
+ * `recover()`"), and rule 5's clear is an upsert WITHOUT the two keys — the spine's in-memory store
+ * treats an absent key as absent rather than as `undefined`, which is what makes "cleared" a state a
+ * reader can see.
+ *
+ * A MISSING ENTRY IS AN ERROR, not a silent no-op: the address is handed in by the launch, so an
+ * entry that is not there means the caller recorded the session under a different address and the
+ * root would be written nowhere.
+ */
+export declare function directoryRecordSink(args: {
+    store: RuntimeDirectoryStore;
+    address: SerializedRuntimeAddress;
+    seed?: () => RuntimeDirectoryEntry;
+}): SpawnRecordSink;

package/dist/official/spool.d.ts

@@ -0,0 +1,80 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { OfficialLaunchProfile } from "../seams/official-adapter.js";
+/**
+ * The spool's path segments under the brand home.
+ *
+ * BRAND-NEUTRAL BY CONSTRUCTION: the product-owned part of the spool path is the HOME DIRECTORY
+ * itself, which the caller passes in already resolved from `brand.homeDirName` (review r1, n4: the
+ * previous sentence spelled one product's home in prose, and the brand gate's own header says a raw
+ * occurrence includes comments even where its regex cannot see one).
+ * These two segments name a ROLE ("the runtimes we host", "the spool the official agent lives in"),
+ * so a reuser inherits them unchanged and the brand gate has nothing to match.
+ */
+export declare const SPOOL_SEGMENTS: readonly ["runtimes", "official-agent-spool"];
+/** WS-16's `activeLocalWriteRoot` kinds — one per launch profile. */
+export type LocalWriteRootKind = "official-spool" | "sdk-resume-staging";
+/**
+ * The durable record §6 rule 2 demands: WHICH root this generation actually got, and of which kind.
+ *
+ * The pair travels together because neither half is derivable from the other at the point it matters:
+ * a reconciler holding only a path cannot tell a spool from a staging root it must not delete, and a
+ * reconciler holding only a kind has nothing to open.
+ */
+export interface ObservedLocalWriteRoot {
+    configDir: string;
+    kind: LocalWriteRootKind;
+    profile: OfficialLaunchProfile;
+}
+/** `<home>/runtimes/official-agent-spool` — profile 1's configured value (§1, §3). */
+export declare function officialSpoolRoot(home: string): string;
+/**
+ * Classifies an OBSERVED `CLAUDE_CONFIG_DIR`.
+ *
+ * The classification is by SHAPE, not by which profile we asked for, because the whole point of §1's
+ * authority rule is that the two can disagree: a session configured `fresh-spool` that resumes out of
+ * the store is handed a staging root by the wrapper, and the record has to say `sdk-resume-staging`
+ * or the reconciler will look in the wrong place after a crash.
+ */
+export declare function classifyLocalWriteRoot(configDir: string): ObservedLocalWriteRoot;
+/**
+ * §6 rule 2's "VALIDATE and durably record": the checks that run before the record is written.
+ *
+ * Two refusals, and each is a real failure mode rather than defensive noise:
+ *
+ *   * AN ABSENT VALUE means the child is about to write its transcript somewhere we did not choose
+ *     and cannot name — under the SDK parent's own `CLAUDE_CONFIG_DIR`, or `~/.claude` when there is
+ *     none. That is the exact leak §3 forbids ("any variable pointing into `~/.claude`" must not
+ *     appear) and it is unrecoverable after the fact, so it fails the spawn.
+ *   * A `fresh-spool` GENERATION THAT DID NOT GET THE SPOOL is either a wrapper we do not understand
+ *     or an env allowlist that was overwritten downstream. Both mean the recorded root and the real
+ *     one have diverged, which is the corruption §1 says breaks crash recovery.
+ *
+ * A `store-backed-resume` generation is deliberately NOT required to match anything: the staging root
+ * is the wrapper's own uuid and we could not have predicted it. It only has to LOOK like one.
+ */
+export declare function validateObservedConfigDir(args: {
+    observed: string | undefined;
+    configured: string;
+    profile: OfficialLaunchProfile;
+    brand: Pick<BrandProfile, "processLabel">;
+}): ObservedLocalWriteRoot;
+/**
+ * WS-14 §3's `CLAUDE_CODE_TMPDIR` and what the engine does with it — reported HONESTLY (WS-17 row 15).
+ *
+ * "Engine appends its literal `claude-<uid>`" — so a host that reports only the configured value is
+ * telling a user the wrong directory. Both are returned, plus the reason the second one cannot be
+ * moved, so a capability matrix can print the truth without re-deriving it.
+ */
+export interface VendorTempRootReport {
+    /** What we set: the shared per-user temp root, derived by the host from `brand.tempRootName`. */
+    configured: string;
+    /** Where the engine actually writes: the configured root plus its own fixed segment. */
+    engineComputed: string;
+    /** The vendor literal in that path. */
+    vendorSegment: string;
+    note: string;
+}
+export declare function vendorTempRootReport(args: {
+    sharedTempRoot: string;
+    uid: number | string;
+}): VendorTempRootReport;

package/dist/official/supervision.d.ts

@@ -0,0 +1,49 @@
+import type { OfficialCrashClass } from "./errors.js";
+import { OfficialInterruptedError } from "./errors.js";
+import type { ProcessIdentity } from "./spawn-proxy.js";
+/**
+ * §9's per-session quotas.
+ *
+ * ANTHROPIC'S OWN PLANNING FIGURES, carried as initial defaults and labelled as what they are: "these
+ * are capacity-planning numbers, NOT guarantees; Winter's enforced per-session quotas need product
+ * tuning before release" (§16 open question 3). They ship as data so a host can read and override
+ * them; nothing in this package enforces them, because enforcement is the daemon's (Phase 8).
+ */
+export declare const DEFAULT_SESSION_QUOTAS: {
+    readonly memoryBytes: number;
+    readonly diskBytes: number;
+    readonly cpus: 1;
+    readonly provenance: "Anthropic's published capacity-planning figures, adopted as initial defaults; not guarantees and not yet product-tuned (WS-14 §9/§16)";
+};
+/**
+ * Does a live process still belong to the identity we recorded?
+ *
+ * BOTH HALVES MUST MATCH. A pid alone revalidates a recycled stranger; a start time alone matches
+ * nothing at all. Anything absent is "not revalidated" rather than "assume yes" — an unrevalidated
+ * handle is marked unavailable by the directory's own recovery (WS-15 §6.4 step 2), which is a
+ * recoverable state, while a wrongly-revalidated one silently steers a stranger's process.
+ */
+export declare function revalidateProcessIdentity(recorded: ProcessIdentity | undefined, observed: ProcessIdentity | undefined): boolean;
+/** §9's host gestures. */
+export type CancellationGesture = "stop-turn" | "stop-background-task" | "end-session" | "kill-process";
+/** What a gesture maps onto, as data — so a host renders §9's table rather than re-deriving it. */
+export interface CancellationMapping {
+    gesture: CancellationGesture;
+    operation: string;
+    effect: string;
+    /** True when this gesture must not run before the §6 reconciliation barrier has completed. */
+    afterReconciliationBarrier: boolean;
+}
+export declare const CANCELLATION_MAPPINGS: readonly CancellationMapping[];
+export declare function cancellationMappingFor(gesture: CancellationGesture): CancellationMapping;
+/** The typed error a gesture produces when it ends a generation (§13's interrupt/cancellation class). */
+export declare function interruptionFor(gesture: CancellationGesture, branchLabel: string): OfficialInterruptedError;
+/**
+ * §9's distinction, as a predicate: is this a PROCESS failure or a TURN failure?
+ *
+ * The projector branches on it, and the two must never collapse: a turn that ended `is_error: true`
+ * leaves a healthy child that can take the next message, while a crash class means there is nothing
+ * left to send to.
+ */
+export declare function crashClassOf(error: unknown): OfficialCrashClass | undefined;
+export declare function isProcessCrash(error: unknown): boolean;

package/dist/official/sweep.d.ts

@@ -0,0 +1,65 @@
+import { OfficialContainmentBreachError } from "./errors.js";
+/**
+ * Tools whose effect is a filesystem write, and therefore worth a snapshot pair.
+ *
+ * `WebFetch` is here for a reason that is not a file write (review r3, NEW-11): a saved WebFetch
+ * approval is §8's one writer with no tool call of its own, and its durable rule update lands in the
+ * vendor's own settings file. Watching the call it rides on is the only post-hoc cover it can have.
+ */
+export declare const SWEPT_TOOLS: readonly string[];
+/**
+ * THE HOOK EVENTS A TOOL'S FILESYSTEM EFFECT CAN BE FOLLOWED BY (review r3, NEW-9).
+ *
+ * Enumerated from the pinned union rather than guessed: `HOOK_EVENTS` in the 0.3.250 declarations
+ * carries `PostToolUse`, `PostToolUseFailure` and `PostToolBatch` as the three events that follow a
+ * tool call, and the sweep registered only the first. MEASURED: a command with a side effect and a
+ * nonzero exit (`mkdir …; exit 1`) fires `PostToolUseFailure` and NO `PostToolUse`, so the baseline
+ * taken in `pre` was never consumed, the artifact survived the session, and `existsSync(<cwd>/.claude)`
+ * — row 14's own predicate — was true with both containment layers installed.
+ *
+ * `PostToolBatch` carries `tool_calls[]` rather than one `tool_use_id`, so the handler reads both
+ * shapes.
+ */
+export declare const POST_TOOL_EVENTS: readonly string[];
+/** One breach: what appeared, from which call, and whether the sweep managed to remove it. */
+export interface ContainmentBreach {
+    toolName: string;
+    toolUseId: string;
+    /** The paths this call created that carry a forbidden name. */
+    created: readonly string[];
+    /** The subset the sweep removed. Anything else is named in `retained`. */
+    removed: readonly string[];
+    retained: readonly string[];
+    at: string;
+}
+/** Every forbidden-named path under `root`, folded-compared, bounded. */
+export declare function forbiddenArtifactsUnder(root: string, depth?: number, maxDepth?: number): string[];
+export interface ContainmentSweepOptions {
+    /** The session's working directory. */
+    cwd: string;
+    /** WS-14 §14's diagnostics label, so a breach error reads like every other error in the package. */
+    branchLabel?: string;
+    /** How deep below each root the walk goes. Default 6; see `MAX_DEPTH`'s own note. */
+    maxDepth?: number;
+    /** The session's home, so `~/.claude/plans` is covered as well as the project (WS-17 row 14). */
+    home?: string;
+    /** Where a breach is reported. The adapter forwards it to the host and keeps it on the session. */
+    onBreach?: (breach: ContainmentBreach, error: OfficialContainmentBreachError) => void;
+    now?: () => Date;
+}
+export interface ContainmentSweep {
+    /** The hook matchers to merge into `Options.hooks` — one PreToolUse, one PostToolUse. */
+    hooks: Record<string, Array<{
+        hooks: Array<(input: unknown) => Promise<unknown>>;
+    }>>;
+    /** Every breach this session has seen, in order. */
+    readonly breaches: readonly ContainmentBreach[];
+}
+/** Builds the sweep's two hooks. One sweep per SESSION: the snapshots are keyed by tool-use id. */
+export declare function createContainmentSweep(options: ContainmentSweepOptions): ContainmentSweep;
+/** The three names the sweep looks for, restated for a caller that wants to report them. */
+export declare const SWEPT_TARGETS: {
+    readonly instructionsFile: "CLAUDE.md";
+    readonly projectDir: ".claude";
+    readonly userPlansDir: ".claude/plans";
+};