ftown-bridge 0.19.44 → 0.19.49

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command as Commander } from 'commander';
+import { Command as Commander, CommanderError } from 'commander';
 import { v4 as uuidv4 } from 'uuid';
 import { resolve, dirname, join } from 'node:path';
 import { hostname as osHostname, networkInterfaces, homedir } from 'node:os';
@@ -16,6 +16,7 @@ import { ProcessRunner } from './claude-runner.js';
 import { SessionStore } from './session-store.js';
 import { MailStore } from './mail-store.js';
 import { AttentionStore } from './attention-store.js';
+import { BridgePushNotifier } from './push-notifier.js';
 import { LocalApiServer } from './local-api-server.js';
 import { BrowserAccess } from './browser-access.js';
 import { registerLocalBrowserCommands } from './local-pair-cli.js';
@@ -42,6 +43,7 @@ import { DEFAULT_SOLO_PORT, SOLO_USER_ID } from './solo/contract.js';
 import { ensureHubBinary, startHub, stopHub, writeHubConfig } from './solo/hub-manager.js';
 import { ensurePanelBundle, findPanelServerDir, normalizePanelVersion, startPanel, stopPanel, } from './solo/panel-manager.js';
 import { createSoloServer } from './solo/solo-server.js';
+import { executeCli, isCliEntry } from './cli-entry.js';
 /** Bridge package version — doubles as the default panel bundle version. */
 const BRIDGE_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version;
 /** LAN IPv4 addresses for the solo banner (loopback excluded). */
@@ -65,722 +67,768 @@ function isLoopbackOnly(ips) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const DEFAULT_API_URL = 'https://ftown.ia.br';
-const program = new Commander();
-program
-    .name('ftown-bridge')
-    .description('ftown orchestrator bridge for Centrifugo')
-    .option('--local', 'Local browser control only: no cloud account or connection')
-    .option('--solo', 'Single-port LAN deployment: no account service, managed hub + panel children, key-based auth')
-    .option('--port <port>', 'Public port for --solo front (default: see DEFAULT_SOLO_PORT)')
-    .option('--rotate-key', 'With --solo: regenerate the access key, print the new banner, exit (offline)')
-    .option('--token <jwt>', 'Bridge bootstrap token from the ftown dashboard (short-lived; used once to onboard, then a rotating refresh token is stored). Optional: with no token and no stored refresh token, the bridge runs interactive device pairing instead.')
-    .option('--api-url <url>', 'ftown UI API URL', DEFAULT_API_URL)
-    .option('--data-dir <path>', 'Directory for session data (default: ~/.ftown/data)')
-    .option('--bridge-id <id>', 'Bridge instance ID (default: persisted per data dir)')
-    .action(async (opts) => {
-    if (opts.local && opts.solo)
-        program.error('--local and --solo cannot be combined');
-    const apiUrl = new URL(opts.apiUrl);
-    const isLocalHost = apiUrl.hostname === 'localhost' ||
-        apiUrl.hostname === '127.0.0.1' ||
-        apiUrl.hostname === '::1' ||
-        apiUrl.hostname.endsWith('.localhost');
-    if (apiUrl.protocol !== 'https:' && !isLocalHost && process.env.FTOWN_ALLOW_INSECURE_API !== '1') {
-        program.error(`--api-url must use https:// for non-local hosts (${opts.apiUrl}). ` +
-            'Bridge tokens would otherwise cross the network unencrypted. ' +
-            'Set FTOWN_ALLOW_INSECURE_API=1 to override for trusted LAN setups.');
-    }
-    // Explicit setup must finish before any migration, identity, network or auth side effect.
-    assertSetupReady(BRIDGE_VERSION);
-    // Read-only default resolution; explicit setup owns legacy data migration.
-    const defaultDataDir = resolveDefaultDataDir();
-    const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir;
-    // Instance-scoped ".ftown home" for pointer and registry files. The DEFAULT
-    // data dir resolves to $HOME/.ftown (unchanged — the harness CLIs hardcode
-    // that path). A non-default --data-dir (Solo test, Docker, a second bridge)
-    // gets its own home so it never touches the primary bridge's bridge.json,
-    // or session-registry.json. Configure the store
-    // singletons ONCE here, before any of them is read/written.
-    const ftownHome = resolveFtownHome(dataDir, defaultDataDir);
-    configureSessionRegistryHome(ftownHome);
-    // Bridge identity sticks to the data dir so a plain restart auto-resumes:
-    // same id → same dashboard entry, sessions reattach without any flags.
-    const bridgeIdPath = join(dataDir, 'bridge-id');
-    let persistedBridgeId;
-    try {
-        persistedBridgeId = readFileSync(bridgeIdPath, 'utf8').trim() || undefined;
-    }
-    catch {
-        persistedBridgeId = undefined;
-    }
-    const bridgeId = opts.bridgeId ?? persistedBridgeId ?? uuidv4();
-    try {
-        mkdirSync(dataDir, { recursive: true });
-        writeFileSync(bridgeIdPath, `${bridgeId}\n`, { mode: 0o600 });
-    }
-    catch (err) {
-        console.error('[Bridge] Failed to persist bridge id:', err instanceof Error ? err.message : String(err));
-    }
-    // L4: --rotate-key short-circuits BEFORE any listener binds (exit 0,
-    // nothing started). Without --solo it is an argument error.
-    if (opts.rotateKey && !opts.solo) {
-        program.error('--rotate-key requires --solo');
-    }
-    if (opts.solo && opts.rotateKey) {
-        const raw = generateAccessKey().raw;
-        mkdirSync(join(dataDir, 'solo'), { recursive: true, mode: 0o700 });
-        writeFileSync(join(dataDir, 'solo', 'access-key-hash'), `${sha256Hex(raw)}\n`, { mode: 0o600 });
-        const port = opts.port ? Number(opts.port) : DEFAULT_SOLO_PORT;
-        console.log('========================================');
-        console.log('  ftown SOLO — access key rotated');
-        for (const ip of networkInterfacesForBanner()) {
-            console.log(`  Open:   http://${ip}:${port}/#k=${raw}`);
+export async function runBridge(argv, commandName = 'ftown-bridge') {
+    const program = new Commander();
+    program.exitOverride();
+    program
+        .name(commandName)
+        .description('ftown orchestrator bridge for Centrifugo')
+        .option('--local', 'Local browser control only: no cloud account or connection')
+        .option('--solo', 'Single-port LAN deployment: no account service, managed hub + panel children, key-based auth')
+        .option('--port <port>', 'Public port for --solo front (default: see DEFAULT_SOLO_PORT)')
+        .option('--rotate-key', 'With --solo: regenerate the access key, print the new banner, exit (offline)')
+        .option('--token <jwt>', 'Bridge bootstrap token from the ftown dashboard (short-lived; used once to onboard, then a rotating refresh token is stored). Optional: with no token and no stored refresh token, the bridge runs interactive device pairing instead.')
+        .option('--api-url <url>', 'ftown UI API URL', DEFAULT_API_URL)
+        .option('--data-dir <path>', 'Directory for session data (default: ~/.ftown/data)')
+        .option('--bridge-id <id>', 'Bridge instance ID (default: persisted per data dir)')
+        .action(async (opts) => {
+        if (opts.local && opts.solo)
+            program.error('--local and --solo cannot be combined');
+        const apiUrl = new URL(opts.apiUrl);
+        const isLocalHost = apiUrl.hostname === 'localhost' ||
+            apiUrl.hostname === '127.0.0.1' ||
+            apiUrl.hostname === '::1' ||
+            apiUrl.hostname.endsWith('.localhost');
+        if (apiUrl.protocol !== 'https:' && !isLocalHost && process.env.FTOWN_ALLOW_INSECURE_API !== '1') {
+            program.error(`--api-url must use https:// for non-local hosts (${opts.apiUrl}). ` +
+                'Bridge tokens would otherwise cross the network unencrypted. ' +
+                'Set FTOWN_ALLOW_INSECURE_API=1 to override for trusted LAN setups.');
         }
-        console.log('========================================');
-        process.exit(0);
-    }
-    // The local API server binds before the token fetch: its ephemeral port and
-    // the per-process loopback nonce ride the auth request so the UI can embed
-    // them in the Centrifugo connection JWT `info` claim (presence advert, L2).
-    // Binding needs no post-auth state — dependencies/routes are wired later.
-    const localApiServer = new LocalApiServer();
-    const apiToken = randomBytes(32).toString('hex');
-    localApiServer.setAuthToken(apiToken);
-    // Reuse the local port so remembered browsers survive restarts. If another
-    // process took it, the server chooses an available port and pair prints it.
-    const localPortPath = join(dataDir, 'local-api-port');
-    let preferredLocalPort = 0;
-    try {
-        const saved = Number(readFileSync(localPortPath, 'utf8').trim());
-        if (Number.isInteger(saved) && saved > 0 && saved <= 65535)
-            preferredLocalPort = saved;
-    }
-    catch { /* first start */ }
-    const hookPort = await localApiServer.start(preferredLocalPort);
-    writeFileSync(localPortPath, `${hookPort}\n`, { mode: 0o600 });
-    console.log(`[Bridge] Local API server started on port ${hookPort}`);
-    const localNonce = randomBytes(16).toString('hex');
-    // ----- SOLO MODE (contract: bridge/src/solo/contract.ts, lifecycle L1-L4) -----
-    let solo;
-    if (opts.solo) {
-        const hubSecretPath = join(dataDir, 'solo', 'hub-secret');
-        let hubSecret;
+        // Explicit setup must finish before any migration, identity, network or auth side effect.
+        assertSetupReady(BRIDGE_VERSION);
+        // Read-only default resolution; explicit setup owns legacy data migration.
+        const defaultDataDir = resolveDefaultDataDir();
+        const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir;
+        // Instance-scoped ".ftown home" for pointer and registry files. The DEFAULT
+        // data dir resolves to $HOME/.ftown (unchanged — the harness CLIs hardcode
+        // that path). A non-default --data-dir (Solo test, Docker, a second bridge)
+        // gets its own home so it never touches the primary bridge's bridge.json,
+        // or session-registry.json. Configure the store
+        // singletons ONCE here, before any of them is read/written.
+        const ftownHome = resolveFtownHome(dataDir, defaultDataDir);
+        configureSessionRegistryHome(ftownHome);
+        // Bridge identity sticks to the data dir so a plain restart auto-resumes:
+        // same id → same dashboard entry, sessions reattach without any flags.
+        const bridgeIdPath = join(dataDir, 'bridge-id');
+        let persistedBridgeId;
         try {
-            hubSecret = readFileSync(hubSecretPath, 'utf8').trim();
+            persistedBridgeId = readFileSync(bridgeIdPath, 'utf8').trim() || undefined;
         }
         catch {
-            hubSecret = randomBytes(32).toString('hex');
-            mkdirSync(dirname(hubSecretPath), { recursive: true, mode: 0o700 });
-            writeFileSync(hubSecretPath, `${hubSecret}\n`, { mode: 0o600 });
+            persistedBridgeId = undefined;
         }
-        // Key lifecycle (S1/S11): raw key exists only in memory at generation and
-        // in the one-time banner. Persisted state is the hash alone. Rotation is
-        // handled by the L4 short-circuit above; here a missing hash means FIRST
-        // boot — generate fresh so the banner can print the full link.
-        const keyHashPath = join(dataDir, 'solo', 'access-key-hash');
-        let accessKeyRaw;
-        let accessKeyHash;
+        const bridgeId = opts.bridgeId ?? persistedBridgeId ?? uuidv4();
         try {
-            accessKeyHash = readFileSync(keyHashPath, 'utf8').trim();
+            mkdirSync(dataDir, { recursive: true });
+            writeFileSync(bridgeIdPath, `${bridgeId}\n`, { mode: 0o600 });
         }
-        catch {
-            accessKeyRaw = generateAccessKey().raw;
-            accessKeyHash = sha256Hex(accessKeyRaw);
+        catch (err) {
+            console.error('[Bridge] Failed to persist bridge id:', err instanceof Error ? err.message : String(err));
         }
-        mkdirSync(join(dataDir, 'solo'), { recursive: true, mode: 0o700 });
-        writeFileSync(keyHashPath, `${accessKeyHash}\n`, { mode: 0o600 });
-        // Ephemeral private ports for children: probe free ports on loopback so
-        // collisions are practically impossible (contract "Ports" block).
-        const probeFreePort = () => new Promise((resolveP, rejectP) => {
-            const srv = createServer();
-            srv.listen(0, '127.0.0.1', () => {
-                const addr = srv.address();
-                if (!addr || typeof addr === 'string') {
-                    srv.close(() => rejectP(new Error('Failed to allocate child port')));
-                    return;
+        // L4: --rotate-key short-circuits BEFORE any listener binds (exit 0,
+        // nothing started). Without --solo it is an argument error.
+        if (opts.rotateKey && !opts.solo) {
+            program.error('--rotate-key requires --solo');
+        }
+        if (opts.solo && opts.rotateKey) {
+            const raw = generateAccessKey().raw;
+            mkdirSync(join(dataDir, 'solo'), { recursive: true, mode: 0o700 });
+            writeFileSync(join(dataDir, 'solo', 'access-key-hash'), `${sha256Hex(raw)}\n`, { mode: 0o600 });
+            const port = opts.port ? Number(opts.port) : DEFAULT_SOLO_PORT;
+            console.log('========================================');
+            console.log('  ftown SOLO — access key rotated');
+            for (const ip of networkInterfacesForBanner()) {
+                console.log(`  Open:   http://${ip}:${port}/#k=${raw}`);
+            }
+            console.log('========================================');
+            process.exit(0);
+        }
+        // The local API server binds before the token fetch: its ephemeral port and
+        // the per-process loopback nonce ride the auth request so the UI can embed
+        // them in the Centrifugo connection JWT `info` claim (presence advert, L2).
+        // Binding needs no post-auth state — dependencies/routes are wired later.
+        const localApiServer = new LocalApiServer();
+        const apiToken = randomBytes(32).toString('hex');
+        localApiServer.setAuthToken(apiToken);
+        // Reuse the local port so remembered browsers survive restarts. If another
+        // process took it, the server chooses an available port and pair prints it.
+        const localPortPath = join(dataDir, 'local-api-port');
+        let preferredLocalPort = 0;
+        try {
+            const saved = Number(readFileSync(localPortPath, 'utf8').trim());
+            if (Number.isInteger(saved) && saved > 0 && saved <= 65535)
+                preferredLocalPort = saved;
+        }
+        catch { /* first start */ }
+        const hookPort = await localApiServer.start(preferredLocalPort);
+        writeFileSync(localPortPath, `${hookPort}\n`, { mode: 0o600 });
+        console.log(`[Bridge] Local API server started on port ${hookPort}`);
+        const localNonce = randomBytes(16).toString('hex');
+        // ----- SOLO MODE (contract: bridge/src/solo/contract.ts, lifecycle L1-L4) -----
+        let solo;
+        if (opts.solo) {
+            const hubSecretPath = join(dataDir, 'solo', 'hub-secret');
+            let hubSecret;
+            try {
+                hubSecret = readFileSync(hubSecretPath, 'utf8').trim();
+            }
+            catch {
+                hubSecret = randomBytes(32).toString('hex');
+                mkdirSync(dirname(hubSecretPath), { recursive: true, mode: 0o700 });
+                writeFileSync(hubSecretPath, `${hubSecret}\n`, { mode: 0o600 });
+            }
+            // Key lifecycle (S1/S11): raw key exists only in memory at generation and
+            // in the one-time banner. Persisted state is the hash alone. Rotation is
+            // handled by the L4 short-circuit above; here a missing hash means FIRST
+            // boot — generate fresh so the banner can print the full link.
+            const keyHashPath = join(dataDir, 'solo', 'access-key-hash');
+            let accessKeyRaw;
+            let accessKeyHash;
+            try {
+                accessKeyHash = readFileSync(keyHashPath, 'utf8').trim();
+            }
+            catch {
+                accessKeyRaw = generateAccessKey().raw;
+                accessKeyHash = sha256Hex(accessKeyRaw);
+            }
+            mkdirSync(join(dataDir, 'solo'), { recursive: true, mode: 0o700 });
+            writeFileSync(keyHashPath, `${accessKeyHash}\n`, { mode: 0o600 });
+            // Ephemeral private ports for children: probe free ports on loopback so
+            // collisions are practically impossible (contract "Ports" block).
+            const probeFreePort = () => new Promise((resolveP, rejectP) => {
+                const srv = createServer();
+                srv.listen(0, '127.0.0.1', () => {
+                    const addr = srv.address();
+                    if (!addr || typeof addr === 'string') {
+                        srv.close(() => rejectP(new Error('Failed to allocate child port')));
+                        return;
+                    }
+                    srv.close(() => resolveP(addr.port));
+                });
+                srv.on('error', rejectP);
+            });
+            const hubPort = await probeFreePort();
+            const panelPort = await probeFreePort();
+            const soloConfig = {
+                port: opts.port ? Number(opts.port) : DEFAULT_SOLO_PORT,
+                hubPort,
+                panelPort,
+                dataDir,
+                accessKeyHash,
+                hubSecret,
+            };
+            const hubHealthy = { up: false };
+            const panelHealthy = { up: false };
+            const front = await createSoloServer({
+                config: soloConfig,
+                localApiPort: hookPort,
+                hub: { isHealthy: () => hubHealthy.up },
+                panel: { isHealthy: () => panelHealthy.up },
+            });
+            // Children ensured asynchronously AFTER the front listens (L1). The hub
+            // must be healthy before the Centrifugo client connects — gated below.
+            const soloDir = join(dataDir, 'solo');
+            const hubReady = (async () => {
+                const binPath = await ensureHubBinary({ dataDir });
+                const configPath = join(soloDir, 'centrifugo.json');
+                await writeHubConfig(configPath, { port: hubPort, secret: hubSecret });
+                await startHub({ configPath, binPath, dataDir });
+                hubHealthy.up = true;
+                console.log('[Solo] Hub is up (private port)');
+            })();
+            hubReady.catch((err) => {
+                console.error('[Solo] Hub failed to start:', err instanceof Error ? err.message : String(err));
+            });
+            // Panel version defaults to the bare bridge version (release-tag
+            // parity — panelBundleUrl's template already supplies the `v` prefix
+            // for the tag segment); override with FTOWN_SOLO_PANEL_VERSION for
+            // development. Either source may be typed with a leading `v`, so both
+            // are normalized to the bare semver panelBundleUrl expects.
+            const panelVersion = normalizePanelVersion(process.env.FTOWN_SOLO_PANEL_VERSION ?? BRIDGE_VERSION);
+            const panelReady = (async () => {
+                if (process.env.FTOWN_SOLO_PANEL_DIR) {
+                    // Dev escape hatch: serve an already-built standalone directory.
+                    const serverDir = await findPanelServerDir(resolve(process.env.FTOWN_SOLO_PANEL_DIR));
+                    console.log(`[Solo] Using local panel dir: ${serverDir}`);
+                    await startPanel({ bundleDir: serverDir, port: panelPort, dataDir });
                 }
-                srv.close(() => resolveP(addr.port));
+                else {
+                    const bundleDir = await ensurePanelBundle({ dataDir, version: panelVersion });
+                    const serverDir = await findPanelServerDir(bundleDir);
+                    await startPanel({ bundleDir: serverDir, port: panelPort, dataDir });
+                }
+                panelHealthy.up = true;
+                console.log('[Solo] Panel is up (private port)');
+            })();
+            panelReady.catch((err) => {
+                console.error('[Solo] Panel failed to start:', err instanceof Error ? err.message : String(err));
             });
-            srv.on('error', rejectP);
-        });
-        const hubPort = await probeFreePort();
-        const panelPort = await probeFreePort();
-        const soloConfig = {
-            port: opts.port ? Number(opts.port) : DEFAULT_SOLO_PORT,
-            hubPort,
-            panelPort,
-            dataDir,
-            accessKeyHash,
-            hubSecret,
-        };
-        const hubHealthy = { up: false };
-        const panelHealthy = { up: false };
-        const front = await createSoloServer({
-            config: soloConfig,
-            localApiPort: hookPort,
-            hub: { isHealthy: () => hubHealthy.up },
-            panel: { isHealthy: () => panelHealthy.up },
-        });
-        // Children ensured asynchronously AFTER the front listens (L1). The hub
-        // must be healthy before the Centrifugo client connects — gated below.
-        const soloDir = join(dataDir, 'solo');
-        const hubReady = (async () => {
-            const binPath = await ensureHubBinary({ dataDir });
-            const configPath = join(soloDir, 'centrifugo.json');
-            await writeHubConfig(configPath, { port: hubPort, secret: hubSecret });
-            await startHub({ configPath, binPath, dataDir });
-            hubHealthy.up = true;
-            console.log('[Solo] Hub is up (private port)');
-        })();
-        hubReady.catch((err) => {
-            console.error('[Solo] Hub failed to start:', err instanceof Error ? err.message : String(err));
-        });
-        // Panel version defaults to the bare bridge version (release-tag
-        // parity — panelBundleUrl's template already supplies the `v` prefix
-        // for the tag segment); override with FTOWN_SOLO_PANEL_VERSION for
-        // development. Either source may be typed with a leading `v`, so both
-        // are normalized to the bare semver panelBundleUrl expects.
-        const panelVersion = normalizePanelVersion(process.env.FTOWN_SOLO_PANEL_VERSION ?? BRIDGE_VERSION);
-        const panelReady = (async () => {
-            if (process.env.FTOWN_SOLO_PANEL_DIR) {
-                // Dev escape hatch: serve an already-built standalone directory.
-                const serverDir = await findPanelServerDir(resolve(process.env.FTOWN_SOLO_PANEL_DIR));
-                console.log(`[Solo] Using local panel dir: ${serverDir}`);
-                await startPanel({ bundleDir: serverDir, port: panelPort, dataDir });
+            // One-time banner (S1 exception): full link ONLY when a fresh key was
+            // generated; otherwise print keyless URL + rotation hint.
+            const bannerIps = networkInterfacesForBanner();
+            console.log('========================================');
+            console.log('  ftown SOLO mode');
+            console.log(`  Bridge ID: ${bridgeId}`);
+            for (const ip of bannerIps) {
+                const base = `http://${ip}:${front.port}`;
+                if (accessKeyRaw) {
+                    console.log(`  Open:   ${base}/#k=${accessKeyRaw}`);
+                }
+                else {
+                    console.log(`  URL:    ${base}  (key already paired — --rotate-key reprints)`);
+                }
             }
-            else {
-                const bundleDir = await ensurePanelBundle({ dataDir, version: panelVersion });
-                const serverDir = await findPanelServerDir(bundleDir);
-                await startPanel({ bundleDir: serverDir, port: panelPort, dataDir });
+            if (!accessKeyRaw) {
+                console.log('  Key not shown: already issued once. --rotate-key regenerates it.');
             }
-            panelHealthy.up = true;
-            console.log('[Solo] Panel is up (private port)');
-        })();
-        panelReady.catch((err) => {
-            console.error('[Solo] Panel failed to start:', err instanceof Error ? err.message : String(err));
-        });
-        // One-time banner (S1 exception): full link ONLY when a fresh key was
-        // generated; otherwise print keyless URL + rotation hint.
-        const bannerIps = networkInterfacesForBanner();
-        console.log('========================================');
-        console.log('  ftown SOLO mode');
-        console.log(`  Bridge ID: ${bridgeId}`);
-        for (const ip of bannerIps) {
-            const base = `http://${ip}:${front.port}`;
-            if (accessKeyRaw) {
-                console.log(`  Open:   ${base}/#k=${accessKeyRaw}`);
+            if (bannerIps.length === 0) {
+                console.log('  WARNING: no LAN interface detected; loopback only.');
             }
             else {
-                console.log(`  URL:    ${base}  (key already paired — --rotate-key reprints)`);
+                console.log('  WARNING: bound to a non-loopback interface over plain HTTP (S9).');
+            }
+            console.log('========================================');
+            solo = {
+                config: soloConfig,
+                front,
+                hub: {
+                    stop: () => {
+                        void stopHub(dataDir).catch(() => { });
+                    },
+                },
+                panel: {
+                    stop: () => {
+                        void stopPanel(dataDir).catch(() => { });
+                    },
+                },
+                hubReady,
+                panelReady,
+            };
+        }
+        // ----- END SOLO MODE -----
+        // The bootstrap token (--token) is single-use and short-lived (F1). Once a
+        // bridge has onboarded it persists its rotating refresh token (F3) and
+        // resumes from that on restart, so the bootstrap token is never reused.
+        const local = { localPort: hookPort, localNonce };
+        const refreshTokenPath = join(dataDir, 'refresh-token');
+        let persistedRefreshToken;
+        try {
+            persistedRefreshToken = readFileSync(refreshTokenPath, 'utf8').trim() || undefined;
+        }
+        catch {
+            persistedRefreshToken = undefined;
+        }
+        const persistRefreshToken = (token) => {
+            try {
+                writeFileSync(refreshTokenPath, `${token}\n`, { mode: 0o600 });
+            }
+            catch (err) {
+                console.error('[Bridge] Failed to persist refresh token:', err instanceof Error ? err.message : String(err));
+            }
+        };
+        // Onboarding precedence (P7): stored refresh token → else --token exchange →
+        // else interactive device pairing. Pairing yields the SAME token bundle shape
+        // as /api/auth/bridge, so all three paths converge on `auth` and the identical
+        // refresh-token persist/resume logic below.
+        const onboard = async () => {
+            if (opts.token) {
+                console.log('[Bridge] Authenticating with API...');
+                return fetchBridgeToken(opts.apiUrl, opts.token, bridgeId, local);
             }
+            console.log('[Bridge] No bootstrap token or stored session — starting device pairing...');
+            return runPairing({
+                apiUrl: opts.apiUrl,
+                bridgeId,
+                hostname: osHostname(),
+                platform: process.platform,
+                localPort: local.localPort,
+                localNonce: local.localNonce,
+                log: (msg) => console.log(msg),
+            });
+        };
+        let auth;
+        if (opts.local) {
+            auth = { userId: 'local', token: '', refreshToken: '', centrifugoUrl: 'ws://127.0.0.1/disabled' };
         }
-        if (!accessKeyRaw) {
-            console.log('  Key not shown: already issued once. --rotate-key regenerates it.');
+        else if (solo) {
+            // Solo mode: identity is synthesized locally (contract S2/S10). No
+            // refresh token exists; getToken() mints a fresh hub JWT on demand.
+            // The bridge's own connection token carries `info` (matching the cloud
+            // minter's shape) so the panel's presence-based bridge list sees it —
+            // browser tokens from /api/solo/bootstrap|token deliberately omit it.
+            const token = mintHubJwt({
+                secret: solo.config.hubSecret,
+                info: { bridgeId, hostname: osHostname() },
+            });
+            auth = {
+                userId: SOLO_USER_ID,
+                token,
+                refreshToken: '',
+                centrifugoUrl: `ws://127.0.0.1:${solo.config.hubPort}/connection/websocket`,
+            };
         }
-        if (bannerIps.length === 0) {
-            console.log('  WARNING: no LAN interface detected; loopback only.');
+        else if (persistedRefreshToken) {
+            console.log('[Bridge] Resuming from stored refresh token...');
+            try {
+                auth = await refreshBridgeToken(opts.apiUrl, persistedRefreshToken, bridgeId, local);
+            }
+            catch (err) {
+                console.warn('[Bridge] Stored refresh token rejected, falling back to bootstrap token / pairing:', err instanceof Error ? err.message : String(err));
+                auth = await onboard();
+            }
         }
         else {
-            console.log('  WARNING: bound to a non-loopback interface over plain HTTP (S9).');
+            auth = await onboard();
         }
-        console.log('========================================');
-        solo = {
-            config: soloConfig,
-            front,
-            hub: {
-                stop: () => {
-                    void stopHub(dataDir).catch(() => { });
+        const currentRefreshToken = auth.refreshToken;
+        let currentBridgeToken = auth.token;
+        if (!solo && !opts.local)
+            persistRefreshToken(currentRefreshToken);
+        const tokenRefresher = solo || opts.local
+            ? null
+            : new RotatingTokenRefresher({
+                initialRefreshToken: currentRefreshToken,
+                refresh: async (refreshToken) => {
+                    const refreshed = await refreshBridgeToken(opts.apiUrl, refreshToken, bridgeId, local);
+                    currentBridgeToken = refreshed.token;
+                    return refreshed;
                 },
-            },
-            panel: {
-                stop: () => {
-                    void stopPanel(dataDir).catch(() => { });
+                loadPersistedRefreshToken: () => {
+                    try {
+                        return readFileSync(refreshTokenPath, 'utf8').trim() || undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                persistRefreshToken,
+                onPersistedTokenRecovery: () => {
+                    console.warn('[Bridge] In-memory refresh token was stale; retrying with the newer persisted token.');
                 },
+            });
+        const userId = auth.userId;
+        const centrifugoUrl = auth.centrifugoUrl;
+        console.log('========================================');
+        console.log('  ftown-bridge starting');
+        console.log(`  Bridge ID:      ${bridgeId}`);
+        console.log(`  User ID:        ${userId}`);
+        console.log(`  Centrifugo URL: ${centrifugoUrl}`);
+        console.log(`  Data dir:       ${dataDir}`);
+        console.log('========================================');
+        async function getToken() {
+            if (solo) {
+                // Solo: mint locally — no remote refresh, no refresh-token rotation.
+                // Carries the same `info` claim as the initial mint above so the
+                // panel keeps seeing this bridge across every refresh.
+                return mintHubJwt({
+                    secret: solo.config.hubSecret,
+                    info: { bridgeId, hostname: osHostname() },
+                });
+            }
+            console.log('[Bridge] Refreshing Centrifugo token...');
+            const token = await tokenRefresher.getToken();
+            console.log('[Bridge] Token refreshed successfully');
+            return token;
+        }
+        const store = new SessionStore(dataDir);
+        // Sessions left in a live state by a previous bridge are handled by
+        // resurrectSessions() once Centrifugo is connected (tmux reattach,
+        // resume respawn, or marked as error).
+        const terminalManager = new TerminalManager(50000, 120);
+        const runner = new ProcessRunner();
+        const centrifugo = new CentrifugoClient(centrifugoUrl, auth.token, getToken, {
+            disabled: opts.local,
+            // On a transport reconnect, re-publish the session snapshot. The UI does
+            // not re-request its list on reconnect, so without this its session list
+            // goes stale/empty after a Centrifugo blip until a page reload.
+            onReconnect: async () => {
+                // Re-publishing EVERY session on each reconnect is a publish storm that
+                // (before the flapping fix) fed the command-echo backlog. Terminal
+                // records (completed/error) don't change and were already in the UI's
+                // list before the blip, so only live sessions need a re-push. Publish in
+                // bounded batches with a macrotask yield between them so a large account
+                // can't monopolize the event loop. A single publish's payload is
+                // unchanged.
+                const RESYNC_CHUNK = 10;
+                const sessions = await store.listSessions();
+                const live = sessions.filter((session) => session.status === 'running' || session.status === 'pending');
+                for (let i = 0; i < live.length; i += RESYNC_CHUNK) {
+                    await Promise.all(live.slice(i, i + RESYNC_CHUNK).map((session) => centrifugo.publishSessionUpdate(userId, session)));
+                    await new Promise((resolve) => setTimeout(resolve, 0));
+                }
+                console.log(`[Bridge] Re-synced ${live.length} session(s) after Centrifugo reconnect`);
             },
-            hubReady,
-            panelReady,
-        };
-    }
-    // ----- END SOLO MODE -----
-    // The bootstrap token (--token) is single-use and short-lived (F1). Once a
-    // bridge has onboarded it persists its rotating refresh token (F3) and
-    // resumes from that on restart, so the bootstrap token is never reused.
-    const local = { localPort: hookPort, localNonce };
-    const refreshTokenPath = join(dataDir, 'refresh-token');
-    let persistedRefreshToken;
-    try {
-        persistedRefreshToken = readFileSync(refreshTokenPath, 'utf8').trim() || undefined;
-    }
-    catch {
-        persistedRefreshToken = undefined;
-    }
-    const persistRefreshToken = (token) => {
+        });
+        // Direct transport (WebRTC DataChannel) data plane. Peers attach per session;
+        // terminal output/screen fan out to them directly, and to Centrifugo only when
+        // the session has an unexpired remote watcher (R2). Signaling and watch
+        // heartbeats ride the existing commands:rpc channel.
+        const watchRegistry = new WatchRegistry();
+        const directPeers = new DirectPeerManager({
+            bridgeId,
+            sendSignal: (msg) => {
+                centrifugo.publishSignal(userId, msg).catch((err) => {
+                    console.error('[Bridge] Failed to publish WebRTC signal:', err);
+                });
+            },
+            onInput: (sid, data) => { runner.write(sid, data); },
+            onResize: (sid, cols, rows) => { handleClientResize(sid, cols, rows); },
+            onAttach: (sid) => terminalManager.serialize(sid, 20000) ?? '',
+        });
+        // Loopback WebSocket rung: same DirectMessage protocol as WebRTC, tunneled
+        // over TCP on the existing 127.0.0.1 local API server. Bypasses VPN/endpoint
+        // filters that kill UDP hairpin. Input/resize/attach feed the SAME sinks as
+        // the WebRTC peer manager; upgrades are gated on the per-process nonce (L1/L2).
+        let browserAccess;
+        let apiOrigin = '';
         try {
-            writeFileSync(refreshTokenPath, `${token}\n`, { mode: 0o600 });
+            apiOrigin = new URL(opts.apiUrl).origin;
         }
-        catch (err) {
-            console.error('[Bridge] Failed to persist refresh token:', err instanceof Error ? err.message : String(err));
-        }
-    };
-    // Onboarding precedence (P7): stored refresh token → else --token exchange →
-    // else interactive device pairing. Pairing yields the SAME token bundle shape
-    // as /api/auth/bridge, so all three paths converge on `auth` and the identical
-    // refresh-token persist/resume logic below.
-    const onboard = async () => {
-        if (opts.token) {
-            console.log('[Bridge] Authenticating with API...');
-            return fetchBridgeToken(opts.apiUrl, opts.token, bridgeId, local);
+        catch { /* leave empty; only localhost origins accepted */ }
+        const loopbackServer = new LoopbackPeerServer({
+            bridgeId,
+            nonce: localNonce,
+            authorize: (token, origin) => browserAccess?.authorize(token, origin) ?? false,
+            allowedOrigins: apiOrigin ? [apiOrigin] : [],
+            onInput: (sid, data) => { runner.write(sid, data); },
+            onResize: (sid, cols, rows) => { handleClientResize(sid, cols, rows); },
+            onAttach: (sid) => terminalManager.serialize(sid, 20000) ?? '',
+        });
+        const publishRouter = new PublishRouter({
+            registry: watchRegistry,
+            peerManager: directPeers,
+            loopback: loopbackServer,
+            centrifugo,
+            userId,
+            // Watch messages fan out to every bridge on commands:rpc; only register
+            // watchers for sessions this bridge actually serves terminal data for.
+            // hasTmuxSession is the third arm: a session can be alive in tmux with no
+            // PTY client in THIS process (agent-spawned re-run, adopted after a bridge
+            // restart, resurrection deferred). Those used to fail the guard, so the
+            // watch was dropped and every device rendered a blank pane. The tmux probe
+            // is a subprocess, so it runs last — the two in-memory checks short-circuit
+            // for every session this bridge already serves.
+            isKnownSession: (sid) => runner.isRunning(sid) || terminalManager.has(sid) || runner.hasTmuxSession(sid),
+        });
+        // Accepting the watch is not enough on its own to make output flow.
+        // publishScreenDump serves entirely from terminalManager, which is fed by
+        // TerminalPump from runner 'data' events — there is no tmux capture-pane
+        // path — so a session alive in tmux with no PTY client here dumps an empty
+        // screen and then streams nothing. Attach one client through the SAME adopt
+        // path session resurrection uses (runner.reattach); tmux redraws the full
+        // screen to a joining client, so live output resumes within milliseconds and
+        // rides the already-attached pump. No new pump, no new tmux plumbing.
+        const watchReattachInFlight = new Set();
+        const ensureWatchedSessionAttached = (sid) => {
+            if (runner.isRunning(sid) || watchReattachInFlight.has(sid))
+                return;
+            if (!runner.hasTmuxSession(sid))
+                return;
+            watchReattachInFlight.add(sid);
+            void store.loadSession(sid)
+                .then((session) => {
+                // Only adopt what this store still considers live: a tmux session with
+                // no live record may belong to another bridge on this machine.
+                if (!session || !shouldResurrectStoredSession(session))
+                    return;
+                if (runner.isRunning(sid))
+                    return;
+                if (!runner.reattach(sid, {
+                    workingDir: session.workingDir,
+                    parentSessionId: session.parentSessionId,
+                }))
+                    return;
+                // Idempotent: subscribeToTerminalInput no-ops on an existing channel.
+                wireTerminalInput(sid);
+                console.log(`[Bridge] Reattached tmux session ${sid} for a new terminal watcher`);
+            })
+                .catch((err) => {
+                console.error(`[Bridge] Failed to reattach ${sid} for a terminal watcher:`, err);
+            })
+                .finally(() => { watchReattachInFlight.delete(sid); });
+        };
+        // Every NEW remote watcher (first, each additional distinct client, or a
+        // post-expiry re-registration) ⇒ push a full screen resync so the joining
+        // Centrifugo-fallback client renders before incremental output (R1). The
+        // dump is channel-wide; existing viewers re-render idempotently.
+        watchRegistry.onNewWatcher((sid) => {
+            ensureWatchedSessionAttached(sid);
+            publishScreenDump(sid);
+        });
+        // Bind the loopback WS upgrade handler onto the already-listening server.
+        const loopbackHttpServer = localApiServer.getHttpServer();
+        if (loopbackHttpServer) {
+            loopbackServer.attach(loopbackHttpServer);
+            console.log(`[Bridge] Loopback WS rung ready at ws://127.0.0.1:${hookPort}/ws`);
         }
-        console.log('[Bridge] No bootstrap token or stored session — starting device pairing...');
-        return runPairing({
+        localApiServer.setDependencies(store, runner, centrifugo, userId, terminalManager);
+        const pushNotifier = opts.local || solo ? undefined : new BridgePushNotifier({
             apiUrl: opts.apiUrl,
             bridgeId,
-            hostname: osHostname(),
-            platform: process.platform,
-            localPort: local.localPort,
-            localNonce: local.localNonce,
-            log: (msg) => console.log(msg),
+            getToken: () => currentBridgeToken,
+            getSession: (sessionId) => store.loadSession(sessionId),
         });
-    };
-    let auth;
-    if (opts.local) {
-        auth = { userId: 'local', token: '', refreshToken: '', centrifugoUrl: 'ws://127.0.0.1/disabled' };
-    }
-    else if (solo) {
-        // Solo mode: identity is synthesized locally (contract S2/S10). No
-        // refresh token exists; getToken() mints a fresh hub JWT on demand.
-        // The bridge's own connection token carries `info` (matching the cloud
-        // minter's shape) so the panel's presence-based bridge list sees it —
-        // browser tokens from /api/solo/bootstrap|token deliberately omit it.
-        const token = mintHubJwt({
-            secret: solo.config.hubSecret,
-            info: { bridgeId, hostname: osHostname() },
+        const attentionStore = new AttentionStore((sessionId) => store.sessionDir(sessionId), 500, pushNotifier ? (sessionId, notice) => pushNotifier.notify(sessionId, notice) : undefined, {
+            isSessionActive: async (sessionId) => {
+                const session = await store.loadSession(sessionId);
+                return !!session && session.status === 'running' && session.shellType !== 'shell';
+            },
+            onIdleCanceled: (sessionId) => pushNotifier?.cancelIdle(sessionId),
+        });
+        localApiServer.setAttentionStore(attentionStore);
+        const stopPushSessionObserver = centrifugo.onLocalPublication((channel, data) => {
+            if (channel !== `sessions:updates#${userId}` || !data || typeof data !== 'object')
+                return;
+            const update = data;
+            if (update.type === 'session_update' && update.session?.id && update.session.status !== 'running') {
+                void attentionStore.cancelIdleNotification(update.session.id).catch(() => { });
+            }
         });
-        auth = {
-            userId: SOLO_USER_ID,
-            token,
-            refreshToken: '',
-            centrifugoUrl: `ws://127.0.0.1:${solo.config.hubPort}/connection/websocket`,
+        if (pushNotifier) {
+            const knownSessions = await store.listSessions();
+            await attentionStore.restoreIdleNotifications(knownSessions
+                .filter((session) => session.status === 'running' && session.shellType !== 'shell')
+                .map((session) => session.id));
+        }
+        const mailStore = new MailStore((sessionId) => store.sessionDir(sessionId));
+        localApiServer.setMailStore(mailStore);
+        const notifyScriptPath = canonicalNotifyPath();
+        const wireTerminalInput = (sessionId) => {
+            centrifugo.subscribeToTerminalInput(userId, sessionId, (sid, data) => { runner.write(sid, data); }, (sid, cols, rows) => { handleClientResize(sid, cols, rows); }, (sid) => { publishScreenDump(sid); });
         };
-    }
-    else if (persistedRefreshToken) {
-        console.log('[Bridge] Resuming from stored refresh token...');
+        const sessionFactoryDeps = {
+            store,
+            runner,
+            centrifugo,
+            userId,
+            bridgeId,
+            hookPort,
+            hookToken: apiToken,
+            notifyScriptPath,
+            wireTerminalInput,
+        };
+        localApiServer.setSessionFactory(sessionFactoryDeps);
+        // Terminal output pump: buffers runner PTY output and owns the runner
+        // 'complete'/'error' lifecycle handlers.
+        const pump = new TerminalPump({
+            store,
+            terminalManager,
+            publishTerminalData: (sid, data) => publishRouter.publishTerminalData(sid, data),
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+            publishHookEvent: (sid, event) => centrifugo.publishHookEvent(userId, sid, event),
+            unregisterSession: (sid) => unregisterSession(sid),
+            collectUsage: (session) => collectSessionUsage(session),
+        });
+        pump.attach(runner);
+        // Resurrection engine for sessions left live by a previous bridge process.
+        const resurrection = new SessionResurrection({
+            store,
+            runner,
+            bridgeId,
+            sessionFactoryDeps,
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+            wireTerminalInput,
+        });
+        // Persists Claude/Cursor/Codex-native session ids from hook events.
+        const agentIdPersister = new AgentSessionIdPersister({
+            store,
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+        });
+        const hookUsagePersister = new HookUsagePersister({
+            store,
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+        });
+        // Session operations shared by local HTTP and dashboard RPC.
+        const sessionController = new SessionController({
+            store,
+            runner,
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+            removeSession: (id, options) => removeFtownSession({ store, runner, centrifugo, userId }, id, options),
+            sessionFactory: sessionFactoryDeps,
+            collectUsage: (session) => collectSessionUsage(session),
+            publishSyntheticStop: (sid, reason) => pump.publishSyntheticStop(sid, reason),
+            withSessionWrite: (sid, task) => pump.withSessionWrite(sid, task),
+            unregisterSession: (sid) => unregisterSession(sid),
+            flushTerminalBuffer: (sid) => pump.flush(sid),
+            destroyTerminal: (sid) => terminalManager.destroy(sid),
+        });
+        localApiServer.setSessionController(sessionController);
+        // Pointer lives under the instance home (see configure* above): default →
+        // $HOME/.ftown (harness CLIs read it there), custom --data-dir → that dir.
+        // Write and cleanup unlink MUST use this same resolved path.
+        const bridgeStateDir = ftownHome;
+        const bridgePointerPath = join(bridgeStateDir, 'bridge.json');
         try {
-            auth = await refreshBridgeToken(opts.apiUrl, persistedRefreshToken, bridgeId, local);
+            mkdirSync(bridgeStateDir, { recursive: true, mode: 0o700 });
+            writeFileSync(bridgePointerPath, JSON.stringify({
+                port: hookPort,
+                apiUrl: opts.apiUrl,
+                token: apiToken,
+                bridgeId,
+                pid: process.pid,
+                startedAt: new Date().toISOString(),
+                harness: join(homedir(), '.ftown', 'bin', 'ftown-harness'),
+                harnessCli: join(homedir(), '.ftown', 'cli', 'dist', 'ftown-cli.js'),
+            }, null, 2), { mode: 0o600 });
+            console.log(`[Bridge] Wrote bridge pointer to ${bridgePointerPath}`);
         }
         catch (err) {
-            console.warn('[Bridge] Stored refresh token rejected, falling back to bootstrap token / pairing:', err instanceof Error ? err.message : String(err));
-            auth = await onboard();
+            console.error('[Bridge] Failed to write bridge pointer:', err);
         }
-    }
-    else {
-        auth = await onboard();
-    }
-    const currentRefreshToken = auth.refreshToken;
-    if (!solo && !opts.local)
-        persistRefreshToken(currentRefreshToken);
-    const tokenRefresher = solo || opts.local
-        ? null
-        : new RotatingTokenRefresher({
-            initialRefreshToken: currentRefreshToken,
-            refresh: (refreshToken) => refreshBridgeToken(opts.apiUrl, refreshToken, bridgeId, local),
-            loadPersistedRefreshToken: () => {
-                try {
-                    return readFileSync(refreshTokenPath, 'utf8').trim() || undefined;
-                }
-                catch {
-                    return undefined;
-                }
-            },
-            persistRefreshToken,
-            onPersistedTokenRecovery: () => {
-                console.warn('[Bridge] In-memory refresh token was stale; retrying with the newer persisted token.');
-            },
-        });
-    const userId = auth.userId;
-    const centrifugoUrl = auth.centrifugoUrl;
-    console.log('========================================');
-    console.log('  ftown-bridge starting');
-    console.log(`  Bridge ID:      ${bridgeId}`);
-    console.log(`  User ID:        ${userId}`);
-    console.log(`  Centrifugo URL: ${centrifugoUrl}`);
-    console.log(`  Data dir:       ${dataDir}`);
-    console.log('========================================');
-    async function getToken() {
-        if (solo) {
-            // Solo: mint locally — no remote refresh, no refresh-token rotation.
-            // Carries the same `info` claim as the initial mint above so the
-            // panel keeps seeing this bridge across every refresh.
-            return mintHubJwt({
-                secret: solo.config.hubSecret,
-                info: { bridgeId, hostname: osHostname() },
-            });
-        }
-        console.log('[Bridge] Refreshing Centrifugo token...');
-        const token = await tokenRefresher.getToken();
-        console.log('[Bridge] Token refreshed successfully');
-        return token;
-    }
-    const store = new SessionStore(dataDir);
-    // Sessions left in a live state by a previous bridge are handled by
-    // resurrectSessions() once Centrifugo is connected (tmux reattach,
-    // resume respawn, or marked as error).
-    const terminalManager = new TerminalManager(50000, 120);
-    const runner = new ProcessRunner();
-    const centrifugo = new CentrifugoClient(centrifugoUrl, auth.token, getToken, {
-        disabled: opts.local,
-        // On a transport reconnect, re-publish the session snapshot. The UI does
-        // not re-request its list on reconnect, so without this its session list
-        // goes stale/empty after a Centrifugo blip until a page reload.
-        onReconnect: async () => {
-            // Re-publishing EVERY session on each reconnect is a publish storm that
-            // (before the flapping fix) fed the command-echo backlog. Terminal
-            // records (completed/error) don't change and were already in the UI's
-            // list before the blip, so only live sessions need a re-push. Publish in
-            // bounded batches with a macrotask yield between them so a large account
-            // can't monopolize the event loop. A single publish's payload is
-            // unchanged.
-            const RESYNC_CHUNK = 10;
-            const sessions = await store.listSessions();
-            const live = sessions.filter((session) => session.status === 'running' || session.status === 'pending');
-            for (let i = 0; i < live.length; i += RESYNC_CHUNK) {
-                await Promise.all(live.slice(i, i + RESYNC_CHUNK).map((session) => centrifugo.publishSessionUpdate(userId, session)));
-                await new Promise((resolve) => setTimeout(resolve, 0));
+        const cleanupPointer = () => {
+            try {
+                const pointer = JSON.parse(readFileSync(bridgePointerPath, 'utf8'));
+                if (pointer.pid === process.pid && pointer.token === apiToken)
+                    unlinkSync(bridgePointerPath);
             }
-            console.log(`[Bridge] Re-synced ${live.length} session(s) after Centrifugo reconnect`);
-        },
-    });
-    // Direct transport (WebRTC DataChannel) data plane. Peers attach per session;
-    // terminal output/screen fan out to them directly, and to Centrifugo only when
-    // the session has an unexpired remote watcher (R2). Signaling and watch
-    // heartbeats ride the existing commands:rpc channel.
-    const watchRegistry = new WatchRegistry();
-    const directPeers = new DirectPeerManager({
-        bridgeId,
-        sendSignal: (msg) => {
-            centrifugo.publishSignal(userId, msg).catch((err) => {
-                console.error('[Bridge] Failed to publish WebRTC signal:', err);
-            });
-        },
-        onInput: (sid, data) => { runner.write(sid, data); },
-        onResize: (sid, cols, rows) => { handleClientResize(sid, cols, rows); },
-        onAttach: (sid) => terminalManager.serialize(sid, 20000) ?? '',
-    });
-    // Loopback WebSocket rung: same DirectMessage protocol as WebRTC, tunneled
-    // over TCP on the existing 127.0.0.1 local API server. Bypasses VPN/endpoint
-    // filters that kill UDP hairpin. Input/resize/attach feed the SAME sinks as
-    // the WebRTC peer manager; upgrades are gated on the per-process nonce (L1/L2).
-    let browserAccess;
-    let apiOrigin = '';
-    try {
-        apiOrigin = new URL(opts.apiUrl).origin;
-    }
-    catch { /* leave empty; only localhost origins accepted */ }
-    const loopbackServer = new LoopbackPeerServer({
-        bridgeId,
-        nonce: localNonce,
-        authorize: (token, origin) => browserAccess?.authorize(token, origin) ?? false,
-        allowedOrigins: apiOrigin ? [apiOrigin] : [],
-        onInput: (sid, data) => { runner.write(sid, data); },
-        onResize: (sid, cols, rows) => { handleClientResize(sid, cols, rows); },
-        onAttach: (sid) => terminalManager.serialize(sid, 20000) ?? '',
-    });
-    const publishRouter = new PublishRouter({
-        registry: watchRegistry,
-        peerManager: directPeers,
-        loopback: loopbackServer,
-        centrifugo,
-        userId,
-        // Watch messages fan out to every bridge on commands:rpc; only register
-        // watchers for sessions this bridge actually serves terminal data for.
-        // hasTmuxSession is the third arm: a session can be alive in tmux with no
-        // PTY client in THIS process (agent-spawned re-run, adopted after a bridge
-        // restart, resurrection deferred). Those used to fail the guard, so the
-        // watch was dropped and every device rendered a blank pane. The tmux probe
-        // is a subprocess, so it runs last — the two in-memory checks short-circuit
-        // for every session this bridge already serves.
-        isKnownSession: (sid) => runner.isRunning(sid) || terminalManager.has(sid) || runner.hasTmuxSession(sid),
-    });
-    // Accepting the watch is not enough on its own to make output flow.
-    // publishScreenDump serves entirely from terminalManager, which is fed by
-    // TerminalPump from runner 'data' events — there is no tmux capture-pane
-    // path — so a session alive in tmux with no PTY client here dumps an empty
-    // screen and then streams nothing. Attach one client through the SAME adopt
-    // path session resurrection uses (runner.reattach); tmux redraws the full
-    // screen to a joining client, so live output resumes within milliseconds and
-    // rides the already-attached pump. No new pump, no new tmux plumbing.
-    const watchReattachInFlight = new Set();
-    const ensureWatchedSessionAttached = (sid) => {
-        if (runner.isRunning(sid) || watchReattachInFlight.has(sid))
-            return;
-        if (!runner.hasTmuxSession(sid))
-            return;
-        watchReattachInFlight.add(sid);
-        void store.loadSession(sid)
-            .then((session) => {
-            // Only adopt what this store still considers live: a tmux session with
-            // no live record may belong to another bridge on this machine.
-            if (!session || !shouldResurrectStoredSession(session))
-                return;
-            if (runner.isRunning(sid))
+            catch { /* already gone or owned by a newer bridge */ }
+        };
+        process.on('exit', cleanupPointer);
+        function publishScreenDump(sid) {
+            // Phase 1: viewport-only dump (~rows*cols bytes) for instant render.
+            const viewportRaw = terminalManager.serialize(sid, 0);
+            if (viewportRaw) {
+                publishRouter.publishTerminalScreen(sid, viewportRaw);
+            }
+            // Phase 2: full dump with scrollback. Client re-renders on top of phase 1.
+            // Cap accounts for ~50% JSON-encoding inflation on ANSI-heavy buffers
+            // (each \x1b ->  expands 1 -> 6 bytes), keeping the on-wire
+            // Centrifugo frame under websocket_message_size_limit.
+            const MAX_BYTES = 2_500_000;
+            let scrollback = 20000;
+            let raw = terminalManager.serialize(sid, scrollback);
+            while (raw && Buffer.byteLength(raw, 'utf8') > MAX_BYTES && scrollback > 100) {
+                scrollback = Math.floor(scrollback / 2);
+                raw = terminalManager.serialize(sid, scrollback);
+            }
+            if (!raw)
                 return;
-            if (!runner.reattach(sid, {
-                workingDir: session.workingDir,
-                parentSessionId: session.parentSessionId,
-            }))
+            if (raw === viewportRaw)
                 return;
-            // Idempotent: subscribeToTerminalInput no-ops on an existing channel.
-            wireTerminalInput(sid);
-            console.log(`[Bridge] Reattached tmux session ${sid} for a new terminal watcher`);
-        })
-            .catch((err) => {
-            console.error(`[Bridge] Failed to reattach ${sid} for a terminal watcher:`, err);
-        })
-            .finally(() => { watchReattachInFlight.delete(sid); });
-    };
-    // Every NEW remote watcher (first, each additional distinct client, or a
-    // post-expiry re-registration) ⇒ push a full screen resync so the joining
-    // Centrifugo-fallback client renders before incremental output (R1). The
-    // dump is channel-wide; existing viewers re-render idempotently.
-    watchRegistry.onNewWatcher((sid) => {
-        ensureWatchedSessionAttached(sid);
-        publishScreenDump(sid);
-    });
-    // Bind the loopback WS upgrade handler onto the already-listening server.
-    const loopbackHttpServer = localApiServer.getHttpServer();
-    if (loopbackHttpServer) {
-        loopbackServer.attach(loopbackHttpServer);
-        console.log(`[Bridge] Loopback WS rung ready at ws://127.0.0.1:${hookPort}/ws`);
-    }
-    localApiServer.setDependencies(store, runner, centrifugo, userId, terminalManager);
-    localApiServer.setAttentionStore(new AttentionStore((sessionId) => store.sessionDir(sessionId)));
-    const mailStore = new MailStore((sessionId) => store.sessionDir(sessionId));
-    localApiServer.setMailStore(mailStore);
-    const notifyScriptPath = canonicalNotifyPath();
-    const wireTerminalInput = (sessionId) => {
-        centrifugo.subscribeToTerminalInput(userId, sessionId, (sid, data) => { runner.write(sid, data); }, (sid, cols, rows) => { handleClientResize(sid, cols, rows); }, (sid) => { publishScreenDump(sid); });
-    };
-    const sessionFactoryDeps = {
-        store,
-        runner,
-        centrifugo,
-        userId,
-        bridgeId,
-        hookPort,
-        hookToken: apiToken,
-        notifyScriptPath,
-        wireTerminalInput,
-    };
-    localApiServer.setSessionFactory(sessionFactoryDeps);
-    // Terminal output pump: buffers runner PTY output and owns the runner
-    // 'complete'/'error' lifecycle handlers.
-    const pump = new TerminalPump({
-        store,
-        terminalManager,
-        publishTerminalData: (sid, data) => publishRouter.publishTerminalData(sid, data),
-        publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
-        publishHookEvent: (sid, event) => centrifugo.publishHookEvent(userId, sid, event),
-        unregisterSession: (sid) => unregisterSession(sid),
-        collectUsage: (session) => collectSessionUsage(session),
-    });
-    pump.attach(runner);
-    // Resurrection engine for sessions left live by a previous bridge process.
-    const resurrection = new SessionResurrection({
-        store,
-        runner,
-        bridgeId,
-        sessionFactoryDeps,
-        publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
-        wireTerminalInput,
-    });
-    // Persists Claude/Cursor/Codex-native session ids from hook events.
-    const agentIdPersister = new AgentSessionIdPersister({
-        store,
-        publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
-    });
-    const hookUsagePersister = new HookUsagePersister({
-        store,
-        publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
-    });
-    // Session operations shared by local HTTP and dashboard RPC.
-    const sessionController = new SessionController({
-        store,
-        runner,
-        publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
-        removeSession: (id, options) => removeFtownSession({ store, runner, centrifugo, userId }, id, options),
-        sessionFactory: sessionFactoryDeps,
-        collectUsage: (session) => collectSessionUsage(session),
-        publishSyntheticStop: (sid, reason) => pump.publishSyntheticStop(sid, reason),
-        withSessionWrite: (sid, task) => pump.withSessionWrite(sid, task),
-        unregisterSession: (sid) => unregisterSession(sid),
-        flushTerminalBuffer: (sid) => pump.flush(sid),
-        destroyTerminal: (sid) => terminalManager.destroy(sid),
-    });
-    localApiServer.setSessionController(sessionController);
-    // Pointer lives under the instance home (see configure* above): default →
-    // $HOME/.ftown (harness CLIs read it there), custom --data-dir → that dir.
-    // Write and cleanup unlink MUST use this same resolved path.
-    const bridgeStateDir = ftownHome;
-    const bridgePointerPath = join(bridgeStateDir, 'bridge.json');
-    try {
-        mkdirSync(bridgeStateDir, { recursive: true, mode: 0o700 });
-        writeFileSync(bridgePointerPath, JSON.stringify({
-            port: hookPort,
-            apiUrl: opts.apiUrl,
-            token: apiToken,
-            bridgeId,
-            pid: process.pid,
-            startedAt: new Date().toISOString(),
-            harness: join(homedir(), '.ftown', 'bin', 'ftown-harness'),
-            harnessCli: join(homedir(), '.ftown', 'cli', 'dist', 'ftown-cli.js'),
-        }, null, 2), { mode: 0o600 });
-        console.log(`[Bridge] Wrote bridge pointer to ${bridgePointerPath}`);
-    }
-    catch (err) {
-        console.error('[Bridge] Failed to write bridge pointer:', err);
-    }
-    const cleanupPointer = () => {
-        try {
-            const pointer = JSON.parse(readFileSync(bridgePointerPath, 'utf8'));
-            if (pointer.pid === process.pid && pointer.token === apiToken)
-                unlinkSync(bridgePointerPath);
-        }
-        catch { /* already gone or owned by a newer bridge */ }
-    };
-    process.on('exit', cleanupPointer);
-    function publishScreenDump(sid) {
-        // Phase 1: viewport-only dump (~rows*cols bytes) for instant render.
-        const viewportRaw = terminalManager.serialize(sid, 0);
-        if (viewportRaw) {
-            publishRouter.publishTerminalScreen(sid, viewportRaw);
+            publishRouter.publishTerminalScreen(sid, raw);
         }
-        // Phase 2: full dump with scrollback. Client re-renders on top of phase 1.
-        // Cap accounts for ~50% JSON-encoding inflation on ANSI-heavy buffers
-        // (each \x1b ->  expands 1 -> 6 bytes), keeping the on-wire
-        // Centrifugo frame under websocket_message_size_limit.
-        const MAX_BYTES = 2_500_000;
-        let scrollback = 20000;
-        let raw = terminalManager.serialize(sid, scrollback);
-        while (raw && Buffer.byteLength(raw, 'utf8') > MAX_BYTES && scrollback > 100) {
-            scrollback = Math.floor(scrollback / 2);
-            raw = terminalManager.serialize(sid, scrollback);
+        function handleClientResize(sid, cols, rows) {
+            runner.resize(sid, cols, rows);
+            terminalManager.resize(sid, cols, rows);
         }
-        if (!raw)
-            return;
-        if (raw === viewportRaw)
-            return;
-        publishRouter.publishTerminalScreen(sid, raw);
-    }
-    function handleClientResize(sid, cols, rows) {
-        runner.resize(sid, cols, rows);
-        terminalManager.resize(sid, cols, rows);
-    }
-    localApiServer.on('event', (hookEvent) => {
-        pump.withSessionWrite(hookEvent.sessionId, async () => {
-            await agentIdPersister.persist(hookEvent);
-            const usage = await hookUsagePersister.persist(hookEvent);
-            await centrifugo.publishHookEvent(userId, hookEvent.sessionId, {
-                type: 'hook_event',
-                eventName: hookEvent.eventName,
-                data: hookEvent.data,
-                ...(usage ? { usage } : {}),
+        localApiServer.on('event', (hookEvent) => {
+            pump.withSessionWrite(hookEvent.sessionId, async () => {
+                await agentIdPersister.persist(hookEvent);
+                const usage = await hookUsagePersister.persist(hookEvent);
+                await centrifugo.publishHookEvent(userId, hookEvent.sessionId, {
+                    type: 'hook_event',
+                    eventName: hookEvent.eventName,
+                    data: hookEvent.data,
+                    ...(usage ? { usage } : {}),
+                });
+            }).catch((err) => {
+                console.error(`[Bridge] Failed to handle hook event for ${hookEvent.sessionId}:`, err);
             });
-        }).catch((err) => {
-            console.error(`[Bridge] Failed to handle hook event for ${hookEvent.sessionId}:`, err);
         });
-    });
-    let ready = false;
-    browserAccess = new BrowserAccess({
-        dataDir,
-        cloudNonce: opts.local || solo ? undefined : localNonce,
-        allowedOrigins: apiOrigin ? [apiOrigin] : [],
-        bootstrap: () => ({ version: 1, userId, bridgeId, hostname: osHostname(), localPort: hookPort, localNonce: '' }),
-        execute: async (command) => {
-            if (!ready)
-                return { requestId: command.requestId, success: false, error: 'Bridge is starting; try again shortly' };
-            let result;
-            await createCommandHandler({
-                bridgeId, sessionController,
-                publishCommandResponse: async (response) => { result = response; },
-            })(command);
-            return result ?? { requestId: command.requestId, success: false, error: 'Command was not handled' };
-        },
-        onRevoke: () => loopbackServer.disconnectPeers(),
-    });
-    localApiServer.setBrowserAccess(browserAccess);
-    centrifugo.onLocalPublication((channel, data) => browserAccess?.publish(channel, data));
-    console.log(`[Bridge] Local browser access: run ftown-bridge pair${opts.dataDir ? ` --data-dir ${JSON.stringify(dataDir)}` : ''}`);
-    const handleCommand = createCommandHandler({
-        bridgeId,
-        relayRequest: createRelayHandler(hookPort, apiToken),
-        sessionController,
-        publishCommandResponse: (response) => centrifugo.publishCommandResponse(userId, response),
-    });
-    // Solo: the hub child must be healthy before connecting (L1 gates the
-    // transport, not the front). A failed hub is fatal for solo — exit cleanly
-    // instead of crashing on an unhandled rejection.
-    if (solo) {
-        try {
-            await solo.hubReady;
-            console.log('[Solo] Hub healthy — connecting Centrifugo client');
-        }
-        catch (err) {
-            console.error('[Solo] Cannot continue without the hub:', err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    }
-    centrifugo.connect();
-    centrifugo.joinBridgesChannel(userId, bridgeId);
-    centrifugo.subscribeToSessions(userId);
-    centrifugo.subscribeToCommands(userId, (command) => {
-        if (!ready)
-            return;
-        handleCommand(command).catch((err) => {
-            console.error(`[Bridge] Unhandled error in command handler:`, err);
+        let ready = false;
+        browserAccess = new BrowserAccess({
+            dataDir,
+            cloudNonce: opts.local || solo ? undefined : localNonce,
+            allowedOrigins: apiOrigin ? [apiOrigin] : [],
+            bootstrap: () => ({ version: 1, userId, bridgeId, hostname: osHostname(), localPort: hookPort, localNonce: '' }),
+            execute: async (command) => {
+                if (!ready)
+                    return { requestId: command.requestId, success: false, error: 'Bridge is starting; try again shortly' };
+                let result;
+                await createCommandHandler({
+                    bridgeId, sessionController,
+                    publishCommandResponse: async (response) => { result = response; },
+                })(command);
+                return result ?? { requestId: command.requestId, success: false, error: 'Command was not handled' };
+            },
+            onRevoke: () => loopbackServer.disconnectPeers(),
         });
-    }, (directCommand) => {
-        publishRouter.handleCommand(directCommand);
-    });
-    setTimeout(() => {
-        void (async () => {
-            ready = true;
-            console.log('[Bridge] Ready and listening for commands');
+        localApiServer.setBrowserAccess(browserAccess);
+        centrifugo.onLocalPublication((channel, data) => browserAccess?.publish(channel, data));
+        console.log(`[Bridge] Local browser access: run ${commandName} pair${opts.dataDir ? ` --data-dir ${JSON.stringify(dataDir)}` : ''}`);
+        const handleCommand = createCommandHandler({
+            bridgeId,
+            relayRequest: createRelayHandler(hookPort, apiToken),
+            sessionController,
+            publishCommandResponse: (response) => centrifugo.publishCommandResponse(userId, response),
+        });
+        // Solo: the hub child must be healthy before connecting (L1 gates the
+        // transport, not the front). A failed hub is fatal for solo — exit cleanly
+        // instead of crashing on an unhandled rejection.
+        if (solo) {
             try {
-                await resurrection.resurrectSessions();
+                await solo.hubReady;
+                console.log('[Solo] Hub healthy — connecting Centrifugo client');
             }
             catch (err) {
-                console.error('[Bridge] Session resurrection failed:', err);
+                console.error('[Solo] Cannot continue without the hub:', err instanceof Error ? err.message : String(err));
+                process.exit(1);
             }
-        })();
-    }, 2000);
-    const shutdown = () => {
-        console.log('\n[Bridge] Shutting down...');
-        // Solo L2 ordering: stop accepting first, then children (panel before
-        // hub), then the rest of the bridge teardown.
-        if (solo) {
-            void solo.front.close().catch(() => { });
-            solo.panel.stop();
-            solo.hub.stop();
-        }
-        localApiServer.stop();
-        runner.stopAll();
-        loopbackServer.closeAll();
-        directPeers.closeAll();
-        watchRegistry.dispose();
-        // node-datachannel module-level cleanup — avoids the native crash-on-exit race.
-        try {
-            ndcCleanup();
         }
-        catch { /* native lib already torn down */ }
-        centrifugo.disconnect();
-        process.exit(0);
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
-});
-registerLocalBrowserCommands(program);
-program.parseAsync().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});
+        centrifugo.connect();
+        centrifugo.joinBridgesChannel(userId, bridgeId);
+        centrifugo.subscribeToSessions(userId);
+        centrifugo.subscribeToCommands(userId, (command) => {
+            if (!ready)
+                return;
+            handleCommand(command).catch((err) => {
+                console.error(`[Bridge] Unhandled error in command handler:`, err);
+            });
+        }, (directCommand) => {
+            publishRouter.handleCommand(directCommand);
+        });
+        setTimeout(() => {
+            void (async () => {
+                ready = true;
+                console.log('[Bridge] Ready and listening for commands');
+                try {
+                    await resurrection.resurrectSessions();
+                }
+                catch (err) {
+                    console.error('[Bridge] Session resurrection failed:', err);
+                }
+            })();
+        }, 2000);
+        const shutdown = () => {
+            console.log('\n[Bridge] Shutting down...');
+            attentionStore.stopNotifications();
+            stopPushSessionObserver();
+            pushNotifier?.stop();
+            // Solo L2 ordering: stop accepting first, then children (panel before
+            // hub), then the rest of the bridge teardown.
+            if (solo) {
+                void solo.front.close().catch(() => { });
+                solo.panel.stop();
+                solo.hub.stop();
+            }
+            localApiServer.stop();
+            runner.stopAll();
+            loopbackServer.closeAll();
+            directPeers.closeAll();
+            watchRegistry.dispose();
+            // node-datachannel module-level cleanup — avoids the native crash-on-exit race.
+            try {
+                ndcCleanup();
+            }
+            catch { /* native lib already torn down */ }
+            centrifugo.disconnect();
+            process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+    registerLocalBrowserCommands(program);
+    try {
+        await program.parseAsync(argv, { from: 'user' });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError)
+            return error.exitCode;
+        throw error;
+    }
+}
+if (isCliEntry(import.meta.url, process.argv[1])) {
+    void executeCli(() => runBridge(process.argv.slice(2)));
+}
 //# sourceMappingURL=index.js.map