@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/teams/scheduler.js

@@ -1,45 +1,4 @@
-/**
- * Placement scheduler for distributed teams.
- *
- * Decides WHERE an unpinned teammate runs, resolving the create→pin→pool→local
- * cascade from the team's device pool and the live roster. Kept pure and
- * I/O-free (plain data in, a device name or null out) so it is trivially
- * testable and can be called from the hot launch path without SSH round-trips.
- *
- *   1. teammate has an explicit `--device` pin      → that device
- *   2. else the team pool has exactly one device     → that device (whole team)
- *   3. else the team pool has many devices           → best-viable pick
- *   4. else (no pin, no pool)                         → active worker pool
- *
- * Step 3 is cap-, health-, and harness-aware (RUSH-2002). When the caller
- * supplies live {@link DevicePlacementSignal}s (probed reachability, headroom,
- * load/mem, and whether the requested agent is installed + signed in), the pick:
- *   - EXCLUDES an unreachable device, an overloaded one (headroom `loaded`), a
- *     device at its `agents.max-concurrent` cap, and one the requested agent is
- *     not installed on;
- *   - RANKS the survivors by (a) agent installed + signed in, (b) lower load /
- *     memory (by headroom tier, then raw), (c) fewer running teammates, ties
- *     broken by pool order.
- * With no signals it degrades to the original cap-aware least-loaded pick, so
- * the pure roster-count path (and its tests) are unchanged.
- *
- * When every pool device is excluded, the pick FAILS LOUD ({@link
- * NoViableDeviceError}) naming each device's reason — never a silent fall back
- * to local, since the user asked for a remote pool. Pins are the user's own
- * choice and are never second-guessed; a pool of one is respected for
- * load/cap/reachability but still fails loud when the agent is provably not
- * installed there (running it would be futile).
- *
- * A device whose name equals the local machine id is treated as "local" — it
- * resolves to a null placement so the existing local spawn path runs unchanged,
- * letting the local machine participate in a pool as just another member.
- */
 import { machineId } from '../machine-id.js';
-/**
- * No device in the pool can host the teammate. Carries the per-device reasons so
- * the caller can print exactly why the pool is unusable instead of silently
- * degrading to a local run the user did not ask for.
- */
 export class NoViableDeviceError extends Error {
     excluded;
     agentLabel;
@@ -50,17 +9,10 @@ export class NoViableDeviceError extends Error {
         this.agentLabel = agentLabel;
     }
 }
-/**
- * Whether a failed placement can become viable without changing the team.
- * Capacity and load are time-varying; a pool with at least one such exclusion
- * must remain schedulable so a later supervisor wave can retry it. A pool that
- * is only missing the requested harness is a durable configuration failure.
- */
 export function isTransientPlacementBlock(error) {
     return error instanceof NoViableDeviceError
         && error.excluded.some((entry) => entry.reason === 'capped' || entry.reason === 'overloaded');
 }
-/** Build the user-facing fail-loud message from the per-device reasons. */
 export function formatNoViableMessage(excluded, agentLabel) {
     const anyNotInstalled = excluded.some((e) => e.reason === 'not-installed');
     const allCapped = excluded.length > 0 && excluded.every((e) => e.reason === 'capped');
@@ -68,8 +20,6 @@ export function formatNoViableMessage(excluded, agentLabel) {
     const perDevice = excluded
         .map((e) => (e.detail ? `${e.device} (${e.reason} ${e.detail})` : `${e.device} (${e.reason})`))
         .join(', ');
-    // When the whole pool lacks the agent, lead with the harness message the
-    // ticket specifies; otherwise summarize the mixed reasons.
     const head = anyNotInstalled
         ? `No device in the team pool can run ${agent}.`
         : allCapped
@@ -88,13 +38,9 @@ export function formatNoViableMessage(excluded, agentLabel) {
         : perDevice;
     return `${head} ${reasons}.${hint}`;
 }
-/** True when `device` names the local machine (case-insensitive). */
 function isLocalDevice(device) {
     return device.toLowerCase() === machineId();
 }
-/** Count RUNNING teammates per pool device. Pure. A null/empty hostName is a
- * LOCAL teammate — it counts against the pool member that is this machine,
- * otherwise a cap on the local device could never engage. */
 function loadByDevice(devices, roster) {
     const load = new Map();
     for (const d of devices)
@@ -104,17 +50,12 @@ function loadByDevice(devices, roster) {
             continue;
         const host = r.hostName ? r.hostName : devices.find((d) => isLocalDevice(d));
         if (!host)
-            continue; // local teammate but this machine is not in the pool
+            continue;
         if (load.has(host))
             load.set(host, (load.get(host) ?? 0) + 1);
     }
     return load;
 }
-/**
- * Pool devices excluded from auto-pick because they are at (or over) their
- * `agents.max-concurrent` cap. Returned with the live counts so the caller can
- * state the reason to the user instead of the device silently never winning.
- */
 export function cappedDevices(devices, roster, maxConcurrent) {
     const load = loadByDevice(devices, roster);
     const capped = [];
@@ -128,16 +69,6 @@ export function cappedDevices(devices, roster, maxConcurrent) {
     }
     return capped;
 }
-/**
- * Pick the least-loaded device from the pool — the one with the fewest RUNNING
- * teammates currently assigned to it. Ties break by pool order (first wins), so
- * an empty pool fills round-robin-ish as teammates launch. Pure: counts the
- * roster, no I/O.
- *
- * With `maxConcurrent`, devices at their cap are excluded; if EVERY device is
- * capped this throws naming each cap and the fix — a loud failure beats a
- * teammate silently landing on a machine its operator capped.
- */
 export function pickLeastLoaded(devices, roster, maxConcurrent) {
     if (devices.length === 0) {
         throw new Error('pickLeastLoaded called with an empty device pool');
@@ -152,7 +83,6 @@ export function pickLeastLoaded(devices, roster, maxConcurrent) {
             detail: `${load.get(device) ?? 0}/${maxConcurrent[device]}`,
         })));
     }
-    // Iterate the pool in declared order so the first device wins ties.
     let best = eligible[0];
     let bestLoad = load.get(best) ?? 0;
     for (const d of eligible) {
@@ -164,32 +94,20 @@ export function pickLeastLoaded(devices, roster, maxConcurrent) {
     }
     return best;
 }
-/** Load cost for a signal: worst of load% and mem%, or undefined when neither
- * was probed. The "how full is this box" number the finer rank tiebreak reads. */
 function loadCost(s) {
     if (!s)
         return undefined;
     const vals = [s.loadPercent, s.memPercent].filter((v) => typeof v === 'number');
     return vals.length ? Math.max(...vals) : undefined;
 }
-/** Rank a headroom bucket into a load TIER (lower is less loaded). An unprobed
- * device sits between `light` and `busy` — preferred over a known-busy box but
- * not over a known-idle one. `loaded` is excluded before ranking, so it never
- * reaches here. */
 function headroomTier(h) {
     switch (h) {
         case 'idle': return 0;
         case 'light': return 1;
         case 'busy': return 3;
-        default: return 2; // 'unknown' / undefined
+        default: return 2;
     }
 }
-/**
- * Split the pool into the viable set and the excluded set (with reasons), from
- * the caps + live signals. Pure — the caller decides what to do with an empty
- * viable set. Reasons are checked in a stable order (unreachable → not-installed
- * → overloaded → capped) so a device reports its most fundamental blocker first.
- */
 export function classifyExclusions(devices, roster, opts) {
     const load = loadByDevice(devices, roster);
     const caps = opts?.maxConcurrent ?? {};
@@ -199,9 +117,6 @@ export function classifyExclusions(devices, roster, opts) {
     for (const d of devices) {
         const s = signals?.get(d);
         if (s?.reachable === false) {
-            // A probe killed for exceeding its budget is a slow link, not a box that
-            // is down. Same exclusion either way — an unresponsive device is still not
-            // placeable — but the operator sees which one it was (PHNX-3682).
             excluded.push({ device: d, reason: s.timedOut ? 'probe-timed-out' : 'unreachable' });
             continue;
         }
@@ -222,14 +137,6 @@ export function classifyExclusions(devices, roster, opts) {
     }
     return { eligible, excluded };
 }
-/**
- * Health-, harness-, and load-aware pick over a pool (RUSH-2002). Filters
- * unreachable / overloaded / capped / not-installed devices, then ranks the
- * survivors by: (a) agent signed in, (b) lower load (headroom tier, then raw
- * load cost), (c) fewer running teammates, ties broken by pool order. Throws
- * {@link NoViableDeviceError} when nothing survives — never returns a local
- * fallback. Pure: all I/O is pre-resolved into `opts.signals`.
- */
 export function pickBestDevice(devices, roster, opts) {
     if (devices.length === 0) {
         throw new Error('pickBestDevice called with an empty device pool');
@@ -237,13 +144,6 @@ export function pickBestDevice(devices, roster, opts) {
     const load = loadByDevice(devices, roster);
     const { eligible, excluded } = classifyExclusions(devices, roster, opts);
     if (eligible.length === 0) {
-        // A pool excluded ONLY for unreachability is a probe MISS / transient infra
-        // blip (a worker went briefly unresponsive during `teams start`), not proof
-        // the agent can't RUN there. Per the fail-loud contract — fire only on
-        // positive evidence (not-installed / saturated), never on a bare
-        // reachability miss — degrade to a best-effort roster-count pick so the wave
-        // retries and the real error surfaces at SSH dispatch, instead of a hard
-        // exit-1 that strands an all-remote pool on a transient blip.
         const onlyUnreachable = excluded.every((e) => e.reason === 'unreachable');
         if (!onlyUnreachable) {
             throw new NoViableDeviceError(excluded, opts?.agentLabel);
@@ -261,66 +161,43 @@ export function pickBestDevice(devices, roster, opts) {
     }
     const signals = opts?.signals;
     const order = new Map(devices.map((d, i) => [d, i]));
-    // Ascending composite sort — the first element is the best placement.
     return [...eligible].sort((a, b) => {
         const sa = signals?.get(a);
         const sb = signals?.get(b);
-        // (a) signed-in agent first.
         const signedIn = (sa?.signedIn === true ? 0 : 1) - (sb?.signedIn === true ? 0 : 1);
         if (signedIn !== 0)
             return signedIn;
-        // (a2) operator-preferred device next — `agents devices config <name> auto-launch.preferred on`
-        // boosts a box above its load-equal peers, overriding load-based order.
         const preferred = opts?.preferred;
         if (preferred && preferred.size > 0) {
             const pref = (preferred.has(a) ? 0 : 1) - (preferred.has(b) ? 0 : 1);
             if (pref !== 0)
                 return pref;
         }
-        // (b) lower load — coarse headroom tier, then raw load cost.
         const tier = headroomTier(sa?.headroom) - headroomTier(sb?.headroom);
         if (tier !== 0)
             return tier;
-        // (c) fewer running teammates.
         const teammates = (load.get(a) ?? 0) - (load.get(b) ?? 0);
         if (teammates !== 0)
             return teammates;
-        // finer load tiebreak: a known-lower load wins; unknown sits mid (50).
         const cost = (loadCost(sa) ?? 50) - (loadCost(sb) ?? 50);
         if (cost !== 0)
             return cost;
-        // stable: first declared in the pool wins.
         return (order.get(a) ?? 0) - (order.get(b) ?? 0);
     })[0];
 }
-/**
- * Resolve where a teammate runs. Returns `{ device: null }` only when the
- * explicitly/default-selected device is the local machine, and
- * `{ device: <name> }` for a remote placement. See the cascade in the module
- * header. Throws {@link NoViableDeviceError} when a required pool has no viable
- * host — the caller surfaces it at `teams start` rather than falling back local.
- */
 export function resolvePlacement(team, explicitDevice, roster, opts) {
-    // 1. Explicit pin wins — even without a pool — and is never second-guessed
-    //    (the remote `agents run` surfaces any install/health issue there).
     if (explicitDevice) {
         return { device: isLocalDevice(explicitDevice) ? null : explicitDevice };
     }
     const pool = team.devices?.length ? team.devices : (opts?.defaultDevices ?? []);
-    // An omitted pool means automatic worker placement, never implicit local.
     if (pool.length === 0)
         throw new NoViableDeviceError([], opts?.agentLabel);
-    // 2. Pool of one → the whole team runs there. Respect the choice for
-    //    load/cap/reachability, but still fail loud when the agent is provably
-    //    NOT installed there — running it would be futile.
     if (pool.length === 1) {
         if (opts?.signals?.get(pool[0])?.installed === false) {
             throw new NoViableDeviceError([{ device: pool[0], reason: 'not-installed' }], opts.agentLabel);
         }
         return { device: isLocalDevice(pool[0]) ? null : pool[0] };
     }
-    // 3. Many → best viable pick. With live signals, this is health-, harness-,
-    //    and load-aware; without them it degrades to the cap-aware roster count.
     const picked = opts?.signals
         ? pickBestDevice(pool, roster, opts)
         : pickLeastLoaded(pool, roster, opts?.maxConcurrent);

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

@@ -1,17 +1,7 @@
-/** Event type priority tiers for filtering. Higher tiers surface more important events. */
 export declare const PRIORITY: Record<string, string[]>;
-/**
- * Collapse sequential events of the same type into summary entries.
- * Returns a cleaner list of events suitable for output.
- */
 export declare function collapseEvents(events: any[], maxEvents?: number): any[];
-/**
- * Get a breakdown of tool calls by type.
- */
 export declare function getToolBreakdown(events: any[]): Record<string, number>;
-/** Group consecutive events of the same type into combined entries with counts and truncated content. */
 export declare function groupAndFlattenEvents(events: any[]): any[];
-/** Accumulated summary of an agent's activity: files touched, tools used, errors, and final message. */
 export declare class AgentSummary {
     agentId: string;
     agentType: string;
@@ -34,18 +24,10 @@ export declare class AgentSummary {
     toDict(detailLevel?: 'brief' | 'standard' | 'detailed'): any;
     private truncate;
 }
-/** Build an AgentSummary by walking all events and accumulating file ops, tool calls, errors, and messages. */
 export declare function summarizeEvents(agentId: string, agentType: string, status: string, events: any[], duration?: string | null): AgentSummary;
-/**
- * Compute the delta of new activity since a given point in time (ISO timestamp)
- * or event index. Used for incremental status polling.
- */
 export declare function getDelta(agentId: string, agentType: string, status: string, events: any[], since?: string | number): any;
-/** Filter events to only those in the specified priority tiers (defaults to critical + important). */
 export declare function filterEventsByPriority(events: any[], includeLevels?: string[] | null): any[];
-/** Return the event type of the last tool-related or significant event, or null. */
 export declare function getLastTool(events: any[]): string | null;
-/** Lightweight status snapshot with counts, recent commands, and error flag. */
 export interface QuickStatus {
     agent_id: string;
     agent_type: string;
@@ -59,14 +41,10 @@ export interface QuickStatus {
     has_errors: boolean;
     last_message: string | null;
 }
-/** Extract all tool_use events as {tool, args} pairs. */
 export declare function getToolUses(events: any[]): Array<{
     tool: string;
     args: any;
 }>;
-/** Extract the last N complete messages from the event stream, joining streaming deltas. */
 export declare function getLastMessages(events: any[], count?: number): string[];
-/** Build a lightweight QuickStatus snapshot from agent events. */
 export declare function getQuickStatus(agentId: string, agentType: string, status: string, events: any[]): QuickStatus;
-/** Produce a one-line human-readable status summary string (e.g. "Running, modified 3 files, used bash 5 times"). */
 export declare function getStatusSummary(agentId: string, agentType: string, status: string, events: any[], duration?: string | null): string;

package/dist/lib/teams/summarizer.js

@@ -19,7 +19,6 @@ function extractErrorFromRawEvents(events, maxChars = 500) {
     }
     return null;
 }
-/** Event type priority tiers for filtering. Higher tiers surface more important events. */
 export const PRIORITY = {
     critical: [
         'error',
@@ -44,10 +43,6 @@ export const PRIORITY = {
         'raw',
     ],
 };
-/**
- * Collapse sequential events of the same type into summary entries.
- * Returns a cleaner list of events suitable for output.
- */
 export function collapseEvents(events, maxEvents = 20) {
     if (events.length === 0)
         return [];
@@ -56,7 +51,6 @@ export function collapseEvents(events, maxEvents = 20) {
     while (i < events.length) {
         const event = events[i];
         const eventType = event.type || 'unknown';
-        // For thinking events, collapse sequential ones
         if (eventType === 'thinking') {
             let count = 1;
             let lastContent = event.content || '';
@@ -82,7 +76,6 @@ export function collapseEvents(events, maxEvents = 20) {
             i = j;
             continue;
         }
-        // For message events, keep the last content
         if (eventType === 'message') {
             collapsed.push({
                 type: 'message',
@@ -93,7 +86,6 @@ export function collapseEvents(events, maxEvents = 20) {
             i++;
             continue;
         }
-        // Keep tool events as-is but truncate large content
         if (['bash', 'file_write', 'file_read', 'file_create', 'file_delete', 'tool_use'].includes(eventType)) {
             const cleaned = { ...event };
             if (cleaned.command && cleaned.command.length > 200) {
@@ -103,24 +95,18 @@ export function collapseEvents(events, maxEvents = 20) {
             i++;
             continue;
         }
-        // Keep errors and results
         if (['error', 'result'].includes(eventType)) {
             collapsed.push(event);
             i++;
             continue;
         }
-        // Skip other event types
         i++;
     }
-    // Return only the last N events
     if (collapsed.length > maxEvents) {
         return collapsed.slice(-maxEvents);
     }
     return collapsed;
 }
-/**
- * Get a breakdown of tool calls by type.
- */
 export function getToolBreakdown(events) {
     const breakdown = {};
     for (const event of events) {
@@ -147,7 +133,6 @@ export function getToolBreakdown(events) {
     }
     return breakdown;
 }
-/** Group consecutive events of the same type into combined entries with counts and truncated content. */
 export function groupAndFlattenEvents(events) {
     if (events.length === 0)
         return [];
@@ -159,9 +144,6 @@ export function groupAndFlattenEvents(events) {
         if (eventType === 'message' || eventType === 'thinking') {
             let count = 1;
             let combinedContent = event.content || '';
-            // Streaming token events (complete:false) get concatenated without a
-            // separator so tokens reassemble into readable prose. Whole-turn events
-            // get joined with newlines so distinct turns/thoughts stay separated.
             const isStreaming = event.complete === false;
             let j = i + 1;
             while (j < events.length && events[j].type === eventType) {
@@ -263,7 +245,6 @@ export function groupAndFlattenEvents(events) {
     }
     return grouped;
 }
-/** Accumulated summary of an agent's activity: files touched, tools used, errors, and final message. */
 export class AgentSummary {
     agentId;
     agentType;
@@ -345,7 +326,6 @@ export class AgentSummary {
         return text.substring(0, maxLen - 3) + '...';
     }
 }
-/** Build an AgentSummary by walking all events and accumulating file ops, tool calls, errors, and messages. */
 export function summarizeEvents(agentId, agentType, status, events, duration = null) {
     const summary = new AgentSummary(agentId, agentType, status, duration, events.length);
     summary.eventsCache = events;
@@ -412,10 +392,6 @@ export function summarizeEvents(agentId, agentType, status, events, duration = n
         else if (eventType === 'message') {
             const content = event.content || '';
             if (content) {
-                // Streaming token-by-token messages (e.g., grok) arrive as many small
-                // `message` events with complete:false; concatenate them so the final
-                // turn reads as one message. Whole-turn messages (claude, codex,
-                // gemini) keep their complete:true semantics — last one wins.
                 if (event.complete === false) {
                     summary.finalMessage = (summary.finalMessage || '') + content;
                 }
@@ -487,26 +463,17 @@ export function summarizeEvents(agentId, agentType, status, events, duration = n
     }
     return summary;
 }
-/**
- * Compute the delta of new activity since a given point in time (ISO timestamp)
- * or event index. Used for incremental status polling.
- */
-export function getDelta(agentId, agentType, status, events, since // Optional: ISO timestamp (string) or event index (number)
-) {
-    // Filter events by timestamp (string) or index (number)
+export function getDelta(agentId, agentType, status, events, since) {
     let newEvents;
     let sinceEvent = 0;
     if (since === undefined || since === null) {
-        // No filter - return all events
         newEvents = events;
     }
     else if (typeof since === 'number') {
-        // Backward compatibility: event index
         sinceEvent = since;
         newEvents = events.slice(sinceEvent);
     }
     else if (typeof since === 'string') {
-        // New behavior: timestamp filtering
         const sinceDate = new Date(since);
         newEvents = events.filter((e) => {
             if (!e.timestamp)
@@ -522,7 +489,7 @@ export function getDelta(agentId, agentType, status, events, since // Optional:
         return {
             agent_id: agentId,
             status: status,
-            since_event: sinceEvent, // For backward compatibility
+            since_event: sinceEvent,
             new_events_count: 0,
             has_changes: false,
             new_files_created: [],
@@ -540,9 +507,9 @@ export function getDelta(agentId, agentType, status, events, since // Optional:
         agent_id: agentId,
         agent_type: agentType,
         status: status,
-        since_event: sinceEvent, // For backward compatibility
+        since_event: sinceEvent,
         new_events_count: newEvents.length,
-        current_event_count: sinceEvent + newEvents.length, // For backward compatibility
+        current_event_count: sinceEvent + newEvents.length,
         has_changes: true,
         new_files_created: Array.from(summary.filesCreated),
         new_files_modified: Array.from(summary.filesModified),
@@ -551,15 +518,14 @@ export function getDelta(agentId, agentType, status, events, since // Optional:
         new_bash_commands: summary.bashCommands.slice(-15),
         new_messages: getLastMessages(newEvents, 5),
         new_tool_count: summary.toolCallCount,
-        new_tool_calls: newEvents // For backward compatibility
+        new_tool_calls: newEvents
             .filter((e) => ['tool_use', 'bash', 'file_write'].includes(e.type))
             .slice(-5)
             .map((e) => `${e.tool || 'unknown'}: ${e.command || e.path || ''}`),
-        latest_message: summary.finalMessage, // For backward compatibility
+        latest_message: summary.finalMessage,
         new_errors: summary.errors,
     };
 }
-/** Filter events to only those in the specified priority tiers (defaults to critical + important). */
 export function filterEventsByPriority(events, includeLevels = null) {
     if (!includeLevels) {
         includeLevels = ['critical', 'important'];
@@ -573,7 +539,6 @@ export function filterEventsByPriority(events, includeLevels = null) {
     }
     return events.filter(e => allowedTypes.has(e.type));
 }
-/** Return the event type of the last tool-related or significant event, or null. */
 export function getLastTool(events) {
     if (events.length === 0)
         return null;
@@ -585,7 +550,6 @@ export function getLastTool(events) {
     }
     return null;
 }
-/** Extract all tool_use events as {tool, args} pairs. */
 export function getToolUses(events) {
     const toolUses = [];
     for (const event of events) {
@@ -597,7 +561,6 @@ export function getToolUses(events) {
     }
     return toolUses;
 }
-/** Extract the last N complete messages from the event stream, joining streaming deltas. */
 export function getLastMessages(events, count = 3) {
     const messages = [];
     let currentBuffer = '';
@@ -605,11 +568,8 @@ export function getLastMessages(events, count = 3) {
     for (const event of events) {
         if (event.type === 'message') {
             const content = event.content || '';
-            // For streaming events (delta=true), content fragments should be joined.
-            // We don't add newlines because these are likely parts of the same sentence/block.
             currentBuffer += content;
             isCollecting = true;
-            // If we hit an explicitly complete message, treat it as a boundary
             if (event.complete) {
                 if (currentBuffer.trim()) {
                     messages.push(currentBuffer);
@@ -619,7 +579,6 @@ export function getLastMessages(events, count = 3) {
             }
         }
         else {
-            // Any non-message event breaks the message stream
             if (isCollecting) {
                 if (currentBuffer.trim()) {
                     messages.push(currentBuffer);
@@ -629,13 +588,11 @@ export function getLastMessages(events, count = 3) {
             }
         }
     }
-    // Handle any remaining buffer at the end
     if (isCollecting && currentBuffer.trim()) {
         messages.push(currentBuffer);
     }
     return messages.slice(-count);
 }
-/** Build a lightweight QuickStatus snapshot from agent events. */
 export function getQuickStatus(agentId, agentType, status, events) {
     const filesCreatedSet = new Set();
     const filesModifiedSet = new Set();
@@ -722,7 +679,6 @@ export function getQuickStatus(agentId, agentType, status, events) {
         last_message: lastMessage,
     };
 }
-/** Produce a one-line human-readable status summary string (e.g. "Running, modified 3 files, used bash 5 times"). */
 export function getStatusSummary(agentId, agentType, status, events, duration = null) {
     if (events.length === 0) {
         if (status === 'running') {

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

@@ -1,22 +1,3 @@
-/**
- * DAG supervisor — the continuous dispatch loop that makes the Factory
- * dynamic.
- *
- * `teams start --watch` and `factory run` both use this. Each wave:
- *   1. call startReady(team) to fire any now-ready teammates
- *   2. listByTask(team) to count pending / running / done / failed
- *   3. emit one status event (via the caller's callback)
- *   4. exit when pending + running == 0 (DAG drained)
- *
- * Why a shared function:
- *  - the loop is the orchestration, the thing that lets any worker add
- *    tasks mid-flight via `agents teams add` and have them picked up
- *  - `factory run` is just `teams start --watch` with factory-flavored
- *    presentation; keeping them in sync avoids drift
- *
- * The caller supplies a presenter callback so the same loop can drive
- * terminal output, json-per-wave output, or a TUI.
- */
 import type { AgentManager, AgentProcess } from './agents.js';
 import type { TeamBudgetWatcher } from '../budget/live-team.js';
 import type { BreachInfo } from '../budget/enforce.js';
@@ -35,35 +16,16 @@ interface SupervisorOptions {
     team: string;
     intervalMs?: number;
     maxWaves?: number;
-    /** Called once per wave. Return false to stop the loop gracefully. */
     onWave: (summary: WaveSummary) => void | Promise<void> | boolean | Promise<boolean>;
-    /**
-     * Optional live-spend watcher (issue #399). Polled once per wave; on first
-     * breach the supervisor calls `manager.stopByTask(team)` and exits with
-     * `stoppedBy: 'budget'`. Dormant when null — supervisor behavior is unchanged
-     * for teams that never opt into budget enforcement.
-     */
     budgetWatcher?: TeamBudgetWatcher | null;
-    /** Called with the breach details when the budget watcher trips. */
     onBudgetBreach?: (breach: BreachInfo) => void;
 }
 interface SupervisorResult {
     waves: number;
     stoppedBy: 'drained' | 'max-waves' | 'signal' | 'callback' | 'budget';
     elapsed_ms: number;
-    /**
-     * Number of teammates in the `failed` state when the team drained. Only set
-     * for `stoppedBy === 'drained'`. A drained DAG means nothing is pending or
-     * running — NOT that everything succeeded — so callers that treat "drained"
-     * as success (e.g. a completion nudge) must check `failed === 0` first.
-     */
     failed?: number;
-    /** Set when `stoppedBy === 'budget'` — the breach that terminated the team. */
     budgetBreach?: BreachInfo;
 }
-/**
- * Run the continuous DAG dispatcher until the team drains, the caller
- * returns false from onWave, or SIGINT/SIGTERM arrives.
- */
 export declare function runSupervisor(mgr: AgentManager, opts: SupervisorOptions): Promise<SupervisorResult>;
 export {};

package/dist/lib/teams/supervisor.js

@@ -1,7 +1,3 @@
-/**
- * Run the continuous DAG dispatcher until the team drains, the caller
- * returns false from onWave, or SIGINT/SIGTERM arrives.
- */
 export async function runSupervisor(mgr, opts) {
     const intervalMs = opts.intervalMs ?? 8000;
     const maxWaves = opts.maxWaves ?? 1000;
@@ -13,16 +9,7 @@ export async function runSupervisor(mgr, opts) {
     process.once('SIGTERM', onSig);
     try {
         for (let wave = 1; wave <= maxWaves; wave++) {
-            // Pick up teammates added by other processes (e.g. the Planner's
-            // `agents teams add` calls). Without this the supervisor only ever
-            // sees teammates it created itself.
             await mgr.rescanFromDisk();
-            // Distributed teammates: one ssh-per-host liveness/exit pre-pass BEFORE any
-            // polling this wave, so every subsequent per-teammate status read
-            // (startReady's roster scan + listByTask below) consumes a cached snapshot
-            // instead of each opening its own SSH handshake — no N-round-trips-per-wave
-            // blowup at 10+ remote teammates. No-op for all-local teams. Reads the
-            // in-memory roster directly, so it doesn't itself trigger a poll.
             await mgr.prefetchRemoteStatus(team);
             const launched = await mgr.startReady(team);
             const all = await mgr.listByTask(team);
@@ -52,9 +39,6 @@ export async function runSupervisor(mgr, opts) {
             if (keepGoing === false) {
                 return { waves: wave, stoppedBy: 'callback', elapsed_ms: Date.now() - startedAt };
             }
-            // Live budget kill (issue #399). Poll AFTER the wave's callback so the
-            // most recent teammate stdout is already flushed to disk. On breach we
-            // stop every RUNNING teammate — the DAG effectively drains this wave.
             if (opts.budgetWatcher) {
                 await opts.budgetWatcher.poll();
                 if (opts.budgetWatcher.breached()) {
@@ -71,11 +55,6 @@ export async function runSupervisor(mgr, opts) {
                     };
                 }
             }
-            // Re-check drain AFTER the callback. The callback may have added new
-            // teammates mid-flight (that's the whole point of the dynamic DAG), so
-            // trusting the pre-callback snapshot would drain prematurely. Rescan
-            // too, because the callback could have triggered a sibling process
-            // that wrote a fresh meta.json.
             await mgr.rescanFromDisk();
             const afterCallback = await mgr.listByTask(team);
             const stillLive = afterCallback.some((a) => a.status === 'pending' || a.status === 'running');