borgmcp 1.1.14 → 2.0.1

package/src/stream-status.ts

@@ -0,0 +1,337 @@
+/**
+ * Renderer + inbox-Monitor liveness probe for `borg_stream-status`.
+ *
+ * Split out from `index.ts` so the 5-state precedence logic and the
+ * `pgrep`-based liveness check can be unit-tested without spinning up
+ * the MCP server. drone-4's 18:30:51 UX contract is the spec for the
+ * rendered output shape; this module is the implementation surface.
+ *
+ * Top-line states (drone-4 contract):
+ *   1. Stream not started.
+ *   2. Stream connected, awaiting first content event.
+ *   3. Stream connected, last content <X> ago.
+ *   4. Stream disconnected (reconnect attempt N).
+ *   5. Stream connected (no inbox-Monitor — wake path broken).
+ *
+ * Precedence when both `disconnected` and `no inbox-Monitor` apply:
+ *   prefer (4) — wire-disconnect is the upstream cause and resolves
+ *   automatically when the wire comes back up; State 5 only matters
+ *   when the wire is healthy but the file-watch isn't.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import type { StreamStatus } from './log-stream.js';
+import {
+  heartbeatPathFor,
+  legacyHeartbeatPathFor,
+  HEARTBEAT_STALE_MS,
+} from './inbox-monitor.js';
+import { shellEscape } from './shell-escape.js';
+
+/**
+ * Best-effort check: is a process tailing this inbox file?
+ *
+ * Returns:
+ *   - true: at least one process matches `tail.*<inboxPath>` in pgrep
+ *   - false: pgrep ran cleanly and found no match
+ *   - null: cannot determine (pgrep unavailable, spawn error, no inbox path)
+ *
+ * The null case is informative — it means we don't know, so the
+ * renderer must NOT fire State 5 (which would be misleading). State 5
+ * only fires when we positively know the wake path is broken.
+ *
+ * Why `pgrep` and not a more elegant check: Claude Code Monitors are
+ * tail-based subprocesses spawned by the harness, completely opaque to
+ * the MCP server. The MCP server has no IPC channel into the harness's
+ * task table. The cheapest reliable signal we can get from inside the
+ * MCP server is "is there a tail subprocess open against this path?"
+ * — which is what `pgrep -f` answers.
+ *
+ * macOS + Linux ship `pgrep`. Windows doesn't (borgmcp targets Mac /
+ * Linux per package.json `os` field; the null branch handles other
+ * platforms gracefully).
+ */
+export function checkInboxMonitorHealthy(
+  inboxPath: string | null,
+  monitorStateRoot?: string | null
+): boolean | null {
+  if (!inboxPath) return null;
+  try {
+    // `-f` matches against the full command line so we catch the
+    // `tail -n 0 -F <inboxPath>` form. `-l` lists matches; we only
+    // need the exit code (0 = match, 1 = no match) and a sanity check
+    // on stdout (some pgrep variants exit 0 with empty stdout under
+    // permission errors — treat empty stdout as "no match" for safety).
+    const res = spawnSync('pgrep', ['-f', inboxPath], {
+      encoding: 'utf-8',
+      timeout: 2_000,
+    });
+    if (res.error) return null;
+    if (res.status === 0 && res.stdout.trim().length > 0) {
+      // gh#822: a tail PROCESS is present — but presence ≠ health (a hung tail
+      // still matches pgrep). Upgrade presence→health via the holder heartbeat
+      // sidecar: if it exists and is STALE past the conservative threshold, the
+      // holder is wedged → wake path broken (false). If it's fresh → healthy.
+      // If it's ABSENT, fall back to presence (an old pre-#822 monitor, or a
+      // #822 monitor armed <1 tick ago that hasn't written its first heartbeat)
+      // → report healthy; never false-flag a monitor that simply lacks the
+      // sidecar (conservative — err toward NOT warning).
+      return !isHeartbeatStale(inboxPath, monitorStateRoot);
+    }
+    if (res.status === 1) return false;
+    // pgrep exits 2 for syntax error, 3 for fatal — treat as unknown.
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * gh#822: are all present holder heartbeat sidecars stale past the threshold?
+ * A fresh legacy sidecar wins during migration; absent sidecars (old monitor /
+ * just-armed) still fall back to process presence. Only present-and-all-stale
+ * state is a wedged-holder signal.
+ */
+export function isHeartbeatStale(inboxPath: string, monitorStateRoot?: string | null): boolean {
+  const paths = [heartbeatPathFor(inboxPath, monitorStateRoot)];
+  if (monitorStateRoot) paths.push(legacyHeartbeatPathFor(inboxPath));
+  let sawHeartbeat = false;
+  for (const path of new Set(paths)) {
+    try {
+      const mtimeMs = statSync(path).mtimeMs;
+      sawHeartbeat = true;
+      if (Date.now() - mtimeMs <= HEARTBEAT_STALE_MS) return false;
+    } catch {
+      // absent / unreadable → keep evaluating the migration counterpart
+    }
+  }
+  return sawHeartbeat;
+}
+
+export interface RenderInputs {
+  status: StreamStatus;
+  /**
+   * Tri-state Monitor liveness: true = healthy, false = wake-path
+   * broken, null = cannot determine.
+   */
+  inboxMonitorHealthy: boolean | null;
+  /**
+   * Inbox path for the State-5 self-arm instruction. Pass null when
+   * unknown (no active cube); State 5 will then surface the failure
+   * mode but omit the exact command.
+   */
+  inboxPath: string | null;
+  /** Explicit worktree-local root for the Monitor command, when known. */
+  monitorStateRoot?: string | null;
+  /** Drone label for the Monitor description copy. */
+  droneLabel: string | null;
+  /** Cube name for the Monitor description copy. */
+  cubeName: string | null;
+  /** Relative-time formatter (injected so the renderer is pure). */
+  humanAgo: (d: Date) => string;
+}
+
+/**
+ * Render the `borg_stream-status` markdown body per drone-4's 18:30:51
+ * contract. Pure function — no I/O, no clock reads. Caller assembles
+ * the inputs.
+ */
+export function renderStreamStatus(inputs: RenderInputs): string {
+  const { status, inboxMonitorHealthy, inboxPath, monitorStateRoot, droneLabel, cubeName, humanAgo } =
+    inputs;
+
+  const isNotStarted =
+    status.reconnectAttempts === 0 &&
+    status.lastWireActivityAt === null &&
+    !status.connected;
+  const ownedByOther = status.ownership?.state === 'owned-by-other-process';
+  const orphanedInitialization = status.ownership?.state === 'orphaned-initialization';
+  const ownershipInitializing = status.ownership?.state === 'initializing';
+
+  // Top-line verdict — 5 states + override per drone-4 contract.
+  // Precedence: disconnected > no-inbox-Monitor (wire-down upstream
+  // cause; State 5 only applies when wire is healthy).
+  let summary: string;
+  if (orphanedInitialization) {
+    summary = '**Stream blocked by an orphaned initialization lock.**';
+  } else if (ownedByOther) {
+    summary = '**Stream owned by another Borg MCP process.**';
+  } else if (isNotStarted) {
+    summary = '**Stream not started.**';
+  } else if (!status.connected) {
+    summary = `**Stream disconnected (reconnect attempt ${status.reconnectAttempts}).**`;
+  } else if (inboxMonitorHealthy === false) {
+    summary = '**Stream connected (no inbox-Monitor — wake path broken).**';
+  } else if (status.lastContentEventAt === null) {
+    // State 2: wire works, no content yet. Collapses two underlying
+    // conditions per drone-4 contract — fresh connect pre-first-content
+    // and quiet cube post-reconnect. The body's heartbeat field
+    // distinguishes them (populated vs `_(none)_`).
+    summary = '**Stream connected, awaiting first content event.**';
+  } else {
+    summary = `**Stream connected, last content ${humanAgo(
+      new Date(status.lastContentEventAt)
+    )}.**`;
+  }
+
+  const lines: string[] = [];
+  lines.push(summary);
+  lines.push('');
+  lines.push('# Log-stream status');
+  lines.push('');
+
+  if (orphanedInitialization) {
+    lines.push('- **state**: _(orphaned stream-owner initialization)_');
+  } else if (ownershipInitializing) {
+    lines.push('- **state**: _(stream-owner initialization in progress)_');
+  } else if (ownedByOther) {
+    lines.push('- **state**: _(stream owner is another local process)_');
+  } else if (isNotStarted) {
+    lines.push('- **state**: _(stream not started)_');
+  } else {
+    lines.push(`- **connected**: ${status.connected}`);
+  }
+
+  // Body shape per drone-4 contract: three timestamp lines (content,
+  // heartbeat, wire) — looks redundant in the common case where they
+  // coincide, but the asymmetric "content quiet, heartbeats alive" case
+  // is exactly the diagnostic scenario this surface exists to support.
+  lines.push(
+    `- **last content event**: ${
+      status.lastContentEventAt
+        ? `${status.lastContentEventAt} (${humanAgo(
+            new Date(status.lastContentEventAt)
+          )})`
+        : '_(none yet)_'
+    }`
+  );
+  lines.push(
+    `- **last heartbeat at**: ${
+      status.lastHeartbeatAt
+        ? `${status.lastHeartbeatAt} (${humanAgo(
+            new Date(status.lastHeartbeatAt)
+          )})`
+        : '_(none)_'
+    }`
+  );
+  lines.push(
+    `- **last wire activity**: ${
+      status.lastWireActivityAt
+        ? `${status.lastWireActivityAt} (${humanAgo(
+            new Date(status.lastWireActivityAt)
+          )})`
+        : '_(none)_'
+    }`
+  );
+  lines.push(
+    `- **last persisted event id**: ${status.lastPersistedEventId ?? '_(none)_'}`
+  );
+  lines.push(`- **reconnect attempts**: ${status.reconnectAttempts}`);
+  lines.push(`- **run-loop restarts**: ${status.runLoopRestartCount}`);
+  lines.push(`- **stream ownership**: ${status.ownership?.state ?? '_(unknown)_'}`);
+  if (status.ownership?.lockPath) {
+    lines.push(`- **ownership lock path**: ${status.ownership.lockPath}`);
+  }
+
+  if (ownedByOther) {
+    const owner = status.ownership!;
+    lines.push(`- **stream owner pid**: ${owner.pid ?? '_(unknown)_'}`);
+    lines.push(`- **stream owner cwd**: ${owner.cwd ?? '_(unknown)_'}`);
+    lines.push(
+      `- **stream owner heartbeat age**: ${
+        typeof owner.ageMs === 'number' && Number.isFinite(owner.ageMs)
+          ? `${Math.max(0, Math.round(owner.ageMs / 1000))}s`
+          : '_(unknown)_'
+      }`
+    );
+  }
+
+  // State-5 body line + self-arm instruction. Only fires when we
+  // POSITIVELY detected wake-path breakage AND the wire is up — the
+  // disconnected case takes precedence above and would never reach
+  // here. When `inboxMonitorHealthy === null` (couldn't determine) we
+  // stay silent; surfacing an uncertain failure mode is worse UX than
+  // omitting it.
+  if (status.connected && inboxMonitorHealthy === false) {
+    lines.push(
+      `- **inbox-monitor**: _(no watcher detected — wake path broken)_`
+    );
+    if (inboxPath && droneLabel && cubeName) {
+      lines.push('');
+      lines.push('## Real-time wake-up (do this now)');
+      lines.push(
+        'No process is tailing this drone\'s inbox file — this session won\'t wake on real-time cube activity, only on its fallback timer, and will miss live coordination from other drones. Arm an inbox Monitor:'
+      );
+      lines.push('');
+      lines.push(
+        `> Monitor command: \`${monitorCommand(inboxPath, monitorStateRoot)}\` — persistent, 1h timeout, description "borg inbox for ${droneLabel} on cube ${cubeName}".`
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Gate predicate for the regen wake-path warning (gh#51 — extracted
+ * from the inline ternary in `src/index.ts` for direct unit-test
+ * coverage of the (connected × healthy) cross-product).
+ *
+ * Returns true ONLY when the wire is up AND we positively detected a
+ * dead inbox Monitor (`=== false` strict). The `null` branch
+ * (couldn't determine) stays silent — surfacing an uncertain failure
+ * mode is worse UX than omitting it (mirrors the State-5 precedence
+ * rule in `renderStreamStatus`). When disconnected, the wire-down case
+ * is the upstream cause and takes precedence; no point warning about
+ * the wake path when the wake-path's input has no events to deliver.
+ */
+export function shouldShowWakePathWarning(
+  streamStatus: StreamStatus,
+  inboxMonitorHealthy: boolean | null
+): boolean {
+  return streamStatus.connected && inboxMonitorHealthy === false;
+}
+
+/**
+ * Wake-path-broken prefix for `borg_regen` output (gh#43).
+ *
+ * Pure function — caller decides whether to call (gates on
+ * `shouldShowWakePathWarning`). Returns an empty string when called
+ * with insufficient context to render the Monitor command (e.g., no
+ * inbox path on a no-active-cube path), so callers can always prepend
+ * the result unconditionally.
+ *
+ * Mirrors the State-5 self-arm instruction shape in
+ * `renderStreamStatus` so a drone sees the same Monitor command via
+ * both `borg_stream-status` and `borg_regen`. The differentiator: regen
+ * runs on every /loop iteration, so the prefix gives passive
+ * self-healing (worst-case latency = the /loop fallback heartbeat),
+ * whereas stream-status only surfaces the warning when actively
+ * called.
+ */
+export function formatWakePathPrefix(inputs: {
+  inboxPath: string | null;
+  monitorStateRoot?: string | null;
+  droneLabel: string | null;
+  cubeName: string | null;
+}): string {
+  const { inboxPath, monitorStateRoot, droneLabel, cubeName } = inputs;
+  if (!inboxPath || !droneLabel || !cubeName) return '';
+  return [
+    `## ⚠ Wake path broken — arm Monitor NOW`,
+    ``,
+    `No process is tailing this drone's inbox file. SSE delivery is healthy (entries reach disk), but Claude Code has no event source to wake on. Until you arm a Monitor, this session only wakes on the /loop fallback heartbeat and will miss live coordination from other drones:`,
+    ``,
+    `> Monitor command: \`${monitorCommand(inboxPath, monitorStateRoot)}\` — persistent, 1h timeout, description "borg inbox for ${droneLabel} on cube ${cubeName}".`,
+    ``,
+    `---`,
+    ``,
+  ].join('\n');
+}
+
+function monitorCommand(inboxPath: string, monitorStateRoot?: string | null): string {
+  return monitorStateRoot
+    ? `borg-inbox-monitor --state-root ${shellEscape(monitorStateRoot)} ${shellEscape(inboxPath)}`
+    : `borg-inbox-monitor ${shellEscape(inboxPath)}`;
+}

package/src/sync-roles-render.ts

@@ -0,0 +1,163 @@
+/**
+ * gh#473 PR2 — non-clobbering sync output rendering.
+ *
+ * The dry-run output is UX-LOAD-BEARING: it must CLEARLY communicate each
+ * conflict (which role/section or taxonomy class, cube-current vs
+ * template-new, and how to accept) so the operator SEES what would be
+ * clobbered. Pure string logic (mirrors `roster-render.ts` /
+ * `list-roles-render.ts`) so it is unit-testable without the MCP runtime.
+ *
+ * The shape mirrors the worker's `NonClobberSyncResult`.
+ */
+
+export type FragmentKind = 'add' | 'unchanged' | 'conflict';
+
+export interface FragmentView {
+  key: string;
+  kind: FragmentKind;
+  label: string;
+  cubeValue: string | null;
+  templateValue: string;
+}
+
+export interface NonClobberSyncResult {
+  dryRun: boolean;
+  roles: Array<{
+    name: string;
+    status: 'new' | 'existing' | 'custom-skipped';
+    fragments: FragmentView[];
+  }>;
+  taxonomy: FragmentView[];
+  applied: { added: string[]; acceptedConflicts: string[] };
+  rejectedConflicts: string[];
+  // `decisions` keys that matched no classified conflict (typo'd / stale).
+  // Optional for back-compat with older worker responses.
+  unmatchedDecisions?: string[];
+}
+
+/** Truncate long fragment bodies for at-a-glance diffs. */
+function trunc(s: string | null, n = 200): string {
+  if (s == null) return '(absent)';
+  const flat = s.replace(/\n/g, '⏎');
+  return flat.length > n ? flat.slice(0, n) + '…' : flat;
+}
+
+/**
+ * Render a `NonClobberSyncResult` as an operator-facing markdown report.
+ *
+ * Conflicts are the headline: each is surfaced with both sides + its
+ * stable accept key, and the report states explicitly that conflicts are
+ * KEPT (the cube's version) unless accepted. ADDs are reported as safe
+ * auto-applies. Custom roles are reported untouched.
+ */
+export function renderSyncRolesResult(
+  result: NonClobberSyncResult,
+  templateName: string
+): string {
+  // Defensive guard against client/worker deploy skew (gh#9 class). A
+  // pre-#473 worker returns the legacy sync-roles shape
+  // ({ updated, added, unchanged, skipped, dryRun }) with no `roles[]`, so
+  // `result.roles.flatMap(...)` below would throw `undefined.flatMap`.
+  // Detect the legacy shape and render an actionable message instead of
+  // crashing — the skew window (0.9.47+ client + pre-#473 worker) becomes a
+  // clean "redeploy the worker" prompt, not an exception.
+  const maybeLegacy = result as unknown as Record<string, unknown>;
+  if (maybeLegacy.roles === undefined && 'updated' in maybeLegacy) {
+    return [
+      `## borg_sync-roles — unavailable (server out of date)`,
+      ``,
+      `The borg server returned the legacy sync-roles response shape — it is running a version older than #473, which the non-clobbering sync view does not support.`,
+      ``,
+      `**Action:** a server (worker) deploy is pending. Retry \`borg_sync-roles\` once it lands.`,
+    ].join('\n');
+  }
+
+  const mode = result.dryRun
+    ? '**DRY RUN** (review conflicts below; re-run with `apply: true` + a `decisions` map to commit)'
+    : '**APPLIED**';
+  const lines: string[] = [`## borg_sync-roles — ${mode}`, `Template: ${templateName}`, ''];
+
+  // Gather all fragments across roles + taxonomy for tallying.
+  const allFragments: FragmentView[] = [
+    ...result.roles.flatMap((r) => r.fragments),
+    ...result.taxonomy,
+  ];
+  const conflicts = allFragments.filter((f) => f.kind === 'conflict');
+  const adds = allFragments.filter((f) => f.kind === 'add');
+  const newRoles = result.roles.filter((r) => r.status === 'new');
+  const customRoles = result.roles.filter((r) => r.status === 'custom-skipped');
+
+  // ── Conflicts (the headline — what would be clobbered) ──
+  if (conflicts.length > 0) {
+    lines.push(
+      `### ⚠ ${conflicts.length} CONFLICT(s) — these fragments differ between your cube and the template`
+    );
+    if (result.dryRun) {
+      lines.push(
+        'These differ between your cube and the template — may be because you evolved them, or because the template changed them. ' +
+          'Surfaced for review, never silently overwritten. Each defaults to **KEEP (reject)** — your version survives. ' +
+          'To take the template version of a specific fragment, pass its key in `decisions` as `"<key>": "accept"`.'
+      );
+    } else {
+      lines.push('Unless explicitly accepted, each conflict was KEPT (your version preserved).');
+    }
+    lines.push('');
+    for (const f of conflicts) {
+      const applied = result.applied.acceptedConflicts.includes(f.key);
+      const status = result.dryRun
+        ? '(would KEEP your version)'
+        : applied
+          ? '✓ accepted — template version applied'
+          : '↩ kept your version';
+      lines.push(`- **${f.label}** \`${f.key}\` ${status}`);
+      lines.push(`  - cube (current): "${trunc(f.cubeValue)}"`);
+      lines.push(`  - template (new): "${trunc(f.templateValue)}"`);
+    }
+    lines.push('');
+  }
+
+  // ── Unmatched decision keys (typo'd / stale — intended accept dropped) ──
+  const unmatched = result.unmatchedDecisions ?? [];
+  if (unmatched.length > 0) {
+    lines.push(
+      `### ⚠ ${unmatched.length} decision key(s) matched no conflict and were ignored`
+    );
+    lines.push(
+      'These keys in your `decisions` map did not correspond to any classified conflict this run ' +
+        '(typo or stale key) — their intended accept had NO effect. Check the exact keys against the conflicts above:'
+    );
+    for (const k of unmatched) {
+      lines.push(`- \`${k}\``);
+    }
+    lines.push('');
+  }
+
+  // ── Additions (safe auto-apply, zero clobber risk) ──
+  if (newRoles.length > 0 || adds.length > 0) {
+    lines.push(`### Additions (safe — auto-applied, zero clobber risk)`);
+    for (const r of newRoles) {
+      const note = result.dryRun ? '(new role — would be created)' : '✓ created';
+      lines.push(`- new role **${r.name}** ${note}`);
+    }
+    for (const f of adds) {
+      const note = result.dryRun ? '(would be added)' : '✓ added';
+      lines.push(`- **${f.label}** \`${f.key}\` ${note}`);
+    }
+    lines.push('');
+  }
+
+  // ── Custom roles (never touched) ──
+  if (customRoles.length > 0) {
+    lines.push(
+      `### Custom roles (untouched): ${customRoles.map((r) => r.name).join(', ')}`
+    );
+    lines.push('');
+  }
+
+  // ── Clean no-op ──
+  if (conflicts.length === 0 && adds.length === 0 && newRoles.length === 0) {
+    lines.push('✓ Cube roles + taxonomy are **up to date** with the template (no changes).');
+  }
+
+  return lines.join('\n').trimEnd();
+}