@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/sync-manifest.js

@@ -0,0 +1,450 @@
+/**
+ * Sync manifest — fast staleness guard for syncResourcesToVersion.
+ *
+ * Written after each full sync; read before the next to skip unconditional
+ * re-copies when nothing has changed. Two-tier check:
+ *   Tier 1 — stat mtime+size   ~0.01ms/file   (kernel VFS cache)
+ *   Tier 2 — sha256 on miss    ~0.1–0.5ms/file
+ *
+ * Env vars in MCP YAML are NOT substituted by agents-cli — ${VAR} is stored
+ * verbatim and passed as-is to `claude mcp add`. Value-only env var changes
+ * (YAML content unchanged) are not detected and are not in scope.
+ *
+ * Layering model:
+ *   First-wins (commands, skills, hooks, MCP, rules): manifest stores fingerprint
+ *   of the WINNING source (project > user > system > extra). A scope change
+ *   (e.g. project file added/removed) is detected via resolved-path mismatch.
+ *
+ *   Merged (permissions): all group files across all scopes contribute. Any
+ *   change in any scope file triggers re-sync.
+ *
+ * The manifest is written only after a full (unselected) sync and is only used
+ * as a guard for full syncs — partial/interactive syncs bypass it entirely.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { getVersionsDir, getProjectAgentsDir, getUserAgentsDir, getSkillsDir, getUserHooksDir, getHooksDir, getUserRulesDir, getResolvedRulesDir, getUserPermissionsDir, getPermissionsDir, getEnabledExtraRepos, } from './state.js';
+import { resolveResource } from './resources.js';
+import { listMcpServerConfigs } from './mcp.js';
+import { isMemoryStale } from './memory-compile.js';
+import { getActivePermissionSetName } from './permissions.js';
+import { listInstalledSubagents } from './subagents.js';
+import { safeJoin } from './paths.js';
+// ─── Types ────────────────────────────────────────────────────────────────────
+const MANIFEST_VERSION = 1;
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+function manifestPath(agent, version) {
+    return path.join(getVersionsDir(), agent, version, 'home', '.sync-manifest.json');
+}
+// ─── Fingerprinting ───────────────────────────────────────────────────────────
+function sha256(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+/** Compute fingerprint for a single file. Returns null if the file can't be read. */
+function fingerprintFile(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return {
+            path: filePath,
+            mtime: stat.mtimeMs,
+            size: stat.size,
+            sha256: sha256(content),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fingerprint all files in a directory recursively.
+ * Returns sorted by absolute path so ordering is deterministic.
+ */
+function fingerprintDir(dirPath) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const fp = fingerprintFile(full);
+                if (fp)
+                    results.push(fp);
+            }
+        }
+    }
+    walk(dirPath);
+    results.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return results;
+}
+// ─── Staleness check ──────────────────────────────────────────────────────────
+/**
+ * Check if a stored fingerprint is still valid for the file at its recorded path.
+ * Tier 1: mtime+size match → clean (no read needed).
+ * Tier 2: sha256 match → clean (mtime drifted, content same).
+ * Path mismatch → immediately stale (scope changed).
+ */
+function isFileStale(stored, currentPath) {
+    if (stored.path !== currentPath)
+        return true;
+    try {
+        const stat = fs.statSync(currentPath);
+        if (stat.mtimeMs === stored.mtime && stat.size === stored.size)
+            return false;
+        return sha256(fs.readFileSync(currentPath, 'utf-8')) !== stored.sha256;
+    }
+    catch {
+        return true; // file disappeared
+    }
+}
+/**
+ * Walk a directory recursively and return sorted absolute file paths.
+ * No file reads — used for the hot-path check where we want stat-only speed.
+ */
+function walkDirPaths(dirPath) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dirPath);
+    results.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return results;
+}
+/**
+ * Check if a DirEntry is stale for the given source directory.
+ * Hot path: stat only (no file reads) when mtime+size match.
+ */
+function isDirStale(stored, currentDirPath) {
+    if (stored.dirPath !== currentDirPath)
+        return true;
+    // Get current file list without reading content
+    const currentPaths = walkDirPaths(currentDirPath);
+    if (currentPaths.length !== stored.files.length)
+        return true;
+    for (let i = 0; i < currentPaths.length; i++) {
+        const storedFp = stored.files[i];
+        const currentPath = currentPaths[i];
+        if (storedFp.path !== currentPath)
+            return true; // added/removed/renamed
+        // Tier 1: mtime+size stat only
+        try {
+            const stat = fs.statSync(currentPath);
+            if (stat.mtimeMs === storedFp.mtime && stat.size === storedFp.size)
+                continue;
+            // Tier 2: sha256 (only on mismatch)
+            if (sha256(fs.readFileSync(currentPath, 'utf-8')) !== storedFp.sha256)
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}
+/** Compare sorted name sets. Returns true if they differ. */
+function nameSetDiffers(manifestKeys, available) {
+    if (manifestKeys.length !== available.length)
+        return true;
+    const sorted = [...available].sort();
+    const mSorted = [...manifestKeys].sort();
+    return sorted.some((name, i) => name !== mSorted[i]);
+}
+// ─── Source resolution helpers ────────────────────────────────────────────────
+function resolveSkillDir(skill, cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const candidates = [
+        projectDir ? path.join(projectDir, 'skills', skill) : null,
+        path.join(getUserAgentsDir(), 'skills', skill),
+        path.join(getSkillsDir(), skill),
+        ...getEnabledExtraRepos().map(e => path.join(e.dir, 'skills', skill)),
+    ];
+    return candidates.find(p => p && fs.existsSync(p) && fs.statSync(p).isDirectory()) ?? null;
+}
+function resolveRuleFile(mem, cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const candidates = [
+        projectDir ? safeJoin(path.join(projectDir, 'rules'), `${mem}.md`) : null,
+        safeJoin(getUserRulesDir(), `${mem}.md`),
+        safeJoin(getResolvedRulesDir(), `${mem}.md`),
+        ...getEnabledExtraRepos().map(e => safeJoin(path.join(e.dir, 'rules'), `${mem}.md`)),
+    ];
+    return candidates.find(p => {
+        if (!p)
+            return false;
+        try {
+            return !fs.lstatSync(p).isSymbolicLink() && fs.existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    }) ?? null;
+}
+/** Collect all permission group files across all scopes (first-wins per name). */
+function collectPermissionGroupFiles() {
+    const seen = new Map(); // name → filePath (first-wins: user > system)
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const groupsDir = path.join(baseDir, 'groups');
+        if (!fs.existsSync(groupsDir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(groupsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                continue;
+            const name = entry.name.replace(/\.(yaml|yml)$/, '');
+            if (!seen.has(name))
+                seen.set(name, path.join(groupsDir, entry.name));
+        }
+    }
+    return Object.fromEntries(seen);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/** Load the manifest for a given agent+version. Returns null on miss or parse error. */
+export function loadSyncManifest(agent, version) {
+    const p = manifestPath(agent, version);
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (raw.v !== MANIFEST_VERSION)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the manifest atomically (tmp + rename). */
+export function saveSyncManifest(agent, version, manifest) {
+    const p = manifestPath(agent, version);
+    const tmp = p + '.tmp';
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+        fs.renameSync(tmp, p);
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Build a manifest by fingerprinting current source state.
+ * Call this after a successful full sync.
+ */
+export function buildManifest(agent, version, available, cwd) {
+    const commands = {};
+    for (const name of available.commands) {
+        const resolved = resolveResource('commands', `${name}.md`, cwd);
+        if (!resolved)
+            continue;
+        const fp = fingerprintFile(resolved.path);
+        if (fp)
+            commands[name] = { source: fp };
+    }
+    const skills = {};
+    for (const name of available.skills) {
+        const dirPath = resolveSkillDir(name, cwd);
+        if (!dirPath)
+            continue;
+        skills[name] = { dirPath, files: fingerprintDir(dirPath) };
+    }
+    const hooks = {};
+    for (const name of available.hooks) {
+        // Hooks: resolve winning source manually (project > user > system > extra)
+        const projectDir = getProjectAgentsDir(cwd);
+        const candidates = [
+            projectDir ? path.join(projectDir, 'hooks', name) : null,
+            path.join(getUserHooksDir(), name),
+            path.join(getHooksDir(), name),
+            ...getEnabledExtraRepos().map(e => path.join(e.dir, 'hooks', name)),
+        ];
+        const hookPath = candidates.find(p => p && fs.existsSync(p)) ?? null;
+        if (!hookPath)
+            continue;
+        const fp = fingerprintFile(hookPath);
+        if (fp)
+            hooks[name] = { source: fp };
+    }
+    const ruleFiles = {};
+    for (const name of available.memory) {
+        const srcPath = resolveRuleFile(name, cwd);
+        if (!srcPath)
+            continue;
+        const fp = fingerprintFile(srcPath);
+        if (fp)
+            ruleFiles[name] = { source: fp };
+    }
+    const mcp = {};
+    for (const server of listMcpServerConfigs(cwd)) {
+        const fp = fingerprintFile(server.path);
+        if (fp)
+            mcp[server.name] = { source: fp };
+    }
+    const groupFiles = collectPermissionGroupFiles();
+    const permGroups = {};
+    for (const [name, filePath] of Object.entries(groupFiles)) {
+        const fp = fingerprintFile(filePath);
+        if (fp)
+            permGroups[name] = { source: fp };
+    }
+    // Subagents: user > system, first-wins per name (mirrors listInstalledSubagents())
+    const subagents = {};
+    for (const sub of listInstalledSubagents()) {
+        if (!available.subagents.includes(sub.name))
+            continue;
+        subagents[sub.name] = { dirPath: sub.path, files: fingerprintDir(sub.path) };
+    }
+    return {
+        v: MANIFEST_VERSION,
+        syncedAt: new Date().toISOString(),
+        commands,
+        skills,
+        hooks,
+        rules: { files: ruleFiles },
+        mcp,
+        permissions: {
+            groups: permGroups,
+            permissionSet: getActivePermissionSetName(),
+        },
+        subagents,
+    };
+}
+/**
+ * Check if sources have changed since the manifest was written.
+ * Returns true (stale) at the first detected mismatch — no need to scan everything.
+ * Returns false (clean) only after all checks pass.
+ *
+ * For rules, also delegates to isMemoryStale() to catch @-import changes
+ * for agents that pre-compile their memory file.
+ */
+export function isSyncStale(manifest, available, agent, version, cwd) {
+    // ── Commands ──────────────────────────────────────────────────────────────
+    if (nameSetDiffers(Object.keys(manifest.commands), available.commands))
+        return true;
+    for (const name of available.commands) {
+        const resolved = resolveResource('commands', `${name}.md`, cwd);
+        if (!resolved)
+            return true;
+        const entry = manifest.commands[name];
+        if (!entry || isFileStale(entry.source, resolved.path))
+            return true;
+    }
+    // ── Skills ────────────────────────────────────────────────────────────────
+    if (nameSetDiffers(Object.keys(manifest.skills), available.skills))
+        return true;
+    for (const name of available.skills) {
+        const dirPath = resolveSkillDir(name, cwd);
+        if (!dirPath)
+            return true;
+        const entry = manifest.skills[name];
+        if (!entry || isDirStale(entry, dirPath))
+            return true;
+    }
+    // ── Hooks ─────────────────────────────────────────────────────────────────
+    if (nameSetDiffers(Object.keys(manifest.hooks), available.hooks))
+        return true;
+    for (const name of available.hooks) {
+        const projectDir = getProjectAgentsDir(cwd);
+        const candidates = [
+            projectDir ? path.join(projectDir, 'hooks', name) : null,
+            path.join(getUserHooksDir(), name),
+            path.join(getHooksDir(), name),
+            ...getEnabledExtraRepos().map(e => path.join(e.dir, 'hooks', name)),
+        ];
+        const hookPath = candidates.find(p => p && fs.existsSync(p)) ?? null;
+        if (!hookPath)
+            return true;
+        const entry = manifest.hooks[name];
+        if (!entry || isFileStale(entry.source, hookPath))
+            return true;
+    }
+    // ── Rules/memory ──────────────────────────────────────────────────────────
+    if (nameSetDiffers(Object.keys(manifest.rules.files), available.memory))
+        return true;
+    for (const name of available.memory) {
+        const srcPath = resolveRuleFile(name, cwd);
+        if (!srcPath)
+            return true;
+        const entry = manifest.rules.files[name];
+        if (!entry || isFileStale(entry.source, srcPath))
+            return true;
+    }
+    // Also catch @-import changes for non-native-import agents
+    if (isMemoryStale(agent, version))
+        return true;
+    // ── MCP ───────────────────────────────────────────────────────────────────
+    const mcpServers = listMcpServerConfigs(cwd);
+    const mcpNames = mcpServers.map(s => s.name);
+    if (nameSetDiffers(Object.keys(manifest.mcp), mcpNames))
+        return true;
+    for (const server of mcpServers) {
+        const entry = manifest.mcp[server.name];
+        if (!entry || isFileStale(entry.source, server.path))
+            return true;
+    }
+    // ── Permissions ───────────────────────────────────────────────────────────
+    if (manifest.permissions.permissionSet !== getActivePermissionSetName())
+        return true;
+    const currentGroups = collectPermissionGroupFiles();
+    if (nameSetDiffers(Object.keys(manifest.permissions.groups), Object.keys(currentGroups)))
+        return true;
+    for (const [name, filePath] of Object.entries(currentGroups)) {
+        const entry = manifest.permissions.groups[name];
+        if (!entry || isFileStale(entry.source, filePath))
+            return true;
+    }
+    // ── Subagents ─────────────────────────────────────────────────────────────
+    const storedSubagents = manifest.subagents ?? {};
+    if (nameSetDiffers(Object.keys(storedSubagents), available.subagents))
+        return true;
+    if (available.subagents.length > 0) {
+        const allSubagents = listInstalledSubagents();
+        const subagentMap = new Map(allSubagents.map(s => [s.name, s]));
+        for (const name of available.subagents) {
+            const sub = subagentMap.get(name);
+            if (!sub)
+                return true;
+            const entry = storedSubagents[name];
+            if (!entry || isDirStale(entry, sub.path))
+                return true;
+        }
+    }
+    return false;
+}

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

@@ -6,6 +6,7 @@ import { AgentType } from './parsers.js';
  * Returns null if paths is empty or paths have no common ancestor (different roots).
  */
 export declare function computePathLCA(paths: string[]): string | null;
+/** Lifecycle status of a teammate process. */
 export declare enum AgentStatus {
     PENDING = "pending",// staged with unresolved --after deps
     RUNNING = "running",
@@ -13,20 +14,62 @@ export declare enum AgentStatus {
     FAILED = "failed",
     STOPPED = "stopped"
 }
+/** Task type label for Software Factory workflows. Drives planner fan-out. Optional — teammates without a task_type work exactly as before. */
+export type TaskType = 'plan' | 'implement' | 'test' | 'review' | 'bugfix' | 'docs';
+export declare const VALID_TASK_TYPES: readonly TaskType[];
 export type { AgentType } from './parsers.js';
+/**
+ * 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 declare function captureProcessStartTime(pid: number): string | null;
 export declare const AGENT_COMMANDS: Record<AgentType, string[]>;
+/**
+ * Rewrite a plan-mode command into edit mode (writes inside cwd allowed,
+ * approval prompts may still appear). Pure function — exported for tests.
+ */
+export declare function applyEditMode(agentType: AgentType, cmd: string[]): string[];
+/**
+ * Rewrite a plan-mode command into full mode (writes + approval gates
+ * bypassed). Pure function — exported for tests.
+ */
+export declare function applyFullMode(agentType: AgentType, cmd: string[]): string[];
+/**
+ * Reasoning-intensity knob wired into buildReasoningFlags.
+ * Does not select a model; use --model separately to pin a specific model per teammate.
+ */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 declare const VALID_MODES: readonly ["plan", "edit", "full"];
 type Mode = typeof VALID_MODES[number];
+/** Resolve a mode string to a validated Mode, falling back to the given default. */
 export declare function resolveMode(requestedMode: string | null | undefined, defaultMode?: Mode): Mode;
+/** Ensure Gemini's settings.json has experimental.plan enabled for headless plan mode. */
 export declare function ensureGeminiPlanMode(): Promise<void>;
+/** Check whether the CLI binary for a given agent type exists in PATH. Returns [available, pathOrError]. */
 export declare function checkCliAvailable(agentType: AgentType): [boolean, string | null];
+/** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export declare function checkAllClis(): Record<string, {
     installed: boolean;
     path: string | null;
     error: string | null;
 }>;
+/** Resolve and cache the base directory where teammate process data is stored. */
 export declare function getAgentsDir(): Promise<string>;
+/**
+ * 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 declare class AgentProcess {
     agentId: string;
     taskName: string;
@@ -36,6 +79,7 @@ export declare class AgentProcess {
     workspaceDir: string | null;
     mode: Mode;
     pid: number | null;
+    startTime: string | null;
     status: AgentStatus;
     startedAt: Date;
     completedAt: Date | null;
@@ -50,12 +94,36 @@ export declare class AgentProcess {
     effort: EffortLevel | null;
     model: string | null;
     envOverrides: Record<string, string> | null;
+    taskType: TaskType | null;
+    cloudRepo: string | null;
+    cloudBranch: string | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
-    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null);
+    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudRepo?: string | null, cloudBranch?: string | null);
     get isEditMode(): boolean;
     getAgentDir(): Promise<string>;
+    /**
+     * Dump the subset of state the Ledger sync hook needs. Keeps sync.ts
+     * free of any teams-internal imports.
+     */
+    toSnapshot(): Promise<{
+        agent_id: string;
+        team_id: string;
+        teammate_name: string | null;
+        agent_type: string;
+        task_type: string | null;
+        status: string;
+        started_at: string;
+        completed_at: string | null;
+        after: string[];
+        cloud_provider: string | null;
+        cloud_session_id: string | null;
+        cloud_repo: string | null;
+        cloud_branch: string | null;
+        agent_dir: string;
+        cwd: string | null;
+    }>;
     getStdoutPath(): Promise<string>;
     getMetaPath(): Promise<string>;
     toDict(): any;
@@ -73,10 +141,24 @@ export declare class AgentProcess {
     updateStatusFromProcess(): Promise<void>;
     private reapProcess;
 }
+/**
+ * Manages the full lifecycle of teammate agent processes.
+ *
+ * Handles spawning (with DAG dependency resolution), status polling,
+ * stopping, and automatic cleanup of old agents. Maintains an in-memory
+ * cache backed by on-disk meta.json files.
+ */
+/**
+ * Callback used to dispatch a cloud-backed teammate when its --after deps
+ * resolve. Teams.ts registers one via setCloudDispatcher() at startup; the
+ * MCP server path leaves it null (cloud teammates aren't dispatched from MCP).
+ */
+export type CloudDispatchFn = (agent: AgentProcess) => Promise<{
+    cloudSessionId: string;
+}>;
 export declare class AgentManager {
     private agents;
     private maxAgents;
-    private maxConcurrent;
     private agentsDir;
     private filterByCwd;
     private cleanupAgeDays;
@@ -84,15 +166,32 @@ export declare class AgentManager {
     private agentConfigs;
     private constructorAgentConfigs;
     private initPromise;
+    private cloudDispatcher;
     private constructorAgentsDir;
-    constructor(maxAgents?: number, maxConcurrent?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, agentConfigs?: Record<AgentType, AgentConfig> | null);
+    constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, agentConfigs?: Record<AgentType, AgentConfig> | null);
     private initialize;
     private doInitialize;
     getDefaultMode(): Mode;
     setModelOverrides(agentConfigs: Record<AgentType, AgentConfig>): void;
+    /**
+     * Register the callback used to dispatch cloud-backed teammates when their
+     * --after deps resolve. Called once at CLI startup by `agents teams`.
+     */
+    setCloudDispatcher(fn: CloudDispatchFn | null): void;
     registerAgent(agent: AgentProcess): void;
+    /**
+     * 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.
+     */
+    rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, 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<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
@@ -143,4 +242,3 @@ export declare class AgentManager {
     private cleanupPartialAgent;
     private cleanupOldAgents;
 }
-//# sourceMappingURL=agents.d.ts.map