@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/host/daemon/plugins/telegram/index.js

@@ -20,12 +20,11 @@
 //       },
 //       ...
 //     ],
-//     // legacy single-channel keys (used only when channels[] is absent/empty):
-//     "bot_token": "",
-//     "chat_id": "",
-//     "route_to_agent": "",
+//     "route_to_agent": "",              // default for channels that omit it
 //     "poll_interval_ms": 1500
 //   }
+// With channels[] empty, one implicit "default" channel is polled using
+// BOT_TELEGRAM_TOKEN / TELEGRAM_CHAT_ID from the environment.
 
 // This poller is intentionally thin: per-update logic lives in core/channels/
 // telegram/ — dispatch (inbound routing), reply (the super-agent turn),
@@ -49,10 +48,56 @@ import { handleUpdate } from "#core/channels/telegram/dispatch.js";
 import { handleCallbackQuery, startAskFlow, maybeConsumeAskTextAnswer } from "#core/channels/telegram/ask-callbacks.js";
 import { sendMessage, sendChatAction, editMessageReplyMarkup, answerCallbackQuery, getUpdates } from "#core/channels/telegram/api.js";
 import { sendPhoto, sendVoice, sendDocument, sendAudio } from "#core/channels/telegram/media.js";
+import { archiveOutboundMedia, outboundMediaMeta } from "#core/stores/media-archive.js";
 export { sendPhoto, sendVoice, sendDocument, sendAudio };
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
+/**
+ * Record a photo/voice/document/audio the agent just SENT, with the file on it.
+ *
+ * Two bugs lived in the four copies of this that used to be inline below.
+ *
+ * `type` was the media kind ("photo", "voice", …), and the ledger's type is a
+ * five-value enum (core/stores/messages.js: user | agent | tool | system |
+ * compact). `inferMessageType` dropped the unknown value in silence and fell
+ * through to "outbound ⇒ agent", so the row was written — just not as anything
+ * that said a file was involved. The kind belongs in meta, where
+ * `mediaFromMeta` reads it; `type` says who spoke.
+ *
+ * And the meta named no file at all, so a thread had nothing to render: the
+ * caption alone, or the bare placeholder `[photo]` when the send had none. The
+ * bytes are archived first (media-archive.js) because a path outside
+ * ~/.apx/media is one the media endpoint must refuse — the photo the user
+ * already has on Telegram would still read "attachment failed" on the web.
+ */
+function logSentMedia({ poller, chat_id, author, kind, body, source, filename, mime, duration }) {
+  const archived = archiveOutboundMedia(source, { filename, mime });
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "out",
+    type: "agent",
+    actor_id: SUPERAGENT_ACTOR_ID,
+    actor_kind: "superagent",
+    // Same attribution `send()` writes. Without it the row is an agent turn
+    // that names no agent, and the thread cannot say who sent the file.
+    agent_slug: SUPERAGENT_ACTOR_ID,
+    author,
+    body,
+    meta: {
+      chat_id: chat_id || resolveChatId(poller.channel),
+      tg_channel: poller.channel.name,
+      // A send by public URL has no bytes of ours to keep, so it gets no
+      // attachment — but the row should still say what went out. Names only:
+      // `mediaFromMeta` needs a path before it offers a card, so this can never
+      // put a player on screen with nothing behind it.
+      ...(filename ? { file_name: filename } : {}),
+      ...(mime ? { mime_type: mime } : {}),
+      ...outboundMediaMeta(kind, archived, { duration }),
+    },
+  });
+}
+
 // ---------- per-channel poller ----------------------------------------------
 
 class ChannelPoller {
@@ -64,9 +109,7 @@ class ChannelPoller {
     this.plugins = plugins;
     this.registries = registries;
     this.state = loadState();
-    this.offset =
-      this.state.channels?.[channel.name]?.offset ??
-      (channel.name === "default" ? this.state._legacy_offset || 0 : 0);
+    this.offset = this.state.channels?.[channel.name]?.offset ?? 0;
     this.polling = false;
     this.lastError = null;
     this.lastUpdateAt = null;
@@ -116,6 +159,12 @@ class ChannelPoller {
 
   stop() {
     this.polling = false;
+    // Kill in-flight turns so a restart doesn't leave a zombie run that still
+    // holds the chat (and so `apx daemon restart` actually interrupts Telegram).
+    for (const ctrl of this.activeRequests.values()) {
+      try { ctrl.abort(); } catch { /* already aborted */ }
+    }
+    this.activeRequests.clear();
   }
 
   async _loop() {
@@ -127,6 +176,9 @@ class ChannelPoller {
         // A successful poll clears any stale error so status reflects recovery.
         this.lastError = null;
         for (const u of updates) {
+          // handleUpdate logs inbound + spawns the model turn; it must NOT
+          // await the super-agent. Awaiting the whole run froze getUpdates,
+          // so a newer message could never abort the one in flight.
           await this._handleUpdate(u);
           this.offset = u.update_id + 1;
           this._saveOffset();
@@ -192,7 +244,12 @@ class ChannelPoller {
   async _typing(chat_id) {
     const token = resolveBotToken(this.channel);
     if (!token || !chat_id) return;
-    try { await sendChatAction(token, chat_id); } catch { /* best-effort */ }
+    try {
+      await sendChatAction(token, chat_id);
+    } catch (e) {
+      // A silent typing failure looks exactly like a frozen agent to the owner.
+      this.log(`telegram[${this.channel.name}] sendChatAction failed: ${e.message}`);
+    }
   }
 
   // Returns a stop() fn; pings the typing indicator every 4s until called.
@@ -318,6 +375,7 @@ export default {
       async send({ channel: channelName, chat_id, text, reply_markup, author = resolveAgentName(config), meta: extraMeta }) {
         const p = pickPoller(pollers, channelName);
         const result = await p._send({ chat_id, text, reply_markup });
+        // attribution-exempt: relay primitive — send() ships text the caller composed; a caller that spent tokens passes model/usage via `meta`.
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
           direction: "out",
@@ -345,15 +403,10 @@ export default {
       async sendPhoto({ channel: channelName, chat_id, photo, caption, parse_mode, author = resolveAgentName(config) }) {
         const p = pickPoller(pollers, channelName);
         const result = await p._sendPhoto({ chat_id, photo, caption, parse_mode });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "photo",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          author,
+        logSentMedia({
+          poller: p, chat_id, author, kind: "photo",
           body: caption || "[photo]",
-          meta: { chat_id: chat_id || resolveChatId(p.channel), tg_channel: p.channel.name },
+          source: photo,
         });
         return result;
       },
@@ -365,15 +418,10 @@ export default {
       async sendVoice({ channel: channelName, chat_id, audio, caption, duration, author = resolveAgentName(config) }) {
         const p = pickPoller(pollers, channelName);
         const result = await p._sendVoice({ chat_id, audio, caption, duration });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "voice",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          author,
+        logSentMedia({
+          poller: p, chat_id, author, kind: "audio",
           body: caption || "[voice]",
-          meta: { chat_id: chat_id || resolveChatId(p.channel), tg_channel: p.channel.name },
+          source: audio, mime: "audio/ogg", duration,
         });
         return result;
       },
@@ -385,15 +433,10 @@ export default {
       async sendDocument({ channel: channelName, chat_id, document, caption, filename, mime_type, author = resolveAgentName(config) }) {
         const p = pickPoller(pollers, channelName);
         const result = await p._sendDocument({ chat_id, document, caption, filename, mime_type });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "document",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          author,
+        logSentMedia({
+          poller: p, chat_id, author, kind: "document",
           body: caption || `[document${filename ? " " + filename : ""}]`,
-          meta: { chat_id: chat_id || resolveChatId(p.channel), tg_channel: p.channel.name, filename, mime_type },
+          source: document, filename, mime: mime_type,
         });
         return result;
       },
@@ -405,15 +448,10 @@ export default {
       async sendAudio({ channel: channelName, chat_id, audio, caption, title, performer, author = resolveAgentName(config) }) {
         const p = pickPoller(pollers, channelName);
         const result = await p._sendAudio({ chat_id, audio, caption, title, performer });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "audio",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          author,
+        logSentMedia({
+          poller: p, chat_id, author, kind: "audio",
           body: caption || title || "[audio]",
-          meta: { chat_id: chat_id || resolveChatId(p.channel), tg_channel: p.channel.name },
+          source: audio, filename: title ? `${title}.mp3` : undefined, mime: "audio/mpeg",
         });
         return result;
       },

package/src/host/daemon/pty-bridge.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Run a command on a pseudo-terminal and relay it over stdin/stdout.
+
+The coding CLIs APX resumes — claude, codex, opencode — are terminal programs:
+they draw an alt-screen UI, read keys in raw mode, and ask the tty how wide it
+is. A plain pipe gives them none of that, so they either refuse to start or
+render into nothing. Something has to allocate a real pty.
+
+The two obvious candidates don't fit. macOS `script(1)` calls tcgetattr on its
+own stdin and exits when that isn't a terminal, which is exactly our case (the
+daemon feeds it a pipe). `node-pty` would work, but it is a native module, and
+APX installs globally through npm onto machines that may have no compiler.
+Python's pty module is already load-bearing for the voice stack, costs nothing
+extra here, and is a few lines.
+
+usage: pty-bridge.py <rows> <cols> <command> [args...]
+
+Exits with the child's status, or 1 if it was killed by a signal. Closing our
+stdin does not end the session — the child decides when it is done.
+"""
+
+import fcntl
+import os
+import pty
+import select
+import struct
+import sys
+import termios
+
+BUF = 65536
+
+
+def main():
+    if len(sys.argv) < 4:
+        sys.stderr.write("usage: pty-bridge.py <rows> <cols> <command> [args...]\n")
+        return 2
+
+    rows, cols = int(sys.argv[1]), int(sys.argv[2])
+    argv = sys.argv[3:]
+
+    pid, master = pty.fork()
+    if pid == 0:
+        # Child: becomes the CLI. execvp only returns on failure, and the
+        # message has to reach the pty (our stderr is the pty now) so the user
+        # sees "command not found" in the terminal instead of a blank panel.
+        try:
+            os.execvp(argv[0], argv)
+        except OSError as e:
+            sys.stderr.write("apx: cannot run %s: %s\r\n" % (argv[0], e))
+            sys.stderr.flush()
+        os._exit(127)
+
+    # Tell the child how big its window is before it draws anything.
+    try:
+        fcntl.ioctl(master, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+    except OSError:
+        pass
+
+    stdin_open = True
+    try:
+        while True:
+            watch = [master] + ([sys.stdin.fileno()] if stdin_open else [])
+            try:
+                ready, _, _ = select.select(watch, [], [])
+            except InterruptedError:
+                continue
+
+            if master in ready:
+                try:
+                    data = os.read(master, BUF)
+                except OSError:
+                    break  # child closed the pty — the session is over
+                if not data:
+                    break
+                os.write(sys.stdout.fileno(), data)
+
+            if stdin_open and sys.stdin.fileno() in ready:
+                try:
+                    data = os.read(sys.stdin.fileno(), BUF)
+                except OSError:
+                    data = b""
+                if data:
+                    os.write(master, data)
+                else:
+                    # Our side hung up. Stop watching stdin, but keep relaying
+                    # the child's output until it exits on its own.
+                    stdin_open = False
+    finally:
+        try:
+            os.close(master)
+        except OSError:
+            pass
+
+    _, status = os.waitpid(pid, 0)
+    return os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/host/daemon/routines-scheduler.js

@@ -52,6 +52,7 @@ export class RoutineScheduler {
               plugins: this.plugins,
               registries: this.registries,
               globalConfig: this.globalConfig,
+              trigger: "schedule",
             },
             r
           );

package/src/host/daemon/smoke.js

@@ -15,8 +15,7 @@ import { readAgents } from "#core/apc/parser.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// Smoke now lives at src/host/daemon/smoke.js — one level deeper than the
-// legacy src/daemon/smoke.js. Adjust the example-project lookup accordingly:
+// Example-project lookup, relative to src/host/daemon/:
 //   ../../../examples/my-first-project           ← repo-local examples (if any)
 //   ../../../../apc/examples/my-first-project    ← sibling apc/ repo
 const EXAMPLE_CANDIDATES = [

package/src/host/daemon/terminal-ws.js

@@ -0,0 +1,132 @@
+// One WebSocket, one terminal, one session.
+//
+// The Sessions list can tell you a conversation exists and hand you the command
+// that reopens it, but pasting that command somewhere else is a context switch
+// away from the thing you were reading. This channel closes the gap: the daemon
+// runs the session's own CLI on a real pty and relays it to a terminal in the
+// web UI.
+//
+// Deliberately NOT a shell. The socket says which session to reopen — engine +
+// id — and the daemon derives the command from the engine that owns it
+// (see resumeArgvFor). A client cannot ask for an arbitrary command, so the
+// channel's blast radius is "the CLIs APX already knows how to launch" rather
+// than "anything on the machine". Whatever the user then types INTO claude or
+// opencode is between them and that tool, exactly as in their own terminal.
+//
+// The wire protocol is the absence of one: every frame is bytes. Client frames
+// are keystrokes for the pty; server frames are output to draw. Status lines
+// from APX itself are written into the same stream, which is why they carry a
+// [apx] prefix — there is no side channel to confuse them with.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { apiPath } from "./api/prefix.js";
+import { findSessionAcrossEngines, findSessionInEngine, resumeArgvFor } from "#core/sessions/index.js";
+
+/** The terminal channel's upgrade path. Lives under /api like every other route. */
+export const TERMINAL_WS_PATH = apiPath("/terminal/ws");
+
+const BRIDGE = path.join(path.dirname(fileURLToPath(import.meta.url)), "pty-bridge.py");
+
+/** Path-gate: is this upgrade for the terminal WS channel? */
+export function isTerminalUpgradePath(url) {
+  let pathname = url || "";
+  try { pathname = new URL(url, "http://localhost").pathname; } catch { /* keep raw */ }
+  return pathname === TERMINAL_WS_PATH;
+}
+
+/** Terminal geometry, clamped: a bad number here misdraws the whole session. */
+function readSize(params) {
+  const n = (key, dflt, min, max) => {
+    const v = Number(params.get(key));
+    return Number.isFinite(v) && v >= min && v <= max ? Math.round(v) : dflt;
+  };
+  return { rows: n("rows", 30, 4, 200), cols: n("cols", 100, 20, 500) };
+}
+
+/**
+ * Resolve which command reopens the session named on the query string, and
+ * where to run it. Returns a `problem` instead of throwing — the socket is
+ * already open, so every failure has to be something we can print in it.
+ */
+export function resolveTerminalTarget(params, { home = os.homedir() } = {}) {
+  const id = String(params.get("id") || "");
+  const engineParam = String(params.get("engine") || "");
+  if (!id) return { problem: "no session id given" };
+
+  let meta = null;
+  try {
+    meta = engineParam ? findSessionInEngine(engineParam, id) : (findSessionAcrossEngines(id)[0] || null);
+  } catch { meta = null; }
+
+  // An engine we were told about is enough to build the command: a session the
+  // engine hasn't flushed to disk yet still deserves to open.
+  const engine = engineParam || meta?.engine || null;
+  const argv = engine ? resumeArgvFor(engine, id) : null;
+  if (!argv) {
+    return { problem: engine ? `engine "${engine}" cannot reopen a session from the terminal` : "unknown session" };
+  }
+
+  // Run where the conversation happened, so relative paths in it still mean
+  // what they meant. Engines that don't record a cwd land in the home dir.
+  const cwd = meta?.cwd && fs.existsSync(meta.cwd) ? meta.cwd : home;
+  return { argv, cwd, engine, id };
+}
+
+/**
+ * Attach a live terminal to `ws`. Spawns the pty bridge, relays bytes both
+ * ways, and makes sure neither side can outlive the other: closing the socket
+ * kills the CLI, and the CLI exiting closes the socket.
+ */
+export function startTerminalSession(ws, req, { python = "python3", home = os.homedir() } = {}) {
+  const say = (line) => { try { if (ws.readyState === 1) ws.send(Buffer.from(`\r\n[apx] ${line}\r\n`)); } catch {} };
+
+  let params;
+  try { params = new URL(req.url || "", "http://localhost").searchParams; } catch { params = new URLSearchParams(); }
+
+  const target = resolveTerminalTarget(params, { home });
+  if (target.problem) {
+    say(target.problem);
+    try { ws.close(); } catch {}
+    return null;
+  }
+
+  const { rows, cols } = readSize(params);
+  let child;
+  try {
+    child = spawn(python, [BRIDGE, String(rows), String(cols), ...target.argv], {
+      cwd: target.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (e) {
+    say(`could not start a terminal: ${e.message}`);
+    try { ws.close(); } catch {}
+    return null;
+  }
+
+  say(`${target.argv.join(" ")}   (${target.cwd})`);
+
+  child.on("error", (e) => {
+    // python3 missing is the realistic case, and it is worth naming: without it
+    // there is no pty, and the panel would otherwise just sit there empty.
+    say(`terminal unavailable: ${e.message}`);
+    try { ws.close(); } catch {}
+  });
+  child.stdout.on("data", (chunk) => { try { if (ws.readyState === 1) ws.send(chunk); } catch {} });
+  child.stderr.on("data", (chunk) => { try { if (ws.readyState === 1) ws.send(chunk); } catch {} });
+  child.on("close", (code) => {
+    say(`session ended (exit ${code ?? "?"})`);
+    try { ws.close(); } catch {}
+  });
+
+  ws.on("message", (raw) => {
+    try { child.stdin.write(Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw))); } catch {}
+  });
+  const stop = () => { try { child.kill("SIGTERM"); } catch {} };
+  ws.on("close", stop);
+  ws.on("error", stop);
+
+  return child;
+}

package/src/host/daemon/tts-keepwarm.js

@@ -0,0 +1,87 @@
+// Keeps a self-hosted voice engine's weights resident, the same way
+// whisper-server.js does for transcription.
+//
+// The problem is not loading — the engine reports `load 0.0s` throughout. On a
+// machine short on RAM macOS compresses the model's pages out from under a
+// process that is merely idle, and the next generation pays to decompress
+// several gigabytes before it can emit a single token. Measured on this M4 Pro
+// with Qwen3-TTS: 1.5s after two minutes idle, 24.5s after nine.
+//
+// The desktop already asks for a warm-up when the microphone opens, which is
+// the right idea and not enough on its own: an utterance lasts three seconds
+// and the decompression takes twenty, so the reply's own synthesis queues
+// behind a warm-up that is still running. Paying it on a timer instead means
+// it is never on the path of a turn at all.
+//
+// Only ever pointed at an engine the user runs themselves — see isSelfHosted.
+// A periodic ping at a metered cloud endpoint would quietly bill for silence.
+import { warmupTts } from "#core/voice/tts.js";
+import { resolveTtsCandidates } from "#core/voice/engines/index.js";
+import { readConfig } from "#core/config/index.js";
+
+// Nine minutes was cold and two and a half was fine, so the default sits well
+// inside the window rather than close to its edge — the ping is cheap and a
+// missed one costs twenty seconds.
+export const DEFAULT_KEEP_WARM_MINUTES = 3;
+
+let _timer = null;
+
+/**
+ * Whether an engine runs on this machine or the local network, and so costs
+ * nothing to poke. Anything reached over the public internet is somebody's
+ * metered API, whatever it is nominally called.
+ */
+export function isSelfHosted(baseUrl) {
+  let host;
+  try { host = new URL(String(baseUrl)).hostname.toLowerCase(); } catch { return false; }
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) return true;
+  if (host === "::1" || host === "0.0.0.0") return true;
+  if (/^127\./.test(host)) return true;
+  if (/^10\./.test(host)) return true;
+  if (/^192\.168\./.test(host)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;   // 172.16/12
+  return false;
+}
+
+/**
+ * The engine a keep-warm ping would reach, or null when pinging it would be
+ * wrong: nothing configured, no warm-up support, or a remote/metered endpoint.
+ */
+export async function keepWarmTarget(globalConfig) {
+  const cfg = globalConfig || readConfig() || {};
+  const [first] = await resolveTtsCandidates({ globalConfig: cfg });
+  if (!first) return null;
+  if (typeof first.adapter?.warmup !== "function") return null;
+  if (!isSelfHosted(first.engineConfig?.base_url)) return null;
+  return first;
+}
+
+export async function startTtsKeepWarm(log = console.log) {
+  stopTtsKeepWarm();
+  try {
+    const cfg = readConfig() || {};
+    const ttsCfg = cfg?.voice?.tts || {};
+    if (ttsCfg.keep_warm === false) return;
+    const target = await keepWarmTarget(cfg);
+    if (!target) return;
+
+    const minutes = Number(ttsCfg.keep_warm_minutes ?? DEFAULT_KEEP_WARM_MINUTES) || DEFAULT_KEEP_WARM_MINUTES;
+    const everyMs = Math.max(60_000, minutes * 60_000);
+    const ping = () => {
+      warmupTts({ globalConfig: readConfig() || {} })
+        .then((r) => { if (!r.ok) log(`tts: keep-warm failed — ${r.error}`); })
+        .catch(() => {});
+    };
+    ping();
+    _timer = setInterval(ping, everyMs);
+    _timer.unref?.();
+    log(`tts: keep-warm every ${Math.round(everyMs / 60_000)} min (${target.provider})`);
+  } catch (e) {
+    log(`tts: keep-warm not started — ${e?.message || e}`);
+  }
+}
+
+export function stopTtsKeepWarm() {
+  if (_timer) clearInterval(_timer);
+  _timer = null;
+}

package/src/host/daemon/wakeup.js

@@ -3,6 +3,7 @@ import fetch from "node-fetch";
 import { readIdentity, writeIdentity } from "#core/identity/index.js";
 import { resolveProvider, getAdapter } from "#core/engines/index.js";
 import { canNudge, recordNudge, nudgeFeedbackKeyboard } from "#core/nudge/index.js";
+import { resolveChannels, resolveBotToken, resolveChatId } from "#core/channels/telegram/helpers.js";
 
 const WAKEUP_COOLDOWN_MS = 30 * 60 * 1000; // 30 min
 
@@ -13,7 +14,7 @@ const ISO_TO_LANGUAGE = {
 };
 
 // Exported for unit testing.
-// Priority: config.user.language (ISO 639-1) → identity.language (legacy) → system LANG env.
+// Priority: config.user.language (ISO 639-1) → identity.language → system LANG env.
 export function detectLanguage(identity, config) {
   const cfgLang = config?.user?.language;
   if (cfgLang) return ISO_TO_LANGUAGE[cfgLang.toLowerCase()] || cfgLang;
@@ -67,8 +68,12 @@ export async function triggerWakeup(config, log) {
   const identity = readIdentity();
   if (!identity) return;
 
-  const tg = config.telegram;
-  if (!tg?.enabled || !tg?.bot_token || !tg?.chat_id) return;
+  if (!config?.telegram?.enabled) return;
+  const channel = resolveChannels(config)[0];
+  if (!channel) return;
+  const botToken = resolveBotToken(channel);
+  const chatId = resolveChatId(channel);
+  if (!botToken || !chatId) return;
 
   // Cooldown check
   if (identity.last_wakeup) {
@@ -91,10 +96,10 @@ export async function triggerWakeup(config, log) {
   try {
     const message = await generateMessage(identity, config);
     const text = message || `${identity.agent_name} online. Ready.`;
-    await sendTelegram(tg.bot_token, tg.chat_id, text, nudgeFeedbackKeyboard(gate.nudge_id));
-    recordNudge(gate, { chat_id: tg.chat_id, preview: text });
+    await sendTelegram(botToken, chatId, text, nudgeFeedbackKeyboard(gate.nudge_id));
+    recordNudge(gate, { chat_id: chatId, preview: text });
     writeIdentity({ last_wakeup: new Date().toISOString() });
-    log?.(`wakeup: sent to Telegram chat ${tg.chat_id}`);
+    log?.(`wakeup: sent to Telegram chat ${chatId}`);
   } catch (e) {
     log?.(`wakeup: failed — ${e.message}`);
   }

package/src/host/daemon/whisper-server.js

@@ -239,6 +239,50 @@ export async function warmupWhisper() {
   }
 }
 
+// ── Keep-warm ───────────────────────────────────────────────────────────────
+//
+// Loading large-v3-turbo costs ~10s, and it is paid by whoever speaks first
+// after the weights fall out of resident memory. That used to be the user:
+// the desktop window warms on open, but `/warmup` holds the model lock while
+// it loads, so an utterance started seconds later queued behind it — which is
+// exactly the ~11s first-transcription stall in the logs, against ~0.9s for
+// every one after it.
+//
+// The window can't own this, because it is closed most of the day and the model
+// goes cold in between. The daemon can: it pings /warmup on a cycle shorter
+// than the server's idle timeout, so the weights stay hot and the timer stays
+// reset for as long as the daemon is up.
+//
+// Turn it off with transcription.local.keep_warm = false, and the idle watchdog
+// takes over: the server exits after idle_minutes and gives the RAM back, at
+// the cost of a cold first utterance.
+let _keepWarmTimer = null;
+
+export function startWhisperKeepWarm(log = console.log) {
+  stopWhisperKeepWarm();
+  return getConfig().then((cfg) => {
+    if (cfg.provider === "openai" || cfg.provider === "custom") return;
+    if (cfg.local.keep_warm === false) return;
+    const idleMin = Number(cfg.local.idle_minutes ?? DEFAULT_LOCAL.idle_minutes) || 10;
+    // Comfortably inside the idle window, and never a busy-loop on a tiny one.
+    const everyMs = Math.max(60_000, (idleMin - 2) * 60_000);
+    const ping = () => {
+      warmupWhisper()
+        .then((r) => { if (!r.ok) log(`whisper: keep-warm failed — ${r.error}`); })
+        .catch(() => {});
+    };
+    ping();
+    _keepWarmTimer = setInterval(ping, everyMs);
+    _keepWarmTimer.unref?.();
+    log(`whisper: keep-warm every ${Math.round(everyMs / 60_000)} min (idle timeout ${idleMin} min)`);
+  }).catch(() => {});
+}
+
+export function stopWhisperKeepWarm() {
+  if (_keepWarmTimer) clearInterval(_keepWarmTimer);
+  _keepWarmTimer = null;
+}
+
 export async function shutdownWhisperServer() {
   if (_serverProcess) {
     try { _serverProcess.kill(); } catch {}