polygram 0.17.10 → 0.17.12

package/lib/tmux/log-tail.js

@@ -1,334 +0,0 @@
-/**
- * LogTail — generic append-only file tailer. Emits 'line' events as
- * new lines arrive.
- *
- * Used by TmuxProcess to follow claude's per-session JSONL conversation
- * file (`~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl`) so we can
- * surface structured assistant + tool + usage + stop_reason events on
- * the tmux backend. The class itself is backend-agnostic — it just
- * tails a file.
- *
- * (Originally named DebugLogTail when the design assumed we'd parse
- * `--debug-file` output. The v9 probe showed that channel carries only
- * MDM/MCP infra messages and zero conversation events; the JSONL
- * session file is the real channel. Class renamed to match what it
- * actually does.)
- *
- * Design:
- *   - Default mode `useWatch: 'auto'` uses `fs.watch` on the parent
- *     directory + filename filter — near-zero steady-state IO. Falls
- *     back to polling automatically if `fs.watch` fails (sandboxed
- *     environment, unsupported FS). A slow 1s safety-net poll runs
- *     alongside the watcher to catch any missed events.
- *   - `useWatch: false` forces polling — for environments where
- *     fs.watch is known broken.
- *   - `useWatch: true` requires fs.watch to work — throws on failure.
- *     Use for testing the watch path deterministically.
- *   - Tolerates the file not existing yet (claude may take ~100ms to
- *     create it after spawn). The directory watcher fires once it
- *     appears.
- *   - Carries a partial-line buffer across reads so a line split
- *     across two reads still emits exactly once.
- *   - Safety cap on per-line size (MAX_BUF_BYTES) so a hostile or
- *     corrupted multi-MB single-line write can't OOM the daemon or
- *     stall the event loop on a sync JSON.parse.
- *   - Idempotent .close().
- *
- * @see lib/util/claude-session-jsonl.js — JSONL line → typed event
- */
-
-'use strict';
-
-const EventEmitter = require('events');
-const fs = require('fs');
-const path = require('path');
-const { StringDecoder } = require('string_decoder');
-
-const DEFAULT_INTERVAL_MS = 100;
-// Slow safety-net poll when fs.watch is active. Catches any events
-// the watcher missed (rare on Linux/macOS, more common on networked
-// or fuse filesystems). 1s is more than enough for backstop.
-const WATCH_SAFETY_NET_MS = 1000;
-const DEFAULT_CHUNK_BYTES = 64 * 1024;
-// Safety cap: a single line with no \n must not grow `_buf` without
-// bound. claude TUI doesn't emit lines this big in normal operation;
-// hitting this is a sign of corruption or a hostile tool result that
-// could OOM the daemon and stall the event loop with a sync JSON.parse.
-const MAX_BUF_BYTES = 16 * 1024 * 1024;
-
-class LogTail extends EventEmitter {
-  /**
-   * @param {object} opts
-   * @param {string} opts.path             — log file path
-   * @param {number} [opts.intervalMs=100] — poll interval when in
-   *   polling mode (also used as the initial-tick delay in watch mode).
-   * @param {boolean} [opts.skipExisting]  — start at current file size,
-   *   only emit lines added AFTER start(). Used for `--resume` on the
-   *   tmux backend so historic JSONL events aren't replayed.
-   * @param {'auto'|true|false} [opts.useWatch='auto']
-   *   - 'auto' (default): try fs.watch; fall back to polling on error.
-   *   - true:  require fs.watch to work; throw on failure.
-   *   - false: force polling.
-   * @param {object} [opts.fs]             — test seam (override fs)
-   * @param {object} [opts.logger=console]
-   */
-  constructor({
-    path: filePath,
-    intervalMs = DEFAULT_INTERVAL_MS,
-    skipExisting = false,
-    useWatch = 'auto',
-    fs: fsOverride,
-    logger = console,
-  } = {}) {
-    super();
-    if (typeof filePath !== 'string' || !filePath) {
-      throw new TypeError('LogTail: path required');
-    }
-    this.path = filePath;
-    this.intervalMs = intervalMs;
-    this.skipExisting = skipExisting;
-    this.useWatch = useWatch;
-    this.logger = logger;
-    this.fs = fsOverride || fs;
-    this._offset = 0;
-    this._buf = '';
-    // L8: decode bytes through a StringDecoder so a multibyte UTF-8 char
-    // split across two read chunks (the 64KB DEFAULT_CHUNK_BYTES boundary)
-    // isn't corrupted into U+FFFD. The decoder holds an incomplete trailing
-    // sequence until the continuation bytes arrive on the next read. The
-    // hook ndjson carries large non-ASCII tool payloads, so this is
-    // load-bearing on the CliProcess observability path.
-    this._decoder = new StringDecoder('utf8');
-    this._closed = false;
-    this._timer = null;
-    this._watcher = null;
-    this._mode = null;       // 'watch' | 'poll' after start()
-    this._initialised = false;
-    this._readInFlight = false; // debounce concurrent _readNew triggers
-    this._readPending = false;
-  }
-
-  start() {
-    if (this._closed) throw new Error('LogTail: closed');
-    if (this._mode) return; // idempotent
-    // Snapshot offset at start() time when skipExisting is requested.
-    // Doing this on first read instead would race: if content is
-    // appended between start() and the first read, the offset jump
-    // would skip those bytes too.
-    if (this.skipExisting) {
-      try {
-        const stat = this.fs.statSync(this.path);
-        this._offset = stat.size;
-      } catch (err) {
-        if (err.code !== 'ENOENT') throw err;
-        // File doesn't exist yet — offset stays 0, all future content
-        // is "new" by definition.
-      }
-      this._initialised = true;
-    }
-    // Decide watch vs poll. In 'auto' mode we attempt fs.watch and
-    // silently fall back; in 'true' mode we throw on failure; in
-    // 'false' mode we skip the attempt entirely.
-    if (this.useWatch !== false) {
-      if (this._tryStartWatch()) {
-        this._mode = 'watch';
-        // Trigger an immediate first read (existing content + warmup),
-        // then add a slow safety-net poll on top of the watcher to
-        // catch any missed events.
-        setImmediate(() => this._triggerRead());
-        this._startSafetyNetPoll();
-        return;
-      }
-      if (this.useWatch === true) {
-        throw new Error('LogTail: useWatch:true requested but fs.watch failed');
-      }
-      this.logger.log?.(`[log-tail] fs.watch unavailable for ${this.path}; falling back to polling`);
-    }
-    this._mode = 'poll';
-    this._startPolling();
-  }
-
-  /**
-   * Try to install fs.watch on the parent directory. We watch the dir
-   * (not the file) because the file may not exist yet — claude TUI
-   * creates it a moment after spawn. Returns true on success.
-   */
-  _tryStartWatch() {
-    try {
-      const dir = path.dirname(this.path);
-      const base = path.basename(this.path);
-      // Ensure the parent exists so fs.watch can attach. If the
-      // ~/.claude/projects/<cwd> dir hasn't been created yet, claude
-      // will create it on first turn; we make it now so the watcher
-      // can attach immediately.
-      this.fs.mkdirSync(dir, { recursive: true });
-      this._watcher = this.fs.watch(dir, { persistent: false }, (eventType, filename) => {
-        if (this._closed) return;
-        if (filename !== base) return;
-        this._triggerRead();
-      });
-      this._watcher.on('error', (err) => {
-        // Watcher errored mid-flight (e.g. dir removed). Fall back to
-        // polling instead of stopping entirely.
-        this.logger.warn?.(`[log-tail] watcher error for ${this.path}: ${err.message}; falling back to polling`);
-        try { this._watcher.close(); } catch {}
-        this._watcher = null;
-        if (!this._closed) {
-          this._mode = 'poll';
-          this._startPolling();
-        }
-      });
-      return true;
-    } catch (err) {
-      // EPERM (sandbox), ENOSYS (unsupported), ENOENT (path gone) — all fall back.
-      this.logger.log?.(`[log-tail] fs.watch attempt failed: ${err.message}`);
-      return false;
-    }
-  }
-
-  /**
-   * Schedule a `_readNew()` call. Multiple triggers between reads are
-   * coalesced into a single read — debounces watcher event storms when
-   * claude writes many lines in quick succession.
-   */
-  _triggerRead() {
-    if (this._closed) return;
-    if (this._readInFlight) {
-      this._readPending = true;
-      return;
-    }
-    this._readInFlight = true;
-    this._readNew()
-      .catch((err) => this.emit('error', err))
-      .finally(() => {
-        this._readInFlight = false;
-        if (this._readPending && !this._closed) {
-          this._readPending = false;
-          // Re-enter once more to catch anything that arrived during
-          // the previous read.
-          setImmediate(() => this._triggerRead());
-        }
-      });
-  }
-
-  _startSafetyNetPoll() {
-    if (this._closed) return;
-    const tick = () => {
-      if (this._closed) return;
-      this._triggerRead();
-      this._timer = setTimeout(tick, WATCH_SAFETY_NET_MS);
-      this._timer.unref?.();
-    };
-    this._timer = setTimeout(tick, WATCH_SAFETY_NET_MS);
-    this._timer.unref?.();
-  }
-
-  _startPolling() {
-    const tick = () => {
-      if (this._closed) return;
-      this._triggerRead();
-      if (!this._closed) {
-        this._timer = setTimeout(tick, this.intervalMs);
-        // Don't keep the event loop alive solely for tailing. In
-        // production the polygram daemon has many other refs (Telegram
-        // polling, IPC, the tmux session itself) keeping it up.
-        this._timer.unref?.();
-      }
-    };
-    // Fire the first tick immediately so existing content (if any)
-    // is consumed without waiting `intervalMs`. setImmediate is NOT
-    // unref'd here — we want at least one read of existing content to
-    // complete before the loop is allowed to exit.
-    this._timer = setImmediate(tick);
-  }
-
-  async _readNew() {
-    let stat;
-    try {
-      stat = await this.fs.promises.stat(this.path);
-    } catch (err) {
-      if (err.code === 'ENOENT') return; // not created yet
-      throw err;
-    }
-    if (stat.size < this._offset) {
-      // File truncated (rare for claude debug-file but possible on log
-      // rotation). Reset offset and re-read from the beginning.
-      this.emit('truncated', { previous: this._offset, current: stat.size });
-      this._offset = 0;
-      this._buf = '';
-    }
-    if (stat.size <= this._offset) return; // unchanged
-    const fd = await this.fs.promises.open(this.path, 'r');
-    try {
-      const bytesToRead = stat.size - this._offset;
-      const buffer = Buffer.alloc(Math.min(bytesToRead, DEFAULT_CHUNK_BYTES));
-      let totalRead = 0;
-      while (totalRead < bytesToRead && !this._closed) {
-        const remaining = bytesToRead - totalRead;
-        const readSize = Math.min(remaining, buffer.length);
-        const { bytesRead } = await fd.read(buffer, 0, readSize, this._offset + totalRead);
-        if (bytesRead === 0) break;
-        // L8: StringDecoder.write instead of per-chunk toString('utf8') so a
-        // multibyte char straddling the read boundary survives intact.
-        this._buf += this._decoder.write(buffer.subarray(0, bytesRead));
-        totalRead += bytesRead;
-      }
-      this._offset += totalRead;
-    } finally {
-      await fd.close();
-    }
-    // Split on newlines, keeping any trailing partial line in _buf.
-    const parts = this._buf.split(/\r?\n/);
-    this._buf = parts.pop() ?? '';
-    // Safety: drop the trailing partial line if it grew past
-    // MAX_BUF_BYTES without a newline. claude TUI doesn't write lines
-    // this large in normal operation; continuing would risk OOM.
-    if (this._buf.length > MAX_BUF_BYTES) {
-      this.emit('line-too-long', {
-        bytes: this._buf.length,
-        max: MAX_BUF_BYTES,
-        location: 'trailing-partial',
-      });
-      this._buf = '';
-    }
-    for (const line of parts) {
-      if (this._closed) return;
-      // Skip empty lines (common in debug logs).
-      if (line.length === 0) continue;
-      // Safety: drop completed lines that exceed the cap. JSON.parse
-      // on a 100MB line synchronously blocks the event loop.
-      if (line.length > MAX_BUF_BYTES) {
-        this.emit('line-too-long', {
-          bytes: line.length,
-          max: MAX_BUF_BYTES,
-          location: 'completed-line',
-        });
-        continue;
-      }
-      this.emit('line', line);
-    }
-  }
-
-  close() {
-    if (this._closed) return;
-    this._closed = true;
-    if (this._timer) {
-      clearTimeout(this._timer);
-      clearImmediate(this._timer);
-      this._timer = null;
-    }
-    if (this._watcher) {
-      try { this._watcher.close(); } catch {}
-      this._watcher = null;
-    }
-    // Flush any trailing buffered partial line as a final 'line' so
-    // consumers don't lose data on shutdown.
-    if (this._buf.length > 0) {
-      this.emit('line', this._buf);
-      this._buf = '';
-    }
-    this.emit('close');
-  }
-}
-
-module.exports = { LogTail };

package/lib/tmux/orphan-sweep.js

@@ -1,79 +0,0 @@
-/**
- * Boot-time tmux orphan sweep — kill any `polygram-<botName>-*` tmux
- * sessions left over from a prior daemon.
- *
- * Why this exists:
- *   - `lib/process-guard.js#claimPidFile` (rc.50) kills the prior
- *     polygram daemon at boot, but tmux sessions OUTLIVE their parent
- *     process — they're owned by the tmux server, not by polygram.
- *   - When the new daemon's TmuxProcess.start() tries to spawn a
- *     session with the bot-prefixed name, `tmux new-session` fails
- *     with EEXIST because the old session is still there.
- *   - The old session is unrecoverable: claudeSessionId is fresh per
- *     turn, the daemon writing to JSONL was SIGKILLed mid-turn, and
- *     any user-visible reply was already lost to the dead daemon.
- *
- * Strategy: list, kill, log. Best-effort — if tmux isn't running or
- * the kill races a concurrent operator, swallow the error and proceed.
- *
- * @see lib/process-guard.js (claimPidFile)
- * @see lib/tmux/tmux-runner.js (listPolygramSessions, killSession)
- */
-
-'use strict';
-
-const { createTmuxRunner } = require('./tmux-runner');
-
-/**
- * Sweep all `polygram-<botName>-*` tmux sessions on the host.
- *
- * @param {object} opts
- * @param {string} opts.botName       — only sweep sessions for THIS bot
- * @param {object} [opts.runner]      — injected TmuxRunner (for tests)
- * @param {object} [opts.logger=console]
- * @returns {Promise<{ swept: string[], errors: Array<{name:string, error:string}> }>}
- */
-async function sweepTmuxOrphans({ botName, runner, logger = console } = {}) {
-  if (!botName) throw new TypeError('sweepTmuxOrphans: botName required');
-  // SECURITY (audit M2): dashes in bot names risk prefix-match
-  // collision when two bots share a prefix (e.g. `shumabit` matches
-  // `polygram-shumabit-prod-*` too). Warn so the operator can rename.
-  // The trailing `-` in the listPolygramSessions filter prevents an
-  // exact-prefix collision but DOES NOT prevent `shumabit` vs
-  // `shumabit-prod`. Defense-in-depth: surface it.
-  if (typeof botName === 'string' && botName.includes('-')) {
-    logger.warn?.(
-      `[orphan-sweep] bot name "${botName}" contains '-'; orphan-sweep `
-      + `prefix matching could collide with other bot names sharing a `
-      + `prefix. Consider renaming (e.g. use _ instead).`,
-    );
-  }
-  const r = runner || createTmuxRunner({ logger });
-  let names;
-  try {
-    names = await r.listPolygramSessions(botName);
-  } catch (err) {
-    // Most common: tmux not running. Best-effort = no-op.
-    logger.log?.(`[orphan-sweep] list-sessions failed (${err.message}); assuming no orphans`);
-    return { swept: [], errors: [] };
-  }
-  if (names.length === 0) {
-    logger.log?.(`[orphan-sweep] no polygram-${botName}-* orphans`);
-    return { swept: [], errors: [] };
-  }
-  logger.log?.(`[orphan-sweep] killing ${names.length} orphan tmux session(s): ${names.join(', ')}`);
-  const errors = [];
-  const swept = [];
-  for (const name of names) {
-    try {
-      await r.killSession(name);
-      swept.push(name);
-    } catch (err) {
-      errors.push({ name, error: err.message });
-      logger.warn?.(`[orphan-sweep] kill ${name} failed: ${err.message}`);
-    }
-  }
-  return { swept, errors };
-}
-
-module.exports = { sweepTmuxOrphans };

package/lib/tmux/poll-scheduler.js

@@ -1,110 +0,0 @@
-/**
- * PollScheduler — shared tick generator for TmuxProcess polling loops.
- *
- * Each in-flight tmux turn polls `tmux capture-pane` every ~250ms to
- * detect READY / STREAMING / approval-prompt state changes. Without
- * coordination, N concurrent in-flight chats run N independent
- * `setTimeout` chains. PollScheduler collapses these into a SINGLE
- * `setInterval` whose firing wakes all registered waiters at once.
- *
- * Wins:
- *   - One timer regardless of how many tmux chats are running.
- *   - Tick-aligned bursts: all capture-pane subprocess spawns happen
- *     in the same JS turn, then the loop idles until the next tick.
- *     Linux/macOS handle bursty fork+exec better than smeared.
- *   - Single shutdown point — `release()` from each process cleanly
- *     stops the timer when nothing is in flight.
- *
- * Usage:
- *   const sched = new PollScheduler({ intervalMs: 250 });
- *   await proc.send(...);   // internally calls:
- *   //   sched.acquire();
- *   //   while (not done) { ...; await sched.waitTick(); }
- *   //   sched.release();
- *
- * Each `waitTick()` returns a Promise that resolves at the NEXT tick.
- * Multiple waiters on the same tick all resolve simultaneously.
- */
-
-'use strict';
-
-class PollScheduler {
-  /**
-   * @param {object} [opts]
-   * @param {number} [opts.intervalMs=250]  — global poll cadence
-   */
-  constructor({ intervalMs = 250 } = {}) {
-    this.intervalMs = intervalMs;
-    this._timer = null;
-    this._refCount = 0;
-    this._waiters = new Set();
-  }
-
-  /**
-   * Register a polling lifetime. Increments refCount and starts the
-   * shared interval if not already running. Pair every acquire() with
-   * a release() in a try/finally.
-   */
-  acquire() {
-    this._refCount++;
-    if (!this._timer) {
-      this._timer = setInterval(() => this._tick(), this.intervalMs);
-      // Don't keep the event loop alive solely for polling. The
-      // polygram daemon has many other refs (Telegram, IPC, the tmux
-      // sessions themselves) keeping it up.
-      this._timer.unref?.();
-    }
-  }
-
-  /**
-   * Drop a polling lifetime. When refCount hits zero we stop the
-   * interval AND resolve any lingering waiters so their loops can
-   * exit cleanly (e.g. process killed mid-tick).
-   */
-  release() {
-    if (this._refCount <= 0) return;
-    this._refCount--;
-    if (this._refCount === 0 && this._timer) {
-      clearInterval(this._timer);
-      this._timer = null;
-      // Wake any leftover waiters so their polling loops can observe
-      // closed state and exit.
-      this._drainWaiters();
-    }
-  }
-
-  /**
-   * Resolves at the next scheduler tick. Cheap — no setTimeout
-   * allocation per call, just a Set insertion. Caller MUST have
-   * called acquire() before its first waitTick() and call release()
-   * after its last.
-   */
-  waitTick() {
-    return new Promise((resolve) => {
-      this._waiters.add(resolve);
-    });
-  }
-
-  /**
-   * Number of registered polling lifetimes (active in-flight turns).
-   * Useful for observability + tests.
-   */
-  get activeCount() {
-    return this._refCount;
-  }
-
-  _tick() {
-    this._drainWaiters();
-  }
-
-  _drainWaiters() {
-    if (this._waiters.size === 0) return;
-    const fns = [...this._waiters];
-    this._waiters.clear();
-    for (const fn of fns) {
-      try { fn(); } catch { /* swallow */ }
-    }
-  }
-}
-
-module.exports = { PollScheduler };