@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/teams/forEach.js

@@ -1,39 +1,12 @@
-/**
- * Runtime wiring for declarative dynamic fan-out (issue #343).
- *
- * The declarative shape (`for_each:` in WORKFLOW.md / routine `run:` blocks) is
- * parsed and expanded by `src/lib/workflows.ts` (`parseForEachBlock`,
- * `expandForEach`). This module is the thin bridge that stages the expanded
- * teammate descriptors into the EXISTING teams substrate — one
- * `AgentManager.spawn` per descriptor, which the DAG supervisor then picks up
- * mid-flight via `rescanFromDisk` / `startReady`
- * (`src/lib/teams/supervisor.ts:98-103`).
- *
- * It deliberately adds NO new orchestration engine: `spawn` with an `--after`
- * chain is the whole mechanism, so cycle detection, wave scheduling, and
- * cross-vendor/rotation dispatch all carry over unchanged.
- */
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { posixShellPath } from '../platform/exec.js';
 import { expandForEach } from '../workflows.js';
 const execFileAsync = promisify(execFile);
-/**
- * Parse a producer's stdout into the item list `expandForEach` fans out over.
- *
- * Two shapes are accepted (issue #343), tried in order:
- *   1. A JSON array — `["a","b","c"]` (each element coerced to a trimmed string).
- *   2. Newline-delimited — one item per line.
- *
- * Empty lines / entries are dropped so a trailing newline or a `[]` never
- * fabricates a phantom teammate. Pure and deterministic — no I/O.
- */
 export function parseProducedItems(stdout) {
     const trimmed = stdout.trim();
     if (trimmed === '')
         return [];
-    // JSON array form first — only when it actually looks like one, so a plain
-    // line that happens to start with '[' doesn't get swallowed by a parse error.
     if (trimmed.startsWith('[')) {
         try {
             const parsed = JSON.parse(trimmed);
@@ -45,25 +18,13 @@ export function parseProducedItems(stdout) {
             }
         }
         catch {
-            // Not valid JSON — fall through to newline parsing.
         }
     }
-    // Newline-delimited form.
     return trimmed
         .split(/\r?\n/)
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
-/**
- * Resolve a `for_each` spec's item list at runtime (issue #343): either by
- * running its `produce:` shell command and parsing stdout, or by resolving an
- * `itemsRef` to a prior step's list. The resulting items feed `expandForEach` /
- * `runForEach`.
- *
- * `itemsRef` wins when a resolver is supplied and returns a list; otherwise the
- * `produce` command runs. A spec with neither a resolvable ref nor a produce
- * command is a hard error — there is nothing to fan out over.
- */
 export async function produceItems(spec, opts = {}) {
     if (spec.itemsRef && opts.resolveItemsRef) {
         const resolved = opts.resolveItemsRef(spec.itemsRef);
@@ -76,11 +37,6 @@ export async function produceItems(spec, opts = {}) {
         }
         throw new Error('for_each has neither a produce command nor a resolvable itemsRef');
     }
-    // The producer is a shell command string (e.g. "rg -l 'x' src/"), so it runs
-    // under `sh -c` exactly like a teammate command — resolved portably, because
-    // /bin/sh does not exist on Windows (there it's Git's sh.exe from PATH).
-    // maxBuffer is raised well above the default 1MB so a producer emitting a
-    // large list isn't truncated silently mid-stream.
     const { stdout } = await execFileAsync(posixShellPath(), ['-c', spec.produce], {
         cwd: opts.cwd ?? undefined,
         env: opts.env ?? process.env,
@@ -90,17 +46,6 @@ export async function produceItems(spec, opts = {}) {
     });
     return parseProducedItems(stdout);
 }
-/**
- * Evaluate a verify panel's `keep_if` gate against its boolean votes (issue
- * #343). A `true` vote is a skeptic confirming the finding should be kept.
- *
- *   - `all`      — every skeptic must vote keep.
- *   - `any`      — at least one skeptic votes keep.
- *   - `majority` — strictly more than half vote keep (a tie does NOT pass).
- *
- * An empty panel returns false: with no votes there is nothing affirming the
- * item, so the conservative gate drops it.
- */
 export function evaluateKeepIf(votes, keepIf) {
     const total = votes.length;
     if (total === 0)
@@ -115,15 +60,6 @@ export function evaluateKeepIf(votes, keepIf) {
             return yes * 2 > total;
     }
 }
-/**
- * Tally the verify panels of an expanded `for_each` and gate each item (issue
- * #343). Groups verify teammates by the stage teammate they depend on, reads a
- * boolean vote per verify teammate via `readVote`, and applies `keep_if`.
- *
- * An item with no verify panel is kept unconditionally (there is no gate).
- * Pure and deterministic: `readVote` is the only place runtime state enters, so
- * this is unit-testable with a synthetic vote reader.
- */
 export function tallyForEach(teammates, readVote) {
     const stages = teammates.filter((t) => t.role === 'stage');
     const verifiersByStage = new Map();
@@ -160,14 +96,6 @@ export function tallyForEach(teammates, readVote) {
         };
     });
 }
-/**
- * Expand a `for_each` spec against a producer's output and stage every
- * resulting teammate into the given team via the dynamic-add path.
- *
- * Returns the descriptors and the spawned handles so a caller can drive the
- * supervisor and later gather results (e.g. to evaluate a `verify` panel's
- * `keep_if` gate — that vote-counting lives downstream, not here).
- */
 export async function runForEach(mgr, teamName, spec, items, opts = {}) {
     const { teammates, producedCount, usedCount, truncated } = expandForEach(spec, items, {
         producerName: opts.producerName,
@@ -175,11 +103,7 @@ export async function runForEach(mgr, teamName, spec, items, opts = {}) {
     const effort = opts.effort ?? 'medium';
     const spawned = [];
     for (const t of teammates) {
-        const agent = await mgr.spawn(teamName, t.agentType, t.prompt, opts.cwd ?? null, null, // mode: inherit team default
-        effort, null, // parentSessionId
-        null, // workspaceDir
-        null, // version
-        t.name, t.after);
+        const agent = await mgr.spawn(teamName, t.agentType, t.prompt, opts.cwd ?? null, null, effort, null, null, null, t.name, t.after);
         spawned.push(agent);
     }
     return { teammates, spawned, producedCount, usedCount, truncated };

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

@@ -1,10 +1,4 @@
-/**
- * Public library surface for the teams subsystem.
- *
- * Consumers import from '@phnx-labs/agents-cli/teams'
- * to reuse the same agent lifecycle, parsing, summarization, and persistence
- * layer that powers the `agents teams` CLI.
- */
+/** Public API imported from '@phnx-labs/agents-cli/teams'. */
 export { AgentManager, AgentProcess, AgentStatus, VALID_TASK_TYPES, computePathLCA, checkAllClis, checkCliAvailable, getAgentsDir, resolveMode, type TaskType, type CloudDispatchFn, } from './agents.js';
 export { type AgentType } from './parsers.js';
 export { normalizeEvents, normalizeEvent, parseEvent } from './parsers.js';

package/dist/lib/teams/index.js

@@ -1,10 +1,4 @@
-/**
- * Public library surface for the teams subsystem.
- *
- * Consumers import from '@phnx-labs/agents-cli/teams'
- * to reuse the same agent lifecycle, parsing, summarization, and persistence
- * layer that powers the `agents teams` CLI.
- */
+/** Public API imported from '@phnx-labs/agents-cli/teams'. */
 export { AgentManager, AgentProcess, AgentStatus, VALID_TASK_TYPES, computePathLCA, checkAllClis, checkCliAvailable, getAgentsDir, resolveMode, } from './agents.js';
 export { normalizeEvents, normalizeEvent, parseEvent } from './parsers.js';
 export { handleSpawn, handleStatus, handleStop, handleTasks, } from './api.js';

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

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

package/dist/lib/teams/parsers.js

@@ -1,20 +1,6 @@
-/**
- * Agent event stream parsers.
- *
- * Normalizes the heterogeneous JSON event formats emitted by each agent CLI
- * (Claude, Codex, Cursor, OpenCode, Grok, Antigravity, Kimi) into a unified
- * event schema with consistent types: init, message, tool_use, bash,
- * file_read, file_write, file_create, file_delete, result, error, and others.
- */
 import { extractFileOpsFromBash } from './file_ops.js';
 const claudeToolUseMap = new Map();
 const droidToolUseMap = new Map();
-/**
- * Registry-dispatch table: each teams `AgentType` to its live team-event
- * normalizer. Replaces the per-type name-chain — the harness axis of Move 3.
- * warp (and any unlisted type) is absent, so it falls through to the generic
- * unknown-event shape below, exactly as the old `else` did.
- */
 const TEAM_EVENT_NORMALIZERS = {
     codex: normalizeCodex,
     cursor: normalizeCursor,
@@ -25,7 +11,6 @@ const TEAM_EVENT_NORMALIZERS = {
     kimi: normalizeKimi,
     droid: normalizeDroid,
 };
-/** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export function normalizeEvents(agentType, raw) {
     const normalizer = TEAM_EVENT_NORMALIZERS[agentType];
     if (normalizer) {
@@ -39,7 +24,6 @@ export function normalizeEvents(agentType, raw) {
             timestamp: timestamp,
         }];
 }
-/** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */
 export function normalizeEvent(agentType, raw) {
     const events = normalizeEvents(agentType, raw);
     if (events.length > 0) {
@@ -577,8 +561,6 @@ function normalizeClaude(raw) {
             timestamp: timestamp,
         }];
 }
-// --- OpenCode parsing ---
-// OpenCode outputs JSON events with step_start, tool_use, text, step_finish types
 function normalizeOpencode(raw) {
     if (!raw || typeof raw !== 'object') {
         return [{
@@ -696,23 +678,6 @@ function normalizeOpencode(raw) {
             timestamp: timestamp,
         }];
 }
-// --- Grok parsing ---
-// Grok's streaming-json mode emits one JSON object per token, with three event
-// types:
-//   {"type":"thought","data":"<chunk>"}   — reasoning tokens (many, small)
-//   {"type":"text","data":"<chunk>"}      — visible response tokens (many, small)
-//   {"type":"end","stopReason":"EndTurn","sessionId":"<uuid>","requestId":"<uuid>"}
-//
-// Tool calls are NOT exposed as separate events in this format; they appear
-// inside the `thought` text as XML-like markup. Extracting them reliably would
-// require running a streaming XML/markup parser over concatenated thought
-// chunks, which is out of scope for v1. The teams summary will show grok
-// teammates' bash/file ops as empty — known limitation, fixable later by
-// switching to grok's `agent` subcommand (richer event stream) once stable.
-//
-// Tokens are emitted as `message` events with `complete: false` so the
-// summarizer can concatenate them into a final message; `thinking` events are
-// already collapsed by the summarizer's groupAndFlattenEvents pathway.
 function normalizeGrok(raw) {
     if (!raw || typeof raw !== 'object') {
         return [{
@@ -768,22 +733,6 @@ function normalizeGrok(raw) {
             timestamp: timestamp,
         }];
 }
-// --- Kimi parsing ---
-// Kimi's `--output-format stream-json` emits one JSON object per line with a
-// simple `role`-based schema:
-//   - {"role":"assistant","content":"..."}                          → final message
-//   - {"role":"assistant","tool_calls":[{"function":{"name":"Bash","arguments":"<json>"}}]} → tool use
-//   - {"role":"tool","tool_call_id":"...","content":"..."}            → tool result
-//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → terminal/result
-// Kimi emits NO dedicated result/turn-complete event and NO init event. The
-// `session.resume_hint` meta is its terminal marker: emitted exactly once, as
-// the LAST line, on clean completion (it carries the `kimi -r <id>` resume
-// command). We map it to a success `result` so the team runner resolves status
-// from the stream; the run's exit code remains the safety net for crashes that
-// never reach the hint. Tool arguments are JSON-stringified inside
-// `function.arguments` and must be parsed before extracting paths/commands.
-// Verified against live `kimi` runs (no-tool and tool-using) — see
-// __tests__/testdata/kimi-stream-*.jsonl.
 function normalizeKimi(raw) {
     const timestamp = new Date().toISOString();
     if (!raw || typeof raw !== 'object') {
@@ -795,7 +744,6 @@ function normalizeKimi(raw) {
             }];
     }
     const role = typeof raw.role === 'string' ? raw.role : '';
-    // Assistant message (final answer or tool-call request).
     if (role === 'assistant') {
         const events = [];
         if (typeof raw.content === 'string' && raw.content) {
@@ -825,9 +773,6 @@ function normalizeKimi(raw) {
             }
             const filePath = toolArgs?.path || toolArgs?.file_path || '';
             const command = toolArgs?.command || '';
-            // Map known tools to structured events. If a known tool is missing the
-            // fields we need (e.g. unparseable arguments), fall back to tool_use so
-            // the event is still visible in summaries rather than dropped.
             let normalized = null;
             if (toolName === 'Bash' && command) {
                 const bashEvents = [{
@@ -891,7 +836,6 @@ function normalizeKimi(raw) {
         }
         return events.length > 0 ? events : [];
     }
-    // Tool result (response to an assistant tool_call).
     if (role === 'tool') {
         const content = typeof raw.content === 'string' ? raw.content : '';
         const success = raw.isError !== true && !(content && content.startsWith('Error:'));
@@ -904,14 +848,9 @@ function normalizeKimi(raw) {
                 timestamp: timestamp,
             }];
     }
-    // Meta events (session lifecycle).
     if (role === 'meta') {
         const metaType = typeof raw.type === 'string' ? raw.type : '';
         if (metaType === 'session.resume_hint') {
-            // Kimi's terminal marker (see header). Emit a success `result` so the
-            // team runner's terminal-event detection resolves the teammate to
-            // COMPLETED from the stream. session_id is preserved for cross-
-            // referencing — readNewEvents() captures it off any event.
             return [{
                     type: 'result',
                     agent: 'kimi',
@@ -935,11 +874,6 @@ function normalizeKimi(raw) {
             timestamp: timestamp,
         }];
 }
-// --- Droid parsing ---
-// Droid's `droid exec -o stream-json` stream mirrors the Factory session JSONL
-// envelope: session_start records plus Anthropic-shaped message content blocks.
-// Tool blocks carry the actionable file path / command in `input`; result blocks
-// only carry `tool_use_id`, so keep a small id map just like normalizeClaude.
 function normalizeDroid(raw) {
     const timestamp = typeof raw?.timestamp === 'string' ? raw.timestamp : new Date().toISOString();
     if (!raw || typeof raw !== 'object') {
@@ -1145,20 +1079,6 @@ function extractDroidToolResultContent(content) {
     }
     return '';
 }
-// --- Antigravity parsing ---
-// Intentionally conservative. Antigravity's `agy` binary advertises an
-// `--output-format json` flag in its docs, but the released binary errors with
-// `flags provided but not defined: -output-format` (tracked upstream as
-// google-antigravity/antigravity-cli#7, open as of May 2026). Until JSON
-// streaming stabilizes, this parser treats agy output as a black box:
-//   - non-object input (a plain string line, or null/number) becomes a single
-//     `message` event with the full content and complete:true so the
-//     summarizer captures it without token-level concatenation
-//   - objects with a recognizable `type` field (e.g. `init`, `message`,
-//     `result`) get a minimal shape-preserving normalization
-//   - everything else falls through to the generic unknown-event shape
-// Once agy ships stable streaming JSON, replace this with proper event
-// mapping mirroring normalizeGrok / normalizeClaude.
 function normalizeAntigravity(raw) {
     const timestamp = new Date().toISOString();
     if (typeof raw === 'string') {
@@ -1217,7 +1137,6 @@ function normalizeAntigravity(raw) {
             timestamp: timestamp,
         }];
 }
-/** Parse a single JSONL line into normalized events. Returns null if the line is not valid JSON. */
 export function parseEvent(agentType, line) {
     try {
         const raw = JSON.parse(line);

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

@@ -1,4 +1,2 @@
-/** Resolve the base data directory for teams, preferring ~/.agents/teams/ with a temp fallback. */
 export declare function resolveBaseDir(): Promise<string>;
-/** Resolve and ensure the agents subdirectory exists under the teams base dir. */
 export declare function resolveAgentsDir(): Promise<string>;

package/dist/lib/teams/persistence.js

@@ -1,12 +1,3 @@
-/**
- * Teams data-directory resolution.
- *
- * Resolves the base directory for teammate metadata + the per-team agents
- * dir, with temp-dir fallbacks for unwritable homedirs. The teams subsystem
- * does NOT carry its own agent-registry config — `agents teams` discovers
- * agents through the same machinery as `agents view` (installed versions
- * via `listInstalledVersions`) and invokes them through `agents run`.
- */
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { tmpdir } from 'os';
@@ -24,7 +15,6 @@ async function ensureWritableDir(p) {
         return false;
     }
 }
-/** Resolve the base data directory for teams, preferring ~/.agents/teams/ with a temp fallback. */
 export async function resolveBaseDir() {
     if (await ensureWritableDir(TEAMS_DIR)) {
         return TEAMS_DIR;
@@ -40,7 +30,6 @@ async function resolveAgentsPath() {
     if (await ensureWritableDir(historyAgents)) {
         return historyAgents;
     }
-    // Last-resort temp fallback so dispatch keeps working when ~/.agents is unwritable.
     const tmpAgents = path.join(TMP_FALLBACK_DIR, 'agents');
     if (await ensureWritableDir(tmpAgents)) {
         console.warn(`[agents teams] Falling back to temp agents dir at ${tmpAgents}`);
@@ -49,7 +38,6 @@ async function resolveAgentsPath() {
     throw new Error('Unable to determine a writable agents directory');
 }
 let AGENTS_DIR = null;
-/** Resolve and ensure the agents subdirectory exists under the teams base dir. */
 export async function resolveAgentsDir() {
     if (!AGENTS_DIR) {
         AGENTS_DIR = await resolveAgentsPath();

package/dist/lib/teams/placement-probe.d.ts

@@ -1,20 +1,8 @@
 import { type AgentType } from './agents.js';
 import type { DevicePlacementSignal } from './scheduler.js';
-/** Per-remote readiness probe budget — matches the health probe's short window
- * (`agents view` on a warm box is sub-second; a wedged one degrades to unknown). */
 export declare const READY_PROBE_TIMEOUT_MS = 8000;
-/** How long a probed pool snapshot is reused within a `teams start` wave. Short
- * enough that a device coming online / going overloaded is seen next wave, long
- * enough that placing a wave of teammates does not re-fan-out per teammate. */
 export declare const SIGNAL_TTL_MS = 15000;
-/** Clear the probe cache — for tests and after a device-registry change. */
 export declare function clearPlacementSignalCache(): void;
-/**
- * Probe every device in the team pool and return a name→signal map for the pure
- * placement pick. Devices with no data at all are omitted (the pick then neither
- * excludes nor prefers them). Never throws — a probe failure degrades to a
- * missing/partial signal.
- */
 export declare function probePoolSignals(pool: string[], agent?: AgentType, opts?: {
     force?: boolean;
     now?: number;

package/dist/lib/teams/placement-probe.js

@@ -1,29 +1,3 @@
-/**
- * Live pool probing for the teams placement scheduler (RUSH-2002).
- *
- * Gathers one {@link DevicePlacementSignal} per pool device so the pure pick in
- * {@link ./scheduler} can filter unreachable / overloaded / not-installed
- * devices and rank the rest. Two concerns, both best-effort:
- *
- *   - reachability + headroom + load  ← {@link probeFleetStats} (one parallel
- *     SSH fan-out over the pool; the local box is measured directly).
- *   - requested agent installed + account eligibility (when known) ← a one-shot
- *     readiness probe per remote device ({@link buildReadyProbeCommand} →
- *     `agents view`), with the same candidate-readiness gate evaluated locally.
- *
- * The result is cached briefly per (pool, agent-or-any) so a `teams start` wave that
- * places N teammates probes the pool ONCE, not N times — the roster-count part
- * of the rank stays live (the pure pick recounts the roster each call), only the
- * SSH-measured load/harness snapshot is reused within the TTL.
- *
- * All SSH here is via `spawn` (async, kill-bounded) so the whole pool is probed
- * in parallel; a slow or wedged box degrades to "no signal" instead of blocking
- * the launch. The readiness payload is `agents view --json`, so remote and local
- * candidates carry the same installed/sign-in verdict. The dispatcher's usage
- * envelope rides the same round-trip on stdin (`agents __usage-ingest` runs
- * first in the probe, PHNX-4116), so the worker the pick lands on holds current
- * usage numbers at dispatch rather than at the next usage-sync tick.
- */
 import { spawn } from 'child_process';
 import { buildFleetStatePayload } from '../accounting/usage-sync.js';
 import { probeFleetStats, headroom } from '../devices/health.js';
@@ -34,27 +8,15 @@ import { collectRunCandidates, isSignInRecoverable, readinessFromCandidate, } fr
 import { localMachineId } from '../origin-machine.js';
 import { normalizeHost } from '../machine-id.js';
 import { checkCliAvailable } from './agents.js';
-/** Per-remote readiness probe budget — matches the health probe's short window
- * (`agents view` on a warm box is sub-second; a wedged one degrades to unknown). */
 export const READY_PROBE_TIMEOUT_MS = 8_000;
-/** How long a probed pool snapshot is reused within a `teams start` wave. Short
- * enough that a device coming online / going overloaded is seen next wave, long
- * enough that placing a wave of teammates does not re-fan-out per teammate. */
 export const SIGNAL_TTL_MS = 15_000;
 const cache = new Map();
 function cacheKey(pool, agent) {
     return `${agent ?? 'any-agent'}::${[...pool].map(normalizeHost).sort().join(',')}`;
 }
-/** Clear the probe cache — for tests and after a device-registry change. */
 export function clearPlacementSignalCache() {
     cache.clear();
 }
-/**
- * Whether the requested agent is installed on a REMOTE device, via one SSH
- * readiness probe. `undefined` when the probe could not answer (ssh/login
- * failure) — reachability is then left to {@link probeFleetStats}; `false` when
- * the box answered but agents-cli or the agent is absent (a genuine can't-run).
- */
 function probeRemoteReadiness(device, agent, usagePayload) {
     const unknown = { installed: undefined, signedIn: undefined, pickerEligible: undefined };
     let args;
@@ -62,8 +24,6 @@ function probeRemoteReadiness(device, agent, usagePayload) {
     try {
         const shim = writeAskpassShim();
         const cmd = buildReadyProbeCommand(device.shell === 'powershell' ? 'windows' : undefined, { ingestUsage: true });
-        // agentOnly: a read-only probe must never force a foreground Touch ID sheet
-        // on a password-auth device (mirrors probeDeviceStats in devices/health).
         ({ args, env } = buildSshInvocation(device, [cmd], shim, {}, { agentOnly: true }));
     }
     catch {
@@ -85,8 +45,6 @@ function probeRemoteReadiness(device, agent, usagePayload) {
             clearTimeout(killTimer);
             resolve(value);
         };
-        // A wedged box degrades to "no signal": SIGTERM at the budget, SIGKILL shortly
-        // after, so one dead peer can never hold the whole placement wave open.
         const timer = setTimeout(() => child.kill('SIGTERM'), READY_PROBE_TIMEOUT_MS);
         const killTimer = setTimeout(() => { if (!settled)
             child.kill('SIGKILL'); }, READY_PROBE_TIMEOUT_MS + 250);
@@ -113,12 +71,6 @@ function probeRemoteReadiness(device, agent, usagePayload) {
         child.stdin.end(usagePayload);
     });
 }
-/**
- * Probe every device in the team pool and return a name→signal map for the pure
- * placement pick. Devices with no data at all are omitted (the pick then neither
- * excludes nor prefers them). Never throws — a probe failure degrades to a
- * missing/partial signal.
- */
 export async function probePoolSignals(pool, agent, opts = {}) {
     const now = opts.now ?? Date.now();
     const key = cacheKey(pool, agent);
@@ -139,8 +91,6 @@ export async function probePoolSignals(pool, agent, opts = {}) {
     }
     const selfProfile = profiles.find((d) => normalizeHost(d.name) === self);
     const stats = await probeFleetStats(profiles, { selfName: selfProfile?.name });
-    // Built once per wave: this box's current usage rows (headed only — a worker
-    // dispatcher has none to give), ingested by every remote candidate it probes.
     const usagePayload = JSON.stringify(buildFleetStatePayload({ usageOnly: true }));
     const installed = new Map(agent
         ? await Promise.all(profiles.map(async (d) => {
@@ -169,7 +119,7 @@ export async function probePoolSignals(pool, agent, opts = {}) {
         const s = d ? stats.get(d.name) : undefined;
         const inst = d ? installed.get(d.name) : undefined;
         if (!s && !inst)
-            continue; // fully unknown device — leave it out of the map
+            continue;
         signals.set(name, {
             reachable: s?.reachable,
             timedOut: s?.timedOut,