@logicseek/hello-cc 1.0.5 → 1.1.0-rc.3

package/lib/web/runtime-main.mjs

@@ -59,18 +59,18 @@ import {
 import { inspectProviderProcess } from '../integrations/peers/processes.mjs';
 import {
   projectRecord,
-  readProjectRegistry,
   registerProject,
   registerProjectActivity
 } from '../runtime/projects.mjs';
 import { resolveProjectDatabase } from '../runtime/project-path.mjs';
 import { contextForProject } from '../runtime/paths.mjs';
 import {
-  clearRuntime,
   writeGlobalRuntime,
   writeRuntime
 } from '../runtime/state.mjs';
 import { createFatalShutdownController } from '../runtime/fatal-shutdown.mjs';
+import { cleanupRuntimeState } from './shutdown-state.mjs';
+import { createShutdownDiagnostics } from './shutdown-diagnostics.mjs';
 import { collectBufferEvidence, externalBufferEvidence, externalBufferOwnerKey, externalBufferSessionIds, readExternalBufferMetadata } from '../runtime/buffer-evidence.mjs';
 import { withBufferDirectoryLease } from '../runtime/buffer-directory-lease.mjs';
 import { applyClockSafeBufferPlan, createBufferGcPlanStore } from '../runtime/buffer-gc-protocol.mjs';
@@ -109,7 +109,7 @@ import {
 import { ensureSelfSignedCert } from '../web/tls.mjs';
 import * as webUiTemplate from '../web/ui-template.mjs';
 import { createWebPeerActions } from '../web/peer-actions.mjs';
-import { createCookieAuth } from '../web/cookie-auth.mjs';
+import { createCookieAuth, createCookieNameForRequest } from '../web/cookie-auth.mjs';
 import { createControlLease } from './control-lease.mjs';
 import { createCodexSessions } from './codex-sessions.mjs';
 import { createTaskResults } from './task-results.mjs';
@@ -190,6 +190,9 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     );
   }
   const processIdentity = runtimeIdentity.identity;
+  const shutdownDiagnostic = createShutdownDiagnostics({ enabled: process.env.HCC_SHUTDOWN_DIAGNOSTICS === '1' });
+  let stopping = false;
+  const isStopping = () => stopping;
   const opts = parseOpts(args, { booleans: ['local', 'no-token', 'no-guidance', 'no-discover', 'tls', 'trust-proxy'] });
   validateOpts('web', opts, ['host', 'port', 'token', 'local', 'no-token', 'no-guidance', 'no-discover', 'tls', 'trust-proxy', 'proxy-origin']);
   validateWebTokenOpts(opts);
@@ -223,6 +226,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     cookieSessionRecord, cookieSessionOk, cookieSocketValid, webAuthMode
   } = createCookieAuth({
     now, ttlSec: WEB_SESSION_TTL_SEC, maxSessions: MAX_WEB_SESSIONS,
+    cookieNameForRequest: createCookieNameForRequest({ useTls, trustProxy, proxyOrigin }),
     requestIsSecure, trustProxy, proxyOrigin, authOk, token
   });
   const webSessionPruner = setInterval(pruneWebSessions, 60000);
@@ -238,7 +242,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     sessionKey, sessionsForProject,
     resolveSessionPeerId, sessionBindingForSerialize,
     serializeBindingSummary, serializeSession,
-    broadcast, hasOpenClients, closeSessionClients: closeSerializedSessionClients
+    broadcast, sendStateSnapshot, hasOpenClients, closeSessionClients: closeSerializedSessionClients
   } = createSessionSerialize({ sessions, cookieSocketValid, ctx, sameResolvedPath,
     localClientObservation: tmuxClientSnapshot.observe
   });
@@ -254,6 +258,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     closeSerializedSessionClients(session);
   }
   function assertSessionControl(session, actionToken, epoch) {
+    const socket = session.actionTokenSockets?.get(actionToken);
+    if (socket && (socket.hccStateClosing || socket.readyState !== 1)) throw new CliError('UNKNOWN_CONTROL_CLIENT', 'Terminal client is reconnecting');
     try { return controlLease.assertControl(session, actionToken, epoch); }
     catch (error) { throw new CliError(error.code || 'CONTROL_REQUIRED', error.message); }
   }
@@ -268,12 +274,13 @@ 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 });
+  const { cursorEscape, tmuxSnapshot, refreshTmuxSnapshot, scheduleTmuxReplace, startTmuxReplacePoller, startTmuxStream, stopTmuxStream } = createTmuxStream({ broadcast, now, refreshPeerIoHeartbeat: lazyRefreshPeerIoHeartbeat, bufferDirectory, withBufferDirectoryLease, shellQuoteArg, ctx, isStopping });
   const prepared = await prepareLocalBus(ctx, opts);
 
-const {
-    projectContexts,
-    newSessionActionToken, rememberProject, knownProjects,
+  const {
+    projectContexts, releaseProjectContexts, dropIdleProjectContextDescriptors,
+    retainProjectContextDescriptor,
+    newSessionActionToken, rememberProject, knownProjects, selectedProjectIdentity,
     resolveWebProjectContext, connectWebProject, projectFromRequest,
     getSession, readActionToken, resolveWebActionSession,
     knownPeerIds, nextProjectSessionId
@@ -328,17 +335,17 @@ const {
   });
 
 
-  rememberProject(ctx);
-  for (const project of readProjectRegistry()) {
-    projectContexts.set(project.root, contextForProject(project.root, project.db, { json: ctx.json }));
-  }
+  // Background discovery must share the retained directory identity used by
+  // HTTP requests, so recovered sessions remain visible under that project.
+  ctx = rememberProject(ctx);
+  knownProjects();
 
 
 
   const {
     reaperPoller, runtimeProjectContexts, runClockAwareReaper, detectClockJump
   } = createLivenessReaper({
-    ctx, projectContexts, sessions,
+    ctx, projectContexts, sessions, isStopping,
     sessionsForProject, connectWebProject,
     now, addEvent,
     peerEvidenceFromDb, mutatePeerWithEvidence, observeClockSafetyOrThrow,
@@ -350,7 +357,7 @@ const {
     collectRuntimeBufferEvidence, prepareRuntimeBufferGc, applyPreparedRuntimeBufferGc,
     runningBufferPathSnapshot, bufferGcPlanStore
   } = createBufferGcRuntime({
-    sessions,
+    sessions, isStopping,
     connectWebProject, runtimeProjectContexts,
     now, runGc, bufferDirectory,
     canonicalRoot, observePeerEvidence, redactedLogText, sameResolvedPath
@@ -358,9 +365,9 @@ const {
 
   const {
     bufsWatchers, externalScanPoller, bufsWatcherSyncPoller,
-    scanExternalSessions, adoptExternalSession, removeExternalBufferFiles
+    scanExternalSessions, adoptExternalSession, removeExternalBufferFiles, stopExternalDiscovery
   } = createExternalSessions({
-    ctx, sessions,
+    ctx, sessions, isStopping,
     sessionKey, broadcast,
     now, tx, connectWebProject,
     bufferDirectory, runtimeProjectContexts,
@@ -380,7 +387,7 @@ const {
     resizeSession, startTmuxManagedSession, restoreTmuxManagedSessions,
     reAdoptOrphanManagedTmuxSessions, reapDeadPeersForProject
   } = createTmuxSessions({
-    ctx, sessions,
+    ctx, sessions, isStopping,
     broadcast, closeSessionClients, hasOpenClients,
     sessionKey, sessionsForProject, resolveSessionPeerId,
     startTmuxStream, stopTmuxStream, refreshTmuxSnapshot,
@@ -403,7 +410,7 @@ const {
     autoAttachPoller, listTmuxPanesOnce, attachedTmuxState,
     reconcileRunningBindings, scanAndAttachDetectedPeers
   } = createAutoAttach({
-    ctx, sessions,
+    ctx, sessions, isStopping,
     connectWebProject, now, addEvent, ACTIVE_PEER_TTL,
     reconcileRunningPeerBindings,
     redactedLogText, sessionsForProject,
@@ -418,7 +425,7 @@ const {
     startPtySession, webSessionBuildOptions, webSessionPeerId,
     normalizeWebSessionInput, startSession
   } = createPtySessions({
-    pty, ctx, sessions,
+    pty, ctx, sessions, isStopping,
     broadcast, closeSessionClients, sessionKey,
     connectWebProject, nextProjectSessionId,
     startTmuxManagedSession,
@@ -431,37 +438,47 @@ const {
   });
   const { startCodexSession, codexAction, stopCodexSession,
     listCodexThreads, readCodexThread, forkCodexThread } = createCodexSessions({
-    sessions, sessionKey, nextProjectSessionId, connectWebProject, upsertPeer,
+    sessions, sessionKey, nextProjectSessionId, connectWebProject, upsertPeer, isStopping,
     upsertCanonicalPeerBinding, observePeerEvidence,
-    broadcast: (session, payload) => {
-      if (payload.type === 'codex_state') {
-        try { observeCodexResults(session, payload.state); }
+    broadcast: (session, payload, event, metadata) => {
+      if (payload.type === 'codex_state' && event?.method !== 'item/agentMessage/delta') {
+        try { observeCodexResults(session, payload.state, event); }
         catch (error) { console.error(redactedLogText(`Result evidence could not be saved: ${error.code || 'UNKNOWN'}`)); }
       }
-      broadcast(session, payload);
+      broadcast(session, payload, metadata);
     }, closeSessionClients, now, addEvent
   });
 
   const restoredTmuxDbs = new Set();
-  const { discoverNativeSessions, nativeAction, closeNativeBridge } = createNativeSessions({
+  const { startNativeSession, listNativeHistory, nativeWorkerHistory, resumeNativeSession, discoverNativeSessions, nativeAction, closeNativeBridge } = createNativeSessions({
     sessions, sessionKey, connectWebProject, broadcast, closeSessionClients, now, addEvent
   });
   let nativeScanRunning = false;
   async function scanNativeProjects() {
-    if (nativeScanRunning) return;
+    if (stopping || nativeScanRunning) return;
     nativeScanRunning = true;
     try { await Promise.allSettled(runtimeProjectContexts().map(discoverNativeSessions)); }
     finally { nativeScanRunning = false; }
   }
   await scanNativeProjects();
-  const nativePoller = setInterval(() => { void scanNativeProjects(); }, 3000);
+  const nativePoller = setInterval(() => {
+    void scanNativeProjects().finally(dropIdleProjectContextDescriptors);
+  }, 3000);
   nativePoller.unref?.();
   for (const projectCtx of runtimeProjectContexts()) {
     const dbKey = path.resolve(projectCtx.dbPath);
     if (restoredTmuxDbs.has(dbKey)) continue;
-    restoredTmuxDbs.add(dbKey);
-    restoreTmuxManagedSessions(projectCtx);
-    reconcileRunningBindings(projectCtx);
+    try {
+      retainProjectContextDescriptor(projectCtx);
+      restoreTmuxManagedSessions(projectCtx);
+      reconcileRunningBindings(projectCtx);
+      restoredTmuxDbs.add(dbKey);
+    } catch (error) {
+      // A path can change after preflight but before the first DB open. The
+      // pane belongs to the original directory, so leave it running and do
+      // not adopt or reconcile it through the replacement pathname.
+      if (error?.code !== 'PROJECT_PATH_CHANGED') throw error;
+    }
   }
   runAutoGc();
 
@@ -471,24 +488,28 @@ const {
     broadcast, serializeSession, sessionsForProject, resolveSessionPeerId,
     parseCookieSid, closeWebSession, issueSession, sessionCookieHeader,
     expiredSessionCookieHeader, cookieSessionOk, webAuthMode,
-    rememberProject, knownProjects, resolveWebProjectContext,
+    rememberProject, knownProjects, selectedProjectIdentity, resolveWebProjectContext,
     connectWebProject, projectFromRequest, getSession, resolveWebActionSession,
     prepareRuntimeBufferGc, applyPreparedRuntimeBufferGc,
     detachTmuxSession, safeTmuxKillPlan, executeTmuxKillPlan,
     killDbProvenTmuxSession, attachTmuxSession, writeSessionInput, startSession,
     startCodexSession, codexAction, stopCodexSession, assertWebWrite,
     listCodexThreads, readCodexThread, forkCodexThread, readSessionResults, writeSessionResult,
-    discoverNativeSessions, nativeAction,
+    startNativeSession, listNativeHistory, nativeWorkerHistory, resumeNativeSession, discoverNativeSessions, nativeAction,
     webStatusSnapshot, webPeerActionForProject,
     now, addEvent, auditPayload, sendMessage,
     getProcessIdentity: () => processIdentity,
     getActualPort: () => actualPort,
-    shutdown, tlsCredentials,
+    shutdown, prepareShutdown, isStopping, shutdownDiagnostic, tlsCredentials,
     renderWebIndex, renderWebLogin, sendWebHtml, webErrorStatus,
     ACTIVE_PEER_TTL, DETECTED_PEER_MAX_AGE, PRODUCT_NAME, VERSION
   });
 
   const dispatchHttp = (req, res) => {
+    if (req.method === 'POST' && req.url?.split('?')[0] === '/api/runtime/stop') {
+      shutdownDiagnostic('request_received');
+      res.once('finish', () => shutdownDiagnostic('response_finished'));
+    }
     void handleWebRequest(req, res).catch((error) => {
       try {
         console.error(redactedLogText(`HTTP request failed: ${error.code || 'UNKNOWN'}`));
@@ -506,6 +527,10 @@ const {
   const wss = new WebSocketServer({ noServer: true });
   server.on('upgrade', (req, socket, head) => {
     try {
+    if (stopping) {
+      socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n');
+      return;
+    }
     const url = requestUrl(req);
     if (!token && !tokenlessRequestAllowed(req, { trustProxy, proxyOrigin })) {
       socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
@@ -547,7 +572,9 @@ const {
       socket.destroy();
       return;
     }
-    const reqCtx = projectFromRequest(req, url);
+    const reqCtx = projectFromRequest(req, url, {
+      requireIdentity: upgradeAuthMode === 'cookie' || cookieSessionOk(req)
+    });
     const id = decodeURIComponent(match[1]);
     const lookupDb = connectWebProject(reqCtx);
     let session;
@@ -561,6 +588,11 @@ const {
       socket.destroy();
       return;
     }
+    const assertSessionProjectUnchanged = () => {
+      reqCtx.rootIdentity?.assertUnchanged();
+      session.ctx?.rootIdentity?.assertUnchanged();
+    };
+    assertSessionProjectUnchanged();
     // ws-5: cap concurrent WS clients per session so the action_token (delivered
     // via the snapshot frame) cannot be harvested by unlimited connections.
     if (session.clients.size >= 4) {
@@ -569,8 +601,11 @@ const {
       return;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
+      try { assertSessionProjectUnchanged(); }
+      catch { ws.close(1008, 'project changed'); return; }
       const connectionActionToken = newSessionActionToken();
       ws.hccCookieAuth = cookieAuth;
+      ws.hccStateSync = url.searchParams.get('state_sync') === '1' && ['app-server', 'native'].includes(session.type);
       session.clients.add(ws);
       if (cookieAuth) cookieAuth.session.sockets.add(ws);
       if (!cookieSocketValid(ws)) {
@@ -585,12 +620,21 @@ const {
       const localClients = session.type === 'tmux' ? serializeSession(session).local_clients : null;
       ws.send(JSON.stringify({ type: 'snapshot', data: refreshTmuxSnapshot(session),
         action_token: connectionActionToken, control: controlLease.status(session, connectionActionToken),
-        local_clients: localClients, ...(session.adapter ? { state: session.adapter.snapshot() } : {}),
-        ...(session.type === 'native' ? { native_state: session.nativeSnapshot() } : {}) }));
+        local_clients: localClients, ...(!ws.hccStateSync && session.adapter ? { state: session.adapter.snapshot() } : {}),
+        ...(!ws.hccStateSync && session.type === 'native' ? { native_state: session.nativeSnapshot() } : {}) }));
+      if (ws.hccStateSync) sendStateSnapshot(session, ws);
       ws.on('message', (raw) => {
         try {
-          if (!cookieSocketValid(ws)) return;
+          if (stopping || !cookieSocketValid(ws) || ws.hccStateClosing) return;
+          assertSessionProjectUnchanged();
           const msg = JSON.parse(String(raw));
+          if (msg.type === 'state_sync_request' && ws.hccStateSync) {
+            if (msg.protocol !== 1 || typeof msg.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,100}$/.test(msg.requestId)) return;
+            if (ws.hccLastStateRecovery && Date.now() - ws.hccLastStateRecovery < 100) { ws.hccStateClosing = true; ws.close(1013, 'state recovery rate exceeded'); return; }
+            ws.hccLastStateRecovery = Date.now();
+            sendStateSnapshot(session, ws, msg.requestId);
+            return;
+          }
           if (msg.type === 'input' && session.status === 'running') {
             if (!tokenMatches(msg.action_token, connectionActionToken)) return;
             assertSessionControl(session, connectionActionToken, msg.epoch);
@@ -618,6 +662,7 @@ const {
           ws.send(JSON.stringify({ type: 'error', error: { code: error.code || 'BAD_REQUEST',
             message: error.code ? error.message : 'Malformed terminal frame' },
             control: controlLease.status(session, connectionActionToken) }));
+          if (error?.code === 'PROJECT_PATH_CHANGED') ws.close(1008, 'project changed');
         }
       });
       ws.on('close', () => {
@@ -635,54 +680,53 @@ const {
   });
 
   let cleanupPromise = null;
+  let shutdownPromise = null;
   let shutdownExitCode = 0;
-  async function performRuntimeCleanup() {
-    tmuxClientSnapshot.close();
-    clearRuntime(ctx);
-    // rob-07: clear this runtime's per-project pointers for every registered
-    // project, not just the primary ctx, so sibling projects don't keep
-    // pointing at a now-dead runtime.
-    try {
-      for (const project of readProjectRegistry()) {
-        clearRuntime({ root: project.root }, process.pid);
-      }
-    } catch {}
-    // sess-02: mark managed (tmux/pty) sessions detached in their own project
-    // DB and clear their runtime_target, so a restart does not consume stale
-    // bindings. Best-effort; never block shutdown.
-    try {
-      const byRoot = new Map();
-      for (const s of sessions.values()) {
-        if (s.status !== 'running' || (s.type !== 'tmux' && s.type !== 'pty')) continue;
-        const peerId = s.peerId || s.id;
-        if (!peerId) continue;
-        const root = path.resolve(s.ctx?.root || s.root || ctx.root);
-        if (!byRoot.has(root)) byRoot.set(root, new Set());
-        byRoot.get(root).add(peerId);
-      }
-      const detachedAt = now();
-      for (const [root, idSet] of byRoot) {
-        const peerIds = [...idSet];
-        if (!peerIds.length) continue;
-        const placeholders = peerIds.map(() => '?').join(',');
-        const cleanupDb = connectWebProject(contextForProject(root, null, { json: ctx.json }));
-        try {
-          cleanupDb.prepare(`UPDATE peers SET status = 'detached' WHERE id IN (${placeholders}) AND status IN ('running','working','busy')`).run(...peerIds);
-          cleanupDb.prepare(`UPDATE peer_bindings SET runtime_target = NULL, updated_at = ? WHERE peer IN (${placeholders})`).run(detachedAt, ...peerIds);
-        } finally {
-          cleanupDb.close();
-        }
-      }
-    } catch {}
+  function prepareShutdown() {
+    if (stopping) return;
+    stopping = true;
+    try { tmuxClientSnapshot.close(); } catch {}
     clearInterval(externalScanPoller);
     clearInterval(autoAttachPoller);
     clearInterval(reaperPoller);
     clearInterval(gcPoller);
     clearInterval(webSessionPruner);
     clearInterval(nativePoller);
-    closeNativeBridge();
-    try { for (const w of bufsWatchers.values()) w.close(); } catch {}
+    try { closeNativeBridge(); } catch {}
+    stopExternalDiscovery();
+    for (const watcher of bufsWatchers.values()) {
+      try { watcher.close(); } catch {}
+    }
+    bufsWatchers.clear();
     clearInterval(bufsWatcherSyncPoller);
+    // Stop queued observation work before yielding to response delivery or
+    // adapter close. Handles and owner-fenced state cleanup remain below.
+    for (const session of sessions.values()) {
+      for (const field of ['outputPoller', 'exitPoller', 'streamPoller', 'replacePoller']) {
+        if (session[field]) clearInterval(session[field]);
+        session[field] = null;
+      }
+      for (const field of ['replaceTimer', 'inputRefreshTimer']) {
+        if (session[field]) clearTimeout(session[field]);
+        session[field] = null;
+      }
+    }
+    shutdownDiagnostic('pollers_closed');
+  }
+  async function performRuntimeCleanup() {
+    const counts = { sessions: sessions.size, running: 0, tmux: 0, appServer: 0, native: 0, external: 0, pty: 0 };
+    for (const session of sessions.values()) {
+      if (session.status === 'running') counts.running++;
+      const type = session.type === 'app-server' ? 'appServer' : session.type || 'pty';
+      if (Object.hasOwn(counts, type) && !['sessions', 'running'].includes(type)) counts[type]++;
+    }
+    shutdownDiagnostic('cleanup_begin', counts);
+    cleanupRuntimeState({ ctx, sessions, connectWebProject, now, ownerIdentity: processIdentity });
+    shutdownDiagnostic('state_cleaned');
+    // Bound admitted tmux work across the whole session set. Nonblocking FIFO
+    // leases avoid contention waits; worker startup/release have their own
+    // bounds, so this is not a hard deadline for the entire runtime shutdown.
+    const tmuxShutdownDeadline = performance.now() + 1000;
     for (const session of sessions.values()) {
       controlLease.forget(session);
       closeSessionClients(session);
@@ -697,12 +741,13 @@ const {
         try { if (session.outputPoller) clearInterval(session.outputPoller); } catch {}
         try { if (session.exitPoller) clearInterval(session.exitPoller); } catch {}
       } else if (session.type === 'tmux') {
-        try { stopTmuxStream(session); } catch {}
+        try { stopTmuxStream(session, { shutdownDeadline: tmuxShutdownDeadline }); } catch {}
         try { if (session.exitPoller) clearInterval(session.exitPoller); } catch {}
       } else {
         try { session.pty.kill(); } catch {}
       }
     }
+    shutdownDiagnostic('sessions_cleaned');
     try { wss.close(); } catch {}
     await new Promise((resolve) => {
       const terminateClients = setTimeout(() => {
@@ -730,19 +775,26 @@ const {
         resolve();
       }
     });
+    shutdownDiagnostic('http_closed');
+    releaseProjectContexts();
+    shutdownDiagnostic('cleanup_end');
   }
   function cleanupRuntime() {
-    if (!cleanupPromise) cleanupPromise = performRuntimeCleanup();
+    // Publish the shared promise before cleanup can synchronously emit events.
+    if (!cleanupPromise) cleanupPromise = Promise.resolve().then(performRuntimeCleanup);
+    prepareShutdown();
     return cleanupPromise;
   }
   function shutdown() {
-    void cleanupRuntime().then(
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = cleanupRuntime().then(
       () => process.exit(shutdownExitCode),
       (error) => {
         console.error(redactedLogText(`[${new Date().toISOString()}] runtime cleanup failed: ${error?.stack || error}`));
         process.exit(1);
       }
     );
+    return shutdownPromise;
   }
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);

package/lib/web/session-serialize.mjs

@@ -1,6 +1,9 @@
 // Session serialization, broadcast, and client management helpers extracted from cmdWeb.
 // These operate on the shared sessions Map and WS clients.
+import path from 'node:path';
 import { selectCurrentTask } from '../core/coordination/automation.mjs';
+import { sameSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
+import { createSessionStateStream, sendStructuredFrame } from './session-state-sync.mjs';
 
 export function createSessionSerialize({
   sessions,
@@ -13,9 +16,21 @@ export function createSessionSerialize({
     return `${projectCtx.root}\0${id}`;
   }
 
+  function sessionIdentityMatches(session, projectCtx) {
+    if (session.ctx?.dbPath && projectCtx.dbPath &&
+        path.resolve(session.ctx.dbPath) !== path.resolve(projectCtx.dbPath)) return false;
+    const owner = session.ctx?.rootIdentity || session.rootIdentity;
+    const requested = projectCtx.rootIdentity;
+    // Legacy contexts without a captured identity retain their old path
+    // behavior; newly managed sessions cannot appear under a rebound root.
+    return owner || requested
+      ? Boolean(owner && requested && sameSelectedCwdIdentity(owner, requested))
+      : true;
+  }
+
   function sessionsForProject(projectCtx) {
     return [...sessions.values()].filter((session) =>
-      sameResolvedPath(session.root, projectCtx.root));
+      sameResolvedPath(session.root, projectCtx.root) && sessionIdentityMatches(session, projectCtx));
   }
 
   function resolveSessionPeerId(db, session) {
@@ -101,9 +116,10 @@ export function createSessionSerialize({
       type: session.type || 'pty',
       task,
       capabilities: session.type === 'app-server'
-        ? ['chat', 'turn-control', 'approval', 'diff', 'plan', 'results', 'history']
+        ? ['chat', 'turn-control', 'approval', 'diff', 'plan', 'results', 'history', 'account-read']
         : session.type === 'native' ? ['chat', 'delivery-receipts', 'results',
-          ...(session.nativeState?.capabilities?.interrupt ? ['turn-control'] : [])] : ['terminal', 'results'],
+          ...(session.nativeState?.capabilities?.interrupt ? ['turn-control'] : []),
+          ...(session.nativeState?.capabilities?.accountRead ? ['account-read'] : [])] : ['terminal', 'results'],
       local_clients: session.type === 'tmux' ? localClientObservation(session) : null,
       executor_id: session.executorId || session.adapter?.snapshot().executorId || session.nativeState?.executorId || null,
       native_connected: session.type === 'native' ? Boolean(session.nativeState?.connected) : null,
@@ -116,11 +132,73 @@ export function createSessionSerialize({
     };
   }
 
-  function broadcast(session, payload) {
-    const text = JSON.stringify(payload);
-    for (const client of [...session.clients]) {
-      if (!cookieSocketValid(client)) { session.clients.delete(client); continue; }
-      if (client.readyState === client.OPEN) client.send(text);
+  function stateStream(session, channel, state, connectingClient = null) {
+    if (!session.stateSync || session.stateSync.executorId !== String(state.executorId || state.owner || '')) {
+      if (session.stateSync) for (const client of session.clients) {
+        if (client.hccStateSync && client !== connectingClient) { client.hccStateClosing = true; client.close(1012, 'executor changed'); }
+      }
+      session.stateSync = createSessionStateStream({ root: session.root || session.ctx?.root || ctx.root,
+        sessionId: session.id, channel, state });
+      return { stream: session.stateSync, initial: true };
+    }
+    return { stream: session.stateSync, initial: false };
+  }
+
+  function sendStateSnapshot(session, client, requestId) {
+    if (!sessionProjectStillSelected(session)) return false;
+    if (!client.hccStateSync || client.hccStateClosing) return false;
+    const channel = session.type === 'native' ? 'native' : session.adapter ? 'codex' : null;
+    if (!channel) return false;
+    const state = channel === 'native' ? session.nativeSnapshot() : session.adapter.snapshot();
+    const { stream, initial } = stateStream(session, channel, state, client.hccStateInitialized ? null : client);
+    if (!initial) {
+      const frame = stream.update(state);
+      // A snapshot can observe deltas waiting in the adapter's 50ms batch.
+      // Advance existing observers too, so their next baseRevision still fits.
+      if (frame) {
+        const encoded = JSON.stringify(frame);
+        for (const observer of session.clients) if (observer !== client && observer.hccStateSync && cookieSocketValid(observer)) sendStructuredFrame(observer, encoded);
+      }
+    }
+    const sent = sendStructuredFrame(client, JSON.stringify(stream.snapshot(requestId)));
+    if (sent) client.hccStateInitialized = true;
+    return sent;
+  }
+
+  function sessionProjectStillSelected(session) {
+    try {
+      (session.ctx?.rootIdentity || session.rootIdentity)?.assertUnchanged();
+      return true;
+    } catch {
+      // Rebinding a selected pathname invalidates Web clients, not the tmux
+      // pane or native worker that still belongs to the original directory.
+      for (const client of session.clients || []) {
+        try { client.close(1008, 'project changed'); } catch {}
+      }
+      return false;
+    }
+  }
+
+  function broadcast(session, payload, metadata) {
+    if (!sessionProjectStillSelected(session)) return;
+    const structured = ['codex_state', 'native_state'].includes(payload.type);
+    const clients = [...session.clients].filter(client => {
+      if (!cookieSocketValid(client)) { session.clients.delete(client); return false; }
+      return client.readyState === client.OPEN && !client.hccStateClosing;
+    });
+    if (!clients.length) return;
+    let synchronizedText = null;
+    if (structured && clients.some(client => client.hccStateSync)) {
+      const { stream, initial } = stateStream(session, payload.type === 'codex_state' ? 'codex' : 'native', payload.state);
+      const frame = initial ? stream.snapshot() : stream.update(payload.state, metadata);
+      if (frame) synchronizedText = JSON.stringify(frame);
+    }
+    const text = !structured || clients.some(client => !client.hccStateSync) ? JSON.stringify(payload) : null;
+    for (const client of clients) {
+      if (structured) {
+        const encoded = client.hccStateSync ? synchronizedText : text;
+        if (encoded) sendStructuredFrame(client, encoded);
+      } else client.send(text);
     }
   }
 
@@ -157,6 +235,7 @@ export function createSessionSerialize({
     serializeBindingSummary,
     serializeSession,
     broadcast,
+    sendStateSnapshot,
     hasOpenClients,
     closeSessionClients
   };