agent-relay 1.1.0 → 1.2.0

package/dist/wrapper/tmux-wrapper.js

@@ -20,6 +20,11 @@ import { InboxManager } from './inbox.js';
 import { SqliteStorageAdapter } from '../storage/sqlite-adapter.js';
 import { getProjectPaths } from '../utils/project-namespace.js';
 import { getTmuxPath } from '../utils/tmux-resolver.js';
+import { findAgentConfig } from '../utils/agent-config.js';
+import { getTrajectoryIntegration, detectPhaseFromContent, detectToolCalls, detectErrors, getCompactTrailInstructions, getTrailEnvVars, } from '../trajectory/integration.js';
+import { escapeForShell } from '../bridge/utils.js';
+import { getContinuityManager, parseContinuityCommand, hasContinuityCommand, } from '../continuity/index.js';
+import { stripAnsi, sleep, getDefaultRelayPrefix, createInjectionMetrics, buildInjectionString, injectWithRetry as sharedInjectWithRetry, INJECTION_CONSTANTS, CLI_QUIRKS, } from './shared.js';
 const execAsync = promisify(exec);
 const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // Constants for cursor stability detection in waitForClearInput
@@ -34,10 +39,10 @@ const RELAY_LOG_TRUNCATE_LENGTH = 50;
 /**
  * Get the default relay prefix for a given CLI type.
  * All agents now use '->relay:' as the unified prefix.
+ * @deprecated Use getDefaultRelayPrefix() from shared.js instead
  */
 export function getDefaultPrefix(_cliType) {
-    // Unified prefix for all agent types
-    return '->relay:';
+    return getDefaultRelayPrefix();
 }
 export class TmuxWrapper {
     config;
@@ -67,15 +72,25 @@ export class TmuxWrapper {
     lastSummaryHash = ''; // Dedup summary saves
     lastSummaryRawContent = ''; // Dedup invalid JSON error logging
     sessionEndProcessed = false; // Track if we've already processed session end
+    sessionEndData; // Store SESSION_END data for handoff
     pendingRelayCommands = [];
     queuedMessageHashes = new Set(); // For offline queue dedup
     MAX_PENDING_RELAY_COMMANDS = 50;
     processedSpawnCommands = new Set(); // Dedup spawn commands
     processedReleaseCommands = new Set(); // Dedup release commands
+    pendingFencedSpawn = null; // Track multi-line spawn task
     receivedMessageIdSet = new Set();
     receivedMessageIdOrder = [];
     MAX_RECEIVED_MESSAGES = 2000;
     tmuxPath; // Resolved path to tmux binary (system or bundled)
+    trajectory; // Trajectory tracking via trail
+    lastDetectedPhase; // Track last auto-detected PDERO phase
+    seenToolCalls = new Set(); // Dedup tool call trajectory events
+    seenErrors = new Set(); // Dedup error trajectory events
+    continuity; // Session continuity management
+    processedContinuityCommands = new Set(); // Dedup continuity commands
+    agentId; // Unique agent ID for resume functionality
+    injectionMetrics = createInjectionMetrics(); // Track injection reliability
     constructor(config) {
         this.config = {
             cols: process.stdout.columns || 120,
@@ -109,6 +124,9 @@ export class TmuxWrapper {
         else if (cmdLower.includes('droid')) {
             this.cliType = 'droid';
         }
+        else if (cmdLower.includes('opencode')) {
+            this.cliType = 'opencode';
+        }
         else {
             this.cliType = 'other';
         }
@@ -118,13 +136,22 @@ export class TmuxWrapper {
         this.sessionName = `relay-${config.name}`;
         // Resolve tmux path early so we fail fast if tmux isn't available
         this.tmuxPath = getTmuxPath();
+        // Auto-detect agent role from .claude/agents/ or .openagents/ if task not provided
+        let detectedTask = this.config.task;
+        if (!detectedTask) {
+            const agentConfig = findAgentConfig(config.name, this.config.cwd);
+            if (agentConfig?.description) {
+                detectedTask = agentConfig.description;
+                this.logStderr(`Auto-detected role: ${detectedTask.substring(0, 60)}...`, true);
+            }
+        }
         this.client = new RelayClient({
             agentName: config.name,
             socketPath: config.socketPath,
             cli: this.cliType,
             program: this.config.program,
             model: this.config.model,
-            task: this.config.task,
+            task: detectedTask,
             workingDirectory: this.config.cwd ?? process.cwd(),
             quiet: true, // Keep stdout clean; we log to stderr via wrapper
         });
@@ -145,6 +172,10 @@ export class TmuxWrapper {
             this.storage = undefined;
             return false;
         });
+        // Initialize trajectory tracking via trail CLI
+        this.trajectory = getTrajectoryIntegration(projectPaths.projectId, config.name);
+        // Initialize continuity manager for session persistence
+        this.continuity = getContinuityManager({ defaultCli: this.cliType });
         // Handle incoming messages from relay
         this.client.onMessage = (from, payload, messageId, meta, originalTo) => {
             this.handleIncomingMessage(from, payload, messageId, meta, originalTo);
@@ -182,6 +213,46 @@ export class TmuxWrapper {
         // Prefix with newline to avoid corrupting tmux status line
         process.stderr.write(`\r[relay:${this.config.name}] ${msg}\n`);
     }
+    /**
+     * Detect PDERO phase from output content and auto-transition if needed.
+     * Also detects tool calls and errors, recording them to the trajectory.
+     */
+    detectAndTransitionPhase(content) {
+        if (!this.trajectory)
+            return;
+        // Detect phase transitions
+        const detectedPhase = detectPhaseFromContent(content);
+        if (detectedPhase && detectedPhase !== this.lastDetectedPhase) {
+            const currentPhase = this.trajectory.getPhase();
+            if (detectedPhase !== currentPhase) {
+                this.trajectory.transition(detectedPhase, 'Auto-detected from output');
+                this.lastDetectedPhase = detectedPhase;
+                this.logStderr(`Phase transition: ${currentPhase || 'none'} → ${detectedPhase}`);
+            }
+        }
+        // Detect and record tool calls
+        // Note: We deduplicate by tool+status to record each unique tool type once per session
+        // (e.g., "Read" started, "Read" completed). This provides a summary of tools used
+        // without flooding the trajectory with every individual invocation.
+        const tools = detectToolCalls(content);
+        for (const tool of tools) {
+            const key = `${tool.tool}:${tool.status || 'started'}`;
+            if (!this.seenToolCalls.has(key)) {
+                this.seenToolCalls.add(key);
+                const statusLabel = tool.status === 'completed' ? ' (completed)' : '';
+                this.trajectory.event(`Tool: ${tool.tool}${statusLabel}`, 'tool_call');
+            }
+        }
+        // Detect and record errors
+        const errors = detectErrors(content);
+        for (const error of errors) {
+            if (!this.seenErrors.has(error.message)) {
+                this.seenErrors.add(error.message);
+                const prefix = error.type === 'warning' ? 'Warning' : 'Error';
+                this.trajectory.event(`${prefix}: ${error.message}`, 'error');
+            }
+        }
+    }
     /**
      * Build the full command with proper quoting
      * Args containing spaces need to be quoted
@@ -286,20 +357,24 @@ export class TmuxWrapper {
                     // Ignore on older tmux versions lacking these key tables
                 }
             }
-            // Set environment variables
+            // Set environment variables including trail/trajectory vars
+            const projectPaths = getProjectPaths();
+            const trailEnvVars = getTrailEnvVars(projectPaths.projectId, this.config.name, projectPaths.dataDir);
             for (const [key, value] of Object.entries({
                 ...this.config.env,
+                ...trailEnvVars,
                 AGENT_RELAY_NAME: this.config.name,
                 TERM: 'xterm-256color',
             })) {
-                const escaped = value.replace(/"/g, '\\"');
+                // Use proper shell escaping to prevent command injection via env var values
+                const escaped = escapeForShell(value);
                 execSync(`"${this.tmuxPath}" setenv -t ${this.sessionName} ${key} "${escaped}"`);
             }
             // Wait for shell to be ready (look for prompt)
             await this.waitForShellReady();
             // Send the command to run
             await this.sendKeysLiteral(fullCommand);
-            await this.sleep(100);
+            await sleep(100);
             await this.sendKeys('Enter');
         }
         catch (err) {
@@ -310,6 +385,10 @@ export class TmuxWrapper {
         this.running = true;
         this.lastActivityTime = Date.now();
         this.activityState = 'active';
+        // Initialize trajectory tracking (auto-start if task provided)
+        this.initializeTrajectory();
+        // Initialize continuity and get/create agentId
+        this.initializeAgentId();
         // Inject instructions for the agent (after a delay to let CLI initialize)
         setTimeout(() => this.injectInstructions(), 3000);
         // Start background polling (silent - no stdout writes)
@@ -319,28 +398,126 @@ export class TmuxWrapper {
         this.attachToSession();
     }
     /**
-     * Inject usage instructions for the agent
+     * Initialize trajectory tracking
+     * Auto-starts a trajectory if task is provided in config
+     */
+    async initializeTrajectory() {
+        if (!this.trajectory)
+            return;
+        // Auto-start trajectory if task is provided
+        if (this.config.task) {
+            const success = await this.trajectory.initialize(this.config.task);
+            if (success) {
+                this.logStderr(`Trajectory started for task: ${this.config.task}`);
+            }
+        }
+        else {
+            // Just initialize without starting a trajectory
+            await this.trajectory.initialize();
+        }
+    }
+    /**
+     * Initialize agent ID for continuity/resume functionality
+     */
+    async initializeAgentId() {
+        if (!this.continuity)
+            return;
+        try {
+            let ledger;
+            // If resuming from a previous agent ID, try to find that ledger
+            if (this.config.resumeAgentId) {
+                ledger = await this.continuity.findLedgerByAgentId(this.config.resumeAgentId);
+                if (ledger) {
+                    this.logStderr(`Resuming agent ID: ${ledger.agentId} (from previous session)`);
+                }
+                else {
+                    this.logStderr(`Resume agent ID ${this.config.resumeAgentId} not found, creating new`, true);
+                }
+            }
+            // If not resuming or resume ID not found, get or create ledger
+            if (!ledger) {
+                ledger = await this.continuity.getOrCreateLedger(this.config.name, this.cliType);
+                this.logStderr(`Agent ID: ${ledger.agentId} (use this to resume if agent dies)`);
+            }
+            this.agentId = ledger.agentId;
+        }
+        catch (err) {
+            this.logStderr(`Failed to initialize agent ID: ${err.message}`, true);
+        }
+    }
+    /**
+     * Get the current agent ID
+     */
+    getAgentId() {
+        return this.agentId;
+    }
+    /**
+     * Inject usage instructions for the agent including persistence protocol
      */
     async injectInstructions() {
         if (!this.running)
             return;
         // Use escaped prefix (\->relay:) in examples to prevent parser from treating them as real commands
         const escapedPrefix = '\\' + this.relayPrefix;
-        const instructions = [
+        // Build instructions including relay and trail
+        const relayInstructions = [
             `[Agent Relay] You are "${this.config.name}" - connected for real-time messaging.`,
             `SEND: ${escapedPrefix}AgentName message`,
             `MULTI-LINE: ${escapedPrefix}AgentName <<<(newline)content(newline)>>> - ALWAYS end with >>> on its own line!`,
-            `RECEIVE: Messages appear as "Relay message from X [id]: content" - use "agent-relay read <id>" for long messages`,
+            `PERSIST: Output [[SUMMARY]]{"currentTask":"...","context":"..."}[[/SUMMARY]] after major work.`,
+            `END: Output [[SESSION_END]]{"summary":"..."}[[/SESSION_END]] when session complete.`,
         ].join(' | ');
+        // Add trail instructions if available
+        const trailInstructions = getCompactTrailInstructions();
         try {
-            await this.sendKeysLiteral(instructions);
-            await this.sleep(50);
+            await this.sendKeysLiteral(relayInstructions);
+            await sleep(50);
             await this.sendKeys('Enter');
+            // Inject trail instructions
+            if (this.trajectory?.isTrailInstalledSync()) {
+                await sleep(100);
+                await this.sendKeysLiteral(trailInstructions);
+                await sleep(50);
+                await this.sendKeys('Enter');
+            }
+            // Inject continuity context from previous session
+            await this.injectContinuityContext();
         }
         catch {
             // Silent fail - instructions are nice-to-have
         }
     }
+    /**
+     * Inject continuity context from previous session
+     */
+    async injectContinuityContext() {
+        if (!this.continuity || !this.running)
+            return;
+        try {
+            const context = await this.continuity.getStartupContext(this.config.name);
+            if (context && context.formatted) {
+                // Inject a brief notification about loaded context
+                const notification = `[Continuity] Previous session context loaded. ${context.ledger ? `Task: ${context.ledger.currentTask?.slice(0, 50) || 'unknown'}` : ''}${context.handoff ? ` | Last handoff: ${context.handoff.createdAt.toISOString().split('T')[0]}` : ''}`;
+                await sleep(200);
+                await this.sendKeysLiteral(notification);
+                await sleep(50);
+                await this.sendKeys('Enter');
+                // Queue the full context for injection when agent is ready
+                this.messageQueue.push({
+                    from: 'system',
+                    body: context.formatted,
+                    messageId: `continuity-startup-${Date.now()}`,
+                });
+                this.checkForInjectionOpportunity();
+                if (this.config.debug) {
+                    this.logStderr(`[CONTINUITY] Loaded context for ${this.config.name}`);
+                }
+            }
+        }
+        catch (err) {
+            this.logStderr(`[CONTINUITY] Failed to load context: ${err.message}`, true);
+        }
+    }
     /**
      * Wait for tmux session to be ready
      */
@@ -374,14 +551,14 @@ export class TmuxWrapper {
                 if (promptPatterns.test(lastLine)) {
                     this.logStderr('Shell ready');
                     // Extra delay to ensure shell is fully ready
-                    await this.sleep(200);
+                    await sleep(200);
                     return;
                 }
             }
             catch {
                 // Session might not be ready yet
             }
-            await this.sleep(200);
+            await sleep(200);
         }
         // Fallback: proceed anyway after timeout
         this.logStderr('Shell ready timeout, proceeding anyway');
@@ -435,10 +612,10 @@ export class TmuxWrapper {
             `"${this.tmuxPath}" capture-pane -t ${this.sessionName} -p -J -S - 2>/dev/null`);
             // Always parse the FULL capture for ->relay commands
             // This handles terminal UIs that rewrite content in place
-            const cleanContent = this.stripAnsi(stdout);
+            const cleanContent = stripAnsi(stdout);
             // Join continuation lines that TUIs split across multiple lines
             const joinedContent = this.joinContinuationLines(cleanContent);
-            const { commands } = this.parser.parse(joinedContent);
+            const { commands, output: filteredOutput } = this.parser.parse(joinedContent);
             // Debug: log relay commands being parsed
             if (commands.length > 0 && this.config.debug) {
                 for (const cmd of commands) {
@@ -452,12 +629,13 @@ export class TmuxWrapper {
                 this.markActivity();
                 this.processedOutputLength = stdout.length;
                 // Stream new output to daemon for dashboard log viewing
+                // Use filtered output to exclude thinking blocks and relay commands
                 if (this.config.streamLogs && this.client.state === 'READY') {
-                    // Send incremental output since last log
-                    const newContent = cleanContent.substring(this.lastLoggedLength);
+                    // Send incremental filtered output since last log
+                    const newContent = filteredOutput.substring(this.lastLoggedLength);
                     if (newContent.length > 0) {
                         this.client.sendLog(newContent);
-                        this.lastLoggedLength = cleanContent.length;
+                        this.lastLoggedLength = filteredOutput.length;
                     }
                 }
             }
@@ -467,6 +645,10 @@ export class TmuxWrapper {
             }
             // Check for [[SUMMARY]] blocks and save to storage
             this.parseSummaryAndSave(cleanContent);
+            // Detect PDERO phase transitions from output content
+            this.detectAndTransitionPhase(cleanContent);
+            // Parse and handle continuity commands (->continuity:save, ->continuity:load, etc.)
+            await this.parseContinuityCommands(joinedContent);
             // Check for [[SESSION_END]] blocks to explicitly close session
             this.parseSessionEndAndClose(cleanContent);
             // Check for ->relay:spawn and ->relay:release commands (any agent can spawn)
@@ -482,18 +664,6 @@ export class TmuxWrapper {
             }
         }
     }
-    /**
-     * Strip ANSI escape codes
-     */
-    stripAnsi(str) {
-        // Strip ANSI escape sequences (with \x1B prefix)
-        // eslint-disable-next-line no-control-regex
-        let result = str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
-        // Strip orphaned CSI sequences that lost their escape byte
-        // These look like [?25h, [?2026l, [0m, etc. at the start of content
-        result = result.replace(/^\s*(\[\??\d*[A-Za-z])+\s*/g, '');
-        return result;
-    }
     /**
      * Join continuation lines after ->relay commands.
      * Claude Code and other TUIs insert real newlines in output, causing
@@ -616,6 +786,8 @@ export class TmuxWrapper {
             this.queuedMessageHashes.delete(msgHash);
             const truncatedBody = cmd.body.substring(0, Math.min(RELAY_LOG_TRUNCATE_LENGTH, cmd.body.length));
             this.logStderr(`→ ${cmd.to}: ${truncatedBody}...`);
+            // Record in trajectory via trail
+            this.trajectory?.message('sent', this.config.name, cmd.to, cmd.body);
         }
         else if (this.client.state !== 'READY') {
             // Only log failure once per state change
@@ -663,7 +835,14 @@ export class TmuxWrapper {
         if (summaryHash === this.lastSummaryHash)
             return;
         this.lastSummaryHash = summaryHash;
-        // Wait for storage to be ready before saving
+        // Save to continuity ledger for session recovery
+        // This ensures the ledger has actual data instead of placeholders
+        if (this.continuity) {
+            this.saveSummaryToLedger(summary).catch(err => {
+                this.logStderr(`Failed to save summary to ledger: ${err.message}`, true);
+            });
+        }
+        // Wait for storage to be ready before saving to project storage
         this.storageReady.then(ready => {
             if (!ready || !this.storage) {
                 this.logStderr('Cannot save summary: storage not initialized');
@@ -685,6 +864,86 @@ export class TmuxWrapper {
             });
         });
     }
+    /**
+     * Save a parsed summary to the continuity ledger.
+     * Maps summary fields to ledger fields for session recovery.
+     */
+    async saveSummaryToLedger(summary) {
+        if (!this.continuity)
+            return;
+        const updates = {};
+        // Map summary fields to ledger fields
+        if (summary.currentTask) {
+            updates.currentTask = summary.currentTask;
+        }
+        if (summary.completedTasks && summary.completedTasks.length > 0) {
+            updates.completed = summary.completedTasks;
+        }
+        if (summary.context) {
+            // Store context in inProgress as "next steps" hint
+            updates.inProgress = [summary.context];
+        }
+        if (summary.files && summary.files.length > 0) {
+            updates.fileContext = summary.files.map((f) => ({ path: f }));
+        }
+        // Only save if we have meaningful updates
+        if (Object.keys(updates).length > 0) {
+            await this.continuity.saveLedger(this.config.name, updates);
+            this.logStderr('Saved summary to continuity ledger');
+        }
+    }
+    /**
+     * Parse ->continuity: commands from output and handle them.
+     * Supported commands:
+     *   ->continuity:save <<<...>>>  - Save session state to ledger
+     *   ->continuity:load            - Request context injection
+     *   ->continuity:search "query"  - Search past handoffs
+     *   ->continuity:uncertain "..."  - Mark item as uncertain
+     *   ->continuity:handoff <<<...>>> - Create explicit handoff
+     */
+    async parseContinuityCommands(content) {
+        if (!this.continuity)
+            return;
+        if (!hasContinuityCommand(content))
+            return;
+        const command = parseContinuityCommand(content);
+        if (!command)
+            return;
+        // Create a hash for deduplication
+        // For commands with content (save, handoff, uncertain), use content hash
+        // For commands without content (load, search), allow each unique call
+        const hasContent = command.content || command.query || command.item;
+        const cmdHash = hasContent
+            ? `${command.type}:${command.content || command.query || command.item}`
+            : `${command.type}:${Date.now()}`; // Allow load/search to run each time
+        if (hasContent && this.processedContinuityCommands.has(cmdHash))
+            return;
+        this.processedContinuityCommands.add(cmdHash);
+        // Limit dedup set size
+        if (this.processedContinuityCommands.size > 100) {
+            const oldest = this.processedContinuityCommands.values().next().value;
+            if (oldest)
+                this.processedContinuityCommands.delete(oldest);
+        }
+        try {
+            if (this.config.debug) {
+                this.logStderr(`[CONTINUITY] Processing ${command.type} command`);
+            }
+            const response = await this.continuity.handleCommand(this.config.name, command);
+            // If there's a response (e.g., from load or search), inject it
+            if (response) {
+                this.messageQueue.push({
+                    from: 'system',
+                    body: response,
+                    messageId: `continuity-${Date.now()}`,
+                });
+                this.checkForInjectionOpportunity();
+            }
+        }
+        catch (err) {
+            this.logStderr(`[CONTINUITY] Error: ${err.message}`, true);
+        }
+    }
     /**
      * Parse [[SESSION_END]] blocks from output and close session explicitly.
      * Agents output this to mark their work session as complete:
@@ -692,6 +951,8 @@ export class TmuxWrapper {
      * [[SESSION_END]]
      * {"summary": "Completed auth module", "completedTasks": ["login", "logout"]}
      * [[/SESSION_END]]
+     *
+     * Also stores the data for use in autoSave to populate handoff (fixes empty handoff issue).
      */
     parseSessionEndAndClose(content) {
         if (this.sessionEndProcessed)
@@ -699,6 +960,8 @@ export class TmuxWrapper {
         const sessionEnd = parseSessionEndFromOutput(content);
         if (!sessionEnd)
             return;
+        // Store SESSION_END data for use in autoSave (fixes empty handoff issue)
+        this.sessionEndData = sessionEnd;
         // Get session ID from client connection - if not available yet, don't set flag
         // so we can retry when sessionId becomes available
         const sessionId = this.client.currentSessionId;
@@ -723,29 +986,184 @@ export class TmuxWrapper {
             });
         });
     }
+    /**
+     * Execute spawn via API (if dashboardPort set) or callback
+     */
+    async executeSpawn(name, cli, task) {
+        if (this.config.dashboardPort) {
+            // Use dashboard API for spawning (works from any context, no terminal required)
+            try {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/spawn`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ name, cli, task }),
+                });
+                const result = await response.json();
+                if (result.success) {
+                    this.logStderr(`Spawned ${name} via API`);
+                }
+                else {
+                    this.logStderr(`Spawn failed: ${result.error}`, true);
+                }
+            }
+            catch (err) {
+                this.logStderr(`Spawn API call failed: ${err.message}`, true);
+            }
+        }
+        else if (this.config.onSpawn) {
+            // Fall back to callback
+            try {
+                await this.config.onSpawn(name, cli, task);
+            }
+            catch (err) {
+                this.logStderr(`Spawn failed: ${err.message}`, true);
+            }
+        }
+    }
+    /**
+     * Execute release via API (if dashboardPort set) or callback
+     */
+    async executeRelease(name) {
+        if (this.config.dashboardPort) {
+            // Use dashboard API for release (works from any context, no terminal required)
+            try {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/spawned/${encodeURIComponent(name)}`, {
+                    method: 'DELETE',
+                });
+                const result = await response.json();
+                if (result.success) {
+                    this.logStderr(`Released ${name} via API`);
+                }
+                else {
+                    this.logStderr(`Release failed: ${result.error}`, true);
+                }
+            }
+            catch (err) {
+                this.logStderr(`Release API call failed: ${err.message}`, true);
+            }
+        }
+        else if (this.config.onRelease) {
+            // Fall back to callback
+            try {
+                await this.config.onRelease(name);
+            }
+            catch (err) {
+                this.logStderr(`Release failed: ${err.message}`, true);
+            }
+        }
+    }
     /**
      * Parse ->relay:spawn and ->relay:release commands from output.
-     * Format:
-     *   ->relay:spawn WorkerName cli "task description"
+     * Supports two formats:
+     *   Single-line: ->relay:spawn WorkerName cli "task description"
+     *   Multi-line (fenced): ->relay:spawn WorkerName cli <<<
+     *                        task description here
+     *                        can span multiple lines>>>
      *   ->relay:release WorkerName
      */
     parseSpawnReleaseCommands(content) {
-        // Only process if callbacks are configured
-        if (!this.config.onSpawn && !this.config.onRelease)
+        // Only process if we have API or callbacks configured
+        const canSpawn = this.config.dashboardPort || this.config.onSpawn;
+        const canRelease = this.config.dashboardPort || this.config.onRelease;
+        if (!canSpawn && !canRelease)
             return;
         const lines = content.split('\n');
+        // Pattern to strip common line prefixes (bullets, prompts, etc.)
+        // Must include ● (U+25CF BLACK CIRCLE) used by Claude's TUI
+        const linePrefixPattern = /^(?:[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■│┃┆┇┊┋╎╏✦]\s*)+/;
         for (const line of lines) {
-            const trimmed = line.trim();
-            // Match ->relay:spawn WorkerName cli OR ->relay:spawn WorkerName cli "task"
-            // Task is now optional - agents can be spawned without immediate task injection
-            // Pattern: ->relay:spawn <name> <cli> [optional: "<task>" or '<task>']
-            // Allow trailing whitespace and optional bullet prefixes that TUIs might add
-            const spawnMatch = trimmed.match(/^(?:[•\-*]\s*)?->relay:spawn\s+(\S+)\s+(\S+)(?:\s+["'](.+?)["'])?\s*$/);
-            if (spawnMatch && this.config.onSpawn) {
-                const [, name, cli, task] = spawnMatch;
-                const taskStr = task || ''; // Task is optional, default to empty string
+            let trimmed = line.trim();
+            // Strip common line prefixes (bullets, prompts) before checking for commands
+            trimmed = trimmed.replace(linePrefixPattern, '');
+            // If we're in fenced spawn mode, accumulate lines until we see >>>
+            if (this.pendingFencedSpawn) {
+                // Check for fence close (>>> at end of line or on its own line)
+                const closeIdx = trimmed.indexOf('>>>');
+                if (closeIdx !== -1) {
+                    // Add content before >>> to task
+                    const contentBeforeClose = trimmed.substring(0, closeIdx);
+                    if (contentBeforeClose) {
+                        this.pendingFencedSpawn.taskLines.push(contentBeforeClose);
+                    }
+                    // Execute the spawn with accumulated task
+                    const { name, cli, taskLines } = this.pendingFencedSpawn;
+                    const taskStr = taskLines.join('\n').trim();
+                    const spawnKey = `${name}:${cli}`;
+                    if (!this.processedSpawnCommands.has(spawnKey)) {
+                        this.processedSpawnCommands.add(spawnKey);
+                        if (taskStr) {
+                            this.logStderr(`Spawn command (fenced): ${name} (${cli}) - "${taskStr.substring(0, 50)}..."`);
+                        }
+                        else {
+                            this.logStderr(`Spawn command (fenced): ${name} (${cli}) - no task`);
+                        }
+                        this.executeSpawn(name, cli, taskStr);
+                    }
+                    this.pendingFencedSpawn = null;
+                }
+                else {
+                    // Accumulate line as part of task
+                    this.pendingFencedSpawn.taskLines.push(line);
+                }
+                continue;
+            }
+            // Check for fenced spawn start: ->relay:spawn Name [cli] <<< (CLI optional, defaults to 'claude')
+            // Prefixes are stripped above, so we just look for the command at start of line
+            const fencedSpawnMatch = trimmed.match(/^->relay:spawn\s+(\S+)(?:\s+(\S+))?\s+<<<(.*)$/);
+            if (fencedSpawnMatch && canSpawn) {
+                const [, name, cliOrUndefined, inlineContent] = fencedSpawnMatch;
+                const cli = cliOrUndefined || 'claude';
+                // Validate name
+                if (name.length < 2) {
+                    this.logStderr(`Fenced spawn has invalid name, skipping: name=${name}`);
+                    continue;
+                }
+                // Check if fence closes on same line (e.g., ->relay:spawn Worker cli <<<task>>>)
+                const inlineCloseIdx = inlineContent.indexOf('>>>');
+                if (inlineCloseIdx !== -1) {
+                    // Single line fenced: extract task between <<< and >>>
+                    const taskStr = inlineContent.substring(0, inlineCloseIdx).trim();
+                    const spawnKey = `${name}:${cli}`;
+                    if (!this.processedSpawnCommands.has(spawnKey)) {
+                        this.processedSpawnCommands.add(spawnKey);
+                        if (taskStr) {
+                            this.logStderr(`Spawn command: ${name} (${cli}) - "${taskStr.substring(0, 50)}..."`);
+                        }
+                        else {
+                            this.logStderr(`Spawn command: ${name} (${cli}) - no task`);
+                        }
+                        this.executeSpawn(name, cli, taskStr);
+                    }
+                }
+                else {
+                    // Start multi-line fenced mode
+                    this.pendingFencedSpawn = {
+                        name,
+                        cli,
+                        taskLines: inlineContent.trim() ? [inlineContent.trim()] : [],
+                    };
+                    this.logStderr(`Starting fenced spawn capture: ${name} (${cli})`);
+                }
+                continue;
+            }
+            // Match single-line spawn: ->relay:spawn WorkerName [cli] ["task"]
+            // CLI is optional - defaults to 'claude'. Task is also optional.
+            // Prefixes are stripped above, so we just look for the command at start of line
+            const spawnMatch = trimmed.match(/^->relay:spawn\s+(\S+)(?:\s+(\S+))?(?:\s+["'](.+?)["'])?\s*$/);
+            if (spawnMatch && canSpawn) {
+                const [, name, cliOrUndefined, task] = spawnMatch;
+                const cli = cliOrUndefined || 'claude';
+                // Validate the parsed values
+                if (cli === '<<<' || cli === '>>>' || name === '<<<' || name === '>>>') {
+                    this.logStderr(`Invalid spawn command (fence markers), skipping: name=${name}, cli=${cli}`);
+                    continue;
+                }
+                if (name.length < 2) {
+                    this.logStderr(`Spawn command has suspiciously short name, skipping: name=${name}`);
+                    continue;
+                }
+                const taskStr = task || '';
                 const spawnKey = `${name}:${cli}`;
-                // Dedup - only process each spawn once (keyed by name:cli, not including task)
                 if (!this.processedSpawnCommands.has(spawnKey)) {
                     this.processedSpawnCommands.add(spawnKey);
                     if (taskStr) {
@@ -754,24 +1172,19 @@ export class TmuxWrapper {
                     else {
                         this.logStderr(`Spawn command: ${name} (${cli}) - no task`);
                     }
-                    this.config.onSpawn(name, cli, taskStr).catch(err => {
-                        this.logStderr(`Spawn failed: ${err.message}`, true);
-                    });
+                    this.executeSpawn(name, cli, taskStr);
                 }
                 continue;
             }
             // Match ->relay:release WorkerName
-            // Allow trailing whitespace and optional bullet prefixes
-            const releaseMatch = trimmed.match(/^(?:[•\-*]\s*)?->relay:release\s+(\S+)\s*$/);
-            if (releaseMatch && this.config.onRelease) {
+            // Prefixes are stripped above, so we just look for the command at start of line
+            const releaseMatch = trimmed.match(/^->relay:release\s+(\S+)\s*$/);
+            if (releaseMatch && canRelease) {
                 const [, name] = releaseMatch;
-                // Dedup - only process each release once
                 if (!this.processedReleaseCommands.has(name)) {
                     this.processedReleaseCommands.add(name);
                     this.logStderr(`Release command: ${name}`);
-                    this.config.onRelease(name).catch(err => {
-                        this.logStderr(`Release failed: ${err.message}`, true);
-                    });
+                    this.executeRelease(name);
                 }
             }
         }
@@ -789,6 +1202,8 @@ export class TmuxWrapper {
         const truncatedBody = payload.body.substring(0, Math.min(DEBUG_LOG_TRUNCATE_LENGTH, payload.body.length));
         const channelInfo = originalTo === '*' ? ' [broadcast]' : '';
         this.logStderr(`← ${from}${channelInfo}: ${truncatedBody}...`);
+        // Record in trajectory via trail
+        this.trajectory?.message('received', from, this.config.name, payload.body);
         // Queue for injection - include originalTo so we can inform the agent how to route responses
         this.messageQueue.push({ from, body: payload.body, messageId, thread: payload.thread, importance: meta?.importance, data: payload.data, originalTo });
         // Write to inbox if enabled
@@ -818,7 +1233,8 @@ export class TmuxWrapper {
         this.injectNextMessage();
     }
     /**
-     * Inject message via tmux send-keys
+     * Inject message via tmux send-keys.
+     * Uses shared injection logic with tmux-specific callbacks.
      */
     async injectNextMessage() {
         const msg = this.messageQueue.shift();
@@ -827,33 +1243,21 @@ export class TmuxWrapper {
         this.isInjecting = true;
         this.logStderr(`Injecting message from ${msg.from} (cli: ${this.cliType})`);
         try {
-            // Strip ANSI escape sequences and orphaned control sequences from message body
-            let sanitizedBody = this.stripAnsi(msg.body).replace(/[\r\n]+/g, ' ').trim();
-            // Gemini interprets certain keywords (While, For, If, etc.) as shell commands
-            // Wrap in backticks to prevent shell keyword interpretation
-            if (this.cliType === 'gemini') {
-                sanitizedBody = `\`${sanitizedBody.replace(/`/g, "'")}\``;
-            }
-            // Short message ID for display (first 8 chars)
             const shortId = msg.messageId.substring(0, 8);
-            // Remove message truncation to allow full messages to pass through
-            const wasTruncated = false;
-            // Always include message ID; add lookup hint if truncated
-            const idTag = `[${shortId}]`;
-            const truncationHint = wasTruncated
-                ? ` [TRUNCATED - run "agent-relay read ${msg.messageId}"]`
-                : '';
             // Wait for input to be clear before injecting
+            // If input is not clear (human typing), re-queue and try later - never clear forcefully!
+            // Fix for agent-relay-j9z: forceful clearing destroys human input in progress
             const waitTimeoutMs = this.config.inputWaitTimeoutMs ?? 5000;
             const waitPollMs = this.config.inputWaitPollMs ?? 200;
             const inputClear = await this.waitForClearInput(waitTimeoutMs, waitPollMs);
             if (!inputClear) {
-                // Input still has text after timeout - clear it forcefully
-                this.logStderr('Input not clear after waiting, clearing forcefully');
-                await this.sendKeys('Escape');
-                await this.sleep(30);
-                await this.sendKeys('C-u');
-                await this.sleep(30);
+                // Input still has text after timeout - DON'T clear forcefully, re-queue instead
+                // This preserves any human input in progress
+                this.logStderr('Input not clear after waiting, re-queuing injection to preserve human input');
+                this.messageQueue.unshift(msg);
+                this.isInjecting = false;
+                setTimeout(() => this.checkForInjectionOpportunity(), this.config.injectRetryMs ?? 1000);
+                return;
             }
             // Ensure pane output is stable to avoid interleaving with active generation
             const stablePane = await this.waitForStablePane(this.config.outputStabilityTimeoutMs ?? 2000, this.config.outputStabilityPollMs ?? 200);
@@ -868,8 +1272,8 @@ export class TmuxWrapper {
             // If at shell prompt, skip injection to avoid shell command execution
             if (this.cliType === 'gemini') {
                 const lastLine = await this.getLastLine();
-                const cleanLine = this.stripAnsi(lastLine).trim();
-                if (/^\$\s*$/.test(cleanLine) || /^\s*\$\s*$/.test(cleanLine)) {
+                const cleanLine = stripAnsi(lastLine).trim();
+                if (CLI_QUIRKS.isShellPrompt(cleanLine)) {
                     this.logStderr('Gemini at shell prompt, skipping injection to avoid shell execution');
                     // Re-queue the message for later
                     this.messageQueue.unshift(msg);
@@ -878,33 +1282,51 @@ export class TmuxWrapper {
                     return;
                 }
             }
-            // Standard injection for all CLIs including Gemini
-            // Format: Relay message from Sender [abc12345] [thread:xxx] [!] [#general]: content
-            // Thread/importance/channel hints are compact and optional to not break TUIs
-            const threadHint = msg.thread ? ` [thread:${msg.thread}]` : '';
-            // Importance indicator: [!!] for high (>75), [!] for medium (>50), none for low/default
-            const importanceHint = msg.importance !== undefined && msg.importance > 75 ? ' [!!]' :
-                msg.importance !== undefined && msg.importance > 50 ? ' [!]' : '';
-            // Channel indicator: [#general] for broadcasts - tells agent to reply to * not sender
-            // This ensures responses to #general messages go back to #general, not as DMs
-            const channelHint = msg.originalTo === '*' ? ' [#general]' : '';
-            // Extract attachment file paths if present
-            let attachmentHint = '';
-            if (msg.data?.attachments && Array.isArray(msg.data.attachments)) {
-                const filePaths = msg.data.attachments
-                    .map((att) => att.filePath)
-                    .filter((p) => typeof p === 'string');
-                if (filePaths.length > 0) {
-                    attachmentHint = ` [Attachments: ${filePaths.join(', ')}]`;
+            // Build injection string using shared utility
+            let injection = buildInjectionString(msg);
+            // Gemini-specific: wrap body in backticks to prevent shell keyword interpretation
+            if (this.cliType === 'gemini') {
+                const colonIdx = injection.indexOf(': ');
+                if (colonIdx > 0) {
+                    const prefix = injection.substring(0, colonIdx + 2);
+                    const body = injection.substring(colonIdx + 2);
+                    injection = prefix + CLI_QUIRKS.wrapForGemini(body);
+                }
+            }
+            // Create callbacks for shared injection logic
+            const callbacks = {
+                getOutput: async () => {
+                    try {
+                        const { stdout } = await execAsync(`"${this.tmuxPath}" capture-pane -t ${this.sessionName} -p -S - 2>/dev/null`);
+                        return stdout;
+                    }
+                    catch {
+                        return '';
+                    }
+                },
+                performInjection: async (inj) => {
+                    await this.pasteLiteral(inj);
+                    await sleep(INJECTION_CONSTANTS.ENTER_DELAY_MS);
+                    await this.sendKeys('Enter');
+                },
+                log: (message) => this.logStderr(message),
+                logError: (message) => this.logStderr(message, true),
+                getMetrics: () => this.injectionMetrics,
+            };
+            // Inject with retry and verification using shared logic
+            const result = await sharedInjectWithRetry(injection, shortId, msg.from, callbacks);
+            if (result.success) {
+                this.logStderr(`Injection complete (attempt ${result.attempts})`);
+            }
+            else {
+                // All retries failed - log and optionally fall back to inbox
+                this.logStderr(`Message delivery failed after ${result.attempts} attempts: from=${msg.from} id=${shortId}`, true);
+                // Write to inbox as fallback if enabled
+                if (this.inbox) {
+                    this.inbox.addMessage(msg.from, msg.body);
+                    this.logStderr('Wrote message to inbox as fallback');
                 }
             }
-            const injection = `Relay message from ${msg.from} ${idTag}${threadHint}${importanceHint}${channelHint}${attachmentHint}: ${sanitizedBody}${truncationHint}`;
-            // Paste message as a bracketed paste to avoid interleaving with active output
-            await this.pasteLiteral(injection);
-            await this.sleep(30);
-            // Submit
-            await this.sendKeys('Enter');
-            this.logStderr(`Injection complete`);
         }
         catch (err) {
             this.logStderr(`Injection failed: ${err.message}`, true);
@@ -912,7 +1334,7 @@ export class TmuxWrapper {
         finally {
             this.isInjecting = false;
             if (this.messageQueue.length > 0) {
-                setTimeout(() => this.checkForInjectionOpportunity(), 1000);
+                setTimeout(() => this.checkForInjectionOpportunity(), INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MS);
             }
         }
     }
@@ -967,7 +1389,7 @@ export class TmuxWrapper {
         // Set tmux buffer then paste
         // Skip bracketed paste (-p) for CLIs that don't handle it properly (droid, other)
         await execAsync(`"${this.tmuxPath}" set-buffer -- "${escaped}"`);
-        const useBracketedPaste = this.cliType === 'claude' || this.cliType === 'codex' || this.cliType === 'gemini';
+        const useBracketedPaste = this.cliType === 'claude' || this.cliType === 'codex' || this.cliType === 'gemini' || this.cliType === 'opencode';
         if (useBracketedPaste) {
             await execAsync(`"${this.tmuxPath}" paste-buffer -t ${this.sessionName} -p`);
         }
@@ -975,9 +1397,6 @@ export class TmuxWrapper {
             await execAsync(`"${this.tmuxPath}" paste-buffer -t ${this.sessionName}`);
         }
     }
-    sleep(ms) {
-        return new Promise(r => setTimeout(r, ms));
-    }
     /**
      * Reset session-specific state for wrapper reuse.
      * Call this when starting a new session with the same wrapper instance.
@@ -986,18 +1405,13 @@ export class TmuxWrapper {
         this.sessionEndProcessed = false;
         this.lastSummaryHash = '';
         this.lastSummaryRawContent = '';
+        this.sessionEndData = undefined;
     }
     /**
      * Get the prompt pattern for the current CLI type.
      */
     getPromptPattern() {
-        const promptPatterns = {
-            claude: /^[>›»]\s*$/, // Claude: "> " or similar
-            gemini: /^[>›»]\s*$/, // Gemini: "> "
-            codex: /^[>›»]\s*$/, // Codex: "> "
-            other: /^[>$%#➜›»]\s*$/, // Shell or other: "$ ", "> ", etc.
-        };
-        return promptPatterns[this.cliType] || promptPatterns.other;
+        return CLI_QUIRKS.getPromptPattern(this.cliType);
     }
     /**
      * Capture the last non-empty line from the tmux pane.
@@ -1016,7 +1430,7 @@ export class TmuxWrapper {
      * Detect if the provided line contains visible user input (beyond the prompt).
      */
     hasVisibleInput(line) {
-        const cleanLine = this.stripAnsi(line).trimEnd();
+        const cleanLine = stripAnsi(line).trimEnd();
         if (cleanLine === '')
             return false;
         return !this.getPromptPattern().test(cleanLine);
@@ -1028,7 +1442,7 @@ export class TmuxWrapper {
     async isInputClear(lastLine) {
         try {
             const lineToCheck = lastLine ?? await this.getLastLine();
-            const cleanLine = this.stripAnsi(lineToCheck).trimEnd();
+            const cleanLine = stripAnsi(lineToCheck).trimEnd();
             const isClear = this.getPromptPattern().test(cleanLine);
             if (this.config.debug) {
                 const truncatedLine = cleanLine.substring(0, Math.min(DEBUG_LOG_TRUNCATE_LENGTH, cleanLine.length));
@@ -1088,7 +1502,7 @@ export class TmuxWrapper {
                 stableCursorCount = 0;
                 lastCursorX = cursorX;
             }
-            await this.sleep(pollIntervalMs);
+            await sleep(pollIntervalMs);
         }
         this.logStderr(`waitForClearInput: timed out after ${maxWaitMs}ms`);
         return false;
@@ -1117,7 +1531,7 @@ export class TmuxWrapper {
             return false;
         let stableCount = 0;
         while (Date.now() - start < maxWaitMs) {
-            await this.sleep(pollIntervalMs);
+            await sleep(pollIntervalMs);
             const sig = await this.capturePaneSignature();
             if (!sig)
                 continue;
@@ -1143,6 +1557,13 @@ export class TmuxWrapper {
             return;
         this.running = false;
         this.activityState = 'disconnected';
+        // Auto-save continuity state before shutdown (fire and forget)
+        // Pass sessionEndData to populate handoff (fixes empty handoff issue)
+        if (this.continuity) {
+            this.continuity.autoSave(this.config.name, 'session_end', this.sessionEndData).catch((err) => {
+                this.logStderr(`[CONTINUITY] Auto-save failed: ${err.message}`, true);
+            });
+        }
         // Reset session state for potential reuse
         this.resetSessionState();
         // Stop polling