@inetafrica/open-claudia 3.2.0 → 3.2.3

package/channels/telegram/adapter.js

@@ -672,11 +672,15 @@ class TelegramAdapter {
     if (!media || !media.fileId) return null;
     const file = await this.bot.getFile(media.fileId);
     const fileUrl = `https://api.telegram.org/file/bot${this.token}/${file.file_path}`;
-    const ext = media.fileName ? path.extname(media.fileName) || ".bin"
-      : media.type === "voice" ? ".ogg"
-      : media.type === "audio" ? path.extname(media.fileName || "") || ".ogg"
-      : media.type === "photo" ? ".jpg"
-      : ".bin";
+    // Telegram's file_path carries the real extension even when the message
+    // has no fileName (e.g. videos), so prefer it over the .bin fallback.
+    const ext = path.extname(media.fileName || "")
+      || path.extname(file.file_path || "")
+      || (media.type === "voice" ? ".ogg"
+        : media.type === "audio" ? ".ogg"
+        : media.type === "photo" ? ".jpg"
+        : media.type === "video" ? ".mp4"
+        : ".bin");
     const baseDir = media.type === "document" ? FILES_DIR : TEMP_DIR;
     const localPath = media.type === "document" && media.fileName
       ? path.join(baseDir, media.fileName)

package/core/handlers.js

@@ -1611,14 +1611,18 @@ register({
       // Stop pending preview flushes but keep statusMessageId/Channel: the
       // killed run's delivery unwind edits the preview to drop its footer.
       if (state.streamInterval) { clearTimeout(state.streamInterval); state.streamInterval = null; }
-      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
+      // Clearing the interval here orphans the run's own stopper (ownership
+      // check makes it a no-op), so the explicit typing:stop must go out now.
+      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; state.thinkingPhase = false; }
+      try { currentAdapter()?.typingStop?.(currentChannelId()); } catch (_) {}
       await sideCancellation;
       await send(`Cancelled.${queuedNote()}`);
     } else if (state.preparingRun) {
       // Turn is mid-recall/prompt-build — no process to kill yet. Flag it so
       // the runner's pre-spawn shouldAbort checkpoint bails before spawning.
       state.cancelRequested = true;
-      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
+      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; state.thinkingPhase = false; }
+      try { currentAdapter()?.typingStop?.(currentChannelId()); } catch (_) {}
       await sideCancellation;
       await send(`Cancelled.${queuedNote()}`);
     } else if (await sideCancellation) await send("Cancelled side response.");

package/core/loopback.js

@@ -82,7 +82,7 @@ const JSON_KINDS = new Set([
   "relay-send", "recent-fetch", "audit-tail",
   "auth-list", "auth-revoke",
   "approval-request",
-  "say",
+  "say", "call", "tts", "transcribe",
 ]);
 
 function callerIsOwner(payload) {
@@ -200,6 +200,56 @@ async function handleJson(req, res, url, kind) {
     return reply(res, ok ? 200 : 500, { ok });
   }
 
+  if (kind === "tts") {
+    // Synthesis-to-FILE: no chat egress, so no guardrail — the artifact stays on
+    // local disk until some send verb (with its own guard) ships it. Runs here
+    // because only the bot process holds the speech token.
+    const text = String(payload.text || "").trim();
+    if (!text) return reply(res, 400, { error: "missing text" });
+    try {
+      const { textToVoiceFile } = require("./media");
+      const outPath = await textToVoiceFile(text, {
+        voice: payload.voice ? String(payload.voice) : undefined,
+        out: payload.out ? String(payload.out) : undefined,
+      });
+      if (!outPath) return reply(res, 503, { error: "no TTS route available" });
+      return reply(res, 200, { ok: true, path: outPath });
+    } catch (e) {
+      return reply(res, 500, { error: `synthesis failed: ${e.message}` });
+    }
+  }
+
+  if (kind === "transcribe") {
+    const filePath = String(payload.path || "").trim();
+    if (!filePath) return reply(res, 400, { error: "missing path" });
+    if (!path.isAbsolute(filePath)) return reply(res, 400, { error: "path must be absolute (the bot process has its own cwd)" });
+    if (!fs.existsSync(filePath)) return reply(res, 400, { error: `file not found: ${filePath}` });
+    try {
+      const { transcribeMedia } = require("./media");
+      const text = await transcribeMedia(filePath);
+      if (text == null) return reply(res, 503, { error: "no STT route available" });
+      return reply(res, 200, { ok: true, text });
+    } catch (e) {
+      return reply(res, 500, { error: `transcription failed: ${e.message}` });
+    }
+  }
+
+  if (kind === "call") {
+    // Placing a live voice call is owner-only: it rings a phone on the bot's
+    // behalf, so nothing guarded/external may trigger it.
+    if (!callerIsOwner(payload)) return reply(res, 403, { error: "only the owner can place a call" });
+    const manager = adapter._callManager;
+    if (!manager || typeof manager.outgoing !== "function") {
+      return reply(res, 501, { error: `adapter ${adapterId} does not support outgoing calls` });
+    }
+    try {
+      const result = await manager.outgoing({ chatId: channelId, toUserId: payload.toUserId || undefined });
+      return reply(res, 200, { ok: true, ...result });
+    } catch (e) {
+      return reply(res, 500, { error: e.message });
+    }
+  }
+
   if (kind === "schedule-wakeup") {
     const fireAt = Number(payload.fireAt);
     if (!Number.isFinite(fireAt) || fireAt <= 0) return reply(res, 400, { error: "missing/invalid fireAt" });
@@ -297,6 +347,10 @@ async function handleJson(req, res, url, kind) {
       label: String(payload.label || payload.prompt).slice(0, 60),
       schedule: payload.schedule ? String(payload.schedule) : undefined,
       repeat: !!payload.repeat,
+      // Absent/invalid → the scheduler stamps its default watch timeout.
+      expiresAt: Number.isFinite(Number(payload.expiresAt)) && Number(payload.expiresAt) > 0
+        ? Number(payload.expiresAt)
+        : undefined,
       source: payload.source || "agent",
       sessionId: payload.sessionId || null,
       previousSessionId: payload.previousSessionId || null,

package/core/media.js

@@ -101,7 +101,7 @@ async function elevenLabsToVoice(clean) {
 
 // Pocket TTS through the Agent Space speech gateway. The gateway returns WAV;
 // Telegram and voice transports receive a compact Ogg/Opus file.
-async function pocketToVoice(clean) {
+async function pocketToVoice(clean, voiceOverride) {
   const token = speechBearerToken();
   if (TTS_PROVIDER === "elevenlabs" || !token || !SPEECH_SERVICE_URL || !FFMPEG) return null;
   let wavPath = null;
@@ -109,7 +109,7 @@ async function pocketToVoice(clean) {
     const res = await fetch(`${SPEECH_SERVICE_URL.replace(/\/$/, "")}/v1/audio/speech`, {
       method: "POST",
       headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-      body: JSON.stringify({ input: clean, voice: ttsVoice.getVoice(), response_format: "wav" }),
+      body: JSON.stringify({ input: clean, voice: voiceOverride || ttsVoice.getVoice(), response_format: "wav" }),
       signal: AbortSignal.timeout(60000),
     });
     if (!res.ok) {
@@ -186,16 +186,69 @@ function canSpeak() {
 }
 
 // Natural voice via ElevenLabs, falling back to macOS `say` only on no-key/error.
-async function textToVoice(text) {
+// opts.voice overrides the gateway voice id (e.g. a cloned voice) for the pocket
+// route only — ElevenLabs/say fallbacks keep their configured voices.
+async function textToVoice(text, opts = {}) {
   const clean = cleanForTTS(text);
   if (!clean) return null;
-  const pocket = await pocketToVoice(clean);
+  const pocket = await pocketToVoice(clean, opts.voice);
   if (pocket) return pocket;
   const eleven = await elevenLabsToVoice(clean);
   if (eleven) return eleven;
   return sayToVoice(clean);
 }
 
+// Synthesize to a caller-chosen FILE (voice-overs, video narration) instead of a
+// chat send. `out` picks the container by extension (.ogg is native; anything
+// else transcodes). Returns the final path, or null when no TTS route exists.
+async function textToVoiceFile(text, { voice, out } = {}) {
+  const oggPath = await textToVoice(text, { voice });
+  if (!oggPath) return null;
+  if (!out || path.resolve(out) === path.resolve(oggPath)) return oggPath;
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  if (path.extname(out).toLowerCase() === path.extname(oggPath).toLowerCase()) {
+    fs.copyFileSync(oggPath, out);
+  } else {
+    if (!FFMPEG) throw new Error(`ffmpeg unavailable to convert to ${path.extname(out) || "the requested format"}`);
+    execSync(`"${FFMPEG}" -i "${oggPath}" -y "${out}" 2>/dev/null`, { timeout: 60000 });
+  }
+  try { fs.unlinkSync(oggPath); } catch (e) {}
+  return out;
+}
+
+// True when at least one transcribeAudio route can produce text.
+function canTranscribe() {
+  if (SPEECH_SERVICE_URL && speechBearerToken()) return true;
+  return Boolean(WHISPER_CLI && FFMPEG);
+}
+
+// Transcribe ANY audio/video file (mp3, m4a, wav, ogg, mp4, mkv...): normalize
+// to 16kHz mono wav first when ffmpeg is available — that extracts the audio
+// track from video containers and shrinks the gateway upload. Returns the
+// transcript string, or null when no STT route exists.
+async function transcribeMedia(filePath) {
+  if (!canTranscribe()) return null;
+  let wavPath = null;
+  let sendPath = filePath;
+  if (FFMPEG && !/\.wav$/i.test(filePath)) {
+    try {
+      wavPath = path.join(TEMP_DIR, `stt-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.wav`);
+      execSync(`"${FFMPEG}" -i "${filePath}" -vn -ar 16000 -ac 1 -y "${wavPath}" 2>/dev/null`, { timeout: 300000 });
+      sendPath = wavPath;
+    } catch (e) {
+      console.error("STT transcode error:", e.message);
+      try { if (wavPath) fs.unlinkSync(wavPath); } catch (_) {}
+      wavPath = null;
+      sendPath = filePath;
+    }
+  }
+  try {
+    return await transcribeAudio(sendPath);
+  } finally {
+    if (wavPath) { try { fs.unlinkSync(wavPath); } catch (e) {} }
+  }
+}
+
 // Split a reply into sentence-sized chunks for streamed TTS. Tiny fragments are
 // merged into the next chunk so we don't fire a TTS call per "Hi." and end up
 // with choppy playback. Returns cleaned, non-empty chunks.
@@ -250,4 +303,4 @@ async function synthSentenceMp3(text) {
   }
 }
 
-module.exports = { transcribeAudio, transcribeAudioLocal, textToVoice, splitSentences, synthSentenceMp3, pocketToVoice, cloneVoiceFromClip, speechBearerToken, canSpeak, TTS_CMD };
+module.exports = { transcribeAudio, transcribeAudioLocal, transcribeMedia, canTranscribe, textToVoice, textToVoiceFile, splitSentences, synthSentenceMp3, pocketToVoice, cloneVoiceFromClip, speechBearerToken, canSpeak, TTS_CMD };

package/core/providers/utility-policy.js

@@ -4,7 +4,7 @@ const config = require("../config");
 
 const PROVIDER_IDS = Object.freeze(["claude", "codex"]);
 const PROVIDER_ID_SET = new Set(PROVIDER_IDS);
-const PURPOSES = Object.freeze(["subagent", "recall", "review", "dream", "introspection", "enforcer"]);
+const PURPOSES = Object.freeze(["subagent", "recall", "review", "dedup", "dream", "introspection", "enforcer"]);
 const PURPOSE_SET = new Set(PURPOSES);
 const TIERS = Object.freeze(["low", "medium", "high"]);
 const TIER_SET = new Set(TIERS);
@@ -12,6 +12,7 @@ const PURPOSE_PROVIDER_ENV = Object.freeze({
   subagent: "SUBAGENT_PROVIDER",
   recall: "RECALL_PROVIDER",
   review: "MEMORY_PROVIDER",
+  dedup: "MEMORY_PROVIDER",
   dream: "DREAM_PROVIDER",
   introspection: "DREAM_PROVIDER",
   enforcer: "ENFORCER_PROVIDER",
@@ -20,12 +21,14 @@ const PURPOSE_MODEL_PREFIX = Object.freeze({
   subagent: "SUBAGENT_MODEL",
   recall: "RECALL_MODEL",
   review: "PACK_REVIEW_MODEL",
+  dedup: "PACK_DEDUP_MODEL",
   dream: "DREAM_MODEL",
   introspection: "DREAM_MODEL",
   enforcer: "ENFORCER_MODEL",
 });
 const LEGACY_CLAUDE_MODEL_ENV = Object.freeze({
   review: "PACK_REVIEW_MODEL",
+  dedup: "PACK_DEDUP_MODEL",
   dream: "DREAM_MODEL",
   introspection: "DREAM_MODEL",
   enforcer: "ENFORCER_MODEL",

package/core/router.js

@@ -12,7 +12,7 @@ const { isChatAuthorized } = require("./access");
 const introFlow = require("./intro-flow");
 const { send, deleteMessage } = require("./io");
 const { currentState, saveState, autoLinkOwnerChannel, getActiveProvider, getProjectKey } = require("./state");
-const { admitRunContext, runAgent } = require("./runner");
+const { admitRunContext, runAgent, startTypingHeartbeat } = require("./runner");
 const { transcribeAudio, cloneVoiceFromClip } = require("./media");
 const { vault } = require("./vault-store");
 const { isOnboarded, handleOnboarding } = require("./onboarding");
@@ -203,9 +203,20 @@ async function admitGuardedTurn(askText, envelope, state = currentState()) {
   return !(triage && triage.held);
 }
 
+// Chip-on-receipt: enforcer triage, media download, and STT all run before
+// runAgent — many seconds with no feedback. Start the "thinking" heartbeat as
+// soon as a turn-bound message arrives; the run's own heartbeat supersedes it
+// at executeAdmittedRun, after which this stopper is a no-op. Skipped while a
+// run is active — the chip is already owned by that turn.
+function startPreTurnTyping(state) {
+  if (state.runningProcess || state.preparingRun) return () => {};
+  try { return startTypingHeartbeat(state); } catch (_) { return () => {}; }
+}
+
 async function handleVoice(envelope) {
   if (isDuplicate(envelope)) return;
   const state = currentState();
+  let stopPreTurnTyping = () => {};
   try {
     const media = envelope.media?.[0];
     if (!media) return;
@@ -223,7 +234,7 @@ async function handleVoice(envelope) {
       purpose: "foreground",
       attachments: [{ type: "voice", mimeType: media.mimeType || "audio/ogg", fileName: media.fileName || null }],
     });
-    envelope.adapter.typing(envelope.channelId).catch(() => {});
+    stopPreTurnTyping = startPreTurnTyping(state);
     const tStart = Date.now();
     const oggPath = await envelope.adapter.downloadMedia(media);
     const tAfterDownload = Date.now();
@@ -243,11 +254,13 @@ async function handleVoice(envelope) {
       voiceStream: envelope.adapter?.type === "voice",
     });
   } catch (err) { await send(`Voice failed: ${err.message}`); }
+  finally { stopPreTurnTyping(); }
 }
 
 async function handleAudio(envelope) {
   if (isDuplicate(envelope)) return;
   const state = currentState();
+  let stopPreTurnTyping = () => {};
   try {
     const media = envelope.media?.[0];
     if (!media) return;
@@ -260,7 +273,7 @@ async function handleAudio(envelope) {
       purpose: "foreground",
       attachments: [{ type: "audio", mimeType: media.mimeType || null, fileName: media.fileName || null }],
     });
-    envelope.adapter.typing(envelope.channelId).catch(() => {});
+    stopPreTurnTyping = startPreTurnTyping(state);
     const p = await envelope.adapter.downloadMedia(media);
     const t = await transcribeAudio(p);
     try { fs.unlinkSync(p); } catch (e) {}
@@ -272,6 +285,7 @@ async function handleAudio(envelope) {
       attachments: [{ type: "audio", path: p, mimeType: media.mimeType || null, fileName: media.fileName || null }],
     });
   } catch (err) { await send(`Audio failed: ${err.message}`); }
+  finally { stopPreTurnTyping(); }
 }
 
 // A clip the owner sent right after /voice clone. Upload it to the speech
@@ -297,6 +311,7 @@ async function captureVoiceClone(envelope, media) {
 async function handlePhoto(envelope) {
   if (isDuplicate(envelope)) return;
   const state = currentState();
+  let stopPreTurnTyping = () => {};
   try {
     const items = envelope.media || [];
     if (!items.length) return;
@@ -304,6 +319,7 @@ async function handlePhoto(envelope) {
       purpose: "foreground",
       attachments: items.map((item) => ({ type: "image", mimeType: item.mimeType || "image/*", fileName: item.fileName || null })),
     });
+    stopPreTurnTyping = startPreTurnTyping(state);
     const paths = [];
     for (const m of items) paths.push(await envelope.adapter.downloadMedia(m));
     const caption = envelope.caption || "Describe this image. If code/UI/error — explain and fix.";
@@ -327,11 +343,13 @@ async function handlePhoto(envelope) {
       })),
     });
   } catch (err) { await send(`Image failed: ${err.message}`); }
+  finally { stopPreTurnTyping(); }
 }
 
 async function handleDocument(envelope) {
   if (isDuplicate(envelope)) return;
   const state = currentState();
+  let stopPreTurnTyping = () => {};
   try {
     const media = envelope.media?.[0];
     if (!media) return;
@@ -342,6 +360,7 @@ async function handleDocument(envelope) {
       purpose: "foreground",
       attachments: [{ type: "document", mimeType: media.mimeType || null, fileName: media.fileName || null }],
     });
+    stopPreTurnTyping = startPreTurnTyping(state);
     const savePath = await envelope.adapter.downloadMedia(media);
     const fileName = media.fileName || path.basename(savePath);
     const mime = media.mimeType || "";
@@ -361,6 +380,7 @@ async function handleDocument(envelope) {
       attachments: [{ type: isImage ? "image" : "document", path: savePath, mimeType: mime, fileName }],
     });
   } catch (err) { await send(`Failed: ${err.message}`); }
+  finally { stopPreTurnTyping(); }
 }
 
 // Provider-agnostic capture of a credential pasted into chat with no auth
@@ -605,7 +625,11 @@ async function handleText(envelope) {
   // stop, instead of forwarding a secret to the model (Codex refuses those).
   if (await captureLooseCredential(text.trim(), envelope)) return;
 
-  if (!(await admitGuardedTurn(text, envelope, state))) return;
+  const stopPreTurnTyping = startPreTurnTyping(state);
+  let admitted;
+  try { admitted = await admitGuardedTurn(text, envelope, state); }
+  catch (e) { stopPreTurnTyping(); throw e; }
+  if (!admitted) { stopPreTurnTyping(); return; }
 
   const runContext = admitRunContext(text, state.currentSession.dir, envelope.messageId, { purpose: "foreground" });
   const attachments = [];

package/core/runner.js

@@ -1725,17 +1725,24 @@ function decorateForegroundInvocation(invocation, runContext, bundle) {
   return { ...invocation, env };
 }
 
+// Singleton per chat state: a new start supersedes any running heartbeat
+// (pre-turn "thinking" started at message receipt hands off to the run's own
+// heartbeat here). A stopper only acts while its own interval is current, so
+// a stale stopper from a superseded start can never kill a newer heartbeat.
 function startTypingHeartbeat(state, store) {
   const adapter = store?.adapter || currentAdapter();
   const channelId = store?.channelId || currentChannelId();
   if (!adapter || !channelId) return () => {};
+  if (state.typingHeartbeat) clearInterval(state.typingHeartbeat);
   const tick = () => adapter.typing(channelId, state.thinkingPhase ? "thinking" : undefined).catch(() => {});
   state.thinkingPhase = true;
   tick();
-  state.typingHeartbeat = setInterval(tick, 4000);
+  const interval = setInterval(tick, 4000);
+  state.typingHeartbeat = interval;
   return () => {
+    if (state.typingHeartbeat !== interval) return;
     state.thinkingPhase = false;
-    if (state.typingHeartbeat) clearInterval(state.typingHeartbeat);
+    clearInterval(interval);
     state.typingHeartbeat = null;
     try { adapter.typingStop?.(channelId); } catch (_) {}
   };
@@ -1880,7 +1887,10 @@ function createForegroundService({ state, store, stopTyping, capture, ownsAdmiss
       observer.onRecallSurfaced(bundle.recallMetadata);
     },
     onEvent(event, runContext) {
-      if (["text_delta", "text_final", "tool_start", "result", "error"].includes(event.type)) state.thinkingPhase = false;
+      // Streaming text reads as "typing"; tool work re-enters "thinking" so
+      // the chip doesn't decay to a stale "typing" through long tool stretches.
+      if (["text_delta", "text_final", "result", "error"].includes(event.type)) state.thinkingPhase = false;
+      else if (event.type === "tool_start") state.thinkingPhase = true;
       if (event.type === "tool_start" && ["Shell", "Bash"].includes(event.name)) {
         const command = typeof event.detail === "string" ? event.detail : event.detail?.command;
         if (command) { try { require("./tool-guard").noteRawOp(command); } catch (_) {} }
@@ -2248,6 +2258,7 @@ module.exports = {
   runAgent,
   runAgentCapture,
   runAgentSilent,
+  startTypingHeartbeat,
   shouldRetryRefusedRun,
   quarantineRefusedRun,
   refusalRetryContext,

package/core/scheduler.js

@@ -43,6 +43,10 @@ const RETRY_DELAY_MS = 30 * 1000;
 const BUSY_DELAY_MS = 30 * 1000;
 // A watch's `check` command is capped so a hung poll can't wedge the tick.
 const WATCH_CHECK_TIMEOUT_MS = 30 * 1000;
+// Every watch carries a hard expiry so none can idle-poll forever: when the
+// deadline lapses with the check still failing, the next poll tick fires the
+// wake anyway (marked expired) instead of skipping silently.
+const DEFAULT_WATCH_TIMEOUT_MS = 2 * 60 * 60 * 1000;
 const WATCH_LOG_FILE = process.env.OPEN_CLAUDIA_WATCH_LOG_FILE || path.join(CONFIG_DIR, "watch.log");
 const WATCHES_ENABLED_FILE = process.env.OPEN_CLAUDIA_WATCHES_ENABLED_FILE || path.join(CONFIG_DIR, "watches-enabled");
 
@@ -107,6 +111,7 @@ function createSchedulerService(dependencies = {}) {
   const retryDelayMs = Number.isFinite(dependencies.retryDelayMs) ? dependencies.retryDelayMs : RETRY_DELAY_MS;
   const busyDelayMs = Number.isFinite(dependencies.busyDelayMs) ? dependencies.busyDelayMs : BUSY_DELAY_MS;
   const missedGraceMs = Number.isFinite(dependencies.missedGraceMs) ? dependencies.missedGraceMs : MISSED_WAKEUP_GRACE_MS;
+  const watchTimeoutMs = Number.isFinite(dependencies.watchTimeoutMs) ? dependencies.watchTimeoutMs : DEFAULT_WATCH_TIMEOUT_MS;
   const occurrenceIdFactory = dependencies.occurrenceIdFactory || (() => uniqueId("occ"));
   const legacyCronsFile = dependencies.legacyCronsFile === undefined
     ? (dependencies.jobsStore ? null : CRONS_FILE)
@@ -273,22 +278,21 @@ function createSchedulerService(dependencies = {}) {
 
   function wrappedPrompt(job, target) {
     const firedAt = new Date(now()).toISOString();
-    const header = job.check ? "Watch triggered" : job.kind === "cron" ? "Scheduled cron" : "Scheduled wakeup";
-    if (target.fallbackFrom) {
-      return [
-        `[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]`,
-        `[Archived provider-neutral brief: the originating ${target.fallbackFrom} provider is unavailable. Its native session is not being resumed; this explicitly configured fallback starts fresh.]`,
-        job.prompt,
-      ].join("\n");
+    const expired = !!(job.check && job.watchExpired);
+    const header = job.check
+      ? (expired ? "Watch expired" : "Watch triggered")
+      : job.kind === "cron" ? "Scheduled cron" : "Scheduled wakeup";
+    const lines = [`[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]`];
+    if (expired) {
+      lines.push("[This watch reached its timeout without its check ever passing — the watched condition did NOT happen. This is a deadline wake-up, not a trigger: investigate why the condition never became true, and arm a new watch if it is still worth waiting for.]");
     }
-    if (target.switchedFrom) {
-      return [
-        `[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]`,
-        `[Provider now tracks your current selection (${target.provider}); this was scheduled under ${target.switchedFrom}, whose native session cannot cross providers, so this run starts a fresh thread.]`,
-        job.prompt,
-      ].join("\n");
+    if (target.fallbackFrom) {
+      lines.push(`[Archived provider-neutral brief: the originating ${target.fallbackFrom} provider is unavailable. Its native session is not being resumed; this explicitly configured fallback starts fresh.]`);
+    } else if (target.switchedFrom) {
+      lines.push(`[Provider now tracks your current selection (${target.provider}); this was scheduled under ${target.switchedFrom}, whose native session cannot cross providers, so this run starts a fresh thread.]`);
     }
-    return `[${header} "${job.label}" fired at ${firedAt}; occurrence ${job.occurrenceId}]\n${job.prompt}`;
+    lines.push(job.prompt);
+    return lines.join("\n");
   }
 
   function unscheduleJob(id) {
@@ -394,7 +398,7 @@ function createSchedulerService(dependencies = {}) {
 
   async function fireJob(idOrJob, options = {}) {
     const requested = typeof idOrJob === "string" ? jobsStore.get(idOrJob) : idOrJob;
-    const job = requested?.id && jobsStore.get(requested.id) ? jobsStore.get(requested.id) : requested;
+    let job = requested?.id && jobsStore.get(requested.id) ? jobsStore.get(requested.id) : requested;
     if (!job) return { ok: false, status: "missing" };
     if (job.disabled || job.status === "dead-letter" || job.status === "archived") {
       return { ok: false, status: job.status, skipped: true };
@@ -424,10 +428,35 @@ function createSchedulerService(dependencies = {}) {
       catch (_) { check = { code: 1, timedOut: false }; }
       finally { checksInFlight.delete(job.id); }
       if (!check || check.code !== 0) {
-        logWatch(job, check && check.timedOut ? "idle (check timed out)" : `idle (check exit ${check ? check.code : "?"})`);
-        return { ok: false, status: "watch-idle", skipped: true };
+        // Expiry backstop: a watch whose deadline has lapsed fires the wake
+        // anyway (marked expired) so no watch can ever end silently. Watches
+        // persisted before expiry existed (no expiresAt) keep polling forever.
+        const expiresAt = Number(job.expiresAt || 0);
+        if (!(expiresAt > 0 && now() >= expiresAt)) {
+          logWatch(job, check && check.timedOut ? "idle (check timed out)" : `idle (check exit ${check ? check.code : "?"})`);
+          return { ok: false, status: "watch-idle", skipped: true };
+        }
+        logWatch(job, `expired without firing (check exit ${check ? check.code : "?"}) — waking agent`);
+        // Expiry ends the watch's window: one-shot removal even for --repeat
+        // (the woken agent re-arms if still wanted). Persisted so a retry of a
+        // failed expiry fire keeps the same semantics across restarts.
+        try {
+          const marked = jobsStore.update(job.id, { repeat: false, watchExpired: true });
+          if (marked) job = marked;
+          else { job.repeat = false; job.watchExpired = true; }
+        } catch (_) { job.repeat = false; job.watchExpired = true; }
+      } else {
+        logWatch(job, "triggered (check passed) — waking agent");
+        if (job.watchExpired) {
+          // A prior expiry fire failed and the condition came true before the
+          // retry: report it as a real trigger, not an expiry.
+          try {
+            const cleared = jobsStore.update(job.id, { watchExpired: false });
+            if (cleared) job = cleared;
+            else job.watchExpired = false;
+          } catch (_) { job.watchExpired = false; }
+        }
       }
-      logWatch(job, "triggered (check passed) — waking agent");
     }
 
     const adapter = resolveAdapter(job);
@@ -504,7 +533,10 @@ function createSchedulerService(dependencies = {}) {
         return { ok: false, status: "failed", error: stableFailure(error) };
       }
 
-      try { await send(job.check ? `🔔 Watch "${job.label}" triggered` : `Wakeup: ${job.label}`); } catch (_) { /* advisory only */ }
+      const advisory = job.check
+        ? (job.watchExpired ? `⏰ Watch "${job.label}" timed out without triggering — waking anyway` : `🔔 Watch "${job.label}" triggered`)
+        : `Wakeup: ${job.label}`;
+      try { await send(advisory); } catch (_) { /* advisory only */ }
       let result;
       try { result = await runInProvider(prompt, runContext.cwd, null, { ...runOptions, runContext }); }
       catch (error) {
@@ -655,15 +687,21 @@ function createSchedulerService(dependencies = {}) {
   }
 
   // A watch is a cron carrying a shell `check`; it rides the migration-verified
-  // jobs store untouched (check/repeat survive normalizeRunnableJob as extra
-  // fields). Default schedule polls every minute; default is one-shot.
+  // jobs store untouched (check/repeat/expiresAt survive normalizeRunnableJob
+  // as extra fields). Default schedule polls every minute; default is one-shot.
+  // Every new watch gets an expiry (caller's expiresAt or the default timeout)
+  // so it can never idle-poll silently forever.
   function addWatch(spec) {
+    const requestedExpiry = Number(spec.expiresAt);
     return addJob({
       ...spec,
       kind: "cron",
       schedule: spec.schedule || "* * * * *",
       check: String(spec.check || "").trim(),
       repeat: !!spec.repeat,
+      expiresAt: Number.isFinite(requestedExpiry) && requestedExpiry > 0
+        ? requestedExpiry
+        : now() + watchTimeoutMs,
       label: spec.label || String(spec.prompt || "watch").slice(0, 60),
     });
   }
@@ -710,6 +748,7 @@ module.exports = {
   MISSED_WAKEUP_GRACE_MS,
   RETRY_DELAY_MS,
   BUSY_DELAY_MS,
+  DEFAULT_WATCH_TIMEOUT_MS,
   createSchedulerService,
   parseFallbacks,
   terminalRunSucceeded,

package/core/socket-reconnect.js

@@ -0,0 +1,71 @@
+"use strict";
+
+// socket.io-client permanently stops reconnecting when the server REJECTS a
+// handshake (auth middleware next(new Error())): connect_error fires with
+// socket.active === false and the manager never dials again. During the
+// 2026-08-08 outage chat-central booted before Central's MongoDB and rejected
+// every handshake for a few minutes, terminally stranding the whole bot fleet.
+// This wires a manual connect() retry with capped backoff so a rejected
+// handshake is never terminal. A deliberate client-side disconnect() cancels
+// any pending retry and stays final until connect() is called again.
+
+const DEFAULT_INITIAL_DELAY_MS = 2000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+
+function wireTerminalReconnect(socket, opts = {}) {
+  const label = opts.label || "socket";
+  const log = opts.log || ((msg) => console.error(msg));
+  const initialDelay = opts.initialDelayMs || DEFAULT_INITIAL_DELAY_MS;
+  const maxDelay = opts.maxDelayMs || DEFAULT_MAX_DELAY_MS;
+
+  let attempts = 0;
+  let timer = null;
+  let stopped = false;
+
+  const cancel = () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+  };
+
+  const schedule = (why) => {
+    if (stopped || timer) return;
+    const delay = Math.min(initialDelay * 2 ** attempts, maxDelay);
+    attempts += 1;
+    log(`${label}: ${why} — socket.io will not retry on its own; manual connect() in ${Math.ceil(delay / 1000)}s (attempt ${attempts})`);
+    timer = setTimeout(() => {
+      timer = null;
+      if (stopped || socket.connected || socket.active) return;
+      try { socket.connect(); }
+      catch (e) { schedule(`reconnect attempt threw (${e.message})`); }
+    }, delay);
+    if (typeof timer.unref === "function") timer.unref();
+  };
+
+  socket.on("connect", () => { attempts = 0; cancel(); });
+  socket.on("connect_error", (err) => {
+    if (socket.active) return; // transport failure: the manager auto-retries
+    schedule(`handshake rejected (${err && err.message ? err.message : err})`);
+  });
+  socket.on("disconnect", (reason) => {
+    if (reason === "io client disconnect") { cancel(); return; }
+    if (socket.active) return; // the manager auto-reconnects
+    schedule(`disconnected (${reason})`);
+  });
+
+  // disconnect() while wedged emits no event, so intercept the call itself;
+  // connect() re-arms retries for the adapter-restart path.
+  const origDisconnect = socket.disconnect;
+  socket.disconnect = function (...args) {
+    stopped = true;
+    cancel();
+    return origDisconnect.apply(this, args);
+  };
+  const origConnect = socket.connect;
+  socket.connect = function (...args) {
+    stopped = false;
+    return origConnect.apply(this, args);
+  };
+
+  return socket;
+}
+
+module.exports = { wireTerminalReconnect, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS };