@cluesmith/codev 2.0.0-rc.8 → 2.0.0

package/dist/agent-farm/commands/spawn.js

@@ -1,39 +1,32 @@
 /**
- * Spawn command - creates a new builder in various modes
+ * Spawn command — orchestrator module.
+ * Spec 0105: Tower Server Decomposition — Phase 7
  *
  * Modes:
  * - spec:     --project/-p  Spawn for a spec file (existing behavior)
  * - task:     --task        Spawn with an ad-hoc task description
  * - protocol: --protocol    Spawn to run a protocol (cleanup, experiment, etc.)
  * - shell:    --shell       Bare Claude session (no prompt, no worktree)
+ *
+ * Role/prompt logic extracted to spawn-roles.ts.
+ * Worktree/git logic extracted to spawn-worktree.ts.
  */
-import { resolve, basename, join } from 'node:path';
-import { existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, symlinkSync, unlinkSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { randomUUID } from 'node:crypto';
-import { readdir } from 'node:fs/promises';
+import { resolve, basename } from 'node:path';
+import { existsSync, writeFileSync } from 'node:fs';
 import { getConfig, ensureDirectories, getResolvedCommands } from '../utils/index.js';
 import { logger, fatal } from '../utils/logger.js';
-import { run, commandExists, findAvailablePort, spawnTtyd } from '../utils/shell.js';
-import { loadState, upsertBuilder } from '../state.js';
+import { run } from '../utils/shell.js';
+import { upsertBuilder } from '../state.js';
 import { loadRolePrompt } from '../utils/roles.js';
+import { buildPromptFromTemplate, buildResumeNotice, loadProtocolRole, findSpecFile, validateProtocol, loadProtocol, resolveProtocol, resolveMode, } from './spawn-roles.js';
+import { DEFAULT_TOWER_PORT, checkDependencies, createWorktree, initPorchInWorktree, checkBugfixCollisions, fetchGitHubIssue, executePreSpawnHooks, slugify, validateResumeWorktree, createPtySession, startBuilderSession, startShellSession, buildWorktreeLaunchScript, } from './spawn-worktree.js';
+// =============================================================================
+// ID and Session Management
+// =============================================================================
 /**
  * Generate a short 4-character base64-encoded ID
  * Uses URL-safe base64 (a-z, A-Z, 0-9, -, _) for filesystem-safe IDs
  */
-/**
- * Get the project name from config (basename of projectRoot)
- * Used to namespace tmux sessions and prevent cross-project collisions
- */
-function getProjectName(config) {
-    return basename(config.projectRoot);
-}
-/**
- * Get a namespaced tmux session name: builder-{project}-{id}
- */
-function getSessionName(config, builderId) {
-    return `builder-${getProjectName(config)}-${builderId}`;
-}
 function generateShortId() {
     // Generate random 24-bit number and base64 encode to 4 chars
     const num = Math.floor(Math.random() * 0xFFFFFF);
@@ -45,64 +38,27 @@ function generateShortId() {
         .substring(0, 4);
 }
 /**
- * Format current date/time as YYYY-MM-DD HH:MM
- */
-function formatDateTime() {
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = String(now.getMonth() + 1).padStart(2, '0');
-    const day = String(now.getDate()).padStart(2, '0');
-    const hours = String(now.getHours()).padStart(2, '0');
-    const minutes = String(now.getMinutes()).padStart(2, '0');
-    return `${year}-${month}-${day} ${hours}:${minutes}`;
-}
-/**
- * Rename a Claude session after it starts
- * Uses tmux buffer approach for reliable text input (same as af send)
- */
-function renameClaudeSession(sessionName, displayName) {
-    // Wait for Claude to be ready, then send /rename command
-    setTimeout(async () => {
-        try {
-            // Add date/time to the display name
-            const nameWithTime = `${displayName} (${formatDateTime()})`;
-            const renameCommand = `/rename ${nameWithTime}`;
-            // Use buffer approach for reliable input (like af send)
-            const tempFile = join(tmpdir(), `rename-${randomUUID()}.txt`);
-            const bufferName = `rename-${sessionName}`;
-            writeFileSync(tempFile, renameCommand);
-            await run(`tmux load-buffer -b "${bufferName}" "${tempFile}"`);
-            await run(`tmux paste-buffer -b "${bufferName}" -t "${sessionName}"`);
-            await run(`tmux delete-buffer -b "${bufferName}"`).catch(() => { });
-            await run(`tmux send-keys -t "${sessionName}" Enter`);
-            // Clean up temp file
-            try {
-                unlinkSync(tempFile);
-            }
-            catch { }
-        }
-        catch {
-            // Non-fatal - session naming is a nice-to-have
-        }
-    }, 5000); // 5 second delay for Claude to initialize
-}
-/**
- * Validate spawn options - ensure exactly one mode is selected
+ * Validate spawn options - ensure exactly one input mode is selected
+ * Note: --protocol serves dual purpose:
+ *   1. As an input mode when used alone (e.g., `af spawn --protocol experiment`)
+ *   2. As a protocol override when combined with other input modes (e.g., `af spawn -p 0001 --protocol tick`)
  */
 function validateSpawnOptions(options) {
-    const modes = [
+    // Count input modes (excluding --protocol which can be used as override)
+    const inputModes = [
         options.project,
         options.task,
-        options.protocol,
         options.shell,
         options.worktree,
         options.issue,
     ].filter(Boolean);
-    if (modes.length === 0) {
+    // --protocol alone is a valid input mode
+    const protocolAlone = options.protocol && inputModes.length === 0;
+    if (inputModes.length === 0 && !protocolAlone) {
         fatal('Must specify one of: --project (-p), --issue (-i), --task, --protocol, --shell, --worktree\n\nRun "af spawn --help" for examples.');
     }
-    if (modes.length > 1) {
-        fatal('Flags --project, --issue, --task, --protocol, --shell, --worktree are mutually exclusive');
+    if (inputModes.length > 1) {
+        fatal('Flags --project, --issue, --task, --shell, --worktree are mutually exclusive');
     }
     if (options.files && !options.task) {
         fatal('--files requires --task');
@@ -110,238 +66,37 @@ function validateSpawnOptions(options) {
     if ((options.noComment || options.force) && !options.issue) {
         fatal('--no-comment and --force require --issue');
     }
+    // --protocol as override cannot be used with --shell or --worktree
+    if (options.protocol && inputModes.length > 0 && (options.shell || options.worktree)) {
+        fatal('--protocol cannot be used with --shell or --worktree (no protocol applies)');
+    }
+    // --use-protocol is now deprecated in favor of --protocol as universal override
+    // Keep for backwards compatibility but prefer --protocol
+    if (options.useProtocol && (options.shell || options.worktree)) {
+        fatal('--use-protocol cannot be used with --shell or --worktree (no protocol applies)');
+    }
 }
 /**
  * Determine the spawn mode from options
+ * Note: --protocol can be used as both an input mode (alone) or an override (with other modes)
  */
 function getSpawnMode(options) {
+    // Primary input modes take precedence over --protocol as override
     if (options.project)
         return 'spec';
     if (options.issue)
         return 'bugfix';
     if (options.task)
         return 'task';
-    if (options.protocol)
-        return 'protocol';
     if (options.shell)
         return 'shell';
     if (options.worktree)
         return 'worktree';
+    // --protocol alone is the protocol input mode
+    if (options.protocol)
+        return 'protocol';
     throw new Error('No mode specified');
 }
-// loadRolePrompt imported from ../utils/roles.js
-/**
- * Load a protocol-specific role if it exists
- */
-function loadProtocolRole(config, protocolName) {
-    const protocolRolePath = resolve(config.codevDir, 'protocols', protocolName, 'role.md');
-    if (existsSync(protocolRolePath)) {
-        return { content: readFileSync(protocolRolePath, 'utf-8'), source: 'protocol' };
-    }
-    // Fall back to builder role
-    return loadRolePrompt(config, 'builder');
-}
-/**
- * Find a spec file by project ID
- */
-async function findSpecFile(codevDir, projectId) {
-    const specsDir = resolve(codevDir, 'specs');
-    if (!existsSync(specsDir)) {
-        return null;
-    }
-    const files = await readdir(specsDir);
-    // Try exact match first (e.g., "0001-feature.md")
-    for (const file of files) {
-        if (file.startsWith(projectId) && file.endsWith('.md')) {
-            return resolve(specsDir, file);
-        }
-    }
-    // Try partial match (e.g., just "0001")
-    for (const file of files) {
-        if (file.startsWith(projectId + '-') && file.endsWith('.md')) {
-            return resolve(specsDir, file);
-        }
-    }
-    return null;
-}
-/**
- * Validate that a protocol exists
- */
-function validateProtocol(config, protocolName) {
-    const protocolDir = resolve(config.codevDir, 'protocols', protocolName);
-    const protocolFile = resolve(protocolDir, 'protocol.md');
-    if (!existsSync(protocolDir)) {
-        // List available protocols
-        const protocolsDir = resolve(config.codevDir, 'protocols');
-        let available = '';
-        if (existsSync(protocolsDir)) {
-            const dirs = readdirSync(protocolsDir, { withFileTypes: true })
-                .filter((d) => d.isDirectory())
-                .map((d) => d.name);
-            if (dirs.length > 0) {
-                available = `\n\nAvailable protocols: ${dirs.join(', ')}`;
-            }
-        }
-        fatal(`Protocol not found: ${protocolName}${available}`);
-    }
-    if (!existsSync(protocolFile)) {
-        fatal(`Protocol ${protocolName} exists but has no protocol.md file`);
-    }
-}
-/**
- * Check for required dependencies
- */
-async function checkDependencies() {
-    if (!(await commandExists('git'))) {
-        fatal('git not found');
-    }
-    if (!(await commandExists('ttyd'))) {
-        fatal('ttyd not found. Install with: brew install ttyd');
-    }
-}
-/**
- * Find an available port, avoiding ports already in use by other builders
- */
-async function findFreePort(config) {
-    const state = loadState();
-    const usedPorts = new Set();
-    for (const b of state.builders || []) {
-        if (b.port)
-            usedPorts.add(b.port);
-    }
-    let port = config.builderPortRange[0];
-    while (usedPorts.has(port)) {
-        port++;
-    }
-    return findAvailablePort(port);
-}
-/**
- * Create git branch and worktree
- */
-async function createWorktree(config, branchName, worktreePath) {
-    logger.info('Creating branch...');
-    try {
-        await run(`git branch ${branchName}`, { cwd: config.projectRoot });
-    }
-    catch (error) {
-        // Branch might already exist, that's OK
-        logger.debug(`Branch creation: ${error}`);
-    }
-    logger.info('Creating worktree...');
-    try {
-        await run(`git worktree add "${worktreePath}" ${branchName}`, { cwd: config.projectRoot });
-    }
-    catch (error) {
-        fatal(`Failed to create worktree: ${error}`);
-    }
-    // Symlink .env from project root into worktree (if it exists)
-    const rootEnvPath = resolve(config.projectRoot, '.env');
-    const worktreeEnvPath = resolve(worktreePath, '.env');
-    if (existsSync(rootEnvPath) && !existsSync(worktreeEnvPath)) {
-        try {
-            symlinkSync(rootEnvPath, worktreeEnvPath);
-            logger.info('Linked .env from project root');
-        }
-        catch (error) {
-            logger.debug(`Failed to symlink .env: ${error}`);
-        }
-    }
-}
-/**
- * Start tmux session and ttyd for a builder
- */
-async function startBuilderSession(config, builderId, worktreePath, baseCmd, prompt, roleContent, roleSource) {
-    const port = await findFreePort(config);
-    const sessionName = getSessionName(config, builderId);
-    logger.info('Creating tmux session...');
-    // Write initial prompt to a file for reference
-    const promptFile = resolve(worktreePath, '.builder-prompt.txt');
-    writeFileSync(promptFile, prompt);
-    // Build the start script with role if provided
-    const scriptPath = resolve(worktreePath, '.builder-start.sh');
-    let scriptContent;
-    if (roleContent) {
-        // Write role to a file and use $(cat) to avoid shell escaping issues
-        const roleFile = resolve(worktreePath, '.builder-role.md');
-        // Inject the actual dashboard port into the role prompt
-        const roleWithPort = roleContent.replace(/\{PORT\}/g, String(config.dashboardPort));
-        writeFileSync(roleFile, roleWithPort);
-        logger.info(`Loaded role (${roleSource})`);
-        scriptContent = `#!/bin/bash
-exec ${baseCmd} --append-system-prompt "$(cat '${roleFile}')" "$(cat '${promptFile}')"
-`;
-    }
-    else {
-        scriptContent = `#!/bin/bash
-exec ${baseCmd} "$(cat '${promptFile}')"
-`;
-    }
-    writeFileSync(scriptPath, scriptContent);
-    chmodSync(scriptPath, '755');
-    // Create tmux session running the script
-    await run(`tmux new-session -d -s "${sessionName}" -x 200 -y 50 -c "${worktreePath}" "${scriptPath}"`);
-    await run(`tmux set-option -t "${sessionName}" status off`);
-    // Enable mouse scrolling in tmux
-    await run('tmux set -g mouse on');
-    await run('tmux set -g set-clipboard on');
-    await run('tmux set -g allow-passthrough on');
-    // Copy selection to clipboard when mouse is released (pbcopy for macOS)
-    await run('tmux bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    await run('tmux bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    // Start ttyd connecting to the tmux session
-    logger.info('Starting builder terminal...');
-    const customIndexPath = resolve(config.templatesDir, 'ttyd-index.html');
-    const hasCustomIndex = existsSync(customIndexPath);
-    if (hasCustomIndex) {
-        logger.info('Using custom terminal with file click support');
-    }
-    const ttydProcess = spawnTtyd({
-        port,
-        sessionName,
-        cwd: worktreePath,
-        customIndexPath: hasCustomIndex ? customIndexPath : undefined,
-    });
-    if (!ttydProcess?.pid) {
-        fatal('Failed to start ttyd process for builder');
-    }
-    // Rename Claude session for better history tracking
-    renameClaudeSession(sessionName, `Builder ${builderId}`);
-    return { port, pid: ttydProcess.pid, sessionName };
-}
-/**
- * Start a shell session (no worktree, just tmux + ttyd)
- */
-async function startShellSession(config, shellId, baseCmd) {
-    const port = await findFreePort(config);
-    const sessionName = `shell-${shellId}`;
-    logger.info('Creating tmux session...');
-    // Shell mode: just launch Claude with no prompt
-    await run(`tmux new-session -d -s "${sessionName}" -x 200 -y 50 -c "${config.projectRoot}" "${baseCmd}"`);
-    await run(`tmux set-option -t "${sessionName}" status off`);
-    // Enable mouse scrolling in tmux
-    await run('tmux set -g mouse on');
-    await run('tmux set -g set-clipboard on');
-    await run('tmux set -g allow-passthrough on');
-    // Copy selection to clipboard when mouse is released (pbcopy for macOS)
-    await run('tmux bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    await run('tmux bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    // Start ttyd connecting to the tmux session
-    logger.info('Starting shell terminal...');
-    const customIndexPath = resolve(config.templatesDir, 'ttyd-index.html');
-    const hasCustomIndex = existsSync(customIndexPath);
-    const ttydProcess = spawnTtyd({
-        port,
-        sessionName,
-        cwd: config.projectRoot,
-        customIndexPath: hasCustomIndex ? customIndexPath : undefined,
-    });
-    if (!ttydProcess?.pid) {
-        fatal('Failed to start ttyd process for shell');
-    }
-    // Rename Claude session for better history tracking
-    renameClaudeSession(sessionName, `Shell ${shellId}`);
-    return { port, pid: ttydProcess.pid, sessionName };
-}
 // =============================================================================
 // Mode-specific spawn implementations
 // =============================================================================
@@ -362,56 +117,53 @@ async function spawnSpec(options, config) {
     // Check for corresponding plan file
     const planFile = resolve(config.codevDir, 'plans', `${specName}.md`);
     const hasPlan = existsSync(planFile);
-    logger.header(`Spawning Builder ${builderId} (spec)`);
+    logger.header(`${options.resume ? 'Resuming' : 'Spawning'} Builder ${builderId} (spec)`);
     logger.kv('Spec', specFile);
     logger.kv('Branch', branchName);
     logger.kv('Worktree', worktreePath);
     await ensureDirectories(config);
     await checkDependencies();
-    await createWorktree(config, branchName, worktreePath);
-    // Parse protocol from spec file metadata
-    const specContent = readFileSync(specFile, 'utf-8');
-    const protocolMatch = specContent.match(/\*\*Protocol\*\*:\s*(\w+)/i);
-    const protocol = protocolMatch ? protocolMatch[1].toUpperCase() : 'SPIDER';
-    const protocolPath = `codev/protocols/${protocol.toLowerCase()}/protocol.md`;
-    // Build the prompt
+    if (options.resume) {
+        validateResumeWorktree(worktreePath);
+    }
+    else {
+        await createWorktree(config, branchName, worktreePath);
+    }
+    const protocol = await resolveProtocol(options, config);
+    const protocolDef = loadProtocol(config, protocol);
+    const mode = resolveMode(options, protocolDef);
+    logger.kv('Protocol', protocol.toUpperCase());
+    logger.kv('Mode', mode.toUpperCase());
+    // Pre-initialize porch so the builder doesn't need to figure out project ID
+    if (!options.resume) {
+        const porchProjectName = specName.replace(new RegExp(`^${projectId}-`), '');
+        await initPorchInWorktree(worktreePath, protocol, projectId, porchProjectName);
+    }
     const specRelPath = `codev/specs/${specName}.md`;
     const planRelPath = `codev/plans/${specName}.md`;
-    let initialPrompt = `## Protocol
-Follow the ${protocol} protocol STRICTLY: ${protocolPath}
-Read and internalize the protocol before starting any work.
-
-## Task
-Implement the feature specified in ${specRelPath}.`;
-    if (hasPlan) {
-        initialPrompt += ` Follow the implementation plan in ${planRelPath}.`;
-    }
-    initialPrompt += `
-
-Start by reading the protocol, spec${hasPlan ? ', and plan' : ''}, then begin implementation.`;
-    const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.
-
-${initialPrompt}`;
-    // Load role
+    const templateContext = {
+        protocol_name: protocol.toUpperCase(), mode,
+        mode_soft: mode === 'soft', mode_strict: mode === 'strict',
+        project_id: projectId,
+        input_description: `the feature specified in ${specRelPath}`,
+        spec: { path: specRelPath, name: specName },
+    };
+    if (hasPlan)
+        templateContext.plan = { path: planRelPath, name: specName };
+    const initialPrompt = buildPromptFromTemplate(config, protocol, templateContext);
+    const resumeNotice = options.resume ? `\n${buildResumeNotice(projectId)}\n` : '';
+    const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n${resumeNotice}\n${initialPrompt}`;
     const role = options.noRole ? null : loadRolePrompt(config, 'builder');
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
-    const builder = {
-        id: builderId,
-        name: specName,
-        port,
-        pid,
-        status: 'spawning',
-        phase: 'init',
-        worktree: worktreePath,
-        branch: branchName,
-        tmuxSession: sessionName,
-        type: 'spec',
-    };
-    upsertBuilder(builder);
+    const { terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
+    upsertBuilder({
+        id: builderId, name: specName, status: 'implementing', phase: 'init',
+        worktree: worktreePath, branch: branchName, type: 'spec', terminalId,
+    });
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Mode', mode === 'strict' ? 'Strict (porch-driven)' : 'Soft (protocol-guided)');
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${terminalId}`);
 }
 /**
  * Spawn builder for an ad-hoc task
@@ -422,7 +174,7 @@ async function spawnTask(options, config) {
     const builderId = `task-${shortId}`;
     const branchName = `builder/task-${shortId}`;
     const worktreePath = resolve(config.buildersDir, builderId);
-    logger.header(`Spawning Builder ${builderId} (task)`);
+    logger.header(`${options.resume ? 'Resuming' : 'Spawning'} Builder ${builderId} (task)`);
     logger.kv('Task', taskText.substring(0, 60) + (taskText.length > 60 ? '...' : ''));
     logger.kv('Branch', branchName);
     logger.kv('Worktree', worktreePath);
@@ -431,34 +183,46 @@ async function spawnTask(options, config) {
     }
     await ensureDirectories(config);
     await checkDependencies();
-    await createWorktree(config, branchName, worktreePath);
-    // Build the prompt
-    let prompt = taskText;
+    if (options.resume) {
+        validateResumeWorktree(worktreePath);
+    }
+    else {
+        await createWorktree(config, branchName, worktreePath);
+    }
+    let taskDescription = taskText;
     if (options.files && options.files.length > 0) {
-        prompt += `\n\nRelevant files to consider:\n${options.files.map(f => `- ${f}`).join('\n')}`;
+        taskDescription += `\n\nRelevant files to consider:\n${options.files.map(f => `- ${f}`).join('\n')}`;
+    }
+    const hasExplicitProtocol = options.protocol || options.useProtocol;
+    const resumeNotice = options.resume ? `\n${buildResumeNotice(builderId)}\n` : '';
+    let builderPrompt;
+    if (hasExplicitProtocol) {
+        const protocol = await resolveProtocol(options, config);
+        const protocolDef = loadProtocol(config, protocol);
+        const mode = resolveMode(options, protocolDef);
+        const templateContext = {
+            protocol_name: protocol.toUpperCase(), mode,
+            mode_soft: mode === 'soft', mode_strict: mode === 'strict',
+            project_id: builderId, input_description: 'an ad-hoc task', task_text: taskDescription,
+        };
+        const prompt = buildPromptFromTemplate(config, protocol, templateContext);
+        builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n${resumeNotice}\n${prompt}`;
+    }
+    else {
+        builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n${resumeNotice}\n# Task\n\n${taskDescription}`;
     }
-    const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition. ${prompt}`;
-    // Load role
     const role = options.noRole ? null : loadRolePrompt(config, 'builder');
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
-    const builder = {
+    const { terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
+    upsertBuilder({
         id: builderId,
         name: `Task: ${taskText.substring(0, 30)}${taskText.length > 30 ? '...' : ''}`,
-        port,
-        pid,
-        status: 'spawning',
-        phase: 'init',
-        worktree: worktreePath,
-        branch: branchName,
-        tmuxSession: sessionName,
-        type: 'task',
-        taskText,
-    };
-    upsertBuilder(builder);
+        status: 'implementing', phase: 'init',
+        worktree: worktreePath, branch: branchName, type: 'task', taskText, terminalId,
+    });
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${terminalId}`);
 }
 /**
  * Spawn builder to run a protocol
@@ -470,36 +234,41 @@ async function spawnProtocol(options, config) {
     const builderId = `${protocolName}-${shortId}`;
     const branchName = `builder/${protocolName}-${shortId}`;
     const worktreePath = resolve(config.buildersDir, builderId);
-    logger.header(`Spawning Builder ${builderId} (protocol)`);
+    logger.header(`${options.resume ? 'Resuming' : 'Spawning'} Builder ${builderId} (protocol)`);
     logger.kv('Protocol', protocolName);
     logger.kv('Branch', branchName);
     logger.kv('Worktree', worktreePath);
     await ensureDirectories(config);
     await checkDependencies();
-    await createWorktree(config, branchName, worktreePath);
-    // Build the prompt
-    const prompt = `You are running the ${protocolName} protocol. Start by reading codev/protocols/${protocolName}/protocol.md and follow its instructions.`;
-    // Load protocol-specific role or fall back to builder role
+    if (options.resume) {
+        validateResumeWorktree(worktreePath);
+    }
+    else {
+        await createWorktree(config, branchName, worktreePath);
+    }
+    const protocolDef = loadProtocol(config, protocolName);
+    const mode = resolveMode(options, protocolDef);
+    logger.kv('Mode', mode.toUpperCase());
+    const templateContext = {
+        protocol_name: protocolName.toUpperCase(), mode,
+        mode_soft: mode === 'soft', mode_strict: mode === 'strict',
+        project_id: builderId,
+        input_description: `running the ${protocolName.toUpperCase()} protocol`,
+    };
+    const promptContent = buildPromptFromTemplate(config, protocolName, templateContext);
+    const resumeNotice = options.resume ? `\n${buildResumeNotice(builderId)}\n` : '';
+    const prompt = resumeNotice ? `${resumeNotice}\n${promptContent}` : promptContent;
     const role = options.noRole ? null : loadProtocolRole(config, protocolName);
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startBuilderSession(config, builderId, worktreePath, commands.builder, prompt, role?.content ?? null, role?.source ?? null);
-    const builder = {
-        id: builderId,
-        name: `Protocol: ${protocolName}`,
-        port,
-        pid,
-        status: 'spawning',
-        phase: 'init',
-        worktree: worktreePath,
-        branch: branchName,
-        tmuxSession: sessionName,
-        type: 'protocol',
-        protocolName,
-    };
-    upsertBuilder(builder);
+    const { terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, prompt, role?.content ?? null, role?.source ?? null);
+    upsertBuilder({
+        id: builderId, name: `Protocol: ${protocolName}`,
+        status: 'implementing', phase: 'init',
+        worktree: worktreePath, branch: branchName, type: 'protocol', protocolName, terminalId,
+    });
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${terminalId}`);
 }
 /**
  * Spawn a bare shell session (no worktree, no prompt)
@@ -511,25 +280,15 @@ async function spawnShell(options, config) {
     await ensureDirectories(config);
     await checkDependencies();
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startShellSession(config, shortId, commands.builder);
-    // Shell sessions are tracked as builders with type 'shell'
-    // They don't have worktrees or branches
-    const builder = {
-        id: shellId,
-        name: 'Shell session',
-        port,
-        pid,
-        status: 'spawning',
-        phase: 'interactive',
-        worktree: '',
-        branch: '',
-        tmuxSession: sessionName,
-        type: 'shell',
-    };
-    upsertBuilder(builder);
+    const { terminalId } = await startShellSession(config, shortId, commands.builder);
+    upsertBuilder({
+        id: shellId, name: 'Shell session',
+        status: 'implementing', phase: 'interactive',
+        worktree: '', branch: '', type: 'shell', terminalId,
+    });
     logger.blank();
     logger.success(`Shell ${shellId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${terminalId}`);
 }
 /**
  * Spawn a worktree session (has worktree/branch, but no initial prompt)
@@ -540,155 +299,42 @@ async function spawnWorktree(options, config) {
     const builderId = `worktree-${shortId}`;
     const branchName = `builder/worktree-${shortId}`;
     const worktreePath = resolve(config.buildersDir, builderId);
-    logger.header(`Spawning Worktree ${builderId}`);
+    logger.header(`${options.resume ? 'Resuming' : 'Spawning'} Worktree ${builderId}`);
     logger.kv('Branch', branchName);
     logger.kv('Worktree', worktreePath);
     await ensureDirectories(config);
     await checkDependencies();
-    await createWorktree(config, branchName, worktreePath);
-    // Load builder role
-    const role = options.noRole ? null : loadRolePrompt(config, 'builder');
-    const commands = getResolvedCommands();
-    // Worktree mode: launch Claude with no prompt, but in the worktree directory
-    const port = await findFreePort(config);
-    const sessionName = getSessionName(config, builderId);
-    logger.info('Creating tmux session...');
-    // Build launch script (with role if provided) to avoid shell escaping issues
-    const scriptPath = resolve(worktreePath, '.builder-start.sh');
-    let scriptContent;
-    if (role) {
-        const roleFile = resolve(worktreePath, '.builder-role.md');
-        // Inject the actual dashboard port into the role prompt
-        const roleWithPort = role.content.replace(/\{PORT\}/g, String(config.dashboardPort));
-        writeFileSync(roleFile, roleWithPort);
-        logger.info(`Loaded role (${role.source})`);
-        scriptContent = `#!/bin/bash
-exec ${commands.builder} --append-system-prompt "$(cat '${roleFile}')"
-`;
+    if (options.resume) {
+        validateResumeWorktree(worktreePath);
     }
     else {
-        scriptContent = `#!/bin/bash
-exec ${commands.builder}
-`;
+        await createWorktree(config, branchName, worktreePath);
     }
+    const role = options.noRole ? null : loadRolePrompt(config, 'builder');
+    const commands = getResolvedCommands();
+    logger.info('Creating terminal session...');
+    const scriptContent = buildWorktreeLaunchScript(worktreePath, commands.builder, role);
+    const scriptPath = resolve(worktreePath, '.builder-start.sh');
     writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
-    // Create tmux session running the launch script
-    await run(`tmux new-session -d -s "${sessionName}" -x 200 -y 50 -c "${worktreePath}" "${scriptPath}"`);
-    await run(`tmux set-option -t "${sessionName}" status off`);
-    // Enable mouse scrolling in tmux
-    await run('tmux set -g mouse on');
-    await run('tmux set -g set-clipboard on');
-    await run('tmux set -g allow-passthrough on');
-    // Copy selection to clipboard when mouse is released (pbcopy for macOS)
-    await run('tmux bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    await run('tmux bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"');
-    // Start ttyd connecting to the tmux session
-    logger.info('Starting worktree terminal...');
-    const customIndexPath = resolve(config.codevDir, 'templates', 'ttyd-index.html');
-    const hasCustomIndex = existsSync(customIndexPath);
-    if (hasCustomIndex) {
-        logger.info('Using custom terminal with file click support');
-    }
-    const ttydProcess = spawnTtyd({
-        port,
-        sessionName,
-        cwd: worktreePath,
-        customIndexPath: hasCustomIndex ? customIndexPath : undefined,
+    logger.info('Creating PTY terminal session for worktree...');
+    const { terminalId: worktreeTerminalId } = await createPtySession(config, '/bin/bash', [scriptPath], worktreePath, { projectPath: config.projectRoot, type: 'builder', roleId: builderId });
+    logger.info(`Worktree terminal session created: ${worktreeTerminalId}`);
+    upsertBuilder({
+        id: builderId, name: 'Worktree session',
+        status: 'implementing', phase: 'interactive',
+        worktree: worktreePath, branch: branchName, type: 'worktree',
+        terminalId: worktreeTerminalId,
     });
-    if (!ttydProcess?.pid) {
-        fatal('Failed to start ttyd process for worktree');
-    }
-    const builder = {
-        id: builderId,
-        name: 'Worktree session',
-        port,
-        pid: ttydProcess.pid,
-        status: 'spawning',
-        phase: 'interactive',
-        worktree: worktreePath,
-        branch: branchName,
-        tmuxSession: sessionName,
-        type: 'worktree',
-    };
-    upsertBuilder(builder);
     logger.blank();
     logger.success(`Worktree ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
-}
-/**
- * Generate a slug from an issue title (max 30 chars, lowercase, alphanumeric + hyphens)
- */
-function slugify(title) {
-    return title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
-        .replace(/-+/g, '-') // Collapse multiple hyphens
-        .replace(/^-|-$/g, '') // Trim leading/trailing hyphens
-        .slice(0, 30); // Max 30 chars
-}
-/**
- * Fetch a GitHub issue via gh CLI
- */
-async function fetchGitHubIssue(issueNumber) {
-    try {
-        const result = await run(`gh issue view ${issueNumber} --json title,body,state,comments`);
-        return JSON.parse(result.stdout);
-    }
-    catch (error) {
-        fatal(`Failed to fetch issue #${issueNumber}. Ensure 'gh' CLI is installed and authenticated.`);
-        throw error; // TypeScript doesn't know fatal() never returns
-    }
-}
-/**
- * Check for collision conditions before spawning bugfix
- */
-async function checkBugfixCollisions(issueNumber, worktreePath, issue, force) {
-    // 1. Check if worktree already exists
-    if (existsSync(worktreePath)) {
-        fatal(`Worktree already exists at ${worktreePath}\nRun: af cleanup --issue ${issueNumber}`);
-    }
-    // 2. Check for recent "On it" comments (< 24h old)
-    const onItComments = issue.comments.filter((c) => c.body.toLowerCase().includes('on it'));
-    if (onItComments.length > 0) {
-        const lastComment = onItComments[onItComments.length - 1];
-        const age = Date.now() - new Date(lastComment.createdAt).getTime();
-        const hoursAgo = Math.round(age / (1000 * 60 * 60));
-        if (hoursAgo < 24) {
-            if (!force) {
-                fatal(`Issue #${issueNumber} has "On it" comment from ${hoursAgo}h ago (by @${lastComment.author.login}).\nSomeone may already be working on this. Use --force to override.`);
-            }
-            logger.warn(`Warning: "On it" comment from ${hoursAgo}h ago - proceeding with --force`);
-        }
-        else {
-            logger.warn(`Warning: Stale "On it" comment (${hoursAgo}h ago). Proceeding.`);
-        }
-    }
-    // 3. Check for open PRs referencing this issue
-    try {
-        const prResult = await run(`gh pr list --search "in:body #${issueNumber}" --json number,title --limit 5`);
-        const openPRs = JSON.parse(prResult.stdout);
-        if (openPRs.length > 0) {
-            if (!force) {
-                const prList = openPRs.map((pr) => `  - PR #${pr.number}: ${pr.title}`).join('\n');
-                fatal(`Found ${openPRs.length} open PR(s) referencing issue #${issueNumber}:\n${prList}\nUse --force to proceed anyway.`);
-            }
-            logger.warn(`Warning: Found ${openPRs.length} open PR(s) referencing issue - proceeding with --force`);
-        }
-    }
-    catch {
-        // Non-fatal: continue if PR check fails
-    }
-    // 4. Warn if issue is already closed
-    if (issue.state === 'CLOSED') {
-        logger.warn(`Warning: Issue #${issueNumber} is already closed`);
-    }
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${worktreeTerminalId}`);
 }
 /**
  * Spawn builder for a GitHub issue (bugfix mode)
  */
 async function spawnBugfix(options, config) {
     const issueNumber = options.issue;
-    logger.header(`Spawning Bugfix Builder for Issue #${issueNumber}`);
+    logger.header(`${options.resume ? 'Resuming' : 'Spawning'} Bugfix Builder for Issue #${issueNumber}`);
     // Fetch issue from GitHub
     logger.info('Fetching issue from GitHub...');
     const issue = await fetchGitHubIssue(issueNumber);
@@ -696,70 +342,72 @@ async function spawnBugfix(options, config) {
     const builderId = `bugfix-${issueNumber}`;
     const branchName = `builder/bugfix-${issueNumber}-${slug}`;
     const worktreePath = resolve(config.buildersDir, builderId);
+    const protocol = await resolveProtocol(options, config);
+    const protocolDef = loadProtocol(config, protocol);
+    const mode = resolveMode(options, protocolDef);
     logger.kv('Title', issue.title);
     logger.kv('Branch', branchName);
     logger.kv('Worktree', worktreePath);
-    // Check for collisions
-    await checkBugfixCollisions(issueNumber, worktreePath, issue, !!options.force);
-    await ensureDirectories(config);
-    await checkDependencies();
-    await createWorktree(config, branchName, worktreePath);
-    // Comment on the issue (unless --no-comment)
-    if (!options.noComment) {
-        logger.info('Commenting on issue...');
-        try {
-            await run(`gh issue comment ${issueNumber} --body "On it! Working on a fix now."`);
+    logger.kv('Protocol', protocol.toUpperCase());
+    logger.kv('Mode', mode.toUpperCase());
+    // Execute pre-spawn hooks (skip in resume mode)
+    if (!options.resume) {
+        if (protocolDef?.hooks?.['pre-spawn']) {
+            await executePreSpawnHooks(protocolDef, {
+                issueNumber,
+                issue,
+                worktreePath,
+                force: options.force,
+                noComment: options.noComment,
+            });
         }
-        catch {
-            logger.warn('Warning: Failed to comment on issue (continuing anyway)');
+        else {
+            // Fallback: hardcoded behavior for backwards compatibility
+            await checkBugfixCollisions(issueNumber, worktreePath, issue, !!options.force);
+            if (!options.noComment) {
+                logger.info('Commenting on issue...');
+                try {
+                    await run(`gh issue comment ${issueNumber} --body "On it! Working on a fix now."`);
+                }
+                catch {
+                    logger.warn('Warning: Failed to comment on issue (continuing anyway)');
+                }
+            }
         }
     }
-    // Build the prompt with issue context
-    const prompt = `You are a Builder working on a BUGFIX task.
-
-## Protocol
-Follow the BUGFIX protocol: codev/protocols/bugfix/protocol.md
-
-## Issue #${issueNumber}
-**Title**: ${issue.title}
-
-**Description**:
-${issue.body || '(No description provided)'}
-
-## Your Mission
-1. Reproduce the bug
-2. Identify root cause
-3. Implement fix (< 300 LOC)
-4. Add regression test
-5. Run CMAP review (3-way parallel: Gemini, Codex, Claude)
-6. Create PR with "Fixes #${issueNumber}" in body
-
-If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
-  af send architect "Issue #${issueNumber} is more complex than expected. [Reason]. Recommend escalating to SPIDER/TICK."
-
-Start by reading the issue and reproducing the bug.`;
-    const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n\n${prompt}`;
-    // Load role
+    await ensureDirectories(config);
+    await checkDependencies();
+    if (options.resume) {
+        validateResumeWorktree(worktreePath);
+    }
+    else {
+        await createWorktree(config, branchName, worktreePath);
+        // Pre-initialize porch so the builder doesn't need to figure out project ID
+        await initPorchInWorktree(worktreePath, protocol, builderId, slug);
+    }
+    const templateContext = {
+        protocol_name: protocol.toUpperCase(), mode,
+        mode_soft: mode === 'soft', mode_strict: mode === 'strict',
+        project_id: builderId,
+        input_description: `a fix for GitHub Issue #${issueNumber}`,
+        issue: { number: issueNumber, title: issue.title, body: issue.body || '(No description provided)' },
+    };
+    const prompt = buildPromptFromTemplate(config, protocol, templateContext);
+    const resumeNotice = options.resume ? `\n${buildResumeNotice(builderId)}\n` : '';
+    const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n${resumeNotice}\n${prompt}`;
     const role = options.noRole ? null : loadRolePrompt(config, 'builder');
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
-    const builder = {
+    const { terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
+    upsertBuilder({
         id: builderId,
         name: `Bugfix #${issueNumber}: ${issue.title.substring(0, 40)}${issue.title.length > 40 ? '...' : ''}`,
-        port,
-        pid,
-        status: 'spawning',
-        phase: 'init',
-        worktree: worktreePath,
-        branch: branchName,
-        tmuxSession: sessionName,
-        type: 'bugfix',
-        issueNumber,
-    };
-    upsertBuilder(builder);
+        status: 'implementing', phase: 'init',
+        worktree: worktreePath, branch: branchName, type: 'bugfix', issueNumber, terminalId,
+    });
     logger.blank();
     logger.success(`Bugfix builder for issue #${issueNumber} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Mode', mode === 'strict' ? 'Strict (porch-driven)' : 'Soft (protocol-guided)');
+    logger.kv('Terminal', `ws://localhost:${DEFAULT_TOWER_PORT}/ws/terminal/${terminalId}`);
 }
 // =============================================================================
 // Main entry point
@@ -770,6 +418,25 @@ Start by reading the issue and reproducing the bug.`;
 export async function spawn(options) {
     validateSpawnOptions(options);
     const config = getConfig();
+    // Refuse to spawn if the main worktree has uncommitted changes.
+    // Builders work in git worktrees branched from HEAD — uncommitted changes
+    // (specs, plans, codev updates) won't be visible to the builder.
+    // Skip this check in resume mode — the worktree already exists with its own branch.
+    if (!options.force && !options.resume) {
+        try {
+            const { stdout } = await run('git status --porcelain', { cwd: config.projectRoot });
+            if (stdout.trim().length > 0) {
+                fatal('Uncommitted changes detected in main worktree.\n\n' +
+                    '  Builders branch from HEAD, so uncommitted files (specs, plans,\n' +
+                    '  codev updates) will NOT be visible to the builder.\n\n' +
+                    '  Please commit or stash your changes first, then retry.\n' +
+                    '  Use --force to skip this check.');
+            }
+        }
+        catch {
+            // Non-fatal — if git status fails, allow spawn to continue
+        }
+    }
     // Prune stale worktrees before spawning to prevent "can't find session" errors
     // This catches orphaned worktrees from crashes, manual kills, or incomplete cleanups
     try {
@@ -779,25 +446,14 @@ export async function spawn(options) {
         // Non-fatal - continue with spawn even if prune fails
     }
     const mode = getSpawnMode(options);
-    switch (mode) {
-        case 'spec':
-            await spawnSpec(options, config);
-            break;
-        case 'bugfix':
-            await spawnBugfix(options, config);
-            break;
-        case 'task':
-            await spawnTask(options, config);
-            break;
-        case 'protocol':
-            await spawnProtocol(options, config);
-            break;
-        case 'shell':
-            await spawnShell(options, config);
-            break;
-        case 'worktree':
-            await spawnWorktree(options, config);
-            break;
-    }
+    const handlers = {
+        spec: () => spawnSpec(options, config),
+        bugfix: () => spawnBugfix(options, config),
+        task: () => spawnTask(options, config),
+        protocol: () => spawnProtocol(options, config),
+        shell: () => spawnShell(options, config),
+        worktree: () => spawnWorktree(options, config),
+    };
+    await handlers[mode]();
 }
 //# sourceMappingURL=spawn.js.map