bloby-bot 0.53.2 → 0.53.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.53.2",
+  "version": "0.53.5",
   "releaseNotes": [
     "1. New Morphy animation system: config-driven sprites loaded from /morphy/*.json",
     "2. Swapped teleporting (splash) and headphones (bubble + chat) to the new format",

package/supervisor/backend.ts

@@ -8,6 +8,10 @@ let child: ChildProcess | null = null;
 let restarts = 0;
 let lastSpawnTime = 0;
 let intentionallyStopped = false;
+// True once the backend has crash-looped past MAX_RESTARTS and given up — i.e. it's down and
+// will NOT come back without the user fixing the code. The supervisor shows the "backend down"
+// interstitial in this state. Cleared on every spawn attempt (a deliberate restart is "trying again").
+let gaveUp = false;
 const MAX_RESTARTS = 3;
 const STABLE_THRESHOLD = 30_000; // 30s — if backend ran this long, it wasn't a crash loop
 
@@ -39,6 +43,7 @@ export function spawnBackend(port: number): ChildProcess {
   const backendPath = path.join(WORKSPACE_DIR, 'backend', 'index.ts');
   lastSpawnTime = Date.now();
   intentionallyStopped = false;
+  gaveUp = false;
 
   // Clear log file on each restart — only keeps current run
   try { fs.writeFileSync(LOG_FILE, ''); } catch {}
@@ -106,6 +111,7 @@ export function spawnBackend(port: number): ChildProcess {
       log.info(`Restarting backend (${restarts}/${MAX_RESTARTS}, delay ${delay}ms)...`);
       setTimeout(() => spawnBackend(port), delay);
     } else {
+      gaveUp = true;
       log.error('Backend failed too many times. Use Bloby chat to debug.');
     }
   });
@@ -131,27 +137,75 @@ export function stopBackend(): Promise<void> {
   const dying = child;
   child = null;
 
-  stopPromise = new Promise<void>((resolve) => {
-    dying.once('exit', () => {
-      stopPromise = null;
+  const promise = new Promise<void>((resolve) => {
+    let killTimer: ReturnType<typeof setTimeout> | null = null;
+    let finished = false;
+    const done = () => {
+      if (finished) return; // exit + SIGKILL paths can both fire; run once
+      finished = true;
+      if (killTimer) clearTimeout(killTimer);
+      // Only release the shared guard if it still points at THIS stop. A later stopBackend()
+      // may already have installed its own promise; the 3s safety timer (or a late exit) must
+      // never null a *different* stop's guard — that would make isBackendStopping() lie and let
+      // a concurrent spawn race the in-flight kill for the port.
+      if (stopPromise === promise) stopPromise = null;
       resolve();
-    });
+    };
+    dying.once('exit', done);
     dying.kill();
-    // Safety: force kill after 3s if SIGTERM doesn't work
-    setTimeout(() => {
-      try { dying.kill('SIGKILL'); } catch {}
-      stopPromise = null;
-      resolve();
-    }, 3000);
+    // Safety: force kill after 3s if SIGTERM doesn't land.
+    killTimer = setTimeout(() => { try { dying.kill('SIGKILL'); } catch {} done(); }, 3000);
   });
+  stopPromise = promise;
 
-  return stopPromise;
+  return promise;
+}
+
+let restartInFlight: Promise<void> | null = null;
+let rerunRequested = false;
+
+/** Serialized + coalescing backend restart — the single funnel for every deliberate restart
+ *  (file watcher, turn-complete, scheduler pulse, channel manager). Concurrent callers share
+ *  one in-flight restart; a request that arrives mid-restart triggers exactly one more
+ *  stop→spawn cycle afterward, so the final backend was spawned after the latest request. This
+ *  removes the double-spawn-onto-contended-port race of independent stopBackend().then(spawn) chains. */
+export function restartBackend(port: number): Promise<void> {
+  if (restartInFlight) {
+    rerunRequested = true;
+    return restartInFlight;
+  }
+  restartInFlight = (async () => {
+    do {
+      rerunRequested = false;
+      resetBackendRestarts();
+      await stopBackend();
+      spawnBackend(port);
+    } while (rerunRequested);
+  })().finally(() => { restartInFlight = null; });
+  return restartInFlight;
 }
 
 export function isBackendAlive(): boolean {
   return child !== null && child.exitCode === null;
 }
 
+/** True when the backend has crash-looped past MAX_RESTARTS and given up — down and not
+ *  coming back without a code fix. Drives the supervisor's "backend down" interstitial. */
+export function isBackendDead(): boolean {
+  return gaveUp;
+}
+
+/** Read the tail of the backend log (default 100 lines) for the "copy logs" debug helper. */
+export function readBackendLogTail(maxLines = 100): string {
+  try {
+    const text = fs.readFileSync(LOG_FILE, 'utf-8');
+    const lines = text.split('\n');
+    return lines.slice(-maxLines).join('\n').trim();
+  } catch {
+    return '';
+  }
+}
+
 export function isBackendStopping(): boolean {
   return stopPromise !== null;
 }

package/supervisor/bloby-agent.ts

@@ -86,6 +86,12 @@ export function isConversationBusy(conversationId: string): boolean {
   return Object.values(HARNESSES).some((h) => h.isConversationBusy(conversationId));
 }
 
+/** True if ANY conversation in ANY harness is mid-turn. Lets the supervisor defer backend
+ *  restarts during channel/Alexa turns, which don't set the dashboard's agentQueryActive flag. */
+export function anyConversationBusy(): boolean {
+  return Object.values(HARNESSES).some((h) => h.anyConversationBusy());
+}
+
 export async function stopSubAgentTask(conversationId: string, taskId: string): Promise<void> {
   for (const h of Object.values(HARNESSES)) {
     if (h.hasConversation(conversationId)) {

package/supervisor/harnesses/claude.ts

@@ -538,6 +538,13 @@ export function isConversationBusy(conversationId: string): boolean {
   return liveConversations.get(conversationId)?.busy || false;
 }
 
+/** True if ANY live conversation in this harness is mid-turn. Used by the supervisor to defer
+ *  backend restarts during channel/Alexa turns (which don't set the dashboard's agentQueryActive). */
+export function anyConversationBusy(): boolean {
+  for (const c of liveConversations.values()) if (c.busy) return true;
+  return false;
+}
+
 /** Stop a specific background sub-agent task */
 export async function stopSubAgentTask(conversationId: string, taskId: string): Promise<void> {
   const conv = liveConversations.get(conversationId);

package/supervisor/harnesses/codex.ts

@@ -365,7 +365,14 @@ async function startTurn(conv: CodexConversation, content: string, savedFiles?:
     await conv.rpc.request('turn/start', params);
   } catch (err: any) {
     conv.busy = false;
+    conv.currentTurnId = null;
     conv.onMessage('bot:error', { conversationId: conv.id, error: `turn/start failed: ${err.message}` });
+    // turn/start produced no turn, so no turn/completed will arrive to clear the supervisor's
+    // agentQueryActive (set on bot:typing above). Left as-is, that wedges true forever:
+    // backend auto-heal is deferred indefinitely and chat is stuck showing "typing". Tear the
+    // conversation down so bot:conversation-ended fires (which, unlike bot:turn-complete, does
+    // NOT trigger a backend restart) — the next user message cold-starts a fresh thread.
+    teardownConversation(conv.id);
   }
 }
 
@@ -633,6 +640,13 @@ export function isConversationBusy(conversationId: string): boolean {
   return conversations.get(conversationId)?.busy ?? false;
 }
 
+/** True if ANY live conversation in this harness is mid-turn. Used by the supervisor to defer
+ *  backend restarts during channel/Alexa turns (which don't set the dashboard's agentQueryActive). */
+export function anyConversationBusy(): boolean {
+  for (const c of conversations.values()) if (c.busy) return true;
+  return false;
+}
+
 export async function startConversation(
   conversationId: string,
   model: string,

package/supervisor/harnesses/pi/index.ts

@@ -320,6 +320,13 @@ export function isConversationBusy(conversationId: string): boolean {
   return liveConversations.get(conversationId)?.busy || false;
 }
 
+/** True if ANY live conversation in this harness is mid-turn. Used by the supervisor to defer
+ *  backend restarts during channel/Alexa turns (which don't set the dashboard's agentQueryActive). */
+export function anyConversationBusy(): boolean {
+  for (const c of liveConversations.values()) if (c.busy) return true;
+  return false;
+}
+
 /** Pi has no sub-agents yet; provided for interface compatibility. */
 export async function stopSubAgentTask(_conversationId: string, _taskId: string): Promise<void> {
   // no-op for Phase 1

package/supervisor/harnesses/pi/session.ts

@@ -220,8 +220,14 @@ export function createPiSession(init: PiSessionInit): PiSession {
       if (toolUses.length === 0 && !pendingInterleave) break;
     }
 
-    if (!turnErrored) {
-      if (accumulatedText) {
+    // Emit text_end only on a clean turn (don't persist a half-baked answer from an errored
+    // turn). But ALWAYS emit turn_complete on a non-aborted turn — including the errored path
+    // — so the supervisor clears agentQueryActive (set on turn_started). Skipping it on error
+    // wedged the flag true: backend auto-heal stayed deferred and chat stuck in "typing" until
+    // the next successful turn. The 'error' event was already emitted by runOneRound, so the
+    // user still sees the failure. Aborted turns are torn down via bot:conversation-ended.
+    if (!init.abortController.signal.aborted) {
+      if (!turnErrored && accumulatedText) {
         init.onEvent({ type: 'text_end', text: accumulatedText });
       }
       const usedFileTools = Array.from(usedTools).some((t) => FILE_TOOL_NAMES.has(t));
@@ -238,6 +244,12 @@ export function createPiSession(init: PiSessionInit): PiSession {
         } catch (err: any) {
           log.warn(`[pi/session] Turn failed: ${err?.message || err}`);
           init.onEvent({ type: 'error', error: err?.message || String(err) });
+          // A thrown turn emitted no turn_complete either — clear agentQueryActive so auto-heal
+          // and chat aren't wedged. Skip when aborting (teardown emits conversation-ended).
+          // usedFileTools=false is the safe default (it only governs whether to auto-restart now).
+          if (!init.abortController.signal.aborted) {
+            init.onEvent({ type: 'turn_complete', usedFileTools: false });
+          }
         }
       }
     },

package/supervisor/harnesses/types.ts

@@ -57,6 +57,8 @@ export interface Harness {
   endConversation(conversationId: string): void;
   endAllConversations(): void;
   isConversationBusy(conversationId: string): boolean;
+  /** True if ANY conversation in this harness is mid-turn (no id — used to defer backend restarts). */
+  anyConversationBusy(): boolean;
   stopSubAgentTask(conversationId: string, taskId: string): Promise<void>;
   warmUpForLiveConversation(
     model: string,

package/supervisor/index.ts

@@ -11,12 +11,12 @@ import { log } from '../shared/logger.js';
 import { startTunnel, stopTunnel, isTunnelAlive, restartTunnel, startNamedTunnel, restartNamedTunnel } from './tunnel.js';
 import { createWorkerApp } from '../worker/index.js';
 import { closeDb, getSession, getSetting } from '../worker/db.js';
-import { spawnBackend, stopBackend, getBackendPort, isBackendAlive, isBackendStopping, resetBackendRestarts, setBackendEnv } from './backend.js';
+import { spawnBackend, stopBackend, restartBackend, getBackendPort, isBackendAlive, isBackendStopping, isBackendDead, readBackendLogTail, setBackendEnv } from './backend.js';
 import { handleAgentQuery, type AgentQueryRequest } from './agent-api.js';
 import { updateTunnelUrl, startHeartbeat, stopHeartbeat, disconnect } from '../shared/relay.js';
 import {
   startConversation, hasConversation, endConversation, endAllConversations,
-  isConversationBusy, stopSubAgentTask,
+  isConversationBusy, anyConversationBusy, stopSubAgentTask,
   startBlobyAgentQuery, stopBlobyAgentQuery,
   warmUpForLiveConversation,
   type RecentMessage,
@@ -69,6 +69,8 @@ const PLATFORM_ASSETS = new Set([
   '/pi-logo.svg',
   '/codex.svg',
   '/manifest.json',
+  '/what-happened.webm',
+  '/what-happened.mp4',
 ]);
 
 // Directory-prefix platform assets — anything under these is served from supervisor/public/.
@@ -250,6 +252,77 @@ const RECOVERING_HTML = `<!DOCTYPE html><html style="background:#222122"><head><
 </div><script>setTimeout(function(){location.reload()},3000)</script>
 <script src="/bloby/widget.js"></script></body></html>`;
 
+/** Interstitial shown (by the supervisor, not the workspace) when the workspace backend has
+ *  crash-looped and given up. Replaces proxying the dashboard SPA to Vite — which would 503 on
+ *  every /app/api call and, for the common workspace-lock template, misread "no backend" as
+ *  "no password set" and show the lock-setup screen. Embeds the Bloby chat widget so the user
+ *  can ask the agent to fix it inline, a "copy logs" button (last 100 backend log lines baked in
+ *  at render time), and a poll that reloads into the real dashboard once the backend is back. */
+function backendDownPage(logTail: string): string {
+  // Embed logs as a JS string literal; escape `<` so a stray `</script>` in the logs can't break out.
+  const logs = JSON.stringify(logTail && logTail.length ? logTail : '(no backend logs were captured)').replace(/</g, '\\u003c');
+  return `<!DOCTYPE html>
+<html lang="en"><head>
+<meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Backend down · Bloby</title>
+<style>
+  *{margin:0;padding:0;box-sizing:border-box}
+  body{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;background:#0a0a0b;color:#e4e4e7;display:flex;align-items:center;justify-content:center;min-height:100dvh;padding:1.5rem;overflow:hidden}
+  .c{text-align:center;max-width:480px;width:100%;animation:fade-up .6s ease-out both}
+  .video-wrap{position:relative;width:200px;height:200px;margin:0 auto 1.4rem;display:flex;align-items:center;justify-content:center}
+  .video-wrap::before{content:'';position:absolute;inset:-20px;background:radial-gradient(circle,rgba(1,102,255,0.18) 0%,transparent 60%);filter:blur(20px);animation:glow 3s ease-in-out infinite}
+  .video-wrap video{position:relative;width:100%;height:100%;object-fit:contain;pointer-events:none;border-radius:50%}
+  h1{font-size:1.55rem;font-weight:700;margin-bottom:.6rem;background:linear-gradient(135deg,#0166FF,#009AFE,#4AEEFF);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text}
+  p{color:#a1a1aa;line-height:1.6;margin-bottom:.5rem;font-size:.95rem}
+  .lead{color:#e4e4e7;font-size:1rem}
+  .actions{margin-top:1.3rem}
+  button{font:inherit;cursor:pointer;border-radius:10px;padding:.65rem 1.2rem;font-size:.9rem;font-weight:600;border:none;background:linear-gradient(135deg,#0166FF,#0069FE);color:#fff;transition:filter .15s}
+  button:hover{filter:brightness(1.12)}
+  .sub{font-size:.82rem;color:#71717a;display:inline-flex;align-items:center;gap:.5rem;background:#18181b;border:1px solid #27272a;border-radius:9999px;padding:.35rem .9rem;margin-top:1.1rem}
+  .sub .dot{width:8px;height:8px;border-radius:50%;background:linear-gradient(135deg,#0166FF,#009AFE);box-shadow:0 0 8px rgba(1,102,255,.6);animation:pulse 1.6s ease-in-out infinite}
+  .badge{display:block;font-size:.7rem;color:#52525b;margin-top:1.3rem}
+  @keyframes pulse{0%,100%{opacity:1;transform:scale(1)}50%{opacity:.45;transform:scale(.85)}}
+  @keyframes glow{0%,100%{opacity:.55;transform:scale(1)}50%{opacity:1;transform:scale(1.08)}}
+  @keyframes fade-up{0%{opacity:0;transform:translateY(12px)}100%{opacity:1;transform:translateY(0)}}
+</style></head>
+<body><div class="c">
+  <div class="video-wrap"><video autoplay loop muted playsinline>
+    <source src="/what-happened.webm" type="video/webm">
+    <source src="/what-happened.mp4" type="video/mp4">
+  </video></div>
+  <h1>Your app's backend is down</h1>
+  <p class="lead">The workspace server crashed and couldn't restart on its own.</p>
+  <p>Ask your agent to fix it — the chat is right here in the corner. Tap below to copy the logs so it can debug faster.</p>
+  <div class="actions"><button id="copyBtn">Copy logs for your agent</button></div>
+  <div class="sub"><span class="dot"></span><span id="statusText">Watching for recovery…</span></div>
+  <span class="badge">Powered by Bloby</span>
+</div>
+<script>
+(function(){
+  var LOGS = ${logs};
+  var btn = document.getElementById('copyBtn'), statusEl = document.getElementById('statusText');
+  btn.addEventListener('click', function(){
+    var text = 'My workspace backend crashed and will not start. Find and fix the root cause. Last backend logs:\\n\\n' + LOGS;
+    function ok(){ btn.textContent = '✓ Copied — paste it to your agent'; setTimeout(function(){ btn.textContent = 'Copy logs for your agent'; }, 2600); }
+    function fallback(){ var ta=document.createElement('textarea'); ta.value=text; ta.style.position='fixed'; ta.style.opacity='0'; document.body.appendChild(ta); ta.select(); try{ document.execCommand('copy'); ok(); }catch(e){ btn.textContent='Copy failed — open the logs manually'; } document.body.removeChild(ta); }
+    if (navigator.clipboard && navigator.clipboard.writeText) { navigator.clipboard.writeText(text).then(ok).catch(fallback); } else { fallback(); }
+  });
+  var attempt = 0;
+  function retry(){
+    attempt++;
+    fetch('/__bloby/backend-status', { cache:'no-store' })
+      .then(function(r){ return r.json(); })
+      .then(function(s){ if (s && s.alive) { location.reload(); } else { schedule(); } })
+      .catch(schedule);
+  }
+  function schedule(){ statusEl.textContent = 'Watching for recovery… (checked ' + attempt + 'x)'; setTimeout(retry, Math.min(4000, 1500 + attempt*250)); }
+  setTimeout(retry, 2500);
+})();
+</script>
+<script src="/bloby/widget.js"></script>
+</body></html>`;
+}
+
 /** Kill any stale process holding a port. Ensures clean startup after crashes/updates. */
 function killPort(port: number): void {
   try {
@@ -464,6 +537,15 @@ export async function startSupervisor() {
       return;
     }
 
+    // Backend liveness for the "backend down" interstitial's recovery poll. Supervisor-served
+    // (not proxied) so it answers even when the workspace backend is dead, and independent of
+    // whatever routes the user's backend happens to define.
+    if (req.url === '/__bloby/backend-status') {
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({ alive: isBackendAlive(), dead: isBackendDead() }));
+      return;
+    }
+
     // App API routes → proxy to user's backend server
     if (req.url?.startsWith('/app/api')) {
       const backendPath = req.url.replace(/^\/app/, '');
@@ -1271,8 +1353,7 @@ mint();
             const result = await handleAgentQuery(parsed);
 
             if (result.usedFileTools) {
-              resetBackendRestarts();
-              stopBackend().then(() => spawnBackend(backendPort));
+              void doRestart();
               broadcastBloby('app:hmr-update', {});
             }
 
@@ -1697,6 +1778,24 @@ mint();
       } catch { /* fall through to Vite */ }
     }
 
+    // Workspace backend has crash-looped and given up → serve the "backend down" interstitial
+    // for dashboard DOCUMENT navigations, instead of proxying to Vite (which serves the user's
+    // SPA that then 503s on every /app/api call and, for the common workspace-lock template,
+    // misreads the dead backend as "no password set" and shows the lock-setup screen). Scoped to
+    // top-level navigations only (not assets/HMR/XHR) and only when the backend has truly given
+    // up — never during a normal 1–2s restart. The chat PWA (/bloby/*) is served earlier and is
+    // unaffected.
+    const wantsHtml = req.method === 'GET' && (
+      req.headers['sec-fetch-dest'] === 'document' ||
+      req.headers['sec-fetch-mode'] === 'navigate' ||
+      (!req.headers['sec-fetch-dest'] && String(req.headers['accept'] || '').includes('text/html'))
+    );
+    if (wantsHtml && isBackendDead()) {
+      res.writeHead(503, { 'Content-Type': 'text/html', 'Cache-Control': 'no-store, no-cache, must-revalidate' });
+      res.end(backendDownPage(readBackendLogTail(100)));
+      return;
+    }
+
     // Everything else → proxy to dashboard Vite dev server
     console.log(`[supervisor] → dashboard Vite :${vitePorts.dashboard} | ${req.method} ${(req.url || '').split('?')[0]}`);
     const proxy = http.request(
@@ -1931,11 +2030,8 @@ mint();
         currentStreamBuffer = '';
 
         if (eventData.usedFileTools || pendingBackendRestart) {
-          log.info('[orchestrator] Restarting backend (file tools used)');
-          pendingBackendRestart = false;
-          if (backendRestartTimer) { clearTimeout(backendRestartTimer); backendRestartTimer = null; }
-          resetBackendRestarts();
-          stopBackend().then(() => spawnBackend(backendPort));
+          log.info('[orchestrator] Restarting backend (file tools used / pending watcher change)');
+          void doRestart();
         }
         if (pendingUpdate) {
           pendingUpdate = false;
@@ -2536,11 +2632,7 @@ mint();
   startScheduler({
     broadcastBloby,
     workerApi,
-    restartBackend: async () => {
-      resetBackendRestarts();
-      await stopBackend();
-      spawnBackend(backendPort);
-    },
+    restartBackend: () => doRestart(),
     getModel: () => loadConfig().ai.model,
   });
 
@@ -2548,11 +2640,7 @@ mint();
   const channelManager = new ChannelManager({
     broadcastBloby,
     workerApi,
-    restartBackend: async () => {
-      resetBackendRestarts();
-      await stopBackend();
-      spawnBackend(backendPort);
-    },
+    restartBackend: () => doRestart(),
     getModel: () => loadConfig().ai.model,
   });
 
@@ -2586,21 +2674,39 @@ mint();
   const backendDir = path.join(workspaceDir, 'backend');
   let backendRestartTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Single funnel for every DELIBERATE backend restart (file watcher, turn-complete, agent-api
+   *  one-shot, scheduler pulse, channel manager). Clears the deferred-restart flag and the
+   *  debounce timer, then delegates to backend.ts's serialized + coalescing restartBackend so
+   *  concurrent triggers can never double-spawn onto the contended port. */
+  function doRestart(): Promise<void> {
+    pendingBackendRestart = false;
+    if (backendRestartTimer) { clearTimeout(backendRestartTimer); backendRestartTimer = null; }
+    return restartBackend(backendPort);
+  }
+
+  /** True while any surface is mid-turn. Dashboard chat sets agentQueryActive; WhatsApp/Alexa
+   *  turns instead set the harness conv.busy (they don't touch agentQueryActive), so we must
+   *  check both — otherwise an agent editing the backend over a channel would get the backend
+   *  restarted out from under it mid-turn. */
+  const aTurnIsActive = () => agentQueryActive || anyConversationBusy();
+
   function scheduleBackendRestart(reason: string) {
-    if (agentQueryActive) {
-      // Agent is working — don't restart now, flag it for bot:done
+    if (aTurnIsActive()) {
+      // A turn is working — don't restart now; flush at turn-complete (createSharedChatOnMessage)
+      // or via the channel manager's own post-turn restart.
       pendingBackendRestart = true;
       return;
     }
-    // Skip if a stop/restart is already in progress (bot:done handler owns the restart)
+    // Skip if a stop/restart is already in progress (that restart owns the spawn).
     if (isBackendStopping()) return;
     if (backendRestartTimer) clearTimeout(backendRestartTimer);
-    backendRestartTimer = setTimeout(async () => {
-      if (isBackendStopping()) return; // re-check after delay
+    backendRestartTimer = setTimeout(() => {
+      backendRestartTimer = null;
+      // Re-check at fire time: a turn may have started during the 1s debounce window.
+      if (aTurnIsActive()) { pendingBackendRestart = true; return; }
+      if (isBackendStopping()) return;
       log.info(`[watcher] ${reason} — restarting backend...`);
-      resetBackendRestarts();
-      await stopBackend();
-      spawnBackend(backendPort);
+      void doRestart();
     }, 1000);
   }
 
@@ -2610,12 +2716,22 @@ mint();
     scheduleBackendRestart(`Backend file changed: ${filename}`);
   });
 
-  // Watch workspace root for .env changes and .restart trigger
+  // Watch workspace root for .env, dependency, and .restart/.update changes
   const workspaceWatcher = fs.watch(workspaceDir, (_event, filename) => {
     if (!filename) return;
     if (filename === '.env') {
       scheduleBackendRestart('.env changed');
     }
+    if (filename === 'package.json' || filename === 'package-lock.json') {
+      // The agent ran `npm install` to add/fix a backend dependency. Neither watcher otherwise
+      // covers workspace-root deps (backendWatcher only watches backend/; node_modules is huge
+      // and intentionally unwatched). Without this, an install done to fix an ENOENT crash — where
+      // the import already exists so no Write tool fires and usedFileTools stays false — never
+      // restarts the backend, leaving it broken until some unrelated edit. npm install runs inside
+      // the agent's turn, so this defers (like every trigger) and lands at turn-complete, after
+      // the install has fully written package.json + node_modules.
+      scheduleBackendRestart(`workspace dependencies changed (${filename})`);
+    }
     if (filename === '.restart') {
       // Consume the trigger file
       try { fs.unlinkSync(path.join(workspaceDir, '.restart')); } catch {}