@orchestrator-claude/cli 3.25.2 → 3.27.0

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

package/dist/templates/base/scripts/lib/mailbox/types.ts

@@ -0,0 +1,175 @@
+/**
+ * types.ts — Mailbox protocol types and Zod schemas (RFC-025 M1)
+ *
+ * Tasks:
+ *   1.1 — MessageEnvelope + Zod schema
+ *   1.2 — MailboxAddress / Role value types
+ *   1.3 — Body variant types + Zod sub-schemas
+ */
+
+import { z } from 'zod';
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.2 — Role value type
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Role identifies the agent type in the mailbox system.
+ * Each role may have multiple instances (differentiated by index in MailboxAddress).
+ */
+export const RoleSchema = z.enum([
+  'orchestrator',
+  'implementer',
+  'planner',
+  'reviewer',
+  'debug-sidecar',
+  'test-sidecar',
+  'doc-sidecar',
+]);
+export type Role = z.infer<typeof RoleSchema>;
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.2 — MailboxAddress value type
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * MailboxAddress uniquely identifies an agent mailbox.
+ * Multiple instances of the same role are distinguished by index.
+ *
+ * @example { role: 'implementer', index: 0 } → "implementer-0"
+ */
+export const MailboxAddressSchema = z.object({
+  role: RoleSchema,
+  index: z.number().int().nonnegative(),
+});
+export type MailboxAddress = z.infer<typeof MailboxAddressSchema>;
+
+/**
+ * Converts a MailboxAddress to its canonical directory-safe string form.
+ * Example: { role: 'implementer', index: 0 } → "implementer-0"
+ */
+export function addressToString(address: MailboxAddress): string {
+  return `${address.role}-${address.index}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.3 — Body variant schemas
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * TaskAssignmentBody — orchestrator → implementer/planner
+ * Assigns a specific task with acceptance criteria.
+ */
+export const TaskAssignmentBodySchema = z.object({
+  type: z.literal('task_assignment'),
+  taskId: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+  acceptanceCriteria: z.array(z.string()),
+});
+export type TaskAssignmentBody = z.infer<typeof TaskAssignmentBodySchema>;
+
+/**
+ * TaskCompleteBody — implementer/planner → orchestrator
+ * Signals that a task has been completed successfully.
+ */
+export const TaskCompleteBodySchema = z.object({
+  type: z.literal('task_complete'),
+  taskId: z.string().min(1),
+  summary: z.string(),
+});
+export type TaskCompleteBody = z.infer<typeof TaskCompleteBodySchema>;
+
+/**
+ * StatusUpdateBody — implementer/planner → orchestrator
+ * Reports incremental progress on a task.
+ */
+export const StatusUpdateBodySchema = z.object({
+  type: z.literal('status_update'),
+  taskId: z.string().min(1),
+  progress: z.number().int().min(0).max(100),
+  message: z.string(),
+});
+export type StatusUpdateBody = z.infer<typeof StatusUpdateBodySchema>;
+
+/**
+ * ErrorReportBody — any → any
+ * Reports an error. taskId is optional (error may not be task-scoped).
+ */
+export const ErrorReportBodySchema = z.object({
+  type: z.literal('error_report'),
+  errorCode: z.string().min(1),
+  message: z.string(),
+  taskId: z.string().optional(),
+});
+export type ErrorReportBody = z.infer<typeof ErrorReportBodySchema>;
+
+/**
+ * PingBody — any → any
+ * Heartbeat request.
+ */
+export const PingBodySchema = z.object({
+  type: z.literal('ping'),
+});
+export type PingBody = z.infer<typeof PingBodySchema>;
+
+/**
+ * PongBody — any → any
+ * Heartbeat response.
+ */
+export const PongBodySchema = z.object({
+  type: z.literal('pong'),
+});
+export type PongBody = z.infer<typeof PongBodySchema>;
+
+/**
+ * MessageBodySchema — discriminated union over all body variants.
+ * Discriminant key: `type`.
+ */
+export const MessageBodySchema = z.discriminatedUnion('type', [
+  TaskAssignmentBodySchema,
+  TaskCompleteBodySchema,
+  StatusUpdateBodySchema,
+  ErrorReportBodySchema,
+  PingBodySchema,
+  PongBodySchema,
+]);
+export type MessageBody = z.infer<typeof MessageBodySchema>;
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.1 — MessageEnvelope + Zod schema
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * MessageEnvelope is the top-level protocol unit exchanged between agents.
+ * All messages on the filesystem are JSON-serialized MessageEnvelope objects.
+ */
+export const MessageEnvelopeSchema = z.object({
+  /** UUID v4 — unique message identifier */
+  id: z.string().uuid(),
+  /** Sender address */
+  from: MailboxAddressSchema,
+  /** Recipient address */
+  to: MailboxAddressSchema,
+  /** ISO 8601 UTC timestamp of creation */
+  timestamp: z.string().datetime(),
+  /** Typed message payload */
+  body: MessageBodySchema,
+});
+export type MessageEnvelope = z.infer<typeof MessageEnvelopeSchema>;
+
+// ─────────────────────────────────────────────────────────────
+// RegistryEntry — sprint agent registration record (RFC-025 M4)
+// ─────────────────────────────────────────────────────────────
+
+export const RegistryEntrySchema = z.object({
+  role: RoleSchema,
+  sprintId: z.string(),
+  sessionId: z.string().optional(),
+  pid: z.number(),
+  registeredAt: z.string().datetime(),
+  worktreePath: z.string().optional(),
+  workflowId: z.string().optional(),
+  resumedAt: z.string().datetime().optional(),
+});
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;

package/dist/templates/base/scripts/lib/sidecar/SidecarWatcher.ts

@@ -0,0 +1,249 @@
+/**
+ * SidecarWatcher.ts — Reactive sidecar process for sprint mailbox events (RFC-025 v3.3)
+ *
+ * A Node.js watcher that listens for incoming mailbox messages and spawns
+ * Agent SDK `query()` calls on demand — zero idle resource usage.
+ *
+ * Architecture:
+ *   1. chokidar watches the inbox directory for new .json files
+ *   2. On "add" event: read + validate envelope via Zod, then unlink (consume)
+ *   3. Build a prompt from the envelope body and call SDK query()
+ *   4. Stream query output to stdout (visible in the tmux pane)
+ *
+ * DI via factory function — same pattern as MailboxWatcher.ts and gate-guardian.ts.
+ * All external dependencies (chokidar, SDK, fs) are injected for testability.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { watch as chokidarWatchFn } from 'chokidar';
+import type { FSWatcher, WatchOptions } from 'chokidar';
+import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
+import type { Options } from '@anthropic-ai/claude-agent-sdk';
+import { MessageEnvelopeSchema } from '../mailbox/types.js';
+import type { MessageEnvelope } from '../mailbox/types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal query function signature — accepts prompt + options, returns async iterable.
+ * Matches @anthropic-ai/claude-agent-sdk's query() signature.
+ */
+export type QueryFn = (params: {
+  prompt: string;
+  options?: Options;
+}) => AsyncIterable<unknown>;
+
+export interface SidecarWatcherDeps {
+  /** Absolute path to the inbox directory to watch. */
+  inboxPath: string;
+  /** Absolute path to the worktree — passed as cwd to SDK query(). */
+  worktreePath: string;
+  /** Agent slug passed to SDK query() options.agent. */
+  agentSlug: string;
+  /** Chokidar watch function (injected for testability). */
+  watch: (inboxPath: string, options?: WatchOptions) => FSWatcher;
+  /** Agent SDK query function (injected for testability). */
+  query: QueryFn;
+  /** fs.readFileSync (injected for testability). */
+  readFileSync: (filePath: string, encoding: BufferEncoding) => string;
+  /** fs.unlinkSync (injected for testability). */
+  unlinkSync: (filePath: string) => void;
+}
+
+export interface SidecarWatcher {
+  /** Start watching the inbox directory. Idempotent — calling twice is safe. */
+  start(): void;
+  /** Stop watching and release resources. Resolves when the watcher is closed. */
+  stop(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the prompt string sent to the Agent SDK from a validated envelope.
+ * For task_assignment: includes taskId, title, description, and acceptance criteria.
+ * For other body types: includes the serialised body as JSON context.
+ */
+function buildPrompt(envelope: MessageEnvelope): string {
+  const { body } = envelope;
+
+  if (body.type === 'task_assignment') {
+    const criteria = body.acceptanceCriteria.length > 0
+      ? `\n\nAcceptance criteria:\n${body.acceptanceCriteria.map(c => `- ${c}`).join('\n')}`
+      : '';
+    return [
+      `Task: ${body.taskId} — ${body.title}`,
+      body.description ? `\n${body.description}` : '',
+      criteria,
+    ].join('');
+  }
+
+  if (body.type === 'status_update') {
+    return `Status update for ${body.taskId}: [${body.progress}%] ${body.message}`;
+  }
+
+  if (body.type === 'task_complete') {
+    return `Task ${body.taskId} is complete. Summary: ${body.summary}`;
+  }
+
+  if (body.type === 'error_report') {
+    const taskSuffix = body.taskId ? ` (task: ${body.taskId})` : '';
+    return `Error [${body.errorCode}]${taskSuffix}: ${body.message}`;
+  }
+
+  // ping / pong / unknown — send minimal context
+  return `Received message of type "${body.type}" from ${envelope.from.role}-${envelope.from.index}. Acknowledge and stand by.`;
+}
+
+// ---------------------------------------------------------------------------
+// File guard
+// ---------------------------------------------------------------------------
+
+function isMessageFile(filePath: string): boolean {
+  const basename = path.basename(filePath);
+  return basename.endsWith('.json') && !basename.startsWith('.tmp-');
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+const defaultDeps: Pick<SidecarWatcherDeps, 'watch' | 'query' | 'readFileSync' | 'unlinkSync'> = {
+  watch: chokidarWatchFn,
+  query: sdkQuery,
+  readFileSync: (p, enc) => fs.readFileSync(p, enc),
+  unlinkSync: fs.unlinkSync,
+};
+
+export function createSidecarWatcher(deps: SidecarWatcherDeps): SidecarWatcher {
+  const {
+    inboxPath,
+    worktreePath,
+    agentSlug,
+    watch,
+    query,
+    readFileSync,
+    unlinkSync,
+  } = { ...defaultDeps, ...deps };
+
+  let fsWatcher: FSWatcher | null = null;
+
+  /**
+   * Handles a newly-added file in the inbox.
+   * Steps:
+   *   1. Guard: skip non-message files
+   *   2. Read + parse the envelope JSON
+   *   3. Validate against Zod schema
+   *   4. Unlink (consume) the file
+   *   5. Call SDK query() and drain the stream to stdout
+   */
+  async function handleAddedFile(filePath: string): Promise<void> {
+    if (!isMessageFile(filePath)) {
+      return;
+    }
+
+    let envelope: MessageEnvelope;
+
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const parsed: unknown = JSON.parse(raw);
+      envelope = MessageEnvelopeSchema.parse(parsed);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[sidecar:${agentSlug}] Failed to parse envelope at ${filePath}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+      return;
+    }
+
+    // Consume the file — done before query() so re-entry is safe
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // Best-effort — continue even if unlink fails (e.g. concurrent consumer)
+    }
+
+    const prompt = buildPrompt(envelope);
+
+    // eslint-disable-next-line no-console
+    console.log(`[sidecar:${agentSlug}] Processing message ${envelope.id} — calling query()...`);
+
+    try {
+      // Defense-in-depth: strip API keys from env passed to query().
+      // Primary stripping happens in run.ts (process.env level), but this
+      // ensures keys are never passed even if run.ts is bypassed.
+      const sidecarEnv: Record<string, string | undefined> = { ...process.env };
+      delete sidecarEnv['ANTHROPIC_API_KEY'];
+      delete sidecarEnv['CLAUDE_API_KEY'];
+
+      const stream = query({
+        prompt,
+        options: {
+          agent: agentSlug,
+          cwd: worktreePath,
+          // Sidecar runs non-interactively — must bypass all permission prompts.
+          permissionMode: 'bypassPermissions',
+          allowDangerouslySkipPermissions: true,
+          // Ephemeral — no need to persist session history for reactive sidecars.
+          persistSession: false,
+          // Force OAuth — same as `env -u ANTHROPIC_API_KEY` in TmuxManager.
+          env: sidecarEnv,
+        },
+      });
+
+      // Drain the stream — log result messages for observability
+      for await (const msg of stream) {
+        const m = msg as Record<string, unknown>;
+        if (m.type === 'result') {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[sidecar:${agentSlug}] query() completed — result: ${m.subtype}`,
+            typeof m.result === 'string' ? m.result.slice(0, 200) : '',
+          );
+        }
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[sidecar:${agentSlug}] query() error for message ${envelope.id}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  function start(): void {
+    if (fsWatcher !== null) {
+      // Already started — idempotent
+      return;
+    }
+
+    fsWatcher = watch(inboxPath, {
+      ignoreInitial: true,
+      persistent: true,
+      // usePolling fallback: when inotify watchers are exhausted (ENOSPC),
+      // chokidar falls back to polling. 1s interval is fine for mailbox events.
+      usePolling: true,
+      interval: 1000,
+    });
+
+    fsWatcher.on('add', (filePath: string) => {
+      // Fire-and-forget — errors are caught inside handleAddedFile
+      void handleAddedFile(filePath);
+    });
+  }
+
+  async function stop(): Promise<void> {
+    if (fsWatcher !== null) {
+      await fsWatcher.close();
+      fsWatcher = null;
+    }
+  }
+
+  return { start, stop };
+}