talon-agent 5.27.0 → 5.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.27.0",
+  "version": "5.29.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -111,7 +111,7 @@
     "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openai/agents": "^0.18.0",
-    "@openai/codex-sdk": "^0.155.0",
+    "@openai/codex-sdk": "^0.156.1",
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.56",
     "@types/cross-spawn": "^6.0.6",

package/src/app.ts

@@ -128,10 +128,18 @@ stampDaemonOwner();
  *
  * Never throws: a failed restore still boots the daemon (with the reason
  * in the log and the request deleted, so the next boot is normal).
+ * Returns the confirmation line and who asked for it, so it can be sent
+ * back to that chat once the frontends are up.
  */
-async function applyStagedRestore(): Promise<string | null> {
+async function applyStagedRestore(): Promise<{
+  text: string;
+  requestedBy?: string;
+  frontend?: string;
+} | null> {
   const { applyPendingRestore, readRestorePending } =
     await import("./core/backup/index.js");
+  const { formatRestoreNotice } =
+    await import("./core/backup/restore/notice.js");
   if (!(await readRestorePending())) return null;
   const { loadConfig } = await import("./core/config/index.js");
   const { resolveBackupSettings } = await import("./core/backup/plan.js");
@@ -141,12 +149,11 @@ async function applyStagedRestore(): Promise<string | null> {
     beforeApply: closeDatabase,
   });
   if (!report) return null;
-  return (
-    `♻️ Restored snapshot ${report.id}` +
-    (report.checkpointId
-      ? ` (previous state saved as checkpoint ${report.checkpointId})`
-      : "")
-  );
+  return {
+    text: formatRestoreNotice(report),
+    requestedBy: report.requestedBy,
+    frontend: report.frontend,
+  };
 }
 
 /**
@@ -546,12 +553,21 @@ async function main(): Promise<void> {
   // Phase 0 accounting (docs/ts-migration-plan.md): the boot is over the
   // moment the frontends are listening, so the totals are folded into the
   // metrics store here, from the same uptime figure the log line prints.
-  // A restore applied at boot happened before any frontend existed, so the
-  // operator hears about it here, on the first channel that can carry it.
+  // A restore applied at boot happened before any frontend existed, so it
+  // is reported here, on the first channels that can carry it: the chat
+  // that asked for it, or the admin's primary chat when that one can't be
+  // reached. Not awaited — delivery may retry while a frontend finishes
+  // connecting, and the boot shouldn't wait on a courtesy message.
   if (restoreReport) {
     const { notifyAdmin } =
       await import("./core/frontend-runtime/admin-notify.js");
-    await notifyAdmin(restoreReport);
+    const { deliverRestoreNotice } =
+      await import("./core/backup/restore/notice.js");
+    void deliverRestoreNotice({
+      text: restoreReport.text,
+      requester: restoreReport,
+      notifyAdmin,
+    });
   }
   // Same reasoning for a crash: the process that died couldn't say so,
   // so the marker it left is announced now. The probes start here too —

package/src/core/agents/runner.ts

@@ -112,7 +112,10 @@ export function initAgents(
     "agents",
     `Initialized — maxConcurrent=${capsHolder.caps.maxConcurrent} ` +
       `maxDepth=${capsHolder.caps.maxDepth} ` +
-      `timeout=${Math.round(capsHolder.caps.defaultTimeoutMs / 1000)}s`,
+      `timeout=${Math.round(capsHolder.caps.defaultTimeoutMs / 1000)}s` +
+      (capsHolder.caps.allowedBackends?.length
+        ? ` allowedBackends=${capsHolder.caps.allowedBackends.join(",")}`
+        : ""),
   );
 }
 
@@ -137,19 +140,37 @@ function inheritedBackendId(parent: AgentParent): string | null {
   return agentRegistry.get(parent.agentId)?.backendId ?? null;
 }
 
+/** Where a spawn lands: backend, the model it inherits, and why. */
+interface SpawnTarget {
+  readonly backendId: string | null;
+  /** The parent agent's model, inherited by an unpinned child. */
+  readonly inheritedModel?: string;
+  readonly routing?: string;
+}
+
 /**
  * Which backend this agent runs on, and why.
  *
  * An explicit backend (or model — a model id is backend-specific, so naming
- * one pins its backend) is honoured as written. With neither, the run is a
- * routing decision: sub-agents are isolated one-shots with no session to
- * keep warm, so they are the cheapest work to move onto whichever
- * subscription has room.
+ * one pins its backend) is honoured as written. A child of another agent
+ * with neither inherits its parent's backend *and* model: a tree of agents
+ * stays on the backend its root was put on, so a parent that chose (or was
+ * told to use) a backend does not see its children wander off to another
+ * subscription. A top-level spawn with neither is a routing decision:
+ * sub-agents are isolated one-shots with no session to keep warm, so they
+ * are the cheapest work to move onto whichever subscription has room.
  */
-async function resolveSpawnBackend(
-  spec: AgentSpawnSpec,
-): Promise<{ backendId: string | null; routing?: string }> {
+async function resolveSpawnBackend(spec: AgentSpawnSpec): Promise<SpawnTarget> {
   if (spec.backendId) return { backendId: spec.backendId };
+  if (spec.parent.kind === "agent" && !spec.model) {
+    const parent = agentRegistry.get(spec.parent.agentId);
+    if (parent) {
+      return {
+        backendId: parent.backendId,
+        ...(parent.model ? { inheritedModel: parent.model } : {}),
+      };
+    }
+  }
   const inherited = inheritedBackendId(spec.parent);
   if (!inherited) return { backendId: null };
   const taskClass = taskClassForEffort(spec.reasoningEffort);
@@ -166,12 +187,37 @@ async function resolveSpawnBackend(
         }
       : {}),
   });
+  // A routed pick outside the allowlist falls back to the inherited
+  // backend rather than refusing a spawn the caller never pinned.
+  if (
+    decision.routed &&
+    !isBackendAllowed(decision.backendId) &&
+    isBackendAllowed(inherited)
+  ) {
+    return { backendId: inherited };
+  }
   return {
     backendId: decision.backendId,
     ...(decision.routed ? { routing: decision.reason } : {}),
   };
 }
 
+/** Whether `agents.allowedBackends` (when set) lets an agent run here. */
+function isBackendAllowed(backendId: string): boolean {
+  const allowed = capsHolder.caps.allowedBackends;
+  return !allowed || allowed.length === 0 || allowed.includes(backendId);
+}
+
+/** The tool error for a backend outside `agents.allowedBackends`. */
+function disallowedBackendError(backendId: string): string {
+  const allowed = capsHolder.caps.allowedBackends ?? [];
+  return (
+    `Backend "${backendId}" is not allowed for sub-agents ` +
+    `(agents.allowedBackends: ${allowed.join(", ")}). Pass one of those ` +
+    `as backend, or leave it unset to inherit.`
+  );
+}
+
 /** The chat a run's task belongs to, for `talon ps`. */
 function taskChatId(parent: AgentParent): string | undefined {
   if (parent.kind === "chat") return parent.chatId;
@@ -262,6 +308,10 @@ export async function spawnAgent(
         "Could not resolve a backend for this agent — pass one explicitly.",
     };
   }
+  if (!isBackendAllowed(backendId)) {
+    return { ok: false, error: disallowedBackendError(backendId) };
+  }
+  const model = spec.model ?? routed.inheritedModel;
 
   // Register first: the slot and the depth are claimed synchronously, so two
   // concurrent spawns can never both slip past maxConcurrent while awaiting
@@ -296,7 +346,7 @@ export async function spawnAgent(
     };
   }
 
-  const resolved = await resolveRun(acquired.backend, backendId, spec.model);
+  const resolved = await resolveRun(acquired.backend, backendId, model);
   if (!resolved.ok) {
     agentRegistry.discard(record.id);
     await acquired.release();

package/src/core/agents/types.ts

@@ -94,9 +94,16 @@ export interface AgentSpawnSpec {
   readonly brief: string;
   readonly label: string;
   readonly parent: AgentParent;
-  /** Defaults to the parent's backend. */
+  /**
+   * Unset: a child of another agent inherits its parent's backend (and,
+   * with no model either, its model); a top-level spawn starts from the
+   * chat's backend and may be routed.
+   */
   readonly backendId?: string;
-  /** Defaults to the resolved backend's own default model. */
+  /**
+   * Defaults to the parent agent's model when the backend is inherited from
+   * one, else the resolved backend's own default model.
+   */
   readonly model?: string;
   readonly reasoningEffort?: ReasoningEffortLevel;
   /** Hard wall-clock cap. Defaults to `agents.defaultTimeoutMs`. */
@@ -132,4 +139,9 @@ export interface AgentCaps {
   readonly maxDepth: number;
   /** Default hard timeout for one run. */
   readonly defaultTimeoutMs: number;
+  /**
+   * Backends a sub-agent may run on. Unset or empty = any backend with a
+   * background capability. Enforced by `spawnAgent` on the final choice.
+   */
+  readonly allowedBackends?: readonly string[];
 }

package/src/core/backup/{restore-guard.ts → restore/guard.ts}

@@ -22,11 +22,11 @@
  */
 
 import { chmod } from "node:fs/promises";
-import { logWarn } from "../../util/log.js";
-import { TalonError } from "../errors.js";
-import { verifyManifest } from "./archive/manifest-auth.js";
-import { resolvePassphrase } from "./passphrase.js";
-import type { BackupSettings, Manifest } from "./types.js";
+import { logWarn } from "../../../util/log.js";
+import { TalonError } from "../../errors.js";
+import { verifyManifest } from "../archive/manifest-auth.js";
+import { resolvePassphrase } from "../passphrase.js";
+import type { BackupSettings, Manifest } from "../types.js";
 
 export type ManifestTrust = {
   /** Operator override for unauthenticated manifests. */

package/src/core/backup/restore/notice.ts

@@ -0,0 +1,164 @@
+/**
+ * Reporting a staged restore back to the chat that asked for it.
+ *
+ * `/backup restore <id>` stages the request and restarts; the restore runs
+ * in the next boot before any frontend exists (see `applyStagedRestore` in
+ * app.ts). Once the frontends are up, the "♻️ Restored snapshot …" line is
+ * delivered here: to the requesting chat, on the frontend it came from,
+ * and — when that chat can't be reached (frontend disabled, delivery
+ * failing) or the request never said who asked — to the operator's
+ * primary chat through the admin notifier, which is where it always went
+ * before.
+ *
+ * Core never imports src/frontend, so delivery goes through the same
+ * cross-send broker `send_via` uses: each enabled frontend's action
+ * handler, keyed by frontend name.
+ */
+
+import { log, logWarn } from "../../../util/log.js";
+import {
+  isNativeChatId,
+  isTelegramChatId,
+  numericChatIdFor,
+} from "../../frontend-runtime/chat-id.js";
+import { crossSendTarget } from "../../engine/gateway-actions/cross-send.js";
+import type { RestoreReport } from "../restore.js";
+
+/** Who asked for a staged restore, as recorded in restore-pending.json. */
+export type RestoreRequester = {
+  /** The requesting chat's key (Telegram id, `d_…`, `discord_…`). */
+  requestedBy?: string;
+  /** The frontend the request came from. Absent in files staged before it existed. */
+  frontend?: string;
+};
+
+/**
+ * The frontend a requester belongs to: the recorded one when the request
+ * carries it, else inferred from the shape of the chat key — Telegram's
+ * ids are numeric, native's start `d_`, Discord's `discord_`. Undefined
+ * when neither says.
+ */
+export function requesterFrontend(
+  requester: RestoreRequester,
+): string | undefined {
+  const explicit =
+    typeof requester.frontend === "string"
+      ? requester.frontend.trim().toLowerCase()
+      : "";
+  if (explicit) return explicit;
+  const key =
+    typeof requester.requestedBy === "string" ? requester.requestedBy : "";
+  if (!key) return undefined;
+  if (isTelegramChatId(key)) return "telegram";
+  if (isNativeChatId(key)) return "native";
+  if (key.startsWith("discord_")) return "discord";
+  return undefined;
+}
+
+/** The confirmation line a successful staged restore reports. */
+export function formatRestoreNotice(
+  report: Pick<RestoreReport, "id" | "checkpointId">,
+): string {
+  return (
+    `♻️ Restored snapshot ${report.id}` +
+    (report.checkpointId
+      ? ` (previous state saved as checkpoint ${report.checkpointId})`
+      : "")
+  );
+}
+
+/**
+ * Send `text` to one chat through its frontend's registered action
+ * handler. The chat key rides in `target` so a frontend that has not
+ * seen the chat since the restart (a Discord channel nobody has spoken
+ * in yet, a native chat the restored database doesn't list) can adopt it.
+ * Resolves true only when the frontend reports the message delivered.
+ */
+async function sendToRequester(
+  frontend: string,
+  chatKey: string,
+  text: string,
+): Promise<boolean> {
+  const handler = crossSendTarget(frontend);
+  if (!handler) return false;
+  const result = await handler(
+    { action: "send_message", text, target: chatKey },
+    numericChatIdFor(chatKey),
+  );
+  return Boolean(result && result.ok === true);
+}
+
+const RESTORE_NOTICE_ATTEMPTS = 6;
+const RESTORE_NOTICE_DELAY_MS = 5_000;
+
+export type RestoreNoticeOptions = {
+  text: string;
+  requester: RestoreRequester;
+  /** The operator's primary chat — the fallback. */
+  notifyAdmin: (text: string) => Promise<unknown>;
+  send?: (frontend: string, chatKey: string, text: string) => Promise<boolean>;
+  /** Whether a frontend is enabled at all (no point retrying one that isn't). */
+  isEnabled?: (frontend: string) => boolean;
+  attempts?: number;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+/**
+ * Deliver the restore notice to the requesting chat, falling back to the
+ * admin's primary chat. Retries a while when the requester's frontend is
+ * enabled but can't deliver yet — the frontends have just started, and a
+ * Discord client may still be logging in. Never throws; resolves with
+ * where the notice went.
+ */
+export async function deliverRestoreNotice(
+  options: RestoreNoticeOptions,
+): Promise<"requester" | "admin"> {
+  const {
+    text,
+    requester,
+    notifyAdmin,
+    send = sendToRequester,
+    isEnabled = (name) => crossSendTarget(name) !== undefined,
+    attempts = RESTORE_NOTICE_ATTEMPTS,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref?.()),
+  } = options;
+  const frontend = requesterFrontend(requester);
+  const chatKey =
+    typeof requester.requestedBy === "string" ? requester.requestedBy : "";
+
+  if (frontend && chatKey && isEnabled(frontend)) {
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        if (await send(frontend, chatKey, text)) {
+          log("backup", `Restore reported to ${frontend} chat ${chatKey}`);
+          return "requester";
+        }
+      } catch (err) {
+        logWarn(
+          "backup",
+          `Restore report to ${frontend} chat ${chatKey} failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (attempt < attempts) await sleep(RESTORE_NOTICE_DELAY_MS);
+    }
+    logWarn(
+      "backup",
+      `Could not reach ${frontend} chat ${chatKey}; reporting the restore to the admin chat instead`,
+    );
+  } else if (chatKey || frontend) {
+    logWarn(
+      "backup",
+      `Restore requester ${frontend ?? "?"}:${chatKey || "?"} is not reachable here; reporting to the admin chat`,
+    );
+  }
+
+  try {
+    await notifyAdmin(text);
+  } catch (err) {
+    logWarn(
+      "backup",
+      `Admin restore report failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return "admin";
+}

package/src/core/backup/restore.ts

@@ -4,7 +4,7 @@
  * The rules that make this safe to run on a live home directory:
  *
  *   1. Verify before you touch anything. The manifest's signature is
- *      checked (restore-guard.ts), then every part's sha256 and — for
+ *      checked (restore/guard.ts), then every part's sha256 and — for
  *      encrypted parts — every record's tag; a part that fails is a
  *      stopped restore, not a half-applied one.
  *   2. Stage, then swap. The archive is extracted into a staging
@@ -55,7 +55,7 @@ import {
   authenticateManifest,
   makePrivate,
   type ManifestTrust,
-} from "./restore-guard.js";
+} from "./restore/guard.js";
 import { buildSnapshot } from "./snapshot.js";
 import {
   relocateRoot,
@@ -84,6 +84,12 @@ export type RestorePending = {
   requestedAt: number;
   /** Chat key that asked, so the boot can report back. */
   requestedBy?: string;
+  /**
+   * Frontend the request came from ("telegram", "discord", "native"), so
+   * the report goes back the way it came. Absent in files staged before
+   * it was recorded — the boot then infers it from `requestedBy`.
+   */
+  frontend?: string;
 };
 
 export type RestoreReport = {
@@ -507,7 +513,7 @@ export type RestoreOptions = {
   beforeApply?: () => void | Promise<void>;
   /** Skip the automatic pre-restore checkpoint (it has already been taken). */
   skipCheckpoint?: boolean;
-  /** Restore a manifest that carries no signature (see restore-guard.ts). */
+  /** Restore a manifest that carries no signature (see restore/guard.ts). */
   allowUnauthenticated?: ManifestTrust["allowUnauthenticated"];
   /**
    * Restoring onto a different machine: relocate the session stores and
@@ -641,7 +647,9 @@ export async function applyPendingRestore(options: {
   settings: BackupSettings;
   home?: string;
   beforeApply?: () => void | Promise<void>;
-}): Promise<(RestoreReport & { requestedBy?: string }) | null> {
+}): Promise<
+  (RestoreReport & { requestedBy?: string; frontend?: string }) | null
+> {
   const home = options.home ?? dirs.root;
   const pending = await readRestorePending(home);
   if (!pending) return null;
@@ -654,7 +662,11 @@ export async function applyPendingRestore(options: {
       beforeApply: options.beforeApply,
     });
     await clearRestorePending(home);
-    return { ...report, requestedBy: pending.requestedBy };
+    return {
+      ...report,
+      requestedBy: pending.requestedBy,
+      frontend: pending.frontend,
+    };
   } catch (err) {
     logWarn("backup", `Staged restore of ${pending.id} failed: ${String(err)}`);
     await clearRestorePending(home);

package/src/core/config/index.ts

@@ -643,6 +643,9 @@ const configSchema = z.object({
    *     default) = chat → agent → agent.
    *   - `defaultTimeoutMs` — hard wall-clock cap when a spawn doesn't pass
    *     its own. Per-spawn values are clamped to [30s, 60min].
+   *   - `allowedBackends` — optional allowlist of backend ids sub-agents
+   *     may run on. Unset = any backend with a background capability. A
+   *     spawn that names (or inherits) a backend outside it is refused.
    */
   agents: z
     .object({
@@ -654,6 +657,7 @@ const configSchema = z.object({
         .min(30_000)
         .max(3_600_000)
         .default(15 * 60 * 1000),
+      allowedBackends: z.array(z.string().min(1)).optional(),
     })
     .optional(),
   /**

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

@@ -23,7 +23,7 @@ import { resolve } from "node:path";
 import { dirs } from "../../../util/paths.js";
 import { log, logWarn } from "../../../util/log.js";
 import { TalonError } from "../../errors.js";
-import { readArray, writePrivateJson } from "../persist.js";
+import { readArray, writePrivateJson, writesSettled } from "../persist.js";
 import { faultText } from "../../engine/fault-text.js";
 import { raiseAlert, resolveAlert } from "../../frontend-runtime/alerts.js";
 import {
@@ -506,6 +506,14 @@ export class DeviceCredentialStore {
     }
   }
 
+  /**
+   * Wait for every background write queued so far (mintNow, bind, re-pair
+   * revocation, lastUsedAt touches) to reach disk or fail.
+   */
+  flush(): Promise<void> {
+    return writesSettled(this.file);
+  }
+
   private persistSoon(): void {
     void this.persist().catch((err: unknown) =>
       logWarn("mesh", `Could not persist mesh credentials: ${err}`),

package/src/core/mesh/persist.ts

@@ -25,6 +25,15 @@ export async function readArray<T>(path: string): Promise<T[]> {
   }
 }
 
+/**
+ * Resolve once every write queued for `path` so far has finished (settled,
+ * success or failure) — for callers that persisted fire-and-forget and now
+ * need the file on disk.
+ */
+export function writesSettled(path: string): Promise<void> {
+  return writeQueues.get(path) ?? Promise.resolve();
+}
+
 /** Persist JSON atomically with 0600 perms, serialized per path. */
 export async function writePrivateJson(
   path: string,

package/src/core/tools/ops/agents.ts

@@ -35,8 +35,8 @@ Bad uses: anything needing a back-and-forth with the user, trivial work you
 could do in one tool call, or work whose result you need in the next second
 (spawning costs a model cold-start).
 
-Backend and model default to this chat's; pass them to put the agent
-somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
+Backend and model default to the caller's (a sub-agent's own children
+inherit its backend and model); pass them to put the agent somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
 a bigger context window). Returns the agent id immediately.`;
 
 export const agentTools: ToolDefinition[] = [
@@ -61,13 +61,13 @@ export const agentTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe(
-          "Backend id to run on. Unset = this chat's backend (agents inherit their parent's). Must have a background capability.",
+          "Backend id to run on. Unset = inherit: an agent's children run on its own backend and model; a chat's spawns start from the chat's backend (and may be routed to one with more headroom). Must have a background capability and, when the deployment sets agents.allowedBackends, be on that list.",
         ),
       model: z
         .string()
         .optional()
         .describe(
-          "Model id on the chosen backend. Unset = that backend's default model. Call list_models for valid ids.",
+          "Model id on the chosen backend. Unset = the parent agent's model when the backend is inherited from one, else that backend's default model. Call list_models for valid ids.",
         ),
       effort: z
         .enum(["minimal", "low", "medium", "high", "xhigh"])

package/src/frontend/discord/actions/channels.ts

@@ -14,9 +14,12 @@ export async function resolveChannel(
   const info = lookupDiscordChat(numericChatId);
   if (!info) return null;
   try {
-    const ch = await client.channels.fetch(info.channelId);
-    if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
-      return ch as TextBasedChannel;
+    // A DM rebuilt from its chat key has no channel id — open it by user.
+    if (info.channelId) {
+      const ch = await client.channels.fetch(info.channelId);
+      if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
+        return ch as TextBasedChannel;
+      }
     }
     if (info.userId) {
       const user = await client.users.fetch(info.userId);

package/src/frontend/discord/actions/index.ts

@@ -24,6 +24,11 @@ import type { Client } from "discord.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { ActionResult } from "../../../core/types.js";
 import { resolveChannel } from "./channels.js";
+import {
+  lookupDiscordChat,
+  parseDiscordChatKey,
+  registerDiscordChat,
+} from "../handlers/registry.js";
 import { messagingHandlers, restoreScheduledMessages } from "./messaging.js";
 import { mediaHandlers } from "./media.js";
 import { chatInfoHandlers } from "./chat-info.js";
@@ -43,6 +48,24 @@ const handlers: DiscordActionHandlers = Object.assign(Object.create(null), {
   ...chatInfoHandlers,
 });
 
+/**
+ * A plain send addressed to a chat this process hasn't registered — the
+ * channel that asked for a staged restore, say, before anyone has spoken
+ * in it since the restart. The sender names the chat by key in
+ * `body.target`; when that key is the one the numeric id was derived
+ * from, register it so the channel resolves. send_message only.
+ */
+function adoptAddressedChat(
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): void {
+  if (action !== "send_message" || lookupDiscordChat(chatId)) return;
+  const key = typeof body.target === "string" ? body.target : "";
+  const info = key ? parseDiscordChatKey(key) : undefined;
+  if (info && info.numericChatId === chatId) registerDiscordChat(info);
+}
+
 export function createDiscordActionHandler(client: Client, gateway: Gateway) {
   const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
 
@@ -58,6 +81,7 @@ export function createDiscordActionHandler(client: Client, gateway: Gateway) {
     const handler = handlers[action];
     if (!handler) return null; // not a Discord action
 
+    adoptAddressedChat(action, body, chatId);
     const channel = await resolveChannel(client, chatId);
 
     // For non-channel actions (e.g. cancel_scheduled) that don't need a

package/src/frontend/discord/commands/backup.ts

@@ -180,6 +180,7 @@ export async function handleBackupComponent(
       id,
       requestedAt: Date.now(),
       requestedBy: chatId,
+      frontend: "discord",
     });
     respawnSelf(`discord /backup restore ${id}`);
   } catch (err) {

package/src/frontend/discord/handlers/messages.ts

@@ -66,15 +66,17 @@ export async function handleMessage(
   if (msg.attachments.size > 0) {
     for (const att of msg.attachments.values()) {
       try {
-        const savedPath = await downloadAttachment(att, config.workspace);
+        const downloadedPath = await downloadAttachment(att, config.workspace);
         const cls = classifyAttachment(att);
-        setMessageFilePath(chatId, numericMessageId, savedPath);
-        addMedia({
+        setMessageFilePath(chatId, numericMessageId, downloadedPath);
+        // addMedia may dedupe onto an existing identical file and delete
+        // the fresh download — prompt with the path it resolves to.
+        const savedPath = await addMedia({
           chatId,
           msgId: numericMessageId,
           senderName: sender,
           type: cls.type,
-          filePath: savedPath,
+          filePath: downloadedPath,
           caption: cleanedContent || undefined,
           timestamp: Date.now(),
         });

package/src/frontend/discord/handlers/registry.ts

@@ -3,6 +3,7 @@
  * Discord channel info the action handler needs to post back.
  */
 
+import { deriveNumericChatId } from "../../../core/frontend-runtime/chat-id.js";
 import {
   chatRegistry,
   chatRegistryByString,
@@ -21,3 +22,37 @@ export function lookupDiscordChat(
 ): DiscordChatInfo | undefined {
   return chatRegistry.get(numericChatId);
 }
+
+/**
+ * Rebuild a chat's registry entry from its string key alone
+ * (`discord_guild_<guild>_<channel>` or `discord_dm_<user>`), for a chat
+ * this process hasn't seen a message from yet — the registry is in-memory,
+ * so after a restart only the allowed users' DMs are known until someone
+ * speaks. A DM entry carries no channel id; resolveChannel opens the DM
+ * from the user id. Undefined for anything that isn't a Discord chat key.
+ */
+export function parseDiscordChatKey(
+  chatKey: string,
+): DiscordChatInfo | undefined {
+  const guild = /^discord_guild_(\d+)_(\d+)$/.exec(chatKey);
+  if (guild) {
+    return {
+      channelId: guild[2]!,
+      guildId: guild[1]!,
+      userId: null,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  const dm = /^discord_dm_(\d+)$/.exec(chatKey);
+  if (dm) {
+    return {
+      channelId: "",
+      guildId: null,
+      userId: dm[1]!,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  return undefined;
+}

package/src/frontend/native/commands/backup.ts

@@ -145,6 +145,7 @@ async function restore(
       id,
       requestedAt: Date.now(),
       requestedBy: ctx.entry.id,
+      frontend: "native",
     });
   } catch (err) {
     logError("backup", "Staging the restore failed", err);

package/src/frontend/native/turn/actions.ts

@@ -15,6 +15,10 @@ import type {
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { NativeChats, ChatEntry } from "../chats/chats.js";
 import type { BridgeEvent, ClientButton } from "../protocol.js";
+import {
+  deriveNumericChatId,
+  isNativeChatId,
+} from "../../../core/frontend-runtime/chat-id.js";
 
 export type NativeActionDeps = {
   chats: NativeChats;
@@ -69,6 +73,28 @@ const NATIVE_ACTIONS = new Set([
   "send_chat_action",
 ]);
 
+/**
+ * A plain send addressed to a native chat this daemon doesn't list — the
+ * chat that asked for a staged restore, say, when the restored database
+ * predates it. The sender names the chat by key in `body.target`; the
+ * chat is adopted (as a deep link would) so the message lands in its
+ * history and the app shows it. Only when the key really is the chat the
+ * numeric id was derived from, and only for send_message: edits,
+ * reactions and deletes address messages, which an unknown chat has none of.
+ */
+function adoptAddressedChat(
+  chats: NativeChats,
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): ChatEntry | undefined {
+  if (action !== "send_message") return undefined;
+  const key = typeof body.target === "string" ? body.target : "";
+  if (!key || !isNativeChatId(key) || deriveNumericChatId(key) !== chatId)
+    return undefined;
+  return chats.ensure(key);
+}
+
 export function createNativeActionHandler(
   deps: NativeActionDeps,
 ): FrontendActionHandler {
@@ -77,7 +103,9 @@ export function createNativeActionHandler(
   return async (body, chatId): Promise<ActionResult | null> => {
     const action = typeof body.action === "string" ? body.action : "";
     if (!NATIVE_ACTIONS.has(action)) return null;
-    const entry = chats.byNumeric(chatId);
+    const entry =
+      chats.byNumeric(chatId) ??
+      adoptAddressedChat(chats, action, body, chatId);
     if (!entry) return { ok: false, error: "No active native chat" };
 
     switch (action) {

package/src/frontend/telegram/actions/chat-info.ts

@@ -21,6 +21,7 @@ import {
   getPinnedMessages as userbotPinnedMessages,
   getOnlineCount as userbotOnlineCount,
 } from "../userbot.js";
+import { getMediaForMessage } from "../../../storage/media-index.js";
 import { savePackToLibrary } from "../sticker-library.js";
 import { toPositiveId } from "./coerce.js";
 import type { TelegramActionHandlers } from "./types.js";
@@ -308,16 +309,32 @@ export const chatInfoHandlers: TelegramActionHandlers = {
   },
 
   download_media: async (body, chatId) => {
+    const msgId = toPositiveId(body.message_id);
+    if (!msgId) return { ok: false, error: "Required: message_id" };
+    // Media the bot received is already on disk and indexed. Answer from
+    // the index first: the userbot can't see messages in the bot's own
+    // DMs (message ids there are per-account), so asking it for an
+    // inbound photo by id reports "not found".
+    const indexed = getMediaForMessage(String(chatId), msgId);
+    if (indexed && existsSync(indexed.filePath)) {
+      return {
+        ok: true,
+        text: `Saved at: ${indexed.filePath} (${indexed.type}). Use the Read tool on this path to view the content.`,
+        file_path: indexed.filePath,
+      };
+    }
     if (isUserClientReady()) {
       const { downloadMessageMedia } = await import("../userbot.js");
       return {
         ok: true,
-        text: await downloadMessageMedia({
-          chatId,
-          messageId: Number(body.message_id),
-        }),
+        text: await downloadMessageMedia({ chatId, messageId: msgId }),
       };
     }
-    return { ok: false, error: "User client not connected." };
+    return {
+      ok: false,
+      error: indexed
+        ? `Media for message ${msgId} is no longer on disk and the user client is not connected to re-download it.`
+        : "User client not connected.",
+    };
   },
 };

package/src/frontend/telegram/commands/backup.ts

@@ -166,6 +166,7 @@ export async function stageRestore(chatId: string, id: string): Promise<void> {
     id,
     requestedAt: Date.now(),
     requestedBy: chatId,
+    frontend: "telegram",
   });
   respawnSelf(`telegram /backup restore ${id}`);
 }

package/src/frontend/telegram/handlers/messages.ts

@@ -72,16 +72,18 @@ async function handleMediaMessage(
       return;
     }
 
-    const savedPath = await downloadTelegramFile(
+    const downloadedPath = await downloadTelegramFile(
       bot,
       config,
       media.fileId,
       media.fileName,
     );
 
-    // Store file path in history + media index
-    setMessageFilePath(chatId, ctx.message.message_id, savedPath);
-    addMedia({
+    // Store file path in history + media index. addMedia may dedupe the
+    // download onto an identical file already on disk (and delete the
+    // fresh one), so the prompt must use the path it resolves to.
+    setMessageFilePath(chatId, ctx.message.message_id, downloadedPath);
+    const savedPath = await addMedia({
       chatId,
       msgId: ctx.message.message_id,
       senderName: sender,
@@ -93,7 +95,7 @@ async function handleMediaMessage(
         | "animation"
         | "audio"
         | "sticker",
-      filePath: savedPath,
+      filePath: downloadedPath,
       caption: media.caption,
       timestamp: Date.now(),
     });

package/src/frontend/whatsapp/messages/media-store.ts

@@ -96,7 +96,9 @@ export async function saveInboundMedia(
     writeFileSync(filePath, buffer);
 
     const caption = content?.caption ?? undefined;
-    addMedia({
+    // addMedia may dedupe onto an existing identical file and delete
+    // this download — report the path it resolves to.
+    const savedPath = await addMedia({
       chatId,
       msgId,
       senderName,
@@ -105,7 +107,7 @@ export async function saveInboundMedia(
       timestamp: Date.now(),
       ...(caption ? { caption } : {}),
     });
-    return { filePath, type, ...(caption ? { caption } : {}) };
+    return { filePath: savedPath, type, ...(caption ? { caption } : {}) };
   } catch (err) {
     logWarn(
       "whatsapp",

package/src/storage/media-index.ts

@@ -73,7 +73,19 @@ function importLegacyMediaIndex(): void {
 
 // ── CRUD ────────────────────────────────────────────────────────────────────
 
-export function addMedia(entry: Omit<MediaEntry, "id">): void {
+/**
+ * Index a downloaded file and dedupe it against identical content.
+ *
+ * Resolves to the path the message's media now lives at — the
+ * canonical copy when the download duplicated one already on disk
+ * (the fresh file is then deleted), otherwise `entry.filePath`.
+ * Callers MUST use the resolved path for anything they show the
+ * model: the original path may no longer exist once this settles.
+ *
+ * The row is written synchronously, so it is queryable before the
+ * hash finishes.
+ */
+export async function addMedia(entry: Omit<MediaEntry, "id">): Promise<string> {
   try {
     repo.upsert(entry);
   } catch (err) {
@@ -85,13 +97,32 @@ export function addMedia(entry: Omit<MediaEntry, "id">): void {
     recordError(
       `Media index write failed: ${err instanceof Error ? err.message : err}`,
     );
-    return;
+    return entry.filePath;
   }
-  // Hash + dedupe off the hot path — the caller is mid-message-handling
-  // and the row is already queryable without the hash.
-  void hashAndDedupe(entry).catch((err) =>
-    logError("media", `Media content hash failed for ${entry.filePath}`, err),
+  // Serialize dedupe: two identical files hashed concurrently (e.g. an
+  // album) could otherwise each pick the other as canonical and both
+  // get unlinked.
+  const run = dedupeChain.then(() => hashAndDedupe(entry));
+  dedupeChain = run.then(
+    () => undefined,
+    () => undefined,
   );
+  try {
+    return await run;
+  } catch (err) {
+    logError("media", `Media content hash failed for ${entry.filePath}`, err);
+    return entry.filePath;
+  }
+}
+
+let dedupeChain: Promise<void> = Promise.resolve();
+
+/** The indexed entry for a message, if any. */
+export function getMediaForMessage(
+  chatId: string,
+  msgId: number,
+): MediaEntry | undefined {
+  return repo.byMessage(chatId, msgId);
 }
 
 /**
@@ -101,15 +132,15 @@ export function addMedia(entry: Omit<MediaEntry, "id">): void {
  * canonical copy and drop the duplicate file, so re-posted media costs
  * one copy on disk no matter how many messages carry it.
  */
-async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<void> {
-  if (!existsSync(entry.filePath)) return; // gone already (expiry, tests)
+async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<string> {
+  if (!existsSync(entry.filePath)) return entry.filePath; // gone already (expiry, tests)
   const hash = await blake3HexFile(entry.filePath);
   repo.setContentHash(entry.chatId, entry.msgId, hash);
 
   const canonical = repo.firstByContentHash(hash, entry.chatId, entry.msgId);
-  if (!canonical) return;
-  if (canonical.filePath === entry.filePath) return; // re-download of the same path
-  if (!existsSync(canonical.filePath)) return; // canonical copy lost — keep ours
+  if (!canonical) return entry.filePath;
+  if (canonical.filePath === entry.filePath) return entry.filePath; // re-download of the same path
+  if (!existsSync(canonical.filePath)) return entry.filePath; // canonical copy lost — keep ours
 
   repo.setFilePath(entry.chatId, entry.msgId, canonical.filePath);
   setMessageFilePath(entry.chatId, entry.msgId, canonical.filePath);
@@ -131,6 +162,7 @@ async function hashAndDedupe(entry: Omit<MediaEntry, "id">): Promise<void> {
       );
     }
   }
+  return canonical.filePath;
 }
 
 /** Get recent media for a chat, newest first. */

package/src/storage/repositories/media-index-repo.ts

@@ -33,7 +33,7 @@ export type MediaEntry = {
   timestamp: number;
   /**
    * BLAKE3 hex digest of the file contents (native/blake3-wasm).
-   * Filled in asynchronously after addMedia; undefined until hashed.
+   * Filled in by addMedia before it resolves; undefined until hashed.
    */
   contentHash?: string;
 };
@@ -112,6 +112,17 @@ export function firstByContentHash(
   return row ? rowToEntry(row) : undefined;
 }
 
+/** The entry for one message, if indexed. */
+export function byMessage(
+  chatId: string,
+  msgId: number,
+): MediaEntry | undefined {
+  const row = getDatabase()
+    .prepare(mediaIndexSql.byMessage)
+    .get(chatId, msgId) as Row | undefined;
+  return row ? rowToEntry(row) : undefined;
+}
+
 /** Entries currently pointing at a file — dedupe makes this > 1. */
 export function countByFilePath(filePath: string): number {
   const row = getDatabase()

package/src/storage/sql/media-index.sql

@@ -43,3 +43,7 @@ ORDER BY timestamp ASC, rowid ASC LIMIT 1
 
 -- name: countByFilePath
 SELECT COUNT(*) AS n FROM media_index WHERE file_path = ?
+
+-- name: byMessage
+SELECT chat_id, msg_id, sender_name, type, file_path, caption, timestamp, content_hash
+FROM media_index WHERE chat_id = ? AND msg_id = ?

package/src/storage/sql/statements.generated.ts

@@ -767,6 +767,8 @@ FROM media_index
 WHERE content_hash = ? AND NOT (chat_id = ? AND msg_id = ?)
 ORDER BY timestamp ASC, rowid ASC LIMIT 1`,
   countByFilePath: `SELECT COUNT(*) AS n FROM media_index WHERE file_path = ?`,
+  byMessage: `SELECT chat_id, msg_id, sender_name, type, file_path, caption, timestamp, content_hash
+FROM media_index WHERE chat_id = ? AND msg_id = ?`,
 } as const;
 
 export const memorySql = {