@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/agent/multi-agent/base-agent.d.ts

@@ -7,6 +7,12 @@
 import { EventEmitter } from "events";
 import { CodeBuddyClient, CodeBuddyMessage, CodeBuddyTool } from "../../codebuddy/client.js";
 import { AgentRole, AgentConfig, AgentTask, AgentExecutionResult, AgentMessage, AgentFeedback, TaskArtifact, SharedContext, ToolExecutor } from "./types.js";
+/**
+ * Resolve the model a MAS agent should call.
+ * An explicit per-agent override wins; otherwise GROK_MODEL (local Ollama)
+ * beats the hardcoded grok-3-latest defaults on Coder/Reviewer/etc.
+ */
+export declare function resolveMultiAgentModel(configModel: string | undefined, overrideModel: string | undefined, envModel?: string | undefined): string;
 /**
  * Abstract base class for all agents
  */
@@ -20,6 +26,8 @@ export declare abstract class BaseAgent extends EventEmitter {
     protected toolsUsed: string[];
     protected rounds: number;
     protected startTime: number;
+    /** Conversation-private scope for lossless tool-observation recovery. */
+    private readonly recoverySessionId;
     constructor(config: AgentConfig, apiKey: string, baseURL?: string);
     /**
      * Initialize the system prompt with agent-specific instructions
@@ -44,7 +52,10 @@ export declare abstract class BaseAgent extends EventEmitter {
     /**
      * Run the main agent loop
      */
-    protected runAgentLoop(tools: CodeBuddyTool[], executeTool: ToolExecutor): Promise<string>;
+    protected runAgentLoop(tools: CodeBuddyTool[], executeTool: ToolExecutor, observationContext: {
+        query: string;
+        workspaceRoot: string;
+    }): Promise<string>;
     /**
      * Parse artifacts from the output
      */

package/dist/agent/multi-agent/base-agent.js

@@ -5,8 +5,28 @@
  * Provides common functionality for LLM interaction, tool execution, and messaging.
  */
 import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
 import { CodeBuddyClient } from "../../codebuddy/client.js";
+import { formatToolResultForRecovery } from "../../context/restorable-compression.js";
 import { getErrorMessage } from "../../types/index.js";
+import { commandFromToolArguments, prepareToolObservationForPrompt, } from "../prompt-tool-observation.js";
+/**
+ * Resolve the model a MAS agent should call.
+ * An explicit per-agent override wins; otherwise GROK_MODEL (local Ollama)
+ * beats the hardcoded grok-3-latest defaults on Coder/Reviewer/etc.
+ */
+export function resolveMultiAgentModel(configModel, overrideModel, envModel = process.env.GROK_MODEL) {
+    const fromOverride = overrideModel?.trim();
+    if (fromOverride)
+        return fromOverride;
+    const fromEnv = envModel?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const fromConfig = configModel?.trim();
+    if (fromConfig)
+        return fromConfig;
+    return 'grok-3-latest';
+}
 /**
  * Abstract base class for all agents
  */
@@ -20,6 +40,8 @@ export class BaseAgent extends EventEmitter {
     toolsUsed = [];
     rounds = 0;
     startTime = 0;
+    /** Conversation-private scope for lossless tool-observation recovery. */
+    recoverySessionId = `multi-agent-${randomUUID()}`;
     constructor(config, apiKey, baseURL) {
         super();
         this.config = {
@@ -37,7 +59,7 @@ export class BaseAgent extends EventEmitter {
         const override = config.providerOverride;
         const effectiveApiKey = override?.apiKey ?? apiKey;
         const effectiveBaseURL = override?.baseURL ?? baseURL;
-        const effectiveModel = override?.model ?? config.model ?? "grok-3-latest";
+        const effectiveModel = resolveMultiAgentModel(config.model, override?.model);
         this.client = new CodeBuddyClient(effectiveApiKey, effectiveModel, effectiveBaseURL);
         this.initializeSystemPrompt();
     }
@@ -105,7 +127,10 @@ Current working directory: ${process.cwd()}`;
             // Filter tools based on agent capabilities
             const allowedTools = this.filterTools(tools);
             // Run the agent loop
-            const output = await this.runAgentLoop(allowedTools, executeTool);
+            const output = await this.runAgentLoop(allowedTools, executeTool, {
+                query: `${task.title}\n${task.description}`,
+                workspaceRoot: context.codebaseInfo?.rootPath ?? process.cwd(),
+            });
             // Parse artifacts from output
             this.parseArtifacts(output);
             const result = {
@@ -180,15 +205,22 @@ ${context.decisions.slice(-5).map(d => `- ${d.description} (by ${d.madeBy})`).jo
      * Filter tools based on agent's allowed tools
      */
     filterTools(tools) {
-        if (!this.config.allowedTools || this.config.allowedTools.length === 0) {
-            return tools;
+        const filtered = !this.config.allowedTools || this.config.allowedTools.length === 0
+            ? tools
+            : tools.filter(t => this.config.allowedTools.includes(t.function.name));
+        // Optimized observations advertise exact callId recovery. Keep the
+        // read-only recovery tool available whenever the host supplied it, even
+        // for specialized agents whose historical whitelist predates it.
+        const restoreContext = tools.find((tool) => tool.function.name === "restore_context");
+        if (restoreContext && !filtered.some((tool) => tool.function.name === "restore_context")) {
+            return [...filtered, restoreContext];
         }
-        return tools.filter(t => this.config.allowedTools.includes(t.function.name));
+        return filtered;
     }
     /**
      * Run the main agent loop
      */
-    async runAgentLoop(tools, executeTool) {
+    async runAgentLoop(tools, executeTool, observationContext) {
         const maxRounds = this.config.maxRounds || 30;
         let accumulatedOutput = "";
         while (this.isRunning && this.rounds < maxRounds) {
@@ -222,12 +254,28 @@ ${context.decisions.slice(-5).map(d => `- ${d.description} (by ${d.madeBy})`).jo
                         role: this.config.role,
                         tool: toolCall.function.name,
                     });
-                    const result = await executeTool(toolCall);
+                    const result = await executeTool(toolCall, {
+                        recoverySessionId: this.recoverySessionId,
+                    });
+                    const rawContent = formatToolResultForRecovery(result);
+                    const observation = await prepareToolObservationForPrompt({
+                        toolName: toolCall.function.name,
+                        toolCallId: toolCall.id,
+                        content: rawContent,
+                        success: result.success,
+                        exitCode: result.success ? 0 : 1,
+                        ...(result.error === undefined ? {} : { error: result.error }),
+                        command: commandFromToolArguments(toolCall.function.arguments),
+                        query: observationContext.query,
+                        workspaceRoot: observationContext.workspaceRoot,
+                        sessionId: this.recoverySessionId,
+                        model: resolveMultiAgentModel(this.config.model, this.config.providerOverride?.model),
+                        messages: this.messages,
+                        allowOptimization: tools.some((tool) => tool.function.name === "restore_context"),
+                    });
                     this.messages.push({
                         role: "tool",
-                        content: result.success
-                            ? result.output || "Success"
-                            : result.error || "Error",
+                        content: observation.content,
                         tool_call_id: toolCall.id,
                     });
                 }

package/dist/agent/multi-agent/enhanced-coordination.js

@@ -704,6 +704,7 @@ export class EnhancedCoordinator extends EventEmitter {
             const { saveMetrics } = await import('./metrics-persistence.js');
             await saveMetrics(this.agentMetrics);
             this.metricsSavedAt = new Date();
+            this.emit('metrics:saved');
         }
         catch (err) {
             logger.warn('[multi-agent] metrics flush save failed', { error: String(err) });

package/dist/agent/multi-agent/metrics-persistence.js

@@ -34,6 +34,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { logger } from '../../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../../utils/atomic-write.js';
 /**
  * Resolve the metrics file path. Honours `CODEBUDDY_METRICS_PATH` env var
  * so parallel test files (running in separate vitest forks) can use unique
@@ -78,33 +79,46 @@ function deserializeMetrics(s) {
         avgCostPerTask: s.avgCostPerTask,
     };
 }
+const pendingSaves = new Map();
 /**
  * Save metrics atomically (write to .tmp + rename).
  * Best-effort — never throws; logs and swallows on failure.
  */
 export async function saveMetrics(map) {
     const metricsPath = resolveMetricsPath();
-    const tmpPath = `${metricsPath}.tmp`;
+    // Capture before yielding: later mutations must not change this snapshot.
+    const envelope = {
+        schemaVersion: 'v0.4',
+        savedAt: new Date().toISOString(),
+        metrics: Array.from(map.entries()).map(([role, m]) => [role, serializeMetrics(m)]),
+    };
+    const save = (pendingSaves.get(metricsPath) ?? Promise.resolve()).then(async () => {
+        try {
+            await ensureDir(metricsPath);
+            await writeJsonAtomic(metricsPath, envelope, { mode: 0o600 });
+        }
+        catch (err) {
+            logger.warn('[multi-agent] metrics persistence save failed', { error: String(err) });
+        }
+    });
+    pendingSaves.set(metricsPath, save);
     try {
-        await ensureDir(metricsPath);
-        const envelope = {
-            schemaVersion: 'v0.4',
-            savedAt: new Date().toISOString(),
-            metrics: Array.from(map.entries()).map(([role, m]) => [role, serializeMetrics(m)]),
-        };
-        const json = JSON.stringify(envelope, null, 2);
-        await fs.writeFile(tmpPath, json, 'utf8');
-        await fs.rename(tmpPath, metricsPath);
+        await save;
     }
-    catch (err) {
-        logger.warn('[multi-agent] metrics persistence save failed', { error: String(err) });
+    finally {
+        if (pendingSaves.get(metricsPath) === save)
+            pendingSaves.delete(metricsPath);
     }
 }
 export async function loadMetrics() {
     const metricsPath = resolveMetricsPath();
     try {
-        const raw = await fs.readFile(metricsPath, 'utf8');
-        const parsed = JSON.parse(raw);
+        const parsed = await readJsonAtomic(metricsPath, null, {
+            mode: 0o600,
+            isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value)),
+        });
+        if (!parsed)
+            return null;
         if (parsed.schemaVersion !== 'v0.4') {
             logger.warn(`[multi-agent] metrics schema version "${parsed.schemaVersion}" not supported in V0.4.1; ignoring persisted metrics`);
             return null;

package/dist/agent/multi-agent/multi-agent-system.d.ts

@@ -27,6 +27,9 @@ export declare class MultiAgentSystem extends EventEmitter {
     private tools;
     private toolExecutor;
     private defaultRegistryInitialized;
+    private activeThreadRunner;
+    private threadEventDrain;
+    private readonly delegatedCostByRole;
     /**
      * Handler references captured when forwarding agent events, so dispose
      * can call `.off()` and avoid leaking listeners (F26). Keyed by role,
@@ -87,6 +90,8 @@ export declare class MultiAgentSystem extends EventEmitter {
      * Run a complete workflow for a given goal
      */
     runWorkflow(goal: string, options?: Partial<WorkflowOptions>): Promise<WorkflowResult>;
+    private startThreadDelegation;
+    private closeThreadDelegation;
     /**
      * Execute tasks sequentially
      */

package/dist/agent/multi-agent/multi-agent-system.js

@@ -17,6 +17,7 @@ import { createOrchestratorAgent } from "./agents/orchestrator-agent.js";
 import { createCoderAgent } from "./agents/coder-agent.js";
 import { createReviewerAgent } from "./agents/reviewer-agent.js";
 import { createTesterAgent } from "./agents/tester-agent.js";
+import { ThreadTaskRunner } from "../delegation/thread-task-runner.js";
 /**
  * Default workflow options
  */
@@ -45,6 +46,9 @@ export class MultiAgentSystem extends EventEmitter {
     tools = [];
     toolExecutor;
     defaultRegistryInitialized = false;
+    activeThreadRunner = null;
+    threadEventDrain = null;
+    delegatedCostByRole = new Map();
     /**
      * Handler references captured when forwarding agent events, so dispose
      * can call `.off()` and avoid leaking listeners (F26). Keyed by role,
@@ -150,7 +154,7 @@ export class MultiAgentSystem extends EventEmitter {
      * Default tool executor backed by the formal tool registry.
      * This keeps the multi-agent system usable even when no external executor is injected.
      */
-    async defaultToolExecutor(toolCall) {
+    async defaultToolExecutor(toolCall, executionExtra) {
         let args;
         try {
             args = JSON.parse(toolCall.function.arguments);
@@ -165,6 +169,7 @@ export class MultiAgentSystem extends EventEmitter {
         const result = await registry.execute(toolCall.function.name, args, {
             cwd: process.cwd(),
             extra: {
+                ...(executionExtra ?? {}),
                 source: "multi-agent-system",
                 toolCallId: toolCall.id,
             },
@@ -231,6 +236,9 @@ export class MultiAgentSystem extends EventEmitter {
         if (this.tools.length === 0) {
             await this.initializeTools();
         }
+        if (opts.threadDelegation) {
+            this.startThreadDelegation(opts.threadDelegation);
+        }
         const startTime = Date.now();
         const results = new Map();
         const errors = [];
@@ -337,9 +345,62 @@ export class MultiAgentSystem extends EventEmitter {
             return workflowResult;
         }
         finally {
+            await this.closeThreadDelegation();
             this.isRunning = false;
         }
     }
+    startThreadDelegation(options) {
+        if (this.activeThreadRunner) {
+            throw new Error("A threaded workflow is already active");
+        }
+        this.delegatedCostByRole.clear();
+        const runner = new ThreadTaskRunner({
+            parentBudget: options.parentBudget,
+            ...(options.concurrency === undefined ? {} : { concurrency: options.concurrency }),
+            ...(options.parentSignal === undefined ? {} : { parentSignal: options.parentSignal }),
+            createAgent: ({ agentId }) => {
+                const role = agentId;
+                const agent = this.agents.get(role);
+                if (!agent)
+                    throw new Error(`No agent found for delegated role: ${agentId}`);
+                return {
+                    execute: async (task) => {
+                        const result = await agent.execute(task, this.sharedContext, this.tools, this.toolExecutor);
+                        if (this.costManager && result.costUsd === undefined) {
+                            const model = agent.model ?? "default";
+                            result.costUsd = await this.costManager.recordExact(result, model, result.rounds);
+                        }
+                        this.delegatedCostByRole.set(role, (this.delegatedCostByRole.get(role) ?? 0) + (result.costUsd ?? 0));
+                        return result;
+                    },
+                    abortCurrentOperation: () => agent.stop(),
+                    dispose: () => undefined,
+                    getSessionCost: () => this.delegatedCostByRole.get(role) ?? 0,
+                };
+            },
+        });
+        this.activeThreadRunner = runner;
+        this.threadEventDrain = (async () => {
+            for await (const event of runner.events()) {
+                try {
+                    options.onEvent?.(event);
+                }
+                catch {
+                    // A display callback must never stop draining the shared channel.
+                }
+            }
+        })();
+    }
+    async closeThreadDelegation() {
+        const runner = this.activeThreadRunner;
+        const drain = this.threadEventDrain;
+        this.activeThreadRunner = null;
+        this.threadEventDrain = null;
+        if (!runner)
+            return;
+        await runner.close();
+        await drain;
+    }
     /**
      * Execute tasks sequentially
      */
@@ -553,13 +614,25 @@ export class MultiAgentSystem extends EventEmitter {
                 this.orchestrator.updateTaskStatus(this.currentPlan, task.id, "completed", dryRunResult);
                 return;
             }
-            // Execute the task
-            const result = await agent.execute(task, this.sharedContext, this.tools, this.toolExecutor);
+            // `/swarm` opts into the bounded ThreadDelegation transport. Ordinary
+            // `/agents` calls retain their existing direct execution path.
+            let result;
+            if (this.activeThreadRunner) {
+                const delegated = await this.activeThreadRunner.submit(agent.getRole(), task);
+                if (!delegated.success || delegated.output === undefined) {
+                    throw new Error(delegated.message ??
+                        `Delegated task stopped (${delegated.reason ?? "missing output"})`);
+                }
+                result = delegated.output;
+            }
+            else {
+                result = await agent.execute(task, this.sharedContext, this.tools, this.toolExecutor);
+            }
             results.set(task.id, result);
             // Phase L (V0.4) — record cost (exact if token counts in result,
             // else estimation). Mutates result.costUsd so EnhancedCoordinator
             // can pick it up via recordTaskCompletion.
-            if (this.costManager) {
+            if (this.costManager && result.costUsd === undefined) {
                 const model = agent.model ?? 'default';
                 const cost = await this.costManager.recordExact(result, model, result.rounds);
                 result.costUsd = cost;
@@ -656,6 +729,7 @@ export class MultiAgentSystem extends EventEmitter {
      */
     stop() {
         this.isRunning = false;
+        this.activeThreadRunner?.cancel("Parent workflow stopped");
         for (const agent of this.agents.values()) {
             agent.stop();
         }
@@ -742,6 +816,9 @@ export class MultiAgentSystem extends EventEmitter {
      * MultiAgentSystem through their own listener arrays.
      */
     dispose() {
+        this.activeThreadRunner?.cancel("Multi-agent system disposed");
+        for (const agent of this.agents.values())
+            agent.stop();
         this.reset();
         for (const [role, handlers] of this.agentListeners) {
             const agent = this.agents.get(role);

package/dist/agent/multi-agent/session-fleet-bridge.js

@@ -27,6 +27,7 @@
  * - No back-pressure (same as (d).1 deferral). Bursty session activity
  *   could fill the WS send buffer.
  */
+import { redactSecrets } from '../../fleet/privacy-lint.js';
 let _fleetBroadcaster = null;
 export function registerSessionFleetBroadcaster(broadcaster) {
     _fleetBroadcaster = broadcaster;
@@ -81,7 +82,7 @@ export function enableSessionFleetBridge(registry) {
             return;
         try {
             const preview = typeof message.content === 'string'
-                ? message.content.slice(0, 200)
+                ? redactSecrets(message.content).slice(0, 200)
                 : '<non-string content>';
             broadcastFleetEvent('fleet:session:message', {
                 sessionId,

package/dist/agent/multi-agent/session-registry.js

@@ -11,6 +11,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { homedir } from 'os';
+import { readJsonAtomic, writeJsonAtomic } from '../../utils/atomic-write.js';
 export const DEFAULT_SESSION_REGISTRY_CONFIG = {
     maxSessions: 1000,
     idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
@@ -345,8 +346,13 @@ export class SessionRegistry extends EventEmitter {
     async loadPersistedSessions() {
         try {
             const indexPath = path.join(this.config.persistPath, 'sessions.json');
-            const data = await fs.readFile(indexPath, 'utf-8');
-            const persisted = JSON.parse(data);
+            const persisted = await readJsonAtomic(indexPath, null, {
+                mode: 0o600,
+                isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value)),
+            });
+            if (!persisted || !Array.isArray(persisted.sessions) || !persisted.messages || typeof persisted.messages !== 'object') {
+                return;
+            }
             for (const session of persisted.sessions) {
                 session.createdAt = new Date(session.createdAt);
                 session.lastActivityAt = new Date(session.lastActivityAt);
@@ -372,7 +378,7 @@ export class SessionRegistry extends EventEmitter {
                 messages: Object.fromEntries(this.messages),
             };
             const indexPath = path.join(this.config.persistPath, 'sessions.json');
-            await fs.writeFile(indexPath, JSON.stringify(data, null, 2));
+            await writeJsonAtomic(indexPath, data, { mode: 0o600 });
         }
         catch (error) {
             this.emit('error', error);

package/dist/agent/multi-agent/team-manager.d.ts

@@ -41,6 +41,15 @@ export interface TeamTask {
     error?: string;
 }
 export type TeamStatus = 'inactive' | 'active' | 'paused' | 'dissolved';
+export interface PersistedTeam {
+    status: TeamStatus;
+    leadId: string | null;
+    teamGoal: string;
+    startedAt: string | null;
+    members: TeamMember[];
+    tasks: TeamTask[];
+    mailbox: MailboxMessage[];
+}
 export declare class TeamManager extends EventEmitter {
     private status;
     private leadId;
@@ -164,6 +173,8 @@ export declare class TeamManager extends EventEmitter {
     getTask(taskId: string): TeamTask | undefined;
     getLeadId(): string | null;
     getTeamGoal(): string;
+    snapshot(): PersistedTeam;
+    restore(raw: PersistedTeam): void;
 }
 export declare function getTeamManager(): TeamManager;
 export declare function resetTeamManager(): void;

package/dist/agent/multi-agent/team-manager.js

@@ -7,6 +7,9 @@
  * windows, communicating via a shared task list and mailbox system.
  */
 import { EventEmitter } from 'events';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
 import { createId } from './base-agent.js';
 // ============================================================================
 // TeamManager
@@ -40,6 +43,7 @@ export class TeamManager extends EventEmitter {
         this.tasks.clear();
         this.mailbox = [];
         this.emit('team:started', { leadId: this.leadId, goal });
+        persistTeam(this);
         return {
             success: true,
             leadId: this.leadId,
@@ -66,6 +70,7 @@ export class TeamManager extends EventEmitter {
         this.teamGoal = '';
         this.startedAt = null;
         this.status = 'inactive';
+        persistTeam(this);
         return {
             success: true,
             message: `Team dissolved. ${completedTasks}/${totalTasks} tasks completed with ${memberCount} member(s).`,
@@ -104,6 +109,7 @@ export class TeamManager extends EventEmitter {
         };
         this.members.set(memberId, member);
         this.emit('team:member-added', member);
+        persistTeam(this);
         return {
             success: true,
             memberId,
@@ -127,6 +133,7 @@ export class TeamManager extends EventEmitter {
         }
         this.members.delete(memberId);
         this.emit('team:member-removed', { memberId, role: member.role });
+        persistTeam(this);
         return { success: true, message: `Removed ${member.label} (${member.role}) from the team.` };
     }
     // ==========================================================================
@@ -154,6 +161,7 @@ export class TeamManager extends EventEmitter {
             this.autoAssignTask(task);
         }
         this.emit('team:task-added', task);
+        persistTeam(this);
         return task;
     }
     /**
@@ -173,19 +181,24 @@ export class TeamManager extends EventEmitter {
         if (updates.error)
             task.error = updates.error;
         task.updatedAt = new Date();
-        if (updates.status === 'completed') {
+        if (updates.status === 'completed')
             task.completedAt = new Date();
-            // Update member stats
+        if (updates.status === 'completed' || updates.status === 'failed') {
             if (task.assignedTo) {
                 const member = this.members.get(task.assignedTo);
                 if (member) {
-                    member.completedTasks++;
-                    member.status = 'idle';
-                    member.currentTaskId = null;
+                    if (updates.status === 'completed')
+                        member.completedTasks++;
+                    const next = Array.from(this.tasks.values()).find((candidate) => candidate.id !== task.id &&
+                        candidate.assignedTo === member.id &&
+                        candidate.status === 'in_progress');
+                    member.currentTaskId = next?.id ?? null;
+                    member.status = next ? 'working' : updates.status === 'failed' ? 'error' : 'idle';
                 }
             }
         }
         this.emit('team:task-updated', task);
+        persistTeam(this);
         return { success: true, message: `Task ${taskId} updated: ${task.status}` };
     }
     /**
@@ -201,11 +214,13 @@ export class TeamManager extends EventEmitter {
             return { success: false, message: `Member ${memberId} not found.` };
         }
         task.assignedTo = memberId;
+        task.assignedRole = member.role;
         task.status = 'in_progress';
         task.updatedAt = new Date();
         member.status = 'working';
         member.currentTaskId = taskId;
         this.emit('team:task-assigned', { taskId, memberId, role: member.role });
+        persistTeam(this);
         return { success: true, message: `Assigned "${task.title}" to ${member.label} (${member.role})` };
     }
     /**
@@ -251,6 +266,7 @@ export class TeamManager extends EventEmitter {
         };
         this.mailbox.push(msg);
         this.emit('team:message', msg);
+        persistTeam(this);
         return msg;
     }
     /**
@@ -277,6 +293,7 @@ export class TeamManager extends EventEmitter {
                 msg.read = true;
             }
         }
+        persistTeam(this);
     }
     // ==========================================================================
     // Status & Reporting
@@ -413,14 +430,86 @@ export class TeamManager extends EventEmitter {
     getTeamGoal() {
         return this.teamGoal;
     }
+    snapshot() {
+        return {
+            status: this.status,
+            leadId: this.leadId,
+            teamGoal: this.teamGoal,
+            startedAt: this.startedAt ? this.startedAt.toISOString() : null,
+            members: this.getMembers(),
+            tasks: this.getTasks(),
+            mailbox: this.mailbox.map((m) => ({ ...m })),
+        };
+    }
+    restore(raw) {
+        if (raw.status !== 'active')
+            return;
+        this.status = 'active';
+        this.leadId = raw.leadId;
+        this.teamGoal = raw.teamGoal ?? '';
+        this.startedAt = raw.startedAt ? new Date(raw.startedAt) : new Date();
+        this.members = new Map((raw.members ?? []).map((m) => [m.id, { ...m, joinedAt: new Date(m.joinedAt) }]));
+        this.tasks = new Map((raw.tasks ?? []).map((t) => [
+            t.id,
+            {
+                ...t,
+                createdAt: new Date(t.createdAt),
+                updatedAt: new Date(t.updatedAt),
+                completedAt: t.completedAt ? new Date(t.completedAt) : undefined,
+            },
+        ]));
+        this.mailbox = (raw.mailbox ?? []).map((msg) => ({
+            ...msg,
+            timestamp: new Date(msg.timestamp),
+        }));
+    }
 }
 // ============================================================================
 // Singleton
 // ============================================================================
 let teamManagerInstance = null;
+function teamPersistPath() {
+    const explicit = process.env.CODEBUDDY_TEAM_FILE?.trim();
+    if (explicit)
+        return explicit;
+    if (process.env.VITEST)
+        return null;
+    return join(homedir(), '.codebuddy', 'team-session.json');
+}
+function persistTeam(team) {
+    const file = teamPersistPath();
+    if (!file)
+        return;
+    try {
+        const snapshot = team.snapshot();
+        mkdirSync(dirname(file), { recursive: true });
+        if (snapshot.status === 'inactive') {
+            if (existsSync(file))
+                unlinkSync(file);
+            return;
+        }
+        writeFileSync(file, JSON.stringify(snapshot), 'utf8');
+    }
+    catch {
+        // Persistence is best-effort; coordination in-process still works.
+    }
+}
+function hydrateTeam(team) {
+    const file = teamPersistPath();
+    if (!file || !existsSync(file))
+        return;
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        team.restore(raw);
+    }
+    catch {
+        // Corrupt snapshot: start empty rather than crash /team status.
+    }
+}
 export function getTeamManager() {
     if (!teamManagerInstance) {
         teamManagerInstance = new TeamManager();
+        hydrateTeam(teamManagerInstance);
     }
     return teamManagerInstance;
 }