ghostterm 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.3.0 (2026-03-17)
+
+### Stability (35 issues fixed)
+- **Graceful shutdown** — SIGTERM/SIGINT properly kills all PTY sessions, closes relay, cleans PID file
+- **Heartbeat timeout** — detects dead relay within 40s, forces reconnect
+- **Buffer backpressure** — output buffer truncation now tracks `bufferStart` for correct delta sync
+- **Message queue** — queues up to 50 messages while disconnected, flushes on reconnect
+- **Spawn error handling** — node-pty spawn failure no longer crashes companion
+- **Create-session lock** — prevents duplicate session creation from rapid requests
+- **Create-session cooldown** — 1 second minimum between creates
+- **Input size limit** — rejects input payloads over 64KB
+- **Standby timer dedup** — prevents multiple standby preparation timers
+- **Login server cleanup** — closes HTTP server immediately on auth error
+- **VBS launcher cleanup** — deletes temporary launcher.vbs after use
+- **Send error handling** — ws.send wrapped in try-catch
+- **Worker stdio fix** — Windows worker inherits stdin for node-pty console compatibility
+
+### Relay Improvements (deployed separately)
+- Graceful shutdown, email validation, dead pair code reuse, dual companion protection
+- Sessions list caching for instant mobile reconnect
+- Message forwarding validation, health endpoint hardened
+
 ## 1.2.3 (2026-03-17)
 
 ### Features (Frontend)

package/bin/ghostterm.js

@@ -134,6 +134,7 @@ function onSignIn(response) {
               resolve(id_token);
             }, 500);
           } catch (e) {
+            loginServer.close(); // H-6: close server on error
             reject(e);
           }
         });
@@ -171,19 +172,28 @@ async function getToken() {
 const sessions = new Map();
 let nextSessionId = 1;
 const OUTPUT_BUFFER_MAX = 500 * 1024;
+const MAX_INPUT_PAYLOAD = 64 * 1024; // L-1: 64KB max input
+let lastCreateSessionTime = 0; // M-3: create-session cooldown
 
 function createSession() {
   const id = nextSessionId++;
   const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
-  const term = pty.spawn(shell, [], {
-    name: 'xterm-256color',
-    cols: 80,
-    rows: 24,
-    cwd: path.join(os.homedir(), 'Desktop'),
-    env: (() => { const e = { ...process.env, TERM: 'xterm-256color' }; delete e.CLAUDECODE; delete e.CLAUDE_CODE; return e; })(),
-  });
+  let term;
+  try {
+    term = pty.spawn(shell, [], {
+      name: 'xterm-256color',
+      cols: 80,
+      rows: 24,
+      cwd: path.join(os.homedir(), 'Desktop'),
+      env: (() => { const e = { ...process.env, TERM: 'xterm-256color' }; delete e.CLAUDECODE; delete e.CLAUDE_CODE; return e; })(),
+    });
+  } catch (err) {
+    console.error(`  Failed to spawn terminal ${id}: ${err.message}`);
+    sendToRelay({ type: 'error_msg', message: 'Failed to create terminal: ' + err.message });
+    return null;
+  }
 
-  const session = { id, term, outputBuffer: '', bufferSeq: 0, exited: false, pendingData: '', flushTimer: null };
+  const session = { id, term, outputBuffer: '', bufferSeq: 0, bufferStart: 0, exited: false, pendingData: '', flushTimer: null };
 
   console.log(`  Terminal ${id} spawned (PID: ${term.pid})`);
 
@@ -199,7 +209,9 @@ function createSession() {
     session.outputBuffer += data;
     session.bufferSeq += data.length;
     if (session.outputBuffer.length > OUTPUT_BUFFER_MAX) {
+      const before = session.outputBuffer.length;
       session.outputBuffer = session.outputBuffer.slice(-OUTPUT_BUFFER_MAX);
+      session.bufferStart += (before - session.outputBuffer.length); // H-1: track truncation
     }
     session.pendingData += data;
     // Adaptive: small output (keystroke echo) → flush immediately
@@ -230,8 +242,10 @@ function getSessionList() {
 
 // ==================== Standby Session (pre-spawn for instant open) ====================
 let standbySession = null;
+let standbyTimerScheduled = false; // H-2: prevent multiple standby timers
 
 function prepareStandby() {
+  standbyTimerScheduled = false; // H-2: clear flag when actually running
   // Only prepare if under max and no standby exists
   if (standbySession || sessions.size >= MAX_SESSIONS) return;
   standbySession = createSession();
@@ -250,9 +264,13 @@ function useStandbyOrCreate() {
   } else {
     standbySession = null;
     s = createSession();
+    if (!s) return null; // spawn failed
+  }
+  // H-2: Prepare next standby after a short delay (only one timer)
+  if (!standbyTimerScheduled) {
+    standbyTimerScheduled = true;
+    setTimeout(() => prepareStandby(), 1000);
   }
-  // Prepare next standby after a short delay
-  setTimeout(() => prepareStandby(), 1000);
   return s;
 }
 
@@ -261,28 +279,51 @@ let relayWs = null;
 let pairCode = null;
 let reconnectTimer = null;
 let googleToken = null;
+let _creatingSession = false;
+const pendingMessages = []; // M-1: queue messages while disconnected
+const PENDING_MSG_MAX = 50;
 
 function connectToRelay() {
   relayWs = new WebSocket(RELAY_URL);
 
+  let lastPingTime = Date.now();
+  let heartbeatCheck = null;
+
   relayWs.on('open', () => {
     console.log('  Connected to relay');
     if (reconnectTimer) {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
     }
+    lastPingTime = Date.now();
+    // Check for heartbeat timeout every 10s
+    heartbeatCheck = setInterval(() => {
+      if (Date.now() - lastPingTime > 40000) { // 40s no ping → dead
+        console.log('  No heartbeat from relay, forcing reconnect...');
+        if (heartbeatCheck) { clearInterval(heartbeatCheck); heartbeatCheck = null; }
+        relayWs?.close();
+      }
+    }, 10000);
     if (googleToken) {
       sendToRelay({ type: 'auth', token: googleToken });
     }
+    flushPendingMessages(); // M-1: flush queued messages on reconnect
   });
 
   relayWs.on('message', (data) => {
     let msg;
     try { msg = JSON.parse(data); } catch { return; }
+    // Reply to relay heartbeat ping
+    if (msg.type === 'ping') {
+      lastPingTime = Date.now();
+      sendToRelay({ type: 'pong' });
+      return;
+    }
     handleRelayMessage(msg);
   });
 
   relayWs.on('close', () => {
+    if (heartbeatCheck) { clearInterval(heartbeatCheck); heartbeatCheck = null; }
     console.log('  Disconnected, reconnecting in 3s...');
     relayWs = null;
     reconnectTimer = setTimeout(connectToRelay, 3000);
@@ -295,7 +336,30 @@ function connectToRelay() {
 
 function sendToRelay(msg) {
   if (relayWs?.readyState === WebSocket.OPEN) {
-    relayWs.send(JSON.stringify(msg));
+    try {
+      relayWs.send(JSON.stringify(msg));
+    } catch (err) {
+      console.error(`  Send failed: ${err.message}`);
+    }
+  } else {
+    // M-1: queue important messages (not output/pong) while disconnected
+    if (msg.type !== 'output' && msg.type !== 'pong' && msg.type !== 'delta') {
+      if (pendingMessages.length < PENDING_MSG_MAX) {
+        pendingMessages.push(msg);
+      }
+    }
+  }
+}
+
+function flushPendingMessages() {
+  while (pendingMessages.length > 0 && relayWs?.readyState === WebSocket.OPEN) {
+    const msg = pendingMessages.shift();
+    try {
+      relayWs.send(JSON.stringify(msg));
+    } catch (err) {
+      console.error(`  Flush failed: ${err.message}`);
+      break;
+    }
   }
 }
 
@@ -337,17 +401,17 @@ function handleRelayMessage(msg) {
       break;
 
     case 'mobile_connected':
-      console.log('  Mobile connected!');
-      if (sessions.size === 0) {
-        // Use standby session if available, otherwise create new
-        const s = useStandbyOrCreate();
-        sendToRelay({ type: 'sessions', list: getSessionList() });
-        sendToRelay({ type: 'attached', id: s.id });
-      } else {
-        sendToRelay({ type: 'sessions', list: getSessionList() });
+      console.log('  Mobile connected! (sessions: ' + sessions.size + ')');
+      // Always send current session list — let mobile decide if it needs more
+      // Only auto-create first session if mobile has never paired before (sessions.size === 0)
+      // Mobile will send 'create-session' if it needs one
+      sendToRelay({ type: 'sessions', list: getSessionList() });
+      if (sessions.size > 0) {
         const first = sessions.values().next().value;
         if (first) sendToRelay({ type: 'attached', id: first.id });
       }
+      // If no sessions exist, don't auto-create — mobile's relay_paired handler
+      // will send 'create-session' after 2 seconds if currentSessionId is null
       break;
 
     case 'mobile_disconnected':
@@ -356,6 +420,8 @@ function handleRelayMessage(msg) {
 
     case 'input':
       if (msg.sessionId) {
+        // L-1: reject oversized input
+        if (typeof msg.data === 'string' && msg.data.length > MAX_INPUT_PAYLOAD) break;
         const session = sessions.get(msg.sessionId);
         if (session && !session.exited) session.term.write(msg.data);
       }
@@ -365,16 +431,27 @@ function handleRelayMessage(msg) {
       if (msg.sessionId) {
         const session = sessions.get(msg.sessionId);
         if (session && !session.exited) {
-          try { session.term.resize(Math.max(msg.cols, 10), Math.max(msg.rows, 4)); } catch {}
+          try { session.term.resize(Math.min(Math.max(msg.cols, 10), 300), Math.min(Math.max(msg.rows, 4), 100)); } catch {}
         }
       }
       break;
 
     case 'create-session':
+      if (_creatingSession) break; // prevent duplicate creation
+      // M-3: rate limit — at least 1s between creates
+      if (Date.now() - lastCreateSessionTime < 1000) {
+        sendToRelay({ type: 'error_msg', message: 'Please wait before creating another session' });
+        break;
+      }
       if (sessions.size < MAX_SESSIONS) {
+        _creatingSession = true;
+        lastCreateSessionTime = Date.now(); // M-3: track creation time
         const session = useStandbyOrCreate();
-        sendToRelay({ type: 'sessions', list: getSessionList() });
-        sendToRelay({ type: 'attached', id: session.id });
+        _creatingSession = false;
+        if (session) {
+          sendToRelay({ type: 'sessions', list: getSessionList() });
+          sendToRelay({ type: 'attached', id: session.id });
+        }
       } else {
         sendToRelay({ type: 'error_msg', message: `Max ${MAX_SESSIONS} sessions` });
       }
@@ -395,7 +472,7 @@ function handleRelayMessage(msg) {
     case 'sync': {
       const syncSession = sessions.get(msg.id);
       if (!syncSession || syncSession.exited) return;
-      const bufStart = syncSession.bufferSeq - syncSession.outputBuffer.length;
+      const bufStart = syncSession.bufferStart; // H-1: use tracked bufferStart
       if (msg.clientSeq >= syncSession.bufferSeq) {
         sendToRelay({ type: 'delta', data: '', seq: syncSession.bufferSeq, id: msg.id });
       } else if (msg.clientSeq >= bufStart) {
@@ -519,6 +596,7 @@ function handleSubcommand() {
         `ws.Run "${cmd.replace(/"/g, '""')}", 0, False\n`
       );
       require('child_process').execSync(`cscript //nologo "${vbsFile}"`, { stdio: 'ignore' });
+      try { fs.unlinkSync(vbsFile); } catch {} // L-3: clean up VBS launcher
       // Wait for supervisor to write PID file
       const waitUntil = Date.now() + 10000;
       while (Date.now() < waitUntil) {
@@ -556,10 +634,16 @@ function handleSubcommand() {
 
     function spawnWorker() {
       const logFd = fs.openSync(LOG_FILE, 'a');
-      const worker = spawn(process.execPath, [__filename, '--daemon'], {
+      const spawnOpts = {
         stdio: ['ignore', logFd, logFd],
         env: { ...process.env },
-      });
+      };
+      // On Windows, worker needs a console for node-pty (AttachConsole)
+      // Inherit stdin (console) but redirect stdout/stderr to log file
+      if (os.platform() === 'win32') {
+        spawnOpts.stdio = ['inherit', logFd, logFd];
+      }
+      const worker = spawn(process.execPath, [__filename, '--daemon'], spawnOpts);
       worker.on('exit', (code) => {
         if (code === 0) {
           // Clean exit (e.g. from stop command), don't restart
@@ -580,6 +664,34 @@ function handleSubcommand() {
   return 'daemon';
 }
 
+// ==================== Graceful Shutdown (L-6) ====================
+function gracefulShutdown(signal) {
+  console.log(`  Received ${signal}, shutting down...`);
+  // Kill all terminal sessions
+  for (const [id, session] of sessions) {
+    if (!session.exited) {
+      try { session.term.kill(); } catch {}
+    }
+  }
+  sessions.clear();
+  // Kill standby session
+  if (standbySession && !standbySession.exited) {
+    try { standbySession.term.kill(); } catch {}
+    standbySession = null;
+  }
+  // Close relay connection
+  if (relayWs) {
+    try { relayWs.close(); } catch {}
+    relayWs = null;
+  }
+  // Clean PID file
+  try { fs.unlinkSync(PID_FILE); } catch {}
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
 // ==================== Main ====================
 async function main() {
   const mode = handleSubcommand();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostterm",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Mobile terminal for Claude Code — control your PC from your phone",
   "bin": {
     "ghostterm": "bin/ghostterm.js"