@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/dist/daemon/iroh-service.js

@@ -0,0 +1,2604 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { createIrohRemoteExplicitAccess, createIrohRemotePresetAccess, getIrohRemoteRpcCommandCapabilities, getIrohRemoteStreamCapability, getMissingIrohRemoteRpcCapability, hasIrohRemoteRpcCapability, parseIrohRemoteRpcCapabilities, parseIrohRemoteRpcGrant, } from "../core/remote/iroh/access-grant.js";
+import { IrohRemoteActiveStreamRegistry } from "../core/remote/iroh/active-stream-registry.js";
+import { hashIrohRemotePairingSecret } from "../core/remote/iroh/authorization.js";
+import { DEFAULT_IROH_REMOTE_PAIRING_TICKET_TTL_MS, IrohRemoteHostEngine, } from "../core/remote/iroh/engine.js";
+import { createIrohRemoteHandshakeFailure } from "../core/remote/iroh/handshake.js";
+import { DEFAULT_IROH_REMOTE_HANDSHAKE_MAX_LINE_BYTES, DEFAULT_IROH_REMOTE_HANDSHAKE_TIMEOUT_MS, writeIrohRemoteHandshakeResponse, } from "../core/remote/iroh/handshake-reader.js";
+import { resolveIrohRemoteWorkspaceProjectTrusted } from "../core/remote/iroh/host-policy.js";
+import { IROH_REMOTE_ALPN, resolveIrohRemoteRuntimeToolPolicy } from "../core/remote/iroh/protocol.js";
+import { IrohRemoteInMemoryPushNotificationDeduper, IrohRemotePushNotificationDispatcher, IrohRemotePushRelayHttpClient, revokeIrohRemoteClientPushTargets, } from "../core/remote/iroh/push.js";
+import { createIrohRemoteRpcCapabilityDeniedResponse, createIrohRemoteRpcErrorResponse, } from "../core/remote/iroh/rpc-command-filter.js";
+import { IROH_REMOTE_WORKSPACE_HAS_WORKTREES_ERROR, isIrohRemoteWorkspaceHasWorktreesError, } from "../core/remote/iroh/state-manager.js";
+import { getIrohRemoteWorkspaceAvailabilityStatus } from "../core/remote/iroh/workspace.js";
+import { getDefaultSessionDir } from "../core/session-manager.js";
+import { getCurrentThemeName, getResolvedThemeColors } from "../core/theme/runtime.js";
+import { ProjectTrustStore } from "../core/trust-manager.js";
+import { runIrohRemoteRpcMode } from "../modes/rpc/iroh-remote-rpc-mode.js";
+import { CONTROL_RPC_GRANTS_CAPABILITY, CONTROL_WORKTREES_CAPABILITY, RELAY_RPC_COMMAND_TYPES, } from "./control-protocol.js";
+import { createKeepAwakeRpcResponse, createRemoteRegisterLiveActivityRpcResponse, createRemoteUnregisterLiveActivityRpcResponse, createRpcSuccessResponse, createWebSearchKeyRpcResponse, getRpcResponseId, handleIntegratedConversationRpcCommand, handleRemoteHostRpcCommand, REMOTE_SESSION_LIST_CURSOR_TTL_MS, toRpcKeepAwakeStatus, } from "./conversation-commands.js";
+import { createIntegratedConversationHandshakeResponse, decorateRemoteHostState, } from "./handshake-responses.js";
+import { createConversationOpenError, getResolvedTargetSessionId, IntegratedRuntimeRegistry, } from "./integrated-runtimes.js";
+import { formatIrohLoadError, loadIrohModule, } from "./iroh-native.js";
+import { IrohRemoteResourceGuard } from "./iroh-resource-guard.js";
+import { LeaseBroker } from "./lease-broker.js";
+import { RELAY_TOKEN_TTL_MS, RelayRegistry } from "./relay-stream.js";
+import { createSessionManagerTargetStore, resolveIrohRemoteSessionTarget, } from "./session-target.js";
+import { resolveWorktreeCleanupPolicy } from "./state.js";
+import { createHostThemeTokensFrame, HOST_THEME_TOKENS_FEATURE } from "./theme-push.js";
+import { ViewerFeedRegistry } from "./viewer-feed.js";
+import { isPathInside } from "./workspace-directory.js";
+import { runWorkspaceDiscoveryStream, runWorkspaceManagementStream, runWorktreeManagementStream, WORKSPACE_UNREGISTERED_CLOSE_REASON, writeIrohRemoteJsonLine, } from "./workspace-streams.js";
+import { evaluateWorktreeRelayGate, getRegisteredWorkingDirectoryForWorktree, getWorkspaceWorktreesDir, getWorktreesRoot, handleWorktreeControlRequest, isWorktreeControlRequest, WorktreeManager, WorktreeRetentionSweeper, } from "./worktree-manager.js";
+const ACTIVE_REVOKE_CLOSE_REASON = "revoked";
+const ACTIVE_REPLACE_CLOSE_REASON = "replaced";
+const DUPLICATE_CONVERSATION_RETRY_AFTER_MS = 500;
+const RELAY_OFFER_RETRY_AFTER_MS = 1000;
+const WORKSPACE_DISCOVERY_STREAM_SESSION_ID = "$workspace-discovery";
+const WORKSPACE_MANAGEMENT_STREAM_SESSION_ID = "$workspace-management";
+const IROH_ENDPOINT_READY_TIMEOUT_MS = 15_000;
+const IROH_UNAUTHENTICATED_CONNECTION_TIMEOUT_MS = 15_000;
+const SHUTDOWN_RUNTIME_IDLE_CAP_MS = 60_000;
+export function collectClientAuthorityInvalidationRuntimes(activeStreams, runtimes, clientNodeId) {
+    const clientEntries = activeStreams.entriesForClientNodeId(clientNodeId);
+    return new Set(Array.from(runtimes).filter((runtime) => runtime.clientNodeId === clientNodeId ||
+        clientEntries.some((entry) => entry.workspaceName === runtime.workspaceName && entry.sessionId === runtime.sessionId)));
+}
+export function collectClientAuthorityInvalidationStreams(activeStreams, runtimes, clientNodeId) {
+    const runtimeList = Array.from(runtimes);
+    const entries = new Set(activeStreams.entriesForClientNodeId(clientNodeId));
+    for (const runtime of collectClientAuthorityInvalidationRuntimes(activeStreams, runtimeList, clientNodeId)) {
+        for (const entry of activeStreams.entriesForConversationKey(runtime.workspaceName, runtime.sessionId)) {
+            entries.add(entry);
+        }
+    }
+    return entries;
+}
+function getRelativeWorkingDirectoryForRoot(rootPath, cwd) {
+    const root = resolve(rootPath);
+    const child = resolve(cwd);
+    if (!isPathInside(root, child)) {
+        return null;
+    }
+    const relativePath = relative(root, child);
+    return relativePath.length === 0 || relativePath === "." ? undefined : relativePath.split(sep).join("/");
+}
+/**
+ * Defensive cap on concurrent in-flight bi-streams per client connection. A
+ * well-behaved client keeps only a handful open (one conversation + a few
+ * utility streams); an authenticated-but-misbehaving client could otherwise open
+ * unbounded concurrent streams, each spawning a runtime attach, and exhaust
+ * daemon resources. Hitting the cap closes the connection.
+ */
+const MAX_CONCURRENT_STREAMS_PER_CONNECTION = 64;
+let activeConnectionSequence = 0;
+let activeStreamSequence = 0;
+/**
+ * The Volt-operated relay fleet. Endpoints bind against these by default
+ * ("production" mode); the n0 public relays ("development" mode) are for
+ * development only and must be opted into via VOLT_IROH_RELAY_MODE=development.
+ */
+export const VOLT_PRODUCTION_RELAY_URLS = ["https://iroh-relay-us-central.volt-cli.dev"];
+/**
+ * Resolves the effective relay configuration. Precedence: explicit service
+ * config, then VOLT_IROH_RELAY_MODE / VOLT_IROH_RELAY_URLS, then the Volt
+ * production relay fleet.
+ */
+export function resolveIrohRelayConfig(config, env = process.env) {
+    const envUrls = parseRelayUrlsEnv(env.VOLT_IROH_RELAY_URLS);
+    const envModeValue = env.VOLT_IROH_RELAY_MODE?.trim();
+    let envMode;
+    let warning;
+    if (envModeValue !== undefined && envModeValue !== "") {
+        if (envModeValue === "disabled" || envModeValue === "development" || envModeValue === "production") {
+            envMode = envModeValue;
+        }
+        else {
+            warning = `ignoring invalid VOLT_IROH_RELAY_MODE "${envModeValue}" (expected disabled, development, or production)`;
+        }
+    }
+    const relayMode = config.relayMode ?? envMode ?? "production";
+    const configuredUrls = config.relayUrls ?? envUrls;
+    const relayUrls = relayMode === "production" ? (configuredUrls ?? VOLT_PRODUCTION_RELAY_URLS) : (configuredUrls ?? []);
+    return { relayMode, relayUrls, ...(warning === undefined ? {} : { warning }) };
+}
+function parseRelayUrlsEnv(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const urls = value
+        .split(",")
+        .map((url) => url.trim())
+        .filter((url) => url.length > 0);
+    return urls.length > 0 ? urls : undefined;
+}
+function isExpectedApplicationClose(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes("ConnectionLost(ApplicationClosed") &&
+        message.includes("error_code: 0") &&
+        (message.includes('reason: b"done"') ||
+            message.includes(`reason: b"${ACTIVE_REVOKE_CLOSE_REASON}"`) ||
+            message.includes(`reason: b"${ACTIVE_REPLACE_CLOSE_REASON}"`) ||
+            message.includes(`reason: b"${WORKSPACE_UNREGISTERED_CLOSE_REASON}"`)));
+}
+function closeConnection(connection, reason) {
+    try {
+        connection.close(0n, Array.from(Buffer.from(reason, "utf8")));
+    }
+    catch {
+        // Transport closure is best-effort; registry/task cleanup must still run.
+    }
+}
+async function waitForConnectionClose(connection) {
+    await Promise.race([
+        connection.closed().catch(() => { }),
+        new Promise((resolveDelay) => {
+            setTimeout(resolveDelay, 500);
+        }),
+    ]);
+}
+async function withTimeout(promise, timeoutMs, message) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+function closeIrohRemoteStream(stream, _reason) {
+    void Promise.resolve(stream.send.finish?.()).catch(() => { });
+    void Promise.resolve(stream.recv.stop?.(0n)).catch(() => { });
+}
+function getRemoteTerminalReason(reason) {
+    if (reason === ACTIVE_REVOKE_CLOSE_REASON) {
+        return "client_revoked";
+    }
+    if (reason === WORKSPACE_UNREGISTERED_CLOSE_REASON ||
+        reason === "workspace_authorization_removed" ||
+        reason === "lease_transferred" ||
+        reason === "session_rekeyed_reconnect") {
+        return reason;
+    }
+    return undefined;
+}
+/**
+ * The daemon's Iroh host: owns the endpoint identity, pairing, revocation,
+ * headless integrated runtimes, workspace/device streams, push dispatch, and
+ * the accept loop. Ported from the dissolved src/remote/iroh-host.mjs.
+ */
+export function createIrohDaemonService(config = {}) {
+    return (services) => {
+        const log = services.logger.child("iroh");
+        const loaded = loadIrohModule();
+        if (!loaded.iroh) {
+            log("warn", formatIrohLoadError(loaded.error));
+            return {
+                async handleRequest(connection, request) {
+                    if (request.type === "pair_request") {
+                        connection.send({
+                            type: "error",
+                            id: request.id,
+                            code: "iroh_unavailable",
+                            message: formatIrohLoadError(loaded.error),
+                        });
+                        return true;
+                    }
+                    return false;
+                },
+            };
+        }
+        const service = new IrohDaemonService(loaded.iroh, services, config);
+        void service.start();
+        return {
+            handleRequest: (connection, request) => service.handleRequest(connection, request),
+            onConnectionClosed: (connection) => service.onControlConnectionClosed(connection),
+            onThemeChanged: () => service.onThemeChanged(),
+            onKeepAwakeChanged: () => service.onKeepAwakeChanged(),
+            statusExtras: () => service.statusExtras(),
+            admitRelay: (relayId, relayToken, socket, bufferedRemainder) => service.admitRelay(relayId, relayToken, socket, bufferedRemainder),
+            shutdown: () => service.shutdown(),
+        };
+    };
+}
+class IrohDaemonService {
+    iroh;
+    services;
+    relayMode;
+    relayUrls;
+    relayAuthToken;
+    relayConfigWarning;
+    log;
+    stateManager;
+    activeStreams = new IrohRemoteActiveStreamRegistry();
+    clientConnections = new Map();
+    connectionTasks = new Set();
+    resourceGuard = new IrohRemoteResourceGuard();
+    pendingPairRequests = new Map();
+    sessionListCursors = new Map();
+    pushRelayClient;
+    pushNotificationDeduper = new IrohRemoteInMemoryPushNotificationDeduper();
+    trustStore;
+    runtimes;
+    worktrees;
+    worktreeRetention;
+    leaseBroker;
+    viewerFeeds;
+    relays = new RelayRegistry();
+    endpoint;
+    engine;
+    hostNodeId;
+    endpointTicket;
+    shuttingDown = false;
+    ready;
+    constructor(iroh, services, config) {
+        this.iroh = iroh;
+        this.services = services;
+        const relayConfig = resolveIrohRelayConfig(config);
+        this.relayMode = relayConfig.relayMode;
+        this.relayUrls = relayConfig.relayUrls;
+        this.relayConfigWarning = relayConfig.warning;
+        const envRelayAuthToken = process.env.VOLT_IROH_RELAY_AUTH_TOKEN?.trim();
+        this.relayAuthToken =
+            config.relayAuthToken ??
+                (envRelayAuthToken !== undefined && envRelayAuthToken !== "" ? envRelayAuthToken : undefined) ??
+                services.state.state.settings.relayAuthToken;
+        // Persist a newly seen token so bare restarts keep authenticating against
+        // the relay without re-exporting the env var.
+        if (this.relayAuthToken !== undefined && this.relayAuthToken !== services.state.state.settings.relayAuthToken) {
+            services.state.updateSettings({ relayAuthToken: this.relayAuthToken });
+        }
+        this.log = services.logger.child("iroh");
+        this.stateManager = services.stateManager;
+        this.trustStore = new ProjectTrustStore(services.agentDir);
+        this.pushRelayClient = new IrohRemotePushRelayHttpClient({
+            authToken: config.pushRelayAuthToken ?? process.env.VOLT_PUSH_RELAY_AUTH_TOKEN,
+            baseUrl: config.pushRelayUrl ?? process.env.VOLT_PUSH_RELAY_URL,
+        });
+        this.runtimes = new IntegratedRuntimeRegistry({
+            agentDir: services.agentDir,
+            profile: config.profile,
+            auditLogger: services.auditLogger,
+            stateManager: this.stateManager,
+            activeStreams: this.activeStreams,
+            detachedRuntimeTtlMs: () => services.state.state.settings.detachedRuntimeTtlMs,
+            getToolPolicy: (workspace, clientAllowTools) => resolveIrohRemoteRuntimeToolPolicy({
+                clientAllowTools,
+                workspaceAllowTools: workspace.allowedTools,
+                daemonAllowTools: services.state.state.settings.allowTools,
+            }),
+            getProjectTrustedForWorkspace: (workspace) => resolveIrohRemoteWorkspaceProjectTrusted(workspace, { trustStore: this.trustStore }),
+            setClientLastSessionId: (nodeId, workspace, sessionId) => this.requireEngine().setClientLastSessionId(nodeId, workspace, sessionId),
+            resolveWorktree: (workspaceName, hello, targetSessionId) => this.resolveConversationWorktree(workspaceName, hello, targetSessionId),
+            resolveWorkingDirectory: (options) => this.resolveConversationWorkingDirectory(options),
+            bindWorktreeSession: (workspaceName, worktreeId, sessionId) => this.worktrees.bindSession(workspaceName, worktreeId, sessionId),
+            onRuntimeRekeyed: (workspaceName, previousSessionId, sessionId) => this.leaseBroker.rekey(workspaceName, previousSessionId, sessionId),
+            onRuntimeDisposed: (entry, reason) => {
+                this.leaseBroker.onDaemonRuntimeDisposed(entry.workspaceName, entry.sessionId, reason);
+                if (entry.worktreeId !== undefined) {
+                    this.worktreeRetention.onRuntimeDisposed(entry.workspaceName, entry.worktreeId);
+                }
+            },
+        });
+        this.worktrees = new WorktreeManager({
+            agentDir: services.agentDir,
+            stateManager: this.stateManager,
+            auditLogger: services.auditLogger,
+            hasActiveRuntimeForSession: (workspaceName, sessionId) => this.runtimes.findOwner(workspaceName, sessionId) !== undefined,
+            flushState: () => services.state.flush(),
+        });
+        this.worktreeRetention = new WorktreeRetentionSweeper({
+            manager: this.worktrees,
+            stateManager: this.stateManager,
+            auditLogger: services.auditLogger,
+            getRetentionPolicy: () => resolveWorktreeCleanupPolicy(services.state.state.settings).retention,
+        });
+        this.viewerFeeds = new ViewerFeedRegistry({
+            sendTo: (connectionId, event) => services.controlServer.sendTo(connectionId, event),
+        });
+        this.leaseBroker = new LeaseBroker({
+            isRuntimeStreaming: (workspaceName, sessionId) => this.runtimes.findOwner(workspaceName, sessionId)?.runtime.session.isBusy ?? false,
+            waitForRuntimeIdle: async (workspaceName, sessionId) => {
+                await this.runtimes.findOwner(workspaceName, sessionId)?.runtime.session.waitForIdle();
+            },
+            disposeRuntime: async (workspaceName, sessionId, reason) => {
+                const owner = this.runtimes.findOwner(workspaceName, sessionId);
+                if (owner) {
+                    await this.runtimes.stopEntry(owner, reason);
+                }
+            },
+            closePhoneStreams: async (workspaceName, sessionId, reason) => {
+                await this.closeActiveStreamsForConversationKey(workspaceName, sessionId, reason);
+            },
+            closeRelays: (record, reason) => {
+                for (const relayId of Array.from(record.relayIds)) {
+                    this.relays.closeActive(relayId, reason);
+                    // Unredeemed offers must not linger until the 10s token expiry:
+                    // fail the phone's deferred handshake immediately so it retries
+                    // against the new lease owner.
+                    this.abortPendingRelay(relayId, reason, "relay offer cancelled; retry", RELAY_OFFER_RETRY_AFTER_MS);
+                }
+            },
+            onDrainStarted: (record, viewerFeedId) => {
+                const owner = this.runtimes.findOwner(record.workspaceName, record.sessionId);
+                if (owner && record.tuiConnectionId) {
+                    this.viewerFeeds.start(viewerFeedId, record.tuiConnectionId, owner.runtime.session);
+                }
+            },
+            onDrainEnded: (_record, viewerFeedId, reason) => {
+                this.viewerFeeds.end(viewerFeedId, reason);
+            },
+            audit: (event) => {
+                void this.logAudit({
+                    type: event.type,
+                    workspace: event.workspaceName,
+                    success: true,
+                    details: { sessionId: event.sessionId, ...event.details },
+                });
+            },
+        });
+        let readyResolve = () => { };
+        let readyReject = () => { };
+        const readyPromise = new Promise((resolve, reject) => {
+            readyResolve = resolve;
+            readyReject = reject;
+        });
+        readyPromise.catch(() => { });
+        this.ready = { promise: readyPromise, resolve: readyResolve, reject: readyReject };
+    }
+    requireEngine() {
+        if (!this.engine) {
+            throw new Error("iroh host engine is not ready");
+        }
+        return this.engine;
+    }
+    async pruneWorktreesOnStart() {
+        if (!resolveWorktreeCleanupPolicy(this.services.state.state.settings).pruneOnStart) {
+            return;
+        }
+        try {
+            const state = await this.stateManager.getState();
+            const workspacesWithRecords = new Set((state.worktrees ?? []).map((worktree) => worktree.workspaceName));
+            for (const workspace of state.workspaces) {
+                // Skip workspaces with neither records nor checkout directories: no git
+                // subprocesses or audit noise on the common no-worktrees start.
+                if (!workspacesWithRecords.has(workspace.name) &&
+                    !existsSync(getWorkspaceWorktreesDir(this.services.agentDir, workspace.path))) {
+                    continue;
+                }
+                try {
+                    await this.worktrees.prune(workspace);
+                }
+                catch (error) {
+                    this.log("warn", "worktree prune failed on start", {
+                        workspace: workspace.name,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        catch {
+            // Startup prune is best-effort; a manual `volt remote worktree prune` covers it.
+        }
+    }
+    getResponseContext() {
+        return {
+            hostNodeId: this.hostNodeId,
+            relayMode: this.relayMode,
+            ...(this.relayMode === "production" ? { relayUrls: this.relayUrls } : {}),
+        };
+    }
+    async isAuthorizationGrantCurrent(authorization) {
+        const client = await this.stateManager.getClient(authorization.client.nodeId);
+        return client?.rpcGrant.revision === authorization.client.rpcGrant.revision;
+    }
+    getCommandContext(conversation) {
+        return {
+            agentDir: this.services.agentDir,
+            auditLogger: this.services.auditLogger,
+            hostEngine: this.engine,
+            stateManager: this.stateManager,
+            sessionListCursors: this.sessionListCursors,
+            sessionListCursorTtlMs: REMOTE_SESSION_LIST_CURSOR_TTL_MS,
+            listRuntimeStates: (workspaceName) => {
+                const states = new Map();
+                for (const record of this.leaseBroker.list()) {
+                    if (record.workspaceName === workspaceName && record.state !== "unowned") {
+                        states.set(record.sessionId, record.state);
+                    }
+                }
+                return states;
+            },
+            keepAwake: this.services.keepAwake,
+            onKeepAwakeSetting: (enabled) => this.services.state.updateSettings({ keepAwakeEnabled: enabled }),
+            webSearchKey: this.services.webSearchKey,
+            createWorktreeBackend: (workspace) => this.createWorktreeRpcBackend(workspace),
+            onWorkspaceUnregistered: async (workspaceName) => {
+                // Unregistering the conversation's own workspace keeps the requesting
+                // stream and runtime alive so the response can still be delivered
+                // (mirrors the workspace-management stream path).
+                const excludeOwn = conversation !== undefined && workspaceName === conversation.workspaceName;
+                const workspacePath = excludeOwn ? conversation.workspacePath : undefined;
+                await this.cleanupUnregisteredWorkspace(workspaceName, excludeOwn
+                    ? { streamEntry: conversation.streamEntry, runtimeEntry: conversation.entry, workspacePath }
+                    : {});
+            },
+            ...(conversation === undefined
+                ? {}
+                : {
+                    isDraining: () => this.leaseBroker.isDraining(conversation.workspaceName, conversation.entry.sessionId),
+                    isSubagentSession: () => conversation.entry.subagentId !== undefined || conversation.entry.parentSessionId !== undefined,
+                }),
+        };
+    }
+    async start() {
+        let endpoint;
+        if (this.relayConfigWarning !== undefined) {
+            this.log("warn", this.relayConfigWarning);
+        }
+        // Reconcile worktree records/checkouts before the endpoint starts taking
+        // conversations (design §5.3 pruneOnStart; default on, quarantine-only).
+        await this.pruneWorktreesOnStart();
+        try {
+            const builder = this.iroh.Endpoint.builder();
+            if (this.relayMode === "development") {
+                this.log("warn", "using public n0 relays (development only; unset VOLT_IROH_RELAY_MODE for the Volt relays)");
+                this.iroh.presetN0(builder);
+            }
+            else if (this.relayMode === "production") {
+                if (this.relayUrls.length === 0) {
+                    throw new Error("relayMode production requires relay URLs (config.relayUrls or VOLT_IROH_RELAY_URLS)");
+                }
+                this.iroh.presetN0DisableRelay(builder);
+                if (this.relayAuthToken !== undefined) {
+                    const relayMap = this.iroh.RelayMap.empty();
+                    for (const url of this.relayUrls) {
+                        relayMap.insert({ url, authToken: this.relayAuthToken });
+                    }
+                    builder.relayMode(this.iroh.RelayMode.custom(relayMap));
+                }
+                else {
+                    builder.relayMode(this.iroh.RelayMode.customFromUrls(this.relayUrls));
+                }
+            }
+            else {
+                this.iroh.presetMinimal(builder);
+                builder.relayMode(this.iroh.RelayMode.disabled());
+            }
+            const secretKey = this.services.state.state.irohSecretKey;
+            if (secretKey) {
+                builder.secretKey(secretKey);
+            }
+            builder.alpns([Array.from(Buffer.from(IROH_REMOTE_ALPN, "utf8"))]);
+            endpoint = await builder.bind();
+            if (!secretKey) {
+                const boundKey = endpoint.secretKey().toBytes();
+                this.services.state.setHostState({
+                    ...this.services.state.getHostState(),
+                    hostSecretKey: boundKey,
+                });
+                // Persist the freshly minted identity synchronously before the accept
+                // loop starts taking pairings. A crash/SIGKILL inside the 250ms debounce
+                // window would otherwise lose the key, and every phone paired against
+                // this endpoint would be talking to a node id the daemon can never
+                // reproduce on restart.
+                await this.services.state.flush();
+            }
+            if (this.relayMode !== "disabled") {
+                await endpoint.online();
+            }
+            this.endpoint = endpoint;
+            this.hostNodeId = endpoint.id().toString();
+            this.endpointTicket = this.iroh.EndpointTicket.fromAddr(endpoint.addr()).toString();
+            this.engine = new IrohRemoteHostEngine({
+                auditLogger: this.services.auditLogger,
+                classifyWorkspaceAvailability: getIrohRemoteWorkspaceAvailabilityStatus,
+                hostNodeId: this.hostNodeId,
+                relayMode: this.relayMode,
+                ...(this.relayMode === "production" ? { relayUrls: this.relayUrls } : {}),
+                stateManager: this.stateManager,
+                validateWorkspace: async (workspace) => (await getIrohRemoteWorkspaceAvailabilityStatus(workspace)) === "available",
+                workspace: { name: "voltd", path: this.services.agentDir },
+            });
+            this.ready.resolve();
+            this.log("info", `iroh endpoint online`, {
+                hostNodeId: this.hostNodeId,
+                relayMode: this.relayMode,
+                ...(this.relayMode === "production" ? { relayUrls: this.relayUrls } : {}),
+            });
+            void this.acceptLoop(endpoint);
+        }
+        catch (error) {
+            if (endpoint) {
+                // bind() succeeded but a later start step (e.g. online()) failed before
+                // the endpoint was adopted; close it so its QUIC socket is not leaked.
+                try {
+                    await endpoint.close();
+                }
+                catch { }
+                if (this.endpoint === endpoint) {
+                    this.endpoint = undefined;
+                }
+            }
+            this.ready.reject(error);
+            this.log("error", `failed to start iroh endpoint: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async acceptLoop(endpoint) {
+        while (!this.shuttingDown) {
+            let incoming;
+            try {
+                incoming = await endpoint.acceptNext();
+            }
+            catch (error) {
+                if (this.shuttingDown) {
+                    break;
+                }
+                this.log("error", `accept failed: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            if (!incoming) {
+                break;
+            }
+            const connectionAdmission = this.resourceGuard.tryAcquireConnectionTask();
+            if (!connectionAdmission.ok) {
+                let refused = true;
+                try {
+                    await incoming.refuse();
+                }
+                catch {
+                    refused = false;
+                }
+                await this.logAudit({
+                    type: "iroh_security_connection_limit",
+                    success: false,
+                    error: "incoming connection refused at daemon connection-task limit",
+                    details: {
+                        limit: connectionAdmission.limit,
+                        refused,
+                        scope: connectionAdmission.scope,
+                    },
+                });
+                continue;
+            }
+            const task = this.handleConnection(incoming)
+                .catch((error) => {
+                if (!isExpectedApplicationClose(error)) {
+                    this.log("error", `connection error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                }
+            })
+                .finally(() => {
+                this.connectionTasks.delete(task);
+                connectionAdmission.lease.release();
+            });
+            this.connectionTasks.add(task);
+        }
+    }
+    async handleConnection(incoming) {
+        let connection;
+        try {
+            const accepting = await incoming.accept();
+            connection = await accepting.connect();
+        }
+        catch {
+            await this.logAudit({
+                type: "iroh_security_transport_rejected",
+                success: false,
+                error: "incoming transport handshake failed",
+                details: { phase: "transport_connect" },
+            });
+            return;
+        }
+        try {
+            connection.setMaxConcurrentBiStreams(BigInt(MAX_CONCURRENT_STREAMS_PER_CONNECTION));
+        }
+        catch {
+            closeConnection(connection, "stream_limit_configuration_failed");
+            await waitForConnectionClose(connection);
+            await this.logAudit({
+                type: "iroh_security_transport_rejected",
+                success: false,
+                error: "connected transport could not enforce the inbound stream limit",
+                details: { phase: "stream_limit_configuration" },
+            });
+            return;
+        }
+        let remoteId;
+        try {
+            remoteId = connection.remoteId().toString();
+        }
+        catch {
+            closeConnection(connection, "invalid_remote_identity");
+            await waitForConnectionClose(connection);
+            await this.logAudit({
+                type: "iroh_security_transport_rejected",
+                success: false,
+                error: "connected transport did not expose a valid remote identity",
+                details: { phase: "remote_identity" },
+            });
+            return;
+        }
+        const nodeConnectionAdmission = this.resourceGuard.tryAcquireNodeConnection(remoteId);
+        if (!nodeConnectionAdmission.ok) {
+            closeConnection(connection, "node_connection_limit");
+            await waitForConnectionClose(connection);
+            await this.logAudit({
+                type: "iroh_security_connection_limit",
+                clientNodeId: remoteId,
+                success: false,
+                error: "connection refused at per-node connection limit",
+                details: { limit: nodeConnectionAdmission.limit, scope: nodeConnectionAdmission.scope },
+            });
+            return;
+        }
+        const unauthenticatedAdmission = this.resourceGuard.tryAcquireUnauthenticatedConnection(remoteId);
+        if (!unauthenticatedAdmission.ok) {
+            nodeConnectionAdmission.lease.release();
+            closeConnection(connection, "unauthenticated_connection_limit");
+            await waitForConnectionClose(connection);
+            await this.logAudit({
+                type: "iroh_security_unauthenticated_connection_limit",
+                clientNodeId: remoteId,
+                success: false,
+                error: "unauthenticated connection refused at admission limit",
+                details: { limit: unauthenticatedAdmission.limit, scope: unauthenticatedAdmission.scope },
+            });
+            return;
+        }
+        const connectionId = `conn-${++activeConnectionSequence}`;
+        const removeClientConnection = this.registerClientConnection(remoteId, connection, connectionId);
+        const streamTasks = new Set();
+        let acceptedStreamCount = 0;
+        let closeRequested = false;
+        let authenticated = false;
+        const unauthenticatedTimer = setTimeout(() => {
+            if (authenticated || closeRequested)
+                return;
+            closeRequested = true;
+            closeConnection(connection, "handshake_timeout");
+            void this.logAudit({
+                type: "iroh_security_handshake_timeout",
+                clientNodeId: remoteId,
+                success: false,
+                error: "connection did not authenticate before the handshake deadline",
+                details: { connectionId, timeoutMs: IROH_UNAUTHENTICATED_CONNECTION_TIMEOUT_MS },
+            });
+        }, IROH_UNAUTHENTICATED_CONNECTION_TIMEOUT_MS);
+        unauthenticatedTimer.unref?.();
+        const markAuthenticated = async () => {
+            if (authenticated)
+                return true;
+            if (closeRequested)
+                return false;
+            authenticated = true;
+            clearTimeout(unauthenticatedTimer);
+            unauthenticatedAdmission.lease.release();
+            this.log("info", `client connection opened: ${remoteId} (${connectionId})`);
+            await this.logAudit({
+                type: "client_connected",
+                clientNodeId: remoteId,
+                success: true,
+                details: { connectionId },
+            });
+            return true;
+        };
+        const requestCloseWhenIdle = () => {
+            if (closeRequested || acceptedStreamCount === 0 || streamTasks.size > 0) {
+                return;
+            }
+            closeRequested = true;
+            closeConnection(connection, "done");
+        };
+        try {
+            while (!closeRequested) {
+                const stream = await (!authenticated
+                    ? withTimeout(connection.acceptBi(), DEFAULT_IROH_REMOTE_HANDSHAKE_TIMEOUT_MS, "handshake timed out")
+                    : connection.acceptBi());
+                acceptedStreamCount++;
+                if (streamTasks.size >= MAX_CONCURRENT_STREAMS_PER_CONNECTION) {
+                    // One connection is holding too many concurrent streams open. Refuse
+                    // further work and close the connection rather than let
+                    // it exhaust daemon resources; the just-accepted stream is torn down
+                    // with the connection. A legitimate client never reaches this.
+                    closeRequested = true;
+                    closeConnection(connection, "stream_limit_exceeded");
+                    await this.logAudit({
+                        type: "iroh_security_stream_limit",
+                        clientNodeId: remoteId,
+                        success: false,
+                        error: "connection exceeded concurrent stream limit",
+                        details: { connectionId, limit: MAX_CONCURRENT_STREAMS_PER_CONNECTION, scope: "connection" },
+                    });
+                    break;
+                }
+                const streamAdmission = this.resourceGuard.tryAcquireActiveStream(remoteId);
+                if (!streamAdmission.ok) {
+                    closeIrohRemoteStream(stream, "stream_limit_exceeded");
+                    await this.logAudit({
+                        type: "iroh_security_stream_limit",
+                        clientNodeId: remoteId,
+                        success: false,
+                        error: "stream refused at daemon active-stream limit",
+                        details: { connectionId, limit: streamAdmission.limit, scope: streamAdmission.scope },
+                    });
+                    requestCloseWhenIdle();
+                    continue;
+                }
+                const streamId = `stream-${++activeStreamSequence}`;
+                const task = this.handleConnectionStream(stream, connection, remoteId, connectionId, streamId, markAuthenticated)
+                    .catch(async (error) => {
+                    if (!isExpectedApplicationClose(error)) {
+                        if (authenticated) {
+                            this.log("error", `stream error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+                        }
+                        else {
+                            await this.logAudit({
+                                type: "iroh_security_transport_rejected",
+                                clientNodeId: remoteId,
+                                success: false,
+                                error: "unauthenticated stream failed",
+                                details: { connectionId, phase: "stream_handshake" },
+                            });
+                        }
+                    }
+                })
+                    .finally(() => {
+                    streamAdmission.lease.release();
+                    streamTasks.delete(task);
+                    requestCloseWhenIdle();
+                });
+                streamTasks.add(task);
+            }
+        }
+        catch (error) {
+            if (acceptedStreamCount === 0 && authenticated) {
+                throw error;
+            }
+            if (acceptedStreamCount === 0 && !closeRequested) {
+                await this.logAudit({
+                    type: "iroh_security_handshake_timeout",
+                    clientNodeId: remoteId,
+                    success: false,
+                    error: "connection closed or timed out before opening a handshake stream",
+                    details: { connectionId, timeoutMs: DEFAULT_IROH_REMOTE_HANDSHAKE_TIMEOUT_MS },
+                });
+            }
+        }
+        finally {
+            clearTimeout(unauthenticatedTimer);
+            unauthenticatedAdmission.lease.release();
+            nodeConnectionAdmission.lease.release();
+            await this.closeActiveStreamsForConnection(connectionId, "connection_closed");
+            await Promise.allSettled(streamTasks);
+            removeClientConnection();
+            if (!closeRequested) {
+                closeConnection(connection, "done");
+            }
+            await waitForConnectionClose(connection);
+            if (authenticated) {
+                this.log("info", `client connection closed: ${remoteId} (${connectionId})`);
+                await this.logAudit({
+                    type: "client_disconnected",
+                    clientNodeId: remoteId,
+                    success: true,
+                    details: { connectionId },
+                });
+            }
+        }
+    }
+    async handleConnectionStream(stream, connection, remoteId, connectionId, streamId, markAuthenticated) {
+        const engine = this.requireEngine();
+        const handshakeAdmission = this.resourceGuard.tryAcquireHandshake(remoteId);
+        if (!handshakeAdmission.ok) {
+            closeIrohRemoteStream(stream, "handshake_limit_exceeded");
+            await this.logAudit({
+                type: "iroh_security_handshake_limit",
+                clientNodeId: remoteId,
+                success: false,
+                error: "stream refused at concurrent handshake limit",
+                details: { connectionId, limit: handshakeAdmission.limit, scope: handshakeAdmission.scope },
+            });
+            return;
+        }
+        let handshake;
+        try {
+            handshake = await engine.readHandshake(stream, remoteId, {
+                child: "volt",
+                maxLineBytes: DEFAULT_IROH_REMOTE_HANDSHAKE_MAX_LINE_BYTES,
+                timeoutMs: DEFAULT_IROH_REMOTE_HANDSHAKE_TIMEOUT_MS,
+                writeSuccessResponse: false,
+            });
+        }
+        finally {
+            handshakeAdmission.lease.release();
+        }
+        if (!handshake.ok) {
+            if (handshake.response.outcome === "workspace_authorization_removed" &&
+                typeof handshake.response.workspace === "string") {
+                await this.closeWorkspaceAuthorizationRemovedStreams(remoteId, handshake.response.workspace);
+            }
+            await Promise.resolve(stream.send.finish?.()).catch(() => { });
+            await Promise.resolve(stream.recv.stop?.(0n)).catch(() => { });
+            return;
+        }
+        if (!(await markAuthenticated())) {
+            closeIrohRemoteStream(stream, "handshake_timeout");
+            return;
+        }
+        const streamCapability = getIrohRemoteStreamCapability({
+            mode: handshake.hello.mode,
+            ...(handshake.hello.mode === "workspaceManagement"
+                ? { purpose: handshake.hello.workspaceManagement.purpose }
+                : {}),
+        });
+        if (streamCapability !== undefined &&
+            !hasIrohRemoteRpcCapability(parseIrohRemoteRpcGrant(handshake.authorization.client.rpcGrant, "client rpcGrant"), streamCapability)) {
+            await writeIrohRemoteHandshakeResponse(stream.send, createIrohRemoteHandshakeFailure(`rpc_capability_denied: ${streamCapability}`, {
+                hostNodeId: this.hostNodeId,
+                workspace: handshake.authorization.workspace.name,
+            }));
+            closeIrohRemoteStream(stream, "rpc_capability_denied");
+            return;
+        }
+        this.notifyPairingConsumed(handshake, remoteId);
+        if (handshake.authorization.paired) {
+            this.log("info", `paired client stream: ${handshake.authorization.client.label} (${remoteId}, ${streamId})`);
+        }
+        if (handshake.hello.mode === "workspaceDiscovery") {
+            await this.runWorkspaceDiscovery(stream, handshake, connection, connectionId, streamId);
+            return;
+        }
+        if (handshake.hello.mode === "workspaceManagement") {
+            if (handshake.hello.workspaceManagement.purpose === "manage_worktrees") {
+                await this.runWorktreeManagement(stream, handshake, connection, connectionId, streamId);
+                return;
+            }
+            await this.runWorkspaceManagement(stream, handshake, connection, connectionId, streamId);
+            return;
+        }
+        await this.runIntegratedConversation(stream, handshake, connection, connectionId, streamId);
+    }
+    // ==========================================================================
+    // Workspace streams
+    // ==========================================================================
+    registerActiveStream(authorization, sessionId, stream, connection, connectionId, streamId, details = {}) {
+        const entry = {
+            clientNodeId: authorization.client.nodeId,
+            connectionId,
+            sessionId,
+            streamId,
+            workspaceName: authorization.workspace.name,
+            close: (reason) => this.closeStreamWithTerminal(stream, reason, {
+                authorization,
+                sessionId: Object.hasOwn(details, "terminalSessionId") ? details.terminalSessionId : entry.sessionId,
+            }),
+            closeConnection: (reason) => closeConnection(connection, reason),
+            write: (value) => writeIrohRemoteJsonLine(stream.send, value, authorization, details.sanitizerOverrides ?? {}),
+        };
+        const remove = this.activeStreams.register(entry);
+        return { entry, remove };
+    }
+    // ==========================================================================
+    // iOS theme token push (§9.5) — flag off by default, capability gated
+    // ==========================================================================
+    isThemeTokenPushEnabled() {
+        return this.services.state.state.settings.themeTokenPush === true || process.env.VOLT_HOST_THEME_TOKENS === "1";
+    }
+    /** Send the current sanitized theme tokens to one capable stream. */
+    pushThemeTokensToStream(entry) {
+        if (!this.isThemeTokenPushEnabled() || !entry.capabilities?.has(HOST_THEME_TOKENS_FEATURE)) {
+            return;
+        }
+        const frame = createHostThemeTokensFrame(getCurrentThemeName() ?? "dark", getResolvedThemeColors());
+        void Promise.resolve(entry.write?.(frame)).catch(() => { });
+    }
+    /** Theme changed: fan the new tokens out to every capable phone stream. */
+    onThemeChanged() {
+        if (!this.isThemeTokenPushEnabled()) {
+            return;
+        }
+        for (const entry of this.activeStreams.allEntries()) {
+            this.pushThemeTokensToStream(entry);
+        }
+    }
+    /**
+     * Keep-awake status changed (control toggle, phone toggle, or degradation):
+     * fan the new state to every phone stream. Clients that ignore the frame are
+     * fully supported, so no capability gating.
+     */
+    onKeepAwakeChanged() {
+        const frame = {
+            type: "keep_awake_changed",
+            data: { keepAwake: toRpcKeepAwakeStatus(this.services.keepAwake.status) },
+        };
+        for (const entry of this.activeStreams.allEntries()) {
+            void Promise.resolve(entry.write?.(frame)).catch(() => { });
+        }
+    }
+    async closeStreamWithTerminal(stream, reason, terminal) {
+        const terminalReason = getRemoteTerminalReason(reason);
+        if (terminalReason) {
+            await writeIrohRemoteJsonLine(stream.send, {
+                type: "remote_terminal",
+                reason: terminalReason,
+                workspace: terminal.authorization.workspace.name,
+                ...(terminal.sessionId === undefined ? {} : { sessionId: terminal.sessionId }),
+                hostNodeId: this.hostNodeId,
+            }, terminal.authorization).catch(() => { });
+        }
+        closeIrohRemoteStream(stream, reason);
+    }
+    async runWorkspaceDiscovery(stream, handshake, connection, connectionId, streamId) {
+        await writeIrohRemoteHandshakeResponse(stream.send, handshake.response);
+        const activeStream = this.registerActiveStream(handshake.authorization, WORKSPACE_DISCOVERY_STREAM_SESSION_ID, stream, connection, connectionId, streamId, { terminalSessionId: undefined });
+        try {
+            await runWorkspaceDiscoveryStream({
+                stream,
+                initialInput: handshake.initialInput,
+                authorization: handshake.authorization,
+                isRpcGrantCurrent: () => this.isAuthorizationGrantCurrent(handshake.authorization),
+                closeStream: (reason) => closeIrohRemoteStream(stream, reason),
+            }, { commandContext: this.getCommandContext() });
+        }
+        finally {
+            activeStream.remove();
+        }
+    }
+    async runWorkspaceManagement(stream, handshake, connection, connectionId, streamId) {
+        await writeIrohRemoteHandshakeResponse(stream.send, handshake.response);
+        const activeStream = this.registerActiveStream(handshake.authorization, WORKSPACE_MANAGEMENT_STREAM_SESSION_ID, stream, connection, connectionId, streamId, { terminalSessionId: undefined });
+        try {
+            await runWorkspaceManagementStream({
+                stream,
+                initialInput: handshake.initialInput,
+                authorization: handshake.authorization,
+                isRpcGrantCurrent: () => this.isAuthorizationGrantCurrent(handshake.authorization),
+                closeStream: (reason) => {
+                    activeStream.remove();
+                    closeIrohRemoteStream(stream, reason);
+                },
+            }, {
+                auditLogger: this.services.auditLogger,
+                commandContext: this.getCommandContext(),
+                unregisterWorkspace: async (workspaceName) => {
+                    let removedWorkspace;
+                    try {
+                        removedWorkspace = await this.stateManager.unregisterWorkspace(workspaceName);
+                    }
+                    catch (error) {
+                        if (!isIrohRemoteWorkspaceHasWorktreesError(error)) {
+                            throw error;
+                        }
+                        return {
+                            ok: false,
+                            error: IROH_REMOTE_WORKSPACE_HAS_WORKTREES_ERROR,
+                            details: {
+                                worktreeCount: error.worktreeIds.length,
+                                worktreeIds: error.worktreeIds,
+                            },
+                        };
+                    }
+                    if (!removedWorkspace) {
+                        return { ok: false, error: "workspace_unregistered" };
+                    }
+                    this.engine?.clearPairingSecretForWorkspace(workspaceName);
+                    const { closedStreamCount, stoppedRuntimeCount } = await this.cleanupUnregisteredWorkspace(workspaceName, { streamEntry: activeStream.entry, workspacePath: removedWorkspace.path });
+                    return { ok: true, closedStreamCount, stoppedRuntimeCount };
+                },
+            });
+        }
+        finally {
+            activeStream.remove();
+        }
+    }
+    /** Serve a manage_worktrees workspaceManagement stream (worktrees.v1). */
+    async runWorktreeManagement(stream, handshake, connection, connectionId, streamId) {
+        await writeIrohRemoteHandshakeResponse(stream.send, handshake.response);
+        const sanitizerOverrides = {
+            additionalRedactedPaths: [getWorktreesRoot(this.services.agentDir)],
+        };
+        const activeStream = this.registerActiveStream(handshake.authorization, WORKSPACE_MANAGEMENT_STREAM_SESSION_ID, stream, connection, connectionId, streamId, { terminalSessionId: undefined, sanitizerOverrides });
+        try {
+            await runWorktreeManagementStream({
+                stream,
+                initialInput: handshake.initialInput,
+                authorization: handshake.authorization,
+                isRpcGrantCurrent: () => this.isAuthorizationGrantCurrent(handshake.authorization),
+                closeStream: (reason) => closeIrohRemoteStream(stream, reason),
+            }, {
+                auditLogger: this.services.auditLogger,
+                additionalRedactedPaths: sanitizerOverrides.additionalRedactedPaths,
+                worktrees: this.createWorktreeRpcBackend(handshake.authorization.workspace),
+            });
+        }
+        finally {
+            activeStream.remove();
+        }
+    }
+    /** Backend for the worktree RPC helpers, bound to the stream's authorized workspace. */
+    createWorktreeRpcBackend(workspace) {
+        return {
+            createWorktree: async (_workspaceName, options) => {
+                const created = await this.worktrees.create(workspace, options);
+                if (!created.ok) {
+                    return {
+                        ok: false,
+                        error: created.error,
+                        ...(created.detail === undefined ? {} : { detail: created.detail }),
+                    };
+                }
+                return { ok: true, worktree: created.worktree };
+            },
+            listWorktrees: async () => ({ ok: true, worktrees: await this.worktrees.list(workspace) }),
+            removeWorktree: async (_workspaceName, worktreeId, force) => this.removeWorkspaceWorktree(workspace, worktreeId, force),
+        };
+    }
+    /**
+     * Runtime-aware worktree removal: refuses busy worktrees without force; with
+     * force, closes bound phone streams and stops bound runtimes first.
+     */
+    async removeWorkspaceWorktree(workspace, worktreeId, force) {
+        const record = await this.worktrees.findWorktree(workspace.name, worktreeId);
+        if (!record) {
+            return { ok: false, error: "worktree_not_found" };
+        }
+        let stoppedRuntimeCount = 0;
+        let closedStreamCount = 0;
+        const boundEntries = record.sessionIds
+            .map((sessionId) => this.runtimes.findOwner(workspace.name, sessionId))
+            .filter((entry) => entry !== undefined);
+        if (boundEntries.length > 0) {
+            if (!force) {
+                return { ok: false, error: "worktree_busy" };
+            }
+            for (const entry of boundEntries) {
+                closedStreamCount += await this.closeActiveStreamsForConversationKey(workspace.name, entry.sessionId, "worktree_removed");
+                await this.runtimes.stopEntry(entry, "worktree_removed");
+                stoppedRuntimeCount++;
+            }
+        }
+        const removed = await this.worktrees.remove(workspace, worktreeId, { force });
+        if (!removed.ok) {
+            return removed;
+        }
+        return { ok: true, stoppedRuntimeCount, closedStreamCount };
+    }
+    /**
+     * Worktree resolution for conversation opens: explicit worktreeId on "new"
+     * (must exist AND be on disk), persisted binding on resume (missing checkout
+     * fails with session_unavailable). Availability is an open-time failure, not
+     * an authorization failure.
+     */
+    async resolveConversationWorktree(workspaceName, hello, targetSessionId) {
+        if (hello.mode !== "conversation") {
+            return undefined;
+        }
+        if (hello.conversation.target === "new") {
+            const worktreeId = hello.conversation.worktreeId;
+            if (worktreeId === undefined) {
+                return undefined;
+            }
+            const worktree = await this.worktrees.findWorktree(workspaceName, worktreeId);
+            if (!worktree || !existsSync(worktree.path)) {
+                throw createConversationOpenError("invalid_conversation_target", "unknown or unavailable worktree", {
+                    workspace: workspaceName,
+                });
+            }
+            return worktree;
+        }
+        if (targetSessionId === undefined) {
+            return undefined;
+        }
+        const worktree = await this.worktrees.resolveSessionWorktree(workspaceName, targetSessionId);
+        if (worktree === undefined) {
+            return undefined;
+        }
+        if (!existsSync(worktree.path)) {
+            throw createConversationOpenError("session_unavailable", "worktree checkout is unavailable", {
+                workspace: workspaceName,
+                sessionId: targetSessionId,
+            });
+        }
+        return worktree;
+    }
+    async resolveConversationWorkingDirectory(options) {
+        if (options.worktree === undefined) {
+            const parentDirectory = await this.worktrees.validateWorkingDirectory(options.workspace, options.workingDirectory);
+            if (!parentDirectory.ok) {
+                const message = parentDirectory.detail ?? parentDirectory.error;
+                throw createConversationOpenError("invalid_conversation_target", message, {
+                    workspace: options.workspace.name,
+                });
+            }
+            return parentDirectory.directory;
+        }
+        const worktreeDirectory = await this.worktrees.resolveWorktreeWorkingDirectory(options.workspace, options.worktree, options.workingDirectory);
+        if (!worktreeDirectory.ok) {
+            throw createConversationOpenError("invalid_conversation_target", worktreeDirectory.detail ?? worktreeDirectory.error, {
+                workspace: options.workspace.name,
+                worktreeId: options.worktree.id,
+            });
+        }
+        return worktreeDirectory.directory;
+    }
+    // ==========================================================================
+    // Integrated conversation serving
+    // ==========================================================================
+    createPushNotificationDispatcher(authorization) {
+        return new IrohRemotePushNotificationDispatcher({
+            auditLogger: this.services.auditLogger,
+            clientNodeId: authorization.client.nodeId,
+            deduper: this.pushNotificationDeduper,
+            relayClient: this.pushRelayClient,
+            stateManager: this.stateManager,
+            workspace: authorization.workspace.name,
+        });
+    }
+    async revokeClientPushTargets(client) {
+        if ((client?.pushTargets?.length ?? 0) === 0)
+            return;
+        try {
+            const summary = await revokeIrohRemoteClientPushTargets(client, this.pushRelayClient);
+            const complete = summary.failed === 0 && summary.skipped === 0;
+            if (!complete) {
+                this.log("warn", "remote push-target cleanup incomplete after client revoke", { ...summary });
+            }
+            await this.logAudit({
+                type: "push_targets_revoked",
+                clientNodeId: client?.nodeId,
+                success: complete,
+                error: complete ? undefined : "remote push-target cleanup incomplete; relay TTL remains the lifetime bound",
+                details: { ...summary, remainingLifetimeBound: "relay_target_ttl" },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log("warn", "remote push-target cleanup failed after client revoke", { error: message });
+            await this.logAudit({
+                type: "push_targets_revoked",
+                clientNodeId: client?.nodeId,
+                success: false,
+                error: "remote push-target cleanup failed; relay TTL remains the lifetime bound",
+                details: { remainingLifetimeBound: "relay_target_ttl" },
+            });
+        }
+    }
+    async sendHandshakeError(stream, error) {
+        const record = (error ?? {});
+        // Plain {message, ...} records (abortPendingRelay, lease re-check) must not
+        // stringify to "[object Object]".
+        const message = error instanceof Error ? error.message : typeof record.message === "string" ? record.message : String(error);
+        const outcome = typeof record.outcome === "string" ? record.outcome : undefined;
+        const workspace = typeof record.workspace === "string" ? record.workspace : undefined;
+        const sessionId = typeof record.sessionId === "string" ? record.sessionId : undefined;
+        const retryAfterMs = typeof record.retryAfterMs === "number" ? record.retryAfterMs : undefined;
+        await writeIrohRemoteHandshakeResponse(stream.send, createIrohRemoteHandshakeFailure(message, {
+            hostNodeId: this.hostNodeId,
+            ...(outcome === undefined ? {} : { outcome: outcome }),
+            ...(workspace === undefined ? {} : { workspace }),
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+        }));
+        await Promise.resolve(stream.send.finish?.()).catch(() => { });
+        await Promise.resolve(stream.recv.stop?.(0n)).catch(() => { });
+    }
+    async rejectDuplicateActiveConnection(stream, authorization, sessionId, source = "active_stream_registry") {
+        const error = "duplicate conversation connection";
+        await this.logAudit({
+            type: "duplicate_connection_rejected",
+            clientNodeId: authorization.client.nodeId,
+            workspace: authorization.workspace.name,
+            success: false,
+            error,
+            details: {
+                retryAfterMs: DUPLICATE_CONVERSATION_RETRY_AFTER_MS,
+                sessionId,
+                source,
+            },
+        });
+        await writeIrohRemoteHandshakeResponse(stream.send, createIrohRemoteHandshakeFailure(error, {
+            hostNodeId: this.hostNodeId,
+            outcome: "duplicate_conversation_connection",
+            workspace: authorization.workspace.name,
+            sessionId,
+            retryAfterMs: DUPLICATE_CONVERSATION_RETRY_AFTER_MS,
+        }));
+        await Promise.resolve(stream.send.finish?.()).catch(() => { });
+        await Promise.resolve(stream.recv.stop?.(0n)).catch(() => { });
+    }
+    async closeReplacedActiveStreams(authorization, replacementStreamId, replacedEntries) {
+        if (replacedEntries.length === 0) {
+            return;
+        }
+        const replacedStreamIds = replacedEntries.map((entry) => entry.streamId);
+        for (const entry of replacedEntries) {
+            await Promise.resolve(entry.close(ACTIVE_REPLACE_CLOSE_REASON)).catch(() => { });
+        }
+        await this.closeIdleConnectionsForEntries(replacedEntries, ACTIVE_REPLACE_CLOSE_REASON);
+        this.log("info", `client stream replaced: ${authorization.client.nodeId}/${authorization.workspace.name} (${replacedStreamIds.join(", ")} -> ${replacementStreamId})`);
+        await this.logAudit({
+            type: "duplicate_connection_replaced",
+            clientNodeId: authorization.client.nodeId,
+            workspace: authorization.workspace.name,
+            success: true,
+            details: {
+                closeReason: ACTIVE_REPLACE_CLOSE_REASON,
+                closedCount: replacedEntries.length,
+                replacedStreamIds,
+                replacementStreamId,
+                source: "active_stream_registry",
+            },
+        });
+    }
+    /**
+     * Relay a phone conversation stream to the owning TUI (§5.6): the daemon
+     * has already authenticated the phone; the TUI serves the framed RPC from
+     * its in-process runtime over a dedicated relay unix connection.
+     */
+    async relayConversationToTui(stream, handshake, connectionId, streamId, targetSessionId, tuiConnectionId) {
+        const authorization = handshake.authorization;
+        const workspaceName = authorization.workspace.name;
+        // Duplicate handling per clientNodeId + key: duplicates already on this
+        // Iroh connection are real duplicates; entries on older connections are
+        // stale for this conversation and may be replaced independently of any
+        // sibling subagent streams that opened first on the new connection.
+        const liveRelays = this.relays.activeForConversation(authorization.client.nodeId, workspaceName, targetSessionId);
+        const pendingRelays = this.relays.pendingForConversation(authorization.client.nodeId, workspaceName, targetSessionId);
+        if (liveRelays.some((relay) => relay.connectionId === connectionId) ||
+            pendingRelays.some((pending) => pending.connectionId === connectionId)) {
+            await this.rejectDuplicateActiveConnection(stream, authorization, targetSessionId, "relay_registry");
+            return;
+        }
+        for (const relay of liveRelays) {
+            relay.close("error");
+        }
+        // Unredeemed offers for the same conversation on older connections are
+        // superseded by this one: fail their deferred handshakes and settle them
+        // (relay_closed to the TUI, lease bookkeeping) instead of leaking tasks.
+        for (const pending of pendingRelays) {
+            this.abortPendingRelay(pending.relayId, "error", "relay offer superseded; retry", RELAY_OFFER_RETRY_AFTER_MS);
+        }
+        // Resolve the concrete session target for the preamble (§3.7).
+        const target = handshake.hello.mode === "conversation" && handshake.hello.conversation.target === "session"
+            ? { kind: "session", sessionId: handshake.hello.conversation.sessionId }
+            : { kind: "last", resumeSessionId: targetSessionId };
+        // A worktree-bound session must resolve against the worktree cwd (the
+        // parent-keyed session dir plus a non-matching cwd makes SessionManager.list
+        // filter by header cwd, restricting resolution to that worktree's sessions).
+        const boundWorktree = await this.stateManager.findWorktreeForSession(workspaceName, targetSessionId);
+        const relayOwnerCapabilities = this.services.controlServer
+            .connections()
+            .find((controlConnection) => controlConnection.connectionId === tuiConnectionId)?.capabilities;
+        if (!relayOwnerCapabilities?.has(CONTROL_RPC_GRANTS_CAPABILITY)) {
+            await this.sendHandshakeError(stream, {
+                message: "conversation owner is not grant-aware; retry",
+                retryAfterMs: RELAY_OFFER_RETRY_AFTER_MS,
+            });
+            return;
+        }
+        // Worktree-bound conversations are only relayed to TUIs that advertised the
+        // worktrees control capability (an old TUI would sanitize with the parent
+        // root and leak host paths), and never when the checkout has vanished.
+        const relayGate = evaluateWorktreeRelayGate(boundWorktree, relayOwnerCapabilities, CONTROL_WORKTREES_CAPABILITY);
+        if (!relayGate.ok) {
+            if (relayGate.reason === "checkout_missing") {
+                await this.sendHandshakeError(stream, {
+                    message: "worktree checkout is unavailable",
+                    outcome: "session_unavailable",
+                    workspace: workspaceName,
+                    sessionId: targetSessionId,
+                });
+                return;
+            }
+            await this.sendHandshakeError(stream, {
+                message: "conversation owner cannot serve worktree sessions; retry",
+                retryAfterMs: RELAY_OFFER_RETRY_AFTER_MS,
+            });
+            return;
+        }
+        let resolvedTarget;
+        try {
+            resolvedTarget = await resolveIrohRemoteSessionTarget(target, { name: workspaceName, path: authorization.workspace.path }, createSessionManagerTargetStore(boundWorktree?.path ?? authorization.workspace.path, getDefaultSessionDir(authorization.workspace.path, this.services.agentDir), { listAll: true, preserveSessionCwd: true }));
+        }
+        catch (error) {
+            await this.sendHandshakeError(stream, error);
+            return;
+        }
+        const resolvedSessionManager = resolvedTarget.sessionManager;
+        const resolvedSessionCwd = resolvedSessionManager.getCwd?.() ?? boundWorktree?.path ?? authorization.workspace.path;
+        const relayWorkingDirectoryRelativeToRoot = getRelativeWorkingDirectoryForRoot(boundWorktree?.path ?? authorization.workspace.path, resolvedSessionCwd);
+        if (relayWorkingDirectoryRelativeToRoot === null) {
+            await this.sendHandshakeError(stream, {
+                message: "stored session working directory is outside the authorized workspace",
+                outcome: "session_unavailable",
+                workspace: workspaceName,
+                sessionId: targetSessionId,
+            });
+            return;
+        }
+        const relayWorkingDirectory = boundWorktree === undefined
+            ? relayWorkingDirectoryRelativeToRoot
+            : getRegisteredWorkingDirectoryForWorktree(boundWorktree, relayWorkingDirectoryRelativeToRoot);
+        // Session-target resolution awaited; the lease can have moved (release,
+        // rekey, connection loss) in the meantime. Re-check before minting so the
+        // offer cannot go to a stale or dead owner.
+        const lease = this.leaseBroker.lookup(workspaceName, targetSessionId);
+        if (lease?.state !== "tui-owned" || lease.tuiConnectionId !== tuiConnectionId) {
+            await this.sendHandshakeError(stream, {
+                message: "conversation lease owner changed; retry",
+                retryAfterMs: RELAY_OFFER_RETRY_AFTER_MS,
+            });
+            return;
+        }
+        // The target-resolution awaits above can race an access update or revoke.
+        // Recheck immediately before the synchronous mint so stale authorization
+        // cannot create a new pending offer after control-plane invalidation acks.
+        if (!(await this.isAuthorizationGrantCurrent(authorization))) {
+            await this.sendHandshakeError(stream, { message: "client access changed; reconnect" });
+            return;
+        }
+        // A sibling stream can resolve/redeem while this stream awaits target
+        // resolution. Re-check immediately before minting the offer.
+        const currentLiveRelays = this.relays.activeForConversation(authorization.client.nodeId, workspaceName, targetSessionId);
+        const currentPendingRelays = this.relays.pendingForConversation(authorization.client.nodeId, workspaceName, targetSessionId);
+        if (currentLiveRelays.some((relay) => relay.connectionId === connectionId) ||
+            currentPendingRelays.some((pending) => pending.connectionId === connectionId)) {
+            await this.rejectDuplicateActiveConnection(stream, authorization, targetSessionId, "relay_registry");
+            return;
+        }
+        for (const relay of currentLiveRelays) {
+            relay.close("error");
+        }
+        for (const pending of currentPendingRelays) {
+            this.abortPendingRelay(pending.relayId, "error", "relay offer superseded; retry", RELAY_OFFER_RETRY_AFTER_MS);
+        }
+        const settled = new Promise((resolveSettled) => {
+            const relay = this.relays.mint({
+                workspaceName,
+                sessionId: targetSessionId,
+                clientNodeId: authorization.client.nodeId,
+                connectionId,
+                ownerControlConnectionId: tuiConnectionId,
+                streamId,
+                stream,
+                preamble: {
+                    handshake: {
+                        hello: handshake.hello,
+                        response: handshake.response,
+                        initialInput: Array.from(handshake.initialInput),
+                    },
+                    authorization: {
+                        clientNodeId: authorization.client.nodeId,
+                        allowedTools: authorization.client.allowedTools,
+                        rpcGrant: authorization.client.rpcGrant,
+                        workspaceName,
+                        workspacePath: authorization.workspace.path,
+                        ...(boundWorktree === undefined
+                            ? {}
+                            : {
+                                worktreeId: boundWorktree.id,
+                                worktreePath: boundWorktree.path,
+                                ...(boundWorktree.sourceRootRelativePath === undefined
+                                    ? {}
+                                    : { worktreeSourceRootRelativePath: boundWorktree.sourceRootRelativePath }),
+                            }),
+                    },
+                    // The phone verifies the saved host's node id in the handshake
+                    // response the TUI writes; without this the relay path fails the
+                    // client's identity check.
+                    ...(this.hostNodeId === undefined ? {} : { hostNodeId: this.hostNodeId }),
+                    relayMode: this.relayMode,
+                    ...(this.relayMode === "production" ? { relayUrls: this.relayUrls } : {}),
+                    connectionId,
+                    streamId,
+                    resolvedTarget: {
+                        sessionId: resolvedTarget.sessionId,
+                        ...(resolvedTarget.sessionFilePath === undefined
+                            ? {}
+                            : { sessionFilePath: resolvedTarget.sessionFilePath }),
+                        selection: resolvedTarget.selection,
+                        ...(resolvedTarget.requestedSessionId === undefined
+                            ? {}
+                            : { requestedSessionId: resolvedTarget.requestedSessionId }),
+                        workspaceName: resolvedTarget.workspaceName,
+                        workspacePath: resolvedTarget.workspacePath,
+                        ...(boundWorktree === undefined ? {} : { worktreeId: boundWorktree.id }),
+                        ...(relayWorkingDirectory === undefined ? {} : { workingDirectory: relayWorkingDirectory }),
+                    },
+                },
+                settle: (outcome) => {
+                    this.leaseBroker.unregisterRelay(workspaceName, targetSessionId, relay.relayId);
+                    this.services.controlServer.sendTo(tuiConnectionId, {
+                        type: "relay_closed",
+                        relayId: relay.relayId,
+                        reason: outcome.reason,
+                    });
+                    void this.logAudit({
+                        type: "relay_closed",
+                        clientNodeId: authorization.client.nodeId,
+                        workspace: workspaceName,
+                        success: outcome.error === undefined,
+                        error: outcome.error,
+                        details: {
+                            relayId: relay.relayId,
+                            reason: outcome.reason,
+                            bytesUp: outcome.bytesUp,
+                            bytesDown: outcome.bytesDown,
+                            durationMs: outcome.durationMs,
+                        },
+                    });
+                    resolveSettled();
+                },
+            });
+            // The offer is single-use with a 10s expiry; the phone's handshake
+            // response is deferred until the TUI redeems the token.
+            const expiryTimer = setTimeout(() => {
+                this.abortPendingRelay(relay.relayId, "error", "relay offer expired; retry", RELAY_OFFER_RETRY_AFTER_MS);
+            }, RELAY_TOKEN_TTL_MS);
+            expiryTimer.unref?.();
+            this.leaseBroker.registerRelay(workspaceName, targetSessionId, relay.relayId);
+            void this.logAudit({
+                type: "relay_opened",
+                clientNodeId: authorization.client.nodeId,
+                workspace: workspaceName,
+                success: true,
+                details: {
+                    relayId: relay.relayId,
+                    workspaceName,
+                    sessionId: targetSessionId,
+                    connectionId,
+                    streamId,
+                },
+            });
+            const delivered = this.services.controlServer.sendTo(tuiConnectionId, {
+                type: "relay_offer",
+                relayId: relay.relayId,
+                relayToken: relay.relayToken,
+                workspaceName,
+                sessionId: targetSessionId,
+                clientNodeId: authorization.client.nodeId,
+                connectionId,
+                streamId,
+            });
+            if (!delivered) {
+                // The TUI connection vanished between the lease check and the offer;
+                // fail the phone's deferred handshake now instead of after the TTL.
+                this.abortPendingRelay(relay.relayId, "error", "relay offer undeliverable; retry", RELAY_OFFER_RETRY_AFTER_MS);
+            }
+        });
+        await settled;
+    }
+    async runIntegratedConversation(stream, handshake, connection, connectionId, streamId) {
+        const authorization = handshake.authorization;
+        const targetSessionId = getResolvedTargetSessionId(handshake.hello, authorization);
+        const daemonAttach = this.leaseBroker.beginDaemonAttach(authorization.workspace.name, targetSessionId);
+        if (daemonAttach.kind === "relay") {
+            if (!targetSessionId) {
+                await this.sendHandshakeError(stream, {
+                    message: "conversation lease owner changed; retry",
+                    retryAfterMs: RELAY_OFFER_RETRY_AFTER_MS,
+                });
+                return;
+            }
+            await this.relayConversationToTui(stream, handshake, connectionId, streamId, targetSessionId, daemonAttach.tuiConnectionId);
+            return;
+        }
+        if (daemonAttach.kind === "retry") {
+            await this.sendHandshakeError(stream, {
+                message: "conversation lease is draining; retry",
+                retryAfterMs: daemonAttach.retryAfterMs,
+            });
+            return;
+        }
+        const daemonAttachClaim = daemonAttach.claim;
+        let entry;
+        let sessionSelection;
+        let createdRuntime = false;
+        try {
+            ({
+                entry,
+                sessionSelection,
+                created: createdRuntime,
+            } = await this.runtimes.getOrCreateEntry({ hello: handshake.hello, response: handshake.response }, authorization));
+        }
+        catch (error) {
+            this.leaseBroker.abortDaemonAttach(daemonAttachClaim);
+            await this.logAudit({
+                type: "runtime_failure",
+                clientNodeId: authorization.client.nodeId,
+                workspace: authorization.workspace.name,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                details: { runtime: "integrated-volt" },
+            });
+            await this.sendHandshakeError(stream, error);
+            return;
+        }
+        if (this.activeStreams.hasConversationOnConnection(authorization.client.nodeId, authorization.workspace.name, entry.sessionId, connectionId)) {
+            this.leaseBroker.abortDaemonAttach(daemonAttachClaim);
+            if (createdRuntime) {
+                await this.runtimes.cleanupUncommittedEntry(entry, sessionSelection);
+            }
+            else {
+                // Reattach: getOrCreateEntry cancelled the detached-runtime retention
+                // timer up front. Re-arm it (no-op unless the entry is still detached
+                // with no timer) so aborting here never leaves the runtime unswept.
+                await this.runtimes.detachWithoutSubscriber(entry, "reattach_superseded");
+            }
+            await this.rejectDuplicateActiveConnection(stream, authorization, entry.sessionId);
+            return;
+        }
+        let activeStream;
+        let subscriber;
+        let subscriberError;
+        let handshakeCommitted = false;
+        try {
+            const brokerCommit = this.leaseBroker.commitDaemonRuntime(daemonAttachClaim, authorization.workspace.name, entry.sessionId);
+            if (!brokerCommit.ok) {
+                if (createdRuntime) {
+                    await this.runtimes.cleanupUncommittedEntry(entry, sessionSelection);
+                }
+                if (brokerCommit.reason === "tui_owned" &&
+                    brokerCommit.tuiConnectionId &&
+                    targetSessionId === entry.sessionId) {
+                    await this.relayConversationToTui(stream, handshake, connectionId, streamId, entry.sessionId, brokerCommit.tuiConnectionId);
+                    return;
+                }
+                await this.sendHandshakeError(stream, {
+                    message: "conversation lease owner changed; retry",
+                    retryAfterMs: RELAY_OFFER_RETRY_AFTER_MS,
+                });
+                return;
+            }
+            try {
+                await this.runtimes.commitEntry(entry, sessionSelection, authorization);
+            }
+            catch (error) {
+                this.leaseBroker.rollbackDaemonRuntimeCommit(authorization.workspace.name, entry.sessionId, brokerCommit.previousState);
+                throw error;
+            }
+            if (this.activeStreams.hasConversationOnConnection(authorization.client.nodeId, authorization.workspace.name, entry.sessionId, connectionId)) {
+                this.leaseBroker.rollbackDaemonRuntimeCommit(authorization.workspace.name, entry.sessionId, brokerCommit.previousState);
+                if (createdRuntime) {
+                    await this.runtimes.cleanupUncommittedEntry(entry, sessionSelection);
+                }
+                else {
+                    await this.runtimes.detachWithoutSubscriber(entry, "reattach_superseded");
+                }
+                await this.rejectDuplicateActiveConnection(stream, authorization, entry.sessionId);
+                return;
+            }
+            handshakeCommitted = true;
+            // Worktree-bound conversations sanitize with the worktree checkout as the
+            // root; the parent checkout and the worktrees root must ALSO redact (bash
+            // output like `git worktree list` prints both).
+            const worktreeSanitizerOverrides = entry.worktreePath === undefined
+                ? undefined
+                : {
+                    remoteWorkspacePath: entry.worktreeSourceRootRelativePath === undefined
+                        ? "/workspace"
+                        : `/workspace/${entry.worktreeSourceRootRelativePath}`,
+                    workspacePath: entry.worktreePath,
+                    additionalRedactedPaths: [authorization.workspace.path, getWorktreesRoot(this.services.agentDir)],
+                };
+            if (!(await this.isAuthorizationGrantCurrent(authorization))) {
+                await this.runtimes.stopEntry(entry, "access_updated_during_attach");
+                throw new Error("client access changed during conversation attach; reconnect");
+            }
+            const replacedEntries = this.activeStreams.takeEntriesForConversationOnOtherConnections(authorization.client.nodeId, authorization.workspace.name, entry.sessionId, connectionId);
+            activeStream = this.registerActiveStream(authorization, entry.sessionId, stream, connection, connectionId, streamId, worktreeSanitizerOverrides === undefined ? {} : { sanitizerOverrides: worktreeSanitizerOverrides });
+            await this.closeReplacedActiveStreams(authorization, streamId, replacedEntries);
+            await writeIrohRemoteHandshakeResponse(stream.send, createIntegratedConversationHandshakeResponse({ hello: handshake.hello, response: handshake.response }, authorization, entry.sessionId, sessionSelection, this.getResponseContext(), entry.worktreeId, entry.workingDirectory));
+            subscriber = await this.runtimes.attachSubscriber(entry);
+            this.leaseBroker.onDaemonRuntimeStreamCountChanged(authorization.workspace.name, entry.sessionId, entry.subscribers.size);
+            await this.runtimes.replayWorkflowEvents(activeStream.entry, entry);
+            const pushDispatcher = this.createPushNotificationDispatcher(authorization);
+            await runIrohRemoteRpcMode(entry.runtime, {
+                rpcGrant: authorization.client.rpcGrant,
+                isRpcGrantCurrent: () => this.isAuthorizationGrantCurrent(authorization),
+                decorateOutbound: (value) => decorateRemoteHostState(value, authorization, this.getResponseContext()),
+                disposeRuntimeOnClose: false,
+                notificationDelivery: pushDispatcher,
+                onClientCapabilitiesChanged: (features) => {
+                    const streamEntry = activeStream?.entry;
+                    if (streamEntry) {
+                        streamEntry.capabilities = new Set(features);
+                        this.pushThemeTokensToStream(streamEntry);
+                    }
+                },
+                onSessionChanged: async (session) => {
+                    await this.runtimes.handleSessionChanged(entry, activeStream?.entry, session, authorization);
+                },
+                onWorkflowEvent: async (event) => {
+                    await this.runtimes.handleWorkflowEvent(entry, event, activeStream?.entry);
+                },
+                registerPushTarget: (args) => pushDispatcher.registerPushTarget(args),
+                remoteCommandHandler: (command) => handleIntegratedConversationRpcCommand(command, authorization, this.getCommandContext({
+                    workspaceName: authorization.workspace.name,
+                    workspacePath: authorization.workspace.path,
+                    entry,
+                    streamEntry: activeStream?.entry,
+                }), entry.runtime),
+                stream,
+                initialInput: handshake.initialInput,
+                workspaceName: authorization.workspace.name,
+                workspacePath: entry.worktreePath ?? authorization.workspace.path,
+                ...(worktreeSanitizerOverrides?.remoteWorkspacePath === undefined
+                    ? {}
+                    : { remoteWorkspacePath: worktreeSanitizerOverrides.remoteWorkspacePath }),
+                ...(worktreeSanitizerOverrides?.additionalRedactedPaths === undefined
+                    ? {}
+                    : { additionalRedactedPaths: worktreeSanitizerOverrides.additionalRedactedPaths }),
+            });
+        }
+        catch (error) {
+            subscriberError = error;
+            if (!handshakeCommitted) {
+                if (createdRuntime) {
+                    await this.runtimes.cleanupUncommittedEntry(entry, sessionSelection);
+                }
+                await this.sendHandshakeError(stream, error);
+                return;
+            }
+        }
+        finally {
+            if (subscriber) {
+                await this.runtimes.detachSubscriber(entry, subscriber, subscriberError ? "transport_error" : "transport_closed", subscriberError);
+                this.leaseBroker.onDaemonRuntimeStreamCountChanged(authorization.workspace.name, entry.sessionId, entry.subscribers.size);
+            }
+            else if (handshakeCommitted || !createdRuntime) {
+                // handshakeCommitted: normal detach after the runtime ran. !createdRuntime:
+                // a reattach that failed before attachSubscriber, whose retention timer
+                // getOrCreateEntry cancelled up front — re-arm it so the runtime is still
+                // swept at TTL instead of leaking forever. detachWithoutSubscriber no-ops
+                // when the entry was replaced or still has other subscribers.
+                await this.runtimes.detachWithoutSubscriber(entry, subscriberError ? "transport_error" : "transport_closed");
+                // Sync the lease's stream count to reality. Without this, a handshake
+                // write that failed after commitDaemonRuntime but before attachSubscriber
+                // leaves the lease stuck at daemon-active with no live stream until the
+                // detached-runtime retention TTL expires.
+                this.leaseBroker.onDaemonRuntimeStreamCountChanged(authorization.workspace.name, entry.sessionId, entry.subscribers.size);
+            }
+            activeStream?.remove();
+        }
+    }
+    // ==========================================================================
+    // Stream/connection registries
+    // ==========================================================================
+    registerClientConnection(nodeId, connection, connectionId) {
+        const record = {
+            connectionId,
+            close: (reason) => closeConnection(connection, reason),
+        };
+        let records = this.clientConnections.get(nodeId);
+        if (!records) {
+            records = new Set();
+            this.clientConnections.set(nodeId, records);
+        }
+        records.add(record);
+        let removed = false;
+        return () => {
+            if (removed) {
+                return;
+            }
+            removed = true;
+            records.delete(record);
+            if (records.size === 0 && this.clientConnections.get(nodeId) === records) {
+                this.clientConnections.delete(nodeId);
+            }
+        };
+    }
+    closeClientConnectionsForClient(nodeId, reason) {
+        const records = Array.from(this.clientConnections.get(nodeId) ?? []);
+        if (records.length === 0) {
+            return 0;
+        }
+        this.clientConnections.delete(nodeId);
+        for (const record of records) {
+            try {
+                record.close(reason);
+            }
+            catch {
+                // Connection closure is best-effort; the transport may already be closing.
+            }
+        }
+        return records.length;
+    }
+    async closeEntryConnection(entry, reason) {
+        try {
+            await Promise.resolve(entry.closeConnection?.(reason));
+        }
+        catch {
+            // Connection closure is best-effort. Stream teardown still drives task cleanup.
+        }
+    }
+    async closeIdleConnectionsForEntries(entries, reason) {
+        const closedConnectionIds = new Set();
+        for (const entry of entries) {
+            if (closedConnectionIds.has(entry.connectionId)) {
+                continue;
+            }
+            if (this.activeStreams.entriesForConnection(entry.connectionId).length > 0) {
+                continue;
+            }
+            closedConnectionIds.add(entry.connectionId);
+            await this.closeEntryConnection(entry, reason);
+        }
+    }
+    async closeActiveStreamsForConnection(connectionId, reason) {
+        const entries = this.activeStreams.entriesForConnection(connectionId);
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+            await Promise.resolve(entry.close(reason)).catch(() => { });
+        }
+    }
+    async closeActiveStreamsForConversationKey(workspaceName, sessionId, reason) {
+        const entries = this.activeStreams.entriesForConversationKey(workspaceName, sessionId);
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+            await Promise.resolve(entry.close(reason)).catch(() => { });
+        }
+        await this.closeIdleConnectionsForEntries(entries, reason);
+        return entries.length;
+    }
+    async closeActiveStreamsForWorkspace(workspaceName, reason, excludedEntry) {
+        const entries = this.activeStreams
+            .entriesForWorkspaceName(workspaceName)
+            .filter((entry) => entry !== excludedEntry);
+        if (entries.length === 0) {
+            return 0;
+        }
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+            await Promise.resolve(entry.close(reason)).catch(() => { });
+        }
+        await this.closeIdleConnectionsForEntries(entries, reason);
+        return entries.length;
+    }
+    /**
+     * Invalidate an unredeemed relay offer: fail the phone's deferred handshake
+     * immediately and settle the relay (lease bookkeeping, relay_closed to the
+     * TUI, audit).
+     */
+    abortPendingRelay(relayId, reason, message, retryAfterMs) {
+        const pending = this.relays.invalidatePending(relayId);
+        if (!pending) {
+            return;
+        }
+        void this.sendHandshakeError(pending.stream, {
+            message,
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+        }).finally(() => pending.settle({ reason, bytesUp: 0, bytesDown: 0, durationMs: 0 }));
+    }
+    closeRelaysForWorkspace(workspaceName, excludeRelayIds) {
+        for (const relay of this.relays.activeRelays()) {
+            if (relay.workspaceName === workspaceName && !excludeRelayIds?.has(relay.relayId)) {
+                relay.close("workspace_unregistered");
+            }
+        }
+        for (const pending of this.relays.pendingRelays()) {
+            if (pending.workspaceName === workspaceName && !excludeRelayIds?.has(pending.relayId)) {
+                this.abortPendingRelay(pending.relayId, "workspace_unregistered", "workspace unregistered");
+            }
+        }
+    }
+    /**
+     * Post-unregister host cleanup shared by the control, workspace-management,
+     * and conversation RPC unregister paths: closes phone streams, stops
+     * runtimes, drops live activities, and closes TUI relays for the workspace.
+     * Exclusions keep the requesting stream/runtime/relays alive so the
+     * unregister response can still be delivered.
+     */
+    async cleanupUnregisteredWorkspace(workspaceName, exclusions = {}) {
+        const closedStreamCount = await this.closeActiveStreamsForWorkspace(workspaceName, WORKSPACE_UNREGISTERED_CLOSE_REASON, exclusions.streamEntry);
+        const stoppedRuntimeCount = await this.runtimes.stopForWorkspace(workspaceName, WORKSPACE_UNREGISTERED_CLOSE_REASON, exclusions.runtimeEntry);
+        await this.stateManager.removeLiveActivitiesForWorkspace(workspaceName);
+        this.closeRelaysForWorkspace(workspaceName, exclusions.relayIds);
+        if (exclusions.workspacePath !== undefined) {
+            await this.worktrees
+                .cleanupUnregisteredWorkspace({ name: workspaceName, path: exclusions.workspacePath })
+                .catch(() => { });
+        }
+        return { closedStreamCount, stoppedRuntimeCount };
+    }
+    async closeActiveStreamsForClientWorkspace(nodeId, workspaceName, reason) {
+        const entries = this.activeStreams
+            .entriesForClientNodeId(nodeId)
+            .filter((entry) => entry.workspaceName === workspaceName);
+        if (entries.length === 0) {
+            return 0;
+        }
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+            await Promise.resolve(entry.close(reason)).catch(() => { });
+        }
+        await this.closeIdleConnectionsForEntries(entries, reason);
+        return entries.length;
+    }
+    async closeClientForAccessUpdate(nodeId) {
+        const runtimeEntries = collectClientAuthorityInvalidationRuntimes(this.activeStreams, this.runtimes.values(), nodeId);
+        const entries = collectClientAuthorityInvalidationStreams(this.activeStreams, runtimeEntries, nodeId);
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+        }
+        // Invalidate transport and relay authority synchronously. Terminal writes
+        // below are best-effort and must never keep old commands or buffered prompts
+        // alive behind backpressure.
+        this.closeClientConnectionsForClient(nodeId, "access_updated");
+        for (const entry of entries) {
+            try {
+                entry.closeConnection?.("access_updated");
+            }
+            catch { }
+        }
+        for (const relay of this.relays.activeRelays()) {
+            if (relay.clientNodeId === nodeId)
+                relay.close("error");
+        }
+        for (const pending of this.relays.pendingRelays()) {
+            if (pending.clientNodeId === nodeId) {
+                this.abortPendingRelay(pending.relayId, "error", "client access updated; reconnect");
+            }
+        }
+        const streamClosures = Promise.allSettled(Array.from(entries, (entry) => Promise.resolve(entry.close("access_updated"))));
+        await Promise.allSettled(Array.from(runtimeEntries, (runtimeEntry) => this.runtimes.stopEntry(runtimeEntry, "access_updated")));
+        await streamClosures;
+    }
+    async closeWorkspaceAuthorizationRemovedStreams(nodeId, workspaceName) {
+        const reason = "workspace_authorization_removed";
+        const closedStreamCount = await this.closeActiveStreamsForClientWorkspace(nodeId, workspaceName, reason);
+        const stoppedRuntimeCount = await this.runtimes.stopForClientWorkspace(nodeId, workspaceName, reason);
+        const removedLiveActivityCount = await this.stateManager.removeClientLiveActivitiesForWorkspace(nodeId, workspaceName);
+        await this.logAudit({
+            type: "workspace_authorization_removed",
+            clientNodeId: nodeId,
+            workspace: workspaceName,
+            success: closedStreamCount > 0 || stoppedRuntimeCount > 0 || removedLiveActivityCount > 0,
+            details: {
+                closedStreamCount,
+                removedLiveActivityCount,
+                source: "authorization_failure",
+                stoppedRuntimeCount,
+            },
+        });
+    }
+    async closeActiveStreamsForClient(nodeId) {
+        const runtimeEntries = collectClientAuthorityInvalidationRuntimes(this.activeStreams, this.runtimes.values(), nodeId);
+        const entries = collectClientAuthorityInvalidationStreams(this.activeStreams, runtimeEntries, nodeId);
+        for (const entry of entries) {
+            this.activeStreams.unregister(entry);
+        }
+        // Match access-update ordering: synchronously make active and unredeemed TUI
+        // relays unusable before any terminal write, runtime disposal, or control ack.
+        const activeRelays = this.relays.activeRelays().filter((relay) => relay.clientNodeId === nodeId);
+        const pendingRelays = this.relays.pendingRelays().filter((relay) => relay.clientNodeId === nodeId);
+        for (const relay of activeRelays) {
+            relay.close("error");
+        }
+        for (const pending of pendingRelays) {
+            this.abortPendingRelay(pending.relayId, "error", "client revoked; re-pair required");
+        }
+        const closedConnectionCount = this.closeClientConnectionsForClient(nodeId, ACTIVE_REVOKE_CLOSE_REASON);
+        for (const entry of entries) {
+            try {
+                entry.closeConnection?.(ACTIVE_REVOKE_CLOSE_REASON);
+            }
+            catch { }
+        }
+        const streamClosures = Promise.allSettled(Array.from(entries, (entry) => Promise.resolve(entry.close(ACTIVE_REVOKE_CLOSE_REASON))));
+        await Promise.allSettled(Array.from(runtimeEntries, (runtimeEntry) => this.runtimes.stopEntry(runtimeEntry, "client_revoked")));
+        await streamClosures;
+        const stoppedRuntimeCount = runtimeEntries.size;
+        const closed = entries.size > 0 || closedConnectionCount > 0 || activeRelays.length > 0 || pendingRelays.length > 0;
+        if (entries.size === 0) {
+            await this.logAudit({
+                type: "active_connection_revoked",
+                clientNodeId: nodeId,
+                success: closed || stoppedRuntimeCount > 0,
+                error: closed || stoppedRuntimeCount > 0 ? undefined : "no active connection found",
+                details: {
+                    activeRelayCount: activeRelays.length,
+                    closeReason: ACTIVE_REVOKE_CLOSE_REASON,
+                    closedConnectionCount,
+                    pendingRelayCount: pendingRelays.length,
+                    source: "control_channel",
+                    stoppedRuntimeCount,
+                },
+            });
+            return { closed, closedCount: closedConnectionCount + activeRelays.length + pendingRelays.length };
+        }
+        for (const entry of entries) {
+            await this.logAudit({
+                type: "active_connection_revoked",
+                clientNodeId: nodeId,
+                workspace: entry.workspaceName,
+                success: true,
+                details: {
+                    activeRelayCount: activeRelays.length,
+                    closeReason: ACTIVE_REVOKE_CLOSE_REASON,
+                    closedConnectionCount,
+                    pendingRelayCount: pendingRelays.length,
+                    source: "control_channel",
+                    streamId: entry.streamId,
+                    stoppedRuntimeCount,
+                },
+            });
+        }
+        return { closed: true, closedCount: entries.size + activeRelays.length + pendingRelays.length };
+    }
+    // ==========================================================================
+    // Pairing over the control plane
+    // ==========================================================================
+    notifyPairingConsumed(handshake, remoteId) {
+        const consumed = handshake.authorization.consumedPairingTicket;
+        if (!consumed) {
+            return;
+        }
+        for (const [requestId, pending] of this.pendingPairRequests) {
+            if (pending.secretHash !== consumed.secretHash) {
+                continue;
+            }
+            clearTimeout(pending.timer);
+            this.pendingPairRequests.delete(requestId);
+            this.services.controlServer.sendTo(pending.connectionId, {
+                type: "pairing_progress",
+                requestId,
+                phase: "completed",
+                clientNodeId: remoteId,
+            });
+        }
+    }
+    async handlePairRequest(connection, request) {
+        try {
+            await withTimeout(this.ready.promise, IROH_ENDPOINT_READY_TIMEOUT_MS, "Iroh endpoint did not become ready within 15s");
+        }
+        catch (error) {
+            connection.send({
+                type: "error",
+                id: request.id,
+                code: "iroh_unavailable",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        const engine = this.requireEngine();
+        const endpoint = this.endpoint;
+        if (!endpoint || !this.endpointTicket) {
+            connection.send({ type: "error", id: request.id, code: "iroh_unavailable", message: "endpoint not ready" });
+            return;
+        }
+        const workspaceName = typeof request.workspaceName === "string"
+            ? request.workspaceName
+            : undefined;
+        const requestId = randomUUID();
+        try {
+            const access = request.access !== undefined
+                ? createIrohRemotePresetAccess(request.access)
+                : request.allowedTools !== undefined && request.rpcCapabilities !== undefined
+                    ? createIrohRemoteExplicitAccess(request.allowedTools, parseIrohRemoteRpcCapabilities(request.rpcCapabilities))
+                    : createIrohRemotePresetAccess("coding");
+            const pairing = await engine.pair({
+                allowTools: access.allowedTools,
+                rpcGrant: access.rpcGrant,
+                irohTicket: this.endpointTicket,
+                nodeId: this.hostNodeId,
+                relayMode: this.relayMode,
+                ...(this.relayMode === "production" ? { relayUrls: this.relayUrls } : {}),
+                ...(this.relayMode === "production" && this.relayAuthToken !== undefined
+                    ? { relayAuthToken: this.relayAuthToken }
+                    : {}),
+                ...(workspaceName === undefined ? {} : { workspace: workspaceName }),
+            });
+            connection.send({ type: "pair_started", id: request.id, requestId });
+            connection.send({
+                type: "pairing_progress",
+                requestId,
+                phase: "ticket",
+                ticket: pairing.ticket,
+            });
+            connection.send({ type: "pairing_progress", requestId, phase: "waiting" });
+            const ttlMs = Math.max(0, pairing.expiresAt - Date.now());
+            const timer = setTimeout(() => {
+                if (!this.pendingPairRequests.delete(requestId)) {
+                    return;
+                }
+                this.services.controlServer.sendTo(connection.connectionId, {
+                    type: "pairing_progress",
+                    requestId,
+                    phase: "failed",
+                    error: "pairing ticket expired",
+                });
+            }, ttlMs > 0 ? ttlMs : DEFAULT_IROH_REMOTE_PAIRING_TICKET_TTL_MS);
+            timer.unref?.();
+            this.pendingPairRequests.set(requestId, {
+                requestId,
+                connectionId: connection.connectionId,
+                secretHash: hashIrohRemotePairingSecret(pairing.secret),
+                expiresAt: pairing.expiresAt,
+                timer,
+            });
+        }
+        catch (error) {
+            connection.send({
+                type: "error",
+                id: request.id,
+                code: "pair_failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // ==========================================================================
+    // Control plane integration
+    // ==========================================================================
+    async handleRequest(connection, request) {
+        switch (request.type) {
+            case "lease_acquire": {
+                const outcome = await this.leaseBroker.acquireForTui({
+                    connectionId: connection.connectionId,
+                    workspaceName: request.workspaceName,
+                    sessionId: request.sessionId,
+                    force: request.force,
+                });
+                if (outcome.kind === "granted") {
+                    connection.send({
+                        type: "lease_granted",
+                        id: request.id,
+                        workspaceName: request.workspaceName,
+                        sessionId: request.sessionId,
+                        handoff: outcome.handoff,
+                    });
+                    return true;
+                }
+                if (outcome.kind === "denied") {
+                    connection.send({ type: "lease_denied", id: request.id, reason: outcome.reason });
+                    return true;
+                }
+                connection.send({ type: "lease_pending", id: request.id, viewerFeedId: outcome.viewerFeedId });
+                outcome.granted.then((granted) => {
+                    connection.send({
+                        type: "lease_granted",
+                        id: request.id,
+                        workspaceName: request.workspaceName,
+                        sessionId: request.sessionId,
+                        handoff: granted.handoff,
+                    });
+                }, (error) => {
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: "drain_failed",
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                return true;
+            }
+            case "lease_release": {
+                const result = this.leaseBroker.releaseFromTui(connection.connectionId, request.workspaceName, request.sessionId);
+                if (!result.ok) {
+                    connection.send({ type: "error", id: request.id, code: result.code, message: "lease not held" });
+                    return true;
+                }
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "lease_rekey": {
+                this.leaseBroker.rekey(request.workspaceName, request.oldSessionId, request.newSessionId);
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "viewer_subscribe": {
+                if (!this.viewerFeeds.subscribe(request.viewerFeedId, connection.connectionId)) {
+                    connection.send({ type: "error", id: request.id, code: "not_found", message: "unknown viewer feed" });
+                    return true;
+                }
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "viewer_unsubscribe": {
+                if (!this.viewerFeeds.unsubscribe(request.viewerFeedId, connection.connectionId)) {
+                    connection.send({ type: "error", id: request.id, code: "not_found", message: "unknown viewer feed" });
+                    return true;
+                }
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "viewer_abort": {
+                if (!(await this.viewerFeeds.abort(request.viewerFeedId, connection.connectionId))) {
+                    connection.send({ type: "error", id: request.id, code: "not_found", message: "unknown viewer feed" });
+                    return true;
+                }
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "pair_request":
+                await this.handlePairRequest(connection, request);
+                return true;
+            case "pair_cancel": {
+                const pending = this.pendingPairRequests.get(request.requestId);
+                if (!pending || pending.connectionId !== connection.connectionId) {
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: "not_found",
+                        message: "pairing request not found",
+                    });
+                    return true;
+                }
+                try {
+                    await this.cancelPendingPairing(request.requestId, pending);
+                    connection.send({ type: "ok", id: request.id });
+                }
+                catch (error) {
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: "cancel_failed",
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                return true;
+            }
+            case "relay_rpc": {
+                const result = await this.handleRelayRpc(connection, request);
+                if (!result.ok) {
+                    connection.send({ type: "error", id: request.id, code: result.code, message: result.message });
+                    return true;
+                }
+                connection.send({
+                    type: "relay_rpc_result",
+                    id: request.id,
+                    response: result.response,
+                    ...(result.workspaceMetadata === undefined ? {} : { workspaceMetadata: result.workspaceMetadata }),
+                });
+                return true;
+            }
+            case "relay_notification_delivery": {
+                const result = await this.handleRelayNotificationDelivery(connection, request);
+                if (!result.ok) {
+                    connection.send({ type: "error", id: request.id, code: result.code, message: result.message });
+                    return true;
+                }
+                connection.send({ type: "relay_push_delivery_result", id: request.id, status: result.status });
+                return true;
+            }
+            case "relay_live_activity_delivery": {
+                const result = await this.handleRelayLiveActivityDelivery(connection, request);
+                if (!result.ok) {
+                    connection.send({ type: "error", id: request.id, code: result.code, message: result.message });
+                    return true;
+                }
+                connection.send({ type: "relay_push_delivery_result", id: request.id, status: result.status });
+                return true;
+            }
+            case "client_access_update": {
+                const access = request.access !== undefined
+                    ? createIrohRemotePresetAccess(request.access)
+                    : createIrohRemoteExplicitAccess(request.allowedTools ?? [], parseIrohRemoteRpcCapabilities(request.rpcCapabilities));
+                const engine = this.engine;
+                const updated = engine
+                    ? await engine.updateClientAccess(request.clientNodeId, request.expectedRevision, access)
+                    : await this.stateManager.updateClientAccess(request.clientNodeId, request.expectedRevision, access);
+                if (!engine) {
+                    await this.logAudit({
+                        type: "client_access_updated",
+                        clientNodeId: request.clientNodeId,
+                        success: updated.ok,
+                        error: updated.ok ? undefined : updated.reason,
+                        details: {
+                            expectedRevision: request.expectedRevision,
+                            ...(updated.ok
+                                ? { revision: updated.client.rpcGrant.revision }
+                                : { currentRevision: updated.currentRevision }),
+                        },
+                    });
+                }
+                if (!updated.ok) {
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: updated.reason,
+                        message: updated.reason === "revision_conflict"
+                            ? `RPC grant revision conflict (current ${updated.currentRevision ?? "unknown"})`
+                            : updated.reason === "revision_exhausted"
+                                ? "RPC grant revision is exhausted; revoke and re-pair the client"
+                                : "client not found",
+                    });
+                    return true;
+                }
+                await this.services.state.flush();
+                await this.closeClientForAccessUpdate(request.clientNodeId);
+                connection.send({
+                    type: "client_access_updated",
+                    id: request.id,
+                    client: {
+                        clientNodeId: updated.client.nodeId,
+                        label: updated.client.label,
+                        pairedAtMs: updated.client.pairedAt,
+                        lastSeenAtMs: updated.client.lastSeenAt,
+                        allowedTools: updated.client.allowedTools.length === 0 ? [] : updated.client.allowedTools.split(","),
+                        rpcGrant: updated.client.rpcGrant,
+                    },
+                });
+                return true;
+            }
+            case "client_revoke": {
+                const result = await this.requireEngineSafe();
+                if (!result.ok) {
+                    connection.send({ type: "error", id: request.id, code: "iroh_unavailable", message: result.error });
+                    return true;
+                }
+                const revocation = await result.engine.revokeClient(request.clientNodeId);
+                if (!revocation.revoked) {
+                    connection.send({ type: "error", id: request.id, code: "not_found", message: "client not found" });
+                    return true;
+                }
+                await this.closeActiveStreamsForClient(request.clientNodeId);
+                await this.revokeClientPushTargets(revocation.client);
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            case "workspace_unregister": {
+                let removedWorkspace;
+                try {
+                    removedWorkspace = await this.stateManager.unregisterWorkspace(request.name);
+                }
+                catch (error) {
+                    if (!isIrohRemoteWorkspaceHasWorktreesError(error)) {
+                        throw error;
+                    }
+                    await this.logAudit({
+                        type: "workspace_unregistered",
+                        workspace: request.name,
+                        success: false,
+                        error: IROH_REMOTE_WORKSPACE_HAS_WORKTREES_ERROR,
+                        details: {
+                            source: "control",
+                            worktreeCount: error.worktreeIds.length,
+                            worktreeIds: error.worktreeIds,
+                        },
+                    });
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: IROH_REMOTE_WORKSPACE_HAS_WORKTREES_ERROR,
+                        message: error.message,
+                    });
+                    return true;
+                }
+                if (!removedWorkspace) {
+                    connection.send({
+                        type: "error",
+                        id: request.id,
+                        code: "not_found",
+                        message: `No registered workspace named ${request.name}`,
+                    });
+                    return true;
+                }
+                this.engine?.clearPairingSecretForWorkspace(request.name);
+                await this.cleanupUnregisteredWorkspace(request.name, { workspacePath: removedWorkspace.path });
+                await this.logAudit({
+                    type: "workspace_unregistered",
+                    workspace: request.name,
+                    success: true,
+                    details: { source: "control" },
+                });
+                connection.send({ type: "ok", id: request.id });
+                return true;
+            }
+            default:
+                if (isWorktreeControlRequest(request)) {
+                    await handleWorktreeControlRequest(connection, request, {
+                        manager: this.worktrees,
+                        stateManager: this.stateManager,
+                        removeWorktree: (workspace, worktreeId, force) => this.removeWorkspaceWorktree(workspace, worktreeId, force),
+                    });
+                    return true;
+                }
+                return false;
+        }
+    }
+    async createRelayDeliveryAuthorization(connection, request) {
+        const lease = this.leaseBroker.lookup(request.workspaceName, request.sessionId);
+        if (!lease || lease.state !== "tui-owned" || lease.tuiConnectionId !== connection.connectionId) {
+            return {
+                ok: false,
+                code: "not_held",
+                message: "relay lease is not held by this control connection",
+            };
+        }
+        const client = await this.stateManager.getClient(request.clientNodeId);
+        if (!client) {
+            return { ok: false, code: "not_found", message: "paired client not found" };
+        }
+        const workspace = (await this.stateManager.getState()).workspaces.find((candidate) => candidate.name === request.workspaceName);
+        if (!workspace) {
+            return { ok: false, code: "not_found", message: `no registered workspace named ${request.workspaceName}` };
+        }
+        return {
+            ok: true,
+            authorization: {
+                ok: true,
+                allowTools: client.allowedTools,
+                client,
+                paired: true,
+                pairingSecretConsumed: false,
+                workspace,
+                workspaceNames: [workspace.name],
+                workspaces: [{ name: workspace.name, status: "available" }],
+            },
+        };
+    }
+    async handleRelayNotificationDelivery(connection, request) {
+        const notification = request.notification;
+        if (notification.sessionId !== undefined && notification.sessionId !== request.sessionId) {
+            return { ok: false, code: "session_mismatch", message: "notification session does not match relay session" };
+        }
+        if (notification.workspace !== undefined && notification.workspace !== request.workspaceName) {
+            return {
+                ok: false,
+                code: "workspace_mismatch",
+                message: "notification workspace does not match relay workspace",
+            };
+        }
+        const authorization = await this.createRelayDeliveryAuthorization(connection, request);
+        if (!authorization.ok) {
+            return authorization;
+        }
+        const scopedNotification = {
+            ...notification,
+            sessionId: notification.sessionId ?? request.sessionId,
+            workspace: notification.workspace ?? request.workspaceName,
+        };
+        try {
+            const status = await this.createPushNotificationDispatcher(authorization.authorization).deliverNotification(scopedNotification);
+            return { ok: true, status };
+        }
+        catch {
+            return { ok: true, status: "failed" };
+        }
+    }
+    async handleRelayLiveActivityDelivery(connection, request) {
+        const contentState = request.update.contentState;
+        if (contentState.sessionID !== undefined && contentState.sessionID !== request.sessionId) {
+            return { ok: false, code: "session_mismatch", message: "Live Activity session does not match relay session" };
+        }
+        if (contentState.workspaceName !== undefined && contentState.workspaceName !== request.workspaceName) {
+            return {
+                ok: false,
+                code: "workspace_mismatch",
+                message: "Live Activity workspace does not match relay workspace",
+            };
+        }
+        const authorization = await this.createRelayDeliveryAuthorization(connection, request);
+        if (!authorization.ok) {
+            return authorization;
+        }
+        const scopedUpdate = {
+            ...request.update,
+            contentState: {
+                ...contentState,
+                sessionID: contentState.sessionID ?? request.sessionId,
+                workspaceName: contentState.workspaceName ?? request.workspaceName,
+            },
+        };
+        try {
+            const status = await this.createPushNotificationDispatcher(authorization.authorization).deliverLiveActivityUpdate(scopedUpdate);
+            return { ok: true, status };
+        }
+        catch {
+            return { ok: true, status: "failed" };
+        }
+    }
+    /**
+     * Execute a state-touching RPC command forwarded from a TUI-owned relay
+     * against the daemon's real state (§5.6): push targets, live activities,
+     * and workspace unregistration must land here, not in the TUI's in-memory
+     * state copy.
+     */
+    async handleRelayRpc(connection, request) {
+        const relayAuthorization = this.relays.authorizeRpc(request.relayId, connection.connectionId, request);
+        if (!relayAuthorization.ok) {
+            return relayAuthorization;
+        }
+        const command = request.command;
+        if (!RELAY_RPC_COMMAND_TYPES.has(command.type)) {
+            return { ok: false, code: "unsupported", message: `unsupported relay rpc command: ${command.type}` };
+        }
+        const client = await this.stateManager.getClient(request.clientNodeId);
+        if (!client) {
+            return { ok: false, code: "not_found", message: "paired client not found" };
+        }
+        const requiredCapabilities = getIrohRemoteRpcCommandCapabilities(command);
+        if (requiredCapabilities === undefined) {
+            return { ok: false, code: "unsupported", message: `unsupported relay rpc command: ${command.type}` };
+        }
+        const missingCapability = getMissingIrohRemoteRpcCapability(client.rpcGrant, requiredCapabilities);
+        if (missingCapability !== undefined) {
+            return {
+                ok: true,
+                response: {
+                    ...createIrohRemoteRpcCapabilityDeniedResponse(getRpcResponseId(command), command.type, missingCapability),
+                },
+            };
+        }
+        const workspace = (await this.stateManager.getState()).workspaces.find((candidate) => candidate.name === request.workspaceName);
+        if (!workspace) {
+            return { ok: false, code: "not_found", message: `no registered workspace named ${request.workspaceName}` };
+        }
+        const authorization = {
+            ok: true,
+            allowTools: client.allowedTools,
+            client,
+            paired: true,
+            pairingSecretConsumed: false,
+            workspace,
+            workspaceNames: [workspace.name],
+            workspaces: [{ name: workspace.name, status: "available" }],
+        };
+        const responseId = getRpcResponseId(command);
+        if (command.type === "set_keep_awake" || command.type === "get_keep_awake") {
+            const response = createKeepAwakeRpcResponse(command, this.getCommandContext());
+            return { ok: true, response: response };
+        }
+        if (command.type === "set_web_search_key" || command.type === "get_web_search_status") {
+            const response = createWebSearchKeyRpcResponse(command, this.getCommandContext());
+            return { ok: true, response: response };
+        }
+        if (command.type === "register_push_target") {
+            try {
+                const data = await this.createPushNotificationDispatcher(authorization).registerPushTarget(command.args);
+                return { ok: true, response: createRpcSuccessResponse(responseId, command.type, { ...data }) };
+            }
+            catch (error) {
+                return {
+                    ok: true,
+                    response: {
+                        ...createIrohRemoteRpcErrorResponse(responseId, command.type, error instanceof Error ? error.message : String(error)),
+                    },
+                };
+            }
+        }
+        if (command.type === "register_live_activity") {
+            const response = await createRemoteRegisterLiveActivityRpcResponse(command, authorization, this.getCommandContext(), request.sessionId);
+            return { ok: true, response: response };
+        }
+        if (command.type === "unregister_live_activity") {
+            const response = await createRemoteUnregisterLiveActivityRpcResponse(command, authorization, this.getCommandContext(), request.sessionId);
+            return { ok: true, response: response };
+        }
+        // unregister_workspace: run against the daemon state with the shared host
+        // cleanup, keeping the requesting conversation's own relays open so the
+        // response can still be delivered over them.
+        const excludeRelayIds = new Set(this.relays
+            .activeForConversation(request.clientNodeId, request.workspaceName, request.sessionId)
+            .map((relay) => relay.relayId));
+        const context = {
+            ...this.getCommandContext(),
+            onWorkspaceUnregistered: async (workspaceName) => {
+                await this.cleanupUnregisteredWorkspace(workspaceName, {
+                    relayIds: excludeRelayIds,
+                    workspacePath: workspace.path,
+                });
+            },
+        };
+        const response = await handleRemoteHostRpcCommand(command, authorization, context);
+        if (!response) {
+            return { ok: false, code: "unsupported", message: `unsupported relay rpc command: ${command.type}` };
+        }
+        return {
+            ok: true,
+            response: response,
+            workspaceMetadata: {
+                workspaceNames: [...authorization.workspaceNames],
+                workspaces: authorization.workspaces.map((entry) => ({ name: entry.name, status: entry.status })),
+            },
+        };
+    }
+    async requireEngineSafe() {
+        try {
+            await withTimeout(this.ready.promise, IROH_ENDPOINT_READY_TIMEOUT_MS, "Iroh endpoint did not become ready within 15s");
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!this.engine) {
+            return { ok: false, error: "iroh host engine is not ready" };
+        }
+        return { ok: true, engine: this.engine };
+    }
+    async cancelPendingPairing(requestId, pending) {
+        clearTimeout(pending.timer);
+        if (this.engine) {
+            await this.engine.cancelPairingSecretByHash(pending.secretHash);
+        }
+        else {
+            await this.stateManager.removePendingPairingTicket(pending.secretHash);
+        }
+        await this.services.state.flush();
+        this.pendingPairRequests.delete(requestId);
+    }
+    onControlConnectionClosed(connection) {
+        this.leaseBroker.releaseAllForConnection(connection.connectionId);
+        for (const [requestId, pending] of this.pendingPairRequests) {
+            if (pending.connectionId !== connection.connectionId)
+                continue;
+            void this.cancelPendingPairing(requestId, pending).catch((error) => {
+                this.log("warn", "failed to cancel pairing after control disconnect", {
+                    requestId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
+    }
+    admitRelay(relayId, relayToken, socket, bufferedRemainder) {
+        return this.relays.admit(relayId, relayToken, socket, bufferedRemainder);
+    }
+    statusExtras() {
+        const leases = this.leaseBroker.list().map((record) => ({
+            workspaceName: record.workspaceName,
+            sessionId: record.sessionId,
+            state: record.state,
+            relayCount: record.relayIds.size,
+            streamCount: record.streamCount,
+        }));
+        return { leases, phoneConnections: this.clientConnections.size, relayCount: this.relays.activeCount() };
+    }
+    async shutdown() {
+        this.shuttingDown = true;
+        this.worktreeRetention.dispose();
+        // 1. Stop accepting: close the endpoint accept loop lazily; new hellos are
+        //    rejected by the control server's shutting-down gate. Close relays and
+        //    unredeemed offers up front with the dedicated host_shutdown reason —
+        //    otherwise they die with the endpoint and TUIs see a misleading
+        //    relay_closed{error}.
+        for (const relay of this.relays.activeRelays()) {
+            relay.close("host_shutdown");
+        }
+        for (const pending of this.relays.pendingRelays()) {
+            this.abortPendingRelay(pending.relayId, "host_shutdown", "daemon shutting down");
+        }
+        // 2. Wait for busy runtimes to go idle (60s cap each, concurrently);
+        //    never abort prompt preflight or a turn from shutdown.
+        const drainResults = await Promise.allSettled(this.runtimes
+            .values()
+            .filter((entry) => entry.runtime.session.isBusy)
+            .map((entry) => withTimeout(entry.runtime.session.waitForIdle(), SHUTDOWN_RUNTIME_IDLE_CAP_MS, "drain cap")));
+        const cappedRuntimes = drainResults.filter((result) => result.status === "rejected").length;
+        // 3. Flush + dispose runtimes through the normal dispose path.
+        await this.runtimes.stopAll("host_shutdown");
+        // 4. Close all phone streams and connections with reason host_shutdown.
+        for (const nodeId of Array.from(this.clientConnections.keys())) {
+            for (const entry of this.activeStreams.entriesForClientNodeId(nodeId)) {
+                this.activeStreams.unregister(entry);
+                await Promise.resolve(entry.close("host_shutdown")).catch(() => { });
+            }
+            await this.closeClientConnectionsForClient(nodeId, "host_shutdown");
+        }
+        try {
+            await this.endpoint?.close();
+        }
+        catch {
+            // Endpoint shutdown is best-effort.
+        }
+        await Promise.allSettled(this.connectionTasks);
+        await this.services.auditLogger.flush().catch(() => { });
+        this.log("info", "iroh service stopped", { cappedRuntimes });
+    }
+    async logAudit(event) {
+        try {
+            await this.services.auditLogger.log(event);
+        }
+        catch {
+            // Audit logging is best-effort.
+        }
+    }
+}
+//# sourceMappingURL=iroh-service.js.map