total-recall-brain 3.41.0 → 3.41.2

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/headscale-client.mjs

@@ -3,14 +3,19 @@ const { loadPluginModule: __loadOwnedPlugin } = await importHostModule('src/core
 /**
  * Headscale control-server client.
  *
- * Single implementation shared by the REST proxy (`routes/headscale.mjs`) and
- * automatic node enrollment (`mesh-enroll.mjs`). No control-server URL is ever
- * hardcoded here — it is resolved from the operator's own secret entry or
- * environment, so this works against any Headscale (or Tailscale SaaS) install.
+ * Host side of the Headscale client, shared by the REST proxy
+ * (`routes/headscale.mjs`) and automatic node enrollment (`mesh-enroll.mjs`).
+ * This module only resolves the operator's credential from the auth plugin and
+ * the throttled transport; the API calls themselves live in the host-free
+ * brick (`capability/headscale-api.mjs`). No control-server URL is ever
+ * hardcoded — it comes from the operator's own secret entry or environment.
  */
-import path from 'node:path';
-const { getSecretsCatalog, getSecret, defaultBrainDir } = await __loadOwnedPlugin('auth', 'secrets-store');
+const { getSecretsCatalog, getSecret } = await __loadOwnedPlugin('auth', 'secrets-store');
+const { hostSecretsBrainDir } = await __loadOwnedPlugin('auth', 'host-secrets-store');
 import { throttledFetch } from './throttled-fetch.mjs';
+import { createHeadscaleApi, assertSecureControlUrl, normalizeControlUrl, buildMeshSshPolicy } from '../../capability/headscale-api.mjs';
+
+export { assertSecureControlUrl, normalizeControlUrl, buildMeshSshPolicy };
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -20,34 +25,15 @@ export function headscaleUrlFromEnv() {
   return raw.trim() || null;
 }
 
-/**
- * Reject non-HTTPS control servers (loopback excepted for local development).
- * Bearer tokens must never travel in cleartext over a network hop.
- */
-export function assertSecureControlUrl(url) {
-  const parsed = new URL(url);
-  const isLoopback = ['localhost', '127.0.0.1', '::1'].includes(parsed.hostname);
-  if (parsed.protocol !== 'https:' && !(isLoopback && parsed.protocol === 'http:')) {
-    throw new Error('Headscale URL must use HTTPS (HTTP is allowed only for loopback development)');
-  }
-  return parsed;
-}
-
-/** Strip a trailing slash so path joining stays predictable. */
-export function normalizeControlUrl(url) {
-  const value = String(url || '').trim();
-  return value.endsWith('/') ? value.slice(0, -1) : value;
-}
-
 /**
  * Locate the operator's headscale credential without knowing its key name.
  * Any secret whose provider is `headscale` is treated as the control-server token.
  *
- * Only the explicitly selected auth store is searched. Missing credentials
- * and unlock failures never select another brain or ambient token.
+ * Auth selects its one store for this host (or explicit TR_SECRETS_BRAIN).
+ * The caller's project brain never creates or selects a second credential store.
  */
 async function locateHeadscaleKey(brainDir) {
-  const target = brainDir || defaultBrainDir();
+  const target = hostSecretsBrainDir();
 
   const local = await getSecretsCatalog(target);
   const hit = local.keys.find((k) => k.provider === 'headscale');
@@ -112,174 +98,41 @@ export async function describeHeadscaleAvailability(brainDir) {
   }
 }
 
+/** A brick client bound to this brain's credential, over the host's throttled transport. */
+async function hostApi(brainDir) {
+  const { url, token } = await resolveHeadscaleConfig(brainDir);
+  return createHeadscaleApi({
+    url,
+    token,
+    fetch: (target, { timeoutMs, ...options }) => throttledFetch(target, options, timeoutMs || DEFAULT_TIMEOUT_MS),
+  });
+}
+
 /**
  * Authenticated request against the control server's API.
- * `brainDir` is required so the caller's brain scope selects the credential.
+ * Credentials always come from the auth owner's host-store selector.
  */
 export async function headscaleFetch(path, options = {}, brainDir) {
-  const { url, token } = await resolveHeadscaleConfig(brainDir);
-  assertSecureControlUrl(url);
-
-  const cleanPath = path.startsWith('/') ? path : `/${path}`;
-  const targetUrl = `${normalizeControlUrl(url)}${cleanPath}`;
-
-  const res = await throttledFetch(
-    targetUrl,
-    {
-      ...options,
-      headers: {
-        ...options.headers,
-        Authorization: `Bearer ${token}`,
-        Accept: 'application/json',
-        'Content-Type': 'application/json',
-      },
-    },
-    options.timeoutMs || DEFAULT_TIMEOUT_MS,
-  );
-
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => '');
-    const error = new Error(`Headscale API error (${res.status} ${res.statusText})`);
-    error.status = res.status;
-    error.detail = errorText.slice(0, 500);
-    throw error;
-  }
-
-  const contentType = res.headers.get('content-type') || '';
-  if (contentType.includes('application/json')) {
-    return res.json();
-  }
-  throw new Error('Control server returned a non-JSON response');
+  return (await hostApi(brainDir)).request(path, options);
 }
 
-/**
- * Resolve a control-server user to both of its identifying forms.
- *
- * User-facing names resolve to the current API numeric ID.
- */
+/** Resolve a control-server user to both of its identifying forms. */
 export async function resolveHeadscaleUser(brainDir, requested) {
-  const data = await headscaleFetch('/api/v1/user', {}, brainDir);
-  const users = data?.users || [];
-
-  if (requested) {
-    const match = users.find(
-      (u) =>
-        String(u.id) === String(requested) ||
-        u.name === requested ||
-        (u.email && u.email === requested),
-    );
-    if (match) return { id: String(match.id), name: match.name };
-    // Unknown to us — pass it through and let the control server decide.
-    return { id: String(requested), name: String(requested) };
-  }
-
-  if (!users.length) return null;
-  return { id: String(users[0].id), name: users[0].name };
+  return (await hostApi(brainDir)).resolveUser(requested);
 }
 
-/** Mint using the current numeric-user API without older-version retries. */
+/** Mint a pre-auth key for a registered numeric control-server user. */
 export async function createHeadscalePreAuthKey(options = {}, brainDir) {
-  const ttlMinutes = Number.isFinite(options.ttlMinutes) ? options.ttlMinutes : 10;
-  const expiration = options.expiration || new Date(Date.now() + ttlMinutes * 60_000).toISOString();
-  const ref = options.userRef || await resolveHeadscaleUser(brainDir, options.user);
-  if (!ref?.id || !/^[0-9]+$/.test(String(ref.id))) throw new Error('Select a registered numeric control-server user');
-  const user = String(ref.id);
-  const data = await headscaleFetch('/api/v1/preauthkey', {
-    method: 'POST', body: JSON.stringify({ user, reusable: options.reusable === true,
-      ephemeral: options.ephemeral === true, expiration, aclTags: options.aclTags || [] }),
-  }, brainDir);
-  const key = data?.preAuthKey?.key;
-  if (typeof key !== 'string' || !key) throw new Error('Headscale did not return a pre-auth key');
-  return { key, expiration, user, raw: data };
+  return (await hostApi(brainDir)).createPreAuthKey(options);
 }
 
-/**
- * Read the control server's ACL policy.
- *
- * Requires the server to run with `policy.mode: database` — in `file` mode the
- * policy lives on the control server's disk and the API cannot manage it.
- *
- * Headscale returns a 500 (not a 404) when database mode is on but the policy
- * table is still empty, so an unset policy is normalised to `policy: null`
- * rather than thrown. That distinction matters: "no policy yet" is the expected
- * first-run state, whereas a real transport or auth failure must still surface.
- */
+/** Read the control server's ACL policy; an empty policy table reads as `policy: null`. */
 export async function getHeadscalePolicy(brainDir) {
-  try {
-    const data = await headscaleFetch('/api/v1/policy', {}, brainDir);
-    return {
-      policy: data?.policy ?? null,
-      updatedAt: data?.updatedAt ?? null,
-      configured: Boolean(data?.policy),
-      raw: data,
-    };
-  } catch (err) {
-    const detail = String(err.detail || '');
-    const emptyPolicyTable =
-      err.status === 404 ||
-      (err.status === 500 && /policy|not found|no such/i.test(detail));
-    if (emptyPolicyTable) {
-      return { policy: null, updatedAt: null, configured: false, unset: true, raw: null };
-    }
-    if (err.status === 400 && /database/i.test(detail)) {
-      const modeError = new Error(
-        'Headscale is running in file policy mode; set `policy.mode: database` to manage the policy over the API',
-      );
-      modeError.status = err.status;
-      modeError.detail = err.detail;
-      modeError.code = 'POLICY_MODE_FILE';
-      throw modeError;
-    }
-    throw err;
-  }
+  return (await hostApi(brainDir)).getPolicy();
 }
 
-/**
- * Replace the control server's ACL policy.
- *
- * `policy` may be an object (serialised here) or an already-formatted
- * HuJSON/JSON string. Headscale validates server-side and rejects the write if
- * the policy's own `tests` block fails, so a bad policy never lands.
- */
+/** Replace the control server's ACL policy; Headscale validates it server-side. */
 export async function setHeadscalePolicy(policy, brainDir) {
   if (!policy) throw new Error('A policy is required');
-  const serialised = typeof policy === 'string' ? policy : JSON.stringify(policy, null, 2);
-
-  const data = await headscaleFetch(
-    '/api/v1/policy',
-    { method: 'PUT', body: JSON.stringify({ policy: serialised }) },
-    brainDir,
-  );
-  return { policy: data?.policy ?? serialised, updatedAt: data?.updatedAt ?? null, raw: data };
-}
-
-/**
- * Build a policy that lets every mesh member reach every other member, and use
- * Tailscale SSH between them as any non-root user.
- *
- * This is deliberately the simple single-operator shape: one person's own
- * machines, all equally trusted. It is NOT appropriate for a multi-tenant
- * tailnet — headscale membership is the trust boundary, so anything admitted to
- * the mesh inherits this access. Narrow `src`/`dst` before adding a node you do
- * not control.
- *
- * root is excluded via `autogroup:nonroot`: SSH-ing straight to root over the
- * mesh removes the audit trail that makes per-user access worth having.
- */
-export function buildMeshSshPolicy({ allowRoot = false } = {}) {
-  return {
-    acls: [{ action: 'accept', src: ['*'], dst: ['*:*'] }],
-    ssh: [
-      {
-        action: 'accept',
-        // autogroup:member, not autogroup:self. 'self' limits a member to SSH on their own
-        // devices, so no node on the mesh could reach any other one and every cross-machine
-        // operation fell back to key auth that had never been set up — which reads as the peer
-        // being unreachable. The point of this policy is that members reach each other.
-        src: ['autogroup:member'],
-        dst: ['autogroup:member'],
-        users: allowRoot ? ['autogroup:nonroot', 'root'] : ['autogroup:nonroot'],
-      },
-    ],
-  };
+  return (await hostApi(brainDir)).setPolicy(policy);
 }

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/mesh-auth.mjs

@@ -2,8 +2,8 @@ import { importHostModule } from '../host-runtime.mjs';
 const { loadPluginModule: __loadOwnedPlugin } = await importHostModule('src/core/plugin-runtime.mjs');
 import crypto from 'node:crypto';
 import net from 'node:net';
-import { brainDir } from './config.mjs';
 const { getSecret } = await __loadOwnedPlugin('auth', 'secrets-store');
+const { hostSecretsBrainDir } = await __loadOwnedPlugin('auth', 'host-secrets-store');
 
 export function normalizeRemoteAddress(value) {
   const address = String(value || '').trim();
@@ -20,7 +20,7 @@ export function isMeshOrLoopbackAddress(value) {
 }
 
 export async function getMeshSyncToken() {
-  const result = await getSecret(brainDir, 'TR_MESH_SYNC_TOKEN', {
+  const result = await getSecret(hostSecretsBrainDir(), 'TR_MESH_SYNC_TOKEN', {
     action: 'use',
     actor: 'mesh-sync-auth',
   });

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/presence.mjs

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { getLocalPresence, resolveActiveDevice } from './mesh-activity.mjs';
-import { getMeshPeers, execMeshCommand } from './mesh.mjs';
+import { getMeshPeers, listEnrichedMeshNodes, meshVaultRoot, execMeshCommand } from './mesh.mjs';
 import { getMeshSyncAuthorization } from './mesh-auth.mjs';
 
 function validRecord(record, peer) {
@@ -11,12 +11,12 @@ export async function getMeshPresence({ fetchImpl = fetch, includePeers = true }
   const local = getLocalPresence();
   const peers = [];
   if (includePeers) {
-    const candidates = getMeshPeers({ includeSelf: false }).filter(peer => peer.online && peer.ip);
-    const authorization = candidates.length ? await getMeshSyncAuthorization() : null;
+    const candidates = listEnrichedMeshNodes(meshVaultRoot()).filter(peer => !peer.self && !peer.vault_only && peer.online && peer.ip);
+    const authorization = candidates.some(peer => Number.isInteger(Number(peer.brain_port)) && Number(peer.brain_port) > 0 && Number(peer.brain_port) <= 65535) ? await getMeshSyncAuthorization() : null;
     await Promise.all(candidates.map(async peer => {
       try {
-        const port = Number(peer.brain_port || process.env.TR_SERVER_PORT || 3000);
-        if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid peer service port');
+        const port = Number(peer.brain_port);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('No valid presence service port is recorded for this peer');
         const response = await fetchImpl(`http://${peer.ip}:${port}/api/mesh/presence/local`, { headers: { Authorization: authorization }, redirect: 'error', signal: AbortSignal.timeout(10000) });
         if (!response.ok) throw new Error(`Peer HTTP ${response.status}`);
         const record = await response.json();

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/screen-view.mjs

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+
+// Fixed read operations only. No command or argument comes from the caller.
+const SOURCES = {
+  machines: { status: ['mesh', 'status'], presence: ['mesh', 'presence'] },
+  flows: {
+    grants: ['mesh', 'grants', 'list'], plugins: ['plugin', 'peers'], updates: ['update', '--status'],
+    tasks: ['user-automations', 'list'], agents: ['agent', 'list'], alerts: ['alerts', 'log'], deployments: ['deploy', 'status'],
+  },
+  placement: { tasks: ['user-automations', 'list'], agents: ['agent', 'list'] },
+  boundary: { policy: ['mesh', 'policy', 'get'], grants: ['mesh', 'grants', 'list'] },
+  join: { status: ['mesh', 'status'] },
+};
+
+export function meshDeclarations() {
+  const manifest = JSON.parse(fs.readFileSync(new URL('../../plugin.json', import.meta.url), 'utf8'));
+  return { ...manifest.mesh, provides: manifest.mesh.provides.map(capability => ({ ...capability, effect: manifest.cli.subcommands.find(operation => operation.name === capability.operation)?.effect })) };
+}
+
+export function parseCliObject(text) {
+  const value = String(text).trim();
+  try { const parsed = JSON.parse(value); if (parsed && typeof parsed === 'object') return parsed; } catch {}
+  const lines = value.split('\n').filter(line => /^\s*[{[]/.test(line));
+  if (lines.length > 1) {
+    try { const rows = lines.map(line => JSON.parse(line)); if (rows.every(row => row && typeof row === 'object')) return rows; } catch {}
+  }
+  // Ignore prose banners; retain arrays and multiline JSON as one payload.
+  for (let start = 0; start < value.length; start++) {
+    if (!'{['.includes(value[start])) continue;
+    let depth = 0, quoted = false;
+    for (let end = start; end < value.length; end++) {
+      const ch = value[end];
+      if (quoted) { if (ch === '\\') end++; else if (ch === '"') quoted = false; }
+      else if (ch === '"') quoted = true;
+      else if ('{['.includes(ch)) depth++;
+      else if ('}]'.includes(ch) && --depth === 0) {
+        try { return JSON.parse(value.slice(start, end + 1)); } catch { break; }
+      }
+    }
+  }
+  throw new Error('Owner command did not return JSON');
+}
+
+async function readSource(args) {
+  const root = process.env.TR_PACKAGE_ROOT;
+  if (!root || !path.isAbsolute(root)) throw new Error('Explicit valid Total Recall host runtime required');
+  const cli = path.join(root, 'bin', 'total-recall.mjs');
+  if (!fs.statSync(cli).isFile()) throw new Error('Selected host CLI is unavailable');
+  let result;
+  try {
+    result = await execute(process.execPath, [cli, ...args, '--json'], {
+      cwd: process.cwd(), timeout: 20000, maxBuffer: 262144, encoding: 'utf8',
+      env: { ...process.env, TR_EMBEDDINGS_DISABLED: '1' },
+    });
+  } catch (error) {
+    // Do not forward arbitrary owner output or command diagnostics into a read view.
+    throw new Error(error.killed ? 'Owner read timed out' : `Owner read failed (exit ${error.code ?? 'unknown'})`);
+  }
+  return parseCliObject(result.stdout);
+}
+
+export async function readMeshView(screen = 'machines', dependencies = {}) {
+  if (!Object.hasOwn(SOURCES, screen)) throw new Error(`Unknown mesh screen: ${screen}`);
+  const read = dependencies.readSource || readSource;
+  const entries = await Promise.all(Object.entries(SOURCES[screen]).map(async ([name, args]) => {
+    const checked_at = new Date().toISOString();
+    try {
+      const data = await read([...args]);
+      if (!data || typeof data !== 'object' || data.ok === false || data.success === false) throw new Error('Owner reported a failed observation');
+      return [name, { ok: true, command: args.join(' '), checked_at, data }];
+    } catch (error) { return [name, { ok: false, command: args.join(' '), checked_at, error: error.message }]; }
+  }));
+  return { screen, observed_at: new Date().toISOString(), declarations: meshDeclarations(), sources: Object.fromEntries(entries) };
+}

package/scaffold/.agent/skills/total-recall/plugins/mesh/ui/DESIGN.md

@@ -1,18 +1,217 @@
-# DESIGN.md — Ghost Net
+# DESIGN.md — Headscale Mesh
 
 ```yaml
 tokens:
-  brand-name: "Ghost Net"
-  wordmark: "[GHOST//NET]"
-  color-primary: "#22c55e"
-  color-background: "#090d16"
-  color-accent: "#38bdf8"
-  badge: "Control Mesh"
-  font-mono: "'JetBrains Mono', 'Fira Code', monospace"
+  brand-name: "Headscale"
+  wordmark: "HEADSCALE"
+  color-primary: "#818cf8"
+  color-background: "#0b1020"
+  color-accent: "#3b82f6"
+  color-ok: "#34d399"
+  color-warn: "#fbbf24"
+  color-danger: "#f87171"
+  badge: "Your machines"
+  font-body: "'Space Grotesk', system-ui, sans-serif"
+  font-mono: "'JetBrains Mono', ui-monospace, monospace"
   border-radius: "8px"
+  density: "compact"
+  motion: "none"
 ```
 
-## Brand & Typographic Wordmark
-- **Name**: Ghost Net
-- **Wordmark Logo**: `[GHOST//NET]` (custom typographic badge, no generic icons)
-- **Palette**: Primary `#22c55e`, Surface `#090d16`, Accent `#38bdf8`.
+This document is the design. The component follows it. Where the component and this file disagree, the component is wrong.
+
+## What a mesh is, for this operator
+
+A mesh here is the operator's own machines (a Mac mini, a laptop, a cloud server, a phone) joined by one control server so that people and agents can reach any of them from any other. The operator is one person, working from whichever machine is in front of them, and agents work across the rest.
+
+A mesh is also a platform. Very little of what matters about it is configuration; most of it is what the mesh lets everything else do: run commands anywhere, tell where the person is, release a secret to a machine that has a grant, share plugins without a catalog, update a fleet, place scheduled work and agents. `docs/MESH_PLATFORM.md` maps those layers, says what is built and what is not, and is the source for this card's scope. This card is the top layer: the operator's view of the platform. It is not a network settings page.
+
+That framing decides everything below. Four facts about this mesh came from reading its real output, not from the manifest, and each one changed the design:
+
+1. **Reachability is a ladder, not a state.** A machine is reachable only if the control server sees it, the network path answers, a login is recorded, and a command actually runs. These are four separate checks that fail for four separate reasons with four separate fixes. A single "Healthy / Offline" label throws away the only thing the operator needs: which rung broke.
+2. **The operator is a participant.** `presence` reports which machine the person is active on and for how long it has been idle. An operator working from the laptop to drive the Mac mini needs the card to know the laptop is where they are.
+3. **Recorded is not live.** A node's entity file carries `last_heartbeat` and hardware figures written once by something that later stopped writing. The laptop's heartbeat is thirteen days old while it is online, pingable, answering commands and in use. A recorded date must never be read as liveness. Every screen separates what was measured now from what was recorded earlier, and states the date of the recording.
+4. **Membership is the trust boundary.** The policy in force lets every member reach every port of every member and SSH as root. The CLI's own help says to audit nodes before widening that. A phone and a Chromebook are inside the same boundary as the cloud server. The card has to make that visible, because it is the one fact about the mesh with security weight.
+
+## Who uses it and what they are in the middle of
+
+One operator, mid-task, who suspects a machine cannot be reached, wants to know whether the things that depend on the mesh are working, or wants to know where something can run. Six jobs, in the order of how often they come up:
+
+| # | Job | How often | What answers it |
+| --- | --- | --- | --- |
+| 1 | "I can't reach X" or "is everything up?" | Constant | Machines |
+| 2 | "Is what rides on the mesh actually working?" (secrets, updates, plugins, scheduled work) | Often | Flows |
+| 3 | "Where can this run?" (needs Docker, Claude, a camera, a display) | Often | Placement |
+| 4 | "What is inside, what is exposed, and what may they do?" | Occasionally, and after any change | Boundary |
+| 5 | "Add a machine." | Rarely | Join |
+| 6 | "Send something to a machine or a person; see what was said." | Will be constant | Messages and Files, **when those capabilities exist** |
+
+Job 6 has no screen yet and gets none until its operations exist. A screen that shows a feature with nothing behind it is a seeded value in another costume.
+
+The control server, the leader and this machine's enrollment are not a job. They are a precondition for all four: if the control server cannot be verified, every other figure on the card is unreliable. So they are a strip that stays on screen, not a screen.
+
+## The persistent strip
+
+One row above the screens, always present:
+
+- **Control server**: the host name and whether the API key was verified. If it is not verified, the strip turns to a danger state and the verdict line says the rest of the card cannot be trusted.
+- **Leader**: which machine leads and by what strategy. It states whether this machine leads.
+- **This machine**: its name, its enrollment state and the backend state.
+
+Then the **verdict**, one sentence computed only from returned values. Its subject is the machines the operator can log in to, because that is what "reachable" can mean. A phone cannot host a login, so it is counted apart and never makes the sentence worse.
+
+## Screen 1 — Machines
+
+Master and detail. The roster is on the left; the selected machine is on the right. On a narrow width they stack. **A machine does not get its own screen.** One machine is a selection inside this screen, which keeps the comparison across machines visible, and that comparison is the point of the job.
+
+### The ladder
+
+Four rungs, always in this order, each in one of four states: passed, failed, not yet checked, not applicable.
+
+| Rung | Question | Source | Measured |
+| --- | --- | --- | --- |
+| Control | Does the control server see it online? | `status` | now |
+| Path | Does the network path answer? | `ping`, and direct or relayed once an operation exposes it | now, from this machine |
+| Login | Is an SSH login recorded for it? | `status` access | recorded, with its verification date |
+| Run | Did a command execute on it? | `doctor` | now, from this machine |
+
+The headline for a machine is the first rung that failed, named in words. `Stops at Login: no SSH login recorded` and `Stops at Run: connection timed out` are different problems and read differently at a glance.
+
+**Severity is decided by contradiction, not by a fixed list of expectations.** The card cannot know which machines are meant to be always on, and it does not guess. So:
+
+- Control says online, but Path or Run fails: **danger**. The mesh claims the machine is there and it does not answer. This is a real fault.
+- Control says offline: **neutral, stated plainly as offline.** Laptops sleep and phones leave. That is a fact, not an alarm.
+- Online and answering, but no login is recorded: **warning**, with the fix on the next line.
+- A rung not yet checked stays not-yet-checked, never passed.
+
+**Not applicable is real.** A phone cannot host an SSH login. Its Login and Run rungs are not applicable, derived from the operating system the node reports, and it is not reported as missing a login.
+
+### Progressive reading
+
+`status` is fast and paints the roster at once. `ping`, `doctor` and `presence` take seconds because they run over SSH or wait on peers. They fill in as they arrive. Until then their rungs read as not yet checked with the word "checking", and a failed source shows its own error without blanking the rest. A failed read clears its figures; it never leaves the previous value standing as if current.
+
+### Presence
+
+The row for the machine the operator is active on says so, with idle time. This card is usually opened from a different machine than the one being fixed, and this is how it shows which is which. A peer whose presence endpoint did not answer says "presence unavailable" with the reason, which is a different fact from "idle".
+
+### Roster order
+
+Danger first, then warning, then not-yet-checked, then reachable, then machines that cannot host a login, with recorded-only records collapsed at the bottom. Within a group, the machine the operator is on comes first.
+
+### The detail pane
+
+Per machine, in this order:
+
+1. The ladder, one line per rung: the state in words, the evidence, and how old the evidence is.
+2. **Fix.** The action that addresses the failing rung, placed directly under it:
+   - Path failed or not checked: **Ping now** (read).
+   - Login failed: **Find a login** (`access discover`, write) and **Record a login** (`access <node> --user …`, write) with user, host, port and key path fields. A key path is a path, never a key.
+   - Run failed or not checked: **Verify execution** (`access verify`, which runs a probe command on each configured machine).
+   - Reachable: **Copy SSH command**. SSH is interactive and cannot run inside a sandboxed frame, so the card hands the operator the exact command.
+3. Recorded facts, each dated: login source and user, verification date, hardware figures and their measurement date. A heading says these were recorded earlier.
+4. Addresses: the mesh address and the LAN address. The overlay and wireless-direct interfaces that the system reports (`utun*`, `awdl0`, `llw0`) are noise for this operator and are not shown.
+
+## Screen 2 — Flows
+
+Job 2 is the one the first version missed entirely. The mesh's value is what it carries, so the card shows each thing that moves and whether it is moving. One row per flow, each answering the same three questions: what moves, when did it last demonstrably work, and which machines is it failing on.
+
+| Flow | What the row shows | Read from |
+| --- | --- | --- |
+| Secrets | machines holding grants, and the keys each may read; an empty list stated as "no machine may read a secret through the mesh" | `grants list` |
+| Plugins | what each peer shares, with each peer's own status: reachable, offline, not configured, unsupported, error | `plugin peers` |
+| Updates | the version and the verified report of the last fleet update; failures counted, with the first reasons | `update --status` |
+| Scheduled work | which tasks exist, on which node they run, and whether placement is per node or a selected node | `user-automations list` |
+| Agents | running and recent agent processes, and the node each runs on | `agent list` |
+| Alerts | recent mesh events from the alert ledger | `alerts log` |
+| Deployments | the active slot and release of each registered deploy host; an empty list stated as "no host is registered with deploy", which is the case today | `deploy status` |
+
+Three more flows belong here and are **not drawn until an operation exists**: service health per node, exit nodes and routes, and speed. The "Operations the card depends on" table in `docs/MESH_PLATFORM.md` lists them. Deployments are read from the deploy plugin and never duplicated: the mesh owns machines, deploy owns releases.
+
+The row's headline is computed from the returned data. The fleet-update row would today read as a failure with its reason, because the last run failed on most consumers. A flow whose read operation fails says so, with the error and the time, and never reads as healthy.
+
+A flow with no read operation is not drawn. File push has none (no transfer log), and appears in the "not built" note below until it does.
+
+## Screen 3 — Placement
+
+The question is "where can this run?", and the native shape of that answer is a matrix: machines down the side, capabilities across the top.
+
+- **Runtimes** and **agent harnesses**: measured now by `doctor`. Columns are the union of what any machine returned, so the card carries no hard-coded list of tools.
+- **Hardware** (screen, microphone, camera, speaker, headless): recorded, shown with the measurement date, because it comes from the entity file and not from a live probe.
+
+A cell is **present**, **known absent**, or **unknown**. Absent is claimed only for a machine that answered `doctor`; for a machine that did not, every probed cell is unknown and the row says which rung stopped it. Without that distinction the matrix would say "no Docker" about a machine it never reached.
+
+Below the matrix, **where work runs**: scheduled tasks and agent processes grouped by node, so "where can this run" and "where does it run" sit together.
+
+**Choosing columns filters rows.** Selecting Docker and Claude shows only the machines that have both. That is the actual task, so it is the interaction.
+
+## Screen 4 — Boundary
+
+Two halves of one boundary, side by side on a wide card.
+
+- **Inside**: who is a member, what the policy lets members do, what each may read, and any exit node or subnet route.
+- **Outside**: what is reachable from the internet. For each public hostname, the origin machine, the path (a public address, the proxy or a tunnel), the protection and the last probe. The most important line on the whole card is any service meant to be mesh-only that is bound to a public address.
+
+The outside half draws only what can be read today: DNS records from the domains plugin matched to the public addresses of machines, deploy health, and the firewall findings of the security audit. It says plainly that tunnels, their hostnames and the machines behind them are **not readable**, because no operation reads them (see `docs/MESH_PLATFORM.md`, "The edge"). It does not say there are none.
+
+Exit nodes and subnet routes belong on the inside half, because each one widens the boundary: an exit node sees all the traffic of every client that uses it. The section appears when the operations in `docs/MESH_PLATFORM.md` (P5) exist. Until then the card does not claim there are none, because it cannot read them; it says exit nodes are not readable.
+
+The boundary: who is inside, what the policy lets them do, and what they may read.
+
+**Inside half.**
+
+- **Members.** Count of machines on the control server, including those that cannot host a login. A recorded-only record is not a member.
+- **Policy in plain words.** The ACL and SSH rules are translated into sentences from the returned policy, and any selector the card does not recognise is shown exactly as written, never guessed at. The policy in force today renders as: any member may reach any port on any member; any member may SSH to any member as a non-root user or as root. Root SSH is marked, because the CLI itself calls it discouraged. Policy editing stays on the command line, behind a dry run, and the card shows the command.
+- **Secret grants.** Which machines may read which secret keys through the mesh. The returned list is empty, and the owner's contract is that a missing policy grants nothing, so the empty state says exactly that: no machine except the one holding the store may read any secret through the mesh. Adding and removing a grant are write actions; removing requires a confirmation that names the machine and the keys. Grants are key names, never values.
+- **Records that look wrong**, computed from returned data only. Two records that share an ethernet hardware address are probably one machine: the mesh holds a live record and a recorded-only record for the Mac mini with the same address. No mesh command retires a record, and the card says so rather than offering a button that does not exist.
+
+## Screen 5 — Join
+
+Admitting a machine widens the boundary, so this screen restates the consequence before it offers the recipe.
+
+- This machine's enrollment: state, backend state, addresses, whether auto-enroll is on or why it is blocked.
+- A two-step recipe: mint an enrollment key on an enrolled machine, then run `tailscale up` with the control server's login address on the new one. The options are explicit: a **reusable** key can admit more than one machine, and an **ephemeral** node disappears when it goes offline. Each toggle states what it does to the boundary.
+- **The card never renders the key.** An enrollment key is a credential. The recipe is shown as commands to run, with the key left to the shell that mints it.
+- **Re-enroll** this machine is a destructive action: it names the target and requires confirmation.
+- When no control server is configured at all, this screen is the whole card: a first-run state that shows the one command that provisions a server, because a new developer project starts here with its own control server and never points at anyone else's.
+
+## What the card does not do, and why
+
+| Operation | Decision |
+| --- | --- |
+| `ssh` | Interactive. Hand-off: the exact command, copyable. |
+| `exec`, `dispatch`, `file put` | **Not on the card for now.** Running a command or sending a file to a machine from a dashboard click, including as root on the cloud server, is a decision that belongs to the operator (open decision 5 in `docs/MESH_PLATFORM.md`). Agents use these through the CLI. |
+| Messages, boards, file spaces | Do not exist. See `docs/MESH_PLATFORM.md`, proposals P2 and P3. |
+| `policy set`, `policy init-ssh` | Hand-off with the dry-run command. A policy edit can lock every machine out of every other. |
+| `server init`, `server update`, `server console` | Hand-off. Long, staged and host-specific. Shown on the first-run state. |
+| `enroll` | Status is read. Re-enroll is on Join, with confirmation. |
+| `preauthkey` | Hand-off. The key is a credential. |
+| `token` | Not on the card. Credentials are entered through the drawer panel, never here. |
+
+Every operation not on the card is listed here on purpose, so that an omission can be told apart from an oversight.
+
+## Failure states, all first-class
+
+Control server unverified; mesh disconnected; a source unreadable (named, with its error and time); a peer's presence unavailable; a machine not on the control server; a login recorded but never verified; a rung not yet checked. None of these renders as a zero, a blank or a reassuring word.
+
+## Identity of a machine
+
+A machine is keyed by its mesh address everywhere on the card. The client reports names that differ from the node records (for example a cloud server reported as `web-01`, a phone as `localhost`), so a name is a label and never a key.
+
+## Layout and accessibility
+
+- Wide first. Machines is two panes at container width 720 px and above, stacked below it.
+- Every control is at least 44 px high, reachable by keyboard, with a visible focus ring.
+- Severity is never colour alone. Each rung state has its own shape (solid, hatched, dashed, dotted) and its own word.
+- No timers. Reading is on open and on Refresh. Nothing animates; the one rule for reduced motion is therefore satisfied by having no motion.
+- Colours come from the host's tokens with a fallback only for the state hues.
+- No emoji, no decorative icons. The mark is a three-node graph drawn in SVG.
+
+## What was wrong with the first version
+
+It joined `status` and `doctor` into one severity label, so the ladder was lost. It treated a phone's missing login as a defect. It printed raw payload states as three adjacent words. It had no notion of where the operator is, no capability view, no trust view and no way to fix what it reported. It never rendered against real data. It was a list of commands with a verdict on top.
+
+## Implemented host contract — 2026-10-25
+
+The five views now follow this design. The card reads the host's frozen permitted-operation list. The dashboard currently mounts the face read-only, so login administration and re-enrollment appear as explicit CLI handoffs there; a writable host can expose the forms and target-specific confirmation. This preserves host enforcement instead of drawing mutation buttons that cannot execute.
+
+The Placement view also renders the plugin-owned manifest integration matrix. It labels declarations separately from timestamped observations and explains what each read proves. Unknown activity, stale presence, untested capabilities, failed reads and missing configuration are distinct. Native guard contention is handled by the generic SSSS owner without dropping auth audit records. Unsupported primitive authorization, exposure/tunnel inventories and route management are not represented as implemented capabilities.