@herdctl/core 0.0.1

package/dist/fleet-manager/fleet-manager.js

@@ -0,0 +1,1906 @@
+/**
+ * FleetManager class for library consumers
+ *
+ * Provides a simple, high-level API to initialize and run a fleet of agents
+ * with minimal configuration. Handles config loading, state directory setup,
+ * and scheduler orchestration internally.
+ *
+ * @example
+ * ```typescript
+ * import { FleetManager } from '@herdctl/core';
+ *
+ * const manager = new FleetManager({
+ *   configPath: './herdctl.yaml',
+ *   stateDir: './.herdctl',
+ * });
+ *
+ * await manager.initialize();
+ * await manager.start();
+ *
+ * // Later...
+ * await manager.stop();
+ * ```
+ */
+import { EventEmitter } from "node:events";
+import { resolve } from "node:path";
+import { loadConfig, ConfigNotFoundError, ConfigError, } from "../config/index.js";
+import { initStateDirectory, createJob, getJob, updateJob, listJobs } from "../state/index.js";
+import { Scheduler } from "../scheduler/index.js";
+import { join } from "node:path";
+import { FleetManagerStateError, FleetManagerConfigError, FleetManagerStateDirError, FleetManagerShutdownError, AgentNotFoundError, ScheduleNotFoundError, ConcurrencyLimitError, InvalidStateError, 
+// Job control errors (US-6)
+JobCancelError, JobForkError, JobNotFoundError, } from "./errors.js";
+import { readFleetState } from "../state/fleet-state.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default check interval in milliseconds (1 second)
+ */
+const DEFAULT_CHECK_INTERVAL = 1000;
+// =============================================================================
+// Default Logger
+// =============================================================================
+/**
+ * Create a default console-based logger
+ */
+function createDefaultLogger() {
+    return {
+        debug: (message) => console.debug(`[fleet-manager] ${message}`),
+        info: (message) => console.info(`[fleet-manager] ${message}`),
+        warn: (message) => console.warn(`[fleet-manager] ${message}`),
+        error: (message) => console.error(`[fleet-manager] ${message}`),
+    };
+}
+// =============================================================================
+// FleetManager Class
+// =============================================================================
+/**
+ * FleetManager provides a simple API to manage a fleet of agents
+ *
+ * This class is the primary entry point for library consumers who want to
+ * run herdctl programmatically. It handles:
+ *
+ * - Configuration loading and validation
+ * - State directory initialization
+ * - Scheduler lifecycle management
+ * - Event emission for monitoring
+ *
+ * ## Lifecycle
+ *
+ * 1. **Construction**: Create with options (configPath, stateDir)
+ * 2. **Initialize**: Call `initialize()` to load config and prepare state
+ * 3. **Start**: Call `start()` to begin scheduler and process schedules
+ * 4. **Stop**: Call `stop()` to gracefully shut down
+ *
+ * ## Events
+ *
+ * The FleetManager emits events for monitoring:
+ * - `initialized` - After successful initialization
+ * - `started` - When the scheduler starts running
+ * - `stopped` - When the scheduler stops
+ * - `error` - When an error occurs
+ * - `schedule:trigger` - When a schedule triggers an agent
+ * - `schedule:complete` - When an agent run completes
+ * - `schedule:error` - When an agent run fails
+ *
+ * ## Typed Events (US-2)
+ *
+ * The FleetManager also supports strongly-typed events via TypeScript:
+ * - `config:reloaded` - When configuration is hot-reloaded
+ * - `agent:started` - When an agent is started
+ * - `agent:stopped` - When an agent is stopped
+ * - `schedule:triggered` - When a schedule triggers (with payload)
+ * - `schedule:skipped` - When a schedule is skipped
+ * - `job:created` - When a job is created
+ * - `job:output` - When a job produces output
+ * - `job:completed` - When a job completes successfully
+ * - `job:failed` - When a job fails
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to typed events
+ * manager.on('job:created', (payload) => {
+ *   console.log(`Job ${payload.job.id} created for ${payload.agentName}`);
+ * });
+ *
+ * manager.on('job:output', (payload) => {
+ *   process.stdout.write(payload.output);
+ * });
+ *
+ * manager.on('job:completed', (payload) => {
+ *   console.log(`Job completed in ${payload.durationSeconds}s`);
+ * });
+ * ```
+ */
+export class FleetManager extends EventEmitter {
+    // Configuration
+    configPath;
+    stateDir;
+    logger;
+    checkInterval;
+    // Internal state
+    status = "uninitialized";
+    config = null;
+    stateDirInfo = null;
+    scheduler = null;
+    // Timing info
+    initializedAt = null;
+    startedAt = null;
+    stoppedAt = null;
+    lastError = null;
+    /**
+     * Create a new FleetManager instance
+     *
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration
+     * const manager = new FleetManager({
+     *   configPath: './herdctl.yaml',
+     *   stateDir: './.herdctl',
+     * });
+     *
+     * // With custom logger
+     * const manager = new FleetManager({
+     *   configPath: './herdctl.yaml',
+     *   stateDir: './.herdctl',
+     *   logger: myLogger,
+     *   checkInterval: 5000, // 5 seconds
+     * });
+     * ```
+     */
+    constructor(options) {
+        super();
+        this.configPath = options.configPath;
+        this.stateDir = resolve(options.stateDir);
+        this.logger = options.logger ?? createDefaultLogger();
+        this.checkInterval = options.checkInterval ?? DEFAULT_CHECK_INTERVAL;
+    }
+    // ===========================================================================
+    // Public State Accessors
+    // ===========================================================================
+    /**
+     * Get the current fleet manager state
+     *
+     * This provides a snapshot of the fleet manager's current status and
+     * configuration for monitoring purposes.
+     */
+    get state() {
+        return {
+            status: this.status,
+            initializedAt: this.initializedAt,
+            startedAt: this.startedAt,
+            stoppedAt: this.stoppedAt,
+            agentCount: this.config?.agents.length ?? 0,
+            lastError: this.lastError,
+        };
+    }
+    /**
+     * Get the loaded configuration
+     *
+     * @returns The resolved configuration, or null if not initialized
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get the loaded agents
+     *
+     * @returns Array of resolved agents, or empty array if not initialized
+     */
+    getAgents() {
+        return this.config?.agents ?? [];
+    }
+    // ===========================================================================
+    // Fleet Status Query Methods (US-3)
+    // ===========================================================================
+    /**
+     * Get overall fleet status
+     *
+     * Returns a comprehensive snapshot of the fleet state including:
+     * - Current state and uptime
+     * - Agent counts (total, idle, running, error)
+     * - Job counts
+     * - Scheduler information
+     *
+     * This method works whether the fleet is running or stopped.
+     *
+     * @returns A consistent FleetStatus snapshot
+     *
+     * @example
+     * ```typescript
+     * const status = await manager.getFleetStatus();
+     * console.log(`Fleet: ${status.state}`);
+     * console.log(`Uptime: ${status.uptimeSeconds}s`);
+     * console.log(`Running jobs: ${status.counts.runningJobs}`);
+     * ```
+     */
+    async getFleetStatus() {
+        // Get agent info to compute counts
+        const agentInfoList = await this.getAgentInfo();
+        // Compute counts from agent info
+        const counts = this.computeFleetCounts(agentInfoList);
+        // Compute uptime
+        let uptimeSeconds = null;
+        if (this.startedAt) {
+            const startTime = new Date(this.startedAt).getTime();
+            const endTime = this.stoppedAt
+                ? new Date(this.stoppedAt).getTime()
+                : Date.now();
+            uptimeSeconds = Math.floor((endTime - startTime) / 1000);
+        }
+        // Get scheduler state
+        const schedulerState = this.scheduler?.getState();
+        return {
+            state: this.status,
+            uptimeSeconds,
+            initializedAt: this.initializedAt,
+            startedAt: this.startedAt,
+            stoppedAt: this.stoppedAt,
+            counts,
+            scheduler: {
+                status: schedulerState?.status ?? "stopped",
+                checkCount: schedulerState?.checkCount ?? 0,
+                triggerCount: schedulerState?.triggerCount ?? 0,
+                lastCheckAt: schedulerState?.lastCheckAt ?? null,
+                checkIntervalMs: this.checkInterval,
+            },
+            lastError: this.lastError,
+        };
+    }
+    /**
+     * Get information about all configured agents
+     *
+     * Returns detailed information for each agent including:
+     * - Current status and job information
+     * - Schedule details with runtime state
+     * - Configuration details
+     *
+     * This method works whether the fleet is running or stopped.
+     *
+     * @returns Array of AgentInfo objects with current state
+     *
+     * @example
+     * ```typescript
+     * const agents = await manager.getAgentInfo();
+     * for (const agent of agents) {
+     *   console.log(`${agent.name}: ${agent.status}`);
+     *   console.log(`  Schedules: ${agent.scheduleCount}`);
+     * }
+     * ```
+     */
+    async getAgentInfo() {
+        const agents = this.config?.agents ?? [];
+        // Read fleet state for runtime information
+        const fleetState = await this.readFleetStateSnapshot();
+        return agents.map((agent) => {
+            const agentState = fleetState.agents[agent.name];
+            return this.buildAgentInfo(agent, agentState);
+        });
+    }
+    /**
+     * Get information about a specific agent by name
+     *
+     * Returns detailed information for the specified agent including:
+     * - Current status and job information
+     * - Schedule details with runtime state
+     * - Configuration details
+     *
+     * This method works whether the fleet is running or stopped.
+     *
+     * @param name - The agent name to look up
+     * @returns AgentInfo for the specified agent
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     *
+     * @example
+     * ```typescript
+     * const agent = await manager.getAgentInfoByName('my-agent');
+     * console.log(`Agent: ${agent.name}`);
+     * console.log(`Status: ${agent.status}`);
+     * console.log(`Running: ${agent.runningCount}/${agent.maxConcurrent}`);
+     * ```
+     */
+    async getAgentInfoByName(name) {
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === name);
+        if (!agent) {
+            throw new AgentNotFoundError(name);
+        }
+        // Read fleet state for runtime information
+        const fleetState = await this.readFleetStateSnapshot();
+        const agentState = fleetState.agents[name];
+        return this.buildAgentInfo(agent, agentState);
+    }
+    // ===========================================================================
+    // Private Status Query Helpers
+    // ===========================================================================
+    /**
+     * Read fleet state from disk for status queries
+     *
+     * This provides a consistent snapshot of the fleet state.
+     */
+    async readFleetStateSnapshot() {
+        if (!this.stateDirInfo) {
+            // Not initialized yet, return empty state
+            return { fleet: {}, agents: {} };
+        }
+        return await readFleetState(this.stateDirInfo.stateFile, {
+            logger: { warn: this.logger.warn },
+        });
+    }
+    /**
+     * Build AgentInfo from configuration and state
+     */
+    buildAgentInfo(agent, agentState) {
+        // Build schedule info
+        const schedules = this.buildScheduleInfoList(agent, agentState);
+        // Get running count from scheduler or state
+        const runningCount = this.scheduler?.getRunningJobCount(agent.name) ?? 0;
+        // Determine workspace path
+        let workspace;
+        if (typeof agent.workspace === "string") {
+            workspace = agent.workspace;
+        }
+        else if (agent.workspace?.root) {
+            workspace = agent.workspace.root;
+        }
+        return {
+            name: agent.name,
+            description: agent.description,
+            status: agentState?.status ?? "idle",
+            currentJobId: agentState?.current_job ?? null,
+            lastJobId: agentState?.last_job ?? null,
+            maxConcurrent: agent.instances?.max_concurrent ?? 1,
+            runningCount,
+            errorMessage: agentState?.error_message ?? null,
+            scheduleCount: schedules.length,
+            schedules,
+            model: agent.model,
+            workspace,
+        };
+    }
+    /**
+     * Build schedule info list from agent configuration and state
+     */
+    buildScheduleInfoList(agent, agentState) {
+        if (!agent.schedules) {
+            return [];
+        }
+        return Object.entries(agent.schedules).map(([name, schedule]) => {
+            const scheduleState = agentState?.schedules?.[name];
+            return {
+                name,
+                agentName: agent.name,
+                type: schedule.type,
+                interval: schedule.interval,
+                expression: schedule.expression,
+                status: scheduleState?.status ?? "idle",
+                lastRunAt: scheduleState?.last_run_at ?? null,
+                nextRunAt: scheduleState?.next_run_at ?? null,
+                lastError: scheduleState?.last_error ?? null,
+            };
+        });
+    }
+    /**
+     * Compute fleet counts from agent info list
+     */
+    computeFleetCounts(agentInfoList) {
+        let idleAgents = 0;
+        let runningAgents = 0;
+        let errorAgents = 0;
+        let totalSchedules = 0;
+        let runningSchedules = 0;
+        let runningJobs = 0;
+        for (const agent of agentInfoList) {
+            switch (agent.status) {
+                case "idle":
+                    idleAgents++;
+                    break;
+                case "running":
+                    runningAgents++;
+                    break;
+                case "error":
+                    errorAgents++;
+                    break;
+            }
+            totalSchedules += agent.scheduleCount;
+            runningJobs += agent.runningCount;
+            for (const schedule of agent.schedules) {
+                if (schedule.status === "running") {
+                    runningSchedules++;
+                }
+            }
+        }
+        return {
+            totalAgents: agentInfoList.length,
+            idleAgents,
+            runningAgents,
+            errorAgents,
+            totalSchedules,
+            runningSchedules,
+            runningJobs,
+        };
+    }
+    // ===========================================================================
+    // Schedule Management Methods (US-7)
+    // ===========================================================================
+    /**
+     * Get all schedules across all agents
+     *
+     * Returns a list of all configured schedules with their current state,
+     * including next trigger times.
+     *
+     * @returns Array of ScheduleInfo objects with current state
+     *
+     * @example
+     * ```typescript
+     * const schedules = await manager.getSchedules();
+     * for (const schedule of schedules) {
+     *   console.log(`${schedule.agentName}/${schedule.name}: ${schedule.status}`);
+     *   console.log(`  Next run: ${schedule.nextRunAt}`);
+     * }
+     * ```
+     */
+    async getSchedules() {
+        const agents = this.config?.agents ?? [];
+        const fleetState = await this.readFleetStateSnapshot();
+        const allSchedules = [];
+        for (const agent of agents) {
+            const agentState = fleetState.agents[agent.name];
+            const schedules = this.buildScheduleInfoList(agent, agentState);
+            allSchedules.push(...schedules);
+        }
+        return allSchedules;
+    }
+    /**
+     * Get a specific schedule by agent name and schedule name
+     *
+     * @param agentName - The name of the agent
+     * @param scheduleName - The name of the schedule
+     * @returns The schedule info with current state
+     * @throws {AgentNotFoundError} If the agent doesn't exist
+     * @throws {ScheduleNotFoundError} If the schedule doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const schedule = await manager.getSchedule('my-agent', 'hourly');
+     * console.log(`Status: ${schedule.status}`);
+     * console.log(`Last run: ${schedule.lastRunAt}`);
+     * console.log(`Next run: ${schedule.nextRunAt}`);
+     * ```
+     */
+    async getSchedule(agentName, scheduleName) {
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            throw new AgentNotFoundError(agentName, {
+                availableAgents: agents.map((a) => a.name),
+            });
+        }
+        if (!agent.schedules || !(scheduleName in agent.schedules)) {
+            const availableSchedules = agent.schedules
+                ? Object.keys(agent.schedules)
+                : [];
+            throw new ScheduleNotFoundError(agentName, scheduleName, {
+                availableSchedules,
+            });
+        }
+        const fleetState = await this.readFleetStateSnapshot();
+        const agentState = fleetState.agents[agentName];
+        const schedule = agent.schedules[scheduleName];
+        const scheduleState = agentState?.schedules?.[scheduleName];
+        return {
+            name: scheduleName,
+            agentName,
+            type: schedule.type,
+            interval: schedule.interval,
+            expression: schedule.expression,
+            status: scheduleState?.status ?? "idle",
+            lastRunAt: scheduleState?.last_run_at ?? null,
+            nextRunAt: scheduleState?.next_run_at ?? null,
+            lastError: scheduleState?.last_error ?? null,
+        };
+    }
+    /**
+     * Enable a disabled schedule
+     *
+     * Enables a schedule that was previously disabled, allowing it to trigger
+     * again on its configured interval. The enabled state is persisted to the
+     * state directory and survives restarts.
+     *
+     * @param agentName - The name of the agent
+     * @param scheduleName - The name of the schedule
+     * @returns The updated schedule info
+     * @throws {AgentNotFoundError} If the agent doesn't exist
+     * @throws {ScheduleNotFoundError} If the schedule doesn't exist
+     *
+     * @example
+     * ```typescript
+     * // Enable a previously disabled schedule
+     * const schedule = await manager.enableSchedule('my-agent', 'hourly');
+     * console.log(`Schedule status: ${schedule.status}`); // 'idle'
+     * ```
+     */
+    async enableSchedule(agentName, scheduleName) {
+        // Validate the agent and schedule exist
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            throw new AgentNotFoundError(agentName, {
+                availableAgents: agents.map((a) => a.name),
+            });
+        }
+        if (!agent.schedules || !(scheduleName in agent.schedules)) {
+            const availableSchedules = agent.schedules
+                ? Object.keys(agent.schedules)
+                : [];
+            throw new ScheduleNotFoundError(agentName, scheduleName, {
+                availableSchedules,
+            });
+        }
+        // Update schedule state to enabled (idle)
+        const { updateScheduleState } = await import("../scheduler/schedule-state.js");
+        await updateScheduleState(this.stateDir, agentName, scheduleName, { status: "idle" }, { logger: { warn: this.logger.warn } });
+        this.logger.info(`Enabled schedule ${agentName}/${scheduleName}`);
+        // Return the updated schedule info
+        return this.getSchedule(agentName, scheduleName);
+    }
+    /**
+     * Disable a schedule
+     *
+     * Disables a schedule, preventing it from triggering on its configured
+     * interval. The schedule remains in the configuration but won't run until
+     * re-enabled. The disabled state is persisted to the state directory and
+     * survives restarts.
+     *
+     * @param agentName - The name of the agent
+     * @param scheduleName - The name of the schedule
+     * @returns The updated schedule info
+     * @throws {AgentNotFoundError} If the agent doesn't exist
+     * @throws {ScheduleNotFoundError} If the schedule doesn't exist
+     *
+     * @example
+     * ```typescript
+     * // Disable a schedule temporarily
+     * const schedule = await manager.disableSchedule('my-agent', 'hourly');
+     * console.log(`Schedule status: ${schedule.status}`); // 'disabled'
+     *
+     * // Later, re-enable it
+     * await manager.enableSchedule('my-agent', 'hourly');
+     * ```
+     */
+    async disableSchedule(agentName, scheduleName) {
+        // Validate the agent and schedule exist
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            throw new AgentNotFoundError(agentName, {
+                availableAgents: agents.map((a) => a.name),
+            });
+        }
+        if (!agent.schedules || !(scheduleName in agent.schedules)) {
+            const availableSchedules = agent.schedules
+                ? Object.keys(agent.schedules)
+                : [];
+            throw new ScheduleNotFoundError(agentName, scheduleName, {
+                availableSchedules,
+            });
+        }
+        // Update schedule state to disabled
+        const { updateScheduleState } = await import("../scheduler/schedule-state.js");
+        await updateScheduleState(this.stateDir, agentName, scheduleName, { status: "disabled" }, { logger: { warn: this.logger.warn } });
+        this.logger.info(`Disabled schedule ${agentName}/${scheduleName}`);
+        // Return the updated schedule info
+        return this.getSchedule(agentName, scheduleName);
+    }
+    // ===========================================================================
+    // Lifecycle Methods
+    // ===========================================================================
+    /**
+     * Initialize the fleet manager
+     *
+     * This method:
+     * 1. Loads and validates the configuration file
+     * 2. Initializes the state directory structure
+     * 3. Prepares the scheduler (but does not start it)
+     *
+     * After initialization, the fleet manager is ready to start.
+     *
+     * @throws {FleetManagerStateError} If already initialized or running
+     * @throws {FleetManagerConfigError} If configuration is invalid or not found
+     * @throws {FleetManagerStateDirError} If state directory cannot be created
+     *
+     * @example
+     * ```typescript
+     * const manager = new FleetManager({ ... });
+     * await manager.initialize();
+     * console.log(`Loaded ${manager.state.agentCount} agents`);
+     * ```
+     */
+    async initialize() {
+        // Validate current state
+        if (this.status !== "uninitialized" && this.status !== "stopped") {
+            throw new FleetManagerStateError("initialize", this.status, ["uninitialized", "stopped"]);
+        }
+        this.logger.info("Initializing fleet manager...");
+        try {
+            // Load configuration
+            this.logger.debug(this.configPath
+                ? `Loading config from: ${this.configPath}`
+                : "Auto-discovering config...");
+            this.config = await this.loadConfiguration();
+            this.logger.info(`Loaded ${this.config.agents.length} agent(s) from config`);
+            // Initialize state directory
+            this.logger.debug(`Initializing state directory: ${this.stateDir}`);
+            this.stateDirInfo = await this.initializeStateDir();
+            this.logger.debug("State directory initialized");
+            // Create scheduler (but don't start it)
+            this.scheduler = new Scheduler({
+                stateDir: this.stateDir,
+                checkInterval: this.checkInterval,
+                logger: this.logger,
+                onTrigger: (info) => this.handleScheduleTrigger(info),
+            });
+            // Update state
+            this.status = "initialized";
+            this.initializedAt = new Date().toISOString();
+            this.lastError = null;
+            this.logger.info("Fleet manager initialized successfully");
+            this.emit("initialized");
+        }
+        catch (error) {
+            this.status = "error";
+            this.lastError = error instanceof Error ? error.message : String(error);
+            this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Start the fleet manager
+     *
+     * This begins the scheduler, which will:
+     * 1. Check agent schedules at the configured interval
+     * 2. Trigger agents when their schedules are due
+     * 3. Track schedule state in the state directory
+     *
+     * @throws {FleetManagerStateError} If not initialized
+     *
+     * @example
+     * ```typescript
+     * await manager.initialize();
+     * await manager.start();
+     *
+     * // The manager is now running and processing schedules
+     * manager.on('schedule:trigger', (agent, schedule) => {
+     *   console.log(`Triggered ${agent}/${schedule}`);
+     * });
+     * ```
+     */
+    async start() {
+        // Validate current state
+        if (this.status !== "initialized") {
+            throw new FleetManagerStateError("start", this.status, "initialized");
+        }
+        this.logger.info("Starting fleet manager...");
+        this.status = "starting";
+        try {
+            // Start the scheduler with loaded agents
+            const agents = this.config.agents;
+            // Start scheduler in background (don't await the loop)
+            this.startSchedulerAsync(agents);
+            // Update state
+            this.status = "running";
+            this.startedAt = new Date().toISOString();
+            this.stoppedAt = null;
+            this.logger.info("Fleet manager started");
+            this.emit("started");
+        }
+        catch (error) {
+            this.status = "error";
+            this.lastError = error instanceof Error ? error.message : String(error);
+            this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Stop the fleet manager gracefully
+     *
+     * This will:
+     * 1. Signal the scheduler to stop accepting new triggers
+     * 2. Wait for running jobs to complete (with timeout)
+     * 3. If timeout is reached and cancelOnTimeout is true, cancel remaining jobs
+     * 4. Persist all state before shutdown completes
+     * 5. Emit 'stopped' event when complete
+     *
+     * @param options - Stop options for controlling shutdown behavior
+     * @throws {FleetManagerShutdownError} If shutdown times out and cancelOnTimeout is false
+     *
+     * @example
+     * ```typescript
+     * // Normal shutdown - wait for jobs with default 30s timeout
+     * await manager.stop();
+     *
+     * // Shutdown with custom timeout
+     * await manager.stop({ timeout: 60000 });
+     *
+     * // Shutdown without waiting for jobs (not recommended)
+     * await manager.stop({ waitForJobs: false });
+     *
+     * // Cancel jobs if they don't complete in time
+     * await manager.stop({
+     *   timeout: 30000,
+     *   cancelOnTimeout: true,
+     *   cancelTimeout: 10000,
+     * });
+     * ```
+     */
+    async stop(options) {
+        if (this.status !== "running" && this.status !== "starting") {
+            this.logger.debug(`Stop called but status is '${this.status}', ignoring`);
+            return;
+        }
+        const waitForJobs = options?.waitForJobs ?? true;
+        const timeout = options?.timeout ?? 30000;
+        const cancelOnTimeout = options?.cancelOnTimeout ?? false;
+        const cancelTimeout = options?.cancelTimeout ?? 10000;
+        this.logger.info("Stopping fleet manager...");
+        this.status = "stopping";
+        try {
+            // Stop the scheduler - don't wait for jobs here, we'll handle it ourselves
+            // This stops new triggers from being accepted
+            if (this.scheduler) {
+                try {
+                    await this.scheduler.stop({
+                        waitForJobs,
+                        timeout,
+                    });
+                }
+                catch (error) {
+                    // Check if it's a scheduler shutdown timeout
+                    if (error instanceof Error && error.name === "SchedulerShutdownError") {
+                        if (cancelOnTimeout) {
+                            // Cancel all running jobs
+                            this.logger.info("Timeout reached, cancelling running jobs...");
+                            await this.cancelRunningJobs(cancelTimeout);
+                        }
+                        else {
+                            // Re-throw the error
+                            this.status = "error";
+                            this.lastError = error.message;
+                            throw new FleetManagerShutdownError(error.message, {
+                                timedOut: true,
+                                cause: error,
+                            });
+                        }
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            // Persist fleet state before completing shutdown
+            await this.persistShutdownState();
+            // Update state
+            this.status = "stopped";
+            this.stoppedAt = new Date().toISOString();
+            this.logger.info("Fleet manager stopped");
+            this.emit("stopped");
+        }
+        catch (error) {
+            this.status = "error";
+            this.lastError = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+    }
+    /**
+     * Reload configuration without restarting the fleet
+     *
+     * This method provides hot configuration reload capability:
+     * 1. Loads and validates the new configuration
+     * 2. If validation fails, keeps the old configuration (fails gracefully)
+     * 3. Running jobs continue with their original configuration
+     * 4. New jobs will use the new configuration
+     * 5. Updates the scheduler with new agent definitions and schedules
+     * 6. Emits a 'config:reloaded' event with a list of changes
+     *
+     * @returns The reload result with change details
+     * @throws {InvalidStateError} If the fleet manager is not initialized
+     * @throws {FleetManagerConfigError} If the new configuration is invalid (re-thrown after logging)
+     *
+     * @example
+     * ```typescript
+     * // Reload configuration
+     * const result = await manager.reload();
+     * console.log(`Reloaded with ${result.changes.length} changes`);
+     *
+     * // Subscribe to reload events
+     * manager.on('config:reloaded', (payload) => {
+     *   console.log(`Config reloaded: ${payload.changes.length} changes`);
+     *   for (const change of payload.changes) {
+     *     console.log(`  ${change.type} ${change.category}: ${change.name}`);
+     *   }
+     * });
+     * ```
+     */
+    async reload() {
+        // Validate state - must be at least initialized
+        if (this.status === "uninitialized") {
+            throw new InvalidStateError("reload", this.status, ["initialized", "starting", "running", "stopping", "stopped"]);
+        }
+        this.logger.info("Reloading configuration...");
+        // Store old config for comparison
+        const oldConfig = this.config;
+        // Try to load new configuration
+        let newConfig;
+        try {
+            newConfig = await this.loadConfiguration();
+        }
+        catch (error) {
+            // Log the error but don't update config - fail gracefully
+            this.logger.error(`Failed to reload configuration: ${error instanceof Error ? error.message : String(error)}`);
+            this.logger.info("Keeping existing configuration");
+            // Re-throw so caller knows reload failed
+            throw error;
+        }
+        // Compute changes between old and new config
+        const changes = this.computeConfigChanges(oldConfig, newConfig);
+        // Update the stored configuration
+        this.config = newConfig;
+        // Update the scheduler with new agents (if scheduler exists and is running)
+        if (this.scheduler) {
+            this.scheduler.setAgents(newConfig.agents);
+            this.logger.debug(`Updated scheduler with ${newConfig.agents.length} agents`);
+        }
+        const timestamp = new Date().toISOString();
+        // Build the reload payload
+        const payload = {
+            agentCount: newConfig.agents.length,
+            agentNames: newConfig.agents.map((a) => a.name),
+            configPath: newConfig.configPath,
+            changes,
+            timestamp,
+        };
+        // Emit the config:reloaded event
+        this.emit("config:reloaded", payload);
+        this.logger.info(`Configuration reloaded: ${newConfig.agents.length} agents, ${changes.length} changes`);
+        return payload;
+    }
+    /**
+     * Compute the list of changes between old and new configuration
+     */
+    computeConfigChanges(oldConfig, newConfig) {
+        const changes = [];
+        const oldAgents = oldConfig?.agents ?? [];
+        const newAgents = newConfig.agents;
+        const oldAgentNames = new Set(oldAgents.map((a) => a.name));
+        const newAgentNames = new Set(newAgents.map((a) => a.name));
+        // Find added agents
+        for (const agent of newAgents) {
+            if (!oldAgentNames.has(agent.name)) {
+                changes.push({
+                    type: "added",
+                    category: "agent",
+                    name: agent.name,
+                    details: agent.description,
+                });
+                // Also add all schedules for new agents
+                if (agent.schedules) {
+                    for (const scheduleName of Object.keys(agent.schedules)) {
+                        changes.push({
+                            type: "added",
+                            category: "schedule",
+                            name: `${agent.name}/${scheduleName}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Find removed agents
+        for (const agent of oldAgents) {
+            if (!newAgentNames.has(agent.name)) {
+                changes.push({
+                    type: "removed",
+                    category: "agent",
+                    name: agent.name,
+                });
+                // Also mark all schedules as removed
+                if (agent.schedules) {
+                    for (const scheduleName of Object.keys(agent.schedules)) {
+                        changes.push({
+                            type: "removed",
+                            category: "schedule",
+                            name: `${agent.name}/${scheduleName}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Find modified agents and schedules
+        for (const newAgent of newAgents) {
+            const oldAgent = oldAgents.find((a) => a.name === newAgent.name);
+            if (!oldAgent) {
+                continue; // Already handled as "added"
+            }
+            // Check for agent-level modifications
+            const agentModified = this.isAgentModified(oldAgent, newAgent);
+            if (agentModified) {
+                changes.push({
+                    type: "modified",
+                    category: "agent",
+                    name: newAgent.name,
+                    details: agentModified,
+                });
+            }
+            // Check for schedule changes
+            const oldScheduleNames = new Set(oldAgent.schedules ? Object.keys(oldAgent.schedules) : []);
+            const newScheduleNames = new Set(newAgent.schedules ? Object.keys(newAgent.schedules) : []);
+            // Added schedules
+            for (const scheduleName of newScheduleNames) {
+                if (!oldScheduleNames.has(scheduleName)) {
+                    changes.push({
+                        type: "added",
+                        category: "schedule",
+                        name: `${newAgent.name}/${scheduleName}`,
+                    });
+                }
+            }
+            // Removed schedules
+            for (const scheduleName of oldScheduleNames) {
+                if (!newScheduleNames.has(scheduleName)) {
+                    changes.push({
+                        type: "removed",
+                        category: "schedule",
+                        name: `${newAgent.name}/${scheduleName}`,
+                    });
+                }
+            }
+            // Modified schedules
+            for (const scheduleName of newScheduleNames) {
+                if (oldScheduleNames.has(scheduleName)) {
+                    const oldSchedule = oldAgent.schedules[scheduleName];
+                    const newSchedule = newAgent.schedules[scheduleName];
+                    if (this.isScheduleModified(oldSchedule, newSchedule)) {
+                        changes.push({
+                            type: "modified",
+                            category: "schedule",
+                            name: `${newAgent.name}/${scheduleName}`,
+                            details: this.getScheduleModificationDetails(oldSchedule, newSchedule),
+                        });
+                    }
+                }
+            }
+        }
+        return changes;
+    }
+    /**
+     * Check if an agent configuration has been modified
+     * Returns a description of what changed, or null if not modified
+     */
+    isAgentModified(oldAgent, newAgent) {
+        const modifications = [];
+        // Check key properties
+        if (oldAgent.description !== newAgent.description) {
+            modifications.push("description");
+        }
+        if (oldAgent.model !== newAgent.model) {
+            modifications.push("model");
+        }
+        if (oldAgent.max_turns !== newAgent.max_turns) {
+            modifications.push("max_turns");
+        }
+        if (oldAgent.system_prompt !== newAgent.system_prompt) {
+            modifications.push("system_prompt");
+        }
+        // Check workspace
+        const oldWorkspace = typeof oldAgent.workspace === "string"
+            ? oldAgent.workspace
+            : oldAgent.workspace?.root;
+        const newWorkspace = typeof newAgent.workspace === "string"
+            ? newAgent.workspace
+            : newAgent.workspace?.root;
+        if (oldWorkspace !== newWorkspace) {
+            modifications.push("workspace");
+        }
+        // Check instances
+        const oldMaxConcurrent = oldAgent.instances?.max_concurrent ?? 1;
+        const newMaxConcurrent = newAgent.instances?.max_concurrent ?? 1;
+        if (oldMaxConcurrent !== newMaxConcurrent) {
+            modifications.push("max_concurrent");
+        }
+        return modifications.length > 0 ? modifications.join(", ") : null;
+    }
+    /**
+     * Check if a schedule configuration has been modified
+     */
+    isScheduleModified(oldSchedule, newSchedule) {
+        return (oldSchedule.type !== newSchedule.type ||
+            oldSchedule.interval !== newSchedule.interval ||
+            oldSchedule.expression !== newSchedule.expression ||
+            oldSchedule.prompt !== newSchedule.prompt);
+    }
+    /**
+     * Get a description of what changed in a schedule
+     */
+    getScheduleModificationDetails(oldSchedule, newSchedule) {
+        const details = [];
+        if (oldSchedule.type !== newSchedule.type) {
+            details.push(`type: ${oldSchedule.type} → ${newSchedule.type}`);
+        }
+        if (oldSchedule.interval !== newSchedule.interval) {
+            details.push(`interval: ${oldSchedule.interval ?? "none"} → ${newSchedule.interval ?? "none"}`);
+        }
+        if (oldSchedule.expression !== newSchedule.expression) {
+            details.push(`expression: ${oldSchedule.expression ?? "none"} → ${newSchedule.expression ?? "none"}`);
+        }
+        if (oldSchedule.prompt !== newSchedule.prompt) {
+            details.push("prompt changed");
+        }
+        return details.join("; ");
+    }
+    /**
+     * Cancel all running jobs during shutdown
+     *
+     * @param cancelTimeout - Timeout for each job cancellation
+     */
+    async cancelRunningJobs(cancelTimeout) {
+        const jobsDir = join(this.stateDir, "jobs");
+        // Get all running jobs from the fleet status
+        const agentInfoList = await this.getAgentInfo();
+        const runningJobIds = [];
+        for (const agent of agentInfoList) {
+            if (agent.currentJobId) {
+                runningJobIds.push(agent.currentJobId);
+            }
+        }
+        if (runningJobIds.length === 0) {
+            this.logger.debug("No running jobs to cancel");
+            return;
+        }
+        this.logger.info(`Cancelling ${runningJobIds.length} running job(s)...`);
+        // Cancel all jobs in parallel
+        const cancelPromises = runningJobIds.map(async (jobId) => {
+            try {
+                const result = await this.cancelJob(jobId, { timeout: cancelTimeout });
+                this.logger.debug(`Cancelled job ${jobId}: ${result.terminationType}`);
+            }
+            catch (error) {
+                this.logger.warn(`Failed to cancel job ${jobId}: ${error.message}`);
+            }
+        });
+        await Promise.all(cancelPromises);
+        this.logger.info("All jobs cancelled");
+    }
+    /**
+     * Persist shutdown state to ensure all state is saved before completing
+     */
+    async persistShutdownState() {
+        if (!this.stateDirInfo) {
+            return;
+        }
+        // Persist fleet state
+        const { writeFleetState } = await import("../state/fleet-state.js");
+        // Read current state and update with stopped status
+        const currentState = await this.readFleetStateSnapshot();
+        // Update fleet-level state
+        const updatedState = {
+            ...currentState,
+            fleet: {
+                ...currentState.fleet,
+                stoppedAt: new Date().toISOString(),
+            },
+        };
+        try {
+            await writeFleetState(this.stateDirInfo.stateFile, updatedState);
+            this.logger.debug("Fleet state persisted");
+        }
+        catch (error) {
+            this.logger.warn(`Failed to persist fleet state: ${error.message}`);
+        }
+    }
+    // ===========================================================================
+    // Manual Triggering (US-5)
+    // ===========================================================================
+    /**
+     * Manually trigger an agent outside its normal schedule
+     *
+     * This method allows you to trigger an agent on-demand for testing or
+     * handling urgent situations. You can optionally specify a schedule to use
+     * for configuration (prompt, work source, etc.) or pass runtime options
+     * to override defaults.
+     *
+     * @param agentName - Name of the agent to trigger
+     * @param scheduleName - Optional schedule name to use for configuration
+     * @param options - Optional runtime options to override defaults
+     * @returns The created job information
+     * @throws {InvalidStateError} If the fleet manager is not initialized
+     * @throws {AgentNotFoundError} If the agent doesn't exist
+     * @throws {ScheduleNotFoundError} If the specified schedule doesn't exist
+     * @throws {ConcurrencyLimitError} If the agent is at capacity and bypassConcurrencyLimit is false
+     *
+     * @example
+     * ```typescript
+     * // Trigger with agent defaults
+     * const job = await manager.trigger('my-agent');
+     *
+     * // Trigger a specific schedule
+     * const job = await manager.trigger('my-agent', 'hourly');
+     *
+     * // Trigger with custom prompt
+     * const job = await manager.trigger('my-agent', undefined, {
+     *   prompt: 'Review the latest security updates',
+     * });
+     *
+     * // Force trigger even at capacity
+     * const job = await manager.trigger('my-agent', undefined, {
+     *   bypassConcurrencyLimit: true,
+     * });
+     * ```
+     */
+    async trigger(agentName, scheduleName, options) {
+        // Validate state - must be at least initialized
+        if (this.status === "uninitialized") {
+            throw new InvalidStateError("trigger", this.status, ["initialized", "running", "stopped"]);
+        }
+        // Find the agent
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            throw new AgentNotFoundError(agentName, {
+                availableAgents: agents.map((a) => a.name),
+            });
+        }
+        // If a schedule name is provided, validate it exists
+        let schedule;
+        if (scheduleName) {
+            if (!agent.schedules || !(scheduleName in agent.schedules)) {
+                const availableSchedules = agent.schedules
+                    ? Object.keys(agent.schedules)
+                    : [];
+                throw new ScheduleNotFoundError(agentName, scheduleName, {
+                    availableSchedules,
+                });
+            }
+            schedule = agent.schedules[scheduleName];
+        }
+        // Check concurrency limits unless bypassed
+        if (!options?.bypassConcurrencyLimit) {
+            const maxConcurrent = agent.instances?.max_concurrent ?? 1;
+            const runningCount = this.scheduler?.getRunningJobCount(agentName) ?? 0;
+            if (runningCount >= maxConcurrent) {
+                throw new ConcurrencyLimitError(agentName, runningCount, maxConcurrent);
+            }
+        }
+        // Determine the prompt to use (priority: options > schedule > agent default)
+        const prompt = options?.prompt ?? schedule?.prompt ?? undefined;
+        // Create the job
+        const jobsDir = join(this.stateDir, "jobs");
+        const job = await createJob(jobsDir, {
+            agent: agentName,
+            trigger_type: "manual",
+            schedule: scheduleName ?? null,
+            prompt: prompt ?? null,
+        });
+        const timestamp = new Date().toISOString();
+        this.logger.info(`Manually triggered ${agentName}${scheduleName ? `/${scheduleName}` : ""} - job ${job.id}`);
+        // Emit job:created event
+        this.emit("job:created", {
+            job,
+            agentName,
+            scheduleName: scheduleName ?? null,
+            timestamp,
+        });
+        // Build and return the result
+        const result = {
+            jobId: job.id,
+            agentName,
+            scheduleName: scheduleName ?? null,
+            startedAt: job.started_at,
+            prompt,
+        };
+        return result;
+    }
+    // ===========================================================================
+    // Job Control (US-6)
+    // ===========================================================================
+    /**
+     * Cancel a running job gracefully
+     *
+     * This method cancels a running job by first sending SIGTERM to allow
+     * graceful shutdown. If the job doesn't terminate within the timeout,
+     * it will be forcefully killed with SIGKILL.
+     *
+     * @param jobId - ID of the job to cancel
+     * @param options - Optional cancellation options
+     * @param options.timeout - Time in ms to wait for graceful shutdown (default: 10000)
+     * @returns Result of the cancellation operation
+     * @throws {InvalidStateError} If the fleet manager is not initialized
+     * @throws {JobNotFoundError} If the job doesn't exist
+     *
+     * @example
+     * ```typescript
+     * // Cancel with default timeout
+     * const result = await manager.cancelJob('job-2024-01-15-abc123');
+     * console.log(`Job cancelled: ${result.terminationType}`);
+     *
+     * // Cancel with custom timeout
+     * const result = await manager.cancelJob('job-2024-01-15-abc123', {
+     *   timeout: 30000, // 30 seconds
+     * });
+     * ```
+     */
+    async cancelJob(jobId, options) {
+        // Validate state - must be at least initialized
+        if (this.status === "uninitialized") {
+            throw new InvalidStateError("cancelJob", this.status, ["initialized", "running", "stopped"]);
+        }
+        const jobsDir = join(this.stateDir, "jobs");
+        const timeout = options?.timeout ?? 10000; // Default 10 seconds
+        // Get the job to verify it exists and check its status
+        const job = await getJob(jobsDir, jobId, { logger: this.logger });
+        if (!job) {
+            throw new JobNotFoundError(jobId);
+        }
+        const timestamp = new Date().toISOString();
+        let terminationType;
+        let durationSeconds;
+        // If job is already not running, return early
+        if (job.status !== "running" && job.status !== "pending") {
+            this.logger.info(`Job ${jobId} is already ${job.status}, no cancellation needed`);
+            terminationType = 'already_stopped';
+            // Calculate duration if we have finished_at
+            if (job.finished_at) {
+                const startTime = new Date(job.started_at).getTime();
+                const endTime = new Date(job.finished_at).getTime();
+                durationSeconds = Math.round((endTime - startTime) / 1000);
+            }
+            return {
+                jobId,
+                success: true,
+                terminationType,
+                canceledAt: timestamp,
+            };
+        }
+        // Calculate duration
+        const startTime = new Date(job.started_at).getTime();
+        const endTime = new Date(timestamp).getTime();
+        durationSeconds = Math.round((endTime - startTime) / 1000);
+        // Try to cancel via the scheduler if it has process tracking
+        // For now, we'll update the job status directly since we don't have
+        // direct process control yet. In a full implementation, this would
+        // send SIGTERM to the process, wait, then SIGKILL if needed.
+        // Note: The scheduler/executor would need to track job processes
+        // and provide an API to cancel them. For this implementation,
+        // we'll update the job state and emit events, assuming the executor
+        // monitors the job status and handles cancellation.
+        this.logger.info(`Cancelling job ${jobId} for agent ${job.agent}`);
+        // Update job status to cancelled
+        try {
+            await updateJob(jobsDir, jobId, {
+                status: "cancelled",
+                exit_reason: "cancelled",
+                finished_at: timestamp,
+            });
+            // Assume graceful termination for now
+            // In a full implementation, this would be determined by whether
+            // the process responded to SIGTERM or required SIGKILL
+            terminationType = 'graceful';
+        }
+        catch (error) {
+            this.logger.error(`Failed to update job status: ${error.message}`);
+            throw new JobCancelError(jobId, 'process_error', {
+                cause: error,
+            });
+        }
+        // Emit job:cancelled event
+        const updatedJob = await getJob(jobsDir, jobId, { logger: this.logger });
+        if (updatedJob) {
+            this.emit("job:cancelled", {
+                job: updatedJob,
+                agentName: job.agent,
+                terminationType,
+                durationSeconds,
+                timestamp,
+            });
+        }
+        this.logger.info(`Job ${jobId} cancelled (${terminationType}) after ${durationSeconds}s`);
+        return {
+            jobId,
+            success: true,
+            terminationType,
+            canceledAt: timestamp,
+        };
+    }
+    /**
+     * Fork a job to create a new job based on an existing one
+     *
+     * This method creates a new job that is based on an existing job's
+     * configuration. The new job will have the same agent and can optionally
+     * have modifications applied (different prompt, schedule, etc.).
+     *
+     * If the original job has a session ID, the new job will fork from that
+     * session, preserving conversation context.
+     *
+     * @param jobId - ID of the job to fork
+     * @param modifications - Optional modifications to apply to the forked job
+     * @returns Result of the fork operation including the new job ID
+     * @throws {InvalidStateError} If the fleet manager is not initialized
+     * @throws {JobNotFoundError} If the original job doesn't exist
+     * @throws {JobForkError} If the job cannot be forked (e.g., no session)
+     *
+     * @example
+     * ```typescript
+     * // Fork with same configuration
+     * const result = await manager.forkJob('job-2024-01-15-abc123');
+     * console.log(`Forked to: ${result.jobId}`);
+     *
+     * // Fork with modified prompt
+     * const result = await manager.forkJob('job-2024-01-15-abc123', {
+     *   prompt: 'Continue the previous task but focus on testing',
+     * });
+     *
+     * // Fork with different schedule
+     * const result = await manager.forkJob('job-2024-01-15-abc123', {
+     *   schedule: 'nightly',
+     * });
+     * ```
+     */
+    async forkJob(jobId, modifications) {
+        // Validate state - must be at least initialized
+        if (this.status === "uninitialized") {
+            throw new InvalidStateError("forkJob", this.status, ["initialized", "running", "stopped"]);
+        }
+        const jobsDir = join(this.stateDir, "jobs");
+        // Get the original job
+        const originalJob = await getJob(jobsDir, jobId, { logger: this.logger });
+        if (!originalJob) {
+            throw new JobForkError(jobId, 'job_not_found');
+        }
+        // Verify the agent exists in config
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === originalJob.agent);
+        if (!agent) {
+            throw new JobForkError(jobId, 'agent_not_found', {
+                message: `Agent "${originalJob.agent}" for job "${jobId}" not found in current configuration`,
+            });
+        }
+        // Determine the prompt to use (priority: modifications > original job)
+        const prompt = modifications?.prompt ?? originalJob.prompt ?? undefined;
+        // Determine the schedule to use
+        const scheduleName = modifications?.schedule ?? originalJob.schedule ?? undefined;
+        // Create the new job
+        const timestamp = new Date().toISOString();
+        const newJob = await createJob(jobsDir, {
+            agent: originalJob.agent,
+            trigger_type: "fork",
+            schedule: scheduleName ?? null,
+            prompt: prompt ?? null,
+            forked_from: jobId,
+        });
+        this.logger.info(`Forked job ${jobId} to new job ${newJob.id} for agent ${originalJob.agent}`);
+        // Emit job:created event
+        this.emit("job:created", {
+            job: newJob,
+            agentName: originalJob.agent,
+            scheduleName: scheduleName ?? undefined,
+            timestamp,
+        });
+        // Emit job:forked event
+        this.emit("job:forked", {
+            job: newJob,
+            originalJob,
+            agentName: originalJob.agent,
+            timestamp,
+        });
+        return {
+            jobId: newJob.id,
+            forkedFromJobId: jobId,
+            agentName: originalJob.agent,
+            startedAt: newJob.started_at,
+            prompt,
+        };
+    }
+    // ===========================================================================
+    // Log Streaming (US-11)
+    // ===========================================================================
+    /**
+     * Stream all fleet logs as an async iterable
+     *
+     * Provides a unified stream of logs from all sources in the fleet including
+     * agents, jobs, and the scheduler. Logs can be filtered by level and optionally
+     * by agent or job.
+     *
+     * For completed jobs, this will replay their history (if includeHistory is true)
+     * before streaming new logs from running jobs.
+     *
+     * @param options - Options for filtering and configuring the stream
+     * @returns An async iterable of LogEntry objects
+     *
+     * @example
+     * ```typescript
+     * // Stream all info+ logs
+     * for await (const log of manager.streamLogs()) {
+     *   console.log(`[${log.level}] ${log.message}`);
+     * }
+     *
+     * // Stream only errors for a specific agent
+     * for await (const log of manager.streamLogs({
+     *   level: 'error',
+     *   agentName: 'my-agent',
+     * })) {
+     *   console.error(log.message);
+     * }
+     * ```
+     */
+    async *streamLogs(options) {
+        const level = options?.level ?? "info";
+        const includeHistory = options?.includeHistory ?? true;
+        const historyLimit = options?.historyLimit ?? 1000;
+        const agentFilter = options?.agentName;
+        const jobFilter = options?.jobId;
+        const jobsDir = join(this.stateDir, "jobs");
+        const { readJobOutputAll } = await import("../state/job-output.js");
+        // Replay historical logs if requested
+        if (includeHistory) {
+            // Get jobs to replay history from
+            const jobsResult = await listJobs(jobsDir, agentFilter ? { agent: agentFilter } : {}, { logger: this.logger });
+            // Filter by job ID if specified
+            let jobs = jobsResult.jobs;
+            if (jobFilter) {
+                jobs = jobs.filter((j) => j.id === jobFilter);
+            }
+            // Sort by started_at ascending to replay in chronological order
+            jobs.sort((a, b) => new Date(a.started_at).getTime() - new Date(b.started_at).getTime());
+            let yielded = 0;
+            for (const job of jobs) {
+                if (yielded >= historyLimit)
+                    break;
+                // Read job output and convert to log entries
+                const output = await readJobOutputAll(jobsDir, job.id, {
+                    skipInvalidLines: true,
+                    logger: this.logger,
+                });
+                for (const msg of output) {
+                    if (yielded >= historyLimit)
+                        break;
+                    const logEntry = this.jobOutputToLogEntry(job, msg);
+                    if (this.shouldYieldLog(logEntry, level, agentFilter, jobFilter)) {
+                        yield logEntry;
+                        yielded++;
+                    }
+                }
+            }
+        }
+        // For running jobs, subscribe to job:output events
+        const outputQueue = [];
+        let resolveWait = null;
+        let stopped = false;
+        const outputHandler = (payload) => {
+            if (stopped)
+                return;
+            const logEntry = {
+                timestamp: payload.timestamp,
+                level: "info",
+                source: "job",
+                agentName: payload.agentName,
+                jobId: payload.jobId,
+                message: payload.output,
+            };
+            if (this.shouldYieldLog(logEntry, level, agentFilter, jobFilter)) {
+                outputQueue.push(logEntry);
+                if (resolveWait) {
+                    resolveWait();
+                    resolveWait = null;
+                }
+            }
+        };
+        this.on("job:output", outputHandler);
+        try {
+            // Yield queued entries as they arrive
+            while (!stopped) {
+                while (outputQueue.length > 0) {
+                    const entry = outputQueue.shift();
+                    yield entry;
+                }
+                // Wait for more entries
+                await new Promise((resolve) => {
+                    resolveWait = resolve;
+                    // Add timeout to prevent hanging forever
+                    setTimeout(resolve, 1000);
+                });
+            }
+        }
+        finally {
+            stopped = true;
+            this.off("job:output", outputHandler);
+        }
+    }
+    /**
+     * Stream output from a specific job as an async iterable
+     *
+     * Provides a stream of log entries for a specific job. For completed jobs,
+     * this will replay the job's history and then complete. For running jobs,
+     * it will continue streaming until the job completes.
+     *
+     * @param jobId - The ID of the job to stream output from
+     * @returns An async iterable of LogEntry objects
+     * @throws {JobNotFoundError} If the job doesn't exist
+     *
+     * @example
+     * ```typescript
+     * // Stream job output
+     * for await (const log of manager.streamJobOutput('job-2024-01-15-abc123')) {
+     *   console.log(`[${log.level}] ${log.message}`);
+     * }
+     * ```
+     */
+    async *streamJobOutput(jobId) {
+        const jobsDir = join(this.stateDir, "jobs");
+        // Verify job exists
+        const job = await getJob(jobsDir, jobId, { logger: this.logger });
+        if (!job) {
+            throw new JobNotFoundError(jobId);
+        }
+        const { readJobOutputAll, getJobOutputPath } = await import("../state/job-output.js");
+        const { watch } = await import("node:fs");
+        const { stat } = await import("node:fs/promises");
+        const { createReadStream } = await import("node:fs");
+        const { createInterface } = await import("node:readline");
+        const outputPath = getJobOutputPath(jobsDir, jobId);
+        // First, replay all existing output
+        const existingOutput = await readJobOutputAll(jobsDir, jobId, {
+            skipInvalidLines: true,
+            logger: this.logger,
+        });
+        for (const msg of existingOutput) {
+            yield this.jobOutputToLogEntry(job, msg);
+        }
+        // If job is already completed, we're done
+        if (job.status !== "running" && job.status !== "pending") {
+            return;
+        }
+        // For running jobs, watch for new output
+        const outputQueue = [];
+        let resolveWait = null;
+        let stopped = false;
+        let lastReadPosition = 0;
+        // Get current file position
+        try {
+            const stats = await stat(outputPath);
+            lastReadPosition = stats.size;
+        }
+        catch {
+            // File doesn't exist yet
+        }
+        // Watch for file changes
+        let watcher = null;
+        try {
+            watcher = watch(outputPath, async (eventType) => {
+                if (stopped || eventType !== "change")
+                    return;
+                try {
+                    const currentStats = await stat(outputPath);
+                    if (currentStats.size > lastReadPosition) {
+                        // Read new content
+                        const fileStream = createReadStream(outputPath, {
+                            encoding: "utf-8",
+                            start: lastReadPosition,
+                        });
+                        const rl = createInterface({
+                            input: fileStream,
+                            crlfDelay: Infinity,
+                        });
+                        for await (const line of rl) {
+                            if (stopped)
+                                break;
+                            const trimmedLine = line.trim();
+                            if (trimmedLine === "")
+                                continue;
+                            try {
+                                const parsed = JSON.parse(trimmedLine);
+                                const logEntry = this.jobOutputToLogEntry(job, parsed);
+                                outputQueue.push(logEntry);
+                                if (resolveWait) {
+                                    resolveWait();
+                                    resolveWait = null;
+                                }
+                            }
+                            catch {
+                                // Skip malformed lines
+                            }
+                        }
+                        rl.close();
+                        fileStream.destroy();
+                        lastReadPosition = currentStats.size;
+                    }
+                }
+                catch (err) {
+                    this.logger.warn(`Error reading output file: ${err.message}`);
+                }
+            });
+        }
+        catch {
+            // Can't watch file - might not exist yet
+        }
+        // Poll for job completion
+        const checkJobComplete = async () => {
+            const currentJob = await getJob(jobsDir, jobId, { logger: this.logger });
+            return (!currentJob ||
+                (currentJob.status !== "running" && currentJob.status !== "pending"));
+        };
+        try {
+            // Yield queued entries as they arrive
+            while (!stopped) {
+                while (outputQueue.length > 0) {
+                    const entry = outputQueue.shift();
+                    yield entry;
+                }
+                // Check if job is complete
+                if (await checkJobComplete()) {
+                    stopped = true;
+                    break;
+                }
+                // Wait for more entries
+                await new Promise((resolve) => {
+                    resolveWait = resolve;
+                    setTimeout(resolve, 1000);
+                });
+            }
+        }
+        finally {
+            stopped = true;
+            if (watcher) {
+                watcher.close();
+            }
+        }
+    }
+    /**
+     * Stream logs for a specific agent as an async iterable
+     *
+     * Provides a stream of log entries for all jobs belonging to a specific agent.
+     * For completed jobs, this will replay their history. For running jobs, it
+     * will continue streaming until the iterator is stopped.
+     *
+     * @param agentName - The name of the agent to stream logs for
+     * @returns An async iterable of LogEntry objects
+     * @throws {AgentNotFoundError} If the agent doesn't exist in the configuration
+     *
+     * @example
+     * ```typescript
+     * // Stream all logs for an agent
+     * for await (const log of manager.streamAgentLogs('my-agent')) {
+     *   console.log(`[${log.jobId}] ${log.message}`);
+     * }
+     * ```
+     */
+    async *streamAgentLogs(agentName) {
+        // Verify agent exists
+        const agents = this.config?.agents ?? [];
+        const agent = agents.find((a) => a.name === agentName);
+        if (!agent) {
+            throw new AgentNotFoundError(agentName, {
+                availableAgents: agents.map((a) => a.name),
+            });
+        }
+        // Delegate to streamLogs with agent filter
+        yield* this.streamLogs({
+            agentName,
+            includeHistory: true,
+        });
+    }
+    // ===========================================================================
+    // Log Streaming Helpers (US-11)
+    // ===========================================================================
+    /**
+     * Convert a job output message to a LogEntry
+     */
+    jobOutputToLogEntry(job, msg) {
+        // Determine log level based on message type
+        let level = "info";
+        if (msg.type === "error") {
+            level = "error";
+        }
+        else if (msg.type === "system") {
+            level = "debug";
+        }
+        return {
+            timestamp: msg.timestamp ?? new Date().toISOString(),
+            level,
+            source: "job",
+            agentName: job.agent,
+            jobId: job.id,
+            scheduleName: job.schedule ?? undefined,
+            message: msg.content ?? "",
+            data: { type: msg.type },
+        };
+    }
+    /**
+     * Determine if a log entry should be yielded based on filters
+     */
+    shouldYieldLog(entry, minLevel, agentFilter, jobFilter) {
+        // Check log level
+        const levelOrder = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3,
+        };
+        if (levelOrder[entry.level] < levelOrder[minLevel]) {
+            return false;
+        }
+        // Check agent filter
+        if (agentFilter && entry.agentName !== agentFilter) {
+            return false;
+        }
+        // Check job filter
+        if (jobFilter && entry.jobId !== jobFilter) {
+            return false;
+        }
+        return true;
+    }
+    // ===========================================================================
+    // Private Helper Methods
+    // ===========================================================================
+    /**
+     * Load configuration with proper error handling
+     */
+    async loadConfiguration() {
+        try {
+            return await loadConfig(this.configPath);
+        }
+        catch (error) {
+            if (error instanceof ConfigNotFoundError) {
+                throw new FleetManagerConfigError(`Configuration file not found. ${error.message}`, this.configPath, { cause: error });
+            }
+            if (error instanceof ConfigError) {
+                throw new FleetManagerConfigError(`Invalid configuration: ${error.message}`, this.configPath, { cause: error });
+            }
+            throw new FleetManagerConfigError(`Failed to load configuration: ${error instanceof Error ? error.message : String(error)}`, this.configPath, { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    /**
+     * Initialize state directory with proper error handling
+     */
+    async initializeStateDir() {
+        try {
+            return await initStateDirectory({ path: this.stateDir });
+        }
+        catch (error) {
+            throw new FleetManagerStateDirError(`Failed to initialize state directory: ${error instanceof Error ? error.message : String(error)}`, this.stateDir, { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    /**
+     * Start the scheduler asynchronously (don't block on the loop)
+     */
+    startSchedulerAsync(agents) {
+        // Start the scheduler loop in the background
+        // The scheduler.start() method runs the loop and returns when stopped
+        this.scheduler.start(agents).catch((error) => {
+            // Only handle errors if we're still supposed to be running
+            if (this.status === "running" || this.status === "starting") {
+                this.logger.error(`Scheduler error: ${error instanceof Error ? error.message : String(error)}`);
+                this.status = "error";
+                this.lastError = error instanceof Error ? error.message : String(error);
+                this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /**
+     * Handle schedule trigger callback from scheduler
+     */
+    async handleScheduleTrigger(info) {
+        const { agent, scheduleName, schedule } = info;
+        const timestamp = new Date().toISOString();
+        this.logger.info(`Triggering ${agent.name}/${scheduleName}`);
+        // Emit legacy event for backwards compatibility
+        this.emit("schedule:trigger", agent.name, scheduleName);
+        // Emit new typed event with full payload
+        this.emit("schedule:triggered", {
+            agentName: agent.name,
+            scheduleName,
+            schedule,
+            timestamp,
+        });
+        try {
+            // For now, just log the trigger
+            // In future PRDs, this will actually run the agent via the runner
+            this.logger.debug(`Schedule ${scheduleName} triggered for agent ${agent.name} ` +
+                `(type: ${schedule.type}, prompt: ${schedule.prompt ?? "default"})`);
+            // Emit legacy completion event for backwards compatibility
+            this.emit("schedule:complete", agent.name, scheduleName);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error(`Error in ${agent.name}/${scheduleName}: ${err.message}`);
+            // Emit legacy error event for backwards compatibility
+            this.emit("schedule:error", agent.name, scheduleName, err);
+            throw error;
+        }
+    }
+    // ===========================================================================
+    // Event Emission Helpers (US-2)
+    // ===========================================================================
+    /**
+     * Emit a config:reloaded event
+     *
+     * Called when configuration is hot-reloaded.
+     */
+    emitConfigReloaded(payload) {
+        this.emit("config:reloaded", payload);
+    }
+    /**
+     * Emit an agent:started event
+     *
+     * Called when an agent is started/registered with the fleet.
+     */
+    emitAgentStarted(payload) {
+        this.emit("agent:started", payload);
+    }
+    /**
+     * Emit an agent:stopped event
+     *
+     * Called when an agent is stopped/unregistered from the fleet.
+     */
+    emitAgentStopped(payload) {
+        this.emit("agent:stopped", payload);
+    }
+    /**
+     * Emit a schedule:skipped event
+     *
+     * Called when a schedule check is skipped (already running, disabled, etc.).
+     */
+    emitScheduleSkipped(payload) {
+        this.emit("schedule:skipped", payload);
+    }
+    /**
+     * Emit a job:created event
+     *
+     * Called when a new job is created.
+     */
+    emitJobCreated(payload) {
+        this.emit("job:created", payload);
+    }
+    /**
+     * Emit a job:output event
+     *
+     * Called when a job produces output during execution.
+     * This enables real-time streaming of output to UIs.
+     */
+    emitJobOutput(payload) {
+        this.emit("job:output", payload);
+    }
+    /**
+     * Emit a job:completed event
+     *
+     * Called when a job completes successfully.
+     */
+    emitJobCompleted(payload) {
+        this.emit("job:completed", payload);
+    }
+    /**
+     * Emit a job:failed event
+     *
+     * Called when a job fails.
+     */
+    emitJobFailed(payload) {
+        this.emit("job:failed", payload);
+    }
+    /**
+     * Emit a job:cancelled event (US-6)
+     *
+     * Called when a job is cancelled.
+     */
+    emitJobCancelled(payload) {
+        this.emit("job:cancelled", payload);
+    }
+    /**
+     * Emit a job:forked event (US-6)
+     *
+     * Called when a job is forked to create a new job.
+     */
+    emitJobForked(payload) {
+        this.emit("job:forked", payload);
+    }
+}
+//# sourceMappingURL=fleet-manager.js.map