@vibesdotdev/session 0.0.0-stage → 1.0.0-rc.2

package/dist/manager.js

@@ -0,0 +1,3029 @@
+/**
+ * Session Manager
+ * Core business logic for session management
+ *
+ * Responsibilities:
+ * - Session lifecycle management (create, resume, pause, archive)
+ * - TODO tracking with dependencies and hierarchies
+ * - Scratchpad operations with expiration
+ * - Job reference tracking
+ * - Participant messaging
+ * - Knowledge context integration
+ * - Participant identification and connection tracking
+ */
+import * as z from 'zod/v4';
+import { sha256Hex } from '@vibesdotdev/shared/hashing';
+import { CapabilityError, CaughtFailureSchema, settle, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getVibesClient } from '@vibesdotdev/kernel/client';
+import { JsonValueSchema as JsonSchema } from '@vibesdotdev/kernel/schemas/json';
+import { getLogger } from '@vibesdotdev/logging';
+import { StorageRecord } from '@vibesdotdev/storage/record';
+import { storageFailureCondition } from '@vibesdotdev/storage/record/failure-condition';
+import { ScratchpadContentTypeSchema } from "./schemas/index.js";
+import { HarnessSeatRegistrationSchema, HarnessSeatSchema, harnessSeatParticipantId, harnessSeatSlug } from "./schemas/harness-seat.js";
+import { ensureSessionContextWithManager, getOrCreateMCPParticipant, resolveParticipantReference, sanitizeSlugCandidate, scanParticipantsBySlug } from "./mcp/utils/participant.js";
+import { emitSessionBound } from "./events/session.bound.event.descriptor.js";
+const SESSION_STATE_LEGACY_KEY = 'session-state';
+const SESSION_STATE_DEFAULT_KEY = 'default';
+const SESSION_STATE_PARTICIPANT_PREFIX = 'participant:';
+const SESSION_STATE_MCP_PREFIX = 'mcp:';
+/** A participant seen within this window is active (the CLI roster uses the same window). */
+const PARTICIPANT_ACTIVE_WINDOW_MS = 5 * 60 * 1000;
+/** The runtime client id notifications register their delivery client under. */
+const NOTIFICATIONS_CLIENT_ID = 'notifications.delivery';
+/**
+ * Whether a storage write lost a unique-index race. LocalDB's driver classifies
+ * the collision on its typed refusal (`unique-constraint`); the adapter's text
+ * is never read. A conflict another adapter reports untyped is not recognised
+ * here and propagates (cross-lane: storage has no adapter-neutral conflict code).
+ */
+function isUniqueConstraintError(failure) {
+    return storageFailureCondition(failure) === 'unique-constraint';
+}
+/**
+ * Run `write`; when it fails with a failure `recoverable` admits, run
+ * `recover` instead. Any other failure of `write`, and a recovery that finds
+ * nothing (`null`), rethrows the write's own failure; a recovery that throws
+ * carries its own failure. The write's failure is never dropped.
+ */
+async function writeOrRecover(write, recover, recoverable) {
+    let lost;
+    const steps = [
+        write,
+        async () => {
+            if (!recoverable(CaughtFailureSchema.parse(lost)))
+                throw lost;
+            const recovered = await recover();
+            if (recovered === null)
+                throw lost;
+            return recovered;
+        }
+    ];
+    for (const step of steps) {
+        try {
+            return await step();
+        }
+        catch (error) {
+            lost = error;
+        }
+    }
+    throw lost;
+}
+/** Any write failure admits a recovery read (the recovery itself confirms the race). */
+function anyFailure() {
+    return true;
+}
+/** Decode JSON text; a parse failure is returned as a value with its cause, never thrown. */
+function decodeJson(text) {
+    try {
+        return { ok: true, value: JsonSchema.parse(JSON.parse(text)) };
+    }
+    catch (error) {
+        return { ok: false, cause: CaughtFailureSchema.parse(error) };
+    }
+}
+/** A persisted routing row's value: each field read independently; a non-string id is no id. */
+const RoutingValueSchema = z.object({
+    sessionId: z.string().nullable().optional().catch(undefined),
+    participantId: z.string().nullable().optional().catch(undefined)
+});
+/** The retired aggregate `session-state` row: each map entry is kept only when both sides are strings. */
+const StringMapSchema = z
+    .record(z.string(), z.unknown())
+    .optional()
+    .catch(undefined)
+    .transform((entries) => {
+    const kept = new Map();
+    for (const [key, value] of Object.entries(entries ?? {})) {
+        const parsed = z.string().safeParse(value);
+        if (parsed.success)
+            kept.set(key, parsed.data);
+    }
+    return kept;
+});
+const LegacySessionStateSchema = z.object({
+    participantSessions: StringMapSchema,
+    mcpSessions: StringMapSchema,
+    defaultSessionId: z.string().nullable().optional().catch(undefined),
+    defaultParticipantId: z.string().nullable().optional().catch(undefined)
+});
+/** Whether a decoded JSON value is an object (not an array or a scalar). */
+function isJsonObject(value) {
+    return Object(value) === value && !Array.isArray(value);
+}
+/** The list/search projection of one scratchpad entry. */
+function scratchpadSummaryOf(entry) {
+    return {
+        id: entry.id,
+        key: entry.key,
+        tags: entry.tags ?? [],
+        contentType: entry.contentType,
+        contentLength: entry.content?.length ?? 0,
+        preview: entry.content?.substring(0, 100) ?? '',
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+        language: entry.language,
+        expiresAt: entry.expiresAt
+    };
+}
+/** A typed `NOT_FOUND session-not-found` for a session id. */
+function sessionNotFound(sessionId) {
+    return new CapabilityError(`Session ${sessionId} not found`, 'NOT_FOUND', {
+        reason: 'session-not-found',
+        details: { kind: 'session', id: sessionId }
+    });
+}
+/** A typed `NOT_FOUND todo-not-found` for a todo id. */
+function todoNotFound(todoId) {
+    return new CapabilityError(`TODO ${todoId} not found`, 'NOT_FOUND', {
+        reason: 'todo-not-found',
+        details: { kind: 'session.todo', id: todoId }
+    });
+}
+/** A typed `CONFLICT session-not-writable` for a session that is paused or archived. */
+function sessionNotWritable(sessionId, status) {
+    return new CapabilityError(`Session ${sessionId} is ${status}; resume it explicitly before writing to it.`, 'CONFLICT', { reason: 'session-not-writable', details: { sessionId, status } });
+}
+/** Default todo order; the id tiebreak keeps the pages of an exhaustive scan stable. */
+const TODO_ORDER = { priority: 'desc', createdAt: 'asc', id: 'asc' };
+/** Page size of an exhaustive todo scan. */
+const TODO_SCAN_PAGE = 1000;
+/** A work item id as the todo record stores it. */
+const WorkItemIdSchema = z.string().min(1);
+/** Whether the filters carry a dependency predicate, which storage cannot evaluate. */
+function hasDependencyFilter(filters) {
+    return filters?.hasDependencies !== undefined || filters?.isBlocked !== undefined;
+}
+/** A storage search total: a finite count, or absent. */
+const SearchTotalSchema = z.number().int().nonnegative();
+/** The display fields a session summary reads from metadata; a non-string value is no value. */
+const SessionDisplayMetadataSchema = z.object({
+    workspacePath: z.string().optional().catch(undefined),
+    workItemTitle: z.string().optional().catch(undefined),
+    gitBranch: z.string().optional().catch(undefined)
+});
+/**
+ * Key-order-independent JSON so metadata comparison can't flake on insertion
+ * order: every object's keys are emitted sorted, arrays keep their order, and
+ * `undefined` encodes as `null`.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(value ?? null, (_key, nested) => sortedObjectKeys(nested));
+}
+/** An object (not an array) re-created with its own keys in sorted order; any other value unchanged. */
+function sortedObjectKeys(nested) {
+    if (Object(nested) !== nested || Array.isArray(nested))
+        return nested;
+    const entries = Object.entries(Object(nested));
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Object.fromEntries(entries);
+}
+/**
+ * Keep the indexed Work item id and its typed execution edge inseparable.
+ * A Work-linked todo always carries exactly one canonical work-item edge.
+ */
+export function normalizeTodoWorkLink(todo, options = {}) {
+    const workLinks = todo.links?.filter((link) => link.kind === 'work-item') ?? [];
+    if (todo.workItemId === undefined) {
+        if (workLinks.length > 0)
+            throw new Error('Todo work-item links require workItemId.');
+        return todo;
+    }
+    if (!options.rewriteExisting && workLinks.some((link) => link.id !== todo.workItemId)) {
+        throw new Error('Todo workItemId must match every work-item link.');
+    }
+    return {
+        ...todo,
+        links: [
+            ...(todo.links ?? []).filter((link) => link.kind !== 'work-item'),
+            { kind: 'work-item', id: todo.workItemId, source: 'session', role: 'executes' }
+        ]
+    };
+}
+/** Attach one authoritative checkout project edge to every Work-linked todo. */
+export function scopeTodoWorkLinks(todo, projectId) {
+    const normalized = normalizeTodoWorkLink(todo);
+    const workLinked = normalized.workItemId !== undefined ||
+        (normalized.links ?? []).some((link) => link.kind === 'work-item');
+    if (!workLinked)
+        return normalized;
+    if (!projectId) {
+        throw new CapabilityError('PROJECT_REF_UNBOUND: Work-linked session todos require a project-bound session', 'CONFLICT', {
+            reason: 'project-ref-unbound',
+            recoveryHint: 'Bind the session to a project or update the todo without Work links.',
+            details: { sessionProjectId: null, sessionCode: 'PROJECT_REF_UNBOUND' }
+        });
+    }
+    const projectLinks = (normalized.links ?? []).filter((link) => link.kind === 'project' && link.role === 'belongs-to');
+    const conflict = projectLinks.find((link) => link.id.toLowerCase() !== projectId.toLowerCase());
+    if (conflict) {
+        throw new CapabilityError(`PROJECT_REF_CONFLICT: todo is linked to ${conflict.id}, not session project ${projectId}`, 'CONFLICT', {
+            reason: 'project-ref-conflict',
+            recoveryHint: 'Ensure the todo project link matches the session project.',
+            details: {
+                sessionProjectId: projectId,
+                linkedProjectId: conflict.id,
+                sessionCode: 'PROJECT_REF_CONFLICT'
+            }
+        });
+    }
+    return {
+        ...normalized,
+        links: [
+            ...(normalized.links ?? []).filter((link) => !(link.kind === 'project' && link.role === 'belongs-to')),
+            {
+                kind: 'project',
+                id: projectId.toLowerCase(),
+                source: 'session.project-ref',
+                role: 'belongs-to'
+            }
+        ]
+    };
+}
+/**
+ * Does a durable row match the send a caller intended under the same
+ * deterministic id? Compares every caller-controlled field. A mismatch means
+ * the caller reused a batch identity for DIFFERENT content — that must
+ * surface as a conflict, never replay as a false "delivered".
+ */
+function messagePayloadMatches(existing, sessionId, intended) {
+    return (existing.sessionId === sessionId &&
+        existing.fromParticipant === intended.fromParticipant &&
+        existing.toParticipant === intended.toParticipant &&
+        existing.messageType === intended.messageType &&
+        existing.content === intended.content &&
+        canonicalJson(existing.metadata ?? {}) === canonicalJson(intended.metadata ?? {}));
+}
+const FIXTURE_PARTICIPANT_NAMES = new Set([
+    'senderx',
+    'betax',
+    'alphx',
+    'alpha',
+    'beta',
+    'ownerx',
+    'all',
+    'Durable owner',
+    'solox',
+    'everyone',
+    'realmember',
+    'stats-sender',
+    'stats-seat-b',
+    'stats-seat-a',
+    'activity-sender',
+    'ghostx',
+    'joinerx'
+]);
+const UUID_LIKE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isFixtureProfile(profile) {
+    if (FIXTURE_PARTICIPANT_NAMES.has(profile.name))
+        return true;
+    if (profile.participantId.startsWith('participant-') && profile.participantId.length > 12)
+        return true;
+    if (profile.metadata?.autoRegistered === true && UUID_LIKE_PATTERN.test(profile.name))
+        return true;
+    if (profile.name === 'MCP Participant')
+        return true;
+    return false;
+}
+/**
+ * SessionManager
+ * High-level API for session operations with business logic
+ *
+ * Uses storage descriptors for adapter-agnostic storage operations.
+ * Supports any compliant storage adapter (localdb, drizzle, etc.)
+ */
+export class SessionManager {
+    hostRuntime;
+    logger;
+    /** A stable manager keeps state while dependencies follow its caller's view. */
+    get runtime() { return this.hostRuntime.invocationRuntime; }
+    /** The runtime this manager serves (its caller's view): per-root transport state keys on its root. */
+    get servingRuntime() { return this.runtime; }
+    bindRuntime(runtime) {
+        this.hostRuntime = runtime;
+        this.logger = getLogger('session:manager', runtime);
+    }
+    initialized = false;
+    // Storage references (lazy initialized via ensureStorage)
+    sessionsStorage;
+    todosStorage;
+    scratchpadStorage;
+    jobsStorage;
+    messagesStorage;
+    participantsStorage;
+    presenceStorage;
+    knowledgeRefsStorage;
+    connectionsStorage;
+    membershipLeasesStorage;
+    // In-memory state
+    participantSessions = new Map();
+    mcpSessions = new Map(); // mcpSessionId -> vibesSessionId
+    defaultSessionId = null;
+    defaultParticipantId = null;
+    persistMappingsTail = Promise.resolve();
+    constructor(runtime) {
+        this.hostRuntime = runtime;
+        this.logger = getLogger('session:manager', runtime);
+    }
+    /**
+     * Resolve Session's participant/session policy through the registered
+     * manager context. Consumers do not import MCP participant internals.
+     */
+    async resolveContext(sessionId, participantId, mcpSessionId, options = {}) {
+        return ensureSessionContextWithManager(this, this.runtime, sessionId, participantId, mcpSessionId, options);
+    }
+    /** Identify this caller by UUID or slug, reusing Session's self-registration policy. */
+    async identifyParticipant(reference) {
+        const resolved = await resolveParticipantReference(reference, this, undefined, {
+            registerIfMissing: true
+        });
+        return resolved.participantId;
+    }
+    /** Resolve or create the caller's MCP participant under Session policy. */
+    async resolveMcpParticipant(options = {}, mcpSessionId, caller) {
+        return getOrCreateMCPParticipant(undefined, options, mcpSessionId, caller, this);
+    }
+    /** Commit and publish Session's canonical bound-session lifecycle event. */
+    async announceBound(sessionId, participantId, surface) {
+        await emitSessionBound({
+            runtime: this.runtime,
+            sessionId,
+            participantId,
+            surface
+        });
+    }
+    /**
+     * Ambient consumers need one stable session identity, not a private map
+     * guess. The durable default is the process' current binding and is cleared
+     * when that session is paused, archived, or deleted.
+     */
+    get activeSessionId() {
+        return this.defaultSessionId ?? undefined;
+    }
+    /**
+     * Resolve one `session.*` storage record through the runtime. A declared
+     * record whose implementation is not registered (the descriptor-only
+     * registration path) is bound directly to its descriptor; a record that is
+     * not declared at all is a typed NOT_FOUND. Every other resolution failure
+     * propagates unchanged.
+     */
+    async resolveStorageRecord(id) {
+        const selected = await this.runtime
+            .query('storage/record')
+            .withId(id)
+            .enabled()
+            .select();
+        if (selected)
+            return selected.impl;
+        const descriptor = this.runtime
+            .query('storage/record')
+            .withId(id)
+            .firstDescriptor();
+        if (!descriptor) {
+            throw new CapabilityError(`Storage record ${id} is not registered.`, 'NOT_FOUND', {
+                reason: 'not-registered',
+                details: { kind: 'storage/record', id }
+            });
+        }
+        return new StorageRecord(descriptor, { runtime: this.runtime });
+    }
+    async ensureStorage() {
+        if (this.sessionsStorage)
+            return; // Already initialized
+        const [sessions, todos, scratchpad, jobs, messages, participants, presence, knowledgeRefs, connections, membershipLeases] = await Promise.all([
+            this.resolveStorageRecord('session.sessions'),
+            this.resolveStorageRecord('session.todos'),
+            this.resolveStorageRecord('session.scratchpad'),
+            this.resolveStorageRecord('session.jobs'),
+            this.resolveStorageRecord('session.messages'),
+            this.resolveStorageRecord('session.participants'),
+            this.resolveStorageRecord('session.presence'),
+            this.resolveStorageRecord('session.knowledge-refs'),
+            this.resolveStorageRecord('session.connections'),
+            this.resolveStorageRecord('session.membership-leases')
+        ]);
+        this.sessionsStorage = sessions;
+        this.todosStorage = todos;
+        this.scratchpadStorage = scratchpad;
+        this.jobsStorage = jobs;
+        this.messagesStorage = messages;
+        this.participantsStorage = participants;
+        this.presenceStorage = presence;
+        this.knowledgeRefsStorage = knowledgeRefs;
+        this.connectionsStorage = connections;
+        this.membershipLeasesStorage = membershipLeases;
+    }
+    /**
+     * The notifications delivery client, or `undefined` when the composition
+     * does not provide one. Notifications are runtime-soft (SPEC): absence is
+     * confirmed by asking the runtime whether the client is declared, never by
+     * catching a failure. A declared client that fails to load propagates.
+     */
+    async resolveNotifications() {
+        const runtime = this.runtime;
+        if (!runtime.hasKind('runtime/client'))
+            return undefined;
+        const declared = await runtime
+            .query('runtime/client')
+            .withId(NOTIFICATIONS_CLIENT_ID)
+            .existsAsync();
+        if (!declared)
+            return undefined;
+        return getVibesClient(NOTIFICATIONS_CLIENT_ID, runtime);
+    }
+    /** A true COUNT over `where` — never a loaded page's length (ledger L-11). */
+    countRecords(storage, where) {
+        return storage.count(where);
+    }
+    async buildSessionSummary(session) {
+        await this.ensureStorage();
+        const [todoCount, completedTodoCount, scratchpadEntryCount, jobCount, messageCount, owner, assigned] = await Promise.all([
+            this.countRecords(this.todosStorage, { sessionId: session.id }),
+            this.countRecords(this.todosStorage, { sessionId: session.id, status: 'completed' }),
+            this.countRecords(this.scratchpadStorage, { sessionId: session.id }),
+            this.countRecords(this.jobsStorage, { sessionId: session.id }),
+            this.countRecords(this.messagesStorage, { sessionId: session.id }),
+            this.projectParticipant(session.ownerParticipant),
+            session.assignedParticipant
+                ? this.projectParticipant(session.assignedParticipant)
+                : Promise.resolve(undefined)
+        ]);
+        const workspaceRoot = this.nonEmptyMetadata(session, 'workspacePath');
+        const workItemTitle = this.nonEmptyMetadata(session, 'workItemTitle');
+        const gitBranch = this.nonEmptyMetadata(session, 'gitBranch');
+        return {
+            id: session.id,
+            title: session.title,
+            tags: session.tags ?? [],
+            status: session.status,
+            ownerParticipant: session.ownerParticipant,
+            assignedParticipant: session.assignedParticipant,
+            ownerParticipantId: session.ownerParticipant,
+            ownerParticipantSlug: owner?.slug,
+            ownerParticipantName: owner?.name,
+            assignedParticipantId: session.assignedParticipant,
+            assignedParticipantSlug: assigned?.slug,
+            assignedParticipantName: assigned?.name,
+            workItemId: session.workItemId,
+            workItemTitle,
+            workspaceRoot,
+            gitBranch,
+            worktree: workspaceRoot,
+            createdAt: session.createdAt,
+            lastActivityAt: session.lastActivityAt,
+            todoCount,
+            completedTodoCount,
+            scratchpadEntryCount,
+            jobCount,
+            messageCount
+        };
+    }
+    nonEmptyMetadata(session, key) {
+        const value = SessionDisplayMetadataSchema.parse(session.metadata ?? {})[key]?.trim();
+        return value ? value : undefined;
+    }
+    async projectParticipant(participantId) {
+        const profile = await this.getParticipant(participantId);
+        if (!profile)
+            return undefined;
+        const storedSlug = profile.metadata?.slug?.trim();
+        const slug = storedSlug
+            ? storedSlug.toLowerCase()
+            : profile.name
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9-]+/g, '-')
+                .replace(/-+/g, '-')
+                .replace(/^-+|-+$/g, '')
+                .slice(0, 64);
+        return { slug: slug || undefined, name: profile.name };
+    }
+    // LIFECYCLE
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Storage descriptors handle their own initialization
+        // No need to call storage.initialize()
+        await this.ensureStorage();
+        this.initialized = true;
+        await this.recoverActiveSession();
+    }
+    async close() {
+        await this.persistMappingsTail;
+        // Instances this host kept open stop heartbeating and expire on their TTL.
+        // Closing writes nothing: storage refuses new work while its runtime ends.
+        this.stopInstanceHeartbeat();
+        this.hostedInstances.clear();
+        // Storage descriptors handle their own cleanup
+        this.initialized = false;
+        this.participantSessions.clear();
+        this.mcpSessions.clear();
+        this.defaultSessionId = null;
+        this.defaultParticipantId = null;
+        // Clear storage references
+        this.sessionsStorage = undefined;
+        this.todosStorage = undefined;
+        this.scratchpadStorage = undefined;
+        this.jobsStorage = undefined;
+        this.messagesStorage = undefined;
+        this.participantsStorage = undefined;
+        this.presenceStorage = undefined;
+        this.knowledgeRefsStorage = undefined;
+        this.membershipLeasesStorage = undefined;
+        this.connectionsStorage = undefined;
+    }
+    /**
+     * Resolves `true` when session storage answers a query. Storage that cannot
+     * answer is a typed `UNAVAILABLE session-storage-unavailable` refusal
+     * carrying the storage failure, never a silent `false`.
+     */
+    async healthCheck() {
+        await this.ensureStorage();
+        try {
+            await this.sessionsStorage.list({ limit: 0 });
+        }
+        catch (error) {
+            throw new CapabilityError('Session storage is unavailable.', 'UNAVAILABLE', {
+                reason: 'session-storage-unavailable',
+                cause: error
+            });
+        }
+        return true;
+    }
+    // SESSIONS
+    /**
+     * Create a session. An active creation becomes the workspace's durable
+     * default unless `adoptAsDefault: false` — a per-native-session continuity
+     * row minted by an external-tool hook is not "the process' current binding"
+     * and must not retarget every later anonymous bind onto itself.
+     */
+    async createSession(session, options = {}) {
+        await this.ensureStorage();
+        const now = new Date();
+        const id = options.id === undefined ? undefined : z.uuid().parse(options.id);
+        if (id && (session.metadata?.source !== 'external-hook' || !session.metadata.nativeSessionId || !session.metadata.externalToolId)) {
+            throw new CapabilityError('An explicit continuity session id requires native identity.', 'INVALID_INPUT', { reason: 'session-native-identity-required' });
+        }
+        const write = () => this.sessionsStorage.create({
+            ...session,
+            id,
+            status: session.status ?? 'active',
+            scope: session.scope ?? 'project',
+            tags: session.tags ?? [],
+            metadata: session.metadata ?? {},
+            lastActivityAt: now
+        });
+        const created = id ? await writeOrRecover(write, async () => {
+            const existing = await this.sessionsStorage.get(id);
+            if (!existing || existing.ownerParticipant !== session.ownerParticipant ||
+                existing.metadata?.source !== session.metadata?.source ||
+                existing.metadata?.nativeSessionId !== session.metadata?.nativeSessionId ||
+                existing.metadata?.externalToolId !== session.metadata?.externalToolId ||
+                existing.metadata?.workspacePath !== session.metadata?.workspacePath)
+                return null;
+            return existing;
+        }, isUniqueConstraintError) : await write();
+        if (created.status === 'active') {
+            if (options.adoptAsDefault !== false) {
+                await this.setDefaultActiveSession(created.id);
+            }
+            await this.setParticipantActiveSession(created.ownerParticipant, created.id);
+            if (created.assignedParticipant) {
+                await this.setParticipantActiveSession(created.assignedParticipant, created.id);
+            }
+        }
+        return created;
+    }
+    async getSession(id) {
+        await this.ensureStorage();
+        return this.sessionsStorage.get(id);
+    }
+    async updateSession(id, updates) {
+        await this.ensureStorage();
+        const { parentSessionId, ...rest } = updates;
+        if (parentSessionId !== undefined)
+            await this.setSessionParent(id, parentSessionId);
+        await this.sessionsStorage.update(id, {
+            ...rest,
+            updatedAt: new Date()
+        });
+    }
+    /**
+     * Place a session under a parent session (a subsession), or make it top
+     * level with `null`. The parent must exist, and may not be the session itself
+     * or any of its descendants: a cycle is refused `INVALID_INPUT
+     * session-parent-cycle`.
+     */
+    async setSessionParent(sessionId, parentSessionId) {
+        await this.ensureStorage();
+        if (parentSessionId !== null) {
+            const seen = new Set();
+            for (let ancestor = parentSessionId; ancestor;) {
+                if (ancestor === sessionId || seen.has(ancestor)) {
+                    throw new CapabilityError('A session cannot be placed under itself or one of its own subsessions.', 'INVALID_INPUT', {
+                        reason: 'session-parent-cycle',
+                        details: { sessionId, parentSessionId }
+                    });
+                }
+                seen.add(ancestor);
+                const node = await this.sessionsStorage.get(ancestor);
+                if (!node && ancestor === parentSessionId) {
+                    throw new CapabilityError('The parent session does not exist.', 'NOT_FOUND', {
+                        reason: 'session-parent-not-found',
+                        details: { parentSessionId }
+                    });
+                }
+                // A dangling ancestor further up ends the chain; only the parent must exist.
+                ancestor = node?.parentSessionId;
+            }
+        }
+        await this.sessionsStorage.update(sessionId, { parentSessionId, updatedAt: new Date() });
+    }
+    /**
+     * Bump a session's activity clock to reflect real traffic (messages), so
+     * `lastActivityAt` tracks when the session was last USED — not merely when its
+     * record was created. Before this, `lastActivityAt` was stamped only at
+     * createSession, so a live session reads hours-stale while agents are actively
+     * messaging on it — a false "dark/idle" signal that mislead liveness reads.
+     * Best-effort: an activity touch must NEVER fail the underlying operation.
+     */
+    async touchSessionActivity(sessionId, at) {
+        const logger = getLogger('session:manager', this.runtime);
+        try {
+            await this.sessionsStorage.update(sessionId, { lastActivityAt: at });
+        }
+        catch (error) {
+            // Activity tracking is advisory; never break the caller on it — but a
+            // swallowed failure here leaves lastActivityAt silently stale, which
+            // reads as a false "idle" liveness signal. Report the value-free facts
+            // so the failure is observable without repeating storage text.
+            logger.warn('Failed to bump session lastActivityAt', {
+                sessionId,
+                error: valueFreeFailure(CaughtFailureSchema.parse(error))
+            });
+        }
+    }
+    async listSessions(filters) {
+        await this.ensureStorage();
+        const where = {};
+        if (filters?.status)
+            where.status = filters.status;
+        if (filters?.ownerParticipant)
+            where.ownerParticipant = filters.ownerParticipant;
+        const result = await this.sessionsStorage.list({
+            where,
+            orderBy: { lastActivityAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        return Promise.all(result.items.map((session) => this.buildSessionSummary(session)));
+    }
+    /**
+     * Count sessions matching the filter without pagination.
+     *
+     * Routines need a way to distinguish "this page is empty" from
+     * "the underlying set is empty," so this exposes the unfiltered
+     * count even when callers paginate via `listSessions`.
+     */
+    async countSessions(filters) {
+        await this.ensureStorage();
+        const where = {};
+        if (filters?.status)
+            where.status = filters.status;
+        if (filters?.ownerParticipant)
+            where.ownerParticipant = filters.ownerParticipant;
+        // True COUNT(*) — never a loaded page's length (ledger L-11).
+        return this.countRecords(this.sessionsStorage, where);
+    }
+    async getActiveSession() {
+        await this.ensureStorage();
+        const result = await this.sessionsStorage.list({
+            where: { status: 'active' },
+            orderBy: { lastActivityAt: 'desc' },
+            limit: 1
+        });
+        return result.items[0] ?? null;
+    }
+    /**
+     * Pause a specific session by id. Prefer this over pauseActiveSession when
+     * the caller has a concrete target (e.g. a UI selection): with more than one
+     * active session, "the active session" is ambiguous and pausing the wrong
+     * one is a real hazard.
+     */
+    async pauseSession(id) {
+        await this.ensureStorage();
+        await this.updateSession(id, { status: 'paused' });
+        // Keep participant and MCP mappings. Concurrent lanes share one manager;
+        // wiping bindings on pause is what made the next send unresolvable and
+        // forced a mint. Archive still clears mappings.
+        if (this.defaultSessionId === id) {
+            await this.setDefaultActiveSession(null);
+        }
+    }
+    /**
+     * Pause the active session and optionally create a new one
+     */
+    async pauseActiveSession() {
+        const active = await this.getActiveSession();
+        if (active) {
+            await this.pauseSession(active.id);
+        }
+    }
+    /**
+     * Resume a paused session (sets it to active)
+     */
+    async resumeSession(id) {
+        await this.ensureStorage();
+        if (!(await this.getSession(id)))
+            throw sessionNotFound(id);
+        // Several collaborations can be active at once. Pausing "the" current
+        // session here is what severed every other bound lane tonight.
+        await this.updateSession(id, { status: 'active' });
+        const resumed = await this.getSession(id);
+        if (!resumed) {
+            throw sessionNotFound(id);
+        }
+        await this.setDefaultActiveSession(resumed.id);
+        await this.setParticipantActiveSession(resumed.ownerParticipant, resumed.id);
+        if (resumed.assignedParticipant) {
+            await this.setParticipantActiveSession(resumed.assignedParticipant, resumed.id);
+        }
+        return resumed;
+    }
+    /**
+     * Open a session for bound work. Paused sessions resume in place.
+     * Archived sessions stay closed until the explicit resume action.
+     */
+    async openSessionForWork(sessionId) {
+        await this.ensureStorage();
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            throw sessionNotFound(sessionId);
+        }
+        if (session.status === 'archived') {
+            throw sessionNotWritable(sessionId, session.status);
+        }
+        if (session.status === 'paused') {
+            return this.resumeSession(sessionId);
+        }
+        return session;
+    }
+    /** Participant ids currently mapped to this session. */
+    async listBoundParticipantIds(sessionId) {
+        await this.ensureStorage();
+        const ids = [];
+        for (const [participantId, boundId] of this.participantSessions) {
+            if (boundId === sessionId)
+                ids.push(participantId);
+        }
+        return ids;
+    }
+    async releaseAllMembershipLeases(sessionId) {
+        const pageSize = 500;
+        const where = {
+            sessionId,
+            releasedAt: { isNull: true }
+        };
+        for (;;) {
+            const result = await this.membershipLeasesStorage.list({
+                where,
+                limit: pageSize,
+                offset: 0
+            });
+            if (result.items.length === 0)
+                return;
+            const releasedAt = new Date().toISOString();
+            await Promise.all(result.items.map((lease) => this.membershipLeasesStorage.update(lease.id, {
+                releasedAt,
+                activeConnectionKey: null
+            })));
+        }
+    }
+    async archiveSession(id) {
+        await this.ensureStorage();
+        await this.releaseAllMembershipLeases(id);
+        await this.sessionsStorage.update(id, {
+            status: 'archived',
+            archivedAt: new Date()
+        });
+        await this.clearMappingsForSession(id);
+        if (this.defaultSessionId === id) {
+            await this.setDefaultActiveSession(null);
+        }
+    }
+    async deleteSession(id) {
+        await this.ensureStorage();
+        await this.sessionsStorage.delete(id);
+        await this.clearMappingsForSession(id);
+        if (this.defaultSessionId === id) {
+            await this.setDefaultActiveSession(null);
+        }
+    }
+    async searchSessions(query, filters) {
+        const { results } = await this.searchSessionsPaged(query, filters);
+        return results;
+    }
+    /**
+     * Session search with true match total (L-11 class).
+     * Storage search already returns COUNT over MATCH+where before limit;
+     * discard-only wrappers were re-introducing page-as-total at CLI/MCP.
+     */
+    async searchSessionsPaged(query, filters) {
+        await this.ensureStorage();
+        const where = {};
+        if (filters?.status)
+            where.status = filters.status;
+        const result = await this.sessionsStorage.search(query, {
+            where,
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        const results = await Promise.all(result.items.map((session) => this.buildSessionSummary(session)));
+        // Prefer storage COUNT; never silently fall back to page length (L-31 advisory).
+        const total = SearchTotalSchema.safeParse(result.total);
+        if (!total.success) {
+            throw new CapabilityError('Session search returned no match total; a page length is not a match count.', 'INTERNAL', { reason: 'search-total-missing' });
+        }
+        return { results, total: total.data };
+    }
+    // SESSION HIERARCHY (Parent/Child Sessions)
+    /**
+     * Get child sessions for a parent session
+     */
+    async getChildSessions(parentSessionId) {
+        await this.ensureStorage();
+        const result = await this.sessionsStorage.list({
+            where: { parentSessionId },
+            limit: 1000
+        });
+        return result.items;
+    }
+    /**
+     * Get parent session if one exists
+     */
+    async getParentSession(childSessionId) {
+        await this.ensureStorage();
+        const child = await this.sessionsStorage.get(childSessionId);
+        if (!child || !child.parentSessionId) {
+            return null;
+        }
+        return this.sessionsStorage.get(child.parentSessionId);
+    }
+    /**
+     * Create a child session linked to a parent
+     */
+    async createChildSession(parentSessionId, session) {
+        await this.ensureStorage();
+        return this.createSession({
+            ...session,
+            parentSessionId
+        });
+    }
+    async createTodo(sessionId, todo) {
+        await this.ensureStorage();
+        const session = await this.sessionsStorage.get(sessionId);
+        if (!session)
+            throw sessionNotFound(sessionId);
+        const scopedTodo = scopeTodoWorkLinks(todo, session.projectId);
+        return this.todosStorage.create({
+            ...scopedTodo,
+            status: scopedTodo.status ?? 'pending',
+            priority: scopedTodo.priority ?? 'medium',
+            dependencies: scopedTodo.dependencies ?? [],
+            tags: scopedTodo.tags ?? [],
+            metadata: scopedTodo.metadata ?? {},
+            sessionId
+        });
+    }
+    /** Create once for one native todo identity; never overwrite another record. */
+    async ensureNativeTodo(sessionId, native, todo) {
+        await this.ensureStorage();
+        const identity = z.object({ tool: z.string().min(1), session: z.string().min(1), id: z.string().min(1) }).parse(native);
+        const session = await this.sessionsStorage.get(sessionId);
+        if (!session)
+            throw sessionNotFound(sessionId);
+        const scoped = scopeTodoWorkLinks(todo, session.projectId);
+        const hex = sha256Hex(JSON.stringify(['native-todo', sessionId, identity.tool, identity.session, identity.id])).slice(0, 32);
+        const variant = ((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16);
+        const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+        const metadata = { ...scoped.metadata, nativeTool: identity.tool, nativeSession: identity.session, nativeTodo: identity.id };
+        return writeOrRecover(() => this.todosStorage.create({
+            ...scoped, id, sessionId, metadata, status: scoped.status ?? 'pending', priority: scoped.priority ?? 'medium',
+            dependencies: scoped.dependencies ?? [], tags: scoped.tags ?? []
+        }), async () => {
+            const existing = await this.todosStorage.get(id);
+            return existing && existing.sessionId === sessionId && existing.metadata.nativeTool === identity.tool &&
+                existing.metadata.nativeSession === identity.session && existing.metadata.nativeTodo === identity.id ? existing : null;
+        }, isUniqueConstraintError);
+    }
+    /**
+     * Legacy alias retained for CLI compatibility.
+     */
+    addTodo(sessionId, todo) {
+        return this.createTodo(sessionId, todo);
+    }
+    async getTodo(id) {
+        await this.ensureStorage();
+        return this.todosStorage.get(id);
+    }
+    async updateTodo(id, updates) {
+        await this.ensureStorage();
+        const current = await this.todosStorage.get(id);
+        if (!current)
+            throw todoNotFound(id);
+        const session = await this.sessionsStorage.get(current.sessionId);
+        if (!session)
+            throw sessionNotFound(current.sessionId);
+        const merged = normalizeTodoWorkLink({ ...current, ...updates }, { rewriteExisting: updates.workItemId !== undefined });
+        const scoped = scopeTodoWorkLinks(merged, session.projectId);
+        const carriesWorkScope = scoped.workItemId !== undefined ||
+            (scoped.links ?? []).some((link) => link.kind === 'work-item' || (link.kind === 'project' && link.role === 'belongs-to'));
+        const persistedUpdates = { ...updates, updatedAt: new Date() };
+        if (carriesWorkScope) {
+            persistedUpdates.workItemId = scoped.workItemId;
+            persistedUpdates.links = scoped.links;
+        }
+        await this.todosStorage.update(id, persistedUpdates);
+    }
+    /**
+     * Legacy alias retained for CLI compatibility.
+     */
+    async completeTodo(id, updates = {}) {
+        await this.updateTodo(id, {
+            ...updates,
+            status: 'completed',
+            completedAt: new Date()
+        });
+        const todo = await this.todosStorage.get(id);
+        if (!todo)
+            throw todoNotFound(id);
+        return todo;
+    }
+    /**
+     * The storage filter for a session's todos. `tags` is exact all-of
+     * membership; `workItemId` is indexed. `hasDependencies`/`isBlocked` are
+     * not storage predicates: {@link scanTodosByDependency} applies them.
+     */
+    buildTodoWhere(sessionId, filters) {
+        const where = { sessionId };
+        if (filters?.status)
+            where.status = filters.status;
+        if (filters?.priority)
+            where.priority = filters.priority;
+        if (filters?.assignedParticipant)
+            where.assignedParticipant = filters.assignedParticipant;
+        if (filters?.workItemId)
+            where.workItemId = filters.workItemId;
+        if (filters?.tags !== undefined)
+            where.tags = { hasAll: filters.tags };
+        if (filters?.parentId !== undefined) {
+            where.parentId = filters.parentId === null ? { isNull: true } : filters.parentId;
+        }
+        return where;
+    }
+    async countTodos(sessionId, filters) {
+        await this.ensureStorage();
+        if (hasDependencyFilter(filters))
+            return (await this.scanTodosByDependency(sessionId, filters)).length;
+        return this.countRecords(this.todosStorage, this.buildTodoWhere(sessionId, filters));
+    }
+    async listTodos(sessionId, filters) {
+        await this.ensureStorage();
+        const limit = filters?.limit ?? 100;
+        const offset = filters?.offset ?? 0;
+        if (hasDependencyFilter(filters)) {
+            return (await this.scanTodosByDependency(sessionId, filters)).slice(offset, offset + limit);
+        }
+        return this.listTodoPage(this.buildTodoWhere(sessionId, filters), limit, offset);
+    }
+    /** One page of todos in the default order; the id tiebreak keeps successive pages stable. */
+    async listTodoPage(where, limit, offset) {
+        const result = await this.todosStorage.list({ where, orderBy: TODO_ORDER, limit, offset });
+        return result.items;
+    }
+    /** Every todo matching `where`, paged exhaustively (no row ceiling). */
+    async scanTodos(where) {
+        const all = [];
+        for (let offset = 0;; offset += TODO_SCAN_PAGE) {
+            const page = await this.listTodoPage(where, TODO_SCAN_PAGE, offset);
+            all.push(...page);
+            if (page.length < TODO_SCAN_PAGE)
+                return all;
+        }
+    }
+    /**
+     * The session's todos matching the storage filters and the dependency
+     * predicates, in the default order. Exhaustive, so callers page and count
+     * the full match set: `isBlocked` follows {@link computeTodo}.
+     */
+    async scanTodosByDependency(sessionId, filters) {
+        const scanned = await this.scanTodos(this.buildTodoWhere(sessionId, filters));
+        const known = new Map(scanned.map((todo) => [todo.id, todo.status]));
+        const matches = [];
+        for (const todo of scanned) {
+            if (filters.hasDependencies !== undefined && (todo.dependencies ?? []).length > 0 !== filters.hasDependencies)
+                continue;
+            if (filters.isBlocked !== undefined && (await this.incompleteDependencies(todo, known)).length > 0 !== filters.isBlocked)
+                continue;
+            matches.push(todo);
+        }
+        return matches;
+    }
+    /**
+     * The dependencies of `todo` not yet completed. A missing dependency row
+     * does not block; one absent from `known` (another session's todo)
+     * resolves through storage. The one blocked-dependency predicate.
+     */
+    async incompleteDependencies(todo, known) {
+        const incomplete = [];
+        for (const dependencyId of todo.dependencies ?? []) {
+            const status = known.has(dependencyId)
+                ? known.get(dependencyId)
+                : (await this.todosStorage.get(dependencyId))?.status;
+            if (status !== undefined && status !== 'completed')
+                incomplete.push(dependencyId);
+        }
+        return incomplete;
+    }
+    /**
+     * Every todo linked to a work item, across all sessions, most recently
+     * updated first. Exhaustive: the work-item trace reads it whole.
+     */
+    async listTodosForWorkItem(workItemId) {
+        await this.ensureStorage();
+        const parsed = WorkItemIdSchema.safeParse(workItemId);
+        if (!parsed.success) {
+            throw new CapabilityError('A work item id must be a non-empty string.', 'INVALID_INPUT', {
+                reason: 'work-item-id-invalid',
+                retryable: false
+            });
+        }
+        const id = parsed.data;
+        const all = [];
+        for (let offset = 0;; offset += TODO_SCAN_PAGE) {
+            const result = await this.todosStorage.list({
+                where: { workItemId: id },
+                orderBy: { updatedAt: 'desc', id: 'asc' },
+                limit: TODO_SCAN_PAGE,
+                offset
+            });
+            all.push(...result.items);
+            if (result.items.length < TODO_SCAN_PAGE)
+                return all;
+        }
+    }
+    async getTodoWithComputed(id) {
+        await this.ensureStorage();
+        const todo = await this.todosStorage.get(id);
+        return todo ? this.computeTodo(todo) : null;
+    }
+    async listTodosWithComputed(sessionId, filters) {
+        await this.ensureStorage();
+        const todos = await this.listTodos(sessionId, filters);
+        return Promise.all(todos.map((todo) => this.computeTodo(todo)));
+    }
+    /**
+     * A todo with its display fields computed from storage: the dependencies
+     * not yet completed (`blockedBy`; a missing dependency row does not block),
+     * its direct subtask counts, and progress (completed share of subtasks, or
+     * 0/100 by its own status when it has none).
+     */
+    async computeTodo(todo) {
+        const blockedBy = await this.incompleteDependencies(todo, new Map());
+        const [subtaskCount, completedSubtaskCount] = await Promise.all([
+            this.countRecords(this.todosStorage, { parentId: todo.id }),
+            this.countRecords(this.todosStorage, { parentId: todo.id, status: 'completed' })
+        ]);
+        const progress = subtaskCount > 0
+            ? Math.round((completedSubtaskCount / subtaskCount) * 100)
+            : todo.status === 'completed'
+                ? 100
+                : 0;
+        return {
+            ...todo,
+            isBlocked: blockedBy.length > 0,
+            blockedBy,
+            subtaskCount,
+            completedSubtaskCount,
+            progress
+        };
+    }
+    async deleteTodo(id) {
+        await this.ensureStorage();
+        await this.todosStorage.delete(id);
+    }
+    async getTodoHierarchy(parentId) {
+        await this.ensureStorage();
+        const result = await this.todosStorage.list({
+            where: { parentId },
+            limit: 100
+        });
+        return result.items;
+    }
+    /**
+     * Blocked means the todo's own explicit status — `status === 'blocked'`.
+     * A todo waiting on incomplete dependencies is a different, truthful state;
+     * ask {@link hasIncompleteDependencies} for that.
+     */
+    async isTodoBlocked(id) {
+        await this.ensureStorage();
+        const todo = await this.todosStorage.get(id);
+        return todo?.status === 'blocked';
+    }
+    /**
+     * True when the todo declares at least one dependency that is not yet
+     * completed. Reports dependency state only — it says nothing about the
+     * todo's own status (a completed todo with a stale incomplete dependency
+     * still answers true here).
+     */
+    async hasIncompleteDependencies(id) {
+        await this.ensureStorage();
+        const todo = await this.todosStorage.get(id);
+        return todo ? (await this.incompleteDependencies(todo, new Map())).length > 0 : false;
+    }
+    /**
+     * Get all root-level TODOs (no parent)
+     */
+    async getRootTodos(sessionId, filters) {
+        await this.ensureStorage();
+        return this.listTodos(sessionId, {
+            ...filters,
+            parentId: null
+        });
+    }
+    /**
+     * Get subtasks for a parent TODO
+     */
+    async getSubtasks(parentId) {
+        await this.ensureStorage();
+        const todo = await this.getTodo(parentId);
+        if (!todo)
+            return [];
+        return this.listTodos(todo.sessionId, {
+            parentId,
+            limit: 100,
+            offset: 0
+        });
+    }
+    // SCRATCHPAD
+    async writeScratchpad(sessionId, entry) {
+        await this.ensureStorage();
+        // (sessionId, key) is unique — a second write to the same key must replace
+        // the entry in place, not collide on the index.
+        const existing = await this.readScratchpad(sessionId, entry.key);
+        if (existing) {
+            return this.replaceScratchpadEntry(existing, entry);
+        }
+        // TOCTOU: a concurrent first write can land between the read above and
+        // this create. On a unique-index collision, replace the entry that won.
+        return writeOrRecover(() => this.scratchpadStorage.create({
+            ...entry,
+            tags: entry.tags ?? [],
+            metadata: entry.metadata ?? {},
+            sessionId
+        }), async () => {
+            const winner = await this.readScratchpad(sessionId, entry.key);
+            return winner ? this.replaceScratchpadEntry(winner, entry) : null;
+        }, isUniqueConstraintError);
+    }
+    /**
+     * Replace an existing scratchpad entry with a fresh write.
+     *
+     * A write is a full replace, not a merge: every ScratchpadEntryCreate field
+     * is passed explicitly with the create-branch defaults, so omitted optional
+     * fields (tags/metadata/expiresAt/language) reset instead of silently
+     * inheriting the previous entry's values. Only id and createdAt survive.
+     */
+    async replaceScratchpadEntry(existing, entry) {
+        await this.scratchpadStorage.update(existing.id, {
+            content: entry.content,
+            contentType: entry.contentType,
+            language: entry.language,
+            tags: entry.tags ?? [],
+            metadata: entry.metadata ?? {},
+            expiresAt: entry.expiresAt,
+            updatedAt: new Date()
+        });
+        return (await this.scratchpadStorage.get(existing.id)) ?? existing;
+    }
+    async readScratchpad(sessionId, key) {
+        await this.ensureStorage();
+        const result = await this.scratchpadStorage.list({
+            where: { sessionId, key },
+            limit: 1
+        });
+        return result.items[0] ?? null;
+    }
+    async getScratchpadEntry(id) {
+        await this.ensureStorage();
+        return this.scratchpadStorage.get(id);
+    }
+    async updateScratchpadEntry(id, updates) {
+        await this.ensureStorage();
+        await this.scratchpadStorage.update(id, {
+            ...updates,
+            updatedAt: new Date()
+        });
+    }
+    buildScratchpadWhere(sessionId, filters) {
+        const where = { sessionId };
+        if (filters?.contentType)
+            where.contentType = filters.contentType;
+        return where;
+    }
+    async countScratchpad(sessionId, filters) {
+        await this.ensureStorage();
+        return this.countRecords(this.scratchpadStorage, this.buildScratchpadWhere(sessionId, filters));
+    }
+    async listScratchpad(sessionId, filters) {
+        await this.ensureStorage();
+        const where = this.buildScratchpadWhere(sessionId, filters);
+        const result = await this.scratchpadStorage.list({
+            where,
+            orderBy: { createdAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        return result.items.map(scratchpadSummaryOf);
+    }
+    async deleteScratchpadEntry(id) {
+        await this.ensureStorage();
+        await this.scratchpadStorage.delete(id);
+    }
+    async cleanupExpiredScratchpad() {
+        await this.ensureStorage();
+        // expiresAt is persisted as an ISO string; storage encodes a Date filter
+        // operand as ISO text (ISO strings order lexicographically = temporally).
+        const result = await this.scratchpadStorage.list({
+            where: { expiresAt: { lt: new Date() } },
+            limit: 1000
+        });
+        // Delete them
+        for (const entry of result.items) {
+            await this.scratchpadStorage.delete(entry.id);
+        }
+        return result.items.length;
+    }
+    async searchScratchpad(sessionId, query, filters) {
+        await this.ensureStorage();
+        const where = this.buildScratchpadWhere(sessionId, filters);
+        const result = await this.scratchpadStorage.search(query, {
+            where,
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        // Convert to summary format; total is the true FTS match count from the
+        // storage layer, not the returned page length (ledger L-11).
+        return {
+            items: result.items.map(scratchpadSummaryOf),
+            total: result.total ?? result.items.length
+        };
+    }
+    // JOBS
+    async addJobRef(sessionId, job) {
+        await this.ensureStorage();
+        return this.jobsStorage.create({
+            ...job,
+            status: job.status ?? 'pending',
+            metadata: job.metadata ?? {},
+            sessionId
+        });
+    }
+    async getJobRef(id) {
+        await this.ensureStorage();
+        return this.jobsStorage.get(id);
+    }
+    async getJobRefByJobId(jobId) {
+        await this.ensureStorage();
+        const result = await this.jobsStorage.list({
+            where: { jobId },
+            limit: 1
+        });
+        return result.items[0] ?? null;
+    }
+    async updateJobRef(id, updates) {
+        await this.ensureStorage();
+        await this.jobsStorage.update(id, updates);
+    }
+    buildJobWhere(sessionId, filters) {
+        const where = { sessionId };
+        if (filters?.status)
+            where.status = filters.status;
+        if (filters?.jobType)
+            where.jobType = filters.jobType;
+        return where;
+    }
+    async countJobRefs(sessionId, filters) {
+        await this.ensureStorage();
+        return this.countRecords(this.jobsStorage, this.buildJobWhere(sessionId, filters));
+    }
+    async getJobRefs(sessionId, filters) {
+        await this.ensureStorage();
+        // Shared with countJobRefs so list and count cannot drift.
+        const where = this.buildJobWhere(sessionId, filters);
+        const result = await this.jobsStorage.list({
+            where,
+            orderBy: { createdAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        // Convert to summary format
+        return result.items.map((job) => ({
+            id: job.id,
+            jobId: job.jobId,
+            jobType: job.jobType,
+            queueName: job.queueName,
+            description: job.description,
+            status: job.status,
+            progress: job.progress,
+            createdAt: job.createdAt,
+            completedAt: job.completedAt
+        }));
+    }
+    async deleteJobRef(id) {
+        await this.ensureStorage();
+        await this.jobsStorage.delete(id);
+    }
+    // MESSAGES
+    async sendMessage(sessionId, message) {
+        await this.ensureStorage();
+        const now = new Date();
+        const saved = await this.messagesStorage.create({
+            ...message,
+            attachments: message.attachments ?? [],
+            metadata: message.metadata ?? {},
+            sessionId,
+            isRead: false
+        });
+        await this.touchSessionActivity(sessionId, now);
+        if (message.fromParticipant)
+            await this.touchParticipantLastSeen(message.fromParticipant);
+        if (message.toParticipant)
+            await this.notifyUnread(sessionId, message.toParticipant);
+        return saved;
+    }
+    /**
+     * Advisory: bump the sender's lastSeen on a send. A failure never fails
+     * the send; it is reported with value-free facts.
+     */
+    async touchParticipantLastSeen(participantId) {
+        const logger = getLogger('session:manager', this.runtime);
+        try {
+            await this.updateParticipantLastSeen(participantId);
+        }
+        catch (error) {
+            logger.warn('Failed to update participant lastSeen on message send', {
+                participantId,
+                error: valueFreeFailure(CaughtFailureSchema.parse(error))
+            });
+        }
+    }
+    /**
+     * Runtime-soft (SPEC): fan an unread-count notice out through the
+     * notifications client at the 1st, 5th and 10th unread message. A
+     * composition without notifications is confirmed absent and skipped; any
+     * other failure never fails the send and is reported with value-free facts.
+     */
+    async notifyUnread(sessionId, toParticipant) {
+        const logger = getLogger('session:manager', this.runtime);
+        try {
+            const notifications = await this.resolveNotifications();
+            if (!notifications)
+                return;
+            const unreadCount = await this.getUnreadCount(sessionId, toParticipant);
+            if (unreadCount !== 1 && unreadCount !== 5 && unreadCount !== 10)
+                return;
+            // ParticipantProfile is keyed by participantId — route notifications to
+            // that identity; consumers map participantId → user id out-of-band.
+            const participant = await this.getParticipant(toParticipant);
+            if (!participant)
+                return;
+            const plural = unreadCount > 1 ? 's' : '';
+            await notifications.send({
+                userId: participant.participantId,
+                channel: 'in-app',
+                priority: unreadCount >= 10 ? 'high' : 'normal',
+                title: `${unreadCount} unread message${plural} in session`,
+                body: `You have ${unreadCount} unread message${plural} waiting.`,
+                actionUrl: `/sessions/${sessionId}`
+            });
+        }
+        catch (error) {
+            logger.warn('Unread-message notification failed; the message was delivered', {
+                sessionId,
+                error: valueFreeFailure(CaughtFailureSchema.parse(error))
+            });
+        }
+    }
+    /**
+     * Exactly-once send keyed on a caller-supplied deterministic id.
+     *
+     * A batch retry after a mid-batch failure re-sends entries whose first
+     * attempt may or may not have persisted. With a stable per-entry id the
+     * replayed create collides on the primary key instead of duplicating;
+     * the existing row is returned with `replay: true` and the side effects
+     * (activity bump, notification) are not re-fired.
+     *
+     * On ANY failure — not only a unique-constraint collision — durable state
+     * is consulted by the deterministic id: a row can persist and a LATER
+     * effect inside sendMessage throw, and classifying that schedule as
+     * "failed" would make the receipt deny a delivery that exists. And a
+     * found row only counts as a replay when its payload MATCHES the intended
+     * send: the same id with different content/recipient is a caller bug that
+     * must surface as a CONFLICT, never as a silent old-row "delivery".
+     */
+    async sendMessageIdempotent(sessionId, message) {
+        await this.ensureStorage();
+        return writeOrRecover(async () => ({ message: await this.sendMessage(sessionId, message), replay: false }), async () => {
+            const existing = await this.messagesStorage.get(message.id);
+            if (!existing)
+                return null;
+            if (!messagePayloadMatches(existing, sessionId, message)) {
+                throw new CapabilityError(`Idempotency conflict: message ${message.id} already exists with a different payload — a retry must not change recipient, type, content, or metadata under the same batch identity.`, 'CONFLICT', {
+                    reason: 'batch-idempotency-conflict',
+                    retryable: false,
+                    recoveryHint: 'Retry a failed batch with the SAME entries, or use a new batchId for changed content.',
+                    details: {
+                        kind: 'BATCH_IDEMPOTENCY_CONFLICT',
+                        messageId: message.id,
+                        storedToParticipant: existing.toParticipant,
+                        intendedToParticipant: message.toParticipant
+                    }
+                });
+            }
+            return { message: existing, replay: true };
+        }, anyFailure);
+    }
+    async getMessage(id) {
+        await this.ensureStorage();
+        return this.messagesStorage.get(id);
+    }
+    buildMessageWhere(sessionId, filters) {
+        const where = { sessionId };
+        if (filters?.fromParticipant)
+            where.fromParticipant = filters.fromParticipant;
+        if (filters?.toParticipant)
+            where.toParticipant = filters.toParticipant;
+        if (filters?.isRead !== undefined)
+            where.isRead = filters.isRead;
+        return where;
+    }
+    async countMessages(sessionId, filters) {
+        await this.ensureStorage();
+        return this.countRecords(this.messagesStorage, this.buildMessageWhere(sessionId, filters));
+    }
+    async getMessages(sessionId, filters) {
+        await this.ensureStorage();
+        // Shared with countMessages so list and count cannot drift.
+        const where = this.buildMessageWhere(sessionId, filters);
+        const result = await this.messagesStorage.list({
+            where,
+            orderBy: { createdAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        return result.items;
+    }
+    async markMessageRead(id) {
+        await this.ensureStorage();
+        await this.messagesStorage.update(id, {
+            isRead: true,
+            readAt: new Date()
+        });
+    }
+    async markAllMessagesRead(sessionId, toParticipant) {
+        await this.ensureStorage();
+        // Drain the WHOLE unread backlog in pages. A single capped list silently
+        // stopped at 1000 and reported the cap as the full count (ledger L-11);
+        // marking rows read removes them from the isRead:false filter, so
+        // re-listing page 0 walks the backlog to a true zero.
+        const PAGE_SIZE = 1000;
+        let marked = 0;
+        while (true) {
+            const result = await this.messagesStorage.list({
+                where: { sessionId, toParticipant, isRead: false },
+                limit: PAGE_SIZE
+            });
+            if (result.items.length === 0)
+                break;
+            const now = new Date();
+            for (const message of result.items) {
+                await this.messagesStorage.update(message.id, {
+                    isRead: true,
+                    readAt: now
+                });
+            }
+            marked += result.items.length;
+            if (result.items.length < PAGE_SIZE)
+                break;
+        }
+        return marked;
+    }
+    async deleteMessage(id) {
+        await this.ensureStorage();
+        await this.messagesStorage.delete(id);
+    }
+    async getUnreadCount(sessionId, toParticipant) {
+        // A true count — not the length of a capped page. A busy inbox past any
+        // page ceiling must still report its real backlog.
+        return this.countMessages(sessionId, { toParticipant, isRead: false });
+    }
+    // PARTICIPANTS
+    async registerParticipant(profile) {
+        await this.ensureStorage();
+        const now = new Date();
+        return this.participantsStorage.create({
+            ...profile,
+            capabilities: profile.capabilities ?? [],
+            preferences: profile.preferences ?? {},
+            metadata: profile.metadata ?? {},
+            lastSeenAt: now
+        });
+    }
+    async getParticipant(participantId) {
+        await this.ensureStorage();
+        return this.participantsStorage.get(participantId);
+    }
+    async getParticipantByConnection(connectionId) {
+        await this.ensureStorage();
+        // Find connection and get associated participant
+        const connection = await this.connectionsStorage.get(connectionId);
+        if (!connection)
+            return null;
+        if (!connection.participantId)
+            return null;
+        return this.participantsStorage.get(connection.participantId);
+    }
+    async updateParticipant(participantId, updates) {
+        await this.ensureStorage();
+        await this.participantsStorage.update(participantId, updates);
+    }
+    /**
+     * The seat for one harness conversation, read-only. See
+     * `schemas/harness-seat.ts`: the id is derived, so this is a point read.
+     */
+    async findHarnessSeat(seat) {
+        return this.getParticipant(harnessSeatParticipantId(HarnessSeatSchema.parse(seat)));
+    }
+    /**
+     * The seat for one harness conversation, registered on first sight. The
+     * harness hook and the MCP connection both call this, so they converge on
+     * one participant whichever arrives first. The seat's identity (agent,
+     * harness session, slug) is written onto rows registered before it was.
+     */
+    async ensureHarnessSeat(input) {
+        const registration = HarnessSeatRegistrationSchema.parse(input);
+        const seat = { agentId: registration.agentId, harnessSessionId: registration.harnessSessionId };
+        const participantId = harnessSeatParticipantId(seat);
+        const slug = harnessSeatSlug(seat);
+        const identity = { agentId: seat.agentId, harnessSessionId: seat.harnessSessionId };
+        let existing = await this.getParticipant(participantId);
+        if (!existing) {
+            // The hook and the MCP connection of one conversation can race the
+            // create; the re-read confirms the race — the derived row must exist.
+            const outcome = await writeOrRecover(async () => ({
+                created: true,
+                profile: await this.registerParticipant({
+                    participantId,
+                    name: registration.name ?? seat.agentId,
+                    role: 'assistant',
+                    capabilities: registration.capabilities ?? ['session-management'],
+                    metadata: {
+                        source: registration.source ?? 'harness',
+                        slug,
+                        clientInfo: { name: registration.name ?? seat.agentId, ...identity }
+                    }
+                })
+            }), async () => {
+                const raced = await this.getParticipant(participantId);
+                return raced ? { created: false, profile: raced } : null;
+            }, anyFailure);
+            if (outcome.created)
+                return outcome.profile;
+            existing = outcome.profile;
+        }
+        const metadata = existing.metadata ?? {};
+        const clientInfo = metadata.clientInfo;
+        if (metadata.slug === slug &&
+            clientInfo?.agentId === identity.agentId &&
+            clientInfo?.harnessSessionId === identity.harnessSessionId) {
+            return existing;
+        }
+        const updated = {
+            ...metadata,
+            slug,
+            clientInfo: { name: existing.name, ...clientInfo, ...identity }
+        };
+        await this.updateParticipant(participantId, { metadata: updated });
+        return { ...existing, metadata: updated };
+    }
+    async updateParticipantLastSeen(participantId) {
+        await this.ensureStorage();
+        await this.participantsStorage.update(participantId, {
+            lastSeenAt: new Date()
+        });
+    }
+    async listParticipants(filters) {
+        await this.ensureStorage();
+        const where = {};
+        // `active` (legacy alias `isActive`): last seen within the activity window.
+        const active = filters?.active ?? filters?.isActive;
+        if (active !== undefined) {
+            const threshold = new Date(Date.now() - PARTICIPANT_ACTIVE_WINDOW_MS);
+            where.lastSeenAt = active ? { gte: threshold } : { lt: threshold };
+        }
+        if (filters?.role !== undefined) {
+            where.role = filters.role;
+        }
+        if (filters?.search !== undefined && filters.search.trim().length > 0) {
+            where.name = { contains: filters.search.trim() };
+        }
+        if (filters?.after !== undefined) {
+            if (filters.orderBy !== 'stable') {
+                throw new CapabilityError('A participant keyset cursor pages only the stable order.', 'INVALID_INPUT', {
+                    reason: 'participant-cursor-unordered',
+                    retryable: false
+                });
+            }
+            where.participantId = { gt: filters.after };
+        }
+        const result = await this.participantsStorage.list({
+            where,
+            // 'stable' = participantId asc (immutable, unique) so paged
+            // enumerations cannot skip/double-visit rows when lastSeenAt moves
+            // mid-scan (ledger L-19). Default stays recency for display callers.
+            orderBy: filters?.orderBy === 'stable' ? { participantId: 'asc' } : { lastSeenAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        return result.items;
+    }
+    async deleteParticipant(participantId) {
+        await this.ensureStorage();
+        await this.participantsStorage.delete(participantId);
+    }
+    async pruneStaleSessionMappings() {
+        await this.ensureStorage();
+        const staleKeys = [];
+        // A storage failure reading a session propagates: an unreadable store
+        // is not proof the session is gone, and pruning on it would drop live
+        // mappings wholesale.
+        for (const [participantId, sessionId] of this.participantSessions) {
+            const session = await this.sessionsStorage.get(sessionId);
+            if (!session || session.status === 'archived') {
+                staleKeys.push(participantId);
+            }
+        }
+        for (const key of staleKeys) {
+            this.participantSessions.delete(key);
+        }
+        if (staleKeys.length > 0) {
+            await Promise.all(staleKeys.map((key) => this.deleteRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${key}`)));
+        }
+        return {
+            prunedEntries: staleKeys.length,
+            remainingEntries: this.participantSessions.size,
+            prunedKeys: staleKeys
+        };
+    }
+    async pruneOrphanedParticipantProfiles() {
+        await this.ensureStorage();
+        const activeSessionIds = new Set();
+        const activeSessions = await this.listSessions({ status: 'active', limit: 10000 });
+        for (const s of activeSessions)
+            activeSessionIds.add(s.id);
+        const pausedSessions = await this.listSessions({ status: 'paused', limit: 10000 });
+        for (const s of pausedSessions)
+            activeSessionIds.add(s.id);
+        const protectedIds = new Set();
+        for (const s of activeSessions) {
+            if (s.ownerParticipant)
+                protectedIds.add(s.ownerParticipant);
+            if (s.assignedParticipant)
+                protectedIds.add(s.assignedParticipant);
+        }
+        for (const s of pausedSessions) {
+            if (s.ownerParticipant)
+                protectedIds.add(s.ownerParticipant);
+            if (s.assignedParticipant)
+                protectedIds.add(s.assignedParticipant);
+        }
+        for (const [participantId, sessionId] of this.participantSessions) {
+            if (activeSessionIds.has(sessionId))
+                protectedIds.add(participantId);
+        }
+        const messageParticipants = new Set();
+        try {
+            const PAGE = 500;
+            let msgOffset = 0;
+            for (;;) {
+                const msgPage = await this.messagesStorage.list({ limit: PAGE, offset: msgOffset });
+                for (const msg of msgPage.items) {
+                    if (activeSessionIds.has(msg.sessionId)) {
+                        if (msg.fromParticipant)
+                            messageParticipants.add(msg.fromParticipant);
+                        if (msg.toParticipant)
+                            messageParticipants.add(msg.toParticipant);
+                    }
+                }
+                if (msgPage.items.length < PAGE)
+                    break;
+                msgOffset += msgPage.items.length;
+            }
+        }
+        catch (error) {
+            throw new CapabilityError('Cannot safely prune participant profiles: message scan failed. A prune without full protection data is unsafe.', 'UNAVAILABLE', { reason: 'prune-protection-scan-failed', cause: error });
+        }
+        for (const pid of messageParticipants)
+            protectedIds.add(pid);
+        const prunedIds = [];
+        let totalProcessed = 0;
+        let offset = 0;
+        const PAGE_SIZE = 100;
+        while (true) {
+            const result = await this.participantsStorage.list({
+                orderBy: { participantId: 'asc' },
+                limit: PAGE_SIZE,
+                offset
+            });
+            if (result.items.length === 0)
+                break;
+            for (const profile of result.items) {
+                totalProcessed++;
+                if (!isFixtureProfile(profile))
+                    continue;
+                if (protectedIds.has(profile.participantId))
+                    continue;
+                prunedIds.push(profile.participantId);
+            }
+            offset += result.items.length;
+            if (result.items.length < PAGE_SIZE)
+                break;
+        }
+        // A failed delete propagates: reporting it as pruned would be false.
+        for (const id of prunedIds) {
+            await this.participantsStorage.delete(id);
+        }
+        return {
+            prunedProfiles: prunedIds.length,
+            remainingProfiles: totalProcessed - prunedIds.length,
+            protectedCount: protectedIds.size,
+            prunedIds
+        };
+    }
+    async recordConnection(connection) {
+        await this.ensureStorage();
+        const now = new Date();
+        const existing = await this.connectionsStorage.get(connection.connectionId);
+        if (existing) {
+            const updated = {
+                ...connection,
+                connectedAt: now,
+                disconnectedAt: null
+            };
+            await this.connectionsStorage.update(connection.connectionId, updated);
+            return { ...existing, ...updated };
+        }
+        return writeOrRecover(() => this.connectionsStorage.create({
+            ...connection,
+            connectedAt: now,
+            disconnectedAt: undefined
+        }), async () => {
+            await this.connectionsStorage.update(connection.connectionId, {
+                ...connection,
+                connectedAt: now,
+                disconnectedAt: null
+            });
+            return this.connectionsStorage.get(connection.connectionId);
+        }, isUniqueConstraintError);
+    }
+    async closeConnection(connectionId) {
+        await this.ensureStorage();
+        await this.connectionsStorage.update(connectionId, {
+            disconnectedAt: new Date()
+        });
+    }
+    // INSTANCES
+    //
+    // One `session.connections` row per running instance, whatever surface it
+    // came through. Live = not disconnected and `expiresAt` in the future. Every
+    // admitted call touches its instance; a host that keeps a seat open while
+    // idle registers it `hosted`, and this manager heartbeats hosted instances
+    // until it closes them. A crashed host's instances simply expire.
+    static INSTANCE_TTL_MS = 10 * 60 * 1000;
+    static INSTANCE_HEARTBEAT_MS = 60 * 1000;
+    /** Touches inside this window are not rewritten: one write per instance per window. */
+    static INSTANCE_TOUCH_MIN_MS = 30 * 1000;
+    static INSTANCE_HANDLE_ATTEMPTS = 6;
+    /** This host's own key: distinguishes its in-process seats from another host's. */
+    hostKey = crypto.randomUUID();
+    hostedInstances = new Set();
+    instanceTouchedAt = new Map();
+    /** Handles of instances this host registered, so a touch need not reread them. */
+    instanceHandles = new Map();
+    /** (instance, session, participant) triples this host has already leased. */
+    instanceMemberships = new Set();
+    instanceHeartbeat;
+    static isLiveInstance(row, nowIso) {
+        const expiresAt = row.expiresAt instanceof Date ? row.expiresAt.toISOString() : row.expiresAt;
+        return !row.disconnectedAt && expiresAt != null && String(expiresAt) >= nowIso;
+    }
+    static randomHandle(base) {
+        const alphabet = 'abcdefghjkmnpqrstuvwxyz23456789';
+        const bytes = crypto.getRandomValues(new Uint8Array(4));
+        const suffix = Array.from(bytes, (byte) => alphabet[byte % alphabet.length]).join('');
+        return `${sanitizeSlugCandidate(base).slice(0, 48)}-${suffix}`;
+    }
+    /**
+     * Register (or re-register) a running instance and give it a handle. A
+     * chosen handle held by another LIVE instance is refused `CONFLICT
+     * instance-handle-taken` naming the holder; one held by an expired or closed
+     * instance is reclaimed. With no choice the instance keeps its live handle,
+     * else gets a random `<agent>-<4>` handle. Uniqueness is the storage index
+     * on `activeHandle`, not this check: a lost race is retried (random) or
+     * refused (chosen).
+     */
+    async registerInstance(input) {
+        await this.ensureStorage();
+        const storage = this.connectionsStorage;
+        const now = Date.now();
+        const nowAt = new Date(now);
+        const nowIso = nowAt.toISOString();
+        const expiresAt = new Date(now + SessionManager.INSTANCE_TTL_MS);
+        const existing = await storage.get(input.instanceId);
+        const chosen = input.handle?.trim() ? sanitizeSlugCandidate(input.handle) : undefined;
+        // A live handle resolves ahead of participant slugs, so a chosen handle may
+        // not be another participant's name: that would capture its messages.
+        if (chosen) {
+            const named = (await scanParticipantsBySlug(this, chosen)).match;
+            const actsAs = input.participantId ?? existing?.participantId;
+            if (named && named.participantId !== actsAs) {
+                throw new CapabilityError(`The handle "${chosen}" is another participant's name.`, 'CONFLICT', {
+                    reason: 'instance-handle-names-participant',
+                    details: { handle: chosen, participantId: named.participantId },
+                    recoveryHint: 'Choose a handle that is not an existing participant\'s name.'
+                });
+            }
+        }
+        const kept = existing && SessionManager.isLiveInstance(existing, nowIso) ? existing.activeHandle ?? undefined : undefined;
+        const base = input.agentId ?? input.harness ?? input.clientName;
+        const fields = {
+            participantId: input.participantId ?? existing?.participantId,
+            clientName: input.clientName,
+            clientVersion: input.clientVersion,
+            hostname: input.hostname,
+            platform: input.platform,
+            workingDirectory: input.workingDirectory,
+            transport: input.transport,
+            agentId: input.agentId,
+            harness: input.harness,
+            harnessSessionId: input.harnessSessionId,
+            lastHeartbeatAt: nowAt,
+            expiresAt,
+            disconnectedAt: null
+        };
+        for (let attempt = 0; attempt < SessionManager.INSTANCE_HANDLE_ATTEMPTS; attempt++) {
+            const handle = chosen ?? (attempt === 0 && kept ? kept : SessionManager.randomHandle(base));
+            if (handle !== existing?.activeHandle)
+                await this.releaseExpiredHandle(handle, input.instanceId, nowIso);
+            const row = { ...fields, handle, activeHandle: handle };
+            const written = await settle(() => existing
+                ? storage.update(input.instanceId, row)
+                : storage.create({ connectionId: input.instanceId, connectedAt: nowAt, ...row }));
+            if (written.ok) {
+                if (input.hosted)
+                    this.hostInstance(input.instanceId);
+                this.instanceTouchedAt.set(input.instanceId, now);
+                return { ...existing, connectionId: input.instanceId, connectedAt: existing?.connectedAt ?? nowAt, ...row };
+            }
+            if (!isUniqueConstraintError(written.cause))
+                throw written.cause;
+            if (chosen) {
+                const holder = await this.liveInstanceByHandle(chosen);
+                throw new CapabilityError(`The handle "${chosen}" is held by another live instance.`, 'CONFLICT', {
+                    reason: 'instance-handle-taken',
+                    details: { handle: chosen, holder: holder?.connectionId ?? null, agentId: holder?.agentId ?? null },
+                    recoveryHint: 'Choose another handle, or omit it to be given a random one.'
+                });
+            }
+        }
+        throw new CapabilityError('Could not allocate a unique instance handle.', 'UNAVAILABLE', {
+            reason: 'instance-handle-exhausted'
+        });
+    }
+    /** Free `handle` when its holder is no longer live, so a new instance can take it. */
+    async releaseExpiredHandle(handle, claimant, nowIso) {
+        const held = await this.connectionsStorage.list({
+            where: { activeHandle: handle },
+            limit: 1
+        });
+        const holder = held.items[0];
+        if (!holder || holder.connectionId === claimant)
+            return;
+        if (SessionManager.isLiveInstance(holder, nowIso))
+            return;
+        await this.connectionsStorage.update(holder.connectionId, { activeHandle: null });
+    }
+    /** The live instance holding `handle`, if any. */
+    async liveInstanceByHandle(handle) {
+        await this.ensureStorage();
+        const held = await this.connectionsStorage.list({
+            where: { activeHandle: sanitizeSlugCandidate(handle) },
+            limit: 1
+        });
+        const holder = held.items[0];
+        return holder && SessionManager.isLiveInstance(holder, new Date().toISOString()) ? holder : null;
+    }
+    /**
+     * Mark an instance alive now and renew the membership leases it holds.
+     * Writes at most once per touch window per instance.
+     */
+    async touchInstance(instanceId, options = {}) {
+        const now = Date.now();
+        const last = this.instanceTouchedAt.get(instanceId);
+        if (!options.force && last !== undefined && now - last < SessionManager.INSTANCE_TOUCH_MIN_MS)
+            return true;
+        await this.ensureStorage();
+        const nowAt = new Date(now);
+        const expiresAt = new Date(now + SessionManager.INSTANCE_TTL_MS);
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row || row.disconnectedAt) {
+            this.forgetInstance(instanceId);
+            return false;
+        }
+        await this.connectionsStorage.update(instanceId, { lastHeartbeatAt: nowAt, expiresAt });
+        this.instanceTouchedAt.set(instanceId, now);
+        for (const lease of await this.unreleasedLeasesOf(instanceId)) {
+            await this.membershipLeasesStorage.update(lease.id, {
+                lastHeartbeatAt: nowAt.toISOString(),
+                expiresAt: expiresAt.toISOString()
+            });
+        }
+        return true;
+    }
+    /**
+     * Keep an admitted caller's instance live: register it the first time this
+     * host sees it (or after it was closed), otherwise touch it.
+     */
+    async ensureInstance(input) {
+        const known = this.instanceHandles.get(input.instanceId);
+        if (known !== undefined && (await this.touchInstance(input.instanceId)))
+            return { handle: known };
+        const row = await this.registerInstance(input);
+        this.instanceHandles.set(input.instanceId, row.activeHandle ?? row.handle ?? '');
+        return { handle: row.activeHandle ?? row.handle ?? undefined };
+    }
+    /**
+     * Make an instance a member of the session it calls with: one lease keyed
+     * on the instance, taken the first time this host sees the pair and renewed
+     * by every touch after. An archived or missing session takes no member.
+     */
+    async ensureInstanceMembership(input) {
+        const key = `${input.instanceId}|${input.sessionId}|${input.participantId}`;
+        if (this.instanceMemberships.has(key))
+            return;
+        const session = await this.getSession(input.sessionId);
+        if (!session || session.status === 'archived')
+            return;
+        await this.acquireMembershipLease({
+            sessionId: input.sessionId,
+            participantId: input.participantId,
+            connectionKey: input.instanceId
+        });
+        this.instanceMemberships.add(key);
+    }
+    /**
+     * Give a live instance the handle it chose. The registry's uniqueness rule
+     * applies: a handle another live instance holds is refused naming its holder.
+     */
+    async chooseInstanceHandle(instanceId, handle) {
+        await this.ensureStorage();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row) {
+            throw new CapabilityError('This caller has no registered instance to name.', 'NOT_FOUND', {
+                reason: 'instance-unregistered',
+                details: { instanceId }
+            });
+        }
+        const named = await this.registerInstance({
+            instanceId,
+            handle,
+            transport: row.transport ?? 'unknown',
+            clientName: row.clientName,
+            clientVersion: row.clientVersion,
+            participantId: row.participantId,
+            agentId: row.agentId,
+            harness: row.harness,
+            harnessSessionId: row.harnessSessionId,
+            hosted: this.hostedInstances.has(instanceId)
+        });
+        this.instanceHandles.set(instanceId, named.activeHandle ?? named.handle ?? '');
+        return named;
+    }
+    /** One instance's registry row. */
+    async getInstance(instanceId) {
+        await this.ensureStorage();
+        return this.connectionsStorage.get(instanceId);
+    }
+    /** Record the session an instance is working in (its bind, or its first write). */
+    async setInstanceSession(instanceId, sessionId) {
+        await this.ensureStorage();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row || row.sessionId === sessionId)
+            return;
+        await this.connectionsStorage.update(instanceId, { sessionId });
+    }
+    /** The session an instance is working in, while that session is still open. */
+    async instanceSession(instanceId) {
+        await this.ensureStorage();
+        const sessionId = (await this.connectionsStorage.get(instanceId))?.sessionId;
+        if (!sessionId)
+            return undefined;
+        const session = await this.getSession(sessionId);
+        return session && session.status !== 'archived' ? session.id : undefined;
+    }
+    /** Close an instance: it stops being live, frees its handle and releases its leases. */
+    async closeInstance(instanceId) {
+        await this.ensureStorage();
+        this.hostedInstances.delete(instanceId);
+        this.forgetInstance(instanceId);
+        const nowAt = new Date();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (row && !row.disconnectedAt) {
+            await this.connectionsStorage.update(instanceId, { disconnectedAt: nowAt, activeHandle: null });
+        }
+        for (const lease of await this.unreleasedLeasesOf(instanceId)) {
+            await this.membershipLeasesStorage.update(lease.id, {
+                releasedAt: nowAt.toISOString(),
+                activeConnectionKey: null
+            });
+        }
+        if (this.hostedInstances.size === 0)
+            this.stopInstanceHeartbeat();
+    }
+    /** Every live instance in this store: who is here, however they arrived. */
+    async listLiveInstances() {
+        await this.ensureStorage();
+        const nowAt = new Date();
+        const nowIso = nowAt.toISOString();
+        const live = [];
+        const pageSize = 500;
+        for (let offset = 0;; offset += pageSize) {
+            const page = await this.connectionsStorage.list({
+                where: { expiresAt: { gte: nowAt } },
+                orderBy: { connectionId: 'asc' },
+                limit: pageSize,
+                offset
+            });
+            live.push(...page.items.filter((row) => SessionManager.isLiveInstance(row, nowIso)));
+            if (page.items.length < pageSize)
+                return live;
+        }
+    }
+    forgetInstance(instanceId) {
+        this.instanceTouchedAt.delete(instanceId);
+        this.instanceHandles.delete(instanceId);
+        for (const key of Array.from(this.instanceMemberships)) {
+            if (key.startsWith(`${instanceId}|`))
+                this.instanceMemberships.delete(key);
+        }
+    }
+    async unreleasedLeasesOf(instanceId) {
+        const result = await this.membershipLeasesStorage.list({
+            where: {
+                activeConnectionKey: instanceId,
+                releasedAt: { isNull: true }
+            },
+            limit: 500
+        });
+        return result.items;
+    }
+    /**
+     * Heartbeat hosted instances on this runtime's lifecycle interval, so the
+     * kernel stops it at disposal. A finite host (a one-shot command) runs no
+     * interval: its instance lives by activity and closes with the manager.
+     */
+    hostInstance(instanceId) {
+        this.hostedInstances.add(instanceId);
+        if (this.instanceHeartbeat)
+            return;
+        const runtime = this.hostRuntime;
+        if (runtime.declaredScope.lifecycle === 'finite' || runtime.lifecycle.signal.aborted)
+            return;
+        this.instanceHeartbeat = runtime.lifecycle.interval(() => {
+            for (const id of this.hostedInstances) {
+                void settle(() => this.touchInstance(id, { force: true })).then((touched) => {
+                    if (touched.ok)
+                        return;
+                    this.logger.warn('Instance heartbeat failed', { instanceId: id, error: valueFreeFailure(touched.cause) });
+                });
+            }
+        }, SessionManager.INSTANCE_HEARTBEAT_MS);
+    }
+    stopInstanceHeartbeat() {
+        const stop = this.instanceHeartbeat;
+        this.instanceHeartbeat = undefined;
+        stop?.();
+    }
+    async getConnectionHistory(participantId, limit) {
+        await this.ensureStorage();
+        const where = {};
+        if (participantId)
+            where.participantId = participantId;
+        const result = await this.connectionsStorage.list({
+            where,
+            orderBy: { connectedAt: 'desc' },
+            limit: limit ?? 100
+        });
+        return result.items;
+    }
+    // KNOWLEDGE
+    async addKnowledgeRef(sessionId, ref) {
+        await this.ensureStorage();
+        return this.knowledgeRefsStorage.create({
+            ...ref,
+            metadata: ref.metadata ?? {},
+            sessionId
+        });
+    }
+    async getKnowledgeRef(id) {
+        await this.ensureStorage();
+        return this.knowledgeRefsStorage.get(id);
+    }
+    async getKnowledgeRefs(sessionId, filters) {
+        await this.ensureStorage();
+        const where = { sessionId };
+        if (filters?.reason)
+            where.reason = filters.reason;
+        const result = await this.knowledgeRefsStorage.list({
+            where,
+            orderBy: { createdAt: 'desc' },
+            limit: filters?.limit ?? 100,
+            offset: filters?.offset ?? 0
+        });
+        return result.items;
+    }
+    async deleteKnowledgeRef(id) {
+        await this.ensureStorage();
+        await this.knowledgeRefsStorage.delete(id);
+    }
+    async deleteSessionKnowledgeRefs(sessionId) {
+        await this.ensureStorage();
+        // Get all knowledge refs for session
+        const result = await this.knowledgeRefsStorage.list({
+            where: { sessionId },
+            limit: 1000
+        });
+        // Delete them
+        for (const ref of result.items) {
+            await this.knowledgeRefsStorage.delete(ref.id);
+        }
+        return result.items.length;
+    }
+    // SESSION STATE (PERSISTED PER PARTICIPANT)
+    async setParticipantActiveSession(participantId, sessionId) {
+        await this.ensureStorage();
+        if (!participantId)
+            return;
+        const previous = this.participantSessions.get(participantId);
+        this.participantSessions.set(participantId, sessionId);
+        try {
+            await this.persistRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`, {
+                sessionId
+            });
+        }
+        catch (error) {
+            if (previous)
+                this.participantSessions.set(participantId, previous);
+            else
+                this.participantSessions.delete(participantId);
+            throw error;
+        }
+    }
+    async getParticipantActiveSession(participantId) {
+        await this.ensureStorage();
+        if (!participantId)
+            return null;
+        return this.participantSessions.get(participantId) ?? null;
+    }
+    /**
+     * Read one participant binding from durable authority for a custody decision.
+     *
+     * The ordinary getter intentionally serves the manager's hydrated read model.
+     * MCP authorization cannot use that cache: another process may have rebound
+     * the participant since this manager started.  Read the body-scoped row on
+     * every call, reconcile only this cache entry, and let storage/parse failures
+     * propagate so the caller fails closed.
+     */
+    async getAuthoritativeParticipantActiveSession(participantId) {
+        await this.ensureStorage();
+        if (!participantId)
+            return null;
+        const routing = await this.readParticipantRouting(participantId);
+        if (routing.state === 'malformed') {
+            throw new CapabilityError(routing.problem === 'invalid-json'
+                ? `Participant ${participantId} routing row contains invalid JSON.`
+                : `Participant ${participantId} routing row has no valid sessionId.`, 'INVALID_INPUT', { reason: 'routing-row-malformed', details: { participantId, problem: routing.problem } });
+        }
+        return routing.state === 'bound' ? routing.sessionId : null;
+    }
+    /**
+     * Read one participant's body-scoped routing row from durable storage and
+     * reconcile this manager's cache entry with it. A storage failure
+     * propagates; a row that cannot be decoded is reported as `malformed`
+     * (never as unbound) so each caller decides whether to fail closed.
+     */
+    async readParticipantRouting(participantId) {
+        await this.persistMappingsTail;
+        const stateStorage = await this.resolveStorageRecord('session.state');
+        const row = await stateStorage.get(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`);
+        if (!row) {
+            this.participantSessions.delete(participantId);
+            return { state: 'unbound' };
+        }
+        const decoded = decodeJson(row.value);
+        if (!decoded.ok)
+            return { state: 'malformed', problem: 'invalid-json' };
+        const parsed = RoutingValueSchema.safeParse(decoded.value);
+        if (!parsed.success)
+            return { state: 'malformed', problem: 'not-an-object' };
+        if (parsed.data.sessionId === null) {
+            this.participantSessions.delete(participantId);
+            return { state: 'unbound' };
+        }
+        const sessionId = parsed.data.sessionId;
+        if (!sessionId || sessionId.trim().length === 0)
+            return { state: 'malformed', problem: 'no-session-id' };
+        this.participantSessions.set(participantId, sessionId);
+        return { state: 'bound', sessionId };
+    }
+    async clearParticipantActiveSession(participantId) {
+        await this.ensureStorage();
+        if (!participantId)
+            return;
+        const previous = this.participantSessions.get(participantId);
+        if (!previous)
+            return;
+        this.participantSessions.delete(participantId);
+        try {
+            await this.deleteRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`);
+        }
+        catch (error) {
+            this.participantSessions.set(participantId, previous);
+            throw error;
+        }
+    }
+    async ensureParticipantSession(participantId) {
+        await this.ensureStorage();
+        if (!participantId)
+            return null;
+        // Participant resolution is part of MCP custody stamping.  A manager can
+        // outlive another process rebinding this participant, so its hydrated map
+        // is not authority here.  Read the exact durable routing row before any
+        // session-open side effect; failures must propagate rather than falling
+        // through to a stale/default session.
+        const routing = await this.readParticipantRouting(participantId);
+        if (routing.state === 'malformed') {
+            // A routing row that cannot even be decoded names nothing bindable;
+            // every reconciliation would refuse on it forever. Tombstone it and
+            // treat the body as unbound rather than wedged. A storage failure
+            // (the read above, or this tombstone write) propagates instead.
+            this.logger.warn('Participant routing row malformed; clearing it', {
+                participantId,
+                problem: routing.problem
+            });
+            await this.deleteRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`);
+            this.participantSessions.delete(participantId);
+            return null;
+        }
+        const sessionId = routing.state === 'bound' ? routing.sessionId : null;
+        if (!sessionId) {
+            return null;
+        }
+        // This resolver reconciles identity; it does not own participant routing.
+        // Repersisting or clearing the row after the read creates a TOCTOU window
+        // where another process' newer binding can be overwritten or tombstoned —
+        // so the heal below re-reads the row and tombstones it only when it still
+        // names the SAME dead session. The mcp: transport mapping already self-
+        // heals this way in getSessionForMcpConnection; a participant row whose
+        // session row is gone used to be the one mapping that could never shed it,
+        // wedging every host reconciliation (and the relay's bind replay) behind a
+        // fail-closed error until storage was hand-edited.
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            // The mapped session row is GONE — not archived (that stays fail-closed
+            // below, because reopening is an explicit lifecycle action) but deleted
+            // out from under the mapping, possibly by another process. Heal it.
+            const stillStale = await this.getAuthoritativeParticipantActiveSession(participantId);
+            if (stillStale === sessionId) {
+                await this.deleteRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`);
+                this.participantSessions.delete(participantId);
+                this.logger.warn('Cleared orphaned participant→session mapping (session row missing)', {
+                    participantId,
+                    sessionId
+                });
+            }
+            return null;
+        }
+        if (session.status === 'archived')
+            return null;
+        if (session.status !== 'paused')
+            return session;
+        // Preserve the historical "open paused work" behavior without calling
+        // resumeSession(), whose broader default/participant writes are forbidden
+        // on this custody-resolution path.
+        await this.updateSession(sessionId, { status: 'active' });
+        return this.getSession(sessionId);
+    }
+    async setDefaultActiveSession(sessionId) {
+        await this.ensureStorage();
+        this.defaultSessionId = sessionId;
+        if (!sessionId ||
+            (this.defaultParticipantId && this.participantSessions.get(this.defaultParticipantId) !== sessionId)) {
+            this.defaultParticipantId = null;
+        }
+        await this.persistRoutingRow(SESSION_STATE_DEFAULT_KEY, {
+            sessionId,
+            participantId: this.defaultParticipantId
+        });
+    }
+    async getDefaultActiveSession() {
+        await this.ensureStorage();
+        return this.defaultSessionId;
+    }
+    /** Persist the default session together with the CLI participant that selected it. */
+    async setDefaultActiveBinding(sessionId, participantId) {
+        await this.ensureStorage();
+        this.defaultSessionId = sessionId;
+        this.defaultParticipantId = participantId;
+        this.participantSessions.set(participantId, sessionId);
+        // Participant binding is the authority. Publish the global/default pointer
+        // only after that exact body row is durable.
+        await this.persistRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${participantId}`, {
+            sessionId
+        });
+        await this.persistRoutingRow(SESSION_STATE_DEFAULT_KEY, { sessionId, participantId });
+    }
+    /** Resolve the durable CLI caller without falling back to a participant-null session. */
+    async getDefaultActiveBinding() {
+        await this.ensureStorage();
+        if (!this.defaultSessionId || !this.defaultParticipantId)
+            return null;
+        if (this.participantSessions.get(this.defaultParticipantId) !== this.defaultSessionId)
+            return null;
+        return {
+            sessionId: this.defaultSessionId,
+            participantId: this.defaultParticipantId
+        };
+    }
+    // UTILITIES
+    /**
+     * Get or create active session for a participant
+     */
+    async getOrCreateActiveSession(participantId, title) {
+        await this.ensureStorage();
+        // Check for existing active session
+        const active = await this.getActiveSession();
+        if (active)
+            return active;
+        // Create new session
+        return this.createSession({
+            title: title || `Session ${new Date().toISOString()}`,
+            status: 'active',
+            ownerParticipant: participantId
+        });
+    }
+    /**
+     * Get session statistics.
+     *
+     * Every figure is a TRUE count — countRecords over the exact where-filters
+     * the corresponding lists use. These totals previously came from capped
+     * list pages (todos/scratchpad/messages at 10000 rows, jobs at the 100-row
+     * default page) and silently froze at the ceiling on busy sessions.
+     */
+    async getSessionStats(sessionId, participantId) {
+        await this.ensureStorage();
+        const session = await this.getSession(sessionId);
+        if (!session)
+            return null;
+        // When the caller names a participant, scope the message view to THAT
+        // seat's inbox so `status {participantId}` reports the seat's own mail —
+        // not a session-wide count that no per-seat mark-read can ever drain.
+        // No participant → preserve the original ambient session-wide view.
+        const messageScope = participantId ? { toParticipant: participantId } : {};
+        const [todosTotal, todosCompleted, todosActive, 
+        // blocked = the todo's OWN explicit status ('blocked'). A todo waiting
+        // on incomplete dependencies is a different state, reported separately
+        // as awaitingDependencies below.
+        todosBlocked, todosPending, awaitingDependencies, scratchpadTotal, scratchpadByType, jobsTotal, jobsCompleted, jobsPending, jobsProcessing, jobsFailed, messagesTotal, messagesUnread] = await Promise.all([
+            this.countTodos(sessionId),
+            this.countTodos(sessionId, { status: 'completed' }),
+            this.countTodos(sessionId, { status: 'in_progress' }),
+            this.countTodos(sessionId, { status: 'blocked' }),
+            this.countTodos(sessionId, { status: 'pending' }),
+            this.countTodosAwaitingDependencies(sessionId),
+            this.countScratchpad(sessionId),
+            this.countScratchpadByType(sessionId),
+            this.countJobRefs(sessionId),
+            this.countJobRefs(sessionId, { status: 'completed' }),
+            this.countJobRefs(sessionId, { status: 'pending' }),
+            this.countJobRefs(sessionId, { status: 'processing' }),
+            this.countJobRefs(sessionId, { status: 'failed' }),
+            this.countMessages(sessionId, messageScope),
+            this.countMessages(sessionId, { ...messageScope, isRead: false })
+        ]);
+        return {
+            session,
+            todos: {
+                total: todosTotal,
+                completed: todosCompleted,
+                active: todosActive,
+                blocked: todosBlocked,
+                awaitingDependencies,
+                pending: todosPending
+            },
+            scratchpad: {
+                total: scratchpadTotal,
+                byType: scratchpadByType
+            },
+            jobs: {
+                total: jobsTotal,
+                completed: jobsCompleted,
+                pending: jobsPending,
+                processing: jobsProcessing,
+                failed: jobsFailed
+            },
+            messages: {
+                total: messagesTotal,
+                unread: messagesUnread,
+                // Label WHOSE mailbox these figures describe: seat-scoped when a
+                // participant was named, session-wide otherwise. An unlabeled
+                // ambient unread count reads as personal backlog when it is the
+                // whole bus (ledger L-11).
+                scope: participantId ? 'participant' : 'session',
+                participantId
+            }
+        };
+    }
+    /**
+     * True counts per scratchpad content type. Enumerates the closed content
+     * type set and counts each — never derived from a capped list page. Types
+     * with zero entries are omitted, matching the historical byType shape.
+     */
+    async countScratchpadByType(sessionId) {
+        const byType = {};
+        await Promise.all(ScratchpadContentTypeSchema.options.map(async (contentType) => {
+            const count = await this.countScratchpad(sessionId, { contentType });
+            if (count > 0)
+                byType[contentType] = count;
+        }));
+        return byType;
+    }
+    /**
+     * Count non-terminal todos waiting on at least one incomplete dependency.
+     * Exhaustive paged scan — no row ceiling. Distinct from the `blocked`
+     * bucket, which is the todo's own explicit status; a completed or
+     * cancelled todo is not awaiting anything, so terminal rows never count.
+     */
+    async countTodosAwaitingDependencies(sessionId) {
+        const blocked = await this.scanTodosByDependency(sessionId, { isBlocked: true });
+        return blocked.filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled').length;
+    }
+    // PRIVATE
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('SessionManager not initialized. Call initialize() first.');
+        }
+    }
+    async loadSessionMappings() {
+        this.participantSessions.clear();
+        this.mcpSessions.clear();
+        this.defaultSessionId = null;
+        this.defaultParticipantId = null;
+        const stateStorage = await this.resolveStorageRecord('session.state');
+        const items = [];
+        const pageSize = 1000;
+        let offset = 0;
+        for (;;) {
+            const page = await stateStorage.list({
+                includeTotal: true,
+                limit: pageSize,
+                offset,
+                orderBy: { key: 'asc' }
+            });
+            items.push(...page.items);
+            if (page.items.length === 0) {
+                if (page.hasMore === true || (page.total !== undefined && offset < page.total)) {
+                    throw new CapabilityError('session.state pagination made no progress while rows remain.', 'INTERNAL', { reason: 'routing-pagination-stalled' });
+                }
+                break;
+            }
+            offset += page.items.length;
+            const hasMore = page.hasMore ??
+                (page.total !== undefined ? offset < page.total : page.items.length === pageSize);
+            if (!hasMore)
+                break;
+        }
+        const legacy = items.find((item) => item.key === SESSION_STATE_LEGACY_KEY);
+        if (legacy) {
+            const decoded = decodeJson(legacy.value);
+            if (!decoded.ok) {
+                throw new CapabilityError('Persisted session.state record contains invalid JSON.', 'INVALID_INPUT', {
+                    reason: 'session-state-malformed',
+                    cause: decoded.cause
+                });
+            }
+            this.applySessionState(LegacySessionStateSchema.parse(isJsonObject(decoded.value) ? decoded.value : {}));
+        }
+        // Body-scoped rows override the legacy aggregate. One participant write
+        // cannot overwrite another participant simply because its manager is
+        // stale. One undecodable row is skipped and reported; it never fails the
+        // rest of the routing state.
+        for (const item of items) {
+            if (item.key === SESSION_STATE_LEGACY_KEY)
+                continue;
+            const decoded = decodeJson(item.value);
+            if (!decoded.ok) {
+                this.logger.warn('Skipping persisted session.state routing row with invalid JSON', {
+                    key: item.key,
+                    error: valueFreeFailure(decoded.cause)
+                });
+                continue;
+            }
+            const parsed = RoutingValueSchema.safeParse(decoded.value);
+            if (!parsed.success) {
+                this.logger.warn('Skipping persisted session.state routing row that is not a JSON object', {
+                    key: item.key
+                });
+                continue;
+            }
+            const value = parsed.data;
+            const sessionId = value.sessionId ?? null;
+            if (item.key.startsWith(SESSION_STATE_PARTICIPANT_PREFIX)) {
+                const participantId = item.key.slice(SESSION_STATE_PARTICIPANT_PREFIX.length);
+                if (participantId && sessionId)
+                    this.participantSessions.set(participantId, sessionId);
+                else if (participantId)
+                    this.participantSessions.delete(participantId);
+            }
+            else if (item.key.startsWith(SESSION_STATE_MCP_PREFIX)) {
+                const mcpSessionId = item.key.slice(SESSION_STATE_MCP_PREFIX.length);
+                if (mcpSessionId && sessionId)
+                    this.mcpSessions.set(mcpSessionId, sessionId);
+                else if (mcpSessionId)
+                    this.mcpSessions.delete(mcpSessionId);
+            }
+            else if (item.key === SESSION_STATE_DEFAULT_KEY) {
+                this.defaultSessionId = sessionId;
+                this.defaultParticipantId = value.participantId ?? null;
+            }
+        }
+    }
+    /**
+     * Serialize one routing write behind every earlier one. Its failure is
+     * returned to the caller that queued it (the returned promise rejects);
+     * the tail only orders writes, so one failed write never blocks the next.
+     */
+    queueRoutingMutation(operation) {
+        const queued = this.persistMappingsTail.then(operation);
+        this.persistMappingsTail = Promise.allSettled([queued]).then(() => undefined);
+        return queued;
+    }
+    persistRoutingRow(key, value) {
+        return this.queueRoutingMutation(async () => {
+            const stateStorage = await this.resolveStorageRecord('session.state');
+            const encoded = JSON.stringify(value);
+            const existing = await stateStorage.get(key);
+            if (existing) {
+                await stateStorage.update(key, { value: encoded });
+                return;
+            }
+            await writeOrRecover(() => stateStorage.create({ key, value: encoded }), () => stateStorage.update(key, { value: encoded }), isUniqueConstraintError);
+        });
+    }
+    deleteRoutingRow(key) {
+        // A null tombstone wins over an old aggregate snapshot written by a stale
+        // process. Physical deletion would let that legacy row resurrect custody.
+        return this.persistRoutingRow(key, { sessionId: null });
+    }
+    async clearMappingsForSession(sessionId) {
+        const participantIds = [];
+        const mcpIds = [];
+        for (const [participantId, mappedSessionId] of this.participantSessions.entries()) {
+            if (mappedSessionId === sessionId) {
+                this.participantSessions.delete(participantId);
+                participantIds.push(participantId);
+            }
+        }
+        for (const [mcpSessionId, mappedSessionId] of this.mcpSessions.entries()) {
+            if (mappedSessionId === sessionId) {
+                this.mcpSessions.delete(mcpSessionId);
+                mcpIds.push(mcpSessionId);
+            }
+        }
+        if (participantIds.length > 0 || mcpIds.length > 0) {
+            await Promise.all([
+                ...participantIds.map((id) => this.deleteRoutingRow(`${SESSION_STATE_PARTICIPANT_PREFIX}${id}`)),
+                ...mcpIds.map((id) => this.deleteRoutingRow(`${SESSION_STATE_MCP_PREFIX}${id}`))
+            ]);
+        }
+    }
+    applySessionState(state) {
+        this.participantSessions = new Map(state.participantSessions);
+        this.mcpSessions = new Map(state.mcpSessions);
+        this.defaultSessionId = state.defaultSessionId ?? null;
+        this.defaultParticipantId = state.defaultParticipantId ?? null;
+    }
+    async recoverActiveSession() {
+        await this.loadSessionMappings();
+        if (!this.defaultSessionId)
+            return;
+        const existing = await this.getSession(this.defaultSessionId);
+        if (!existing || existing.status !== 'active')
+            await this.setDefaultActiveSession(null);
+    }
+    async ensureSessionActive(sessionId) {
+        await this.ensureStorage();
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            throw sessionNotFound(sessionId);
+        }
+        if (session.status !== 'active') {
+            throw sessionNotWritable(sessionId, session.status);
+        }
+        return session;
+    }
+    // MCP SESSION MAPPING
+    /**
+     * Link MCP HTTP session to Vibes session
+     *
+     * MCP HTTP transport maintains connection-based sessions.
+     * This maps those to active Vibes sessions for tool execution context.
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     * @param vibesSessionId - Vibes session UUID
+     */
+    async linkMcpSession(mcpSessionId, vibesSessionId) {
+        await this.ensureStorage();
+        const session = await this.getSession(vibesSessionId);
+        if (!session || session.status !== 'active') {
+            throw new CapabilityError(`Cannot bind MCP connection to inactive session ${vibesSessionId}`, session ? 'CONFLICT' : 'NOT_FOUND', { reason: session ? 'session-not-writable' : 'session-not-found', details: { sessionId: vibesSessionId } });
+        }
+        this.mcpSessions.set(mcpSessionId, vibesSessionId);
+        await this.persistRoutingRow(`${SESSION_STATE_MCP_PREFIX}${mcpSessionId}`, {
+            sessionId: vibesSessionId
+        });
+    }
+    /**
+     * Get Vibes session for MCP connection
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     * @returns Session if mapped and exists, null otherwise
+     */
+    async getSessionForMcpConnection(mcpSessionId) {
+        await this.ensureStorage();
+        const vibesSessionId = this.mcpSessions.get(mcpSessionId);
+        if (!vibesSessionId) {
+            return null;
+        }
+        const session = await this.getSession(vibesSessionId);
+        if (!session || session.status === 'archived') {
+            this.mcpSessions.delete(mcpSessionId);
+            await this.deleteRoutingRow(`${SESSION_STATE_MCP_PREFIX}${mcpSessionId}`);
+            return null;
+        }
+        return session;
+    }
+    /**
+     * Unlink MCP HTTP session from Vibes session
+     *
+     * Called when MCP session closes or Vibes session is archived.
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     */
+    async unlinkMcpSession(mcpSessionId) {
+        await this.ensureStorage();
+        if (this.mcpSessions.delete(mcpSessionId)) {
+            await this.deleteRoutingRow(`${SESSION_STATE_MCP_PREFIX}${mcpSessionId}`);
+        }
+    }
+    /**
+     * Clear all MCP session mappings for a given Vibes session
+     *
+     * Called when a session is archived or deleted.
+     *
+     * @param vibesSessionId - Vibes session UUID
+     */
+    async clearMcpSessionsForVibesSession(vibesSessionId) {
+        await this.ensureStorage();
+        const removed = [];
+        for (const [mcpId, vibesId] of this.mcpSessions.entries()) {
+            if (vibesId === vibesSessionId) {
+                this.mcpSessions.delete(mcpId);
+                removed.push(mcpId);
+            }
+        }
+        await Promise.all(removed.map((mcpId) => this.deleteRoutingRow(`${SESSION_STATE_MCP_PREFIX}${mcpId}`)));
+    }
+    // PRESENCE TRACKING
+    /**
+     * Record presence for a connection to a session
+     */
+    async recordPresence(input) {
+        await this.ensureStorage();
+        const now = new Date();
+        const presence = await this.presenceStorage.create({
+            contextType: 'session',
+            contextId: input.sessionId,
+            participantId: input.participantId,
+            connectionId: input.connectionId,
+            metadata: input.metadata,
+            lastHeartbeat: now.toISOString(),
+            status: 'active',
+            connectedAt: now.toISOString()
+        });
+        if (input.participantId) {
+            // Lease authority must not be swallowed: presence without a lease
+            // creates a ghost connection absent from the membership roster.
+            try {
+                await this.acquireMembershipLease({
+                    sessionId: input.sessionId,
+                    participantId: input.participantId,
+                    connectionKey: input.connectionId,
+                    role: 'member',
+                    metadata: input.metadata
+                });
+            }
+            catch (error) {
+                // Presence without a lease is a ghost roster entry — roll back. The
+                // lease failure is what surfaces; a failed rollback is reported too.
+                const [rollback] = await Promise.allSettled([this.presenceStorage.delete(presence.id)]);
+                if (rollback.status === 'rejected') {
+                    this.logger.warn('Failed to roll back presence after lease failure', {
+                        presenceId: presence.id,
+                        error: valueFreeFailure(CaughtFailureSchema.parse(rollback.reason))
+                    });
+                }
+                throw error;
+            }
+        }
+        return presence;
+    }
+    /**
+     * Update heartbeat for a connection
+     */
+    async updateHeartbeat(connectionId) {
+        await this.ensureStorage();
+        const now = new Date();
+        // Find presence by connectionId
+        const result = await this.presenceStorage.list({
+            where: { connectionId },
+            limit: 1
+        });
+        const presence = result.items[0];
+        if (!presence)
+            return;
+        await this.presenceStorage.update(presence.id, {
+            lastHeartbeat: now.toISOString()
+        });
+        // Renew the membership lease on the same cadence as presence heartbeat
+        // so the roster cannot expire while the connection is still live.
+        if (presence.participantId) {
+            await this.acquireMembershipLease({
+                sessionId: presence.contextId,
+                participantId: presence.participantId,
+                connectionKey: presence.connectionId ?? connectionId
+            });
+        }
+    }
+    /**
+     * Get active presence records for a session
+     */
+    async getActivePresence(sessionId) {
+        await this.ensureStorage();
+        // Get recent presence records (last 5 minutes)
+        const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+        const result = await this.presenceStorage.list({
+            where: { contextId: sessionId, status: 'active' },
+            limit: 100
+        });
+        // Filter by heartbeat
+        return result.items.filter((p) => p.lastHeartbeat >= fiveMinutesAgo);
+    }
+    /**
+     * Get presence summary for a session
+     */
+    async getPresenceSummary(sessionId) {
+        await this.ensureStorage();
+        const active = await this.listActiveMembershipLeases(sessionId);
+        const asIso = (value) => value instanceof Date ? value.toISOString() : value;
+        return {
+            sessionId,
+            activeCount: active.length,
+            idleCount: 0,
+            staleCount: 0,
+            totalCount: active.length,
+            isOccupied: active.length > 0,
+            connections: active.map((lease) => ({
+                id: lease.id,
+                status: 'active',
+                lastHeartbeat: asIso(lease.lastHeartbeatAt),
+                connectionId: lease.connectionKey,
+                participantId: lease.participantId
+            }))
+        };
+    }
+    /**
+     * Check if session is occupied (has active/idle connections)
+     */
+    async isSessionOccupied(sessionId) {
+        await this.ensureStorage();
+        const active = await this.listActiveMembershipLeases(sessionId);
+        return active.length > 0;
+    }
+    // MEMBERSHIP LEASES
+    static MEMBERSHIP_LEASE_TTL_MS = 10 * 60 * 1000;
+    normalizeConnectionKey(connectionKey) {
+        const key = connectionKey?.trim() ?? '';
+        return key.length > 0 ? key : 'local';
+    }
+    /**
+     * Acquire or renew a membership lease. Idempotent on
+     * (sessionId, participantId, connectionKey).
+     */
+    async acquireMembershipLease(input) {
+        await this.ensureStorage();
+        const connectionKey = this.normalizeConnectionKey(input.connectionKey);
+        const now = Date.now();
+        const ttl = Math.max(30_000, input.ttlMs ?? SessionManager.MEMBERSHIP_LEASE_TTL_MS);
+        const nowIso = new Date(now).toISOString();
+        const expiresAt = new Date(now + ttl).toISOString();
+        const existing = await this.membershipLeasesStorage.list({
+            where: {
+                sessionId: input.sessionId,
+                participantId: input.participantId,
+                activeConnectionKey: connectionKey
+            },
+            limit: 1
+        });
+        const row = existing.items[0];
+        if (row) {
+            return this.membershipLeasesStorage.update(row.id, {
+                role: input.role ?? row.role ?? 'member',
+                lastHeartbeatAt: nowIso,
+                expiresAt,
+                releasedAt: null,
+                activeConnectionKey: connectionKey,
+                claimedTodoIds: input.claimedTodoIds,
+                metadata: input.metadata ? { ...row.metadata, ...input.metadata } : undefined
+            });
+        }
+        return writeOrRecover(() => this.membershipLeasesStorage.create({
+            sessionId: input.sessionId,
+            participantId: input.participantId,
+            connectionKey,
+            activeConnectionKey: connectionKey,
+            role: input.role ?? 'member',
+            joinedAt: nowIso,
+            lastHeartbeatAt: nowIso,
+            expiresAt,
+            releasedAt: null,
+            claimedTodoIds: input.claimedTodoIds ?? [],
+            metadata: input.metadata ?? {}
+        }), async () => {
+            const raced = await this.membershipLeasesStorage.list({
+                where: {
+                    sessionId: input.sessionId,
+                    participantId: input.participantId,
+                    activeConnectionKey: connectionKey
+                },
+                limit: 1
+            });
+            const racedRow = raced.items[0];
+            if (!racedRow)
+                return null;
+            return this.membershipLeasesStorage.update(racedRow.id, {
+                lastHeartbeatAt: nowIso,
+                expiresAt,
+                releasedAt: null,
+                activeConnectionKey: connectionKey
+            });
+        }, isUniqueConstraintError);
+    }
+    async releaseMembershipLease(input) {
+        await this.ensureStorage();
+        const connectionKey = this.normalizeConnectionKey(input.connectionKey);
+        const existing = await this.membershipLeasesStorage.list({
+            where: {
+                sessionId: input.sessionId,
+                participantId: input.participantId,
+                activeConnectionKey: connectionKey
+            },
+            limit: 1
+        });
+        const row = existing.items[0];
+        if (!row || row.releasedAt)
+            return false;
+        await this.membershipLeasesStorage.update(row.id, {
+            releasedAt: new Date().toISOString(),
+            activeConnectionKey: null
+        });
+        return true;
+    }
+    /** Live roster: unreleased leases whose expiry is still in the future. */
+    async listActiveMembershipLeases(sessionId) {
+        await this.ensureStorage();
+        const nowIso = new Date().toISOString();
+        const leases = [];
+        const pageSize = 500;
+        const where = {
+            sessionId,
+            releasedAt: { isNull: true }
+        };
+        for (let offset = 0;; offset += pageSize) {
+            const result = await this.membershipLeasesStorage.list({
+                where,
+                limit: pageSize,
+                offset
+            });
+            leases.push(...result.items);
+            if (result.items.length < pageSize)
+                break;
+        }
+        return leases
+            .filter((lease) => !lease.releasedAt && String(lease.expiresAt) >= nowIso)
+            .sort((a, b) => {
+            const roleRank = (role) => (role === 'owner' ? 0 : 1);
+            const byRole = roleRank(a.role) - roleRank(b.role);
+            if (byRole !== 0)
+                return byRole;
+            return String(a.participantId).localeCompare(String(b.participantId));
+        });
+    }
+    /**
+     * Remove presence record (on disconnect) and release its membership lease.
+     */
+    async removePresence(connectionId) {
+        await this.ensureStorage();
+        // Find presence by connectionId
+        const result = await this.presenceStorage.list({
+            where: { connectionId },
+            limit: 1
+        });
+        const presence = result.items[0];
+        if (!presence)
+            return;
+        // Release before delete so a lease-authority failure cannot leave a
+        // ghost roster entry after presence is gone.
+        if (presence.participantId) {
+            await this.releaseMembershipLease({
+                sessionId: presence.contextId,
+                participantId: presence.participantId,
+                connectionKey: presence.connectionId ?? connectionId
+            });
+        }
+        await this.presenceStorage.delete(presence.id);
+    }
+    /**
+     * Cleanup stale presence records and release any associated leases.
+     */
+    async cleanupStalePresence(thresholdMs) {
+        await this.ensureStorage();
+        const threshold = new Date(Date.now() - (thresholdMs ?? 5 * 60 * 1000)).toISOString();
+        // Get stale records
+        const result = await this.presenceStorage.list({
+            limit: 1000
+        });
+        const stale = result.items.filter((p) => p.lastHeartbeat < threshold);
+        // Delete them (and release leases — same contract as removePresence)
+        for (const presence of stale) {
+            if (presence.participantId) {
+                await this.releaseMembershipLease({
+                    sessionId: presence.contextId,
+                    participantId: presence.participantId,
+                    connectionKey: presence.connectionId ?? undefined
+                });
+            }
+            await this.presenceStorage.delete(presence.id);
+        }
+        return stale.length;
+    }
+    /**
+     * Resolve session with occupation awareness
+     * Returns the first unoccupied session from candidates, or null if all occupied
+     */
+    async resolveUnoccupiedSession(candidateIds) {
+        await this.ensureStorage();
+        for (const sessionId of candidateIds) {
+            const session = await this.getSession(sessionId);
+            if (!session || session.status === 'archived')
+                continue;
+            const occupied = await this.isSessionOccupied(sessionId);
+            if (!occupied) {
+                return session;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=manager.js.map