npm - total-recall-brain - Versions diffs - 3.25.6 → 3.28.0 - Mend

total-recall-brain 3.25.6 → 3.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/bin/total-recall.mjs +31 -1
package/docs/ARCHITECTURE.md +76 -9
package/frontend/dist/assets/index-U7o-qU99.js +5742 -0
package/frontend/dist/index.html +1 -1
package/frontend/src/App.tsx +39 -1
package/frontend/src/api/index.ts +1 -0
package/frontend/src/api/mesh.ts +32 -0
package/frontend/src/api/plugins.ts +167 -0
package/frontend/src/components/MobilePairing.spec.tsx +89 -0
package/frontend/src/components/MobilePairing.tsx +72 -1
package/frontend/src/components/TailnetEnroll.spec.tsx +29 -1
package/frontend/src/components/TailnetEnroll.tsx +85 -3
package/frontend/src/pages/ChatPage.tsx +44 -17
package/frontend/src/pages/IntegrationsPage.tsx +7 -0
package/frontend/src/pages/PluginsPage.spec.tsx +17 -0
package/frontend/src/pages/PluginsPage.tsx +1331 -0
package/package.json +1 -1
package/scaffold/.agent/plugins/.gitkeep +0 -0
package/scaffold/.agent/plugins/code-quality/README.md +16 -0
package/scaffold/.agent/plugins/code-quality/cli.mjs +15 -0
package/scaffold/.agent/plugins/code-quality/plugin.json +34 -0
package/scaffold/.agent/plugins/git-sentinel/README.md +16 -0
package/scaffold/.agent/plugins/git-sentinel/cli.mjs +86 -0
package/scaffold/.agent/plugins/git-sentinel/plugin.json +34 -0
package/scaffold/.agent/plugins/meta-harness/README.md +16 -0
package/scaffold/.agent/plugins/meta-harness/cli.mjs +34 -0
package/scaffold/.agent/plugins/meta-harness/plugin.json +34 -0
package/scaffold/.agent/plugins/system-monitor/README.md +16 -0
package/scaffold/.agent/plugins/system-monitor/cli.mjs +79 -0
package/scaffold/.agent/plugins/system-monitor/generator.mjs +20 -0
package/scaffold/.agent/plugins/system-monitor/plugin.json +38 -0
package/scaffold/.agent/skills/meta-harness/SKILL.md +113 -0
package/scaffold/.agent/skills/total-recall/references/cli-reference.md +23 -0
package/src/cli/agent.mjs +173 -0
package/src/cli/connect.mjs +89 -4
package/src/cli/deploy-ui.mjs +6 -0
package/src/cli/harness.mjs +135 -0
package/src/cli/ingest-openwiki.mjs +71 -2
package/src/cli/init.mjs +1 -0
package/src/cli/lint.mjs +47 -3
package/src/cli/mesh.mjs +286 -0
package/src/cli/plugin/create.mjs +186 -0
package/src/cli/plugin/index.mjs +139 -0
package/src/cli/plugin/install.mjs +141 -0
package/src/cli/plugin/list.mjs +83 -0
package/src/cli/plugin/remove.mjs +51 -0
package/src/cli/plugin/search.mjs +37 -0
package/src/cli/skill-projection.mjs +14 -0
package/src/cli/wizard.html +9 -0
package/src/core/agent-manager.mjs +290 -0
package/src/core/bound-hosts.mjs +64 -0
package/src/core/cache-prune.mjs +341 -0
package/src/core/context-cache.mjs +130 -0
package/src/core/daemon-loop.mjs +47 -1
package/src/core/evolving-context.mjs +171 -0
package/src/core/mesh-activity.mjs +140 -0
package/src/core/mesh-late-bind.mjs +105 -0
package/src/core/mesh.mjs +174 -1
package/src/core/meta-harness.mjs +251 -0
package/src/core/pairing.mjs +49 -10
package/src/core/plugin-context.mjs +206 -0
package/src/core/plugin-loader.mjs +210 -0
package/src/core/registration-watch.mjs +193 -0
package/src/core/runtime.mjs +65 -13
package/src/core/secrets-store.mjs +8 -0
package/src/core/surface.mjs +32 -10
package/src/server/api.mjs +18 -2
package/src/server/auth.mjs +11 -1
package/src/server/index.mjs +43 -2
package/src/server/rest.mjs +4 -0
package/src/server/route-manifest.json +12 -0
package/src/server/routes/auth.mjs +31 -0
package/src/server/routes/integrations.mjs +5 -1
package/src/server/routes/mesh-presence.mjs +143 -0
package/src/server/routes/mesh.mjs +55 -0
package/src/server/routes/models.mjs +42 -30
package/src/server/routes/plugins.mjs +517 -0
package/src/server/routes/secrets.mjs +1 -0
package/src/server/routes/system.mjs +5 -0
package/src/server/tools.mjs +266 -0
package/frontend/dist/assets/index-DSxCyPAx.js +0 -5742

package/frontend/dist/index.html CHANGED Viewed

@@ -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-DSxCyPAx.js"></script>
+    <script type="module" crossorigin src="/assets/index-U7o-qU99.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/frontend/src/App.tsx CHANGED Viewed

@@ -1,7 +1,7 @@
 import { useState, useEffect } from 'react'
 import { BrowserRouter, Routes, Route, NavLink, Navigate, useLocation } from 'react-router-dom'
 import './App.css'
-import { getApiBase, setApiBase, checkSession, logout, registerUnauthedCallback, fetchHealth } from './api'
+import { getApiBase, setApiBase, checkSession, logout, registerUnauthedCallback, fetchHealth, fetchPlugins, type PluginInfo } from './api'
 import type { HealthData } from './types'
 import LoginPage from './pages/LoginPage'
 import ChatPage from './pages/ChatPage'
@@ -19,6 +19,7 @@ import RulesPage from './pages/RulesPage'
 import HelpPage from './pages/HelpPage'
 import GraphPage from './pages/GraphPage'
 import OpenWikiPage from './pages/OpenWikiPage'
+import PluginsPage from './pages/PluginsPage'
 import OnboardingPage from './pages/OnboardingPage'
 import { NotificationsPage } from './pages/NotificationsPage'
 import { isOnboardingComplete } from './utils/onboarding'
@@ -86,6 +87,12 @@ interface SidebarProps {
 const getNavLinkClass = ({ isActive }: { isActive: boolean }) => `nav-link ${isActive ? 'active' : ''}`;
 function Sidebar({ onLogout, health, activeBrainId, onBrainChange }: SidebarProps) {
+  const [plugins, setPlugins] = useState<PluginInfo[]>([])
+  useEffect(() => {
+    fetchPlugins().then(setPlugins).catch(() => {})
+  }, [])
   return (
     <aside className="sidebar">
       <div className="sidebar-brand">
@@ -158,6 +165,36 @@ function Sidebar({ onLogout, health, activeBrainId, onBrainChange }: SidebarProp
           </svg>
           OpenWiki
         </NavLink>
+        <NavLink to="/plugins" className={getNavLinkClass} id="nav-plugins">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+            <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
+            <line x1="12" y1="22.08" x2="12" y2="12" />
+          </svg>
+          Plugins
+        </NavLink>
+        {plugins.length > 0 && (
+          <>
+            <div className="nav-section-label">Plugins</div>
+            {plugins.map((p) => (
+              <NavLink
+                key={p.id}
+                to={`/plugins?id=${encodeURIComponent(p.id)}`}
+                className={getNavLinkClass}
+                id={`nav-plugin-${p.id}`}
+                title={p.description}
+              >
+                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+                  <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+                  <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
+                  <line x1="12" y1="22.08" x2="12" y2="12" />
+                </svg>
+                {p.name}
+              </NavLink>
+            ))}
+          </>
+        )}
         <div className="nav-section-label">Account</div>
         <NavLink to="/network" className={getNavLinkClass} id="nav-network">
@@ -396,6 +433,7 @@ function MainContent({ activeBrainId, onBrainChange }: { activeBrainId: string;
             <Route path="/tasks" element={<TasksPage />} />
             <Route path="/skills" element={<SkillsPage activeBrainId={activeBrainId} />} />
             <Route path="/openwiki" element={<OpenWikiPage activeBrainId={activeBrainId} />} />
+            <Route path="/plugins" element={<PluginsPage activeBrainId={activeBrainId} />} />
             <Route path="/integrations" element={<IntegrationsPage activeBrainId={activeBrainId} />} />
             <Route path="/keys" element={<Navigate to="/secrets" replace />} />
             <Route path="/settings" element={<SettingsPage activeBrainId={activeBrainId} />} />

package/frontend/src/api/index.ts CHANGED Viewed

@@ -19,3 +19,4 @@ export * from './sessions'
 export * from './integrations'
 export * from './config'
 export * from './secrets'
+export * from './plugins'

package/frontend/src/api/mesh.ts CHANGED Viewed

@@ -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/api/plugins.ts ADDED Viewed

@@ -0,0 +1,167 @@
+// ─── Plugins domain ───────────────────────────────────────────────────────────
+import { apiFetch, API_BASE } from "./_base"
+export interface PluginInfo {
+  id: string
+  name: string
+  version: string
+  description: string
+  valid: boolean
+  errors: string[]
+  dir: string
+  rating: number
+  reviewCount: number
+  installCount: string
+  userRating?: number | null
+  userReview?: string | null
+  verified?: boolean
+  categories: Array<{ name: string; description?: string }>
+  tasks: Array<{ intent: string; schedule: string }>
+  openwiki_hubs: Array<{ title: string; path: string }>
+  tools: Array<{ name: string; description?: string }>
+  cli?: { command: string; handler: string } | null
+  manifest?: Record<string, unknown>
+}
+export interface CatalogPlugin {
+  id: string
+  name: string
+  version: string
+  description: string
+  tags: string[]
+  author: string
+  sourceUrl: string
+  rating: number
+  reviewCount: number
+  installCount: string
+  userRating?: number | null
+  verified?: boolean
+  isInstalled: boolean
+}
+export interface PluginsResponse {
+  success: boolean
+  count: number
+  plugins: PluginInfo[]
+}
+export interface CatalogResponse {
+  success: boolean
+  catalog: CatalogPlugin[]
+}
+export async function fetchPlugins(): Promise<PluginInfo[]> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins`)
+    if (!res.ok) return []
+    const data: PluginsResponse = await res.json()
+    return Array.isArray(data.plugins) ? data.plugins : []
+  } catch {
+    return []
+  }
+}
+export async function fetchPlugin(id: string): Promise<PluginInfo | null> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(id)}`)
+    if (!res.ok) return null
+    const data = await res.json()
+    return data.plugin || null
+  } catch {
+    return null
+  }
+}
+export async function fetchPluginCatalog(): Promise<CatalogPlugin[]> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/catalog`)
+    if (!res.ok) return []
+    const data: CatalogResponse = await res.json()
+    return Array.isArray(data.catalog) ? data.catalog : []
+  } catch {
+    return []
+  }
+}
+export async function installPlugin(options: { source: string; link?: boolean; global?: boolean }): Promise<{ success: boolean; message?: string; error?: string }> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/install`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    })
+    const data = await res.json()
+    if (!res.ok) {
+      return { success: false, error: data.error || data.message || "Failed to install plugin" }
+    }
+    return { success: true, message: data.message }
+  } catch (err: any) {
+    return { success: false, error: err.message || "Network error" }
+  }
+}
+export async function removePlugin(id: string, global = false): Promise<{ success: boolean; message?: string; error?: string }> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(id)}?global=${global ? "true" : "false"}`, {
+      method: "DELETE"
+    })
+    const data = await res.json()
+    if (!res.ok) {
+      return { success: false, error: data.error || data.message || "Failed to remove plugin" }
+    }
+    return { success: true, message: data.message }
+  } catch (err: any) {
+    return { success: false, error: err.message || "Network error" }
+  }
+}
+export async function ratePlugin(id: string, rating: number, review?: string): Promise<{ success: boolean; message?: string; error?: string }> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(id)}/rate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ rating, review })
+    })
+    const data = await res.json()
+    if (!res.ok) {
+      return { success: false, error: data.error || data.message || "Failed to submit rating" }
+    }
+    return { success: true, message: data.message }
+  } catch (err: any) {
+    return { success: false, error: err.message || "Network error" }
+  }
+}
+export async function runPluginCommand(
+  id: string,
+  subcommand = "",
+  args: string[] = []
+): Promise<{ success: boolean; output?: string; error?: string }> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(id)}/run`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ subcommand, args })
+    })
+    const data = await res.json()
+    if (!res.ok) {
+      return { success: false, error: data.error || data.message || "Failed to execute plugin command" }
+    }
+    return { success: true, output: data.output || "" }
+  } catch (err: any) {
+    return { success: false, error: err.message || "Network error" }
+  }
+}
+export async function fetchPluginReadme(id: string): Promise<string> {
+  try {
+    const res = await apiFetch(`${API_BASE}/api/plugins/${encodeURIComponent(id)}/readme`)
+    if (!res.ok) return ""
+    const data = await res.json()
+    return data.readme || ""
+  } catch {
+    return ""
+  }
+}

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

@@ -61,4 +61,93 @@ describe('MobilePairing', () => {
     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 CHANGED Viewed

@@ -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>

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

@@ -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 CHANGED Viewed

@@ -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>