@cluesmith/codev 2.0.0-rc.6 → 2.0.0-rc.61

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

@@ -7,16 +7,119 @@
  * - protocol: --protocol    Spawn to run a protocol (cleanup, experiment, etc.)
  * - shell:    --shell       Bare Claude session (no prompt, no worktree)
  */
-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 { resolve, basename } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, symlinkSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 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 { run, commandExists, findAvailablePort } from '../utils/shell.js';
 import { loadState, upsertBuilder } from '../state.js';
 import { loadRolePrompt } from '../utils/roles.js';
+/**
+ * Simple Handlebars-like template renderer
+ * Supports: {{variable}}, {{#if condition}}...{{/if}}, {{object.property}}
+ */
+function renderTemplate(template, context) {
+    let result = template;
+    // Process {{#if condition}}...{{/if}} blocks
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const ifMatch = result.match(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/);
+        if (!ifMatch)
+            break;
+        const [fullMatch, condition, content] = ifMatch;
+        const value = getNestedValue(context, condition);
+        result = result.replace(fullMatch, value ? content : '');
+    }
+    // Process {{variable}} and {{object.property}} substitutions
+    result = result.replace(/\{\{(\w+(?:\.\w+)*)\}\}/g, (_, path) => {
+        const value = getNestedValue(context, path);
+        if (value === undefined || value === null)
+            return '';
+        return String(value);
+    });
+    // Clean up any double newlines left from removed sections
+    result = result.replace(/\n{3,}/g, '\n\n');
+    return result.trim();
+}
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Load builder-prompt.md template for a protocol
+ */
+function loadBuilderPromptTemplate(config, protocolName) {
+    const templatePath = resolve(config.codevDir, 'protocols', protocolName, 'builder-prompt.md');
+    if (existsSync(templatePath)) {
+        return readFileSync(templatePath, 'utf-8');
+    }
+    return null;
+}
+/**
+ * Build the prompt using protocol template or fallback to inline prompt
+ */
+function buildPromptFromTemplate(config, protocolName, context) {
+    const template = loadBuilderPromptTemplate(config, protocolName);
+    if (template) {
+        logger.info(`Using template: protocols/${protocolName}/builder-prompt.md`);
+        return renderTemplate(template, context);
+    }
+    // Fallback: no template found, return a basic prompt
+    logger.debug(`No template found for ${protocolName}, using inline prompt`);
+    return buildFallbackPrompt(protocolName, context);
+}
+/**
+ * Build a fallback prompt when no template exists
+ */
+function buildFallbackPrompt(protocolName, context) {
+    const modeInstructions = context.mode === 'strict'
+        ? `## Mode: STRICT
+Porch orchestrates your work. Run: \`porch next ${context.project_id || ''}\` to get your next tasks.`
+        : `## Mode: SOFT
+You follow the protocol yourself. The architect monitors your work and verifies compliance.`;
+    let prompt = `# ${protocolName.toUpperCase()} Builder (${context.mode} mode)
+
+You are implementing ${context.input_description}.
+
+${modeInstructions}
+
+## Protocol
+Follow the ${protocolName.toUpperCase()} protocol: \`codev/protocols/${protocolName}/protocol.md\`
+Read and internalize the protocol before starting any work.
+`;
+    if (context.spec) {
+        prompt += `\n## Spec\nRead the specification at: \`${context.spec.path}\`\n`;
+    }
+    if (context.plan) {
+        prompt += `\n## Plan\nFollow the implementation plan at: \`${context.plan.path}\`\n`;
+    }
+    if (context.issue) {
+        prompt += `\n## Issue #${context.issue.number}
+**Title**: ${context.issue.title}
+
+**Description**:
+${context.issue.body || '(No description provided)'}
+`;
+    }
+    if (context.task_text) {
+        prompt += `\n## Task\n${context.task_text}\n`;
+    }
+    return prompt;
+}
+// =============================================================================
+// 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
@@ -45,64 +148,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,23 +176,35 @@ 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
@@ -188,6 +266,136 @@ function validateProtocol(config, protocolName) {
         fatal(`Protocol ${protocolName} exists but has no protocol.md file`);
     }
 }
+/**
+ * Load and parse a protocol.json file
+ */
+function loadProtocol(config, protocolName) {
+    const protocolJsonPath = resolve(config.codevDir, 'protocols', protocolName, 'protocol.json');
+    if (!existsSync(protocolJsonPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(protocolJsonPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        logger.warn(`Warning: Failed to parse ${protocolJsonPath}`);
+        return null;
+    }
+}
+/**
+ * Resolve which protocol to use based on precedence:
+ * 1. Explicit --protocol flag when used as override (with other input modes)
+ * 2. Explicit --use-protocol flag (backwards compatibility)
+ * 3. Spec file **Protocol**: header (for --project mode)
+ * 4. Hardcoded defaults (spir for specs, bugfix for issues)
+ */
+async function resolveProtocol(options, config) {
+    // Count input modes to determine if --protocol is being used as override
+    const inputModes = [
+        options.project,
+        options.task,
+        options.shell,
+        options.worktree,
+        options.issue,
+    ].filter(Boolean);
+    const protocolAsOverride = options.protocol && inputModes.length > 0;
+    // 1. --protocol as override always wins when combined with other input modes
+    if (protocolAsOverride) {
+        validateProtocol(config, options.protocol);
+        return options.protocol.toLowerCase();
+    }
+    // 2. Explicit --use-protocol override (backwards compatibility)
+    if (options.useProtocol) {
+        validateProtocol(config, options.useProtocol);
+        return options.useProtocol.toLowerCase();
+    }
+    // 3. For spec mode, check spec file header (preserves existing behavior)
+    if (options.project) {
+        const specFile = await findSpecFile(config.codevDir, options.project);
+        if (specFile) {
+            const specContent = readFileSync(specFile, 'utf-8');
+            const match = specContent.match(/\*\*Protocol\*\*:\s*(\w+)/i);
+            if (match) {
+                const protocolFromSpec = match[1].toLowerCase();
+                // Validate the protocol exists
+                try {
+                    validateProtocol(config, protocolFromSpec);
+                    return protocolFromSpec;
+                }
+                catch {
+                    // If protocol from spec doesn't exist, fall through to defaults
+                    logger.warn(`Warning: Protocol "${match[1]}" from spec not found, using default`);
+                }
+            }
+        }
+    }
+    // 4. Hardcoded defaults based on input type
+    if (options.project)
+        return 'spir';
+    if (options.issue)
+        return 'bugfix';
+    // --protocol alone (not as override) uses the protocol name itself
+    if (options.protocol)
+        return options.protocol.toLowerCase();
+    if (options.task)
+        return 'spir';
+    return 'spir'; // Final fallback
+}
+// Note: GitHubIssue interface is defined later in the file
+/**
+ * Resolve the builder mode (strict vs soft)
+ * Precedence:
+ * 1. Explicit --strict or --soft flags (always win)
+ * 2. Protocol defaults from protocol.json
+ * 3. Input type defaults (spec = strict, all others = soft)
+ */
+function resolveMode(options, protocol) {
+    // 1. Explicit flags always win
+    if (options.strict && options.soft) {
+        fatal('--strict and --soft are mutually exclusive');
+    }
+    if (options.strict) {
+        return 'strict';
+    }
+    if (options.soft) {
+        return 'soft';
+    }
+    // 2. Protocol defaults from protocol.json
+    if (protocol?.defaults?.mode) {
+        return protocol.defaults.mode;
+    }
+    // 3. Input type defaults: only spec mode defaults to strict
+    if (options.project) {
+        return 'strict';
+    }
+    // All other modes default to soft
+    return 'soft';
+}
+/**
+ * Execute pre-spawn hooks defined in protocol.json
+ * Hooks are data-driven but reuse existing implementation logic
+ */
+async function executePreSpawnHooks(protocol, context) {
+    if (!protocol?.hooks?.['pre-spawn'])
+        return;
+    const hooks = protocol.hooks['pre-spawn'];
+    // collision-check: reuses existing checkBugfixCollisions() logic
+    if (hooks['collision-check'] && context.issueNumber && context.issue && context.worktreePath) {
+        await checkBugfixCollisions(context.issueNumber, context.worktreePath, context.issue, !!context.force);
+    }
+    // comment-on-issue: posts comment to GitHub issue
+    if (hooks['comment-on-issue'] && context.issueNumber && !context.noComment) {
+        const message = hooks['comment-on-issue'];
+        logger.info('Commenting on issue...');
+        try {
+            await run(`gh issue comment ${context.issueNumber} --body "${message}"`);
+        }
+        catch {
+            logger.warn('Warning: Failed to comment on issue (continuing anyway)');
+        }
+    }
+}
 /**
  * Check for required dependencies
  */
@@ -195,9 +403,6 @@ 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
@@ -206,7 +411,7 @@ async function findFreePort(config) {
     const state = loadState();
     const usedPorts = new Set();
     for (const b of state.builders || []) {
-        if (b.port)
+        if (b.port > 0)
             usedPorts.add(b.port);
     }
     let port = config.builderPortRange[0];
@@ -248,7 +453,34 @@ async function createWorktree(config, branchName, worktreePath) {
     }
 }
 /**
- * Start tmux session and ttyd for a builder
+ * Create a terminal session via the Tower REST API.
+ * The Tower server must be running (port 4100).
+ */
+async function createPtySession(config, command, args, cwd, registration) {
+    const towerPort = 4100;
+    const body = { command, args, cwd, cols: 200, rows: 50 };
+    if (registration) {
+        body.projectPath = registration.projectPath;
+        body.type = registration.type;
+        body.roleId = registration.roleId;
+        if (registration.tmuxSession) {
+            body.tmuxSession = registration.tmuxSession;
+        }
+    }
+    const response = await fetch(`http://localhost:${towerPort}/api/terminals`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to create PTY session: ${response.status} ${text}`);
+    }
+    const result = await response.json();
+    return { terminalId: result.id, tmuxSession: result.tmuxSession ?? null };
+}
+/**
+ * Start a terminal session for a builder
  */
 async function startBuilderSession(config, builderId, worktreePath, baseCmd, prompt, roleContent, roleSource) {
     const port = await findFreePort(config);
@@ -268,79 +500,47 @@ async function startBuilderSession(config, builderId, worktreePath, baseCmd, pro
         writeFileSync(roleFile, roleWithPort);
         logger.info(`Loaded role (${roleSource})`);
         scriptContent = `#!/bin/bash
-exec ${baseCmd} --append-system-prompt "$(cat '${roleFile}')" "$(cat '${promptFile}')"
+cd "${worktreePath}"
+while true; do
+  ${baseCmd} --append-system-prompt "$(cat '${roleFile}')" "$(cat '${promptFile}')"
+  echo ""
+  echo "Claude exited. Restarting in 2 seconds... (Ctrl+C to quit)"
+  sleep 2
+done
 `;
     }
     else {
         scriptContent = `#!/bin/bash
-exec ${baseCmd} "$(cat '${promptFile}')"
+cd "${worktreePath}"
+while true; do
+  ${baseCmd} "$(cat '${promptFile}')"
+  echo ""
+  echo "Claude exited. Restarting in 2 seconds... (Ctrl+C to quit)"
+  sleep 2
+done
 `;
     }
     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 };
+    // Create PTY session via REST API (node-pty backend, tmux for persistence)
+    logger.info('Creating PTY terminal session...');
+    const { terminalId, tmuxSession: actualTmux } = await createPtySession(config, '/bin/bash', [scriptPath], worktreePath, { projectPath: config.projectRoot, type: 'builder', roleId: builderId, tmuxSession: sessionName });
+    logger.info(`Terminal session created: ${terminalId}${actualTmux ? ` (tmux: ${actualTmux})` : ''}`);
+    // Use the actual tmux session name from Tower (null if tmux was unavailable/failed)
+    return { port: 0, pid: 0, sessionName: actualTmux || sessionName, terminalId };
 }
 /**
- * Start a shell session (no worktree, just tmux + ttyd)
+ * Start a shell session (no worktree, just node-pty)
  */
 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 };
+    const tmuxName = `shell-${getProjectName(config)}-${shellId}`;
+    const sessionName = tmuxName;
+    // Create PTY session via REST API (node-pty backend, tmux for persistence)
+    logger.info('Creating PTY terminal session for shell...');
+    const { terminalId, tmuxSession: actualTmux } = await createPtySession(config, '/bin/bash', ['-c', baseCmd], config.projectRoot, { projectPath: config.projectRoot, type: 'shell', roleId: shellId, tmuxSession: tmuxName });
+    logger.info(`Shell terminal session created: ${terminalId}${actualTmux ? ` (tmux: ${actualTmux})` : ''}`);
+    return { port: 0, pid: 0, sessionName: actualTmux || sessionName, terminalId };
 }
 // =============================================================================
 // Mode-specific spawn implementations
@@ -369,49 +569,61 @@ async function spawnSpec(options, config) {
     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
+    // Resolve protocol using precedence: --use-protocol > spec header > default
+    const protocol = await resolveProtocol(options, config);
+    const protocolPath = `codev/protocols/${protocol}/protocol.md`;
+    // Load protocol definition for potential hooks/config
+    const protocolDef = loadProtocol(config, protocol);
+    // Resolve mode: --soft flag > protocol defaults > input type defaults
+    const mode = resolveMode(options, protocolDef);
+    logger.kv('Protocol', protocol.toUpperCase());
+    logger.kv('Mode', mode.toUpperCase());
+    // Build the prompt using template
     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}.`;
+    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) {
-        initialPrompt += ` Follow the implementation plan in ${planRelPath}.`;
+        templateContext.plan = { path: planRelPath, name: specName };
     }
-    initialPrompt += `
-
-Start by reading the protocol, spec${hasPlan ? ', and plan' : ''}, then begin implementation.`;
+    const initialPrompt = buildPromptFromTemplate(config, protocol, templateContext);
     const builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.
 
 ${initialPrompt}`;
     // 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 { port, pid, sessionName, terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
     const builder = {
         id: builderId,
         name: specName,
         port,
         pid,
-        status: 'spawning',
+        status: 'implementing',
         phase: 'init',
         worktree: worktreePath,
         branch: branchName,
         tmuxSession: sessionName,
         type: 'spec',
+        terminalId,
     };
     upsertBuilder(builder);
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Mode', mode === 'strict' ? 'Strict (porch-driven)' : 'Soft (protocol-guided)');
+    if (terminalId) {
+        logger.kv('Terminal', `ws://localhost:${config.dashboardPort}/ws/terminal/${terminalId}`);
+    }
+    else {
+        logger.kv('Terminal', `http://localhost:${port}`);
+    }
 }
 /**
  * Spawn builder for an ad-hoc task
@@ -432,33 +644,58 @@ async function spawnTask(options, config) {
     await ensureDirectories(config);
     await checkDependencies();
     await createWorktree(config, branchName, worktreePath);
-    // Build the prompt
-    let prompt = taskText;
+    // Build the prompt — only include protocol if explicitly requested
+    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;
+    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\n${prompt}`;
+    }
+    else {
+        builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.
+
+# Task
+
+${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 { port, pid, sessionName, terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
     const builder = {
         id: builderId,
         name: `Task: ${taskText.substring(0, 30)}${taskText.length > 30 ? '...' : ''}`,
         port,
         pid,
-        status: 'spawning',
+        status: 'implementing',
         phase: 'init',
         worktree: worktreePath,
         branch: branchName,
         tmuxSession: sessionName,
         type: 'task',
         taskText,
+        terminalId,
     };
     upsertBuilder(builder);
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', terminalId ? `node-pty:${terminalId}` : `http://localhost:${port}`);
 }
 /**
  * Spawn builder to run a protocol
@@ -477,29 +714,42 @@ async function spawnProtocol(options, config) {
     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 definition and resolve mode
+    const protocolDef = loadProtocol(config, protocolName);
+    const mode = resolveMode(options, protocolDef);
+    logger.kv('Mode', mode.toUpperCase());
+    // Build the prompt using template
+    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 prompt = buildPromptFromTemplate(config, protocolName, templateContext);
     // Load protocol-specific role or fall back to builder role
     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 { port, pid, sessionName, terminalId } = 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',
+        status: 'implementing',
         phase: 'init',
         worktree: worktreePath,
         branch: branchName,
         tmuxSession: sessionName,
         type: 'protocol',
         protocolName,
+        terminalId,
     };
     upsertBuilder(builder);
     logger.blank();
     logger.success(`Builder ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', terminalId ? `node-pty:${terminalId}` : `http://localhost:${port}`);
 }
 /**
  * Spawn a bare shell session (no worktree, no prompt)
@@ -511,7 +761,7 @@ async function spawnShell(options, config) {
     await ensureDirectories(config);
     await checkDependencies();
     const commands = getResolvedCommands();
-    const { port, pid, sessionName } = await startShellSession(config, shortId, commands.builder);
+    const { port, pid, sessionName, terminalId } = await startShellSession(config, shortId, commands.builder);
     // Shell sessions are tracked as builders with type 'shell'
     // They don't have worktrees or branches
     const builder = {
@@ -519,17 +769,18 @@ async function spawnShell(options, config) {
         name: 'Shell session',
         port,
         pid,
-        status: 'spawning',
+        status: 'implementing',
         phase: 'interactive',
         worktree: '',
         branch: '',
         tmuxSession: sessionName,
         type: 'shell',
+        terminalId,
     };
     upsertBuilder(builder);
     logger.blank();
     logger.success(`Shell ${shellId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', terminalId ? `node-pty:${terminalId}` : `http://localhost:${port}`);
 }
 /**
  * Spawn a worktree session (has worktree/branch, but no initial prompt)
@@ -563,57 +814,48 @@ async function spawnWorktree(options, config) {
         writeFileSync(roleFile, roleWithPort);
         logger.info(`Loaded role (${role.source})`);
         scriptContent = `#!/bin/bash
-exec ${commands.builder} --append-system-prompt "$(cat '${roleFile}')"
+cd "${worktreePath}"
+while true; do
+  ${commands.builder} --append-system-prompt "$(cat '${roleFile}')"
+  echo ""
+  echo "Claude exited. Restarting in 2 seconds... (Ctrl+C to quit)"
+  sleep 2
+done
 `;
     }
     else {
         scriptContent = `#!/bin/bash
-exec ${commands.builder}
+cd "${worktreePath}"
+while true; do
+  ${commands.builder}
+  echo ""
+  echo "Claude exited. Restarting in 2 seconds... (Ctrl+C to quit)"
+  sleep 2
+done
 `;
     }
     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,
-    });
-    if (!ttydProcess?.pid) {
-        fatal('Failed to start ttyd process for worktree');
-    }
+    // Create PTY session via REST API (node-pty backend, tmux for persistence)
+    logger.info('Creating PTY terminal session for worktree...');
+    const { terminalId: worktreeTerminalId, tmuxSession: actualTmux } = await createPtySession(config, '/bin/bash', [scriptPath], worktreePath, { projectPath: config.projectRoot, type: 'builder', roleId: builderId, tmuxSession: sessionName });
+    logger.info(`Worktree terminal session created: ${worktreeTerminalId}${actualTmux ? ` (tmux: ${actualTmux})` : ''}`);
     const builder = {
         id: builderId,
         name: 'Worktree session',
-        port,
-        pid: ttydProcess.pid,
-        status: 'spawning',
+        port: 0,
+        pid: 0,
+        status: 'implementing',
         phase: 'interactive',
         worktree: worktreePath,
         branch: branchName,
-        tmuxSession: sessionName,
+        tmuxSession: actualTmux || sessionName,
         type: 'worktree',
+        terminalId: worktreeTerminalId,
     };
     upsertBuilder(builder);
     logger.blank();
     logger.success(`Worktree ${builderId} spawned!`);
-    logger.kv('Terminal', `http://localhost:${port}`);
+    logger.kv('Terminal', `node-pty:${worktreeTerminalId}`);
 }
 /**
  * Generate a slug from an issue title (max 30 chars, lowercase, alphanumeric + hyphens)
@@ -696,70 +938,87 @@ async function spawnBugfix(options, config) {
     const builderId = `bugfix-${issueNumber}`;
     const branchName = `builder/bugfix-${issueNumber}-${slug}`;
     const worktreePath = resolve(config.buildersDir, builderId);
+    // Resolve protocol (allows --use-protocol override)
+    const protocol = await resolveProtocol(options, config);
+    const protocolDef = loadProtocol(config, protocol);
+    // Resolve mode: --soft flag > protocol defaults > input type defaults (bugfix defaults to soft)
+    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);
+    logger.kv('Protocol', protocol.toUpperCase());
+    logger.kv('Mode', mode.toUpperCase());
+    // Execute pre-spawn hooks from protocol.json (collision check, issue comment)
+    // If protocol has hooks defined, use them; otherwise fall back to hardcoded behavior
+    if (protocolDef?.hooks?.['pre-spawn']) {
+        await executePreSpawnHooks(protocolDef, {
+            issueNumber,
+            issue,
+            worktreePath,
+            force: options.force,
+            noComment: options.noComment,
+        });
+    }
+    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)');
+            }
+        }
+    }
     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."`);
-        }
-        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.`;
+    // Build the prompt using template
+    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 builderPrompt = `You are a Builder. Read codev/roles/builder.md for your full role definition.\n\n${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 { port, pid, sessionName, terminalId } = await startBuilderSession(config, builderId, worktreePath, commands.builder, builderPrompt, role?.content ?? null, role?.source ?? null);
     const builder = {
         id: builderId,
         name: `Bugfix #${issueNumber}: ${issue.title.substring(0, 40)}${issue.title.length > 40 ? '...' : ''}`,
         port,
         pid,
-        status: 'spawning',
+        status: 'implementing',
         phase: 'init',
         worktree: worktreePath,
         branch: branchName,
         tmuxSession: sessionName,
         type: 'bugfix',
         issueNumber,
+        terminalId,
     };
     upsertBuilder(builder);
     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)');
+    if (terminalId) {
+        logger.kv('Terminal', `ws://localhost:${config.dashboardPort}/ws/terminal/${terminalId}`);
+    }
+    else {
+        logger.kv('Terminal', `http://localhost:${port}`);
+    }
 }
 // =============================================================================
 // Main entry point
@@ -770,6 +1029,24 @@ 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.
+    if (!options.force) {
+        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 {