session-orchestrator 3.16.0

package/scripts/lib/tmux-layout/layouts.mjs

@@ -0,0 +1,224 @@
+/**
+ * layouts.mjs — tmux layout renderers for the session-orchestrator tmux-layout skill.
+ *
+ * Exports:
+ *   renderDefaultLayout({ sessionName, force, projectRoot, vcsConfig? })
+ *   renderDebugLayout({ sessionName, force, projectRoot })
+ *
+ * Default layout pane map (user-facing numbering):
+ *   Pane 1 (top-left)     — scratch shell (NO command — default tmux shell, AUQ-001 compliance)
+ *   Pane 2 (top-right)    — tail -F <stateDir>/STATE.md
+ *   Pane 3 (bottom-right) — vcs-aware CI watch (poll-loop from detectVcsCommand)
+ *   Pane 4 (bottom-left)  — tail -F .orchestrator/metrics/events.jsonl | jq select(wave|gate|spiral)
+ *   Pane 5 (optional)     — agent-status telemetry (#565), only when withStatusPane is true:
+ *                           poll-loop over .orchestrator/runtime/agent-status-current.json
+ *
+ * Debug layout pane map (user-facing numbering):
+ *   Pane 1 (top-left)     — scratch shell (NO command — default tmux shell, AUQ-001 compliance)
+ *   Pane 2 (top-right)    — hypothesis-test runner: npm test -- --watch
+ *   Pane 3 (bottom-right) — debug-artifact tail: tail -F .orchestrator/debug/*.md
+ *   Pane 4 (bottom-left)  — diff-watch: watch -n 2 'git diff --stat | head -30'
+ *
+ * Issues #561, #562 — ADR-0007 tmux-visualization substrate.
+ */
+
+import path from 'node:path';
+import { resolveStateDir } from '../platform.mjs';
+import { detectVcsCommand } from './vcs-detector.mjs';
+import { isSessionCollision } from './tmux-shell.mjs';
+
+// ---------------------------------------------------------------------------
+// Telemetry wrapper — defensive import (P2 parallel agent owns telemetry.mjs)
+// ---------------------------------------------------------------------------
+
+/** @type {(layoutName: string, fn: Function) => Function} */
+let withTelemetry;
+try {
+  // P2 owns scripts/lib/tmux-layout/telemetry.mjs — import defensively so that
+  // layouts.mjs works (without telemetry) even when P2's file has not landed yet.
+  ({ withTelemetry } = await import('./telemetry.mjs'));
+} catch {
+  // Fallback: identity wrapper — emits no telemetry but preserves the layout API.
+  // This code path is exercised during development and test runs before P2 ships.
+  withTelemetry = (_layoutName, fn) => fn;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Single-quote a shell command string for use as a tmux send-keys argument.
+ * Escapes embedded single-quotes using the POSIX `'...' '\'' '...'` pattern.
+ *
+ * @param {string} s
+ * @returns {string}  e.g. 'tail -F /path/to/STATE.md'
+ */
+function shellQuote(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+// ---------------------------------------------------------------------------
+// renderDefaultLayout
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the default 4-pane tmux layout.
+ *
+ * Produces a one-liner shell command that the user pastes into a SECOND terminal
+ * (not the coordinator terminal). The coordinator terminal remains untouched.
+ *
+ * Collision policy (PSA-003):
+ *   - If session already exists and --force is false → refuse with an error.
+ *   - If session already exists and --force is true  → kill it first.
+ *
+ * @param {{ sessionName: string, force: boolean, projectRoot: string, vcsConfig?: object, withStatusPane?: boolean }} ctx
+ * @returns {Promise<{ ok: boolean, oneliner: string, panes: number, degraded: boolean, attachCommand: string, error?: string }>}
+ */
+async function _renderDefaultLayoutInner({ sessionName, force, projectRoot, vcsConfig, withStatusPane = false }) {
+  // 1. Resolve STATE.md path: resolveStateDir() returns '.claude' / '.codex' / '.cursor'
+  //    We intentionally do NOT hard-code projectRoot into the STATE.md path inside the
+  //    one-liner — the user pastes the command in THEIR second terminal from the same
+  //    project dir, so relative-from-cwd paths work. But for the tail -F of events.jsonl
+  //    (which is relative) and STATE.md (also relative) we keep them relative.
+  const stateDirName = resolveStateDir();   // returns '.claude' | '.codex' | '.cursor'
+  const stateMdPath = path.join(stateDirName, 'STATE.md');
+
+  // 2. Resolve vcs command (Pane 3)
+  const vcs = detectVcsCommand({ config: vcsConfig, projectRoot });
+
+  // 3. Build pane commands (Pane 1 = scratch shell per AUQ-001 — no command sent, tmux uses default shell)
+  const pane2Cmd = `tail -F ${stateMdPath}`;
+  const pane3Cmd = vcs.command;
+  const pane4Cmd = `tail -F .orchestrator/metrics/events.jsonl | jq --unbuffered 'select(.event | test("wave|gate|spiral"))'`;
+  // Pane 5 (optional, #565): poll the LWW agent-status map. The `|| echo` fallback
+  // (mirrors Pane 3 style) keeps a missing file / absent jq from erroring the pane.
+  const pane5Cmd = `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null || echo 'no agent-status yet — set persistence:true + run a wave (see skills/wave-executor/wave-loop.md § 3a-bis)'; sleep 2; done`;
+
+  // 4. Session-collision check
+  const collision = isSessionCollision(sessionName);
+  if (collision.exists && !force) {
+    return {
+      ok: false,
+      oneliner: '',
+      panes: 0,
+      degraded: true,
+      attachCommand: '',
+      error: `Session '${sessionName}' already exists. Use --force to replace, or --session-name <other> to coexist (PSA-003).`,
+    };
+  }
+
+  // 5. Build one-liner segments. Commands are joined with ' && ' so any
+  //    failure aborts the chain early (fail-fast is safer than silent partial setup).
+  const segments = [];
+
+  // Kill existing session if --force
+  if (collision.exists && force) {
+    segments.push(`tmux kill-session -t ${sessionName} 2>/dev/null || true`);
+  }
+
+  // Create new detached session (Pane 0 = user-facing Pane 1, the scratch shell)
+  segments.push(`tmux new-session -d -s ${sessionName}`);
+
+  // Pane 1 (tmux index 0.0): scratch shell — send 'clear' to tidy it up, no further command
+  segments.push(`tmux send-keys -t ${sessionName}:0.0 'clear' Enter`);
+
+  // Pane 2 (tmux index 0.1): split horizontal on the window, run STATE.md tail
+  segments.push(`tmux split-window -h -t ${sessionName}:0`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.1 ${shellQuote(pane2Cmd)} Enter`);
+
+  // Pane 3 (tmux index 0.2): split vertically on Pane 2 (right side), run CI watch
+  segments.push(`tmux split-window -v -t ${sessionName}:0.1`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.2 ${shellQuote(pane3Cmd)} Enter`);
+
+  // Pane 4 (tmux index 0.3): split vertically on Pane 1 (left side), run events tail
+  segments.push(`tmux split-window -v -t ${sessionName}:0.0`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.3 ${shellQuote(pane4Cmd)} Enter`);
+
+  // Pane 5 (tmux index 0.4, optional #565): split off Pane 4, run agent-status poll-loop
+  if (withStatusPane) {
+    segments.push(`tmux split-window -v -t ${sessionName}:0.3`);
+    segments.push(`tmux send-keys -t ${sessionName}:0.4 ${shellQuote(pane5Cmd)} Enter`);
+  }
+
+  // Select Pane 1 (scratch shell) as the active pane, then attach
+  segments.push(`tmux select-pane -t ${sessionName}:0.0`);
+  segments.push(`tmux attach-session -t ${sessionName}`);
+
+  const oneliner = segments.join(' && ');
+  const attachCommand = `tmux attach-session -t ${sessionName}`;
+
+  return {
+    ok: true,
+    oneliner,
+    panes: withStatusPane ? 5 : 4,
+    // degraded = true when no vcs tool available (Pane 3 shows a help message instead)
+    degraded: vcs.bin === null,
+    attachCommand,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// renderDebugLayout — STUB (#562, deferred to W3 P1)
+// ---------------------------------------------------------------------------
+
+/**
+ * STUB for GitLab #562 — W3 P1 will implement the debug layout variant.
+ * For now returns a degraded result indicating not-yet-implemented.
+ *
+ * Signature MUST match renderDefaultLayout for uniform consumption by I2.
+ *
+ * @param {{ sessionName: string, force: boolean, projectRoot: string }} ctx
+ * @returns {Promise<{ ok: boolean, oneliner: string, panes: number, degraded: boolean, attachCommand: string, error?: string }>}
+ */
+async function _renderDebugLayoutInner({ sessionName, force, projectRoot: _projectRoot }) {
+  // Debug layout (4 panes — #562):
+  //   Pane 1: scratch shell (AUQ-001)
+  //   Pane 2: npm test --watch (hypothesis-test runner)
+  //   Pane 3: tail -F .orchestrator/debug/*.md (debug-artifact tail)
+  //   Pane 4: watch -n 2 'git diff --stat | head -30' (diff-watch)
+
+  const pane2Cmd = `npm test -- --watch 2>&1 | head -200`;
+  const pane3Cmd = `tail -F .orchestrator/debug/*.md 2>/dev/null || echo 'no .orchestrator/debug/*.md yet — companion to /debug skill Phase 2'`;
+  const pane4Cmd = `watch -n 2 'git diff --stat | head -30'`;
+
+  // Session-collision check (same policy as default layout — PSA-003)
+  const collision = isSessionCollision(sessionName);
+  if (collision.exists && !force) {
+    return {
+      ok: false,
+      oneliner: '',
+      panes: 0,
+      degraded: true,
+      attachCommand: '',
+      error: `Session '${sessionName}' already exists. Use --force to replace, or --session-name <other> to coexist (PSA-003).`,
+    };
+  }
+
+  const segments = [];
+  if (collision.exists && force) {
+    segments.push(`tmux kill-session -t ${sessionName} 2>/dev/null || true`);
+  }
+  segments.push(`tmux new-session -d -s ${sessionName}`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.0 'clear' Enter`);
+  segments.push(`tmux split-window -h -t ${sessionName}:0`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.1 ${shellQuote(pane2Cmd)} Enter`);
+  segments.push(`tmux split-window -v -t ${sessionName}:0.1`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.2 ${shellQuote(pane3Cmd)} Enter`);
+  segments.push(`tmux split-window -v -t ${sessionName}:0.0`);
+  segments.push(`tmux send-keys -t ${sessionName}:0.3 ${shellQuote(pane4Cmd)} Enter`);
+  segments.push(`tmux select-pane -t ${sessionName}:0.0`);
+  segments.push(`tmux attach-session -t ${sessionName}`);
+
+  return {
+    ok: true,
+    oneliner: segments.join(' && '),
+    panes: 4,
+    degraded: false,
+    attachCommand: `tmux attach-session -t ${sessionName}`,
+  };
+}
+
+// Public exports — wrapped with telemetry for promotion-gate criteria (#563)
+export const renderDefaultLayout = withTelemetry('default', _renderDefaultLayoutInner);
+export const renderDebugLayout = withTelemetry('debug', _renderDebugLayoutInner);

package/scripts/lib/tmux-layout/telemetry-stats.mjs

@@ -0,0 +1,100 @@
+/**
+ * scripts/lib/tmux-layout/telemetry-stats.mjs
+ *
+ * Aggregator stub for /tmux-layout telemetry promotion gate (#563).
+ * Reads .orchestrator/metrics/events.jsonl and computes:
+ *   - invocation count (total + per layout)
+ *   - completion rate (completed / invoked) — promotion gate threshold 80%
+ *   - top-K degradation reasons
+ *   - meetsPromotionGate boolean (#563 acceptance criterion)
+ *
+ * Usage:
+ *   - Programmatic: `import { computeStats, readTmuxEvents } from './telemetry-stats.mjs'`
+ *   - CLI: `node scripts/lib/tmux-layout/telemetry-stats.mjs` (emits JSON to stdout)
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+
+const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
+
+/**
+ * Read events.jsonl and return tmux-layout-related events.
+ *
+ * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
+ * @returns {Array<object>}  parsed event records (filtered to tmux-layout.* events)
+ */
+export function readTmuxEvents(eventsPath = EVENTS_PATH) {
+  if (!existsSync(eventsPath)) return [];
+  const raw = readFileSync(eventsPath, 'utf-8');
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  return lines
+    .map((l) => {
+      try { return JSON.parse(l); } catch { return null; }
+    })
+    .filter((rec) => rec && typeof rec.event === 'string' && rec.event.startsWith('tmux-layout.'));
+}
+
+/**
+ * Compute promotion-gate stats from tmux-layout events.
+ *
+ * @param {Array<object>} events  output of readTmuxEvents()
+ * @returns {{
+ *   invocations: number,
+ *   completions: number,
+ *   degradations: number,
+ *   completionRate: number | null,
+ *   byLayout: Record<string, {invoked: number, completed: number, degraded: number}>,
+ *   topDegradationReasons: Array<{reason: string, count: number}>,
+ *   meetsPromotionGate: boolean
+ * }}
+ */
+export function computeStats(events) {
+  const invocations = events.filter((e) => e.event === 'tmux-layout.invoked');
+  const completions = events.filter((e) => e.event === 'tmux-layout.completed');
+  const degradations = events.filter((e) => e.event === 'tmux-layout.degraded');
+
+  const byLayout = {};
+  const bump = (e, key) => {
+    const layout = e.layout ?? 'unknown';
+    byLayout[layout] ??= { invoked: 0, completed: 0, degraded: 0 };
+    byLayout[layout][key]++;
+  };
+  for (const e of invocations) bump(e, 'invoked');
+  for (const e of completions) bump(e, 'completed');
+  for (const e of degradations) bump(e, 'degraded');
+
+  const completionRate = invocations.length > 0
+    ? completions.length / invocations.length
+    : null;
+
+  const reasonCounts = {};
+  for (const e of degradations) {
+    const reason = e.reason ?? 'unknown';
+    reasonCounts[reason] = (reasonCounts[reason] ?? 0) + 1;
+  }
+  const topDegradationReasons = Object.entries(reasonCounts)
+    .map(([reason, count]) => ({ reason, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5);
+
+  // Promotion gate (#563): >= 5 invocations AND completion rate >= 0.80
+  const meetsPromotionGate =
+    invocations.length >= 5 && (completionRate ?? 0) >= 0.80;
+
+  return {
+    invocations: invocations.length,
+    completions: completions.length,
+    degradations: degradations.length,
+    completionRate,
+    byLayout,
+    topDegradationReasons,
+    meetsPromotionGate,
+  };
+}
+
+// CLI entry-point — emit stats as JSON to stdout when run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const events = readTmuxEvents();
+  const stats = computeStats(events);
+  console.log(JSON.stringify(stats, null, 2));
+}

package/scripts/lib/tmux-layout/telemetry.mjs

@@ -0,0 +1,88 @@
+/**
+ * scripts/lib/tmux-layout/telemetry.mjs
+ *
+ * Telemetry for the /tmux-layout skill — emits structured events to
+ * .orchestrator/metrics/events.jsonl for the promotion-gate criteria
+ * defined in GitLab #563 and docs/adr/0007-tmux-visualization-substrate.md.
+ *
+ * Three event types:
+ *   - tmux-layout.invoked    — fires before layout function runs
+ *   - tmux-layout.completed  — fires after layout function returns ok
+ *   - tmux-layout.degraded   — fires when layout returns ok:false OR throws
+ *
+ * Promotion gate (#563): invocation count >= 5 across >= 3 distinct deep
+ * sessions over >= 2 calendar weeks, layout-completion rate >= 80%, zero
+ * AUQ-001 / PSA-003 regressions. See ADR-0007 § Follow-ups.
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
+
+/**
+ * Emit a single tmux-layout event to events.jsonl.
+ * Best-effort — never throws (telemetry must not block the layout itself).
+ *
+ * @param {string} eventType - 'tmux-layout.invoked' | 'tmux-layout.degraded' | 'tmux-layout.completed'
+ * @param {object} [payload] - additional fields (layout, duration_ms, reason, etc.)
+ */
+export function emit(eventType, payload = {}) {
+  try {
+    const dir = path.dirname(EVENTS_PATH);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const record = {
+      event: eventType,
+      timestamp: new Date().toISOString(),
+      ...payload,
+    };
+    appendFileSync(EVENTS_PATH, JSON.stringify(record) + '\n');
+  } catch {
+    // Best-effort — swallow all errors. Telemetry must not block layout.
+  }
+}
+
+/**
+ * Wrap a layout function with telemetry. Emits invoked → completed/degraded.
+ *
+ * @param {string} layoutName - 'default' | 'debug'
+ * @param {Function} fn - async function returning { ok, oneliner, panes, degraded, attachCommand, error? }
+ * @returns {Function} wrapped function with same signature
+ * @throws {TypeError} synchronously when fn is not a function
+ */
+export function withTelemetry(layoutName, fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError(`withTelemetry: fn must be a function (got ${typeof fn})`);
+  }
+  return async function telemetryWrapped(...args) {
+    const startedAt = Date.now();
+    emit('tmux-layout.invoked', { layout: layoutName });
+    try {
+      const result = await fn(...args);
+      const durationMs = Date.now() - startedAt;
+      if (result && result.ok === true) {
+        emit('tmux-layout.completed', {
+          layout: layoutName,
+          duration_ms: durationMs,
+          panes: result.panes ?? null,
+          degraded: result.degraded === true,
+        });
+      } else {
+        emit('tmux-layout.degraded', {
+          layout: layoutName,
+          duration_ms: durationMs,
+          reason: result?.error ?? 'unknown',
+        });
+      }
+      return result;
+    } catch (err) {
+      const durationMs = Date.now() - startedAt;
+      emit('tmux-layout.degraded', {
+        layout: layoutName,
+        duration_ms: durationMs,
+        reason: `exception: ${err?.message ?? String(err)}`,
+      });
+      throw err;
+    }
+  };
+}

package/scripts/lib/tmux-layout/tmux-shell.mjs

@@ -0,0 +1,82 @@
+/**
+ * tmux-shell.mjs — tmux availability detection + session-collision helpers.
+ *
+ * Issue #561 — ADR-0007 tmux-visualization substrate.
+ */
+
+import { execSync } from 'node:child_process';
+
+const MIN_MAJOR = 3;
+const MIN_MINOR = 0;
+
+/**
+ * Detect tmux availability + version.
+ *
+ * Supports standard version strings ("tmux 3.4", "tmux 3.4a") and the
+ * "next-" prefix used in development builds ("tmux next-3.5").
+ *
+ * @returns {{ available: boolean, version: string|null, satisfiesMin: boolean, major?: number, minor?: number }}
+ */
+export function detectTmuxVersion() {
+  try {
+    const raw = execSync('tmux -V', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+
+    // Supports both "tmux 3.4a" (stable) and "tmux next-3.5" (development builds)
+    const match = raw.match(/^tmux\s+(?:next-)?(\d+)\.(\d+)([a-z])?/i);
+    if (!match) {
+      return { available: true, version: raw, satisfiesMin: false };
+    }
+
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    const satisfiesMin =
+      major > MIN_MAJOR || (major === MIN_MAJOR && minor >= MIN_MINOR);
+
+    return { available: true, version: raw, satisfiesMin, major, minor };
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.status === 127) {
+      return { available: false, version: null, satisfiesMin: false };
+    }
+    // Other spawn errors — re-classify as unavailable to be safe
+    return { available: false, version: null, satisfiesMin: false };
+  }
+}
+
+/**
+ * Check whether a tmux session with the given name already exists.
+ *
+ * Runs `tmux has-session -t <name>`: exit 0 means session found, exit 1 means not found.
+ *
+ * @param {string} sessionName
+ * @returns {{ exists: boolean, error?: string }}
+ */
+export function isSessionCollision(sessionName) {
+  if (!sessionName || typeof sessionName !== 'string') {
+    return { exists: false, error: 'sessionName must be a non-empty string' };
+  }
+
+  try {
+    execSync(`tmux has-session -t ${shellQuote(sessionName)}`, {
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return { exists: true }; // exit 0 means session found
+  } catch (err) {
+    if (err.status === 1) return { exists: false }; // exit 1 means no such session
+    if (err.code === 'ENOENT') return { exists: false, error: 'tmux not installed' };
+    return { exists: false, error: `tmux has-session failed: ${err.message}` };
+  }
+}
+
+/**
+ * Shell-quote a string for safe interpolation into a shell command.
+ * Uses single-quote wrapping with embedded single-quote escaping.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function shellQuote(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}

package/scripts/lib/tmux-layout/vcs-detector.mjs

@@ -0,0 +1,88 @@
+/**
+ * vcs-detector.mjs — Resolve the CI-watch pane command for the tmux default layout.
+ *
+ * Reads the `vcs:` key from Session Config and returns a poll-loop shell command
+ * suitable for Pane 3 (bottom-right). Both glab and gh are poll-based (not live-tail),
+ * so all commands are wrapped in a `while true; sleep` loop per D5 findings.
+ *
+ * Issue #561 — ADR-0007 tmux-visualization substrate.
+ */
+
+/**
+ * Resolve the CI-watch pane command based on Session Config vcs: key.
+ *
+ * @param {{ config?: object, projectRoot: string }} args
+ * @returns {{ bin: 'glab'|'gh'|null, command: string, fallback: string, blocking: boolean, platform: 'gitlab'|'github'|null }}
+ *   - command: the shell command for Pane 3 (wrapped in poll-loop since glab/gh are poll-based, not live-tail)
+ *   - fallback: shell command shown when bin is not available in PATH
+ */
+export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
+  const vcs = config?.vcs;   // 'gitlab' | 'github' | undefined
+
+  if (vcs === 'gitlab') {
+    return {
+      bin: 'glab',
+      platform: 'gitlab',
+      blocking: true,
+      command: [
+        'while true; do',
+        '  clear;',
+        '  date;',
+        "  echo '--- glab ci status (refresh: 15s) ---';",
+        '  glab ci status --pipeline-id LATEST --output json 2>&1',
+        "    | jq -r '.[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
+        "    || echo 'glab not available or no pipeline';",
+        '  sleep 15;',
+        'done',
+      ].join(' '),
+      fallback: [
+        'while true; do',
+        '  clear;',
+        "  echo 'glab not installed — install: brew install glab (macOS) / apt install glab (Linux)';",
+        '  sleep 60;',
+        'done',
+      ].join(' '),
+    };
+  }
+
+  if (vcs === 'github') {
+    return {
+      bin: 'gh',
+      platform: 'github',
+      blocking: true,
+      command: [
+        'while true; do',
+        '  clear;',
+        '  date;',
+        "  echo '--- gh pr checks --watch (will exit on PR completion) ---';",
+        '  gh pr checks --watch 2>&1',
+        "    || echo 'no PR in current branch';",
+        '  sleep 15;',
+        'done',
+      ].join(' '),
+      fallback: [
+        'while true; do',
+        '  clear;',
+        "  echo 'gh CLI not installed — install: brew install gh (macOS) / apt install gh (Linux)';",
+        '  sleep 60;',
+        'done',
+      ].join(' '),
+    };
+  }
+
+  // vcs unset or other value — show a static informational message
+  return {
+    bin: null,
+    platform: null,
+    blocking: false,
+    command: [
+      'while true; do',
+      '  clear;',
+      "  echo 'vcs: not configured in Session Config (CLAUDE.md / AGENTS.md on Codex CLI).';",
+      "  echo 'Set vcs: gitlab or vcs: github to enable CI-watch in this pane.';",
+      '  sleep 60;',
+      'done',
+    ].join(' '),
+    fallback: '',
+  };
+}