specrails-desktop 2.61.0 → 2.63.0

package/server/dist/modules/agent-sessions/domain/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionRequestError = void 0;
+exports.isSessionRequestError = isSessionRequestError;
+/** A session protocol request failed; `code` is Core's stable error code. */
+class SessionRequestError extends Error {
+    rpcCode;
+    code;
+    retryable;
+    detail;
+    constructor(message, data, rpcCode) {
+        super(message);
+        this.rpcCode = rpcCode;
+        this.name = 'SessionRequestError';
+        this.code = data.code;
+        this.retryable = data.retryable;
+        this.detail = data.detail;
+    }
+}
+exports.SessionRequestError = SessionRequestError;
+function isSessionRequestError(error, code) {
+    return error instanceof SessionRequestError && (code === undefined || error.code === code);
+}

package/server/dist/modules/agent-sessions/domain/host-state.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INITIAL_HOST_STATE = exports.DEFAULT_SUPERVISION = void 0;
+exports.canTransition = canTransition;
+exports.onDemand = onDemand;
+exports.onReady = onReady;
+exports.onFailure = onFailure;
+exports.onFatal = onFatal;
+exports.onRestartDue = onRestartDue;
+exports.onRetry = onRetry;
+exports.onStop = onStop;
+exports.acceptsSessions = acceptsSessions;
+exports.DEFAULT_SUPERVISION = Object.freeze({
+    baseDelayMs: 500,
+    maxDelayMs: 30_000,
+    maxFailures: 5,
+    failureWindowMs: 5 * 60_000,
+});
+exports.INITIAL_HOST_STATE = Object.freeze({ status: 'absent', failures: [] });
+const TRANSITIONS = Object.freeze({
+    absent: ['starting', 'stopped'],
+    starting: ['ready', 'restarting', 'degraded', 'stopped'],
+    ready: ['restarting', 'degraded', 'stopped'],
+    restarting: ['starting', 'degraded', 'stopped'],
+    degraded: ['starting', 'stopped'],
+    stopped: [],
+});
+function canTransition(from, to) {
+    return from === to || TRANSITIONS[from].includes(to);
+}
+function transition(state, to, failures = state.failures) {
+    if (!canTransition(state.status, to))
+        throw new Error(`Session host: ${state.status} → ${to} is not allowed`);
+    return { status: to, failures };
+}
+/** A session is needed in this scope. */
+function onDemand(state) {
+    if (state.status === 'absent')
+        return { state: transition(state, 'starting'), decision: { action: 'start' } };
+    return { state, decision: { action: 'none' } };
+}
+function onReady(state) {
+    return transition(state, 'ready');
+}
+/** The host exited unexpectedly or failed to start. */
+function onFailure(state, now, policy = exports.DEFAULT_SUPERVISION) {
+    if (state.status === 'stopped')
+        return { state, decision: { action: 'none' } };
+    const failures = [...state.failures.filter((at) => now - at < policy.failureWindowMs), now];
+    if (failures.length >= policy.maxFailures) {
+        return { state: transition(state, 'degraded', failures), decision: { action: 'degrade', reason: `${failures.length} host failures within ${Math.round(policy.failureWindowMs / 1000)}s` } };
+    }
+    const delayMs = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (failures.length - 1));
+    return { state: transition(state, 'restarting', failures), decision: { action: 'restart', delayMs } };
+}
+/** A failure no restart can fix (e.g. another host owns the scope's journal): degrade at once. */
+function onFatal(state, reason) {
+    if (state.status === 'stopped' || state.status === 'degraded')
+        return { state, decision: { action: 'none' } };
+    return { state: transition(state, 'degraded'), decision: { action: 'degrade', reason } };
+}
+/** The restart delay elapsed. */
+function onRestartDue(state) {
+    if (state.status !== 'restarting')
+        return { state, decision: { action: 'none' } };
+    return { state: transition(state, 'starting'), decision: { action: 'start' } };
+}
+/** A user explicitly retries a degraded scope (e.g. after fixing Core). */
+function onRetry(state) {
+    if (state.status !== 'degraded')
+        return { state, decision: { action: 'none' } };
+    return { state: transition(state, 'starting', []), decision: { action: 'start' } };
+}
+function onStop(state) {
+    return state.status === 'stopped' ? state : transition(state, 'stopped');
+}
+/** Whether new turns in this scope should use Core sessions right now. */
+function acceptsSessions(state) {
+    return state.status !== 'degraded' && state.status !== 'stopped';
+}

package/server/dist/modules/agent-sessions/domain/projection.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialProjection = initialProjection;
+exports.reduceEnvelope = reduceEnvelope;
+exports.liveSubagentCount = liveSubagentCount;
+const protocol_1 = require("./protocol");
+function initialProjection(sessionId, lastSeq = 0) {
+    return { sessionId, lastSeq, phase: 'idle', processAlive: false, openTurn: null, liveSubagents: 0, subagents: {} };
+}
+const KNOWN = new Set(protocol_1.KNOWN_EVENT_TYPES);
+function phaseOp(state) {
+    return { kind: 'resident.phase', phase: state.phase, liveSubagents: state.liveSubagents, processAlive: state.processAlive };
+}
+function reduceEnvelope(state, envelope) {
+    if (envelope.sessionId !== state.sessionId)
+        throw new Error(`Event for ${envelope.sessionId} applied to ${state.sessionId}`);
+    if (envelope.seq <= state.lastSeq)
+        return { status: 'duplicate', state, ops: [] };
+    if (envelope.seq !== state.lastSeq + 1)
+        return { status: 'gap', state, ops: [], expected: state.lastSeq + 1 };
+    const next = { ...state, lastSeq: envelope.seq };
+    const event = envelope.event;
+    if (!KNOWN.has(event.type))
+        return { status: 'applied', state: next, ops: [] };
+    const ops = [];
+    switch (event.type) {
+        case 'session.phase':
+            next.phase = event.phase;
+            ops.push(phaseOp(next));
+            break;
+        case 'session.process':
+            next.processAlive = event.state === 'started';
+            ops.push(phaseOp(next));
+            break;
+        case 'session.provider-ref':
+            ops.push({ kind: 'provider.ref', providerSessionRef: event.providerSessionRef });
+            break;
+        case 'session.updated':
+            ops.push({ kind: 'session.updated', changes: event.changes, outcome: event.outcome });
+            break;
+        case 'session.closed':
+            ops.push({ kind: 'session.closed', reason: event.reason });
+            break;
+        case 'input.accepted':
+            ops.push({ kind: 'input.state', inputId: event.inputId, state: 'accepted', turnId: null, reason: null });
+            break;
+        case 'input.state':
+            ops.push({ kind: 'input.state', inputId: event.inputId, state: event.state, turnId: event.turnId ?? null, reason: event.reason ?? null });
+            break;
+        case 'turn.started':
+            next.openTurn = { turnId: event.turnId, origin: event.origin, startedAt: event.at };
+            ops.push({ kind: 'turn.opened', turnId: event.turnId, origin: event.origin, inputIds: [...event.inputIds], triggeredBy: [...(event.trigger?.subagentIds ?? [])], at: event.at });
+            break;
+        case 'turn.output':
+            ops.push({ kind: 'turn.delta', turnId: event.turnId, channel: event.channel, delta: event.delta });
+            break;
+        case 'turn.tool': {
+            const { type: _type, at: _at, turnId, ...tool } = event;
+            ops.push({ kind: 'turn.tool', turnId, tool });
+            break;
+        }
+        case 'turn.completed': {
+            const open = next.openTurn;
+            next.openTurn = null;
+            ops.push({ kind: 'turn.closed', turnId: event.turnId, origin: open?.origin ?? 'user', status: event.status, text: event.text, error: event.error ?? null, usage: event.usage, startedAt: open?.startedAt ?? event.at, at: event.at });
+            break;
+        }
+        case 'subagent.started': {
+            const existing = next.subagents[event.subagentId];
+            const node = existing
+                ? { ...existing, phase: 'running', reason: null, endedAt: null, restarts: existing.restarts + (existing.phase === 'idle' ? 1 : 0) }
+                : {
+                    subagentId: event.subagentId,
+                    parentId: event.parentId,
+                    kind: event.kind,
+                    agentType: event.agentType ?? null,
+                    description: event.description,
+                    phase: 'running',
+                    reason: null,
+                    restarts: 0,
+                    startedAt: event.at,
+                    endedAt: null,
+                    usage: null,
+                    toolUses: null,
+                    durationMs: null,
+                    resultSummary: null,
+                    launchedInTurnId: next.openTurn?.turnId ?? null,
+                    delegated: event.delegated ?? null,
+                };
+            next.subagents = { ...next.subagents, [node.subagentId]: node };
+            ops.push({ kind: 'subagent.upsert', subagent: node });
+            break;
+        }
+        case 'subagent.phase': {
+            const node = next.subagents[event.subagentId];
+            if (!node)
+                break;
+            const live = event.phase === 'running';
+            const updated = { ...node, phase: event.phase, reason: event.reason ?? (live ? null : node.reason), endedAt: live ? null : event.at };
+            next.subagents = { ...next.subagents, [node.subagentId]: updated };
+            ops.push({ kind: 'subagent.upsert', subagent: updated });
+            break;
+        }
+        case 'subagent.usage': {
+            const node = next.subagents[event.subagentId];
+            if (!node)
+                break;
+            const updated = { ...node, usage: event.usage, toolUses: event.toolUses ?? node.toolUses, durationMs: event.durationMs ?? node.durationMs };
+            next.subagents = { ...next.subagents, [node.subagentId]: updated };
+            ops.push({ kind: 'subagent.upsert', subagent: updated });
+            if (event.billing === 'separate' && node.delegated)
+                ops.push({ kind: 'subagent.billed', subagentId: node.subagentId, driver: node.delegated.driver, model: event.usage.model ?? node.delegated.model, usage: event.usage, seq: envelope.seq, at: event.at });
+            break;
+        }
+        case 'subagent.result': {
+            const node = next.subagents[event.subagentId];
+            if (!node)
+                break;
+            const updated = { ...node, resultSummary: event.summary };
+            next.subagents = { ...next.subagents, [node.subagentId]: updated };
+            ops.push({ kind: 'subagent.upsert', subagent: updated });
+            break;
+        }
+        case 'subagent.output':
+            ops.push({ kind: 'subagent.output', subagentId: event.subagentId, channel: event.channel, delta: event.delta ?? null, tool: event.tool ?? null, seq: envelope.seq });
+            break;
+        case 'subagents.settled':
+            next.liveSubagents = event.live;
+            ops.push(phaseOp(next));
+            break;
+        case 'output.truncated':
+            ops.push({ kind: 'notice', level: 'info', code: 'output_truncated', message: `${event.droppedEvents} output chunks (${event.droppedBytes} bytes) were not stored` });
+            break;
+        case 'provider.diagnostic':
+            if (event.level === 'warning')
+                ops.push({ kind: 'notice', level: 'warning', code: event.code, message: event.message });
+            break;
+        case 'session.opened':
+        case 'notice.interruption':
+            break;
+    }
+    return { status: 'applied', state: next, ops };
+}
+/** Number of sub-agents the provider is still running. */
+function liveSubagentCount(state) {
+    return Object.values(state.subagents).filter((node) => node.phase === 'running').length;
+}

package/server/dist/modules/agent-sessions/domain/protocol.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Session protocol v1 wire types, as Desktop consumes them from the Core
+ * session host (`specrails-core runtime host --stdio`). This is Desktop's
+ * anti-corruption layer for the protocol: Core's internals never leak in.
+ * Drift is checked against the resolved Core's integration contract
+ * (`agentRuntime.sessions`) by `checkSessionContract` and check-core-compat.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_EVENT_TYPES = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+exports.checkSessionContract = checkSessionContract;
+exports.SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([1]);
+/** Event types this Desktop understands; newer Cores may send more (ignored). */
+exports.KNOWN_EVENT_TYPES = Object.freeze([
+    'session.opened',
+    'session.phase',
+    'session.process',
+    'session.provider-ref',
+    'session.updated',
+    'session.closed',
+    'input.accepted',
+    'input.state',
+    'turn.started',
+    'turn.output',
+    'turn.tool',
+    'turn.completed',
+    'subagent.started',
+    'subagent.phase',
+    'subagent.output',
+    'subagent.usage',
+    'subagent.result',
+    'subagents.settled',
+    'output.truncated',
+    'notice.interruption',
+    'provider.diagnostic',
+]);
+/** Compare a Core contract block with what this Desktop speaks. Pure. */
+function checkSessionContract(block) {
+    if (!block)
+        return { compatible: false, protocolVersion: null, unknownEventTypes: [], missingEventTypes: [], reasons: ['Core does not declare agentRuntime.sessions'] };
+    const common = block.protocolVersions.filter((version) => exports.SUPPORTED_PROTOCOL_VERSIONS.includes(version));
+    const declared = new Set(block.eventTypes);
+    const known = new Set(exports.KNOWN_EVENT_TYPES);
+    const missingEventTypes = exports.KNOWN_EVENT_TYPES.filter((type) => !declared.has(type));
+    const reasons = [];
+    if (common.length === 0)
+        reasons.push(`No common protocol version (Core ${block.protocolVersions.join(', ')}; Desktop ${exports.SUPPORTED_PROTOCOL_VERSIONS.join(', ')})`);
+    if (block.cliOperation !== 'host')
+        reasons.push(`Unexpected session CLI operation "${block.cliOperation}"`);
+    if (missingEventTypes.length)
+        reasons.push(`Core no longer declares: ${missingEventTypes.join(', ')}`);
+    return {
+        compatible: reasons.length === 0,
+        protocolVersion: common.length ? Math.max(...common) : null,
+        unknownEventTypes: block.eventTypes.filter((type) => !known.has(type)),
+        missingEventTypes,
+        reasons,
+    };
+}

package/server/dist/modules/agent-sessions/domain/subagent-policy.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSubagentPolicy = resolveSubagentPolicy;
+exports.resolveSubagentRuntime = resolveSubagentRuntime;
+/** The project setting decides; conversations without a project use the global one. */
+function resolveSubagentPolicy(input) {
+    const allowed = input.projectAllows ?? input.globalAllows;
+    return allowed ? 'enabled' : 'disabled';
+}
+/**
+ * Hybrid runtime (core-agent-sessions-host D9): native unless the user chose a
+ * provider other than the mission's; then Core launches them. Overrides a
+ * driver cannot apply are dropped (the UI never offers them).
+ */
+function resolveSubagentRuntime(input) {
+    const { choice } = input;
+    if (!choice)
+        return { runtime: { mode: 'native' } };
+    if (choice.provider === input.missionProvider) {
+        const caps = input.drivers.find((driver) => driver.id === input.missionProvider)?.capabilities;
+        return {
+            runtime: {
+                mode: 'native',
+                ...(caps?.subagentModel ? { model: choice.model } : {}),
+                ...(caps?.subagentEffort && choice.effort ? { effort: choice.effort } : {}),
+            },
+        };
+    }
+    if (!input.delegation)
+        return { runtime: { mode: 'native' }, unavailable: 'delegation_unsupported' };
+    if (!input.drivers.some((driver) => driver.id === choice.provider))
+        return { runtime: { mode: 'native' }, unavailable: 'driver_unavailable' };
+    return { runtime: { mode: 'delegated', driver: choice.provider, model: choice.model, ...(choice.effort ? { effort: choice.effort } : {}) } };
+}

package/server/dist/modules/agent-sessions/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionEventPump = exports.resolveCoreSessionsAvailability = exports.parseCoreSessionsFlag = exports.DEFAULT_CORE_SESSIONS_FLAG = exports.acceptsSessions = exports.DEFAULT_SUPERVISION = exports.resolveSubagentRuntime = exports.resolveSubagentPolicy = exports.reduceEnvelope = exports.liveSubagentCount = exports.initialProjection = exports.isSessionRequestError = exports.SessionRequestError = exports.checkSessionContract = exports.KNOWN_EVENT_TYPES = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+/**
+ * Agent sessions: Desktop as the host of Core's agent session runtime.
+ * Public API for conversational features (missions first). Adapters and the
+ * runtime registry are exposed through focused subpaths, not this barrel.
+ */
+var protocol_1 = require("./domain/protocol");
+Object.defineProperty(exports, "SUPPORTED_PROTOCOL_VERSIONS", { enumerable: true, get: function () { return protocol_1.SUPPORTED_PROTOCOL_VERSIONS; } });
+Object.defineProperty(exports, "KNOWN_EVENT_TYPES", { enumerable: true, get: function () { return protocol_1.KNOWN_EVENT_TYPES; } });
+Object.defineProperty(exports, "checkSessionContract", { enumerable: true, get: function () { return protocol_1.checkSessionContract; } });
+var errors_1 = require("./domain/errors");
+Object.defineProperty(exports, "SessionRequestError", { enumerable: true, get: function () { return errors_1.SessionRequestError; } });
+Object.defineProperty(exports, "isSessionRequestError", { enumerable: true, get: function () { return errors_1.isSessionRequestError; } });
+var projection_1 = require("./domain/projection");
+Object.defineProperty(exports, "initialProjection", { enumerable: true, get: function () { return projection_1.initialProjection; } });
+Object.defineProperty(exports, "liveSubagentCount", { enumerable: true, get: function () { return projection_1.liveSubagentCount; } });
+Object.defineProperty(exports, "reduceEnvelope", { enumerable: true, get: function () { return projection_1.reduceEnvelope; } });
+var subagent_policy_1 = require("./domain/subagent-policy");
+Object.defineProperty(exports, "resolveSubagentPolicy", { enumerable: true, get: function () { return subagent_policy_1.resolveSubagentPolicy; } });
+Object.defineProperty(exports, "resolveSubagentRuntime", { enumerable: true, get: function () { return subagent_policy_1.resolveSubagentRuntime; } });
+var host_state_1 = require("./domain/host-state");
+Object.defineProperty(exports, "DEFAULT_SUPERVISION", { enumerable: true, get: function () { return host_state_1.DEFAULT_SUPERVISION; } });
+Object.defineProperty(exports, "acceptsSessions", { enumerable: true, get: function () { return host_state_1.acceptsSessions; } });
+var availability_1 = require("./domain/availability");
+Object.defineProperty(exports, "DEFAULT_CORE_SESSIONS_FLAG", { enumerable: true, get: function () { return availability_1.DEFAULT_CORE_SESSIONS_FLAG; } });
+Object.defineProperty(exports, "parseCoreSessionsFlag", { enumerable: true, get: function () { return availability_1.parseCoreSessionsFlag; } });
+Object.defineProperty(exports, "resolveCoreSessionsAvailability", { enumerable: true, get: function () { return availability_1.resolveCoreSessionsAvailability; } });
+var session_event_pump_1 = require("./application/session-event-pump");
+Object.defineProperty(exports, "SessionEventPump", { enumerable: true, get: function () { return session_event_pump_1.SessionEventPump; } });

package/server/dist/modules/agent-sessions/ports.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/server/dist/modules/agent-sessions/runtime/core-sessions-availability.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSelectedSessionContract = readSelectedSessionContract;
+exports.coreSessionsAvailability = coreSessionsAvailability;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
+const availability_1 = require("../domain/availability");
+const protocol_1 = require("../domain/protocol");
+/** Read `agentRuntime.sessions` from the selected Core package next to its runtime CLI. */
+function readSelectedSessionContract(cli = (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)()) {
+    if (!cli)
+        return null;
+    const contract = node_path_1.default.resolve(node_path_1.default.dirname(cli), '..', '..', 'integration-contract.json');
+    if (!node_fs_1.default.existsSync(contract))
+        return null;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(contract, 'utf8')).agentRuntime?.sessions ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide once per call whether Core sessions are usable now. Any failure to
+ * probe Core degrades to legacy transports with an explicit reason.
+ */
+async function coreSessionsAvailability(env = process.env) {
+    const flag = (0, availability_1.parseCoreSessionsFlag)(env.SPECRAILS_CORE_SESSIONS);
+    if (flag === 'off')
+        return (0, availability_1.resolveCoreSessionsAvailability)(flag, null);
+    try {
+        const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+        const contract = (0, protocol_1.checkSessionContract)(readSelectedSessionContract());
+        return (0, availability_1.resolveCoreSessionsAvailability)(flag, runtime.api?.capabilities, contract.compatible);
+    }
+    catch (error) {
+        return { enabled: false, flag, reason: `Core runtime probe failed: ${error.message}` };
+    }
+}

package/server/dist/modules/agent-sessions/runtime/session-host-registry.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionHostRegistry = void 0;
+const session_event_pump_1 = require("../application/session-event-pump");
+const errors_1 = require("../domain/errors");
+const host_state_1 = require("../domain/host-state");
+/** Failures a restart cannot fix: the scope degrades at once instead of looping. */
+const FATAL_CODES = new Set(['journal_locked', 'protocol_mismatch', 'driver_unavailable']);
+/**
+ * One supervised Core session host per scope (project key or `global`).
+ * Hosts start lazily, restart with backoff after unexpected exits, re-open and
+ * replay tracked sessions, and become degraded after repeated failures so
+ * callers can fall back to legacy transports for new turns.
+ */
+class SessionHostRegistry {
+    options;
+    scopes = new Map();
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+    }
+    status(scope) {
+        return this.scopes.get(scope)?.state.status ?? 'absent';
+    }
+    /** Every known scope with its status (operator view, UI notices). */
+    hosts() {
+        return [...this.scopes].map(([scope, entry]) => ({ scope, status: entry.state.status, detail: entry.degradedReason, code: entry.degradedCode }));
+    }
+    /** Why a degraded scope is unavailable, when known. */
+    degradedCode(scope) {
+        return this.scopes.get(scope)?.degradedCode ?? null;
+    }
+    /** Whether new turns in this scope should use Core sessions now. */
+    available(scope) {
+        return !this.stopped && (0, host_state_1.acceptsSessions)(this.scopes.get(scope)?.state ?? host_state_1.INITIAL_HOST_STATE);
+    }
+    /** A ready client for the scope, starting the host when needed. */
+    async acquire(scope) {
+        if (this.stopped)
+            throw new errors_1.SessionRequestError('Session hosts are shutting down', { code: 'busy', retryable: true });
+        const entry = this.entry(scope);
+        if (entry.client && !this.isClosed(entry.client))
+            return entry.client;
+        if (entry.state.status === 'degraded') {
+            throw new errors_1.SessionRequestError(`Core sessions are unavailable for ${scope}: ${entry.degradedReason ?? 'repeated host failures'}`, { code: 'host_degraded', retryable: false });
+        }
+        if (entry.starting)
+            return entry.starting;
+        if (entry.state.status === 'ready') {
+            // The client closed before its close event was processed: count it as a failure.
+            this.fail(scope, entry, 'Session host connection closed');
+            if (this.status(scope) === 'degraded')
+                return this.acquire(scope);
+        }
+        if (entry.state.status === 'restarting') {
+            // A caller needs the host now: start immediately instead of waiting for the backoff timer.
+            entry.restartTimer?.cancel();
+            entry.restartTimer = null;
+            entry.state = (0, host_state_1.onRestartDue)(entry.state).state;
+        }
+        else if (entry.state.status === 'absent') {
+            entry.state = (0, host_state_1.onDemand)(entry.state).state;
+        }
+        return this.start(scope, entry);
+    }
+    /**
+     * Follow a session: its events are applied to `sink` and reported to
+     * `listener`. Survives host restarts (resume + replay from the sink cursor).
+     */
+    async track(scope, sessionId, sink, listener) {
+        const client = await this.acquire(scope);
+        const entry = this.entry(scope);
+        const tracked = entry.tracked.get(sessionId) ?? { sessionId, sink, listener, pump: null };
+        entry.tracked.set(sessionId, tracked);
+        tracked.pump?.detach();
+        tracked.pump = new session_event_pump_1.SessionEventPump(sessionId, client, sink, listener);
+        await tracked.pump.attach();
+        return tracked.pump;
+    }
+    untrack(scope, sessionId) {
+        const entry = this.scopes.get(scope);
+        const tracked = entry?.tracked.get(sessionId);
+        tracked?.pump?.detach();
+        entry?.tracked.delete(sessionId);
+    }
+    /** Manual retry of a degraded scope. */
+    async retry(scope) {
+        const entry = this.entry(scope);
+        const result = (0, host_state_1.onRetry)(entry.state);
+        if (result.decision.action !== 'start')
+            return;
+        entry.state = result.state;
+        entry.degradedReason = null;
+        entry.degradedCode = null;
+        await this.start(scope, entry);
+    }
+    /** Graceful stop of one scope (project removed). */
+    async stop(scope) {
+        const entry = this.scopes.get(scope);
+        if (!entry)
+            return;
+        entry.restartTimer?.cancel();
+        entry.state = (0, host_state_1.onStop)(entry.state);
+        for (const tracked of entry.tracked.values())
+            tracked.pump?.detach();
+        for (const unsubscribe of entry.unsubscribe.splice(0))
+            unsubscribe();
+        const client = entry.client ?? (entry.starting ? await entry.starting.catch(() => null) : null);
+        entry.client = null;
+        this.options.onStatus?.(scope, 'stopped');
+        if (client)
+            await client.close();
+        this.scopes.delete(scope);
+    }
+    /** App shutdown. */
+    async stopAll() {
+        this.stopped = true;
+        await Promise.allSettled([...this.scopes.keys()].map((scope) => this.stop(scope)));
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    entry(scope) {
+        let entry = this.scopes.get(scope);
+        if (!entry) {
+            entry = { state: host_state_1.INITIAL_HOST_STATE, client: null, starting: null, restartTimer: null, tracked: new Map(), unsubscribe: [], degradedReason: null, degradedCode: null };
+            this.scopes.set(scope, entry);
+        }
+        return entry;
+    }
+    isClosed(client) {
+        return client.closed === true;
+    }
+    start(scope, entry) {
+        this.options.onStatus?.(scope, 'starting');
+        entry.starting = (async () => {
+            try {
+                const client = await this.options.launcher.launch(scope);
+                if (entry.state.status === 'stopped') {
+                    await client.close();
+                    throw new errors_1.SessionRequestError('Scope stopped', { code: 'busy', retryable: false });
+                }
+                entry.client = client;
+                entry.state = (0, host_state_1.onReady)(entry.state);
+                this.wire(scope, entry, client);
+                this.options.onStatus?.(scope, 'ready');
+                await this.reattach(entry, client);
+                return client;
+            }
+            catch (error) {
+                if (entry.state.status !== 'stopped') {
+                    if ((0, errors_1.isSessionRequestError)(error) && FATAL_CODES.has(error.code))
+                        this.fatal(scope, entry, error.code, error.message);
+                    else
+                        this.fail(scope, entry, error.message);
+                }
+                throw error;
+            }
+            finally {
+                entry.starting = null;
+            }
+        })();
+        return entry.starting;
+    }
+    wire(scope, entry, client) {
+        for (const unsubscribe of entry.unsubscribe.splice(0))
+            unsubscribe();
+        entry.unsubscribe.push(client.onEvent((envelope) => { void entry.tracked.get(envelope.sessionId)?.pump?.push(envelope).catch((error) => this.options.onStatus?.(scope, entry.state.status, `projection failed: ${error.message}`)); }), client.onLagged((sessionId) => { void entry.tracked.get(sessionId)?.pump?.catchUp().catch(() => undefined); }), client.onClose((reason, code) => {
+            if (entry.client !== client || entry.state.status === 'stopped')
+                return;
+            entry.client = null;
+            if (code && FATAL_CODES.has(code))
+                this.fatal(scope, entry, code, reason);
+            else
+                this.fail(scope, entry, reason);
+        }));
+    }
+    /** After a (re)start: resume every tracked session and replay from its cursor. */
+    async reattach(entry, client) {
+        for (const tracked of entry.tracked.values()) {
+            tracked.pump?.detach();
+            try {
+                await client.request('session.open', { resume: { sessionId: tracked.sessionId } });
+            }
+            catch (error) {
+                // Closed sessions replay as history; a session Core never opened has nothing to resume.
+                if (!(error instanceof errors_1.SessionRequestError) || (error.code !== 'session_closed' && error.code !== 'session_not_found'))
+                    throw error;
+                if (error.code === 'session_not_found')
+                    continue;
+            }
+            tracked.pump = new session_event_pump_1.SessionEventPump(tracked.sessionId, client, tracked.sink, tracked.listener);
+            await tracked.pump.attach();
+        }
+    }
+    fatal(scope, entry, code, reason) {
+        const result = (0, host_state_1.onFatal)(entry.state, reason);
+        entry.state = result.state;
+        if (result.decision.action !== 'degrade')
+            return;
+        entry.restartTimer?.cancel();
+        entry.restartTimer = null;
+        entry.degradedReason = reason;
+        entry.degradedCode = code;
+        this.options.onStatus?.(scope, 'degraded', reason, code);
+    }
+    fail(scope, entry, reason) {
+        const result = (0, host_state_1.onFailure)(entry.state, this.options.clock.now(), this.options.policy ?? host_state_1.DEFAULT_SUPERVISION);
+        entry.state = result.state;
+        if (result.decision.action === 'degrade') {
+            entry.degradedReason = `${result.decision.reason}; last: ${reason}`;
+            this.options.onStatus?.(scope, 'degraded', entry.degradedReason);
+            return;
+        }
+        if (result.decision.action === 'restart') {
+            this.options.onStatus?.(scope, 'restarting', reason);
+            entry.restartTimer?.cancel();
+            entry.restartTimer = this.options.clock.after(result.decision.delayMs, () => {
+                entry.restartTimer = null;
+                const due = (0, host_state_1.onRestartDue)(entry.state);
+                entry.state = due.state;
+                if (due.decision.action === 'start')
+                    void this.start(scope, entry).catch(() => undefined);
+            });
+        }
+    }
+}
+exports.SessionHostRegistry = SessionHostRegistry;