talon-agent 5.14.0 → 5.18.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dylan Neve
+Copyright (c) 2026 The Falconry
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -10,7 +10,7 @@
 [![Frontends](https://img.shields.io/badge/frontends-Telegram_%7C_WhatsApp_%7C_Discord_%7C_Teams_%7C_Terminal_%7C_App-25D366)](#frontends)
 [![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex_%7C_Antigravity_%7C_OpenAI_Agents-D97706)](#backends)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![CI](https://github.com/dylanneve1/talon/actions/workflows/ci.yml/badge.svg)](https://github.com/dylanneve1/talon/actions/workflows/ci.yml)
+[![CI](https://github.com/thefalconry/talon/actions/workflows/ci.yml/badge.svg)](https://github.com/thefalconry/talon/actions/workflows/ci.yml)
 
 Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **Discord**, **Microsoft Teams**, the **Terminal**, and a **cross-platform Desktop/Mobile companion app** (Flutter), with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, **Codex**, **Antigravity**, or **OpenAI Agents**) and full tool access through MCP.
 
@@ -39,7 +39,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **Discord
 ## Quick Start
 
 ```bash
-git clone https://github.com/dylanneve1/talon.git && cd talon
+git clone https://github.com/thefalconry/talon.git && cd talon
 npm install
 
 # Interactive setup (select frontend, configure tokens, pick model)
@@ -73,7 +73,7 @@ modules are embedded in the binary.
 
 ```bash
 # Homebrew (macOS / Linux)
-brew install dylanneve1/talon/talon
+brew install thefalconry/talon/talon
 
 # Debian / Ubuntu — download the .deb for your arch from the release, then:
 sudo apt install ./talon_<version>_amd64.deb     # or _arm64.deb
@@ -498,6 +498,9 @@ Config file: `~/.talon/config.json`
 | `disabledTools`            | ---          | Hide individual tools by name (`end_turn` cannot be disabled)                                                           |
 | `adminUserId`              | ---          | Telegram user ID for `/admin` commands                                                                                  |
 | `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                                                                          |
+| `allowedGroups`            | ---          | Telegram group IDs the bot serves. Unset: groups the admin is in are still admitted (legacy, warned at startup)          |
+| `operatorIds`              | ---          | Extra operator identities (`"123"`, `"wa_dm_<number>"`, `"discord:<id>"`, `"teams:<id>"`) — only operators get the full tool set |
+| `guestDmScope`             | on           | Conversation-only tools for non-operator senders. Always applied in groups; `enabled: false` exempts DMs (legacy)       |
 | `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                                                 |
@@ -564,7 +567,7 @@ Commands: `/model`, `/effort`, `/context`, `/status`, `/reset`, `/rename`, `/res
 
 ## Production
 
-**Docker:** the image runs the daemon on Bun (`bun src/index.ts`); `~/.talon` and `~/.claude` are bind-mounted from the host into the container's `HOME=/home/bun`. Prebuilt images are on GHCR (`ghcr.io/dylanneve1/talon:latest`), and a first boot can be configured entirely from `TALON_*` environment variables — see **[docs/docker.md](docs/docker.md)** for the quick install, and **[docs/truenas.md](docs/truenas.md)** for a step-by-step TrueNAS SCALE install.
+**Docker:** the image runs the daemon on Bun (`bun src/index.ts`); `~/.talon` and `~/.claude` are bind-mounted from the host into the container's `HOME=/home/bun`. Prebuilt images are on GHCR (`ghcr.io/thefalconry/talon:latest`), and a first boot can be configured entirely from `TALON_*` environment variables — see **[docs/docker.md](docs/docker.md)** for the quick install, and **[docs/truenas.md](docs/truenas.md)** for a step-by-step TrueNAS SCALE install.
 
 ```bash
 docker compose up -d
@@ -576,7 +579,7 @@ The image is also ready for the **Antigravity (`agy`) backend**: add `-f docker-
 
 **Systemd:** unit file at `packaging/systemd/talon.service` — copy to `/etc/systemd/system/`, set `User=` and `WorkingDirectory=`, then `systemctl enable --now talon`.
 
-**Health endpoint:** `GET http://localhost:19876/health` returns JSON with uptime, memory, queue depth, active sessions, and last activity timestamp.
+**Health endpoint:** `GET http://localhost:19876/health` returns the daemon's identity (`app`, `mode`, `pid`, `port`, `startedAt`, `ok`). With the gateway token (`Authorization: Bearer $(cat ~/.talon/keys/gateway-token)`) it also returns uptime, memory, queue depth, active sessions, and last activity timestamp. Every other gateway route requires that token.
 
 **Logging:** Structured JSON via pino to `~/.talon/talon.log`. Rotated on startup when the file exceeds 10MB.
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "talon-agent",
-  "version": "5.14.0",
+  "version": "5.18.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
-  "author": "Dylan Neve",
+  "author": "The Falconry",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dylanneve1/talon.git"
+    "url": "https://github.com/thefalconry/talon.git"
   },
   "keywords": [
     "telegram",

package/prompts/system/heartbeat-agent.md

@@ -40,7 +40,7 @@ is a primary responsibility, not an optional extra. Goal tools
 (`update_goal`, `list_goals`, …) require an explicit `chat_id` parameter
 in heartbeat mode — use the chat id shown next to each goal.
 
-OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Dylan's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'. Cross-frontend: every tool server also carries `send_via(frontend=..., target=..., text=...)`, which delivers through ANY enabled frontend — target is the numeric chat id as a string, or for WhatsApp a phone number ("+353871234567") or wa_dm_/wa_group_ id.
+OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Ada's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'. Cross-frontend: every tool server also carries `send_via(frontend=..., target=..., text=...)`, which delivers through ANY enabled frontend — target is the numeric chat id as a string, or for WhatsApp a phone number ("+353871234567") or wa_dm_/wa_group_ id.
 
 Reaching out is part of the job, not an exception: when a run turns up
 something a user would genuinely want to know — a goal completed or

package/src/backend/agy/factory.ts

@@ -52,6 +52,9 @@ import {
 const agyFactory: BackendFactory = {
   id: "agy",
   label: "Antigravity",
+  // Its own shell/file tools can't be withheld per turn, so guest-scoped
+  // turns (non-operator senders) are refused rather than run with them.
+  guestToolScope: "refused",
   doctor: (config, isActive) => agyDoctorChecks(config, isActive),
 
   async init(config, ctx) {

package/src/backend/agy/mcp/config.ts

@@ -45,6 +45,7 @@ import {
 } from "../../../core/mcp-hub/index.js";
 import { frontendsForChat } from "../../runtime/frontends.js";
 import { logWarn } from "../../../util/log.js";
+import { gatewayAuthHeaders } from "../../../core/engine/gateway-auth.js";
 import { AGY_MCP_PREFIX } from "../constants.js";
 
 // ── Paths ───────────────────────────────────────────────────────────────────
@@ -77,6 +78,8 @@ function agyMcpSnapshotDir(override?: string): string {
  */
 export interface AgyMcpServer {
   disabled: boolean;
+  /** Gateway bearer token (`agy mcp add --header` writes this shape). */
+  headers: Record<string, string>;
   serverUrl: string;
 }
 
@@ -129,8 +132,13 @@ export function buildAgyMcpServers(args: {
   const { chatId, bridgeUrl, frontends, braveApiKey } = args;
   const scope = args.scope ?? agyScopeSlug(chatId);
   const servers: Record<string, AgyMcpServer> = {};
+  const headers = gatewayAuthHeaders();
   const add = (name: string, url: string) => {
-    servers[agyServerKey(scope, name)] = { disabled: false, serverUrl: url };
+    servers[agyServerKey(scope, name)] = {
+      disabled: false,
+      headers,
+      serverUrl: url,
+    };
   };
 
   for (const frontend of frontendsForChat(chatId, frontends)) {
@@ -198,7 +206,11 @@ function writeConfigAtomic(
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.talon-${randomBytes(6).toString("hex")}.tmp`;
   try {
-    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, "utf-8");
+    // Owner-only: Talon's entries carry the gateway token.
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
     renameSync(tmp, path);
   } catch (err) {
     try {

package/src/backend/claude-sdk/factory.ts

@@ -41,6 +41,9 @@ const claudeSdkFactory: BackendFactory = {
   // no migration is needed.
   id: "claude",
   label: "Anthropic",
+  // Guest turns run with no SDK built-ins and only guest-allowed MCP
+  // servers (see options.ts), so the hub's guest scope is the whole surface.
+  guestToolScope: "enforced",
   doctor: (config, isActive) => claudeDoctorChecks(config, isActive),
 
   async init(config, ctx) {

package/src/backend/claude-sdk/options.ts

@@ -32,10 +32,14 @@ import {
 import { toolFingerprint } from "../runtime/cache/cache-telemetry.js";
 import { reportToolFingerprint } from "../runtime/cache/cache-metrics.js";
 import { log, logError } from "../../util/log.js";
+import {
+  GATEWAY_TOKEN_ENV,
+  gatewayToken,
+} from "../../core/engine/gateway-auth.js";
 import { getConfig, getBridgePort } from "./state.js";
 import { ALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
 import {
-  isGuestChat,
+  isGuestTurn,
   isGuestPluginAllowed,
 } from "../../core/mcp-hub/guest-scope.js";
 import { VALID_TOOL_FRONTENDS } from "../../core/mcp-hub/talon-server.js";
@@ -92,6 +96,8 @@ export function getActiveFrontends(): readonly string[] {
 export type HubMcpEntry = {
   type: "http";
   url: string;
+  /** Gateway bearer token — see `hubAuthHeaders`. */
+  headers: Record<string, string>;
   alwaysLoad?: boolean;
   /** Per-server tool-call timeout in ms (overrides MCP_TOOL_TIMEOUT). */
   timeout?: number;
@@ -106,6 +112,18 @@ export type HubMcpEntry = {
  */
 const FRONTEND_TOOL_CALL_TIMEOUT_MS = 3_900_000; // 65 min
 
+/**
+ * Hub auth header for the Claude CLI's MCP config. The SDK hands that config
+ * to the CLI on its command line, which other local accounts can read — so
+ * the header carries a `${TALON_GATEWAY_TOKEN}` reference the CLI expands
+ * from its environment (inherited from the daemon), never the value itself.
+ * `gatewayToken()` runs first so the variable is guaranteed to be exported.
+ */
+function hubAuthHeaders(): Record<string, string> {
+  gatewayToken();
+  return { Authorization: `Bearer \${${GATEWAY_TOKEN_ENV}}` };
+}
+
 /**
  * Build the MCP servers map for a chat query.
  * Includes frontend-specific tool servers and Brave Search, if configured.
@@ -130,6 +148,7 @@ export function buildMcpServers(chatId: string): Record<string, HubMcpEntry> {
     servers[`${frontend}-tools`] = {
       type: "http",
       url: talonHubUrl(bridgeUrl, frontend, chatId),
+      headers: hubAuthHeaders(),
       // Always include the frontend's tools in the turn-1 prompt instead of
       // deferring them behind the SDK's tool search. These are the bot's
       // primary surface — it needs `end_turn`/`send`/`react` on EVERY turn to
@@ -155,6 +174,7 @@ export function buildMcpServers(chatId: string): Record<string, HubMcpEntry> {
     servers["brave-search"] = {
       type: "http",
       url: pluginHubUrl(bridgeUrl, "brave-search", chatId),
+      headers: hubAuthHeaders(),
     };
   }
 
@@ -176,6 +196,7 @@ export function buildPluginMcpServers(
     servers[name] = {
       type: "http",
       url: pluginHubUrl(bridgeUrl, name, chatId),
+      headers: hubAuthHeaders(),
     };
   }
   return servers;
@@ -393,10 +414,10 @@ export function buildSdkOptions(
   const { postToolUseFailureHook, postToolBatchHook } =
     buildTurnTerminatorHooks();
 
-  // Guest DMs (non-operator) get no SDK built-ins at all — Bash/Read/
+  // Guest turns (non-operator sender) get no SDK built-ins at all — Bash/Read/
   // Write/Skill live outside the hub, so the hub's guest scope can't hide
   // them — and only the plugin servers the guest scope allows.
-  const guest = isGuestChat(chatId);
+  const guest = isGuestTurn(chatId);
   const builtinTools = guest
     ? []
     : config.nativeTools

package/src/backend/codex/factory.ts

@@ -42,6 +42,9 @@ import {
 const codexFactory: BackendFactory = {
   id: "codex",
   label: "Codex",
+  // Its own shell/file tools can't be withheld per turn, so guest-scoped
+  // turns (non-operator senders) are refused rather than run with them.
+  guestToolScope: "refused",
   doctor: (config) => codexDoctorChecks(config),
 
   async init(config, ctx) {

package/src/backend/codex/init.ts

@@ -30,6 +30,7 @@ import { getState } from "./state.js";
 import { asCodexConfig, buildCodexMcpServers } from "./mcp-config.js";
 import { detectCodexAuth, type CodexAuthInfo } from "./auth.js";
 import { startDiscovery } from "./discovery.js";
+import { gatewayToken } from "../../core/engine/gateway-auth.js";
 import {
   computeAuthFingerprint,
   loadOAuthIncompatStore,
@@ -199,6 +200,9 @@ export function ensureCodex(chatId: string): Codex {
   const codexPathOverride =
     process.env.TALON_CODEX_BINARY || state.config.codexBinary || undefined;
 
+  // Export TALON_GATEWAY_TOKEN before snapshotting the env: the MCP entries
+  // name it via `bearer_token_env_var`.
+  gatewayToken();
   const codex = new Codex({
     apiKey,
     baseUrl,

package/src/backend/codex/mcp-config.ts

@@ -30,6 +30,7 @@ import {
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
 import type { ToolExclusionConfig } from "../../core/tools/mcp-env.js";
+import { GATEWAY_TOKEN_ENV } from "../../core/engine/gateway-auth.js";
 import { frontendsForChat } from "../runtime/frontends.js";
 
 /**
@@ -69,6 +70,12 @@ export interface CodexMcpServer {
    * Serialised as `default_tools_approval_mode` in the TOML config.
    */
   default_tools_approval_mode?: CodexToolApprovalMode;
+  /**
+   * Env var holding the hub's bearer token. Codex reads the value from its
+   * own environment (inherited from the daemon), so the token never lands
+   * in the `--config` flags on its command line.
+   */
+  bearer_token_env_var: string;
 }
 
 /**
@@ -140,6 +147,7 @@ export function buildCodexMcpServers(args: {
     servers[`${frontend}-tools`] = {
       url: talonHubUrl(bridgeUrl, frontend, chatId),
       default_tools_approval_mode: TALON_MCP_DEFAULT_APPROVAL,
+      bearer_token_env_var: GATEWAY_TOKEN_ENV,
     };
   }
 
@@ -149,6 +157,7 @@ export function buildCodexMcpServers(args: {
     servers["brave-search"] = {
       url: pluginHubUrl(bridgeUrl, "brave-search", chatId),
       default_tools_approval_mode: TALON_MCP_DEFAULT_APPROVAL,
+      bearer_token_env_var: GATEWAY_TOKEN_ENV,
     };
   }
 
@@ -157,6 +166,7 @@ export function buildCodexMcpServers(args: {
     servers[name] = {
       url: pluginHubUrl(bridgeUrl, name, chatId),
       default_tools_approval_mode: TALON_MCP_DEFAULT_APPROVAL,
+      bearer_token_env_var: GATEWAY_TOKEN_ENV,
     };
   }
 

package/src/backend/codex/oauth-incompat.ts

@@ -39,7 +39,7 @@
  * Keyed by auth fingerprint
  * ─────────────────────────
  *
- * If Dylan switches OAuth accounts (e.g. work vs personal) the cache
+ * If Ada switches OAuth accounts (e.g. work vs personal) the cache
  * file at `~/.codex/auth.json` changes, and what we learned about
  * account A doesn't necessarily apply to account B. To stay correct
  * across credential changes we tag the store with a fingerprint of the

package/src/backend/codex/token-usage.ts

@@ -71,7 +71,7 @@ interface CodexTokenTotals {
  *       "rate_limit_reached_type": null
  *     }
  *
- *   Exhausted (the silent-exit case on Dylan's free ChatGPT OAuth):
+ *   Exhausted (the silent-exit case on Ada's free ChatGPT OAuth):
  *     {
  *       "limit_id": "premium",
  *       "primary": null,
@@ -242,7 +242,7 @@ export async function readLastTokenCount(
  * Returns `null` only when the file can't be found or no `token_count`
  * event exists in it. Returns `{ usage: undefined, rateLimits: {...} }`
  * when a usage-exhausted turn writes a `token_count` event with
- * `info: null` but populated rate_limits (the literal shape on Dylan's
+ * `info: null` but populated rate_limits (the literal shape on Ada's
  * exhausted OAuth account, 2026-05-21).
  */
 export async function readLastRolloutSnapshot(

package/src/backend/openai-agents/factory.ts

@@ -40,6 +40,9 @@ import {
 const openAIAgentsFactory: BackendFactory = {
   id: "openai-agents",
   label: "OpenAI Agents",
+  // Its own shell/file tools can't be withheld per turn, so guest-scoped
+  // turns (non-operator senders) are refused rather than run with them.
+  guestToolScope: "refused",
   doctor: (config) => openAIAgentsDoctorChecks(config),
 
   async init(config, ctx) {

package/src/backend/openai-agents/mcp-pool.ts

@@ -25,6 +25,7 @@
 
 import { connectMcpServers, MCPServerStreamableHttp } from "@openai/agents";
 import type { MCPServer } from "@openai/agents";
+import { gatewayAuthHeaders } from "../../core/engine/gateway-auth.js";
 import {
   talonHubUrl,
   pluginHubUrl,
@@ -185,6 +186,7 @@ async function buildBundle(args: BundleInputs): Promise<OpenAIAgentsMcpBundle> {
         name: `${frontend}-tools`,
         url: talonHubUrl(bridgeUrl, frontend, chatId),
         cacheToolsList: true,
+        requestInit: { headers: gatewayAuthHeaders() },
       }),
     );
   }
@@ -197,6 +199,7 @@ async function buildBundle(args: BundleInputs): Promise<OpenAIAgentsMcpBundle> {
         name: "brave-search",
         url: pluginHubUrl(bridgeUrl, "brave-search", chatId),
         cacheToolsList: true,
+        requestInit: { headers: gatewayAuthHeaders() },
       }),
     );
   }
@@ -208,6 +211,7 @@ async function buildBundle(args: BundleInputs): Promise<OpenAIAgentsMcpBundle> {
         name,
         url: pluginHubUrl(bridgeUrl, name, chatId),
         cacheToolsList: true,
+        requestInit: { headers: gatewayAuthHeaders() },
       }),
     );
   }

package/src/backend/remote-server/factory.ts

@@ -68,6 +68,9 @@ export function createRemoteBackendFactory(
   return {
     id,
     label,
+    // The server's built-in shell/file tools can't be withheld per turn,
+    // so guest-scoped turns (non-operator senders) are refused.
+    guestToolScope: "refused",
     // The SDK ships as an npm dep but only talks to a server it spawns from
     // the CLI of the same name (`cross-spawn` → PATH lookup). A present
     // package with an absent binary fails at the first turn with a bare

package/src/backend/remote-server/mcp.ts

@@ -42,6 +42,7 @@ import {
   describeHubChildExit,
 } from "../../core/mcp-hub/index.js";
 import type { RemoteAgentClient } from "./client.js";
+import { gatewayAuthHeaders } from "../../core/engine/gateway-auth.js";
 import type { RemoteServerState } from "./state.js";
 import { errMsg } from "./state.js";
 import type { TalonConfig } from "../../core/config/index.js";
@@ -222,6 +223,7 @@ export async function ensureChatMcpServer<TClient extends RemoteAgentClient>(
       name: serverName,
       config: {
         type: "remote",
+        headers: gatewayAuthHeaders(),
         // Talon's MCP hub serves the chat's tool set in-process over
         // streamable HTTP — no subprocess on the agent-server side, and
         // the (frontend, chatId) binding travels in the URL instead of
@@ -305,6 +307,7 @@ export async function ensurePluginMcpServers<TClient extends RemoteAgentClient>(
           name: serverName,
           config: {
             type: "remote",
+            headers: gatewayAuthHeaders(),
             // Hub-managed child, shared across sessions and idle-reaped —
             // the agent server holds an HTTP connection, not a subprocess.
             url: pluginHubUrl(bridgeUrl, name, chatId),

package/src/backend/runtime/prompt/prompt-format.ts

@@ -10,7 +10,7 @@
  * doesn't" drift that motivated the shared-framework refactor.
  *
  * Examples:
- *   group:  "[2026-05-15 11:01:23] [Dylan (@dylanneve1)] [msg_id:2485]: actual text"
+ *   group:  "[2026-05-15 11:01:23] [Ada (@ada)] [msg_id:2485]: actual text"
  *   DM:     "[2026-05-15 11:01:23] [msg_id:2485] actual text"
  *   DM (no msg_id): "[2026-05-15 11:01:23] actual text"
  */
@@ -23,10 +23,10 @@ import { formatFullDatetime } from "../../../util/time.js";
 export type PromptFormatInputs = {
   /** Raw user text — passed through verbatim. */
   text: string;
-  /** Display name of the sender (e.g. "Dylan"). */
+  /** Display name of the sender (e.g. "Ada"). */
   senderName: string;
   /**
-   * Platform handle of the sender WITHOUT the leading `@` (e.g. `dylanneve1`).
+   * Platform handle of the sender WITHOUT the leading `@` (e.g. `ada`).
    * Rendered next to the display name in group chats so the model can address
    * or mention someone correctly — display names are not addressable, handles
    * are. Absent for users who have no handle set.

package/src/bootstrap.ts

@@ -139,6 +139,10 @@ export async function bootstrap(
   // trimming + brave key come from config; endpoints mount on the
   // gateway HTTP server).
   const { initHub } = await import("./core/mcp-hub/index.js");
+  const { setNativeToolsEnabled } =
+    await import("./core/engine/gateway-actions/native/index.js");
+  // The native shell/fs actions only answer when the tool set is on.
+  setNativeToolsEnabled(config.nativeTools);
   initHub({
     disabledTools: config.disabledTools,
     disabledToolTags: config.disabledToolTags,
@@ -146,6 +150,10 @@ export async function bootstrap(
     nativeTools: config.nativeTools,
     guestDmScope: config.guestDmScope,
     adminUserId: config.adminUserId,
+    operatorIds: [
+      ...(config.operatorIds ?? []),
+      ...(config.discord?.adminUserIds ?? []).map((id) => `discord:${id}`),
+    ],
   });
 
   initWorkspace(config.workspace);

package/src/cli/commands/backup.ts

@@ -22,7 +22,12 @@
 
 import pc from "picocolors";
 import { createInterface } from "node:readline/promises";
-import { getFrontends, loadConfig } from "../../core/config/index.js";
+import { join } from "node:path";
+import {
+  getFrontends,
+  loadBackupConfig,
+  loadConfig,
+} from "../../core/config/index.js";
 import { findRunningInstance } from "../../core/daemon/discovery.js";
 import {
   collectBackupStatus,
@@ -40,7 +45,9 @@ import {
 } from "../../core/backup/index.js";
 import { resolveBackupSettings } from "../../core/backup/plan.js";
 import { buildSnapshot } from "../../core/backup/snapshot.js";
-import { pruneLocal } from "../../core/backup/store.js";
+import { pruneLocal, reconcileIndex } from "../../core/backup/store.js";
+import { generatePassphraseFile } from "../../core/backup/passphrase.js";
+import { dirs } from "../../util/paths.js";
 import { fetchGateway } from "../daemon-api.js";
 
 const USAGE = `
@@ -50,10 +57,13 @@ const USAGE = `
     ${pc.cyan("list")} [--remote <targetId>]           list snapshots
     ${pc.cyan("show")} <id>                            everything about one snapshot
     ${pc.cyan("pin")} <id>  |  ${pc.cyan("unpin")} <id>          keep past retention, or release
-    ${pc.cyan("restore")} <id> [--from <target>] [--yes]  restore (daemon must be stopped)
+    ${pc.cyan("restore")} <id> [--from <target>] [--yes] [--allow-unauthenticated]
+                                       restore (daemon must be stopped)
+          [--clone]                            …onto a new machine: relocate sessions + plugin paths
     ${pc.cyan("prune")}                                apply the local retention policy
     ${pc.cyan("targets")}                              remote targets and their readiness
     ${pc.cyan("status")}                               schedule, sizes, targets
+    ${pc.cyan("keygen")} [path]                        new passphrase file (mode 600)
 `;
 
 type Flags = { values: string[]; flags: Map<string, string | true> };
@@ -169,6 +179,9 @@ async function backupNow(flags: Flags): Promise<void> {
 
 async function backupList(flags: Flags): Promise<void> {
   const target = flags.flags.get("remote");
+  // The manifests on disk are authoritative: a fresh host with a copied-in
+  // backups/ directory has an empty index until something reconciles it.
+  await reconcileIndex();
   const snapshots = await listSnapshots();
   const filtered =
     typeof target === "string"
@@ -312,10 +325,23 @@ async function backupRestore(id: string, flags: Flags): Promise<void> {
       return;
     }
   }
-  const settings = resolveBackupSettings(loadConfig().backup);
+  // Only the backup block: on a fresh host the real config is inside the
+  // snapshot, and a full load would reject the placeholder one.
+  const settings = resolveBackupSettings(loadBackupConfig());
   const target =
     typeof from === "string" ? await resolveTarget(from) : undefined;
-  const report = await restoreSnapshot({ id, settings, target });
+  if (typeof from === "string" && !target) {
+    process.exitCode = 1;
+    return;
+  }
+  const clone = flags.flags.get("clone") === true;
+  const report = await restoreSnapshot({
+    id,
+    settings,
+    target,
+    allowUnauthenticated: flags.flags.get("allow-unauthenticated") === true,
+    clone,
+  });
   const written = Object.entries(report.written)
     .map(([root, count]) => `${root} (${count})`)
     .join(", ");
@@ -330,6 +356,12 @@ async function backupRestore(id: string, flags: Flags): Promise<void> {
   console.log(
     `  Database: ${report.databaseReplaced ? "replaced" : "left in place"}\n`,
   );
+  if (clone) {
+    console.log(
+      `  Clone: config.json paths ${report.configRewritten ? "rewritten for this machine" : "unchanged"}.\n` +
+        `  Reinstall fetched plugins from ${pc.cyan("~/.talon/plugins-manifest.json")} (docs/backups.md).\n`,
+    );
+  }
 }
 
 /**
@@ -354,6 +386,27 @@ async function resolveTarget(id: string): Promise<BackupTarget | undefined> {
   return target;
 }
 
+/** Write a fresh passphrase file. Prints where, never what. */
+async function backupKeygen(path: string | undefined): Promise<void> {
+  try {
+    const dest = await generatePassphraseFile(
+      path ?? join(dirs.root, "backup.key"),
+    );
+    console.log(
+      `  ${pc.green("●")} Wrote a new backup passphrase to ${pc.bold(dest)} (mode 600).\n` +
+        `    Enable it in config.json:\n` +
+        `      "backup": { "encryption": { "passphraseFile": "${dest}" } }\n` +
+        `    Keep a copy OFF this machine — encrypted snapshots cannot be\n` +
+        `    restored without it.\n`,
+    );
+  } catch (err) {
+    console.log(
+      `  ${pc.red("●")} ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exitCode = 1;
+  }
+}
+
 // ── Entry ───────────────────────────────────────────────────────────────────
 
 export async function runBackupCommand(argv: readonly string[]): Promise<void> {
@@ -386,6 +439,9 @@ export async function runBackupCommand(argv: readonly string[]): Promise<void> {
     case "targets":
       await backupTargets();
       return;
+    case "keygen":
+      await backupKeygen(id);
+      return;
     case "status":
     case undefined:
       await backupStatus();