@phnx-labs/agents-cli 1.12.0 → 1.14.1

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

@@ -1,5 +1,11 @@
-import { AgentManager } from './agents.js';
+import { AgentManager, type TaskType } from './agents.js';
 import { AgentType } from './parsers.js';
+export interface ToolCallDetail {
+    tool: string;
+    summary: string;
+    timestamp: string | null;
+}
+/** Result returned after spawning a new teammate. */
 export interface SpawnResult {
     task_name: string;
     agent_id: string;
@@ -10,17 +16,25 @@ export interface SpawnResult {
     remote_session_id?: string | null;
     name?: string | null;
     after?: string[];
+    task_type?: TaskType | null;
+    cloud_provider?: string | null;
+    cloud_session_id?: string | null;
 }
+/** Detailed status of a single teammate, including file ops, commands, and a cursor for delta polling. */
 export interface AgentStatusDetail {
     agent_id: string;
     agent_type: string;
     status: string;
+    prompt: string;
+    started_at: string;
+    completed_at: string | null;
     duration: string | null;
     files_created: string[];
     files_modified: string[];
     files_read: string[];
     files_deleted: string[];
     bash_commands: string[];
+    recent_tool_calls: ToolCallDetail[];
     last_messages: string[];
     tool_count: number;
     has_errors: boolean;
@@ -31,9 +45,12 @@ export interface AgentStatusDetail {
     pr_url?: string | null;
     version?: string | null;
     remote_session_id?: string | null;
+    session_label?: string | null;
     name?: string | null;
     after?: string[];
+    task_type?: TaskType | null;
 }
+/** Aggregated status of all teammates in a task, with per-status counts and a global cursor. */
 export interface TaskStatusResult {
     task_name: string;
     agents: AgentStatusDetail[];
@@ -46,12 +63,14 @@ export interface TaskStatusResult {
     };
     cursor: string;
 }
+/** Result of stopping one or more teammates. */
 export interface StopResult {
     task_name: string;
     stopped: string[];
     already_stopped: string[];
     not_found: string[];
 }
+/** Summary metadata for a single task (team), including agent counts by status and timestamps. */
 export interface TaskInfo {
     task_name: string;
     agent_count: number;
@@ -64,14 +83,18 @@ export interface TaskInfo {
     created_at: string;
     modified_at: string;
 }
+/** Paginated list of tasks sorted by most recent activity. */
 export interface TasksResult {
     tasks: TaskInfo[];
 }
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null): Promise<SpawnResult>;
+/** Spawn a new teammate in a task and return its initial metadata. */
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null): Promise<SpawnResult>;
+/** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;
+/** List all known tasks grouped by task name, sorted by most recent activity. */
 export declare function handleTasks(manager: AgentManager, limit?: number): Promise<TasksResult>;
+/** Stop a specific teammate or all teammates in a task. */
 export declare function handleStop(manager: AgentManager, taskName: string, agentId?: string): Promise<StopResult | {
     error: string;
 }>;
-//# sourceMappingURL=api.d.ts.map

package/dist/lib/teams/api.js

@@ -1,6 +1,7 @@
 import { AgentStatus, resolveMode } from './agents.js';
 import { getDelta } from './summarizer.js';
 import { debug } from './debug.js';
+import { buildClaudeLabelMap } from '../session/discover.js';
 /**
  * Truncate a bash command for status output.
  * Handles heredocs specially - shows the redirect target instead of contents.
@@ -16,12 +17,51 @@ function truncateBashCommand(cmd, maxLen = 120) {
         return cmd;
     return cmd.substring(0, maxLen - 3) + '...';
 }
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null) {
+function eventToolName(event) {
+    const eventType = event.type || '';
+    if (eventType === 'bash')
+        return 'Bash';
+    if (eventType === 'file_write')
+        return 'Write';
+    if (eventType === 'file_create')
+        return 'Create';
+    if (eventType === 'file_read')
+        return 'Read';
+    if (eventType === 'file_delete')
+        return 'Delete';
+    if (eventType === 'directory_list')
+        return 'List';
+    if (eventType === 'tool_use')
+        return event.tool || 'Tool';
+    return null;
+}
+function eventToolSummary(event) {
+    const value = event.command ||
+        event.path ||
+        event.args?.command ||
+        event.args?.path ||
+        event.input?.command ||
+        event.input?.path ||
+        '';
+    return truncateBashCommand(String(value || eventToolName(event) || 'tool call'));
+}
+function recentToolCalls(events, max = 10) {
+    return events
+        .filter((event) => eventToolName(event))
+        .slice(-max)
+        .map((event) => ({
+        tool: eventToolName(event) || 'Tool',
+        summary: eventToolSummary(event),
+        timestamp: typeof event.timestamp === 'string' ? event.timestamp : null,
+    }));
+}
+/** Spawn a new teammate in a task and return its initial metadata. */
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, 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) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
     debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}...`);
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,
@@ -33,8 +73,12 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
         remote_session_id: agent.remoteSessionId,
         name: agent.name,
         after: agent.after,
+        task_type: agent.taskType,
+        cloud_provider: agent.cloudProvider,
+        cloud_session_id: agent.cloudSessionId,
     };
 }
+/** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export async function handleStatus(manager, taskName, filter, since, // Optional ISO timestamp - return only events after this time
 parentSessionId) {
     // Default to 'all' so callers see completed/failed agents unless they opt to filter
@@ -72,6 +116,9 @@ parentSessionId) {
     }
     // Build details only for filtered agents
     let maxTimestamp = since || new Date(0).toISOString(); // Track max timestamp for cursor
+    const claudeLabels = allAgents.some((agent) => agent.agentType === 'claude')
+        ? buildClaudeLabelMap()
+        : new Map();
     for (const agent of agents) {
         await agent.readNewEvents();
         const events = agent.events;
@@ -87,16 +134,28 @@ parentSessionId) {
             agent_id: agent.agentId,
             agent_type: agent.agentType,
             status: agent.status,
+            prompt: agent.prompt,
+            started_at: agent.startedAt.toISOString(),
+            completed_at: agent.completedAt?.toISOString() ?? null,
             duration: agent.duration(),
             version: agent.version,
             remote_session_id: agent.remoteSessionId,
+            session_label: agent.remoteSessionId
+                ? claudeLabels.get(agent.remoteSessionId) ?? null
+                : null,
             name: agent.name,
             after: agent.after,
+            task_type: agent.taskType,
+            mode: agent.mode,
+            cloud_session_id: agent.cloudSessionId,
+            cloud_provider: agent.cloudProvider,
+            pr_url: agent.prUrl,
             files_created: delta.new_files_created,
             files_modified: delta.new_files_modified,
             files_read: delta.new_files_read,
             files_deleted: delta.new_files_deleted,
             bash_commands: delta.new_bash_commands.map((cmd) => truncateBashCommand(cmd)),
+            recent_tool_calls: recentToolCalls(events),
             last_messages: delta.new_messages,
             tool_count: delta.new_tool_count,
             has_errors: delta.new_errors.length > 0,
@@ -112,6 +171,7 @@ parentSessionId) {
         cursor: maxTimestamp, // Max timestamp across all agents
     };
 }
+/** List all known tasks grouped by task name, sorted by most recent activity. */
 export async function handleTasks(manager, limit = 10) {
     debug(`[tasks] Listing tasks (limit=${limit})...`);
     const allAgents = await manager.listAll();
@@ -177,6 +237,7 @@ export async function handleTasks(manager, limit = 10) {
     debug(`[tasks] Returning ${limitedTasks.length}/${tasks.length} tasks`);
     return { tasks: limitedTasks };
 }
+/** Stop a specific teammate or all teammates in a task. */
 export async function handleStop(manager, taskName, agentId) {
     if (agentId) {
         debug(`[stop] Stopping agent ${agentId} in task "${taskName}"...`);
@@ -226,4 +287,3 @@ export async function handleStop(manager, taskName, agentId) {
         };
     }
 }
-//# sourceMappingURL=api.js.map

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

@@ -1,2 +1,7 @@
+/**
+ * Debug logging for the teams module.
+ *
+ * Outputs to stderr when AGENTS_DEBUG or DEBUG environment variables are set.
+ */
+/** Log debug messages to stderr when debug mode is enabled. */
 export declare function debug(...args: unknown[]): void;
-//# sourceMappingURL=debug.d.ts.map

package/dist/lib/teams/debug.js

@@ -1,6 +1,11 @@
+/**
+ * Debug logging for the teams module.
+ *
+ * Outputs to stderr when AGENTS_DEBUG or DEBUG environment variables are set.
+ */
 const ENABLED = Boolean(process.env.AGENTS_DEBUG || process.env.DEBUG);
+/** Log debug messages to stderr when debug mode is enabled. */
 export function debug(...args) {
     if (ENABLED)
         console.error(...args);
 }
-//# sourceMappingURL=debug.js.map

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

@@ -1,6 +1,12 @@
+/**
+ * Bash command file-operation inference.
+ *
+ * Heuristically extracts file read, write, and delete operations from
+ * shell command strings using regex patterns. Used by the event parsers
+ * and summarizer to attribute file-level side effects to bash tool calls.
+ */
 /**
  * Try to infer file operations (read/write/delete) from a bash command string.
  * Returns three arrays: files read, written, and deleted.
  */
 export declare function extractFileOpsFromBash(command: string): [string[], string[], string[]];
-//# sourceMappingURL=file_ops.d.ts.map

package/dist/lib/teams/file_ops.js

@@ -1,3 +1,10 @@
+/**
+ * Bash command file-operation inference.
+ *
+ * Heuristically extracts file read, write, and delete operations from
+ * shell command strings using regex patterns. Used by the event parsers
+ * and summarizer to attribute file-level side effects to bash tool calls.
+ */
 /**
  * Try to infer file operations (read/write/delete) from a bash command string.
  * Returns three arrays: files read, written, and deleted.
@@ -56,4 +63,3 @@ export function extractFileOpsFromBash(command) {
     const unique = (paths) => Array.from(new Set(paths.filter(Boolean)));
     return [unique(filesRead), unique(filesWritten), unique(filesDeleted)];
 }
-//# sourceMappingURL=file_ops.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Public library surface for the teams subsystem.
+ *
+ * Consumers import from '@phnx-labs/agents-cli/teams'
+ * to reuse the same agent lifecycle, parsing, summarization, and persistence
+ * layer that powers the `agents teams` CLI.
+ */
+export { AgentManager, AgentProcess, AgentStatus, VALID_TASK_TYPES, AGENT_COMMANDS, computePathLCA, checkAllClis, checkCliAvailable, ensureGeminiPlanMode, getAgentsDir, resolveMode, type TaskType, type CloudDispatchFn, } from './agents.js';
+export { type AgentType } from './parsers.js';
+export { normalizeEvents, normalizeEvent, parseEvent } from './parsers.js';
+export { handleSpawn, handleStatus, handleStop, handleTasks, type SpawnResult, type AgentStatusDetail, type TaskStatusResult, type StopResult, type TaskInfo, type TasksResult, } from './api.js';
+export { readConfig, resolveAgentsDir, resolveBaseDir, type EffortLevel, type ModelOverrides, type ProviderConfig, type AgentConfig, type SwarmConfig, type ReadConfigResult, } from './persistence.js';
+export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, type QuickStatus, } from './summarizer.js';
+export { extractFileOpsFromBash } from './file_ops.js';
+export { debug } from './debug.js';

package/dist/lib/teams/index.js

@@ -0,0 +1,14 @@
+/**
+ * Public library surface for the teams subsystem.
+ *
+ * Consumers import from '@phnx-labs/agents-cli/teams'
+ * to reuse the same agent lifecycle, parsing, summarization, and persistence
+ * layer that powers the `agents teams` CLI.
+ */
+export { AgentManager, AgentProcess, AgentStatus, VALID_TASK_TYPES, AGENT_COMMANDS, computePathLCA, checkAllClis, checkCliAvailable, ensureGeminiPlanMode, getAgentsDir, resolveMode, } from './agents.js';
+export { normalizeEvents, normalizeEvent, parseEvent } from './parsers.js';
+export { handleSpawn, handleStatus, handleStop, handleTasks, } from './api.js';
+export { readConfig, resolveAgentsDir, resolveBaseDir, } from './persistence.js';
+export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, } from './summarizer.js';
+export { extractFileOpsFromBash } from './file_ops.js';
+export { debug } from './debug.js';

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

@@ -1,5 +1,8 @@
+/** Supported agent CLI types for team spawning. */
 export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode';
+/** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export declare function normalizeEvents(agentType: AgentType, raw: any): any[];
+/** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */
 export declare function normalizeEvent(agentType: AgentType, raw: any): any;
+/** Parse a single JSONL line into normalized events. Returns null if the line is not valid JSON. */
 export declare function parseEvent(agentType: AgentType, line: string): any[] | null;
-//# sourceMappingURL=parsers.d.ts.map

package/dist/lib/teams/parsers.js

@@ -1,5 +1,14 @@
+/**
+ * Agent event stream parsers.
+ *
+ * Normalizes the heterogeneous JSON event formats emitted by each agent CLI
+ * (Claude, Codex, Gemini, Cursor, OpenCode) into a unified event schema
+ * with consistent types: init, message, tool_use, bash, file_read, file_write,
+ * file_create, file_delete, result, error, and others.
+ */
 import { extractFileOpsFromBash } from './file_ops.js';
 const claudeToolUseMap = new Map();
+/** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export function normalizeEvents(agentType, raw) {
     if (agentType === 'codex') {
         return normalizeCodex(raw);
@@ -24,6 +33,7 @@ export function normalizeEvents(agentType, raw) {
             timestamp: timestamp,
         }];
 }
+/** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */
 export function normalizeEvent(agentType, raw) {
     const events = normalizeEvents(agentType, raw);
     if (events.length > 0) {
@@ -814,6 +824,7 @@ function normalizeOpencode(raw) {
             timestamp: timestamp,
         }];
 }
+/** Parse a single JSONL line into normalized events. Returns null if the line is not valid JSON. */
 export function parseEvent(agentType, line) {
     try {
         const raw = JSON.parse(line);
@@ -823,4 +834,3 @@ export function parseEvent(agentType, line) {
         return null;
     }
 }
-//# sourceMappingURL=parsers.js.map

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

@@ -1,28 +1,42 @@
 import { AgentType } from './parsers.js';
+/** Resolve the base data directory for teams, preferring ~/.agents/teams/ with a temp fallback. */
 export declare function resolveBaseDir(): Promise<string>;
+/** Reasoning-intensity levels supported by the teams system. */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/**
+ * Legacy type retained for config-file back-compat. Older configs pinned a
+ * model per effort tier; we no longer act on these entries but accept them
+ * without error when loading from disk.
+ */
 export type ModelOverrides = Partial<Record<AgentType, Partial<Record<EffortLevel, string>>>>;
+/** API endpoint configuration for a model provider. */
 export interface ProviderConfig {
     apiEndpoint: string | null;
 }
+/** Per-agent-type configuration: CLI command template, enabled state, optional pinned model, and provider. */
 export interface AgentConfig {
     command: string;
     enabled: boolean;
     model: string | null;
     provider: string;
 }
+/** Top-level teams configuration structure persisted to config.json. */
 export interface SwarmConfig {
     agents: Record<AgentType, AgentConfig>;
     providers: Record<string, ProviderConfig>;
 }
+/** Result of reading the teams config, including resolved agent and provider configurations. */
 export interface ReadConfigResult {
     hasConfig: boolean;
     enabledAgents: AgentType[];
     agentConfigs: Record<AgentType, AgentConfig>;
     providerConfigs: Record<string, ProviderConfig>;
 }
+/** Resolve and ensure the agents subdirectory exists under the teams base dir. */
 export declare function resolveAgentsDir(): Promise<string>;
+/** Read teams config from disk, migrating legacy formats if needed. Returns defaults when no config exists. */
 export declare function readConfig(): Promise<ReadConfigResult>;
+/** Write teams config to disk. */
 export declare function writeConfig(config: SwarmConfig): Promise<void>;
+/** Update the enabled/disabled status of a specific agent type in the config file. */
 export declare function setAgentEnabled(agentType: AgentType, enabled: boolean): Promise<void>;
-//# sourceMappingURL=persistence.d.ts.map

package/dist/lib/teams/persistence.js

@@ -1,13 +1,72 @@
+/**
+ * Teams configuration persistence.
+ *
+ * Manages reading, writing, and migrating the teams config file
+ * (~/.agents/teams/config.json) that stores per-agent-type settings
+ * (command templates, enabled state, pinned models) and provider configs.
+ * Also resolves the base data directory for teammate process storage.
+ */
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
 import { homedir, tmpdir } from 'os';
 import { constants as fsConstants } from 'fs';
+import { randomBytes } from 'crypto';
+import lockfile from 'proper-lockfile';
+import { getAgentsDir } from '../state.js';
+/**
+ * Atomic JSON write: writes to a sibling tmp file then renames over the
+ * target. rename(2) is atomic on POSIX, so a crashed/interrupted write
+ * leaves the old config intact instead of leaving a half-written file the
+ * next read will reject.
+ */
+async function atomicWriteJson(p, data) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    const body = JSON.stringify(data, null, 2);
+    await fs.writeFile(tmp, body);
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Hold an exclusive cross-process lock on the config file while running
+ * `fn`. proper-lockfile requires the target to exist, so we touch it
+ * first. Stale locks auto-expire after 10s.
+ */
+async function withConfigLock(p, fn) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    if (!fsSync.existsSync(p)) {
+        try {
+            await fs.writeFile(p, '{}', { flag: 'wx' });
+        }
+        catch (err) {
+            if (err && err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    const release = await lockfile.lock(p, {
+        retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
+        stale: 10_000,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
 // All supported teammate agent types
 const ALL_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode'];
-// Teams data lives under ~/.agents/teams/
-const TEAMS_DIR = path.join(homedir(), '.agents', 'teams');
+// Teams data lives under ~/.agents-system/teams/
+const TEAMS_DIR = path.join(getAgentsDir(), 'teams');
 // Legacy paths (for migration)
 const LEGACY_CONFIG_DIR = path.join(homedir(), '.agents');
+// Legacy migration from pre-OSS brand; safe to remove after 2026-07
 const LEGACY_BASE_DIR = path.join(homedir(), '.swarmify');
 const TMP_FALLBACK_DIR = path.join(tmpdir(), 'agents');
 async function pathExists(p) {
@@ -29,6 +88,7 @@ async function ensureWritableDir(p) {
         return false;
     }
 }
+/** Resolve the base data directory for teams, preferring ~/.agents/teams/ with a temp fallback. */
 export async function resolveBaseDir() {
     if (await ensureWritableDir(TEAMS_DIR)) {
         return TEAMS_DIR;
@@ -55,6 +115,7 @@ async function resolveLegacySwarmifyConfigPath() {
 }
 let AGENTS_DIR = null;
 let CONFIG_PATH = null;
+/** Resolve and ensure the agents subdirectory exists under the teams base dir. */
 export async function resolveAgentsDir() {
     if (!AGENTS_DIR) {
         AGENTS_DIR = await resolveAgentsPath();
@@ -174,20 +235,20 @@ async function migrateLegacyConfig() {
     // Try ~/.agents/config.json first (most recent legacy location)
     const legacyConfigPath = await resolveLegacyConfigPath();
     let config = await tryReadLegacyConfig(legacyConfigPath);
-    // Try ~/.swarmify/agents/config.json
+    // Try ~/.swarmify/agents/config.json (legacy pre-OSS brand path)
     if (!config) {
-        const swarmifyConfigPath = await resolveLegacySwarmifyConfigPath();
-        config = await tryReadLegacyConfig(swarmifyConfigPath);
+        const legacyBrandConfigPath = await resolveLegacySwarmifyConfigPath();
+        config = await tryReadLegacyConfig(legacyBrandConfigPath);
     }
     if (!config)
         return null;
     // Write migrated config to new location
     const newConfigPath = await ensureConfigPath();
     await fs.writeFile(newConfigPath, JSON.stringify(config, null, 2));
-    console.warn(`[agents-mcp] Migrated config to ${newConfigPath}`);
+    console.warn(`[agents] Migrated config to ${newConfigPath}`);
     return config;
 }
-// Read teams config, returns default config if file doesn't exist
+/** Read teams config from disk, migrating legacy formats if needed. Returns defaults when no config exists. */
 export async function readConfig() {
     const configPath = await ensureConfigPath();
     // Try to read new config first
@@ -268,22 +329,43 @@ export async function readConfig() {
         return { enabledAgents, agentConfigs, providerConfigs, hasConfig: false };
     }
 }
-// Write teams config
+/** Write teams config to disk. */
 export async function writeConfig(config) {
     const configPath = await ensureConfigPath();
-    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+    await withConfigLock(configPath, async () => {
+        await atomicWriteJson(configPath, config);
+    });
 }
-// Update agent enabled status
+/** Update the enabled/disabled status of a specific agent type in the config file. */
 export async function setAgentEnabled(agentType, enabled) {
-    const { agentConfigs } = await readConfig();
-    agentConfigs[agentType].enabled = enabled;
     const configPath = await ensureConfigPath();
-    const config = await fs.readFile(configPath, 'utf-8');
-    const parsed = JSON.parse(config);
-    if (!parsed.agents[agentType]) {
-        parsed.agents[agentType] = getDefaultAgentConfig(agentType);
-    }
-    parsed.agents[agentType].enabled = enabled;
-    await fs.writeFile(configPath, JSON.stringify(parsed, null, 2));
+    await withConfigLock(configPath, async () => {
+        let parsed;
+        try {
+            const raw = await fs.readFile(configPath, 'utf-8');
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            // ENOENT: the lock held briefly above touched a placeholder, but a
+            // racing writer could still have produced an empty file. Fall back
+            // to defaults rather than wedge the call.
+            if (err && err.code === 'ENOENT') {
+                parsed = getDefaultSwarmConfig();
+            }
+            else if (err instanceof SyntaxError) {
+                throw new Error(`Teams config corrupted at ${configPath}: ${err.message}. Inspect and restore from backup.`);
+            }
+            else {
+                throw err;
+            }
+        }
+        if (!parsed.agents) {
+            parsed.agents = getDefaultSwarmConfig().agents;
+        }
+        if (!parsed.agents[agentType]) {
+            parsed.agents[agentType] = getDefaultAgentConfig(agentType);
+        }
+        parsed.agents[agentType].enabled = enabled;
+        await atomicWriteJson(configPath, parsed);
+    });
 }
-//# sourceMappingURL=persistence.js.map

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

@@ -1,11 +1,22 @@
+/** Metadata for a registered team. */
 export interface TeamMeta {
     created_at: string;
     description?: string;
 }
+/** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
+/**
+ * Load all teams from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let any caller wipe the user's registry on the next
+ * write, which is exactly the data-loss path we are trying to close.
+ */
 export declare function loadTeams(): Promise<TeamRegistry>;
+/** Create a new team. Throws if a team with the same name already exists. */
 export declare function createTeam(name: string, description?: string): Promise<TeamMeta>;
+/** Return existing team metadata or create a new team if it does not exist. */
 export declare function ensureTeam(name: string): Promise<TeamMeta>;
+/** Remove a team from the registry. Returns false if the team did not exist. */
 export declare function removeTeam(name: string): Promise<boolean>;
+/** Check whether a team with the given name exists in the registry. */
 export declare function teamExists(name: string): Promise<boolean>;
-//# sourceMappingURL=registry.d.ts.map