@celestea/studio 2.7.1

package/dist/runtime/session-compose.js

@@ -0,0 +1,350 @@
+/**
+ * SessionComposer — `compose()` for ONE session (W513).
+ *
+ * Every session runtime is one self-consistent generation: its own profile
+ * snapshot (base profile + the session's `session.json` model override), its own
+ * session binding (`<dir>/cli-main.jsonl` or an in-memory log when detached),
+ * its own usage tracker, its own agent loop instance and its own worker
+ * registry. Nothing is shared but the process (and the LLM seam factory), which
+ * is exactly what makes two sessions unable to see each other's history.
+ *
+ * The module also owns the resource caps and the two error channels the host
+ * maps onto HTTP 503, so the adapter itself stays about the HTTP contract.
+ */
+import { createUsageTracker, DefaultAgentLoop } from "@celestea/agent-loop";
+import { listSkills, memoryContextOf, readLayers, renderSkillCatalog } from "@celestea/core";
+import { createSessionInbox } from "@celestea/runtime";
+import { createLedgerLlm, createUsageLedger, hostOf, HOST_SESSION_ID, } from "@celestea/runtime";
+import { InMemorySessionLog } from "@celestea/session";
+import { compose, llmSummarizer, SessionCapacityError, TurnCapacityError, } from "@celestea/runtime";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapacityError } from "../runtime-adapter.js";
+import { bindingFor, closeLog, workerSessionPrefix } from "./engine-session.js";
+import { DEFAULT_SESSION_MODE, effectiveMode } from "../store/mode.js";
+import { enginePlugins } from "./engine-plugins.js";
+import { questionAnsweredRow, questionAskedRow } from "../question-rows.js";
+import { EMPTY_GRANTS } from "./engine-grants.js";
+import { createEngineLlm } from "./llm-assembly.js";
+import { workerTablePath } from "./worker-table.js";
+import { ATTACHMENTS_DIRNAME, createAttachmentStore } from "@celestea/tools";
+import { createImageDowngradeLlm } from "@celestea/llm";
+import { withAttachments } from "./attachments-llm.js";
+/** W510 resource caps (overridable through the adapter options or the env). */
+export const MAX_LIVE_SESSIONS = 4;
+export const MAX_CONCURRENT_TURNS = 2;
+export const SESSION_IDLE_TTL_MS = 15 * 60 * 1_000;
+/** Non-negative integer from the environment, else the frozen default. */
+export function limitFromEnv(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+/** Shut one instance down and close its log descriptor (order matters). */
+export async function disposeRuntime(runtime) {
+    const log = runtime.session;
+    await runtime.shutdown();
+    closeLog(log);
+    runtime.release();
+}
+/** Wrap the registry caps into the ONE error the HTTP layer maps to 503. */
+export function capacityErrorOf(e) {
+    if (e instanceof SessionCapacityError)
+        return new CapacityError(`too many live sessions (limit ${e.limit})`);
+    if (e instanceof TurnCapacityError)
+        return new CapacityError(`too many concurrent turns (limit ${e.limit})`);
+    return e;
+}
+export class SessionComposer {
+    opts;
+    memoryLogs = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Compose one session generation (the registry's build factory). */
+    compose(sessionId, dir) {
+        const profile = this.profileFor(sessionId);
+        // W804 (multimodal P0 section 5): the session's attachment store. It lives
+        // INSIDE the session directory, so trash/archive/delete carry it along. The
+        // DETACHED generation (dir === null, the face /api/tools and the default
+        // prompt read) gets a host-level store so read_image is part of the SAME face
+        // every session's prompt advertises; a session-less turn is the only caller
+        // that could ever write there.
+        const attachments = createAttachmentStore(dir === null ? join(tmpdir(), "celestea-detached-attachments") : join(dir, ATTACHMENTS_DIRNAME));
+        // Optimistic default (section 7.1): only an EXPLICIT input_modalities without
+        // "image" disables the read_image gate; an unknown model stays optimistic.
+        const modalities = this.opts.modelInputModalities?.(profile.model) ?? null;
+        const imageInputAllowed = modalities === null ? true : modalities.includes("image");
+        // W768: the session's OWN workspace, taken from the same resolution the
+        // system prompt renders (the host's `resolveSession` hook). A session with no
+        // resolvable workspace keeps the process env posture — never a failure.
+        const workspace = sessionId === null ? null : (this.opts.resolveSession?.(sessionId)?.workspace ?? null);
+        // W884 + F3: the engine-owned TURN CONTEXT. The skill catalog (name +
+        // description ONLY) and the workspace MEMORY.md are re-read at EVERY turn
+        // start from the SAME workspace the sandbox/guard use (W768) and injected
+        // as durable user-role history. Neither is ever put in the system prompt.
+        // A workspace with neither produces NO rows at all (zero cost), and a
+        // detached generation (no workspace) never attaches the provider at all.
+        const turnContext = workspace === null
+            ? undefined
+            : () => {
+                const rows = [];
+                const catalog = renderSkillCatalog(listSkills(readLayers(workspace.path, { env: this.opts.env })));
+                if (catalog !== null)
+                    rows.push({ text: catalog, origin: "skill" });
+                const memory = memoryContextOf(workspace.path, { env: this.opts.env });
+                if (memory !== null)
+                    rows.push({ text: memory, origin: "memory" });
+                return rows;
+            };
+        const reader = this.opts.grants;
+        const read = reader?.read(sessionId, dir) ?? { grants: EMPTY_GRANTS, warnings: [] };
+        // W728: the ledger must exist before the Llm wrapper (every step books).
+        const ledger = this.usageLedger(sessionId, dir);
+        // W783: the question wiring of THIS generation. The runtime handle does not
+        // exist until `compose()` below returns, so the wiring reaches it through a
+        // holder it fills in immediately afterwards — the same late-binding the
+        // `isLive` probe and the log write both need.
+        const questionHolder = { runtime: null };
+        const questions = this.questionWiring(sessionId, questionHolder);
+        const engine = enginePlugins({
+            profile,
+            // W791 (P1, §5.2 #2): the mode decided at compose time. The DETACHED
+            // generation never asks the hook (its id is not addressable), a session
+            // without a declared mode reads as `standard` (K8), and both compose the
+            // whole registry — so nothing about a pre-P1 generation changes.
+            mode: sessionId === null ? DEFAULT_SESSION_MODE : effectiveMode(this.opts.sessionMode?.(sessionId) ?? null),
+            workspace: workspace === null ? null : { workspace: workspace.path },
+            ...(questions === null ? {} : { questions }),
+            attachments,
+            imageInputAllowed,
+            llm: this.engineLlm(sessionId, profile, ledger, attachments),
+            workers: null, // the workers plugin registers the three tools, in compose order
+            ...(this.opts.disclosure === undefined || sessionId === null ? {} : { disclosure: this.opts.disclosure }),
+            ...(this.opts.tools === undefined ? {} : { tools: this.opts.tools }),
+            ...(this.opts.sandbox === undefined ? {} : { sandbox: this.opts.sandbox }),
+            ...(this.opts.guard === undefined ? {} : { guard: this.opts.guard }),
+            grants: read.grants,
+            ...(reader === undefined ? {} : { audit: reader.audit(sessionId) }),
+            env: this.opts.env,
+        });
+        // After the boundary is built: audit the generation and spend one-shots, so
+        // THIS turn keeps its grants and the next one sees the consumption.
+        reader?.onComposed(sessionId, dir, read);
+        const usage = createUsageTracker();
+        const hooks = this.opts.sessionHooks?.(sessionId) ?? {};
+        const composed = compose({
+            profile,
+            plugins: engine.plugins,
+            sessionBinding: this.bindingTo(sessionId, dir),
+            // W855 #1: reap detached `run_shell background:true` children on shutdown.
+            // The composer holds the registry from `engine.tools`; runtime is L2 and
+            // may not import @celestea/tools, so the hook is wired HERE (host side).
+            shutdownHooks: [() => engine.tools.processes.dispose()],
+            usage,
+            ...(ledger === null ? {} : { ledger }),
+            inbox: hooks.inbox ?? createSessionInbox(),
+            ...(hooks.onInjected === undefined ? {} : { onInjected: hooks.onInjected }),
+            ...(turnContext === undefined ? {} : { turnContext }),
+            loopFactory: (bindings) => {
+                // W806: the turn boundary is the ONLY place the disclosed set may move.
+                engine.tools.disclosure.beginTurn();
+                return new DefaultAgentLoop(bindings.config, {
+                    signal: bindings.signal,
+                    sink: bindings.sink,
+                    usage,
+                    ...(bindings.injections === undefined ? {} : { injections: bindings.injections }),
+                });
+            },
+            workers: this.workerWiring(sessionId, profile),
+            // W740: the watchdog settings come from the process environment; the
+            // composition root reads them and registers the stop hook with the sweep.
+            env: this.opts.env,
+            ...(this.opts.watchdog === undefined ? {} : { watchdog: this.opts.watchdog }),
+            ...(this.opts.now === undefined ? {} : { now: this.opts.now }),
+        });
+        // W783: bind the just-composed runtime into the question wiring, so
+        // `isLive` and the `user_question` log row address THIS generation.
+        questionHolder.runtime = composed;
+        return composed;
+    }
+    /**
+     * W783: the user-question wiring of ONE session generation, or null when the
+     * host mounted no table (the tool is then not offered to the model at all).
+     *
+     * The bus is the SESSION's own (`compose()` provides it), filled in by the
+     * plugin body: an answerer chain per generation is what stops a question asked
+     * in one session from being answered into another.
+     */
+    questionWiring(sessionId, holder) {
+        const registry = this.opts.questionRegistry;
+        if (registry === undefined || registry === null)
+            return null;
+        return {
+            registry,
+            sessionId,
+            bus: { current: null },
+            isLive: () => holder.runtime !== null && !holder.runtime.isReleased,
+            publish: (question) => this.opts.publishQuestion?.(sessionId, question),
+            record: (question) => holder.runtime?.session.append(questionAskedRow(question)),
+            recordAnswer: (requestId, answers, timedOut) => holder.runtime?.session.append(questionAnsweredRow(requestId, answers, timedOut)),
+        };
+    }
+    /**
+     * The session's ledger, or null when the host did not wire one. The session
+     * label is the file's self-description (`<workspace>/<session>`, §3.2.1).
+     *
+     * W878: `compose(sessionId, dir)` already carries the trusted id, so the label
+     * uses it directly and only falls back to `HOST_SESSION_ID` when the id is
+     * null (the detached generation). `dir` is kept in the signature for the
+     * caller but is deliberately no longer a source of the label.
+     */
+    usageLedger(sessionId, dir) {
+        void dir;
+        const file = this.opts.ledgerFile;
+        if (file === undefined || file === null)
+            return null;
+        return createUsageLedger({ session: sessionId ?? HOST_SESSION_ID, file });
+    }
+    /**
+     * E §4 P1 (W785): the ONE place a composed generation decides which `Llm` it
+     * runs on. Fallback OFF (or unwired) = the W728 path unchanged (ledger wrapper
+     * around the raw seam). Fallback ON = the decorator, which books one ledger
+     * row per ATTEMPT and hands the switch to the next target.
+     */
+    engineLlm(sessionId, profile, ledger, attachments) {
+        const inner = this.llmFactory()(profile);
+        const wrapped = this.opts.fallback?.wrap({
+            inner,
+            profile,
+            sessionId,
+            steps: ledger,
+            provider: this.opts.providerLabel ?? null,
+        }) ?? null;
+        const observed = wrapped ?? this.stepObservedLlm(inner, profile, ledger);
+        // W804: resolve image references to a REQUEST-scoped data-URL table (inner),
+        // then downgrade once on an "image unsupported" 400 (outer). The downgrade
+        // decorator is provider-seam typed; it only forwards streams, so the cast is
+        // a type-level bridge (same pattern as fallback-host.ts).
+        const resolved = withAttachments(observed, attachments);
+        return createImageDowngradeLlm({
+            inner: resolved,
+            onDowngrade: (info) => this.opts.onModelDowngrade?.(sessionId, info),
+            // W855: the SAME per-model modality gate that feeds read_image. It is
+            // evaluated against the request's own req.model (inside the decorator),
+            // so a model switch is never stale. null (unconfigured) = optimistic:
+            // images allowed; only an EXPLICIT list without "image" is text-only.
+            isTextOnly: (requestModel) => {
+                const modalities = this.opts.modelInputModalities?.(requestModel) ?? null;
+                return modalities !== null && !modalities.includes("image");
+            },
+        });
+    }
+    /**
+     * W728 §3 P0: wrap the engine `Llm` so every model step books one ledger row
+     * (success, failure and retry alike). The wrapper lives in the composed
+     * Context, so worker-driven calls go through it as well; the summarizer path
+     * is separate (`summarizer()`, a P1 concern).
+     */
+    stepObservedLlm(llm, profile, ledger) {
+        if (ledger === null)
+            return llm;
+        return createLedgerLlm({
+            inner: llm,
+            sink: ledger,
+            provider: this.opts.providerLabel ?? null,
+            model: profile.model,
+            base_url_host: hostOf(profile.base_url),
+        });
+    }
+    /**
+     * Base profile + the session's own `session.json` overrides (model AND, since
+     * W729, the mode-dependent system prompt). This is the ONE place a session's
+     * instance profile is decided, so two sessions in the same process can differ
+     * in prompt without either one seeing the other's.
+     */
+    profileFor(sessionId) {
+        const base = this.opts.baseProfile();
+        const overrides = this.sessionOverrides(sessionId);
+        return overrides === null ? base : { ...base, ...overrides };
+    }
+    /** The session's profile overrides; `null` when it declares none. */
+    sessionOverrides(sessionId) {
+        if (sessionId === null)
+            return null;
+        const out = {};
+        const model = this.opts.sessionModel?.(sessionId) ?? "";
+        if (model !== "")
+            out.model = model;
+        const prompt = this.opts.sessionSystemPrompt?.(sessionId) ?? "";
+        if (prompt !== "")
+            out.system_prompt = prompt;
+        return Object.keys(out).length === 0 ? null : out;
+    }
+    /** The compact summarizer of the CURRENT base profile. */
+    summarizer() {
+        const profile = this.opts.baseProfile();
+        const factory = this.opts.summarize;
+        if (factory !== undefined)
+            return factory(profile);
+        return llmSummarizer({ llm: this.llmFactory()(profile), model: profile.model });
+    }
+    /**
+     * Worker wiring: ONE registry per session instance (W513, design D7), so a
+     * receipt returns to the session that spawned the worker and `worker:<sid>`
+     * ids stay unique through the session-derived prefix. W787: the table is
+     * PERSISTED by default at `workerRegistryPath()` (`<data dir>/
+     * worker-registry.tsv`; `CELESTEA_WORKER_REGISTRY` overrides). Only an
+     * explicit `tsvPath: null` is an in-memory table, so the default no
+     * longer collides the host with the fleet's shared `/tmp/registry.tsv`.
+     */
+    workerWiring(sessionId, profile) {
+        if (this.opts.workers === false)
+            return false;
+        return {
+            tsvPath: this.workerRegistryPath(),
+            resultsDir: this.opts.resultsDir ?? join(process.cwd(), "worker-results"),
+            sourceLabel: "celestea.studio-ts",
+            logFactory: () => new InMemorySessionLog(),
+            hostSessionId: sessionId ?? "cli-main",
+            sessionIdPrefix: workerSessionPrefix(sessionId),
+            hostModel: profile.model,
+            // W729 §2.3: workers inherit the spawning session's mode by default.
+            hostMode: sessionId === null ? null : (this.opts.sessionMode?.(sessionId) ?? null),
+        };
+    }
+    /** E §2.3 P0 ①: the configured table path (see `worker-table.ts` for the rules). */
+    workerRegistryPath() {
+        return workerTablePath({
+            env: this.opts.env,
+            ...(this.opts.dataDir === undefined ? {} : { dataDir: this.opts.dataDir }),
+            resultsDir: this.opts.resultsDir ?? join(process.cwd(), "worker-results"),
+            ...(this.opts.workerRegistryPath === undefined ? {} : { override: this.opts.workerRegistryPath }),
+        });
+    }
+    llmFactory() {
+        return this.opts.llm ?? ((profile) => createEngineLlm(profile, this.opts.env));
+    }
+    bindingTo(sessionId, dir) {
+        const target = dir === null || sessionId === null ? null : { sessionId, dir };
+        return bindingFor(sessionId, target, this.memoryLogs, {
+            ...(this.opts.checkpoint ?? {}),
+            onDegraded: (info) => this.noteDegraded(info),
+        });
+    }
+    /**
+     * E §1.3 P1 ③: a session log that refused a write is reported to the audit
+     * channel (the sidecar already carries the sticky counter, §1.2.2). One line
+     * per session instance — the store fires this at most once.
+     */
+    noteDegraded(info) {
+        this.opts.recoveryAudit?.write({
+            event: "log_degraded",
+            session: info.session,
+            count: info.count,
+            detail: `session log writeErrorCount=${info.count} (disk and memory diverged)`,
+        });
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The session grant boundary at COMPOSE time (W516 §4.2, §4.4).
+ *
+ * One instance per session is composed per turn boundary, so this is where the
+ * session's widenings are read, audited and (for one-shot entries) spent. "Read
+ * at compose" is what makes a grant land in the NEXT turn and never inside the
+ * running one: the instance a turn runs on keeps the boundary it was composed
+ * with, whatever happens to `grants.json` meanwhile.
+ *
+ * Honest limits of this implementation (also listed in the W516 report): `use`
+ * is sampled once per composed generation (i.e. per turn boundary) rather than
+ * once per sandbox spawn, and a one-shot entry is spent at compose time — the
+ * safe direction (it can only be lost earlier, never used twice).
+ */
+import { type EffectiveGrants } from "./engine-grants.js";
+import type { EngineGrantAudit } from "./engine-grants.js";
+export interface GrantsReadResult {
+    grants: EffectiveGrants;
+    warnings: string[];
+}
+export interface SessionGrantsReader {
+    /** Effective grants of one session directory (never throws — §4.1). */
+    read(sessionId: string | null, dir: string | null): GrantsReadResult;
+    /** Audit the boundary + spend one-shot entries; called once per compose. */
+    onComposed(sessionId: string | null, dir: string | null, read: GrantsReadResult): void;
+    /** An audit sink already bound to one session. */
+    audit(sessionId: string | null): EngineGrantAudit;
+    /** Await in-flight platform-audit deliveries (tests / shutdown). */
+    flush(): Promise<void>;
+}
+export interface SessionGrantsOptions {
+    dataDir: string;
+    env: NodeJS.ProcessEnv;
+    now?: () => number;
+}
+export declare function createSessionGrants(opts: SessionGrantsOptions): SessionGrantsReader;

package/dist/runtime/session-grants.js

@@ -0,0 +1,69 @@
+/**
+ * The session grant boundary at COMPOSE time (W516 §4.2, §4.4).
+ *
+ * One instance per session is composed per turn boundary, so this is where the
+ * session's widenings are read, audited and (for one-shot entries) spent. "Read
+ * at compose" is what makes a grant land in the NEXT turn and never inside the
+ * running one: the instance a turn runs on keeps the boundary it was composed
+ * with, whatever happens to `grants.json` meanwhile.
+ *
+ * Honest limits of this implementation (also listed in the W516 report): `use`
+ * is sampled once per composed generation (i.e. per turn boundary) rather than
+ * once per sandbox spawn, and a one-shot entry is spent at compose time — the
+ * safe direction (it can only be lost earlier, never used twice).
+ */
+import { effectiveGrantsOf, expiredGrants } from "./engine-grants.js";
+import { GrantsAuditWriter } from "../store/grants-audit.js";
+import { isExpired, readGrantsFile, writeGrantsFile } from "../store/grants.js";
+/** Caps whose use changes the process environment → always sampled (§4.4). */
+const HEAVY_CAPS = ["network", "unsandboxed"];
+export function createSessionGrants(opts) {
+    const writer = new GrantsAuditWriter({ dataDir: opts.dataDir, env: opts.env, now: opts.now ?? Date.now });
+    const audit = (sessionId) => (event) => writer.write({ session: sessionId ?? "", ...event });
+    const ctx = { env: opts.env, now: opts.now ?? Date.now };
+    return {
+        read: (sessionId, dir) => effectiveGrantsOf(dir, sessionId, ctx.env, Math.floor(ctx.now() / 1000)),
+        audit,
+        flush: () => writer.flush(),
+        onComposed: (sessionId, dir, result) => recordComposed(writer, sessionId, dir, result, ctx),
+    };
+}
+/** Warnings → audit; heavyweight caps → `use`; expired / one-shot entries. */
+function recordComposed(writer, sessionId, dir, result, ctx) {
+    const session = sessionId ?? "";
+    const sink = (event) => writer.write({ session, ...event });
+    const seconds = Math.floor(ctx.now() / 1000);
+    for (const warning of result.warnings) {
+        const event = warning.startsWith("grants_unreadable") ? "grants_unreadable" : "deny";
+        sink({ event, reason: warning });
+    }
+    for (const source of result.grants.sources) {
+        if (!HEAVY_CAPS.includes(source.cap))
+            continue;
+        sink({ event: "use", cap: source.cap, grant_id: source.grantId, detail: "active for the composed session instance" });
+    }
+    // W878: the file is self-describing, so validate it against the TRUSTED id
+    // (never a path inference). A null id with a real dir reads nothing.
+    const read = dir === null || sessionId === null ? null : readGrantsFile(dir, sessionId);
+    if (read?.file === undefined)
+        return;
+    for (const grant of expiredGrants(read.file, seconds))
+        sink({ event: "expire", cap: grant.cap, grant_id: grant.id });
+    spendOneShot(writer, { dir, sessionId, file: read.file, active: new Set(result.grants.sources.map((s) => s.grantId)), seconds, env: ctx.env });
+}
+/** Remove the one-shot entries that were just composed in (§2.3). */
+function spendOneShot(writer, ctx) {
+    const spent = ctx.file.grants.filter((entry) => entry.uses_left === 1 && ctx.active.has(entry.id) && !isExpired(entry, ctx.seconds));
+    if (ctx.dir === null || ctx.sessionId === null || spent.length === 0)
+        return;
+    const keep = ctx.file.grants.filter((entry) => !spent.some((s) => s.id === entry.id));
+    try {
+        writeGrantsFile(ctx.dir, { version: 1, session: ctx.sessionId, updated_at: ctx.seconds, grants: keep }, { env: ctx.env, now: ctx.seconds });
+    }
+    catch {
+        return; // best-effort: the entry stays and stays valid for one more turn
+    }
+    for (const entry of spent) {
+        writer.write({ session: ctx.sessionId, event: "use", cap: entry.cap, grant_id: entry.id, uses_left: 0, detail: "one-shot grant spent" });
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * The two lifecycle operations of ONE session generation — `clear` and `compact`
+ * (extracted from `real-runtime-adapter.ts`, W787: the adapter is the HTTP seam
+ * and stays inside the §4.1 file budget; the operations themselves are about the
+ * session runtime, not about the seam).
+ *
+ *   - `clearSession` empties the log and resets the turn counter of the LIVE
+ *     instance, and 409s (`TurnBusyError`) while a turn is in flight — clearing
+ *     a session mid-turn would delete the rows the turn is writing;
+ *   - `compactSession` compacts `<dir>/cli-main.jsonl`, and when an instance is
+ *     live it is EVICTED first and composed again afterwards: the compaction
+ *     rewrites the file behind the log's descriptor, so reusing the old instance
+ *     would keep serving the pre-compaction history from memory. W825 P0: when
+ *     `evict` REFUSES (a pinned instance with live worker work, or a busy one)
+ *     the log is NOT rewritten at all — no orphaned descriptor, no false
+ *     `rebound` — and `rebound:true` is reported only for a verified rebuild.
+ */
+import { type SessionRuntimeRegistry, type Summarizer } from "@celestea/runtime";
+import { type ClearOutcome, type CompactOutcome } from "../runtime-adapter.js";
+import { type SessionTarget } from "./engine-session.js";
+/** The frozen "nothing to compact" note (kept in sync with compact/plan.ts). */
+export declare const SKIPPED_NOTE = "\u5386\u53F2\u4E0D\u8DB3\uFF0C\u65E0\u9700\u538B\u7F29";
+/**
+ * W825 P0: the session holds LIVE worker work, so its instance is pinned and
+ * [SessionRuntimeRegistry.evict] refuses it. Rewriting the log anyway would
+ * leave the live log descriptor pointing at the unlinked old inode — every
+ * later append is lost on process exit while the response still claims
+ * `rebound:true`. The lifecycle therefore refuses (no rewrite, `rebound:false`);
+ * the HTTP layer turns the same condition into a 409.
+ */
+export declare const PINNED_NOTE = "worker \u8FD0\u884C\u4E2D\uFF0C\u5DF2\u8DF3\u8FC7\u538B\u7F29";
+export interface SessionLifecycleDeps {
+    registry: SessionRuntimeRegistry;
+    /** Host lookup (`<workspace>/<session>` -> dir); null for an unresolvable id. */
+    resolve: (id: string) => SessionTarget | null;
+    /** The compact summarizer of the current base profile. */
+    summarizer: () => Summarizer;
+}
+export declare function clearSession(registry: SessionRuntimeRegistry, session: string | null): ClearOutcome;
+export declare function compactSession(deps: SessionLifecycleDeps, session: string): Promise<CompactOutcome>;

package/dist/runtime/session-lifecycle.js

@@ -0,0 +1,86 @@
+/**
+ * The two lifecycle operations of ONE session generation — `clear` and `compact`
+ * (extracted from `real-runtime-adapter.ts`, W787: the adapter is the HTTP seam
+ * and stays inside the §4.1 file budget; the operations themselves are about the
+ * session runtime, not about the seam).
+ *
+ *   - `clearSession` empties the log and resets the turn counter of the LIVE
+ *     instance, and 409s (`TurnBusyError`) while a turn is in flight — clearing
+ *     a session mid-turn would delete the rows the turn is writing;
+ *   - `compactSession` compacts `<dir>/cli-main.jsonl`, and when an instance is
+ *     live it is EVICTED first and composed again afterwards: the compaction
+ *     rewrites the file behind the log's descriptor, so reusing the old instance
+ *     would keep serving the pre-compaction history from memory. W825 P0: when
+ *     `evict` REFUSES (a pinned instance with live worker work, or a busy one)
+ *     the log is NOT rewritten at all — no orphaned descriptor, no false
+ *     `rebound` — and `rebound:true` is reported only for a verified rebuild.
+ */
+import { join } from "node:path";
+import { keyOfSession, runCompaction } from "@celestea/runtime";
+import { EngineError } from "../runtime-adapter.js";
+import { TurnBusyError } from "@celestea/runtime";
+import { SESSION_LOG_NAME } from "./engine-session.js";
+/** The frozen "nothing to compact" note (kept in sync with compact/plan.ts). */
+export const SKIPPED_NOTE = "历史不足，无需压缩";
+/**
+ * W825 P0: the session holds LIVE worker work, so its instance is pinned and
+ * [SessionRuntimeRegistry.evict] refuses it. Rewriting the log anyway would
+ * leave the live log descriptor pointing at the unlinked old inode — every
+ * later append is lost on process exit while the response still claims
+ * `rebound:true`. The lifecycle therefore refuses (no rewrite, `rebound:false`);
+ * the HTTP layer turns the same condition into a 409.
+ */
+export const PINNED_NOTE = "worker 运行中，已跳过压缩";
+export function clearSession(registry, session) {
+    const entry = registry.peek(session);
+    if (entry !== null) {
+        if (entry.inFlight)
+            throw new TurnBusyError("clear");
+        entry.runtime.session.clear();
+        entry.turnNo = 0;
+    }
+    return { cleared: true };
+}
+export async function compactSession(deps, session) {
+    const target = deps.resolve(session);
+    if (target === null || target.dir === null) {
+        return { compacted: false, note: SKIPPED_NOTE, session, rebound: false };
+    }
+    const before = deps.registry.peek(session);
+    if (before !== null) {
+        // W825 P0: evict() is the ONE gate that knows both rules — a BUSY turn and a
+        // PINNED instance (live worker work) both refuse it. Its verdict used to be
+        // discarded, so a pinned session was compacted UNDER a live descriptor: the
+        // atomic rename replaced the path, the old fd kept pointing at the unlinked
+        // inode, and every later turn event was written where nobody would read it.
+        const evicted = await deps.registry.evict(keyOfSession(session));
+        if (!evicted) {
+            return { compacted: false, note: PINNED_NOTE, session, rebound: false };
+        }
+    }
+    const result = await runCompactionOf(deps, join(target.dir, SESSION_LOG_NAME));
+    let rebound = false;
+    if (before !== null) {
+        const after = deps.registry.ensure(session, target.dir);
+        // rebound is a FACT, not a promise: only a genuinely NEW runtime counts. A
+        // refused evict returns above, so this can never claim a rebuild that did
+        // not happen.
+        rebound = result.compacted && after.runtime !== before.runtime;
+    }
+    return {
+        compacted: result.compacted,
+        ...(result.compacted && result.kept_turns !== null ? { kept_turns: result.kept_turns } : {}),
+        note: result.note,
+        session,
+        rebound,
+    };
+}
+/** A compaction failure is an ENGINE error (HTTP 500), never a host-side crash. */
+async function runCompactionOf(deps, logPath) {
+    try {
+        return await runCompaction({ logPath, summarize: deps.summarizer() });
+    }
+    catch (e) {
+        throw new EngineError(e instanceof Error ? e.message : String(e));
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * The SSE publishers the host raises on behalf of ONE session (W515 §2/§4).
+ *
+ * Two concerns that look alike and are kept together for that reason:
+ *   - an injected message's placement change (`status` frames: `queued` /
+ *     `steering` on acceptance, `context` when a boundary consumes it);
+ *   - a parked user question (`question`, W783).
+ *
+ * Both are "the adapter knows the session id and the bus; nobody else does", so
+ * both are built from the same two callbacks and neither needs the engine.
+ *
+ * NOTE (pure move, W783): the injection publisher below is W515 behaviour that
+ * used to live inline in `real-runtime-adapter.ts`. Nothing about what it emits
+ * changed — only where it is written down.
+ */
+import { type SessionInbox } from "@celestea/runtime";
+import type { PendingInjection } from "@celestea/core";
+/**
+ * The session hooks the composer consumes (inbox + observed boundaries).
+ * Structurally identical to `session-compose.ts`'s own `SessionInjectionHooks`;
+ * the `onInjected` parameter is the composer's tamer `PendingInjection` view,
+ * because the composer reports a drained message before it is materialized.
+ */
+export interface SessionInjectionHooks {
+    inbox: SessionInbox;
+    onInjected: (messages: readonly PendingInjection[], boundary: "turn-start" | "step") => void;
+}
+/** Reach the bus and the clock without owning either. */
+export interface PublisherDeps {
+    /** Emit one status frame for this session. */
+    emitStatus: (sessionId: string | null, payload: Record<string, unknown>) => void;
+    now: () => number;
+}
+/**
+ * The injection hooks of one session: the ACCEPT side is observed when the inbox
+ * queues a message, and the CONSUME side only through `onInjected`, which knows
+ * WHICH boundary drained it (a mailbox receipt never enters the inbox, so it
+ * cannot be reported here).
+ */
+export declare function injectionHooksOf(sessionId: string | null, deps: PublisherDeps): SessionInjectionHooks;