@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/teams/agents.js

@@ -1,5 +1,15 @@
-import { spawn, execSync } from 'child_process';
+/**
+ * Teams agent lifecycle management.
+ *
+ * Defines the AgentProcess and AgentManager classes that handle spawning,
+ * monitoring, stopping, and persisting teammate processes across all supported
+ * agent CLIs (Claude, Codex, Gemini, Cursor, OpenCode). Supports DAG-based
+ * dependency scheduling via --after, per-teammate model/effort overrides, and
+ * multiple permission modes (plan, edit, full).
+ */
+import { spawn, execSync, execFileSync } from 'child_process';
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
@@ -7,6 +17,53 @@ import { resolveAgentsDir } from './persistence.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { buildReasoningFlags } from '../models.js';
+import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
+import { getAgentsDir as getSystemAgentsDir } from '../state.js';
+let lastMemoryWarnAt = 0;
+// On macOS, os.freemem() returns only the truly-free pool and ignores the
+// large inactive+purgeable cache the kernel will reclaim under pressure, so
+// it always looks alarmingly low on a healthy Mac. Parse vm_stat to get the
+// real "available" figure: free + inactive + purgeable + speculative.
+function availableMemoryBytes() {
+    if (process.platform !== 'darwin')
+        return os.freemem();
+    try {
+        const out = execSync('vm_stat', { encoding: 'utf8', timeout: 1000 });
+        const pageSizeMatch = out.match(/page size of (\d+) bytes/);
+        const pageSize = pageSizeMatch ? Number(pageSizeMatch[1]) : 4096;
+        const grab = (label) => {
+            const m = out.match(new RegExp(`${label}:\\s+(\\d+)\\.`));
+            return m ? Number(m[1]) : 0;
+        };
+        const pages = grab('Pages free') +
+            grab('Pages inactive') +
+            grab('Pages purgeable') +
+            grab('Pages speculative');
+        if (pages <= 0)
+            return os.freemem();
+        return pages * pageSize;
+    }
+    catch {
+        return os.freemem();
+    }
+}
+function warnIfMemoryLow(runningCount) {
+    const total = os.totalmem();
+    if (total <= 0)
+        return;
+    const available = availableMemoryBytes();
+    const freeRatio = available / total;
+    if (freeRatio >= 0.15)
+        return;
+    const now = Date.now();
+    if (now - lastMemoryWarnAt < 60_000)
+        return;
+    lastMemoryWarnAt = now;
+    const freeGb = (available / 1024 ** 3).toFixed(1);
+    const totalGb = (total / 1024 ** 3).toFixed(1);
+    process.stderr.write(`Heads up: only ${freeGb}GB of ${totalGb}GB free with ${runningCount} teammates already running. ` +
+        `Spawning more may slow your machine.\n`);
+}
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
  * Returns the deepest common directory shared by all paths.
@@ -44,6 +101,7 @@ export function computePathLCA(paths) {
     const lca = path.sep + commonSegments.join(path.sep);
     return lca;
 }
+/** Lifecycle status of a teammate process. */
 export var AgentStatus;
 (function (AgentStatus) {
     AgentStatus["PENDING"] = "pending";
@@ -52,6 +110,9 @@ export var AgentStatus;
     AgentStatus["FAILED"] = "failed";
     AgentStatus["STOPPED"] = "stopped";
 })(AgentStatus || (AgentStatus = {}));
+export const VALID_TASK_TYPES = [
+    'plan', 'implement', 'test', 'review', 'bugfix', 'docs',
+];
 /**
  * Walk the `after` chain from `startName` within the given map; returns true
  * if `targetName` appears anywhere in the transitive dependency closure.
@@ -72,14 +133,129 @@ function hasTransitiveDep(byName, startName, targetName, seen = new Set()) {
     }
     return false;
 }
-// Base commands for plan mode (read-only, may prompt for confirmation)
+/**
+ * Capture a stable identifier for a process at the moment it was started.
+ * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
+ * still occupies the PID we observed at spawn time. A bare kill(pid, 0)
+ * probe cannot tell whether the OS has recycled the slot to an unrelated
+ * process — combined with detached spawns and unref(), that's exactly how
+ * `agents teams stop` ends up SIGKILLing random process groups.
+ *
+ * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
+ * Returns null on any error so callers can skip the guard rather than crash.
+ */
+export function captureProcessStartTime(pid) {
+    if (!pid || pid <= 0)
+        return null;
+    try {
+        if (process.platform === 'linux') {
+            const stat = fsSync.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            const lastParen = stat.lastIndexOf(')');
+            if (lastParen < 0)
+                return null;
+            const tail = stat.slice(lastParen + 2);
+            const fields = tail.split(' ');
+            // After comm we are at field 3; starttime is field 22, so index 19 here.
+            return fields[19] || null;
+        }
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = out.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Base commands for plan mode (read-only). applyEditMode / applyFullMode
+// rewrite these for write-capable modes. Each agent's read-only flag MUST be
+// here so a plan-mode teammate truly cannot write — even if the teammate
+// prompt tries to ignore the instruction. See agents.test.ts for the contract.
 export const AGENT_COMMANDS = {
-    codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
+    codex: ['codex', 'exec', '--sandbox', 'read-only', '{prompt}', '--json'],
     cursor: ['cursor-agent', '-p', '--output-format', 'stream-json', '{prompt}'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json', '--approval-mode', 'plan'],
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     opencode: ['opencode', 'run', '--format', 'json', '{prompt}'],
 };
+/**
+ * Rewrite a plan-mode command into edit mode (writes inside cwd allowed,
+ * approval prompts may still appear). Pure function — exported for tests.
+ */
+export function applyEditMode(agentType, cmd) {
+    const editCmd = [...cmd];
+    switch (agentType) {
+        case 'codex': {
+            // Swap --sandbox read-only -> --sandbox workspace-write so the codex
+            // sandbox actually permits writes. --full-auto then disables approvals.
+            const sandboxIndex = editCmd.indexOf('--sandbox');
+            if (sandboxIndex !== -1 && sandboxIndex + 1 < editCmd.length) {
+                editCmd[sandboxIndex + 1] = 'workspace-write';
+            }
+            editCmd.push('--full-auto');
+            break;
+        }
+        case 'cursor':
+            editCmd.push('-f');
+            break;
+        case 'gemini': {
+            const approvalIndex = editCmd.indexOf('--approval-mode');
+            if (approvalIndex !== -1) {
+                editCmd.splice(approvalIndex, 2);
+            }
+            editCmd.push('--yolo');
+            break;
+        }
+        case 'claude': {
+            const permModeIndex = editCmd.indexOf('--permission-mode');
+            if (permModeIndex !== -1 && permModeIndex + 1 < editCmd.length) {
+                editCmd[permModeIndex + 1] = 'acceptEdits';
+            }
+            break;
+        }
+    }
+    return editCmd;
+}
+/**
+ * Rewrite a plan-mode command into full mode (writes + approval gates
+ * bypassed). Pure function — exported for tests.
+ */
+export function applyFullMode(agentType, cmd) {
+    const fullCmd = [...cmd];
+    switch (agentType) {
+        case 'codex': {
+            const sandboxIndex = fullCmd.indexOf('--sandbox');
+            if (sandboxIndex !== -1 && sandboxIndex + 1 < fullCmd.length) {
+                fullCmd[sandboxIndex + 1] = 'workspace-write';
+            }
+            fullCmd.push('--full-auto');
+            break;
+        }
+        case 'cursor':
+            fullCmd.push('-f');
+            break;
+        case 'gemini': {
+            const approvalIndex = fullCmd.indexOf('--approval-mode');
+            if (approvalIndex !== -1) {
+                fullCmd.splice(approvalIndex, 2);
+            }
+            fullCmd.push('--yolo');
+            break;
+        }
+        case 'claude': {
+            const permModeIndex = fullCmd.indexOf('--permission-mode');
+            if (permModeIndex !== -1) {
+                fullCmd.splice(permModeIndex, 2);
+            }
+            fullCmd.push('--dangerously-skip-permissions');
+            break;
+        }
+    }
+    return fullCmd;
+}
 // Minimal defaults — no per-effort model map. Configs on disk may still have
 // a model pinned; launchProcess picks it up from agent.model when set.
 function loadDefaultAgentConfigs() {
@@ -168,6 +344,7 @@ function extractTimestamp(raw) {
     }
     return null;
 }
+/** Resolve a mode string to a validated Mode, falling back to the given default. */
 export function resolveMode(requestedMode, defaultMode = 'plan') {
     const normalizedDefault = normalizeModeValue(defaultMode);
     if (!normalizedDefault) {
@@ -182,28 +359,31 @@ export function resolveMode(requestedMode, defaultMode = 'plan') {
     }
     return normalizedDefault;
 }
+/** Ensure Gemini's settings.json has experimental.plan enabled for headless plan mode. */
 export async function ensureGeminiPlanMode() {
     const settingsPath = path.join(os.homedir(), '.gemini', 'settings.json');
     try {
-        let settings = {};
-        try {
-            const raw = await fs.readFile(settingsPath, 'utf-8');
-            settings = JSON.parse(raw);
-        }
-        catch {
-            // No settings file or invalid JSON
+        let changed = false;
+        const settings = updateGeminiSettings(settingsPath, (nextSettings) => {
+            setGeminiAutoUpdateDisabled(nextSettings);
+            const experimental = typeof nextSettings.experimental === 'object' && nextSettings.experimental !== null
+                ? nextSettings.experimental
+                : {};
+            if (experimental.plan === true) {
+                return;
+            }
+            nextSettings.experimental = { ...experimental, plan: true };
+            changed = true;
+        });
+        if (changed && settings.experimental && typeof settings.experimental === 'object' && settings.experimental.plan === true) {
+            console.error('[Swarm] Enabled Gemini experimental.plan in', settingsPath);
         }
-        if (settings.experimental?.plan === true)
-            return;
-        settings.experimental = { ...settings.experimental, plan: true };
-        await fs.mkdir(path.dirname(settingsPath), { recursive: true });
-        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-        console.error('[Swarm] Enabled Gemini experimental.plan in', settingsPath);
     }
     catch (err) {
         console.warn('[Swarm] Could not enable Gemini plan mode:', err);
     }
 }
+/** Check whether the CLI binary for a given agent type exists in PATH. Returns [available, pathOrError]. */
 export function checkCliAvailable(agentType) {
     const cmdTemplate = AGENT_COMMANDS[agentType];
     if (!cmdTemplate) {
@@ -218,6 +398,7 @@ export function checkCliAvailable(agentType) {
         return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
     }
 }
+/** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {
     const results = {};
     for (const agentType of Object.keys(AGENT_COMMANDS)) {
@@ -232,12 +413,20 @@ export function checkAllClis() {
     return results;
 }
 let AGENTS_DIR = null;
+/** Resolve and cache the base directory where teammate process data is stored. */
 export async function getAgentsDir() {
     if (!AGENTS_DIR) {
         AGENTS_DIR = await resolveAgentsDir();
     }
     return AGENTS_DIR;
 }
+/**
+ * Represents a single teammate process within a team.
+ *
+ * Tracks process metadata (PID, status, timestamps), reads incremental
+ * stdout events, persists state to disk as meta.json, and can be
+ * reconstituted from disk via loadFromDisk().
+ */
 export class AgentProcess {
     agentId;
     taskName;
@@ -247,6 +436,9 @@ export class AgentProcess {
     workspaceDir;
     mode = 'plan';
     pid = null;
+    // Captured at spawn time so we can detect PID reuse before signaling.
+    // Compared against the live /proc or `ps` value at every kill() call.
+    startTime = null;
     status = AgentStatus.RUNNING;
     startedAt = new Date();
     completedAt = null;
@@ -269,10 +461,17 @@ export class AgentProcess {
     model = null;
     // Extra env vars passed through to the child process (from --env KEY=VALUE).
     envOverrides = null;
+    // Factory task-type label. Drives planner fan-out. Null for plain teammates — no behavioral change.
+    taskType = null;
+    // Repo/branch for cloud dispatches that stage behind --after. Captured
+    // at spawn time so startReady() can invoke the dispatcher with the same
+    // options the user originally supplied.
+    cloudRepo = null;
+    cloudBranch = null;
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
-    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null) {
+    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null) {
         this.agentId = agentId;
         this.remoteSessionId = remoteSessionId;
         this.name = name;
@@ -280,6 +479,9 @@ export class AgentProcess {
         this.effort = effort;
         this.model = model;
         this.envOverrides = envOverrides;
+        this.taskType = taskType;
+        this.cloudRepo = cloudRepo;
+        this.cloudBranch = cloudBranch;
         this.taskName = taskName;
         this.agentType = agentType;
         this.prompt = prompt;
@@ -304,6 +506,29 @@ export class AgentProcess {
         const base = this.baseDir || await getAgentsDir();
         return path.join(base, this.agentId);
     }
+    /**
+     * Dump the subset of state the Ledger sync hook needs. Keeps sync.ts
+     * free of any teams-internal imports.
+     */
+    async toSnapshot() {
+        return {
+            agent_id: this.agentId,
+            team_id: this.taskName,
+            teammate_name: this.name,
+            agent_type: this.agentType,
+            task_type: this.taskType,
+            status: this.status,
+            started_at: this.startedAt.toISOString(),
+            completed_at: this.completedAt?.toISOString() ?? null,
+            after: this.after,
+            cloud_provider: this.cloudProvider,
+            cloud_session_id: this.cloudSessionId,
+            cloud_repo: this.cloudRepo,
+            cloud_branch: this.cloudBranch,
+            agent_dir: await this.getAgentDir(),
+            cwd: this.cwd,
+        };
+    }
     async getStdoutPath() {
         return path.join(await this.getAgentDir(), 'stdout.log');
     }
@@ -333,6 +558,9 @@ export class AgentProcess {
             effort: this.effort,
             model: this.model,
             env_overrides: this.envOverrides,
+            task_type: this.taskType,
+            cloud_repo: this.cloudRepo,
+            cloud_branch: this.cloudBranch,
         };
     }
     duration() {
@@ -445,6 +673,7 @@ export class AgentProcess {
             workspace_dir: this.workspaceDir,
             mode: this.mode,
             pid: this.pid,
+            start_time: this.startTime,
             status: this.status,
             started_at: this.startedAt.toISOString(),
             completed_at: this.completedAt?.toISOString() || null,
@@ -459,6 +688,9 @@ export class AgentProcess {
             effort: this.effort,
             model: this.model,
             env_overrides: this.envOverrides,
+            task_type: this.taskType,
+            cloud_repo: this.cloudRepo,
+            cloud_branch: this.cloudBranch,
         };
         const metaPath = await this.getMetaPath();
         await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
@@ -492,7 +724,10 @@ export class AgentProcess {
             const resolvedStatus = validStatuses.includes(meta.status)
                 ? meta.status
                 : AgentStatus.RUNNING;
-            const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, resolvedMode, meta.pid || null, resolvedStatus, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null, meta.cloud_session_id || null, meta.cloud_provider || null, meta.pr_url || null, meta.version || null, meta.remote_session_id || null, meta.name || null, Array.isArray(meta.after) ? meta.after : [], meta.effort || null, meta.model || null, meta.env_overrides || null);
+            const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, resolvedMode, meta.pid || null, resolvedStatus, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null, meta.cloud_session_id || null, meta.cloud_provider || null, meta.pr_url || null, meta.version || null, meta.remote_session_id || null, meta.name || null, Array.isArray(meta.after) ? meta.after : [], meta.effort || null, meta.model || null, meta.env_overrides || null, meta.task_type && VALID_TASK_TYPES.includes(meta.task_type)
+                ? meta.task_type
+                : null, meta.cloud_repo || null, meta.cloud_branch || null);
+            agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
             return agent;
         }
         catch {
@@ -504,15 +739,61 @@ export class AgentProcess {
             return false;
         try {
             process.kill(this.pid, 0);
-            return true;
         }
         catch {
             return false;
         }
+        // PID is occupied — but is it still OUR process? If we captured a
+        // start-time at spawn, refuse to claim aliveness when the live value
+        // differs. A null startTime means we never captured one (legacy
+        // teammates loaded from disk before this field existed) — fall back to
+        // the bare kill(pid, 0) result for those.
+        if (this.startTime !== null) {
+            const current = captureProcessStartTime(this.pid);
+            if (current === null || current !== this.startTime) {
+                return false;
+            }
+        }
+        return true;
     }
     async updateStatusFromProcess() {
-        if (!this.pid)
+        if (!this.pid) {
+            await this.readNewEvents();
+            // Cloud-backed teammates have no local PID by design; their lifecycle
+            // is driven by the remote provider instead of a local process.
+            if (this.cloudProvider) {
+                if (!this.completedAt && this.status !== AgentStatus.RUNNING) {
+                    const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
+                    this.completedAt = fallbackCompletion;
+                    await this.saveMeta();
+                }
+                return;
+            }
+            // Pending teammates with unresolved --after deps also have no PID yet.
+            // Leave them alone until startReady() launches them.
+            if (this.status === AgentStatus.PENDING) {
+                return;
+            }
+            // A local teammate marked RUNNING without a PID is an impossible state:
+            // launch never produced a durable process identity, so it cannot still
+            // be doing work. Keep any terminal event parsed from stdout; otherwise
+            // fail it and stamp completion so team rollups stop showing it as live.
+            if (this.status === AgentStatus.RUNNING) {
+                const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
+                if (this.status === AgentStatus.RUNNING) {
+                    this.status = AgentStatus.FAILED;
+                    this.completedAt = fallbackCompletion;
+                }
+                await this.saveMeta();
+                return;
+            }
+            if (!this.completedAt) {
+                const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
+                this.completedAt = fallbackCompletion;
+                await this.saveMeta();
+            }
             return;
+        }
         if (this.isProcessAlive()) {
             await this.readNewEvents();
             return;
@@ -553,7 +834,6 @@ export class AgentProcess {
 export class AgentManager {
     agents = new Map();
     maxAgents;
-    maxConcurrent;
     agentsDir = '';
     filterByCwd;
     cleanupAgeDays;
@@ -561,10 +841,10 @@ export class AgentManager {
     agentConfigs;
     constructorAgentConfigs = null;
     initPromise = null;
+    cloudDispatcher = null;
     constructorAgentsDir = null;
-    constructor(maxAgents = 50, maxConcurrent = 10, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7, agentConfigs = null) {
+    constructor(maxAgents = 50, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7, agentConfigs = null) {
         this.maxAgents = maxAgents;
-        this.maxConcurrent = maxConcurrent;
         this.constructorAgentsDir = agentsDir;
         this.filterByCwd = filterByCwd;
         this.cleanupAgeDays = cleanupAgeDays;
@@ -594,9 +874,53 @@ export class AgentManager {
     setModelOverrides(agentConfigs) {
         this.agentConfigs = agentConfigs;
     }
+    /**
+     * Register the callback used to dispatch cloud-backed teammates when their
+     * --after deps resolve. Called once at CLI startup by `agents teams`.
+     */
+    setCloudDispatcher(fn) {
+        this.cloudDispatcher = fn;
+    }
     registerAgent(agent) {
         this.agents.set(agent.agentId, agent);
     }
+    /**
+     * Scan the agents dir for meta.json files not already in the in-memory
+     * cache and load them. Needed when another process (e.g. a Planner
+     * teammate running `agents teams add`) creates new teammates while this
+     * manager is alive — the supervisor loop calls this each wave so
+     * dynamically-added teammates get picked up.
+     *
+     * Does not modify or re-load agents already in the cache; that path is
+     * covered by updateStatusFromProcess() which re-reads stdout.log.
+     */
+    async rescanFromDisk() {
+        await this.initialize();
+        try {
+            await fs.access(this.agentsDir);
+        }
+        catch {
+            return 0;
+        }
+        const entries = await fs.readdir(this.agentsDir);
+        let added = 0;
+        for (const entry of entries) {
+            if (this.agents.has(entry))
+                continue;
+            const agentDir = path.join(this.agentsDir, entry);
+            const stat = await fs.stat(agentDir).catch(() => null);
+            if (!stat || !stat.isDirectory())
+                continue;
+            const agent = await AgentProcess.loadFromDisk(entry, this.agentsDir);
+            if (!agent)
+                continue;
+            if (this.filterByCwd !== null && agent.cwd !== this.filterByCwd)
+                continue;
+            this.agents.set(entry, agent);
+            added++;
+        }
+        return added;
+    }
     async loadExistingAgents() {
         try {
             await fs.access(this.agentsDir);
@@ -647,7 +971,7 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null) {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Enforce: teammate names are unique within a team.
@@ -689,15 +1013,24 @@ export class AgentManager {
                 throw new Error(`Working directory is not a directory: ${cwd}`);
             }
         }
-        const [available, pathOrError] = checkCliAvailable(agentType);
-        if (!available) {
-            throw new Error(pathOrError || 'CLI tool not available');
+        // Cloud-backed teammates run on remote infrastructure; we don't need the
+        // local CLI for them (the pod has its own). The caller has already
+        // dispatched via the cloud provider and passed us the provider + session.
+        const isCloudBacked = Boolean(cloudProvider);
+        if (!isCloudBacked) {
+            const [available, pathOrError] = checkCliAvailable(agentType);
+            if (!available) {
+                throw new Error(pathOrError || 'CLI tool not available');
+            }
         }
         // Use a full UUIDv4 as the canonical agent_id. For Claude, we pass it via
         // --session-id so it's also Claude's session id (unified identity).
         const agentId = randomUUID();
         const isStaged = cleanAfter.length > 0;
-        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, isStaged ? AgentStatus.PENDING : AgentStatus.RUNNING, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, null, null, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null);
+        const initialStatus = isStaged || !isCloudBacked
+            ? AgentStatus.PENDING
+            : AgentStatus.RUNNING;
+        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch);
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -705,13 +1038,19 @@ export class AgentManager {
         catch (err) {
             throw new Error(`Failed to create agent directory: ${err.message}`);
         }
-        await agent.saveMeta();
         this.agents.set(agentId, agent);
-        if (!isStaged) {
-            await this.launchProcess(agent);
+        if (isStaged) {
+            await agent.saveMeta();
+            debug(`Staged ${agentType} teammate '${name}' in team '${taskName}' (after: ${cleanAfter.join(', ')})`);
+        }
+        else if (isCloudBacked) {
+            // Cloud-backed teammate: the provider already dispatched a remote task.
+            // No local process to launch; status polling walks the provider instead.
+            await agent.saveMeta();
+            debug(`Cloud-backed ${agentType} teammate via ${cloudProvider} (session=${cloudSessionId})`);
         }
         else {
-            debug(`Staged ${agentType} teammate '${name}' in team '${taskName}' (after: ${cleanAfter.join(', ')})`);
+            await this.launchProcess(agent);
         }
         await this.cleanupOldAgents();
         return agent;
@@ -722,9 +1061,7 @@ export class AgentManager {
      */
     async launchProcess(agent) {
         const running = await this.listRunning();
-        if (running.length >= this.maxConcurrent) {
-            throw new Error(`Maximum concurrent agents (${this.maxConcurrent}) reached. Wait for an agent to complete or stop one first.`);
-        }
+        warnIfMemoryLow(running.length);
         const effort = agent.effort ?? 'medium';
         // Falls back to the pinned model in agentConfigs; null means "let the
         // CLI pick its own default" (no --model flag forwarded). Effort is a
@@ -750,6 +1087,11 @@ export class AgentManager {
             childProcess.unref();
             stdoutFile.close().catch(() => { });
             agent.pid = childProcess.pid || null;
+            // Capture start-time NOW, while we know the PID is ours. Once the
+            // OS reuses this PID slot, /proc and `ps` will report a different
+            // value — that's the signal stop() uses to refuse to signal an
+            // unrelated process.
+            agent.startTime = agent.pid ? captureProcessStartTime(agent.pid) : null;
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
@@ -782,8 +1124,22 @@ export class AgentManager {
             if (!depsReady)
                 continue;
             try {
-                await this.launchProcess(agent);
-                launched.push(agent);
+                if (agent.cloudProvider) {
+                    if (!this.cloudDispatcher) {
+                        console.error(`Cannot start cloud-backed teammate ${agent.agentId}: no dispatcher registered.`);
+                        continue;
+                    }
+                    const { cloudSessionId } = await this.cloudDispatcher(agent);
+                    agent.cloudSessionId = cloudSessionId;
+                    agent.status = AgentStatus.RUNNING;
+                    agent.startedAt = new Date();
+                    await agent.saveMeta();
+                    launched.push(agent);
+                }
+                else {
+                    await this.launchProcess(agent);
+                    launched.push(agent);
+                }
             }
             catch (err) {
                 console.error(`Could not launch ${agent.agentId}:`, err);
@@ -821,6 +1177,14 @@ export class AgentManager {
             // ~/.claude/settings.json would override that and bind settings to the
             // *default* version rather than the one this teammate is running.
         }
+        if (agentType === 'codex') {
+            // Codex's workspace-write sandbox blocks writes outside cwd. Factory
+            // teammates need to run further `agents teams add` commands,
+            // which write to ~/.agents/. Grant that root so subprocess-issued
+            // `agents teams add` calls hit the real store instead of the tmp
+            // fallback (which the supervisor does not watch).
+            cmd.push('--add-dir', getSystemAgentsDir());
+        }
         // Add model flag for each agent type only when the teammate has a pinned
         // model. When null, the agent's CLI picks its own default.
         if (model) {
@@ -870,61 +1234,10 @@ export class AgentManager {
         return cmd;
     }
     applyEditMode(agentType, cmd) {
-        const editCmd = [...cmd];
-        switch (agentType) {
-            case 'codex':
-                editCmd.push('--full-auto');
-                break;
-            case 'cursor':
-                editCmd.push('-f');
-                break;
-            case 'gemini': {
-                const approvalIndex = editCmd.indexOf('--approval-mode');
-                if (approvalIndex !== -1) {
-                    editCmd.splice(approvalIndex, 2);
-                }
-                editCmd.push('--yolo');
-                break;
-            }
-            case 'claude':
-                const permModeIndex = editCmd.indexOf('--permission-mode');
-                if (permModeIndex !== -1 && permModeIndex + 1 < editCmd.length) {
-                    editCmd[permModeIndex + 1] = 'acceptEdits';
-                }
-                break;
-        }
-        return editCmd;
+        return applyEditMode(agentType, cmd);
     }
-    // "full" mode: edit-level write access with permission gates bypassed.
-    // For Claude that's --dangerously-skip-permissions; other agents already
-    // lack gates in edit mode so their commands match applyEditMode.
     applyFullMode(agentType, cmd) {
-        const fullCmd = [...cmd];
-        switch (agentType) {
-            case 'codex':
-                fullCmd.push('--full-auto');
-                break;
-            case 'cursor':
-                fullCmd.push('-f');
-                break;
-            case 'gemini': {
-                const approvalIndex = fullCmd.indexOf('--approval-mode');
-                if (approvalIndex !== -1) {
-                    fullCmd.splice(approvalIndex, 2);
-                }
-                fullCmd.push('--yolo');
-                break;
-            }
-            case 'claude':
-                // Replace --permission-mode plan with --dangerously-skip-permissions
-                const permModeIndex = fullCmd.indexOf('--permission-mode');
-                if (permModeIndex !== -1) {
-                    fullCmd.splice(permModeIndex, 2); // Remove --permission-mode and its value
-                }
-                fullCmd.push('--dangerously-skip-permissions');
-                break;
-        }
-        return fullCmd;
+        return applyFullMode(agentType, cmd);
     }
     async get(agentId) {
         await this.initialize();
@@ -1019,6 +1332,17 @@ export class AgentManager {
             return false;
         }
         if (agent.pid && agent.status === AgentStatus.RUNNING) {
+            // PID-reuse guard: if the PID we recorded at spawn no longer maps to
+            // our process (start-time mismatch), the OS has recycled it. Sending
+            // SIGTERM/SIGKILL to -pid here would kill an unrelated process group.
+            // Treat as already gone and just record the stop without signaling.
+            if (!agent.isProcessAlive()) {
+                debug(`Agent ${agentId} PID ${agent.pid} no longer ours (start-time mismatch or exited); skipping signal`);
+                agent.status = AgentStatus.STOPPED;
+                agent.completedAt = new Date();
+                await agent.saveMeta();
+                return true;
+            }
             try {
                 process.kill(-agent.pid, 'SIGTERM');
                 debug(`Sent SIGTERM to agent ${agentId} (PID ${agent.pid})`);
@@ -1069,4 +1393,3 @@ export class AgentManager {
         }
     }
 }
-//# sourceMappingURL=agents.js.map