@logicseek/hello-cc 1.1.0-rc.7 → 1.1.0-rc.8

package/CHANGELOG.md

@@ -16,6 +16,24 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 1.1.0-rc.8
+
+### Summary
+
+Background tmux display refreshes no longer block the shared HTTP runtime while
+waiting for terminal snapshots. This preserves responsive Agent coordination
+when a tmux display command is slow, and continues the existing preview channel.
+
+### Highlights
+
+- Bound asynchronous background snapshots, keep one request in flight per
+  session, and preserve the previous display when capture fails or times out.
+- Discard stale results after a session stops, changes panes or is rebound;
+  terminal display refresh does not replace process ownership checks.
+- Retain the rc.7 original-App cooperation path and add delayed-tmux regression
+  coverage. A reproduced synchronous display stall motivated this repair; the
+  exact server-side cause of the earlier macOS CI timeout remains unconfirmed.
+
 ## 1.1.0-rc.7
 
 ### Summary

package/lib/terminal/tmux.mjs

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
 import { CliError } from '../shared/errors.mjs';
 import { shellQuoteArg } from '../format.mjs';
 import {
@@ -284,20 +285,76 @@ export function tmuxCapturePane(pane) {
   return out.endsWith('\n') ? out.slice(0, -1) : out;
 }
 
+// Display-only reads must not block the shared HTTP event loop. Both reads
+// share one deadline; timeout/abort joins the child before a new read starts.
+function readTmuxDisplay(args, { deadline, signal }) {
+  return new Promise((resolve, reject) => {
+    const remaining = deadline - performance.now();
+    if (signal?.aborted || remaining <= 0) {
+      reject(new CliError('TMUX_ERROR', 'tmux display read cancelled or timed out'));
+      return;
+    }
+    const child = spawn('tmux', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    const chunks = [];
+    let bytes = 0, failure = null;
+    const stop = message => {
+      failure ||= new CliError('TMUX_ERROR', message);
+      if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+      // A PATH wrapper can leave a descendant holding stdout after it exits.
+      // Release our read endpoint so that descendant cannot hold close/flight.
+      child.stdout.destroy();
+    };
+    const abort = () => stop('tmux display read cancelled');
+    const timer = setTimeout(() => stop('tmux display read timed out'), Math.ceil(remaining));
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdout.on('data', chunk => {
+      bytes += chunk.length;
+      if (bytes > 1024 * 1024) stop('tmux display output is too large');
+      else if (!failure) chunks.push(chunk);
+    });
+    child.once('error', () => { failure ||= new CliError('TMUX_ERROR', 'tmux display command failed'); });
+    child.once('close', code => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      if (failure) reject(failure);
+      else if (signal?.aborted || performance.now() >= deadline) reject(new CliError('TMUX_ERROR', 'tmux display read cancelled or timed out'));
+      else if (code !== 0) reject(new CliError('TMUX_ERROR', 'tmux display command failed'));
+      else resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+  });
+}
+
+export async function tmuxDisplaySnapshot(pane, { timeoutMs = 5000, signal } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 5000) {
+    throw new CliError('BAD_ARGS', 'tmux display deadline must be 1..5000ms');
+  }
+  const deadline = performance.now() + timeoutMs;
+  const options = { deadline, signal };
+  const output = await readTmuxDisplay(['capture-pane', '-p', '-e', '-S', '-2000', '-t', pane], options);
+  const cursor = await readTmuxDisplay(['display-message', '-p', '-t', pane,
+    '#{cursor_x},#{cursor_y},#{cursor_flag},#{history_size},#{pane_height}'], options);
+  return { captured: output.endsWith('\n') ? output.slice(0, -1) : output, cursor: parseTmuxCursorInfo(cursor) };
+}
+
+function parseTmuxCursorInfo(out) {
+  const [x, y, flag, hist, height] = out.trim().split(',').map((n) => Number.parseInt(n, 10));
+  return {
+    x: Number.isFinite(x) ? x : 0,
+    y: Number.isFinite(y) ? y : 0,
+    visible: flag !== 0,
+    history: Number.isFinite(hist) ? hist : 0,
+    height: Number.isFinite(height) && height > 0 ? height : 1
+  };
+}
+
 // Read the real cursor cell + screen geometry from tmux so the browser mirror
 // can draw the input cursor at the right place. Returns null if unavailable.
 export function tmuxCursorInfo(pane) {
   try {
     const out = runTmux(['display-message', '-p', '-t', pane,
       '#{cursor_x},#{cursor_y},#{cursor_flag},#{history_size},#{pane_height}']);
-    const [x, y, flag, hist, height] = out.trim().split(',').map((n) => Number.parseInt(n, 10));
-    return {
-      x: Number.isFinite(x) ? x : 0,
-      y: Number.isFinite(y) ? y : 0,
-      visible: flag !== 0,
-      history: Number.isFinite(hist) ? hist : 0,
-      height: Number.isFinite(height) && height > 0 ? height : 1
-    };
+    return parseTmuxCursorInfo(out);
   } catch {
     return null;
   }

package/lib/web/runtime-main.mjs

@@ -274,7 +274,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   // refreshPeerIoHeartbeat comes from createTmuxSessions below; wrap it so the
   // reference resolves at call time instead of at this forward-passing site.
   const lazyRefreshPeerIoHeartbeat = (session) => refreshPeerIoHeartbeat(session);
-  const { cursorEscape, tmuxSnapshot, refreshTmuxSnapshot, scheduleTmuxReplace, startTmuxReplacePoller, startTmuxStream, stopTmuxStream } = createTmuxStream({ broadcast, now, refreshPeerIoHeartbeat: lazyRefreshPeerIoHeartbeat, bufferDirectory, withBufferDirectoryLease, shellQuoteArg, ctx, isStopping });
+  const { cursorEscape, tmuxSnapshot, refreshTmuxSnapshot, refreshTmuxSnapshotAsync, invalidateTmuxSnapshot, scheduleTmuxReplace, startTmuxReplacePoller, startTmuxStream, stopTmuxStream } = createTmuxStream({ broadcast, now, refreshPeerIoHeartbeat: lazyRefreshPeerIoHeartbeat, bufferDirectory, withBufferDirectoryLease, shellQuoteArg, ctx, isStopping });
   const prepared = await prepareLocalBus(ctx, opts);
 
   const {
@@ -390,7 +390,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     ctx, sessions, isStopping,
     broadcast, closeSessionClients, hasOpenClients,
     sessionKey, sessionsForProject, resolveSessionPeerId,
-    startTmuxStream, stopTmuxStream, refreshTmuxSnapshot,
+    startTmuxStream, stopTmuxStream, refreshTmuxSnapshotAsync, invalidateTmuxSnapshot,
     connectWebProject, nextProjectSessionId, getSession,
     runtimeProjectContexts,
     scanExternalSessions, adoptExternalSession, removeExternalBufferFiles,

package/lib/web/tmux-sessions.mjs

@@ -85,7 +85,7 @@ export function createTmuxSessions(deps) {
     ctx, sessions, isStopping = () => false,
     broadcast, closeSessionClients, hasOpenClients,
     sessionKey, sessionsForProject, resolveSessionPeerId,
-    startTmuxStream, stopTmuxStream, refreshTmuxSnapshot,
+    startTmuxStream, stopTmuxStream, refreshTmuxSnapshotAsync, invalidateTmuxSnapshot,
     connectWebProject, nextProjectSessionId, getSession,
     runtimeProjectContexts,
     scanExternalSessions, adoptExternalSession, removeExternalBufferFiles,
@@ -873,10 +873,11 @@ export function createTmuxSessions(deps) {
 
   function scheduleTmuxInputRefresh(session) {
     if (isStopping() || session.type !== 'tmux' || !session.pane) return;
+    invalidateTmuxSnapshot(session);
     if (session.inputRefreshTimer) return;
     session.inputRefreshTimer = setTimeout(() => {
       session.inputRefreshTimer = null;
-      if (!isStopping() && session.status === 'running') broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+      if (!isStopping() && session.status === 'running') void refreshTmuxSnapshotAsync(session);
     }, 80);
   }
 

package/lib/web/tmux-stream.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { performance } from 'node:perf_hooks';
-import { runTmux, tmuxCapturePane, tmuxCursorInfo, tmuxCursorPayload } from '../terminal/tmux.mjs';
+import { runTmux, tmuxCapturePane, tmuxCursorInfo, tmuxCursorPayload, tmuxDisplaySnapshot } from '../terminal/tmux.mjs';
 import { CliError } from '../shared/errors.mjs';
 import { ensurePrivateProjectBufferDirectory } from '../runtime/project-path.mjs';
 
@@ -17,8 +17,28 @@ export function createTmuxStream({
   withBufferDirectoryLease,
   shellQuoteArg,
   ctx,
-  isStopping = () => false
+  isStopping = () => false,
+  snapshotTimeoutMs = 5000
 }) {
+  const snapshots = new WeakMap();
+  function snapshotState(session) {
+    let state = snapshots.get(session);
+    if (!state) {
+      state = { generation: 0, revision: 0, enabled: true, flight: null, dirty: false };
+      snapshots.set(session, state);
+    }
+    return state;
+  }
+  function invalidateSnapshot(session, enabled) {
+    const state = snapshotState(session);
+    state.generation++;
+    state.enabled = enabled;
+    state.dirty = false;
+    state.flight?.controller.abort();
+  }
+  function invalidateTmuxSnapshot(session) {
+    snapshotState(session).revision++;
+  }
   function cursorEscape(payload) {
     if (!payload) return '';
     return '\x1b[' + (payload.row + 1) + ';' + (payload.col + 1) + 'H' +
@@ -33,6 +53,7 @@ export function createTmuxStream({
 
   function refreshTmuxSnapshot(session) {
     if (session.type !== 'tmux' || !session.pane) return session.buffer || '';
+    snapshotState(session).revision++;
     try {
       session.buffer = tmuxSnapshot(session);
     } catch {
@@ -41,19 +62,60 @@ export function createTmuxStream({
     return session.buffer || '';
   }
 
+  // Display refreshes share one flight per session. A later input/resize
+  // invalidates that image and coalesces into one follow-up, never a queue.
+  function refreshTmuxSnapshotAsync(session, { invalidate = false } = {}) {
+    const state = snapshotState(session);
+    const active = () => state.enabled && !isStopping() && session.type === 'tmux' &&
+      session.status === 'running' && Boolean(session.pane);
+    if (!active()) return Promise.resolve(false);
+    if (invalidate) state.revision++;
+    if (state.flight) {
+      if (state.flight.revision !== state.revision || state.flight.pane !== session.pane || state.flight.generation !== state.generation) state.dirty = true;
+      return state.flight.promise;
+    }
+    const flight = { pane: session.pane, generation: state.generation, revision: state.revision,
+      controller: new globalThis.AbortController(), promise: null };
+    state.flight = flight;
+    flight.promise = (async () => {
+      let published = false;
+      try {
+        const { captured, cursor } = await tmuxDisplaySnapshot(flight.pane,
+          { timeoutMs: snapshotTimeoutMs, signal: flight.controller.signal });
+        if (active() && state.generation === flight.generation && state.revision === flight.revision &&
+            session.pane === flight.pane && !flight.controller.signal.aborted) {
+          session.buffer = captured + cursorEscape(tmuxCursorPayload(captured, cursor));
+          state.revision++;
+          session.lastBroadcastTime = Date.now();
+          broadcast(session, { type: 'replace', data: session.buffer });
+          published = true;
+        }
+      } catch { /* Keep the last image on timeout, cancellation or tmux errors. */ }
+      finally { if (state.flight === flight) state.flight = null; }
+      if (state.dirty && active()) {
+        state.dirty = false;
+        return refreshTmuxSnapshotAsync(session);
+      }
+      return published;
+    })();
+    return flight.promise;
+  }
+
   function scheduleTmuxReplace(session) {
     if (isStopping() || session.type !== 'tmux' || !session.pane) return;
+    invalidateTmuxSnapshot(session);
     if (session.replaceTimer) clearTimeout(session.replaceTimer);
     session.replaceTimer = setTimeout(() => {
       session.replaceTimer = null;
       if (isStopping()) return;
-      session.lastBroadcastTime = Date.now();
-      broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+      void refreshTmuxSnapshotAsync(session);
     }, 80);
   }
 
   function startTmuxReplacePoller(session, warning = null) {
     if (isStopping()) return;
+    const state = snapshotState(session);
+    if (!state.enabled) invalidateSnapshot(session, true);
     if (session.replacePoller) clearInterval(session.replacePoller);
     if (warning) {
       session.warning = {
@@ -66,13 +128,14 @@ export function createTmuxStream({
       if (isStopping() || session.status !== 'running') return;
       if (Date.now() - (session.lastBroadcastTime || 0) > 4000) {
         session.lastBroadcastTime = Date.now();
-        broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+        void refreshTmuxSnapshotAsync(session);
       }
     }, 1600);
   }
 
   function startTmuxStream(session) {
     if (isStopping()) throw new CliError('RUNTIME_STOPPING', 'Web runtime is stopping');
+    invalidateSnapshot(session, true);
     const safePane = String(session.pane).replace(/[^A-Za-z0-9_-]/g, '');
     const safeId = String(session.id).replace(/[^A-Za-z0-9_.-]/g, '_');
     const streamDirectory = ensurePrivateProjectBufferDirectory((session.ctx || ctx).root);
@@ -131,6 +194,7 @@ export function createTmuxStream({
         }
         if (!chunks.length) return;
         const data = Buffer.concat(chunks).toString();
+        snapshotState(session).revision++;
         session.buffer += data;
         if (session.buffer.length > 250000) session.buffer = session.buffer.slice(-200000);
         session.lastBroadcastTime = Date.now();
@@ -149,6 +213,7 @@ export function createTmuxStream({
   }
 
   function stopTmuxStream(session, { shutdownDeadline = null } = {}) {
+    invalidateSnapshot(session, false);
     const shuttingDown = Number.isFinite(shutdownDeadline);
     const remaining = () => shuttingDown ? shutdownDeadline - performance.now() : Infinity;
     if (session.streamPoller) { clearInterval(session.streamPoller); session.streamPoller = null; }
@@ -189,5 +254,5 @@ export function createTmuxStream({
     }
   }
 
-  return { cursorEscape, tmuxSnapshot, refreshTmuxSnapshot, scheduleTmuxReplace, startTmuxReplacePoller, startTmuxStream, stopTmuxStream };
+  return { cursorEscape, tmuxSnapshot, refreshTmuxSnapshot, refreshTmuxSnapshotAsync, invalidateTmuxSnapshot, scheduleTmuxReplace, startTmuxReplacePoller, startTmuxStream, stopTmuxStream };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "1.1.0-rc.7",
+  "version": "1.1.0-rc.8",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {

package/scripts/regression.mjs

@@ -7127,9 +7127,10 @@ async function syntaxAndHelp() {
   // skip the old hccSource-based migration fanout check (code moved to lib/db/connection.mjs)
   const migrationFanoutSource = '';
   const tmuxStreamSource = fs.readFileSync(path.join(repoRoot, 'lib', 'web', 'tmux-stream.mjs'), 'utf8');
+  // Display refresh responsiveness and stale-frame suppression are exercised
+  // behaviorally in tmux-display-http/refresh.test.mjs.
   for (const expected of [
-    "runTmux(['pipe-pane', '-t', session.pane]);",
-    "broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });"
+    "runTmux(['pipe-pane', '-t', session.pane]);"
   ]) {
     if (!tmuxStreamSource.includes(expected)) fail(`web terminal input refresh support missing: ${expected}`);
   }