Enhance trajectory integration for tmux and pty wrappers

- Add TrajectoryIntegration class with lifecycle methods
- Auto-start trajectory when agents spawn with a task
- Record incoming/outgoing messages in trajectory
- Auto-detect PDERO phase transitions from output
- Complete trajectory on graceful stop, abandon on kill
- Inject compact trail instructions to agents
- Set trail environment variables for CLI access

Author: claude

src/trajectory/integration.ts

@@ -6,9 +6,15 @@
  *
  * This module provides a bridge between agent-relay and the
  * external `trail` CLI / agent-trajectories library.
+ *
+ * Key integration points:
+ * - Auto-starts trajectory when agent is instantiated with a task
+ * - Records all inter-agent messages
+ * - Auto-detects PDERO phase transitions from output
+ * - Provides hooks for key agent lifecycle events
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, execSync } from 'node:child_process';
 import { getProjectPaths } from '../utils/project-namespace.js';
 
 /**
@@ -280,12 +286,21 @@ export function detectPhaseFromContent(content: string): PDEROPhase | undefined
 
 /**
  * TrajectoryIntegration class for managing trajectory state
+ *
+ * This class enforces trajectory tracking during agent lifecycle:
+ * - Auto-starts trajectory when agent is instantiated with a task
+ * - Records all inter-agent messages
+ * - Auto-detects PDERO phase transitions
+ * - Provides lifecycle hooks for tmux/pty wrappers
  */
 export class TrajectoryIntegration {
   private projectId: string;
   private agentName: string;
   private trailAvailable: boolean | null = null;
   private currentPhase: PDEROPhase | null = null;
+  private trajectoryId: string | null = null;
+  private initialized = false;
+  private task: string | null = null;
 
   constructor(projectId: string, agentName: string) {
     this.projectId = projectId;
@@ -302,6 +317,43 @@ export class TrajectoryIntegration {
     return this.trailAvailable;
   }
 
+  /**
+   * Check if trail CLI is installed synchronously
+   */
+  isTrailInstalledSync(): boolean {
+    try {
+      execSync('which trail', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Initialize trajectory tracking for agent lifecycle
+   * Called automatically when agent starts with a task
+   */
+  async initialize(task?: string, taskId?: string, source?: string): Promise<boolean> {
+    if (this.initialized) return true;
+
+    if (!(await this.isAvailable())) {
+      return false;
+    }
+
+    // If task provided, auto-start trajectory
+    if (task) {
+      const success = await this.start(task, taskId, source);
+      if (success) {
+        this.initialized = true;
+        this.task = task;
+      }
+      return success;
+    }
+
+    this.initialized = true;
+    return true;
+  }
+
   /**
    * Start tracking a trajectory
    */
@@ -318,11 +370,34 @@ export class TrajectoryIntegration {
 
     if (result.success) {
       this.currentPhase = 'plan';
+      this.trajectoryId = result.trajectoryId || null;
+      this.task = task;
     }
 
     return result.success;
   }
 
+  /**
+   * Check if there's an active trajectory
+   */
+  hasActiveTrajectory(): boolean {
+    return this.currentPhase !== null;
+  }
+
+  /**
+   * Get the current task
+   */
+  getTask(): string | null {
+    return this.task;
+  }
+
+  /**
+   * Get trajectory ID
+   */
+  getTrajectoryId(): string | null {
+    return this.trajectoryId;
+  }
+
   /**
    * Record a message
    */
@@ -433,3 +508,63 @@ export function getTrajectoryIntegration(projectId: string, agentName: string):
   }
   return instance;
 }
+
+/**
+ * Generate trail usage instructions for agents
+ */
+export function getTrailInstructions(): string[] {
+  return [
+    '📍 TRAJECTORY TRACKING (PDERO Paradigm)',
+    '',
+    'You MUST use trail commands to track your work:',
+    '',
+    'PHASES: plan → design → execute → review → observe',
+    '',
+    'COMMANDS:',
+    '  trail start "task"           Start trajectory for a task',
+    '  trail phase <phase>          Transition to new phase',
+    '  trail decision "choice"      Record key decisions',
+    '  trail event "what happened"  Log significant events',
+    '  trail complete               Complete with summary',
+    '',
+    'WHEN TO USE:',
+    '  - Start: At beginning of any task',
+    '  - Phase: When shifting focus (planning→implementing, etc.)',
+    '  - Decision: For architecture/approach choices',
+    '  - Event: For tool calls, errors, milestones',
+    '  - Complete: When task is done',
+    '',
+    'Example workflow:',
+    '  trail start "Implement auth feature"',
+    '  trail phase design',
+    '  trail decision "Use JWT" --reasoning "Stateless, scalable"',
+    '  trail phase execute',
+    '  trail event "Created auth middleware"',
+    '  trail phase review',
+    '  trail event "All tests passing"',
+    '  trail complete --summary "Auth implemented" --confidence 0.9',
+  ];
+}
+
+/**
+ * Get a compact trail instruction string for injection
+ */
+export function getCompactTrailInstructions(): string {
+  return [
+    '[TRAIL] Track work with PDERO: plan→design→execute→review→observe.',
+    'Commands: trail start "task" | trail phase <phase> | trail decision "choice" | trail event "log" | trail complete',
+    'Use trail often to document your thought process.',
+  ].join(' ');
+}
+
+/**
+ * Get environment variables for trail CLI
+ */
+export function getTrailEnvVars(projectId: string, agentName: string, dataDir: string): Record<string, string> {
+  return {
+    TRAJECTORIES_PROJECT: projectId,
+    TRAJECTORIES_DATA_DIR: dataDir,
+    TRAJECTORIES_AGENT: agentName,
+    TRAIL_AUTO_PHASE: '1', // Enable auto phase detection
+  };
+}

src/wrapper/pty-wrapper.ts

@@ -13,6 +13,15 @@ import { EventEmitter } from 'node:events';
 import { RelayClient } from './client.js';
 import type { ParsedCommand } from './parser.js';
 import type { SendPayload, SpeakOnTrigger } from '../protocol/types.js';
+import { getProjectPaths } from '../utils/project-namespace.js';
+import {
+  TrajectoryIntegration,
+  getTrajectoryIntegration,
+  getTrailEnvVars,
+  getCompactTrailInstructions,
+  detectPhaseFromContent,
+  type PDEROPhase,
+} from '../trajectory/integration.js';
 
 /** Maximum lines to keep in output buffer */
 const MAX_BUFFER_LINES = 10000;
@@ -42,6 +51,8 @@ export interface PtyWrapperConfig {
   shadowSpeakOn?: SpeakOnTrigger[];
   /** Stream output to daemon for dashboard log viewing (default: true) */
   streamLogs?: boolean;
+  /** Task/role description for trajectory tracking */
+  task?: string;
 }
 
 export interface PtyWrapperEvents {
@@ -67,6 +78,8 @@ export class PtyWrapper extends EventEmitter {
   private logFilePath?: string;
   private logStream?: fs.WriteStream;
   private hasAcceptedPrompt = false;
+  private trajectory?: TrajectoryIntegration; // Trajectory tracking via trail
+  private lastDetectedPhase?: PDEROPhase;
 
   constructor(config: PtyWrapperConfig) {
     super();
@@ -81,6 +94,10 @@ export class PtyWrapper extends EventEmitter {
       quiet: true,
     });
 
+    // Initialize trajectory tracking
+    const projectPaths = getProjectPaths();
+    this.trajectory = getTrajectoryIntegration(projectPaths.projectId, config.name);
+
     // Handle incoming messages
     this.client.onMessage = (from: string, payload: SendPayload, messageId: string) => {
       this.handleIncomingMessage(from, payload, messageId);
@@ -131,6 +148,10 @@ export class PtyWrapper extends EventEmitter {
     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, {
@@ -141,6 +162,7 @@ export class PtyWrapper extends EventEmitter {
         env: {
           ...process.env,
           ...this.config.env,
+          ...trailEnvVars,
           AGENT_RELAY_NAME: this.config.name,
           TERM: 'xterm-256color',
         },
@@ -152,6 +174,15 @@ export class PtyWrapper extends EventEmitter {
       throw spawnError;
     }
 
+    // Initialize trajectory (auto-start if task provided)
+    if (this.config.task) {
+      this.trajectory?.initialize(this.config.task).then(success => {
+        if (success) {
+          console.log(`[pty:${this.config.name}] Trajectory started for task: ${this.config.task}`);
+        }
+      });
+    }
+
     this.running = true;
 
     // Capture output
@@ -215,6 +246,24 @@ export class PtyWrapper extends EventEmitter {
 
     // Parse for relay commands
     this.parseRelayCommands();
+
+    // Auto-detect phase transitions from output
+    this.detectAndTransitionPhase(data);
+  }
+
+  /**
+   * Detect PDERO phase from output and transition if needed
+   */
+  private detectAndTransitionPhase(data: string): void {
+    if (!this.trajectory) return;
+
+    const cleanData = this.stripAnsi(data);
+    const detectedPhase = detectPhaseFromContent(cleanData);
+
+    if (detectedPhase && detectedPhase !== this.lastDetectedPhase) {
+      this.lastDetectedPhase = detectedPhase;
+      this.trajectory.transition(detectedPhase, 'Auto-detected from output');
+    }
   }
 
   /**
@@ -386,6 +435,9 @@ export class PtyWrapper extends EventEmitter {
     const success = this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread);
     if (success) {
       this.sentMessageHashes.add(msgHash);
+
+      // Record outgoing message in trajectory
+      this.trajectory?.message('sent', this.config.name, cmd.to, cmd.body);
     }
   }
 
@@ -514,6 +566,9 @@ export class PtyWrapper extends EventEmitter {
   private handleIncomingMessage(from: string, payload: SendPayload, messageId: string): void {
     this.messageQueue.push({ from, body: payload.body, messageId });
     this.processMessageQueue();
+
+    // Record incoming message in trajectory
+    this.trajectory?.message('received', from, this.config.name, payload.body);
   }
 
   /**
@@ -562,7 +617,14 @@ export class PtyWrapper extends EventEmitter {
     if (!this.running || !this.ptyProcess) return;
 
     const escapedPrefix = '\\' + this.relayPrefix;
-    const instructions = `[Agent Relay] You are "${this.config.name}" - connected for real-time messaging. SEND: ${escapedPrefix}AgentName message`;
+    const relayInstruction = `[Agent Relay] You are "${this.config.name}" - connected for real-time messaging. SEND: ${escapedPrefix}AgentName message`;
+
+    // Include trail instructions if available
+    const trailInstruction = this.trajectory?.isTrailInstalledSync()
+      ? ` ${getCompactTrailInstructions()}`
+      : '';
+
+    const instructions = relayInstruction + trailInstruction;
 
     try {
       this.ptyProcess.write(instructions + '\r');
@@ -604,6 +666,11 @@ export class PtyWrapper extends EventEmitter {
     if (!this.running) return;
     this.running = false;
 
+    // Complete trajectory with summary
+    this.trajectory?.complete({
+      summary: `Agent ${this.config.name} stopped gracefully`,
+    });
+
     if (this.ptyProcess) {
       // Try graceful termination first
       this.ptyProcess.write('\x03'); // Ctrl+C
@@ -623,6 +690,10 @@ export class PtyWrapper extends EventEmitter {
    */
   kill(): void {
     this.running = false;
+
+    // Abandon trajectory (forced termination)
+    this.trajectory?.abandon(`Agent ${this.config.name} killed`);
+
     if (this.ptyProcess) {
       this.ptyProcess.kill();
     }