@phnx-labs/agents-cli 1.20.57 → 1.20.59

package/dist/lib/staleness/writers/subagents.js

@@ -13,7 +13,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
-import { listInstalledSubagents, transformSubagentForClaude, transformSubagentForCodex, writeKimiSubagentFiles, buildKimiSubagentsParentYaml, KIMI_SUBAGENTS_PARENT_FILE, transformSubagentForOpenCode, transformSubagentForDroid, syncSubagentToOpenclaw, parseSubagentFrontmatter, } from '../../subagents.js';
+import { listInstalledSubagents, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, writeKimiSubagentFiles, buildKimiSubagentsParentYaml, KIMI_SUBAGENTS_PARENT_FILE, transformSubagentForOpenCode, transformSubagentForDroid, transformSubagentForKiro, syncSubagentToOpenclaw, parseSubagentFrontmatter, } from '../../subagents.js';
 import { safeJoin } from '../../paths.js';
 import { lazyAgentMap } from './lazy-map.js';
 function buildSubagentsWriter(agent) {
@@ -57,12 +57,24 @@ function buildSubagentsWriter(agent) {
                         fs.writeFileSync(safeJoin(droidsDir, `${sub.name}.md`), transformSubagentForDroid(sub.path));
                         synced.push(sub.name);
                     }
+                    else if (agent === 'copilot') {
+                        const agentsDir = path.join(versionHome, '.copilot', 'agents');
+                        fs.mkdirSync(agentsDir, { recursive: true });
+                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.agent.md`), transformSubagentForCopilot(sub.path));
+                        synced.push(sub.name);
+                    }
                     else if (agent === 'openclaw') {
                         const target = safeJoin(path.join(versionHome, '.openclaw'), sub.name);
                         const r = syncSubagentToOpenclaw(sub.path, target);
                         if (r.success)
                             synced.push(sub.name);
                     }
+                    else if (agent === 'kiro') {
+                        const agentsDir = path.join(versionHome, '.kiro', 'agents');
+                        fs.mkdirSync(agentsDir, { recursive: true });
+                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.json`), transformSubagentForKiro(sub.path));
+                        synced.push(sub.name);
+                    }
                 }
                 catch { /* per-item sync failure: skip */ }
             }

package/dist/lib/startup/command-registry.d.ts

@@ -65,6 +65,7 @@ export declare const loadDrive: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
 export declare const loadCost: ModuleLoader;
+export declare const loadOutput: ModuleLoader;
 export declare const loadBudget: ModuleLoader;
 export declare const loadAlias: ModuleLoader;
 export declare const loadPty: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -43,6 +43,7 @@ export const loadDrive = async () => (await import('../../commands/drive.js')).r
 export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
 export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
+export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
 export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
 export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
 export const loadPty = async () => (await import('../../commands/pty.js')).registerPtyCommands;
@@ -137,6 +138,7 @@ export const COMMAND_LOADERS = {
     factory: [loadFactory],
     usage: [loadUsage],
     cost: [loadCost],
+    output: [loadOutput],
     budget: [loadBudget],
     alias: [loadAlias],
     pty: [loadPty],

package/dist/lib/subagents.d.ts

@@ -56,6 +56,18 @@ export declare function transformSubagentForClaude(subagentDir: string): string;
  * See https://docs.factory.ai/cli/configuration/custom-droids.
  */
 export declare function transformSubagentForDroid(subagentDir: string): string;
+/**
+ * Transform a subagent into a GitHub Copilot CLI custom agent `.agent.md` file.
+ *
+ * Copilot custom agents are Markdown profiles with YAML frontmatter stored in
+ * `~/.copilot/agents/` (user) or `.github/agents/` (project). The file name
+ * ends in `.agent.md` and the frontmatter carries `name`, `description`, and
+ * optionally `model` and `tools`. The emitted body is identical to Factory
+ * Droid's custom-droid format (flatten frontmatter + body + appended .md
+ * sections, `color` dropped), so this is an alias of transformSubagentForDroid.
+ * See GitHub docs for custom agents.
+ */
+export declare const transformSubagentForCopilot: typeof transformSubagentForDroid;
 /**
  * Transform a subagent into an OpenCode agent markdown file.
  *
@@ -107,6 +119,16 @@ export declare function writeKimiSubagentFiles(agentsDir: string, subagentDir: s
  * https://developers.openai.com/codex/subagents (custom agents section)
  */
 export declare function transformSubagentForCodex(subagentDir: string): string;
+/**
+ * Transform a subagent into a Kiro CLI custom-agent JSON file.
+ *
+ * Kiro custom agents live in `~/.kiro/agents/<name>.json` (or `.kiro/agents/`
+ * workspace-local) and declare name, description, prompt, tools, and optional
+ * model. We flatten the AGENT.md frontmatter + body plus any sibling .md files
+ * as sections into a single `prompt`, and expose the standard built-in tool
+ * set so the subagent can actually run.
+ */
+export declare function transformSubagentForKiro(subagentDir: string): string;
 /**
  * Sync a subagent to an OpenClaw workspace
  * Copies full directory, renames AGENT.md to AGENTS.md
@@ -137,6 +159,7 @@ export declare function subagentContentMatches(installedDir: string, sourceDir:
  * List subagents installed to a specific agent's home
  * Claude: scans ~/.claude/agents/{name}.md
  * Kimi: scans ~/.kimi-code/agents/{name}.yaml (+ sibling .system.md)
+ * Kiro: scans ~/.kiro/agents/{name}.json
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export declare function listSubagentsForAgent(agentId: AgentId, home: string): InstalledSubagent[];

package/dist/lib/subagents.js

@@ -262,6 +262,18 @@ export function transformSubagentForDroid(subagentDir) {
     }
     return result;
 }
+/**
+ * Transform a subagent into a GitHub Copilot CLI custom agent `.agent.md` file.
+ *
+ * Copilot custom agents are Markdown profiles with YAML frontmatter stored in
+ * `~/.copilot/agents/` (user) or `.github/agents/` (project). The file name
+ * ends in `.agent.md` and the frontmatter carries `name`, `description`, and
+ * optionally `model` and `tools`. The emitted body is identical to Factory
+ * Droid's custom-droid format (flatten frontmatter + body + appended .md
+ * sections, `color` dropped), so this is an alias of transformSubagentForDroid.
+ * See GitHub docs for custom agents.
+ */
+export const transformSubagentForCopilot = transformSubagentForDroid;
 /**
  * Transform a subagent into an OpenCode agent markdown file.
  *
@@ -381,21 +393,10 @@ export function writeKimiSubagentFiles(agentsDir, subagentDir, name) {
 export function transformSubagentForCodex(subagentDir) {
     const agentMd = path.join(subagentDir, 'AGENT.md');
     const frontmatter = parseSubagentFrontmatter(agentMd);
-    const body = getSubagentBody(agentMd);
     if (!frontmatter) {
         throw new Error(`Invalid AGENT.md in ${subagentDir}`);
     }
-    // Append other .md files into the developer_instructions body.
-    let instructions = body.trim();
-    const files = fs.readdirSync(subagentDir)
-        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
-        .sort();
-    for (const file of files) {
-        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
-        const sectionName = file.replace('.md', '');
-        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
-        instructions += `\n\n## ${title}\n\n${content}`;
-    }
+    const instructions = flattenSubagentInstructions(subagentDir);
     // Escape TOML multi-line string (""") content — only """ needs escaping.
     const safeInstructions = instructions.replace(/"""/g, '\\"""');
     const safeName = frontmatter.name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
@@ -409,6 +410,56 @@ export function transformSubagentForCodex(subagentDir) {
     toml += `developer_instructions = """\n${safeInstructions}\n"""\n`;
     return toml;
 }
+function flattenSubagentInstructions(subagentDir) {
+    let instructions = getSubagentBody(path.join(subagentDir, 'AGENT.md')).trim();
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        instructions += `\n\n## ${title}\n\n${content}`;
+    }
+    return instructions;
+}
+/**
+ * Transform a subagent into a Kiro CLI custom-agent JSON file.
+ *
+ * Kiro custom agents live in `~/.kiro/agents/<name>.json` (or `.kiro/agents/`
+ * workspace-local) and declare name, description, prompt, tools, and optional
+ * model. We flatten the AGENT.md frontmatter + body plus any sibling .md files
+ * as sections into a single `prompt`, and expose the standard built-in tool
+ * set so the subagent can actually run.
+ */
+export function transformSubagentForKiro(subagentDir) {
+    const agentMd = path.join(subagentDir, 'AGENT.md');
+    const frontmatter = parseSubagentFrontmatter(agentMd);
+    const body = getSubagentBody(agentMd);
+    if (!frontmatter) {
+        throw new Error(`Invalid AGENT.md in ${subagentDir}`);
+    }
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    let prompt = body;
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(subagentDir, file), 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        prompt += `\n\n## ${title}\n\n${content}`;
+    }
+    const config = {
+        name: frontmatter.name,
+        description: frontmatter.description,
+        prompt,
+        tools: ['read', 'write', 'shell', 'web_search', 'web_fetch'],
+    };
+    if (frontmatter.model) {
+        config.model = frontmatter.model;
+    }
+    return JSON.stringify(config, null, 2);
+}
 /**
  * Sync a subagent to an OpenClaw workspace
  * Copies full directory, renames AGENT.md to AGENTS.md
@@ -497,6 +548,21 @@ export function installSubagentToAgent(subagentDir, subagentName, agent, agentHo
         const targetDir = safeJoin(path.join(agentHome, '.openclaw'), subagentName);
         return syncSubagentToOpenclaw(subagentDir, targetDir);
     }
+    else if (agent === 'kiro') {
+        // Kiro: JSON custom-agent file under ~/.kiro/agents/
+        const agentsDir = path.join(agentHome, '.kiro', 'agents');
+        if (!fs.existsSync(agentsDir)) {
+            fs.mkdirSync(agentsDir, { recursive: true });
+        }
+        try {
+            const transformed = transformSubagentForKiro(subagentDir);
+            fs.writeFileSync(safeJoin(agentsDir, `${subagentName}.json`), transformed);
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: String(err) };
+        }
+    }
     else {
         // Other agents don't support subagents yet
         return { success: false, error: `Agent '${agent}' does not support subagents` };
@@ -545,6 +611,13 @@ export function removeSubagentFromAgent(subagentName, agent, agentHome) {
             }
             return { success: true };
         }
+        else if (agent === 'kiro') {
+            const targetPath = safeJoin(path.join(agentHome, '.kiro', 'agents'), `${subagentName}.json`);
+            if (fs.existsSync(targetPath)) {
+                fs.unlinkSync(targetPath);
+            }
+            return { success: true };
+        }
         else {
             return { success: true }; // No-op for unsupported agents
         }
@@ -584,6 +657,7 @@ export function subagentContentMatches(installedDir, sourceDir) {
  * List subagents installed to a specific agent's home
  * Claude: scans ~/.claude/agents/{name}.md
  * Kimi: scans ~/.kimi-code/agents/{name}.yaml (+ sibling .system.md)
+ * Kiro: scans ~/.kiro/agents/{name}.json
  * OpenClaw: scans ~/.openclaw/{name}/AGENTS.md
  */
 export function listSubagentsForAgent(agentId, home) {
@@ -656,6 +730,22 @@ export function listSubagentsForAgent(agentId, home) {
             subagents.push({ name, path: filePath, files: [file], frontmatter });
         }
     }
+    else if (agentId === 'copilot') {
+        // Copilot: flat `<name>.agent.md` files under ~/.copilot/agents/
+        const agentsDir = path.join(home, '.copilot', 'agents');
+        if (!fs.existsSync(agentsDir))
+            return subagents;
+        for (const file of fs.readdirSync(agentsDir)) {
+            if (!file.endsWith('.agent.md'))
+                continue;
+            const filePath = path.join(agentsDir, file);
+            if (!fs.statSync(filePath).isFile())
+                continue;
+            const name = file.replace(/\.agent\.md$/, '');
+            const frontmatter = parseSubagentFrontmatter(filePath) ?? { name, description: '' };
+            subagents.push({ name, path: filePath, files: [file], frontmatter });
+        }
+    }
     else if (agentId === 'openclaw') {
         // OpenClaw: directories with AGENTS.md
         const openclawDir = path.join(home, '.openclaw');
@@ -697,6 +787,38 @@ export function listSubagentsForAgent(agentId, home) {
             });
         }
     }
+    else if (agentId === 'kiro') {
+        // Kiro: JSON files under ~/.kiro/agents/
+        const agentsDir = path.join(home, '.kiro', 'agents');
+        if (!fs.existsSync(agentsDir))
+            return subagents;
+        for (const file of fs.readdirSync(agentsDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = path.join(agentsDir, file);
+            if (!fs.statSync(filePath).isFile())
+                continue;
+            let frontmatter;
+            try {
+                const config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                frontmatter = {
+                    name: config.name || file.replace('.json', ''),
+                    description: config.description || '',
+                    model: config.model,
+                };
+            }
+            catch {
+                continue;
+            }
+            const name = file.replace('.json', '');
+            subagents.push({
+                name,
+                path: filePath,
+                files: [file],
+                frontmatter,
+            });
+        }
+    }
     return subagents;
 }
 /**
@@ -768,6 +890,19 @@ export function diffVersionSubagents(agent, version) {
             }
         }
     }
+    else if (agent === 'kiro') {
+        const agentsDir = path.join(versionHome, '.kiro', 'agents');
+        if (fs.existsSync(agentsDir)) {
+            for (const file of fs.readdirSync(agentsDir)) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const name = path.basename(file, '.json');
+                if (!discovered.has(name)) {
+                    orphans.push(name);
+                }
+            }
+        }
+    }
     return { agent, version, orphans: orphans.sort() };
 }
 /**
@@ -826,6 +961,13 @@ export function removeSubagentFromVersion(agent, version, subagentName) {
                 fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.md.${stamp}`));
             }
         }
+        else if (agent === 'copilot') {
+            const targetPath = path.join(versionHome, '.copilot', 'agents', `${subagentName}.agent.md`);
+            if (fs.existsSync(targetPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.agent.md.${stamp}`));
+            }
+        }
         else if (agent === 'openclaw') {
             const targetDir = path.join(versionHome, '.openclaw', subagentName);
             if (fs.existsSync(targetDir)) {
@@ -834,6 +976,13 @@ export function removeSubagentFromVersion(agent, version, subagentName) {
                 fs.renameSync(targetDir, trashDest);
             }
         }
+        else if (agent === 'kiro') {
+            const targetPath = path.join(versionHome, '.kiro', 'agents', `${subagentName}.json`);
+            if (fs.existsSync(targetPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.json.${stamp}`));
+            }
+        }
         return { success: true };
     }
     catch (err) {

package/dist/lib/teams/agents.d.ts

@@ -213,6 +213,10 @@ export declare class AgentProcess {
      * round-trips so a bare `teams status`/`teams logs` is still correct.
      */
     private syncRemoteMirror;
+    /** Reset the local stdout cursor for a newly truncated resume log. */
+    resetLogReadPosition(): number;
+    /** Restore the cursor when a resume transaction puts the prior log back. */
+    restoreLogReadPosition(position: number): void;
     readNewEvents(): Promise<void>;
     /**
      * Truncate the local mirror to its trailing REMOTE_MIRROR_MAX_BYTES and reset
@@ -268,6 +272,16 @@ export declare class AgentProcess {
 export type CloudDispatchFn = (agent: AgentProcess) => Promise<{
     cloudSessionId: string;
 }>;
+interface ResumeLogTransaction {
+    agent: AgentProcess;
+    stdoutPath: string;
+    backupPath: string;
+    hadOriginal: boolean;
+    previousReadPos: number;
+}
+export declare function beginResumeLogTransaction(agent: AgentProcess): Promise<ResumeLogTransaction>;
+export declare function commitResumeLogTransaction(transaction: ResumeLogTransaction): Promise<void>;
+export declare function terminateSpawnedProcess(pid: number): Promise<void>;
 export declare class AgentManager {
     private agents;
     private maxAgents;

package/dist/lib/teams/agents.js

@@ -27,7 +27,7 @@ import { recordRunName } from '../session/run-names.js';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { sshTargetFor } from '../hosts/types.js';
-import { dispatchAgentsCommand } from '../hosts/dispatch.js';
+import { dispatchAgentsCommand, terminateDispatchedTask } from '../hosts/dispatch.js';
 import { ensureHostReady } from '../hosts/ready.js';
 import { remoteShellFor } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -746,6 +746,16 @@ export class AgentProcess {
             }
         }
     }
+    /** Reset the local stdout cursor for a newly truncated resume log. */
+    resetLogReadPosition() {
+        const previous = this.lastReadPos;
+        this.lastReadPos = 0;
+        return previous;
+    }
+    /** Restore the cursor when a resume transaction puts the prior log back. */
+    restoreLogReadPosition(position) {
+        this.lastReadPos = position;
+    }
     async readNewEvents() {
         // Distributed teammate: mirror the host's new log bytes locally first, then
         // fall through to the identical local read+parse below.
@@ -1107,6 +1117,62 @@ export class AgentProcess {
         }
     }
 }
+export async function beginResumeLogTransaction(agent) {
+    const stdoutPath = await agent.getStdoutPath();
+    const backupPath = `${stdoutPath}.resume-backup-${randomUUID()}`;
+    let hadOriginal = false;
+    try {
+        await fs.rename(stdoutPath, backupPath);
+        hadOriginal = true;
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const previousReadPos = agent.resetLogReadPosition();
+    return { agent, stdoutPath, backupPath, hadOriginal, previousReadPos };
+}
+export async function commitResumeLogTransaction(transaction) {
+    if (transaction.hadOriginal)
+        await fs.rm(transaction.backupPath, { force: true });
+}
+async function rollbackResumeLogTransaction(transaction) {
+    try {
+        await fs.rm(transaction.stdoutPath, { force: true });
+        if (transaction.hadOriginal) {
+            await fs.rename(transaction.backupPath, transaction.stdoutPath);
+        }
+    }
+    finally {
+        transaction.agent.restoreLogReadPosition(transaction.previousReadPos);
+    }
+}
+export async function terminateSpawnedProcess(pid) {
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch (err) {
+        if (err?.code === 'ESRCH')
+            return;
+        throw err;
+    }
+    await new Promise(resolve => setTimeout(resolve, 250));
+    try {
+        process.kill(-pid, 0);
+    }
+    catch (err) {
+        if (err?.code === 'ESRCH')
+            return;
+        throw err;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch (err) {
+        if (err?.code !== 'ESRCH')
+            throw err;
+    }
+}
 export class AgentManager {
     agents = new Map();
     maxAgents;
@@ -1402,16 +1468,42 @@ export class AgentManager {
                 `(it may have failed before its first turn). Start a fresh teammate instead.`);
         }
         const resume = { id: agent.remoteSessionId ?? agent.agentId, message };
+        const priorRuntime = {
+            status: agent.status,
+            completedAt: agent.completedAt,
+            pid: agent.pid,
+            startTime: agent.startTime,
+            startedAt: agent.startedAt,
+            remotePid: agent.remotePid,
+            remoteLog: agent.remoteLog,
+            remoteExit: agent.remoteExit,
+            remoteLogOffset: agent.remoteLogOffset,
+            worktreePath: agent.worktreePath,
+        };
         // Flip to RUNNING up front so a concurrent status poll can't reap the
         // teammate between the exit-sentinel clear and the new PID landing; the
-        // launch re-persists with the fresh pid/startTime.
+        // launch re-persists with the fresh pid/startTime. If relaunch fails before
+        // that happens, restore the stopped lifecycle state and keep its existing
+        // metadata/log directory intact so the user can retry.
         agent.status = AgentStatus.RUNNING;
         agent.completedAt = null;
-        if (agent.hostName) {
-            await this.launchRemoteProcess(agent, resume);
+        try {
+            if (agent.hostName) {
+                await this.launchRemoteProcess(agent, resume);
+            }
+            else {
+                await this.launchProcess(agent, resume);
+            }
         }
-        else {
-            await this.launchProcess(agent, resume);
+        catch (err) {
+            Object.assign(agent, priorRuntime);
+            try {
+                await agent.saveMeta();
+            }
+            catch (restoreErr) {
+                throw new Error(`Failed to resume teammate: ${err.message}; restoring stopped state also failed: ${restoreErr.message}`, { cause: err });
+            }
+            throw err;
         }
         return agent;
     }
@@ -1429,8 +1521,13 @@ export class AgentManager {
         const resolvedModel = agent.model ?? null;
         const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume);
         debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]${resume ? ' (resume)' : ''}: ${cmd.slice(0, 3).join(' ')}...`);
+        let childProcess = null;
+        let stdoutFile = null;
+        let resumeLog = null;
         try {
-            const stdoutPath = await agent.getStdoutPath();
+            if (resume)
+                resumeLog = await beginResumeLogTransaction(agent);
+            const stdoutPath = resumeLog?.stdoutPath ?? await agent.getStdoutPath();
             // Always TRUNCATE — including on resume. The status reader re-reads the
             // whole log from byte 0 every poll (lastReadPos is in-memory, not
             // persisted) and marks terminal status from the last `result` event it
@@ -1441,7 +1538,7 @@ export class AgentManager {
             // a forked session. Truncating keeps exactly one turn in the log, so the
             // re-read is always correct. The authoritative transcript lives in the
             // agent's own session (resumed via --resume), not this stdout mirror.
-            const stdoutFile = await fs.open(stdoutPath, 'w');
+            stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
             // Wrap the teammate command in a shell that records the underlying CLI's
             // exit code to a sentinel file. Detached + unref()'d children can't be
@@ -1455,7 +1552,7 @@ export class AgentManager {
             const wrappedCmd = buildSentinelCommand(cmd, exitCodePath);
             // detached:true makes the shell the process-group leader, so stop()'s
             // `kill(-pid)` still reaches the underlying CLI through the group.
-            const childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
+            childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
                 stdio: ['ignore', stdoutFd, stdoutFd],
                 cwd: agent.cwd || undefined,
                 detached: true,
@@ -1463,8 +1560,13 @@ export class AgentManager {
                     ? { ...sanitizeProcessEnv(process.env), ...agent.envOverrides }
                     : sanitizeProcessEnv(process.env),
             });
+            await new Promise((resolve, reject) => {
+                childProcess.once('spawn', resolve);
+                childProcess.once('error', reject);
+            });
             childProcess.unref();
-            stdoutFile.close().catch(() => { });
+            await stdoutFile.close();
+            stdoutFile = null;
             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
@@ -1474,9 +1576,21 @@ export class AgentManager {
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
+            if (resumeLog)
+                await commitResumeLogTransaction(resumeLog);
         }
         catch (err) {
-            await this.cleanupPartialAgent(agent);
+            if (stdoutFile)
+                await stdoutFile.close().catch(() => { });
+            if (childProcess?.pid)
+                await terminateSpawnedProcess(childProcess.pid);
+            if (resumeLog)
+                await rollbackResumeLogTransaction(resumeLog);
+            // Fresh spawns own a newly-created directory, so a failed launch removes
+            // that partial record. A resume reuses an existing teammate: its caller
+            // restores the prior terminal state and preserves the directory for retry.
+            if (!resume)
+                await this.cleanupPartialAgent(agent);
             console.error(`Failed to spawn agent ${agent.agentId}:`, err);
             throw new Error(`Failed to spawn agent: ${err.message}`);
         }
@@ -1535,12 +1649,19 @@ export class AgentManager {
         // — the supervisor polls the host, we don't block here.
         const effort = agent.effort ?? 'medium';
         const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName, resume);
+        let dispatchedTask = null;
+        let resumeLog = null;
         try {
+            if (resume) {
+                resumeLog = await beginResumeLogTransaction(agent);
+                await fs.writeFile(resumeLog.stdoutPath, '');
+            }
             const { task } = await dispatchAgentsCommand(host, {
                 forwardedArgs,
                 remoteCwd,
                 follow: false,
             });
+            dispatchedTask = task;
             agent.remotePid = task.pid ?? null;
             agent.remoteLog = task.remoteLog ?? null;
             agent.remoteExit = task.remoteExit ?? null;
@@ -1549,15 +1670,34 @@ export class AgentManager {
             // syncRemoteMirror appends the delta onto the local mirror. Truncate that
             // mirror first so the prior turn's terminal event can't linger and get
             // re-read as the current status (same hazard the local path truncates for).
-            if (resume) {
-                await fs.writeFile(await agent.getStdoutPath(), '').catch(() => { });
-            }
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
+            if (resumeLog)
+                await commitResumeLogTransaction(resumeLog);
         }
         catch (err) {
+            let cleanupError = null;
+            if (dispatchedTask) {
+                try {
+                    terminateDispatchedTask(dispatchedTask);
+                }
+                catch (cleanupErr) {
+                    cleanupError = cleanupErr;
+                }
+            }
+            if (resumeLog) {
+                try {
+                    await rollbackResumeLogTransaction(resumeLog);
+                }
+                catch (cleanupErr) {
+                    cleanupError = cleanupError ?? cleanupErr;
+                }
+            }
             console.error(`Failed to launch remote teammate ${agent.agentId} on ${agent.hostName}:`, err);
+            if (cleanupError) {
+                throw new Error(`Failed to launch remote teammate: ${err.message}; cleanup failed: ${cleanupError.message}`, { cause: err });
+            }
             throw new Error(`Failed to launch remote teammate: ${err.message}`);
         }
         debug(`Launched remote agent ${agent.agentId} on ${agent.hostName} (remote pid ${agent.remotePid})`);
@@ -1910,17 +2050,13 @@ export class AgentManager {
         if (!agent) {
             return false;
         }
-        // Distributed teammate: no local PID — signal it over SSH. Try the process
-        // GROUP first (negative pid, matching local `kill(-pid)`) to catch the
-        // detached `agents run` and its children; but the remote launcher is
-        // `nohup bash -lc … &` under a non-interactive shell where job control is off,
-        // so `&` may NOT open a new group — fall back to signalling the wrapper pid
-        // directly. Best-effort either way; the `.exit` sentinel is the durable
-        // terminal-status source if a grandchild lingers.
+        // Distributed teammate: no local PID — signal the dedicated process group
+        // created by dispatch.ts. The persisted PID is the group leader, so one
+        // negative-PID signal reaches the login-shell wrapper and every descendant.
         if (agent.hostName && agent.status === AgentStatus.RUNNING) {
             if (agent.hostTarget && agent.remotePid) {
                 try {
-                    sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null || kill -TERM ${agent.remotePid} 2>/dev/null`, {
+                    sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null`, {
                         timeoutMs: 10000,
                         multiplex: true,
                     });