agent-relay 1.1.0 → 1.2.3

package/dist/wrapper/pty-wrapper.js

@@ -10,6 +10,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { EventEmitter } from 'node:events';
 import { RelayClient } from './client.js';
+import { parseSummaryWithDetails, parseSessionEndFromOutput, isPlaceholderTarget } from './parser.js';
+import { getProjectPaths } from '../utils/project-namespace.js';
+import { getTrailEnvVars } from '../trajectory/integration.js';
+import { findAgentConfig } from '../utils/agent-config.js';
+import { HookRegistry, createTrajectoryHooks } from '../hooks/index.js';
+import { getContinuityManager, parseContinuityCommand, hasContinuityCommand } from '../continuity/index.js';
+import { INJECTION_CONSTANTS, stripAnsi, sleep, buildInjectionString, injectWithRetry as sharedInjectWithRetry, calculateSuccessRate, createInjectionMetrics, getDefaultRelayPrefix, detectCliType, CLI_QUIRKS, } from './shared.js';
 /** Maximum lines to keep in output buffer */
 const MAX_BUFFER_LINES = 10000;
 export class PtyWrapper extends EventEmitter {
@@ -20,26 +27,93 @@ export class PtyWrapper extends EventEmitter {
     outputBuffer = [];
     rawBuffer = '';
     relayPrefix;
+    cliType;
     sentMessageHashes = new Set();
+    receivedMessageIds = new Set(); // Dedup incoming messages
     processedSpawnCommands = new Set();
     processedReleaseCommands = new Set();
+    pendingFencedSpawn = null;
     messageQueue = [];
     isInjecting = false;
     readyForMessages = false;
+    lastOutputTime = 0;
+    injectionMetrics = createInjectionMetrics();
     logFilePath;
     logStream;
-    hasAcceptedPrompt = false;
+    acceptedPrompts = new Set(); // Track which prompts have been accepted
+    hookRegistry;
+    sessionStartTime = Date.now();
+    continuity;
+    agentId;
+    processedContinuityCommands = new Set();
+    lastSummaryRawContent = ''; // Dedup summary event emissions
+    sessionEndProcessed = false; // Track if we've already emitted session-end
+    inThinkingBlock = false; // Track if inside <thinking>...</thinking>
+    lastSummaryTime = Date.now(); // Track when last summary was output
+    outputsSinceSummary = 0; // Count outputs since last summary
+    detectedTask; // Auto-detected task from agent config
+    sessionEndData; // Store SESSION_END data for handoff
+    instructionsInjected = false; // Track if init instructions have been injected
+    continuityInjected = false; // Track if continuity context has been injected
+    recentLogChunks = new Map(); // Dedup log streaming (hash -> timestamp)
+    static LOG_DEDUP_WINDOW_MS = 500; // Window for considering logs as duplicates
+    static LOG_DEDUP_MAX_SIZE = 100; // Max entries in dedup map
+    lastParsedLength = 0; // Track last parsed position to avoid re-parsing entire buffer
+    lastContinuityParsedLength = 0; // Same for continuity commands
     constructor(config) {
         super();
         this.config = config;
-        this.relayPrefix = config.relayPrefix ?? '->relay:';
+        this.relayPrefix = config.relayPrefix ?? getDefaultRelayPrefix();
+        // Detect CLI type from command for special handling
+        this.cliType = config.cliType ?? detectCliType(config.command);
+        // Auto-detect agent role from .claude/agents/ or .openagents/ if task not provided
+        let detectedTask = config.task;
+        if (!detectedTask) {
+            const agentConfig = findAgentConfig(config.name, config.cwd);
+            if (agentConfig?.description) {
+                detectedTask = agentConfig.description;
+                // Use stderr for consistency with TmuxWrapper's logStderr pattern
+                process.stderr.write(`[pty:${config.name}] Auto-detected role: ${detectedTask.substring(0, 60)}...\n`);
+            }
+        }
+        // Store detected task for use in hook registry
+        this.detectedTask = detectedTask;
         this.client = new RelayClient({
             agentName: config.name,
             socketPath: config.socketPath,
-            cli: 'spawned',
+            cli: this.cliType,
+            task: detectedTask,
             workingDirectory: config.cwd ?? process.cwd(),
             quiet: true,
         });
+        // Initialize hook registry
+        const projectPaths = getProjectPaths();
+        this.hookRegistry = new HookRegistry({
+            agentName: config.name,
+            workingDir: config.cwd ?? process.cwd(),
+            projectId: projectPaths.projectId,
+            task: this.detectedTask,
+            env: config.env,
+            inject: (text) => this.write(text + '\r'),
+            send: async (to, body) => {
+                this.client.sendMessage(to, body, 'message');
+            },
+        });
+        // Register trajectory hooks if enabled (default: true if task provided or auto-detected)
+        const enableTrajectory = config.trajectoryTracking ?? !!this.detectedTask;
+        if (enableTrajectory) {
+            const trajectoryHooks = createTrajectoryHooks({
+                projectId: projectPaths.projectId,
+                agentName: config.name,
+            });
+            this.hookRegistry.registerLifecycleHooks(trajectoryHooks);
+        }
+        // Register custom hooks if provided
+        if (config.hooks) {
+            this.hookRegistry.registerLifecycleHooks(config.hooks);
+        }
+        // Initialize continuity manager
+        this.continuity = getContinuityManager({ defaultCli: 'spawned' });
         // Handle incoming messages
         this.client.onMessage = (from, payload, messageId, meta, originalTo) => {
             this.handleIncomingMessage(from, payload, messageId, meta, originalTo);
@@ -87,6 +161,9 @@ export class PtyWrapper extends EventEmitter {
         // Log spawn details for debugging
         console.log(`[pty:${this.config.name}] Spawning: ${this.config.command} ${args.join(' ')}`);
         console.log(`[pty:${this.config.name}] CWD: ${cwd}`);
+        // Get trail environment variables
+        const projectPaths = getProjectPaths();
+        const trailEnvVars = getTrailEnvVars(projectPaths.projectId, this.config.name, projectPaths.dataDir);
         // Spawn the process with error handling
         try {
             this.ptyProcess = pty.spawn(this.config.command, args, {
@@ -97,6 +174,7 @@ export class PtyWrapper extends EventEmitter {
                 env: {
                     ...process.env,
                     ...this.config.env,
+                    ...trailEnvVars,
                     AGENT_RELAY_NAME: this.config.name,
                     TERM: 'xterm-256color',
                 },
@@ -109,6 +187,17 @@ export class PtyWrapper extends EventEmitter {
             throw spawnError;
         }
         this.running = true;
+        this.sessionStartTime = Date.now();
+        // Dispatch session start hook (handles trajectory initialization)
+        this.hookRegistry.dispatchSessionStart().catch(err => {
+            console.error(`[pty:${this.config.name}] Session start hook error:`, err);
+        });
+        // Initialize continuity and get agentId, then inject context
+        this.initializeAgentId()
+            .then(() => this.injectContinuityContext())
+            .catch(err => {
+            console.error(`[pty:${this.config.name}] Agent ID/continuity initialization error:`, err);
+        });
         // Capture output
         this.ptyProcess.onData((data) => {
             this.handleOutput(data);
@@ -128,10 +217,139 @@ export class PtyWrapper extends EventEmitter {
             this.processMessageQueue();
         }, 2000);
     }
+    /**
+     * 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) {
+                    console.log(`[pty:${this.config.name}] Resuming agent ID: ${ledger.agentId} (from previous session)`);
+                }
+                else {
+                    console.error(`[pty:${this.config.name}] Resume agent ID ${this.config.resumeAgentId} not found, creating new`);
+                }
+            }
+            // If not resuming or resume ID not found, get or create ledger
+            if (!ledger) {
+                ledger = await this.continuity.getOrCreateLedger(this.config.name, 'spawned');
+                console.log(`[pty:${this.config.name}] Agent ID: ${ledger.agentId} (use this to resume if agent dies)`);
+            }
+            this.agentId = ledger.agentId;
+        }
+        catch (err) {
+            console.error(`[pty:${this.config.name}] Failed to initialize agent ID: ${err.message}`);
+        }
+    }
+    /**
+     * Get the current agent ID
+     */
+    getAgentId() {
+        return this.agentId;
+    }
+    /**
+     * Inject continuity context from previous session.
+     * Called after agent ID initialization to restore state from ledger.
+     */
+    async injectContinuityContext() {
+        if (!this.continuity || !this.running)
+            return;
+        // Guard: Only inject once per session
+        if (this.continuityInjected) {
+            console.log(`[pty:${this.config.name}] Continuity context already injected, skipping`);
+            return;
+        }
+        this.continuityInjected = true;
+        try {
+            const context = await this.continuity.getStartupContext(this.config.name);
+            // Skip if no meaningful context (empty ledger or just boilerplate)
+            if (!context?.formatted || context.formatted.length < 50) {
+                console.log(`[pty:${this.config.name}] Skipping continuity injection (no meaningful context)`);
+                return;
+            }
+            if (context?.formatted) {
+                // Build context notification similar to TmuxWrapper
+                const taskInfo = context.ledger?.currentTask
+                    ? `Task: ${context.ledger.currentTask.slice(0, 50)}`
+                    : '';
+                const handoffInfo = context.handoff
+                    ? `Last handoff: ${context.handoff.createdAt.toISOString().split('T')[0]}`
+                    : '';
+                const statusParts = [taskInfo, handoffInfo].filter(Boolean).join(' | ');
+                const notification = `[Continuity] Previous session context loaded.${statusParts ? ` ${statusParts}` : ''}\n\n${context.formatted}`;
+                // Queue continuity context directly to messageQueue with 'system' as sender
+                // This avoids creating confusing "Agent -> Agent" self-messages in the dashboard
+                // Fix for Lead communication issue: continuity checkpoints were creating self-messages
+                this.messageQueue.push({
+                    from: 'system',
+                    body: notification,
+                    messageId: `continuity-startup-${Date.now()}`,
+                    thread: 'continuity-context',
+                });
+                this.processMessageQueue();
+                const mode = context.handoff ? 'resume' : 'continue';
+                console.log(`[pty:${this.config.name}] Continuity context injected (${mode})`);
+            }
+        }
+        catch (err) {
+            console.error(`[pty:${this.config.name}] Failed to inject continuity context: ${err.message}`);
+        }
+    }
+    /**
+     * 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;
+        // Deduplication: use type + content hash for all commands
+        // Fixed: content-less commands (like load) now use static hash to prevent infinite loops
+        const cmdHash = `${command.type}:${command.content || command.query || command.item || 'no-content'}`;
+        if (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 {
+            const response = await this.continuity.handleCommand(this.config.name, command);
+            if (response) {
+                // Inject response via relay message to self
+                this.client.sendMessage(this.config.name, response, 'message', {
+                    thread: 'continuity-response',
+                });
+                console.log(`[pty:${this.config.name}] Continuity command handled: ${command.type}`);
+            }
+        }
+        catch (err) {
+            console.error(`[pty:${this.config.name}] Continuity command error: ${err.message}`);
+        }
+    }
     /**
      * Handle output from the process
      */
     handleOutput(data) {
+        // Track output timing for stability checks
+        this.lastOutputTime = Date.now();
         // Append to raw buffer
         this.rawBuffer += data;
         // Write to log file if available
@@ -141,8 +359,13 @@ export class PtyWrapper extends EventEmitter {
         // Emit for external listeners
         this.emit('output', data);
         // Stream to daemon for dashboard log viewing (if connected)
+        // Filter out Claude's extended thinking blocks before streaming
+        // Also deduplicate to prevent terminal redraws from causing duplicate log entries
         if (this.config.streamLogs !== false && this.client.state === 'READY') {
-            this.client.sendLog(data);
+            const filteredData = this.filterThinkingBlocks(data);
+            if (filteredData && !this.isDuplicateLogChunk(filteredData)) {
+                this.client.sendLog(filteredData);
+            }
         }
         // Auto-accept Claude's first-run prompt for --dangerously-skip-permissions
         // The prompt shows: "2. Yes, I accept" - we send "2" to accept
@@ -162,28 +385,172 @@ export class PtyWrapper extends EventEmitter {
         }
         // Parse for relay commands
         this.parseRelayCommands();
+        // Dispatch output hook (handles phase detection, etc.)
+        const cleanData = stripAnsi(data);
+        this.hookRegistry.dispatchOutput(cleanData, data).catch(err => {
+            console.error(`[pty:${this.config.name}] Output hook error:`, err);
+        });
+        // Check for [[SUMMARY]] and [[SESSION_END]] blocks and emit events
+        // This allows cloud services to handle persistence without hardcoding storage
+        const cleanContent = stripAnsi(this.rawBuffer);
+        this.checkForSummaryAndEmit(cleanContent);
+        this.checkForSessionEndAndEmit(cleanContent);
+        // Parse for continuity commands (->continuity:save, ->continuity:load, etc.)
+        // Use rawBuffer (accumulated content) not immediate chunk, since multi-line
+        // fenced commands like ->continuity:save <<<...>>> span multiple output events
+        // Optimization: Only parse new content with lookback for incomplete fenced commands
+        if (cleanContent.length > this.lastContinuityParsedLength) {
+            const lookbackStart = Math.max(0, this.lastContinuityParsedLength - 500);
+            const contentToParse = cleanContent.substring(lookbackStart);
+            this.parseContinuityCommands(contentToParse).catch(err => {
+                console.error(`[pty:${this.config.name}] Continuity command parsing error:`, err);
+            });
+            this.lastContinuityParsedLength = cleanContent.length;
+        }
+        // Track outputs and potentially remind about summaries
+        this.trackOutputAndRemind(data);
+    }
+    /**
+     * Filter Claude's extended thinking blocks from output.
+     * Thinking blocks are wrapped in <thinking>...</thinking> tags and should
+     * not be streamed to the dashboard or stored in output buffers.
+     *
+     * This method tracks state across calls to handle multi-line thinking blocks.
+     */
+    filterThinkingBlocks(data) {
+        const THINKING_START = /<thinking>/;
+        const THINKING_END = /<\/thinking>/;
+        const lines = data.split('\n');
+        const outputLines = [];
+        for (const line of lines) {
+            // If in thinking block, check for end
+            if (this.inThinkingBlock) {
+                if (THINKING_END.test(line)) {
+                    this.inThinkingBlock = false;
+                    // If there's content after </thinking> on the same line, keep it
+                    const afterEnd = line.split('</thinking>')[1];
+                    if (afterEnd && afterEnd.trim()) {
+                        outputLines.push(afterEnd);
+                    }
+                }
+                // Skip this line - inside thinking block
+                continue;
+            }
+            // Check for thinking start
+            if (THINKING_START.test(line)) {
+                this.inThinkingBlock = true;
+                // Check if it ends on the same line
+                if (THINKING_END.test(line)) {
+                    this.inThinkingBlock = false;
+                }
+                // Keep content before <thinking> if any
+                const beforeStart = line.split('<thinking>')[0];
+                if (beforeStart && beforeStart.trim()) {
+                    outputLines.push(beforeStart);
+                }
+                continue;
+            }
+            // Normal line - keep it
+            outputLines.push(line);
+        }
+        return outputLines.join('\n');
     }
     /**
-     * Auto-accept Claude's first-run prompts for --dangerously-skip-permissions
-     * Detects the acceptance prompt and sends "2" to select "Yes, I accept"
+     * Check if a log chunk is a duplicate (recently streamed).
+     * Prevents terminal redraws from causing duplicate log entries in the dashboard.
+     *
+     * Uses content normalization and time-based deduplication:
+     * - Strips whitespace and normalizes content for comparison
+     * - Considers chunks with same normalized content within LOG_DEDUP_WINDOW_MS as duplicates
+     * - Cleans up old entries to prevent memory growth
+     */
+    isDuplicateLogChunk(data) {
+        // Normalize: strip excessive whitespace, limit to first 200 chars for hash
+        // This helps catch redraws that might have slight formatting differences
+        const normalized = stripAnsi(data).replace(/\s+/g, ' ').trim().substring(0, 200);
+        // Very short chunks (likely control chars or partial output) - allow through
+        if (normalized.length < 10) {
+            return false;
+        }
+        // Simple hash using string as key
+        const hash = normalized;
+        const now = Date.now();
+        // Check if this chunk was recently streamed
+        const lastSeen = this.recentLogChunks.get(hash);
+        if (lastSeen && (now - lastSeen) < PtyWrapper.LOG_DEDUP_WINDOW_MS) {
+            return true; // Duplicate
+        }
+        // Record this chunk
+        this.recentLogChunks.set(hash, now);
+        // Cleanup: remove old entries if map is getting large
+        if (this.recentLogChunks.size > PtyWrapper.LOG_DEDUP_MAX_SIZE) {
+            const cutoff = now - PtyWrapper.LOG_DEDUP_WINDOW_MS * 2;
+            for (const [key, timestamp] of this.recentLogChunks) {
+                if (timestamp < cutoff) {
+                    this.recentLogChunks.delete(key);
+                }
+            }
+        }
+        return false; // Not a duplicate
+    }
+    /**
+     * Auto-accept Claude's first-run prompts
+     * Handles multiple prompts in sequence:
+     * 1. --dangerously-skip-permissions acceptance ("Yes, I accept")
+     * 2. Trust directory prompt ("Yes, I trust this folder")
+     * 3. "Ready to code here?" permission prompt ("Yes, continue")
+     *
+     * Uses a Set to track which prompts have been accepted, allowing
+     * multiple different prompts to be handled in sequence.
      */
     handleAutoAcceptPrompts(data) {
-        if (this.hasAcceptedPrompt)
-            return;
         if (!this.ptyProcess || !this.running)
             return;
-        // Check for the permission acceptance prompt
+        const cleanData = stripAnsi(data);
+        // Check for the permission acceptance prompt (--dangerously-skip-permissions)
         // Pattern: "2. Yes, I accept" in the output
-        const cleanData = this.stripAnsi(data);
-        if (cleanData.includes('Yes, I accept') && cleanData.includes('No, exit')) {
+        if (!this.acceptedPrompts.has('permission') &&
+            cleanData.includes('Yes, I accept') && cleanData.includes('No, exit')) {
             console.log(`[pty:${this.config.name}] Detected permission prompt, auto-accepting...`);
-            this.hasAcceptedPrompt = true;
+            this.acceptedPrompts.add('permission');
             // Send "2" to select "Yes, I accept" and Enter to confirm
             setTimeout(() => {
                 if (this.ptyProcess && this.running) {
                     this.ptyProcess.write('2');
                 }
             }, 100);
+            return;
+        }
+        // Check for the trust directory prompt
+        // Pattern: "1. Yes, I trust this folder" with "No, exit"
+        if (!this.acceptedPrompts.has('trust') &&
+            (cleanData.includes('trust this folder') || cleanData.includes('safety check'))
+            && cleanData.includes('No, exit')) {
+            console.log(`[pty:${this.config.name}] Detected trust directory prompt, auto-accepting...`);
+            this.acceptedPrompts.add('trust');
+            // Send Enter to accept first option (already selected)
+            setTimeout(() => {
+                if (this.ptyProcess && this.running) {
+                    this.ptyProcess.write('\r');
+                }
+            }, 300);
+            return;
+        }
+        // Check for "Ready to code here?" permission prompt
+        // Pattern: "Yes, continue" with "No, exit" and "Ready to code here?"
+        // This prompt asks for permission to work with files in the workspace
+        if (!this.acceptedPrompts.has('ready-to-code') &&
+            cleanData.includes('Yes, continue') && cleanData.includes('No, exit')
+            && (cleanData.includes('Ready to code here') || cleanData.includes('permission to work with your files'))) {
+            console.log(`[pty:${this.config.name}] Detected "Ready to code here?" prompt, auto-accepting...`);
+            this.acceptedPrompts.add('ready-to-code');
+            // Send Enter to accept first option (already selected with ❯)
+            setTimeout(() => {
+                if (this.ptyProcess && this.running) {
+                    this.ptyProcess.write('\r');
+                }
+            }, 300);
+            return;
         }
     }
     /**
@@ -218,15 +585,27 @@ export class PtyWrapper extends EventEmitter {
      * Parse relay commands from output.
      * Handles both single-line and multi-line (fenced) formats.
      * Deduplication via sentMessageHashes.
+     *
+     * Optimization: Only parses new content since last parse to avoid O(n²) behavior.
+     * Uses lookback buffer for incomplete fenced messages that span output chunks.
      */
     parseRelayCommands() {
-        const cleanContent = this.stripAnsi(this.rawBuffer);
+        const cleanContent = stripAnsi(this.rawBuffer);
+        // Skip if no new content
+        if (cleanContent.length <= this.lastParsedLength)
+            return;
+        // For fenced messages, need some lookback for incomplete fences that span chunks
+        // 500 chars is enough to capture most relay message headers
+        const lookbackStart = Math.max(0, this.lastParsedLength - 500);
+        const contentToParse = cleanContent.substring(lookbackStart);
         // First, try to find fenced multi-line messages: ->relay:Target <<<\n...\n>>>
-        this.parseFencedMessages(cleanContent);
+        this.parseFencedMessages(contentToParse);
         // Then parse single-line messages
-        this.parseSingleLineMessages(cleanContent);
+        this.parseSingleLineMessages(contentToParse);
         // Parse spawn/release commands
-        this.parseSpawnReleaseCommands(cleanContent);
+        this.parseSpawnReleaseCommands(contentToParse);
+        // Update parsed position
+        this.lastParsedLength = cleanContent.length;
     }
     /**
      * Parse fenced multi-line messages: ->relay:Target [thread:xxx] <<<\n...\n>>>
@@ -242,6 +621,14 @@ export class PtyWrapper extends EventEmitter {
             const threadProject = match[2]; // Optional: project part of thread
             const threadId = match[3]; // Thread ID
             const startIdx = match.index + match[0].length;
+            // Skip spawn/release commands - they are handled by parseSpawnReleaseCommands
+            if (/^spawn$/i.test(target) || /^release$/i.test(target)) {
+                continue;
+            }
+            // Skip placeholder targets (documentation examples like "AgentName", "Lead", etc.)
+            if (isPlaceholderTarget(target)) {
+                continue;
+            }
             // Find the closing >>>
             const endIdx = content.indexOf('>>>', startIdx);
             if (endIdx === -1)
@@ -258,6 +645,10 @@ export class PtyWrapper extends EventEmitter {
                 project = target.substring(0, colonIdx);
                 to = target.substring(colonIdx + 1);
             }
+            // Skip placeholder targets after parsing cross-project syntax
+            if (isPlaceholderTarget(to)) {
+                continue;
+            }
             this.sendRelayCommand({
                 to,
                 kind: 'message',
@@ -283,6 +674,11 @@ export class PtyWrapper extends EventEmitter {
             const prefixIdx = line.indexOf(this.relayPrefix);
             if (prefixIdx === -1)
                 continue;
+            // Skip spawn/release commands - they are handled by parseSpawnReleaseCommands
+            const afterPrefixForCheck = line.substring(prefixIdx + this.relayPrefix.length);
+            if (/^spawn\s+/i.test(afterPrefixForCheck) || /^release\s+/i.test(afterPrefixForCheck)) {
+                continue;
+            }
             // Extract everything after the prefix
             const afterPrefix = line.substring(prefixIdx + this.relayPrefix.length);
             // Pattern: Target [thread:project:id] body or Target [thread:id] body or Target body
@@ -296,6 +692,9 @@ export class PtyWrapper extends EventEmitter {
                 const [, target, body] = simpleMatch;
                 if (!body)
                     continue;
+                // Skip placeholder targets (documentation examples)
+                if (isPlaceholderTarget(target))
+                    continue;
                 // Parse target for cross-project syntax
                 const colonIdx = target.indexOf(':');
                 let to = target;
@@ -304,6 +703,9 @@ export class PtyWrapper extends EventEmitter {
                     project = target.substring(0, colonIdx);
                     to = target.substring(colonIdx + 1);
                 }
+                // Skip placeholder targets after parsing cross-project syntax
+                if (isPlaceholderTarget(to))
+                    continue;
                 this.sendRelayCommand({
                     to,
                     kind: 'message',
@@ -316,6 +718,9 @@ export class PtyWrapper extends EventEmitter {
             const [, target, threadProject, threadId, body] = targetMatch;
             if (!body)
                 continue;
+            // Skip placeholder targets (documentation examples)
+            if (isPlaceholderTarget(target))
+                continue;
             // Parse target for cross-project syntax
             const colonIdx = target.indexOf(':');
             let to = target;
@@ -324,6 +729,9 @@ export class PtyWrapper extends EventEmitter {
                 project = target.substring(0, colonIdx);
                 to = target.substring(colonIdx + 1);
             }
+            // Skip placeholder targets after parsing cross-project syntax
+            if (isPlaceholderTarget(to))
+                continue;
             this.sendRelayCommand({
                 to,
                 kind: 'message',
@@ -335,77 +743,204 @@ export class PtyWrapper extends EventEmitter {
             });
         }
     }
-    /**
-     * Strip ANSI escape codes from string.
-     * Converts cursor movements to spaces to preserve visual layout.
-     */
-    stripAnsi(str) {
-        // Convert cursor forward movements to spaces (CSI n C)
-        // \x1B[nC means move cursor right n columns
-        // eslint-disable-next-line no-control-regex
-        str = str.replace(/\x1B\[(\d+)C/g, (_m, n) => ' '.repeat(parseInt(n, 10) || 1));
-        // Convert single cursor right (CSI C) to space
-        // eslint-disable-next-line no-control-regex
-        str = str.replace(/\x1B\[C/g, ' ');
-        // Remove carriage returns (causes text overwriting issues)
-        str = str.replace(/\r(?!\n)/g, '');
-        // Strip remaining ANSI escape sequences (with \x1B prefix)
-        // eslint-disable-next-line no-control-regex
-        str = str.replace(/\x1B(?:\[[0-9;?]*[A-Za-z]|\].*?(?:\x07|\x1B\\)|[@-Z\\-_])/g, '');
-        // Strip orphaned CSI sequences that lost their escape byte
-        // These look like [?25h, [?2026l, [0m, etc. at the start of content
-        str = str.replace(/^\s*(\[\??\d*[A-Za-z])+\s*/g, '');
-        return str;
-    }
     /**
      * Send relay command to daemon
      */
     sendRelayCommand(cmd) {
         const msgHash = `${cmd.to}:${cmd.body}`;
         if (this.sentMessageHashes.has(msgHash)) {
+            console.log(`[pty:${this.config.name}] Skipping duplicate message to ${cmd.to}`);
             return;
         }
         if (this.client.state !== 'READY') {
+            console.log(`[pty:${this.config.name}] Cannot send to ${cmd.to} - relay not ready (state: ${this.client.state})`);
             return;
         }
         const success = this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread);
+        console.log(`[pty:${this.config.name}] Sent message to ${cmd.to}: ${success ? 'success' : 'failed'}`);
         if (success) {
             this.sentMessageHashes.add(msgHash);
+            // Dispatch message sent hook
+            this.hookRegistry.dispatchMessageSent(cmd.to, cmd.body, cmd.thread).catch(err => {
+                console.error(`[pty:${this.config.name}] Message sent hook error:`, err);
+            });
         }
     }
+    /** Valid CLI types for spawn commands */
+    static VALID_CLI_TYPES = new Set([
+        'claude', 'codex', 'gemini', 'droid', 'aider', 'cursor', 'cline', 'opencode',
+    ]);
+    /** Validate agent name format (PascalCase, alphanumeric, 2-30 chars) */
+    isValidAgentName(name) {
+        // Must start with uppercase letter, contain only alphanumeric chars
+        // Length 2-30 characters
+        return /^[A-Z][a-zA-Z0-9]{1,29}$/.test(name);
+    }
+    /** Validate CLI type */
+    isValidCliType(cli) {
+        return PtyWrapper.VALID_CLI_TYPES.has(cli.toLowerCase());
+    }
     /**
      * Parse spawn/release commands from output
      * Uses string-based parsing for robustness with PTY output.
+     * 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>>>
      * Delegates to dashboard API if dashboardPort is set (for nested spawns).
+     *
+     * STRICT VALIDATION:
+     * - Command must be at start of line (after whitespace)
+     * - Agent name must be PascalCase (e.g., Backend, Frontend, Worker1)
+     * - CLI must be a known type (claude, codex, gemini, etc.)
      */
     parseSpawnReleaseCommands(content) {
         // Need either API port or callbacks to handle spawn/release
-        const canSpawn = this.config.dashboardPort || this.config.onSpawn;
+        // Also check allowSpawn config - spawned workers should not spawn other agents
+        const spawnAllowed = this.config.allowSpawn !== false;
+        const canSpawn = spawnAllowed && (this.config.dashboardPort || this.config.onSpawn);
         const canRelease = this.config.dashboardPort || this.config.onRelease;
+        // Debug: always log spawn detection for debugging
+        if (content.includes('->relay:spawn')) {
+            console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] Spawn pattern detected in content`);
+            console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] canSpawn=${canSpawn} (allowSpawn=${spawnAllowed}, dashboardPort=${this.config.dashboardPort}, hasOnSpawn=${!!this.config.onSpawn})`);
+            // Log the actual lines containing spawn
+            const spawnLines = content.split('\n').filter(l => l.includes('->relay:spawn'));
+            spawnLines.forEach((line, i) => {
+                console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] Line ${i}: "${line.substring(0, 100)}"`);
+            });
+        }
+        // Debug: always log release detection for debugging
+        if (content.includes('->relay:release')) {
+            console.log(`[pty:${this.config.name}] [RELEASE-DEBUG] Release pattern detected in content`);
+            console.log(`[pty:${this.config.name}] [RELEASE-DEBUG] canRelease=${canRelease} (dashboardPort=${this.config.dashboardPort}, hasOnRelease=${!!this.config.onRelease})`);
+        }
         if (!canSpawn && !canRelease)
             return;
         const lines = content.split('\n');
         const spawnPrefix = '->relay:spawn';
         const releasePrefix = '->relay:release';
         for (const line of lines) {
-            // Check for spawn command
-            const spawnIdx = line.indexOf(spawnPrefix);
-            if (spawnIdx !== -1 && canSpawn) {
-                const afterSpawn = line.substring(spawnIdx + spawnPrefix.length).trim();
-                // Parse: WorkerName cli OR WorkerName cli "task" (task is optional)
+            let trimmed = line.trim();
+            // Strip bullet/prompt prefixes but PRESERVE the ->relay: pattern
+            // Look for ->relay: in the line and only strip what comes before it
+            const relayIdx = trimmed.indexOf('->relay:');
+            if (relayIdx > 0) {
+                // There's content before ->relay: - check if it's just prefix chars
+                const beforeRelay = trimmed.substring(0, relayIdx);
+                // Only strip if the prefix is just bullets/prompts/whitespace
+                if (/^[\s●•◦‣⁃⏺◆◇○□■│┃┆┇┊┋╎╏✦→➜›»$%#*]+$/.test(beforeRelay)) {
+                    const originalTrimmed = trimmed;
+                    trimmed = trimmed.substring(relayIdx);
+                    console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] Stripped prefix: "${originalTrimmed.substring(0, 60)}" -> "${trimmed.substring(0, 60)}"`);
+                }
+            }
+            // Skip escaped commands: \->relay:spawn should not trigger
+            if (trimmed.includes('\\->relay:')) {
+                continue;
+            }
+            // If we're in fenced spawn mode, accumulate lines until we see >>>
+            if (this.pendingFencedSpawn) {
+                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);
+                        console.log(`[pty:${this.config.name}] Spawn command (fenced): ${name} (${cli}) - "${taskStr.substring(0, 50)}..."`);
+                        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] <<<
+            // STRICT: Must be at start of line (after whitespace)
+            if (canSpawn && trimmed.startsWith(spawnPrefix)) {
+                const afterSpawn = trimmed.substring(spawnPrefix.length).trim();
+                console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] Detected spawn prefix, afterSpawn: "${afterSpawn.substring(0, 60)}"`);
+                // Check for fenced format: Name [cli] <<< (CLI optional, defaults to 'claude')
+                const fencedMatch = afterSpawn.match(/^(\S+)(?:\s+(\S+))?\s+<<<(.*)$/);
+                console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] Fenced match result: ${fencedMatch ? 'MATCHED' : 'NO MATCH'}`);
+                if (fencedMatch) {
+                    const [, name, cliOrUndefined, inlineContent] = fencedMatch;
+                    let cli = cliOrUndefined || 'claude';
+                    // STRICT: Validate agent name (PascalCase) and CLI type
+                    if (!this.isValidAgentName(name)) {
+                        console.warn(`[pty:${this.config.name}] Invalid agent name format, skipping: name=${name} (must be PascalCase)`);
+                        continue;
+                    }
+                    if (!this.isValidCliType(cli)) {
+                        console.warn(`[pty:${this.config.name}] Unknown CLI type, using default: cli=${cli}`);
+                        cli = 'claude';
+                    }
+                    // Check if fence closes on same line
+                    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);
+                            console.log(`[pty:${this.config.name}] Spawn command (fenced): ${name} (${cli}) - "${taskStr.substring(0, 50)}..."`);
+                            this.executeSpawn(name, cli, taskStr);
+                        }
+                    }
+                    else {
+                        // Start multi-line fenced mode - but only if not already processed
+                        const spawnKey = `${name}:${cli}`;
+                        if (this.processedSpawnCommands.has(spawnKey)) {
+                            // Already processed this spawn, skip the fenced capture
+                            continue;
+                        }
+                        this.pendingFencedSpawn = {
+                            name,
+                            cli,
+                            taskLines: inlineContent.trim() ? [inlineContent.trim()] : [],
+                        };
+                        console.log(`[pty:${this.config.name}] Starting fenced spawn capture: ${name} (${cli})`);
+                    }
+                    continue;
+                }
+                // Parse single-line format: WorkerName [cli] [task]
+                // CLI defaults to 'claude' if not provided
                 const parts = afterSpawn.split(/\s+/);
-                if (parts.length >= 2) {
+                if (parts.length >= 1) {
                     const name = parts[0];
-                    const cli = parts[1];
-                    // Task is everything after cli, potentially in quotes (optional)
+                    // CLI is optional - defaults to 'claude'
+                    let cli = parts[1] || 'claude';
+                    // Task is everything after cli (if cli was provided) or after name (if cli was omitted)
                     let task = '';
-                    if (parts.length >= 3) {
-                        const taskPart = parts.slice(2).join(' ');
+                    const taskStartIndex = parts[1] ? 2 : 1;
+                    if (parts.length > taskStartIndex) {
+                        const taskPart = parts.slice(taskStartIndex).join(' ');
                         // Remove surrounding quotes if present
                         const quoteMatch = taskPart.match(/^["'](.*)["']$/);
                         task = quoteMatch ? quoteMatch[1] : taskPart;
                     }
-                    if (name && cli) {
+                    if (name) {
+                        // STRICT: Validate agent name (PascalCase) and CLI type
+                        if (!this.isValidAgentName(name)) {
+                            // Don't log warning for documentation text - just silently skip
+                            continue;
+                        }
+                        if (!this.isValidCliType(cli)) {
+                            // Default CLI 'claude' should always be valid, but validate anyway
+                            console.warn(`[pty:${this.config.name}] Unknown CLI type, using default: cli=${cli}, defaulting to 'claude'`);
+                            cli = 'claude';
+                        }
                         const spawnKey = `${name}:${cli}`;
                         if (!this.processedSpawnCommands.has(spawnKey)) {
                             this.processedSpawnCommands.add(spawnKey);
@@ -416,13 +951,18 @@ export class PtyWrapper extends EventEmitter {
                 continue;
             }
             // Check for release command
-            const releaseIdx = line.indexOf(releasePrefix);
-            if (releaseIdx !== -1 && canRelease) {
-                const afterRelease = line.substring(releaseIdx + releasePrefix.length).trim();
-                const name = afterRelease.split(/\s+/)[0];
-                if (name && !this.processedReleaseCommands.has(name)) {
-                    this.processedReleaseCommands.add(name);
-                    this.executeRelease(name);
+            // STRICT: Must be at start of line (after whitespace)
+            if (trimmed.startsWith(releasePrefix)) {
+                console.log(`[pty:${this.config.name}] [RELEASE-DEBUG] Release prefix detected, canRelease=${canRelease}`);
+                if (canRelease) {
+                    const afterRelease = trimmed.substring(releasePrefix.length).trim();
+                    const name = afterRelease.split(/\s+/)[0];
+                    console.log(`[pty:${this.config.name}] [RELEASE-DEBUG] Parsed name: ${name}, isValidName=${name ? this.isValidAgentName(name) : false}, alreadyProcessed=${this.processedReleaseCommands.has(name)}`);
+                    // STRICT: Validate agent name format
+                    if (name && this.isValidAgentName(name) && !this.processedReleaseCommands.has(name)) {
+                        this.processedReleaseCommands.add(name);
+                        this.executeRelease(name);
+                    }
                 }
             }
         }
@@ -431,6 +971,8 @@ export class PtyWrapper extends EventEmitter {
      * Execute spawn via API or callback
      */
     async executeSpawn(name, cli, task) {
+        console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] executeSpawn called: name=${name}, cli=${cli}, task="${task.substring(0, 50)}..."`);
+        console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] dashboardPort=${this.config.dashboardPort}, hasOnSpawn=${!!this.config.onSpawn}`);
         if (this.config.dashboardPort) {
             // Use dashboard API for spawning (works from spawned agents)
             try {
@@ -468,7 +1010,7 @@ export class PtyWrapper extends EventEmitter {
         if (this.config.dashboardPort) {
             // Use dashboard API for releasing
             try {
-                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/spawned/${name}`, {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/spawned/${encodeURIComponent(name)}`, {
                     method: 'DELETE',
                 });
                 const result = await response.json();
@@ -498,11 +1040,67 @@ export class PtyWrapper extends EventEmitter {
      * @param originalTo - The original 'to' field from sender. '*' indicates this was a broadcast message.
      */
     handleIncomingMessage(from, payload, messageId, meta, originalTo) {
+        // Deduplicate: skip if we've already received this message
+        if (this.receivedMessageIds.has(messageId)) {
+            console.log(`[pty:${this.config.name}] Skipping duplicate message: ${messageId.substring(0, 8)}`);
+            return;
+        }
+        this.receivedMessageIds.add(messageId);
+        // Limit dedup set size to prevent memory leak
+        if (this.receivedMessageIds.size > 1000) {
+            const oldest = this.receivedMessageIds.values().next().value;
+            if (oldest)
+                this.receivedMessageIds.delete(oldest);
+        }
         this.messageQueue.push({ from, body: payload.body, messageId, thread: payload.thread, importance: meta?.importance, data: payload.data, originalTo });
         this.processMessageQueue();
+        // Dispatch message received hook
+        this.hookRegistry.dispatchMessageReceived(from, payload.body, messageId).catch(err => {
+            console.error(`[pty:${this.config.name}] Message received hook error:`, err);
+        });
+    }
+    /**
+     * Wait for output to stabilize before injection.
+     * Returns true if output has been stable for the required duration.
+     */
+    async waitForOutputStable() {
+        const startTime = Date.now();
+        let stablePolls = 0;
+        let lastBufferLength = this.rawBuffer.length;
+        while (Date.now() - startTime < INJECTION_CONSTANTS.STABILITY_TIMEOUT_MS) {
+            await sleep(INJECTION_CONSTANTS.STABILITY_POLL_MS);
+            const timeSinceOutput = Date.now() - this.lastOutputTime;
+            const bufferUnchanged = this.rawBuffer.length === lastBufferLength;
+            // Consider stable if no output for at least one poll interval
+            if (timeSinceOutput >= INJECTION_CONSTANTS.STABILITY_POLL_MS && bufferUnchanged) {
+                stablePolls++;
+                if (stablePolls >= INJECTION_CONSTANTS.REQUIRED_STABLE_POLLS) {
+                    return true;
+                }
+            }
+            else {
+                stablePolls = 0;
+                lastBufferLength = this.rawBuffer.length;
+            }
+        }
+        // Timeout - return true anyway to avoid blocking forever
+        console.warn(`[pty:${this.config.name}] Stability timeout, proceeding with injection`);
+        return true;
+    }
+    /**
+     * Check if the agent process is still alive and responsive.
+     */
+    isAgentAlive() {
+        return this.running && this.ptyProcess !== undefined;
     }
     /**
-     * Process queued messages
+     * Process queued messages with reliability improvements:
+     * 1. Wait for output stability before injection
+     * 2. Verify injection appeared in output
+     * 3. Retry with backoff on failure
+     * 4. Fall back to logging on complete failure
+     *
+     * Uses shared injection logic with PTY-specific callbacks.
      */
     async processMessageQueue() {
         // Wait until instructions have been injected and agent is ready
@@ -510,8 +1108,11 @@ export class PtyWrapper extends EventEmitter {
             return;
         if (this.isInjecting || this.messageQueue.length === 0)
             return;
-        if (!this.ptyProcess || !this.running)
+        // Health check: is agent still alive?
+        if (!this.isAgentAlive()) {
+            console.error(`[pty:${this.config.name}] Agent not alive, cannot inject messages`);
             return;
+        }
         this.isInjecting = true;
         const msg = this.messageQueue.shift();
         if (!msg) {
@@ -519,31 +1120,68 @@ export class PtyWrapper extends EventEmitter {
             return;
         }
         try {
-            const shortId = msg.messageId.substring(0, 8);
-            // Strip ANSI escape sequences and orphaned control sequences from message body
-            const sanitizedBody = this.stripAnsi(msg.body).replace(/[\r\n]+/g, ' ').trim();
-            // Thread/importance/channel hints to match tmux-wrapper format
-            const threadHint = msg.thread ? ` [thread:${msg.thread}]` : '';
-            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
-            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(', ')}]`;
+            // Wait for output to stabilize before injecting
+            await this.waitForOutputStable();
+            // For Gemini: check if at shell prompt, skip injection to avoid shell execution
+            if (this.cliType === 'gemini') {
+                const recentOutput = this.rawBuffer.slice(-200);
+                const lastLine = recentOutput.split('\n').filter(l => l.trim()).pop() || '';
+                if (CLI_QUIRKS.isShellPrompt(lastLine)) {
+                    console.log(`[pty:${this.config.name}] Gemini at shell prompt, re-queuing message`);
+                    this.messageQueue.unshift(msg);
+                    this.isInjecting = false;
+                    setTimeout(() => this.processMessageQueue(), 2000);
+                    return;
+                }
+            }
+            // Build injection string using shared utility
+            let injection = buildInjectionString(msg);
+            // Gemini-specific: wrap in backticks to prevent shell keyword interpretation
+            if (this.cliType === 'gemini') {
+                // Extract the message body part and wrap it
+                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);
                 }
             }
-            const injection = `Relay message from ${msg.from} [${shortId}]${threadHint}${importanceHint}${channelHint}${attachmentHint}: ${sanitizedBody}`;
-            // Write message to PTY, then send Enter separately after a small delay
-            // This matches how TmuxWrapper does it for better CLI compatibility
-            this.ptyProcess.write(injection);
-            await this.sleep(50);
-            this.ptyProcess.write('\r');
+            const shortId = msg.messageId.substring(0, 8);
+            // Create callbacks for shared injection logic
+            const callbacks = {
+                getOutput: async () => {
+                    // Look at last 2000 chars to avoid scanning entire buffer
+                    return this.rawBuffer.slice(-2000);
+                },
+                performInjection: async (inj) => {
+                    if (!this.ptyProcess || !this.running) {
+                        throw new Error('PTY process not running');
+                    }
+                    // Write message to PTY, then send Enter separately after a small delay
+                    this.ptyProcess.write(inj);
+                    await sleep(INJECTION_CONSTANTS.ENTER_DELAY_MS);
+                    this.ptyProcess.write('\r');
+                },
+                log: (message) => console.log(`[pty:${this.config.name}] ${message}`),
+                logError: (message) => console.error(`[pty:${this.config.name}] ${message}`),
+                getMetrics: () => this.injectionMetrics,
+                // Skip verification for PTY-based injection - CLIs don't echo input back
+                // so verification will always fail. Trust that pty.write() succeeds.
+                skipVerification: true,
+            };
+            // Inject with retry and verification using shared logic
+            const result = await sharedInjectWithRetry(injection, shortId, msg.from, callbacks);
+            if (!result.success) {
+                // Log the failed message for debugging/recovery
+                console.error(`[pty:${this.config.name}] Message delivery failed after ${result.attempts} attempts: ` +
+                    `from=${msg.from} id=${shortId}`);
+                // Emit event for external monitoring (e.g., dashboard)
+                this.emit('injection-failed', {
+                    messageId: msg.messageId,
+                    from: msg.from,
+                    attempts: result.attempts,
+                });
+            }
         }
         catch (err) {
             console.error(`[pty:${this.config.name}] Injection failed: ${err.message}`);
@@ -552,24 +1190,34 @@ export class PtyWrapper extends EventEmitter {
             this.isInjecting = false;
             // Process next message if any
             if (this.messageQueue.length > 0) {
-                setTimeout(() => this.processMessageQueue(), 500);
+                setTimeout(() => this.processMessageQueue(), INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MS);
             }
         }
     }
     /**
-     * Inject usage instructions
+     * Queue minimal agent identity notification as the first message.
+     *
+     * Full protocol instructions are in ~/.claude/CLAUDE.md (set up by entrypoint.sh).
+     * We only inject a brief identity message here to let the agent know its name
+     * and that it's connected to the relay.
      */
     injectInstructions() {
-        if (!this.running || !this.ptyProcess)
+        if (!this.running)
+            return;
+        // Guard: Only inject once per session
+        if (this.instructionsInjected) {
+            console.log(`[pty:${this.config.name}] Init instructions already injected, skipping`);
             return;
-        const escapedPrefix = '\\' + this.relayPrefix;
-        const instructions = `[Agent Relay] You are "${this.config.name}" - connected for real-time messaging. SEND: ${escapedPrefix}AgentName message. PROTOCOL: (1) Wait for task via relay. (2) ACK receipt before starting. (3) Send "DONE: <summary>" when complete, then wait for next task.`;
-        try {
-            this.ptyProcess.write(instructions + '\r');
-        }
-        catch {
-            // Silent fail
         }
+        this.instructionsInjected = true;
+        // Minimal notification - full protocol is in ~/.claude/CLAUDE.md
+        const notification = `You are agent "${this.config.name}" connected to Agent Relay. See CLAUDE.md for the messaging protocol. ACK messages, do work, send DONE when complete.`;
+        // Queue as first message from "system" - will be injected when CLI is ready
+        this.messageQueue.unshift({
+            from: 'system',
+            body: notification,
+            messageId: `init-${Date.now()}`,
+        });
     }
     /**
      * Write directly to the PTY
@@ -597,38 +1245,73 @@ export class PtyWrapper extends EventEmitter {
     /**
      * Stop the agent process
      */
-    stop() {
+    async stop() {
         if (!this.running)
             return;
         this.running = false;
+        // Auto-save continuity state before stopping
+        // Pass sessionEndData to populate handoff (fixes empty handoff issue)
+        if (this.continuity) {
+            try {
+                await this.continuity.autoSave(this.config.name, 'session_end', this.sessionEndData);
+            }
+            catch (err) {
+                console.error(`[pty:${this.config.name}] Continuity auto-save failed:`, err);
+            }
+        }
+        // Dispatch session end hook (handles trajectory completion)
+        try {
+            await this.hookRegistry.dispatchSessionEnd(0, true);
+        }
+        catch (err) {
+            console.error(`[pty:${this.config.name}] Session end hook error:`, err);
+        }
         if (this.ptyProcess) {
             // Try graceful termination first
             this.ptyProcess.write('\x03'); // Ctrl+C
-            setTimeout(() => {
-                if (this.ptyProcess) {
-                    this.ptyProcess.kill();
-                }
-            }, 1000);
+            await sleep(1000);
+            if (this.ptyProcess) {
+                this.ptyProcess.kill();
+            }
         }
         this.closeLogStream();
         this.client.destroy();
+        this.hookRegistry.destroy();
     }
     /**
      * Kill the process immediately
      */
-    kill() {
+    async kill() {
         this.running = false;
+        // Auto-save continuity state before killing (with timeout to avoid hanging)
+        // Pass sessionEndData if available (may have been parsed before kill)
+        if (this.continuity) {
+            try {
+                await Promise.race([
+                    this.continuity.autoSave(this.config.name, 'crash', this.sessionEndData),
+                    sleep(2000), // 2s timeout for crash saves
+                ]);
+            }
+            catch (err) {
+                console.error(`[pty:${this.config.name}] Continuity auto-save failed:`, err);
+            }
+        }
+        // Dispatch session end hook (forced termination, with timeout)
+        try {
+            await Promise.race([
+                this.hookRegistry.dispatchSessionEnd(undefined, false),
+                sleep(1000), // 1s timeout for hooks on kill
+            ]);
+        }
+        catch (err) {
+            console.error(`[pty:${this.config.name}] Session end hook error:`, err);
+        }
         if (this.ptyProcess) {
             this.ptyProcess.kill();
         }
         this.closeLogStream();
         this.client.destroy();
-    }
-    /**
-     * Sleep helper
-     */
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+        this.hookRegistry.destroy();
     }
     /**
      * Close the log file stream
@@ -652,5 +1335,159 @@ export class PtyWrapper extends EventEmitter {
     get logPath() {
         return this.logFilePath;
     }
+    /**
+     * Track significant outputs and inject summary reminder if needed.
+     * Works with any CLI (Claude, Gemini, Codex, etc.)
+     */
+    trackOutputAndRemind(data) {
+        // Disabled if config.summaryReminder === false or env RELAY_SUMMARY_REMINDER_ENABLED=false
+        if (this.config.summaryReminder === false)
+            return;
+        if (process.env.RELAY_SUMMARY_REMINDER_ENABLED === 'false')
+            return;
+        const config = this.config.summaryReminder ?? {};
+        // Env vars take precedence over config, config takes precedence over defaults
+        const intervalMinutes = process.env.RELAY_SUMMARY_INTERVAL_MINUTES
+            ? parseInt(process.env.RELAY_SUMMARY_INTERVAL_MINUTES, 10)
+            : (config.intervalMinutes ?? 15);
+        const minOutputs = process.env.RELAY_SUMMARY_MIN_OUTPUTS
+            ? parseInt(process.env.RELAY_SUMMARY_MIN_OUTPUTS, 10)
+            : (config.minOutputs ?? 50);
+        // Only count "significant" outputs (more than just whitespace/control chars)
+        const cleanData = stripAnsi(data).trim();
+        if (cleanData.length > 20) {
+            this.outputsSinceSummary++;
+        }
+        // Check if we should remind
+        const minutesSinceSummary = (Date.now() - this.lastSummaryTime) / (1000 * 60);
+        const shouldRemind = minutesSinceSummary >= intervalMinutes &&
+            this.outputsSinceSummary >= minOutputs;
+        if (shouldRemind && this.running && this.ptyProcess) {
+            // Reset counters before injecting (prevent spam)
+            this.lastSummaryTime = Date.now();
+            this.outputsSinceSummary = 0;
+            // Inject reminder as a relay-style message
+            // IMPORTANT: Must be single-line - embedded newlines cause the message to span
+            // multiple lines in the CLI input buffer, and the final Enter only submits
+            // the last (empty) line. Regular relay messages are also single-line (see buildInjectionString).
+            const reminder = `[Agent Relay] It's been ${Math.round(minutesSinceSummary)} minutes. Please output a [[SUMMARY]] block to checkpoint your progress: [[SUMMARY]]{"currentTask": "...", "completedTasks": [...], "context": "..."}[[/SUMMARY]]`;
+            // Delay slightly to not interrupt current output, then write + Enter
+            setTimeout(async () => {
+                if (this.ptyProcess && this.running) {
+                    this.ptyProcess.write(reminder);
+                    await sleep(INJECTION_CONSTANTS.ENTER_DELAY_MS);
+                    this.ptyProcess.write('\r');
+                }
+            }, 1000);
+        }
+    }
+    /**
+     * Check for [[SUMMARY]] blocks and emit 'summary' event.
+     * Allows cloud services to persist summaries without hardcoding storage.
+     * Also updates the local continuity ledger for session recovery.
+     */
+    checkForSummaryAndEmit(content) {
+        const result = parseSummaryWithDetails(content);
+        // No SUMMARY block found
+        if (!result.found)
+            return;
+        // Dedup based on raw content - prevents repeated event emissions for same summary
+        if (result.rawContent === this.lastSummaryRawContent)
+            return;
+        this.lastSummaryRawContent = result.rawContent || '';
+        // Reset reminder counters on any summary (even invalid JSON)
+        this.lastSummaryTime = Date.now();
+        this.outputsSinceSummary = 0;
+        // Invalid JSON - log warning
+        if (!result.valid) {
+            console.warn(`[pty:${this.config.name}] Invalid JSON in SUMMARY block`);
+            return;
+        }
+        const summary = result.summary;
+        // Save to local continuity ledger for session recovery
+        // This ensures the ledger has actual data instead of placeholders
+        if (this.continuity) {
+            this.saveSummaryToLedger(summary).catch(err => {
+                console.error(`[pty:${this.config.name}] Failed to save summary to ledger:`, err);
+            });
+        }
+        // Emit event for external handlers (cloud services, dashboard, etc.)
+        this.emit('summary', {
+            agentName: this.config.name,
+            summary,
+        });
+    }
+    /**
+     * 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);
+            console.log(`[pty:${this.config.name}] Saved summary to continuity ledger`);
+        }
+    }
+    /**
+     * Check for [[SESSION_END]] blocks and emit 'session-end' event.
+     * Allows cloud services to handle session closure without hardcoding storage.
+     * Also stores the data for use in autoSave to populate handoff.
+     */
+    checkForSessionEndAndEmit(content) {
+        if (this.sessionEndProcessed)
+            return; // Only emit once per session
+        const sessionEnd = parseSessionEndFromOutput(content);
+        if (!sessionEnd)
+            return;
+        this.sessionEndProcessed = true;
+        // Store SESSION_END data for use in autoSave (fixes empty handoff issue)
+        this.sessionEndData = sessionEnd;
+        // Emit event for external handlers
+        this.emit('session-end', {
+            agentName: this.config.name,
+            marker: sessionEnd,
+        });
+    }
+    /**
+     * Reset session-specific state for wrapper reuse.
+     * Call this when starting a new session with the same wrapper instance.
+     */
+    resetSessionState() {
+        this.sessionEndProcessed = false;
+        this.lastSummaryRawContent = '';
+        this.sessionEndData = undefined;
+    }
+    /**
+     * Get injection reliability metrics
+     */
+    getInjectionMetrics() {
+        return {
+            ...this.injectionMetrics,
+            successRate: calculateSuccessRate(this.injectionMetrics),
+        };
+    }
+    /**
+     * Get count of pending messages in queue
+     */
+    get pendingMessageCount() {
+        return this.messageQueue.length;
+    }
 }
 //# sourceMappingURL=pty-wrapper.js.map