talon-agent 5.20.1 → 5.22.0

package/README.md

@@ -493,6 +493,7 @@ Config file: `~/.talon/config.json`
 | `dreamModel`               | ---          | Model for dream / memory consolidation (falls back to `model`)                                                          |
 | `dreamEffort`              | ---          | Reasoning effort for the dream agent — same levels as `heartbeatEffort`                                                 |
 | `braveApiKey`              | ---          | Brave Search API key                                                                                                    |
+| `fetchUrl`                 | ---          | `fetch_url` reaches every address by default, LAN and loopback included. `{ "allowPrivateNetworks": false }` opts into the SSRF guard (refuses private, loopback, link-local and metadata addresses on every redirect hop) — worth it on a cloud VM |
 | `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                                                                                  |
 | `plugins`                  | `[]`         | External plugin packages                                                                                                |
 | `disabledToolTags`         | ---          | Hide whole tool groups from the model (e.g. `["stickers", "web"]`) — each registered tool costs context tokens per session |
@@ -505,7 +506,7 @@ Config file: `~/.talon/config.json`
 | `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history                                                                       |
 | `whatsapp`                 | ---          | WhatsApp frontend: pairing, allowlists, group policy ([above](#whatsapp))                                               |
 | `discord`                  | ---          | Discord frontend: bot token, application ID, guild / channel allowlists                                                 |
-| `native`                   | ---          | Client bridge: host, port, token, TLS ([above](#desktop--mobile-app))                                                   |
+| `native`                   | ---          | Client bridge: host, port, token, TLS ([above](#desktop--mobile-app)). `companionScopes` (default all three) narrows what a paired companion's credential may do ([docs/mesh-credentials.md](docs/mesh-credentials.md)) |
 | `nativeTools`              | `false`      | Swap the SDK's built-in Read/Write/Edit/Bash/Glob/Grep for Talon's own — these also route to a teleported device        |
 | `fuse`                     | `"auto"`     | Mount the `talon://` namespace with FUSE live views; falls back to a symlink farm where the host can't                  |
 | `github`                   | ---          | GitHub plugin config (see above)                                                                                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.20.1",
+  "version": "5.22.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -101,7 +101,7 @@
     "build:fusefs": "node native/talon-fusefs/build.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.104.1",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",

package/src/cli/commands/mesh-audit.ts

@@ -0,0 +1,89 @@
+/**
+ * `talon mesh audit [--limit N] [--device X]` — the daemon's record of
+ * every command it sent to a mesh device (core/mesh/audit.ts), read
+ * through the loopback gateway. Arguments were never recorded, only their
+ * hash; the short form here is its first 12 hex characters.
+ */
+
+import pc from "picocolors";
+import { fetchGateway } from "../daemon-api.js";
+import type { MeshAuditEntry } from "../../core/mesh/audit.js";
+
+type AuditQuery = { limit?: number; device?: string };
+
+/** Parse `--limit N` / `--device X` (either `--flag value` or `--flag=value`). */
+export function parseAuditArgs(args: readonly string[]): AuditQuery | string {
+  const query: AuditQuery = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    const eq = arg.indexOf("=");
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    if (flag !== "--limit" && flag !== "--device") {
+      return `Unknown option: ${arg}`;
+    }
+    const value = eq === -1 ? args[++i] : arg.slice(eq + 1);
+    if (value === undefined || value === "") return `${flag} needs a value`;
+    if (flag === "--device") {
+      query.device = value;
+      continue;
+    }
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1) {
+      return `--limit must be a positive integer, got "${value}"`;
+    }
+    query.limit = limit;
+  }
+  return query;
+}
+
+function issuerText(entry: MeshAuditEntry): string {
+  const i = entry.issuer;
+  if (!i) return pc.dim("no turn");
+  return [
+    i.source && i.source !== "message" ? i.source : null,
+    i.sender ? `by ${i.sender}` : null,
+    `chat ${i.chatId}`,
+    i.turnId,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+function renderEntry(entry: MeshAuditEntry): void {
+  const mark = entry.ok ? pc.green("✔") : pc.red("✖");
+  console.log(
+    `  ${pc.dim(entry.time)}  ${mark} ${pc.cyan(entry.command)} → ${entry.deviceName} ${pc.dim(`(${entry.deviceId})`)}  ${entry.durationMs}ms`,
+  );
+  console.log(
+    pc.dim(
+      `      ${issuerText(entry)} · args ${entry.argsHash.slice(0, 12)}` +
+        (entry.error ? ` · ${entry.error}` : ""),
+    ),
+  );
+}
+
+export async function runMeshAudit(
+  port: number,
+  query: AuditQuery,
+): Promise<void> {
+  const params = new URLSearchParams();
+  if (query.limit !== undefined) params.set("limit", String(query.limit));
+  if (query.device) params.set("device", query.device);
+  const qs = params.size > 0 ? `?${params.toString()}` : "";
+  const reply = (await fetchGateway(port, `/mesh/audit${qs}`)) as {
+    ok: boolean;
+    entries?: MeshAuditEntry[];
+    error?: string;
+  };
+  if (!reply.ok) {
+    console.error(`\n  ${pc.red("✖")} ${reply.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const entries = reply.entries ?? [];
+  console.log(`\n  ${pc.bold("Mesh command audit")}\n`);
+  if (entries.length === 0)
+    console.log(`  ${pc.dim("(no commands recorded)")}`);
+  for (const entry of entries) renderEntry(entry);
+  console.log("");
+}

package/src/cli/commands/mesh.ts

@@ -7,6 +7,9 @@
  *   talon mesh rotate <device>           the device swaps credentials on its
  *                                        next heartbeat (old one: 7-day grace)
  *   talon mesh scopes <device> <list>    e.g. device,client,operator
+ *   talon mesh audit [--limit N] [--device X]
+ *                                        commands the daemon sent to devices
+ *                                        (core/mesh/audit.ts)
  *
  * Everything goes through the running daemon's loopback gateway
  * (core/engine/gateway-routes.ts → core/mesh/credentials/admin.ts): the
@@ -17,14 +20,16 @@
 import pc from "picocolors";
 import { fetchGateway, requireGatewayPort } from "../daemon-api.js";
 import type { DeviceCredential } from "../../core/mesh/credentials/index.js";
+import { parseAuditArgs, runMeshAudit } from "./mesh-audit.js";
 
 const USAGE = `
-  ${pc.bold("talon mesh")} — per-device mesh credentials
+  ${pc.bold("talon mesh")} — per-device mesh credentials and command audit
 
     ${pc.cyan("list")}                              credentials, scopes, last use (default)
     ${pc.cyan("revoke")} <device|credential-id>     revoke now; drops its live sessions
     ${pc.cyan("rotate")} <device>                   re-issue on the device's next heartbeat
     ${pc.cyan("scopes")} <device> <scope,scope>     set scopes: device, client, operator
+    ${pc.cyan("audit")} [--limit N] [--device X]    commands sent to devices (newest last)
 `;
 
 type Overview = {
@@ -101,12 +106,28 @@ async function adminOp(
   }
 }
 
+async function runAudit(args: readonly string[]): Promise<void> {
+  const query = parseAuditArgs(args);
+  if (typeof query === "string") {
+    console.error(`  ${pc.red("✖")} ${query}\n${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+  const port = await requireGatewayPort();
+  if (port === null) {
+    process.exitCode = 1;
+    return;
+  }
+  await runMeshAudit(port, query);
+}
+
 export async function runMeshCommand(args: string[]): Promise<void> {
   const [sub = "list", target, scopes] = args;
   if (sub === "help" || sub === "--help" || sub === "-h") {
     console.log(USAGE);
     return;
   }
+  if (sub === "audit") return runAudit(args.slice(1));
   const known = ["list", "revoke", "rotate", "scopes"];
   if (!known.includes(sub)) {
     console.error(`  Unknown mesh command: ${sub}\n${USAGE}`);

package/src/cli/index.ts

@@ -113,7 +113,7 @@ function printHelp(): void {
     `    ${pc.cyan("backup")}     Snapshots and checkpoints (now/list/show/pin/restore)`,
   );
   console.log(
-    `    ${pc.cyan("mesh")}       Device credentials (list/revoke/rotate/scopes)`,
+    `    ${pc.cyan("mesh")}       Device credentials + command audit (list/revoke/rotate/scopes/audit)`,
   );
   console.log(`    ${pc.cyan("config")}     View/edit configuration`);
   console.log(

package/src/cli/status.ts

@@ -4,8 +4,9 @@
  */
 
 import pc from "picocolors";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { findRunningInstance } from "../core/daemon/discovery.js";
+import { files } from "../util/paths.js";
 import { printBanner, loadConfig } from "./config.js";
 import { CONFIG_FILE } from "./context.js";
 
@@ -38,6 +39,26 @@ export function formatAlertLines(health: Record<string, unknown>): string[] {
   });
 }
 
+/**
+ * The native bridge's TLS certificate fingerprint, from its discovery file —
+ * what a talon-node pins on first use, shown so an operator can compare the
+ * two. Null when the bridge is off, serves plain http, or never ran.
+ */
+export function bridgeFingerprint(
+  path: string = files.nativeBridge,
+): string | null {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as {
+      fingerprint?: unknown;
+    };
+    return typeof raw.fingerprint === "string" && raw.fingerprint
+      ? raw.fingerprint
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function showStatus(): Promise<void> {
   printBanner();
   const instance = await findRunningInstance();
@@ -60,6 +81,8 @@ export async function showStatus(): Promise<void> {
     console.log(`  ${pc.dim("Messages")}     ${h.messages}`);
     console.log(`  ${pc.dim("Queue")}        ${h.queue} pending`);
     console.log(`  ${pc.dim("Errors")}       ${h.errors}`);
+    const fingerprint = bridgeFingerprint();
+    if (fingerprint) console.log(`  ${pc.dim("Bridge TLS")}   ${fingerprint}`);
     console.log(`  ${pc.dim("Last active")}  ${h.lastActivity}\n`);
     const alerts = formatAlertLines(h);
     if (alerts.length > 0) {

package/src/core/config/index.ts

@@ -234,11 +234,11 @@ const nativeConfigSchema = z
     legacySharedToken: z.boolean().optional(),
     /**
      * Scopes a companion's per-device credential carries — at pairing and
-     * on the in-band upgrade. Default ["device", "client"]: the mesh plus
-     * the chat UI. Adding "operator" lets every paired phone change config,
-     * toggle plugins and read logs; prefer granting it to one device with
-     * `talon mesh scopes <device> device,client,operator`. Nodes always get
-     * ["device"].
+     * on the in-band upgrade. Default ["device", "client", "operator"]:
+     * the mesh, the chat UI and its settings (config writes, plugin
+     * toggles, logs) — what the shared token allowed. Set ["device",
+     * "client"] to keep paired phones out of config; `talon mesh scopes
+     * <device> <list>` changes one device. Nodes always get ["device"].
      */
     companionScopes: z
       .array(z.enum(["device", "client", "operator"]))
@@ -677,14 +677,15 @@ const configSchema = z.object({
     .optional(),
   braveApiKey: z.string().optional(),
   /**
-   * `fetch_url` refuses hosts that resolve to loopback, private (RFC 1918,
-   * CGNAT, ULA), link-local (incl. the 169.254.169.254 metadata endpoint)
-   * or reserved addresses, re-checking every redirect hop. Set
-   * `allowPrivateNetworks: true` only on a host where the agent should
-   * read local services (a home lab, a dev server).
+   * `fetch_url` reaches any address by default, local services included (a
+   * home lab, a dev server, the LAN). Set `allowPrivateNetworks: false` to
+   * opt into the SSRF guard: it then refuses hosts that resolve to
+   * loopback, private (RFC 1918, CGNAT, ULA), link-local (incl. the
+   * 169.254.169.254 metadata endpoint) or reserved addresses, re-checking
+   * every redirect hop — worth it on a cloud VM.
    */
   fetchUrl: z
-    .object({ allowPrivateNetworks: z.boolean().default(false) })
+    .object({ allowPrivateNetworks: z.boolean().default(true) })
     .strict()
     .optional(),
   /**

package/src/core/engine/gateway-actions/fetch-url/guard.ts

@@ -17,9 +17,9 @@
  * direct, redirect and static-DNS paths; rebinding needs a hostile DNS
  * server and a lucky race.
  *
- * Operators who run Talon next to services they WANT it to read (a home
- * lab, a local dev server) can opt out with
- * `fetchUrl.allowPrivateNetworks: true`.
+ * The guard is opt-in: `fetch_url` applies it only when the operator sets
+ * `fetchUrl.allowPrivateNetworks: false`. By default the agent can read
+ * local services (a home lab, a local dev server).
  */
 
 import { lookup } from "node:dns/promises";
@@ -163,7 +163,7 @@ export async function assertPublicUrl(
   if (blocked) {
     throw new BlockedUrlError(
       `Refusing to fetch ${host}: it resolves to a private, loopback or link-local address (${blocked}). ` +
-        `Set fetchUrl.allowPrivateNetworks in config.json to allow local addresses.`,
+        `Remove fetchUrl.allowPrivateNetworks: false from config.json (or set it to true) to allow local addresses.`,
     );
   }
 }

package/src/core/engine/gateway-actions/fetch-url/index.ts

@@ -75,8 +75,9 @@ export const fetchUrlHandlers: SharedActionHandlers = {
     const invalid = urlError(url);
     if (invalid) return { ok: false, error: invalid };
     try {
-      // Every hop is checked against private/loopback/link-local ranges
-      // (see guard.ts) unless the operator opted out for local use.
+      // Local addresses are reachable by default; with
+      // `fetchUrl.allowPrivateNetworks: false` every hop is checked against
+      // private/loopback/link-local ranges (see guard.ts).
       const resp = await guardedFetch(
         url,
         {
@@ -85,7 +86,7 @@ export const fetchUrlHandlers: SharedActionHandlers = {
         },
         {
           allowPrivateNetworks:
-            getPoolConfig()?.fetchUrl?.allowPrivateNetworks === true,
+            getPoolConfig()?.fetchUrl?.allowPrivateNetworks !== false,
         },
       );
       if (!resp.ok) return { ok: false, error: `HTTP ${resp.status}` };

package/src/core/engine/gateway-actions/mesh.ts

@@ -68,6 +68,7 @@ export const meshHandlers: SharedActionHandlers = {
       body.device ?? body.deviceId,
       body.apk_path,
       body.remote_path,
+      body.allow_downgrade,
     ),
   // Remote self-update for a headless talon-node: push a new binary and have
   // the node verify, swap, and restart into it. binary_path is optional —
@@ -78,6 +79,7 @@ export const meshHandlers: SharedActionHandlers = {
       body.device ?? body.deviceId,
       body.binary_path,
       body.remote_path,
+      body.allow_downgrade,
     ),
   // Node provisioning: materialize a talon-node binary for any arch, and
   // mint single-use bridge-served install links for fresh hosts.

package/src/core/engine/gateway-routes.ts

@@ -204,6 +204,22 @@ const ROUTES: readonly GatewayRoute[] = [
       sendJson(res, 200, await credentialAdmin(ctx, body));
     },
   },
+  {
+    // The mesh command audit — the transport for `talon mesh audit`.
+    // Prefix match: the query (?limit=&device=) follows the path.
+    method: "GET",
+    path: "/mesh/audit",
+    match: "prefix",
+    handle: async ({ res, url }) => {
+      const limit = Number(url.searchParams.get("limit") ?? "");
+      const device = url.searchParams.get("device") ?? "";
+      const entries = await getMeshService().readAudit({
+        ...(Number.isInteger(limit) && limit > 0 ? { limit } : {}),
+        ...(device ? { device } : {}),
+      });
+      sendJson(res, 200, { ok: true, entries });
+    },
+  },
   {
     // MCP hub — daemon-hosted MCP-over-HTTP endpoints for every backend
     // (see core/mcp-hub).

package/src/core/mesh/audit.ts

@@ -0,0 +1,232 @@
+/**
+ * Mesh command audit — one line per device command the daemon dispatched:
+ * when, who asked (chat / turn / sender, when a turn issued it), which
+ * device, which command, a hash of its arguments, how it ended, and how
+ * long it took.
+ *
+ * Arguments are never written, only `argsHash`: the SHA-256 of their
+ * canonical JSON (keys sorted at every depth). Command lines and file
+ * bodies stay out of the file, but an operator holding a suspect command
+ * can still prove whether it is the one that ran.
+ *
+ * The log is a bounded ring on disk: JSON lines appended to
+ * ~/.talon/data/mesh-audit.jsonl (0600). When the next line would take the
+ * file past `maxBytes` it rotates to `mesh-audit.jsonl.1`, replacing the
+ * previous generation, so the pair never holds more than about twice the
+ * cap. Appends are serialized, so lines never interleave.
+ *
+ * Recording is fire-and-forget and can never fail a command: every error
+ * is caught here and logged (once per failure streak), and the command
+ * path carries on.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  appendFile,
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  stat,
+} from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { dirs } from "../../util/paths.js";
+import { logWarn } from "../../util/log.js";
+import { currentTurn } from "../../util/logging/turn-scope.js";
+
+const DEFAULT_FILE = resolve(dirs.data, "mesh-audit.jsonl");
+/** One generation's cap; the file plus its `.1` stay under twice this. */
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const DEFAULT_READ_LIMIT = 50;
+const MAX_READ_LIMIT = 5_000;
+/** Longest failure reason kept (the device's own one-line summary). */
+const MAX_ERROR_CHARS = 200;
+
+/** Who issued a command. Present only when a turn issued it. */
+export type MeshAuditIssuer = {
+  chatId: string;
+  turnId: string;
+  /** The sender's operator key or display name, when the turn had one. */
+  sender?: string;
+  /** What started the turn: message, cron, trigger, pulse, agent. */
+  source?: string;
+};
+
+export type MeshAuditEntry = {
+  /** ISO-8601 dispatch time. */
+  time: string;
+  issuer: MeshAuditIssuer | null;
+  deviceId: string;
+  deviceName: string;
+  command: string;
+  /** SHA-256 (hex) of the canonical JSON of the command's params. */
+  argsHash: string;
+  ok: boolean;
+  /** Why it failed (one line, truncated); absent on success. */
+  error?: string;
+  durationMs: number;
+};
+
+export type MeshAuditQuery = {
+  /** Newest entries to return (default 50). */
+  limit?: number;
+  /** Device id (exact) or name (case-insensitive, substring). */
+  device?: string;
+};
+
+/** Sort object keys at every depth, so equal params hash equally. */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    // fromEntries defines own properties, so a `__proto__` key stays data.
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .map((key) => [key, canonical(record[key])]),
+    );
+  }
+  return value;
+}
+
+/** SHA-256 (hex) of the canonical JSON of a command's params. */
+export function hashCommandArgs(params: unknown): string {
+  const json = JSON.stringify(canonical(params ?? {})) ?? "null";
+  return createHash("sha256").update(json).digest("hex");
+}
+
+/**
+ * Who is issuing a command right now: the running turn of the current
+ * async chain (tool actions re-enter it through the gateway), or null for
+ * a dispatch no turn made (a `/mesh` command, a bridge UI request).
+ */
+export function auditIssuer(): MeshAuditIssuer | null {
+  const turn = currentTurn();
+  if (!turn) return null;
+  const { sender, source } = turn.issuer;
+  return {
+    chatId: turn.chatId,
+    turnId: turn.turnId,
+    ...(sender ? { sender } : {}),
+    ...(source ? { source } : {}),
+  };
+}
+
+/** A device's failure message, kept to one short line. */
+export function auditErrorText(message: string | undefined): string {
+  const line = (message ?? "failed").split(/\r?\n/, 1)[0]!.trim();
+  return line.length > MAX_ERROR_CHARS
+    ? `${line.slice(0, MAX_ERROR_CHARS - 1)}…`
+    : line || "failed";
+}
+
+function matchesDevice(entry: MeshAuditEntry, device: string): boolean {
+  const q = device.toLowerCase();
+  return (
+    entry.deviceId === device ||
+    (typeof entry.deviceName === "string" &&
+      entry.deviceName.toLowerCase().includes(q))
+  );
+}
+
+/** Parse JSON lines, skipping any torn or foreign line. */
+function parseLines(raw: string): MeshAuditEntry[] {
+  const out: MeshAuditEntry[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line) as MeshAuditEntry;
+      if (entry && typeof entry.command === "string") out.push(entry);
+    } catch {
+      // A half-written line from a crash mid-append: skip it.
+    }
+  }
+  return out;
+}
+
+export class MeshAuditLog {
+  private chain: Promise<void> = Promise.resolve();
+  /** Bytes in the current generation; null until first checked on disk. */
+  private size: number | null = null;
+  private failing = false;
+
+  constructor(
+    private readonly file: string = DEFAULT_FILE,
+    private readonly maxBytes: number = DEFAULT_MAX_BYTES,
+  ) {}
+
+  /** Queue one entry. Never throws and never rejects. */
+  record(entry: MeshAuditEntry): void {
+    let line: string;
+    try {
+      line = `${JSON.stringify(entry)}\n`;
+    } catch (err) {
+      this.warn(err);
+      return;
+    }
+    this.chain = this.chain
+      .then(() => this.append(line))
+      .then(() => {
+        this.failing = false;
+      })
+      .catch((err: unknown) => this.warn(err));
+  }
+
+  /** Resolves once every queued entry has been written (or given up on). */
+  flush(): Promise<void> {
+    return this.chain;
+  }
+
+  /** The newest matching entries, oldest first. */
+  async read(query: MeshAuditQuery = {}): Promise<MeshAuditEntry[]> {
+    await this.flush();
+    const limit = Math.min(
+      MAX_READ_LIMIT,
+      Math.max(1, Math.floor(query.limit ?? DEFAULT_READ_LIMIT)),
+    );
+    const [older, current] = await Promise.all([
+      readFile(`${this.file}.1`, "utf8").catch(() => ""),
+      readFile(this.file, "utf8").catch(() => ""),
+    ]);
+    let entries = [...parseLines(older), ...parseLines(current)];
+    if (query.device) {
+      const device = query.device;
+      entries = entries.filter((e) => matchesDevice(e, device));
+    }
+    return entries.slice(-limit);
+  }
+
+  private async append(line: string): Promise<void> {
+    if (this.size === null) this.size = await this.open();
+    const bytes = Buffer.byteLength(line);
+    if (this.size > 0 && this.size + bytes > this.maxBytes) {
+      await rename(this.file, `${this.file}.1`);
+      this.size = 0;
+    }
+    await appendFile(this.file, line, { mode: 0o600 });
+    this.size += bytes;
+  }
+
+  /** First write this process: make the directory, tighten an old file. */
+  private async open(): Promise<number> {
+    await mkdir(dirname(this.file), { recursive: true, mode: 0o700 });
+    let size: number;
+    try {
+      size = (await stat(this.file)).size;
+    } catch {
+      return 0; // no file yet: appendFile creates it 0600
+    }
+    // A file from an older build or a copied home may be wider than 0600.
+    await chmod(this.file, 0o600).catch(() => {});
+    return size;
+  }
+
+  private warn(err: unknown): void {
+    if (this.failing) return;
+    this.failing = true;
+    logWarn(
+      "mesh",
+      `mesh.audit event=write_failed file=${this.file} err=${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/core/mesh/credentials/index.ts

@@ -7,6 +7,7 @@ export { DeviceCredentialStore } from "./store.js";
 export { isDeviceCredentialToken } from "./token.js";
 export {
   DEFAULT_COMPANION_SCOPES,
+  FORMER_COMPANION_SCOPES,
   NODE_SCOPES,
   type CredentialOrigin,
   type DeviceCredential,