@logicseek/hello-cc 0.1.9 → 1.0.1

package/lib/terminal/tmux.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { CliError } from '../shared/errors.mjs';
@@ -16,9 +17,16 @@ export function runTmux(args, opts = {}) {
   const result = spawnSync('tmux', args, {
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
-    input: opts.input || ''
+    input: opts.input || '',
+    // xx-02: a hung tmux (D-state pane, wedged pty, stuck filesystem) must not
+    // freeze the shared runtime event loop forever. Normal tmux commands finish
+    // in milliseconds; a 5s bound only trips when tmux is genuinely stuck.
+    timeout: opts.timeout ?? 5000
   });
   if (result.error) {
+    if (result.error.code === 'ETIMEDOUT' || result.killed) {
+      throw new CliError('TMUX_ERROR', `tmux timed out after ${opts.timeout ?? 5000}ms: tmux ${args.join(' ')}`);
+    }
     throw new CliError('TMUX_ERROR', `tmux failed: ${result.error.message}`);
   }
   if (result.status !== 0) {
@@ -28,14 +36,20 @@ export function runTmux(args, opts = {}) {
   return result.stdout || '';
 }
 
-function tmuxInstallHint() {
-  if (process.platform === 'darwin') return 'Install tmux with: brew install tmux';
-  if (process.platform === 'linux') {
-    if (fs.existsSync('/etc/debian_version')) return 'Install tmux with: sudo apt-get update && sudo apt-get install -y tmux';
-    if (fs.existsSync('/etc/alpine-release')) return 'Install tmux with: sudo apk add tmux';
-    if (fs.existsSync('/etc/arch-release')) return 'Install tmux with: sudo pacman -S --noconfirm tmux';
-    if (fs.existsSync('/etc/fedora-release')) return 'Install tmux with: sudo dnf install -y tmux';
-    return 'Install tmux with your system package manager.';
+export function tmuxInstallHint({
+  platform = process.platform,
+  pathExists = fs.existsSync
+} = {}) {
+  if (platform === 'darwin') return 'Install tmux with: brew install tmux';
+  if (platform === 'linux') {
+    if (pathExists('/etc/debian_version')) return 'Install tmux with: sudo apt-get update && sudo apt-get install -y tmux';
+    if (pathExists('/etc/alpine-release')) return 'Install tmux with: sudo apk add tmux';
+    if (pathExists('/etc/arch-release')) return 'Install tmux with: sudo pacman -S --noconfirm tmux';
+    if (pathExists('/etc/fedora-release') || pathExists('/etc/redhat-release')) {
+      return 'Install tmux with: sudo dnf install -y tmux (or sudo yum install -y tmux on older systems)';
+    }
+    if (pathExists('/etc/SuSE-release')) return 'Install tmux with: sudo zypper --non-interactive install tmux';
+    return 'Install tmux with your Linux system package manager (apt/apt-get, dnf/yum, apk, pacman, or zypper).';
   }
   return 'Install tmux and make sure it is on PATH.';
 }
@@ -46,6 +60,36 @@ function commandExists(name) {
   }).status === 0;
 }
 
+export function tmuxInstallPlan({
+  platform = process.platform,
+  commandAvailable = commandExists,
+  isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+} = {}) {
+  if (platform === 'darwin') {
+    return commandAvailable('brew')
+      ? { manager: 'brew', commands: ['brew install tmux'] }
+      : null;
+  }
+  if (platform !== 'linux') return null;
+
+  if (!isRoot && !commandAvailable('sudo')) return null;
+  const sudo = isRoot ? '' : 'sudo ';
+  if (commandAvailable('apt-get')) {
+    return {
+      manager: 'apt-get',
+      commands: [`${sudo}apt-get update`, `${sudo}apt-get install -y tmux`]
+    };
+  }
+  if (commandAvailable('dnf')) return { manager: 'dnf', commands: [`${sudo}dnf install -y tmux`] };
+  if (commandAvailable('yum')) return { manager: 'yum', commands: [`${sudo}yum install -y tmux`] };
+  if (commandAvailable('apk')) return { manager: 'apk', commands: [`${sudo}apk add tmux`] };
+  if (commandAvailable('pacman')) return { manager: 'pacman', commands: [`${sudo}pacman -S --noconfirm tmux`] };
+  if (commandAvailable('zypper')) {
+    return { manager: 'zypper', commands: [`${sudo}zypper --non-interactive install tmux`] };
+  }
+  return null;
+}
+
 function runInstallCommand(command) {
   const result = spawnSync('sh', ['-lc', command], {
     encoding: 'utf8',
@@ -62,22 +106,16 @@ export function tryInstallTmux() {
   if (process.env.HCC_NO_AUTO_INSTALL_TMUX === '1') {
     return { ok: false, output: 'automatic tmux installation disabled by HCC_NO_AUTO_INSTALL_TMUX=1' };
   }
-  const sudo = typeof process.getuid === 'function' && process.getuid() === 0 ? '' : (commandExists('sudo') ? 'sudo ' : '');
-  if (process.platform === 'darwin' && commandExists('brew')) {
-    return runInstallCommand('brew install tmux');
-  }
-  if (process.platform === 'linux') {
-    if (commandExists('apt-get')) {
-      const update = runInstallCommand(`${sudo}apt-get update`);
-      if (!update.ok) return update;
-      return runInstallCommand(`${sudo}apt-get install -y tmux`);
-    }
-    if (commandExists('dnf')) return runInstallCommand(`${sudo}dnf install -y tmux`);
-    if (commandExists('yum')) return runInstallCommand(`${sudo}yum install -y tmux`);
-    if (commandExists('apk')) return runInstallCommand(`${sudo}apk add tmux`);
-    if (commandExists('pacman')) return runInstallCommand(`${sudo}pacman -S --noconfirm tmux`);
+  const plan = tmuxInstallPlan();
+  if (!plan) return { ok: false, output: 'no supported package manager with sufficient privileges found' };
+
+  const output = [];
+  for (const command of plan.commands) {
+    const result = runInstallCommand(command);
+    if (result.output) output.push(result.output);
+    if (!result.ok) return { ok: false, output: output.join('\n') };
   }
-  return { ok: false, output: 'no supported package manager found' };
+  return { ok: true, output: output.join('\n') };
 }
 
 export function ensureTmuxAvailable({ autoInstall = true } = {}) {
@@ -119,6 +157,16 @@ export function tmuxKillSession(sessionName) {
   }
 }
 
+export function tmuxListSessionNames() {
+  const result = spawnSync('tmux', ['list-sessions', '-F', '#{session_name}'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  // No tmux server (status 1, "no server running") or no sessions → empty list.
+  if (result.status !== 0) return [];
+  return (result.stdout || '').split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
 export function tmuxSessionEnvironmentValue(sessionName, key) {
   const result = spawnSync('tmux', ['show-environment', '-t', sessionName, key], {
     encoding: 'utf8',
@@ -139,11 +187,57 @@ export function tmuxProviderState(sessionName) {
   return tmuxSessionEnvironmentValue(sessionName, PROVIDER_STATE_ENV);
 }
 
+function managedProjectRoot(root) {
+  try {
+    return fs.realpathSync(root);
+  } catch {
+    return path.resolve(root);
+  }
+}
+
+function legacyManagedProjectRoot(root) {
+  return path.resolve(root);
+}
+
+export function tmuxManagedSessionPrefix(ctx) {
+  return `hcc-${shortHash(managedProjectRoot(ctx.root))}-`;
+}
+
 export function tmuxManagedSessionName(ctx, peerId) {
-  const name = `hcc-${shortHash(ctx.root)}-${sanitizePeerPart(peerId, 'peer')}`;
+  const name = `${tmuxManagedSessionPrefix(ctx)}${sanitizePeerPart(peerId, 'peer')}`;
   return name.slice(0, 80);
 }
 
+function legacyTmuxManagedSessionPrefix(ctx) {
+  return `hcc-${shortHash(legacyManagedProjectRoot(ctx.root))}-`;
+}
+
+function legacyTmuxManagedSessionName(ctx, peerId) {
+  return `${legacyTmuxManagedSessionPrefix(ctx)}${sanitizePeerPart(peerId, 'peer')}`.slice(0, 80);
+}
+
+function rootsIdentifySameProject(left, right) {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return false;
+  }
+}
+
+export function tmuxManagedSessionPrefixMatches(ctx, sessionName, sessionRoot = null) {
+  if (!sessionName) return false;
+  if (sessionName.startsWith(tmuxManagedSessionPrefix(ctx))) return true;
+  return Boolean(sessionRoot) && rootsIdentifySameProject(ctx.root, sessionRoot) &&
+    sessionName.startsWith(legacyTmuxManagedSessionPrefix({ root: sessionRoot }));
+}
+
+export function tmuxManagedSessionNameMatches(ctx, sessionName, peerId, sessionRoot = null) {
+  if (!sessionName) return false;
+  if (sessionName === tmuxManagedSessionName(ctx, peerId)) return true;
+  return Boolean(sessionRoot) && rootsIdentifySameProject(ctx.root, sessionRoot) &&
+    sessionName === legacyTmuxManagedSessionName({ root: sessionRoot }, peerId);
+}
+
 export function tmuxEnvironmentArgs(env) {
   const args = [];
   for (const [key, value] of Object.entries(env)) {
@@ -158,9 +252,19 @@ export function tmuxEnvironmentArgs(env) {
 export function tmuxPaneInfo(targetPane = null) {
   const pane = targetPane || process.env.TMUX_PANE;
   if (!pane) throw new CliError('BAD_ARGS', 'Missing --pane and current terminal is not inside tmux');
-  const format = '#{pane_id}\t#{pane_current_path}\t#{pane_pid}\t#{pane_current_command}\t#{pane_dead}';
+  // NOTE: do not use tab characters as field separators — older tmux (e.g. 3.3a
+  // on Debian) replaces whitespace in display-message/list-panes -F output with
+  // '_', which silently corrupts parsing and produces invalid pane targets. '|'
+  // is preserved across tmux versions and never appears in pane_id/pid/command/
+  // dead; the path is placed last and rejoined so a '|' inside a path is safe.
+  const format = '#{pane_id}|#{pane_dead}|#{pane_pid}|#{pane_current_command}|#{pane_current_path}';
   const out = runTmux(['display-message', '-p', '-t', pane, format]).trimEnd();
-  const [paneId, currentPath, pid, currentCommand, paneDead] = out.split('\t');
+  const parts = out.split('|');
+  const paneId = parts[0];
+  const paneDead = parts[1];
+  const pid = parts[2];
+  const currentCommand = parts[3];
+  const currentPath = parts.slice(4).join('|');
   if (!paneId) throw new CliError('TMUX_ERROR', `Cannot resolve tmux pane: ${pane}`);
   return {
     pane: paneId,

package/lib/tmux.mjs

@@ -8,7 +8,11 @@ export {
   tmuxHasSession,
   tmuxKillSession,
   tmuxLaunchFingerprint,
+  tmuxListSessionNames,
   tmuxManagedSessionName,
+  tmuxManagedSessionNameMatches,
+  tmuxManagedSessionPrefix,
+  tmuxManagedSessionPrefixMatches,
   tmuxPaneInfo,
   tmuxProviderState,
   tmuxSendLiteral,

package/lib/ui/help.mjs

@@ -41,7 +41,8 @@ Commands:
   lock <subcommand>            Acquire, renew, release, and list advisory locks
   handoff <subcommand>         Create and list handoffs
   event tail                   Show recent coordination events
-  gc [--older-than DAYS] [--yes] Clean up stale peers, events, tasks, and buf files
+  gc [--older-than DAYS] [--history] [--yes] Clean technical state; opt in to history cleanup
+  doctor                       Run a read-only database health check (integrity, sizes, row counts)
 Internal:
   hook                         Hook entrypoint used by Claude/Codex
   find-root                    Shim helper
@@ -51,7 +52,8 @@ Environment:
   HCC_ROOT               Override project root
   HCC_DB                 Override database path
   HCC_PEER               Default peer id; inferred automatically when absent
-  HCC_WEB_TOKEN          Replace and save the stable web access token
+  HCC_WEB_TOKEN          Set an explicit web access token
+  HCC_RUNTIME_CA         CA file for HCC_RUNTIME_URL=https endpoints
 `);
     },
 
@@ -65,9 +67,10 @@ Usage:
   ${cliName} task create --title TEXT --parent N [--team-role ROLE]
   ${cliName} task list [--status pending|claimed|running|review|blocked|done|abandoned] [--peer ID] [--all]
   ${cliName} task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
-  ${cliName} task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
+  ${cliName} task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--force] [--stale-after SECONDS]
   ${cliName} task next [--peer ID] [--force] [--count N]
   ${cliName} task update [--peer ID] --id N --status STATUS [--summary TEXT] [--body TEXT] [--to ID]
+  ${cliName} task running|review|blocked|abandoned [--peer ID] --id N [--summary TEXT] [--body TEXT] [--to ID]
   ${cliName} task done [--peer ID] --id N --summary TEXT
 
 Default task list shows all project tasks that are not done or abandoned.
@@ -83,9 +86,12 @@ dispatch; use --force only when intentionally injecting while the target already
 owns another active task.
 Use task takeover when explicitly taking over a non-complete task from another
 owner; it records the previous owner, requires a reason, and notifies them.
-Use --policy blocked, stale, or blocked-or-stale to require an auditable
-precondition before takeover. The default policy is any for backward
-compatibility.
+The default policy is blocked-or-stale: takeover is allowed only when the task
+is blocked or its owner is stale/exited, so an active owner's task is not taken
+silently. Use --force (or --policy any) to take over an active owner's task
+explicitly; use --policy blocked or --stale-after to narrow the precondition.
+task running, task review, task blocked, and task abandoned are shortcuts for
+task update --status STATUS.
 
 If --peer/--from and HCC_PEER are absent, hcc auto-joins the current terminal
 as a stable project-local peer.
@@ -275,14 +281,21 @@ a dry-run; deletion requires --yes.
       console.log(`${cliName} gc
 
 Usage:
-  ${cliName} gc [--older-than DAYS] [--yes]
+  ${cliName} gc [--older-than DAYS] [--history] [--yes]
 
 Examples:
   ${cliName} gc
   ${cliName} gc --older-than 14 --yes
-
-Clean stale coordination database records and old buffer files for the current
-project. By default this is a dry-run; deletion requires --yes.
+  ${cliName} gc --older-than 14 --history --yes
+
+Clean stale technical state for the current project: dead peers, expired locks,
+and old buffer files. Events, completed tasks, messages, and eligible handoffs
+are retained unless --history is supplied.
+Handoffs linked to open tasks are always preserved. By default this is a dry-run.
+Technical deletion requires --yes, and
+history deletion requires both --history and --yes.
+--older-than must be zero or greater. During clock grace,
+every age-based category is deferred.
 `);
     },
 
@@ -427,7 +440,7 @@ automatically when provider CLIs are available on PATH.
       console.log(`${cliName} web
 
 Usage:
-  ${cliName} web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
+  ${cliName} web [--host HOST] [--port N] [--token TEXT] [--local] [--tls] [--trust-proxy --proxy-origin ORIGIN] [--no-token] [--no-discover] [--no-guidance]
 
 Examples:
   ${cliName} web
@@ -439,10 +452,35 @@ installs Claude/Codex hooks and shims, ensures tmux is available, starts the
 browser terminal console as a background runtime, prints the URL, PID, runtime
 file, and log file, then returns the terminal to you.
 
-By default, the web runtime listens on 0.0.0.0 and uses a saved token,
-generating one on first use. Use HCC_WEB_TOKEN or --token to replace the saved
-token, --local to bind only to 127.0.0.1, or --no-token only for a trusted
-local/test environment.
+By default, the web runtime listens on 0.0.0.0 and generates a token scoped to
+that runtime. Use HCC_WEB_TOKEN or --token to set an explicit token, --local to
+bind only to 127.0.0.1, or --no-token only for a trusted
+local/test environment. The web console exposes a writable terminal, so binding
+a non-loopback address prints an exposure warning, and --no-token is refused on
+any non-loopback bind (use --local with it). Prefer --local plus an SSH tunnel
+(ssh -L 8787:127.0.0.1:8787) or a TLS reverse proxy for remote access. Use --tls
+to serve over HTTPS/WSS with an auto-generated self-signed certificate (stored
+under ~/.hello-cc/tls, reused across restarts); this encrypts the token and
+terminal stream against passive LAN sniffing. The browser will warn about the
+self-signed certificate until you trust it manually. For an HTTPS reverse proxy
+terminating TLS on the same machine, use --trust-proxy together with a fixed
+--proxy-origin https://host[:port]. Forwarded scheme and host must match that
+origin and arrive from loopback. For HCC_RUNTIME_URL=https endpoints with a
+private CA, set HCC_RUNTIME_CA to the CA file.
+
+The printed ?token= URL is the one-time entry: the browser exchanges it for an
+HttpOnly session cookie and is redirected to a token-free URL. After that,
+subsequent requests and the address bar no longer carry the token (the initial
+URL remains in browser history as the access link). CLI API requests use the
+Authorization header; query tokens are accepted only by the browser exchange.
+
+Version 1.0.0 uses schema v7 with a verified pre-migration backup and no
+downgrade support, full-session provider peer IDs without legacy remapping, and
+Runtime API v2. Liveness follows process evidence; only unknown evidence gets a
+120-second grace. hcc gc keeps history unless --history is explicit.
+
+Accepted risks: the default 0.0.0.0 listener is plaintext HTTP for trusted LANs,
+and an authenticated browser may select any existing server directory.
 
 After hcc web, plain claude/codex commands started from a new shell are wrapped
 as local tmux-backed terminals. Existing ordinary terminals can communicate

package/lib/web/api-version.mjs

@@ -0,0 +1,42 @@
+export const API_VERSION = 2;
+
+function versionResult(value) {
+  if (Array.isArray(value)) return { ok: false, version: null };
+  const text = String(value ?? '').trim();
+  if (!/^\d+$/.test(text)) return { ok: false, version: null };
+  const version = Number(text);
+  if (!Number.isSafeInteger(version)) return { ok: false, version: null };
+  return { ok: version === API_VERSION, version };
+}
+
+export function readHttpApiVersion(req) {
+  return versionResult(req?.headers?.['x-hcc-api-version']);
+}
+
+export function readWebSocketApiVersion(url) {
+  return versionResult(url?.searchParams?.get('api_version'));
+}
+
+export function apiVersionUnsupportedBody() {
+  return {
+    ok: false,
+    error: {
+      code: 'API_VERSION_UNSUPPORTED',
+      message: `Runtime API version ${API_VERSION} is required`,
+      supported_version: API_VERSION
+    }
+  };
+}
+
+export function withRuntimeApiVersionHeader(headers = {}) {
+  const versioned = {};
+  const entries = typeof headers?.entries === 'function'
+    ? headers.entries()
+    : Object.entries(headers || {});
+  for (const [name, value] of entries) {
+    if (String(name).toLowerCase() === 'x-hcc-api-version') continue;
+    versioned[name] = value;
+  }
+  versioned['X-HCC-API-Version'] = String(API_VERSION);
+  return versioned;
+}

package/lib/web/auto-attach.mjs

@@ -0,0 +1,185 @@
+// Auto-attach of detected provider peers, extracted from lib/web/runtime-main.mjs.
+// Scans tmux panes once per tick, reconciles DB bindings against live panes,
+// and attaches hcc-detected provider sessions to the web runtime.
+
+import { inferPeerKind } from '../integrations/providers.mjs';
+import { runTmux } from '../tmux.mjs';
+import { inspectProviderProcess } from '../integrations/peers/processes.mjs';
+
+export function createAutoAttach(deps) {
+  const {
+    ctx, sessions,
+    connectWebProject, now, addEvent,
+    reconcileRunningPeerBindings,
+    ACTIVE_PEER_TTL, redactedLogText, sessionsForProject,
+    attachTmuxSession,
+    latestHookProviderSession,
+    resolveSessionPeerId,
+    reAdoptOrphanManagedTmuxSessions, reapDeadPeersForProject
+  } = deps;
+
+  function listTmuxPanesOnce() {
+    // Use '|' not '\t' as the field separator: older tmux (3.3a) replaces
+    // whitespace in -F output with '_'. Path is last and rejoined so a '|'
+    // inside a path is safe. tmux-8: session_name is NOT included here — a
+    // user-created session name could contain '|', corrupting the parse. Callers
+    // that need the session name use tmuxSessionNameForPane(pane.pane) which
+    // queries a single field with no separator issue.
+    const result = runTmux([
+      'list-panes',
+      '-a',
+      '-F',
+      '#{pane_id}|#{pane_pid}|#{pane_current_command}|#{pane_current_path}'
+    ]);
+    return result.trim().split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const parts = line.split('|');
+        return {
+          pane: parts[0],
+          pid: Number.parseInt(parts[1] || '0', 10) || null,
+          command: parts[2] || '',
+          sessionName: '',
+          cwd: parts.slice(3).join('|') || ''
+        };
+      })
+      .filter((pane) => pane.pane && pane.pid);
+  }
+
+  function attachedTmuxState(projectCtx, db) {
+    const peers = new Set();
+    const panes = new Set();
+    for (const session of sessionsForProject(projectCtx)) {
+      if (session.status !== 'running') continue;
+      peers.add(session.id);
+      if (session.peerId) peers.add(session.peerId);
+      const resolved = resolveSessionPeerId(db, session);
+      if (resolved) peers.add(resolved);
+      if (session.type === 'tmux' && session.pane) panes.add(session.pane);
+    }
+    return { peers, panes };
+  }
+
+  function reconcileRunningBindings(projectCtx = ctx, panes = null) {
+    const db = connectWebProject(projectCtx);
+    try {
+      const tmuxPanes = Array.isArray(panes) ? panes : listTmuxPanesOnce();
+      return reconcileRunningPeerBindings(db, projectCtx, {
+        panes: tmuxPanes,
+        inspectProcess: inspectProviderProcess,
+        latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
+        addEvent,
+        now
+      });
+    } catch {
+      return null;
+    } finally {
+      db.close();
+    }
+  }
+
+  let autoAttachScanInFlight = false;
+
+  function scanAndAttachDetectedPeers() {
+    if (autoAttachScanInFlight) return;
+    autoAttachScanInFlight = true;
+    let db = null;
+    try {
+      db = connectWebProject(ctx);
+
+      // Always-on, TTL-independent hygiene: recover managed tmux sessions left
+      // alive (default Stop = detach-without-kill, or across a restart) and reap
+      // peers whose process is gone. Sweep first so its live set protects
+      // still-alive sessions from being reaped.
+      const liveManaged = reAdoptOrphanManagedTmuxSessions(ctx);
+      reapDeadPeersForProject(ctx, liveManaged, db);
+
+      const rows = db.prepare(`
+        SELECT p.id, p.kind, p.role, p.worktree, p.pid,
+               b.peer AS binding_peer, b.provider, b.provider_session_id,
+               b.provider_session_name, b.resume_mode, b.resume_arg,
+               b.command AS binding_command, b.runtime_session_id,
+               b.runtime_target
+        FROM peers p
+        LEFT JOIN peer_bindings b ON b.peer = p.id
+        WHERE p.status IN ('running', 'working', 'busy')
+          AND p.pid IS NOT NULL
+          AND p.last_seen_at >= ? - ?
+        ORDER BY p.last_seen_at DESC
+      `).all(now(), ACTIVE_PEER_TTL);
+      if (!rows.length) return;
+
+      let panes;
+      try {
+        panes = listTmuxPanesOnce();
+      } catch {
+        return;
+      }
+      if (!panes.length) return;
+      const paneByPid = new Map();
+      for (const pane of panes) {
+        if (!paneByPid.has(pane.pid)) paneByPid.set(pane.pid, pane);
+      }
+      reconcileRunningPeerBindings(db, ctx, {
+        panes,
+        inspectProcess: inspectProviderProcess,
+        latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
+        addEvent,
+        now
+      });
+      const attached = attachedTmuxState(ctx, db);
+
+      for (const row of rows) {
+        if (attached.peers.has(row.id)) continue;
+        if (row.binding_peer && attached.peers.has(row.binding_peer)) continue;
+        if (row.runtime_session_id && attached.peers.has(row.runtime_session_id)) continue;
+
+        const pane = paneByPid.get(Number(row.pid));
+        if (!pane || attached.panes.has(pane.pane)) continue;
+
+        const binding = row.binding_peer ? {
+          provider: row.provider,
+          provider_session_id: row.provider_session_id,
+          provider_session_name: row.provider_session_name,
+          resume_mode: row.resume_mode,
+          resume_arg: row.resume_arg,
+          command: row.binding_command,
+          runtime_session_id: row.runtime_session_id || row.id,
+          runtime_target: pane.pane
+        } : null;
+        try {
+          const session = attachTmuxSession({
+            id: row.id,
+            pane: pane.pane,
+            kind: row.kind || inferPeerKind(row.id, null, pane.command),
+            role: row.role || 'peer',
+            cwd: pane.cwd || row.worktree || ctx.root,
+            command: row.binding_command || null,
+            force: false,
+            projectCtx: ctx,
+            binding,
+            autoAttach: true,
+            auditActorPeer: 'web-runtime',
+            auditSource: 'runtime'
+          });
+          attached.peers.add(row.id);
+          if (session.peerId) attached.peers.add(session.peerId);
+          attached.panes.add(pane.pane);
+        } catch {}
+      }
+    } catch (err) {
+      console.error(redactedLogText(`[${new Date().toISOString()}] auto-attach scan failed: ${err?.message || err}`));
+    } finally {
+      try { db?.close(); } catch {}
+      autoAttachScanInFlight = false;
+    }
+  }
+
+  scanAndAttachDetectedPeers();
+  const autoAttachPoller = setInterval(scanAndAttachDetectedPeers, 5000);
+
+  return {
+    autoAttachPoller, listTmuxPanesOnce, attachedTmuxState,
+    reconcileRunningBindings, scanAndAttachDetectedPeers
+  };
+}