@geohar/un-bien 0.9.0 → 0.16.0

package/dist/index.js

@@ -30,54 +30,39 @@
  *   for integration tests.
  */
 import { randomUUID } from "node:crypto";
-import { SettingsManager } from "@earendil-works/pi-coding-agent";
-import { buildQRUri, qrSession, renderQRAscii, clampPairTtlMs, TOKEN_TTL_MS, } from "./pairing/qr.js";
-import { addPeer, getOrCreateEd25519Keypair, describeIdentity, KeyringUnavailableError, PairedIdentityMissingError, listPeers, removePeer, snapshotOwnerPubkeys, conditionalRemovePeer, } from "./pairing/storage.js";
-import { MeshClient } from "./mesh/client.js";
-import { SelfRevoke } from "./mesh/self_revoke.js";
-import { RelayClient, RoomAlreadyOpenError } from "./transport/relay_client.js";
-import { PlainPeerChannel } from "./transport/peer_channel.js";
+import { listPeers, pairingAllowList } from "./pairing/storage.js";
 import { createExtensionUiBridge, } from "./extension_ui_bridge.js";
 import { createPanelBridge } from "./panel_bridge.js";
 import { initSubagentRooms, subagentRoomsEnabled, } from "./subagent_rooms.js";
-import { createRpcEnvelope, isEnvelopeFrame, helloEnvelope, } from "./session/rpc_envelope.js";
-import { dispatchRpcCommand, } from "./session/rpc_inbound.js";
+import { createRpcEnvelope, } from "./session/rpc_envelope.js";
+import { dispatchRpcCommand } from "./session/rpc_inbound.js";
 import { envLog } from "./session/debug_log.js";
-import { roomIdFor, roomIdForSession } from "./rooms.js";
+import { roomIdForSession } from "./rooms.js";
 import { registerAgentTools } from "./session/tools.js";
 import { formatPeerInventory } from "./session/peer_inventory.js";
-import { MeshNode } from "./session/mesh_node.js";
-import { wireFromModel, } from "./actions/handlers.js";
-import { ensureModelRegistry } from "./actions/registry.js";
-import { ensureGlobalDirs, LOCAL_SESSION_NAME, sessionAuditPath, sessionSockPath, skillsDir, } from "./session/global_config.js";
-import { acquireCwdLock } from "./session/cwd_lock.js";
-import { installService, uninstallService, linkCliBinaries, unlinkCliBinaries, } from "./daemon/install.js";
-import { defaultAgentName, effectiveAutoStartRelay, effectiveAllowRemoteLaunch, loadLocalConfig, localConfigExists, saveLocalConfig, } from "./session/local_config.js";
-import { runSetupWizard } from "./session/setup_wizard.js";
+import { ensureGlobalDirs, LOCAL_SESSION_NAME, sessionSockPath, skillsDir, } from "./session/global_config.js";
+import { effectiveAutoStartRelay, effectiveAllowRemoteLaunch, effectiveAllowRemoteTerminate, loadLocalConfig, localConfigExists, piSessionName, resolveAgentName, saveLocalConfig, } from "./session/local_config.js";
 import { updateFooter } from "./ui/footer.js";
-import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { chmodSync, mkdirSync, copyFileSync, existsSync, unlinkSync, readFileSync, writeFileSync, realpathSync, } from "node:fs";
-import { createInterface } from "node:readline";
-import { spawnSync } from "node:child_process";
-import { hostname, tmpdir } from "node:os";
-import { resolveRelayUrl, loadConfig, saveConfig, isValidRelayUrl, isWebSocketScheme, toWebSocketUrl, } from "./config.js";
-import { _expandTilde, _launchSession } from "./launch.js";
+import { realpathSync } from "node:fs";
+import { loadConfig, saveConfig, isValidRelayUrl, isWebSocketScheme, } from "./config.js";
+import { _expandTilde, _launchSession, launchDirAllowed } from "./launch.js";
 import { _enrichToolArgs } from "./enrich_tool_args.js";
-import { IMAGE_PREVIEW_MIME, _imageCacheRootDir, _imageExtension, _safeFilenameToken, _safePreviewPath, _renderablePngPathFromImage, _decodeImagePayload, } from "./image_codec.js";
-import { _findKnownPeer, _inspectPeerRecord, _runtimeOwnerFingerprint, } from "./pairing/peer_trust.js";
-import { Box, Container, Image, Text } from "@earendil-works/pi-tui";
+import { _inspectPeerRecord, _runtimeOwnerFingerprint, } from "./pairing/peer_trust.js";
+import { _flushPendingReceivedImagePreviews, _isReceivedImageContextMessage, _registerReceivedImageRenderer, } from "./session/received_images.js";
+import { _cmdRoot, _cmdStart, } from "./commands/lifecycle.js";
+import { _cmdClaudeCli, _cmdInstall, _cmdUninstall, _deployAgentNetworkSkill, } from "./commands/housekeeping.js";
+import { registerUnbienCommands } from "./commands/register.js";
+import { takeForkLink } from "./commands/fork_link.js";
+import { createTestHooks } from "./test_hooks.js";
+import { createRpcHandlers, } from "./session/rpc_handlers.js";
+import { CTRL_PREFIX, _anyPeerActive, _broadcastEnvelope, _broadcastEnvelopeFlushed, _controlCtx, _detachPeerChannel, _emitRelayState, _getReconnectTimer, _getRelayLifecycleGeneration, _goIdle, _handleControl as _handleControlImpl, _headlessUi, _installAutoListener, _onPeerDisconnect as _onPeerDisconnectImpl, _onRelayClose, _panelBroadcast, _relayStatus, _setRelayLifecycleGeneration, _uiBroadcast, } from "./session/relay_lifecycle.js";
+// Relay-lifecycle seam re-exports: the control-channel sentinel + the
+// connectivity type moved to ./session/relay_lifecycle.ts; these keep the
+// exact export surface (tests import CTRL_PREFIX from here).
+export { CTRL_PREFIX };
 let _state = "idle";
 let _relay = null;
-/** Last `RelayConnectivity` emitted, for change-dedup. Starts "disconnected"
- *  (the process boots with the relay down). */
-let _lastRelayStatus = null;
-/** Sentinel prefix for a transparent control message an RPC client sends on the
- *  `prompt` channel (stdin). The `input` hook intercepts it, runs the action,
- *  and swallows it (`action:"handled"`) so it never becomes an LLM turn or a
- *  transcript entry. Starts with NUL so it can't collide with real user input
- *  and doesn't begin with "/" (which would route to the command parser). */
-export const CTRL_PREFIX = "\x00un-bien-ctrl:";
 let _relayUrl = null; // URL used by current _relay connection
 /**
  * Owners currently connected via the relay. Key = app peer pubkey (Ed25519,
@@ -93,16 +78,24 @@ let _relayUrl = null; // URL used by current _relay connection
  */
 const _activePeers = new Map();
 let _peerShort = ""; // shortid of the most recently attached peer (UX hint only)
-const UNBIEN_RECEIVED_IMAGE_TYPE = "un-bien:received-image";
-const _pendingReceivedImagePreviews = [];
 let _myRoomId = null; // this Pi's room id (derived from the session id)
-/** THE App<->Pi room id for the current chat session. Prefers the STABLE pi
- *  session id (durable across resume) so the room can't drift when the assigned
- *  name changes on reconnect; falls back to the legacy (cwd, name) derivation
- *  only when no session id is available yet (pre-sessionManager edge). */
-function _deriveRoomId(cwd, name) {
+/** True when a relay start was DEFERRED because no session id existed yet
+ *  (design 01M1CAW0). The root session_start handler re-runs the start once
+ *  the session id becomes available. */
+let _relayStartDeferred = false;
+/** THE App<->Pi room id for the current chat session: ALWAYS derived from the
+ *  STABLE pi session id (durable across resume) so the room can't drift when
+ *  the assigned name changes on reconnect. Returns null when no session id
+ *  exists yet — the legacy (cwd, name) fallback is RETIRED (design 01M1CAW0):
+ *  it was identical for same-cwd processes, so a pre-session subprocess could
+ *  announce the SAME room an earlier session occupies (and a parent's keeper
+ *  then stamped set-once parentage onto that shared room). Callers must SKIP
+ *  the room announce/join on null — never guess a cwd-derived room id.
+ *  `cwd`/`name` are still accepted because callers derive them for room_meta
+ *  labels, but they no longer key the room. */
+function _deriveRoomId(_cwd, _name) {
     const sid = _rootState().sessionManager?.getSessionId();
-    return sid ? roomIdForSession(sid) : roomIdFor(cwd, name);
+    return sid ? roomIdForSession(sid) : null;
 }
 // Plan/28 Wave D.1: `thinking` published alongside `model` so the app's
 // Quick Actions sheet hydrates the thinking segmented control on first
@@ -144,6 +137,12 @@ function _refreshPairingsCache() {
     void listPeers()
         .then((peers) => {
         _hasGlobalPairings = peers.length > 0;
+        // Keep the relay's ROOMS-gate allow-list in sync on every pairing change
+        // (pair / unpair / revoke). Design 01M1ZE43; no-ops when the relay is down.
+        _relay?.sendControl({
+            type: "pairing_set",
+            owners: pairingAllowList(peers),
+        });
         _refreshFooter();
     })
         .catch(() => {
@@ -211,193 +210,6 @@ function _publishWorking(working) {
         });
     }
 }
-function _sendReceivedImagePreviewNow(details) {
-    if (!_pi)
-        return;
-    try {
-        _pi.sendMessage({
-            customType: UNBIEN_RECEIVED_IMAGE_TYPE,
-            content: "",
-            display: true,
-            details,
-        });
-    }
-    catch {
-        // TUI preview is best-effort; skip on failure.
-    }
-}
-function _shouldDeferReceivedImagePreview() {
-    return _rootState().turnId !== null || _myRoomMeta?.working === true;
-}
-function _sendReceivedImagePreview(details, delivery = "immediate") {
-    if (delivery === "defer" || _shouldDeferReceivedImagePreview()) {
-        _pendingReceivedImagePreviews.push(details);
-        return;
-    }
-    _sendReceivedImagePreviewNow(details);
-}
-function _flushPendingReceivedImagePreviews() {
-    if (_pendingReceivedImagePreviews.length === 0)
-        return;
-    const pending = _pendingReceivedImagePreviews.splice(0);
-    for (const details of pending)
-        _sendReceivedImagePreviewNow(details);
-}
-async function _collectReceivedImagePreviews(msg) {
-    if (!msg.images || msg.images.length === 0)
-        return [];
-    const previews = [];
-    const text = typeof msg.text === "string" ? msg.text : "";
-    const dir = _imageCacheRootDir();
-    for (let i = 0; i < msg.images.length; i += 1) {
-        const image = msg.images[i];
-        const mime = typeof image?.mime === "string" ? image.mime : "unknown";
-        if (!image || typeof image.data !== "string") {
-            console.error(`[un-bien] malformed image in message ${msg.id} index=${i}`);
-            previews.push({
-                messageId: msg.id,
-                index: i,
-                mime,
-                ...(text ? { text } : {}),
-                error: "malformed image payload",
-                reason: "missing mime/data payload fields",
-            });
-            continue;
-        }
-        const decoded = _decodeImagePayload(image.data, image.mime);
-        if (!decoded.ok) {
-            console.error(`[un-bien] skipped image id=${msg.id} index=${i}: ${decoded.reason}`);
-            previews.push({
-                messageId: msg.id,
-                index: i,
-                mime: image.mime,
-                ...(text ? { text } : {}),
-                error: "invalid image payload",
-                reason: decoded.reason,
-            });
-            continue;
-        }
-        const ext = _imageExtension(image.mime);
-        if (!ext) {
-            console.error(`[un-bien] unsupported image mime in message ${msg.id} index=${i}: ${image.mime}`);
-            previews.push({
-                messageId: msg.id,
-                index: i,
-                mime: image.mime,
-                ...(text ? { text } : {}),
-                error: "invalid image payload",
-                reason: `unsupported mime: ${image.mime}`,
-            });
-            continue;
-        }
-        const filename = `${_safeFilenameToken(msg.id)}-${i}.${ext}`;
-        const path = join(dir, filename);
-        try {
-            writeFileSync(path, decoded.decoded, { mode: 0o600 });
-            try {
-                chmodSync(path, 0o600);
-            }
-            catch {
-                /* best-effort permission hardening */
-            }
-            const previewPath = image.mime === IMAGE_PREVIEW_MIME
-                ? undefined
-                : await _renderablePngPathFromImage(image.data, image.mime, _safePreviewPath(dir, msg.id, i));
-            previews.push({
-                messageId: msg.id,
-                index: i,
-                mime: image.mime,
-                size: decoded.size,
-                path,
-                ...(previewPath ? { previewPath } : {}),
-                ...(text ? { text } : {}),
-            });
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            console.error(`[un-bien] failed saving image id=${msg.id} index=${i}: ${detail}`);
-            previews.push({
-                messageId: msg.id,
-                index: i,
-                mime: image.mime,
-                ...(text ? { text } : {}),
-                path,
-                error: "failed to save image",
-                reason: detail,
-            });
-        }
-    }
-    return previews;
-}
-async function _emitReceivedImagePreviews(msg, delivery = "immediate") {
-    const previews = await _collectReceivedImagePreviews(msg);
-    for (const preview of previews)
-        _sendReceivedImagePreview(preview, delivery);
-}
-function _registerReceivedImageRenderer(pi) {
-    pi.registerMessageRenderer(UNBIEN_RECEIVED_IMAGE_TYPE, (message, _options, theme) => {
-        const details = (message.details ?? {});
-        const path = typeof details.path === "string" ? details.path : "";
-        const previewPath = typeof details.previewPath === "string" ? details.previewPath : "";
-        const mime = typeof details.mime === "string"
-            ? details.mime
-            : "application/octet-stream";
-        const inlineImagePath = previewPath.length > 0
-            ? previewPath
-            : mime === IMAGE_PREVIEW_MIME
-                ? path
-                : "";
-        const size = typeof details.size === "number" ? details.size : undefined;
-        const index = typeof details.index === "number" ? details.index : undefined;
-        const text = typeof details.text === "string" ? details.text.trim() : "";
-        const messageId = typeof details.messageId === "string" ? details.messageId : "unknown";
-        const error = typeof details.error === "string" ? details.error : undefined;
-        const reason = typeof details.reason === "string" ? details.reason : undefined;
-        const label = `📷 Photo from Android (${messageId}${index === undefined ? "" : ` #${index}`})`;
-        const lines = [
-            theme.fg("customMessageLabel", label),
-            theme.fg("customMessageText", `Saved: ${path || "(not saved)"}`),
-        ];
-        if (size !== undefined)
-            lines.push(theme.fg("customMessageText", `Size: ${size} bytes`));
-        if (mime)
-            lines.push(theme.fg("customMessageText", `MIME: ${mime}`));
-        if (error)
-            lines.push(theme.fg("customMessageText", `Error: ${error}`));
-        if (reason)
-            lines.push(theme.fg("customMessageText", `Reason: ${reason}`));
-        if (text)
-            lines.push(theme.fg("customMessageText", `Text: ${text}`));
-        const container = new Container();
-        const metadata = new Box(1, 1, (line) => theme.bg("customMessageBg", line));
-        metadata.addChild(new Text(lines.join("\n")));
-        container.addChild(metadata);
-        if (inlineImagePath && !error) {
-            try {
-                const imageData = readFileSync(inlineImagePath).toString("base64");
-                if (imageData.length > 0) {
-                    const image = new Image(imageData, IMAGE_PREVIEW_MIME, {
-                        fallbackColor: (str) => theme.fg("customMessageText", str),
-                    });
-                    // Keep Kitty image rows out of Box padding/background so pi-tui can
-                    // preserve the empty reserved rows that make inline images visible.
-                    container.addChild(image);
-                }
-            }
-            catch {
-                // Keep the metadata-only fallback on any IO/terminal issue.
-            }
-        }
-        return container;
-    });
-}
-function _isReceivedImageContextMessage(message) {
-    return (typeof message === "object" &&
-        message !== null &&
-        message.role === "custom" &&
-        message.customType ===
-            UNBIEN_RECEIVED_IMAGE_TYPE);
-}
 /**
  * Issue #105 — pure-data events must not reach the model.
  *
@@ -430,57 +242,6 @@ function _filterInternalMessagesFromContext(messages) {
             !_isPureDataContextMessage(message))
         : [];
 }
-function _contentFromUserMessage(msg) {
-    return msg.images && msg.images.length > 0
-        ? [
-            ...msg.images.map((img) => ({
-                type: "image",
-                data: img.data,
-                mimeType: img.mime,
-            })),
-            { type: "text", text: msg.text },
-        ]
-        : msg.text;
-}
-async function _deliverImageUserMessage(sender, msg, shouldSteer) {
-    const previewDelivery = shouldSteer || _rootState().turnId !== null || _myRoomMeta?.working === true
-        ? "defer"
-        : "immediate";
-    const emitPreview = async () => {
-        try {
-            await _emitReceivedImagePreviews(msg, previewDelivery);
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            console.error(`[un-bien] failed emitting image preview id=${msg.id}: ${detail}`);
-        }
-    };
-    if (previewDelivery === "immediate") {
-        await emitPreview();
-    }
-    else {
-        void emitPreview().finally(() => {
-            if (!_shouldDeferReceivedImagePreview())
-                _flushPendingReceivedImagePreviews();
-        });
-    }
-    const previousTurnId = _rootState().turnId;
-    const seededTurnId = !shouldSteer || _rootState().turnId === null;
-    if (seededTurnId)
-        _rootState().turnId = msg.id;
-    const wake = _wakeAgent(_contentFromUserMessage(msg), `app user_message id=${msg.id} (+${msg.images?.length ?? 0} image)`, "steer");
-    if (!wake.ok) {
-        if (seededTurnId)
-            _rootState().turnId = previousTurnId;
-        sender.send({
-            type: "error",
-            code: "internal_error",
-            in_reply_to: msg.id,
-            message: `Agent rejected incoming message: ${wake.detail}`,
-        });
-        return;
-    }
-}
 // ── Cross-PC mesh wiring (plan/25 Wave B/C) ───────────────────────────────────
 /**
  * Hand the live relay to MeshNode so it can bring up the cross-PC bridge
@@ -513,13 +274,14 @@ function _attachBridgeIfReady() {
     });
 }
 /**
- * Prefer an explicit ctx, then the always-fresh session_start ctx, then the
- * last command ctx. Relay/async paths must not rely on `_lastCtx` alone —
- * the SDK marks captured command ctxs stale after session replacement.
+ * Prefer an explicit ctx, else the always-fresh session_start ctx
+ * (`_lastEventCtx`, re-captured on every session_start so it is never a stale
+ * capture). Relay/async paths reach the ctx-only surfaces (ui/abort/compact)
+ * through this, since they fire outside any live pi event.
  * @see https://github.com/jacobaraujo7/remote_pi/issues/55
  */
 function _liveCtx(preferred) {
-    return preferred ?? _lastEventCtx ?? _lastCtx ?? null;
+    return preferred ?? _lastEventCtx ?? null;
 }
 /**
  * Read `ctx.ui` without letting a stale-ctx getter become an uncaughtException.
@@ -573,7 +335,7 @@ function _refreshFooter(ctx) {
             // `devicePaired` now reflects "any owner currently attached" — picks one
             // shortid representatively (multi-owner UX detail surfaces in the
             // `/unbien status` line, not the footer slot).
-            devicePaired: _anyPeerActive() ? _peerShort : undefined,
+            devicePaired: _anyPeerActive(relayDeps) ? _peerShort : undefined,
             hasPairings: _hasGlobalPairings,
             agentName: _meshNode?.name(),
         };
@@ -596,155 +358,6 @@ let _pendingMeshMessages = [];
 // agent-run active/generation now live PER-SESSION in _stateFor(sid).agentRun;
 // mesh delivery targets the ROOT run, so the drain reads _rootState().agentRun.
 let _meshDrainScheduled = false;
-/** Test-only override of the message buffer. */
-/**
- * Test-only: emulate what `/unbien` does on the returning-user path
- * (join the local mesh, then start the relay) without touching the FS for
- * a `localConfigExists()` lookup. Lets tests bring the relay up without
- * mocking the wizard or the local config storage.
- *
- * Typed loosely to accept any ctx shape with `ui.notify` + `cwd` — the
- * unit tests use minimal mocks that don't satisfy the full
- * `ExtensionContext` interface.
- */
-export async function _connectForTest(ctx) {
-    const real = ctx;
-    await _cmdJoin(real);
-    await _cmdStart(real);
-}
-/** Test-only: tear everything down (mirrors `/unbien stop`). */
-export async function _stopForTest(ctx) {
-    await _cmdStop(ctx);
-}
-/** Test-only: read/reset the `_disposed` flag. Production clears it only when
- *  a host reuses this module for a replacement session; tests share one module
- *  across cases, so they also reset it to avoid cross-test pollution. */
-export function _getDisposedForTest() {
-    return _disposed;
-}
-export function _setDisposedForTest(v) {
-    _disposed = v;
-}
-/** Test-only: reset the once-per-session auto-init gate so session_start re-runs it. */
-export function _resetAutoInitedForTest() {
-    _autoInited = false;
-}
-/** Test-only: clear the globalThis panel/ui bridge ownership so each fresh
- *  `extension(pi)` in a shared test process can (re)claim and rebuild bridges. */
-export function _resetBridgeOwnersForTest() {
-    const g = globalThis;
-    delete g[_ROOT_SESSION_OWNER_KEY];
-    _panelBridge?.dispose();
-    _panelBridge = null;
-    _rpcEnvelope?.dispose();
-    _rpcEnvelope = null;
-    _subagentRooms?.dispose();
-    _subagentRooms = null;
-    _extensionUiBridge?.dispose();
-    _extensionUiBridge = null;
-}
-/** Test-only: reset the keyed per-session state at a TEST BOUNDARY (beforeEach).
- *  Must NOT be folded into _resetBridgeOwnersForTest — that fires mid-test on
- *  every captureEventHandler call and would wipe state a test seeds across two
- *  captures (e.g. input seeds turnId, message_update reads it). */
-export function _resetSessionsForTest() {
-    _sessions.clear();
-    _rootSessionId = null;
-}
-/** Test-only: set the auto-init gate for lifecycle replacement tests. */
-export function _setAutoInitedForTest(value) {
-    _autoInited = value;
-}
-/** Test-only: true when this instance holds a live local-mesh node. */
-export function _hasMeshNodeForTest() {
-    return _meshNode !== null;
-}
-/** Test-only: drive the current real SelfRevoke producer through one sweep. */
-export async function _checkSelfRevokeForTest() {
-    await _selfRevoke?.checkOnce();
-}
-/** Test-only: the effective (possibly `#N`-suffixed) name the cwd-lock reserved. */
-export function _getLockedNameForTest() {
-    return _lockedName;
-}
-/** Test-only: release + clear the cwd lock (the lock normally survives stop). */
-export function _resetCwdLockForTest() {
-    try {
-        _cwdLock?.release();
-    }
-    catch {
-        /* ignored */
-    }
-    _cwdLock = null;
-    _lockedName = null;
-}
-/**
- * Test-only: relay-only startup, no UDS mesh join. Replaces the old
- * `unbien relay start` handler that some tests captured to bring up
- * the relay in isolation (e.g. ping/pong tests that don't care about the
- * agent-network broker).
- */
-export async function _startRelayForTest(ctx) {
-    await _cmdStart(ctx);
-}
-/** Test-only: public marker for canceled-keypair cache regression checks. */
-export function _getCachedPublicKeyForTest() {
-    return _cachedEd25519
-        ? Buffer.from(_cachedEd25519.publicKey).toString("base64")
-        : null;
-}
-/** Test-only override of session started timestamp. */
-export function _setSessionStartedAtForTest(ts) {
-    _sessionStartedAt = ts;
-}
-/** Test-only: reset the cached model name (between tests). */
-export function _setCurrentModelForTest(name) {
-    _currentModel = name;
-}
-/** Test-only: read the active turn id used for plain `cancel` routing. */
-export function _getCurrentTurnIdForTest() {
-    return _rootState().turnId;
-}
-/** Test-only: override the bound AgentSession so a spy can capture the
- *  content handed to `sendUserMessage` (plan/30 multimodal ingest). */
-export function _setPiForTest(pi) {
-    _pi = pi;
-}
-/**
- * Persist a model change to the PROJECT settings (`<cwd>/.pi/settings.json`) so
- * a model picked from the app survives a Pi/daemon restart. `pi.setModel` only
- * sets the LIVE model — on the next restart a fresh session reads the saved
- * default and reverts (the reported bug). We write the PROJECT scope, NOT
- * global, deliberately: the SDK merges global←project with PROJECT winning
- * (`SettingsManager`), so a folder that already has a project default (every
- * created daemon does) would shadow a global write like the TUI's. Project
- * scope is also correct for a fleet — each daemon keeps its own model rather
- * than leaking one default globally.
- *
- * Read-merge-write + best-effort: preserves other keys and never throws (a
- * settings write must not fail the live model change, which already applied).
- */
-function _persistModelDefault(provider, modelId) {
-    try {
-        const path = join(process.cwd(), ".pi", "settings.json");
-        let obj = {};
-        try {
-            const parsed = JSON.parse(readFileSync(path, "utf8"));
-            if (parsed && typeof parsed === "object")
-                obj = parsed;
-        }
-        catch {
-            /* no existing/parseable file → start fresh */
-        }
-        obj["defaultProvider"] = provider;
-        obj["defaultModel"] = modelId;
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(obj, null, 2));
-    }
-    catch {
-        /* best-effort — model change already applied live */
-    }
-}
 const _sessions = new Map();
 // The session bound to the app room. null until the ROOT session_start fires;
 // while null, everything is treated as root (single-session / test harness).
@@ -820,29 +433,14 @@ let _cwdLock = null;
 // registers under this name; the broker confirms it (and may bump it again under
 // a live race). Null until the lock is acquired.
 let _lockedName = null;
-// ── Relay reconnect state ─────────────────────────────────────────────────────
-// Backoffs in ms: 1s, 2s, 5s, 10s, 30s, then stays at 30s.
-const RECONNECT_BACKOFFS_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
-let _reconnectTimer = null;
-let _reconnectAttempt = 0;
-// Every initial connect/reconnect candidate captures this generation. Stop,
-// relay-off, and an unexpected close invalidate older async continuations.
-let _relayLifecycleGeneration = 0;
 // Root startup has pre-candidate awaits (cwd lock, wizard) that relay/mesh
 // generations cannot safely represent: child startup intentionally advances
 // those generations. Stop/off/session replacement advance this separate epoch
 // so a queued root can never regain authority by creating a newer child.
 let _rootLifecycleGeneration = 0;
-// Coalesces concurrent `/unbien` startup paths inside ONE extension instance.
-// Separate Pi processes still keep the existing #N behavior via the cwd lock.
-let _cmdRootInFlight = null;
 function _isCurrentRootLifecycle(generation) {
     return !_disposed && generation === _rootLifecycleGeneration;
 }
-/** Test-only: exposes pending reconnect timer state. */
-export function _hasPendingReconnect() {
-    return _reconnectTimer !== null;
-}
 /**
  * Public state-snapshot helper. Returns the derived UX state, not the raw
  * `_state` enum: the W2D refactor collapsed the internal machine to
@@ -855,19 +453,6 @@ export function _getState() {
         return "idle";
     return _activePeers.size > 0 ? "paired" : "started";
 }
-/** Test-only: number of owners currently attached via PlainPeerChannel. */
-export function _getActivePeerCountForTest() {
-    return _activePeers.size;
-}
-/** Test-only: true if a specific peer (base64 std) has an attached channel. */
-export function _hasActivePeerForTest(appPeerIdStd) {
-    return _activePeers.has(appPeerIdStd);
-}
-// ── Multi-channel helpers ─────────────────────────────────────────────────────
-/** Returns true when at least one owner is attached. Derived `paired` UX. */
-function _anyPeerActive() {
-    return _activePeers.size > 0;
-}
 // ── Hidden e2e UI test harness (dev-only, undocumented) ───────────────────
 // Broadcasts CANNED frames to paired apps so the app UI can be exercised
 // end-to-end without a real agent turn. For plan/subagents/rich-ask it EMITS the
@@ -880,6 +465,7 @@ const _TEST_SVG_B64 = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg" viewB
     ' font-family="sans-serif">un-bien</text></svg>').toString("base64");
 function _emitTestBus(channel, data) {
     try {
+        ;
         _pi?.events?.emit(channel, data);
     }
     catch {
@@ -892,7 +478,7 @@ function _runTestScenario(scenario) {
     const id = `test-${Date.now()}`;
     switch (s) {
         case "ask-select":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "extension_ui_request",
                     id,
@@ -903,7 +489,7 @@ function _runTestScenario(scenario) {
             });
             return "sent ask-select";
         case "ask-confirm":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "extension_ui_request",
                     id,
@@ -914,7 +500,7 @@ function _runTestScenario(scenario) {
             });
             return "sent ask-confirm";
         case "ask-input":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "extension_ui_request",
                     id,
@@ -925,7 +511,7 @@ function _runTestScenario(scenario) {
             });
             return "sent ask-input";
         case "ask-editor":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "extension_ui_request",
                     id,
@@ -936,7 +522,7 @@ function _runTestScenario(scenario) {
             });
             return "sent ask-editor";
         case "ask-notify":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "extension_ui_request",
                     id,
@@ -1020,8 +606,8 @@ function _runTestScenario(scenario) {
             // `{content:[{type:"image",data,mimeType}]}`) and renders them below the
             // card (WireImageView -> SVGImageView). Deliver the SVG that way.
             const tc = `tc-svg-${Date.now()}`;
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1029,7 +615,7 @@ function _runTestScenario(scenario) {
                     args: { note: "test svg" },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1046,13 +632,13 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent svg (envelope tool_execution_end + image)";
         }
         case "tool": {
             const tc = `tc-${Date.now()}`;
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1060,7 +646,7 @@ function _runTestScenario(scenario) {
                     args: { command: "echo hello" },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1068,7 +654,7 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent tool pair (envelope)";
         }
         case "diff": {
@@ -1086,8 +672,8 @@ function _runTestScenario(scenario) {
                     ],
                 },
             ];
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1100,7 +686,7 @@ function _runTestScenario(scenario) {
                 },
                 aux: { hunks },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1108,15 +694,15 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent diff (edit + aux hunks — shows the Diff⇄Content toggle)";
         }
         case "code-shell": {
             // bash-family result → the app classifies it into a `code` block (lang
             // shell), syntax-highlighted. OUTPUT is app-side now — no aux stamped.
             const tc = `tc-sh-${Date.now()}`;
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1124,7 +710,7 @@ function _runTestScenario(scenario) {
                     args: { command: "ls -la" },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1132,15 +718,15 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent code-shell (bash output → code block, lang shell)";
         }
         case "code-file": {
             // read-family with a *.swift path → `code` block, lang inferred from the
             // extension (swift) and highlighted.
             const tc = `tc-rd-${Date.now()}`;
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1148,7 +734,7 @@ function _runTestScenario(scenario) {
                     args: { path: "/src/Greeter.swift" },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1156,15 +742,15 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent code-file (read .swift → highlighted code block)";
         }
         case "diff-output": {
             // A tool whose RESULT already embeds a unified diff → the app parses it
             // into a `diff` block (re-reading persisted text; replay-safe).
             const tc = `tc-do-${Date.now()}`;
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1172,7 +758,7 @@ function _runTestScenario(scenario) {
                     args: { command: "git diff" },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1180,7 +766,7 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent diff-output (result embeds a unified diff → diff block)";
         }
         case "write": {
@@ -1188,8 +774,8 @@ function _runTestScenario(scenario) {
             // card shows the Content view (new text as a code block, replay-safe).
             const tc = `tc-wr-${Date.now()}`;
             const content = "export function add(a: number, b: number): number {\n  return a + b;\n}";
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_start",
                     toolCallId: tc,
@@ -1197,7 +783,7 @@ function _runTestScenario(scenario) {
                     args: { path: "/src/math.ts", content },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "tool_execution_end",
                     toolCallId: tc,
@@ -1205,12 +791,12 @@ function _runTestScenario(scenario) {
                     isError: false,
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent write (args.content → content-as-code block)";
         }
         case "agent": {
-            _broadcastEnvelope({ rpc: { type: "turn_start" } });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, { rpc: { type: "turn_start" } });
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "message_update",
                     assistantMessageEvent: {
@@ -1219,7 +805,7 @@ function _runTestScenario(scenario) {
                     },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "message_update",
                     assistantMessageEvent: {
@@ -1228,7 +814,7 @@ function _runTestScenario(scenario) {
                     },
                 },
             });
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "message_end",
                     message: {
@@ -1237,11 +823,11 @@ function _runTestScenario(scenario) {
                     },
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent agent message (envelope)";
         }
         case "error":
-            _broadcastEnvelope({
+            _broadcastEnvelope(relayDeps, {
                 rpc: {
                     type: "message_end",
                     message: {
@@ -1251,7 +837,7 @@ function _runTestScenario(scenario) {
                     },
                 },
             });
-            _broadcastEnvelope({ rpc: { type: "agent_settled" } });
+            _broadcastEnvelope(relayDeps, { rpc: { type: "agent_settled" } });
             return "sent error (envelope message_end/error)";
         case "all":
             for (const sc of [
@@ -1296,150 +882,7 @@ function _routeRpcCommandFrom(sender, env) {
     // session_sync (reconstruction) is un-bien's OWN protocol — dispatched on the
     // un plane by _routeUnBienPlaneFrom, NOT here. Only byte-faithful pi rpc
     // commands + extension_ui_response ride this rpc dispatch.
-    const handlers = {
-        prompt: async (message, opts) => {
-            // Full parity with the retired stock user_message handler:
-            //  - ALWAYS hand off with deliverAs:"steer" — the SDK ignores it while idle
-            //    but REQUIRES it when a turn is running or still settling right after
-            //    agent return; without it the message is rejected as busy.
-            //  - `shouldSteer` (echo label + steer tracking) = requested OR inferred
-            //    busy-room send.
-            //  - seed `_rootState().turnId` for a fresh (non-steer) turn so the agent's
-            //    reply chunks/done have a target; restore it if the handoff fails.
-            // The APP owns the steer-vs-followUp semantic switch (design 01M14T6J5W):
-            // pass its chosen streamingBehavior straight through to pi. The extension does
-            // NOT force steer over a followUp anymore. `shouldSteer` below is now only
-            // BOOKKEEPING (turn-seeding + image-preview defer), not the delivery verb.
-            const requestedSteer = opts.streamingBehavior === "steer";
-            // Authoritative busy signal from pi's OWN state (AgentSession.isStreaming),
-            // correct across subagent lifecycles (turnId/working stick busy after a
-            // subagent run).
-            const streaming = _pi?.isStreaming === true;
-            const shouldSteer = requestedSteer || streaming;
-            const msg = {
-                type: "user_message",
-                id: opts.id ?? _rootState().turnId ?? String(Date.now()),
-                text: message,
-                images: opts.images,
-            };
-            // Image path mirrors the stock handler (SDK handoff WITH images + echo).
-            if (msg.images && msg.images.length > 0) {
-                await _deliverImageUserMessage(sender, msg, shouldSteer);
-                return;
-            }
-            const previousTurnId = _rootState().turnId;
-            const seededTurnId = !shouldSteer || _rootState().turnId === null;
-            if (seededTurnId)
-                _rootState().turnId = msg.id;
-            // PASS-THROUGH the app's verb (design 01M14T6J5W). pi's prompt(): idle
-            // ignores streamingBehavior (fresh run); streaming+"steer" -> _queueSteer;
-            // streaming+"followUp" -> _queueFollowUp; streaming+none -> throws. The
-            // `?? (streaming ? "steer" : undefined)` is a MECHANICAL safety net (not
-            // semantic inference) so a racing/old client's no-behavior busy send
-            // defensively steers instead of throwing (keeps plan/43).
-            const wake = _wakeAgent(message, "app rpc prompt", opts.streamingBehavior === "followUp"
-                ? "followUp"
-                : opts.streamingBehavior === "steer" || streaming
-                    ? "steer"
-                    : undefined);
-            if (!wake.ok) {
-                if (seededTurnId)
-                    _rootState().turnId = previousTurnId;
-                throw new Error(wake.detail);
-            }
-        },
-        steer: async (message) => {
-            const wake = _wakeAgent(message, "app rpc steer", "steer");
-            if (!wake.ok)
-                throw new Error(wake.detail);
-        },
-        followUp: async (message) => {
-            const wake = _wakeAgent(message, "app rpc follow_up", "followUp");
-            if (!wake.ok)
-                throw new Error(wake.detail);
-        },
-        abort: async () => {
-            if (!_abortCurrentTurn())
-                throw new Error("no active turn to abort");
-        },
-        setModel: async (provider, modelId) => {
-            if (!_pi)
-                throw new Error("agent session not bound");
-            const actionCtx = (_lastEventCtx ?? _lastCtx);
-            const reg = actionCtx?.modelRegistry ?? ensureModelRegistry(actionCtx);
-            reg.refresh();
-            const model = reg.find(provider, modelId);
-            if (!model)
-                throw new Error(`model "${provider}/${modelId}" not in registry`);
-            // Route via the minimal ActionPi view (matches handleModelSet): the
-            // registry's `find` returns the minimal SdkModelLike, structurally fine
-            // for setModel at runtime.
-            // SAFETY: _pi (checked non-null above) is the concrete AgentSession; its
-            // setModel accepts the minimal SdkModelLike the registry's find() returns,
-            // matching handleModelSet's ActionPi view.
-            const ok = await _pi.setModel(model);
-            if (!ok)
-                throw new Error("no auth configured for this model");
-            _persistModelDefault(model.provider, model.id); // survive restart, mirrors stock model_set
-            return wireFromModel(model);
-        },
-        setThinkingLevel: async (level) => {
-            if (!_pi)
-                throw new Error("agent session not bound");
-            _pi.setThinkingLevel(level);
-        },
-        getAvailableModels: async () => {
-            const actionCtx = (_lastEventCtx ?? _lastCtx);
-            const reg = actionCtx?.modelRegistry ?? ensureModelRegistry(actionCtx);
-            reg.refresh();
-            const models = reg.getAvailable().map(wireFromModel);
-            const current = actionCtx?.getModel?.();
-            return { models, current: current ? wireFromModel(current) : undefined };
-        },
-        compact: async (customInstructions) => {
-            const actionCtx = (_lastEventCtx ?? _lastCtx);
-            if (!actionCtx?.compact)
-                throw new Error("compact unavailable (no active session ctx)");
-            actionCtx.compact(customInstructions ? { customInstructions } : undefined);
-            return {};
-        },
-        newSession: async () => {
-            const actionCtx = (_lastEventCtx ?? _lastCtx);
-            if (!actionCtx?.newSession) {
-                throw new Error("new_session unavailable (no command ctx)");
-            }
-            await actionCtx.newSession({ withSession: async () => { } });
-            // Restamp the session clock (parity with the retired stock session_new):
-            // session_sync_end carries it so the app can detect the pi restart.
-            _resetSessionForNew();
-            return { cancelled: false };
-        },
-        clearQueue: async () => {
-            if (!_pi)
-                throw new Error("agent session not bound");
-            // SAFETY: _pi (checked non-null above) is the concrete AgentSession,
-            // which implements clearQueue(); the public ExtensionAPI type omits it.
-            return _pi.clearQueue();
-        },
-        getEntries: async (since) => {
-            // Native pi get_entries: the app reconstructs the transcript itself from
-            // the raw entry log (each message entry carries an AgentMessage). `since`
-            // slices to entries AFTER that id (delta cursor); leafId is the cursor to
-            // resume from next time. The extension does NOT replay these — see the app's
-            // SessionState.applyEntries (design 01M15FMQ).
-            const sm = _rootState().sessionManager;
-            if (!sm)
-                return { entries: [], leafId: null };
-            const all = sm.getEntries();
-            const sliced = typeof since === "string"
-                ? (() => {
-                    const i = all.findIndex((e) => e.id === since);
-                    return i === -1 ? all : all.slice(i + 1);
-                })()
-                : all;
-            return { entries: sliced, leafId: sm.getLeafId() };
-        },
-    };
+    const handlers = createRpcHandlers(rpcDeps, sender);
     void dispatchRpcCommand(frame, handlers)
         .then((resp) => {
         // Envelope-native ONLY: no stock fallback. An unhandled rpc type is
@@ -1481,16 +924,99 @@ function _routeUnBienPlaneFrom(sender, env) {
         envLog(`session_sync(ub): panels=${panels.length} + ui (transcript is the app's get_entries rpc)`);
         // Terminator/ack on the ub plane; carries the session clock so the app can
         // detect a pi restart. `truncated`/`limit` are gone (a replay concern;
-        // get_entries is unbounded / since-delta).
+        // get_entries is unbounded / since-delta). `session_name` (pre-release
+        // 2026-09-18): the NAME PULL — heals a missed session_info_changed push
+        // (an iOS backgrounded socket misses live frames; the relay's stored meta
+        // is stale until our next hello, so reconnects can't carry it either).
+        // session_sync is issued on EVERY open + reconnect, so the name heals on
+        // every natural cycle. Old apps ignore the field; old extensions omit it.
+        //
+        // SOURCE = the room's DISPLAY name (myRoomMeta.name), NOT deps.sessionName:
+        // the latter is `_sessionName`, which `_cmdJoin` sets to the mesh session
+        // id LOCAL_SESSION_NAME ("local"). Sending that here clobbered the tile
+        // label with "local" on every reconnect (the flaky-name bug) — the
+        // non-live pull disagreed with the live session_info push. myRoomMeta.name
+        // is the same value pair_ok sends (deps.displayName) and tracks live
+        // renames (session_info_changed updates it), so pull == push now.
+        const displayName = deps.myRoomMeta?.name;
+        // Fork auto-nav: a fork-born session's FIRST sync echoes the app's
+        // originating fork request id (design: fork switch). take = read+unlink,
+        // so it fires once (the app navigates on first receipt; later reconnects
+        // must not re-jump). Keyed by the session id, so it survives the extension
+        // module re-eval that ctx.fork triggers.
+        const forkSm = _rootState().sessionManager;
+        const forkedFromReq = forkSm && typeof forkSm.getSessionDir === "function"
+            ? takeForkLink(forkSm.getSessionDir(), forkSm.getSessionId())
+            : undefined;
         sender.sendEnvelope({
             ub: {
                 type: "session_sync_end",
                 ...(typeof f.id === "string" ? { in_reply_to: f.id } : {}),
                 session_started_at: _sessionStartedAt ?? 0,
+                ...(displayName ? { session_name: displayName } : {}),
+                ...(forkedFromReq ? { forked_from_req: forkedFromReq } : {}),
             },
         });
         return;
     }
+    if (type === "terminate") {
+        // app->ext: kill THIS session. Root room only — a child room's terminate
+        // is handled by the child-room router in subagent_rooms (never reaches
+        // here; that room's conn dispatches its own ub frames). Gate on local
+        // config; the app confirms + shows red before sending.
+        if (!effectiveAllowRemoteTerminate(loadLocalConfig(process.cwd()))) {
+            envLog("terminate(ub): remote terminate disabled on this machine");
+            return;
+        }
+        envLog(`terminate(ub): graceful host shutdown requested${typeof frame.reason === "string" ? ` (${String(frame.reason)})` : ""}`);
+        _safeNotify("Terminated from the app", "warning");
+        try {
+            // ctx.shutdown() IS the /quit equivalent — pi's own source lists
+            // "extension shutdown()" alongside Ctrl+D / /quit (interactive-mode.js
+            // 3229: same graceful this.shutdown(): drain input, ui.stop() restores
+            // cooked mode + cursor, extension disposal, resume hint, exit). It sits
+            // DIRECTLY on the event ctx (ExtensionContext.shutdown — there is no
+            // ctx.actions sub-object; the first two attempts failed exactly there).
+            //
+            // MID-TURN DEFERRAL: the interactive handler fires immediately only when
+            // idle; otherwise it sets `shutdownRequested` and waits for
+            // `agent_settled` — which never arrives when nothing is running. So
+            // abort() FIRST: aborting a running turn forces the settle that
+            // re-checks the flag; on an idle session abort is a no-op and the
+            // idle fast-path fires directly.
+            //
+            // NO process.exit fallback, ever: a raw exit leaves the TTY in raw
+            // mode (keypresses echo escape codes until `stty sane`). No live ctx =>
+            // log loudly and stay up; the user quits on the machine.
+            const ctx = _liveCtx();
+            if (ctx?.shutdown) {
+                ctx.abort?.();
+                ctx.shutdown();
+            }
+            else {
+                envLog("terminate(ub): no live ctx — refusing raw exit (would leave the terminal in raw mode); staying up");
+            }
+        }
+        catch (err) {
+            envLog(`terminate(ub) error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    if (type === "close_child_room") {
+        // app->ext(PARENT): permanently close one of MY child rooms (done-subagent
+        // removal — the room lingers by design otherwise). Tombstone + dispose in
+        // subagent_rooms; the relay fires room_ended when the last conn drops.
+        if (!effectiveAllowRemoteTerminate(loadLocalConfig(process.cwd()))) {
+            envLog("close_child_room(ub): remote terminate disabled on this machine");
+            return;
+        }
+        const roomId = frame.room_id;
+        if (typeof roomId !== "string" || roomId.length === 0)
+            return;
+        const closed = _subagentRooms?.closeChildRoom(roomId) ?? false;
+        envLog(`close_child_room(ub): room=${roomId.slice(0, 8)} closed=${closed}`);
+        return;
+    }
     if (type === "session_launch") {
         const f = frame;
         const cwd = _expandTilde(typeof f.cwd === "string" && f.cwd.length > 0 ? f.cwd : process.cwd());
@@ -1498,6 +1024,16 @@ function _routeUnBienPlaneFrom(sender, env) {
             envLog("session_launch(ub): remote launch disabled on this machine");
             return;
         }
+        // Directory allow-list (design 01M211VW9), read FRESH each request.
+        if (!launchDirAllowed(cwd, loadConfig().launch?.dirs)) {
+            envLog("session_launch(ub): cwd not in launch.dirs allow-list");
+            sender.send({
+                type: "error",
+                code: "permission_denied",
+                message: "Remote launch not permitted for this directory",
+            });
+            return;
+        }
         // Backend is a MACHINE config choice (pick-one via launch.backend), not
         // app-chosen; rpc is a fast-follow so only tmux|herdr resolve here.
         const backend = loadConfig().launch?.backend === "herdr" ? "herdr" : "tmux";
@@ -1506,67 +1042,42 @@ function _routeUnBienPlaneFrom(sender, env) {
             envLog(`session_launch(ub) error: ${launchError}`);
         return;
     }
-}
-/** Broadcast for the extension_ui bridge. The bridge only ever emits
- *  `extension_ui_request`, sent ENVELOPE-ONLY as a `{rpc}` frame (the wire
- *  shape mirrors the SDK rpc contract 1:1). No stock fallback. */
-function _uiBroadcast(msg) {
-    if (msg.type === "extension_ui_request")
-        _broadcastEnvelope({ rpc: msg });
-}
-/** Broadcast for the panel bridge. The bridge only ever emits `panel_update`,
- *  forwarded ENVELOPE-ONLY as `{evt:{channel:"panel", data}}` (the {evt} plane);
- *  the app folds it into its panel store. No stock fallback. */
-function _panelBroadcast(msg) {
-    if (msg.type === "panel_update")
-        _broadcastEnvelope({ evt: { channel: "panel", data: msg } });
-}
-/** Fan an rpc-envelope frame out to every attached peer (base64 ct via each
- *  channel) — the single owner-fanout path for `{ rpc | evt }` messages. */
-function _broadcastEnvelope(env) {
-    {
-        // Observability only (not a route gate): watch the {rpc|evt} wire during
-        // e2e bring-up. Frame type only — payloads can be large / carry images.
-        const kind = env.rpc
-            ? `rpc:${env.rpc.type ?? "?"}`
-            : `evt:${env.evt?.channel ?? "?"}`;
-        envLog(`envelope -> ${_activePeers.size} peer(s): ${kind}`);
-    }
-    for (const ch of _activePeers.values()) {
-        try {
-            ch.sendEnvelope(env);
+    if (type === "session_fork" || type === "session_navigate") {
+        // app->ext: fork a NEW session / branch IN PLACE from a conversation entry.
+        // ctx.fork / ctx.navigateTree live ONLY on the command ctx, so we can't act
+        // here (this is the peer-channel dispatch, not a command). Self-dispatch the
+        // registered `/unbien fork|branch` command via sendUserMessage — pi runs it
+        // with a real ExtensionCommandContext. No stashed ctx, no startup bootstrap:
+        // the command ctx lives exactly as long as the op that needs it. Not gated
+        // beyond being paired — these are no more privileged than a prompt on this
+        // same room (which the app can already send).
+        const f = frame;
+        const entryId = typeof f.entry_id === "string" ? f.entry_id : "";
+        if (!entryId) {
+            envLog(`${String(type)}(ub): missing entry_id — ignored`);
+            return;
         }
-        catch {
-            /* best-effort per channel */
+        if (type === "session_fork") {
+            // Thread the request id (reqId) so the new session can echo it back as
+            // forked_from_req on its first sync — the app's auto-nav correlation.
+            // Order: `<entryId> <reqId> [pos]` (see _cmdFork's parse).
+            const reqId = typeof f.id === "string" ? f.id : "";
+            const posArg = f.position === "at" || f.position === "before" ? ` ${f.position}` : "";
+            const reqArg = reqId ? ` ${reqId}` : "";
+            envLog(`session_fork(ub): entry=${entryId.slice(0, 8)}${posArg}`);
+            _pi?.sendUserMessage(`/unbien fork ${entryId}${reqArg}${posArg}`, {
+                deliverAs: "followUp",
+                expandPromptTemplates: true,
+            });
+        }
+        else {
+            envLog(`session_navigate(ub): entry=${entryId.slice(0, 8)}`);
+            _pi?.sendUserMessage(`/unbien branch ${entryId}`, {
+                deliverAs: "followUp",
+                expandPromptTemplates: true,
+            });
         }
-    }
-}
-/**
- * Adds an owner's channel to `_activePeers`. Also updates the UX hint
- * `_peerShort` (last-attached shortid) so the footer + status can pick
- * a representative device when only one is connected.
- */
-function _attachPeerChannel(appPeerId, channel) {
-    _activePeers.set(appPeerId, channel);
-    _peerShort = appPeerId.slice(0, 8);
-}
-/** Detaches a single owner's channel + removes it from the map. Used by
- *  `_onPeerDisconnect`, `_cmdRevoke`, and the SelfRevoke callback. */
-function _detachPeerChannel(appPeerId) {
-    const ch = _activePeers.get(appPeerId);
-    if (!ch)
         return;
-    try {
-        ch.detach();
-    }
-    catch {
-        /* best-effort */
-    }
-    _activePeers.delete(appPeerId);
-    if (_peerShort === appPeerId.slice(0, 8)) {
-        // Pick a different remaining peer for the UX hint, or clear when none.
-        const next = _activePeers.keys().next().value;
-        _peerShort = next ? next.slice(0, 8) : "";
     }
 }
 // ── Display-name helpers ──────────────────────────────────────────────────────
@@ -1588,12 +1099,14 @@ function _detachPeerChannel(appPeerId) {
  * inline at three different sites (pair_ok, room_meta, QR URI); this
  * helper consolidates them and lifts the user's configured name above
  * the raw cwd path.
+ *
+ * A session-scoped name (pi `-n`, set by the remote launcher) slots in just
+ * below the broker-assigned mesh name — see `resolveAgentName`.
  */
 function _displayName(cwd) {
     if (_meshNode)
         return _meshNode.name();
-    const local = loadLocalConfig(cwd);
-    return local.agent_name || defaultAgentName(cwd);
+    return resolveAgentName(cwd, piSessionName(_pi));
 }
 function _reportRevocationByFingerprint(canonicalOwnerPubkey) {
     const fingerprint = _runtimeOwnerFingerprint(canonicalOwnerPubkey);
@@ -1609,299 +1122,10 @@ function _revokeActiveOwnerRuntime(canonicalOwnerPubkey) {
     if (!_activePeers.has(canonicalOwnerPubkey))
         return;
     _refreshPairingsCache();
-    _detachPeerChannel(canonicalOwnerPubkey);
+    _detachPeerChannel(relayDeps, canonicalOwnerPubkey);
     _refreshFooter();
     _reportRevocationByFingerprint(canonicalOwnerPubkey);
 }
-// ── Transition helpers ────────────────────────────────────────────────────────
-/**
- * Full teardown: stop listener, detach channel, close relay → idle.
- */
-function _goIdle() {
-    _rootLifecycleGeneration += 1;
-    _relayLifecycleGeneration += 1;
-    // Cancel any pending reconnect attempt. Critical: /unbien stop must
-    // win the race against a scheduled reconnect.
-    if (_reconnectTimer !== null) {
-        clearTimeout(_reconnectTimer);
-        _reconnectTimer = null;
-    }
-    _reconnectAttempt = 0;
-    _stopAutoListener?.();
-    _stopAutoListener = null;
-    // Tear down every per-owner channel and clear the map.
-    for (const ch of _activePeers.values()) {
-        try {
-            ch.detach();
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-    _activePeers.clear();
-    _peerShort = "";
-    _rootState().turnId = null;
-    _pendingReceivedImagePreviews.length = 0;
-    // Invalidate async producers and bridge ownership before closing the host
-    // Relay. A synchronous/delayed close callback must observe stale identity.
-    const producer = _selfRevoke;
-    _selfRevoke = null;
-    _selfRevokeEpoch += 1;
-    _selfRevokeTopologyReadyEpoch = -1;
-    _selfRevokeTopology = null;
-    producer?.stop();
-    _meshNode?.detachBridge();
-    const relay = _relay;
-    _relay = null;
-    _relayUrl = null;
-    relay?.close();
-    // Preserve _sessionStartedAt + _messageBuffer across stop/start cycles.
-    // The Pi agent session outlives the relay connection — `message_end` keeps
-    // firing for terminal turns even while idle, and the buffer must survive
-    // so those turns appear in the next session_sync. Only a Pi process
-    // restart resets these (init-time values).
-    _state = "idle";
-    _refreshFooter();
-    _emitRelayState(); // → disconnected
-}
-/**
- * Called when the relay WS closes unexpectedly (network drop, relay restart,
- * etc.). Does a **partial** teardown — keeps `_sessionStartedAt`, `_messageBuffer`,
- * `_relayUrl`, `_cachedEd25519`, `_peerShort` so the session can resume on
- * reconnect — and schedules an `_attemptReconnect`.
- *
- * Peer (app) reconnect after a successful relay reconnect is handled by the
- * existing auto-listener via `peers.json` lookup, so we don't need to track
- * the prior peer here; we just go back to `started` and wait.
- */
-function _onRelayClose(closedRelay) {
-    if (_relay !== closedRelay)
-        return; // delayed close from a replaced Relay
-    if (_state === "idle")
-        return; // already torn down (e.g. /unbien stop)
-    _relayLifecycleGeneration += 1;
-    _stopAutoListener?.();
-    _stopAutoListener = null;
-    // Detach every per-owner channel — relay is gone, none can route. The
-    // auto-listener re-attaches owners after `_attemptReconnect` succeeds
-    // (via the same known-peer + pair_request paths used on first connect).
-    for (const ch of _activePeers.values()) {
-        try {
-            ch.detach();
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-    _activePeers.clear();
-    _peerShort = "";
-    _rootState().turnId = null;
-    _relay = null; // _relayUrl preserved for retry
-    // Cross-PC routing relies on _relay; bring it down. Will be re-instated
-    // by _attemptReconnect on success.
-    _meshNode?.detachBridge();
-    _state = "started";
-    _refreshFooter();
-    _emitRelayState(); // → reconnecting
-    const reconnectUrl = _relayUrl;
-    if (reconnectUrl) {
-        _scheduleReconnect(_relayLifecycleGeneration, reconnectUrl);
-    }
-}
-function _isCurrentReconnect(lifecycleGeneration, url) {
-    return (lifecycleGeneration === _relayLifecycleGeneration &&
-        _state === "started" &&
-        _relay === null &&
-        _relayUrl === url);
-}
-function _scheduleReconnect(lifecycleGeneration, url) {
-    if (_reconnectTimer !== null)
-        return; // already scheduled
-    if (!_cachedEd25519)
-        return; // can't reconnect without the cached identity
-    if (!_isCurrentReconnect(lifecycleGeneration, url))
-        return;
-    const idx = Math.min(_reconnectAttempt, RECONNECT_BACKOFFS_MS.length - 1);
-    const delay = RECONNECT_BACKOFFS_MS[idx];
-    _reconnectAttempt += 1;
-    // The timer belongs to the lifecycle that scheduled it. Re-check that exact
-    // generation + URL before constructing a candidate so a dequeued old timer
-    // cannot act on a newer stop/start lifecycle.
-    _reconnectTimer = setTimeout(() => {
-        _reconnectTimer = null;
-        if (!_isCurrentReconnect(lifecycleGeneration, url))
-            return;
-        void _attemptReconnect(lifecycleGeneration, url);
-    }, delay);
-}
-async function _attemptReconnect(lifecycleGeneration, url) {
-    if (!_cachedEd25519)
-        return;
-    if (!_isCurrentReconnect(lifecycleGeneration, url))
-        return;
-    const edKp = _cachedEd25519;
-    // _relayUrl is stored in canonical http(s):// form — convert at the
-    // WS boundary, same as _cmdStart.
-    const relay = new RelayClient(toWebSocketUrl(url), edKp);
-    try {
-        // Replay the same room identity from _cmdStart. Without this the relay
-        // would log this WS as a default-room peer and the app would see a
-        // phantom "legacy session" appear (regression of plano 17 + 18).
-        await relay.connect({
-            ...(_myRoomId ? { roomId: _myRoomId } : {}),
-            ...(_myRoomMeta ? { roomMeta: _myRoomMeta } : {}),
-        });
-    }
-    catch {
-        // A reconnect candidate stays local until publication; every rejected
-        // candidate is deterministically closed before stale-return or retry.
-        try {
-            relay.close();
-        }
-        catch {
-            /* best-effort rejected candidate cleanup */
-        }
-        if (!_isCurrentReconnect(lifecycleGeneration, url))
-            return;
-        _scheduleReconnect(lifecycleGeneration, url);
-        return;
-    }
-    if (!_isCurrentReconnect(lifecycleGeneration, url)) {
-        try {
-            relay.close();
-        }
-        catch {
-            /* best-effort stale candidate cleanup */
-        }
-        return;
-    }
-    _relay = relay;
-    _reconnectAttempt = 0;
-    relay.on("close", () => _onRelayClose(relay));
-    _stopAutoListener = _installAutoListener(relay);
-    // Plan/25 Wave B/C: relay is back; bring cross-PC routing back online.
-    _attachBridgeIfReady();
-    // _state stays "started"; peer reconnect (if previously paired) flows
-    // through _installAutoListener → _findKnownPeer → _promoteToPaired
-    // automatically when the app sends any inner.
-    _emitRelayState();
-}
-// ── Relay state event + transparent control channel (Cockpit toggle) ─────────
-/** Current relay connectivity, derived from `_state` + `_relay`. */
-function _relayStatus() {
-    if (_getState() === "idle")
-        return "disconnected";
-    return _relay ? "connected" : "reconnecting";
-}
-/**
- * Emit the `un-bien:relay-state` custom message so an RPC client (Cockpit)
- * can render a relay on/off indicator. Pure data (`display:false`) — never
- * shown in the transcript. De-duped on the connectivity value; pass
- * `force=true` to answer an explicit `relay:status` query regardless.
- */
-function _emitRelayState(force = false) {
-    const status = _relayStatus();
-    if (!force && status === _lastRelayStatus)
-        return;
-    _lastRelayStatus = status;
-    // This can run inside a WebSocket 'close' callback (via _onRelayClose). After a
-    // session replacement (newSession/fork/switchSession/reload) the module-level
-    // `_pi` is stale, and `assertActive` throws synchronously inside `sendMessage`.
-    // An uncaught throw from a WS event callback becomes a process-level
-    // uncaughtException and exits pi. Swallow it here: the next relay-state
-    // change re-emits, so connectivity is eventually consistent. See issue #55.
-    try {
-        _pi?.sendMessage({
-            customType: "un-bien:relay-state",
-            content: `Relay ${status}`,
-            details: {
-                status,
-                connected: status === "connected",
-                ...(_relayUrl ? { relayUrl: _relayUrl } : {}),
-                ...(_myRoomId ? { room: _myRoomId } : {}),
-            },
-            display: false,
-        });
-    }
-    catch {
-        // _pi stale (session replaced) or extension runtime not yet bound.
-    }
-}
-/** Minimal ctx for relay start/stop driven by a control message (no command
- *  ctx is available in the `input` hook). cwd matches the daemon's launch dir,
- *  so the derived relay room is identical to the one `_cmdStart` first used. */
-function _controlCtx() {
-    // SAFETY: _headlessUi() implements every ui method the relay start/stop path
-    // actually calls; the notify-forwarding shim is structurally narrower than the
-    // full ExtensionContext["ui"] but complete for this headless control path.
-    return {
-        ui: _headlessUi(),
-        cwd: process.cwd(),
-    };
-}
-/**
- * `ui.notify` for headless contexts (daemon auto-init + control channel). There
- * is no TUI, and the RPC client (Cockpit) already gets everything it needs via
- * structured events (`un-bien:relay-state`, `un-bien:name-assigned`,
- * room_meta) — so routine INFO chatter would just pollute the client's captured
- * stderr. We drop info and forward only warnings/errors (kept for the
- * supervisor's journal / genuine failures). The interactive Pi keeps its normal
- * footer/notify path — this only affects headless ctxs.
- */
-function _headlessUi() {
-    return {
-        notify: (msg, type) => {
-            if (type === "warning" || type === "error")
-                process.stderr.write(`${msg}\n`);
-        },
-    };
-}
-/**
- * Handle a transparent control command from an RPC client (Cockpit), received
- * as a `CTRL_PREFIX`-tagged input the `input` hook swallowed. Toggles the relay
- * WITHOUT leaving the local mesh (relay-only: `_cmdStart` up / `_goIdle` down),
- * then emits the fresh state. `relay:status` just re-emits (no change) so the
- * client can sync its button after (re)attaching to the RPC stream.
- */
-export async function _handleControl(cmd) {
-    // `rename:<new-name>` carries an argument, so it's matched before the
-    // fixed-verb switch. Renames the agent live (broker re-register + relay room
-    // swap) WITHOUT restarting the process or losing the SDK session.
-    if (cmd.startsWith("rename:")) {
-        await _renameAgent(cmd.slice("rename:".length).trim());
-        return;
-    }
-    switch (cmd) {
-        case "relay:on":
-            if (_getState() === "idle")
-                await _cmdStart(_controlCtx());
-            _emitRelayState(true);
-            return;
-        case "relay:off":
-            if (_getState() === "idle") {
-                _rootLifecycleGeneration += 1;
-                _relayLifecycleGeneration += 1;
-            }
-            else
-                _goIdle();
-            _emitRelayState(true);
-            return;
-        case "relay:toggle":
-            if (_getState() === "idle")
-                await _cmdStart(_controlCtx());
-            else
-                _goIdle();
-            _emitRelayState(true);
-            return;
-        case "relay:status":
-            _emitRelayState(true);
-            return;
-        default:
-            // Unknown control verb — ignore (forward-compat: a newer client may send
-            // verbs an older extension doesn't know).
-            return;
-    }
-}
 /**
  * Rename the agent LIVE (plan/38/41), without restarting the process or losing
  * the SDK session/conversation. Touches two layers:
@@ -1931,7 +1155,7 @@ async function _renameAgent(newName) {
     // clean; bring it back up after with the new name.
     const wasStarted = _getState() !== "idle";
     if (wasStarted)
-        _goIdle();
+        _goIdle(relayDeps);
     let assigned = newName;
     try {
         assigned = await _meshNode.rename(newName); // broker soft rejoin
@@ -1940,7 +1164,7 @@ async function _renameAgent(newName) {
         ctx.ui.notify(`[un-bien] rename failed: ${String(err)}`, "error");
     }
     if (wasStarted && !_disposed)
-        await _cmdStart(ctx); // relay back up → roomIdFor(cwd, assigned)
+        await _cmdStart(deps, ctx); // relay back up → roomIdFor(cwd, assigned)
     _pi?.sendMessage({
         customType: "un-bien:name-assigned",
         content: assigned === newName
@@ -1950,338 +1174,48 @@ async function _renameAgent(newName) {
         display: false,
     });
 }
-/**
- * Per-owner disconnect callback. Fires when one specific owner's channel
- * detaches (e.g. relay told us the peer is gone). Other owners' channels
- * keep running — relay stays "started".
- *
- * Exported so tests can trigger the disconnect path for a specific peer.
- *
- * Backward-compat: a no-arg call (legacy tests / pre-W2D callers) falls
- * back to detaching the most recently attached peer, mirroring the old
- * singleton semantics.
- */
-export function _onPeerDisconnect(appPeerId) {
-    if (_state === "idle")
-        return;
-    const target = appPeerId ?? [..._activePeers.keys()].pop();
-    if (!target)
-        return;
-    if (!_activePeers.has(target))
-        return;
-    _detachPeerChannel(target);
-    if (_anyPeerActive()) {
-        // Other owners still attached — keep _rootState().turnId so they continue
-        // seeing the in-flight agent stream.
-        _refreshFooter();
-        return;
+// ── Extension factory (default export) ───────────────────────────────────────
+// One-shot flag for the turn-ctx surface probe (see the turn_start handler).
+let _turnCtxProbed = false;
+/** TARGETED, PROXY-SAFE ctx probe: the ctx objects carry guarded getters
+ * (throwing on invalid/stale access — see _ctxUi), so full reflection
+ * under-reports or throws. Access each interesting member individually,
+ * catching per property. Reflection-only: never invokes anything. */
+function _probeCtx(label, ctx) {
+    const names = [
+        "fork",
+        "navigateTree",
+        "newSession",
+        "switchSession",
+        "compact",
+        "shutdown",
+        "sendMessage",
+        "prompt",
+        "clearQueue",
+    ];
+    const parts = [];
+    // SAFETY: per-property try/catch — a throwing getter (guarded proxy)
+    // reports "throws" instead of failing the whole probe.
+    const target = ctx;
+    for (const name of names) {
+        try {
+            const v = target[name];
+            parts.push(`${name}=${typeof v === "function" ? "fn" : String(v)}`);
+        }
+        catch {
+            parts.push(`${name}=throws`);
+        }
     }
-    // No owner left. Conservatively clear the turn so the next pair_request
-    // starts cleanly.
-    _rootState().turnId = null;
-    _refreshFooter();
-    _safeNotify("[un-bien] All app peers disconnected, listening for reconnect", "info");
-    // Auto-listener stays up — same listener catches the reconnect on any peer.
+    envLog(`${label} targeted: ${parts.join(" ")}`);
 }
-/**
- * Attaches a new owner channel to the multi-owner set. Replaces the
- * pre-W2D singleton `_promoteToPaired` which set `_state = "paired"` and
- * a single `_peerChannel`. The relay state remains `started`; pairing
- * status is derived from `_activePeers.size`.
- *
- * Idempotent for the same `appPeerId` (re-attaching tears down the prior
- * channel and installs a fresh one — covers reconnect from the same
- * device without leaking listeners).
- */
-function _attachOwner(relay, appPeerId, peerName, firstInner) {
-    const peerShort = appPeerId.slice(0, 8);
-    // Drop any stale channel for this owner before re-attaching.
-    if (_activePeers.has(appPeerId))
-        _detachPeerChannel(appPeerId);
-    // Prefer always-fresh session_start ctx for async relay routing — `_lastCtx`
-    // is a captured command ctx that goes stale after session replacement (#55).
-    const channel = new PlainPeerChannel(relay, appPeerId, _myRoomId ?? undefined, (msg) => _routeClientMessageFrom(channel, msg, _liveCtx() ?? _noopCtx), () => _onPeerDisconnect(appPeerId), (env) => env.ub === undefined
-        ? _routeRpcCommandFrom(channel, env)
-        : _routeUnBienPlaneFrom(channel, env), () => _rootState().sessionManager?.getSessionId() ??
-        _rootSessionId ??
-        undefined);
-    _attachPeerChannel(appPeerId, channel);
-    // Envelope-native capability handshake: advertise caps up front so the app can
-    // enable the {rpc|evt} route + suppress stock before any session content
-    // arrives. Additive to the stock session_history caps (parity transition).
-    const _sid = _rootState().sessionManager?.getSessionId();
-    channel.sendEnvelope(helloEnvelope(_capabilities(), _sid));
-    envLog(`attach: peer=${appPeerId.slice(0, 8)} hello sent (caps + sessionId=${_sid ?? "?"}); active=${_activePeers.size}`);
-    // Reconstruction (transcript + panels + extension_ui) is request-driven: the
-    // app issues session_sync — on fresh open AND on relay reconnect — and the
-    // handler in _routeUnBienPlaneFrom replays all of it. Re-sync is idempotent
-    // (stable identify ids + ns/id panel merge), so nothing is replayed
-    // proactively here.
-    _refreshFooter();
-    _safeNotify(`[un-bien] Owner attached: peer=${peerShort}, name=${peerName} ` +
-        `(${_activePeers.size} active)`, "info");
-    if (firstInner) {
-        // The PlainPeerChannel listener fired on the same line that triggered
-        // attachment in some flows; we route explicitly here too to ensure the
-        // inner reaches the handler exactly once.
-        void firstInner;
-    }
-    return channel;
-}
-// ── Auto-listener ─────────────────────────────────────────────────────────────
-//
-// Installed while in 'started' state. Decodes the outer envelope as
-// base64(JSON) and dispatches per sender peer_id:
-//   • Sender already in `_activePeers` → ignored here (the per-owner
-//     PlainPeerChannel listens on the same relay event and handles its own
-//     traffic via its `remotePeerId` filter)
-//   • `pair_request` from a new peer → validate token, persist peer, send
-//     pair_ok/pair_error, attach a new channel
-//   • Non-pair message from a known peer (peers.json) without an active
-//     channel yet → attach + route the inner (reconnect path)
-//   • Anything else (unknown peer + non-pair) → emit `error: unknown_peer`
-function _installAutoListener(relay) {
-    const listenerGeneration = _relayLifecycleGeneration;
-    const hasListenerAuthority = () => !_disposed &&
-        _state === "started" &&
-        _relay === relay &&
-        _relayLifecycleGeneration === listenerGeneration;
-    const onMsg = async (line) => {
-        let outer;
-        try {
-            outer = JSON.parse(line);
-        }
-        catch {
-            return;
-        }
-        if (!outer.peer || !outer.ct)
-            return;
-        if (!hasListenerAuthority())
-            return;
-        // Already-attached owners: their PlainPeerChannel handles routing.
-        if (_activePeers.has(outer.peer))
-            return;
-        // Decode inner envelope (base64 JSON)
-        let inner;
-        try {
-            const plaintext = Buffer.from(outer.ct, "base64").toString("utf8");
-            const parsed = JSON.parse(plaintext);
-            if (!parsed ||
-                typeof parsed !== "object" ||
-                typeof parsed.type !== "string")
-                return;
-            inner = parsed;
-        }
-        catch {
-            return;
-        }
-        const appPeerId = outer.peer;
-        if (inner.type === "pair_request") {
-            await _handlePairRequest(relay, appPeerId, inner, hasListenerAuthority);
-            return;
-        }
-        // Reconnect path: known peer (peers.json) without an active channel
-        // sends a non-pair message → attach + route through the new channel.
-        // See pairing.md §Reconexão.
-        const known = await _findKnownPeer(appPeerId);
-        if (!hasListenerAuthority())
-            return;
-        if (known) {
-            const channel = _attachOwner(relay, appPeerId, known.name);
-            // The channel listener didn't see the line that triggered the attach, so
-            // route it explicitly — MIRRORING the channel's own dispatch (peer_channel
-            // _onLine): a real-typed envelope ("rpc"/"evt"/"ub", legacy "env") or a
-            // bare rpc/evt/ub body goes to the envelope dispatcher, a stock
-            // ClientMessage to the stock switch. Everything is on the envelope proto
-            // now, so the first message is normally the ub session_sync (or the rpc
-            // get_entries) — routing that through the stock switch dropped it. Use
-            // _liveCtx (session_start-fresh), not #55.
-            const innerObj = inner;
-            if (isEnvelopeFrame(innerObj)) {
-                {
-                    // SAFETY: isEnvelopeFrame confirmed rpc/evt/ub envelope keys are
-                    // present, so this ClientMessage is byte-compatible with EnvelopeMessage.
-                    const innerEnv = inner;
-                    if (innerEnv.ub === undefined)
-                        _routeRpcCommandFrom(channel, innerEnv);
-                    else
-                        _routeUnBienPlaneFrom(channel, innerEnv);
-                }
-            }
-            else {
-                _routeClientMessageFrom(channel, inner, _liveCtx() ?? _noopCtx);
-            }
-            return;
-        }
-        // Unknown peer with non-pair_request inner — signal so the app can react
-        // (peer was revoked / never paired). pair_request from unknown peer was
-        // already handled above as a legitimate path. We never log inner contents,
-        // only inner.type.
-        const errReply = {
-            type: "error",
-            code: "unknown_peer",
-            message: "Peer not paired — re-scan QR",
-        };
-        const errCt = Buffer.from(JSON.stringify(errReply)).toString("base64");
-        relay.send(JSON.stringify({ peer: appPeerId, ct: errCt }));
-    };
-    relay.on("message", onMsg);
-    return () => relay.off("message", onMsg);
-}
-/**
- * Plan/27 Wave A: lazily resolve the pi-extension package version from
- * disk so the `pair_ok.harness.version` field reflects what's actually
- * shipped. The lookup is best-effort — a parse failure (or running this
- * file out-of-tree) falls back to "0.0.0" which is still semver-valid
- * and the app tolerates it. Cached at module load.
- */
-function _readExtensionVersion() {
-    try {
-        const here = fileURLToPath(import.meta.url);
-        // dist/index.js → ../package.json. src/index.ts under tsx → also one level up.
-        const pkgPath = join(here, "..", "..", "package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-const _HARNESS = {
-    name: "Pi coding agent",
-    version: _readExtensionVersion(),
-};
-const _HOSTNAME = hostname();
-// un-bien capability handshake. PROTOCOL_VERSION bumps on a HARD (breaking)
-// wire change; the app gates UI on capability PRESENCE, not this number.
-const PROTOCOL_VERSION = 1;
-// Features this extension supports, advertised on attach (session_history) + pair_ok.
-// `remote_launch` is conditional (added only when local config opts in) — see
-// `_capabilities()`. Passive server->app extras (images/panels) are listed so
-// the app can also gate any future *controls* it grows for them.
-const _BASE_CAPABILITIES = [
-    "thinking",
-    "models",
-    "cancel",
-    "queued_messages",
-    "images",
-    "tool_result_images",
-    "panels",
-    "rpc_envelope",
-];
-/** The capability set to advertise right now (config-dependent bits included). */
-function _capabilities() {
-    const caps = [..._BASE_CAPABILITIES];
-    // `remote_launch` is advertised ONLY when the machine opts in via local
-    // config — single choke point so the advertised set and honored behavior
-    // can't drift. Read the session cwd's config (pi runs in the session cwd).
-    if (effectiveAllowRemoteLaunch(loadLocalConfig(process.cwd()))) {
-        caps.push("remote_launch");
-    }
-    return caps;
-}
-async function _handlePairRequest(relay, appPeerId, inner, hasListenerAuthority) {
-    const sendInner = (msg) => {
-        const ct = Buffer.from(JSON.stringify(msg)).toString("base64");
-        relay.send(JSON.stringify({ peer: appPeerId, ct }));
-    };
-    const sendError = (code, message) => {
-        sendInner({ type: "pair_error", in_reply_to: inner.id, code, message });
-    };
-    const status = qrSession.consumeToken(inner.token);
-    if (status !== "ok") {
-        const code = status === "expired"
-            ? "token_expired"
-            : status === "consumed"
-                ? "token_consumed"
-                : "token_unknown";
-        const msg = code === "token_expired"
-            ? "Ephemeral token expired. Generate a new QR with /unbien pair."
-            : code === "token_consumed"
-                ? "Token already consumed by another pair_request."
-                : "Token was not issued by this Pi.";
-        sendError(code, msg);
-        return;
-    }
-    // A delayed signed revoke must lose authority before the same-process
-    // re-pair enters storage; the replacement owns a fresh token snapshot.
-    const producer = _selfRevoke;
-    const producerEpoch = _selfRevokeEpoch;
-    producer?.invalidateStorageAuthority();
-    const pairedAt = new Date().toISOString();
-    try {
-        await addPeer({
-            name: inner.device_name,
-            remote_epk: appPeerId,
-            paired_at: pairedAt,
-        });
-        if (!hasListenerAuthority())
-            return;
-        _refreshPairingsCache();
-        if (producer &&
-            _selfRevoke === producer &&
-            _selfRevokeEpoch === producerEpoch) {
-            void producer.requestFreshCheck().catch(() => {
-                // The regular cadence retries; pairing itself already succeeded.
-            });
-        }
-    }
-    catch (err) {
-        if (!hasListenerAuthority())
-            return;
-        sendError("internal_error", `Failed to persist peer: ${String(err)}`);
-        return;
-    }
-    const cwd = _lastCtx && "cwd" in _lastCtx
-        ? _lastCtx.cwd
-        : process.cwd();
-    // Prefer the user-configured agent_name (with broker suffix when on the
-    // mesh) over the legacy parent/folder path — matches what the user sees
-    // in the terminal title and in /unbien status.
-    const sessionName = _displayName(cwd);
-    _attachOwner(relay, appPeerId, inner.device_name);
-    sendInner({
-        type: "pair_ok",
-        in_reply_to: inner.id,
-        session_name: sessionName,
-        session_started_at: _sessionStartedAt ?? Date.now(),
-        // App uses this to address subsequent inner messages to the right room
-        // when this Pi runs alongside others with the same epk. Defensive fallback
-        // to roomIdFor(cwd, name) covers the edge case where pair_request lands
-        // before _cmdStart could set _myRoomId (shouldn't happen in practice) —
-        // and stays plan/41-consistent (same (cwd, name) derivation as the announce).
-        room_id: _myRoomId ?? _deriveRoomId(cwd, sessionName),
-        // Plan/27 Wave A — surface the host coding-agent identity + machine
-        // hostname so the app can render a meaningful device row (and tell
-        // two PCs apart even when nicknames collide).
-        harness: _HARNESS,
-        hostname: _HOSTNAME,
-        protocol_version: PROTOCOL_VERSION,
-        capabilities: _capabilities(),
-    });
-    // Notify local RPC clients (e.g. Cockpit) that pairing completed, so they can
-    // close the QR screen and show the new device. Pure data event (display:false)
-    // — still emitted to the RPC stdout via the session stream.
-    _pi?.sendMessage({
-        customType: "un-bien:paired",
-        content: `Paired with ${inner.device_name}`,
-        details: { name: inner.device_name, peerId: appPeerId, pairedAt },
-        display: false,
-    });
-}
-// ── Extension factory (default export) ───────────────────────────────────────
-// Stores most recent command context so the auto-listener can use ui.notify.
-// NOTE: this is a CAPTURED command ctx — the SDK marks it stale after a
-// session replacement (newSession/fork/switch/reload). We re-capture it via
-// `withSession` when WE drive a newSession (see the session_new dispatch).
-let _lastCtx = null;
 // Freshest base ExtensionContext, re-captured on EVERY `session_start`
 // (startup/new/fork/reload/resume). The session_start ctx is always bound to
 // the CURRENT session, so compact + cancel (base-ctx methods) routed through
 // here never hit a stale ctx — regardless of who triggered the replacement
 // (an app Quick Action OR a `/new` typed in the Pi TUI). It carries only
-// base-ctx methods (no newSession — that's command-ctx only), so command ops
-// keep using `_lastCtx`.
+// base-ctx methods (no newSession — that's command-ctx only); command-only ops
+// (fork/new/branch) reach a command ctx by self-dispatching a slash command
+// instead of retaining one.
 let _lastEventCtx = null;
 const _noopCtx = { ui: { notify: () => undefined }, abort: () => undefined };
 // A single Pi process can load this extension TWICE in the SAME session:
@@ -2341,6 +1275,466 @@ function _releaseRootSession(pi) {
     if (g[_ROOT_SESSION_OWNER_KEY] === pi)
         delete g[_ROOT_SESSION_OWNER_KEY];
 }
+// ── Received-image pipeline seam ──────────────────────────────────────────
+//
+// The image-preview domain lives in ./session/received_images.ts and reaches
+// this module's state + helpers ONLY through this object (that module never
+// imports ../index.js — no circular imports). Same pattern as CommandDeps.
+const imageDeps = {
+    get pi() {
+        return _pi;
+    },
+    rootState: _rootState,
+    get myRoomMeta() {
+        return _myRoomMeta;
+    },
+    wakeAgent: _wakeAgent,
+};
+// ── Rpc-inbound handler seam ──────────────────────────────────────────────
+//
+// The rpc-command handler implementations live in ./session/rpc_handlers.ts
+// (a factory this module's `_routeRpcCommandFrom` — which owns channel/sender
+// routing — calls per dispatch). Same pattern as CommandDeps: that module
+// never imports ../index.js — no circular imports.
+const rpcDeps = {
+    get pi() {
+        return _pi;
+    },
+    rootState: _rootState,
+    get lastEventCtx() {
+        return _lastEventCtx;
+    },
+    imageDeps,
+    wakeAgent: _wakeAgent,
+    abortCurrentTurn: () => _abortCurrentTurn(),
+};
+// ── Relay lifecycle seam ──────────────────────────────────────────────────
+//
+// The relay lifecycle + owner-management code lives in
+// ./session/relay_lifecycle.ts and reaches this module's state and helpers
+// ONLY through this object (that module never imports ../index.js — no
+// circular imports). Same pattern as CommandDeps. The two wrappers below
+// preserve the exact `_handleControl` / `_onPeerDisconnect` export signatures
+// the integration tests import.
+const relayDeps = {
+    get state() {
+        return _state;
+    },
+    set state(v) {
+        _state = v;
+    },
+    get relay() {
+        return _relay;
+    },
+    set relay(v) {
+        _relay = v;
+    },
+    get relayUrl() {
+        return _relayUrl;
+    },
+    set relayUrl(v) {
+        _relayUrl = v;
+    },
+    get peerShort() {
+        return _peerShort;
+    },
+    set peerShort(v) {
+        _peerShort = v;
+    },
+    get stopAutoListener() {
+        return _stopAutoListener;
+    },
+    set stopAutoListener(v) {
+        _stopAutoListener = v;
+    },
+    get selfRevoke() {
+        return _selfRevoke;
+    },
+    set selfRevoke(v) {
+        _selfRevoke = v;
+    },
+    get selfRevokeEpoch() {
+        return _selfRevokeEpoch;
+    },
+    set selfRevokeEpoch(v) {
+        _selfRevokeEpoch = v;
+    },
+    get selfRevokeTopologyReadyEpoch() {
+        return _selfRevokeTopologyReadyEpoch;
+    },
+    set selfRevokeTopologyReadyEpoch(v) {
+        _selfRevokeTopologyReadyEpoch = v;
+    },
+    get selfRevokeTopology() {
+        return _selfRevokeTopology;
+    },
+    set selfRevokeTopology(v) {
+        _selfRevokeTopology = v;
+    },
+    get rootLifecycleGeneration() {
+        return _rootLifecycleGeneration;
+    },
+    set rootLifecycleGeneration(v) {
+        _rootLifecycleGeneration = v;
+    },
+    get meshNode() {
+        return _meshNode;
+    },
+    get cachedEd25519() {
+        return _cachedEd25519;
+    },
+    get myRoomId() {
+        return _myRoomId;
+    },
+    get myRoomMeta() {
+        return _myRoomMeta;
+    },
+    get sessionStartedAt() {
+        return _sessionStartedAt;
+    },
+    sessionCwd: () => {
+        const sm = _rootState().sessionManager;
+        return sm && typeof sm.getCwd === "function" ? sm.getCwd() : process.cwd();
+    },
+    get disposed() {
+        return _disposed;
+    },
+    get pi() {
+        return _pi;
+    },
+    get rootSessionId() {
+        return _rootSessionId;
+    },
+    get commandDeps() {
+        return deps;
+    },
+    activePeers: _activePeers,
+    rootState: _rootState,
+    getState: _getState,
+    refreshFooter: _refreshFooter,
+    safeNotify: _safeNotify,
+    refreshPairingsCache: _refreshPairingsCache,
+    displayName: _displayName,
+    attachBridgeIfReady: _attachBridgeIfReady,
+    routeClientMessageFrom: _routeClientMessageFrom,
+    routeRpcCommandFrom: _routeRpcCommandFrom,
+    routeUnBienPlaneFrom: _routeUnBienPlaneFrom,
+    liveCtx: _liveCtx,
+    noopCtx: _noopCtx,
+    renameAgent: _renameAgent,
+};
+export async function _handleControl(cmd) {
+    await _handleControlImpl(relayDeps, cmd);
+}
+export function _onPeerDisconnect(appPeerId) {
+    _onPeerDisconnectImpl(relayDeps, appPeerId);
+}
+// ── Command seam ──────────────────────────────────────────────────────────────
+//
+// The /unbien handlers live in ./commands/ and reach this module's state
+// and helpers ONLY through this object (command modules never import
+// ../index.js — no circular imports). Mutable module state is exposed as
+// accessor closures so handlers and this module always see the same
+// variables.
+const deps = {
+    get state() {
+        return _state;
+    },
+    set state(v) {
+        _state = v;
+    },
+    get relay() {
+        return _relay;
+    },
+    set relay(v) {
+        _relay = v;
+    },
+    get relayUrl() {
+        return _relayUrl;
+    },
+    set relayUrl(v) {
+        _relayUrl = v;
+    },
+    get meshNode() {
+        return _meshNode;
+    },
+    set meshNode(v) {
+        _meshNode = v;
+    },
+    get sessionName() {
+        return _sessionName;
+    },
+    set sessionName(v) {
+        _sessionName = v;
+    },
+    get sessionPeerCount() {
+        return _sessionPeerCount;
+    },
+    set sessionPeerCount(v) {
+        _sessionPeerCount = v;
+    },
+    get cachedEd25519() {
+        return _cachedEd25519;
+    },
+    set cachedEd25519(v) {
+        _cachedEd25519 = v;
+    },
+    get currentModel() {
+        return _currentModel;
+    },
+    set currentModel(v) {
+        _currentModel = v;
+    },
+    get currentThinking() {
+        return _currentThinking;
+    },
+    set currentThinking(v) {
+        _currentThinking = v;
+    },
+    get myRoomId() {
+        return _myRoomId;
+    },
+    set myRoomId(v) {
+        _myRoomId = v;
+    },
+    get myRoomMeta() {
+        return _myRoomMeta;
+    },
+    set myRoomMeta(v) {
+        _myRoomMeta = v;
+    },
+    get peerShort() {
+        return _peerShort;
+    },
+    set peerShort(v) {
+        _peerShort = v;
+    },
+    get sessionStartedAt() {
+        return _sessionStartedAt;
+    },
+    set sessionStartedAt(v) {
+        _sessionStartedAt = v;
+    },
+    get cwdLock() {
+        return _cwdLock;
+    },
+    set cwdLock(v) {
+        _cwdLock = v;
+    },
+    get lockedName() {
+        return _lockedName;
+    },
+    set lockedName(v) {
+        _lockedName = v;
+    },
+    get relayLifecycleGeneration() {
+        return _getRelayLifecycleGeneration();
+    },
+    set relayLifecycleGeneration(v) {
+        _setRelayLifecycleGeneration(v);
+    },
+    get relayStartDeferred() {
+        return _relayStartDeferred;
+    },
+    set relayStartDeferred(v) {
+        _relayStartDeferred = v;
+    },
+    get rootLifecycleGeneration() {
+        return _rootLifecycleGeneration;
+    },
+    set rootLifecycleGeneration(v) {
+        _rootLifecycleGeneration = v;
+    },
+    get meshJoinGeneration() {
+        return _meshJoinGeneration;
+    },
+    set meshJoinGeneration(v) {
+        _meshJoinGeneration = v;
+    },
+    get selfRevoke() {
+        return _selfRevoke;
+    },
+    set selfRevoke(v) {
+        _selfRevoke = v;
+    },
+    get selfRevokeEpoch() {
+        return _selfRevokeEpoch;
+    },
+    set selfRevokeEpoch(v) {
+        _selfRevokeEpoch = v;
+    },
+    get selfRevokeTopologyReadyEpoch() {
+        return _selfRevokeTopologyReadyEpoch;
+    },
+    set selfRevokeTopologyReadyEpoch(v) {
+        _selfRevokeTopologyReadyEpoch = v;
+    },
+    get selfRevokeTopology() {
+        return _selfRevokeTopology;
+    },
+    set selfRevokeTopology(v) {
+        _selfRevokeTopology = v;
+    },
+    get stopAutoListener() {
+        return _stopAutoListener;
+    },
+    set stopAutoListener(v) {
+        _stopAutoListener = v;
+    },
+    get hasGlobalPairings() {
+        return _hasGlobalPairings;
+    },
+    get disposed() {
+        return _disposed;
+    },
+    get lastEventCtx() {
+        return _lastEventCtx;
+    },
+    get pi() {
+        return _pi;
+    },
+    get rootSessionId() {
+        return _rootSessionId;
+    },
+    activePeers: _activePeers,
+    isCurrentRootLifecycle: _isCurrentRootLifecycle,
+    displayName: _displayName,
+    deriveRoomId: _deriveRoomId,
+    currentModelName: _currentModelName,
+    rootState: _rootState,
+    goIdle: () => _goIdle(relayDeps),
+    onRelayClose: (closedRelay) => _onRelayClose(relayDeps, closedRelay),
+    installAutoListener: (relay) => _installAutoListener(relayDeps, relay),
+    refreshFooter: _refreshFooter,
+    revokeActiveOwnerRuntime: _revokeActiveOwnerRuntime,
+    attachBridgeIfReady: _attachBridgeIfReady,
+    emitRelayState: (force) => _emitRelayState(relayDeps, force),
+    refreshSessionPeerCount: _refreshSessionPeerCount,
+    deliverMeshMessageToAgent: _deliverMeshMessageToAgent,
+    refreshPairingsCache: _refreshPairingsCache,
+    detachPeerChannel: (appPeerId) => _detachPeerChannel(relayDeps, appPeerId),
+    handleControl: _handleControl,
+    relayStatus: () => _relayStatus(relayDeps),
+    getState: _getState,
+    runTestScenario: _runTestScenario,
+    safeNotify: _safeNotify,
+    renameAgent: _renameAgent,
+};
+// ── Test-only hooks seam ──────────────────────────────────────────────────────
+//
+// The _xForTest surface lives in ./test_hooks.ts (a factory over this module's
+// state + helpers — that module never imports ../index.js). The one-line
+// re-exports below preserve the exact export names every existing test
+// (extension.test.ts + the colocated command tests) imports.
+const _testHooks = createTestHooks({
+    commandDeps: deps,
+    get disposed() {
+        return _disposed;
+    },
+    set disposed(v) {
+        _disposed = v;
+    },
+    set autoInited(v) {
+        _autoInited = v;
+    },
+    get panelBridge() {
+        return _panelBridge;
+    },
+    set panelBridge(v) {
+        _panelBridge = v;
+    },
+    get rpcEnvelope() {
+        return _rpcEnvelope;
+    },
+    set rpcEnvelope(v) {
+        _rpcEnvelope = v;
+    },
+    get subagentRooms() {
+        return _subagentRooms;
+    },
+    set subagentRooms(v) {
+        _subagentRooms = v;
+    },
+    get extensionUiBridge() {
+        return _extensionUiBridge;
+    },
+    set extensionUiBridge(v) {
+        _extensionUiBridge = v;
+    },
+    set rootSessionId(v) {
+        _rootSessionId = v;
+    },
+    get cwdLock() {
+        return _cwdLock;
+    },
+    set cwdLock(v) {
+        _cwdLock = v;
+    },
+    get lockedName() {
+        return _lockedName;
+    },
+    set lockedName(v) {
+        _lockedName = v;
+    },
+    set sessionStartedAt(v) {
+        _sessionStartedAt = v;
+    },
+    set currentModel(v) {
+        _currentModel = v;
+    },
+    set pi(v) {
+        _pi = v;
+    },
+    set relayStartDeferred(v) {
+        _relayStartDeferred = v;
+    },
+    rootSessionOwnerKey: _ROOT_SESSION_OWNER_KEY,
+    sessions: _sessions,
+    get meshNode() {
+        return _meshNode;
+    },
+    get selfRevoke() {
+        return _selfRevoke;
+    },
+    get cachedEd25519() {
+        return _cachedEd25519;
+    },
+    get reconnectTimer() {
+        return _getReconnectTimer();
+    },
+    activePeers: _activePeers,
+    rootState: _rootState,
+    seedRootSession(sid) {
+        _rootSessionId = sid;
+        _stateFor(sid).sessionManager = {
+            getSessionId: () => sid,
+        };
+    },
+    deliverMeshMessageToAgent: _deliverMeshMessageToAgent,
+});
+export const _connectForTest = _testHooks.connectForTest;
+export const _stopForTest = _testHooks.stopForTest;
+export const _getDisposedForTest = _testHooks.getDisposedForTest;
+export const _setDisposedForTest = _testHooks.setDisposedForTest;
+export const _resetAutoInitedForTest = _testHooks.resetAutoInitedForTest;
+export const _resetBridgeOwnersForTest = _testHooks.resetBridgeOwnersForTest;
+export const _resetSessionsForTest = _testHooks.resetSessionsForTest;
+export const _seedRootSessionForTest = _testHooks.seedRootSessionForTest;
+export const _setAutoInitedForTest = _testHooks.setAutoInitedForTest;
+export const _hasMeshNodeForTest = _testHooks.hasMeshNodeForTest;
+export const _checkSelfRevokeForTest = _testHooks.checkSelfRevokeForTest;
+export const _getLockedNameForTest = _testHooks.getLockedNameForTest;
+export const _resetCwdLockForTest = _testHooks.resetCwdLockForTest;
+export const _startRelayForTest = _testHooks.startRelayForTest;
+export const _getCachedPublicKeyForTest = _testHooks.getCachedPublicKeyForTest;
+export const _setSessionStartedAtForTest = _testHooks.setSessionStartedAtForTest;
+export const _setCurrentModelForTest = _testHooks.setCurrentModelForTest;
+export const _getCurrentTurnIdForTest = _testHooks.getCurrentTurnIdForTest;
+export const _setPiForTest = _testHooks.setPiForTest;
+export const _hasPendingReconnect = _testHooks.hasPendingReconnect;
+export const _getActivePeerCountForTest = _testHooks.getActivePeerCountForTest;
+export const _hasActivePeerForTest = _testHooks.hasActivePeerForTest;
+export const _deliverMeshMessageToAgentForTest = _testHooks.deliverMeshMessageToAgentForTest;
 const extension = (pi) => {
     const applied = _appliedRegistry();
     if (applied.has(pi))
@@ -2365,13 +1759,13 @@ const extension = (pi) => {
     if (_claimRootSession(pi)) {
         _pi = pi;
         _extensionUiBridge?.dispose();
-        _extensionUiBridge = createExtensionUiBridge(pi, _uiBroadcast);
+        _extensionUiBridge = createExtensionUiBridge(pi, (msg) => _uiBroadcast(relayDeps, msg));
         _panelBridge?.dispose();
-        _panelBridge = createPanelBridge(pi, _panelBroadcast, {
+        _panelBridge = createPanelBridge(pi, (msg) => _panelBroadcast(relayDeps, msg), {
             suppressAgents: subagentRoomsEnabled(),
         });
         _rpcEnvelope?.dispose();
-        _rpcEnvelope = createRpcEnvelope(pi, _broadcastEnvelope, {
+        _rpcEnvelope = createRpcEnvelope(pi, (env) => _broadcastEnvelope(relayDeps, env), {
             enrichArgs: (tool, args) => {
                 const e = _enrichToolArgs(tool, args, _resolveToolCwd());
                 return Array.isArray(e.hunks) ? { hunks: e.hunks } : null;
@@ -2381,11 +1775,11 @@ const extension = (pi) => {
         _subagentRooms = initSubagentRooms(pi, {
             getParentRoomId: () => _myRoomId,
             getParentSessionId: () => _rootSessionId,
-            broadcastPanel: _panelBroadcast,
+            broadcastPanel: (msg) => _panelBroadcast(relayDeps, msg),
         });
     }
-    // Plano 19: ensure ~/.pi/un-bien/{sessions,skills}/ exist and deploy the
-    // agent-network skill on first load. resources_discover lets Pi find it.
+    // Plano 19: ensure the state root's `sessions/` + `skills/` dirs exist and
+    // deploy the agent-network skill on first load. resources_discover lets Pi find it.
     try {
         ensureGlobalDirs();
         _deployAgentNetworkSkill();
@@ -2427,7 +1821,7 @@ const extension = (pi) => {
             void _handleControl(event.text.slice(CTRL_PREFIX.length).trim());
             return { action: "handled" };
         }
-        if (!_anyPeerActive())
+        if (!_anyPeerActive(relayDeps))
             return;
         if (event.source === "extension")
             return;
@@ -2508,7 +1902,7 @@ const extension = (pi) => {
         // only clear the turn id used for queue/turn correlation.
         if (st.turnId)
             st.turnId = null;
-        _flushPendingReceivedImagePreviews();
+        _flushPendingReceivedImagePreviews(imageDeps);
         settleRun();
     });
     // plan/34: the broker no longer gates delivery on busy state, so we no
@@ -2516,6 +1910,17 @@ const extension = (pi) => {
     // room_meta over the relay (plan/32) below — that's independent of the
     // broker and drives the app's working indicator.
     pi.on("turn_start", (_event, ctx) => {
+        // One-shot TURN CTX TARGETED PROBE (see the session_start probe note):
+        // per-property, proxy-safe. Turn ctxs fire while the agent RUNS — if
+        // they carry the session-control powers, the always-warm capture
+        // replaces the stash entirely.
+        if (!_turnCtxProbed) {
+            _turnCtxProbed = true;
+            if (ctx)
+                _probeCtx("turn ctx", ctx);
+            else
+                envLog("turn ctx targeted: ctx is undefined at turn_start");
+        }
         const sid = _sidOf(ctx);
         const st = _stateFor(sid);
         // Each session records its OWN sessionManager (no cross-session clobber).
@@ -2594,6 +1999,61 @@ const extension = (pi) => {
         if (!_isNonRootSid(_sidOf(ctx)))
             _publishWorking(false);
     });
+    // RENAME FORWARD (pre-release 2026-09-18): the session display name
+    // changed — via /name in the TUI, RPC, or the app's own set_session_name
+    // command (pi's native verb; the reply IS the standard rpc response). Two
+    // effects: (1) forward to the app — over the relay-OPAQUE envelope plane (any
+    // relay, but only reaches ATTACHED peers) AND, for relay >=0.6.0, a
+    // room_meta_update the relay fans to ROOM SUBSCRIBERS (Home, pre-attach);
+    // (2) refresh the local announce state so the NEXT hello re-announces the
+    // fresh name — the relay's stored meta self-heals at the extension's next
+    // connect.
+    // Root sessions only (v1): a subagent child's rename gets its own forward
+    // when child renames matter.
+    pi.on("session_info_changed", (event, ctx) => {
+        const name = event?.name;
+        if (typeof name !== "string" || name.length === 0)
+            return;
+        if (_isNonRootSid(_sidOf(ctx)))
+            return;
+        _sessionName = name;
+        if (_myRoomMeta)
+            _myRoomMeta = { ..._myRoomMeta, name };
+        _broadcastEnvelope(relayDeps, {
+            evt: { channel: "session_info", data: { name } },
+        });
+        // ALSO fan via room_meta_update so the relay pushes the rename to ROOM
+        // SUBSCRIBERS (Home apps subscribed but NOT attached) — the evt above only
+        // reaches attached peers, so pre-attach the Home tile went stale until open
+        // or reconnect. Relay >=0.6.0 merges + fans `name`; older relays drop the
+        // unknown field (harmless — attached peers still get the evt). Design 01M1SPN7.
+        if (_relay && _myRoomId) {
+            _relay.sendControl({
+                type: "room_meta_update",
+                room_id: _myRoomId,
+                meta: { name },
+            });
+        }
+    });
+    // LEAF BEACON on tree navigation (branch). pi fires session_tree AFTER a leaf
+    // move for EVERY source — TUI /tree, edit-resubmit, and our own /unbien branch
+    // (event.fromExtension) — carrying the new leaf directly. Push it so the app
+    // re-derives its active path (evt session_info leafId → SessionState.derivePath
+    // walks parentId from the new leaf over its already-cached tree; no prefetch).
+    // THE single source for all leaf moves: without it a TUI /tree only reflected
+    // on the next get_entries refetch (stale path until then). Root room only — a
+    // subagent's tree move must not re-path the app's root session.
+    pi.on("session_tree", (event, ctx) => {
+        if (_isNonRootSid(_sidOf(ctx)))
+            return;
+        const leafId = event
+            ?.newLeafId;
+        if (typeof leafId === "string" && leafId.length > 0) {
+            _broadcastEnvelope(relayDeps, {
+                evt: { channel: "session_info", data: { leafId } },
+            });
+        }
+    });
     // Re-capture the freshest base ctx on every session replacement so compact
     // never operates on a stale captured ctx — this is the fix for the
     // "stale after session replacement" crash when the app taps Compact after a
@@ -2610,6 +2070,13 @@ const extension = (pi) => {
         // subagent steals the base ctx and root-scoped notifies silently drop.
         if (!_isNonRootSid(sid))
             _lastEventCtx = ctx;
+        // EVENT-CTX TARGETED PROBE (run 2026-09-18, round 3): the ctx objects
+        // are guarded (throwing getters — proxies), so full reflection
+        // under-reports or throws. Per-property access, each caught, is the
+        // proxy-safe probe.
+        if (!_isNonRootSid(sid) && ctx) {
+            _probeCtx("event ctx", ctx);
+        }
         if (ctx?.sessionManager)
             _stateFor(sid).sessionManager = ctx.sessionManager;
         // session_shutdown disposes per-session pi-ask subscriptions. A host that
@@ -2624,13 +2091,13 @@ const extension = (pi) => {
             if (ctx?.sessionManager)
                 _rootSessionId = sid;
             if (!_extensionUiBridge)
-                _extensionUiBridge = createExtensionUiBridge(pi, _uiBroadcast);
+                _extensionUiBridge = createExtensionUiBridge(pi, (msg) => _uiBroadcast(relayDeps, msg));
             if (!_panelBridge)
-                _panelBridge = createPanelBridge(pi, _panelBroadcast, {
+                _panelBridge = createPanelBridge(pi, (msg) => _panelBroadcast(relayDeps, msg), {
                     suppressAgents: subagentRoomsEnabled(),
                 });
             if (!_rpcEnvelope)
-                _rpcEnvelope = createRpcEnvelope(pi, _broadcastEnvelope, {
+                _rpcEnvelope = createRpcEnvelope(pi, (env) => _broadcastEnvelope(relayDeps, env), {
                     enrichArgs: (tool, args) => {
                         const e = _enrichToolArgs(tool, args, _resolveToolCwd());
                         return Array.isArray(e.hunks) ? { hunks: e.hunks } : null;
@@ -2640,7 +2107,7 @@ const extension = (pi) => {
                 _subagentRooms = initSubagentRooms(pi, {
                     getParentRoomId: () => _myRoomId,
                     getParentSessionId: () => _rootSessionId,
-                    broadcastPanel: _panelBroadcast,
+                    broadcastPanel: (msg) => _panelBroadcast(relayDeps, msg),
                 });
         }
         else if (_isNonRootSid(sid)) {
@@ -2648,6 +2115,17 @@ const extension = (pi) => {
             // `pi` here is the CHILD's ExtensionAPI (per-activation).
             _subagentRooms?.onChildSession(pi, ctx);
         }
+        // design 01M1CAW0 (announce waits for the session id): a relay start that
+        // was deferred because no session id existed re-runs NOW — the root
+        // session's sessionManager was captured above, so _deriveRoomId has an id
+        // to announce. Root session_starts only (a child never owned the relay);
+        // the flag stays armed when this session_start still carries no id.
+        if (deps.relayStartDeferred && !_isNonRootSid(sid)) {
+            if (_rootState().sessionManager?.getSessionId()) {
+                deps.relayStartDeferred = false;
+                void _cmdStart(deps, ctx);
+            }
+        }
         // Rearm a reused-but-disposed instance. The session_shutdown teardown (below)
         // sets _disposed=true assuming the host re-evaluates THIS module fresh for the
         // replacement session, yielding a new instance with _disposed=false. Some hosts
@@ -2661,7 +2139,7 @@ const extension = (pi) => {
             const restartAuthority = {
                 rootLifecycleGeneration: _rootLifecycleGeneration,
             };
-            void _cmdRoot(ctx, restartAuthority);
+            void _cmdRoot(deps, ctx, restartAuthority);
         }
         // Auto-start un-bien on a fresh boot when the cwd's local config has
         // auto_start_relay enabled (default true). Covers BOTH interactive
@@ -2702,7 +2180,7 @@ const extension = (pi) => {
                 const initCtx = isDaemon
                     ? { ui: _headlessUi(), cwd: process.cwd() }
                     : ctx;
-                void _cmdRoot(initCtx);
+                void _cmdRoot(deps, initCtx);
             }
         }
     });
@@ -2750,7 +2228,7 @@ const extension = (pi) => {
         // clears `_disposed` before its promises settle.
         _disposed = true;
         _rootLifecycleGeneration += 1;
-        _relayLifecycleGeneration += 1;
+        _setRelayLifecycleGeneration(_getRelayLifecycleGeneration() + 1);
         _meshJoinGeneration += 1;
         // The bridge owns live pi.events subscriptions + flow TTLs. Dispose before
         // the outgoing session is replaced so stale listeners cannot leak or
@@ -2765,8 +2243,18 @@ const extension = (pi) => {
             // app can mark the session ended. Emit EXPLICITLY here, BEFORE the
             // producer dispose below: `_rpcEnvelope` gates on its `disposed` flag,
             // so once disposed it can no longer build/broadcast this frame.
-            if (_anyPeerActive()) {
-                _broadcastEnvelope({ rpc: { type: "session_shutdown" } });
+            if (_anyPeerActive(relayDeps)) {
+                // FLUSH-BEFORE-TEARDOWN: await the frame's ws send-completion
+                // (bounded — a wedged socket can't hang the shutdown) BEFORE _goIdle
+                // closes the relay below. Fire-and-forget only beat close() by
+                // incidental FIFO luck; the switch flow (/resume: old instance
+                // broadcasts shutdown, fresh instance takes the new room) NEEDS the
+                // app to reliably mark the old session ended, or it lingers live
+                // forever (the app has no disconnect-implies-ended backstop, by
+                // design).
+                await _broadcastEnvelopeFlushed(relayDeps, {
+                    rpc: { type: "session_shutdown" },
+                });
             }
             _extensionUiBridge?.dispose();
             _extensionUiBridge = null;
@@ -2778,11 +2266,9 @@ const extension = (pi) => {
             _subagentRooms = null;
             _releaseRootSession(pi);
         }
-        // Drop captured ctxs immediately. On module-reuse hosts the same instance
-        // survives session replacement; leaving `_lastCtx` pointing at the now-
-        // stale command ctx is what crashed pi in _refreshFooter on peer reconnect
-        // (issue #55). session_start re-binds `_lastEventCtx` for the new session.
-        _lastCtx = null;
+        // Drop the captured event ctx immediately. On module-reuse hosts the same
+        // instance survives session replacement; the next session_start re-binds
+        // `_lastEventCtx` for the new session.
         _lastEventCtx = null;
         // No bye reason: the process keeps running and the fresh instance re-joins
         // the SAME relay room, so an explicit offline→online flap would be wrong.
@@ -2792,7 +2278,7 @@ const extension = (pi) => {
             _meshNode?.detachBridge();
         }
         else {
-            _goIdle();
+            _goIdle(relayDeps);
         }
         const meshNode = _meshNode;
         _meshNode = null;
@@ -2822,232 +2308,7 @@ const extension = (pi) => {
             /* best-effort */
         }
     });
-    // ── Commands ──────────────────────────────────────────────────────────────
-    //
-    // Final surface: 8 commands. Pre-2026-05-23 we had 20 commands covering
-    // multi-session UDS + granular relay control; in practice every install
-    // converged on one session and the relay was always either fully on or
-    // fully off. The simplified surface keeps the day-to-day path one-key
-    // (`/unbien`) and exposes only the actions that have distinct user
-    // intent: setup, status, stop, pair, devices, revoke, set-relay.
-    pi.registerCommand("unbien", {
-        description: "Connect (join local mesh + start relay), or run setup on first use",
-        getArgumentCompletions: async (prefix) => {
-            if (prefix.startsWith("revoke ") || prefix === "revoke") {
-                const shortPrefix = prefix === "revoke" ? "" : prefix.slice("revoke ".length);
-                return _shortidCompletions(shortPrefix, "revoke ");
-            }
-            return [
-                "setup",
-                "status",
-                "stop",
-                "pair",
-                "devices",
-                "revoke",
-                "rename",
-                "set-relay",
-                "relay",
-                "relay start",
-                "relay stop",
-                "relay status",
-                "relay url",
-                "config",
-                "identity",
-                "identity show",
-                "test", // hidden e2e UI harness (dev-only)
-                "peers", // plan/25 Wave D — local + cross-PC inventory
-                "create",
-                "remove",
-                "daemons", // daemon registry (plan/26 W1)
-                // Fleet ops use the `daemon` prefix so `/unbien stop` keeps
-                // meaning "stop this local Pi" — the local UX shipped in plan/25.
-                "daemon start",
-                "daemon stop",
-                "daemon restart",
-                "daemon send",
-                "daemon status",
-                "cron",
-                "cron add",
-                "cron list",
-                "cron remove",
-                "cron enable",
-                "cron disable",
-                "cron run",
-                "cron log",
-                "install",
-                "uninstall", // service install (plan/26 W3)
-            ]
-                .filter((o) => o.startsWith(prefix))
-                .map((o) => ({ value: o, label: o }));
-        },
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            const sub = args.trim();
-            if (sub === "") {
-                await _cmdRoot(ctx);
-            }
-            else if (sub === "setup") {
-                await _cmdSetup(ctx);
-            }
-            else if (sub === "status") {
-                _cmdStatus(ctx);
-            }
-            else if (sub === "stop") {
-                await _cmdStop(ctx);
-            }
-            else if (sub === "pair" || sub.startsWith("pair ")) {
-                await _cmdPair(ctx, sub.slice("pair".length).trim());
-            }
-            else if (sub === "devices") {
-                await _cmdList(ctx);
-            }
-            else if (sub.startsWith("revoke")) {
-                await _cmdRevoke(sub.slice("revoke".length).trim(), ctx);
-            }
-            else if (sub.startsWith("set-relay")) {
-                _cmdSetRelay(sub.slice("set-relay".length).trim(), ctx);
-            }
-            else if (sub === "relay" || sub.startsWith("relay ")) {
-                await _cmdRelay(sub.slice("relay".length).trim(), ctx);
-            }
-            else if (sub === "config") {
-                _cmdConfig(ctx);
-            }
-            else if (sub === "identity" || sub.startsWith("identity ")) {
-                await _cmdIdentity(ctx);
-            }
-            else if (sub === "test" || sub.startsWith("test ")) {
-                // Hidden dev-only e2e UI harness: broadcast canned frames to paired apps.
-                _safeNotify(`[un-bien test] ${_runTestScenario(sub.slice("test".length).trim())}`, "info", ctx);
-            }
-            else if (sub === "rename" || sub.startsWith("rename ")) {
-                await _renameAgent(sub.slice("rename".length).trim());
-            }
-            else if (sub === "peers") {
-                await _cmdPeers(ctx);
-            }
-            else if (sub === "install") {
-                _cmdInstall(ctx, { linkCli: true });
-            }
-            else if (sub === "uninstall") {
-                _cmdUninstall(ctx, { linkCli: true });
-            }
-            else {
-                await _cmdRoot(ctx);
-            }
-        },
-    });
-    // Nested registrations (one entry per public action). The flat handler
-    // above already routes `/unbien <sub>` — these exist for the SDK's
-    // command palette and slash-autocomplete in some UI modes.
-    pi.registerCommand("unbien setup", {
-        description: "Run the setup wizard and update local config",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdSetup(ctx);
-        },
-    });
-    pi.registerCommand("unbien status", {
-        description: "Show local mesh + relay status",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            _cmdStatus(ctx);
-        },
-    });
-    pi.registerCommand("unbien stop", {
-        description: "Stop everything (leave local mesh + disconnect relay)",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdStop(ctx);
-        },
-    });
-    pi.registerCommand("unbien pair", {
-        description: "Show a QR code to pair a new mobile device (optional: --ttl <seconds>)",
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            await _cmdPair(ctx, args.trim());
-        },
-    });
-    pi.registerCommand("unbien devices", {
-        description: "List paired mobile devices",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdList(ctx);
-        },
-    });
-    pi.registerCommand("unbien rename", {
-        description: "Rename this agent in the current session (updates mesh + relay room)",
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            await _renameAgent(args.trim());
-        },
-    });
-    pi.registerCommand("unbien revoke", {
-        description: "Revoke a paired device by its shortid",
-        getArgumentCompletions: async (prefix) => _shortidCompletions(prefix),
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            await _cmdRevoke(args.trim(), ctx);
-        },
-    });
-    pi.registerCommand("unbien set-relay", {
-        description: "Persist a new relay URL to user config",
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            _cmdSetRelay(args.trim(), ctx);
-        },
-    });
-    pi.registerCommand("unbien config", {
-        description: "Show the effective relay URL and where it came from",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            _cmdConfig(ctx);
-        },
-    });
-    pi.registerCommand("unbien identity", {
-        description: "Show this machine's identity: active EPK (public), backend, and source",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdIdentity(ctx);
-        },
-    });
-    pi.registerCommand("unbien identity show", {
-        description: "Show this machine's identity (EPK/backend/source) — alias of `identity`",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdIdentity(ctx);
-        },
-    });
-    pi.registerCommand("unbien relay", {
-        description: "Relay control: start | stop | status | url <http(s) url> (no arg toggles)",
-        handler: async (args, ctx) => {
-            _lastCtx = ctx;
-            await _cmdRelay(args.trim(), ctx);
-        },
-    });
-    // Plan/25 Wave D
-    pi.registerCommand("unbien peers", {
-        description: "List local + cross-PC mesh peers, grouped by PC label",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            await _cmdPeers(ctx);
-        },
-    });
-    // Service install / uninstall — the launcher daemon as a system service.
-    pi.registerCommand("unbien install", {
-        description: "Install the un-bien launcher daemon as a system service + link the un-bien CLI (systemd/launchd/Task Scheduler; Windows prompts for admin)",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            _cmdInstall(ctx, { linkCli: true });
-        },
-    });
-    pi.registerCommand("unbien uninstall", {
-        description: "Remove the un-bien launcher daemon system service + the CLI shims (Windows prompts for admin)",
-        handler: async (_, ctx) => {
-            _lastCtx = ctx;
-            _cmdUninstall(ctx, { linkCli: true });
-        },
-    });
+    registerUnbienCommands(pi, deps);
     // Auto-init now runs from the session_start handler (above), AFTER the
     // SDK calls bindCore(). The original setTimeout(0) here fired before bindCore
     // replaced the throwing action-method stubs, so the first pi.sendMessage in
@@ -3057,960 +2318,6 @@ const extension = (pi) => {
     // interactive pi sessions are on remote automatically — no /unbien needed.
 };
 export default extension;
-// ── Command implementations ───────────────────────────────────────────────────
-/**
- * `/unbien status` — full state snapshot. Two lines: local mesh + relay.
- *
- * Always callable; safe when nothing is up (renders the off variants).
- * Reuses the same icons as the footer so terminal + status output stay
- * visually consistent.
- */
-function _cmdStatus(ctx) {
-    const relayUrl = _relayUrl ?? resolveRelayUrl().url ?? "not configured";
-    // Mesh line
-    let meshLine;
-    if (_meshNode) {
-        const name = _meshNode.name();
-        meshLine = `🟢 Local mesh: connected as "${name}" (${_sessionPeerCount} peer${_sessionPeerCount === 1 ? "" : "s"})`;
-    }
-    else {
-        meshLine = "⚪ Local mesh: not connected";
-    }
-    // Relay line — paired state is derived from _activePeers.size now.
-    let relayLine;
-    if (_state === "idle") {
-        relayLine = `⚪ Relay: off (${relayUrl}) — run /unbien to start`;
-    }
-    else if (_activePeers.size > 0) {
-        const count = _activePeers.size;
-        const shortids = [..._activePeers.keys()]
-            .map((peerId) => peerId.slice(0, 8))
-            .join(", ");
-        relayLine = `🟢 Relay: ${count} owner${count === 1 ? "" : "s"} online (${shortids}) (${relayUrl})`;
-    }
-    else {
-        relayLine = _hasGlobalPairings
-            ? `🟢 Relay: on, waiting for an app to connect (${relayUrl})`
-            : `🟡 Relay: on, waiting for first pairing (${relayUrl})`;
-    }
-    ctx.ui.notify(`[un-bien]\n  ${meshLine}\n  ${relayLine}`, "info");
-}
-/**
- * Plan/25 Wave D: `/unbien peers`.
- *
- * Queries the local broker for the aggregated peer inventory (`list_peers`
- * returns locals + cross-PC entries prefixed with `<pc_label>:`). Formats
- * the result grouped by source so users can see at a glance who's on
- * their machine vs. on a paired sibling Pi.
- */
-async function _cmdPeers(ctx) {
-    if (!_meshNode) {
-        ctx.ui.notify("[un-bien] Not on the local mesh. Run /unbien to join.", "warning");
-        return;
-    }
-    let peers;
-    try {
-        const reply = await _meshNode.request("broker", { type: "list_peers" }, 2000);
-        peers = reply.body?.peers ?? [];
-    }
-    catch (err) {
-        ctx.ui.notify(`[un-bien] peers list failed: ${String(err)}`, "error");
-        return;
-    }
-    // Exclude self from the printed list — `list_peers` returns every peer
-    // registered with the broker including the caller, which is noise here.
-    const selfName = _meshNode.name();
-    ctx.ui.notify(`[un-bien] peers:\n${formatPeerInventory(peers, selfName)}`, "info");
-}
-/**
- * Root handler for `/unbien`. On first run (no local config) drops into
- * the wizard; on subsequent runs auto-joins the local mesh + starts the
- * relay (if opted in during setup), then prints the status.
- *
- * `/unbien` is intentionally the only command users need day-to-day:
- * idempotent connect + status display.
- */
-async function _cmdRoot(ctx, restartAuthority) {
-    const rootLifecycleGeneration = restartAuthority?.rootLifecycleGeneration ?? _rootLifecycleGeneration;
-    if (_cmdRootInFlight) {
-        try {
-            await _cmdRootInFlight;
-        }
-        catch (err) {
-            // Stale authority stops here. A current normal duplicate preserves the
-            // outgoing error, while a current replacement suppresses that old-session
-            // failure and falls through to start one fresh root below.
-            if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-                return;
-            if (!restartAuthority)
-                throw err;
-        }
-        if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-            return;
-        if (!restartAuthority) {
-            _cmdStatus(ctx);
-            return;
-        }
-    }
-    if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-        return;
-    const run = _cmdRootInner(ctx, rootLifecycleGeneration);
-    _cmdRootInFlight = run;
-    try {
-        await run;
-    }
-    finally {
-        if (_cmdRootInFlight === run)
-            _cmdRootInFlight = null;
-    }
-}
-async function _cmdRootInner(ctx, rootLifecycleGeneration) {
-    // A root retains its startup epoch through every pre-candidate await. This is
-    // stronger than `_disposed`, which a same-module session_start intentionally
-    // clears while an outgoing continuation may still be pending.
-    if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-        return;
-    const cwd = "cwd" in ctx ? ctx.cwd : process.cwd();
-    // Lock identity is (cwd, name). Several agents may run in the SAME folder; the
-    // requested name just has to be made unique. Derive the name the same way
-    // `_cmdJoin` does so the lock and the mesh registration agree on identity.
-    const requestedName = loadLocalConfig(cwd).agent_name || defaultAgentName(cwd);
-    // Per-(cwd,name) lock. Interactive agents may coexist by auto-suffixing
-    // (`name#2`, `name#3`, …), but supervised daemons must be singletons for their
-    // registered cwd/name. If a daemon silently came up as `#2`, the supervisor
-    // would report "running" while the mesh had duplicate peers for one repo.
-    if (_cwdLock === null) {
-        const isDaemon = process.env["UNBIEN_DAEMON"] === "1";
-        const maxAttempts = isDaemon ? 1 : 1000;
-        for (let n = 1; n <= maxAttempts; n++) {
-            const candidate = n === 1 ? requestedName : `${requestedName}#${n}`;
-            const result = await acquireCwdLock(cwd, candidate);
-            if (!_isCurrentRootLifecycle(rootLifecycleGeneration)) {
-                if (result.ok) {
-                    try {
-                        result.release();
-                    }
-                    catch {
-                        /* best-effort stale lock cleanup */
-                    }
-                }
-                return;
-            }
-            if (result.ok) {
-                _cwdLock = result;
-                _lockedName = candidate;
-                break;
-            }
-        }
-        if (_cwdLock === null) {
-            if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-                return;
-            ctx.ui.notify(process.env["UNBIEN_DAEMON"] === "1"
-                ? `[un-bien] Daemon not started: another live agent already owns "${requestedName}" in this folder. Stop the old Pi process, then restart the daemon.`
-                : `[un-bien] Could not start: too many agents named "${requestedName}" already running in this folder.`, "warning");
-            return;
-        }
-    }
-    // First-time wizard: no local config in this cwd → run interactive setup.
-    if (!localConfigExists(cwd)) {
-        // SAFETY: ctx.ui MIGHT carry the wizard's select/input methods (interactive
-        // Pi) or not (headless); the `typeof ui.select !== "function"` guard on the
-        // next line validates the structural assumption before any method call.
-        const ui = ctx.ui;
-        if (typeof ui.select !== "function") {
-            _cmdStatus(ctx);
-            return;
-        }
-        const baseDefault = defaultAgentName(cwd);
-        const newConfig = await runSetupWizard(ui, {
-            agent_name: baseDefault,
-            use_relay: true,
-        });
-        if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-            return;
-        if (!newConfig) {
-            ctx.ui.notify("[un-bien] Setup cancelled.", "info");
-            return;
-        }
-        saveLocalConfig(cwd, newConfig);
-        ctx.ui.notify(`[un-bien] Config saved to ${cwd}/.pi/un-bien/config.json`, "info");
-        if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-            return;
-        await _cmdJoin(ctx);
-        if (!_isCurrentRootLifecycle(rootLifecycleGeneration) || !_meshNode)
-            return;
-        if (effectiveAutoStartRelay(newConfig))
-            await _cmdStart(ctx);
-        if (!_isCurrentRootLifecycle(rootLifecycleGeneration) || !_meshNode)
-            return;
-        _cmdStatus(ctx);
-        return;
-    }
-    // Returning user with config: ALWAYS join the local UDS mesh on connect; the
-    // relay is the only thing gated by auto_start_relay. So auto_start_relay:false
-    // now means "local mesh, no relay" (matching the first-time/wizard path and
-    // the field's documented intent) — previously a false flag skipped the mesh
-    // join entirely, leaving the agent (incl. daemons) fully idle.
-    const config = loadLocalConfig(cwd);
-    if (!_isCurrentRootLifecycle(rootLifecycleGeneration))
-        return;
-    if (!_meshNode)
-        await _cmdJoin(ctx);
-    // `_cmdJoin` returns void on a canceled/failed join, so recheck both the
-    // root lifecycle and publication before bringing the Relay up.
-    if (!_isCurrentRootLifecycle(rootLifecycleGeneration) || !_meshNode)
-        return;
-    if (effectiveAutoStartRelay(config) && _state === "idle")
-        await _cmdStart(ctx);
-    if (!_isCurrentRootLifecycle(rootLifecycleGeneration) || !_meshNode)
-        return;
-    _cmdStatus(ctx);
-}
-/**
- * `/unbien setup` — re-run the wizard. Defaults pre-fill from the
- * existing config so it doubles as an "edit" flow.
- */
-async function _cmdSetup(ctx) {
-    const cwd = "cwd" in ctx ? ctx.cwd : process.cwd();
-    // SAFETY: ctx.ui MIGHT carry the wizard's select/input methods (interactive
-    // Pi) or not (headless); the `typeof ui.select !== "function"` guard on the
-    // next line validates the structural assumption before any method call.
-    const ui = ctx.ui;
-    if (typeof ui.select !== "function") {
-        ctx.ui.notify("[un-bien] Setup requires an interactive UI.", "warning");
-        return;
-    }
-    const current = loadLocalConfig(cwd);
-    const baseDefault = defaultAgentName(cwd);
-    const newConfig = await runSetupWizard(ui, {
-        agent_name: current.agent_name ?? baseDefault,
-        use_relay: effectiveAutoStartRelay(current),
-    });
-    if (!newConfig) {
-        ctx.ui.notify("[un-bien] Setup cancelled.", "info");
-        return;
-    }
-    saveLocalConfig(cwd, newConfig);
-    ctx.ui.notify("[un-bien] Config updated. Run /unbien to apply now.", "info");
-}
-async function _cmdStart(ctx) {
-    if (_state !== "idle") {
-        ctx.ui.notify("[un-bien] Already started.", "warning");
-        return;
-    }
-    const lifecycleGeneration = ++_relayLifecycleGeneration;
-    const isCurrentCandidate = () => !_disposed &&
-        lifecycleGeneration === _relayLifecycleGeneration &&
-        _state === "idle" &&
-        _relay === null;
-    let edKp;
-    try {
-        edKp = await getOrCreateEd25519Keypair();
-    }
-    catch (err) {
-        // Identity lookup is part of the candidate lifecycle. A later stop/off or
-        // session replacement must silence its stale rejection before any UI or
-        // error propagation touches the superseded context.
-        if (!isCurrentCandidate())
-            return;
-        if (err instanceof KeyringUnavailableError) {
-            // The platform keyring (macOS Keychain / Windows Credential Manager) is
-            // locked/denied and there's no file identity to fall back to. We refuse
-            // to mint a new key (that's what silently broke pairing after idle), so
-            // abort cleanly with an actionable message instead of crashing or
-            // re-pairing. Unlocking the keychain and re-running fixes it.
-            ctx.ui.notify("[un-bien] Could not read this machine's identity: the system " +
-                "keychain is locked or access was denied. Unlock it (open the app / " +
-                "log in) and run /unbien again. Your pairing is NOT lost. " +
-                '(For a headless host, set "identity": { "storage": "file" } in un-bien.json.)', "error");
-            return;
-        }
-        if (err instanceof PairedIdentityMissingError) {
-            // Issues #95/#69: this process can't reach the keyring that holds the
-            // paired identity (classically a `systemd --user` daemon vs. the desktop
-            // session that paired). Minting a fresh key here would make SelfRevoke
-            // wipe peers.json seconds later and take the phone offline, so storage
-            // refuses. Surface the actionable fix instead of failing silently.
-            ctx.ui.notify("[un-bien] Could not read this machine's identity, but devices are " +
-                "already paired — refusing to generate a new one (that would revoke " +
-                "them). This process likely cannot reach the same keyring as the " +
-                "session that paired (e.g. a systemd --user daemon). Give the service " +
-                "keyring access, or copy the paired keypair to ~/.pi/un-bien/identity.json " +
-                "(0600) so both contexts read the same identity.", "error");
-            return;
-        }
-        throw err;
-    }
-    // Re-check immediately after the first await, before cache/config/model/UI
-    // mutation or Relay construction. `_disposed` alone is insufficient because
-    // same-module session_start intentionally clears it for the replacement.
-    if (!isCurrentCandidate())
-        return;
-    _cachedEd25519 = edKp;
-    const { url: relayUrl, source } = resolveRelayUrl();
-    if (relayUrl === null) {
-        ctx.ui.notify("[un-bien] No relay configured — staying on the local mesh only. Set one " +
-            "with `/unbien set-relay <url>` (or the UNBIEN_RELAY env var) to connect " +
-            "the phone app.", "warning");
-        return;
-    }
-    const myShort = Buffer.from(edKp.publicKey).toString("base64").slice(0, 8);
-    const cwd = "cwd" in ctx ? ctx.cwd : process.cwd();
-    // Same name we send in pair_ok — keeps room_meta.name and the per-pair
-    // session_name aligned so the app shows consistent labels.
-    const sessionName = _displayName(cwd);
-    // plan/41: derive the App↔Pi room from (cwd, name) so several agents in the
-    // SAME folder get distinct rooms (the app renders one tile per agent). The
-    // default/unnamed case preserves the legacy cwd-only id (no re-keying). Uses
-    // the SAME name as room_meta.name / pair_ok below — the invariant that the
-    // app pairs on the room the Pi actually announces.
-    const roomId = _deriveRoomId(cwd, sessionName);
-    // Seed the current model from the SDK's resolved selection so room_meta
-    // carries it on connect. `model_select` only fires on an explicit set/cycle
-    // (NOT on settings load), so a headless daemon that just runs its default
-    // model never emits it — without this its room_meta would omit the model and
-    // the app shows "unknown". `getModel()` returns the session's resolved model
-    // in every mode (interactive + RPC daemon); turn_start hydrates it later if
-    // the SDK resolves the model lazily.
-    if (!_currentModel) {
-        try {
-            const c = ctx;
-            // Prefer the live getModel() / ctx.model — populated for an interactive
-            // Pi. For a HEADLESS DAEMON both are undefined at connect: the SDK only
-            // resolves `this.model` lazily at the first turn, and `model_select`
-            // never fires for a default-model session. So fall back to the CONFIGURED
-            // default (defaultProvider/defaultModel in <cwd>/.pi/settings.json) — the
-            // model the daemon will actually use. Without this an idle daemon (never
-            // prompted → no turn) would never report its model and the app shows
-            // "unknown". turn_start still hydrates a later override.
-            const live = c.getModel?.() ?? c.model;
-            if (live) {
-                _currentModel = live.name ?? live.id ?? undefined;
-            }
-            else {
-                const sm = SettingsManager.create(cwd);
-                const provider = sm.getDefaultProvider();
-                const modelId = sm.getDefaultModel();
-                if (modelId) {
-                    // SAFETY: ensureModelRegistry only reads modelRegistry/getModel off
-                    // the ctx; c (and the _lastEventCtx/_lastCtx fallbacks) carry those
-                    // when present, and it tolerates null.
-                    const regCtx = (c ??
-                        _lastEventCtx ??
-                        _lastCtx);
-                    const found = provider
-                        ? ensureModelRegistry(regCtx).find(provider, modelId)
-                        : undefined;
-                    _currentModel = found?.name ?? modelId;
-                }
-            }
-        }
-        catch {
-            /* defensive — never block start on a model lookup */
-        }
-    }
-    // Plan/28 Wave D.1: seed thinking from the SDK's current level so the
-    // first room_meta hello already carries it. `pi.getThinkingLevel()` is
-    // safe at this point — extension factory has been bound by the SDK
-    // before any command handler fires. Future toggles go through the
-    // `thinking_level_select` event handler above.
-    try {
-        _currentThinking = _pi?.getThinkingLevel();
-    }
-    catch {
-        /* defensive — never block /unbien start on this */
-    }
-    const roomMeta = { name: sessionName, cwd };
-    const modelName = _currentModelName();
-    if (modelName)
-        roomMeta.model = modelName;
-    if (_currentThinking)
-        roomMeta.thinking = _currentThinking;
-    // The room's OWN pi sessionId on the announce — so the app keys per-session
-    // state by the pi id (wire identity), not the routing roomId. roomId stays
-    // relay-routing only.
-    const rootSid = _rootState().sessionManager?.getSessionId() ?? _rootSessionId ?? undefined;
-    if (rootSid)
-        roomMeta.sessionId = rootSid;
-    // Persist so _attemptReconnect can replay the same hello payload — without
-    // this, reconnect issues a bare hello and the relay creates a "default room"
-    // entry that surfaces in the app as a phantom legacy session.
-    _myRoomMeta = roomMeta;
-    ctx.ui.notify(`[un-bien] Connecting to relay ${relayUrl} (source: ${source}, room: ${roomId})…`, "info");
-    // Transport opens WebSocket; convert the canonical http(s):// stored
-    // form to ws(s):// at this boundary. The relayUrl variable keeps the
-    // http(s):// form for logging + mesh client construction below.
-    const relay = new RelayClient(toWebSocketUrl(relayUrl), edKp);
-    try {
-        await relay.connect({ roomId, roomMeta });
-    }
-    catch (err) {
-        // A rejected local candidate is never published and must always be closed,
-        // regardless of whether this lifecycle is still authoritative.
-        try {
-            relay.close();
-        }
-        catch {
-            /* best-effort rejected candidate cleanup */
-        }
-        // A stop, shutdown/replacement, relay-off, or newer start may supersede a
-        // candidate before its rejection arrives. Keep the outgoing context silent;
-        // only the authoritative attempt may report an error.
-        if (!isCurrentCandidate())
-            return;
-        if (err instanceof RoomAlreadyOpenError) {
-            ctx.ui.notify("[un-bien] Already running in this cwd. Stop the other terminal first.", "error");
-            return;
-        }
-        ctx.ui.notify(`[un-bien] relay connect failed: ${String(err)}`, "error");
-        return;
-    }
-    // The candidate is local until this publication point. Session shutdown,
-    // stop/relay-off, or a newer start may have invalidated it while connect()
-    // was pending; never let that stale continuation resurrect the Relay.
-    if (!isCurrentCandidate()) {
-        try {
-            relay.close();
-        }
-        catch {
-            /* best-effort stale candidate cleanup */
-        }
-        return;
-    }
-    _relay = relay;
-    _relayUrl = relayUrl;
-    _peerShort = myShort;
-    _myRoomId = roomId;
-    _state = "started";
-    // Set _sessionStartedAt ONLY on first /unbien start since process boot.
-    // Subsequent start cycles (after stop) preserve the original epoch so the
-    // app keeps treating it as the same session (and merges new events from
-    // the terminal turns that happened during the idle window). Pi process
-    // restart is the only thing that produces a fresh session_started_at.
-    if (_sessionStartedAt === null)
-        _sessionStartedAt = Date.now();
-    // _messageBuffer intentionally preserved across stop/start — it accumulates
-    // message_end events for the lifetime of the Pi process, including turns
-    // initiated from the terminal while the relay was disconnected.
-    relay.on("close", () => _onRelayClose(relay));
-    _stopAutoListener = _installAutoListener(relay);
-    _refreshFooter(ctx);
-    // SelfRevoke is the Pi path's single initial topology producer. Its first
-    // coalesced sweep always publishes verified membership or a safe fallback
-    // before the bridge may attach.
-    let createdProducer = false;
-    if (_selfRevoke === null) {
-        createdProducer = true;
-        const producerEpoch = ++_selfRevokeEpoch;
-        _selfRevokeTopologyReadyEpoch = -1;
-        _selfRevokeTopology = null;
-        let producer;
-        producer = new SelfRevoke({
-            client: new MeshClient(relayUrl),
-            storage: { snapshotOwnerPubkeys, conditionalRemovePeer },
-            myPubkey: edKp.publicKey,
-            onRevoke: (rawOwnerPubkey, canonicalOwnerPubkey) => {
-                if (_selfRevoke !== producer || producerEpoch !== _selfRevokeEpoch) {
-                    return;
-                }
-                _revokeActiveOwnerRuntime(canonicalOwnerPubkey);
-                void rawOwnerPubkey; // exact storage removal already happened upstream
-            },
-            onAuthoritativeOwners: (canonicalOwnerPubkeys) => {
-                if (_selfRevoke !== producer || producerEpoch !== _selfRevokeEpoch) {
-                    return;
-                }
-                const presentOwners = new Set(canonicalOwnerPubkeys);
-                let effectFailed = false;
-                for (const canonicalOwnerPubkey of [..._activePeers.keys()]) {
-                    if (_selfRevoke !== producer || producerEpoch !== _selfRevokeEpoch) {
-                        return;
-                    }
-                    if (presentOwners.has(canonicalOwnerPubkey))
-                        continue;
-                    try {
-                        _revokeActiveOwnerRuntime(canonicalOwnerPubkey);
-                    }
-                    catch {
-                        effectFailed = true;
-                    }
-                }
-                if (effectFailed)
-                    throw new Error("Owner runtime reconciliation failed");
-            },
-            onTopologyChanged: (snapshot) => {
-                if (_selfRevoke !== producer || producerEpoch !== _selfRevokeEpoch) {
-                    return;
-                }
-                _selfRevokeTopology = snapshot;
-                _meshNode?.setTopology(snapshot);
-                _selfRevokeTopologyReadyEpoch = producerEpoch;
-                _attachBridgeIfReady();
-            },
-            log: { info: () => { }, warn: () => { }, error: () => { } },
-        });
-        _selfRevoke = producer;
-        producer.start();
-        await producer.checkOnce();
-        if (_disposed ||
-            _selfRevoke !== producer ||
-            producerEpoch !== _selfRevokeEpoch ||
-            _relay !== relay) {
-            return;
-        }
-    }
-    // Relay reconnect reuses the current producer's retained snapshot. Initial
-    // startup is callback-driven above, so it must not issue a second attach.
-    if (!createdProducer)
-        _attachBridgeIfReady();
-    _emitRelayState(); // → connected
-    ctx.ui.notify(`[un-bien] state: started (peer=${myShort}) — Connected to relay ${relayUrl}`, "info");
-}
-/**
- * `/unbien pair` — always generates a fresh QR when the relay is up.
- *
- * Pre-W2D this rejected with "Already paired with X" once one owner was
- * connected, forcing /unbien stop to pair a second device — the
- * catch-22 the multi-channel refactor was designed to break. Now the new
- * device is **added** to `_activePeers` after scanning, while existing
- * owners keep their session.
- */
-async function _cmdPair(ctx, args = "") {
-    const cwd = "cwd" in ctx ? ctx.cwd : "";
-    // Auto-bootstrap when services are down. Before this, `/unbien pair`
-    // on a fresh terminal forced the user to call `/unbien` first — every
-    // session began with the same surprise warning + second command. Now we
-    // do the join + relay-start inline so the common "I just opened a
-    // terminal and want to pair my phone" flow is a single command.
-    //
-    // We don't run the first-time wizard here: pair is a focused operation
-    // and the wizard prompts are wrong UX in that flow. If there's no local
-    // config, the user truly needs to run `/unbien` first to configure.
-    if (_state === "idle") {
-        if (!localConfigExists(cwd)) {
-            ctx.ui.notify("[un-bien] First-time setup needed. Run /unbien to configure, then /unbien pair.", "warning");
-            return;
-        }
-        ctx.ui.notify("[un-bien] Starting mesh + relay before pairing…", "info");
-        if (!_meshNode)
-            await _cmdJoin(ctx);
-        if (_state === "idle")
-            await _cmdStart(ctx);
-    }
-    // Relay must be up — the QR carries a token the app exchanges through
-    // the relay. Without a live WS there's nothing for the scan to land on.
-    if (_state === "idle" || !_relay) {
-        ctx.ui.notify("[un-bien] Pair requires the relay to be connected. " +
-            "Run /unbien to start it (or fix your relay URL via /unbien set-relay).", "warning");
-        return;
-    }
-    const edKp = _cachedEd25519;
-    // Embed the user-configured name in the QR so the app shows it on the
-    // pairing screen before pair_ok lands (better UX than "remote" or a
-    // raw path snippet).
-    const sessionName = _displayName(cwd);
-    // Optional `--ttl <seconds>` — RPC clients (e.g. Cockpit) pass a caller-
-    // defined expiry. Defaults to TOKEN_TTL_MS, clamped to the safe window.
-    const ttlMatch = /--ttl\s+(\d+)/.exec(args);
-    const ttlMs = ttlMatch
-        ? clampPairTtlMs(Number(ttlMatch[1]) * 1000)
-        : TOKEN_TTL_MS;
-    const { token, expiresAt } = qrSession.issueToken(ttlMs);
-    // The QR room is the ISSUING session's room (session-id-derived `_myRoomId`).
-    // Pairing is room-scoped to this session (it owns the QR token), so only this
-    // session answers the pair_request — no fan-out race. Trust still lands on the
-    // MACHINE: pair_ok persists a PairedMachine keyed by epk, and the app then
-    // discovers all the machine's sessions via room_announced.
-    const roomId = _myRoomId ?? _deriveRoomId(cwd, sessionName);
-    const qrUri = buildQRUri(token, edKp.publicKey, sessionName, roomId);
-    // Render both the QR ASCII and the copy-paste URI inside the Pi TUI's
-    // chat panel via `pi.sendMessage` — the same channel the SDK uses for
-    // agent responses + tool results. `process.stderr.write` (the old QR
-    // path via `displayQR`) broke the TUI layout because it bypassed the
-    // chat widget and bled into the prompt area. qrcode-terminal v0.12
-    // small mode is pure Unicode (█ ▀ ▄ space, no ANSI escapes — see
-    // `lib/main.js:48-53`), so embedding the ASCII inside a sendMessage
-    // content string renders correctly without raw escape bytes.
-    if (_pi) {
-        const qrAscii = renderQRAscii(qrUri);
-        _pi.sendMessage({
-            customType: "un-bien:pair-code",
-            content: `📱 Scan to pair:\n\n${qrAscii}\n` +
-                `📋 Or copy this pairing code (camera-less devices):\n\n${qrUri}`,
-            // Structured payload for RPC clients (e.g. Cockpit): render their own QR
-            // from `uri` + show the expiry, without scraping the display string.
-            details: { uri: qrUri, token, expiresAt, roomId, name: sessionName },
-            display: true,
-        });
-    }
-    ctx.ui.notify(`[un-bien] QR ready — valid until ${new Date(expiresAt).toLocaleTimeString()}. ` +
-        `Scan with the app, or copy the pairing code printed above.`, "info");
-    // Returns immediately; the auto-listener transitions to 'paired' on pair_request.
-}
-/**
- * `/unbien stop` — full teardown. Leaves the local UDS mesh AND closes
- * the relay. Safe when one or both are already off. To resume, run
- * `/unbien` again.
- */
-async function _cmdStop(ctx) {
-    // Invalidate queued root work and local async candidates even when none has
-    // published yet.
-    _rootLifecycleGeneration += 1;
-    _meshJoinGeneration += 1;
-    const meshUp = _meshNode !== null;
-    const relayUp = _state !== "idle";
-    if (!meshUp && !relayUp) {
-        _relayLifecycleGeneration += 1;
-        ctx.ui.notify("[un-bien] Already stopped — nothing to do.", "info");
-        return;
-    }
-    // Revoke Relay/SelfRevoke/bridge authority while the global node is still
-    // visible and before close() begins UDS leave.
-    if (relayUp) {
-        _goIdle();
-    }
-    else {
-        _relayLifecycleGeneration += 1;
-        _meshNode?.detachBridge();
-    }
-    const meshNode = _meshNode;
-    _meshNode = null;
-    _sessionName = null;
-    _sessionPeerCount = 0;
-    let meshClose = null;
-    try {
-        meshClose = meshNode?.close() ?? null;
-    }
-    catch {
-        /* best-effort */
-    }
-    try {
-        await meshClose;
-    }
-    catch {
-        /* best-effort */
-    }
-    ctx.ui.notify("[un-bien] Stopped (mesh + relay disconnected).", "info");
-    _refreshFooter(ctx);
-}
-async function _cmdList(ctx) {
-    const peers = await listPeers();
-    if (peers.length === 0) {
-        ctx.ui.notify("[un-bien] No paired devices.", "info");
-        return;
-    }
-    // Multi-channel (W2D): each peer is either `online` (channel attached
-    // right now) or `offline` (in peers.json but not connected). Replaces
-    // the singleton " (active)" marker that only ever marked one peer.
-    const lines = peers
-        .flatMap((record) => {
-        const inspected = _inspectPeerRecord(record);
-        if (!inspected)
-            return [];
-        const tag = inspected.runtimeKey !== null && _activePeers.has(inspected.runtimeKey)
-            ? " 🟢 online"
-            : " ⚪ offline";
-        return `• ${inspected.rawHandle.slice(0, 8)} — ${inspected.record.name}${tag}`;
-    })
-        .join("\n");
-    ctx.ui.notify(`[un-bien] Paired devices:\n${lines}`, "info");
-}
-async function _cmdRevoke(arg, ctx) {
-    const shortid = arg.trim();
-    if (!shortid) {
-        ctx.ui.notify("[un-bien] Usage: /unbien revoke <shortid>. Run /unbien list to see shortids.", "warning");
-        return;
-    }
-    // Revoke needs the relay so the revoked device's live channel is torn down
-    // — not just a silent peers.json edit. Auto-bootstrap the mesh + relay when
-    // down, mirroring `_cmdPair`.
-    const cwd = "cwd" in ctx ? ctx.cwd : "";
-    if (_state === "idle") {
-        if (!localConfigExists(cwd)) {
-            ctx.ui.notify("[un-bien] First-time setup needed. Run /unbien to configure, then /unbien revoke.", "warning");
-            return;
-        }
-        ctx.ui.notify("[un-bien] Starting mesh + relay before revoking…", "info");
-        if (!_meshNode)
-            await _cmdJoin(ctx);
-        if (_state === "idle")
-            await _cmdStart(ctx);
-    }
-    if (_state === "idle" || !_relay) {
-        ctx.ui.notify("[un-bien] Revoke requires the relay to be connected. " +
-            "Run /unbien to start it (or fix your relay URL via /unbien set-relay).", "warning");
-        return;
-    }
-    const matches = (await listPeers())
-        .map(_inspectPeerRecord)
-        .filter((peer) => peer !== null)
-        .filter((peer) => peer.rawHandle.startsWith(shortid));
-    if (matches.length === 0) {
-        ctx.ui.notify("[un-bien] No peer matching that shortid. Run /unbien devices to see shortids.", "warning");
-        return;
-    }
-    if (matches.length > 1) {
-        const collisions = matches
-            .map((peer) => peer.rawHandle.slice(0, 8))
-            .join(", ");
-        ctx.ui.notify(`[un-bien] Ambiguous shortid — ${matches.length} matches: ${collisions}. Use mais chars.`, "warning");
-        return;
-    }
-    const peer = matches[0];
-    await removePeer(peer.rawHandle);
-    _refreshPairingsCache();
-    // Storage removal uses the exact saved representation; the active channel
-    // is indexed by its canonical identity.
-    if (peer.runtimeKey !== null && _activePeers.has(peer.runtimeKey)) {
-        _detachPeerChannel(peer.runtimeKey);
-        _refreshFooter();
-    }
-    ctx.ui.notify(`[un-bien] Revoked: ${peer.record.name} (${peer.rawHandle.slice(0, 8)}…)`, "info");
-}
-async function _shortidCompletions(prefix, valuePrefix = "") {
-    const peers = (await listPeers())
-        .map(_inspectPeerRecord)
-        .filter((peer) => peer !== null);
-    return peers
-        .map((peer) => ({
-        shortid: peer.rawHandle.slice(0, 8),
-        name: peer.record.name,
-    }))
-        .filter((entry) => entry.shortid.startsWith(prefix))
-        .map((entry) => ({
-        value: `${valuePrefix}${entry.shortid}`,
-        label: `${entry.shortid} (${entry.name})`,
-    }));
-}
-function _cmdSetRelay(arg, ctx) {
-    const raw = arg.trim();
-    if (!raw) {
-        ctx.ui.notify("[un-bien] Usage: /unbien set-relay <http:// or https:// url>", "warning");
-        return;
-    }
-    if (isWebSocketScheme(raw)) {
-        ctx.ui.notify(`[un-bien] Use http:// or https://. The extension converts to WebSocket automatically.`, "error");
-        return;
-    }
-    if (!isValidRelayUrl(raw)) {
-        ctx.ui.notify(`[un-bien] Invalid URL: ${raw}. Must start with http:// or https://`, "error");
-        return;
-    }
-    saveConfig({ relay: raw });
-    ctx.ui.notify(`[un-bien] Relay set to ${raw}. Run /unbien relay stop then /unbien relay start to apply.`, "info");
-}
-/**
- * `/unbien config` — print the effective relay URL and where it came from.
- *
- * Documented in the README ("Verify the active URL and its source") and in
- * CLAUDE.md, but like the `relay` family (issue #119) it had no handler and
- * fell through to the status panel, which shows the URL but not the source —
- * so `env` vs `config` vs `default` was unverifiable without a restart.
- */
-function _cmdConfig(ctx) {
-    const { url, source } = resolveRelayUrl();
-    const origin = source === "env"
-        ? "UNBIEN_RELAY environment variable"
-        : source === "config"
-            ? "extensions/un-bien.json (set via /unbien set-relay)"
-            : "not set — run /unbien set-relay <url> or set UNBIEN_RELAY";
-    const live = _relayUrl && _relayUrl !== url
-        ? `\n  ⚠ Live connection still on ${_relayUrl} — run /unbien relay stop then /unbien relay start to apply.`
-        : "";
-    ctx.ui.notify(`[un-bien]\n  Relay URL: ${url ?? "(none)"}\n  Source: ${source} — ${origin}${live}`, "info");
-}
-/**
- * `/unbien identity` — report NON-SECRET identity state (active EPK, backend,
- * resolved source). The private seed is NEVER shown: command output is
- * LLM-visible, so extraction stays a manual `cat`/keychain op. Read-only
- * (never mints).
- */
-async function _cmdIdentity(ctx) {
-    const info = await describeIdentity();
-    const backendLine = info.backend === "file" ? `file (${info.filePath})` : "keychain";
-    const epkLine = info.epk ?? "(none yet — minted on first use)";
-    const sourceLine = info.detail
-        ? `${info.source} — ${info.detail}`
-        : info.source;
-    ctx.ui.notify(`[un-bien] identity\n  Backend: ${backendLine}\n  EPK (public): ${epkLine}\n  Source: ${sourceLine}`, info.source === "error" ? "error" : "info");
-}
-/**
- * `/unbien relay [start|stop|status|url <url>]` — issue #119.
- *
- * The README has always documented this family (`relay url` to point at a
- * self-hosted relay, `relay stop` + `relay start` to apply the change), but no
- * handler existed: every `relay …` invocation fell through the `else` in the
- * flat dispatcher and silently reprinted the status panel. Users following the
- * README believed they had switched relays and stayed on the community relay —
- * exactly the case where our own docs warn the operator sees routed plaintext.
- *
- * Verbs map onto the same primitives the RPC control channel already uses
- * (`_handleControl`), so the slash command and the Cockpit button can't drift:
- * relay-only up (`_cmdStart`) / relay-only down (`_goIdle`), never touching
- * local-mesh membership — that stays `/unbien stop`'s job.
- */
-async function _cmdRelay(arg, ctx) {
-    const raw = arg.trim();
-    const [verb, ...rest] = raw.split(/\s+/);
-    const value = rest.join(" ").trim();
-    switch (verb) {
-        case "":
-        case "toggle":
-            await _handleControl("relay:toggle");
-            ctx.ui.notify(`[un-bien] Relay ${_relayStatus()}.`, "info");
-            _refreshFooter(ctx);
-            return;
-        case "start":
-        case "on":
-            if (_getState() === "idle")
-                await _cmdStart(ctx);
-            else
-                ctx.ui.notify(`[un-bien] Relay already ${_relayStatus()}.`, "info");
-            _emitRelayState(true);
-            return;
-        case "stop":
-        case "off":
-            if (_getState() === "idle") {
-                ctx.ui.notify("[un-bien] Relay already disconnected.", "info");
-            }
-            else {
-                _goIdle();
-                ctx.ui.notify("[un-bien] Relay disconnected (local mesh untouched).", "info");
-            }
-            _emitRelayState(true);
-            _refreshFooter(ctx);
-            return;
-        case "status":
-            _cmdStatus(ctx);
-            _emitRelayState(true);
-            return;
-        case "url":
-            // Same writer as `set-relay` — one code path, so validation and the
-            // "restart to apply" hint can never diverge between the two spellings.
-            _cmdSetRelay(value, ctx);
-            return;
-        default:
-            ctx.ui.notify("[un-bien] Usage: /unbien relay [start|stop|status|url <http(s) url>]", "warning");
-            return;
-    }
-}
-// ── Install/uninstall the launcher-daemon service ────────────────────────────
-//
-// Installs the un-bien launcher daemon as a user-level system service (systemd
-// `--user` unit on Linux, launchd LaunchAgent on macOS, Task Scheduler on
-// Windows). Once installed the launcher daemon starts at login + survives
-// reboots. Uninstall is the inverse.
-/**
- * `linkCli` controls whether we symlink `un-bien` into `~/.local/bin/`. The
- * slash-command path passes `true` (user is inside Pi's TUI — they installed
- * via `pi install npm:un-bien` and need us to expose the CLI for them). The
- * standalone-CLI path passes `false` because the user is already running our
- * binary from PATH (they did `npm install -g un-bien`), so re-linking would
- * point their `un-bien` at the Pi-extension copy and diverge on upgrades.
- */
-/** Returns true on success, false when install failed (so the standalone CLI
- *  can exit non-zero — e.g. the Cockpit / CI detect failure by exit code).
- *  We do NOT process.exit here: this also runs inside the Pi TUI, where exiting
- *  would kill the session. */
-function _cmdInstall(ctx, opts = {}) {
-    const linkCli = opts.linkCli ?? false;
-    try {
-        const result = installService();
-        const sections = [
-            `[un-bien] Launcher daemon service installed (${result.platform}).`,
-            `  Unit: ${result.unitPath}`,
-            `  Steps:\n${result.log.map((l) => "    " + l).join("\n")}`,
-        ];
-        if (linkCli) {
-            const link = linkCliBinaries();
-            sections.push(`  CLI bins linked into ${link.binDir}:`, link.links.map((l) => `    ${l.name} → ${l.target}`).join("\n"), `  Steps:\n${link.log.map((l) => "    " + l).join("\n")}`);
-            if (!link.onPath) {
-                if (process.platform === "win32") {
-                    sections.push(`  ⚠ ${link.binDir} was just added to your user PATH (it wasn't there yet).`, `    Open a NEW terminal and run \`unbien status\` to verify.`);
-                }
-                else {
-                    sections.push(`  ⚠ ${link.binDir} is not on $PATH yet. Add this line to ~/.zshrc / ~/.bashrc:`, `      export PATH="$HOME/.local/bin:$PATH"`, `    Then open a new terminal and run \`unbien status\` to verify.`);
-                }
-            }
-        }
-        ctx.ui.notify(sections.join("\n"), "info");
-        return true;
-    }
-    catch (err) {
-        ctx.ui.notify(`[un-bien] install failed: ${String(err)}`, "error");
-        return false;
-    }
-}
-function _cmdUninstall(ctx, opts = {}) {
-    const linkCli = opts.linkCli ?? false;
-    try {
-        const result = uninstallService();
-        const sections = [
-            `[un-bien] Launcher daemon service uninstalled (${result.platform}).`,
-            `  Unit: ${result.unitPath} (${result.removed ? "removed" : "not present"})`,
-            `  Steps:\n${result.log.map((l) => "    " + l).join("\n")}`,
-        ];
-        if (linkCli) {
-            const unlink = unlinkCliBinaries();
-            sections.push(`  CLI bins cleanup (${unlink.binDir}):`, unlink.removed
-                .map((r) => `    ${r.name} (${r.existed ? "removed" : "not present"})`)
-                .join("\n"));
-        }
-        ctx.ui.notify(sections.join("\n"), "info");
-    }
-    catch (err) {
-        ctx.ui.notify(`[un-bien] uninstall failed: ${String(err)}`, "error");
-    }
-}
-// ── Agent-network commands (plano 19) ─────────────────────────────────────────
-function _resolveExtensionDir() {
-    // dist/index.js → dist; skills sit at <extensionRoot>/skills/. When we run
-    // from src/ via tsx (dev), index.ts is in src/ and skills/ is sibling. We
-    // detect by checking both locations.
-    const here = fileURLToPath(import.meta.url);
-    // dist/index.js or src/index.ts → parent = <dist or src>; sibling = ../skills
-    const parent = here.replace(/\/[^/]+$/, "");
-    const candidateA = join(parent, "..", "skills"); // dist → ../skills
-    const candidateB = join(parent, "skills"); // src → skills
-    if (existsSync(candidateA))
-        return parent.replace(/\/dist$/, "");
-    if (existsSync(candidateB))
-        return parent;
-    return parent;
-}
-function _deployAgentNetworkSkill() {
-    // Pi SDK spec (core/skills.js): every skill must live at
-    //   <skillsRoot>/<skill-name>/SKILL.md
-    // The skill `name:` frontmatter must equal the parent directory name. We
-    // ship the source pre-arranged that way so deploy is a straight copy into
-    // ~/.pi/un-bien/skills/agent-network/SKILL.md.
-    const root = _resolveExtensionDir();
-    const src1 = join(root, "skills", "agent-network", "SKILL.md");
-    const src2 = join(root, "..", "skills", "agent-network", "SKILL.md");
-    const src = existsSync(src1) ? src1 : existsSync(src2) ? src2 : null;
-    if (!src)
-        return;
-    const dstDir = join(skillsDir(), "agent-network");
-    const dst = join(dstDir, "SKILL.md");
-    try {
-        mkdirSync(dstDir, { recursive: true });
-        copyFileSync(src, dst);
-        // Cleanup legacy deploy at ~/.pi/un-bien/skills/agent-network.md (flat
-        // layout, fails the Pi SDK's name-vs-parent-dir validation).
-        const legacy = join(skillsDir(), "agent-network.md");
-        if (existsSync(legacy)) {
-            try {
-                unlinkSync(legacy);
-            }
-            catch {
-                /* ignored */
-            }
-        }
-    }
-    catch {
-        /* best-effort */
-    }
-}
 function _wakeAgent(content, label, steeringBehavior) {
     if (!_pi) {
         const detail = "agent session not bound yet";
@@ -4018,9 +2325,17 @@ function _wakeAgent(content, label, steeringBehavior) {
         return { ok: false, detail };
     }
     try {
-        const options = steeringBehavior
-            ? { deliverAs: steeringBehavior }
-            : undefined;
+        // expandPromptTemplates: true — TUI PARITY for app-sent text. pi's
+        // sendUserMessage defaults it to FALSE, so a "/"-prefixed message typed
+        // in the PHONE composer reached the MODEL as literal text (observed:
+        // "ignoring the two /unbien pair statements prior in the chat") instead
+        // of dispatching as a command like the same text typed in the TUI. pi's
+        // prompt() dispatches extension commands FIRST — even mid-stream — so
+        // steering a running turn with a command now behaves identically too.
+        const options = {
+            ...(steeringBehavior ? { deliverAs: steeringBehavior } : {}),
+            expandPromptTemplates: true,
+        };
         _pi.sendUserMessage(content, options);
         return { ok: true };
     }
@@ -4108,181 +2423,6 @@ function _deliverMeshMessageToAgent(env) {
     _pendingMeshMessages.push(env);
     _scheduleMeshMessageDrain();
 }
-/** Test-only entry point for verifying mesh-to-agent delivery semantics. */
-export function _deliverMeshMessageToAgentForTest(env) {
-    _deliverMeshMessageToAgent(env);
-}
-/**
- * Joins the fixed local UDS mesh ("local" session — see LOCAL_SESSION_NAME).
- * Called by `_cmdRoot` on first run and on subsequent runs when the relay
- * is up and the user hasn't explicitly stopped. The session name is no
- * longer user-configurable: every Pi on the same machine joins the same
- * broker.
- */
-async function _cmdJoin(ctx) {
-    const cwd = "cwd" in ctx ? ctx.cwd : process.cwd();
-    const local = loadLocalConfig(cwd);
-    const sessionName = LOCAL_SESSION_NAME;
-    // What the user configured for this agent…
-    const requestedName = local.agent_name || defaultAgentName(cwd);
-    // …and what we actually register: the name the cwd-lock reserved, which is
-    // `requestedName` or a `#N` variant when same-named agents share this folder.
-    // Falls back to requestedName when join runs without a prior `_cmdRoot` lock
-    // (e.g. legacy/test paths).
-    const agentName = _lockedName ?? requestedName;
-    if (_meshNode) {
-        ctx.ui.notify("[un-bien] Already on the local mesh.", "warning");
-        return;
-    }
-    const joinGeneration = ++_meshJoinGeneration;
-    ensureGlobalDirs();
-    mkdirSync(join(skillsDir(), "..", "sessions", sessionName), {
-        recursive: true,
-    });
-    const sock = sessionSockPath(sessionName);
-    const audit = sessionAuditPath(sessionName);
-    // Forward the cwd so the broker keys this peer by (cwd, name): a same-folder
-    // same-name reincarnation (switch_session re-eval, app restart) takes over the
-    // name instead of registering behind a mute `name#N` ghost. Canonicalize via
-    // realpath so symlinked cwds map to one identity (matches roomIdForCwd).
-    let canonCwd = cwd;
-    try {
-        canonCwd = realpathSync(cwd);
-    }
-    catch {
-        /* cwd missing — use raw path */
-    }
-    const peer = new MeshNode({
-        sockPath: sock,
-        name: agentName,
-        cwd: canonCwd,
-        auditPath: audit,
-        takeoverExisting: process.env["UNBIEN_DAEMON"] === "1",
-    });
-    peer.onMessage((env) => {
-        const body = env.body;
-        // Broker system events: re-query broker for authoritative count.
-        // Incremental ±1 drifts when peer_left is missed (leader leaves cleanly,
-        // failover, etc.) — querying list_peers makes the count self-healing.
-        if (body && (body.type === "peer_joined" || body.type === "peer_left")) {
-            _refreshSessionPeerCount(peer, ctx);
-            // Plan/25 Wave B: push fresh peer list to all siblings so their
-            // remotePeers cache stays current without polling.
-            void peer
-                .request("broker", { type: "list_peers" }, 2000)
-                .then((reply) => {
-                const body = reply.body;
-                // onLocalPeersChanged wants LOCAL-only addresses (list_peers returns
-                // the aggregated local + cross-PC roster). Prefer the structured
-                // roster (plan/38): a local peer has no `pc`. This is drive-letter
-                // safe — a Windows local address `C:\…@app` contains ':' but is NOT
-                // remote, so the old naive `!p.includes(":")` misclassified it.
-                let local = null;
-                const detailed = body?.peers_detailed;
-                if (Array.isArray(detailed)) {
-                    local = detailed
-                        .filter((p) => !p.pc && typeof p.address === "string")
-                        .map((p) => p.address);
-                }
-                else if (Array.isArray(body?.peers)) {
-                    // Fallback for a legacy broker without `peers_detailed`.
-                    local = body.peers.filter((p) => !p.includes(":"));
-                }
-                // No-op when the bridge isn't up (follower / relay down).
-                if (local)
-                    peer.onLocalPeersChanged(local);
-            })
-                .catch(() => {
-                /* bridge not bound yet, or list_peers failed */
-            });
-            return;
-        }
-        if (env.from === "broker")
-            return; // other broker control messages — ignore
-        // Real agent-to-agent message (SessionPeer already correlated replies via
-        // env.re before this point). Show it in the app's TOOL timeline and wake
-        // the agent as a CUSTOM message — never as the user's own message.
-        _deliverMeshMessageToAgent(env);
-    });
-    // After failover (leader died, we re-elected): the new broker's peers map
-    // starts fresh, but our cached `_sessionPeerCount` is stale. Re-seed it so
-    // surviving peers don't carry the pre-failover count forever.
-    //
-    // The cross-PC bridge re-attach on failover (drop the stale broker ref,
-    // re-wire against the fresh `localBroker()` if we were promoted to leader)
-    // is handled INSIDE MeshNode — no manual teardown/ensure needed here.
-    peer.onReconnect(() => {
-        _refreshSessionPeerCount(peer, ctx);
-    });
-    const isCurrentCandidate = () => !_disposed && joinGeneration === _meshJoinGeneration && _meshNode === null;
-    try {
-        const assigned = await peer.connect();
-        // The candidate stays local until connect resolves. Shutdown, stop, or a
-        // newer join invalidates its generation; close it instead of publishing a
-        // ghost peer or allowing _cmdRoot to continue into Relay startup.
-        if (!isCurrentCandidate()) {
-            try {
-                await peer.close();
-            }
-            catch {
-                /* best-effort */
-            }
-            return;
-        }
-        _meshNode = peer;
-        _sessionName = sessionName;
-        _sessionPeerCount = 1; // optimistic — overwritten by list_peers below
-        // Broker broadcasts `peer_joined` only to existing peers when a new one
-        // arrives — the newcomer doesn't get retroactive joined events. Ask the
-        // broker for the live peer list to seed the count correctly on join.
-        _refreshSessionPeerCount(peer, ctx);
-        // Tell RPC clients (e.g. Cockpit) the EFFECTIVE mesh name. The broker
-        // appends a `#N` suffix only on a same-(cwd,name) collision, so the name we
-        // requested and the one actually assigned can differ. Emit a pure-data event
-        // (display:false) carrying both + a `changed` flag so the client can rename
-        // the agent in its own UI to match what the mesh/relay will show. Fired on
-        // every join (incl. failover re-elect, which can re-assign the name), so the
-        // client always reflects the live name, not just the first one.
-        //
-        // plan/38 decision E: we deliberately DO NOT persist `assigned`. A `#N` is a
-        // RUNTIME collision resolution; freezing it into `agent_name` fossilizes an
-        // accident and causes cross-folder name ping-pong across restarts. The clean
-        // name (wizard / explicit `agent_name`) already lives in config or re-derives
-        // from `basename(cwd)`; the event above carries the live `#N` for the UI.
-        _pi?.sendMessage({
-            customType: "un-bien:name-assigned",
-            content: assigned === requestedName
-                ? `Mesh name: ${assigned}`
-                : `Mesh name reassigned: "${requestedName}" → "${assigned}" (collision)`,
-            details: {
-                requested: requestedName,
-                assigned,
-                changed: assigned !== requestedName,
-            },
-            display: false,
-        });
-        ctx.ui.notify(`[un-bien] Joined local mesh as "${assigned}" (${peer.currentRole()})`, "info");
-        _refreshFooter(ctx);
-        // Plan/25 Wave B/C: try to bring up cross-PC routing now that the
-        // local broker exists. No-op if the relay isn't up yet (will fire
-        // again from `_cmdStart`).
-        _attachBridgeIfReady();
-    }
-    catch (err) {
-        // A replacement/stop/newer join can invalidate this candidate before its
-        // failure arrives. Clean it up and never notify the outgoing session ctx.
-        if (!isCurrentCandidate()) {
-            try {
-                await peer.close();
-            }
-            catch {
-                /* best-effort */
-            }
-            return;
-        }
-        ctx.ui.notify(`[un-bien] join failed: ${String(err)}`, "error");
-    }
-}
 // ── routeClientMessage ────────────────────────────────────────────────────────
 /**
  * Per-channel router. Replaces the W2D-pre `routeClientMessage` which
@@ -4296,7 +2436,7 @@ async function _cmdJoin(ctx) {
  * handles incoming app→pi requests.
  */
 function _abortCurrentTurn(fallbackCtx) {
-    const candidates = [_lastEventCtx, _lastCtx, fallbackCtx];
+    const candidates = [_lastEventCtx, fallbackCtx];
     for (const candidate of candidates) {
         if (!candidate || candidate === _noopCtx)
             continue;
@@ -4380,24 +2520,10 @@ export function routeClientMessage(msg, ctx) {
  * also dump history to owner B's wire — duplicate traffic + the wrong
  * `in_reply_to`.
  */
-/**
- * Resets the Pi-side session view after a SUCCESSFUL `session_new`. The app's
- * New Session clears its local store on `action_ok`, but that alone isn't
- * durable: `_messageBuffer` (which answers `session_sync`) is append-only and
- * `_sessionStartedAt` is stamped once, so a later reconnect/restart would
- * replay the OLD history. We clear the buffer and restamp the clock so the
- * envelope `session_sync` reconstructs from a clean slate. The app drops the
- * stale conversation off the new-session `hello` (changed `sessionId`).
- */
-function _resetSessionForNew() {
-    // Restamp the session clock so the app detects the pi restart (session_sync_end
-    // carries it). The transcript resets naturally: the app re-fetches via
-    // get_entries against the fresh session and drops the old one on the new hello.
-    _sessionStartedAt = Date.now();
-}
-/** Resolve the base dir for tool-arg file lookups from the last command ctx. */
+/** Resolve the base dir for tool-arg file lookups from the current session. */
 function _resolveToolCwd() {
-    return _lastCtx && "cwd" in _lastCtx ? _lastCtx.cwd : process.cwd();
+    const sm = _rootState().sessionManager;
+    return sm && typeof sm.getCwd === "function" ? sm.getCwd() : process.cwd();
 }
 // ── Standalone CLI ────────────────────────────────────────────────────────────
 function _isDirectRun() {
@@ -4599,150 +2725,4 @@ if (_isDirectRun()) {
         ].join("\n"));
     }
 }
-// ── `unbien claude` — launch Claude Code connected to the mesh ─────────────
-/**
- * Resolve the packaged agent-network skill path
- * (`<pkgRoot>/skills/agent-network/SKILL.md`). Single source of truth shared
- * by both runtimes: Pi discovers it via `resources_discover`, and the Claude
- * launcher injects it as a system prompt (see `_cmdClaudeCli`). Returns null
- * if the file is missing (e.g. running before `pnpm build`).
- */
-function _agentNetworkSkillPath() {
-    const here = fileURLToPath(import.meta.url); // dist/index.js (or src/index.ts via tsx)
-    const pkgRoot = dirname(dirname(here)); // package root (dist → ..; src → ..)
-    const skill = join(pkgRoot, "skills", "agent-network", "SKILL.md");
-    return existsSync(skill) ? skill : null;
-}
-async function _cmdClaudeCli(args) {
-    // Contract: `unbien claude [cwd] [claude-flags...]`. The optional cwd is
-    // ONLY the leading positional (first token, not a flag); everything after it
-    // is forwarded verbatim to the `claude` binary (e.g. `--resume`, `-c`,
-    // `-p "prompt"`). Restricting cwd to the leading token avoids mistaking a
-    // flag's value (e.g. the id in `--resume <id>`) for the cwd.
-    const hasCwdArg = args.length > 0 && !args[0].startsWith("-");
-    const targetCwd = hasCwdArg ? args[0] : process.cwd();
-    const passthroughArgs = hasCwdArg ? args.slice(1) : args;
-    // Wizard when no local config exists
-    if (!localConfigExists(targetCwd)) {
-        const suggested = defaultAgentName(targetCwd);
-        process.stdout.write(`\n[un-bien] No config found for ${targetCwd}\n`);
-        process.stdout.write("Let's set up this agent.\n\n");
-        const rl = createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        const agentName = await new Promise((res) => rl.question(`Agent name [${suggested}]: `, (ans) => {
-            rl.close();
-            res(ans.trim() || suggested);
-        }));
-        saveLocalConfig(targetCwd, {
-            agent_name: agentName,
-            auto_start_relay: true,
-        });
-        process.stdout.write(`[un-bien] Config saved: agent="${agentName}"\n\n`);
-    }
-    // Resolve mesh server script path (dist/mcp/mesh_server.js)
-    const here = fileURLToPath(import.meta.url);
-    const distRoot = dirname(here);
-    const meshServerPath = resolve(distRoot, "mcp/mesh_server.js");
-    if (!existsSync(meshServerPath)) {
-        console.log(`[un-bien] mesh server not found at ${meshServerPath}. Run pnpm build first.`);
-        process.exit(1);
-    }
-    const absCwd = resolve(targetCwd);
-    const SERVER_NAME = "un-bien-mesh";
-    // The mesh MCP must be visible ONLY inside a `unbien claude` session — a
-    // plain `claude` in the same repo must NOT inherit it (otherwise every
-    // ordinary session silently joins the mesh as a stray agent).
-    //
-    // Older builds registered the server with `claude mcp add -s local`. That
-    // scope lives in `~/.claude.json` keyed by the **git repo root** and is
-    // inherited by EVERY claude session under that root — which is exactly the
-    // leak we're closing. So we no longer write any persistent scope; we load
-    // the server through an ephemeral `--mcp-config <tmpfile>` passed on the
-    // launch command line (see below). That config is session-only: it is never
-    // recorded in any scope `claude mcp list` enumerates, so a normal `claude`
-    // sees nothing.
-    //
-    // Migration: best-effort scrub of the stale `-s local` entry that prior
-    // versions left behind (and that is the source of the inherited-mesh bug).
-    // Idempotent — a no-op (non-zero, ignored) when the entry is already gone.
-    spawnSync("claude", ["mcp", "remove", SERVER_NAME, "-s", "local"], {
-        cwd: absCwd,
-        stdio: "ignore",
-        shell: false,
-    });
-    // Ephemeral MCP config consumed by `--mcp-config` below. We do NOT bake a
-    // `cwd` into it: the server resolves its folder from its own `process.cwd()`,
-    // which Claude sets to the directory the session was launched in (verified
-    // empirically — NOT the git root, NOT CLAUDE_PROJECT_DIR). We spawn claude
-    // with `cwd: absCwd`, the MCP child inherits it, so the server self-identifies
-    // as the right agent without leaking that path to any other session.
-    // Unique per pid so concurrent `unbien claude` launches don't collide.
-    const mcpConfigPath = join(tmpdir(), `un-bien-mesh-mcp-${process.pid}.json`);
-    writeFileSync(mcpConfigPath, JSON.stringify({
-        mcpServers: {
-            [SERVER_NAME]: { command: process.execPath, args: [meshServerPath] },
-        },
-    }));
-    // Inject the agent-network protocol as a system prompt instead of deploying a
-    // skill file into ~/.claude. Anyone running `unbien claude` is here to use
-    // the mesh, so load the protocol unconditionally — no lazy skill gating, no
-    // global skills-dir pollution, and the packaged file is the single source of
-    // truth shared with the Pi runtime. Skipped only if the file is missing.
-    const skillPath = _agentNetworkSkillPath();
-    // Launch flags:
-    //   --mcp-config <tmpfile>                       — load the mesh server for
-    //       THIS session only (never a persistent scope). We intentionally omit
-    //       `--strict-mcp-config` so the user's own persistent MCP servers stay
-    //       available alongside the mesh.
-    //   --dangerously-load-development-channels TAG  — enable claude/channel push
-    //       for our local (non-allowlisted) server, so incoming mesh messages
-    //       wake Claude instead of waiting for a get_messages poll. Entries must
-    //       be tagged: `server:<name>` for a manually configured MCP server
-    //       (`plugin:<name>@<marketplace>` is the plugin form). Shows a one-time
-    //       confirmation dialog at startup. Works against the `--mcp-config`
-    //       server in current Claude Code; if a build ever fails to match it, the
-    //       per-turn `get_messages` poll (mandated by the mesh protocol) still
-    //       delivers — we lose the wake, not the messages.
-    //   --dangerously-skip-permissions               — auto-approve tool calls
-    //   --append-system-prompt-file=<skill>           — load the mesh protocol
-    // `--append-system-prompt-file` uses the glued `--flag=value` form (a SINGLE
-    // argv token) on purpose: tools that restore a session by capturing and
-    // replaying the live process's argv (e.g. cmux) drop the TRAILING token,
-    // which here was the skill path — leaving a dangling `--append-system-prompt-file`
-    // → `claude` aborts with "argument missing" and the session never comes back.
-    // As one token, the worst case is the whole flag being dropped: claude still
-    // starts (just without the injected protocol), which is recoverable instead
-    // of fatal. (The other flags stay separate pairs — never last, so unaffected,
-    // and we don't risk a parser that may not accept `=`.)
-    // Any extra args the user passed (e.g. `--resume`, `-c`) are appended last so
-    // they reach the claude binary; ours come first as sensible defaults.
-    try {
-        spawnSync("claude", [
-            "--mcp-config",
-            mcpConfigPath,
-            "--dangerously-load-development-channels",
-            `server:${SERVER_NAME}`,
-            "--dangerously-skip-permissions",
-            ...(skillPath ? [`--append-system-prompt-file=${skillPath}`] : []),
-            ...passthroughArgs,
-        ], {
-            cwd: absCwd,
-            stdio: "inherit",
-            shell: false,
-        });
-    }
-    finally {
-        // Session over — drop the ephemeral config so it never lingers as a stray
-        // file. spawnSync blocks until claude exits, so claude has long since read
-        // it. Best-effort: ignore if already gone.
-        try {
-            unlinkSync(mcpConfigPath);
-        }
-        catch {
-            /* already removed */
-        }
-    }
-}
 //# sourceMappingURL=index.js.map