@agentmeshhq/agent 0.2.0 → 0.3.0

package/src/core/daemon.ts

@@ -1,1317 +0,0 @@
-import { type ChildProcess, execSync, spawn } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import {
-  addAgentToState,
-  getAgentState,
-  loadConfig,
-  resetAgentRestartCount,
-  updateAgentInState,
-} from "../config/loader.js";
-import type { AgentConfig, AgentStatus, Config } from "../config/schema.js";
-import { loadContext, loadOrCreateContext, saveContext } from "../context/index.js";
-import { Heartbeat } from "./heartbeat.js";
-import { handleWebSocketEvent, injectRestoredContext, injectStartupMessage } from "./injector.js";
-import { checkInbox, fetchAssignments, registerAgent, type ServerContext } from "./registry.js";
-import { buildRunnerConfig, getRunnerDisplayName, type RunnerConfig } from "./runner.js";
-import { DockerSandbox } from "./sandbox.js";
-import { getLatestSessionId, snapshotSessionId, waitForNewSessionId } from "./session-id.js";
-import {
-  captureSessionContext,
-  captureSessionOutput,
-  createSession,
-  destroySession,
-  getSessionName,
-  isSessionHealthy,
-  sessionExists,
-  updateSessionEnvironment,
-} from "./tmux.js";
-import {
-  checkAgentProgress,
-  cleanupOrphanContainers,
-  isProcessRunning,
-  sendNudge,
-} from "./watchdog.js";
-import { AgentWebSocket } from "./websocket.js";
-
-// Maximum number of auto-restart attempts
-const MAX_RESTART_ATTEMPTS = 3;
-// Time after which restart count resets (30 minutes of stable operation)
-const RESTART_COUNT_RESET_MS = 30 * 60 * 1000;
-// Time to wait after nudging before restarting (2 minutes)
-const NUDGE_WAIT_MS = 2 * 60 * 1000;
-
-// Path to the sandbox OpenCode config (permissive permissions)
-const SANDBOX_OPENCODE_CONFIG_PATH = path.join(os.homedir(), ".agentmesh", "opencode-sandbox.json");
-
-// Sandbox OpenCode config content - allow everything since container is sandboxed
-const SANDBOX_OPENCODE_CONFIG = {
-  $schema: "https://opencode.ai/config.json",
-  permission: "allow",
-};
-
-export interface DaemonOptions {
-  name: string;
-  command?: string;
-  workdir?: string;
-  model?: string;
-  daemonize?: boolean;
-  /** Whether to restore context from previous session (default: false) */
-  restoreContext?: boolean;
-  /** Only send nudges/restart for worker agents (default: false) */
-  worker?: boolean;
-  /** Auto-clone repository for project assignments */
-  autoSetup?: boolean;
-  /** Run opencode serve instead of tmux TUI (for Integration Service) */
-  serve?: boolean;
-  /** Port for opencode serve (default: 3001) */
-  servePort?: number;
-  /** Run agent in Docker sandbox container */
-  sandbox?: boolean;
-  /** Docker image for sandbox (default: agentmesh/agent-sandbox:latest) */
-  sandboxImage?: string;
-  /** CPU limit for sandbox (default: 1) */
-  sandboxCpu?: string;
-  /** Memory limit for sandbox (default: 2g) */
-  sandboxMemory?: string;
-}
-
-export class AgentDaemon {
-  private agentName: string;
-  private config: Config;
-  private agentConfig: AgentConfig;
-  private runnerConfig: RunnerConfig;
-  private ws: AgentWebSocket | null = null;
-  private heartbeat: Heartbeat | null = null;
-  private token: string | null = null;
-  private agentId: string | null = null;
-  private isRunning = false;
-  private assignedProject: string | undefined;
-  private shouldRestoreContext: boolean;
-  private isWorkerAgent: boolean;
-  private autoSetup: boolean;
-  private serveMode: boolean;
-  private servePort: number;
-  private serveProcess: ChildProcess | null = null;
-  private sandboxMode: boolean;
-  private sandboxImage: string;
-  private sandboxCpu: string;
-  private sandboxMemory: string;
-  private sandbox: DockerSandbox | null = null;
-  private healthCheckInterval: ReturnType<typeof setInterval> | null = null;
-  private serverContext: ServerContext | undefined;
-  // Session resume tracking
-  private _preStartSessionId: string | null | undefined;
-  private _attemptedResumeSessionId: string | undefined;
-  // Auto-restart tracking
-  private restartCount = 0;
-  private lastStableTime: Date | null = null;
-  private stuckSince: Date | null = null;
-  private nudgeSentAt: Date | null = null;
-
-  constructor(options: DaemonOptions) {
-    const config = loadConfig();
-    if (!config) {
-      throw new Error("No config found. Run 'agentmesh init' first.");
-    }
-
-    // Ensure config has required fields with defaults
-    if (!config.agents) config.agents = [];
-    if (!config.defaults) config.defaults = { command: "opencode", model: "claude-sonnet-4-5-20250929" };
-
-    this.config = config;
-    this.agentName = options.name;
-    this.shouldRestoreContext = options.restoreContext === true;
-    this.isWorkerAgent = options.worker === true;
-    this.autoSetup = options.autoSetup === true;
-
-    // Find or create agent config
-    let agentConfig = config.agents.find((a) => a.name === options.name);
-
-    if (!agentConfig) {
-      agentConfig = {
-        name: options.name,
-        command: options.command || config.defaults.command,
-        workdir: options.workdir,
-        model: options.model || config.defaults.model,
-      };
-    }
-
-    // Override with provided options
-    if (options.command) agentConfig.command = options.command;
-    if (options.workdir) agentConfig.workdir = options.workdir;
-    if (options.model) agentConfig.model = options.model;
-
-    this.agentConfig = agentConfig;
-    this.serveMode = options.serve === true;
-    this.servePort = options.servePort || 3001;
-    this.sandboxMode = options.sandbox === true;
-    this.sandboxImage = options.sandboxImage || "agentmesh/agent-sandbox:latest";
-    this.sandboxCpu = options.sandboxCpu || "1";
-    this.sandboxMemory = options.sandboxMemory || "2g";
-
-    // Build runner configuration with model resolution
-    this.runnerConfig = buildRunnerConfig({
-      cliModel: options.model,
-      agentModel: agentConfig.model,
-      defaultModel: config.defaults.model,
-      command: agentConfig.command,
-    });
-
-    const runnerName = getRunnerDisplayName(this.runnerConfig.type);
-    console.log(`Runner: ${runnerName}`);
-    console.log(`Effective model: ${this.runnerConfig.model}`);
-  }
-
-  async start(): Promise<void> {
-    if (this.isRunning) {
-      console.error("Daemon already running");
-      return;
-    }
-
-    console.log(`Starting agent: ${this.agentName}`);
-
-    // Check for duplicate process
-    const existingState = getAgentState(this.agentName);
-    if (existingState && existingState.pid > 0) {
-      if (isProcessRunning(existingState.pid)) {
-        throw new Error(
-          `Agent "${this.agentName}" is already running (PID: ${existingState.pid}). ` +
-            `Use 'agentmesh stop ${this.agentName}' first.`,
-        );
-      }
-      // Process not running, clean up stale state
-      console.log(`Cleaning up stale state for PID ${existingState.pid}`);
-    }
-
-    // Clean up orphan containers in sandbox mode
-    if (this.sandboxMode) {
-      const cleaned = cleanupOrphanContainers(this.agentName);
-      if (cleaned > 0) {
-        console.log(`Cleaned up ${cleaned} orphan container(s)`);
-      }
-    }
-
-    // Reset restart count on manual start
-    this.restartCount = 0;
-    this.lastStableTime = new Date();
-
-    // Register with hub first (needed for assignment check)
-    console.log("Registering with AgentMesh hub...");
-    console.log(`Existing state: ${existingState ? `agentId=${existingState.agentId}` : "none"}`);
-
-    const registration = await registerAgent({
-      url: this.config.hubUrl,
-      apiKey: this.config.apiKey,
-      workspace: this.config.workspace,
-      agentId: existingState?.agentId || this.agentConfig.agentId,
-      agentName: this.agentName,
-      model: this.agentConfig.model || this.config.defaults.model,
-      restoreContext: this.shouldRestoreContext,
-    });
-
-    this.agentId = registration.agentId;
-    this.token = registration.token;
-
-    if (registration.status === "re-registered") {
-      console.log(`Re-registered as: ${this.agentId}`);
-      if (registration.context && Object.keys(registration.context).length > 0) {
-        this.serverContext = registration.context;
-        console.log(`Server context restored: ${Object.keys(registration.context).join(", ")}`);
-      }
-    } else {
-      console.log(`Registered as: ${this.agentId}`);
-    }
-
-    // Check assignments and auto-setup workdir if needed (before creating tmux session)
-    await this.checkAssignments();
-
-    // Choose runtime mode: sandbox > serve > tmux
-    if (this.sandboxMode) {
-      await this.startSandboxMode();
-    } else if (this.serveMode) {
-      await this.startServeMode();
-    } else {
-      // Check if session already exists
-      const sessionName = getSessionName(this.agentName);
-      const sessionAlreadyExists = sessionExists(sessionName);
-
-      // Create tmux session if it doesn't exist
-      if (!sessionAlreadyExists) {
-        // Load saved context to check for OpenCode session ID (for native resume)
-        let savedSessionId: string | undefined;
-        if (this.shouldRestoreContext && this.agentId) {
-          const savedContext = loadContext(this.agentId);
-          savedSessionId = savedContext?.custom?.opencodeSessionId as string | undefined;
-          if (savedSessionId) {
-            console.log(`[CONTEXT] Found saved OpenCode session ID: ${savedSessionId}`);
-          }
-        }
-
-        // Snapshot the latest session ID in logs BEFORE starting OpenCode.
-        // This lets us detect whether OpenCode actually resumed vs created a new session.
-        const preStartSessionId = snapshotSessionId(this.agentName);
-
-        console.log(`Creating tmux session: ${sessionName}`);
-
-        // Include runner env vars (e.g., OPENCODE_MODEL) at session creation
-        const created = createSession(
-          this.agentName,
-          this.agentConfig.command,
-          this.agentConfig.workdir,
-          this.runnerConfig.env, // Apply model env at process start
-          savedSessionId, // Resume OpenCode session if available
-        );
-
-        if (!created) {
-          throw new Error("Failed to create tmux session");
-        }
-
-        // Store pre-start snapshot for fallback detection later
-        this._preStartSessionId = preStartSessionId;
-        this._attemptedResumeSessionId = savedSessionId;
-      } else {
-        console.log(`Reconnecting to existing session: ${sessionName}`);
-        // Update environment for existing session
-        updateSessionEnvironment(this.agentName, this.runnerConfig.env);
-      }
-
-      // Inject environment variables into tmux session
-      console.log("Injecting environment variables...");
-      updateSessionEnvironment(this.agentName, {
-        AGENT_TOKEN: this.token,
-        AGENTMESH_AGENT_ID: this.agentId,
-      });
-    }
-
-    // Save state including runtime model info
-    const sessionName = this.serveMode ? `serve:${this.servePort}` : getSessionName(this.agentName);
-    addAgentToState({
-      name: this.agentName,
-      agentId: this.agentId,
-      pid: process.pid,
-      tmuxSession: sessionName,
-      startedAt: new Date().toISOString(),
-      token: this.token,
-      workdir: this.agentConfig.workdir,
-      assignedProject: this.assignedProject,
-      runtimeModel: this.runnerConfig.model,
-      runnerType: this.runnerConfig.type,
-      sandboxContainer: this.sandbox?.getContainerName(),
-    });
-
-    // Start heartbeat with auto-refresh
-    console.log("Starting heartbeat...");
-    this.heartbeat = new Heartbeat({
-      url: this.config.hubUrl,
-      token: this.token,
-      intervalMs: 30000,
-      agentName: this.agentName,
-      agentId: this.agentId,
-      apiKey: this.config.apiKey,
-      workspace: this.config.workspace,
-      onError: (error) => {
-        console.error("Heartbeat error:", error.message);
-      },
-      onContextSave: () => {
-        // Periodically save context (every 5 heartbeats = ~2.5 minutes)
-        this.saveAgentContext();
-      },
-      contextSaveFrequency: 5,
-      onTokenRefresh: (newToken) => {
-        this.token = newToken;
-        // Update state file
-        updateAgentInState(this.agentName, { token: newToken });
-        // Update tmux environment
-        updateSessionEnvironment(this.agentName, {
-          AGENT_TOKEN: newToken,
-          AGENTMESH_AGENT_ID: this.agentId!,
-        });
-        // Reconnect WebSocket with new token
-        if (this.ws) {
-          this.ws.disconnect();
-          const wsUrl = this.config.hubUrl
-            .replace("https://", "wss://")
-            .replace("http://", "ws://");
-          this.ws = new AgentWebSocket({
-            url: `${wsUrl}/ws/v1`,
-            token: newToken,
-            onMessage: (event) => {
-              console.log(`[WS] Received event: ${event.type}`);
-              handleWebSocketEvent(this.agentName, event);
-            },
-            onConnect: () => {
-              console.log("WebSocket reconnected with new token");
-            },
-            onDisconnect: () => {
-              console.log("WebSocket disconnected");
-            },
-            onError: (error) => {
-              console.error("WebSocket error:", error.message);
-            },
-          });
-          this.ws.connect();
-        }
-      },
-    });
-    this.heartbeat.start();
-
-    // Connect WebSocket
-    console.log("Connecting WebSocket...");
-    const wsUrl = this.config.hubUrl.replace("https://", "wss://").replace("http://", "ws://");
-
-    this.ws = new AgentWebSocket({
-      url: `${wsUrl}/ws/v1`,
-      token: this.token,
-      onMessage: (event) => {
-        console.log(`[WS] Received event: ${event.type}`);
-        handleWebSocketEvent(this.agentName, event, {
-          hubUrl: this.config.hubUrl,
-          token: this.token ?? undefined,
-        });
-      },
-      onConnect: () => {
-        console.log("WebSocket connected");
-      },
-      onDisconnect: () => {
-        console.log("WebSocket disconnected");
-      },
-      onError: (error) => {
-        console.error("WebSocket error:", error.message);
-      },
-    });
-    this.ws.connect();
-
-    // Check inbox and auto-nudge with full handoff details
-    console.log("Checking inbox...");
-    try {
-      const inboxItems = await checkInbox(this.config.hubUrl, this.config.workspace, this.token);
-      injectStartupMessage(this.agentName, inboxItems.length, inboxItems);
-    } catch (error) {
-      console.error("Failed to check inbox:", error);
-      injectStartupMessage(this.agentName, 0);
-    }
-
-    // Restore context from previous session
-    if (this.shouldRestoreContext && this.agentId) {
-      console.log("Checking for previous context...");
-      const savedContext = loadContext(this.agentId);
-      if (savedContext) {
-        if (this._attemptedResumeSessionId && !this.serveMode && !this.sandboxMode) {
-          // Native session resume was attempted — verify it worked.
-          // Wait for OpenCode to write a NEW session entry to logs.
-          // If resume succeeded, it reuses the session (no new entry).
-          // If resume failed, OpenCode creates a new session (new entry appears).
-          const newSessionId = await waitForNewSessionId(
-            this.agentName,
-            this._preStartSessionId ?? null,
-            15000,
-          );
-
-          if (!newSessionId) {
-            // No new session appeared in logs. Could mean:
-            // a) Resume succeeded (OpenCode reused session, no new "created" log)
-            // b) OpenCode is sitting at splash (session not found, no new session created)
-            const health = isSessionHealthy(this.agentName);
-            const currentSessionId = getLatestSessionId(this.agentName);
-
-            if (!health.healthy) {
-              // OpenCode died — clear stale session ID to prevent restart loop
-              console.log(`[CONTEXT] Fallback: OpenCode not healthy, injecting text summary.`);
-              savedContext.custom = { ...savedContext.custom, opencodeSessionId: undefined };
-              saveContext(savedContext);
-              injectRestoredContext(this.agentName, savedContext);
-            } else if (currentSessionId === this._attemptedResumeSessionId) {
-              // The session ID we tried to resume is still the latest — resume worked
-              console.log(`[CONTEXT] Resumed OpenCode session ${this._attemptedResumeSessionId}`);
-            } else {
-              // Pane is alive but no matching session ID in logs — OpenCode is at splash
-              console.log(
-                `[CONTEXT] Fallback: session not found in OpenCode. Injecting text summary.`,
-              );
-              savedContext.custom = { ...savedContext.custom, opencodeSessionId: undefined };
-              saveContext(savedContext);
-              injectRestoredContext(this.agentName, savedContext);
-            }
-          } else if (newSessionId === this._attemptedResumeSessionId) {
-            // OpenCode logged the same session ID — resume succeeded
-            console.log(`[CONTEXT] Resumed OpenCode session ${this._attemptedResumeSessionId}`);
-          } else {
-            // OpenCode created a different session — resume failed, fallback to text.
-            // Update saved context with new session ID to prevent restart loop.
-            console.log(
-              `[CONTEXT] Fallback: resume failed (expected ${this._attemptedResumeSessionId}, got ${newSessionId}). Injecting text summary.`,
-            );
-            savedContext.custom = { ...savedContext.custom, opencodeSessionId: newSessionId };
-            saveContext(savedContext);
-            injectRestoredContext(this.agentName, savedContext);
-          }
-        } else {
-          // No session ID saved or non-tmux mode — use text injection
-          console.log(`Restoring context from ${savedContext.savedAt}`);
-          await new Promise((resolve) => setTimeout(resolve, 1000));
-          injectRestoredContext(this.agentName, savedContext);
-        }
-      }
-    }
-
-    this.isRunning = true;
-
-    // Start session health monitoring (every 60 seconds)
-    this.startHealthMonitor();
-
-    console.log(`
-Agent "${this.agentName}" is running.
-
-Attach to session:
-  agentmesh attach ${this.agentName}
-
-Stop agent:
-  agentmesh stop ${this.agentName}
-
-Nudge agent:
-  agentmesh nudge ${this.agentName} "Your message"
-`);
-
-    // Handle shutdown
-    process.on("SIGINT", () => this.stop());
-    process.on("SIGTERM", () => this.stop());
-  }
-
-  /**
-   * Starts periodic health monitoring for the tmux session
-   * Includes auto-restart logic and progress watchdog
-   */
-  private startHealthMonitor(): void {
-    // Skip health monitoring for serve mode (no tmux session)
-    if (this.serveMode) return;
-
-    const logDir = path.join(os.homedir(), ".agentmesh", "logs");
-    if (!fs.existsSync(logDir)) {
-      fs.mkdirSync(logDir, { recursive: true });
-    }
-
-    this.healthCheckInterval = setInterval(async () => {
-      if (!this.isRunning) return;
-
-      // Reset restart count after stable operation
-      if (this.lastStableTime && this.restartCount > 0) {
-        const stableTime = Date.now() - this.lastStableTime.getTime();
-        if (stableTime > RESTART_COUNT_RESET_MS) {
-          console.log(`[HEALTH] Agent stable for 30+ minutes, resetting restart count`);
-          this.restartCount = 0;
-          resetAgentRestartCount(this.agentName);
-        }
-      }
-
-      // For sandbox mode, pass container name so health check looks inside container
-      const containerName = this.sandboxMode ? this.sandbox?.getContainerName() : undefined;
-      const health = isSessionHealthy(this.agentName, containerName);
-
-      if (!health.healthy) {
-        // Session died - attempt restart
-        await this.handleSessionDeath(health.reason || "unknown", logDir);
-        return;
-      }
-
-      // Session is alive - check progress watchdog
-      const progress = checkAgentProgress(this.agentName, containerName);
-
-      if (progress.status === "permission_blocked" || progress.status === "stuck") {
-        await this.handleStuckAgent(progress);
-      } else if (progress.status === "active") {
-        // Agent is working - reset stuck tracking
-        if (this.stuckSince) {
-          console.log(`[HEALTH] Agent resumed activity`);
-          this.stuckSince = null;
-          this.nudgeSentAt = null;
-          updateAgentInState(this.agentName, { stuckSince: undefined, status: "running" });
-        }
-        this.lastStableTime = new Date();
-      }
-    }, 60000); // Check every 60 seconds
-  }
-
-  /**
-   * Handles session death - logs crash and attempts auto-restart
-   */
-  private async handleSessionDeath(reason: string, logDir: string): Promise<void> {
-    const timestamp = new Date().toISOString();
-    const logFile = path.join(logDir, `crash-${this.agentName}.log`);
-
-    // Capture last session output before it's gone
-    let lastOutput = "";
-    try {
-      lastOutput = captureSessionOutput(this.agentName, 200) || "Unable to capture output";
-    } catch {
-      lastOutput = "Failed to capture session output";
-    }
-
-    const crashLog = `
-================================================================================
-AGENT CRASH DETECTED
-================================================================================
-Timestamp: ${timestamp}
-Agent: ${this.agentName}
-Agent ID: ${this.agentId}
-Reason: ${reason}
-Restart Count: ${this.restartCount}/${MAX_RESTART_ATTEMPTS}
-Sandbox: ${this.sandboxMode ? this.sandbox?.getContainerName() : "none"}
-Workdir: ${this.agentConfig.workdir}
-Model: ${this.runnerConfig.model}
-
---- Last Session Output ---
-${lastOutput}
-================================================================================
-
-`;
-
-    fs.appendFileSync(logFile, crashLog);
-
-    // Save context (including session ID) before restart attempt
-    if (this.agentId) {
-      this.saveAgentContext();
-    }
-
-    // Check if we can restart
-    if (this.restartCount < MAX_RESTART_ATTEMPTS) {
-      this.restartCount++;
-      console.error(
-        `[CRASH] Session died: ${reason}. Attempting restart (${this.restartCount}/${MAX_RESTART_ATTEMPTS})...`,
-      );
-
-      updateAgentInState(this.agentName, {
-        restartCount: this.restartCount,
-        lastRestartAt: timestamp,
-        status: "running",
-      });
-
-      try {
-        await this.restartSession();
-        console.log(`[RESTART] Agent restarted successfully`);
-        this.lastStableTime = new Date();
-      } catch (error) {
-        console.error(`[RESTART] Failed to restart: ${(error as Error).message}`);
-      }
-    } else {
-      // Exceeded restart limit - mark as failed
-      console.error(
-        `[FAILED] Agent exceeded restart limit (${MAX_RESTART_ATTEMPTS}). Manual intervention required.`,
-      );
-
-      // Terminal bell to alert user
-      process.stdout.write("\x07");
-
-      updateAgentInState(this.agentName, {
-        status: "failed",
-        restartCount: this.restartCount,
-      });
-
-      // Stop monitoring
-      this.isRunning = false;
-      if (this.healthCheckInterval) {
-        clearInterval(this.healthCheckInterval);
-        this.healthCheckInterval = null;
-      }
-    }
-  }
-
-  /**
-   * Handles stuck agent - sends nudge first, then restarts if still stuck
-   */
-  private async handleStuckAgent(progress: {
-    status: string;
-    blockedOn?: string;
-    details?: string;
-  }): Promise<void> {
-    const now = new Date();
-
-    if (!this.stuckSince) {
-      // First detection of stuck state
-      this.stuckSince = now;
-      console.log(
-        `[HEALTH] Agent appears stuck: ${progress.details || progress.blockedOn || "no activity"}`,
-      );
-
-      updateAgentInState(this.agentName, {
-        stuckSince: now.toISOString(),
-        status: "stuck",
-      });
-    }
-
-    // Only nudge worker agents - others restart immediately
-    if (this.isWorkerAgent) {
-      // If we haven't sent a nudge yet, send one
-      if (!this.nudgeSentAt) {
-        console.log(`[HEALTH] Sending nudge to worker agent...`);
-
-        const nudgeMessage =
-          progress.status === "permission_blocked"
-            ? "Please continue with your task. If you see a permission prompt, try an alternative approach that doesn't require that permission."
-            : "Please continue with your current task.";
-
-        const sent = sendNudge(this.agentName, nudgeMessage);
-        if (sent) {
-          this.nudgeSentAt = now;
-          console.log(`[HEALTH] Nudge sent successfully`);
-        } else {
-          console.log(`[HEALTH] Failed to send nudge`);
-        }
-        return;
-      }
-
-      // Check if enough time has passed since nudge
-      const timeSinceNudge = now.getTime() - this.nudgeSentAt.getTime();
-      if (timeSinceNudge < NUDGE_WAIT_MS) {
-        // Still waiting for agent to respond to nudge
-        return;
-      }
-    }
-
-    // Agent still stuck - trigger restart (or restart immediately if not a worker)
-    console.log(
-      `[HEALTH] Agent still stuck${this.isWorkerAgent ? " after nudge" : ""}, triggering restart...`,
-    );
-    this.stuckSince = null;
-    this.nudgeSentAt = null;
-
-    await this.handleSessionDeath(
-      "stuck_after_nudge",
-      path.join(os.homedir(), ".agentmesh", "logs"),
-    );
-  }
-
-  /**
-   * Restarts the agent session (sandbox or non-sandbox)
-   */
-  private async restartSession(): Promise<void> {
-    // Destroy existing session
-    destroySession(this.agentName);
-
-    if (this.sandboxMode && this.sandbox) {
-      // Restart sandbox container
-      const newContainerId = await this.sandbox.restart();
-      console.log(`[RESTART] New container: ${newContainerId.substring(0, 12)}`);
-
-      // Recreate tmux session for sandbox
-      const containerName = this.sandbox.getContainerName();
-      const sessionName = getSessionName(this.agentName);
-
-      // Build environment args for docker exec
-      const envArgs: string[] = [];
-      const allEnv = {
-        ...this.runnerConfig.env,
-        AGENT_TOKEN: this.token!,
-        AGENTMESH_AGENT_ID: this.agentId!,
-      };
-      for (const [key, value] of Object.entries(allEnv)) {
-        if (value !== undefined && value !== "") {
-          envArgs.push(`-e "${key}=${value}"`);
-        }
-      }
-      const envString = envArgs.join(" ");
-      const modelArg = this.runnerConfig.env?.OPENCODE_MODEL
-        ? ` --model ${this.runnerConfig.env.OPENCODE_MODEL}`
-        : "";
-      const dockerExecCommand = `docker exec -it ${envString} ${containerName} opencode${modelArg}`;
-
-      const created = createSession(this.agentName, dockerExecCommand, undefined, undefined);
-      if (!created) {
-        throw new Error("Failed to create tmux session for restarted sandbox");
-      }
-
-      // Update state with new container name
-      updateAgentInState(this.agentName, {
-        sandboxContainer: containerName,
-      });
-    } else {
-      // Non-sandbox restart — load saved session ID for native resume
-      let savedSessionId: string | undefined;
-      let savedContext = null;
-      if (this.agentId) {
-        savedContext = loadContext(this.agentId);
-        savedSessionId = savedContext?.custom?.opencodeSessionId as string | undefined;
-        if (savedSessionId) {
-          console.log(`[RESTART] Attempting to resume OpenCode session: ${savedSessionId}`);
-        }
-      }
-
-      const preRestartSessionId = snapshotSessionId(this.agentName);
-
-      const created = createSession(
-        this.agentName,
-        this.agentConfig.command,
-        this.agentConfig.workdir,
-        this.runnerConfig.env,
-        savedSessionId,
-      );
-
-      if (!created) {
-        throw new Error("Failed to create tmux session");
-      }
-
-      // Re-inject environment
-      updateSessionEnvironment(this.agentName, {
-        AGENT_TOKEN: this.token!,
-        AGENTMESH_AGENT_ID: this.agentId!,
-        ...this.runnerConfig.env,
-      });
-
-      // Verify native resume and fallback if needed
-      if (savedSessionId && savedContext) {
-        const newSessionId = await waitForNewSessionId(this.agentName, preRestartSessionId, 15000);
-
-        if (!newSessionId) {
-          const health = isSessionHealthy(this.agentName);
-          const currentSessionId = getLatestSessionId(this.agentName);
-
-          if (!health.healthy) {
-            console.log(`[RESTART] Fallback: OpenCode not healthy, injecting text summary.`);
-            savedContext.custom = { ...savedContext.custom, opencodeSessionId: undefined };
-            saveContext(savedContext);
-            injectRestoredContext(this.agentName, savedContext);
-          } else if (currentSessionId === savedSessionId) {
-            console.log(`[RESTART] Resumed OpenCode session ${savedSessionId}`);
-          } else {
-            console.log(`[RESTART] Fallback: session not found. Injecting text summary.`);
-            savedContext.custom = { ...savedContext.custom, opencodeSessionId: undefined };
-            saveContext(savedContext);
-            injectRestoredContext(this.agentName, savedContext);
-          }
-        } else if (newSessionId === savedSessionId) {
-          console.log(`[RESTART] Resumed OpenCode session ${savedSessionId}`);
-        } else {
-          console.log(
-            `[RESTART] Fallback: resume failed (got ${newSessionId}). Injecting text summary.`,
-          );
-          savedContext.custom = { ...savedContext.custom, opencodeSessionId: newSessionId };
-          saveContext(savedContext);
-          injectRestoredContext(this.agentName, savedContext);
-        }
-      }
-    }
-
-    // Wait for session to be ready
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-  }
-
-  async stop(): Promise<void> {
-    console.log(`\nStopping agent: ${this.agentName}`);
-
-    this.isRunning = false;
-
-    // Stop health monitor
-    if (this.healthCheckInterval) {
-      clearInterval(this.healthCheckInterval);
-      this.healthCheckInterval = null;
-    }
-
-    // Save context before stopping
-    if (this.agentId) {
-      console.log("Saving agent context...");
-      this.saveAgentContext();
-    }
-
-    // Stop heartbeat
-    if (this.heartbeat) {
-      this.heartbeat.stop();
-      this.heartbeat = null;
-    }
-
-    // Disconnect WebSocket
-    if (this.ws) {
-      this.ws.disconnect();
-      this.ws = null;
-    }
-
-    // Stop sandbox, serve process, or destroy tmux session
-    if (this.sandboxMode && this.sandbox) {
-      console.log("Stopping sandbox...");
-      // In sandbox mode, we have both a tmux session (on host) and a Docker container
-      // Destroy tmux session first (this stops docker exec)
-      destroySession(this.agentName);
-      // Then destroy the container
-      await this.sandbox.destroy();
-      this.sandbox = null;
-    } else if (this.serveMode && this.serveProcess) {
-      console.log("Stopping opencode serve...");
-      this.serveProcess.kill("SIGTERM");
-      this.serveProcess = null;
-    } else {
-      destroySession(this.agentName);
-    }
-
-    // Update state to mark as stopped but preserve agentId for next restart
-    updateAgentInState(this.agentName, {
-      pid: 0,
-      tmuxSession: "",
-      startedAt: "",
-      token: undefined,
-    });
-
-    console.log("Agent stopped.");
-    process.exit(0);
-  }
-
-  /**
-   * Starts opencode serve mode (for Integration Service)
-   * Replaces tmux with a direct HTTP server
-   */
-  private async startServeMode(): Promise<void> {
-    console.log(`Starting opencode serve mode on port ${this.servePort}...`);
-
-    const workdir = this.agentConfig.workdir || process.cwd();
-
-    // Isolate OpenCode's SQLite database per agent to prevent WAL corruption.
-    // See docs/RCA-OPENCODE-SQLITE-CORRUPTION.md for details.
-    const agentDataDir = path.join(os.homedir(), ".agentmesh", "opencode-data", this.agentName);
-    const agentOpencodeDir = path.join(agentDataDir, "opencode");
-    if (!fs.existsSync(agentOpencodeDir)) {
-      fs.mkdirSync(agentOpencodeDir, { recursive: true });
-    }
-
-    // Copy auth.json from default OpenCode data dir so agents inherit API keys.
-    // Strips xAI provider to prevent OpenCode from defaulting to non-Anthropic models.
-    const agentAuthPath = path.join(agentOpencodeDir, "auth.json");
-    const sourceAuthPath = path.join(os.homedir(), ".local", "share", "opencode", "auth.json");
-    if (!fs.existsSync(agentAuthPath) && fs.existsSync(sourceAuthPath)) {
-      try {
-        const auth = JSON.parse(fs.readFileSync(sourceAuthPath, "utf-8"));
-        delete auth.xai;
-        fs.writeFileSync(agentAuthPath, JSON.stringify(auth, null, 2));
-      } catch {
-        // Non-fatal — agent will just need manual auth
-      }
-    }
-
-    // Build environment for opencode serve
-    const env: Record<string, string> = {
-      ...process.env,
-      ...this.runnerConfig.env,
-      AGENT_TOKEN: this.token!,
-      AGENTMESH_AGENT_ID: this.agentId!,
-      XDG_DATA_HOME: agentDataDir,
-    } as Record<string, string>;
-
-    // Spawn opencode serve as a child process
-    this.serveProcess = spawn(
-      "opencode",
-      ["serve", "--port", String(this.servePort), "--hostname", "0.0.0.0"],
-      {
-        cwd: workdir,
-        env,
-        stdio: ["ignore", "inherit", "inherit"],
-      },
-    );
-
-    // Handle process exit
-    this.serveProcess.on("exit", (code, signal) => {
-      console.error(`opencode serve exited with code ${code}, signal ${signal}`);
-      if (this.isRunning) {
-        console.log("Restarting opencode serve in 5 seconds...");
-        setTimeout(() => {
-          if (this.isRunning) {
-            this.startServeMode().catch(console.error);
-          }
-        }, 5000);
-      }
-    });
-
-    this.serveProcess.on("error", (error) => {
-      console.error("Failed to start opencode serve:", error);
-    });
-
-    // Wait a moment for the server to start
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-
-    console.log(`opencode serve started on http://0.0.0.0:${this.servePort}`);
-
-    // Store saved session ID for integration service reuse
-    if (this.shouldRestoreContext && this.agentId) {
-      const savedContext = loadContext(this.agentId);
-      const savedSessionId = savedContext?.custom?.opencodeSessionId as string | undefined;
-      if (savedSessionId) {
-        console.log(`[SERVE] Saved OpenCode session available for reuse: ${savedSessionId}`);
-        updateAgentInState(this.agentName, { opencodeSessionId: savedSessionId });
-      }
-    }
-  }
-
-  /**
-   * Starts agent in Docker sandbox mode
-   * Provides filesystem isolation with only workspace mounted
-   *
-   * Strategy: Start Docker container with tail -f /dev/null, then create
-   * a tmux session on the HOST that runs `docker exec -it <container> opencode`.
-   * This way tmux provides the TTY that docker exec needs.
-   */
-  private async startSandboxMode(): Promise<void> {
-    console.log("Starting in Docker sandbox mode...");
-
-    // Check Docker availability
-    if (!DockerSandbox.checkDockerAvailable()) {
-      throw new Error(
-        "Docker is not available. Install Docker or use --sandbox host to run on host.",
-      );
-    }
-
-    const workdir = this.agentConfig.workdir || process.cwd();
-
-    // Check for existing sandbox container
-    const existingContainer = DockerSandbox.findExisting(this.agentName);
-    if (existingContainer) {
-      console.log(`Found existing sandbox container: ${existingContainer}`);
-      console.log(`Stop it with: agentmesh stop ${this.agentName}`);
-      throw new Error("Sandbox container already exists");
-    }
-
-    // Build additional mounts for credentials and config
-    // The entrypoint script copies these from /tmp/ to the correct locations
-    const additionalMounts: string[] = [];
-
-    // Mount git credentials
-    const gitCredentialsPath = path.join(os.homedir(), ".git-credentials");
-    if (fs.existsSync(gitCredentialsPath)) {
-      additionalMounts.push(`${gitCredentialsPath}:/tmp/.git-credentials-host:ro`);
-    }
-
-    // Mount OpenCode auth.json for API provider tokens (Anthropic, OpenAI, etc.)
-    const opencodeAuthPath = path.join(os.homedir(), ".local", "share", "opencode", "auth.json");
-    if (fs.existsSync(opencodeAuthPath)) {
-      additionalMounts.push(`${opencodeAuthPath}:/tmp/.opencode-auth-host:ro`);
-    }
-
-    // Mount AgentMesh config for hub URL, API key, workspace
-    const agentmeshConfigPath = path.join(os.homedir(), ".agentmesh", "config.json");
-    if (fs.existsSync(agentmeshConfigPath)) {
-      additionalMounts.push(`${agentmeshConfigPath}:/tmp/.agentmesh-config-host:ro`);
-    }
-
-    // Create and mount permissive OpenCode config for sandbox
-    // This allows all permissions since the container is already sandboxed
-    this.ensureSandboxOpencodeConfig();
-    additionalMounts.push(`${SANDBOX_OPENCODE_CONFIG_PATH}:/workspace/opencode.json:ro`);
-
-    // Pass GitHub token as environment variable for git operations
-    const gitCredentials = fs.existsSync(gitCredentialsPath)
-      ? fs.readFileSync(gitCredentialsPath, "utf-8").trim()
-      : "";
-    const gitHubToken = gitCredentials.match(/github_pat_[^\s@]+/)?.[0] || "";
-
-    // Build the command to run inside the container
-    // The agentmesh CLI inside the container will create tmux + opencode
-    const model =
-      this.runnerConfig.env?.OPENCODE_MODEL || this.runnerConfig.model || "claude-sonnet-4";
-    const containerCommand = [
-      "agentmesh",
-      "start",
-      "--name",
-      this.agentName,
-      "--model",
-      model,
-      "--foreground",
-    ];
-
-    // Create sandbox configuration
-    // Isolate OpenCode's SQLite database per agent to prevent WAL corruption.
-    const hostDataDir = path.join(os.homedir(), ".agentmesh", "opencode-data", this.agentName);
-    if (!fs.existsSync(hostDataDir)) {
-      fs.mkdirSync(hostDataDir, { recursive: true });
-    }
-
-    this.sandbox = new DockerSandbox({
-      agentName: this.agentName,
-      image: this.sandboxImage,
-      workspacePath: workdir,
-      cpuLimit: this.sandboxCpu,
-      memoryLimit: this.sandboxMemory,
-      env: {
-        ...this.runnerConfig.env,
-        AGENT_TOKEN: this.token!,
-        AGENTMESH_AGENT_ID: this.agentId!,
-        AGENT_NAME: this.agentName,
-        // XDG_DATA_HOME set by entrypoint based on AGENT_NAME
-        // Git credentials for pushing to GitHub
-        ...(gitHubToken && { GH_TOKEN: gitHubToken, GITHUB_TOKEN: gitHubToken }),
-      },
-      serveMode: this.serveMode,
-      servePort: this.servePort,
-      networkMode: "bridge",
-      additionalMounts: [
-        ...additionalMounts,
-        `${hostDataDir}:/home/node/.agentmesh/opencode-data/${this.agentName}:rw`,
-      ],
-      command: this.serveMode ? undefined : containerCommand,
-    });
-
-    // Validate mount policy (will throw if denied)
-    this.sandbox.validateMountPolicy();
-
-    // Pull image if needed
-    await this.sandbox.pullImage();
-
-    // Start container with agentmesh running inside
-    // The entrypoint script sets up credentials before agentmesh starts
-    await this.sandbox.start();
-
-    const containerName = this.sandbox.getContainerName();
-
-    console.log(`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-SANDBOX MODE ACTIVE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Container: ${containerName}
-Image:     ${this.sandboxImage}
-Workspace: ${workdir} -> /workspace
-CPU:       ${this.sandboxCpu} core(s)
-Memory:    ${this.sandboxMemory}
-Model:     ${model}
-
-The agent daemon is running INSIDE the Docker container.
-tmux session and OpenCode are managed inside the container.
-
-Attach:  agentmesh attach ${this.agentName}
-Nudge:   agentmesh nudge ${this.agentName} "message"
-Stop:    agentmesh stop ${this.agentName}
-Logs:    docker logs ${containerName}
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-`);
-
-    // No host tmux session needed - the container runs agentmesh which creates its own tmux
-    // Heartbeats are sent by the daemon running inside the container
-  }
-
-  /**
-   * Saves the current agent context to disk
-   */
-  private saveAgentContext(): void {
-    if (!this.agentId) return;
-
-    try {
-      // Load existing context or create new
-      const context = loadOrCreateContext(this.agentId, this.agentName);
-
-      // Capture current session state
-      const sessionContext = captureSessionContext(this.agentName);
-      if (sessionContext) {
-        context.workingState = {
-          ...context.workingState,
-          workdir: sessionContext.workdir,
-          gitBranch: sessionContext.gitBranch,
-          gitStatus: sessionContext.gitStatus,
-        };
-      }
-
-      // Capture OpenCode session ID for native resume on restart
-      const sessionId = getLatestSessionId(this.agentName);
-      if (sessionId) {
-        context.custom = { ...context.custom, opencodeSessionId: sessionId };
-        console.log(`[CONTEXT] Captured OpenCode session ID: ${sessionId}`);
-      }
-
-      // Save updated context
-      saveContext(context);
-      console.log(`Context saved for agent ${this.agentName}`);
-    } catch (error) {
-      console.error("Failed to save agent context:", error);
-    }
-  }
-
-  /**
-   * Fetches assignments from HQ and validates workdir setup
-   * Uses project.workdir from HQ as source of truth, falls back to helpful instructions
-   */
-  private async checkAssignments(): Promise<void> {
-    if (!this.token) return;
-
-    try {
-      console.log("Fetching project assignments from HQ...");
-      const assignments = await fetchAssignments(this.config.hubUrl, this.token);
-
-      if (assignments.length === 0) {
-        console.log("No project assignments found.");
-        return;
-      }
-
-      console.log(`Found ${assignments.length} assignment(s):`);
-      for (const assignment of assignments) {
-        const repoInfo = assignment.repo ? ` -> ${assignment.repo.full_name}` : "";
-        const workdirInfo = assignment.project.workdir ? ` [${assignment.project.workdir}]` : "";
-        console.log(`  - ${assignment.project.name} (${assignment.role})${repoInfo}${workdirInfo}`);
-      }
-
-      this.assignedProject = assignments[0]?.project.name;
-
-      // If no CLI workdir specified, try to use project.workdir from HQ
-      if (!this.agentConfig.workdir) {
-        const assignmentWithWorkdir = assignments.find((a) => a.project.workdir);
-        if (assignmentWithWorkdir?.project.workdir) {
-          console.log(
-            `Using workdir from project settings: ${assignmentWithWorkdir.project.workdir}`,
-          );
-          this.agentConfig.workdir = assignmentWithWorkdir.project.workdir;
-          return;
-        }
-
-        // No project.workdir set, check if we have a repo assignment
-        const repoAssignment = assignments.find((a) => a.repo !== null);
-        if (repoAssignment) {
-          const repo = repoAssignment.repo!;
-          const expandedPath = path.join(
-            os.homedir(),
-            ".agentmesh",
-            "workspaces",
-            this.config.workspace,
-            repoAssignment.project.code.toLowerCase(),
-            this.agentName,
-          );
-          const suggestedPath = `~/.agentmesh/workspaces/${this.config.workspace}/${repoAssignment.project.code.toLowerCase()}/${this.agentName}`;
-
-          // If --auto-setup is enabled, automatically clone the repo
-          if (this.autoSetup) {
-            this.agentConfig.workdir = this.setupWorkspace(
-              expandedPath,
-              repo.url,
-              repo.default_branch,
-              repoAssignment.project.name,
-            );
-            return;
-          }
-
-          console.error(`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️  WORKDIR REQUIRED
-
-You have a project assignment with a repository, but no workdir is configured.
-
-Project:  ${repoAssignment.project.name}
-Repo:     ${repo.full_name}
-Branch:   ${repo.default_branch}
-
-Option 1: Set workdir in project settings (recommended)
-  - Go to AgentMesh HQ → Projects → ${repoAssignment.project.name} → Settings
-  - Set the workdir field to the local path
-
-Option 2: Set up workspace manually and pass --workdir:
-
-  mkdir -p ${suggestedPath}
-  git clone ${repo.url} ${suggestedPath}
-  cd ${suggestedPath} && git checkout ${repo.default_branch}
-
-Then start the agent with:
-
-  agentmesh start -n ${this.agentName} --workdir ${suggestedPath}
-
-Option 3: Use --auto-setup to automatically clone the repository:
-
-  agentmesh start -n ${this.agentName} --auto-setup
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-`);
-          // No session to clean up - we haven't created it yet
-          process.exit(1);
-        }
-      }
-    } catch (error) {
-      // Non-fatal: log and continue (HQ might not have assignments feature yet)
-      console.log("Could not fetch assignments:", (error as Error).message);
-    }
-  }
-
-  /**
-   * Sets up workspace by cloning repository or using existing clone
-   * Returns the absolute path to the workspace
-   */
-  private setupWorkspace(
-    workspacePath: string,
-    repoUrl: string,
-    defaultBranch: string,
-    projectName: string,
-  ): string {
-    console.log(
-      `\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
-    );
-    console.log(`🔧 AUTO-SETUP: Setting up workspace for ${projectName}`);
-    console.log(
-      `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`,
-    );
-
-    // Check if directory already exists and is a git repo
-    const gitDir = path.join(workspacePath, ".git");
-    if (fs.existsSync(gitDir)) {
-      console.log(`✓ Workspace already exists: ${workspacePath}`);
-      console.log(`  Updating from remote...`);
-
-      try {
-        // Fetch and checkout the branch
-        execSync(`git fetch origin`, { cwd: workspacePath, stdio: "inherit" });
-        execSync(`git checkout ${defaultBranch}`, { cwd: workspacePath, stdio: "inherit" });
-        execSync(`git pull origin ${defaultBranch}`, { cwd: workspacePath, stdio: "inherit" });
-        console.log(`✓ Workspace updated successfully\n`);
-      } catch (error) {
-        console.warn(`⚠ Could not update workspace: ${(error as Error).message}`);
-        console.log(`  Continuing with existing state...\n`);
-      }
-
-      return workspacePath;
-    }
-
-    // Create parent directories
-    const parentDir = path.dirname(workspacePath);
-    if (!fs.existsSync(parentDir)) {
-      console.log(`Creating directory: ${parentDir}`);
-      fs.mkdirSync(parentDir, { recursive: true });
-    }
-
-    // Clone the repository
-    console.log(`Cloning repository...`);
-    console.log(`  URL: ${repoUrl}`);
-    console.log(`  Path: ${workspacePath}`);
-    console.log(`  Branch: ${defaultBranch}\n`);
-
-    try {
-      execSync(`git clone --branch ${defaultBranch} "${repoUrl}" "${workspacePath}"`, {
-        stdio: "inherit",
-      });
-      console.log(`\n✓ Repository cloned successfully`);
-    } catch (error) {
-      console.error(`\n✗ Failed to clone repository: ${(error as Error).message}`);
-      console.error(`\nMake sure you have access to the repository and SSH keys are configured.`);
-      // No session to clean up - we haven't created it yet
-      process.exit(1);
-    }
-
-    console.log(`✓ Workspace ready: ${workspacePath}\n`);
-    return workspacePath;
-  }
-
-  /**
-   * Ensures the sandbox OpenCode config exists
-   * Creates ~/.agentmesh/opencode-sandbox.json with permissive permissions and model
-   */
-  private ensureSandboxOpencodeConfig(): void {
-    const configDir = path.dirname(SANDBOX_OPENCODE_CONFIG_PATH);
-
-    if (!fs.existsSync(configDir)) {
-      fs.mkdirSync(configDir, { recursive: true });
-    }
-
-    // Build config with model if available
-    const config: Record<string, unknown> = {
-      ...SANDBOX_OPENCODE_CONFIG,
-    };
-
-    // Include model from runner config
-    const model = this.runnerConfig.env?.OPENCODE_MODEL;
-    if (model) {
-      config.model = model;
-    }
-
-    // Always write to ensure model is up to date
-    fs.writeFileSync(SANDBOX_OPENCODE_CONFIG_PATH, JSON.stringify(config, null, 2));
-    console.log(`Updated sandbox OpenCode config: ${SANDBOX_OPENCODE_CONFIG_PATH}`);
-  }
-}