talon-agent 5.18.2 → 5.19.1

package/src/core/mcp-hub/children.ts

@@ -2,11 +2,8 @@
  * Hub child manager — the single owner of external MCP server
  * subprocesses (plugins, brave-search).
  *
- * Before the hub, every chat turn (claude-sdk, codex) or every chat
- * lifetime (openai-agents, kilo/opencode) spawned its own copy of every
- * plugin MCP server — memory grew linearly with chats. The hub instead
- * keeps one child per key and reaps it after an idle TTL, so resident
- * cost tracks *recently active* keys, not every chat ever seen.
+ * One child per key, reaped after an idle TTL, so resident cost tracks
+ * *recently active* keys, not every chat ever seen.
  *
  * Keys: chat-scoped plugins get `name + chatId` (they read
  * `TALON_CHAT_ID` at boot, so instances cannot be shared across chats
@@ -14,8 +11,8 @@
  * use a shared key. Either way the spec factory decides — this module
  * only manages lifecycles.
  *
- * Each child is spawned through the same supervisor wrap as before
- * (stdout JSON filtering + orphan cleanup if the daemon is SIGKILLed),
+ * Each child is spawned through the supervisor wrap (stdout JSON
+ * filtering + orphan cleanup if the daemon is SIGKILLed),
  * connected once over stdio, and shared by every hub session that
  * proxies to it. The tools list is cached per child lifetime — plugin
  * reload restarts children, which naturally invalidates the cache.
@@ -30,6 +27,8 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
 import { log, logError, logWarn } from "../../util/log.js";
 import { HubChildTransport, type ChildExit } from "./child-transport.js";
+import { raiseAlert, resolveAlert } from "../frontend-runtime/alerts.js";
+import { faultText } from "../engine/fault-text.js";
 
 export type ChildSpec = {
   command: string;
@@ -40,13 +39,15 @@ export type ChildSpec = {
 export type ChildHandle = {
   /** Cached tools/list result — fetched once per child lifetime. */
   listTools(): Promise<Tool[]>;
-  /** Forward one tool call; tracked so retirement can drain in-flight work. */
+  /**
+   * Forward one tool call; tracked so retirement can drain in-flight work.
+   * Aborting `signal` cancels the call on the child too.
+   */
   callTool(
     name: string,
     args: Record<string, unknown>,
+    signal?: AbortSignal,
   ): Promise<CallToolResult>;
-  /** Mark activity so the idle reaper skips this child. */
-  touch(): void;
 };
 
 type ChildEntry = {
@@ -151,6 +152,8 @@ type SpawnFailure = { at: number; count: number; error: unknown };
 const spawnFailures = new Map<string, SpawnFailure>();
 const FAILURE_BACKOFF_BASE_MS = 30_000;
 const FAILURE_BACKOFF_MAX_MS = 10 * 60_000;
+/** Consecutive spawn failures of one child before the operator hears. */
+const SPAWN_FAILURE_ALERT_THRESHOLD = 3;
 
 function failureBackoffMs(count: number): number {
   return Math.min(
@@ -159,6 +162,42 @@ function failureBackoffMs(count: number): number {
   );
 }
 
+/** The MCP server name of a child key (keys are `server\0chat`). */
+function serverOf(key: string): string {
+  const nul = key.indexOf("\u0000");
+  return nul === -1 ? key : key.slice(0, nul);
+}
+
+/**
+ * Count a failed spawn into the negative cache, log it with the child's
+ * last words, and alert once the same child has failed
+ * SPAWN_FAILURE_ALERT_THRESHOLD times running — its tools are gone for
+ * every turn until whatever backs it comes back.
+ */
+function noteSpawnFailure(key: string, err: unknown): void {
+  const count = (spawnFailures.get(key)?.count ?? 0) + 1;
+  spawnFailures.set(key, { at: Date.now(), count, error: err });
+  const backoffMs = failureBackoffMs(count);
+  // The exit record is this attempt's only when it is fresh — an older
+  // one belongs to a child that ran and was reaped long ago.
+  const exit = lastExits.get(key);
+  const stderr =
+    exit && Date.now() - exit.at < 60_000 ? exit.stderr.at(-1) : undefined;
+  const detail = faultText(err);
+  logWarn(
+    "gateway",
+    `hub child spawn failed ${describeKey(key)} attempt=${count} backoff_ms=${backoffMs} ` +
+      `error="${detail}"${stderr ? ` stderr="${faultText(stderr)}"` : ""}`,
+  );
+  if (count < SPAWN_FAILURE_ALERT_THRESHOLD) return;
+  const server = serverOf(key);
+  raiseAlert(
+    `mcp.child.${server}`,
+    `MCP server "${server}" has failed to start ${count} times in a row: ${detail}` +
+      `${stderr ? ` (stderr: ${faultText(stderr, 120)})` : ""}. Its tools are unavailable until it starts.`,
+  );
+}
+
 /** Idle TTL for hub children; tunable for tests / tight deployments. */
 function idleTtlMs(): number {
   const raw = Number(process.env.TALON_MCP_HUB_IDLE_MS);
@@ -166,6 +205,14 @@ function idleTtlMs(): number {
 }
 
 const REAP_INTERVAL_MS = 60_000;
+
+/**
+ * Backstop for one forwarded tool call. The SDK's default (60s) would cut
+ * any longer plugin call, though the upstream client allows far more —
+ * its own timeout or cancel reaches the child through the forwarded
+ * signal. This only bounds a call nobody is waiting on any more.
+ */
+const CHILD_CALL_TIMEOUT_MS = 65 * 60_000;
 let reaper: ReturnType<typeof setInterval> | null = null;
 
 async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
@@ -217,9 +264,6 @@ async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
         })());
     })(),
     handle: {
-      touch: () => {
-        entry.lastActivity = Date.now();
-      },
       listTools: () =>
         track(async () => {
           if (toolsCache) return toolsCache;
@@ -227,12 +271,12 @@ async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
           toolsCache = result.tools;
           return toolsCache;
         }),
-      callTool: (name, args) =>
+      callTool: (name, args, signal) =>
         track(
           () =>
-            client.callTool({
-              name,
-              arguments: args,
+            client.callTool({ name, arguments: args }, undefined, {
+              signal,
+              timeout: CHILD_CALL_TIMEOUT_MS,
             }) as Promise<CallToolResult>,
         ),
     },
@@ -272,23 +316,26 @@ export function acquireChild(
     );
   }
 
-  const promise = (async () => {
+  const spawn = async (): Promise<ChildHandle> => {
     try {
       const handle = await spawnChild(key, spec());
-      spawnFailures.delete(key);
+      if (spawnFailures.delete(key)) {
+        const server = serverOf(key);
+        resolveAlert(
+          `mcp.child.${server}`,
+          `MCP server "${server}" is starting normally again.`,
+        );
+      }
       return handle;
     } catch (err) {
-      const prior = spawnFailures.get(key);
-      spawnFailures.set(key, {
-        at: Date.now(),
-        count: (prior?.count ?? 0) + 1,
-        error: err,
-      });
+      noteSpawnFailure(key, err);
       throw err;
-    } finally {
-      inflight.delete(key);
     }
-  })();
+  };
+  // `.finally` always runs after the `set` below. A `finally` block inside
+  // `spawn` would not: when `spec()` throws synchronously it runs before
+  // the set, leaving the rejected promise in `inflight` for good.
+  const promise = spawn().finally(() => inflight.delete(key));
   inflight.set(key, promise);
   return promise;
 }
@@ -340,7 +387,9 @@ export function retireAllChildren(): void {
 function reapIdle(): void {
   const cutoff = Date.now() - idleTtlMs();
   for (const [key, entry] of children) {
-    if (entry.lastActivity >= cutoff) continue;
+    // A call outliving the TTL is work, not idleness — closing the child
+    // would fail it mid-flight. The first sweep after it drains reaps.
+    if (entry.lastActivity >= cutoff || entry.pending > 0) continue;
     children.delete(key);
     entry.close().catch((err) => {
       logError("gateway", `hub reap of ${describeKey(key)} failed`, err);

package/src/core/mcp-hub/index.ts

@@ -1,12 +1,6 @@
 /**
  * MCP hub — daemon-hosted MCP over streamable HTTP, one endpoint for
- * every backend.
- *
- * Motivation: every backend used to spawn its own stdio copy of every
- * MCP server per chat (claude-sdk/codex per turn; openai-agents and
- * kilo/opencode per chat, held indefinitely) — two processes per server
- * per chat once the supervisor wrap is counted. Memory grew linearly
- * with chats. The hub inverts the ownership: the daemon hosts
+ * every backend. The daemon hosts
  *
  *   /mcp/talon/<frontend>/<chatId>   Talon's own tools, IN-PROCESS
  *                                    (zero subprocesses; chat binding
@@ -20,13 +14,13 @@
  * (claude-sdk `type:"http"`, openai-agents `MCPServerStreamableHttp`,
  * codex `mcp_servers.<name>.url`, kilo/opencode `type:"remote"`).
  *
- * What stays exactly as before:
+ * Invariants:
  *   - per-chat tool isolation (binding is per-session from the URL)
- *   - plugin semantics (chat-scoped children keep TALON_CHAT_ID env)
+ *   - chat-scoped plugin children keep TALON_CHAT_ID in their env
  *   - tool-surface trimming (disabledTools / disabledToolTags)
- *   - plugin reloading (reload closes children; next request respawns
- *     from the current registry — see reloadHubChildren)
- *   - orphan cleanup (children still run under the supervisor wrap)
+ *   - plugin reload retires children; the next request respawns from
+ *     the current registry (see reloadHubChildren)
+ *   - children run under the supervisor wrap (orphan cleanup)
  *
  * Endpoints live on the gateway HTTP server (127.0.0.1-bound, behind the
  * same token and Host/Origin guard as /action — see engine/gateway-auth.ts;
@@ -112,8 +106,7 @@ export function pluginHubUrl(
  * Names of every hub-served plugin server — what backends enumerate to
  * build their per-chat URL maps. Registry-backed, so it reflects plugin
  * reloads immediately. (brave-search is served by the hub too, but each
- * backend adds it explicitly alongside its frontend tools, matching the
- * pre-hub structure.)
+ * backend adds it explicitly alongside its frontend tools.)
  */
 export function hubPluginServerNames(only?: string[]): string[] {
   // Specs are built with placeholder identity — only the names matter.
@@ -134,7 +127,6 @@ export async function listHubPluginToolNames(
   const child = await acquireChild(childKey(serverName, chatId), () =>
     pluginSpec(serverName, chatId, bridgeUrl),
   );
-  child.touch();
   return (await child.listTools()).map((tool) => tool.name);
 }
 
@@ -253,6 +245,8 @@ function guestPluginDenied(target: { serverName: string; chatId: string }) {
 type SessionEntry = {
   transport: StreamableHTTPServerTransport;
   lastSeen: number;
+  /** Requests still open on this session, SSE streams included. */
+  open: number;
 };
 
 const sessions = new Map<string, SessionEntry>();
@@ -260,7 +254,11 @@ const sessions = new Map<string, SessionEntry>();
 /**
  * Sessions whose client vanished without a DELETE (crashed subprocess,
  * kill -9) are closed after this idle window. Every well-behaved client
- * terminates explicitly, so this only catches stragglers.
+ * terminates explicitly, so this only catches stragglers. A session with
+ * a request still open is never idle: a client that holds its event
+ * stream between turns (openai-agents keeps one per chat for good) is
+ * alive however quiet the chat, and it does not re-initialize on a 404.
+ * The idle clock restarts when its last open request ends.
  */
 const SESSION_IDLE_MS = 30 * 60_000;
 const SESSION_REAP_INTERVAL_MS = 5 * 60_000;
@@ -271,7 +269,7 @@ function startSessionReaper(): void {
   sessionReaper = setInterval(() => {
     const cutoff = Date.now() - SESSION_IDLE_MS;
     for (const [id, entry] of sessions) {
-      if (entry.lastSeen >= cutoff) continue;
+      if (entry.open > 0 || entry.lastSeen >= cutoff) continue;
       sessions.delete(id);
       entry.transport.close().catch(() => {});
       log("gateway", `hub session reaped (idle): ${id.slice(0, 8)}…`);
@@ -330,6 +328,11 @@ export async function handleHubRequest(
         return;
       }
       entry.lastSeen = Date.now();
+      entry.open++;
+      res.once("close", () => {
+        entry.open--;
+        entry.lastSeen = Date.now();
+      });
       await entry.transport.handleRequest(req, res);
       return;
     }
@@ -369,7 +372,7 @@ export async function handleHubRequest(
       enableDnsRebindingProtection: true,
       allowedHosts: loopbackHosts(bridgeUrl),
       onsessioninitialized: (id) => {
-        sessions.set(id, { transport, lastSeen: Date.now() });
+        sessions.set(id, { transport, lastSeen: Date.now(), open: 0 });
       },
     });
     transport.onclose = () => {

package/src/core/mcp-hub/proxy-server.ts

@@ -31,14 +31,18 @@ export function buildProxyServer(
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const child = await getChild();
-    child.touch();
     return { tools: await child.listTools() };
   });
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  // `extra.signal` fires when the upstream client cancels or its session
+  // closes; passing it on stops the child's work instead of orphaning it.
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const child = await getChild();
-    child.touch();
-    return child.callTool(request.params.name, request.params.arguments ?? {});
+    return child.callTool(
+      request.params.name,
+      request.params.arguments ?? {},
+      extra.signal,
+    );
   });
 
   return server;

package/src/core/mcp-hub/talon-server.ts

@@ -1,17 +1,10 @@
 /**
- * In-process Talon tool server — the hub-side twin of
- * `core/tools/mcp-server.ts`.
+ * In-process Talon tool server: composeTools + createBridge + textResult,
+ * bound to one (frontend, chatId) that arrives per hub session from the
+ * request URL. One `McpServer` instance per session, zero processes.
  *
- * Same composition (composeTools + createBridge + textResult), but
- * instead of reading `TALON_CHAT_ID`/`TALON_FRONTEND` from the env of a
- * dedicated subprocess, the binding arrives per hub session from the
- * request URL. One `McpServer` instance per session, zero processes —
- * this replaces the two processes (supervisor + server) that every
- * chat previously paid per configured frontend.
- *
- * Tool-surface trimming (`disabledTools` / `disabledToolTags`) applies
- * exactly as in the subprocess version, including the `end_turn`
- * exemption — tool-only backends need it to close every turn.
+ * Tool-surface trimming (`disabledTools` / `disabledToolTags`) never
+ * removes `end_turn` — tool-only backends need it to close every turn.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

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

@@ -24,6 +24,8 @@ 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 { faultText } from "../../engine/fault-text.js";
+import { raiseAlert, resolveAlert } from "../../frontend-runtime/alerts.js";
 import {
   credentialIdOf,
   digestsEqual,
@@ -65,6 +67,8 @@ export type MintInput = {
 export type BindResult =
   { ok: true; credential: DeviceCredential } | { ok: false; error: string };
 
+const PERSIST_ALERT = "mesh.credentials.persist";
+
 export class DeviceCredentialStore {
   private records = new Map<string, DeviceCredentialRecord>();
   private loading: Promise<void> | null = null;
@@ -418,7 +422,18 @@ export class DeviceCredentialStore {
 
   private async persist(): Promise<void> {
     this.lastPersist = this.now();
-    await writePrivateJson(this.file, [...this.records.values()]);
+    try {
+      await writePrivateJson(this.file, [...this.records.values()]);
+    } catch (err) {
+      // A credential that never reached disk is gone after a restart —
+      // the device holding it is locked out. Disk faults need a human.
+      raiseAlert(
+        PERSIST_ALERT,
+        `Could not save mesh device credentials: ${faultText(err)}. Newly paired or rotated devices will lose access after a restart until this is fixed.`,
+      );
+      throw err;
+    }
+    resolveAlert(PERSIST_ALERT, "Mesh device credentials are saving again.");
   }
 }
 

package/src/core/mesh/devices/registry.ts

@@ -125,23 +125,7 @@ export class MeshRegistry {
       now,
     );
     this.devices.set(device.id, device);
-    // Stale-duplicate eviction. A reinstall (or an old app build) carries its
-    // own persisted device id, so the same physical machine re-registers
-    // under a fresh identity and the old entry lingers forever as an offline
-    // ghost. Same name + platform under a different id, currently OFFLINE →
-    // superseded install, drop it. An online doppelganger is kept: two live
-    // devices can legitimately share a name.
-    let evicted = false;
-    for (const [id, d] of this.devices) {
-      if (id === device.id) continue;
-      if (d.name !== device.name || d.platform !== device.platform) continue;
-      if (toDeviceInfo(d, now, PRESENCE_TIMEOUT_MS).online) continue;
-      this.devices.delete(id);
-      this.locations.delete(id);
-      this.history.delete(id);
-      evicted = true;
-    }
-    if (this.enforceDeviceCap()) evicted = true;
+    const evicted = this.enforceDeviceCap();
     await this.persistDevices();
     if (evicted) {
       await this.persistLocations();

package/src/core/mesh/devices/service.ts

@@ -69,8 +69,6 @@ export type MeshTransport = {
   command(command: DeviceCommand): void;
 };
 
-export type { MeshToolResult } from "../tool-surface.js";
-
 /** Outcome of pinging one device (see {@link MeshService.pingAll}). */
 export type MeshPingResult = {
   device: DeviceInfo;
@@ -101,8 +99,6 @@ export type MeshServiceOptions = {
   credentials?: DeviceCredentialStore;
 };
 
-export type { MeshBridgeInfo } from "../links/bridge-links.js";
-
 const DEFAULT_FRESH_FIX_TIMEOUT_MS = 8_000;
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_COMMAND_TIMEOUT_MS = 12_000;
@@ -281,17 +277,14 @@ export class MeshService {
    * whose deviceId names a DIFFERENT device is dropped (a confused or
    * misbehaving companion must not be able to answer for its peers).
    *
-   * An ABSENT deviceId is dropped too. It used to be tolerated "for older app
-   * builds", but omitting the field skipped the ownership check entirely —
-   * which is exactly what a spoofer would do to feed the model fabricated
-   * exec stdout or a fake install success. The alternative (accept it when
-   * only one command is pending) was rejected: it still cannot attribute the
-   * reply, it merely narrows the window to whenever the mesh is idle, which
-   * is most of the time. Nothing real is lost — `deviceId` has always been
-   * part of the command-result wire contract (protocol/fixtures/mesh_v1.json,
-   * asserted by daemon, node and companion alike) and both shipped clients
-   * send it. An unattributable reply now leaves the command to time out with
-   * the honest "did not answer" rather than resolving with someone's data.
+   * An ABSENT deviceId is dropped too: omitting the field would skip the
+   * ownership check, which is exactly what a spoofer would do to feed the
+   * model fabricated exec stdout or a fake install success. Accepting it
+   * when only one command is pending still cannot attribute the reply — it
+   * only narrows the window to whenever the mesh is idle. `deviceId` is part
+   * of the command-result wire contract (protocol/fixtures/mesh_v1.json) and
+   * every shipped client sends it, so an unattributable reply is left to
+   * time out with "did not answer" rather than resolving with someone's data.
    */
   completeCommand(body: Record<string, unknown>): boolean {
     const commandId = typeof body.commandId === "string" ? body.commandId : "";
@@ -317,6 +310,15 @@ export class MeshService {
     return true;
   }
 
+  /** Resolve every command still waiting on `deviceId` as failed. */
+  private failPendingCommands(deviceId: string, message: string): void {
+    for (const [commandId, pending] of this.pendingCommands) {
+      if (pending.deviceId !== deviceId) continue;
+      this.pendingCommands.delete(commandId);
+      pending.resolve({ commandId, deviceId, ok: false, message });
+    }
+  }
+
   /**
    * Fail a pending command early when its device stops heartbeating.
    *
@@ -511,6 +513,15 @@ export class MeshService {
     const revoked =
       (await this.credentials?.revokeDevice(removed.id, "device removed")) ??
       [];
+    // With its credential gone it can no longer post a result, and presence
+    // can't fail these for it (the registry entry is gone too) — without
+    // this, a command in flight waits out its whole budget.
+    if (revoked.length > 0) {
+      this.failPendingCommands(
+        removed.id,
+        `${removed.name} was removed from the mesh before it answered.`,
+      );
+    }
     return {
       ok: true,
       text:
@@ -866,6 +877,7 @@ export class MeshService {
       const q = raw.toLowerCase();
       const byId = devices.find((d) => d.id.toLowerCase() === q);
       if (byId) return { target: byId };
+
       const fold = (s: string): string =>
         s.toLowerCase().replace(/[^a-z0-9]+/g, "");
       const folded = fold(raw);
@@ -874,6 +886,7 @@ export class MeshService {
       ): { target: DeviceInfo } | { error: string } | undefined => {
         if (candidates.length === 1) return { target: candidates[0]! };
         if (candidates.length > 1) {
+          const exactNames = new Set(candidates.map((d) => fold(d.name)));
           const online = candidates.filter((d) => d.online);
           if (online.length === 1) return { target: online[0]! };
           return {
@@ -882,13 +895,32 @@ export class MeshService {
                 (d) =>
                   `${d.name} [id: ${d.id}, ${d.online ? "online" : "offline"}]`,
               )
-              .join(", ")}. Use the device id or full name.`,
+              .join(
+                ", ",
+              )}. Use the device id${exactNames.size > 1 ? " or full name" : ""}.`,
           };
         }
         return undefined;
       };
+
+      const exactMatch = pick(devices.filter((d) => fold(d.name) === folded));
+      if (exactMatch) return exactMatch;
+
+      if (q.length >= 6) {
+        const byPrefix = devices.filter((d) =>
+          d.id.toLowerCase().startsWith(q),
+        );
+        if (byPrefix.length === 1) return { target: byPrefix[0]! };
+        if (byPrefix.length > 1) {
+          return {
+            error: `Device id prefix "${raw}" matches ${byPrefix.length} devices: ${byPrefix
+              .map((d) => `${d.name} [id: ${d.id}]`)
+              .join(", ")}. Provide more characters of the id.`,
+          };
+        }
+      }
+
       return (
-        pick(devices.filter((d) => fold(d.name) === folded)) ??
         (folded
           ? pick(devices.filter((d) => fold(d.name).includes(folded)))
           : undefined) ?? { error: this.noSuchDevice(query).text }

package/src/core/mesh/devices/teleport.ts

@@ -44,6 +44,12 @@ function stateFile(): string {
 }
 
 let cache: TeleportStore | undefined;
+/**
+ * The in-flight first read. Shared so concurrent cold callers all get the
+ * one store: separate reads would each build their own, and the last to
+ * finish would replace the cache — dropping any teleport set on another.
+ */
+let loading: Promise<TeleportStore> | undefined;
 
 function emptyStore(): TeleportStore {
   return { chats: Object.create(null) as Record<string, TeleportState> };
@@ -69,8 +75,13 @@ function parseState(value: unknown): TeleportState | null {
   };
 }
 
-async function readStore(): Promise<TeleportStore> {
-  if (cache !== undefined) return cache;
+function readStore(): Promise<TeleportStore> {
+  if (cache !== undefined) return Promise.resolve(cache);
+  loading ??= loadStore();
+  return loading;
+}
+
+async function loadStore(): Promise<TeleportStore> {
   try {
     const raw = await readFile(stateFile(), "utf8");
     const parsed = JSON.parse(raw) as unknown;
@@ -155,4 +166,5 @@ export async function clearTeleport(
 /** Test seam — drop the in-memory cache so the next read hits disk. */
 export function resetTeleportCache(): void {
   cache = undefined;
+  loading = undefined;
 }

package/src/core/mesh/links/node-binaries.ts

@@ -23,6 +23,7 @@
 
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
 import {
   chmod,
   mkdir,
@@ -382,12 +383,18 @@ async function pruneStaleVersions(
   }
 }
 
-async function hashFile(
+/** Stream a file through SHA-256 without loading it into memory (APKs are big
+ *  and Buffer has a hard ceiling). Returns the hex digest and byte size. */
+export async function hashFile(
   path: string,
 ): Promise<{ sha256: string; size: number }> {
-  const data = await readFile(path);
-  return {
-    sha256: createHash("sha256").update(data).digest("hex"),
-    size: data.length,
-  };
+  const { size } = await stat(path);
+  const hash = createHash("sha256");
+  await new Promise<void>((resolve, reject) => {
+    createReadStream(path)
+      .on("data", (chunk) => hash.update(chunk))
+      .on("end", () => resolve())
+      .on("error", reject);
+  });
+  return { sha256: hash.digest("hex"), size };
 }

package/src/core/mesh/persist.ts

@@ -8,7 +8,7 @@
  */
 
 import { randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 /** Per-path write chain: new writes queue onto the tail promise. */
@@ -31,19 +31,31 @@ export async function writePrivateJson(
   value: unknown,
 ): Promise<void> {
   const prior = writeQueues.get(path) ?? Promise.resolve();
-  const next = prior.catch(() => {}).then(() => atomicWriteJson(path, value));
-  writeQueues.set(
-    path,
-    next.finally(() => {
-      if (writeQueues.get(path) === next) writeQueues.delete(path);
-    }),
-  );
+  const next = prior.then(() => atomicWriteJson(path, value));
+  // The queued tail must never reject: a failed write is reported to its
+  // caller through `next`; a rejecting tail that no later writer happens to
+  // chain onto surfaces as a process-level unhandled rejection.
+  const tail: Promise<void> = next
+    .catch(() => {})
+    .then(() => {
+      if (writeQueues.get(path) === tail) writeQueues.delete(path);
+    });
+  writeQueues.set(path, tail);
   return next;
 }
 
 async function atomicWriteJson(path: string, value: unknown): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   const tmp = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-  await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-  await rename(tmp, path);
+  try {
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    await rename(tmp, path);
+  } catch (err) {
+    // Each attempt names a fresh temp file, so one left behind is never
+    // reused — on a full disk every heartbeat would strand another.
+    await rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
 }