@celestea/studio 2.7.1

package/dist/runtime/engine-profile.js

@@ -0,0 +1,88 @@
+/**
+ * `EngineProfile` (the HTTP-facing host view) <-> `Profile` (the runtime's
+ * frozen 12-key compose config).
+ *
+ * The two shapes differ on purpose: the host view uses the contract names of
+ * `GET /api/config` (`context_window`, no key source), while the engine profile
+ * carries the key RESOLUTION (env var name + optional file) and the request
+ * format. This module is the only translation point, so a new profile key can
+ * never be added on one side only.
+ */
+import { defaultAgentConfig } from "@celestea/core";
+import { CONTEXT_WINDOW, MIN_STEPS } from "../config.js";
+/** The only request format the TS engine composes today (OpenAI-compatible). */
+export const ENGINE_REQUEST_FORMAT = "chat_completions";
+/** Host view of a composed profile. */
+export function engineProfileOf(profile) {
+    return {
+        model: profile.model,
+        base_url: profile.base_url,
+        reasoning_effort: profile.reasoning_effort,
+        max_steps: profile.max_steps,
+        max_parallel_tool_calls: profile.max_parallel_tool_calls,
+        max_output_tokens: profile.max_output_tokens,
+        context_window: profile.context_window_tokens,
+        api_key_env: profile.api_key_env,
+        system_prompt: profile.system_prompt,
+    };
+}
+/** Compose profile from the host view (extra keys inherit from `base`). */
+export function profileFromEngine(engine, base) {
+    return {
+        model: engine.model,
+        base_url: engine.base_url,
+        api_key_env: engine.api_key_env,
+        api_key_file: base?.api_key_file ?? null,
+        max_steps: engine.max_steps,
+        max_parallel_tool_calls: engine.max_parallel_tool_calls,
+        reasoning_effort: engine.reasoning_effort,
+        max_output_tokens: engine.max_output_tokens,
+        context_window_tokens: engine.context_window,
+        system_prompt: engine.system_prompt,
+        request_format: base?.request_format ?? ENGINE_REQUEST_FORMAT,
+        temperature: base?.temperature ?? null,
+    };
+}
+/** Apply an accepted `POST /api/config` patch (the host already validated it). */
+export function applyProfilePatch(profile, patch) {
+    const next = { ...profile };
+    if (patch.model !== undefined)
+        next.model = patch.model;
+    if (patch.reasoning_effort !== undefined)
+        next.reasoning_effort = patch.reasoning_effort;
+    if (patch.base_url !== undefined)
+        next.base_url = patch.base_url;
+    if (patch.max_steps !== undefined)
+        next.max_steps = Math.max(MIN_STEPS, Math.trunc(patch.max_steps));
+    if (patch.max_output_tokens !== undefined) {
+        next.max_output_tokens = patch.max_output_tokens === null ? null : Math.trunc(patch.max_output_tokens);
+    }
+    if (patch.context_window !== undefined)
+        next.context_window_tokens = Math.trunc(patch.context_window);
+    if (patch.system_prompt !== undefined)
+        next.system_prompt = patch.system_prompt;
+    return next;
+}
+/**
+ * The startup profile: the host's frozen constants (`MIN_STEPS`,
+ * `CONTEXT_WINDOW`, both read off the frozen `/api/config` snapshot) plus the env
+ * overrides the host honors. The loop budget derives from this profile
+ * (`agentConfigFromProfile`), so the statusline window and the trim budget can
+ * never disagree.
+ */
+export function defaultEngineProfile(env, apiKeyEnv) {
+    const base = defaultAgentConfig();
+    const maxSteps = env["CELESTEA_MAX_STEPS"];
+    const contextWindow = env["CELESTEA_CONTEXT_WINDOW"];
+    return {
+        model: env["CELESTEA_MODEL"] ?? "unknown",
+        base_url: env["CELESTEA_BASE_URL"] ?? "http://127.0.0.1:3001/v1",
+        reasoning_effort: env["CELESTEA_REASONING_EFFORT"] ?? null,
+        max_steps: maxSteps === undefined ? MIN_STEPS : Math.max(MIN_STEPS, Number(maxSteps) || MIN_STEPS),
+        max_parallel_tool_calls: base.max_parallel_tool_calls,
+        max_output_tokens: null,
+        context_window: contextWindow === undefined ? CONTEXT_WINDOW : Number(contextWindow) || CONTEXT_WINDOW,
+        api_key_env: apiKeyEnv,
+        system_prompt: base.system_prompt,
+    };
+}

package/dist/runtime/engine-session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * W747 compat shim — this module moved to the runtime's host layer:
+ * `packages/runtime/src/host/engine-session.ts` (exported as `@celestea/runtime`).
+ *
+ * The file is kept (and its export list is unchanged) so every existing
+ * `./engine-session.js` / `../runtime/engine-session.js` import keeps working:
+ * a caller migrates by deleting its import, not by editing the engine.
+ */
+export { PROCESS_CHECKPOINT_IDENTITY, SESSION_LOG_ID, SESSION_LOG_NAME, bindingFor, closeLog, memoryBindingFor, openSessionLog, workerSessionPrefix, type CheckpointWiring, type SessionTarget, } from "@celestea/runtime";

package/dist/runtime/engine-session.js

@@ -0,0 +1,9 @@
+/**
+ * W747 compat shim — this module moved to the runtime's host layer:
+ * `packages/runtime/src/host/engine-session.ts` (exported as `@celestea/runtime`).
+ *
+ * The file is kept (and its export list is unchanged) so every existing
+ * `./engine-session.js` / `../runtime/engine-session.js` import keeps working:
+ * a caller migrates by deleting its import, not by editing the engine.
+ */
+export { PROCESS_CHECKPOINT_IDENTITY, SESSION_LOG_ID, SESSION_LOG_NAME, bindingFor, closeLog, memoryBindingFor, openSessionLog, workerSessionPrefix, } from "@celestea/runtime";

package/dist/runtime/fallback-contract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The two fallback VIEWS the host layer promises (E §4.2.3 #2/#4, W785).
+ *
+ * They live in their own leaf module on purpose: `runtime-adapter.ts` (the seam)
+ * must be able to name them, and importing them from `fallback-host.ts` closed a
+ * cycle (`runtime-adapter -> fallback-host -> llm-assembly -> runtime-adapter`,
+ * caught by `no-circular`). A leaf with no imports of its own keeps the seam a
+ * leaf too.
+ */
+/** The `status` frame the host publishes when a hand-over happens (§4.2.3 #2). */
+export interface FallbackFrame {
+    phase: "fallback";
+    from: string | null;
+    to: string;
+    reason: string;
+    attempt: number;
+    effective_model: string;
+}
+/** The `fallback` block of `/api/status` (§4.2.3 #4). */
+export interface FallbackStatusView {
+    active: boolean;
+    chain: string[];
+    effective_model: string | null;
+    last_reason: string | null;
+    targets: Array<{
+        name: string;
+        model: string;
+        available: boolean;
+        cooling: boolean;
+    }>;
+    problems: string[];
+}

package/dist/runtime/fallback-contract.js

@@ -0,0 +1,10 @@
+/**
+ * The two fallback VIEWS the host layer promises (E §4.2.3 #2/#4, W785).
+ *
+ * They live in their own leaf module on purpose: `runtime-adapter.ts` (the seam)
+ * must be able to name them, and importing them from `fallback-host.ts` closed a
+ * cycle (`runtime-adapter -> fallback-host -> llm-assembly -> runtime-adapter`,
+ * caught by `no-circular`). A leaf with no imports of its own keeps the seam a
+ * leaf too.
+ */
+export {};

package/dist/runtime/fallback-host.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Fallback wiring of the studio host (iteration E §4.2.3, P1) — the visibility
+ * half of the `Llm` decorator.
+ *
+ * `packages/llm` owns the RULES (trigger table, produced lock, cooldown); this
+ * module owns everything the rules cannot know: which targets exist in THIS
+ * deployment (sidecar config + the composed profile), their credentials (env var
+ * NAMES only, U7 inventory), and the three places a hand-over must be visible
+ * (§4.2.3, "三者缺一视为未实现"):
+ *
+ *   1. local append-only `fallbacks-audit.jsonl` (authoritative) + best-effort
+ *      platform `POST /api/audit` when `CELESTEA_AUDIT_URL` is set;
+ *   2. one SSE `status` frame with `phase:"fallback"` — the event NAME is frozen
+ *      (K5), only payload fields are added;
+ *   3. the `/api/status` view (`effective_model` + `fallback.{active,chain,
+ *      last_reason,targets,problems}`), with `model` keeping its old meaning.
+ *
+ * The switch is OFF by default: when `CELESTEA_LLM_FALLBACK` is not on, `wrap()`
+ * returns null and the caller keeps the pre-P1 path byte-for-byte (D9). Nothing
+ * here reads a credential VALUE, and no target's key ever leaves its env var.
+ */
+import { type FallbackStepSink, type LlmTarget } from "@celestea/llm";
+import type { Llm, Statusline } from "@celestea/core";
+import type { StudioBus } from "../sse.js";
+import type { Profile } from "@celestea/runtime";
+import type { FallbackFrame, FallbackStatusView } from "./fallback-contract.js";
+/** `<data dir>/fallbacks-audit.jsonl` (§4.2.3 #3, same discipline as grants). */
+export declare const FALLBACKS_AUDIT_FILE = "fallbacks-audit.jsonl";
+/** Rotate at 16 MiB, keeping the previous chain (LTS ops audit rules). */
+export declare const FALLBACKS_AUDIT_MAX_BYTES: number;
+export declare const ENV_AUDIT_URL = "CELESTEA_AUDIT_URL";
+export declare const ENV_CENTER_TOKEN = "CELESTEA_CENTER_TOKEN";
+/** One audit line: target NAMES and reasons only, never a key or a prompt. */
+export interface FallbackAuditEvent {
+    ts: number;
+    event: "fallback" | "target_unavailable" | "platform_audit_failed";
+    session: string | null;
+    /** The five hand-over fields exist on `fallback` lines; they are absent on
+     * operational lines (`target_unavailable`, `platform_audit_failed`). */
+    from?: string | null;
+    to?: string | null;
+    reason?: string | null;
+    attempt?: number | null;
+    model?: string | null;
+    detail?: string;
+}
+export type { FallbackFrame, FallbackStatusView } from "./fallback-contract.js";
+export interface FallbackWrapInput {
+    /** The composed engine seam (used verbatim while the capability is off). */
+    inner: Llm;
+    profile: Profile;
+    sessionId: string | null;
+    /** Per-attempt ledger booking (the ledger makes N attempts visible, D6). */
+    steps: FallbackStepSink | null;
+    /** `providers.json` row id for the ledger's `provider` column. */
+    provider: string | null;
+}
+/**
+ * The `status` payload of one hand-over (§4.2.3 #2). The event NAME is frozen
+ * (K5); these five keys are the ones declared in
+ * `contracts/sse-events.json#payloadExtensions.status`, and they live HERE so the
+ * emitted key set and the contract declaration cannot drift apart.
+ */
+export declare function fallbackFramePayload(frame: FallbackFrame, statusline: unknown): Record<string, unknown>;
+/** `/api/status.fallback` of one session (null = the capability is off). */
+export declare function fallbackViewOf(wiring: FallbackWiring, sessionId: string | null): FallbackStatusView | null;
+/**
+ * The adapter-facing glue of the capability: the process-wide wiring plus the two
+ * host effects a hand-over has (the SSE frame and the `/api/status` view). It
+ * lives here, not in `real-runtime-adapter.ts`, for the same reason
+ * `ledger-view.ts` does — the adapter stays a thin seam inside the §4.1 budget.
+ */
+export declare class AdapterFallback {
+    private readonly deps;
+    /** Handed to `SessionComposer`; `wrap()` answers null while the switch is off. */
+    readonly wiring: FallbackWiring;
+    constructor(deps: {
+        dataDir?: string | null;
+        /** Falls back to the ledger's own directory: both files are process-level. */
+        ledgerFile?: {
+            path: string;
+        } | null;
+        env: NodeJS.ProcessEnv;
+        now?: () => number;
+        bus: () => StudioBus | null;
+        peek: (sessionId: string | null) => {
+            turnNo: number;
+            runtime: {
+                statusline(): Statusline;
+            };
+        } | null;
+    });
+    /** `/api/status.fallback` of one session (null = the capability is off). */
+    view(sessionId: string | null): FallbackStatusView | null;
+    /** One `status` frame per hand-over (frozen event name, declared payload). */
+    emit(sessionId: string | null, frame: FallbackFrame): void;
+    /** Await in-flight platform deliveries (tests / shutdown). */
+    flush(): Promise<void>;
+    /** In-flight platform deliveries (diagnostics; bounded by construction). */
+    pendingCount(): number;
+}
+export interface FallbackWiring {
+    /** True only when the switch is on AND a chain could be assembled. */
+    readonly enabled: boolean;
+    /** The decorated seam, or null = "fallback off, use your normal path". */
+    wrap(input: FallbackWrapInput): Llm | null;
+    /** The `/api/status` half for one session. */
+    view(sessionId: string | null): FallbackStatusView;
+    /** Await in-flight platform deliveries (tests / shutdown). */
+    flush(): Promise<void>;
+    /** In-flight platform deliveries (bounded: a delivered event leaves). */
+    pendingCount(): number;
+}
+export interface FallbackHostOptions {
+    /** `<data dir>`: `fallbacks.json` and `fallbacks-audit.jsonl` live here. */
+    dataDir?: string | null;
+    env?: NodeJS.ProcessEnv;
+    /** Bus sink: one `status` frame per hand-over. */
+    emit?: (sessionId: string | null, frame: FallbackFrame) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Injectable per-target client builder (tests): the production default builds
+     * a live provider client from the composed profile (`liveEngineLlmFor`), and a
+     * test can hand in a scripted seam without touching the network.
+     */
+    clientFor?: (target: LlmTarget, profile: Profile) => Llm;
+    /** Injectable platform transport (tests); default `fetch`. */
+    post?: (url: string, body: string, headers: Record<string, string>) => Promise<{
+        ok: boolean;
+        status: number;
+    }>;
+}
+export declare function createFallbackWiring(opts?: FallbackHostOptions): FallbackWiring;

package/dist/runtime/fallback-host.js

@@ -0,0 +1,299 @@
+/**
+ * Fallback wiring of the studio host (iteration E §4.2.3, P1) — the visibility
+ * half of the `Llm` decorator.
+ *
+ * `packages/llm` owns the RULES (trigger table, produced lock, cooldown); this
+ * module owns everything the rules cannot know: which targets exist in THIS
+ * deployment (sidecar config + the composed profile), their credentials (env var
+ * NAMES only, U7 inventory), and the three places a hand-over must be visible
+ * (§4.2.3, "三者缺一视为未实现"):
+ *
+ *   1. local append-only `fallbacks-audit.jsonl` (authoritative) + best-effort
+ *      platform `POST /api/audit` when `CELESTEA_AUDIT_URL` is set;
+ *   2. one SSE `status` frame with `phase:"fallback"` — the event NAME is frozen
+ *      (K5), only payload fields are added;
+ *   3. the `/api/status` view (`effective_model` + `fallback.{active,chain,
+ *      last_reason,targets,problems}`), with `model` keeping its old meaning.
+ *
+ * The switch is OFF by default: when `CELESTEA_LLM_FALLBACK` is not on, `wrap()`
+ * returns null and the caller keeps the pre-P1 path byte-for-byte (D9). Nothing
+ * here reads a credential VALUE, and no target's key ever leaves its env var.
+ */
+import { appendFileSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configProblems, createFallbackLlm, FallbackState, loadFallbackConfig, } from "@celestea/llm";
+import { bridgeProviderLlm, liveEngineLlmFor } from "./llm-assembly.js";
+/** `<data dir>/fallbacks-audit.jsonl` (§4.2.3 #3, same discipline as grants). */
+export const FALLBACKS_AUDIT_FILE = "fallbacks-audit.jsonl";
+/** Rotate at 16 MiB, keeping the previous chain (LTS ops audit rules). */
+export const FALLBACKS_AUDIT_MAX_BYTES = 16 * 1024 * 1024;
+export const ENV_AUDIT_URL = "CELESTEA_AUDIT_URL";
+export const ENV_CENTER_TOKEN = "CELESTEA_CENTER_TOKEN";
+/**
+ * The `status` payload of one hand-over (§4.2.3 #2). The event NAME is frozen
+ * (K5); these five keys are the ones declared in
+ * `contracts/sse-events.json#payloadExtensions.status`, and they live HERE so the
+ * emitted key set and the contract declaration cannot drift apart.
+ */
+export function fallbackFramePayload(frame, statusline) {
+    return {
+        phase: frame.phase,
+        statusline,
+        effective_model: frame.effective_model,
+        from: frame.from,
+        to: frame.to,
+        reason: frame.reason,
+        attempt: frame.attempt,
+    };
+}
+/** `/api/status.fallback` of one session (null = the capability is off). */
+export function fallbackViewOf(wiring, sessionId) {
+    return wiring.enabled ? wiring.view(sessionId) : null;
+}
+/**
+ * The adapter-facing glue of the capability: the process-wide wiring plus the two
+ * host effects a hand-over has (the SSE frame and the `/api/status` view). It
+ * lives here, not in `real-runtime-adapter.ts`, for the same reason
+ * `ledger-view.ts` does — the adapter stays a thin seam inside the §4.1 budget.
+ */
+export class AdapterFallback {
+    deps;
+    /** Handed to `SessionComposer`; `wrap()` answers null while the switch is off. */
+    wiring;
+    constructor(deps) {
+        this.deps = deps;
+        this.wiring = createFallbackWiring({
+            dataDir: deps.dataDir ?? (deps.ledgerFile == null ? null : dirname(deps.ledgerFile.path)),
+            env: deps.env,
+            emit: (sessionId, frame) => this.emit(sessionId, frame),
+            ...(deps.now === undefined ? {} : { now: deps.now }),
+        });
+    }
+    /** `/api/status.fallback` of one session (null = the capability is off). */
+    view(sessionId) {
+        return fallbackViewOf(this.wiring, sessionId);
+    }
+    /** One `status` frame per hand-over (frozen event name, declared payload). */
+    emit(sessionId, frame) {
+        const entry = this.deps.peek(sessionId);
+        this.deps.bus()?.emit("status", entry?.turnNo ?? 0, fallbackFramePayload(frame, entry?.runtime.statusline() ?? {}), sessionId);
+    }
+    /** Await in-flight platform deliveries (tests / shutdown). */
+    flush() {
+        return this.wiring.flush();
+    }
+    /** In-flight platform deliveries (diagnostics; bounded by construction). */
+    pendingCount() {
+        return this.wiring.pendingCount();
+    }
+}
+/** What `/api/status` reports while the capability is off (never null there). */
+const DISABLED_VIEW = {
+    active: false,
+    chain: [],
+    effective_model: null,
+    last_reason: null,
+    targets: [],
+    problems: [],
+};
+export function createFallbackWiring(opts = {}) {
+    const env = opts.env ?? process.env;
+    const config = loadFallbackConfig({ dataDir: opts.dataDir ?? null, env });
+    const audit = new FallbackAudit(opts);
+    // OFF (or nothing configured) is the default: no chain, no state, no file.
+    if (config === null || !config.enabled)
+        return disabledWiring(config, audit);
+    const problems = configProblems(config, env);
+    const state = new FallbackState();
+    const sessions = new Map();
+    const now = opts.now ?? Date.now;
+    for (const problem of problems)
+        audit.write({ event: "target_unavailable", session: null, detail: problem });
+    const deps = { opts, env, state, sessions, audit, now, problems, config };
+    return {
+        enabled: true,
+        wrap: (input) => armedLlm(deps, input),
+        view: (sessionId) => statusView(deps, sessionId),
+        flush: () => audit.flush(),
+        pendingCount: () => audit.pendingCount(),
+    };
+}
+/** The OFF wiring: `wrap` hands the caller nothing, so the path cannot change. */
+function disabledWiring(config, audit) {
+    if (config !== null && !config.enabled) {
+        audit.write({ event: "target_unavailable", session: null, detail: "config declares enabled:false" });
+    }
+    return {
+        enabled: false,
+        wrap: () => null,
+        view: () => DISABLED_VIEW,
+        flush: () => audit.flush(),
+        pendingCount: () => audit.pendingCount(),
+    };
+}
+/** The chain: the configured targets, or the composed profile as its own target. */
+function chainOf(deps, profile) {
+    const configured = deps.config.targets;
+    if (configured.length > 0)
+        return configured;
+    return [
+        {
+            name: "primary",
+            provider: "profile",
+            model: profile.model,
+            baseUrl: profile.base_url,
+            apiKeyEnv: profile.api_key_env,
+        },
+    ];
+}
+function armedLlm(deps, input) {
+    const targets = chainOf(deps, input.profile);
+    // The decorator lives on the PROVIDER seam (it must see a provider's
+    // `failed{kindOf:"timeout"}`); the engine consumes core's seam. The input
+    // clients are already core-shaped (only the documented `kindOf` widening is
+    // lost, and `liveEngineLlmFor` never produces "timeout" — it reports a torn
+    // stream instead), so the cast is a type-level bridge only; the OUTPUT is
+    // bridged for real by [bridgeProviderLlm].
+    const decorated = createFallbackLlm({
+        targets,
+        state: deps.state,
+        policy: deps.config.policy,
+        clientFor: (target) => asProviderSeam(deps.opts.clientFor?.(target, input.profile) ?? liveEngineLlmFor(input.profile, target, deps.env)),
+        steps: input.steps,
+        ...(deps.opts.now === undefined ? {} : { now: deps.opts.now }),
+        ...(deps.opts.sleep === undefined ? {} : { sleep: deps.opts.sleep }),
+        onAttempt: (info) => report(deps, input.sessionId, info),
+    });
+    return bridgeProviderLlm(decorated);
+}
+/** Type-level only (see [armedLlm]): the two seams differ in one union member. */
+function asProviderSeam(llm) {
+    return llm;
+}
+/** §4.2.3: one hand-over reaches the bus AND the audit channel, never just one. */
+function report(deps, sessionId, info) {
+    deps.sessions.set(sessionKey(sessionId), { model: info.model, name: info.target, reason: info.reason });
+    deps.opts.emit?.(sessionId, {
+        phase: "fallback",
+        from: info.from,
+        to: info.target,
+        reason: info.reason,
+        attempt: info.attempt,
+        effective_model: info.model,
+    });
+    deps.audit.write({
+        event: "fallback",
+        session: sessionId,
+        from: info.from,
+        to: info.target,
+        reason: info.reason,
+        attempt: info.attempt,
+        model: info.model,
+    });
+}
+/** `/api/status.fallback`: the chain, what is really serving, and what is wrong. */
+function statusView(deps, sessionId) {
+    const known = deps.sessions.get(sessionKey(sessionId));
+    const now = deps.now();
+    return {
+        active: true,
+        chain: deps.config.targets.map((t) => t.name),
+        effective_model: known?.model ?? null,
+        last_reason: known?.reason ?? null,
+        targets: deps.config.targets.map((t) => {
+            const envName = t.apiKeyEnv ?? null;
+            return {
+                name: t.name,
+                model: t.model,
+                available: envName === null || (deps.env[envName] ?? "") !== "",
+                cooling: deps.state.isCooling(t.name, now),
+            };
+        }),
+        problems: deps.problems,
+    };
+}
+function sessionKey(sessionId) {
+    return sessionId ?? "(default)";
+}
+/** Local append-only channel (authoritative) + best-effort platform delivery. */
+class FallbackAudit {
+    path;
+    env;
+    now;
+    post;
+    pending = [];
+    constructor(opts) {
+        this.path = opts.dataDir === null || opts.dataDir === undefined ? null : join(opts.dataDir, FALLBACKS_AUDIT_FILE);
+        this.env = opts.env ?? process.env;
+        this.now = opts.now ?? Date.now;
+        this.post = opts.post ?? httpPost;
+    }
+    write(event) {
+        const line = { ts: event.ts ?? Math.floor(this.now() / 1000), ...event };
+        if (this.path !== null)
+            appendRotating(this.path, line);
+        // W833 (R3 B8 / W816 F4): a delivered line LEAVES the ledger, so the array
+        // is bounded by the number of in-flight deliveries — it used to grow with
+        // every event the process ever produced.
+        const task = this.deliver(line);
+        this.pending.push(task);
+        void task
+            .finally(() => {
+            const at = this.pending.indexOf(task);
+            if (at >= 0)
+                this.pending.splice(at, 1);
+        })
+            .catch(() => undefined);
+    }
+    /** In-flight platform deliveries (diagnostics / bound assertion). */
+    pendingCount() {
+        return this.pending.length;
+    }
+    async flush() {
+        // Await everything in flight; completed deliveries have already removed
+        // themselves, and nothing new is written during shutdown.
+        while (this.pending.length > 0)
+            await Promise.all([...this.pending]);
+    }
+    /** Unset `CELESTEA_AUDIT_URL` = local channel only; a failed one is recorded. */
+    async deliver(line) {
+        const url = this.env[ENV_AUDIT_URL];
+        if (url === undefined || url.trim() === "")
+            return;
+        const token = this.env[ENV_CENTER_TOKEN];
+        const body = JSON.stringify({
+            category: "audit",
+            summary: `llm fallback ${line.from ?? "-"} -> ${line.to ?? "-"} (${line.reason ?? "-"})`,
+            detail: JSON.stringify(line).slice(0, 8192),
+        });
+        const headers = { "content-type": "application/json" };
+        if (token !== undefined && token !== "")
+            headers["x-center-token"] = token;
+        try {
+            const res = await this.post(url, body, headers);
+            if (!res.ok && this.path !== null)
+                appendRotating(this.path, { ...line, ts: line.ts, event: "platform_audit_failed", detail: `http ${res.status}` });
+        }
+        catch (e) {
+            if (this.path !== null) {
+                appendRotating(this.path, { ...line, ts: line.ts, event: "platform_audit_failed", detail: e instanceof Error ? e.message : String(e) });
+            }
+        }
+    }
+}
+/** Append one line, rotating at 16 MiB; a failure is reported, never thrown. */
+function appendRotating(path, line) {
+    try {
+        const size = statSync(path, { throwIfNoEntry: false })?.size ?? 0;
+        if (size >= FALLBACKS_AUDIT_MAX_BYTES)
+            renameSync(path, `${path}.1`);
+        appendFileSync(path, `${JSON.stringify(line)}\n`, { mode: 0o600 });
+    }
+    catch (e) {
+        process.stderr.write(`fallbacks audit: ${e instanceof Error ? e.message : String(e)}\n`);
+    }
+}
+async function httpPost(url, body, headers) {
+    const res = await fetch(url, { method: "POST", headers, body });
+    return { ok: res.ok, status: res.status };
+}

package/dist/runtime/host-autowake.d.ts

@@ -0,0 +1,79 @@
+/**
+ * W769 — the studio host's auto-wake wiring.
+ *
+ * The loop itself is `@celestea/runtime`'s `AutowakeLoop` (mailbox → busy check →
+ * wake). This module owns the studio-specific part: WHICH conversations have a
+ * loop (one per host session, keyed by session id / `cli-main` for the detached
+ * generation) and how the loop reads the state of the generation in force.
+ *
+ * It lives outside the adapter on purpose: `real-runtime-adapter.ts` sits at the
+ * eslint size budget, and "which sessions can be woken" is a policy of its own —
+ * a worker's receipt is addressed to the session that spawned it, so the set of
+ * queues that can carry one is exactly the set of live host sessions.
+ */
+import type { SessionMailbox } from "@celestea/workers";
+/** What the adapter must tell the wiring. */
+export interface HostAutowakeOptions {
+    /** `CELESTEA_AUTOWAKE` (read once by the adapter at construction). */
+    enabled: boolean;
+    /**
+     * Current state of one host conversation (null = no live generation).
+     * W855 (C8): `userPending` is the size of the USER's `next-turn` lane; the
+     * loop only observes it (the turn-start drain is the lane's consumer).
+     */
+    lookup: (session: string | null) => {
+        mailbox: SessionMailbox | null;
+        busy: boolean;
+        userPending: number;
+    } | null;
+    /** Claim the slot and run one ordinary turn over the drained receipts. */
+    wake: (session: string | null, input: string | null) => boolean;
+}
+/**
+ * W855 (C8): the generation state the loop reads on every pass, seen
+ * structurally (the registry entry satisfies it). Keeping this here — instead of
+ * inline in `real-runtime-adapter.ts` — is what keeps that file under its
+ * eslint `max-lines` budget.
+ */
+export interface AutowakeGeneration {
+    inFlight: boolean;
+    runtime: {
+        workers?: {
+            mailbox?: SessionMailbox | null;
+        } | null;
+        pendingInjections(lane?: "next-turn"): number;
+    };
+}
+/** Mailbox + busy + the USER's next-turn lane depth, from one entry (or null). */
+export declare function autowakeStateOf(entry: AutowakeGeneration | null): {
+    mailbox: SessionMailbox | null;
+    busy: boolean;
+    userPending: number;
+} | null;
+/** The studio's log line for auto-wake decisions (stderr, like boot recovery). */
+export declare function autowakeLog(session: string | null, line: string): void;
+export declare class HostAutowake {
+    private readonly loops;
+    private readonly opts;
+    constructor(opts: HostAutowakeOptions);
+    /** Is auto-wake on? (`CELESTEA_AUTOWAKE`, default on.) */
+    get running(): boolean;
+    /** Live loops (diagnostics / tests). */
+    get count(): number;
+    /**
+     * Mount the (idempotent) loop of one host conversation. Called from the
+     * generation's build callback: the hooks read the CURRENT entry on every pass,
+     * so a rebuilt instance is picked up without re-mounting anything.
+     */
+    ensure(session: string | null): void;
+    /**
+     * W794: a DELETED session never comes back under that id, so its loop is
+     * unparked for good — otherwise it keeps re-binding to a generation that can
+     * never exist again and re-logs `no live generation to bind` forever (the
+     * timer is real). A rebuild / idle eviction must NOT call this: the same id
+     * recomposes, and its loop has to be waiting for it. Idempotent.
+     */
+    forget(session: string | null): Promise<void>;
+    /** Unpark every loop (process shutdown; idempotent). */
+    stop(): Promise<void>;
+}