esque-bridge 0.6.7 → 0.6.9

package/index.js

@@ -25,6 +25,7 @@ const { spawn } = require('child_process');
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const BRIDGE_VERSION = require('./package.json').version;
 const os = require('os');
 
 // Windows has no POSIX process groups or `.cmd`-aware spawn, so several
@@ -153,14 +154,31 @@ function saveSessions() {
     console.warn('[bridge] could not persist session map:', err.message);
   }
 }
+// Keyed by workdir AS WELL as the esque session id: the sessions file is
+// global (~/.esque-bridge-sessions.json) but Claude Code stores its sessions
+// per project directory — a cliSessionId recorded in project A can never be
+// resumed by a bridge running in project B. Without the workdir in the key,
+// re-pointing a project at a different folder reuses the foreign id and every
+// prompt fails. (Old-format flat entries simply never match → clean restart.)
+function sessionKey(esqueSessionId) {
+  return `${WORKDIR}::${esqueSessionId}`;
+}
 function getCliSessionId(agent, esqueSessionId) {
   if (!esqueSessionId) return null;
-  return sessionMap[agent]?.[esqueSessionId] ?? null;
+  return sessionMap[agent]?.[sessionKey(esqueSessionId)] ?? null;
 }
 function setCliSessionId(agent, esqueSessionId, cliId) {
   if (!cliId || !esqueSessionId) return;
   if (!sessionMap[agent]) sessionMap[agent] = {};
-  sessionMap[agent][esqueSessionId] = cliId;
+  sessionMap[agent][sessionKey(esqueSessionId)] = cliId;
+  saveSessions();
+}
+// Drop a mapping that turned out to be dead (the CLI no longer recognizes the
+// session id) so the next attempt starts a fresh CLI session instead of
+// failing on --resume forever.
+function clearCliSessionId(agent, esqueSessionId) {
+  if (!esqueSessionId || !sessionMap[agent]) return;
+  delete sessionMap[agent][sessionKey(esqueSessionId)];
   saveSessions();
 }
 
@@ -247,9 +265,15 @@ const ADAPTERS = {
     // Aider keeps its own .aider.chat.history.md per-directory, so we
     // don't need to track a session id — every invocation against the
     // same workdir picks up where the last one left off.
-    buildArgs(_prompt) {
+    //
+    // The prompt rides as the --message VALUE (argv, no shell → no injection,
+    // and ARG_MAX comfortably fits blueprint-sized prompts). Aider has no
+    // "--message -  = read stdin" convention; passing '-' would send the
+    // agent a literal one-character message.
+    promptInArgs: true,
+    buildArgs(prompt) {
       return [
-        '--message', '-',           // read message from stdin (we'll pipe it)
+        '--message', prompt,
         '--no-stream',
         '--yes-always',             // skip the "apply edit? y/n" prompts
         '--no-pretty',              // ANSI-free output for parsing
@@ -313,6 +337,12 @@ if (AGENT_TYPE === 'custom') {
 
 // --- Runner ---------------------------------------------------------------
 
+// Kill-handle for whatever agent child is currently running, so shutdown can
+// stop it. The agent is spawned detached into its own process group, which
+// means a terminal Ctrl-C does NOT reach it — without this, the agent keeps
+// editing files after the bridge is gone.
+let activeAgentKill = null;
+
 function runAgent(prompt, esqueSessionId) {
   return new Promise((resolve, reject) => {
     const prevId = getCliSessionId(AGENT_TYPE, esqueSessionId);
@@ -325,10 +355,10 @@ function runAgent(prompt, esqueSessionId) {
     }
 
     // For 'custom', substitute the {prompt} placeholder in argv. For
-    // built-in adapters, the prompt always rides via stdin (avoids
-    // ARG_MAX on long blueprint payloads).
+    // built-in adapters, the prompt rides via stdin (avoids ARG_MAX on long
+    // blueprint payloads) unless the adapter opts into argv delivery.
     let bin = AGENT_BIN;
-    let usesStdin = true;
+    let usesStdin = !adapter.promptInArgs;
     if (AGENT_TYPE === 'custom') {
       bin = argv.shift();
       argv = argv.map((a) => a.replace('{prompt}', prompt));
@@ -359,6 +389,7 @@ function runAgent(prompt, esqueSessionId) {
     const settle = (fn) => (val) => {
       if (settled) return;
       settled = true;
+      if (activeAgentKill === killTree) activeAgentKill = null;
       fn(val);
     };
     const resolveOnce = settle(resolve);
@@ -392,6 +423,8 @@ function runAgent(prompt, esqueSessionId) {
       }
     };
 
+    activeAgentKill = killTree;
+
     const killTimer = setTimeout(() => {
       killTree('SIGTERM');
       // Escalate to SIGKILL if the agent ignores SIGTERM.
@@ -466,6 +499,26 @@ function runAgent(prompt, esqueSessionId) {
   });
 }
 
+// `--resume <id>` fails hard when the CLI no longer recognizes the stored
+// session (its own history GC'd it, or the project moved). Without recovery
+// the SAME dead id is retried on every subsequent prompt — the session is
+// bricked forever. Detect that specific failure, drop the mapping, and rerun
+// once as a fresh CLI session.
+const RESUME_FAIL_RE = /no conversation found|session.*not found|unknown session|invalid session/i;
+async function runAgentResilient(prompt, esqueSessionId) {
+  const prevId = getCliSessionId(AGENT_TYPE, esqueSessionId);
+  try {
+    return await runAgent(prompt, esqueSessionId);
+  } catch (err) {
+    if (prevId && RESUME_FAIL_RE.test(String(err && err.message))) {
+      console.warn('[bridge] stored CLI session is gone — retrying as a fresh session');
+      clearCliSessionId(AGENT_TYPE, esqueSessionId);
+      return runAgent(prompt, esqueSessionId);
+    }
+    throw err;
+  }
+}
+
 // --- HTTP server ----------------------------------------------------------
 
 const app = express();
@@ -491,7 +544,16 @@ function workdirInfo() {
   } catch {
     /* unreadable dir — report unknown via -1 */
   }
-  return { workdir: WORKDIR, workdirName: path.basename(WORKDIR), empty, git, entries };
+  return {
+    workdir: WORKDIR,
+    workdirName: path.basename(WORKDIR),
+    empty,
+    git,
+    entries,
+    // Lets the app detect a stale bridge and say "restart your bridge"
+    // instead of silently degrading (older bridges lack newer self-healing).
+    version: BRIDGE_VERSION,
+  };
 }
 
 // Public health probe.
@@ -549,11 +611,27 @@ const { execSync } = require('child_process');
 
 let preview = null; // { port, proc, kind, url, tunnel, tunnelProc }
 
+// Kill a spawned command's WHOLE process tree. `proc.kill()` alone signals
+// only the immediate child (`sh`/`npm`) — npm does not reliably forward
+// signals, so the actual dev server survives, keeps the port, and the next
+// preview's waitForPort "succeeds" against the STALE server. That's how the
+// auto-fix loop ends up re-reporting an error the agent already fixed.
+function killCmdTree(proc, signal) {
+  if (!proc || proc.exitCode !== null) return;
+  if (isWindows) {
+    try { spawn('taskkill', ['/pid', String(proc.pid), '/T', '/F'], { stdio: 'ignore' }); }
+    catch { try { proc.kill(); } catch { /* already gone */ } }
+    return;
+  }
+  try { process.kill(-proc.pid, signal); }
+  catch { try { proc.kill(signal); } catch { /* already gone */ } }
+}
+
 function killPreview() {
   if (!preview) return;
-  try { preview.proc && preview.proc.kill('SIGTERM'); } catch {}
-  try { preview.tunnel && preview.tunnel.close(); } catch {}
-  try { preview.tunnelProc && preview.tunnelProc.kill('SIGTERM'); } catch {}
+  killCmdTree(preview.proc, 'SIGTERM');
+  try { preview.tunnel && preview.tunnel.close(); } catch { /* already closed */ }
+  try { preview.tunnelProc && preview.tunnelProc.kill('SIGTERM'); } catch { /* already gone */ }
   preview = null;
 }
 
@@ -574,7 +652,7 @@ function waitForPort(port, timeoutMs) {
 }
 
 function hasCloudflared() {
-  try { execSync('which cloudflared', { stdio: 'ignore' }); return true; }
+  try { execSync(isWindows ? 'where cloudflared' : 'which cloudflared', { stdio: 'ignore' }); return true; }
   catch { return false; }
 }
 
@@ -587,16 +665,24 @@ function openPreviewTunnel(port) {
         stdio: ['ignore', 'pipe', 'pipe'],
       });
       let done = false;
+      // A spawn failure emits 'error' async — unhandled it would crash the bridge.
+      proc.on('error', (e) => {
+        console.error('[preview] cloudflared failed to start:', e.message);
+        if (!done) { done = true; resolve(null); }
+      });
       const scan = (d) => {
         const m = String(d).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
         if (m && !done) { done = true; resolve({ url: m[0], kind: 'cloudflared', tunnelProc: proc }); }
       };
       proc.stdout.on('data', scan);
       proc.stderr.on('data', scan);
-      setTimeout(() => { if (!done) { done = true; try { proc.kill(); } catch {} resolve(null); } }, 25000);
+      setTimeout(() => { if (!done) { done = true; try { proc.kill(); } catch { /* gone */ } resolve(null); } }, 25000);
     } else {
       try {
         const tunnel = await localtunnel({ port });
+        // localtunnel handles emit 'error' on connection blips; with no
+        // listener that's an uncaught exception that kills the process.
+        tunnel.on('error', (e) => console.error('[preview] tunnel error:', e.message));
         resolve({ url: tunnel.url, kind: 'localtunnel', tunnel });
       } catch { resolve(null); }
     }
@@ -605,7 +691,7 @@ function openPreviewTunnel(port) {
 
 // Strip ANSI color codes bundlers embed in their error output.
 function stripAnsi(s) {
-  return String(s).replace(/\[[0-9;]*m/g, '');
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '').replace(/\[[0-9;]*m/g, '');
 }
 
 // Reduce a bundler error (Metro's JSON payload, or raw stderr text) to a
@@ -693,12 +779,16 @@ async function probeBuildError(port) {
 // { code, out } (code -1 on timeout/spawn error).
 function runInWorkdir(cmd, label, timeoutMs) {
   return new Promise((resolve) => {
-    const proc = spawn('sh', ['-c', cmd], { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Windows has no `sh`; let spawn route through cmd.exe there. POSIX gets
+    // its own process group so a timeout kill takes the whole tree.
+    const proc = isWindows
+      ? spawn(cmd, { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'], shell: true })
+      : spawn('sh', ['-c', cmd], { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
     let out = '';
     const onData = (d) => { out = (out + d).slice(-20000); process.stdout.write(`[${label}] ${d}`); };
     proc.stdout.on('data', onData);
     proc.stderr.on('data', onData);
-    const timer = setTimeout(() => { try { proc.kill('SIGKILL'); } catch { /* already gone */ } resolve({ code: -1, out }); }, timeoutMs);
+    const timer = setTimeout(() => { killCmdTree(proc, 'SIGKILL'); resolve({ code: -1, out }); }, timeoutMs);
     proc.on('exit', (code) => { clearTimeout(timer); resolve({ code, out }); });
     proc.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, out: `${out}\n${e.message}` }); });
   });
@@ -735,18 +825,33 @@ function dropUnresolvableDep(npmOutput) {
 // the slow install to Esque (the blueprint says so), so the first preview would
 // otherwise die with "module 'expo' is not installed" / "next: not found".
 // Idempotent — skipped as soon as node_modules exists.
+// Resolves { ok, error }: `error` is a short human/agent-readable summary of
+// WHY installation failed, which flows into the preview's buildError so the
+// phone (and the auto-fix loop, which can rewrite package.json) sees the real
+// cause instead of a generic "couldn't start the preview".
 async function ensureDeps() {
-  let isNode = false, hasModules = false, isExpo = false;
+  const pkgPath = path.join(WORKDIR, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { ok: true, error: null }; // not a Node project
+
+  let pkg;
   try {
-    const pkgPath = path.join(WORKDIR, 'package.json');
-    isNode = fs.existsSync(pkgPath);
-    hasModules = fs.existsSync(path.join(WORKDIR, 'node_modules'));
-    if (isNode) {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-      isExpo = !!(pkg.dependencies && pkg.dependencies.expo);
-    }
-  } catch { isNode = false; }
-  if (!isNode || hasModules) return true;
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch (e) {
+    // A broken package.json must SURFACE, not silently skip the install —
+    // everything downstream fails confusingly otherwise.
+    return { ok: false, error: `package.json is not valid JSON: ${e.message}` };
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const isExpo = !!deps.expo;
+
+  // "Installed" means the project's key dependency RESOLVES — not merely that
+  // node_modules exists. A failed install can leave a partial node_modules
+  // behind, which would otherwise skip reinstall forever.
+  const keyDep = isExpo ? 'expo' : deps.next ? 'next' : Object.keys(pkg.dependencies || {})[0] || null;
+  const hasModules = fs.existsSync(path.join(WORKDIR, 'node_modules'));
+  const keyResolves =
+    !keyDep || fs.existsSync(path.join(WORKDIR, 'node_modules', ...keyDep.split('/')));
+  if (hasModules && keyResolves) return { ok: true, error: null };
 
   console.log('[preview] installing dependencies — first preview, this can take a few minutes…');
   // `--legacy-peer-deps`: AI-scaffolded RN projects routinely pin a React-18 app
@@ -754,17 +859,23 @@ async function ensureDeps() {
   const INSTALL = 'npm install --legacy-peer-deps --no-audit --no-fund';
 
   let ok = false;
+  let lastOut = '';
   // Each failed pass may expose one invented version we can drop, then retry.
   // Bounded so a genuinely unfixable project can't loop forever.
   for (let attempt = 0; attempt < 6; attempt++) {
     const { code, out } = await runInWorkdir(INSTALL, 'npm', 360000);
+    lastOut = out;
     if (code === 0) { ok = true; break; }
     const dropped = dropUnresolvableDep(out);
     if (dropped) { console.log(`[preview] "${dropped}" has no installable version — removed it and retrying…`); continue; }
-    console.error(`[preview] npm install failed (exit ${code}) — preview may fail`);
+    console.error(`[preview] npm install failed (exit ${code})`);
     break;
   }
-  if (!ok) return false;
+  if (!ok) {
+    const tail = stripAnsi(lastOut).split('\n').filter((l) => /npm error|err!/i.test(l)).slice(0, 6).join('\n')
+      || stripAnsi(lastOut).trim().split('\n').slice(-6).join('\n');
+    return { ok: false, error: `npm install failed:\n${tail.slice(0, 600)}` };
+  }
   console.log('[preview] dependencies installed');
 
   // For Expo apps, realign every SDK-managed package to the version the SDK
@@ -776,40 +887,72 @@ async function ensureDeps() {
     if (code === 0) console.log('[preview] aligned dependency versions to the Expo SDK');
     else console.warn('[preview] could not run expo install --fix — continuing with installed versions');
   }
-  return true;
+  return { ok: true, error: null };
 }
 
 async function startPreview(cmd, port) {
   killPreview();
-  // Make sure node_modules exists before the dev server tries to boot.
-  await ensureDeps();
+  // Make sure node_modules exists before the dev server tries to boot. A
+  // failed install IS the build error — surface the npm cause to the phone
+  // (and the auto-fix loop, which can repair package.json) instead of letting
+  // the dev server fail 60s later with something unrelated.
+  const deps = await ensureDeps();
+  if (!deps.ok) {
+    console.error(`[preview] dependency install failed:\n${deps.error}`);
+    return { url: null, buildError: deps.error };
+  }
   console.log(`[preview] starting: ${cmd}  (port ${port})`);
-  const proc = spawn('sh', ['-c', cmd], { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
-  preview = { port, proc, kind: null, url: null, tunnel: null, tunnelProc: null, output: '', buildError: null };
+  // Own process group (POSIX) so killPreview can take down the WHOLE tree —
+  // `npm run dev` does not forward signals to the real dev server. Windows
+  // has no `sh`; route through cmd.exe and kill via taskkill /T.
+  const proc = isWindows
+    ? spawn(cmd, { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'], shell: true })
+    : spawn('sh', ['-c', cmd], { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+  proc.on('error', (e) => console.error(`[preview] dev server spawn failed: ${e.message}`));
+  // Local handle `p`: this function awaits for minutes, and a NEWER preview
+  // may replace/kill the global `preview` meanwhile. Every write below checks
+  // `preview === p` so a superseded run can't deref null, clobber the new
+  // preview's state, or leak its own processes.
+  const p = { port, proc, kind: null, url: null, tunnel: null, tunnelProc: null, output: '', buildError: null };
+  preview = p;
   // Keep a rolling tail of output so the error scanner has something to read.
   const capture = (d) => {
     process.stdout.write(`[preview] ${d}`);
-    if (preview) preview.output = (preview.output + d).slice(-16000);
+    p.output = (p.output + d).slice(-16000);
   };
   proc.stdout.on('data', capture);
   proc.stderr.on('data', capture);
   proc.on('exit', (code) => console.log(`[preview] dev server exited (${code})`));
 
   const up = await waitForPort(port, 60000);
-  if (!up) { console.log('[preview] dev server never opened the port'); return null; }
+  if (preview !== p) { killCmdTree(proc, 'SIGTERM'); return null; } // superseded
+  if (!up) {
+    console.log('[preview] dev server never opened the port');
+    killPreview(); // don't leave a half-started server holding state
+    return null;
+  }
 
   const t = await openPreviewTunnel(port);
-  if (!t) { console.log('[preview] could not open a public tunnel'); return null; }
-  preview.url = t.url;
-  preview.kind = t.kind;
-  preview.tunnel = t.tunnel || null;
-  preview.tunnelProc = t.tunnelProc || null;
+  if (preview !== p) { // superseded while the tunnel opened
+    killCmdTree(proc, 'SIGTERM');
+    if (t) { try { t.tunnel && t.tunnel.close(); } catch { /* closed */ } try { t.tunnelProc && t.tunnelProc.kill(); } catch { /* gone */ } }
+    return null;
+  }
+  if (!t) {
+    console.log('[preview] could not open a public tunnel');
+    killPreview(); // the message tells the user to run it themselves — free the port
+    return null;
+  }
+  p.url = t.url;
+  p.kind = t.kind;
+  p.tunnel = t.tunnel || null;
+  p.tunnelProc = t.tunnelProc || null;
   console.log(`[preview] live at ${t.url}  (${t.kind})`);
 
   // Before handing the URL to the phone, make sure the page will actually
   // render — a dev server can be "up" while its bundle fails to compile.
   const buildError = await probeBuildError(port);
-  if (preview) preview.buildError = buildError;
+  if (preview === p) p.buildError = buildError;
   if (buildError) console.error(`[preview] ⚠ web build is failing:\n${buildError}`);
 
   return { url: t.url, buildError };
@@ -841,19 +984,22 @@ async function applyPreview(text) {
     buildError = result.buildError;
     // Surface the failure as plain text WITHOUT the URL — the app turns any
     // URL in a message into a "Preview Build" pill, and we don't want a pill
-    // that just opens a blank page.
+    // that just opens a blank page. (Covers both dependency-install failures,
+    // where no server is running, and compile failures, where one is.)
     replacement =
-      `⚠️ Preview build failed — the web bundle didn't compile:\n\n` +
+      `⚠️ Preview failed to build:\n\n` +
       `${result.buildError}\n\n` +
-      `Fix that and I'll preview again. (Dev server is still running locally on port ${port}.)`;
+      `Fix that and I'll preview again.`;
   } else {
     replacement = `🔗 Live preview: ${result.url}`;
   }
-  return { text: text.replace(PREVIEW_RE, replacement), buildError };
+  // Function replacement: the text can contain `$&`/`$'`-style sequences
+  // (shell-ish build errors do), which String.replace would otherwise expand.
+  return { text: text.replace(PREVIEW_RE, () => replacement), buildError };
 }
 
 async function runAgentWithPreview(prompt, sessionId) {
-  const result = await runAgent(prompt, sessionId);
+  const result = await runAgentResilient(prompt, sessionId);
   if (!result || !result.text) return result;
 
   const applied = await applyPreview(result.text);
@@ -872,7 +1018,7 @@ async function runAgentWithPreview(prompt, sessionId) {
       `Fix the root cause in the code, then re-emit the ESQUE_PREVIEW marker on ` +
       `its own line. Keep the explanation brief — make the fix and output the marker.`;
     let fix = null;
-    try { fix = await runAgent(fixPrompt, sessionId); } catch (e) { console.error('[preview] auto-fix run failed:', e.message); }
+    try { fix = await runAgentResilient(fixPrompt, sessionId); } catch (e) { console.error('[preview] auto-fix run failed:', e.message); }
     if (fix && fix.text) {
       const fixApplied = await applyPreview(fix.text);
       result.text = `${applied.text}\n\n— Auto-fix attempt —\n${fixApplied.text}`;
@@ -897,7 +1043,11 @@ function newJobId() {
 function gcJobs() {
   const now = Date.now();
   for (const [id, j] of jobs) {
-    if (now - j.createdAt > RESULT_TTL_MS) jobs.delete(id);
+    // Never evict a RUNNING job: a first-preview scaffold (agent run +
+    // dependency install + auto-fix) can legitimately exceed the TTL, and
+    // evicting it mid-run makes the phone's poll 404 with a bogus "bridge
+    // may have restarted" while the agent is still working.
+    if (j.status !== 'working' && now - j.createdAt > RESULT_TTL_MS) jobs.delete(id);
   }
 }
 // Evict expired jobs even on an idle bridge (the POST path GCs too, but an
@@ -912,7 +1062,7 @@ setInterval(gcJobs, 60_000).unref?.();
 async function sendExpoPush(token, kind, sessionId, title, message) {
   if (!token || !String(token).startsWith('ExponentPushToken[')) return;
   try {
-    await fetch('https://exp.host/--/api/v2/push/send', {
+    const r = await fetch('https://exp.host/--/api/v2/push/send', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
       body: JSON.stringify({
@@ -924,11 +1074,30 @@ async function sendExpoPush(token, kind, sessionId, title, message) {
         data: { kind, sessionId },
       }),
     });
+    // Expo reports per-message failures (e.g. DeviceNotRegistered) inside a
+    // 200 response — surface them so dead tokens don't look like delivered
+    // pushes forever.
+    const out = await r.json().catch(() => null);
+    const ticket = out && Array.isArray(out.data) ? out.data[0] : null;
+    if (ticket && ticket.status !== 'ok') {
+      console.warn(`[push] not delivered: ${ticket.message || ticket.details?.error || 'unknown'}`);
+    }
   } catch (e) {
     console.error('[push] send failed:', e.message);
   }
 }
 
+// One agent run at a time. Without this, a follow-up prompt sent while the
+// previous one is still working spawns a SECOND agent mutating the same files,
+// races two --resume's of the same CLI session, and collides in the preview
+// pipeline. A simple promise chain keeps arrival order and isolates failures.
+let runQueue = Promise.resolve();
+function enqueueRun(prompt, sessionId) {
+  const run = runQueue.then(() => runAgentWithPreview(prompt, sessionId));
+  runQueue = run.then(() => undefined, () => undefined);
+  return run;
+}
+
 async function executeHandler(req, res) {
   const body = req.body || {};
   const prompt = String(body.prompt || '');
@@ -954,7 +1123,7 @@ async function executeHandler(req, res) {
     const jobId = newJobId();
     jobs.set(jobId, { status: 'working', text: '', createdAt: Date.now() });
     res.json({ jobId, status: 'working' });
-    runAgentWithPreview(prompt, esqueSessionId)
+    enqueueRun(prompt, esqueSessionId)
       .then((result) => {
         jobs.set(jobId, {
           status: result.isError ? 'blocked' : 'finished',
@@ -1009,7 +1178,7 @@ async function executeHandler(req, res) {
   };
 
   try {
-    const result = await runAgentWithPreview(prompt, esqueSessionId);
+    const result = await enqueueRun(prompt, esqueSessionId);
     finish({
       text: result.text,
       status: result.isError ? 'blocked' : 'finished',
@@ -1097,6 +1266,50 @@ function listenOnFreePort(app, startPort, maxTries = 25) {
   });
 }
 
+// Open the public pairing tunnel. Prefers cloudflared (reliable, no
+// interstitial), and falls back to localtunnel with a HARD timeout — otherwise
+// a slow/down localtunnel.me hangs the whole bridge before the QR ever prints
+// (exactly the "nothing happens after y" failure). Resolves a uniform handle
+// { url, kind, close(), onClose(cb) }, or null if both paths fail.
+function openPairTunnel(port) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val) => { if (!settled) { settled = true; resolve(val); } };
+
+    const tryLocaltunnel = () => {
+      const timer = setTimeout(() => done(null), 20000);
+      localtunnel({ port, subdomain: LT_SUBDOMAIN })
+        .then((t) => {
+          clearTimeout(timer);
+          // localtunnel handles emit 'error' on connection blips; unhandled,
+          // that's an uncaught exception that kills the bridge.
+          t.on('error', (e) => console.error('[bridge] pair tunnel error:', e.message));
+          if (settled) { try { t.close(); } catch { /* already gone */ } return; }
+          done({ url: t.url, kind: 'localtunnel', close: () => { try { t.close(); } catch { /* already gone */ } }, onClose: (cb) => t.on('close', cb) });
+        })
+        .catch(() => { clearTimeout(timer); done(null); });
+    };
+
+    if (!hasCloudflared()) { tryLocaltunnel(); return; }
+
+    const proc = spawn('cloudflared', ['tunnel', '--url', `http://localhost:${port}`], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let gotUrl = false, fellBack = false;
+    const scan = (d) => {
+      const m = String(d).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
+      if (m && !gotUrl) {
+        gotUrl = true;
+        done({ url: m[0], kind: 'cloudflared', close: () => { try { proc.kill(); } catch { /* already gone */ } }, onClose: (cb) => proc.on('exit', cb) });
+      }
+    };
+    proc.stdout.on('data', scan);
+    proc.stderr.on('data', scan);
+    // cloudflared died before emitting a URL, or took too long → fall back once.
+    const fallback = () => { if (!gotUrl && !fellBack) { fellBack = true; try { proc.kill(); } catch { /* already gone */ } tryLocaltunnel(); } };
+    proc.on('exit', fallback);
+    setTimeout(fallback, 25000);
+  });
+}
+
 async function main() {
   if (!fs.existsSync(WORKDIR) || !fs.statSync(WORKDIR).isDirectory()) {
     console.error(`workdir does not exist: ${WORKDIR}`);
@@ -1136,15 +1349,17 @@ async function main() {
     console.log(`  ✓ Using port ${boundPort} instead (${PORT} was taken).`);
   }
 
-  let tunnel;
-  try {
-    tunnel = await localtunnel({ port: boundPort, subdomain: LT_SUBDOMAIN });
-  } catch (err) {
-    console.error('Failed to open localtunnel:', err.message);
-    console.error('If localtunnel.me is blocked, try cloudflared:');
-    console.error(`  cloudflared tunnel --url http://localhost:${boundPort}`);
+  const tunnel = await openPairTunnel(boundPort);
+  if (!tunnel) {
+    console.error('\n  ✗ Could not open a public tunnel.');
+    console.error('    cloudflared and localtunnel.me both failed to respond.');
+    console.error('    Check your internet connection and retry. For the reliable path:');
+    console.error('      brew install cloudflared');
     process.exit(1);
   }
+  if (tunnel.kind === 'localtunnel') {
+    console.log('  (Using localtunnel — install cloudflared for a faster, steadier tunnel: brew install cloudflared)');
+  }
 
   const pairUrl = `esque://pair?url=${encodeURIComponent(tunnel.url)}&secret=${PAIRING_SECRET}&agent=${AGENT_TYPE}`;
 
@@ -1169,8 +1384,14 @@ async function main() {
   console.log('  Press Ctrl-C to stop.');
   console.log('━'.repeat(68));
 
+  let shuttingDown = false;
   const shutdown = (signal) => {
+    shuttingDown = true;
     console.log(`\n  Received ${signal} — closing tunnel…`);
+    // The agent runs detached in its own process group, so the terminal's
+    // Ctrl-C does NOT reach it — stop it explicitly or it keeps editing
+    // files with no bridge attached.
+    try { activeAgentKill && activeAgentKill('SIGTERM'); } catch { /* already gone */ }
     killPreview();
     try {
       tunnel.close();
@@ -1182,7 +1403,20 @@ async function main() {
   process.on('SIGINT', () => shutdown('SIGINT'));
   process.on('SIGTERM', () => shutdown('SIGTERM'));
 
-  tunnel.on('close', () => {
+  // Crash safety net: without this, an unexpected throw leaves the dev
+  // server, both cloudflared tunnels, and a detached agent running headless.
+  process.on('uncaughtException', (err) => {
+    console.error('\n  ✗ Unexpected error:', err && err.stack ? err.stack : err);
+    try { activeAgentKill && activeAgentKill('SIGTERM'); } catch { /* gone */ }
+    killPreview();
+    try { tunnel.close(); } catch { /* closed */ }
+    process.exit(1);
+  });
+
+  // Detect an unexpected tunnel drop (but stay quiet during our own shutdown,
+  // since closing the tunnel also fires this).
+  tunnel.onClose(() => {
+    if (shuttingDown) return;
     console.error('\nTunnel closed unexpectedly. Restart `esque-bridge`.');
     process.exit(1);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esque-bridge",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Desktop-side receiver for the Esque Agent mobile app. Pairs your phone with a local coding-agent CLI (Claude Code, Codex, Aider, or any custom command) via a tunnel + QR code, so prompts run through your subscription instead of per-token API billing.",
   "bin": {
     "esque-bridge": "index.js"