@logicseek/hello-cc 0.1.9 → 1.0.0

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) {
@@ -119,6 +127,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 +157,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 +222,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
+  };
+}

package/lib/web/buffer-gc-runtime.mjs

@@ -0,0 +1,175 @@
+// Runtime-side automatic buffer GC, extracted from lib/web/runtime-main.mjs.
+// Plans and applies buffer-file GC with runtime arbitration: live-session
+// path snapshots, cross-project evidence collection, fenced plan tokens,
+// and the periodic auto-GC sweep.
+
+import path from 'node:path';
+import { CliError } from '../shared/errors.mjs';
+import { clockSafetyUnavailable } from '../core/coordination/clock-safety.mjs';
+import { collectBufferEvidence } from '../runtime/buffer-evidence.mjs';
+import { applyClockSafeBufferPlan, createBufferGcPlanStore } from '../runtime/buffer-gc-protocol.mjs';
+import { bufferPlanGcCutoffs, planBufferFiles } from '../runtime/buffer-gc.mjs';
+
+export function createBufferGcRuntime(deps) {
+  const {
+    sessions,
+    connectWebProject, runtimeProjectContexts,
+    now, runGc, bufferDirectory,
+    canonicalRoot, observePeerEvidence, redactedLogText, sameResolvedPath
+  } = deps;
+
+  const bufferGcPlanStore = createBufferGcPlanStore();
+  const bufferUnknownTracker = new Map();
+  const bufferDirectoriesByProject = new Map();
+
+  // ── Automatic GC ──────────────────────────────────────────────────────────
+  // Bound events/WAL growth without manual `hcc gc` (conc-05). Auto scope only
+  // prunes high-volume/ephemeral items (events >14d, expired locks, stale bufs),
+  // never peers/tasks/messages/handoffs. Runs once at startup then every 6h.
+  let autoGcInFlight = false;
+  function runningBufferPathSnapshot(projectCtx) {
+    const protectedPaths = new Set();
+    const projectKey = canonicalRoot(projectCtx.root) || path.resolve(projectCtx.root);
+    const projectDirectories = bufferDirectoriesByProject.get(projectKey) || new Set();
+    for (const session of sessions.values()) {
+      for (const file of [session.outFile, session.inFile, session.resizeFile, session.pipeFile, session.metaFile]) {
+        if (!file) continue;
+        const resolved = path.resolve(file);
+        if (sameResolvedPath(session.root, projectCtx.root)) projectDirectories.add(path.dirname(resolved));
+        if (session.status === 'running') protectedPaths.add(resolved);
+      }
+    }
+    bufferDirectoriesByProject.set(projectKey, projectDirectories);
+    return { protectedPaths, projectDirectories };
+  }
+
+  function collectRuntimeBufferEvidence(directories, candidatePaths = null) {
+    const projectDbs = [];
+    const opened = [];
+    try {
+      for (const projectCtx of runtimeProjectContexts()) {
+        try {
+          const db = connectWebProject(projectCtx, { migrateRegistered: false, create: false });
+          opened.push(db);
+          projectDbs.push({ ctx: projectCtx, db });
+        } catch (error) {
+          projectDbs.push({
+            ctx: projectCtx,
+            db: { prepare() { throw error; } }
+          });
+        }
+      }
+      return collectBufferEvidence({
+        directories,
+        projectDbs,
+        sessions: [...sessions.values()],
+        observePeer: observePeerEvidence,
+        unknownTracker: bufferUnknownTracker,
+        candidatePaths
+      });
+    } finally {
+      for (const db of opened) {
+        try { db.close(); } catch {}
+      }
+    }
+  }
+
+  function prepareRuntimeBufferGc(projectCtx, { dryRun, retentionSec }) {
+    const observedAt = now();
+    const cutoffMs = observedAt * 1000 - retentionSec * 1000;
+    const { projectDirectories } = runningBufferPathSnapshot(projectCtx);
+    const directories = new Set([bufferDirectory(projectCtx), ...projectDirectories]);
+    const { protectedPaths, unknownPaths, gcCutoffs } = collectRuntimeBufferEvidence(directories);
+    const plan = planBufferFiles({
+      directories,
+      cutoffMs,
+      protectedPaths,
+      unknownPaths,
+      evidenceGcCutoffs: gcCutoffs
+    });
+    const prepared = {
+      observedAt,
+      cutoffMs,
+      retentionSec,
+      deleted: plan.deleteEntries.length,
+      protected: plan.protectedEntries.length,
+      deferred: plan.unknownEntries.length,
+      gcCutoffs: bufferPlanGcCutoffs(plan, retentionSec)
+    };
+    if (!dryRun) {
+      prepared.token = bufferGcPlanStore.prepare({
+        root: projectCtx.root,
+        dbPath: projectCtx.dbPath,
+        observedAt,
+        retentionSec,
+        plan
+      });
+    }
+    return prepared;
+  }
+
+  function applyPreparedRuntimeBufferGc(projectCtx, token) {
+    const prepared = bufferGcPlanStore.take({
+      token,
+      root: projectCtx.root,
+      dbPath: projectCtx.dbPath
+    });
+    let db = null;
+    try {
+      db = connectWebProject(projectCtx);
+      return applyClockSafeBufferPlan({
+        db,
+        plan: prepared.plan,
+        retentionSec: prepared.retentionSec,
+        nowSec: now,
+        collectEvidence: ({ entries }) => collectRuntimeBufferEvidence(
+          new Set(entries.map((entry) => entry.directory.path)),
+          entries.map((entry) => entry.path)
+        )
+      });
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw clockSafetyUnavailable(error);
+    } finally {
+      try { db?.close(); } catch {}
+    }
+  }
+
+  function runAutoGc() {
+    if (autoGcInFlight) return;
+    autoGcInFlight = true;
+    try {
+      for (const projectCtx of runtimeProjectContexts()) {
+        let db = null;
+        try {
+          db = connectWebProject(projectCtx, { migrateRegistered: false, create: false });
+          const result = runGc(projectCtx, db, {
+            olderThanDays: 14,
+            dryRun: false,
+            scope: 'auto',
+            collectBufferEvidenceNow: () => collectRuntimeBufferEvidence([
+              bufferDirectory(projectCtx)
+            ])
+          });
+          const appliedDatabaseRows = result.expired_locks + result.old_events;
+          if (appliedDatabaseRows > 0) {
+            try { db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get(); } catch {}
+          }
+        } catch (err) {
+          console.error(redactedLogText(`[${new Date().toISOString()}] auto-gc failed for ${projectCtx.root}: ${err?.message || err}`));
+        } finally {
+          try { db?.close(); } catch {}
+        }
+      }
+    } finally {
+      autoGcInFlight = false;
+    }
+  }
+  const gcPoller = setInterval(runAutoGc, 6 * 60 * 60 * 1000);
+
+  return {
+    gcPoller, runAutoGc,
+    collectRuntimeBufferEvidence, prepareRuntimeBufferGc, applyPreparedRuntimeBufferGc,
+    runningBufferPathSnapshot, bufferGcPlanStore
+  };
+}