@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/deployment/deployment-identity.d.ts

@@ -5,27 +5,21 @@ import { type DeploymentIdentity, type ConfigPaths } from '@kici-dev/engine';
  *
  * Two candidates are tried in order:
  *
- *  1. `<npm global bin>/kici-admin`, derived from where this module itself
- *     lives. This is the correct answer when npm's global prefix differs from
- *     the node install prefix — e.g. an operator who set
- *     `npm config set prefix ~/.npm-global` while running a system node.
- *  2. `<dirname(execPath)>/kici-admin`, correct for version-manager layouts
+ *  1. `<npm global bin>/kici-admin`, derived from this module's location: right
+ *     when npm's global prefix differs from node's (e.g.
+ *     `npm config set prefix ~/.npm-global` with a system node).
+ *  2. `<dirname(execPath)>/kici-admin`, right for version-manager layouts
  *     (mise / nvm / fnm) where the two prefixes coincide.
  *
- * Candidate 1 wins a tie because it is the shim belonging to the install this
- * process is actually running from; a stale shim elsewhere on the system must
- * not be pinned in preference to it.
+ * Candidate 1 wins a tie: it belongs to the install this process runs from, and
+ * a stale shim elsewhere must not be pinned over it.
  *
- * Global installs only, matching `resolveNpmInstallTarget`'s scope: an
- * orchestrator installed locally into a project's own `node_modules` keeps its
- * shim in `node_modules/.bin`, which is never a candidate, so it resolves to
- * `undefined` and gets the bare form.
+ * Global installs only, matching `resolveNpmInstallTarget`: a local install
+ * keeps its shim in `node_modules/.bin`, never a candidate, so it gets
+ * `undefined`. The dashboard then falls back to a PATH-resolved bare
+ * `kici-admin`, which beats naming a path that is not there.
  *
- * Returning `undefined` is deliberate: the dashboard falls back to a
- * PATH-resolved bare `kici-admin`, which beats naming a path that is not there.
- *
- * Both halves are rendered as POSIX shell words, so the pair survives a path
- * that holds whitespace when the operator pastes it.
+ * Both halves are rendered as POSIX shell words.
  */
 export declare function resolveAdminInvocation(execPath: string, entryPath: string | undefined, fileExists: (p: string) => boolean): string | undefined;
 /**
@@ -33,31 +27,25 @@ export declare function resolveAdminInvocation(execPath: string, entryPath: stri
  * when it cannot be located.
  *
  * Deliberately NOT built on {@link globalBinDirFrom}: npm lays a Windows global
- * install out as `<prefix>\node_modules\<pkg>` with no `lib` folder, and links
- * the shims directly into `<prefix>` rather than `<prefix>\bin`. The posix
- * helper requires a `lib` segment, so it returns `undefined` for every real
- * Windows install — reusing it would ship a resolver that can never fire.
+ * install out as `<prefix>\node_modules\<pkg>` with no `lib` folder and links
+ * the shims into `<prefix>`, not `<prefix>\bin`, so the posix helper would
+ * return `undefined` for every real Windows install.
  *
  * Three candidate directories are tried in order:
  *
- *  1. The npm global prefix implied by this module's own location, split on the
- *     FIRST `node_modules` segment (matching the posix helper's convention, so
- *     the nested-under-kici-admin install shape resolves too). A prefix holding
- *     a `package.json` is REJECTED: that is a local project install, whose shim
- *     lives in `node_modules\.bin`, and a same-named launcher sitting in the
- *     project root must not be pinned. npm's own global prefix carries no
- *     `package.json`, which is what distinguishes the two.
- *  2. The light-package deploy directory, which lays out
- *     `<deployDir>\lib\<target>.cjs` beside `<deployDir>\kici-admin.cmd`. Gated
- *     on the entry's parent directory actually being named `lib` so an
- *     unrelated bundle layout cannot derive a directory and pin whatever
- *     happens to sit there.
- *  3. `dirname(execPath)`, for the case where node and the launcher are
- *     co-located.
- *
- * Every path is built with `path.win32`, so the derivation is deterministic
- * when this runs on a posix test host rather than depending on the ambient
- * separator.
+ *  1. The npm global prefix implied by this module's location, split on the
+ *     FIRST `node_modules` segment as the posix helper does, so the shape nested
+ *     under kici-admin resolves too. A prefix holding a `package.json` is
+ *     REJECTED: npm's global prefix has none, so it marks a local project
+ *     install, whose shim lives in `node_modules\.bin`; a same-named launcher in
+ *     the project root must not be pinned.
+ *  2. The light-package deploy directory (`<deployDir>\lib\<target>.cjs` beside
+ *     `<deployDir>\kici-admin.cmd`), only when the entry's parent directory is
+ *     named `lib`, so an unrelated bundle layout cannot pin whatever sits there.
+ *  3. `dirname(execPath)`, when node and the launcher are co-located.
+ *
+ * Every path is built with `path.win32`, so the derivation is deterministic on a
+ * posix test host.
  *
  * A candidate directory that is not absolute is skipped. The check has to be on
  * the DIRECTORY, not on the joined result: `path.win32.dirname('C:node.exe')`
@@ -76,19 +64,17 @@ export declare function resolveWindowsAdminPath(execPath: string, entryPath: str
  * Read the orchestrator's deployment shape from the env the installer injects
  * (`KICI_DEPLOY_MODE` / `KICI_DEPLOY_CONTAINER` / `KICI_DEPLOY_CONTAINER_RUNTIME`).
  * Hand-run / dev orchestrators carry no `KICI_DEPLOY_*` env and report `unknown`.
- * Surrounding whitespace is stripped from all three before they are read: the
- * values reach the process through an env file, where a hand edit or a writer
- * that leaves the trailing byte on can attach a space or a newline. The shape
- * is known in that case, so degrading the whole identity to `unknown` — and
- * dropping the pinned invocation with it — would discard an answer we have.
- * Container fields are kept only for the `compose` mode. For posix bare-metal
- * (`systemd` / `launchd`) the identity carries a pinned `<node> <kici-admin>`
- * `adminInvocation` when the shim can be located on disk; for `windows` it
- * instead carries a raw, unquoted `adminPath` naming the `kici-admin.cmd`
- * launcher. Each is omitted when its target cannot be located, so the reader
- * falls back to a PATH-resolved `kici-admin`. The two never coexist: they are
- * different kinds of value (a shell command vs a bare path) because the Windows
- * shells cannot share one quoting.
+ *
+ * All three are trimmed: they arrive through an env file, where a hand edit or a
+ * writer can attach a space or a newline, and the shape is still known —
+ * degrading to `unknown` would drop the pinned invocation too.
+ *
+ * Container fields are kept only for `compose`. Posix bare-metal (`systemd` /
+ * `launchd`) carries a pinned `<node> <kici-admin>` `adminInvocation`; `windows`
+ * carries a raw, unquoted `adminPath` to `kici-admin.cmd`. Each is omitted when
+ * its target cannot be located, so the reader falls back to a PATH-resolved
+ * `kici-admin`. They never coexist: a shell command vs a bare path, because the
+ * Windows shells cannot share one quoting.
  */
 export declare function readDeploymentIdentity(env?: NodeJS.ProcessEnv, execPath?: string, entryPath?: string | undefined, fileExists?: (p: string) => boolean): DeploymentIdentity;
 /**
@@ -102,20 +88,16 @@ export declare function readDeploymentIdentity(env?: NodeJS.ProcessEnv, execPath
  * it in its own config — so every orchestrator reports it, including hand-run
  * ones and installs that predate the stamp.
  *
- * Values are trimmed for the same reason the deployment reader trims them:
- * they arrive through an env file, where a hand edit or a writer that leaves
- * the trailing byte on attaches a space or a newline. A known path carrying a
- * stray space is still a known path, and dropping it would discard an answer
- * we have.
+ * Values are trimmed for the reason `readDeploymentIdentity` gives: a known
+ * path carrying a stray space from an env file is still a known path.
  *
  * No path is checked for existence. On bare metal such a check would pass; in
  * a compose container it would fail for every path, because these are HOST
  * paths the container cannot see — blanking the value for exactly the
  * deployment shape that needs it most.
  *
- * This is a standalone reader rather than a branch of `readDeploymentIdentity`
- * because that function returns early for `compose`, and anything placed after
- * that return does nothing for compose deployments.
+ * Standalone rather than a branch of `readDeploymentIdentity`, which returns
+ * early for `compose`.
  */
 export declare function readConfigPaths(env?: NodeJS.ProcessEnv, scaler?: {
     scalerConfigPath?: string;

package/dist/diagnostics/bundle-reader.d.ts

@@ -1,9 +1,6 @@
 /**
- * Debug bundle reader.
- *
- * Parses a diagnostic ZIP bundle and returns a structured summary
- * for the inspect-bundle CLI command. Works offline -- no network
- * access or running orchestrator needed.
+ * Parses a diagnostic ZIP bundle into a structured summary for the inspect-bundle CLI
+ * command. Works offline -- no network access or running orchestrator needed.
  */
 export interface BundleManifest {
     version: string;
@@ -14,9 +11,7 @@ export interface BundleManifest {
     platform: string;
 }
 export interface BundleSummary {
-    /** Bundle metadata. */
     manifest: BundleManifest;
-    /** Diagnostic check results from the bundle. */
     checkResults: Array<{
         name: string;
         status: 'pass' | 'warn' | 'fail';
@@ -27,22 +22,15 @@ export interface BundleSummary {
     errorCount: number;
     /** Number of checks that warned. */
     warningCount: number;
-    /** System information from the bundle. */
     systemInfo: Record<string, unknown>;
     /** Detected config issues (missing required fields, etc.). */
     configIssues: string[];
-    /** Log file statistics (if logs were included). */
+    /** Present only if logs were included. */
     logSummary?: {
         totalLines: number;
         errors: number;
         warnings: number;
     };
 }
-/**
- * Read and parse a debug bundle ZIP file.
- *
- * @param zipPath - Path to the ZIP file to parse
- * @returns Structured summary of the bundle contents
- */
 export declare function readDebugBundle(zipPath: string): Promise<BundleSummary>;
 //# sourceMappingURL=bundle-reader.d.ts.map

package/dist/diagnostics/bundle-writer.d.ts

@@ -1,29 +1,20 @@
 /**
- * Debug bundle writer.
- *
- * Creates a sanitized ZIP diagnostic bundle containing config (secrets redacted),
- * recent logs, system info, metrics, cluster state, and execution data.
- * This is the primary support tool -- operators run debug-bundle and share
- * the ZIP for troubleshooting.
+ * Debug bundle writer: a sanitized ZIP of config (secrets redacted), recent logs, system info,
+ * metrics, cluster state, and execution data. The primary support tool -- operators run
+ * debug-bundle and share the ZIP for troubleshooting.
  */
 import type { DiagnosticDeps } from './types.js';
 export { redactConfig, addLogsToArchive } from '@kici-dev/shared';
 export interface BundleOptions {
-    /** Where to write the ZIP. */
     outputPath: string;
-    /** Orchestrator instance identifier. */
     orchestratorId: string;
     /** Raw orchestrator config (will be redacted). */
     config: Record<string, unknown>;
-    /** Path to log files directory. */
     logDir?: string;
     /** Hours of logs to include (default: 4). */
     logWindow?: number;
-    /** Dependencies for running diagnostic checks. */
     diagnosticDeps: DiagnosticDeps;
-    /** URL for cluster health endpoint. */
     clusterHealthUrl?: string;
-    /** URL for recent runs endpoint. */
     recentRunsUrl?: string;
 }
 /**
@@ -34,6 +25,8 @@ export interface BundleOptions {
  * - config/config.json: redacted configuration
  * - system/info.json: OS, Node, CPU, memory info
  * - diagnostics/results.json: health check results
+ * - cluster/health.json: cluster health (if clusterHealthUrl provided and reachable)
+ * - executions/recent.json: recent runs (if recentRunsUrl provided and reachable)
  * - logs/: recent log files (if logDir provided)
  * - logs/summary.json: log statistics
  */

package/dist/diagnostics/checks/agents.d.ts

@@ -1,10 +1,4 @@
-/**
- * Agent connectivity diagnostic check.
- *
- * Reads the agent registry count and reports whether any agents
- * are connected. Zero agents is a warning (not failure) since
- * agents may be scaling up.
- */
+/** Agent connectivity check. Zero agents only warns: agents may be scaling up. */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare function checkAgentConnectivity(deps: DiagnosticDeps): Promise<DiagnosticResult>;
 //# sourceMappingURL=agents.d.ts.map

package/dist/diagnostics/checks/backup.d.ts

@@ -1,15 +1,12 @@
 /**
- * Backup-freshness diagnostic check.
+ * Whether the orchestrator DB has a recent `kici-admin db backup`, from the newest
+ * `backup_runs.created_at`: FAIL when none was ever recorded, WARN when older than the
+ * effective staleness threshold, else PASS.
  *
- * Reads the newest `backup_runs.created_at` and reports whether the
- * orchestrator DB has a recent `kici-admin db backup`. FAIL when none was ever
- * recorded, WARN when the newest is older than the effective staleness
- * threshold, else PASS.
- *
- * The threshold is cluster-configurable: the strictest (minimum) non-null
- * `org_settings.backup_staleness_warn_hours` across all orgs, falling back to
- * `config.backupStalenessWarnHours` when no org sets an override. A stale
- * whole-DB backup affects every org, so the tightest org requirement wins.
+ * The threshold is the strictest (minimum) non-null
+ * `org_settings.backup_staleness_warn_hours` across all orgs, else
+ * `config.backupStalenessWarnHours`. A stale whole-DB backup affects every org, so the
+ * tightest org requirement wins.
  */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare const DEFAULT_BACKUP_STALENESS_WARN_HOURS = 24;

package/dist/diagnostics/checks/certs.d.ts

@@ -1,9 +1,4 @@
-/**
- * TLS certificate expiry diagnostic check.
- *
- * Reads a TLS certificate from the configured path and checks
- * the not-after date. Warns if expiring within 30 days, fails if expired.
- */
+/** TLS certificate expiry check: warns within 30 days of not-after, fails once expired. */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare function checkCertificateExpiry(deps: DiagnosticDeps): Promise<DiagnosticResult>;
 //# sourceMappingURL=certs.d.ts.map

package/dist/diagnostics/checks/config.d.ts

@@ -1,9 +1,6 @@
 /**
- * Config validity diagnostic check.
- *
- * Validates the current orchestrator config against key required fields.
- * Uses a lightweight validation (not the full Zod schema) to avoid
- * importing the entire config module.
+ * Config validity check: a lightweight required-field check rather than the
+ * full Zod schema, to avoid importing the entire config module.
  */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare function checkConfigValidity(deps: DiagnosticDeps): Promise<DiagnosticResult>;

package/dist/diagnostics/checks/db.d.ts

@@ -1,7 +1,7 @@
 /**
  * Database connectivity diagnostic check.
  *
- * Runs a simple SELECT 1 query to verify the database is reachable
+ * Reads one row of `dedup_cache` to verify the database is reachable
  * and reports latency.
  */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';

package/dist/diagnostics/checks/disk.d.ts

@@ -1,9 +1,4 @@
-/**
- * Disk space diagnostic check.
- *
- * Uses `df` command to check available disk space on the root partition.
- * Thresholds: warn < 1GB, fail < 100MB.
- */
+/** Disk space check on the root partition via `df`: warn < 1GB, fail < 100MB. */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare function checkDiskSpace(_deps: DiagnosticDeps): Promise<DiagnosticResult>;
 //# sourceMappingURL=disk.d.ts.map

package/dist/diagnostics/checks/firecracker-network.d.ts

@@ -1,7 +1,7 @@
 /**
- * Firecracker host-bridge diagnostic. Emits one row per configured Firecracker
- * scaler backend: the bridge interface + its gateway addr + its nft table must
- * all be present, else the scaler cannot spawn microVMs.
+ * One row per configured Firecracker scaler backend: the bridge interface, its
+ * gateway addr and its nft table must all be present, else the scaler cannot
+ * spawn microVMs.
  */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 import { type BridgeHealth, type FirecrackerBridgeConfig } from '../../firecracker/host-network.js';

package/dist/diagnostics/checks/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * Diagnostic check registry.
- *
- * Exports the array of all diagnostic check functions
- * in the order they should be displayed.
- */
 import type { DiagnosticCheck } from '../types.js';
 import { checkDbConnectivity } from './db.js';
 import { checkBackupFreshness } from './backup.js';

package/dist/diagnostics/checks/retention.d.ts

@@ -2,7 +2,7 @@ import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 import { type RetentionWindows } from '../../queue/retention.js';
 /** Rows past which an unbounded `execution_runs` is worth warning about. */
 export declare const RETENTION_WARN_ROW_THRESHOLD = 500000;
-/** What the verdict needs to know. Gathered by the check, decided here. */
+/** Gathered by the check, decided by `retentionVerdict`. */
 export interface RetentionVerdictInput {
     windows: RetentionWindows;
     coldStoreEnabled: boolean;
@@ -13,11 +13,8 @@ export interface RetentionVerdictInput {
     rowThreshold?: number;
 }
 /**
- * Decide the check's outcome from already-gathered facts.
- *
- * Split from the check so the branches are testable without standing up a
- * database — in particular the WARN branch, which needs a row count larger
- * than any fixture would seed.
+ * Split from the check so branches are testable without a database — notably WARN, which needs
+ * a row count larger than any fixture would seed.
  */
 export declare function retentionVerdict(input: RetentionVerdictInput): Pick<DiagnosticResult, 'status' | 'message' | 'details'>;
 export declare function checkRunHistoryRetention(deps: DiagnosticDeps): Promise<DiagnosticResult>;

package/dist/diagnostics/checks/scaler.d.ts

@@ -1,13 +1,9 @@
 /**
- * Scaler provisioning diagnostic check.
- *
- * Reads recent scaler spawn failures (in-process, over a short rolling window)
- * and emits one row per configured scaler backend instance. Severity is
- * bound-aware: a warm-pool/unbound failure is a warning (no run impact yet); a
- * job-bound failure is a failure (a queued run could not get an agent).
+ * Scaler provisioning check: one row per configured backend from in-process spawn failures
+ * over a rolling window. A warm-pool/unbound failure warns (no run impact yet); a job-bound
+ * failure fails (a queued run could not get an agent).
  */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
-/** Rolling window for "recent" spawn failures. */
 export declare const SCALER_FAILURE_WINDOW_MS: number;
 export declare function checkScalerProvisioning(deps: DiagnosticDeps): Promise<DiagnosticResult[]>;
 //# sourceMappingURL=scaler.d.ts.map

package/dist/diagnostics/checks/ws.d.ts

@@ -1,9 +1,4 @@
-/**
- * Platform WebSocket connectivity diagnostic check.
- *
- * Attempts an HTTP(S) request to the Platform URL health endpoint
- * to verify the relay is reachable.
- */
+/** Platform connectivity check: an HTTP(S) request to the Platform health endpoint. */
 import type { DiagnosticDeps, DiagnosticResult } from '../types.js';
 export declare function checkWsToPlatform(deps: DiagnosticDeps): Promise<DiagnosticResult>;
 //# sourceMappingURL=ws.d.ts.map

package/dist/diagnostics/fleet-collector.d.ts

@@ -1,12 +1,9 @@
 /**
- * Recursive fleet subtree assembler.
- *
- * Every orchestrator runs this to produce a self-similar subtree ZIP:
- * local/ + nested agents/<id>.zip + workers/<id>.zip + peers/<id>.zip, plus
- * fleet-manifest.json recording per-node status. Dead branches are recorded,
- * never fatal (Promise.allSettled at each level). The loop guard
- * (includeCoordinatorMesh) is true only on the root call; every downstream peer
- * request sets it false so the coordinator mesh never echoes.
+ * Recursive fleet subtree assembler. Every orchestrator produces a self-similar ZIP: local/,
+ * nested agents/<id>.zip, workers/<id>.zip and peers/<id>.zip, plus fleet-manifest.json with
+ * per-node status. Dead branches are recorded, never fatal (Promise.allSettled per level).
+ * The loop guard (includeCoordinatorMesh) is true only on the root call, so the coordinator
+ * mesh never echoes.
  */
 import { z } from 'zod';
 /** Per-node collection outcome recorded in the fleet manifest. */
@@ -18,23 +15,23 @@ export declare const FleetNodeStatus: z.ZodEnum<{
 }>;
 export type FleetNodeStatus = z.infer<typeof FleetNodeStatus>;
 export interface FleetCollectorDeps {
-    /** This orchestrator's instanceId (the manifest owner). */
+    /** The manifest owner. */
     instanceId: string;
-    /** Build this node's own debug bundle as a Buffer (createDebugBundle output). */
+    /** createDebugBundle output. */
     buildLocalBundle: () => Promise<Buffer>;
-    /** List this node's directly-connected agents. */
+    /** Directly-connected agents only. */
     listAgents: () => {
         agentId: string;
     }[];
-    /** Request a connected agent's mini-bundle over the agent WS channel. */
+    /** Over the agent WS channel. */
     requestAgentBundle: (agentId: string) => Promise<Buffer>;
-    /** List this node's downstream peers (coordinator-mesh peers + its workers). */
+    /** Coordinator-mesh peers plus this node's workers. */
     listPeers: () => {
         instanceId: string;
         role: 'coordinator' | 'worker';
         kind: 'peer' | 'worker';
     }[];
-    /** Request a peer's subtree bundle over the peer WS channel (loop-guarded false). */
+    /** Over the peer WS channel; callers pass includeCoordinatorMesh=false. */
     requestPeerSubtree: (instanceId: string, includeCoordinatorMesh: boolean) => Promise<Buffer>;
 }
 export interface FleetCollectOptions {

package/dist/diagnostics/fleet-constants.d.ts

@@ -1,6 +1,4 @@
-/**
- * Shared constants for fleet log collection.
- */
+/** Fleet log collection constants. */
 /** Default per-node deadline for a fleet bundle request (overridable via --fleet-timeout). */
 export declare const FLEET_NODE_TIMEOUT_MS = 60000;
 /** Per-node cap on raw log bytes an agent includes in its mini-bundle (50 MiB). */

package/dist/diagnostics/fleet-selection.d.ts

@@ -3,13 +3,9 @@ import type { FleetTopology } from './fleet-topology.js';
 /** A per-orchestrator selection, keyed by orchestrator instanceId. Absent = prune. */
 export type ResolvedSelectionMap = Map<string, FleetSelection>;
 /**
- * Resolve `--pick` selectors into a per-orchestrator FleetSelection map.
- *
- * No selectors -> every orchestrator gets `{ all: true }`. With selectors, an
- * orchestrator is included only if at least one of its agents/workers (or the
- * orchestrator itself) matches; its FleetSelection then carries exactly the
- * matched agent ids and worker instanceIds. Orchestrators with no matches are
- * omitted from the map (their branch is pruned).
+ * No selectors -> every orchestrator gets `{ all: true }`. Otherwise an orchestrator is included
+ * only if it or one of its agents/workers matches, carrying exactly the matched agent ids and
+ * worker instanceIds; one with no matches is omitted (branch pruned, no request issued).
  */
 export declare function resolveSelection(topology: FleetTopology, selectors: string[]): ResolvedSelectionMap;
 //# sourceMappingURL=fleet-selection.d.ts.map

package/dist/diagnostics/fleet-topology.d.ts

@@ -1,10 +1,8 @@
 /**
- * Fleet topology enumeration.
- *
  * Builds the cluster tree for `debug-bundle --fleet --list` / `--pick` from the
  * local agent registry plus the heartbeat-cached peer inventory — no fan-out.
- * Each peer's cached agent list is already maintained by ~30s heartbeats, so
- * enumeration is a cheap in-memory read.
+ * ~30s heartbeats already keep each peer's agent list, so enumeration is a
+ * cheap in-memory read.
  */
 /** A node in the enumerated fleet topology. */
 export interface FleetTopologyNode {
@@ -23,9 +21,7 @@ export interface FleetTopology {
 export interface FleetTopologyDeps {
     /** This collector's own instanceId (the root orchestrator). */
     instanceId: string;
-    /** This collector's role. */
     role: 'coordinator' | 'worker';
-    /** This collector's hostname, if known. */
     hostname?: string;
     /** This node's directly-connected agents. */
     listLocalAgents: () => {

package/dist/diagnostics/fleet-wiring.d.ts

@@ -29,31 +29,25 @@ export interface FleetRuntime {
     peerClients: Map<string, PeerClient>;
     /** Incoming peer-handler with the dual-direction collect send. */
     peerHandler: FleetPeerHandlerLike;
-    /** Deps for the local createDebugBundle. */
     diagnosticDeps: DiagnosticDeps;
     /** Raw orchestrator config (redacted by createDebugBundle). */
     config: Record<string, unknown>;
     /** Cluster health endpoint for the local bundle's cluster/health.json. */
     clusterHealthUrl?: string;
 }
-/**
- * Build the FleetCollectorDeps for a given selection of this node's downstream
- * agents/workers. The collector passes per-branch selection in when it knows
- * which downstream subset each peer should gather.
- */
+/** `perBranchSelection` names the downstream subset each peer gathers. */
 export declare function buildFleetCollectorDeps(runtime: FleetRuntime, perBranchSelection: (instanceId: string) => FleetSelection): FleetCollectorDeps;
-/** Build the FleetTopologyDeps for `--list` / `--pick` enumeration. */
+/** For `--list` / `--pick` enumeration. */
 export declare function buildFleetTopologyDeps(runtime: FleetRuntime): FleetTopologyDeps;
-/** Enumerate this node's fleet topology (no fan-out). */
+/** No fan-out. */
 export declare function getFleetTopology(runtime: FleetRuntime): FleetTopology;
 /**
- * Collect this node's full subtree (root call: includeCoordinatorMesh=true) with
- * an optional per-orchestrator selection map. Absent map entry => collect all.
+ * Root call (includeCoordinatorMesh=true) for this node's subtree. An orchestrator absent from
+ * `selectionByOrch` collects all.
  */
 export declare function collectFleet(runtime: FleetRuntime, selectionByOrch: Map<string, FleetSelection> | null): Promise<Buffer>;
 /**
- * Peer-side responder: on an inbound peer.logs.collect.request, assemble this
- * node's subtree (with the request's loop guard + selection) and stream it back
+ * Assembles this node's subtree under the request's loop guard and selection, streamed back
  * as peer.logs.collect.chunk frames, or a peer.logs.collect.error on failure.
  */
 export declare function makeFleetCollectResponder(runtime: FleetRuntime): (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;

package/dist/diagnostics/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * Diagnostics module.
- *
- * Re-exports all diagnostic types, runner, checks, bundle writer, and bundle reader.
- */
 export type { DiagnosticResult, DiagnosticDeps, DiagnosticCheck } from './types.js';
 export { runDiagnostics } from './runner.js';
 export type { RunDiagnosticsOptions } from './runner.js';

package/dist/diagnostics/runner.d.ts

@@ -1,12 +1,8 @@
 /**
- * Diagnostic check runner.
- *
- * Executes all diagnostic checks in parallel with timeout safety.
- * Each check runs independently -- a failing or timing out check
- * does not prevent other checks from completing.
+ * Runs all diagnostic checks in parallel, each with its own timeout: a failing or
+ * timed-out check does not prevent the others from completing.
  */
 import type { DiagnosticCheck, DiagnosticDeps, DiagnosticResult } from './types.js';
-/** Options for the diagnostic runner. */
 export interface RunDiagnosticsOptions {
     /** Timeout per check in milliseconds. Default: 5000. */
     timeoutMs?: number;
@@ -15,9 +11,9 @@ export interface RunDiagnosticsOptions {
  * Run all diagnostic checks and return results.
  *
  * @param deps - Dependencies available to checks
- * @param checks - Array of check functions (defaults to all 6 checks)
+ * @param checks - Array of check functions (defaults to `defaultChecks`)
  * @param options - Runner options (timeout, etc.)
- * @returns Array of diagnostic results, one per check
+ * @returns Array of diagnostic results; a check may yield more than one
  */
 export declare function runDiagnostics(deps: DiagnosticDeps, checks?: DiagnosticCheck[], options?: RunDiagnosticsOptions): Promise<DiagnosticResult[]>;
 //# sourceMappingURL=runner.d.ts.map