@orchestrator-claude/cli 3.25.1 → 3.26.0

package/dist/templates/base/scripts/lib/SprintLauncher.ts

@@ -0,0 +1,325 @@
+/**
+ * SprintLauncher.ts — Orchestrates the full sprint session launch (RFC-025)
+ *
+ * Responsibilities:
+ *   1. Validate prerequisites (tmux on PATH, claude on PATH, no duplicate session)
+ *   2. Prune stale worktrees
+ *   3. Create worktrees via WorktreeManager (one per pane)
+ *   4. Isolate each worktree via WorktreeIsolator
+ *   5. Launch tmux session via TmuxManager
+ *   6. Return LaunchResult
+ *
+ * DI via factory function — same pattern as gate-guardian.ts (ADR-017 Phase 4).
+ * execSync is injected for testability; in production use child_process.execSync.
+ * Input values (preset, workflowId) are validated before use in shell commands.
+ */
+
+import type { WorktreeManager } from './WorktreeManager.js';
+import type { WorktreeIsolator } from './WorktreeIsolator.js';
+import type { TmuxManager, PaneLaunchConfig } from './TmuxManager.js';
+import { SprintPreset } from '../../src/domain/value-objects/SprintLayout.js';
+import type { PaneConfig } from '../../src/domain/value-objects/SprintLayout.js';
+import type { generateLayout as GenerateLayoutFn } from '../../src/domain/value-objects/generateLayout.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Milliseconds to wait after launchLayout before sending activation prompts.
+ * Claude Code needs ~5-8 seconds to boot and display the ❯ prompt.
+ */
+export const BOOT_DELAY_MS = 7000;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+import type { MailboxAddress, MessageEnvelope } from './mailbox/types.js';
+
+/** Minimal MailboxManager interface required by SprintLauncher. */
+export interface MailboxManager {
+  /** Create mailbox inbox directories for each role in the sprint. */
+  init(addresses: readonly MailboxAddress[]): void;
+  /**
+   * Send a message envelope to the address encoded in envelope.to.
+   * Matches MailboxManager.sendMessage(envelope) from MailboxManager.ts.
+   */
+  sendMessage(envelope: MessageEnvelope): void;
+}
+
+export interface SprintTask {
+  taskId: string;
+  title: string;
+  description: string;
+  acceptanceCriteria: string[];
+}
+
+export interface LaunchResult {
+  sessionName: string;
+  workflowId: string;
+  preset: string;
+  worktreePaths: readonly string[];
+}
+
+export interface SprintLauncherDeps {
+  worktreeManager: WorktreeManager;
+  worktreeIsolator: WorktreeIsolator;
+  tmuxManager: TmuxManager;
+  generateLayout: typeof GenerateLayoutFn;
+  execSync: (cmd: string, opts?: object) => string | Buffer;
+  projectRoot: string;
+  /** Optional mailbox manager — initialises inbox directories before launch. */
+  mailboxManager?: MailboxManager;
+  /**
+   * Optional delay function — defaults to real setTimeout-based delay.
+   * Inject a no-op `() => Promise.resolve()` in tests to avoid 7s waits.
+   */
+  delay?: (ms: number) => Promise<void>;
+}
+
+export interface SprintLauncher {
+  launch(presetName: string, workflowId: string, tasks?: SprintTask[]): Promise<LaunchResult>;
+  cleanup(sessionName: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the agent role is a reactive sidecar (RFC-025 v3.3).
+ * Sidecars launch as Node.js watcher processes instead of interactive claude sessions.
+ * Implementers, reviewers, and other roles remain interactive.
+ */
+function isSidecarRole(role: string): boolean {
+  return role.includes('sidecar');
+}
+
+/**
+ * Builds the shell command for a reactive sidecar pane.
+ * Launches the SidecarWatcher script which watches the mailbox inbox
+ * and spawns Agent SDK query() calls on demand.
+ *
+ * The inbox path matches MailboxManager's layout: `/tmp/{sessionName}/mailbox/{role}-{index}/inbox`
+ *
+ * NOTE: The script runs from `projectRoot` (not the worktree) so that node_modules
+ * are available for chokidar and SDK imports. The worktree is passed as --worktree
+ * and used as cwd for the SDK query() call.
+ */
+function buildSidecarCommand(agentSlug: string, worktreePath: string, sessionName: string, mailboxRole: string, paneIndex: number, projectRoot: string): string {
+  const inboxPath = `/tmp/${sessionName}/mailbox/${mailboxRole}-${paneIndex}/inbox`;
+  return `cd "${projectRoot}" && npx tsx scripts/lib/sidecar/run.ts --inbox "${inboxPath}" --worktree "${worktreePath}" --agent ${agentSlug}`;
+}
+
+export function createSprintLauncher(deps: SprintLauncherDeps): SprintLauncher {
+  const { worktreeManager, worktreeIsolator, tmuxManager, generateLayout, execSync, mailboxManager } = deps;
+  const delay = deps.delay ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  function validatePrerequisites(sessionName: string): void {
+    // Validate tmux is on PATH (static command — no user input)
+    try {
+      execSync('which tmux', { stdio: 'pipe' });
+    } catch {
+      throw new Error(
+        'tmux is not on PATH. Install tmux to use sprint-launch.',
+      );
+    }
+
+    // Validate claude is on PATH (static command — no user input)
+    try {
+      execSync('which claude', { stdio: 'pipe' });
+    } catch {
+      throw new Error(
+        'claude is not on PATH. Install Claude Code CLI to use sprint-launch.',
+      );
+    }
+
+    // Guard against duplicate session via TmuxManager (no shell exec here)
+    if (tmuxManager.hasSession(sessionName)) {
+      throw new Error(
+        `tmux session '${sessionName}' already exists. Attach with: tmux attach -t ${sessionName}`,
+      );
+    }
+  }
+
+  async function launch(presetName: string, workflowId: string, tasks?: SprintTask[]): Promise<LaunchResult> {
+    // 1. Validate preset (validates input before any use in commands)
+    const presetResult = SprintPreset.create(presetName);
+    if (presetResult.isErr()) {
+      throw new Error(`Invalid preset: ${presetResult.error}`);
+    }
+    const preset = presetResult.value;
+
+    // 2. Derive session name
+    const sessionName = `sprint-${workflowId.slice(0, 8)}`;
+
+    // 3. Validate prerequisites
+    validatePrerequisites(sessionName);
+
+    // 4. Generate layout
+    const layoutResult = generateLayout(preset, workflowId);
+    if (layoutResult.isErr()) {
+      throw new Error(`Failed to generate layout: ${layoutResult.error}`);
+    }
+    const layout = layoutResult.value;
+
+    // 5. Initialise mailbox inbox directories (before worktree prune)
+    if (mailboxManager) {
+      const addresses: MailboxAddress[] = layout.panes.map((p: PaneConfig, i: number) => ({
+        role: p.context.mailboxRole as MailboxAddress['role'],
+        index: i,
+      }));
+      mailboxManager.init(addresses);
+    }
+
+    // 6. Prune stale worktrees
+    worktreeManager.prune();
+
+    // 7. Create worktrees (one per pane, indexed)
+    const worktreePaths: string[] = [];
+    for (let i = 0; i < layout.panes.length; i++) {
+      const worktreePath = worktreeManager.addWorktree(i, sessionName);
+      worktreePaths.push(worktreePath);
+    }
+
+    // 8. Build round-robin task assignment map (implementer panes only).
+    //    PaneConfig is frozen — use a separate Map to track assignments.
+    const paneTaskMap = new Map<number, SprintTask>();
+    if (tasks && tasks.length > 0) {
+      const implementerIndices = layout.panes
+        .map((pane: PaneConfig, i: number) => ({ pane, i }))
+        .filter(({ pane }) => pane.agent.includes('implementer'))
+        .map(({ i }) => i);
+
+      for (let t = 0; t < tasks.length; t++) {
+        const paneIndex = implementerIndices[t % implementerIndices.length];
+        if (paneIndex !== undefined) {
+          paneTaskMap.set(paneIndex, tasks[t]);
+        }
+      }
+    }
+
+    // 9. Isolate each worktree — inject sprint context into CLAUDE.md
+    //    so agents know their workflow, mailbox, and task at startup.
+    //    Zero tmux input needed (TD-133 resolved via CLAUDE.md injection).
+    for (let i = 0; i < layout.panes.length; i++) {
+      const pane = layout.panes[i];
+      const assignedTask = paneTaskMap.get(i);
+      worktreeIsolator.isolateWorktree(pane.agent, worktreePaths[i], {
+        sessionName,
+        workflowId,
+        mailboxRole: `${pane.context.mailboxRole}-${i}`,
+        task: assignedTask?.title ?? pane.context.task,
+      });
+    }
+
+    // 10. Send task assignment messages to agents via mailbox (before launch)
+    if (mailboxManager) {
+      for (let i = 0; i < layout.panes.length; i++) {
+        const pane = layout.panes[i];
+        const assignedTask = paneTaskMap.get(i);
+
+        // Use assigned SprintTask if available, otherwise fall back to pane.context.task
+        if (assignedTask) {
+          const address: MailboxAddress = {
+            role: pane.context.mailboxRole as MailboxAddress['role'],
+            index: i,
+          };
+          const envelope: MessageEnvelope = {
+            id: crypto.randomUUID(),
+            from: { role: 'orchestrator', index: 0 },
+            to: address,
+            timestamp: new Date().toISOString(),
+            body: {
+              type: 'task_assignment',
+              taskId: assignedTask.taskId,
+              title: assignedTask.title,
+              description: assignedTask.description,
+              acceptanceCriteria: assignedTask.acceptanceCriteria,
+            },
+          };
+          mailboxManager.sendMessage(envelope);
+        } else if (pane.context.task) {
+          const address: MailboxAddress = {
+            role: pane.context.mailboxRole as MailboxAddress['role'],
+            index: i,
+          };
+          const envelope: MessageEnvelope = {
+            id: crypto.randomUUID(),
+            from: { role: 'orchestrator', index: 0 },
+            to: address,
+            timestamp: new Date().toISOString(),
+            body: {
+              type: 'task_assignment',
+              taskId: `task-${i}`,
+              title: pane.context.task,
+              description: '',
+              acceptanceCriteria: [],
+            },
+          };
+          mailboxManager.sendMessage(envelope);
+        }
+      }
+    }
+
+    // 11. Build PaneLaunchConfig[] for TmuxManager (no initialPrompt needed)
+    //     Sidecar panes get a custom `command` that launches the reactive watcher
+    //     instead of an interactive `claude --agent` session (RFC-025 v3.3).
+    const paneLaunchConfigs: PaneLaunchConfig[] = layout.panes.map((pane: PaneConfig, i: number) => {
+      const config: PaneLaunchConfig = {
+        role: pane.agent,
+        workdir: worktreePaths[i],
+        sprintId: sessionName,
+        paneRole: `${pane.context.mailboxRole}-${i}`,
+      };
+      if (isSidecarRole(pane.agent)) {
+        config.command = buildSidecarCommand(
+          pane.agent,
+          worktreePaths[i],
+          sessionName,
+          pane.context.mailboxRole as string,
+          i,
+          deps.projectRoot,
+        );
+      }
+      return config;
+    });
+
+    // 12. Launch tmux session (interactive mode — TUI visible, context from CLAUDE.md)
+    tmuxManager.launchLayout(sessionName, paneLaunchConfigs);
+
+    // 12a. Wait for Claude to boot then activate implementer panes.
+    //      Sidecars stay idle — they respond reactively in a future version.
+    const implementerIndicesForActivation = paneLaunchConfigs
+      .map((pane, i) => ({ pane, i }))
+      .filter(({ pane }) => pane.role.includes('implementer'))
+      .map(({ i }) => i);
+
+    if (implementerIndicesForActivation.length > 0) {
+      // eslint-disable-next-line no-console
+      console.log('[sprint-launch] Activating implementer panes...');
+      await delay(BOOT_DELAY_MS);
+      for (const paneIndex of implementerIndicesForActivation) {
+        tmuxManager.sendPromptLiteral(sessionName, paneIndex, 'siga');
+      }
+    }
+
+    // 13. Auto-attach for seamless UX
+    tmuxManager.autoAttach(sessionName);
+
+    return {
+      sessionName,
+      workflowId,
+      preset: preset.value,
+      worktreePaths: Object.freeze(worktreePaths),
+    };
+  }
+
+  function cleanup(sessionName: string): void {
+    worktreeManager.removeAll(sessionName);
+    tmuxManager.killSession(sessionName);
+  }
+
+  return { launch, cleanup };
+}

package/dist/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,
+  };
+}