total-recall-brain 3.25.5 → 3.26.0

package/frontend/dist/index.html

@@ -17,7 +17,7 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-BX15G8l-.js"></script>
+    <script type="module" crossorigin src="/assets/index-Bl3I11B0.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/frontend/src/api/mesh.ts

@@ -303,6 +303,38 @@ export async function registerNode(authId: string, user?: string): Promise<Regis
   return data as RegisteredNode;
 }
 
+export interface WatchStatus {
+  state: 'idle' | 'watching' | 'registered' | 'expired' | 'stopped' | 'unavailable' | 'error';
+  id?: string | null;
+  node?: { id: string | null; name: string | null; ip_addresses: string[] } | null;
+  error?: string | null;
+  remaining_ms?: number;
+  source?: string;
+}
+
+/** Arm the server to approve the next device that signs in. */
+export async function startWatch(ttlMinutes?: number): Promise<WatchStatus> {
+  const res = await apiFetch(`${API_BASE}/api/mesh/watch`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(ttlMinutes ? { ttlMinutes } : {}),
+  });
+  // 409 means watch mode is not available here — a real answer the UI acts on,
+  // not an error to throw away.
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok && res.status !== 409) throw new Error(data.error || `watch failed: ${res.status}`);
+  return data as WatchStatus;
+}
+
+export async function getWatchStatus(): Promise<WatchStatus> {
+  return get('/api/mesh/watch');
+}
+
+export async function stopWatch(): Promise<WatchStatus> {
+  const res = await apiFetch(`${API_BASE}/api/mesh/watch`, { method: 'DELETE' });
+  return (await res.json().catch(() => ({ state: 'idle' }))) as WatchStatus;
+}
+
 export async function fetchEnrollmentStatus(): Promise<EnrollmentStatus> {
   return get('/api/mesh/enrollment');
 }

package/frontend/src/components/MobilePairing.spec.tsx

@@ -51,4 +51,103 @@ describe('MobilePairing', () => {
     expect(screen.getByTestId('pairing-qr')).toBeTruthy();
     expect(screen.getByTestId('pairing-warnings')).toBeTruthy();
   });
+  it('sends you to enrol the device instead of hand-waving "log into your tailnet"', async () => {
+    // The old copy said "Log into your tailnet/headscale server" -- five words
+    // covering an iOS flow that needs the alternate coordination server, a
+    // keychain reset and server-side approval. Scanning a 100.64.x.x QR from a
+    // phone that has not joined just times out.
+    render(<MobilePairing />);
+    expect(await screen.findByText(/Add a device to the tailnet/i)).toBeTruthy();
+    expect(screen.getByText(/Reset Keychain/i)).toBeTruthy();
+  });
+
+  const pairingResponse = (over = {}) => ({
+    ok: true,
+    json: async () => ({
+      port: 3000,
+      protocol: 'http',
+      preferred_url: 'http://100.64.0.2:3000',
+      listen_hosts: ['127.0.0.1'],
+      listen_hosts_source: 'actual',
+      reachable_from_other_devices: false,
+      warnings: ['This brain is listening on loopback only'],
+      endpoints: [
+        {
+          kind: 'mesh',
+          label: 'Tailscale / mesh',
+          ip: '100.64.0.2',
+          url: 'http://100.64.0.2:3000',
+          recommended: true,
+          reachable_hint: 'Tailscale',
+          listening: false,
+        },
+      ],
+      ...over,
+    }),
+  });
+
+  it('says no device can reach the brain instead of drawing a QR that fails', async () => {
+    // The Mac Mini shipped this card for a week: brain bound loopback-only
+    // after losing the boot race to the mesh client, while the card happily
+    // recommended a mesh URL nothing had ever listened on.
+    vi.mocked(apiFetch).mockResolvedValue(pairingResponse() as never);
+
+    render(<MobilePairing />);
+
+    const alert = await screen.findByTestId('pairing-unreachable');
+    expect(alert.textContent).toMatch(/No other device can reach this brain/i);
+    // Naming the cause is what turns an error into something a user can act on.
+    expect(alert.textContent).toMatch(/still starting when the brain launched/i);
+    expect(alert.textContent).toMatch(/restart the brain/i);
+    // And the code itself must not look scannable.
+    expect(screen.getByTestId('pairing-qr-dead')).toBeTruthy();
+  });
+
+  it('flags the specific address that is not listening', async () => {
+    vi.mocked(apiFetch).mockResolvedValue(pairingResponse() as never);
+    render(<MobilePairing />);
+    await screen.findByTestId('pairing-unreachable');
+    expect(screen.getByTestId('pairing-endpoint-select').textContent).toMatch(/not listening/i);
+  });
+
+  it('stays quiet when the brain is genuinely reachable', async () => {
+    vi.mocked(apiFetch).mockResolvedValue(
+      pairingResponse({
+        preferred_url: 'http://100.64.0.6:3000',
+        listen_hosts: ['100.64.0.6', '127.0.0.1'],
+        reachable_from_other_devices: true,
+        warnings: [],
+        endpoints: [
+          {
+            kind: 'mesh',
+            label: 'Tailscale / mesh',
+            ip: '100.64.0.6',
+            url: 'http://100.64.0.6:3000',
+            recommended: true,
+            reachable_hint: 'Tailscale',
+            listening: true,
+          },
+        ],
+      }) as never,
+    );
+    render(<MobilePairing />);
+    await waitFor(() => {
+      expect(screen.getByTestId('pairing-url').textContent).toContain('100.64.0.6');
+    });
+    expect(screen.queryByTestId('pairing-unreachable')).toBeNull();
+    expect(screen.queryByTestId('pairing-qr-dead')).toBeNull();
+  });
+
+  it('does not cry wolf when the server could not observe its own sockets', async () => {
+    // `null` is unknown. Rendering unknown as a red banner would put a false
+    // alarm on every install whose page load beat the listen callback.
+    vi.mocked(apiFetch).mockResolvedValue(
+      pairingResponse({ reachable_from_other_devices: null, listen_hosts_source: 'derived' }) as never,
+    );
+    render(<MobilePairing />);
+    await waitFor(() => {
+      expect(screen.getByTestId('pairing-url')).toBeTruthy();
+    });
+    expect(screen.queryByTestId('pairing-unreachable')).toBeNull();
+  });
 });

package/frontend/src/components/MobilePairing.tsx

@@ -10,6 +10,8 @@ export interface PairingEndpoint {
   interface?: string | null;
   recommended: boolean;
   reachable_hint: string;
+  /** null when the server could not observe its own sockets. */
+  listening?: boolean | null;
 }
 
 export interface PairingInfo {
@@ -19,6 +21,10 @@ export interface PairingInfo {
   endpoints: PairingEndpoint[];
   warnings: string[];
   listen_hosts: string[];
+  /** 'actual' = observed sockets. 'derived' = a guess; do not render as fact. */
+  listen_hosts_source?: 'actual' | 'derived';
+  /** null means unknown — must not be shown as either working or broken. */
+  reachable_from_other_devices?: boolean | null;
 }
 
 export function MobilePairing() {
@@ -67,6 +73,8 @@ export function MobilePairing() {
         ],
         warnings: ['Could not load live network endpoints from the brain.'],
         listen_hosts: [],
+        listen_hosts_source: 'derived',
+        reachable_from_other_devices: null,
       });
     } finally {
       setLoading(false);
@@ -78,6 +86,9 @@ export function MobilePairing() {
   }, []);
 
   const selected = info?.endpoints?.find((e) => e.url === selectedUrl) || null;
+  // Observed, not guessed. `undefined`/`null` means the server could not tell
+  // us — that is not the same as broken, so it must not raise this banner.
+  const unreachable = info?.reachable_from_other_devices === false;
   const isLoopback =
     selected?.kind === 'loopback' ||
     selectedUrl.includes('127.0.0.1') ||
@@ -111,6 +122,39 @@ export function MobilePairing() {
         Wi‑Fi, or <strong>Tailscale/mesh</strong> if the phone is on your tailnet.
       </p>
 
+      {unreachable && (
+        <div
+          role="alert"
+          data-testid="pairing-unreachable"
+          style={{
+            marginBottom: 16,
+            padding: '12px 14px',
+            borderRadius: 8,
+            border: '1px solid #ef4444',
+            background: 'rgba(239, 68, 68, 0.08)',
+            color: 'var(--text-primary)',
+            fontSize: 13,
+            lineHeight: 1.55,
+          }}
+        >
+          <div style={{ fontWeight: 700, marginBottom: 4 }}>
+            No other device can reach this brain
+          </div>
+          <div style={{ color: 'var(--text-secondary)' }}>
+            It is listening on{' '}
+            <code>{info?.listen_hosts?.join(', ') || 'loopback'}</code> only, so every code on this
+            card is a dead address — a phone that scans one will time out no matter how it is
+            connected. This normally means the mesh client was still starting when the brain
+            launched, so the brain never got a mesh address to bind.
+            <div style={{ marginTop: 6 }}>
+              <strong>Fix:</strong> restart the brain now that the mesh is up. It re-checks for a
+              mesh address on its own for the first few minutes after launch, so a restart is
+              usually all this needs.
+            </div>
+          </div>
+        </div>
+      )}
+
       {loading && (
         <div data-testid="pairing-loading" style={{ color: 'var(--text-tertiary)', fontSize: 13 }}>
           Detecting reachable addresses…
@@ -149,7 +193,33 @@ export function MobilePairing() {
             data-testid="pairing-qr"
           >
             {selectedUrl ? (
-              <QRCodeSVG value={selectedUrl} size={150} level="M" includeMargin />
+              <div style={{ position: 'relative' }}>
+                {/* Greyed rather than hidden: the address is still the right one
+                    to reach for once the bind is fixed. */}
+                <div style={{ opacity: unreachable ? 0.15 : 1 }}>
+                  <QRCodeSVG value={selectedUrl} size={150} level="M" includeMargin />
+                </div>
+                {unreachable && (
+                  <div
+                    data-testid="pairing-qr-dead"
+                    style={{
+                      position: 'absolute',
+                      inset: 0,
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      textAlign: 'center',
+                      padding: 8,
+                      color: '#b91c1c',
+                      fontSize: 12,
+                      fontWeight: 700,
+                      lineHeight: 1.4,
+                    }}
+                  >
+                    Nothing is listening on this address
+                  </div>
+                )}
+              </div>
             ) : (
               <div style={{ width: 150, height: 150 }} />
             )}
@@ -173,6 +243,7 @@ export function MobilePairing() {
                     <option key={ep.url} value={ep.url}>
                       {ep.label}
                       {ep.recommended ? ' ★' : ''} — {ep.url}
+                      {ep.listening === false ? ' (not listening)' : ''}
                     </option>
                   ))}
                 </select>
@@ -243,7 +314,17 @@ export function MobilePairing() {
 
       <div style={{ marginTop: 16, padding: '12px 14px', background: 'rgba(59, 130, 246, 0.06)', borderRadius: 8, border: '1px solid rgba(59, 130, 246, 0.15)', fontSize: 12, color: 'var(--text-secondary)', lineHeight: 1.5 }}>
         <div style={{ color: 'var(--text-primary)', fontWeight: 600, marginBottom: 4 }}>📱 How to connect your phone:</div>
-        <div><strong>Option A (WireGuard / Mesh — Recommended):</strong> Install the standard <em>Tailscale</em> app on your phone (iOS App Store / Google Play). Log into your tailnet/headscale server. Scan the <code>100.64.x.x</code> QR code above.</div>
+        <div>
+          <strong>Option A (WireGuard / Mesh — Recommended):</strong> The device has to be <em>on the tailnet</em>
+          before a <code>100.64.x.x</code> address can reach anything — scanning this QR from a phone that has not
+          joined will simply time out. Join it first in{' '}
+          <strong>Add a device to the tailnet</strong>, directly below, which has the per-platform steps.
+          <div style={{ marginTop: 4, opacity: 0.85 }}>
+            Short version: <strong>Android / ChromeOS</strong> take an enrollment key directly. <strong>iOS</strong>
+            {' '}cannot — it needs the alternate coordination server set in iOS Settings, <em>Reset Keychain</em> turned
+            on, and then approval from that card. Once joined, come back and scan the <code>100.64.x.x</code> code.
+          </div>
+        </div>
         <div style={{ marginTop: 4 }}><strong>Option B (Local Home Wi-Fi):</strong> Check <strong>Allow Public Bind</strong> in <em>Network & Binding</em> below, restart the server, and scan your local Wi-Fi LAN QR code (e.g. <code>192.168.x.x</code>).</div>
       </div>
     </div>

package/frontend/src/components/TailnetEnroll.spec.tsx

@@ -6,8 +6,12 @@ vi.mock('../api/mesh', () => ({
   fetchNodes: vi.fn(),
   fetchEnrollmentStatus: vi.fn(),
   mintPreAuthKey: vi.fn(),
+  registerNode: vi.fn(),
+  startWatch: vi.fn(),
+  getWatchStatus: vi.fn(),
+  stopWatch: vi.fn(),
 }));
-import { fetchNodes, fetchEnrollmentStatus, mintPreAuthKey } from '../api/mesh';
+import { fetchNodes, fetchEnrollmentStatus, mintPreAuthKey, startWatch } from '../api/mesh';
 
 const node = (over = {}) => ({
   hostname: 'laptop', ip: '100.64.0.3', online: true, self: false, os: 'macOS', ...over,
@@ -150,4 +154,28 @@ describe('TailnetEnroll', () => {
     expect(screen.getByText(/Crostini/i)).toBeTruthy();
   });
 
+  it('leads with a watch button rather than a key to carry between devices', async () => {
+    // No Tailscale client can scan a QR to authenticate, and nobody types a
+    // 40-character secret from a laptop into a phone. The device generates the
+    // id and waits; the server approves it.
+    vi.mocked(startWatch).mockResolvedValue({ state: 'watching', remaining_ms: 300000 } as never);
+    render(<TailnetEnroll />);
+    const btn = await screen.findByTestId('watch-start');
+    fireEvent.click(btn);
+    await waitFor(() => expect(screen.getByTestId('watch-active')).toBeTruthy());
+    expect(startWatch).toHaveBeenCalled();
+  });
+
+  it('says watch mode is unavailable instead of offering a button that cannot work', async () => {
+    vi.mocked(startWatch).mockResolvedValue({
+      state: 'unavailable',
+      error: 'no log source is configured.',
+    } as never);
+    render(<TailnetEnroll />);
+    fireEvent.click(await screen.findByTestId('watch-start'));
+    await waitFor(() => expect(screen.getByTestId('watch-unavailable')).toBeTruthy());
+    // and the manual path is still reachable
+    expect(screen.getByTestId('enroll-approve')).toBeTruthy();
+  });
+
 });

package/frontend/src/components/TailnetEnroll.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { QRCodeSVG } from 'qrcode.react';
-import { fetchNodes, fetchEnrollmentStatus, mintPreAuthKey, registerNode } from '../api/mesh';
+import { fetchNodes, fetchEnrollmentStatus, mintPreAuthKey, registerNode, startWatch, getWatchStatus, stopWatch } from '../api/mesh';
+import type { WatchStatus } from '../api/mesh';
 import type { MeshNode, PreAuthKey } from '../api/mesh';
 
 /**
@@ -28,6 +29,7 @@ export function TailnetEnroll() {
   const [authId, setAuthId] = useState('');
   const [approving, setApproving] = useState(false);
   const [approved, setApproved] = useState<string | null>(null);
+  const [watch, setWatch] = useState<WatchStatus | null>(null);
 
   useEffect(() => {
     fetchNodes()
@@ -64,6 +66,34 @@ export function TailnetEnroll() {
     }
   };
 
+  // Poll while armed. The server holds the watch; this only mirrors it, so a
+  // page reload cannot orphan a running watch.
+  useEffect(() => {
+    if (watch?.state !== 'watching') return undefined;
+    const id = setInterval(async () => {
+      try {
+        const st = await getWatchStatus();
+        setWatch(st);
+        if (st.state === 'registered') setNodes(await fetchNodes().catch(() => nodes));
+      } catch { /* transient */ }
+    }, 2000);
+    return () => clearInterval(id);
+  }, [watch?.state, nodes]);
+
+  const arm = async () => {
+    setError(null);
+    setApproved(null);
+    try {
+      setWatch(await startWatch(5));
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'could not start watching');
+    }
+  };
+
+  const disarm = async () => {
+    try { setWatch(await stopWatch()); } catch { setWatch(null); }
+  };
+
   const approve = async () => {
     setApproving(true);
     setError(null);
@@ -136,11 +166,63 @@ export function TailnetEnroll() {
           existed, finishing that required SSH and a CLI -- on the machine you
           are not holding.
         */}
+        {/*
+          The primary action. The device generates the id and waits; the server
+          approves it. Nothing is typed, copied or scanned — which matters
+          because no Tailscale client scans QR codes to authenticate, and moving
+          a 40-character key from a laptop to a phone by hand is not a flow
+          anyone finishes.
+        */}
         <div
+          data-testid="enroll-watch"
+          style={{ margin: '0 0 12px', padding: 12, borderRadius: 8, border: '1px solid var(--border)' }}
+        >
+          <strong style={{ fontSize: 12 }}>Add a device</strong>
+          <p style={{ fontSize: 12, opacity: 0.75, margin: '4px 0 8px' }}>
+            Press this, then sign in on the device. It joins on its own — nothing to copy.
+          </p>
+
+          {watch?.state === 'watching' ? (
+            <div style={{ display: 'flex', gap: 10, alignItems: 'center', flexWrap: 'wrap' }}>
+              <span data-testid="watch-active" style={{ fontSize: 12, color: '#10b981' }}>
+                ● Watching — sign in on the device now
+                {typeof watch.remaining_ms === 'number'
+                  ? ` (${Math.ceil(watch.remaining_ms / 1000)}s left)`
+                  : ''}
+              </span>
+              <button type="button" onClick={disarm} data-testid="watch-stop">Stop</button>
+            </div>
+          ) : (
+            <button type="button" onClick={arm} data-testid="watch-start">
+              Watch for a device
+            </button>
+          )}
+
+          {watch?.state === 'registered' && (
+            <p data-testid="watch-registered" style={{ fontSize: 12, color: '#10b981', margin: '8px 0 0' }}>
+              {watch.node?.name || 'Device'} joined the tailnet
+              {watch.node?.ip_addresses?.[0] ? ` (${watch.node.ip_addresses[0]})` : ''}.
+            </p>
+          )}
+          {watch?.state === 'expired' && (
+            <p data-testid="watch-expired" style={{ fontSize: 12, color: '#f59e0b', margin: '8px 0 0' }}>
+              Nothing signed in before the watch ran out. Press it again when the device is ready.
+            </p>
+          )}
+          {watch?.state === 'unavailable' && (
+            <p data-testid="watch-unavailable" style={{ fontSize: 12, color: '#f59e0b', margin: '8px 0 0' }}>
+              {watch.error} Use the manual box below in the meantime.
+            </p>
+          )}
+        </div>
+
+        <details
           data-testid="enroll-approve"
           style={{ margin: '0 0 12px', padding: 12, borderRadius: 8, border: '1px solid var(--border)' }}
         >
-          <strong style={{ fontSize: 12 }}>Device waiting for approval?</strong>
+          <summary style={{ cursor: 'pointer' }}>
+            <strong style={{ fontSize: 12 }}>Device waiting for approval? (manual)</strong>
+          </summary>
           <p style={{ fontSize: 12, opacity: 0.75, margin: '4px 0 8px' }}>
             If a device shows “run the command below in the headscale server”, paste that whole line
             (or just the <code>hskey-authreq-…</code> part) here.
@@ -173,7 +255,7 @@ export function TailnetEnroll() {
               {approved}
             </p>
           )}
-        </div>
+        </details>
 
         <details open style={{ fontSize: 12 }}>
           <summary style={{ cursor: 'pointer', fontWeight: 600 }}>On a phone (iOS)</summary>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.25.5",
+  "version": "3.26.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/src/core/bound-hosts.mjs

@@ -0,0 +1,64 @@
+/**
+ * bound-hosts — what the server ACTUALLY bound, as opposed to what it hoped to.
+ *
+ * The pairing card renders a QR code of the URL it believes a phone can reach.
+ * It used to work that URL out by derivation: loopback, plus whatever
+ * `getMeshIp()` reported at the moment the card was opened. That derivation is
+ * wrong on any machine where the mesh came up AFTER the brain did.
+ *
+ * The Mac Mini is the worked example. Its brain started 2026-08-13 while
+ * Tailscale was still starting, so `getMeshIp()` returned null and the bind
+ * fell back to loopback only. A week later Tailscale answers perfectly, so the
+ * card derived `listen_hosts = [127.0.0.1, 100.64.0.2]`, recommended the mesh
+ * URL, and drew a QR for an address nothing has ever listened on -- while
+ * reporting no warning, because every check downstream was reading the guess.
+ *
+ * A socket knows its own address. Registering each successful listen here means
+ * the card reports observed truth, and "no other device can reach this brain"
+ * becomes something the UI can state instead of something the user discovers.
+ */
+
+/** @type {Set<string>} */
+const bound = new Set();
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+
+/** Record an address the server has successfully bound. */
+export function registerBoundHost(host) {
+  if (host === null || host === undefined || host === '') return;
+  bound.add(String(host));
+}
+
+/** Forget an address (a listener closed, or a late bind was replaced). */
+export function unregisterBoundHost(host) {
+  bound.delete(String(host));
+}
+
+/** Every address currently listening. Order is insertion order. */
+export function getBoundHosts() {
+  return [...bound];
+}
+
+/** Test seam — module state is process-wide by design. */
+export function resetBoundHosts() {
+  bound.clear();
+}
+
+export function isLoopbackHost(host) {
+  return LOOPBACK.has(String(host));
+}
+
+/**
+ * Is this brain reachable from any device other than the one it runs on?
+ *
+ * `0.0.0.0` / `::` count as reachable: they accept from every interface.
+ * An empty set means nothing has registered yet -- unknown, not unreachable,
+ * so callers must not render that as a failure.
+ *
+ * @returns {boolean|null} null when nothing is known yet
+ */
+export function isReachableFromOtherDevices() {
+  const hosts = getBoundHosts();
+  if (!hosts.length) return null;
+  return hosts.some((h) => !isLoopbackHost(h));
+}

package/src/core/mesh-late-bind.mjs

@@ -0,0 +1,105 @@
+/**
+ * mesh-late-bind — bind the mesh address when the mesh shows up late.
+ *
+ * `resolveServerHost()` runs once, during startup, and whatever it decides is
+ * permanent for the life of the process. At boot that is a race the brain can
+ * lose: if the mesh client is still starting, `getMeshIp()` returns null, the
+ * bind falls back to loopback, and the node is unreachable from every other
+ * device until somebody restarts it by hand.
+ *
+ * Nothing reports this. The node looks healthy from its own console, answers
+ * `/health` on loopback, and is simply absent from the tailnet. One machine sat
+ * that way for a week.
+ *
+ * So: when the brain ends up loopback-only, watch for a mesh address and bind
+ * it the moment one exists. Polling is the honest mechanism here -- the mesh
+ * client offers no readiness event to subscribe to.
+ */
+
+const DEFAULT_INTERVAL_MS = 15_000;
+const DEFAULT_MAX_WAIT_MS = 10 * 60 * 1000;
+
+/**
+ * @param {object} opts
+ * @param {() => (string|null)} opts.getMeshIp
+ * @param {(ip: string) => Promise<void>} opts.bind   resolves once listening
+ * @param {() => string[]} opts.boundHosts            addresses already listening
+ * @param {number} [opts.intervalMs]
+ * @param {number} [opts.maxWaitMs]  give up after this long; 0 disables the cap
+ * @param {{info: Function, warn: Function}} [opts.logger]
+ * @returns {{stop: () => void, promise: Promise<string|null>}}
+ */
+export function startMeshBindWatch({
+  getMeshIp,
+  bind,
+  boundHosts,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  maxWaitMs = DEFAULT_MAX_WAIT_MS,
+  logger,
+} = {}) {
+  let timer = null;
+  let stopped = false;
+  let settle;
+  const promise = new Promise((resolve) => { settle = resolve; });
+  const startedAt = Date.now();
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+    settle(null);
+  };
+
+  const schedule = () => {
+    if (stopped) return;
+    timer = setTimeout(tick, intervalMs);
+    // Never keep the process alive for this; it is opportunistic repair.
+    timer.unref?.();
+  };
+
+  const tick = async () => {
+    if (stopped) return;
+    if (maxWaitMs > 0 && Date.now() - startedAt >= maxWaitMs) {
+      logger?.warn?.(
+        'server',
+        'Mesh address never appeared; this brain stays reachable only on loopback. '
+        + 'Other devices cannot open its UI until the mesh client is running and the brain restarts.',
+      );
+      stop();
+      return;
+    }
+
+    let ip = null;
+    try {
+      ip = getMeshIp();
+    } catch {
+      ip = null;
+    }
+
+    if (!ip || boundHosts().includes(ip)) {
+      schedule();
+      return;
+    }
+
+    try {
+      await bind(ip);
+      logger?.info?.(
+        'server',
+        `Mesh address ${ip} appeared after startup — now also listening there, `
+        + 'so other devices on the mesh can reach this brain.',
+      );
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      settle(ip);
+    } catch (err) {
+      // Port taken by another process, address not ready yet: keep trying.
+      logger?.warn?.('server', `Late mesh bind to ${ip} failed: ${err?.message || err}`);
+      schedule();
+    }
+  };
+
+  schedule();
+  return { stop, promise };
+}