@logicseek/hello-cc 1.0.0 → 1.0.2-dsh.3

package/scripts/regression.mjs

@@ -26,6 +26,7 @@ const outDir = path.join(os.tmpdir(), `hcc-reg-out-${testId}`);
 const tmuxSession = `hcc-reg-${process.pid}`;
 const tmuxSocketName = `hcc-reg-${testId}`.replace(/[^A-Za-z0-9_-]/g, '-');
 const secondProjectRoot = path.join(root, 'second-project');
+const TERMINAL_WEBSOCKET_TIMEOUT_MS = 15_000;
 const realHome = process.env.HOME || os.homedir();
 const realRegistryFile = path.join(realHome, '.hello-cc', 'projects.json');
 const realTmuxBin = spawnSync('sh', ['-lc', 'command -v tmux || true'], {
@@ -432,6 +433,13 @@ async function assertTmuxGcPolicy() {
   managedTmuxSessions.add(rootEventSession);
   managedTmuxSessions.add(manualSession);
 
+  // Create the one runtime-managed authority before the bulk synthetic tmux
+  // fixtures. Leaving the runtime up while those sessions are created lets its
+  // five-second orphan scan adopt them and contend with this start on slow CI.
+  const eventActivePane = parsePane(hcc(['peer', 'start', eventPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
+  const eventActiveSession = run('tmux', ['display-message', '-p', '-t', eventActivePane, '#{session_name}']).trim();
+  await stopRuntime();
+
   run('tmux', ['new-session', '-d', '-s', staleSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
   run('tmux', ['new-session', '-d', '-s', peerFilterSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
   run('tmux', ['new-session', '-d', '-s', attachedSession, '-e', `HCC_ROOT=${root}`, '-c', root, 'bash', '--noprofile', '--norc']);
@@ -489,10 +497,27 @@ async function assertTmuxGcPolicy() {
   insertRuntimeTargetBinding(deadBindingPeer, 'shell', 'tmux-gc-binding-dead-session', deadBindingPane);
   insertRuntimeTargetBinding(reusedBindingPeer, 'shell', 'tmux-gc-binding-reused-session', reusedBindingPane);
   insertRuntimeTargetBinding(clientUnknownBindingPeer, 'shell', 'tmux-gc-binding-client-unknown-session', clientUnknownBindingPane);
-  const eventActivePane = parsePane(hcc(['peer', 'start', eventPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
-  const eventActiveSession = run('tmux', ['display-message', '-p', '-t', eventActivePane, '#{session_name}']).trim();
   withMeshDb((db) => {
     const t = Math.floor(Date.now() / 1000) - 30 * 86400;
+    for (const [peer, pane] of [
+      [stalePeer, stalePane],
+      [peerFilterPeer, peerFilterPane],
+      [attachedPeer, attachedPane],
+      [deadBindingPeer, deadBindingPane],
+      [reusedBindingPeer, reusedBindingPane],
+      [clientUnknownBindingPeer, clientUnknownBindingPane]
+    ]) {
+      db.prepare(`
+        UPDATE peer_bindings
+        SET transport = 'tmux', runtime_target = ?, updated_at = ?
+        WHERE peer = ?
+      `).run(pane, t, peer);
+    }
+    db.prepare(`
+      UPDATE peer_bindings
+      SET transport = 'tmux', runtime_target = ?
+      WHERE peer = ?
+    `).run(eventActivePane, eventPeer);
     db.prepare('UPDATE peers SET last_seen_at = ? WHERE id IN (?, ?, ?)').run(t, stalePeer, peerFilterPeer, attachedPeer);
     db.prepare("UPDATE peers SET status = 'exited' WHERE id IN (?, ?)").run(stalePeer, peerFilterPeer);
     db.prepare('UPDATE peer_bindings SET updated_at = ? WHERE peer IN (?, ?, ?)').run(t, stalePeer, peerFilterPeer, attachedPeer);
@@ -1581,32 +1606,82 @@ async function expectWebSocketMarker(peer, marker) {
   await new Promise((resolve, reject) => {
     let sawSnapshot = false;
     let sawMarker = false;
-    const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket timeout`)), 5000);
-    ws.on('open', () => {
-      const result = hccMaybe(['inject', peer, `echo ${marker}`]);
-      if (result.status !== 0) reject(new Error(result.stderr || result.stdout || 'inject failed'));
-    });
+    const ws = trackTerminalControl(new WebSocket(runtimeWsUrl(peer), runtimeWsOptions()));
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
-      if (msg.type === 'snapshot') sawSnapshot = true;
+      if (msg.type === 'snapshot') {
+        sawSnapshot = true;
+        claimTerminalControl(ws).then(() => ws.send(JSON.stringify({
+          type: 'input', data: `echo ${marker}\r`, action_token: ws.hccActionToken,
+          epoch: ws.hccControl.epoch
+        }))).catch(reject);
+      }
       if (['snapshot', 'data', 'replace'].includes(msg.type) && String(msg.data || '').includes(marker)) {
         sawMarker = true;
       }
       if (sawSnapshot && sawMarker) {
         clearTimeout(timer);
+        releaseTerminalControl(ws);
         ws.close();
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+// Keep the private token and public fencing epoch on each test connection.
+// Reconnecting helpers explicitly claim control before an authorized write.
+function trackTerminalControl(ws) {
+  ws.on('message', (raw) => {
+    let message;
+    try { message = JSON.parse(String(raw)); } catch { return; }
+    if (message.action_token) ws.hccActionToken = message.action_token;
+    if (message.control) ws.hccControl = message.control;
+  });
+  return ws;
+}
+
+async function claimTerminalControl(ws) {
+  if (ws.hccControl?.can_control) return ws.hccControl;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(new Error('terminal control claim timeout')), 5000);
+    const finish = (error = null) => {
+      clearTimeout(timer);
+      ws.off('message', onMessage);
+      if (error) reject(error);
+      else resolve(ws.hccControl);
+    };
+    const onMessage = (raw) => {
+      let message;
+      try { message = JSON.parse(String(raw)); } catch { return; }
+      if (message.type === 'error') finish(new Error(`terminal control claim failed: ${JSON.stringify(message.error)}`));
+      else if (message.type === 'control' && message.control?.can_control) finish();
+    };
+    ws.on('message', onMessage);
+    ws.send(JSON.stringify({ type: 'control', action: 'claim', action_token: ws.hccActionToken,
+      epoch: ws.hccControl?.epoch, force: true }));
   });
 }
 
+function releaseTerminalControl(ws) {
+  if (ws?.readyState === WebSocket.OPEN && ws.hccControl?.can_control) {
+    ws.send(JSON.stringify({ type: 'control', action: 'release', action_token: ws.hccActionToken,
+      epoch: ws.hccControl.epoch }));
+  }
+}
+
 async function openTerminalWebSocket(peer) {
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket open timeout`)), 5000);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket open timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('open', () => {
       clearTimeout(timer);
       resolve(ws);
@@ -1626,13 +1701,16 @@ async function openSessionActionChannel(peer, params = {}) {
     for (const [key, value] of Object.entries(params)) {
       if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
     }
-    const ws = new WebSocket(url, runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} action token fetch timeout`)), 5000);
+    const ws = trackTerminalControl(new WebSocket(url, runtimeWsOptions()));
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} action token fetch timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       if (msg.type === 'snapshot') {
         clearTimeout(timer);
-        resolve({ token: msg.action_token || '', ws });
+        resolve({ token: msg.action_token || '', ws, get epoch() { return ws.hccControl?.epoch; } });
       }
     });
     ws.on('error', (err) => { clearTimeout(timer); reject(err); });
@@ -1643,8 +1721,23 @@ async function fetchSessionActionToken(peer, params = {}) {
   return (await openSessionActionChannel(peer, params)).token;
 }
 
+async function stopControlledSession(id, payload = {}, projectRoot = root) {
+  const channel = await openSessionActionChannel(id, { root: projectRoot });
+  try {
+    await claimTerminalControl(channel.ws);
+    return await runtimeFetch(`/api/sessions/${encodeURIComponent(id)}/stop`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...payload, action_token: channel.token, epoch: channel.epoch })
+    }, { root: projectRoot });
+  } finally {
+    await closeTerminalWebSocket(channel.ws);
+  }
+}
+
 async function closeTerminalWebSocket(ws) {
   if (!ws || ws.readyState === WebSocket.CLOSED) return;
+  releaseTerminalControl(ws);
   await new Promise((resolve) => {
     const timer = setTimeout(() => {
       try { ws.terminate(); } catch {}
@@ -1667,12 +1760,16 @@ async function fetchTerminalSnapshot(peer, params = {}) {
     for (const [key, value] of Object.entries(params)) {
       if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
     }
-    const ws = new WebSocket(url, runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} terminal snapshot timeout`)), 5000);
+    const ws = trackTerminalControl(new WebSocket(url, runtimeWsOptions()));
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} terminal snapshot timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       if (msg.type !== 'snapshot') return;
       clearTimeout(timer);
+      releaseTerminalControl(ws);
       try { ws.close(); } catch {}
       resolve(String(msg.data || ''));
     });
@@ -1759,12 +1856,12 @@ async function openCookieTerminalWebSocket(peer, sid, params = {}) {
   }
   return new Promise((resolve, reject) => {
     let settled = false;
-    const ws = new WebSocket(url, {
+    const ws = trackTerminalControl(new WebSocket(url, {
       headers: {
         Cookie: `hcc_sid=${sid}`,
         Origin: new URL(baseUrl).origin
       }
-    });
+    }));
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
@@ -1885,25 +1982,30 @@ async function assertEvictionClosesCookieWebSocket(peer, params = {}) {
 async function expectResizeReplaceSnapshot(peer, marker) {
   await new Promise((resolve, reject) => {
     let sawSnapshot = false;
-    const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} resize replace timeout`)), 5000);
-    ws.on('open', () => {
-      const result = hccMaybe(['inject', peer, `echo ${marker}`]);
-      if (result.status !== 0) reject(new Error(result.stderr || result.stdout || 'inject failed'));
-    });
+    const ws = trackTerminalControl(new WebSocket(runtimeWsUrl(peer), runtimeWsOptions()));
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} resize replace timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       if (msg.type === 'snapshot') {
         sawSnapshot = true;
-        ws.send(JSON.stringify({ type: 'resize', cols: 96, rows: 28 }));
+        claimTerminalControl(ws).then(() => {
+          ws.send(JSON.stringify({ type: 'input', data: `echo ${marker}\r`,
+            action_token: ws.hccActionToken, epoch: ws.hccControl.epoch }));
+          ws.send(JSON.stringify({ type: 'resize', cols: 96, rows: 28,
+            action_token: ws.hccActionToken, epoch: ws.hccControl.epoch }));
+        }).catch(reject);
       }
       if (sawSnapshot && msg.type === 'replace' && String(msg.data || '').includes(marker)) {
         clearTimeout(timer);
+        releaseTerminalControl(ws);
         ws.close();
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
   });
 }
 
@@ -1913,18 +2015,21 @@ async function expectWebSocketInputVisible(peer, marker) {
     let sent = false;
     let sawMarkerAfterInput = false;
     let sawFrameAfterInput = false;
-    let actionToken = '';
-    const ws = new WebSocket(runtimeWsUrl(peer), runtimeWsOptions());
-    const timer = setTimeout(() => reject(new Error(`${peer} websocket input visibility timeout`)), 5000);
+    const ws = trackTerminalControl(new WebSocket(runtimeWsUrl(peer), runtimeWsOptions()));
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch {}
+      reject(new Error(`${peer} websocket input visibility timeout`));
+    }, TERMINAL_WEBSOCKET_TIMEOUT_MS);
     ws.on('message', (raw) => {
       const msg = JSON.parse(String(raw));
       const data = String(msg.data || '');
       if (msg.type === 'snapshot') {
         sawSnapshot = true;
-        if (msg.action_token) actionToken = msg.action_token;
         if (!sent) {
           sent = true;
-          ws.send(JSON.stringify({ type: 'input', data: `echo ${marker}\r`, action_token: actionToken }));
+          claimTerminalControl(ws).then(() => ws.send(JSON.stringify({ type: 'input',
+            data: `echo ${marker}\r`, action_token: ws.hccActionToken,
+            epoch: ws.hccControl.epoch }))).catch(reject);
         }
         return;
       }
@@ -1934,11 +2039,12 @@ async function expectWebSocketInputVisible(peer, marker) {
       }
       if (sawSnapshot && sawFrameAfterInput && sawMarkerAfterInput) {
         clearTimeout(timer);
+        releaseTerminalControl(ws);
         ws.close();
         resolve();
       }
     });
-    ws.on('error', reject);
+    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
   });
 }
 
@@ -1948,7 +2054,7 @@ async function assertTerminalInputTokenRejected(peer, suppliedToken, params = {}
     for (const [key, value] of Object.entries(params)) {
       if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
     }
-    const ws = new WebSocket(url, runtimeWsOptions());
+    const ws = trackTerminalControl(new WebSocket(url, runtimeWsOptions()));
     const rejectedMarker = `REJECTED_${testId}_${Math.random().toString(16).slice(2)}`;
     const acceptedMarker = `ACCEPTED_${testId}_${Math.random().toString(16).slice(2)}`;
     let snapshotToken = '';
@@ -1965,6 +2071,7 @@ async function assertTerminalInputTokenRejected(peer, suppliedToken, params = {}
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      releaseTerminalControl(ws);
       try { ws.close(); } catch {}
       if (err) reject(err);
       else resolve();
@@ -1975,7 +2082,7 @@ async function assertTerminalInputTokenRejected(peer, suppliedToken, params = {}
       output += String(message.data || '');
       if (message.type === 'snapshot' && !snapshotToken) {
         snapshotToken = message.action_token || '';
-        const frame = { type: 'input', data: `echo ${rejectedMarker}\r` };
+        const frame = { type: 'input', data: `echo ${rejectedMarker}\r`, epoch: ws.hccControl.epoch };
         if (suppliedToken !== undefined) frame.action_token = suppliedToken;
         ws.send(JSON.stringify(frame));
         setTimeout(() => {
@@ -1984,11 +2091,12 @@ async function assertTerminalInputTokenRejected(peer, suppliedToken, params = {}
             return;
           }
           checkedRejected = true;
-          ws.send(JSON.stringify({
+          claimTerminalControl(ws).then(() => ws.send(JSON.stringify({
             type: 'input',
             data: `echo ${acceptedMarker}\r`,
-            action_token: snapshotToken
-          }));
+            action_token: snapshotToken,
+            epoch: ws.hccControl.epoch
+          }))).catch(finish);
         }, 350);
       }
       if (checkedRejected && output.includes(acceptedMarker)) finish();
@@ -2495,7 +2603,8 @@ async function cookieSessionExpiryWorkflow() {
     ws.send(JSON.stringify({
       type: 'input',
       data: `echo ${marker}\r`,
-      action_token: ws.hccActionToken
+      action_token: ws.hccActionToken,
+      epoch: ws.hccControl.epoch
     }));
     const closeResult = await closed;
     if (closeResult.code !== 4001 || !closeResult.reason.includes('session expired')) {
@@ -2515,7 +2624,7 @@ async function cookieSessionExpiryWorkflow() {
       try { ws.terminate(); } catch {}
     }
     try {
-      await runtimeFetch(`/api/sessions/${encodeURIComponent(expirySessionId)}/stop`, { method: 'POST' }, { root });
+      await stopControlledSession(expirySessionId);
     } catch {}
     await stopRuntime();
   }
@@ -2564,7 +2673,8 @@ async function webSecretRedactionWorkflow() {
     }, { root });
     if (!create.ok) fail(`redaction PTY create failed with status ${create.status}`);
     terminalWs = await openCookieTerminalWebSocket(sessionId, sid, { root });
-    terminalWs.send(JSON.stringify({ type: 'resize', cols: 90, rows: 28 }));
+    terminalWs.send(JSON.stringify({ type: 'resize', cols: 90, rows: 28,
+      action_token: terminalWs.hccActionToken, epoch: terminalWs.hccControl.epoch }));
 
     const badProject = await fetch(new URL(`/api/projects?token=${encodeURIComponent(secret)}`, runtime.base_url), {
       method: 'POST',
@@ -2609,7 +2719,7 @@ async function webSecretRedactionWorkflow() {
       try { terminalWs.terminate(); } catch {}
     }
     try {
-      await runtimeFetch(`/api/sessions/${encodeURIComponent(sessionId)}/stop`, { method: 'POST' }, { root });
+      await stopControlledSession(sessionId);
     } catch {}
     await stopRuntime();
   }
@@ -4031,6 +4141,10 @@ async function multiProjectWebWorkflow() {
         !arbitraryRuntime.process_identity?.commandHash) {
       fail(`project API runtime pointer omitted the shared runtime fingerprint:\n${JSON.stringify(arbitraryRuntime, null, 2)}`);
     }
+    const arbitraryBufs = path.join(arbitraryRoot, '.hello-cc', 'bufs');
+    if (fs.existsSync(arbitraryBufs)) {
+      fail('project registration eagerly created the optional buffer directory');
+    }
     fs.rmSync(path.join(arbitraryRoot, '.hello-cc'), { recursive: true, force: true });
     await sleep(1250);
     if (fs.existsSync(path.join(arbitraryRoot, '.hello-cc'))) {
@@ -4322,17 +4436,16 @@ async function multiProjectWebWorkflow() {
   }
   for (const expected of [
     'id="langSelect"',
-    "localStorage.getItem('hcc.lang')",
-    "localStorage.setItem('hcc.lang', lang)",
-    "document.documentElement.lang = lang === 'zh' ? 'zh-CN' : 'en'",
-    "zh: {",
-    "language: '语言'",
-    "projectState: '项目状态'",
-    "noSessionSelected: '未选择会话'",
-    "sendMessage: '发送消息'",
-    "peers: '协作方'",
-    "noPeers: '没有协作方。'",
-    "'status.active': '活跃'",
+    'window.hccUi',
+    'hccUi.language',
+    'hccUi.tr(key',
+    '"language":"语言"',
+    '"projectState":"项目状态"',
+    '"noSessionSelected":"未选择会话"',
+    '"sendMessage":"发送消息"',
+    '"peers":"协作方"',
+    '"noPeers":"没有协作方。"',
+    '"status.active":"活跃"',
     "data-i18n=\"language\"",
     "data-i18n-placeholder=\"projectPathPlaceholder\"",
     "data-i18n-title=\"collapseSidebar\"",
@@ -4379,7 +4492,7 @@ async function multiProjectWebWorkflow() {
     'setPointerCapture',
     'sideIsCollapsed(opposite) ? 0',
     'Math.abs(delta) <= 3',
-    "localStorage.setItem('hcc.collapse.' + side, on ? '1' : '0');\n      applySideWidths();",
+    "hccUi.safeSet('hcc.collapse.' + side, on ? '1' : '0');\n      applySideWidths();",
     'cursor: col-resize'
   ]) {
     if (!html.includes(expected)) fail(`web layout missing resizable sidebar support: ${expected}`);
@@ -4389,13 +4502,13 @@ async function multiProjectWebWorkflow() {
   }
   for (const expected of [
     'function stateCardCollapsed(section)',
-    "localStorage.getItem('hcc.stateCard.' + section + '.collapsed')",
+    "hccUi.safeGet('hcc.stateCard.' + section + '.collapsed')",
     'function stateCardHtml(section, title, count, bodyHtml)',
     'state-card-toggle',
     'aria-expanded=',
     'state-card-collapsed',
     'function bindStateCardToggles()',
-    "localStorage.setItem('hcc.stateCard.' + section + '.collapsed'",
+    "hccUi.safeSet('hcc.stateCard.' + section + '.collapsed'",
     "stateCardHtml('automation'",
     "stateCardHtml('timeline'",
     "stateCardHtml('messages'",
@@ -4427,11 +4540,18 @@ async function multiProjectWebWorkflow() {
   for (const expected of [
     'term.onData((data) => {',
     'sendTerminalInput(data);',
-    'function flushPendingTerminalInput(id, socket)',
-    "socket.send(JSON.stringify({ type: 'input', data, action_token: actionToken }))"
+    "function sendTerminalInput(data, inputId = '')",
+    'epoch: controlEpoch()',
+    "...(inputId ? { input_id: inputId } : {})",
+    "msg.type === 'input_ack' && handoffStore.acknowledge(currentProject, id, msg.input_id)",
+    'handoffStore.uncertain(currentProject, id)',
+    'Connection recovery never replays terminal input or a draft.'
   ]) {
     if (!html.includes(expected)) fail(`web terminal input forwarding missing: ${expected}`);
   }
+  if (html.includes('flushPendingTerminalInput') || html.includes('pendingTerminalInput')) {
+    fail('web terminal recovery must not buffer or replay terminal input');
+  }
   if (!html.includes("stateCardHtml('timeline'") || !html.includes('renderTimelineItem') || !html.includes('bodyPinned') || !html.includes('refreshCurrentState')) {
     fail('web state panel missing collaboration timeline or refresh routing');
   }
@@ -4483,14 +4603,7 @@ async function multiProjectWebWorkflow() {
     return json.session;
   };
   const stopSession = async (id, payload = null, projectRoot = root) => {
-    const options = payload
-      ? {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload)
-        }
-      : { method: 'POST' };
-    const response = await runtimeFetch(`/api/sessions/${encodeURIComponent(id)}/stop`, options, { root: projectRoot });
+    const response = await stopControlledSession(id, payload || {}, projectRoot);
     const json = await response.json();
     if (!response.ok) fail(`web provider session stop failed: ${JSON.stringify(json)}`);
     return json.session;
@@ -4638,7 +4751,8 @@ async function multiProjectWebWorkflow() {
       const inputResponse = await cookieRuntimeFetch(inputRoute, cookieAdmin, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ data: `echo ${marker}\r` })
+        body: JSON.stringify({ data: `echo ${marker}\r`, action_token: cookieAdminWs.hccActionToken,
+          epoch: cookieAdminWs.hccControl.epoch })
       }, { root });
       if (!inputResponse.ok) fail(`same-origin cookie administrator input returned ${inputResponse.status}`);
     });
@@ -4661,7 +4775,7 @@ async function multiProjectWebWorkflow() {
     const cookieStop = await cookieRuntimeFetch(stopRoute, cookieAdmin, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: '{}'
+      body: JSON.stringify({ action_token: cookieAdminWs.hccActionToken, epoch: cookieAdminWs.hccControl.epoch })
     }, { root });
     if (!cookieStop.ok) fail(`same-origin cookie administrator stop returned ${cookieStop.status}`);
   } finally {
@@ -4758,14 +4872,16 @@ async function multiProjectWebWorkflow() {
     kind: 'shell',
     command: 'bash --noprofile --norc'
   });
-  const encodedActionToken = await fetchSessionActionToken(encodedActionId, { root });
+  const encodedActionChannel = await openSessionActionChannel(encodedActionId, { root });
+  const encodedActionToken = encodedActionChannel.token;
   const siblingActionId = `web-action-sibling-${testId}`;
   const siblingActionSession = await startProvider({
     id: siblingActionId,
     kind: 'shell',
     command: 'bash --noprofile --norc'
   }, otherRoot);
-  const siblingActionToken = await fetchSessionActionToken(siblingActionId, { root: otherRoot });
+  const siblingActionChannel = await openSessionActionChannel(siblingActionId, { root: otherRoot });
+  const siblingActionToken = siblingActionChannel.token;
   if (!encodedActionToken || !siblingActionToken) {
     fail(`alternate sessions did not deliver action tokens:\n${JSON.stringify({ encodedActionSession, siblingActionSession }, null, 2)}`);
   }
@@ -4798,10 +4914,12 @@ async function multiProjectWebWorkflow() {
   }
   await closeTerminalWebSocket(secondManagedChannel.ws);
   await expectActionTokenRejected(secondManagedChannel.token, 'closed-connection');
+  await claimTerminalControl(managedActionChannel.ws);
+  await claimTerminalControl(encodedActionChannel.ws);
   const encodedPeerAction = await runtimeFetch(`/api/peers/${encodeURIComponent(encodedActionId)}/actions/heartbeat`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: encodedActionToken, renew_locks: false })
+    body: JSON.stringify({ action_token: encodedActionToken, epoch: encodedActionChannel.epoch, renew_locks: false })
   }, { root });
   if (!encodedPeerAction.ok) {
     fail(`URL-encoded peer action rejected its own token:\n${await encodedPeerAction.text()}`);
@@ -4810,11 +4928,13 @@ async function multiProjectWebWorkflow() {
   const actionNext = await (await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionSession.peer_id || managedActionSession.id)}/actions/task-next`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: managedActionToken })
+    body: JSON.stringify({ action_token: managedActionToken, epoch: managedActionChannel.epoch })
   }, { root })).json();
   if (!actionNext.ok || actionNext.action !== 'task-next' || String(actionNext.data?.task?.id) !== taskMatch[1]) {
     fail(`web task-next action did not claim pending task #${taskMatch[1]}:\n${JSON.stringify(actionNext, null, 2)}`);
   }
+  await closeTerminalWebSocket(encodedActionChannel.ws);
+  await closeTerminalWebSocket(siblingActionChannel.ws);
   await stopSession(encodedActionSession.id);
   await stopSession(siblingActionSession.id, null, otherRoot);
   // Cookie-authenticated terminal sockets are tied to the opaque browser
@@ -4828,7 +4948,7 @@ async function multiProjectWebWorkflow() {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      action_token: managedActionToken,
+      action_token: managedActionToken, epoch: managedActionChannel.epoch,
       resource: webTtlResource,
       task: Number(taskMatch[1]),
       ttl: 60
@@ -4846,7 +4966,7 @@ async function multiProjectWebWorkflow() {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        action_token: managedActionToken,
+        action_token: managedActionToken, epoch: managedActionChannel.epoch,
         renew_locks: true,
         ...(ttlOverride === null ? {} : { ttl: ttlOverride })
       })
@@ -4890,7 +5010,7 @@ async function multiProjectWebWorkflow() {
   const unknownHeartbeatResponse = await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionPeer)}/actions/heartbeat`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: managedActionToken, renew_locks: true })
+    body: JSON.stringify({ action_token: managedActionToken, epoch: managedActionChannel.epoch, renew_locks: true })
   }, { root });
   const unknownHeartbeat = await unknownHeartbeatResponse.json();
   if (!unknownHeartbeatResponse.ok || unknownHeartbeat.data?.renewed !== 0) {
@@ -4906,7 +5026,7 @@ async function multiProjectWebWorkflow() {
   const graceHeartbeatResponse = await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionPeer)}/actions/heartbeat`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: managedActionToken, renew_locks: true })
+    body: JSON.stringify({ action_token: managedActionToken, epoch: managedActionChannel.epoch, renew_locks: true })
   }, { root });
   const graceHeartbeat = await graceHeartbeatResponse.json();
   const graceHeartbeatState = withMeshDb((db) => ({
@@ -4986,7 +5106,7 @@ async function multiProjectWebWorkflow() {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      action_token: managedActionToken,
+      action_token: managedActionToken, epoch: managedActionChannel.epoch,
       id: evidenceTaskId,
       reason: 'owner process identity was reused',
       policy: 'stale',
@@ -5047,7 +5167,7 @@ async function multiProjectWebWorkflow() {
   const liveLockResponse = await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionPeer)}/actions/lock-acquire`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: managedActionToken, resource: liveExpiredResource, ttl: 60 })
+    body: JSON.stringify({ action_token: managedActionToken, epoch: managedActionChannel.epoch, resource: liveExpiredResource, ttl: 60 })
   }, { root });
   const liveLockResult = await liveLockResponse.json();
   if (liveLockResponse.ok || liveLockResult.error?.code !== 'LOCK_HELD') {
@@ -5075,7 +5195,7 @@ async function multiProjectWebWorkflow() {
   const deadLockResponse = await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionPeer)}/actions/lock-acquire`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action_token: managedActionToken, resource: deadLockResource, ttl: 60 })
+    body: JSON.stringify({ action_token: managedActionToken, epoch: managedActionChannel.epoch, resource: deadLockResource, ttl: 60 })
   }, { root });
   const deadLockResult = await deadLockResponse.json();
   if (!deadLockResponse.ok || !deadLockResult.ok || deadLockResult.data?.lock?.owner !== managedActionPeer) {
@@ -5104,7 +5224,7 @@ async function multiProjectWebWorkflow() {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      action_token: managedActionToken,
+      action_token: managedActionToken, epoch: managedActionChannel.epoch,
       resource: 'web/identity-spoof-lock',
       task: Number(ownerTaskMatch[1])
     })
@@ -5277,50 +5397,6 @@ async function statusServer(status) {
   };
 }
 
-async function stalledRuntimeServer(phase) {
-  const child = spawn(process.execPath, ['-e', `
-    const http = require('node:http');
-    const sockets = new Set();
-    const server = http.createServer((req, res) => {
-      if (${JSON.stringify(phase)} === 'body') {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.write('{"deleted":0');
-      }
-    });
-    server.on('connection', (socket) => {
-      sockets.add(socket);
-      socket.on('close', () => sockets.delete(socket));
-    });
-    server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));
-    process.on('SIGTERM', () => {
-      for (const socket of sockets) socket.destroy();
-      server.close(() => process.exit(0));
-    });
-  `], { stdio: ['ignore', 'pipe', 'inherit'] });
-  const port = await new Promise((resolve, reject) => {
-    let output = '';
-    const timer = setTimeout(() => reject(new Error(`timed out starting ${phase} stalled runtime`)), 5000);
-    child.stdout.on('data', (chunk) => {
-      output += chunk;
-      const match = output.match(/^(\d+)\n/);
-      if (!match) return;
-      clearTimeout(timer);
-      resolve(Number(match[1]));
-    });
-    child.once('exit', (code) => {
-      clearTimeout(timer);
-      reject(new Error(`${phase} stalled runtime exited early with ${code}`));
-    });
-  });
-  return {
-    baseUrl: `http://127.0.0.1:${port}`,
-    close: async () => {
-      child.kill('SIGTERM');
-      try { await waitForProcessExit(child.pid, `${phase} stalled runtime exit`, 3000); } catch {}
-    }
-  };
-}
-
 function bufferGcCanonicalizationRaceWorkflow() {
   for (const phase of ['before', 'after']) {
     const raceRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-realpath-${phase}-${testId}-`));
@@ -5445,7 +5521,10 @@ async function bufferGcArbitrationWorkflow() {
   if (!firstApply.ok || replayApply.ok) fail('buffer GC token was not exactly once');
 
   const cutoffMs = Date.now() - 60_000;
-  const oldTime = new Date(cutoffMs - 60_000);
+  // Ordinary deletion checks use a non-zero retention window so crossing a
+  // wall-clock second cannot legitimately activate clock-jump protection.
+  const stableGcRetentionDays = 1;
+  const oldTime = new Date(Date.now() - 2 * 86400_000);
   const rootBufs = path.join(root, '.hello-cc', 'bufs');
   const siblingBufs = path.join(secondProjectRoot, '.hello-cc', 'bufs');
   fs.mkdirSync(rootBufs, { recursive: true });
@@ -5586,7 +5665,9 @@ async function bufferGcArbitrationWorkflow() {
   const parentAlias = path.join(aliasContainer, 'parent');
   fs.symlinkSync(path.dirname(secondProjectRoot), parentAlias);
   const siblingAliasRoot = path.join(parentAlias, path.basename(secondProjectRoot));
-  const gcOutput = hccFrom(['--json', 'gc', '--older-than', '0', '--yes'], siblingAliasRoot);
+  const gcOutput = hccFrom([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ], siblingAliasRoot);
   fs.rmSync(aliasContainer, { recursive: true, force: true });
   const gcPayload = JSON.parse(gcOutput);
   const result = gcPayload.data || {};
@@ -5609,7 +5690,9 @@ async function bufferGcArbitrationWorkflow() {
   } finally {
     rootGcClockDb.close();
   }
-  const rootGcPayload = JSON.parse(hcc(['--json', 'gc', '--older-than', '0', '--yes']));
+  const rootGcPayload = JSON.parse(hcc([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ]));
   const rootGcResult = rootGcPayload.data || {};
   if (rootGcResult.buf_files !== 1 || rootGcResult.protected_buf_files < liveFiles.length ||
       rootGcResult.deferred_buf_files < legacyFiles.length || fs.existsSync(rootOrphan)) {
@@ -5735,7 +5818,9 @@ async function bufferGcArbitrationWorkflow() {
   const normalOrphan = path.join(siblingBufs, `gc-actual-dir-normal-${testId}.out`);
   fs.writeFileSync(normalOrphan, 'actual directory normal baseline');
   fs.utimesSync(normalOrphan, oldTime, oldTime);
-  const normalGc = JSON.parse(hccFrom(['--json', 'gc', '--older-than', '0', '--yes'], secondProjectRoot)).data;
+  const normalGc = JSON.parse(hccFrom([
+    '--json', 'gc', '--older-than', String(stableGcRetentionDays), '--yes'
+  ], secondProjectRoot)).data;
   if (fs.existsSync(gapOrphan) || fs.existsSync(normalOrphan) || Number(normalGc.buf_files || 0) < 2) {
     fail(`actual runtime buffer directory did not delete against a live baseline: ${JSON.stringify(normalGc)}`);
   }
@@ -5812,42 +5897,6 @@ async function bufferGcArbitrationWorkflow() {
     }
   }
 
-  for (const phase of ['headers', 'body']) {
-    const isolatedRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-stall-${phase}-${testId}-`));
-    const isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-stall-home-${phase}-${testId}-`));
-    let server = null;
-    try {
-      const isolatedEnv = { ...env, HOME: isolatedHome };
-      run(process.execPath, [hccBin, '--root', isolatedRoot, 'init', '--no-guidance'], { env: isolatedEnv });
-      const directory = path.join(isolatedRoot, '.hello-cc', 'bufs');
-      fs.mkdirSync(directory, { recursive: true });
-      const orphan = path.join(directory, 'old-orphan.out');
-      fs.writeFileSync(orphan, 'orphan');
-      fs.utimesSync(orphan, oldTime, oldTime);
-      server = await stalledRuntimeServer(phase);
-      fs.writeFileSync(path.join(isolatedRoot, '.hello-cc', 'runtime.json'), JSON.stringify({
-        pid: process.pid,
-        base_url: server.baseUrl,
-        token: 'regression-token'
-      }));
-
-      const startedAt = Date.now();
-      const gc = run(process.execPath, [hccBin, '--root', isolatedRoot, '--json', 'gc', '--older-than', '0', '--yes'], { env: isolatedEnv });
-      const elapsedMs = Date.now() - startedAt;
-      const payload = JSON.parse(gc);
-      if (elapsedMs >= 9000 ||
-          Number(payload.data?.buf_files || 0) !== 0 ||
-          Number(payload.data?.deferred_buf_files || 0) < 1 ||
-          !fs.existsSync(orphan)) {
-        fail(`runtime ${phase} stall did not fail closed within deadline (${elapsedMs}ms): ${gc}`);
-      }
-    } finally {
-      await server?.close();
-      fs.rmSync(isolatedRoot, { recursive: true, force: true });
-      fs.rmSync(isolatedHome, { recursive: true, force: true });
-    }
-  }
-
   const localRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-local-${testId}-`));
   const localHome = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-buffer-gc-local-home-${testId}-`));
   try {
@@ -5991,9 +6040,24 @@ async function tmuxBackedStartWorkflow() {
   if (!restoredAuthority?.payload?.tmux_session_created || !restoredAuthority?.payload?.tmux_session_id) {
     fail(`startup auto GC left no complete immutable tmux authority: ${JSON.stringify({ authorityBindingAfterStop, restoredAuthority })}`);
   }
-  withMeshDb((db) => db.prepare('UPDATE events SET created_at = ? WHERE id = ?')
-    .run(oldAuthorityAt, restoredAuthority.id));
-  hcc(['gc', '--older-than', '14', '--yes']);
+  const authorityGcNow = Math.floor(Date.now() / 1000);
+  withMeshDb((db) => {
+    db.prepare('UPDATE events SET created_at = ? WHERE id = ?')
+      .run(oldAuthorityAt, restoredAuthority.id);
+    // Backdating the fixture must not itself look like a real wall-clock jump.
+    // Establish the same current baseline used by the other explicit GC tests.
+    db.prepare("DELETE FROM meta WHERE key IN ('clock_grace_until', 'clock_pending_gap')").run();
+    db.prepare(`
+      INSERT INTO meta(key, value) VALUES ('clock_last_observed_at', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `).run(String(authorityGcNow));
+  });
+  // This assertion exercises manual history pruning. Request it explicitly
+  // instead of racing the runtime's asynchronous startup auto-GC.
+  const authorityGc = JSON.parse(hcc(['--json', 'gc', '--older-than', '14', '--history', '--yes']));
+  if (authorityGc.data?.deferred_age_based || Number(authorityGc.data?.deferred_old_events || 0) !== 0) {
+    fail(`tmux authority history GC was unexpectedly deferred: ${JSON.stringify(authorityGc.data)}`);
+  }
   const authorityRowsAfterFullGc = withMeshDb((db) => db.prepare(`
     SELECT id FROM events
     WHERE type = 'tmux.session.attached'
@@ -6476,10 +6540,36 @@ function identityEnforcementWorkflow() {
       db2.close();
     }
 
-    hccFrom(['run', '--peer', 'fake-runner', '--', process.execPath, '-e', 'process.exit(0)'], identityRoot, { env: identityEnv });
+    const readRunOwner = () => {
+      const ownerDb = new DatabaseSync(dbPath);
+      try {
+        return {
+          peer: ownerDb.prepare('SELECT * FROM peers WHERE id = ?').get('real-peer'),
+          binding: ownerDb.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get('real-peer') || null,
+          runEvents: ownerDb.prepare("SELECT * FROM events WHERE actor = 'real-peer' AND type LIKE 'run.session.%' ORDER BY id").all()
+        };
+      } finally {
+        ownerDb.close();
+      }
+    };
+    // Earlier identity commands registered real-peer with the live regression
+    // parent as owner. Correcting --peer must preserve that occupied identity.
+    const ownerBeforeRun = readRunOwner();
+    const occupiedRun = hccFromMaybe(['--json', 'run', '--peer', 'fake-runner', '--', process.execPath, '-e', 'process.exit(0)'], identityRoot, { env: identityEnv });
+    let occupiedError;
+    try { occupiedError = JSON.parse(occupiedRun.stderr).error; } catch {}
+    if (occupiedRun.status === 0 || occupiedError?.code !== 'PEER_SESSION_EXISTS' || occupiedError?.peer !== 'real-peer') {
+      fail(`run did not protect the existing system peer owner:\nstdout=${occupiedRun.stdout}\nstderr=${occupiedRun.stderr}`);
+    }
+    if (JSON.stringify(readRunOwner()) !== JSON.stringify(ownerBeforeRun)) {
+      fail('rejected run changed the existing system peer, binding, or run events');
+    }
+
+    const runnerEnv = { ...identityEnv, HCC_PEER: 'real-runner' };
+    hccFrom(['run', '--peer', 'fake-runner', '--', process.execPath, '-e', 'process.exit(0)'], identityRoot, { env: runnerEnv });
     const db3 = new DatabaseSync(dbPath);
     try {
-      const realRunner = db3.prepare('SELECT id, status FROM peers WHERE id = ?').get('real-peer');
+      const realRunner = db3.prepare('SELECT id, status FROM peers WHERE id = ?').get('real-runner');
       const fakeRunner = db3.prepare('SELECT id FROM peers WHERE id = ?').get('fake-runner');
       if (!realRunner || realRunner.status !== 'exited' || fakeRunner) {
         fail(`run did not enforce system peer identity:\n${JSON.stringify({ realRunner, fakeRunner }, null, 2)}`);
@@ -6487,6 +6577,9 @@ function identityEnforcementWorkflow() {
     } finally {
       db3.close();
     }
+    if (JSON.stringify(readRunOwner()) !== JSON.stringify(ownerBeforeRun)) {
+      fail('fresh run changed the occupied system peer owner');
+    }
 
     hccFrom(['peer', 'stop', 'fake-target'], identityRoot, { env: identityEnv });
     const stopRequested = eventPayloads('peer.stop.requested', 5, dbPath)
@@ -6758,21 +6851,28 @@ async function syntaxAndHelp() {
     'function detectedPeerCanStop(peer)',
     "if (['exited', 'detached'].includes(status)) return false;",
     'const canStop = detectedPeerCanStop(p);',
-    '${canStop ?',
+    "${dshCoordinationPeer(p) ? '' : canStop ?",
     'function providerSessionKnown(session)',
     "tr('providerSession') + '=' + sessionProvider(session) + ':' + (value || tr('unknown'))",
-    'sessionCardDetailText(s)',
+    "sessionDetailsHtml('managed:' + s.id",
+    "[tr('runtime'), sessionRuntimeTarget(s)]",
+    "[tr('providerSession'), sessionProvider(s) + ':' + (sessionProviderSessionValue(s) || tr('unknown'))]",
+    "[tr('command'), s.command]",
+    "[tr('cwd'), path]",
     'const activeDetectedPeers = visibleDetected.filter((p) => peerIsActive(p));',
     'const staleDetectedPeers = visibleDetected.filter((p) => !peerIsActive(p));',
-    "localStorage.setItem('hcc.showStaleDetected'",
+    "hccUi.safeSet('hcc.showStaleDetected'",
     'id="toggleStaleDetected"',
-    "if (e.target.closest('[data-action]')) return;",
+    "if (e.target.closest('details, [data-action]')) return;",
     'id="stopKillLabel" data-i18n="dialog.killTmux"',
     'id="stopCancelBtn" type="button" data-i18n="dialog.cancel"',
     'id="stopConfirmBtn" type="button" data-i18n="stop"'
   ]) {
     if (!webUiTemplateSource.includes(expected)) fail(`web display regression guard missing: ${expected}`);
   }
+  // Execute the shipped renderer as well: a helper name alone does not prove
+  // session identities remain visible or disclosure/action clicks stay local.
+  run(process.execPath, ['--test', path.join(repoRoot, 'test', 'web-ui-session-display.test.mjs')]);
   if (webUiTemplateSource.includes("p.status === 'running' ?")) {
     fail('detected peer action rendering still depends on status === running instead of liveness');
   }
@@ -9280,8 +9380,9 @@ async function syntaxAndHelp() {
   };
   const html = webUiTemplate.webIndexHtml({ nonce: 'regression-template-nonce' });
   if (!html.includes('<!doctype html>') ||
-      !html.includes('<div class="app">') ||
-      !html.includes('<script src="/assets/xterm.js"></script>')) {
+      !html.includes('<div class="app" data-view="terminal">') ||
+      !html.includes('<script src="/assets/xterm.js"></script>') ||
+      !html.includes('<script src="/assets/addon-fit.js"></script>')) {
     fail('web UI template module did not render the expected shell HTML');
   }
   const jsonReq = Readable.from(['{"ok":true}']);
@@ -9529,12 +9630,15 @@ async function syntaxAndHelp() {
   expectEqual(webRuntime.publicRuntimeUrl(ipv6WildcardRuntime, '/tmp/hcc project'), 'http://<machine-ip>:8788/?token=tok&project=%2Ftmp%2Fhcc%20project', 'publicRuntimeUrl ipv6 wildcard');
   expectEqual(webRuntime.localRuntimeUrl(localRuntime, null), 'http://127.0.0.1:8789/?token=tok', 'localRuntimeUrl no project');
   const mainHelp = run(process.execPath, [hccBin, '--help']);
-  if (mainHelp.includes('setup') || mainHelp.includes('--web-managed')) {
+  if (/^\s*setup(?:\s|$)/m.test(mainHelp) || mainHelp.includes('--web-managed')) {
     fail(`public help exposes maintenance or removed commands:\n${mainHelp}`);
   }
   if (!mainHelp.includes('  update                       Update the global npm install of hello-cc')) {
     fail(`main help missing update command:\n${mainHelp}`);
   }
+  if (!mainHelp.includes('  dsh <setup|status|web>        Connect DeepSeek Harness through project-local hooks')) {
+    fail(`main help missing dsh command:\n${mainHelp}`);
+  }
   if (!mainHelp.includes('  state [--peer ID]            Show timeline and next coordination action')) {
     fail(`main help missing state command:\n${mainHelp}`);
   }
@@ -9726,6 +9830,10 @@ function uninstallWorkflow() {
 
 async function processEvidenceWorkflow() {
   log('process evidence: live, reused, legacy, dead, root mismatch');
+  // These fixtures deliberately backdate peers beyond the production reaper's
+  // grace window. Keep the runtime stopped until the external-adoption cases so
+  // a 30-second scheduler tick cannot turn an evidence snapshot into exited.
+  await stopRuntime();
 
   const createOwnedTask = (peer, title) => {
     const output = hcc(['task', 'create', '--from', 'human', '--to', peer, '--title', title]);
@@ -9831,6 +9939,8 @@ async function processEvidenceWorkflow() {
     cleanupBindingPeers(rootPeer);
   }
 
+  startRuntime();
+  await waitRuntime();
   const externalDir = path.join(root, '.hello-cc', 'bufs');
   const shortExternalId = `evidence-external-short-${testId}`;
   const shortProducer = spawn(process.execPath, [
@@ -10711,17 +10821,18 @@ function manualGcRetentionContractWorkflow() {
   }
 }
 
-// Name-authoritative re-adoption + dead-peer reaper (session leak hardening).
+// Intentional detach persists; unpaused orphans recover by name and dead peers
+// are reaped without treating terminal detachment as process death.
 async function sessionRecoveryWorkflow() {
   if (!tmuxAvailable()) {
     log('session recovery skipped (tmux not installed)');
     return;
   }
-  log('session recovery: re-adopt orphan tmux + reap dead peer');
+  log('session recovery: persistent detach + explicit resume + orphan adoption + dead peer reaping');
   if (!fs.existsSync(path.join(root, '.hello-cc', 'runtime.json'))) startRuntime();
   await waitRuntime();
 
-  // ── Default Stop (no kill) must not strand a live managed session ──
+  // Default Stop pauses Web adoption while leaving the local terminal alive.
   const readoptPeer = 'readopt-shell';
   const pane = parsePane(hcc(['peer', 'start', readoptPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
   const sessionName = tmuxManagedSession(root, readoptPeer);
@@ -10753,22 +10864,57 @@ async function sessionRecoveryWorkflow() {
       detachedTakeover.status === 0) {
     fail(`live detached tmux pane did not block takeover: ${JSON.stringify(detachedRow)}\n${detachedTakeover.stdout}\n${detachedTakeover.stderr}`);
   }
-  // Within a few poll cycles the name-sweep must re-adopt the still-live session.
+  const pauseEvent = eventPayloads('web.adoption.paused')
+    .find((event) => event.payload?.peer === readoptPeer && event.payload?.pane === pane);
+  if (!pauseEvent) fail('default detach did not persist its adoption pause');
+  // A genuinely orphaned binding has no intentional pause. Simulate runtime
+  // state loss while keeping the managed tmux name and process identity.
+  const orphanPeer = 'unpaused-orphan-shell';
+  const orphanPane = parsePane(hcc(['peer', 'start', orphanPeer, '--kind', 'shell', '--', 'bash', '--noprofile', '--norc']));
+  const orphanSessionName = tmuxManagedSession(root, orphanPeer);
+  await stopRuntime();
+  withMeshDb((db) => {
+    db.prepare('UPDATE peer_bindings SET runtime_target = NULL WHERE peer = ?').run(orphanPeer);
+    db.prepare("UPDATE peers SET status = 'detached' WHERE id = ?").run(orphanPeer);
+  });
+  startRuntime();
+  await waitRuntime();
   await waitFor(() => {
-    const row = peerBindingRow(readoptPeer);
-    return Boolean(row && row.runtime_target === pane);
-  }, 'orphan managed tmux session re-adoption', 20000);
+    const row = peerBindingRow(orphanPeer);
+    return Boolean(row && row.runtime_target === orphanPane);
+  }, 'unpaused orphan managed tmux session re-adoption', 20000);
+  // Cover another auto-attach cycle after restart: it must not override a pause.
+  await sleep(5500);
+  binding = peerBindingRow(readoptPeer);
+  if (!binding || binding.runtime_target !== null ||
+      runMaybe('tmux', ['has-session', '-t', sessionName]).status !== 0) {
+    fail(`runtime restart or polling overrode an intentional live-terminal detach:\n${JSON.stringify(binding, null, 2)}`);
+  }
+  const pausedSessions = await (await runtimeFetch('/api/sessions', {}, { root })).json();
+  if ((pausedSessions.sessions || []).some((session) => session.id === readoptPeer && session.status === 'running')) {
+    fail(`intentionally detached session was automatically re-adopted:\n${JSON.stringify(pausedSessions, null, 2)}`);
+  }
+  const resumeResponse = await runtimeFetch('/api/sessions/attach', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id: readoptPeer, kind: 'shell', pane, force: true })
+  }, { root });
+  const resumed = await resumeResponse.json();
+  if (!resumeResponse.ok || resumed.session?.pane !== pane) {
+    fail(`explicit attach did not resume the same detached terminal:\n${JSON.stringify(resumed, null, 2)}`);
+  }
   const restoredStatus = withMeshDb((db) => db.prepare('SELECT status FROM peers WHERE id = ?').get(readoptPeer)?.status);
-  if (restoredStatus !== 'running') fail(`re-adopted peer not marked running (status=${restoredStatus})`);
-  // Re-enterability: the runtime now exposes the session again.
+  if (restoredStatus !== 'running') fail(`explicitly resumed peer not marked running (status=${restoredStatus})`);
+  // Both explicit resume and automatic orphan recovery expose a live session.
   const sessions = await (await runtimeFetch('/api/sessions', {}, { root })).json();
   if (!(sessions.sessions || []).some((s) => s.id === readoptPeer && s.status === 'running')) {
-    fail(`re-adopted session not exposed by /api/sessions:\n${JSON.stringify(sessions, null, 2)}`);
+    fail(`explicitly resumed session not exposed by /api/sessions:\n${JSON.stringify(sessions, null, 2)}`);
+  }
+  if (!(sessions.sessions || []).some((session) => session.id === orphanPeer && session.pane === orphanPane && session.status === 'running')) {
+    fail(`unpaused orphan session not exposed by /api/sessions:\n${JSON.stringify(sessions, null, 2)}`);
   }
   hcc(['task', 'takeover', '--peer', 'human', '--id', detachedTaskId, '--reason', 'detached evidence cleanup', '--force']);
   hcc(['task', 'update', '--peer', 'human', '--id', detachedTaskId, '--status', 'abandoned', '--summary', 'detached evidence cleanup']);
-  // Destroying the live session is the real teardown path (CLI peer stop has
-  // no kill flag; the web API's kill_tmux is the equivalent). Kill it directly
+  // Destroying the live session is the real teardown path. Kill it directly
   // so it does not leak into the final tmux-session leak assertion.
   runMaybe('tmux', ['kill-session', '-t', sessionName]);
   if (runMaybe('tmux', ['has-session', '-t', sessionName]).status === 0) {
@@ -10778,6 +10924,11 @@ async function sessionRecoveryWorkflow() {
     db.prepare('DELETE FROM peer_bindings WHERE peer = ?').run(readoptPeer);
     db.prepare('DELETE FROM peers WHERE id = ?').run(readoptPeer);
   });
+  runMaybe('tmux', ['kill-session', '-t', orphanSessionName]);
+  withMeshDb((db) => {
+    db.prepare('DELETE FROM peer_bindings WHERE peer = ?').run(orphanPeer);
+    db.prepare('DELETE FROM peers WHERE id = ?').run(orphanPeer);
+  });
 
   // ── A peer whose process is gone must be reaped, not stuck at 'running' ──
   const reaped = spawnSync('sleep', ['10'], { stdio: 'ignore' });