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

package/dist/mcp/utils/participant.js

@@ -0,0 +1,1429 @@
+import { StoredClientInfoSchema } from "../../schemas/participant.js";
+/**
+ * MCP Participant Utilities
+ * Auto-registration and identification for MCP clients
+ *
+ * HTTP transport state is connection-scoped; durable identity and session
+ * routing are resolved by the canonical SessionManager.
+ */
+import { CapabilityError, CaughtFailureSchema, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+import { boundSessionIdOf } from '@vibesdotdev/kernel/schemas/scope';
+import { getLogger } from '@vibesdotdev/logging';
+import { generateId } from '@vibesdotdev/shared/utils';
+import { harnessSeatOf, harnessSeatSlug, harnessSessionSeat } from "../../schemas/harness-seat.js";
+import { McpSessionRegistry, mcpSessionRegistryFor } from "./session-registry.js";
+import { unboundSessionErrorFields } from "./unbound-guidance.js";
+/** The serving root's MCP transport registry: the manager's runtime names the root. */
+function registryOf(session) {
+    return mcpSessionRegistryFor(session.servingRuntime);
+}
+/**
+ * Get participant cache for an MCP session
+ * Uses connection-scoped cache for HTTP and one transport cache for stdio.
+ */
+function getParticipantCache(registry, mcpSessionId) {
+    return registry.getParticipantCache(mcpSessionId ?? null);
+}
+function getRuntimeClientInfo(registry, mcpSessionId) {
+    return registry.getClientInfo(mcpSessionId ?? null) ?? undefined;
+}
+/** Connection-scoped initialize identity for bind/receipt projection, on the manager's root. */
+export function getMcpClientInfo(session, mcpSessionId) {
+    return getRuntimeClientInfo(registryOf(session), mcpSessionId);
+}
+function getRuntimeConnectionState(registry, mcpSessionId) {
+    return registry.getConnectionState(mcpSessionId ?? null) ?? undefined;
+}
+function updateRuntimeConnectionState(registry, updates, mcpSessionId) {
+    const effectiveKey = mcpSessionId || updates.connectionId || undefined;
+    const previous = getRuntimeConnectionState(registry, effectiveKey) ?? {
+        transport: 'stdio'
+    };
+    const next = {
+        transport: updates.transport ?? previous.transport ?? 'stdio',
+        connectionId: updates.connectionId ?? previous.connectionId,
+        sessionId: updates.sessionId ?? previous.sessionId,
+        participantId: updates.participantId ?? previous.participantId ?? null,
+        participantSlug: updates.participantSlug ?? previous.participantSlug ?? null,
+        httpPeer: updates.httpPeer ?? previous.httpPeer,
+        // Map to base type fields for compatibility
+        agentId: updates.participantId ?? previous.participantId ?? previous.agentId ?? null,
+        agentSlug: updates.participantSlug ?? previous.participantSlug ?? previous.agentSlug ?? null
+    };
+    registry.setConnectionState(effectiveKey ?? null, next);
+    return next;
+}
+/**
+ * Publish an already-authoritative participant/session receipt into one live
+ * transport context. This is deliberately memory-only: reconnect recovery has
+ * already validated the durable participant mapping and must not create a new
+ * connection row, routing row, presence row, or lease merely to teach the
+ * replacement HTTP transport what it owns.
+ */
+export function bindRuntimeConnectionReceipt(runtime, mcpSessionId, participantId, sessionId) {
+    updateRuntimeConnectionState(mcpSessionRegistryFor(runtime), {
+        transport: 'http',
+        connectionId: mcpSessionId,
+        participantId,
+        sessionId
+    }, mcpSessionId);
+}
+/**
+ * Every session refusal code, mapped onto the CapabilityError taxonomy. The
+ * session code travels as the kebab-case `reason` and as
+ * `details.sessionCode` (compatibility for readers of the old wire code).
+ */
+const SESSION_TOOL_ERROR_CODES = {
+    AMBIGUOUS_BATCH_SEND: 'CONFLICT',
+    BATCH_BROADCAST_UNSUPPORTED: 'INVALID_INPUT',
+    CONNECTION_UNBOUND: 'AUTH_REQUIRED',
+    FORBIDDEN_MARK_READ: 'PERMISSION_DENIED',
+    INVALID_MESSAGE_TARGET: 'INVALID_INPUT',
+    INVALID_PATH: 'INVALID_INPUT',
+    INVALID_SCRATCHPAD_INPUT: 'INVALID_INPUT',
+    INVALID_SCRATCHPAD_TARGET: 'INVALID_INPUT',
+    MESSAGE_TOO_LONG: 'INVALID_INPUT',
+    MISSING_BATCH_ID: 'INVALID_INPUT',
+    MISSING_CONTENT: 'INVALID_INPUT',
+    MISSING_RECIPIENT: 'INVALID_INPUT',
+    NO_BROADCAST_RECIPIENTS: 'NOT_FOUND',
+    NOT_FOUND: 'NOT_FOUND',
+    PARTICIPANT_IDENTITY_REQUIRED: 'AUTH_REQUIRED',
+    PARTICIPANT_NOT_FOUND: 'NOT_FOUND',
+    PROJECT_REF_CONFLICT: 'CONFLICT',
+    PROJECT_REF_UNBOUND: 'CONFLICT',
+    REQUESTED_SESSION_UNRESOLVABLE: 'NOT_FOUND',
+    SCRATCHPAD_ENTRY_NOT_FOUND: 'NOT_FOUND',
+    SESSION_MANAGER_UNAVAILABLE: 'UNAVAILABLE',
+    SESSION_NOT_ACTIVE: 'CONFLICT',
+    SESSION_NOT_FOUND: 'NOT_FOUND',
+    SESSION_RECEIPT_STALE: 'CONFLICT',
+    SESSION_TARGET_REQUIRED: 'INVALID_INPUT',
+    SESSION_REFERENCE_AMBIGUOUS: 'CONFLICT',
+    SESSION_REQUIRED: 'AUTH_REQUIRED',
+    STALE_SESSION_MANAGER: 'UNAVAILABLE',
+    TODO_FILTER_CONFLICT: 'INVALID_INPUT',
+    TODO_GRAPH_CYCLE: 'CONFLICT',
+    TODO_NOT_FOUND: 'NOT_FOUND',
+    UNKNOWN_PARTICIPANT: 'NOT_FOUND',
+    UNKNOWN_RECIPIENT: 'NOT_FOUND'
+};
+/** `SESSION_NOT_ACTIVE` → `session-not-active`. */
+export function sessionToolErrorReason(code) {
+    return code.toLowerCase().replaceAll('_', '-');
+}
+/**
+ * Build a session tool refusal as a typed CapabilityError: the taxonomy code
+ * mapped from `code`, `reason` the kebab-case session code, the hint as its
+ * `recoveryHint`, and `details` (JSON) plus `details.sessionCode`.
+ */
+export function createSessionToolError(code, message, hint, details) {
+    const options = {
+        reason: sessionToolErrorReason(code),
+        details: { ...details, sessionCode: code }
+    };
+    if (hint)
+        options.recoveryHint = hint;
+    return new CapabilityError(message, SESSION_TOOL_ERROR_CODES[code], options);
+}
+/** Whether `error` is the session refusal `code` (read from its reason, never its message). */
+export function isSessionToolError(error, code) {
+    return isCapabilityError(error) && error.reason === sessionToolErrorReason(code);
+}
+/**
+ * Get the one canonical process SessionManager (sync version).
+ *
+ * @deprecated There is no ambient process manager. Resolve the runtime's own
+ * owner instead: `runtime.context('session/manager')` or
+ * `getVibesClient<SessionClient>('session', runtime).getManager()`. Kept
+ * exported for external callers; it always refuses typed.
+ */
+export function getSessionManager() {
+    throw createSessionToolError('SESSION_MANAGER_UNAVAILABLE', 'Session manager is not initialized for this runtime.', 'Resolve runtime.context("session/manager") during surface bootstrap.');
+}
+/**
+ * Resolve the manager owned by an explicit runtime.
+ */
+export async function getSessionManagerAsync(runtime) {
+    if (runtime?.hasContext?.('session/manager')) {
+        return await runtime.context('session/manager');
+    }
+    throw createSessionToolError('SESSION_MANAGER_UNAVAILABLE', 'The runtime has no session/manager context.', 'Ensure the session plugin is registered before using session tools.');
+}
+/**
+ * Ensure session manager is initialized for the runtime.
+ *
+ * @deprecated Pass-through to {@link getSessionManagerAsync}. Use the canonical
+ * owner directly: `runtime.context('session/manager')` or
+ * `getVibesClient<SessionClient>('session', runtime).getManager()`.
+ */
+export function ensureSessionManagerAsync(runtime) {
+    return getSessionManagerAsync(runtime);
+}
+/**
+ * Seed the canonical process SessionManager during surface bootstrap.
+ *
+ * @deprecated The manager is runtime-owned; this is a no-op. Register the
+ * session plugin and resolve `runtime.context('session/manager')` (or
+ * `getVibesClient<SessionClient>('session', runtime).getManager()`) instead.
+ */
+export function setSessionManager(_manager) {
+    // Deprecated: SessionManager is runtime-owned via runtime.context('session/manager').
+}
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SLUG_REGEX = /^[a-z0-9](?:[a-z0-9-]{1,62}[a-z0-9])?$/;
+/**
+ * Hex soup that reads as a BOTCHED UUID (>=20 hex chars once dashes drop) is a
+ * typo'd identity, never a deliberate seat name. Self-identification must
+ * refuse to register these: store-writer reproduced the disease live — one
+ * mistyped UUID digit in fromParticipant minted a phantom whose slug IS the
+ * typo, and the send reported success (stoa L-14, FROM-side).
+ */
+function looksLikeBotchedUuid(reference) {
+    const compact = reference.replace(/-/g, '');
+    return !UUID_REGEX.test(reference) && /^[0-9a-f]{20,}$/i.test(compact);
+}
+export function sanitizeSlugCandidate(candidate) {
+    const normalized = candidate
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+/, '')
+        .replace(/-+$/, '');
+    if (normalized.length === 0) {
+        return 'participant';
+    }
+    return normalized.slice(0, 64);
+}
+/** The profile metadata fields identity reads; each parsed independently, a malformed one is absent. */
+const IdentityMetadataSchema = z.object({
+    slug: z.string().min(1).optional().catch(undefined),
+    clientInfo: z
+        .object({ harnessSessionId: z.string().optional().catch(undefined) })
+        .optional()
+        .catch(undefined),
+    source: z.string().optional().catch(undefined),
+    connectionId: z.string().optional().catch(undefined),
+    registeredAt: z.string().optional().catch(undefined)
+});
+function identityMetadataOf(metadata) {
+    const parsed = IdentityMetadataSchema.safeParse(metadata ?? {});
+    return parsed.success ? parsed.data : {};
+}
+function extractSlug(metadata) {
+    const slug = identityMetadataOf(metadata).slug;
+    return slug ? sanitizeSlugCandidate(slug) : null;
+}
+export async function ensureParticipantSlug(session, participantId, profile) {
+    const resolvedProfile = profile ?? (await session.getParticipant(participantId));
+    if (!resolvedProfile) {
+        throw createSessionToolError('PARTICIPANT_NOT_FOUND', `Participant ${participantId} is not registered in this workspace.`, 'Call `session-participant-list` to inspect registered participants or register a new participant before assignment.');
+    }
+    const existingSlug = extractSlug(resolvedProfile.metadata);
+    if (existingSlug && SLUG_REGEX.test(existingSlug)) {
+        return { profile: resolvedProfile, slug: existingSlug };
+    }
+    const slug = sanitizeSlugCandidate(resolvedProfile.name || participantId);
+    const metadata = {
+        ...resolvedProfile.metadata,
+        clientInfo: StoredClientInfoSchema.parse(resolvedProfile.metadata.clientInfo),
+        slug
+    };
+    await session.updateParticipant(resolvedProfile.participantId, { metadata });
+    return {
+        profile: {
+            ...resolvedProfile,
+            metadata
+        },
+        slug
+    };
+}
+/**
+ * Resolve an already-registered participant without repairing metadata or
+ * registering a new seat. Recovery admission uses this read-only lookup before
+ * deciding whether a legacy bind can take the parallel receipt lane.
+ */
+export async function resolveExistingParticipantReference(reference, session) {
+    const trimmed = reference.trim();
+    if (UUID_REGEX.test(trimmed)) {
+        const profile = await session.getParticipant(trimmed);
+        if (!profile)
+            return null;
+        return {
+            participantId: profile.participantId,
+            profile,
+            slug: extractSlug(profile.metadata) ?? sanitizeSlugCandidate(profile.name || profile.participantId)
+        };
+    }
+    const scan = await scanParticipantsBySlug(session, trimmed);
+    if (!scan.match)
+        return null;
+    return {
+        participantId: scan.match.participantId,
+        profile: scan.match,
+        slug: extractSlug(scan.match.metadata) ??
+            sanitizeSlugCandidate(scan.match.name || scan.match.participantId)
+    };
+}
+/**
+ * Harness conversation ids (Grok TUI, Codex, Claude Code, Muse). Distinct
+ * from the MCP transport `connectionId`, which must never seed a slug —
+ * that minted a participant per hook handshake and buried the roster.
+ * Order is precedence when several are set; a body normally sets one.
+ */
+export const HARNESS_SESSION_ENV_KEYS = [
+    'GROK_SESSION_ID',
+    'CODEX_SESSION_ID',
+    // Claude Code exports CLAUDE_CODE_SESSION_ID; CLAUDE_SESSION_ID was never
+    // set by it, so Claude seats had no harness session and a bare init fell
+    // through to the workspace default session.
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_SESSION_ID',
+    'MUSE_SESSION_ID'
+];
+export function readHarnessSessionIdFromEnv(runtime, env) {
+    // Reads through the handed runtime's environment gateway rather than the
+    // `process` global. This module is reachable from unqualified public exports
+    // (`./mcp/utils/participant`, `./mcp/utils/mcp-session-resolver`), so its
+    // closure has to import in EVERY scope — and `process` does not exist in
+    // workerd. An explicit `env` still wins, which is what the tests pass.
+    for (const key of HARNESS_SESSION_ENV_KEYS) {
+        const value = (env ? env[key] : runtime.getEnv(key))?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** Legacy display key. Never use this truncated value as custody authority. */
+export function shortHarnessSeat(harnessSessionId) {
+    const compact = harnessSessionId.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    return compact.slice(0, 8);
+}
+/** Collision-resistant seat key derived from the complete normalized harness identity. */
+export { harnessSessionSeat };
+/**
+ * A slug derived from identity the client DECLARES about itself, never from
+ * the transport connection it arrived on.
+ *
+ * Two identities live on one body:
+ * - **Kind** (`agentId`, e.g. `grok`) keys presence/brain/storage. Shared.
+ * - **Seat** (participant slug) is this harness conversation. Unique without
+ *   the agent inventing a nickname.
+ *
+ * A connection is how a body reached us. Seeding the slug with `connectionId`
+ * minted a participant per hook handshake and buried the roster. Harness
+ * session id is the interactive seat. `externalToolId` remains the durable
+ * seat for short-lived tool runners.
+ */
+export function declaredIdentitySlug(clientInfo) {
+    if (!clientInfo)
+        return undefined;
+    const seat = harnessSeatOf(clientInfo);
+    if (seat)
+        return harnessSeatSlug(seat);
+    const kind = sanitizeSlugCandidate(clientInfo.agentId || clientInfo.name || '');
+    if (clientInfo.harnessSessionId) {
+        const seat = harnessSessionSeat(clientInfo.harnessSessionId);
+        if (kind && kind !== 'participant' && seat) {
+            const slug = sanitizeSlugCandidate(`${kind}-${seat}`);
+            return slug.length > 0 ? slug : undefined;
+        }
+    }
+    const declared = clientInfo.externalToolId ?? clientInfo.agentId;
+    if (!declared)
+        return undefined;
+    const seed = clientInfo.name ? `${clientInfo.name}-${declared}` : declared;
+    const slug = sanitizeSlugCandidate(seed);
+    return slug.length > 0 ? slug : undefined;
+}
+function legacyDeclaredIdentitySlug(clientInfo) {
+    if (!clientInfo.harnessSessionId)
+        return undefined;
+    const kind = sanitizeSlugCandidate(clientInfo.agentId || clientInfo.name || '');
+    const seat = shortHarnessSeat(clientInfo.harnessSessionId);
+    if (!kind || kind === 'participant' || !seat)
+        return undefined;
+    return sanitizeSlugCandidate(`${kind}-${seat}`);
+}
+function storedHarnessSessionId(profile) {
+    return identityMetadataOf(profile.metadata).clientInfo?.harnessSessionId?.trim().toLowerCase();
+}
+/**
+ * Every participant in STABLE order (participantId ascending), one keyset page
+ * at a time: each page is a single range read of the participantId index, so a
+ * full scan reads each row once. OFFSET paging re-walked every earlier row on
+ * every page, which is quadratic in the directory size.
+ */
+export async function* stableParticipantPages(session, pageSize) {
+    let after;
+    while (true) {
+        const page = await session.listParticipants(after === undefined
+            ? { limit: pageSize, orderBy: 'stable' }
+            : { limit: pageSize, orderBy: 'stable', after });
+        if (page.length > 0)
+            yield page;
+        if (page.length < pageSize)
+            return;
+        after = page[page.length - 1].participantId;
+    }
+}
+/**
+ * Scan the participant directory for a slug in STABLE order.
+ *
+ * Paging over the default recency sort (lastSeenAt desc) is a race: any
+ * participant whose lastSeenAt is bumped mid-scan moves across the page
+ * cursor, so a registered slug can be SKIPPED (→ duplicate registration) or
+ * visited twice (ledger L-19). participantId-ascending is immutable and
+ * unique, so every scanner walks the same total order and — when duplicates
+ * of a slug do exist — every resolver converges on the same deterministic
+ * winner (the first in that order).
+ */
+async function scanParticipantsBySlug(session, slug) {
+    const normalized = sanitizeSlugCandidate(slug);
+    const knownSlugs = new Set();
+    for await (const participants of stableParticipantPages(session, 200)) {
+        for (const participant of participants) {
+            const metadataSlug = extractSlug(participant.metadata);
+            if (metadataSlug)
+                knownSlugs.add(sanitizeSlugCandidate(metadataSlug));
+            if (participant.name)
+                knownSlugs.add(sanitizeSlugCandidate(participant.name));
+            if ((metadataSlug && sanitizeSlugCandidate(metadataSlug) === normalized) ||
+                sanitizeSlugCandidate(participant.name) === normalized ||
+                sanitizeSlugCandidate(participant.participantId) === normalized) {
+                return { match: participant, knownSlugs: Array.from(knownSlugs) };
+            }
+        }
+    }
+    return { match: null, knownSlugs: Array.from(knownSlugs) };
+}
+async function scanLegacyParticipantByHarness(session, legacySlug, harnessSessionId) {
+    const normalizedSlug = sanitizeSlugCandidate(legacySlug);
+    const normalizedHarness = harnessSessionId.trim().toLowerCase();
+    for await (const participants of stableParticipantPages(session, 200)) {
+        for (const participant of participants) {
+            if (extractSlug(participant.metadata) === normalizedSlug &&
+                storedHarnessSessionId(participant) === normalizedHarness) {
+                return participant;
+            }
+        }
+    }
+    return null;
+}
+async function resolveDeclaredIdentityParticipant(session, clientInfo) {
+    const currentSlug = declaredIdentitySlug(clientInfo);
+    if (!currentSlug)
+        return null;
+    const seat = harnessSeatOf(clientInfo);
+    if (seat) {
+        const seated = await session.findHarnessSeat(seat);
+        if (seated) {
+            return { participantId: seated.participantId, profile: seated, slug: currentSlug, legacy: false };
+        }
+    }
+    const current = (await scanParticipantsBySlug(session, currentSlug)).match;
+    if (current) {
+        return { participantId: current.participantId, profile: current, slug: currentSlug, legacy: false };
+    }
+    const legacySlug = legacyDeclaredIdentitySlug(clientInfo);
+    if (!legacySlug || legacySlug === currentSlug || !clientInfo.harnessSessionId)
+        return null;
+    const legacy = await scanLegacyParticipantByHarness(session, legacySlug, clientInfo.harnessSessionId);
+    if (!legacy)
+        return null;
+    return { participantId: legacy.participantId, profile: legacy, slug: currentSlug, legacy: true };
+}
+/** Bounded Levenshtein distance (early-exit above `max`) for typo suggestions. */
+function editDistanceAtMost(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    const previous = Array.from({ length: b.length + 1 }, () => 0);
+    const current = Array.from({ length: b.length + 1 }, () => 0);
+    for (let j = 0; j <= b.length; j++)
+        previous[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        current[0] = i;
+        let rowMin = current[0];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            rowMin = Math.min(rowMin, current[j]);
+        }
+        if (rowMin > max)
+            return max + 1;
+        for (let j = 0; j <= b.length; j++)
+            previous[j] = current[j];
+    }
+    return previous[b.length];
+}
+/** Rank known slugs by closeness to a mistyped reference; top 3 within distance 2 or containment. */
+function suggestNearMissSlugs(target, knownSlugs) {
+    const scored = [];
+    for (const slug of new Set(knownSlugs)) {
+        if (!slug || slug === target)
+            continue;
+        const distance = editDistanceAtMost(target, slug, 2);
+        if (distance <= 2) {
+            scored.push({ slug, distance });
+        }
+        else if (slug.includes(target) || target.includes(slug)) {
+            scored.push({ slug, distance: 3 });
+        }
+    }
+    scored.sort((a, b) => a.distance - b.distance || a.slug.localeCompare(b.slug));
+    return scored.slice(0, 3).map((entry) => entry.slug);
+}
+export async function resolveParticipantReference(reference, sessionManager, mcpSessionId, options = {}) {
+    const session = sessionManager ?? getSessionManager();
+    const trimmed = reference.trim();
+    if (UUID_REGEX.test(trimmed)) {
+        const { profile, slug } = await ensureParticipantSlug(session, trimmed);
+        return { participantId: trimmed, profile, slug, registered: false };
+    }
+    const scan = await scanParticipantsBySlug(session, trimmed);
+    let profile = scan.match;
+    let registered = false;
+    if (!profile) {
+        if (options.registerIfMissing && looksLikeBotchedUuid(trimmed)) {
+            throw createSessionToolError(options.missingCode ?? 'UNKNOWN_PARTICIPANT', `"${trimmed}" reads as a mistyped UUID, not a participant name — refusing to register it as a new identity.`, 'Copy the exact UUID from session status / the roster. If you really meant a new seat, pick a human-readable slug.', { reference: trimmed, suggestions: [] });
+        }
+        if (!options.registerIfMissing) {
+            const sanitized = sanitizeSlugCandidate(trimmed);
+            const suggestions = suggestNearMissSlugs(sanitized, scan.knownSlugs);
+            throw createSessionToolError(options.missingCode ?? 'UNKNOWN_PARTICIPANT', `No participant matches "${trimmed}".${suggestions.length > 0 ? ` Closest registered: ${suggestions.join(', ')}.` : ''}`, 'Copy the exact UUID or slug from session status / the session roster. Participants are only auto-registered when identifying THEMSELVES (init/status participantId, message fromParticipant); a recipient, filter, or assignee must already exist.', { reference: trimmed, suggestions });
+        }
+        const sanitizedSlug = sanitizeSlugCandidate(trimmed);
+        const generatedId = generateId();
+        profile = await session.registerParticipant({
+            participantId: generatedId,
+            name: sanitizedSlug.length > 0 ? sanitizedSlug : `participant-${generatedId.slice(0, 8)}`,
+            role: 'participant',
+            metadata: {
+                source: 'mcp',
+                autoRegistered: true,
+                slug: sanitizedSlug.length > 0 ? sanitizedSlug : undefined
+            }
+        });
+        registered = true;
+        // Registration race guard (ledger L-19): find-then-create has no unique
+        // constraint, so two concurrent self-identifications with the same fresh
+        // slug can BOTH register. Re-scan in stable order and yield to the
+        // deterministic winner, deleting our own extra row so the slug maps to
+        // ONE identity everywhere.
+        const winner = (await scanParticipantsBySlug(session, sanitizedSlug)).match;
+        if (winner && winner.participantId !== profile.participantId) {
+            await deleteLosingDuplicate(session, profile.participantId);
+            profile = winner;
+            registered = false;
+        }
+    }
+    const { profile: ensuredProfile, slug } = await ensureParticipantSlug(session, profile.participantId, profile);
+    return { participantId: ensuredProfile.participantId, profile: ensuredProfile, slug, registered };
+}
+/**
+ * Best-effort cleanup of a registration race loser: the row is seconds old and
+ * unreferenced, so a failed delete leaves it dormant while every resolver
+ * converges on the winner. The failure is reported, value-free, once.
+ */
+async function deleteLosingDuplicate(session, participantId) {
+    // Session's MCP logger on the manager's runtime: that root's sinks and redaction.
+    const logger = getLogger('session:mcp', session.servingRuntime);
+    try {
+        await session.deleteParticipant(participantId);
+    }
+    catch (error) {
+        logger.warn('Failed to delete losing duplicate participant row', {
+            participantId,
+            error: valueFreeFailure(CaughtFailureSchema.parse(error))
+        });
+    }
+}
+/**
+ * Reserved references that mean "everyone in this session" rather than a single
+ * participant slug. Sending to one of these fans out (see
+ * {@link resolveSessionBroadcastRecipients}); it must NEVER be resolved as an
+ * ordinary slug, because {@link resolveParticipantReference} would auto-register
+ * a phantom participant literally named "all"/"everyone" that reaches nobody.
+ */
+export const BROADCAST_KEYWORDS = new Set([
+    'all',
+    'everyone',
+    'everybody',
+    'broadcast',
+    '*'
+]);
+export function isBroadcastReference(reference) {
+    return BROADCAST_KEYWORDS.has(reference.trim().toLowerCase());
+}
+/**
+ * Enumerate the real recipients of a session broadcast.
+ *
+ * Session membership is NOT a first-class durable table — `participant_profiles`
+ * is workspace-global — so membership is derived from durable, session-scoped
+ * signals, unioned for robustness against any single source going cold:
+ *   1. every participant that has sent or received a message in this session
+ *   2. the session owner
+ *   3. anyone with live presence in this session (best-effort; 5-min window)
+ *
+ * The sender is excluded, and any legacy phantom broadcast-keyword participants
+ * (auto-registered "all"/"everyone" from the pre-fix behavior) are filtered out
+ * by slug so a broadcast never re-targets the very phantoms this replaces.
+ */
+export async function resolveSessionBroadcastRecipients(session, sessionId, senderParticipantId) {
+    const candidateIds = new Set();
+    // Union every session-scoped membership signal. Exclusive-preferring
+    // leases delivered to 1 of N when only one lease was live. A signal whose
+    // read fails fails the broadcast: delivering to a silently narrowed set
+    // would report success while reaching only part of the session.
+    for (const lease of await session.listActiveMembershipLeases(sessionId)) {
+        if (lease.participantId)
+            candidateIds.add(lease.participantId);
+    }
+    const messages = await session.getMessages(sessionId, { limit: 5000, offset: 0 });
+    for (const message of messages) {
+        if (message.fromParticipant)
+            candidateIds.add(message.fromParticipant);
+        if (message.toParticipant)
+            candidateIds.add(message.toParticipant);
+    }
+    const sessionData = await session.getSession(sessionId);
+    if (sessionData?.ownerParticipant)
+        candidateIds.add(sessionData.ownerParticipant);
+    if (sessionData?.assignedParticipant)
+        candidateIds.add(sessionData.assignedParticipant);
+    for (const record of await session.getActivePresence(sessionId)) {
+        if (record.participantId)
+            candidateIds.add(record.participantId);
+    }
+    for (const participantId of await session.listBoundParticipantIds(sessionId)) {
+        candidateIds.add(participantId);
+    }
+    candidateIds.delete(senderParticipantId);
+    const recipients = [];
+    for (const participantId of candidateIds) {
+        // Only a confirmed-unregistered id is skipped (a stale reference in history);
+        // a failed read propagates.
+        const profile = await session.getParticipant(participantId);
+        if (!profile)
+            continue;
+        const { slug } = await ensureParticipantSlug(session, participantId, profile);
+        if (BROADCAST_KEYWORDS.has(slug))
+            continue;
+        recipients.push({ participantId, slug });
+    }
+    return recipients;
+}
+async function updateTransportSessionBinding(sessionManager, resolved, mcpSessionId, participantId) {
+    if (!mcpSessionId)
+        return;
+    if (resolved?.status === 'active') {
+        await sessionManager.linkMcpSession(mcpSessionId, resolved.id);
+        await recordTransportPresence(sessionManager, resolved.id, mcpSessionId, participantId);
+        return;
+    }
+    await sessionManager.unlinkMcpSession(mcpSessionId);
+}
+/**
+ * Presence is an advisory liveness signal (a five-minute window), recorded
+ * after the binding itself is durable: a failed write is reported, value-free,
+ * once and never undoes the bind it decorates.
+ */
+async function recordTransportPresence(sessionManager, sessionId, mcpSessionId, participantId) {
+    const logger = getLogger('session:mcp', sessionManager.servingRuntime);
+    try {
+        await sessionManager.recordPresence({
+            sessionId,
+            connectionId: mcpSessionId,
+            participantId: participantId ?? undefined,
+            metadata: { transport: 'mcp-http' }
+        });
+    }
+    catch (error) {
+        logger.warn('Failed to record MCP session presence', {
+            mcpSessionId,
+            error: valueFreeFailure(CaughtFailureSchema.parse(error))
+        });
+    }
+}
+async function setResolvedSession(sessionManager, participantId, session, mcpSessionId, options = {}) {
+    await sessionManager.setParticipantActiveSession(participantId, session.id);
+    if (options.setDefault !== false) {
+        await sessionManager.setDefaultActiveSession(session.id);
+    }
+    await updateTransportSessionBinding(sessionManager, session, mcpSessionId, participantId);
+    return session.id;
+}
+async function resolveFromSession(sessionManager, participantId, candidate, mcpSessionId, options) {
+    if (!candidate || candidate.status === 'archived')
+        return null;
+    const writable = candidate.status === 'paused'
+        ? await sessionManager.openSessionForWork(candidate.id)
+        : candidate;
+    return setResolvedSession(sessionManager, participantId, writable, mcpSessionId, options);
+}
+async function resolveFromId(sessionManager, participantId, sessionId, mcpSessionId, options) {
+    if (!sessionId)
+        return null;
+    // Only a confirmed-missing or archived session falls through to the next
+    // resolution step; a failed read propagates rather than binding elsewhere.
+    const resolved = await sessionManager.getSession(sessionId);
+    if (!resolved || resolved.status === 'archived')
+        return null;
+    const writable = resolved.status === 'paused'
+        ? await sessionManager.openSessionForWork(resolved.id)
+        : resolved;
+    return setResolvedSession(sessionManager, participantId, writable, mcpSessionId, options);
+}
+/**
+ * Bind an explicitly-resolved participant identity to THIS transport connection.
+ *
+ * A seat-scoped `session {action:"status"|"init", participantId}` used to
+ * resolve the participant durably but leave the CONNECTION's identity unbound
+ * — the very next ambient call (no participantId) then ran the anonymous
+ * getOrCreateMCPParticipant path and minted a fresh 'MCP Participant' whose
+ * slug equals its UUID (ledger L-15). Stamping the connection state and the
+ * participant cache here makes the bound identity the ONE ambient resolution
+ * path for the rest of the connection's life.
+ */
+/**
+ * Stable durable connection key for a unix-RPC (stdio-family) seat, scoped by
+ * (workspace, agent).
+ *
+ * The unix daemon is a long-lived, per-workspace process shared by every agent
+ * seated in it (Aris, Rig, ...). A seat bound to it must survive daemon
+ * restarts, so its binding persists under this key via recordConnection /
+ * getParticipantByConnection — the same durable path HTTP transports use with
+ * their connection id. Scoping by agent keeps each seat's binding independent:
+ * the last binder on the shared in-memory slot never shadows another seat's
+ * durable row.
+ *
+ * The digest is FNV-1a (non-cryptographic): this is a storage key, not a
+ * security boundary.
+ */
+export function unixSeatConnectionKey(workspaceRoot, agentId) {
+    const root = String(workspaceRoot ?? '').trim();
+    const agent = String(agentId ?? '').trim().toLowerCase();
+    if (!root || !agent)
+        return undefined;
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < root.length; i++) {
+        hash ^= root.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    const digest = (hash >>> 0).toString(16).padStart(8, '0');
+    return `unix-${agent}-${digest}`;
+}
+/** The participant currently bound to this transport connection, if any. */
+export function getBoundConnectionParticipantId(session, mcpSessionId) {
+    return getRuntimeConnectionState(registryOf(session), mcpSessionId)?.participantId ?? null;
+}
+/**
+ * Durable seat key for an MCP client that declared nothing beyond its kind:
+ * "the <kind> seat in Vibes session <id>".
+ *
+ * Identity used to key on the transport connection id — per-process,
+ * per-connection state that changes on every body restart and every `/mcp`
+ * reconnect. The same Claude Code conversation therefore came back as a NEW
+ * participant each time; mail and todos addressed to the old one were
+ * orphaned and slug lookups broke (session-hygiene wave, 2026-08-28). Keying
+ * the seat on (client kind, session) makes it the same row across restarts.
+ *
+ * Same durable mechanism unix seats use (`recordConnection` /
+ * `getParticipantByConnection`), keyed differently. Two undeclared clients of
+ * the same kind in ONE session cannot be told apart by anything on the wire:
+ * the second keeps a fresh seat while the first is live (see
+ * {@link isSeatLiveElsewhere}); such clients should declare `participantId`
+ * or `harnessSessionId`.
+ */
+export function mcpSeatConnectionKey(clientInfo, sessionId) {
+    if (!sessionId || !UUID_REGEX.test(sessionId))
+        return undefined;
+    const kind = mcpClientKind(clientInfo);
+    if (!kind)
+        return undefined;
+    return `mcp-seat:${kind}:${sessionId.toLowerCase()}`;
+}
+/** Client kind for seat keys and slug seeds: agent family first, product name second. */
+export function mcpClientKind(clientInfo) {
+    if (!clientInfo)
+        return undefined;
+    const kind = sanitizeSlugCandidate(clientInfo.agentId || clientInfo.name || '');
+    return kind && kind !== 'participant' ? kind : undefined;
+}
+const SEAT_LIVE_WINDOW_MS = 2 * 60 * 1000;
+/**
+ * True when ANOTHER registered transport connection in this process is bound
+ * to the participant and spoke within the liveness window. A fresh daemon has
+ * an empty registry, so a restart never blocks a reclaim; a context left
+ * behind by a client that vanished without DELETE ages out of "live" after
+ * the window even though the registry retains it for hours.
+ */
+export function isSeatLiveElsewhere(registry, participantId, mcpSessionId, now = Date.now()) {
+    for (const id of registry.getActiveSessionIds()) {
+        if (id === mcpSessionId)
+            continue;
+        const context = registry.peek(id);
+        const state = context?.connectionState;
+        const bound = state?.participantId ?? state?.agentId ?? null;
+        if (bound !== participantId)
+            continue;
+        if (now - (context?.lastActivityAt ?? 0) < SEAT_LIVE_WINDOW_MS)
+            return true;
+    }
+    return false;
+}
+/** Same-kind undeclared clients sharing one session get ordinal seats up to this. */
+const MCP_SEAT_ORDINALS = 8;
+/**
+ * Find the seat this client kind may take in `sessionId`: the first ordinal
+ * slot that is either free or recorded for a participant no other live
+ * connection holds. Pure lookup: binds and records nothing. Null when the key
+ * cannot be formed or every slot is held by a live connection.
+ */
+export async function reclaimMcpSeat(session, clientInfo, sessionId, mcpSessionId) {
+    const base = mcpSeatConnectionKey(clientInfo, sessionId);
+    if (!base)
+        return null;
+    const registry = registryOf(session);
+    for (let ordinal = 1; ordinal <= MCP_SEAT_ORDINALS; ordinal++) {
+        const seatKey = ordinal === 1 ? base : `${base}#${ordinal}`;
+        // A storage failure propagates: only a confirmed-absent row is a free
+        // seat. Reading a failed lookup as "no seat" minted a duplicate identity.
+        const profile = await session.getParticipantByConnection(seatKey);
+        if (!profile)
+            return { seatKey, profile: null };
+        if (isSeatLiveElsewhere(registry, profile.participantId, mcpSessionId))
+            continue;
+        return { seatKey, profile };
+    }
+    return null;
+}
+/** Persist "this participant is the <kind> seat in <session>" under a resolved key. */
+export async function recordMcpSeat(session, clientInfo, seatKey, participantId) {
+    await session.recordConnection({
+        connectionId: seatKey,
+        participantId,
+        clientName: clientInfo?.name ?? 'MCP Client',
+        clientVersion: clientInfo?.version
+    });
+    return seatKey;
+}
+const AMBIENT_MINT_RETIRE_WINDOW_MS = 10 * 60 * 1000;
+/**
+ * Retire the participant the ambient pre-call minted for THIS connection once
+ * the bind resolved a different durable seat. Without this, every restart left
+ * one more ghost row in the roster. Guarded so nothing older, foreign, or
+ * referenced is ever removed: the row must be this connection's own auto-mint,
+ * minutes old, and own no session. Best-effort — a ghost that survives is
+ * dormant, never authoritative.
+ */
+export async function retireAmbientMint(session, ghostParticipantId, mcpSessionId) {
+    const profile = await session.getParticipant(ghostParticipantId);
+    if (!profile)
+        return false;
+    const metadata = identityMetadataOf(profile.metadata);
+    if (metadata.source !== 'mcp')
+        return false;
+    if (metadata.connectionId !== (mcpSessionId ?? 'mcp-unknown'))
+        return false;
+    const registeredAt = metadata.registeredAt === undefined ? Number.NaN : Date.parse(metadata.registeredAt);
+    if (!Number.isFinite(registeredAt) || Date.now() - registeredAt > AMBIENT_MINT_RETIRE_WINDOW_MS) {
+        return false;
+    }
+    const owned = await session.countSessions({ ownerParticipant: ghostParticipantId });
+    if (owned > 0)
+        return false;
+    await session.clearParticipantActiveSession(ghostParticipantId);
+    await session.deleteParticipant(ghostParticipantId);
+    return true;
+}
+/**
+ * Retire an ambient mint as the advisory cleanup the bind promises: a ghost
+ * that survives is dormant, never authoritative, so a failed retirement is
+ * reported, value-free, once and never fails the bind that already succeeded.
+ */
+export async function retireAmbientMintAfterBind(session, ghostParticipantId, mcpSessionId) {
+    const logger = getLogger('session:mcp', session.servingRuntime);
+    try {
+        await retireAmbientMint(session, ghostParticipantId, mcpSessionId);
+    }
+    catch (error) {
+        logger.warn('Ambient mint retirement failed; leaving the participant in place', {
+            participantId: ghostParticipantId,
+            error: valueFreeFailure(CaughtFailureSchema.parse(error))
+        });
+    }
+}
+export async function bindConnectionParticipant(session, participantId, slug, mcpSessionId, seatKey, options = {}) {
+    const effectiveConnectionId = mcpSessionId ?? seatKey;
+    const registry = registryOf(session);
+    const connectionUpdate = { participantId, participantSlug: slug };
+    if (effectiveConnectionId)
+        connectionUpdate.connectionId = effectiveConnectionId;
+    updateRuntimeConnectionState(registry, connectionUpdate, effectiveConnectionId);
+    // Seed the ambient participant cache under every key getOrCreateMCPParticipant
+    // derives (the participant id AND the connection key), so ambient calls
+    // resolve this identity without re-running the registration path. The cache
+    // is reset first: after a rebind (seat reclaim, self-identification) a stale
+    // connection-key entry would keep answering with the previous, possibly
+    // retired, participant.
+    const cache = getParticipantCache(registry, effectiveConnectionId);
+    cache.clear();
+    cache.set(participantId.toLowerCase(), Promise.resolve(participantId));
+    const connectionKey = effectiveConnectionId ?? getRuntimeConnectionState(registry, effectiveConnectionId)?.connectionId;
+    if (connectionKey)
+        cache.set(connectionKey.toLowerCase(), Promise.resolve(participantId));
+    // HTTP transports carry a durable connection id; unix seats carry a stable
+    // (workspace, agent) seat key. Persist the binding under either so
+    // caller-identity lookups (getParticipantByConnection) survive daemon
+    // restarts. Plain stdio has no durable connection id; its binding lives in
+    // the transport context above for the life of the process.
+    const durableConnectionId = effectiveConnectionId;
+    if (durableConnectionId && options.persistConnection !== false) {
+        const clientInfo = getRuntimeClientInfo(registry, effectiveConnectionId);
+        await session.recordConnection({
+            connectionId: durableConnectionId,
+            participantId,
+            clientName: clientInfo?.name ?? (seatKey ? 'unix-seat' : 'MCP Client'),
+            clientVersion: clientInfo?.version
+        });
+    }
+}
+/**
+ * Get or create participant ID for MCP client.
+ * Uses Layer 2 identification (connection-based) unless a preferred ID is supplied.
+ * @param clientInfo - Optional client info from MCP connection
+ * @param options - Optional participant options
+ * @param mcpSessionId - MCP session ID for HTTP transport isolation
+ */
+export async function getOrCreateMCPParticipant(clientInfo, options = {}, mcpSessionId, caller, sessionManager, workspaceRoot) {
+    // Durable seat key for unix-RPC (stdio-family) transports: scoped by
+    // (workspace, agent) so each seat on the shared per-workspace daemon keeps
+    // its own persisted binding. HTTP transports keep their connection id.
+    const seatKey = mcpSessionId ? undefined : unixSeatConnectionKey(workspaceRoot, caller?.agentId);
+    // The serving root's manager and transport registry: every connection read
+    // and write below is that root's, never another root's in this process.
+    const session = sessionManager ?? (await getSessionManagerAsync());
+    const registry = registryOf(session);
+    // The admitted connection this call belongs to: the transport's key, or the
+    // seat's own key. Its in-memory state, client info and cache are read and
+    // written under this key only; a seat-keyed bind never answers from the
+    // process-wide stdio slot, which is whichever connection bound last.
+    const connectionScope = mcpSessionId ?? seatKey;
+    // The stdio slot (keyed null) is the in-memory home of a plain-stdio bind
+    // (no seat key): that bind writes no durable row, so a later seat-keyed
+    // ambient read must still resolve it from the slot until the seat persists.
+    // A seat-keyed bind never writes the stdio slot, so this fallback cannot
+    // leak one agent's seat to another (per-agent scope).
+    const runtimeConnection = getRuntimeConnectionState(registry, connectionScope) ??
+        (mcpSessionId ? undefined : getRuntimeConnectionState(registry, null));
+    const hasExplicitIdentity = Boolean(options.preferredParticipantId?.trim() ||
+        options.preferredSlug?.trim() ||
+        caller?.participantId?.trim());
+    const hasBoundIdentity = Boolean(runtimeConnection?.participantId);
+    // The refusal must key on a REGISTERED HTTP transport context — never on
+    // the mere truthiness of the mcpSessionId string. Callers that mistake the
+    // slot for a session-scoped id (brain passed scope.qualifiers.sessionId
+    // here) have no registered context; keying on truthiness let them sail past
+    // the guard and phantom-mint (stoa L-23 adversarial, 2026-07-17).
+    const isRegisteredTransport = Boolean(mcpSessionId) &&
+        (runtimeConnection?.transport === 'http' ||
+            runtimeConnection?.transport === 'stdio' ||
+            Boolean(runtimeConnection?.connectionId) ||
+            Boolean(getRuntimeClientInfo(registry, mcpSessionId)));
+    // Anonymous stdio (no transport id and no agent-scoped seat key) may create
+    // its connection identity. Once an agent id produces a durable seat key,
+    // bind-once applies: a missing row must refuse instead of minting a new seat.
+    // A truthy mcpSessionId that is NOT registered HTTP is likewise the L-23
+    // injury (a Vibes session UUID stuffed into the transport slot).
+    const isAnonymousStdioTransport = !mcpSessionId && !seatKey;
+    const runtimeClientInfo = getRuntimeClientInfo(registry, connectionScope);
+    const effectiveClientInfo = clientInfo ?? runtimeClientInfo;
+    const explicitParticipantId = options.preferredParticipantId?.trim() ??
+        caller?.participantId?.trim() ??
+        undefined;
+    // A seat's key is its admitted identity and wins over any client-supplied
+    // connection id, so the same seat always resolves the same durable row.
+    const connectionKeySource = seatKey ??
+        effectiveClientInfo?.connectionId ??
+        runtimeConnection?.connectionId ??
+        'mcp-unknown';
+    // Durable binding for this connection key (HTTP connection id or unix seat
+    // key), consulted BEFORE the in-memory slot: the slot is last-binder-wins
+    // and shared across agents on the unix daemon, while the row is scoped to
+    // this seat. On a fresh daemon process the slot is empty but the row
+    // survives — this is what makes a unix seat bind-once.
+    // A storage failure propagates: the in-memory slot cannot stand in for the
+    // durable row, and reading a failed lookup as absence mints a second seat.
+    let persistedParticipant = null;
+    if (connectionKeySource !== 'mcp-unknown') {
+        persistedParticipant = (await session.getParticipantByConnection(connectionKeySource)) ?? null;
+    }
+    if (!isRegisteredTransport &&
+        !isAnonymousStdioTransport &&
+        !hasBoundIdentity &&
+        !hasExplicitIdentity &&
+        !(seatKey && persistedParticipant)) {
+        throw createSessionToolError('CONNECTION_UNBOUND', 'Cannot resolve an ambient participant before this connection identifies itself.', 'Call session init or status with participantId first, or pass fromParticipant for a self-identifying message.', { transport: runtimeConnection?.transport ?? 'stdio', requiresIdentity: true });
+    }
+    const cacheKey = (explicitParticipantId || connectionKeySource).toLowerCase();
+    // The admitted connection's own cache (the stdio transport's only when the
+    // call has neither a transport key nor a seat key).
+    // IMPORTANT: Don't cache for 'mcp-unknown' key to prevent cross-contamination
+    // between different Claude Code instances sharing the same MCP server
+    const cache = getParticipantCache(registry, connectionScope);
+    const shouldCache = cacheKey !== 'mcp-unknown';
+    if (shouldCache) {
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+    }
+    const createParticipantPromise = (async () => {
+        // Priority: explicit identity → durable seat row (scoped) → in-memory
+        // slot (last-binder-wins) → durable row for non-seat connection keys.
+        const preferredIdCandidate = explicitParticipantId ??
+            (seatKey ? persistedParticipant?.participantId : undefined) ??
+            runtimeConnection?.participantId ??
+            persistedParticipant?.participantId;
+        // A client that declared a durable identity gets the seat it already owns
+        // rather than a fresh one per connection. Reuses the same stable-order
+        // scan the self-identification path uses (ledger L-19), so concurrent
+        // reconnects converge on one winner instead of racing to register.
+        const declaredSlug = declaredIdentitySlug(effectiveClientInfo);
+        let declaredSeatId;
+        let declaredSeatWasLegacy = false;
+        if (!preferredIdCandidate && declaredSlug && effectiveClientInfo) {
+            const seated = await resolveDeclaredIdentityParticipant(session, effectiveClientInfo);
+            declaredSeatId = seated?.participantId;
+            declaredSeatWasLegacy = seated?.legacy === true;
+            // A harness conversation's seat is derived, not minted: register it
+            // under its derived id so the harness hook resolves the same row.
+            const seat = harnessSeatOf(effectiveClientInfo);
+            if (!declaredSeatId && seat) {
+                declaredSeatId = (await session.ensureHarnessSeat({
+                    ...seat,
+                    name: effectiveClientInfo.name,
+                    source: 'mcp'
+                })).participantId;
+            }
+        }
+        // An UNDECLARED client (bare product name) reaching a fresh body: reclaim
+        // the seat its kind holds in the workspace's durable default session
+        // before minting. Nothing stable arrives on the wire for such a client,
+        // so this — not the transport connection id — is what survives a daemon
+        // restart. `session init` re-keys the seat to the session it binds.
+        // A lookup failure propagates; only a confirmed-free seat falls through to a mint.
+        let reclaimedSeatId;
+        if (!preferredIdCandidate && !declaredSlug) {
+            const anchor = await session.getDefaultActiveSession();
+            const reclaimed = await reclaimMcpSeat(session, effectiveClientInfo, anchor, mcpSessionId);
+            reclaimedSeatId = reclaimed?.profile?.participantId;
+        }
+        // Generate participant identifier from provided references or random UUID
+        let participantId;
+        if (preferredIdCandidate && UUID_REGEX.test(preferredIdCandidate)) {
+            participantId = preferredIdCandidate;
+        }
+        else if (preferredIdCandidate) {
+            const slugCandidate = sanitizeSlugCandidate(preferredIdCandidate);
+            participantId = slugCandidate.startsWith('participant-')
+                ? slugCandidate
+                : `participant-${slugCandidate}`;
+        }
+        else if (declaredSeatId) {
+            participantId = declaredSeatId;
+        }
+        else if (reclaimedSeatId) {
+            participantId = reclaimedSeatId;
+        }
+        else {
+            participantId = generateId();
+        }
+        // Slug seed is NEVER the transport connection id (session/SPEC.md hard
+        // rule). Seeding it minted `claude-code-<Mcp-Session-Id>` on every
+        // reconnect and broke slug lookups after each restart. A fresh seat is
+        // `<kind>-<8 of its own id>`: stable for the row's life and independent
+        // of how it connected.
+        const kind = mcpClientKind(effectiveClientInfo);
+        const slugSeed = options.preferredSlug ??
+            declaredSlug ??
+            (kind
+                ? `${kind}-${participantId.replace(/^participant-/, '').slice(0, 8)}`
+                : runtimeConnection?.httpPeer?.remoteAddress
+                    ? `peer-${runtimeConnection.httpPeer.remoteAddress}`
+                    : participantId.replace(/^participant-/, ''));
+        const slug = sanitizeSlugCandidate(slugSeed);
+        // Check if participant exists
+        const existing = await session.getParticipant(participantId);
+        if (!existing) {
+            const registration = {
+                source: 'mcp',
+                connectionId: connectionKeySource,
+                transport: runtimeConnection?.transport ?? effectiveClientInfo?.transport ?? 'stdio',
+                httpPeer: runtimeConnection?.httpPeer,
+                registeredAt: new Date().toISOString(),
+                slug
+            };
+            if (effectiveClientInfo)
+                registration.clientInfo = effectiveClientInfo;
+            // Register new participant
+            await session.registerParticipant({
+                participantId,
+                name: effectiveClientInfo?.name || 'MCP Participant',
+                role: 'assistant',
+                capabilities: [
+                    'session-management',
+                    'todo-tracking',
+                    'scratchpad-notes',
+                    'code-analysis',
+                    'planning'
+                ],
+                metadata: registration
+            });
+        }
+        else {
+            if (options.preferredSlug || declaredSeatWasLegacy) {
+                const metadata = { ...existing.metadata, slug };
+                if (effectiveClientInfo)
+                    metadata.clientInfo = effectiveClientInfo;
+                await session.updateParticipant(existing.participantId, { metadata });
+            }
+            await ensureParticipantSlug(session, existing.participantId, existing);
+        }
+        const ensured = await session.ensureParticipantSession(participantId);
+        if (ensured) {
+            await updateTransportSessionBinding(session, ensured, mcpSessionId, participantId);
+        }
+        if (connectionKeySource !== 'mcp-unknown') {
+            await session.recordConnection({
+                connectionId: connectionKeySource,
+                participantId,
+                clientName: effectiveClientInfo?.name ?? 'MCP Client',
+                clientVersion: effectiveClientInfo?.version
+            });
+        }
+        updateRuntimeConnectionState(registry, {
+            transport: runtimeConnection?.transport ?? 'stdio',
+            // 'mcp-unknown' is a sentinel for "no durable connection key", not a
+            // real transport id: writing it would store anonymous-stdio state
+            // under a key the next ambient read never consults, minting a fresh
+            // participant on every call (stoa L-23).
+            connectionId: connectionKeySource === 'mcp-unknown' ? undefined : connectionKeySource,
+            sessionId: runtimeConnection?.sessionId,
+            participantId: participantId,
+            participantSlug: slug,
+            httpPeer: runtimeConnection?.httpPeer
+        }, connectionScope);
+        return participantId;
+    })().catch((error) => {
+        cache.delete(cacheKey);
+        throw error;
+    });
+    if (shouldCache) {
+        cache.set(cacheKey, createParticipantPromise);
+    }
+    return createParticipantPromise;
+}
+/**
+ * Normalize a caller-supplied participant reference to a registered UUID
+ * before it touches session resolution. The durable participant→session map
+ * is UUID-keyed: a raw slug READ misses it (ghost SESSION_NOT_ACTIVE on
+ * stdio) and a raw slug WRITE pollutes it with slug keys (ledger L-04). This
+ * chokepoint never registers — self-identification sites resolve (and may
+ * register) BEFORE calling into session resolution.
+ */
+async function normalizeParticipantIdForSessionResolution(reference, session, mcpSessionId) {
+    const trimmed = reference.trim();
+    if (UUID_REGEX.test(trimmed))
+        return trimmed;
+    const resolved = await resolveParticipantReference(trimmed, session, mcpSessionId);
+    return resolved.participantId;
+}
+/**
+ * The canonical scope-bound vibes session, when a surface announced one.
+ *
+ * `session.bound` (emitted by session init / MCP serve lifecycle / CLI
+ * bootstrap) records the bind in the session registry, which feeds each
+ * invocation's `scope.actor.sessionId`. Brain already resolves its bound
+ * session from there; the session family ignored it — two resolution paths for
+ * one concern (stoa L-09 seam, cross-lane with cog-writer). The reader is the
+ * runtime's `boundSessionIdOf`; brain uses it too. Note the TRANSPORT key
+ * (the MCP connection id, never a declared-scope qualifier) is deliberately
+ * excluded — transport→session mapping already resolves durably via
+ * getSessionForMcpConnection.
+ */
+export function getScopeBoundSessionId(runtime, caller) {
+    return boundSessionIdOf(runtime?.scope, caller);
+}
+/** The participant identity committed alongside the ambient session bind (the invocation actor's). */
+export function getScopeBoundParticipantId(runtime, caller) {
+    const callerParticipantId = caller?.participantId?.trim();
+    if (callerParticipantId)
+        return callerParticipantId;
+    const actorParticipantId = runtime?.scope?.actor?.participantId?.trim();
+    return actorParticipantId ? actorParticipantId : null;
+}
+/**
+ * Get session ID from input or active session
+ * @param sessionId - Optional explicit session ID
+ * @param participantId - Optional participant ID
+ * @param mcpSessionId - MCP session ID for HTTP transport isolation
+ */
+export async function resolveSessionIdForParticipant(sessionId, participantId, mcpSessionId, options = {}, sessionManager, runtime) {
+    const session = sessionManager ?? getSessionManager();
+    if (sessionId && options.intent === 'read') {
+        // Pure lookup: no resume, no participant-map write, no workspace-default
+        // retarget, no transport link. Archived sessions stay archived and are
+        // readable in place (ledger L-13).
+        const existing = await session.getSession(sessionId);
+        if (!existing) {
+            throw createSessionToolError('SESSION_NOT_FOUND', `Session ${sessionId} was not found.`, 'Provide a valid sessionId or call session-init first.');
+        }
+        return existing.id;
+    }
+    if (!participantId && options.intent === 'read' && !sessionId) {
+        const scopeBoundId = getScopeBoundSessionId(runtime, options.caller);
+        if (scopeBoundId) {
+            const existing = await session.getSession(scopeBoundId);
+            if (!existing) {
+                throw createSessionToolError('SESSION_NOT_FOUND', `Session ${scopeBoundId} was not found.`, 'Provide a valid sessionId or call session-init first.');
+            }
+            return existing.id;
+        }
+    }
+    if (!participantId && options.intent === 'read') {
+        participantId =
+            getScopeBoundParticipantId(runtime, options.caller) ??
+                (await resolveBoundMCPParticipant(undefined, mcpSessionId, session, options)) ??
+                undefined;
+        if (!participantId) {
+            throw createSessionToolError('CONNECTION_UNBOUND', 'An unbound session read cannot create a participant.', 'Identify this connection or supply an existing sessionId first.');
+        }
+    }
+    const resolvedParticipantId = participantId
+        ? await normalizeParticipantIdForSessionResolution(participantId, session, mcpSessionId)
+        : await getOrCreateMCPParticipant(undefined, {}, mcpSessionId, options.caller, session);
+    if (sessionId) {
+        const existing = await session.getSession(sessionId);
+        if (!existing) {
+            throw createSessionToolError('SESSION_NOT_FOUND', `Session ${sessionId} was not found.`, 'Provide a valid sessionId or call session-init first.');
+        }
+        if (existing.status === 'archived') {
+            throw createSessionToolError('SESSION_NOT_ACTIVE', `Session ${sessionId} is archived; this mutation will not reopen it implicitly.`, `Call session { action: "resume", sessionId: "${sessionId}" } first if reopening this collaboration is intentional.`);
+        }
+        const writable = existing.status === 'paused' ? await session.openSessionForWork(sessionId) : existing;
+        return setResolvedSession(session, resolvedParticipantId, writable, mcpSessionId, {
+            setDefault: !mcpSessionId
+        });
+    }
+    const boundSession = mcpSessionId ? await session.getSessionForMcpConnection(mcpSessionId) : null;
+    const resolvedFromBinding = await resolveFromSession(session, resolvedParticipantId, boundSession, mcpSessionId, { setDefault: false });
+    if (resolvedFromBinding)
+        return resolvedFromBinding;
+    const mappedId = await session.getParticipantActiveSession(resolvedParticipantId);
+    const resolvedFromMap = await resolveFromId(session, resolvedParticipantId, mappedId, mcpSessionId, {
+        setDefault: false
+    });
+    if (resolvedFromMap)
+        return resolvedFromMap;
+    // Canonical scope-bound session (session.bound → session registry →
+    // invocation actor.sessionId) — the SAME source brain resolves. Honored after the
+    // caller's own durable bindings so an explicit participant mapping always
+    // wins, and before failing SESSION_NOT_ACTIVE (stoa L-09 seam).
+    const scopeBoundId = getScopeBoundSessionId(runtime, options.caller);
+    const resolvedFromScope = await resolveFromId(session, resolvedParticipantId, scopeBoundId, mcpSessionId, { setDefault: false });
+    if (resolvedFromScope)
+        return resolvedFromScope;
+    // Do not adopt the workspace default or "the" active session. Listing
+    // related rows is the unbound receipt; attaching is an explicit init.
+    // No session found - provide helpful error
+    // For stdio transport without mcpSessionId, this is expected behavior:
+    // each Claude instance should explicitly init its own session
+    const unbound = await unboundSessionErrorFields(session, {
+        workspacePath: options.workspaceRoot
+    });
+    throw createSessionToolError('SESSION_NOT_ACTIVE', unbound.message, unbound.hint, unbound.details);
+}
+/**
+ * Resolve the identity ALREADY bound to this transport connection without
+ * minting, caching, or registering anything. Returns null when the connection
+ * is genuinely unbound. Read-intent callers use this so a bound seat still
+ * satisfies identity-shaped filters (e.g. todo list `mine=true`) while a
+ * virgin stdio connection resolves sessions identity-free (ledger L-23).
+ */
+export async function resolveBoundMCPParticipant(clientInfo, mcpSessionId, sessionManager, callerOrOptions, workspaceRoot) {
+    const options = resolutionOptionsOf(callerOrOptions, workspaceRoot);
+    const caller = options.caller;
+    const resolvedWorkspaceRoot = options.workspaceRoot;
+    const manager = sessionManager ?? (await getSessionManagerAsync());
+    const registry = registryOf(manager);
+    const callerSeatKey = mcpSessionId
+        ? undefined
+        : unixSeatConnectionKey(resolvedWorkspaceRoot, caller?.agentId);
+    if (callerSeatKey) {
+        const persisted = await manager.getParticipantByConnection(callerSeatKey);
+        if (persisted?.participantId)
+            return persisted.participantId;
+    }
+    const effectiveKey = mcpSessionId ?? callerSeatKey ?? clientInfo?.connectionId;
+    const runtimeConnection = effectiveKey
+        ? getRuntimeConnectionState(registry, effectiveKey)
+        : getRuntimeConnectionState(registry, mcpSessionId);
+    if (runtimeConnection?.participantId) {
+        if (!effectiveKey ||
+            !runtimeConnection.connectionId ||
+            runtimeConnection.connectionId === effectiveKey) {
+            return runtimeConnection.participantId;
+        }
+    }
+    const runtimeClientInfo = getRuntimeClientInfo(registry, effectiveKey ?? mcpSessionId);
+    const connectionId = clientInfo?.connectionId ??
+        effectiveKey ??
+        runtimeClientInfo?.connectionId ??
+        runtimeConnection?.connectionId ??
+        undefined;
+    if (!connectionId)
+        return null;
+    const persisted = await manager.getParticipantByConnection(connectionId);
+    return persisted?.participantId ?? null;
+}
+/** The caller and workspace root, from either the options form or the legacy positional caller. */
+function resolutionOptionsOf(callerOrOptions, workspaceRoot) {
+    if (callerOrOptions === undefined)
+        return { workspaceRoot };
+    if (isResolutionOptions(callerOrOptions)) {
+        return { caller: callerOrOptions.caller, workspaceRoot: callerOrOptions.workspaceRoot };
+    }
+    return { caller: callerOrOptions, workspaceRoot };
+}
+function isResolutionOptions(value) {
+    return 'caller' in value || 'workspaceRoot' in value;
+}
+/**
+ * Resolve the participant an already-known HTTP client seat owned before a
+ * host replacement. This is deliberately read-only: recovery admission may
+ * reuse durable authority, but it must never mint a participant merely because
+ * an old relay replayed its pre-receipt `session init` request.
+ */
+export async function resolveExistingMcpParticipant(clientInfo, mcpSessionId, sessionManager) {
+    const bound = await resolveBoundMCPParticipant(clientInfo, mcpSessionId, sessionManager);
+    if (bound)
+        return resolveExistingParticipantReference(bound, sessionManager);
+    const effectiveClientInfo = clientInfo ?? getRuntimeClientInfo(registryOf(sessionManager), mcpSessionId);
+    const declaredSlug = declaredIdentitySlug(effectiveClientInfo);
+    if (declaredSlug && effectiveClientInfo) {
+        const resolved = await resolveDeclaredIdentityParticipant(sessionManager, effectiveClientInfo);
+        if (resolved) {
+            return {
+                participantId: resolved.participantId,
+                profile: resolved.profile,
+                slug: extractSlug(resolved.profile.metadata) ?? resolved.slug
+            };
+        }
+        return null;
+    }
+    const anchor = await sessionManager.getDefaultActiveSession();
+    if (!anchor)
+        return null;
+    const reclaimed = await reclaimMcpSeat(sessionManager, effectiveClientInfo, anchor, mcpSessionId);
+    if (!reclaimed?.profile)
+        return null;
+    return resolveExistingParticipantReference(reclaimed.profile.participantId, sessionManager);
+}
+/**
+ * Ensure session context is available
+ * @param sessionId - Optional explicit session ID
+ * @param participantId - Optional participant ID
+ * @param mcpSessionId - MCP session ID for HTTP transport isolation
+ */
+export async function ensureSessionContext(sessionId, participantId, mcpSessionId, options = {}, runtime) {
+    const session = await getSessionManagerAsync(runtime);
+    return ensureSessionContextWithManager(session, runtime, sessionId, participantId, mcpSessionId, options);
+}
+/**
+ * Manager-bound form used by cross-feature consumers resolving the registered
+ * `session/manager` context. It never falls back to a second ambient manager.
+ */
+export async function ensureSessionContextWithManager(session, runtime, sessionId, participantId, mcpSessionId, options = {}) {
+    const readOnly = options.intent === 'read';
+    const participant = participantId ??
+        (readOnly
+            ? (options.caller?.participantId?.trim() ??
+                (await resolveBoundMCPParticipant(undefined, mcpSessionId, session, { caller: options.caller, workspaceRoot: options.workspaceRoot })) ??
+                getScopeBoundParticipantId(runtime) ??
+                undefined)
+            : await getOrCreateMCPParticipant(undefined, {}, mcpSessionId, options.caller, session, options.workspaceRoot));
+    if (readOnly && !participant && !sessionId && !getScopeBoundSessionId(runtime, options.caller)) {
+        throw createSessionToolError('CONNECTION_UNBOUND', 'An unbound session read cannot create a participant.', 'Identify this connection or supply an existing sessionId first.');
+    }
+    const resolvedSessionId = await resolveSessionIdForParticipant(sessionId, participant, mcpSessionId, options, session, runtime);
+    const sessionData = await session.getSession(resolvedSessionId);
+    return { session, sessionId: resolvedSessionId, participantId: participant, sessionData };
+}
+/**
+ * Refresh session state from database
+ * @param sessionManager - Optional session manager instance
+ * @param mcpSessionId - MCP session ID for HTTP transport isolation
+ */
+export async function refreshSessionState(sessionManager, mcpSessionId) {
+    const session = sessionManager ?? getSessionManager();
+    if (!mcpSessionId)
+        return;
+    const defaultId = await session.getDefaultActiveSession();
+    const resolved = defaultId ? await session.getSession(defaultId) : null;
+    await updateTransportSessionBinding(session, resolved, mcpSessionId);
+}
+/**
+ * The participant a transport's connection state names: `participantId`, or
+ * `agentId`, which mirrors it and is the field the MCP surface keeps when it
+ * restamps the connection.
+ */
+const membershipIdentitySchema = z.object({
+    participantId: z.string().nullish(),
+    agentId: z.string().nullish()
+});
+/**
+ * Renew the durable membership lease while the MCP transport remains alive.
+ * Tool-activity heartbeats are useful, but they are insufficient when an agent
+ * is thinking or waiting for another lane; the transport registry supplies the
+ * missing liveness clock.
+ */
+async function renewTransportMembershipLease(runtime, registry, mcpSessionId) {
+    const state = registry.getConnectionState(mcpSessionId);
+    if (!state)
+        return;
+    const identity = membershipIdentitySchema.parse(state);
+    const participantId = identity.participantId ?? identity.agentId;
+    if (!participantId)
+        return;
+    const session = await getSessionManagerAsync(runtime);
+    const sessionId = state.sessionId ??
+        (mcpSessionId
+            ? (await session.getSessionForMcpConnection(mcpSessionId))?.id
+            : null) ??
+        (await session.getParticipantActiveSession(participantId));
+    if (!sessionId)
+        return;
+    // Archive closes membership, and only the explicit resume action reopens it:
+    // a transport whose recorded session was archived or removed renews no claim
+    // on it (the rule getSessionForMcpConnection applies to the durable mapping).
+    const target = await session.getSession(sessionId);
+    if (!target || target.status === 'archived')
+        return;
+    await session.acquireMembershipLease({
+        sessionId,
+        participantId,
+        connectionKey: state.connectionId ?? mcpSessionId ?? 'local'
+    });
+}
+/** Resolve the declared manager before admitting any renewal timers. */
+export async function attachMcpMembershipOwner(runtime, registry = mcpSessionRegistryFor(runtime)) {
+    await getSessionManagerAsync(runtime);
+    return registry.attachMembershipOwner(runtime, (id) => renewTransportMembershipLease(runtime, registry, id));
+}
+// The registry class and the per-root accessor; no process-wide registry exists.
+export { McpSessionRegistry, mcpSessionRegistryFor };
+export { buildUnboundSessionGuidance, isSessionDiscoveryCall, renderUnboundSessionGuidance, UNBOUND_SESSION_HINT, unboundSessionErrorFields } from "./unbound-guidance.js";
+//# sourceMappingURL=participant.js.map