sealcode 0.1.0 → 1.1.0

package/src/cli-watch.js

@@ -0,0 +1,862 @@
+'use strict';
+
+/**
+ * `sealcode watch <code>` — long-running agent for an access-code recipient.
+ *
+ * This is the missing piece of the "real-time revoke" story:
+ *
+ *   On the OWNER side: `sealcode share` mints a code, `sealcode revoke`
+ *   (or the dashboard) kills it.
+ *
+ *   On the RECIPIENT side: `sealcode redeem` validates the code once and
+ *   (since 1.0.0) unwraps a team-shared K straight into the session
+ *   cache; then `sealcode unlock` materializes plaintext. While they're
+ *   working, `sealcode watch <code>` polls the heartbeat endpoint and:
+ *
+ *     - prints a live status line so the demo is visible
+ *     - on `action: "lock"` (revoked / expired / auto-lock / strict-mode
+ *       device mismatch), it immediately runs the same lock pipeline as
+ *       `sealcode lock`, wipes the cached session, and exits status 0.
+ *     - on `action: "warn"` (close to expiry), warns the user.
+ *     - on transient network failure, retries with backoff; after the
+ *       grant's `offlineGraceSeconds` it self-locks (strict mode) or
+ *       warns (lenient mode).
+ *     - watches the project root with fs.watch and raises EXFIL ALERTS to
+ *       the server when heuristics trip (mass reads, mass bytes, a tar/zip
+ *       process touching the dir, a new git remote, dir moved/renamed).
+ *
+ * The watcher does NOT need an account / login — the access code itself
+ * is the authentication for these endpoints. That matches the contractor
+ * flow: they may not have a sealcode.dev account at all.
+ *
+ * --daemon mode (sealcode@1.0.0+):
+ *   When invoked with --daemon, the watcher detaches from the parent's
+ *   stdio and writes structured JSONL events to ~/.sealcode/logs/<id>.jsonl.
+ *   This is the form auto-spawned by `runUnlock` when the session was
+ *   derived from a grant (so the contractor doesn't have to remember to
+ *   run watch by hand).
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+
+const { request, ApiError, clientInfo } = require('./api');
+const { loadConfig } = require('./config');
+const { detectPreset } = require('./presets');
+const {
+  isInitialized,
+  loadSession,
+  loadSessionMeta,
+  updateSessionMeta,
+  clearSession,
+  projectId,
+} = require('./keystore');
+const { runLock } = require('./seal');
+const { getDeviceFingerprint } = require('./device');
+const { SealcodeError } = require('./errors');
+const grantPolicy = require('./grant-policy');
+const pkg = require('../package.json');
+const ui = require('./ui');
+
+const DEFAULT_INTERVAL_SEC = 30;
+const MIN_INTERVAL_SEC = 5;
+const MAX_INTERVAL_SEC = 600;
+const TRANSIENT_BACKOFF_SEC = 5;
+
+// Where the watcher writes its heartbeat sidecar — cli-guard reads this to
+// decide whether a grant-derived session is still being supervised.
+const WATCH_STATE_DIR = path.join(os.homedir(), '.sealcode', 'sessions');
+const WATCH_LOG_DIR = path.join(os.homedir(), '.sealcode', 'logs');
+
+function watchStateFile(projectRoot) {
+  return path.join(WATCH_STATE_DIR, `${projectId(projectRoot)}.watch.json`);
+}
+function watchLogFile(projectRoot) {
+  return path.join(WATCH_LOG_DIR, `${projectId(projectRoot)}.jsonl`);
+}
+
+function getActiveConfig(projectRoot) {
+  const fromFile = loadConfig(projectRoot);
+  if (fromFile) return fromFile;
+  const preset = detectPreset(projectRoot);
+  return {
+    version: 1,
+    preset: preset.id,
+    lockedDir: preset.lockedDir,
+    include: preset.include,
+    exclude: preset.exclude,
+    stubs: preset.stubs || {},
+    _file: null,
+    _implicit: true,
+  };
+}
+
+function fmtRemaining(ms) {
+  if (ms == null) return '';
+  if (ms <= 0) return 'expired';
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ${sec % 60}s`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ${min % 60}m`;
+  return `${Math.floor(hr / 24)}d ${hr % 24}h`;
+}
+
+function ts() {
+  return new Date().toTimeString().slice(0, 8);
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true, mode: 0o700 });
+}
+
+function writeWatchState(projectRoot, patch) {
+  ensureDir(WATCH_STATE_DIR);
+  const p = watchStateFile(projectRoot);
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) { /* fresh file */ }
+  const merged = { ...existing, ...patch, updatedAt: new Date().toISOString() };
+  fs.writeFileSync(p, JSON.stringify(merged) + '\n', { mode: 0o600 });
+  return merged;
+}
+
+function deleteWatchState(projectRoot) {
+  try {
+    fs.unlinkSync(watchStateFile(projectRoot));
+  } catch (_) { /* ignore */ }
+}
+
+function appendLog(projectRoot, event) {
+  ensureDir(WATCH_LOG_DIR);
+  try {
+    fs.appendFileSync(
+      watchLogFile(projectRoot),
+      JSON.stringify({ at: new Date().toISOString(), ...event }) + '\n',
+    );
+  } catch (_) { /* best-effort */ }
+}
+
+/**
+ * Single heartbeat round-trip.
+ */
+async function heartbeatOnce(code, extras) {
+  try {
+    const res = await request('POST', '/api/v1/access/heartbeat', {
+      body: {
+        code,
+        watcherPid: process.pid,
+        watcherVersion: pkg.version,
+        deviceFingerprint: getDeviceFingerprint(),
+        ...(extras || {}),
+      },
+      // sealcode@1.1.0 — long-poll allowed up to ~30s; we leave ~5s of
+      // headroom over the server's `waitMs` for the TCP round trip
+      // before our local request timeout fires.
+      timeoutMs: extras && extras.waitMs ? extras.waitMs + 5000 : undefined,
+    });
+    return { ok: true, response: res };
+  } catch (err) {
+    if (err instanceof ApiError) {
+      if (err.status === 0 || err.status >= 500) {
+        return { ok: false, transient: true, err };
+      }
+      throw new SealcodeError('SEALCODE_WATCH_BAD_CODE', {
+        detail: `Heartbeat rejected (${err.status} ${err.apiCode}): ${err.message}`,
+        hint: 'Try: sealcode redeem <code>   (re-validate the access code)',
+      });
+    }
+    return { ok: false, transient: true, err };
+  }
+}
+
+/**
+ * Post a batch of per-file activity events. sealcode@1.1.0 — these feed
+ * the dashboard's per-grant "what did they touch" timeline. Best-effort.
+ */
+async function postFileEvents(code, events) {
+  if (!events || events.length === 0) return;
+  try {
+    await request('POST', '/api/v1/access/file-events', {
+      body: {
+        code,
+        events,
+        deviceFingerprint: getDeviceFingerprint(),
+      },
+    });
+  } catch (_) { /* never tear down the watcher over telemetry */ }
+}
+
+/**
+ * Post a structured exfil alert to the server. Best-effort — failure is
+ * logged locally but doesn't tear down the watcher.
+ */
+async function postAlert(code, alert) {
+  try {
+    await request('POST', '/api/v1/access/alerts', {
+      body: {
+        code,
+        kind: alert.kind,
+        severity: alert.severity || 'warn',
+        summary: alert.summary,
+        detail: alert.detail || {},
+        deviceFingerprint: getDeviceFingerprint(),
+        hostname: os.hostname(),
+        ...clientInfo(),
+      },
+    });
+  } catch (_) {
+    // We never let a failed alert bring down the watcher.
+  }
+}
+
+/**
+ * Lightweight exfiltration heuristics. Runs inside the watcher process,
+ * polls cheap signals every few seconds, and posts alerts when thresholds
+ * trip. Deliberately heuristic — false positives are fine (owner can
+ * dismiss), false negatives are the failure mode.
+ *
+ * Tracked signals:
+ *   - file count opened in last 60s (uses fs.watch counts)
+ *   - bytes read in last 60s (uses fs.watch + stat sizes, capped)
+ *   - presence of suspicious processes (tar/zip/cp/rsync/scp) on Unix
+ *   - new git remotes added (diff vs initial remote set)
+ *   - project root moved or renamed (we hold the inode; if it disappears
+ *     the watcher just locks because the manifest is gone)
+ *
+ * @returns {{stop: () => void}}
+ */
+function startExfilWatchers({
+  projectRoot,
+  code,
+  config,
+  onAlert,
+  // sealcode@1.1.0 — per-event hook for the per-file activity log + the
+  // idle-lock + RO-violation detectors. All optional; legacy callers
+  // (no per-file reporting) can omit.
+  onFileEvent = null,
+}) {
+  const lockedDir = config.lockedDir || 'vendor';
+  const projectAbs = path.resolve(projectRoot);
+  const lockedAbs = path.join(projectAbs, lockedDir);
+
+  let stopped = false;
+
+  // Rolling 60s window of file events.
+  const windowMs = 60_000;
+  const events = []; // { at, kind, path, size? }
+  function prune(now) {
+    const cutoff = now - windowMs;
+    while (events.length && events[0].at < cutoff) events.shift();
+  }
+  function bytesInWindow() {
+    let total = 0;
+    for (const e of events) total += e.size || 0;
+    return total;
+  }
+  function countInWindow() { return events.length; }
+
+  // Watch the project root recursively for change/rename events. macOS
+  // and Linux both support recursive watch on the root; Linux gives
+  // per-file events via inotify.
+  let watcher;
+  try {
+    watcher = fs.watch(projectAbs, { recursive: true, persistent: false }, (event, filename) => {
+      if (stopped || !filename) return;
+      // Ignore everything under lockedDir (those are the encrypted blobs
+      // we ourselves write during lock — would self-trigger constantly).
+      const rel = String(filename);
+      if (rel.startsWith(lockedDir + path.sep) || rel === lockedDir) return;
+      // Don't try to stat — fs.watch can fire AFTER the file was deleted.
+      let size = 0;
+      try {
+        const st = fs.statSync(path.join(projectAbs, rel));
+        if (st.isFile()) size = st.size;
+      } catch (_) { /* fine */ }
+      const now = Date.now();
+      events.push({ at: now, kind: event, path: rel, size });
+      prune(now);
+      // sealcode@1.1.0 — surface per-event signal upward. We translate
+      // fs.watch's "rename"/"change" into the canonical kinds the
+      // server's file-events table expects.
+      if (onFileEvent) {
+        let kind = 'modified';
+        if (event === 'rename') {
+          kind = fs.existsSync(path.join(projectAbs, rel)) ? 'renamed' : 'deleted';
+        }
+        try {
+          onFileEvent({ path: rel, kind, sizeBytes: size, occurredAt: new Date(now).toISOString() });
+        } catch (_) { /* observer must not crash the watcher */ }
+      }
+    });
+    watcher.on('error', () => { /* fs.watch can race; ignore */ });
+  } catch (_) {
+    // Some platforms (notably some container images) can't do recursive
+    // watch. Heuristic just won't fire — not fatal.
+  }
+
+  // Pin initial git remote set so we can detect "new remote added".
+  let initialRemotes = '';
+  try {
+    const cp = require('child_process');
+    initialRemotes = cp
+      .execFileSync('git', ['-C', projectAbs, 'remote', '-v'], {
+        encoding: 'utf8',
+        timeout: 1500,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      .trim();
+  } catch (_) { /* repo may not have git */ }
+
+  // Pin initial project-root inode/mtime so we can detect "dir moved".
+  let initialStat = null;
+  try {
+    initialStat = fs.statSync(projectAbs);
+  } catch (_) { /* nothing we can do */ }
+
+  // Thresholds. Configurable via env so power-users can tune; defaults
+  // chosen so a normal coding session (saving a few files / running
+  // tests) never trips them, but `tar -czf` of the project does.
+  const FILES_THRESHOLD = parseInt(process.env.SEALCODE_EXFIL_FILES || '120', 10);
+  const BYTES_THRESHOLD = parseInt(process.env.SEALCODE_EXFIL_BYTES || String(50 * 1024 * 1024), 10);
+  const SUSPICIOUS_BINARIES = new Set(['tar', 'gtar', 'bsdtar', 'zip', 'gzip', '7z', 'rsync', 'scp']);
+
+  // Process scanner — only on Unix; uses /proc on Linux, ps on macOS.
+  function suspiciousProcesses() {
+    try {
+      if (process.platform === 'linux') {
+        const dir = '/proc';
+        const out = [];
+        for (const pid of fs.readdirSync(dir)) {
+          if (!/^\d+$/.test(pid)) continue;
+          let cmdline = '';
+          try {
+            cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+          } catch (_) { continue; }
+          if (!cmdline) continue;
+          const argv = cmdline.split('\0').filter(Boolean);
+          const exe = path.basename(argv[0] || '').toLowerCase();
+          if (SUSPICIOUS_BINARIES.has(exe) && argv.slice(1).some((a) => a.includes(projectAbs))) {
+            out.push({ pid, exe, cmd: argv.join(' ').slice(0, 200) });
+          }
+        }
+        return out;
+      }
+      if (process.platform === 'darwin') {
+        const cp = require('child_process');
+        const out = cp
+          .execFileSync('ps', ['-axo', 'pid=,comm=,args='], {
+            encoding: 'utf8',
+            timeout: 1500,
+            stdio: ['ignore', 'pipe', 'ignore'],
+          })
+          .split('\n');
+        const matches = [];
+        for (const line of out) {
+          const m = line.trim().match(/^(\d+)\s+(\S+)\s+(.*)$/);
+          if (!m) continue;
+          const [, pid, comm, args] = m;
+          const exe = path.basename(comm).toLowerCase();
+          if (SUSPICIOUS_BINARIES.has(exe) && args.includes(projectAbs)) {
+            matches.push({ pid, exe, cmd: args.slice(0, 200) });
+          }
+        }
+        return matches;
+      }
+    } catch (_) { /* ignore */ }
+    return [];
+  }
+
+  // Sweep loop. We dedupe alerts so a single tar invocation doesn't
+  // spam the server.
+  const recentlyFired = new Map(); // kind -> lastFiredAt
+  function maybeFire(kind, severity, summary, detail) {
+    const last = recentlyFired.get(kind) || 0;
+    if (Date.now() - last < 60_000) return;
+    recentlyFired.set(kind, Date.now());
+    onAlert({ kind, severity, summary, detail });
+  }
+
+  const sweepTimer = setInterval(() => {
+    if (stopped) return;
+    prune(Date.now());
+
+    const files = countInWindow();
+    const bytes = bytesInWindow();
+    if (files > FILES_THRESHOLD) {
+      maybeFire('mass_read', 'alert',
+        `Read or wrote ${files} files in the last 60s under ${projectAbs}.`,
+        { files, projectAbs });
+    }
+    if (bytes > BYTES_THRESHOLD) {
+      maybeFire('mass_bytes', 'alert',
+        `Touched ${(bytes / 1024 / 1024).toFixed(1)} MB of project files in the last 60s.`,
+        { bytes, projectAbs });
+    }
+
+    const susp = suspiciousProcesses();
+    if (susp.length > 0) {
+      maybeFire('archiver_process', 'alert',
+        `Detected ${susp[0].exe} touching the project root (${susp[0].cmd}).`,
+        { processes: susp });
+    }
+
+    // Git remote drift
+    try {
+      const cp = require('child_process');
+      const cur = cp
+        .execFileSync('git', ['-C', projectAbs, 'remote', '-v'], {
+          encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        .trim();
+      if (initialRemotes && cur !== initialRemotes) {
+        maybeFire('git_remote_changed', 'alert',
+          `git remotes changed since the watcher started.`,
+          { before: initialRemotes, after: cur });
+        initialRemotes = cur;
+      }
+    } catch (_) { /* repo may not have git */ }
+
+    // Project moved/renamed
+    if (initialStat) {
+      try {
+        const s = fs.statSync(projectAbs);
+        if (s.ino !== initialStat.ino) {
+          maybeFire('project_moved', 'alert',
+            `Project root inode changed — directory may have been moved or replaced.`,
+            { wasIno: initialStat.ino, nowIno: s.ino });
+        }
+      } catch (_) {
+        maybeFire('project_disappeared', 'alert',
+          `Project root no longer exists at ${projectAbs}.`, {});
+      }
+    }
+  }, 5000);
+
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(sweepTimer);
+      try { watcher && watcher.close(); } catch (_) { /* ignore */ }
+    },
+  };
+}
+
+/**
+ * The CLI entry. Options:
+ *   - intervalSec: override server-suggested poll interval
+ *   - verbose:     print every tick instead of one live line
+ *   - json:        emit JSONL to stdout (used by --daemon)
+ *   - daemon:      detach from TTY, write JSONL to log file, no stdout
+ *   - exfil:       enable file-system exfiltration heuristics (default true)
+ */
+async function runWatch({
+  projectRoot,
+  code,
+  intervalSec,
+  verbose = false,
+  json = false,
+  daemon = false,
+  exfil = true,
+}) {
+  if (!code || typeof code !== 'string') {
+    throw new SealcodeError('SEALCODE_WATCH_NO_CODE', {
+      detail: 'Pass the access code as the first argument.',
+      hint: 'Try: sealcode watch SC-XXXX-XXXX-XXXX-XXXX',
+    });
+  }
+  const config = getActiveConfig(projectRoot);
+  if (!isInitialized(projectRoot, config.lockedDir)) {
+    throw new SealcodeError('SEALCODE_NO_MANIFEST');
+  }
+
+  const trimmedCode = code.trim();
+
+  // First call doubles as a fast-fail validator and as a way to learn the
+  // server-side heartbeat interval, which we honor unless --interval is
+  // explicitly set.
+  const first = await heartbeatOnce(trimmedCode);
+  if (!first.ok) {
+    throw new SealcodeError('SEALCODE_WATCH_OFFLINE', {
+      detail: `Cannot reach sealcode.dev: ${first.err?.message || 'network error'}.`,
+      hint: 'Try: check connectivity, then re-run `sealcode watch`.',
+    });
+  }
+  const serverInterval = Number(first.response?.heartbeatIntervalSeconds) || DEFAULT_INTERVAL_SEC;
+  const effectiveInterval = Math.max(
+    MIN_INTERVAL_SEC,
+    Math.min(MAX_INTERVAL_SEC, intervalSec || serverInterval),
+  );
+  const offlineGraceSec = Number(first.response?.offlineGraceSeconds) || 1800;
+  const strict = !!first.response?.strictMode;
+  // sealcode@1.1.0 — pull policy from the session meta (set by redeem)
+  // and from the heartbeat echo (in case the owner edited the grant
+  // after redeem). Local session is authoritative for mode/idle —
+  // server's heartbeat policy is just a refresh hint.
+  const sessionMeta = loadSessionMeta(projectRoot) || {};
+  const policy = grantPolicy.normalize(
+    (sessionMeta.meta && sessionMeta.meta.policy) || first.response?.policy || {},
+  );
+  // Long-poll budget. We pick min(server_interval * 1000, 25_000).
+  // ~25s wait keeps the open connection well under typical load-balancer
+  // / proxy idle timeouts (30s on most). When wait elapses we just go
+  // around again immediately.
+  const waitMs = Math.min(25_000, effectiveInterval * 1000);
+
+  // Heartbeat sidecar — read by cli-guard.js to decide whether the
+  // grant-derived session is still being supervised. We touch it every
+  // tick; stale mtime = dead watcher.
+  writeWatchState(projectRoot, {
+    pid: process.pid,
+    code: trimmedCode,
+    startedAt: new Date().toISOString(),
+    intervalSec: effectiveInterval,
+    strict,
+    daemon: !!daemon,
+  });
+  // Record the watcher pid in the session meta too — guard checks both.
+  updateSessionMeta(projectRoot, {
+    watchPidFile: watchStateFile(projectRoot),
+    strictWatch: strict,
+  });
+
+  // If we somehow started watching an already-locked grant, lock first
+  // and exit. Don't pretend everything's fine.
+  if (first.response.action === 'lock') {
+    return finalLock(projectRoot, config, trimmedCode, first.response.reason, json, daemon);
+  }
+
+  if (daemon) {
+    appendLog(projectRoot, { type: 'start', intervalSec: effectiveInterval, ...first.response });
+  } else if (json) {
+    process.stdout.write(
+      JSON.stringify({ type: 'start', intervalSec: effectiveInterval, ...first.response }) + '\n',
+    );
+  } else {
+    ui.box('Watching access code', [
+      `${ui.c.dim('code      ')} ${ui.c.bold(trimmedCode)}`,
+      `${ui.c.dim('interval  ')} every ${effectiveInterval}s`,
+      `${ui.c.dim('expires   ')} ${first.response.expiresAt || '(unknown)'}`,
+      first.response.autoLockAt
+        ? `${ui.c.dim('auto-lock ')} ${first.response.autoLockAt}`
+        : `${ui.c.dim('auto-lock ')} ${ui.c.dim('(none)')}`,
+      `${ui.c.dim('strict    ')} ${strict ? ui.c.yellow('yes — files will lock if I am killed') : 'no'}`,
+      '',
+      ui.c.dim('Press Ctrl-C to stop. If the owner revokes this code, your local'),
+      ui.c.dim('files will be re-locked automatically.'),
+    ]);
+  }
+
+  // First tick line right after the box so demos look alive immediately.
+  printTick(first.response, json, verbose, daemon, projectRoot);
+
+  // sealcode@1.1.0 — track file activity (for the activity timeline +
+  // idle-lock + RO-violation detection). We buffer per-file events
+  // between heartbeats and flush them with each tick.
+  const fileEventBuffer = [];
+  let lastFsActivityAt = Date.now();
+  let roViolationPending = null; // { path, at } or null
+  const FILE_EVENT_BUFFER_MAX = 500;
+
+  // Exfil heuristics
+  let exfilCtrl = null;
+  if (exfil) {
+    exfilCtrl = startExfilWatchers({
+      projectRoot,
+      code: trimmedCode,
+      config,
+      onAlert: (a) => {
+        appendLog(projectRoot, { type: 'exfil_alert', ...a });
+        if (!daemon && !json) ui.warn(`[${ts()}] ⚠ ${a.summary}`);
+        void postAlert(trimmedCode, a);
+      },
+      onFileEvent: (ev) => {
+        lastFsActivityAt = Date.now();
+        // RO violation: any modification of an unlocked file means the
+        // recipient bypassed the chmod 0444 (chmod is advisory on
+        // Unix and not enforced for root / chattr). Trigger an immediate
+        // re-lock + alert.
+        if (policy.mode === 'ro' && (ev.kind === 'modified' || ev.kind === 'created' || ev.kind === 'deleted' || ev.kind === 'renamed')) {
+          if (!roViolationPending) {
+            roViolationPending = { path: ev.path, at: ev.occurredAt };
+          }
+        }
+        if (fileEventBuffer.length < FILE_EVENT_BUFFER_MAX) {
+          fileEventBuffer.push(ev);
+        }
+      },
+    });
+  }
+
+  // Signal handling. In strict mode, ANY exit path (SIGINT, SIGTERM)
+  // must re-lock the project before we die — otherwise the contractor
+  // could just Ctrl-C the watcher to keep plaintext.
+  let stopped = false;
+  const cleanup = async (reason) => {
+    if (stopped) return;
+    stopped = true;
+    if (exfilCtrl) exfilCtrl.stop();
+    deleteWatchState(projectRoot);
+    if (strict) {
+      appendLog(projectRoot, { type: 'strict_exit_lock', reason });
+      await finalLock(projectRoot, config, trimmedCode, `strict:${reason}`, json, daemon).catch(() => {});
+    } else {
+      if (!json && !daemon) ui.say('\n' + ui.c.dim('stopped watching (lenient mode — files left as-is)'));
+    }
+    process.exit(0);
+  };
+  process.on('SIGINT', () => { void cleanup('sigint'); });
+  process.on('SIGTERM', () => { void cleanup('sigterm'); });
+  process.on('SIGHUP', () => { void cleanup('sighup'); });
+
+  // Poll loop with offline-grace.
+  //
+  // sealcode@1.1.0 — we use HTTP long-poll (`waitMs`) for near-instant
+  // revoke. The server holds the heartbeat open for up to ~25s and
+  // returns immediately when a lock event fires for our grant. If it
+  // returns "ok"/"warn" naturally, we go around the loop again with
+  // no additional sleep — long-poll already burned the interval.
+  let consecutiveTransient = 0;
+  let firstTransientAt = 0;
+  let lastFlushAt = 0;
+  while (!stopped) {
+    if (stopped) break;
+    writeWatchState(projectRoot, { lastTickAt: new Date().toISOString() });
+
+    // Self-reports (idle / ro-violation) MUST flush before we hit the
+    // long-poll heartbeat — the server uses the self-report kind to
+    // audit the lock with the right reason.
+    if (policy.mode === 'ro' && roViolationPending) {
+      const violation = roViolationPending;
+      roViolationPending = null;
+      try {
+        await heartbeatOnce(trimmedCode, {
+          selfReport: { reason: 'ro_violation', detail: violation.path.slice(0, 200) },
+        });
+      } catch (_) { /* fall through; we lock either way */ }
+      appendLog(projectRoot, { type: 'ro_violation', path: violation.path });
+      if (!daemon && !json) ui.warn(`[${ts()}] ⚠ read-only violation: ${violation.path} — re-locking`);
+      return finalLock(projectRoot, config, trimmedCode, 'ro_violation', json, daemon);
+    }
+    if (policy.idleAutoLockMinutes > 0) {
+      const idleMs = Date.now() - lastFsActivityAt;
+      if (idleMs >= policy.idleAutoLockMinutes * 60_000) {
+        try {
+          await heartbeatOnce(trimmedCode, {
+            selfReport: { reason: 'idle_lock', detail: `idle ${Math.floor(idleMs / 60_000)}m` },
+          });
+        } catch (_) { /* lock anyway */ }
+        appendLog(projectRoot, { type: 'idle_lock', idleMs });
+        if (!daemon && !json) ui.warn(`[${ts()}] ⏰ idle ${Math.floor(idleMs / 60_000)}m — auto-locking`);
+        return finalLock(projectRoot, config, trimmedCode, 'idle_lock', json, daemon);
+      }
+    }
+
+    // Flush per-file activity batch (at most once every 10s; otherwise
+    // we'd hit the rate limiter on `access.file-events`).
+    if (fileEventBuffer.length > 0 && Date.now() - lastFlushAt > 10_000) {
+      const batch = fileEventBuffer.splice(0, fileEventBuffer.length);
+      lastFlushAt = Date.now();
+      void postFileEvents(trimmedCode, batch);
+    }
+
+    let r;
+    try {
+      r = await heartbeatOnce(trimmedCode, { waitMs });
+    } catch (err) {
+      throw err;
+    }
+    if (!r.ok) {
+      const now = Date.now();
+      if (consecutiveTransient === 0) firstTransientAt = now;
+      consecutiveTransient += 1;
+      const offlineSec = Math.floor((now - firstTransientAt) / 1000);
+      const msg = `transient: ${r.err?.message || 'network'} (offline ${offlineSec}s / ${offlineGraceSec}s grace, retry in ${TRANSIENT_BACKOFF_SEC}s)`;
+      if (daemon) {
+        appendLog(projectRoot, { type: 'transient', error: String(r.err?.message || r.err), offlineSec });
+      } else if (json) {
+        process.stdout.write(JSON.stringify({ type: 'transient', error: String(r.err?.message || r.err), offlineSec }) + '\n');
+      } else {
+        ui.warn(`[${ts()}] ${msg}`);
+      }
+      if (offlineSec >= offlineGraceSec) {
+        return finalLock(projectRoot, config, trimmedCode, 'offline_grace_exceeded', json, daemon);
+      }
+      await sleep(TRANSIENT_BACKOFF_SEC * 1000);
+      continue;
+    }
+    consecutiveTransient = 0;
+    if (r.response.action === 'lock') {
+      return finalLock(projectRoot, config, trimmedCode, r.response.reason, json, daemon);
+    }
+    printTick(r.response, json, verbose, daemon, projectRoot);
+    // After a successful (possibly long-polled) heartbeat we do NOT
+    // sleep here — long-poll already consumed our budget. If the server
+    // returned quickly (no wait) we still loop immediately; that's
+    // fine, the inner heartbeat handles its own pacing.
+  }
+}
+
+function printTick(resp, json, verbose, daemon, projectRoot) {
+  if (daemon) {
+    appendLog(projectRoot, { type: 'tick', ...resp });
+    return;
+  }
+  if (json) {
+    process.stdout.write(JSON.stringify({ type: 'tick', ...resp }) + '\n');
+    return;
+  }
+  const remaining = fmtRemaining(resp.remainingMs);
+  if (resp.action === 'warn') {
+    ui.warn(`[${ts()}] ${ui.c.yellow('warn')} — ${remaining} left, lock incoming`);
+  } else if (verbose) {
+    ui.say(`[${ts()}] ${ui.c.green('ok')} — ${remaining} left`);
+  } else {
+    if (ui.STDERR_TTY) {
+      process.stderr.write(
+        `\r${ui.c.green('●')} watching · ${ui.c.dim(ts())} · ${ui.c.dim(remaining + ' left')}\x1b[K`,
+      );
+    } else {
+      ui.say(`[${ts()}] ok — ${remaining} left`);
+    }
+  }
+}
+
+async function finalLock(projectRoot, config, code, reason, json, daemon) {
+  if (!json && !daemon && ui.STDERR_TTY) process.stderr.write('\r\x1b[K');
+  const label = reason || 'lock';
+  if (daemon) {
+    appendLog(projectRoot, { type: 'lock', reason: label });
+  } else if (json) {
+    process.stdout.write(JSON.stringify({ type: 'lock', reason: label }) + '\n');
+  } else {
+    ui.warn(`[${ts()}] server says LOCK — reason: ${ui.c.bold(label)}`);
+  }
+
+  const K = loadSession(projectRoot);
+  if (!K) {
+    deleteWatchState(projectRoot);
+    if (!json && !daemon) {
+      ui.fail('access revoked — but no cached session was found, so there is nothing to re-lock here.');
+      ui.hint('  (this is normal if you never ran `sealcode unlock` on this machine.)');
+    }
+    process.exit(2);
+  }
+
+  // sealcode@1.1.0 — for grant-derived sessions that had a path scope
+  // (or any future "subset-only" policy), preserve out-of-scope blobs
+  // so the contractor's re-lock doesn't wipe the project for everyone.
+  const _sessionMeta = loadSessionMeta(projectRoot);
+  const _preserveUnseen =
+    !!_sessionMeta &&
+    _sessionMeta.meta &&
+    _sessionMeta.meta.source === 'grant' &&
+    _sessionMeta.meta.policy &&
+    Array.isArray(_sessionMeta.meta.policy.allowedPaths) &&
+    _sessionMeta.meta.policy.allowedPaths.length > 0;
+
+  let res;
+  try {
+    res = await runLock({ projectRoot, config, K, preserveUnseen: _preserveUnseen });
+  } catch (err) {
+    if (daemon) appendLog(projectRoot, { type: 'lock_error', error: String(err.message || err) });
+    else if (!json) ui.fail(`re-lock failed: ${err.message}`);
+    process.exit(3);
+  }
+  clearSession(projectRoot);
+  deleteWatchState(projectRoot);
+  if (daemon) {
+    appendLog(projectRoot, { type: 'locked', count: res.count, reason: label });
+  } else if (json) {
+    process.stdout.write(JSON.stringify({ type: 'locked', count: res.count, reason: label }) + '\n');
+  } else {
+    ui.ok(`[${ts()}] re-locked ${ui.c.bold(res.count)} files into ${ui.c.cyan(config.lockedDir + '/')} — session cleared`);
+    ui.hint('  Your local plaintext has been wiped. Ask the owner for a fresh code if you still need access.');
+  }
+  process.exit(0);
+}
+
+/**
+ * Helper: spawn a detached `sealcode watch <code> --daemon` child. Used
+ * by runUnlock when the unlock came from a grant-derived session.
+ * Returns the child pid (already detached). Best-effort.
+ */
+function spawnDaemonWatcher({ projectRoot, code }) {
+  try {
+    ensureDir(WATCH_LOG_DIR);
+    const bin = process.execPath;
+    const entry = require.resolve('../bin/sealcode.js');
+    const child = spawn(
+      bin,
+      [entry, 'watch', code, '--daemon'],
+      {
+        cwd: projectRoot,
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, SEALCODE_AUTO_DAEMON: '1' },
+      },
+    );
+    child.unref();
+    return { pid: child.pid };
+  } catch (err) {
+    return { error: String(err.message || err) };
+  }
+}
+
+/**
+ * Check whether a daemon watcher is currently running for this project.
+ * Used by cli-guard. Returns one of:
+ *   { state: 'none' }           no watch state file
+ *   { state: 'alive', pid }     pid exists + heartbeat fresh
+ *   { state: 'stale', pid }     heartbeat older than 3 * interval
+ *   { state: 'dead',  pid }     process not found
+ */
+function readWatcherStatus(projectRoot) {
+  const p = watchStateFile(projectRoot);
+  if (!fs.existsSync(p)) return { state: 'none' };
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return { state: 'none' };
+  }
+  const pid = state.pid;
+  if (typeof pid !== 'number') return { state: 'none' };
+  // Process exists?
+  let alive = false;
+  try {
+    process.kill(pid, 0);
+    alive = true;
+  } catch (_) {
+    alive = false;
+  }
+  if (!alive) return { state: 'dead', pid };
+  // Heartbeat fresh?
+  const interval = Number(state.intervalSec) || DEFAULT_INTERVAL_SEC;
+  const last = state.lastTickAt
+    ? Date.parse(state.lastTickAt)
+    : state.startedAt
+    ? Date.parse(state.startedAt)
+    : 0;
+  if (!last || Date.now() - last > 3 * interval * 1000) {
+    return { state: 'stale', pid, lastTickAt: state.lastTickAt };
+  }
+  return { state: 'alive', pid };
+}
+
+module.exports = {
+  runWatch,
+  spawnDaemonWatcher,
+  readWatcherStatus,
+  watchStateFile,
+  watchLogFile,
+};