@orchestrator-claude/cli 3.25.1 → 3.26.0

package/templates/base/scripts/lib/TmuxManager.ts

@@ -0,0 +1,296 @@
+import * as childProcess from 'child_process';
+import * as fs from 'fs';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PaneLaunchConfig {
+  /** Agent role name passed to `--agent` flag */
+  role: string;
+  /** Worktree or project root path used as the pane working directory */
+  workdir: string;
+  /**
+   * Optional initial prompt for this pane. Not used by TmuxManager directly —
+   * consumed by SprintLauncher which calls `sendPromptLiteral()` after launch.
+   */
+  initialPrompt?: string;
+  /**
+   * Optional custom command to run instead of `claude --agent {role}`.
+   * Used by reactive sidecars (RFC-025 v3.3) to launch Node.js watcher
+   * processes instead of interactive Claude sessions.
+   */
+  command?: string;
+  /**
+   * Sprint session name (e.g. "sprint-5c757626"). When set, exported as
+   * SPRINT_ID env var so the sprint-teammate skill can resolve mailbox paths.
+   */
+  sprintId?: string;
+  /**
+   * Pane role with index (e.g. "implementer-0", "doc-sidecar-1"). When set,
+   * exported as PANE_ROLE env var for the sprint-teammate skill.
+   */
+  paneRole?: string;
+}
+
+export interface TmuxManager {
+  /** Returns true when a tmux session with the given name exists. */
+  hasSession(name: string): boolean;
+
+  /**
+   * Creates a new detached tmux session and starts the first pane.
+   * Window geometry: 220 columns x 50 rows.
+   */
+  createSession(sessionName: string, firstPane: PaneLaunchConfig): void;
+
+  /**
+   * Adds a pane to window 0 of an existing session via a horizontal split.
+   */
+  addPane(sessionName: string, pane: PaneLaunchConfig): void;
+
+  /**
+   * Applies the `even-horizontal` layout to window 0 of the session.
+   * Call after all panes have been added.
+   */
+  applyLayout(sessionName: string): void;
+
+  /**
+   * Kills the named tmux session.
+   * Errors (e.g. session not found) are swallowed.
+   */
+  killSession(name: string): void;
+
+  /**
+   * Convenience method: creates session + adds remaining panes + applies layout.
+   *
+   * @param sessionName  Name for the tmux session.
+   * @param panes        At least one PaneLaunchConfig. First becomes the session's
+   *                     initial pane; subsequent configs are added via split-window.
+   * @returns The session name passed in.
+   * @throws  When `panes` is empty.
+   */
+  launchLayout(sessionName: string, panes: PaneLaunchConfig[]): string;
+
+  /**
+   * Sends a prompt to a pane via literal keystrokes (`send-keys -l`) + Enter.
+   * Does NOT trigger bracket paste mode — prompt auto-submits in Claude Code.
+   * Use for initial sprint prompts and mid-sprint task dispatches.
+   */
+  sendPromptLiteral(sessionName: string, paneIndex: number, prompt: string): void;
+
+  /**
+   * @deprecated Use `sendPromptLiteral` instead.
+   * paste-buffer triggers bracket paste mode (TD-133).
+   */
+  sendPrompt(sessionName: string, paneIndex: number, prompt: string): void;
+
+  /**
+   * Attaches to the session.
+   * - If inside an existing tmux session (TMUX env var set): splits a window horizontally.
+   * - Otherwise: prints the attach command to console.log.
+   * Never throws.
+   */
+  autoAttach(sessionName: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Dependencies
+// ---------------------------------------------------------------------------
+
+export interface TmuxManagerDeps {
+  execSync: typeof childProcess.execSync;
+  /** Used by sendPrompt (deprecated) to write temp prompt files. Defaults to fs.writeFileSync. */
+  writeFileSync?: typeof fs.writeFileSync;
+  /** Used by sendPrompt (deprecated) to clean up temp prompt files. Defaults to fs.unlinkSync. */
+  unlinkSync?: typeof fs.unlinkSync;
+  /** Environment variables used for TMUX detection. Defaults to process.env. */
+  env?: Record<string, string | undefined>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a TmuxManager instance.
+ *
+ * @param deps  Optional dependency overrides. Defaults to the real `execSync`
+ *              from Node's `child_process` module so callers do not need to
+ *              pass anything in production.
+ */
+export function createTmuxManager(deps?: Partial<TmuxManagerDeps>): TmuxManager {
+  const exec = deps?.execSync ?? childProcess.execSync;
+  const writeFile = deps?.writeFileSync ?? fs.writeFileSync;
+  const unlink = deps?.unlinkSync ?? fs.unlinkSync;
+  const env: Record<string, string | undefined> = deps?.env ?? process.env;
+
+  /** Detects the tmux base-index setting (default: 0). */
+  function getBaseIndex(): number {
+    try {
+      const output = exec('tmux show-option -gv base-index', { stdio: 'pipe' });
+      const parsed = parseInt(String(output).trim(), 10);
+      return isNaN(parsed) ? 0 : parsed;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Detects the tmux pane-base-index setting (default: 0). */
+  function getPaneBaseIndex(): number {
+    try {
+      const output = exec('tmux show-window-option -gv pane-base-index', { stdio: 'pipe' });
+      const parsed = parseInt(String(output).trim(), 10);
+      return isNaN(parsed) ? 0 : parsed;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Builds the shell command for a given pane config.
+   * If `config.command` is set (reactive sidecars), uses it directly.
+   * Otherwise builds the claude CLI invocation for interactive mode.
+   */
+  function paneCmd(config: PaneLaunchConfig): string {
+    if (config.command) {
+      return config.command;
+    }
+    // Build env prefix: strip API key + inject sprint context vars.
+    const envParts = ['env -u ANTHROPIC_API_KEY'];
+    if (config.sprintId) {
+      envParts.push(`SPRINT_ID=${config.sprintId}`);
+    }
+    if (config.paneRole) {
+      envParts.push(`PANE_ROLE=${config.paneRole}`);
+    }
+    return `${envParts.join(' ')} claude --dangerously-skip-permissions --agent ${config.role}`;
+  }
+
+  /** Wraps a command so the pane shell stays alive after the process exits. */
+  function keepAlive(cmd: string): string {
+    return `bash -c "${cmd}; exec bash"`;
+  }
+
+  function hasSession(name: string): boolean {
+    try {
+      exec(`tmux has-session -t "${name}"`, { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function createSession(sessionName: string, firstPane: PaneLaunchConfig): void {
+    const cmd = keepAlive(paneCmd(firstPane));
+    exec(
+      `tmux new-session -d -s "${sessionName}" -x 220 -y 50 -c "${firstPane.workdir}" -- ${cmd}`,
+      { stdio: 'pipe' },
+    );
+  }
+
+  function addPane(sessionName: string, pane: PaneLaunchConfig): void {
+    const cmd = keepAlive(paneCmd(pane));
+    const winIdx = getBaseIndex();
+    exec(
+      `tmux split-window -h -t "${sessionName}:${winIdx}" -c "${pane.workdir}" -- ${cmd}`,
+      { stdio: 'pipe' },
+    );
+  }
+
+  function applyLayout(sessionName: string): void {
+    exec(`tmux select-layout -t "${sessionName}" even-horizontal`, { stdio: 'pipe' });
+  }
+
+  function killSession(name: string): void {
+    try {
+      exec(`tmux kill-session -t "${name}"`, { stdio: 'pipe' });
+    } catch {
+      // Session may not exist -- not an error for callers.
+    }
+  }
+
+  function launchLayout(sessionName: string, panes: PaneLaunchConfig[]): string {
+    if (panes.length === 0) {
+      throw new Error('launchLayout requires at least one PaneLaunchConfig');
+    }
+
+    createSession(sessionName, panes[0]);
+
+    for (let i = 1; i < panes.length; i++) {
+      addPane(sessionName, panes[i]);
+    }
+
+    if (panes.length > 1) {
+      applyLayout(sessionName);
+    }
+
+    return sessionName;
+  }
+
+  /**
+   * Sends a prompt to a pane using `send-keys -l` (literal keystrokes) + Enter.
+   * Unlike paste-buffer, literal keys do NOT trigger bracket paste mode,
+   * so the final Enter actually submits in Claude Code's TUI (TD-133).
+   * Slower than paste for long prompts (~1-2s for typical sprint prompts).
+   */
+  function sendPromptLiteral(sessionName: string, paneIndex: number, prompt: string): void {
+    const winIdx = getBaseIndex();
+    const paneBase = getPaneBaseIndex();
+    const tmuxPaneIdx = paneIndex + paneBase;
+    const target = `"${sessionName}:${winIdx}.${tmuxPaneIdx}"`;
+    // send-keys -l sends characters literally (no key lookup), avoiding bracket paste.
+    // Escape single quotes for the shell wrapper.
+    const escaped = prompt.replace(/'/g, "'\\''");
+    exec(`tmux send-keys -l -t ${target} '${escaped}'`, { stdio: 'pipe' });
+    exec(`tmux send-keys -t ${target} Enter`, { stdio: 'pipe' });
+  }
+
+  /**
+   * @deprecated Use `sendPromptLiteral` instead.
+   * Bracket paste mode prevents auto-submission in Claude Code (TD-133).
+   * Kept only as fallback reference.
+   */
+  function sendPrompt(sessionName: string, paneIndex: number, prompt: string): void {
+    const tmpPath = `/tmp/sprint-prompt-${sessionName}-${paneIndex}.txt`;
+    const winIdx = getBaseIndex();
+    const paneBase = getPaneBaseIndex();
+    const tmuxPaneIdx = paneIndex + paneBase;
+    writeFile(tmpPath, prompt);
+    try {
+      exec(`tmux load-buffer ${tmpPath}`, { stdio: 'pipe' });
+      exec(`tmux paste-buffer -t "${sessionName}:${winIdx}.${tmuxPaneIdx}"`, { stdio: 'pipe' });
+      exec(`tmux send-keys -t "${sessionName}:${winIdx}.${tmuxPaneIdx}" Enter`, { stdio: 'pipe' });
+    } finally {
+      unlink(tmpPath);
+    }
+  }
+
+  function autoAttach(sessionName: string): void {
+    const attachCmd = `tmux attach -t "${sessionName}"`;
+    try {
+      if (env['TMUX'] !== undefined) {
+        const baseIdx = getBaseIndex();
+        exec(`tmux link-window -s "${sessionName}:${baseIdx}"`, { stdio: 'pipe' });
+      } else {
+        // eslint-disable-next-line no-console
+        console.log(`Attach with: ${attachCmd}`);
+      }
+    } catch {
+      // Swallow errors — attach is best-effort.
+      // eslint-disable-next-line no-console
+      console.log(`Attach with: ${attachCmd}`);
+    }
+  }
+
+  return {
+    hasSession,
+    createSession,
+    addPane,
+    applyLayout,
+    killSession,
+    launchLayout,
+    sendPromptLiteral,
+    sendPrompt,
+    autoAttach,
+  };
+}

package/templates/base/scripts/lib/WorktreeIsolator.ts

@@ -0,0 +1,165 @@
+/**
+ * WorktreeIsolator.ts — Isolates worktree Claude environments (RFC-025)
+ *
+ * Responsibilities:
+ *   1. generateClaudeMd(role, worktreePath): Reads .claude/agents/<role>.md and
+ *      writes a role-specific CLAUDE.md to the worktree with a header wrapper.
+ *   2. generateSettingsJson(role, worktreePath): Strips orchestrator hooks, overrides
+ *      agent field, preserves all other settings, writes to worktree .claude/settings.json.
+ *   3. isolateWorktree(role, worktreePath): Convenience method calling both above.
+ *
+ * DI via factory function pattern (same pattern as gate-guardian.ts in ADR-017 Phase 4).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ─────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────
+
+export interface WorktreeIsolatorDeps {
+  readFileSync: typeof fs.readFileSync;
+  writeFileSync: typeof fs.writeFileSync;
+  mkdirSync: typeof fs.mkdirSync;
+  existsSync: typeof fs.existsSync;
+}
+
+export interface SprintContext {
+  sessionName: string;
+  workflowId: string;
+  mailboxRole: string;
+  task?: string;
+}
+
+export interface WorktreeIsolator {
+  generateClaudeMd(role: string, worktreePath: string, sprintContext?: SprintContext): void;
+  generateSettingsJson(role: string, worktreePath: string, sprintContext?: SprintContext): void;
+  isolateWorktree(role: string, worktreePath: string, sprintContext?: SprintContext): void;
+}
+
+// Shape of .claude/settings.json (only fields we care about)
+interface ClaudeSettings {
+  env?: Record<string, string>;
+  permissions?: unknown;
+  hooks?: unknown;
+  enableAllProjectMcpServers?: boolean;
+  enabledPlugins?: unknown;
+  alwaysThinkingEnabled?: boolean;
+  agent?: string;
+  [key: string]: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────
+
+const defaultDeps: WorktreeIsolatorDeps = {
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  existsSync: fs.existsSync,
+};
+
+export function createWorktreeIsolator(
+  projectRoot: string,
+  deps: Partial<WorktreeIsolatorDeps> = {},
+): WorktreeIsolator {
+  const { readFileSync, writeFileSync, mkdirSync, existsSync } = {
+    ...defaultDeps,
+    ...deps,
+  };
+
+  function generateClaudeMd(role: string, worktreePath: string, sprintContext?: SprintContext): void {
+    const capitalised = role.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('-');
+    const lines: string[] = [`# ${capitalised} Agent`];
+
+    if (sprintContext) {
+      const taskHint = sprintContext.task
+        ? `Task hint: ${sprintContext.task} (full task via mailbox)`
+        : 'Check mailbox for task assignments';
+      lines.push(
+        `Sprint: ${sprintContext.sessionName} | Mailbox: ${sprintContext.mailboxRole}`,
+        taskHint,
+      );
+    }
+
+    const output = lines.join('\n') + '\n';
+    writeFileSync(path.join(worktreePath, 'CLAUDE.md'), output, 'utf-8');
+  }
+
+  function generateSettingsJson(
+    role: string,
+    worktreePath: string,
+    sprintContext?: SprintContext,
+  ): void {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    const raw = readFileSync(settingsPath, 'utf-8') as string;
+    const original: ClaudeSettings = JSON.parse(raw);
+
+    // Build hooks: inject sprint-specific hooks when sprint context is available
+    const hooks: Record<string, unknown> = sprintContext
+      ? {
+          SessionStart: [
+            {
+              matcher: '',
+              hooks: [
+                { type: 'command', command: 'npx tsx .claude/hooks/sprint-registry.ts' },
+                {
+                  type: 'command',
+                  command: 'npx tsx .claude/hooks/mailbox-listener.ts',
+                  timeout: 3000,
+                },
+              ],
+            },
+          ],
+          PostToolUse: [
+            {
+              matcher: '',
+              hooks: [
+                {
+                  type: 'command',
+                  command: 'npx tsx .claude/hooks/mailbox-listener.ts',
+                  timeout: 3000,
+                },
+              ],
+            },
+          ],
+        }
+      : {};
+
+    // Merge sprint env vars into existing env when sprint context is present
+    const env = sprintContext
+      ? {
+          ...(original.env ?? {}),
+          SPRINT_ID: sprintContext.sessionName,
+          PANE_ROLE: sprintContext.mailboxRole,
+        }
+      : original.env;
+
+    const isolated: ClaudeSettings = {
+      ...original,
+      env,
+      hooks,
+      agent: role,
+    };
+
+    const claudeDir = path.join(worktreePath, '.claude');
+    if (!existsSync(claudeDir)) {
+      mkdirSync(claudeDir, { recursive: true });
+    }
+
+    writeFileSync(
+      path.join(claudeDir, 'settings.json'),
+      JSON.stringify(isolated, null, 2),
+      'utf-8',
+    );
+  }
+
+  function isolateWorktree(role: string, worktreePath: string, sprintContext?: SprintContext): void {
+    generateClaudeMd(role, worktreePath, sprintContext);
+    generateSettingsJson(role, worktreePath, sprintContext);
+  }
+
+  return { generateClaudeMd, generateSettingsJson, isolateWorktree };
+}

package/templates/base/scripts/lib/WorktreeManager.ts

@@ -0,0 +1,106 @@
+import * as childProcess from 'child_process';
+import path from 'path';
+
+export interface WorktreeManagerDeps {
+  execSync: typeof childProcess.execSync;
+}
+
+interface WorktreeEntry {
+  worktreePath: string;
+  branchName: string;
+}
+
+export interface WorktreeManager {
+  prune(): void;
+  getCurrentBranch(): string;
+  addWorktree(index: number, sessionName: string): string;
+  removeWorktree(worktreePath: string): void;
+  removeAll(sessionName: string): void;
+  getCreatedWorktrees(): string[];
+}
+
+export function createWorktreeManager(
+  projectRoot: string,
+  deps?: Partial<WorktreeManagerDeps>,
+): WorktreeManager {
+  const exec = deps?.execSync ?? childProcess.execSync;
+  const opts = { encoding: 'utf-8' as const };
+  const tracked: WorktreeEntry[] = [];
+
+  function prune(): void {
+    exec(`git -C "${projectRoot}" worktree prune`, opts);
+  }
+
+  function getCurrentBranch(): string {
+    const result = exec(`git -C "${projectRoot}" rev-parse --abbrev-ref HEAD`, opts);
+    return (result as string).trim();
+  }
+
+  function addWorktree(index: number, sessionName: string): string {
+    const worktreePath = path.resolve(projectRoot, '..', `wt-${sessionName}-${index}`);
+    const branchName = `${sessionName}-impl-${index}`;
+
+    exec(`git -C "${projectRoot}" worktree add -b "${branchName}" "${worktreePath}" HEAD`, opts);
+    tracked.push({ worktreePath, branchName });
+
+    return worktreePath;
+  }
+
+  function removeWorktree(worktreePath: string): void {
+    try {
+      exec(`git -C "${projectRoot}" worktree remove --force "${worktreePath}"`, opts);
+    } catch {
+      // Worktree may not exist — not an error
+    }
+
+    const entryIndex = tracked.findIndex((e) => e.worktreePath === worktreePath);
+    if (entryIndex !== -1) {
+      const { branchName } = tracked[entryIndex];
+      tracked.splice(entryIndex, 1);
+      try {
+        exec(`git -C "${projectRoot}" branch -d "${branchName}"`, opts);
+      } catch {
+        // Branch delete failure is non-fatal (e.g. unmerged changes) — warn but do not crash
+        console.warn(
+          `[WorktreeManager] Could not delete branch "${branchName}" — it may not have been fully merged.`,
+        );
+      }
+    }
+  }
+
+  function removeAll(_sessionName: string): void {
+    // Snapshot so iteration is stable even if tracked mutates
+    const entries = [...tracked];
+
+    for (const { worktreePath } of entries) {
+      try {
+        exec(`git -C "${projectRoot}" worktree remove --force "${worktreePath}"`, opts);
+      } catch {
+        // Continue removing remaining worktrees on partial failure
+      }
+    }
+
+    for (const { branchName } of entries) {
+      try {
+        exec(`git -C "${projectRoot}" branch -D "${branchName}"`, opts);
+      } catch {
+        // Branch may already be deleted — not an error
+      }
+    }
+
+    tracked.splice(0);
+  }
+
+  function getCreatedWorktrees(): string[] {
+    return tracked.map((e) => e.worktreePath);
+  }
+
+  return {
+    prune,
+    getCurrentBranch,
+    addWorktree,
+    removeWorktree,
+    removeAll,
+    getCreatedWorktrees,
+  };
+}