total-recall-brain 3.41.0 → 3.41.2

package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-merge.mjs

@@ -0,0 +1,131 @@
+/**
+ * Merge a stray secrets store into the host's single store.
+ *
+ * Per-repo stores grew when the CLI resolved its store from the cwd. This
+ * folds one of them back in without losing or silently replacing anything:
+ * a key the target lacks is imported with its metadata; a key with the same
+ * value only gains the source's repo binding and tags; a key whose value
+ * differs is a conflict and is never overwritten unless the operator names it,
+ * either taking the source value (`take`) or importing it under a new,
+ * app-specific name (`rename`). Values are never returned or logged.
+ */
+import crypto from 'node:crypto';
+import { loadSecrets, saveSecrets, ensureMeta, appendAudit, META_KEY } from './secrets-gateway.mjs';
+import { mergeSecretMeta, normalizeReposBinding, normalizeTags } from './secrets-store.mjs';
+
+const KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
+
+/** Values can be strings or JSON (account lists); compare by content, not reference. */
+const sameValue = (a, b) => (typeof a === 'string' || typeof b === 'string' ? a === b : JSON.stringify(a) === JSON.stringify(b));
+
+function fingerprint(value) {
+  return crypto.createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex').slice(0, 12);
+}
+
+/** The metadata worth showing an operator to decide a conflict. */
+function summary(meta = {}, value) {
+  return {
+    fingerprint: value ? fingerprint(value) : null,
+    provider: meta.provider || null,
+    repos: Array.isArray(meta.repos) ? meta.repos : [],
+    tags: Array.isArray(meta.tags) ? meta.tags : [],
+    created_at: meta.created_at || null,
+    updated_at: meta.updated_at || null,
+    rotated_at: meta.rotated_at || null,
+    tracking_status: meta.tracking_status || null,
+    tracking_synced_at: meta.tracking_synced_at || null,
+    key_valid: meta.key_valid ?? null,
+  };
+}
+
+/**
+ * @param {string} targetDir  brain dir of the single store
+ * @param {string} sourceDir  brain dir of the stray store
+ * @param {{ apply?: boolean, bindSame?: boolean, datesFromSource?: boolean, repo?: string, tags?: string[]|string, rename?: Record<string,string>,
+ *   take?: string[], actor?: string }} [opts]
+ * @returns {Promise<{ applied: boolean, imported: object[], same: object[], conflicts: object[], renamed: object[], taken: object[] }>}
+ */
+export async function mergeStore(targetDir, sourceDir, opts = {}) {
+  if (!targetDir || !sourceDir) throw new Error('merge-store needs a target and a source store');
+  if (targetDir === sourceDir) throw new Error('The source store is the target store');
+  const rename = opts.rename || {};
+  const take = new Set(opts.take || []);
+  for (const [from, to] of Object.entries(rename)) {
+    if (!KEY_PATTERN.test(from) || !KEY_PATTERN.test(to)) throw new Error(`Invalid rename ${from}=${to}`);
+    if (take.has(from)) throw new Error(`${from} cannot be both renamed and taken`);
+  }
+  const bindRepo = opts.repo ? normalizeReposBinding(opts.repo) : [];
+  const extraTags = opts.tags ? normalizeTags(opts.tags) : [];
+
+  const source = ensureMeta(await loadSecrets(sourceDir));
+  const target = ensureMeta(await loadSecrets(targetDir));
+  const sourceKeys = Object.keys(source).filter((k) => k !== META_KEY);
+  for (const k of [...Object.keys(rename), ...take]) {
+    if (!sourceKeys.includes(k)) throw new Error(`${k} is not in the source store`);
+  }
+
+  const report = { applied: false, imported: [], same: [], conflicts: [], renamed: [], taken: [] };
+  const now = new Date().toISOString();
+  const withBinding = (meta) => ({
+    repos: [...new Set([...(meta.repos || []), ...bindRepo])],
+    tags: [...new Set([...(meta.tags || []), ...extraTags])],
+  });
+
+  for (const key of sourceKeys) {
+    const value = source[key];
+    if (value === undefined || value === null || value === '') continue;
+    const sMeta = source[META_KEY].keys[key] || {};
+    const name = rename[key] || key;
+    const exists = name in target && target[name] !== '' && target[name] != null;
+    const tMeta = target[META_KEY].keys[name] || {};
+
+    if (rename[key]) {
+      if (exists && !sameValue(target[name], value)) throw new Error(`Rename target ${name} already holds a different value`);
+      target[name] = value;
+      target[META_KEY].keys[name] = mergeSecretMeta({ ...sMeta, ...tMeta }, { ...withBinding(sMeta), scope: 'global', created_at: sMeta.created_at || now, updated_at: now, notes: sMeta.notes || `merged from ${key}`, provides: key });
+      report.renamed.push({ from: key, to: name, ...summary(sMeta, value) });
+      continue;
+    }
+    if (!exists) {
+      target[name] = value;
+      target[META_KEY].keys[name] = mergeSecretMeta(sMeta, { ...withBinding(sMeta), scope: 'global', created_at: sMeta.created_at || now, updated_at: sMeta.updated_at || now });
+      report.imported.push({ key: name, ...summary(sMeta, value) });
+      continue;
+    }
+    if (sameValue(target[name], value)) {
+      // A store that was a copy of the global one says nothing about which keys
+      // the repo uses, so equal keys gain its binding only when asked.
+      if (opts.bindSame) target[META_KEY].keys[name] = mergeSecretMeta(tMeta, {
+        repos: [...new Set([...(tMeta.repos || []), ...(sMeta.repos || []), ...bindRepo])],
+        tags: [...new Set([...(tMeta.tags || []), ...(sMeta.tags || []), ...extraTags])],
+      });
+      // The value dates belong to the value: when it is identical, an older
+      // source date is the true one (repairs a date a label edit bumped).
+      if (opts.datesFromSource) {
+        const cur = target[META_KEY].keys[name] || {};
+        const fix = {};
+        for (const f of ['updated_at', 'rotated_at']) if (sMeta[f] && (!cur[f] || sMeta[f] < cur[f])) fix[f] = sMeta[f];
+        if (Object.keys(fix).length) { target[META_KEY].keys[name] = { ...cur, ...fix }; report.redated = (report.redated || 0) + 1; }
+      }
+      report.same.push({ key: name });
+      continue;
+    }
+    if (take.has(key)) {
+      const replaced = summary(tMeta, target[name]);
+      target[name] = value;
+      target[META_KEY].keys[name] = mergeSecretMeta(tMeta, { ...withBinding(tMeta), updated_at: now, notes: tMeta.notes || 'value taken from a merged store' });
+      report.taken.push({ key: name, replaced, with: summary(sMeta, value) });
+      continue;
+    }
+    report.conflicts.push({ key: name, target: summary(tMeta, target[name]), source: summary(sMeta, value) });
+  }
+
+  if (opts.apply) {
+    await saveSecrets(targetDir, target);
+    for (const row of [...report.imported, ...report.renamed, ...report.taken]) {
+      appendAudit(targetDir, { action: 'merge', key: row.key || row.to, from_key: row.from || null, actor: opts.actor || 'cli' });
+    }
+    report.applied = true;
+  }
+  return report;
+}

package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-remote-deploy.mjs

@@ -18,7 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { buildEnvProjection, mergeEnvManagedBlock, projectSlugFromPath } from './secrets-env-export.mjs';
-import { resolveSecretsPath } from './secrets-store.mjs';
+import { resolveSecretsPath, loadSecrets, setSecret, secretValueFingerprint } from './secrets-store.mjs';
 import { authState } from './metadata-state.mjs';
 
 /**
@@ -114,6 +114,7 @@ function runSsh(target, remoteCommand, { input } = {}) {
     input: input != null ? input : undefined,
     encoding: 'utf8',
     timeout: 20000,
+    maxBuffer: 16 * 1024 * 1024,
   });
   return result;
 }
@@ -128,6 +129,7 @@ function quoteRemotePath(p) {
  */
 function fetchRemoteFile(target, remoteFile) {
   const r = runSsh(target, `cat ${quoteRemotePath(remoteFile)} 2>/dev/null || true`);
+  if (r.error || r.status !== 0) throw new Error(`SSH read failed for target "${target.name}": ${r.error?.message || (r.stderr || '').slice(0, 300)}`);
   if (r.error) throw new Error(`SSH connect failed for target "${target.name}": ${r.error.message}`);
   return r.stdout || '';
 }
@@ -209,7 +211,7 @@ export async function deployEnvToRemote(brainDir, targetName, opts = {}) {
   }
 
   const existing = fetchRemoteFile(target, remoteFile);
-  const merged = mergeEnvManagedBlock(existing, projection.body);
+  const merged = mergeEnvManagedBlock(existing, projection.body, { partial: Boolean(opts.keys?.length) });
   writeRemoteFile(target, remoteFile, merged);
 
   let restarted = false;
@@ -232,6 +234,113 @@ export async function deployEnvToRemote(brainDir, targetName, opts = {}) {
   };
 }
 
+/**
+ * Parse dotenv text into key -> { value, count }. The last assignment wins, as
+ * in dotenv; `count` exposes duplicates, which loaders resolve differently.
+ */
+export function parseDotenv(text) {
+  const out = new Map();
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+    if (!m) continue;
+    let value = m[2].trim();
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+      try { value = JSON.parse(value); } catch { value = value.slice(1, -1); }
+    } else if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, '');
+    }
+    out.set(m[1], { value, count: (out.get(m[1])?.count || 0) + 1 });
+  }
+  return out;
+}
+
+function findTarget(brainDir, targetName) {
+  const target = loadRemoteTargets(brainDir).find((t) => t.name === targetName);
+  if (!target) throw new Error(`Unknown remote target "${targetName}". List them with: total-recall auth secret remote list`);
+  return target;
+}
+
+/**
+ * Compare a deployed remote file with what the store would project there, key
+ * by key, by value fingerprint. Values never leave this process.
+ *
+ * @param {string} brainDir
+ * @param {string} targetName
+ * @param {{ keys?: string[], projectPath?: string }} opts
+ */
+export async function verifyRemote(brainDir, targetName, opts = {}) {
+  const target = findTarget(brainDir, targetName);
+  const projectPath = opts.projectPath || process.cwd();
+  const projection = await buildEnvProjection(brainDir, {
+    includeGlobal: target.includeGlobal !== false,
+    keys: opts.keys?.length ? opts.keys : target.keys,
+    projectPath,
+    projectSlug: projectSlugFromPath(projectPath),
+  });
+  const remoteFile = path.posix.join(target.remotePath, target.filename || '.env');
+  const remote = parseDotenv(fetchRemoteFile(target, remoteFile));
+  const projected = new Set(projection.entries.map(([key]) => key));
+  const rows = projection.entries.map(([key, value]) => {
+    const found = remote.get(key);
+    const status = !found ? 'missing'
+      : secretValueFingerprint(found.value) === secretValueFingerprint(value) ? 'match' : 'differs';
+    return { key, status, duplicates: found ? found.count - 1 : 0 };
+  });
+  return {
+    target: target.name,
+    host: target.host,
+    remoteFile,
+    rows,
+    remoteOnly: [...remote.keys()].filter((key) => !projected.has(key)),
+    ok: rows.every((row) => row.status === 'match' && !row.duplicates),
+  };
+}
+
+/**
+ * Move named keys out of a pm2 app's captured environment into the store, so
+ * the app can run from the store's projection instead. pm2 keeps the
+ * environment a process was first started with and lets it override the
+ * app's env file, which hides stale and unneeded credentials from the store.
+ * Only the keys asked for are read; nothing is printed.
+ *
+ * @param {string} brainDir
+ * @param {string} targetName
+ * @param {{ app: string, keys: string[], apply?: boolean, overwrite?: boolean, repos?: string[] }} opts
+ */
+export async function importFromPm2(brainDir, targetName, opts = {}) {
+  if (!opts.app) throw new Error('import-pm2 requires --app <pm2 process name>');
+  if (!opts.keys?.length) throw new Error('import-pm2 requires --keys: import only what the app needs');
+  const target = findTarget(brainDir, targetName);
+  const r = runSsh(target, 'pm2 jlist');
+  if (r.error || r.status !== 0) throw new Error(`pm2 jlist failed on "${target.name}": ${r.error?.message || (r.stderr || '').slice(0, 300)}`);
+  const raw = r.stdout || '';
+  let list;
+  // pm2 may print "[PM2] …" notices before the JSON array; start where the array does.
+  const start = raw.search(/^\[\s*(?:\{|\])/m);
+  try { list = JSON.parse(raw.slice(start)); } catch { throw new Error('pm2 jlist did not return JSON'); }
+  if (start === -1 || !Array.isArray(list)) throw new Error('pm2 jlist did not return JSON');
+  const proc = list.find((p) => p.name === opts.app);
+  if (!proc) throw new Error(`pm2 process "${opts.app}" not found on "${target.name}"`);
+  const env = proc.pm2_env?.env || {};
+  const secrets = await loadSecrets(brainDir);
+  const rows = [];
+  for (const key of opts.keys) {
+    const value = env[key] ?? proc.pm2_env?.[key];
+    if (value == null || value === '') { rows.push({ key, status: 'absent', applied: false }); continue; }
+    const stored = secrets[key];
+    const status = stored == null || stored === '' ? 'new' : String(stored) === String(value) ? 'same' : 'conflict';
+    let applied = false;
+    if (opts.apply && (status === 'new' || (status === 'conflict' && opts.overwrite))) {
+      await setSecret(brainDir, key, String(value), opts.repos?.length ? { repos: opts.repos } : {});
+      applied = true;
+    }
+    rows.push({ key, status, applied });
+  }
+  return { target: target.name, app: opts.app, rows };
+}
+
 /**
  * Deploy to every remote target that has this key bound via `keys`, or to
  * every target when the key list is unset (target opts into "all keys").

package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-store.mjs

@@ -80,6 +80,9 @@ export function mergeSecretMeta(prev = {}, patch = {}) {
   });
   assign('auto_rotate', (v) => !!v);
   assign('notes', (v) => (v == null || v === '' ? null : String(v)));
+  // The app-facing name a production key stands in for: GRO_CRM_TICKETS_SIGNING_SECRET
+  // provides TICKETS_SIGNING_SECRET to the repos it is bound to (see resolveSecretKey).
+  assign('provides', (v) => (v == null || v === '' ? null : String(v)));
   assign('project_path', (v) => (v == null || v === '' ? null : String(v)));
   assign('headscale_url', (v) => (v == null || v === '' ? null : String(v)));
   // Command that prints the headscale server log. Watch mode needs it because
@@ -478,11 +481,13 @@ export async function updateSecretMeta(brainDir, key, patch = {}, opts = {}) {
     throw new Error(`Secret not found: ${key}`);
   }
   const prev = secrets[META_KEY].keys[key] || {};
-  secrets[META_KEY].keys[key] = mergeSecretMeta(prev, {
-    ...patch,
-    updated_at: new Date().toISOString(),
-    created_at: prev.created_at || new Date().toISOString(),
-  });
+  // updated_at dates the value (set, rotate). A metadata write — labels, account
+  // sync, tracking — records meta_updated_at instead, so it never makes a stale
+  // value look fresh or pushes back its rotation.
+  secrets[META_KEY].keys[key] = {
+    ...mergeSecretMeta(prev, { ...patch, created_at: prev.created_at || new Date().toISOString() }),
+    meta_updated_at: new Date().toISOString(),
+  };
   await saveSecrets(brainDir, secrets);
   appendAudit(brainDir, {
     action: 'meta',
@@ -555,6 +560,22 @@ export async function setSecret(brainDir, key, value, opts = {}) {
   return { key, set: true };
 }
 
+/**
+ * The store key that answers `key` for one repo. Production services own
+ * distinct credentials under app-specific names; a key bound to the repo whose
+ * `provides` is `key` wins over the plain (developer) key. Two such keys for the
+ * same repo and name are ambiguous and refused, never guessed between.
+ */
+export async function resolveSecretKey(brainDir, key, repo) {
+  if (!repo) return key;
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  const meta = secrets[META_KEY].keys;
+  const hits = Object.keys(meta).filter((k) => k !== key && meta[k]?.provides === key
+    && Array.isArray(meta[k].repos) && meta[k].repos.includes(repo) && secrets[k] != null && secrets[k] !== '');
+  if (hits.length > 1) throw new Error(`${hits.join(' and ')} both provide ${key} for ${repo}; keep one`);
+  return hits[0] || key;
+}
+
 /**
  * Get a secret value (CLI only — do not inject into surfaces).
  */

package/scaffold/.agent/skills/total-recall/plugins/code-quality/package-lock.json

@@ -12,7 +12,7 @@
         "@gregiteen/ssss-cli": "0.11.2"
       },
       "devDependencies": {
-        "total-recall-brain": "^3.40.7"
+        "total-recall-brain": "3.41.1"
       }
     },
     "node_modules/@gregiteen/ssss-cli": {
@@ -2595,9 +2595,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
+      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/package-lock.json

@@ -12,7 +12,7 @@
         "@gregiteen/ssss-cli": "0.11.2"
       },
       "devDependencies": {
-        "total-recall-brain": "^3.40.7"
+        "total-recall-brain": "3.41.1"
       }
     },
     "node_modules/@gregiteen/ssss-cli": {
@@ -2595,9 +2595,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
+      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/embeddings/package-lock.json

@@ -9,7 +9,7 @@
       "version": "0.1.0",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "3.40.7"
+        "total-recall-brain": "3.41.1"
       }
     },
     "node_modules/@hexagon/base64": {
@@ -2566,9 +2566,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
+      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/package-lock.json

@@ -9,7 +9,7 @@
       "version": "1.1.2",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "3.40.7",
+        "total-recall-brain": "3.41.1",
         "vitest": "^4.1.10"
       }
     },
@@ -3560,9 +3560,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.1",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
+      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -45,3 +45,13 @@ This copies the plugin's source, skills, tests and docs into `bricks/mesh` and r
 **Use it directly with Total Recall (for your own machines and workflow).** Install it with `total-recall plugin install https://github.com/gregiteen/tr-plugin-mesh.git` and run `total-recall mesh`. Manage its credentials with `total-recall auth secret` and its skills with `total-recall skill`.
 
 Native-only state: new installations use validated SSSS records and the shared auth owner. Legacy imports and compatibility fallback formats are not supported.
+
+## Mesh screens and integration declarations
+
+The card defines Machines, Flows, Placement, Boundary and Join. Machines separates control membership, path checks, recorded login and actual execution. Hardware cells retain their measurement dates; failed or untested runtime probes remain unknown. Placement filters confirmed capabilities and includes the integration matrix declared in `plugin.json.mesh`.
+
+`total-recall mesh view <machines|flows|placement|boundary|join> --json` reads fixed owner commands. Each source carries its command, attempt time and either data or an explicit error. `mesh.provides` references declared operations/runtime modules; `mesh.integrations` identifies each owner and the meaning of its evidence; `mesh.endpoints` identifies served peer routes. These are declarations, not primitive grants or proof every provider action works. Read-only views never perform enrollment, policy changes, grant edits, deployments or secret transfers.
+
+The dashboard supplies frozen `host.operations`. Read-only cards show CLI handoffs for login administration and re-enrollment. A writable host may expose those declared actions; re-enrollment then requires target-specific confirmation. Enrollment keys never enter the card.
+
+Auth's `host-secrets-store` runtime supplies the single host-store selector for control credentials and mesh-sync authentication. Project `AGENT_DIR`/`TR_BRAIN` cannot divert these reads. Native SSSS audit contention is serialized by the generic host; errors still fail closed. The corresponding source runtime must be installed; missing modules never select a fallback implementation.

package/scaffold/.agent/skills/total-recall/plugins/mesh/{src/core/headscale-server.mjs → capability/control-server.mjs}

@@ -117,9 +117,12 @@ export async function provisionHeadscale(target, { exec = sshExec(target), fetch
   await must(exec('headscale configtest'), 'headscale configtest');
 
   log('start');
-  await must(exec('systemctl enable --now headscale'), 'Starting Headscale');
+  // The package starts Headscale at install with the example config (loopback :8080);
+  // `enable --now` leaves that process running, so restart to load the written config.
+  await must(exec('systemctl enable headscale && systemctl restart headscale'), 'Starting Headscale');
   let healthy = false;
-  for (let i = 0; i < 20 && !healthy; i++) {
+  // The first start also obtains the Let's Encrypt certificate, so allow it about a minute.
+  for (let i = 0; i < 40 && !healthy; i++) {
     healthy = (await exec(`curl -fsS https://${target.domain}/health`)).code === 0;
     if (!healthy) await wait(1500);
   }

package/scaffold/.agent/skills/total-recall/plugins/mesh/capability/headscale-api.mjs

@@ -0,0 +1,192 @@
+/**
+ * Headscale control-server API, host-free.
+ *
+ * The caller supplies the control-server URL, the API key and the HTTP
+ * transport, so this module reads no credential store and no environment. The
+ * Total Recall host resolves the key from its auth plugin and passes it in;
+ * a vendored copy passes its own.
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * 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;
+}
+
+/** A fetch with a deadline, used when the caller supplies no transport. */
+function timedFetch(fetchImpl) {
+  return async (url, options = {}) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs || DEFAULT_TIMEOUT_MS);
+    try {
+      return await fetchImpl(url, { ...options, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+/**
+ * Bind a client to one control server.
+ * @param {{ url: string, token: string, fetch?: (url: string, options: object) => Promise<Response> }} options
+ *   `fetch` receives `timeoutMs` in its options and is responsible for honouring it.
+ */
+export function createHeadscaleApi({ url, token, fetch: transport } = {}) {
+  const base = normalizeControlUrl(url);
+  if (!base) throw new Error('A Headscale control server URL is required');
+  assertSecureControlUrl(base);
+  if (typeof token !== 'string' || !token) throw new Error('A Headscale API key is required');
+  const send = transport || timedFetch(globalThis.fetch);
+
+  /** Authenticated JSON request; a non-2xx answer throws with `status` and a bounded `detail`. */
+  async function request(path, options = {}) {
+    const cleanPath = path.startsWith('/') ? path : `/${path}`;
+    const res = await send(`${base}${cleanPath}`, {
+      ...options,
+      headers: {
+        ...options.headers,
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      timeoutMs: 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');
+  }
+
+  /**
+   * Resolve a control-server user to both of its identifying forms.
+   * User-facing names resolve to the current API numeric ID.
+   */
+  async function resolveUser(requested) {
+    const data = await request('/api/v1/user');
+    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 };
+  }
+
+  /** Mint using the current numeric-user API without older-version retries. */
+  async function createPreAuthKey(options = {}) {
+    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 resolveUser(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 request('/api/v1/preauthkey', {
+      method: 'POST', body: JSON.stringify({ user, reusable: options.reusable === true,
+        ephemeral: options.ephemeral === true, expiration, aclTags: options.aclTags || [] }),
+    });
+    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 };
+  }
+
+  /**
+   * 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.
+   */
+  async function getPolicy() {
+    try {
+      const data = await request('/api/v1/policy');
+      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;
+    }
+  }
+
+  /**
+   * 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.
+   */
+  async function setPolicy(policy) {
+    if (!policy) throw new Error('A policy is required');
+    const serialised = typeof policy === 'string' ? policy : JSON.stringify(policy, null, 2);
+    const data = await request('/api/v1/policy', { method: 'PUT', body: JSON.stringify({ policy: serialised }) });
+    return { policy: data?.policy ?? serialised, updatedAt: data?.updatedAt ?? null, raw: data };
+  }
+
+  return { url: base, request, resolveUser, createPreAuthKey, getPolicy, setPolicy };
+}
+
+/**
+ * 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'],
+      },
+    ],
+  };
+}