@agentmeshhq/agent 0.2.0 → 0.2.1

package/dist/core/daemon/workspace.d.ts

@@ -0,0 +1,10 @@
+export interface WorkspaceSetupInput {
+    workspacePath: string;
+    repoUrl: string;
+    defaultBranch: string;
+    projectName: string;
+}
+/**
+ * Ensures a project workspace exists and is on the target default branch.
+ */
+export declare function setupWorkspace(input: WorkspaceSetupInput): string;

package/dist/core/daemon/workspace.js

@@ -0,0 +1,51 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Ensures a project workspace exists and is on the target default branch.
+ */
+export function setupWorkspace(input) {
+    const { workspacePath, repoUrl, defaultBranch, projectName } = input;
+    console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    console.log(`🔧 AUTO-SETUP: Setting up workspace for ${projectName}`);
+    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+    const gitDir = path.join(workspacePath, ".git");
+    if (fs.existsSync(gitDir)) {
+        console.log(`✓ Workspace already exists: ${workspacePath}`);
+        console.log("  Updating from remote...");
+        try {
+            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.message}`);
+            console.log("  Continuing with existing state...\n");
+        }
+        return workspacePath;
+    }
+    const parentDir = path.dirname(workspacePath);
+    if (!fs.existsSync(parentDir)) {
+        console.log(`Creating directory: ${parentDir}`);
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    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.message}`);
+        console.error("\nMake sure you have access to the repository and SSH keys are configured.");
+        process.exit(1);
+    }
+    console.log(`✓ Workspace ready: ${workspacePath}\n`);
+    return workspacePath;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/daemon/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/core/daemon/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAS7B;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAErE,OAAO,CAAC,GAAG,CAAC,oFAAoF,CAAC,CAAC;IAClG,OAAO,CAAC,GAAG,CAAC,2CAA2C,WAAW,EAAE,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,oFAAoF,CAAC,CAAC;IAElG,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,+BAA+B,aAAa,EAAE,CAAC,CAAC;QAC5D,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QAEzC,IAAI,CAAC;YACH,QAAQ,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YACvE,QAAQ,CAAC,gBAAgB,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YACpF,QAAQ,CAAC,mBAAmB,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YACvF,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,iCAAkC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,uBAAuB,SAAS,EAAE,CAAC,CAAC;QAChD,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,WAAW,aAAa,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,aAAa,aAAa,IAAI,CAAC,CAAC;IAE5C,IAAI,CAAC;QACH,QAAQ,CAAC,sBAAsB,aAAa,KAAK,OAAO,MAAM,aAAa,GAAG,EAAE;YAC9E,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,mCAAoC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,sBAAsB,aAAa,IAAI,CAAC,CAAC;IACrD,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/core/daemon.d.ts

@@ -46,7 +46,6 @@ export declare class AgentDaemon {
     private sandboxMemory;
     private sandbox;
     private healthCheckInterval;
-    private serverContext;
     private _preStartSessionId;
     private _attemptedResumeSessionId;
     private restartCount;
@@ -96,11 +95,6 @@ export declare class AgentDaemon {
      * Uses project.workdir from HQ as source of truth, falls back to helpful instructions
      */
     private checkAssignments;
-    /**
-     * Sets up workspace by cloning repository or using existing clone
-     * Returns the absolute path to the workspace
-     */
-    private setupWorkspace;
     /**
      * Ensures the sandbox OpenCode config exists
      * Creates ~/.agentmesh/opencode-sandbox.json with permissive permissions and model

package/dist/core/daemon.js

@@ -1,16 +1,25 @@
-import { execSync, spawn } from "node:child_process";
+import { 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 { getAgentState, resetAgentRestartCount, updateAgentInState } from "../config/loader.js";
 import { loadContext, loadOrCreateContext, saveContext } from "../context/index.js";
+import { renderMissingWorkdirMessage } from "./daemon/assignment-message.js";
+import { bootstrapDaemon } from "./daemon/bootstrap.js";
+import { formatCrashLog } from "./daemon/crash-log.js";
+import { getNudgeMessage, getStuckDetail, isWithinNudgeWaitWindow, shouldResetRestartCount, } from "./daemon/health-policy.js";
+import { writeSandboxOpencodeConfig } from "./daemon/sandbox-config.js";
+import { captureAgentChildPids, persistRunningState } from "./daemon/state.js";
+import { startTmuxRuntimeSession } from "./daemon/tmux-session.js";
+import { setupWorkspace } from "./daemon/workspace.js";
 import { Heartbeat } from "./heartbeat.js";
 import { handleWebSocketEvent, injectRestoredContext, injectStartupMessage } from "./injector.js";
 import { checkInbox, fetchAssignments, registerAgent } from "./registry.js";
-import { buildRunnerConfig, getRunnerDisplayName } from "./runner.js";
+import { getRunnerDisplayName } 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 { captureSessionContext, captureSessionOutput, createSession, destroySession, isSessionHealthy, killProcessTree, updateSessionEnvironment, } from "./tmux.js";
+import { prepareOpenCodeRuntime } from "./tmux-runtime.js";
 import { checkAgentProgress, cleanupOrphanContainers, isProcessRunning, sendNudge, } from "./watchdog.js";
 import { AgentWebSocket } from "./websocket.js";
 // Maximum number of auto-restart attempts
@@ -49,7 +58,6 @@ export class AgentDaemon {
     sandboxMemory;
     sandbox = null;
     healthCheckInterval = null;
-    serverContext;
     // Session resume tracking
     _preStartSessionId;
     _attemptedResumeSessionId;
@@ -59,51 +67,20 @@ export class AgentDaemon {
     stuckSince = null;
     nudgeSentAt = null;
     constructor(options) {
-        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;
+        const boot = bootstrapDaemon(options);
+        this.config = boot.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,
-        });
+        this.shouldRestoreContext = boot.shouldRestoreContext;
+        this.isWorkerAgent = boot.isWorkerAgent;
+        this.autoSetup = boot.autoSetup;
+        this.agentConfig = boot.agentConfig;
+        this.serveMode = boot.serveMode;
+        this.servePort = boot.servePort;
+        this.sandboxMode = boot.sandboxMode;
+        this.sandboxImage = boot.sandboxImage;
+        this.sandboxCpu = boot.sandboxCpu;
+        this.sandboxMemory = boot.sandboxMemory;
+        this.runnerConfig = boot.runnerConfig;
         const runnerName = getRunnerDisplayName(this.runnerConfig.type);
         console.log(`Runner: ${runnerName}`);
         console.log(`Effective model: ${this.runnerConfig.model}`);
@@ -121,8 +98,13 @@ export class AgentDaemon {
                 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
+            // Process not running — clean up stale state and any orphaned child processes
             console.log(`Cleaning up stale state for PID ${existingState.pid}`);
+            const orphanPids = existingState.childPids ?? [];
+            if (orphanPids.length > 0) {
+                console.log(`[STARTUP] Found ${orphanPids.length} orphaned child PIDs from previous run — killing...`);
+                killProcessTree(orphanPids);
+            }
         }
         // Clean up orphan containers in sandbox mode
         if (this.sandboxMode) {
@@ -151,7 +133,6 @@ export class AgentDaemon {
         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(", ")}`);
             }
         }
@@ -168,39 +149,16 @@ export class AgentDaemon {
             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;
-                if (this.shouldRestoreContext && this.agentId) {
-                    const savedContext = loadContext(this.agentId);
-                    savedSessionId = savedContext?.custom?.opencodeSessionId;
-                    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);
-                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);
-            }
+            const sessionStart = startTmuxRuntimeSession({
+                agentName: this.agentName,
+                agentId: this.agentId,
+                command: this.agentConfig.command,
+                workdir: this.agentConfig.workdir,
+                runnerEnv: this.runnerConfig.env,
+                shouldRestoreContext: this.shouldRestoreContext,
+            });
+            this._preStartSessionId = sessionStart.preStartSessionId;
+            this._attemptedResumeSessionId = sessionStart.attemptedResumeSessionId;
             // Inject environment variables into tmux session
             console.log("Injecting environment variables...");
             updateSessionEnvironment(this.agentName, {
@@ -209,20 +167,27 @@ export class AgentDaemon {
             });
         }
         // Save state including runtime model info
-        const sessionName = this.serveMode ? `serve:${this.servePort}` : getSessionName(this.agentName);
-        addAgentToState({
-            name: this.agentName,
+        persistRunningState({
+            agentName: 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(),
+            serveMode: this.serveMode,
+            servePort: this.servePort,
         });
+        // Track child PIDs for cleanup on restart/stop (tmux mode only — sandbox/serve manage their own)
+        if (!this.sandboxMode && !this.serveMode) {
+            const childPids = captureAgentChildPids(this.agentName);
+            if (childPids.length > 0) {
+                updateAgentInState(this.agentName, { childPids });
+                console.log(`[STARTUP] Tracking ${childPids.length} child PIDs: ${childPids.join(", ")}`);
+            }
+        }
         // Start heartbeat with auto-refresh
         console.log("Starting heartbeat...");
         this.heartbeat = new Heartbeat({
@@ -404,13 +369,10 @@ Nudge agent:
             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);
-                }
+            if (shouldResetRestartCount(this.restartCount, this.lastStableTime, 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;
@@ -422,7 +384,17 @@ Nudge agent:
             }
             // Session is alive - check progress watchdog
             const progress = checkAgentProgress(this.agentName, containerName);
-            if (progress.status === "permission_blocked" || progress.status === "stuck") {
+            if (progress.status === "waiting_for_human") {
+                // Agent is intentionally waiting for human input - do not classify as stuck
+                if (this.stuckSince) {
+                    // Clear any prior stuck tracking since the agent signalled a legitimate wait
+                    this.stuckSince = null;
+                    this.nudgeSentAt = null;
+                    updateAgentInState(this.agentName, { stuckSince: undefined, status: "waiting" });
+                }
+                console.log(`[HEALTH] Agent is waiting for human input: ${progress.details}`);
+            }
+            else if (progress.status === "permission_blocked" || progress.status === "stuck") {
                 await this.handleStuckAgent(progress);
             }
             else if (progress.status === "active") {
@@ -451,24 +423,18 @@ Nudge agent:
         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}
-================================================================================
-
-`;
+        const crashLog = formatCrashLog({
+            timestamp,
+            agentName: this.agentName,
+            agentId: this.agentId,
+            reason,
+            restartCount: this.restartCount,
+            maxRestartAttempts: MAX_RESTART_ATTEMPTS,
+            sandboxLabel: this.sandboxMode ? this.sandbox?.getContainerName() || "sandbox" : "none",
+            workdir: this.agentConfig.workdir,
+            model: this.runnerConfig.model,
+            lastOutput,
+        });
         fs.appendFileSync(logFile, crashLog);
         // Save context (including session ID) before restart attempt
         if (this.agentId) {
@@ -517,7 +483,7 @@ ${lastOutput}
         if (!this.stuckSince) {
             // First detection of stuck state
             this.stuckSince = now;
-            console.log(`[HEALTH] Agent appears stuck: ${progress.details || progress.blockedOn || "no activity"}`);
+            console.log(`[HEALTH] Agent appears stuck: ${getStuckDetail(progress)}`);
             updateAgentInState(this.agentName, {
                 stuckSince: now.toISOString(),
                 status: "stuck",
@@ -528,9 +494,7 @@ ${lastOutput}
             // 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 nudgeMessage = getNudgeMessage(progress);
                 const sent = sendNudge(this.agentName, nudgeMessage);
                 if (sent) {
                     this.nudgeSentAt = now;
@@ -542,8 +506,7 @@ ${lastOutput}
                 return;
             }
             // Check if enough time has passed since nudge
-            const timeSinceNudge = now.getTime() - this.nudgeSentAt.getTime();
-            if (timeSinceNudge < NUDGE_WAIT_MS) {
+            if (isWithinNudgeWaitWindow(this.nudgeSentAt, NUDGE_WAIT_MS, now)) {
                 // Still waiting for agent to respond to nudge
                 return;
             }
@@ -558,15 +521,19 @@ ${lastOutput}
      * Restarts the agent session (sandbox or non-sandbox)
      */
     async restartSession() {
-        // Destroy existing session
-        destroySession(this.agentName);
+        // Retrieve tracked child PIDs before destroying the session
+        const currentState = getAgentState(this.agentName);
+        const childPids = currentState?.childPids ?? [];
+        // Destroy existing session AND kill all tracked child processes
+        destroySession(this.agentName, childPids);
+        // Allow cleanup to settle before spawning a new session
+        await new Promise((resolve) => setTimeout(resolve, 1000));
         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 = [];
             const allEnv = {
@@ -588,10 +555,15 @@ ${lastOutput}
             if (!created) {
                 throw new Error("Failed to create tmux session for restarted sandbox");
             }
-            // Update state with new container name
+            // Track new child PIDs and update state
+            const newChildPids = captureAgentChildPids(this.agentName);
             updateAgentInState(this.agentName, {
                 sandboxContainer: containerName,
+                childPids: newChildPids,
             });
+            if (newChildPids.length > 0) {
+                console.log(`[RESTART] Tracking ${newChildPids.length} child PIDs: ${newChildPids.join(", ")}`);
+            }
         }
         else {
             // Non-sandbox restart — load saved session ID for native resume
@@ -615,6 +587,12 @@ ${lastOutput}
                 AGENTMESH_AGENT_ID: this.agentId,
                 ...this.runnerConfig.env,
             });
+            // Track new child PIDs
+            const newChildPids = captureAgentChildPids(this.agentName);
+            updateAgentInState(this.agentName, { childPids: newChildPids });
+            if (newChildPids.length > 0) {
+                console.log(`[RESTART] Tracking ${newChildPids.length} child PIDs: ${newChildPids.join(", ")}`);
+            }
             // Verify native resume and fallback if needed
             if (savedSessionId && savedContext) {
                 const newSessionId = await waitForNewSessionId(this.agentName, preRestartSessionId, 15000);
@@ -709,27 +687,7 @@ ${lastOutput}
     async startServeMode() {
         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
-            }
-        }
+        const agentDataDir = prepareOpenCodeRuntime(this.agentName);
         // Build environment for opencode serve
         const env = {
             ...process.env,
@@ -966,39 +924,22 @@ Logs:    docker logs ${containerName}
                     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);
+                        this.agentConfig.workdir = setupWorkspace({
+                            workspacePath: expandedPath,
+                            repoUrl: repo.url,
+                            defaultBranch: repo.default_branch,
+                            projectName: 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
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-`);
+                    console.error(renderMissingWorkdirMessage({
+                        projectName: repoAssignment.project.name,
+                        repoFullName: repo.full_name,
+                        repoUrl: repo.url,
+                        defaultBranch: repo.default_branch,
+                        suggestedPath,
+                        agentName: this.agentName,
+                    }));
                     // No session to clean up - we haven't created it yet
                     process.exit(1);
                 }
@@ -1009,78 +950,16 @@ Option 3: Use --auto-setup to automatically clone the repository:
             console.log("Could not fetch assignments:", error.message);
         }
     }
-    /**
-     * Sets up workspace by cloning repository or using existing clone
-     * Returns the absolute path to the workspace
-     */
-    setupWorkspace(workspacePath, repoUrl, defaultBranch, projectName) {
-        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.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.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
      */
     ensureSandboxOpencodeConfig() {
-        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 = {
-            ...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));
+        writeSandboxOpencodeConfig({
+            configPath: SANDBOX_OPENCODE_CONFIG_PATH,
+            baseConfig: SANDBOX_OPENCODE_CONFIG,
+            model: this.runnerConfig.env?.OPENCODE_MODEL,
+        });
         console.log(`Updated sandbox OpenCode config: ${SANDBOX_OPENCODE_CONFIG_PATH}`);
     }
 }