@shumkov/orchestra 0.2.0

package/lib/claude-bin.js

@@ -0,0 +1,247 @@
+// provenance: polygram@0.17.11 lib/claude-bin.js (git 746bca6) — verbatim*: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+// 0.12 Phase 4: moved from lib/process/tmux-process.js into the helper module
+// that consumes it, so the constant survives TmuxProcess deletion. CliProcess
+// + spike scripts + polygram boot all import from here now.
+// 0.12.0-rc.18: bumped 2.1.142 → 2.1.158 (latest installed) chasing the
+// dev-channels reliability issues (see docs/0.12.0-known-issues.md).
+// 0.12.0-rc.38: bumped 2.1.158 → 2.1.173. Two reasons: (1) the ~32s startup
+// deaths root-caused 2026-06-11 to a stale MCP connect-timeout racing the
+// --resume session-id swap — a newer claude may fix the timer (2.1.173 also
+// adds "Channel notifications re-registered after reconnect"); (2) keep the
+// research-preview channels current. Per-bump re-validation done 2026-06-11:
+// resume-dialog env vars survive (CLAUDE_CODE_RESUME_THRESHOLD_MINUTES /
+// _TOKEN_THRESHOLD), trust + dev-channels dialogs unchanged, "esc to
+// interrupt" hint unchanged (template-rendered), but the channels READY
+// banner text CHANGED → readySignal in cli-process.js matches both forms.
+// Re-validate the channel flow on each bump via
+// tests/e2e-channels-real-claude.test.js (run with E2E_REAL_CLAUDE=1).
+const CLAUDE_CLI_PINNED_VERSION = '2.1.173';
+
+/**
+ * Resolve + verify the pinned claude CLI binary.
+ *
+ * Why this exists: the tmux + CLI backends read claude CLI internal
+ * artefacts (TUI banner ASCII, READY hint strings, channel notification
+ * registration timing, MCP-init order) — none a stable public contract.
+ * polygram pins ONE version (`CLAUDE_CLI_PINNED_VERSION`) and must
+ * spawn THAT binary, never whatever `claude` on $PATH happens to
+ * resolve to.
+ *
+ * Before this module the tmux runner spawned the bare string
+ * `claude`, resolved through $PATH. The claude CLI installs each
+ * version as a standalone binary at
+ *   ~/.local/share/claude/versions/<version>
+ * and points ~/.local/bin/claude (a symlink) at the active one.
+ * Its auto-updater re-points that symlink whenever a new version
+ * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
+ * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
+ *
+ * Spawning the ABSOLUTE versioned path avoids the symlink-drift, but is
+ * NOT immune to the updater: claude keeps only the ~3 newest versions
+ * and PRUNES (deletes) the rest. Once the pin falls out of the top 3 the
+ * pinned path is a dead file → every cli spawn exits in ~14ms (prod
+ * outages 2026-06-21/22). So `verifyPinnedClaudeBin` (point-in-time check)
+ * is not enough; `ensureVendoredClaudeBin` (below, 0.17) keeps a
+ * polygram-owned copy the pruner can't touch.
+ */
+
+/**
+ * Absolute path to the pinned claude binary.
+ *
+ * Resolution order:
+ *   1. ORCHESTRA_CLAUDE_BIN env — explicit override (non-standard
+ *      installs, CI, hosts where the layout differs).
+ *   2. ~/.local/share/claude/versions/<version> — the standard
+ *      claude-CLI install location.
+ *
+ * The returned path is NOT guaranteed to exist — callers verify
+ * via verifyPinnedClaudeBin().
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {string} absolute path
+ */
+function resolvePinnedClaudeBin(version) {
+  const override = process.env.ORCHESTRA_CLAUDE_BIN;
+  if (override) return override;
+  return path.join(os.homedir(), '.local', 'share', 'claude', 'versions', version);
+}
+
+/**
+ * Verify the pinned binary exists and is executable.
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {{ ok: boolean, path: string, reason?: string }}
+ *   ok=true → path is a spawnable binary.
+ *   ok=false → reason carries an operator-actionable message.
+ */
+function verifyPinnedClaudeBin(version) {
+  const binPath = resolvePinnedClaudeBin(version);
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return { ok: true, path: binPath };
+  } catch (err) {
+    const code = err && err.code ? err.code : (err && err.message) || 'unknown';
+    return {
+      ok: false,
+      path: binPath,
+      reason: `pinned claude CLI v${version} not found or not executable at `
+        + `${binPath} (${code}). Install it with \`claude install ${version}\` `
+        + 'or set ORCHESTRA_CLAUDE_BIN to the correct binary path.',
+    };
+  }
+}
+
+// ─── 0.17: vendored pinned binary (immune to claude's auto-pruner) ──────────
+//
+// claude's updater deletes all but the ~3 newest versions, so the pinned
+// version eventually vanishes from ~/.local/share/claude/versions and every
+// cli spawn dies. We can't fall forward (the cli backend reads version-specific
+// TUI internals). Fix: polygram keeps its OWN copy of the exact pinned binary
+// in a dir the pruner never touches, and spawns from there. Once vendored it
+// never depends on the system copy or the network again.
+
+/**
+ * polygram-owned vendor dir for claude binaries. Under ~/.local/share/water
+ * (XDG data) — claude's pruner only touches ~/.local/share/claude/versions, and
+ * `npm i -g polygram` only replaces the package dir, so this survives both.
+ * Override with ORCHESTRA_CLAUDE_VENDOR_DIR.
+ */
+function vendorDir() {
+  return process.env.ORCHESTRA_CLAUDE_VENDOR_DIR
+    || path.join(os.homedir(), '.local', 'share', 'orchestra', 'claude-bin');
+}
+
+function isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+// Atomic: copy to a unique tmp in the same dir, chmod, then rename over.
+function _atomicCopyExec(src, dst) {
+  const tmp = `${dst}.tmp.${process.pid}.${Date.now()}`;
+  fs.copyFileSync(src, tmp);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, dst);
+}
+
+// Remove vendored binaries (and stale .tmp.*) that aren't the live version.
+function _gcVendored(dir, keepVersion, logger) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (name === keepVersion) continue;
+    // Never delete an in-flight copy: a CONCURRENT boot (multi-bot host shares
+    // this dir) may be mid-copy into `<keepVersion>.tmp.<pid>.<ts>`; removing it
+    // ENOENTs that boot's rename → it falls back to SDK. Skip all .tmp.* — a
+    // genuinely orphaned tmp is cheap to leave (cleaned when its version is GC'd
+    // by name, or harmless). Defense-in-depth: only GC version-shaped names so a
+    // misconfigured vendor dir can't nuke unrelated files.
+    if (name.includes('.tmp.')) continue;
+    if (!/^\d+\.\d+\.\d+$/.test(name)) continue;
+    try { fs.rmSync(path.join(dir, name), { force: true }); } catch (e) {
+      logger?.warn?.(`[claude-bin] vendor GC: could not remove ${name}: ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Ensure a polygram-owned copy of the pinned claude binary exists and return
+ * its path. Steady state is a single stat (fast). On a cold/pruned host it
+ * obtains the binary once (copy from the system install, else `claude install`
+ * then copy) and caches it forever.
+ *
+ * @param {string} version
+ * @param {{ logger?: object }} [opts]
+ * @returns {{ ok: boolean, path: string, vendored?: boolean, reason?: string }}
+ */
+function ensureVendoredClaudeBin(version, { logger = console } = {}) {
+  // Explicit override wins, unchanged — non-standard installs / CI / tests.
+  const override = process.env.ORCHESTRA_CLAUDE_BIN;
+  if (override) {
+    return isExecutable(override)
+      ? { ok: true, path: override, vendored: false }
+      : { ok: false, path: override, reason: `ORCHESTRA_CLAUDE_BIN=${override} not executable` };
+  }
+
+  const dir = vendorDir();
+  const vendored = path.join(dir, version);
+
+  // Fast path: already vendored.
+  if (isExecutable(vendored)) {
+    _gcVendored(dir, version, logger);
+    return { ok: true, path: vendored, vendored: true };
+  }
+
+  // Need to obtain it. Ensure the dir exists.
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {
+    return { ok: false, path: vendored, reason: `cannot create vendor dir ${dir}: ${e.message}` };
+  }
+
+  const versionsDir = process.env.ORCHESTRA_CLAUDE_VERSIONS_DIR
+    || path.join(os.homedir(), '.local', 'share', 'claude', 'versions');
+  const systemPath = path.join(versionsDir, version);
+
+  // (a) copy from the system install if present.
+  if (isExecutable(systemPath)) {
+    try {
+      _atomicCopyExec(systemPath, vendored);
+      logger?.log?.(`[claude-bin] vendored claude v${version} ← ${systemPath} → ${vendored}`);
+    } catch (e) {
+      return { ok: false, path: vendored, reason: `copy ${systemPath} → ${vendored} failed: ${e.message}` };
+    }
+  } else {
+    // (b) try to install the exact version, then copy. If
+    // ORCHESTRA_CLAUDE_INSTALL_BIN is set, use it VERBATIM (no fallback — an
+    // explicit override that's wrong must fail loudly, not silently shell out to
+    // a different claude). Otherwise prefer ~/.local/bin/claude, else PATH.
+    let installerBin = process.env.ORCHESTRA_CLAUDE_INSTALL_BIN;
+    if (!installerBin) {
+      const localBin = path.join(os.homedir(), '.local', 'bin', 'claude');
+      installerBin = isExecutable(localBin) ? localBin : 'claude';
+    }
+    logger?.warn?.(`[claude-bin] pinned claude v${version} absent from ${systemPath}; installing via ${installerBin}…`);
+    try {
+      // Synchronous: blocks boot until the install completes. Rare (deploys
+      // pre-install the pin → the fast copy path above is the norm). On the VPS
+      // polygram boots DETACHED in tmux (Type=oneshot start-sessions.sh), so
+      // this block is NOT gated by systemd's TimeoutStartSec; on the Mac launchd
+      // has no hard start-timeout. Timeout kept under the VPS unit's 120s anyway.
+      execFileSync(installerBin, ['install', version], { timeout: 110_000, stdio: 'ignore' });
+    } catch (e) {
+      return {
+        ok: false, path: vendored,
+        reason: `claude v${version} not present and \`claude install ${version}\` failed (${e.message}). `
+          + 'Install it manually or set ORCHESTRA_CLAUDE_BIN.',
+      };
+    }
+    if (!isExecutable(systemPath)) {
+      return { ok: false, path: vendored, reason: `claude install ${version} ran but ${systemPath} still missing` };
+    }
+    try {
+      _atomicCopyExec(systemPath, vendored);
+      logger?.log?.(`[claude-bin] installed + vendored claude v${version} → ${vendored}`);
+    } catch (e) {
+      return { ok: false, path: vendored, reason: `copy after install failed: ${e.message}` };
+    }
+  }
+
+  _gcVendored(dir, version, logger);
+  if (!isExecutable(vendored)) {
+    return { ok: false, path: vendored, reason: `vendored copy ${vendored} is not executable after copy` };
+  }
+  return { ok: true, path: vendored, vendored: true };
+}
+
+module.exports = {
+  resolvePinnedClaudeBin,
+  verifyPinnedClaudeBin,
+  ensureVendoredClaudeBin,
+  vendorDir,
+  CLAUDE_CLI_PINNED_VERSION,
+};

package/lib/compaction-warn.js

@@ -0,0 +1,60 @@
+// provenance: polygram@0.17.11 lib/compaction-warn.js (git 746bca6) — verbatim: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * compaction-warn — per-chat config resolution + warn-once state for the
+ * compaction warning (0.12.0-rc.13).
+ *
+ * The warning is OFF by default. A chat (or topic) opts in via
+ * `compactionWarnings`:
+ *   true                                   → enabled, default threshold
+ *   { enabled: true, thresholdPct: 80 }    → enabled, custom threshold
+ *   false / absent / object w/o enabled    → off
+ *
+ * `thresholdPct` is the context-fill % at which the PROACTIVE warning fires
+ * (propose /compact before claude auto-compacts mid-turn). Default 75 — below
+ * claude's own auto-compact threshold so the user gets a window to act.
+ */
+
+'use strict';
+
+const DEFAULT_THRESHOLD_PCT = 75;
+
+/**
+ * @param {object|undefined} cfg  resolved topic/chat config (getTopicConfig result)
+ * @returns {{enabled: boolean, thresholdPct: number}}
+ */
+function resolveCompactionWarnConfig(cfg) {
+  const raw = cfg?.compactionWarnings;
+  const off = { enabled: false, thresholdPct: DEFAULT_THRESHOLD_PCT };
+
+  if (raw === true) return { enabled: true, thresholdPct: DEFAULT_THRESHOLD_PCT };
+  if (raw && typeof raw === 'object' && raw.enabled === true) {
+    const t = Number(raw.thresholdPct);
+    const thresholdPct = (Number.isFinite(t) && t > 0 && t < 100) ? t : DEFAULT_THRESHOLD_PCT;
+    return { enabled: true, thresholdPct };
+  }
+  return off;
+}
+
+/**
+ * Per-session "have we already warned on this climb?" state. Warn ONCE per
+ * session until reset — without this the proactive warning would re-fire on
+ * every turn-end while the context stays high. Reset on a successful
+ * compaction (PostCompact → context dropped) or a fresh session so the next
+ * climb can warn again. Mirrors the autoResumeTracker shape.
+ */
+function createCompactionWarnTracker() {
+  const warned = new Set();
+  return {
+    shouldWarn(sessionKey) { return !warned.has(sessionKey); },
+    markWarned(sessionKey) { warned.add(sessionKey); },
+    reset(sessionKey) { warned.delete(sessionKey); },
+    resetAll() { warned.clear(); },
+    _size() { return warned.size; },
+  };
+}
+
+module.exports = {
+  resolveCompactionWarnConfig,
+  createCompactionWarnTracker,
+  DEFAULT_THRESHOLD_PCT,
+};

package/lib/context-usage.js

@@ -0,0 +1,94 @@
+// provenance: polygram@0.17.11 lib/context-usage.js (git 746bca6) — verbatim: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * context-usage — read live context occupancy from a Claude Code session
+ * transcript (JSONL).
+ *
+ * Used by the per-chat compaction warning (0.12.0-rc.13). polygram has no
+ * usage payload on the channels/CLI backend (hook events carry none — see
+ * the rc.13 spike), so the only source of "how full is the context" is the
+ * transcript itself. We read it ONCE per turn-end (Stop hook), not on a
+ * poll loop, so a single streamed pass is fine.
+ *
+ * What "occupancy" means: Claude's own context-% / auto-compact threshold is
+ * measured against what's fed INTO the model each turn —
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ * (cache_read dominates once the conversation is warm). output_tokens is the
+ * reply, not context, so it's excluded.
+ *
+ * We take the LAST main-thread (non-sidechain) assistant frame with a usage
+ * block. Subagents write to their own agent_transcript_path so sidechain
+ * frames don't normally appear here, but we skip them defensively: a format
+ * change that inlined a subagent's large usage would otherwise spike the
+ * parent's apparent context and trigger a false "you're full" warning.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+
+// Standard Claude context window (sonnet/opus, non-beta). The warning is a
+// heuristic ("you're getting full"), so an approximate denominator is fine;
+// callers can pass a different window for 1M-beta sessions.
+const DEFAULT_WINDOW_TOKENS = 200_000;
+
+/**
+ * @param {string} transcriptPath
+ * @returns {Promise<{inputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, total:number} | null>}
+ *   null when the path is falsy/unreadable or no usable usage frame exists.
+ */
+async function readContextTokens(transcriptPath) {
+  if (!transcriptPath) return null;
+
+  let stream;
+  try {
+    stream = fs.createReadStream(transcriptPath, { encoding: 'utf8' });
+  } catch {
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    let last = null;
+    // Resolve only once — error and close can both fire.
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+
+    stream.on('error', () => finish(null));
+
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    // readline forwards the input stream's 'error' (e.g. ENOENT on open) to
+    // the interface; without this handler that re-emit is unhandled and
+    // crashes the process even though we resolved null on the stream error.
+    rl.on('error', () => finish(null));
+    rl.on('line', (line) => {
+      if (!line) return;
+      let o;
+      try { o = JSON.parse(line); } catch { return; }  // skip partial/non-JSON lines
+      if (!o || o.type !== 'assistant' || o.isSidechain === true) return;
+      const u = o.message?.usage;
+      if (!u) return;
+      const inputTokens = Number(u.input_tokens) || 0;
+      const cacheReadTokens = Number(u.cache_read_input_tokens) || 0;
+      const cacheCreationTokens = Number(u.cache_creation_input_tokens) || 0;
+      const total = inputTokens + cacheReadTokens + cacheCreationTokens;
+      if (total > 0) last = { inputTokens, cacheReadTokens, cacheCreationTokens, total };
+    });
+    rl.on('close', () => finish(last));
+  });
+}
+
+/**
+ * Fraction (0..1) of the context window currently occupied. Clamps to 0 on
+ * non-positive / non-finite inputs so callers never see NaN/Infinity.
+ *
+ * @param {number} totalTokens
+ * @param {number} [windowTokens=DEFAULT_WINDOW_TOKENS]
+ * @returns {number}
+ */
+function contextPct(totalTokens, windowTokens = DEFAULT_WINDOW_TOKENS) {
+  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return 0;
+  if (!Number.isFinite(windowTokens) || windowTokens <= 0) return 0;
+  return totalTokens / windowTokens;
+}
+
+module.exports = { readContextTokens, contextPct, DEFAULT_WINDOW_TOKENS };