@kici-dev/orchestrator 0.18.0 → 0.19.0

package/dist/agent/registry.d.ts

@@ -70,8 +70,16 @@ export interface AgentEntry {
      * In memory rather than DB-backed, unlike reboot-pending: the destroy is issued by
      * this process, lasts seconds, and ends with the WebSocket close that removes the
      * entry — there is nothing to outlive.
+     *
+     * Also set when the agent itself reports `draining` on `agent.status` (a SIGUSR1
+     * drain, or a single-job agent that accepted its job); see {@link drainReported}.
      */
     draining: boolean;
+    /**
+     * The agent reported `draining` itself. Its drain is terminal for this connection,
+     * so {@link AgentRegistry.clearDraining} (the warm-pool undo) leaves it draining.
+     */
+    drainReported?: boolean;
     /**
      * Epoch ms until which the agent is held out of routing after it rejected a
      * dispatch as busy. Unset when no hold is in force. See {@link AgentRegistry.markBusyHeld}.
@@ -337,8 +345,11 @@ export declare class AgentRegistry {
      */
     isRegistered(agentId: string): boolean;
     /**
-     * Condemn an agent before a warm-pool destroy: it stays registered and finishes its
-     * current work, but takes no new dispatches.
+     * Condemn an agent: it stays registered and keeps finishing its current work,
+     * but takes no new dispatches.
+     *
+     * Called before a warm-pool destroy is issued. An agent that reports its own
+     * drain goes through {@link markDrainReported} instead.
      *
      * @returns the agent's `activeJobs`, so the caller can see a job claimed between its
      *   idle check and this mark and back out; `undefined` when not registered
@@ -382,7 +393,15 @@ export declare class AgentRegistry {
      * free slot now.
      */
     clearExpiredBusyHold(agentId: string, now?: number): void;
-    /** Undo {@link markDraining} — a destroy that was rejected leaves the agent alive. */
+    /**
+     * The agent reported on `agent.status` that it takes no new job: a drain, or a
+     * single-job agent that has accepted its job. Terminal for this connection.
+     */
+    markDrainReported(agentId: string): void;
+    /**
+     * Undo {@link markDraining} — a destroy that was rejected leaves the agent alive.
+     * An agent that reported its own drain stays draining.
+     */
     clearDraining(agentId: string): void;
     get(agentId: string): AgentEntry | undefined;
     getByWs(ws: WsLike): AgentEntry | undefined;

package/dist/cli/commands/shared/versioned-upgrade.d.ts

@@ -265,13 +265,13 @@ export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version
     error: string;
 };
 /**
- * Install `<owningPackage>@<version>` globally under the unit's pinned node, so
- * it lands in the prefix the unit's ExecStart resolves from. npm derives its
- * global prefix from the node that runs npm-cli.js, and the unit's
- * `<pinned>/bin/npm` (an `env node` shebang or a version-manager wrapper)
- * resolves `node` off PATH; run bare it would inherit the shell's active node,
- * the mise/nvm/asdf drift this upgrade fixes. Hence the pinned bin dir goes
- * first on PATH ({@link npmEnv}).
+ * Install `<owningPackage>@<version>` globally into the prefix the unit's
+ * ExecStart resolves from, with the unit's pinned node. Without an explicit
+ * prefix npm derives one from the node that runs npm-cli.js, or takes the
+ * `npm_config_prefix` the caller's environment carries (`npx` exports its
+ * own), so the install would land where the unit never reads it. The pinned
+ * node runs npm-cli.js directly, skipping a version-manager wrapper at
+ * `<pinned>/bin/npm`, which also keeps the shell's active node out of it.
  */
 export declare function installGlobalPackage(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
     ok: boolean;

package/dist/cli/service/instance/manifest.d.ts

@@ -57,16 +57,42 @@ export declare function writeInstallManifest(instanceDir: string, fresh: Instanc
  * Where an npm-source upgrade installs, from a unit's launch spec.
  * `owningPackage` is the top-level global package ExecStart runs (`kici-admin`
  * when the component loads through its nested node_modules, else
- * `@kici-dev/<component>`). `npmPath` sits beside the pinned node, so
- * `npm install -g` lands in the prefix ExecStart resolves from, whatever the
- * shell's active node.
+ * `@kici-dev/<component>`). `globalPrefix` is the npm prefix the launch entry
+ * lives in; every npm call passes it as `--prefix`, because the caller's
+ * environment can name another one (`npx` exports `npm_config_prefix`).
+ * `npmInvocation` runs `npm-cli.js` with the pinned node when it sits beside
+ * that node, so a version-manager wrapper at `npmPath` (mise's reshim needs
+ * mise on PATH) is never started.
  */
 export interface NpmInstallTarget {
     nodeExecPath: string;
     npmPath: string;
     owningPackage: string;
+    globalPrefix: string;
+    npmInvocation: {
+        cmd: string;
+        preArgs: string[];
+    };
 }
+/**
+ * The resolution of a launch spec to an install target. `no-entry` covers an
+ * opaque `--binary` install and a path outside `node_modules`; `not-global`
+ * an entry under a local `node_modules` tree, whose prefix the unit's npm
+ * cannot install into with `-g`.
+ */
+export type NpmInstallResolution = {
+    ok: true;
+    target: NpmInstallTarget;
+} | {
+    ok: false;
+    reason: 'no-entry';
+} | {
+    ok: false;
+    reason: 'not-global';
+    entry: string;
+};
 export declare function resolveNpmInstallTarget(spec: LaunchSpec, component: Component, opts: {
     windows: boolean;
-}): NpmInstallTarget | null;
+    exists?: (p: string) => boolean;
+}): NpmInstallResolution;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/cli.js

@@ -15246,19 +15246,60 @@ function writeInstallManifest(instanceDir, fresh, launch, opts = {}) {
 function resolveNpmInstallTarget(spec, component, opts) {
 	const entryRe = new RegExp(`[/\\\\]@kici-dev[/\\\\]${component}[/\\\\]dist[/\\\\](?:server|standalone)\\.js$`);
 	const entry = [spec.execPath, ...spec.args].find((a) => entryRe.test(a));
-	if (!entry) return null;
+	if (!entry) return {
+		ok: false,
+		reason: "no-entry"
+	};
 	const owningPackage = firstGlobalPackage(entry);
-	if (!owningPackage) return null;
+	if (!owningPackage) return {
+		ok: false,
+		reason: "no-entry"
+	};
 	const p = opts.windows ? path.win32 : path.posix;
-	const npmBin = opts.windows ? "npm.cmd" : "npm";
-	const npmPath = p.join(p.dirname(spec.execPath), npmBin);
+	const globalPrefix = globalPrefixOf(entry, opts.windows);
+	if (!globalPrefix) return {
+		ok: false,
+		reason: "not-global",
+		entry
+	};
+	const nodeDir = p.dirname(spec.execPath);
+	const npmPath = p.join(nodeDir, opts.windows ? "npm.cmd" : "npm");
+	const npmCliJs = opts.windows ? p.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js") : p.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+	const npmInvocation = (opts.exists ?? fs.existsSync)(npmCliJs) ? {
+		cmd: spec.execPath,
+		preArgs: [npmCliJs]
+	} : {
+		cmd: npmPath,
+		preArgs: []
+	};
 	return {
-		nodeExecPath: spec.execPath,
-		npmPath,
-		owningPackage
+		ok: true,
+		target: {
+			nodeExecPath: spec.execPath,
+			npmPath,
+			owningPackage,
+			globalPrefix,
+			npmInvocation
+		}
 	};
 }
 /**
+* The npm global prefix holding `entry`, split on its FIRST `node_modules`
+* segment like {@link firstGlobalPackage}. Windows lays a global install out as
+* `<prefix>\node_modules\<pkg>`; posix as `<prefix>/lib/node_modules/<pkg>`, so
+* there the segment before must be `lib`, which tells a global install from a
+* local `node_modules` tree. Null for anything else.
+*/
+function globalPrefixOf(entry, windows) {
+	const p = windows ? path.win32 : path.posix;
+	const segments = entry.split(/[/\\]/);
+	const idx = segments.indexOf("node_modules");
+	if (idx < 1) return null;
+	if (windows) return segments.slice(0, idx).join(p.sep) || null;
+	if (idx < 2 || segments[idx - 1] !== "lib") return null;
+	return segments.slice(0, idx - 1).join(p.sep) || p.sep;
+}
+/**
 * The package under the FIRST `node_modules` segment (the global root), which
 * `npm install -g` must target; `@scope/name` keeps both segments. Null
 * without a `node_modules` segment.
@@ -24448,14 +24489,18 @@ function planNpmSourceUpgrade(opts) {
 		kind: "error",
 		reason: "self-driving upgrade requires --version <target> (the version to install). Pass --restart-only to restart the already-installed package without installing."
 	};
-	const target = spec ? resolveNpmInstallTarget(spec, component, { windows }) : null;
-	if (!target) return {
+	const resolution = spec ? resolveNpmInstallTarget(spec, component, { windows }) : null;
+	if (resolution && !resolution.ok && resolution.reason === "not-global") return {
+		kind: "error",
+		reason: `npm-source upgrade cannot self-install: the unit's launch target ${resolution.entry} is not inside a global npm install, so the unit's npm has no global prefix that holds it. The unit runs ${spec.execPath}; this kici-admin runs ${process.execPath}. Use an archive upgrade (--from <archive> / --url <url> + --version), or pre-install the package and re-run with --restart-only.`
+	};
+	if (!resolution?.ok) return {
 		kind: "error",
 		reason: "npm-source upgrade cannot self-install: the unit's launch target is a custom --binary install or a non-node_modules path, so there is no global package to update. Use an archive upgrade (--from <archive> / --url <url> + --version), or pre-install the package and re-run with --restart-only."
 	};
 	return {
 		kind: "self-drive",
-		target,
+		target: resolution.target,
 		version: requestedVersion
 	};
 }
@@ -24471,9 +24516,14 @@ function windowsShellCommand(cmd, args) {
 	for (const arg of args) if (!/^[A-Za-z0-9@/._+-]+$/.test(arg)) throw new Error(`cannot pass "${arg}" to npm: it holds a character cmd.exe reads as syntax`);
 	return [`"${cmd}"`, ...args].join(" ");
 }
+/**
+* Only a Windows batch file (`npm.cmd`) goes through cmd.exe; the pinned
+* `node.exe` running npm-cli.js spawns directly, with no shell to parse its
+* `C:\…` arguments.
+*/
 const defaultSpawnRunner = (cmd, args, opts) => {
 	const env = opts?.env ?? process.env;
-	const r = process.platform === "win32" ? spawnSync(windowsShellCommand(cmd, args), {
+	const r = process.platform === "win32" && /\.cmd$/i.test(cmd) ? spawnSync(windowsShellCommand(cmd, args), {
 		encoding: "utf-8",
 		shell: true,
 		env
@@ -24488,15 +24538,40 @@ const defaultSpawnRunner = (cmd, args, opts) => {
 	};
 };
 /**
-* The environment npm runs in: the unit's pinned node first on PATH, because
-* npm derives its global prefix from the node that runs it.
+* The environment npm runs in: the unit's pinned node first on PATH, so a
+* wrapper fallback (`npmPath`, an `env node` shebang) resolves that node. The
+* caller's `npm_config_*` stay, so an operator-set registry or proxy still
+* applies.
+*
+* On the `npm.cmd` fallback the prefix goes through `npm_config_prefix`:
+* {@link windowsShellCommand} refuses the `\`, `:` and `=` a `--prefix=C:\…`
+* argument holds. Every other invocation passes `--prefix` on the command
+* line ({@link npmArgs}), which npm ranks above the environment.
 */
 function npmEnv(target) {
 	const pinnedBinDir = path.dirname(target.nodeExecPath);
-	return {
+	const env = {
 		...process.env,
 		PATH: `${pinnedBinDir}${path.delimiter}${process.env.PATH ?? ""}`
 	};
+	if (prefixViaEnv(target)) {
+		for (const key of Object.keys(env)) if (/^npm_config_(global_)?prefix$/i.test(key)) delete env[key];
+		env.npm_config_prefix = target.globalPrefix;
+	}
+	return env;
+}
+/** Whether the prefix travels in the environment: the `npm.cmd` fallback. */
+function prefixViaEnv(target) {
+	return target.npmInvocation.preArgs.length === 0 && /\.cmd$/i.test(target.npmInvocation.cmd);
+}
+/** The argv for one npm call: npm-cli.js first when the pinned node runs it, `--prefix` last. */
+function npmArgs(target, args) {
+	const prefix = prefixViaEnv(target) ? [] : [`--prefix=${target.globalPrefix}`];
+	return [
+		...target.npmInvocation.preArgs,
+		...args,
+		...prefix
+	];
 }
 /**
 * Whether `version` reads KICI_ENV_FILE, asked of the unit's npm registry. Such
@@ -24504,12 +24579,12 @@ function npmEnv(target) {
 * KiCI package of that version depends on.
 */
 function npmReleaseReadsEnvFile(target, version, run = defaultSpawnRunner) {
-	const res = run(target.npmPath, [
+	const res = run(target.npmInvocation.cmd, npmArgs(target, [
 		"view",
 		`@kici-dev/shared@${version}`,
 		"exports",
 		"--json"
-	], { env: npmEnv(target) });
+	]), { env: npmEnv(target) });
 	if (res.status !== 0) return {
 		ok: false,
 		error: res.stderr.trim() || `npm view exited with ${res.status}`
@@ -24538,20 +24613,20 @@ function npmReleaseReadsEnvFile(target, version, run = defaultSpawnRunner) {
 	};
 }
 /**
-* Install `<owningPackage>@<version>` globally under the unit's pinned node, so
-* it lands in the prefix the unit's ExecStart resolves from. npm derives its
-* global prefix from the node that runs npm-cli.js, and the unit's
-* `<pinned>/bin/npm` (an `env node` shebang or a version-manager wrapper)
-* resolves `node` off PATH; run bare it would inherit the shell's active node,
-* the mise/nvm/asdf drift this upgrade fixes. Hence the pinned bin dir goes
-* first on PATH ({@link npmEnv}).
+* Install `<owningPackage>@<version>` globally into the prefix the unit's
+* ExecStart resolves from, with the unit's pinned node. Without an explicit
+* prefix npm derives one from the node that runs npm-cli.js, or takes the
+* `npm_config_prefix` the caller's environment carries (`npx` exports its
+* own), so the install would land where the unit never reads it. The pinned
+* node runs npm-cli.js directly, skipping a version-manager wrapper at
+* `<pinned>/bin/npm`, which also keeps the shell's active node out of it.
 */
 function installGlobalPackage(target, version, run = defaultSpawnRunner) {
-	const res = run(target.npmPath, [
+	const res = run(target.npmInvocation.cmd, npmArgs(target, [
 		"install",
 		"-g",
 		`${target.owningPackage}@${version}`
-	], { env: npmEnv(target) });
+	]), { env: npmEnv(target) });
 	return {
 		ok: res.status === 0,
 		stderr: res.stderr
@@ -24886,15 +24961,14 @@ async function performSelfDrivingInstall(args) {
 		if (!verdict.reads) throw new Error(`refusing to install ${release} for "${config.name}": ${envFileRefusal(release, config.envFilePath)} The service and the installed package were not changed.`);
 	}
 	if (!opts.yes) {
-		console.log(`This will install ${target.owningPackage}@${version} using ${target.npmPath}`);
-		console.log(`  (node runtime: ${target.nodeExecPath}), then restart "${config.name}".`);
+		console.log(`This will install ${target.owningPackage}@${version} with ${target.nodeExecPath} into ${target.globalPrefix} (the unit's runtime), then restart "${config.name}".`);
 		console.log("");
 		if (!await confirm$1("Proceed with upgrade?")) {
 			console.log("Upgrade cancelled.");
 			return;
 		}
 	}
-	console.log(`Installing ${target.owningPackage}@${version} under the unit's runtime...`);
+	console.log(`Installing ${target.owningPackage}@${version} with ${target.nodeExecPath} into ${target.globalPrefix} (the unit's runtime)...`);
 	const result = installGlobalPackage(target, version, args.run);
 	if (!result.ok) {
 		const hint = /EACCES|permission denied|EPERM/i.test(result.stderr) ? " The unit's global prefix is not writable — re-run with privileges matching the unit's runtime." : "";
@@ -26603,7 +26677,7 @@ init_manifest();
 const ALL_PLATFORMS = AgentPlatform.options;
 /** The orchestrator's own version (single-version invariant) = the packaged agent version. */
 function resolveKiciVersion() {
-	return "0.18.0";
+	return "0.19.0";
 }
 /** Parse the --platform value: default set | single | CSV | `all`. */
 function parsePlatforms(raw) {
@@ -35310,6 +35384,7 @@ function buildAgentContainerHostConfig(input) {
 		...typeof cpus === "number" && cpus > 0 ? { NanoCpus: Math.round(cpus * 1e9) } : {},
 		...input.binds && input.binds.length > 0 ? { Binds: input.binds } : {},
 		...input.extraHosts && input.extraHosts.length > 0 ? { ExtraHosts: input.extraHosts } : {},
+		...input.supplementaryGroups && input.supplementaryGroups.length > 0 ? { GroupAdd: input.supplementaryGroups.map(String) } : {},
 		AutoRemove: false,
 		PidsLimit: AGENT_CONTAINER_PIDS_LIMIT
 	};
@@ -35374,6 +35449,19 @@ async function detectRuntime(runtimeHint) {
 * Create a LogCapture from a running container's stdout/stderr streams.
 * Uses dockerode's demuxStream to strip Docker's 8-byte multiplexed headers.
 */
+/**
+* The cpu / memory ceiling for one spawn. `effectiveLimits` from ScalerManager
+* wins: it already folds in job overrides, label-set and scaler defaults.
+* Otherwise the label set's (or the scaler's default) `resources.limits` apply.
+*/
+function resolveSpawnLimits(effectiveLimits, resources) {
+	if (effectiveLimits && (effectiveLimits.cpus || effectiveLimits.memBytes)) return effectiveLimits;
+	const limits = resources?.limits;
+	return {
+		...limits?.memory ? { memBytes: parseMemoryString(limits.memory) } : {},
+		...limits?.cpus ? { cpus: limits.cpus } : {}
+	};
+}
 async function createContainerLogCapture(docker, containerId) {
 	const stream = await docker.getContainer(containerId).logs({
 		follow: true,
@@ -35661,15 +35749,7 @@ var ContainerScalerBackend = class ContainerScalerBackend {
 			];
 			const binds = [...matchedLabelSet.volumes ?? []];
 			if (matchedLabelSet.containerSocket && this.resolvedSocketPath) binds.push(`${this.resolvedSocketPath}:${this.resolvedSocketPath}`);
-			let resolvedLimits;
-			if (effectiveLimits && (effectiveLimits.cpus || effectiveLimits.memBytes)) resolvedLimits = effectiveLimits;
-			else {
-				const limits = (matchedLabelSet.resources ?? this.defaultResources)?.limits;
-				resolvedLimits = {
-					...limits?.memory ? { memBytes: parseMemoryString(limits.memory) } : {},
-					...limits?.cpus ? { cpus: limits.cpus } : {}
-				};
-			}
+			const resolvedLimits = resolveSpawnLimits(effectiveLimits, matchedLabelSet.resources ?? this.defaultResources);
 			const jobContainer = spawnContext?.container;
 			const spawnImage = jobContainer?.image ?? matchedLabelSet.image;
 			await pullImageIfMissing({
@@ -35692,6 +35772,7 @@ var ContainerScalerBackend = class ContainerScalerBackend {
 				binds.push(runtimeInjectBind(runtimeVolume));
 				agentInit = runtimeInitCommand(await agentImageLabels(this.docker, matchedLabelSet.image));
 			}
+			if (!jobContainer) env.push("KICI_SCALER_SINGLE_JOB=1");
 			emit(ScalerEventType.enum["scaler.provisioning"], "creating container");
 			const normalizedLabelSetStr = normalizeLabelSet(labelSet);
 			const container = await this.docker.createContainer({
@@ -35710,7 +35791,8 @@ var ContainerScalerBackend = class ContainerScalerBackend {
 				HostConfig: buildAgentContainerHostConfig({
 					limits: resolvedLimits,
 					binds,
-					...this.extraHosts ? { extraHosts: this.extraHosts } : {}
+					...this.extraHosts ? { extraHosts: this.extraHosts } : {},
+					...!jobContainer && { supplementaryGroups: [1990] }
 				}),
 				...this.networkIsolation && { NetworkingConfig: { EndpointsConfig: { ["kici-agent-net"]: {} } } }
 			});
@@ -36844,7 +36926,7 @@ function routeRootArgs(root, args) {
 * build entry; the fallback covers a source run (tests, `tsx`), the same shape
 * `server.ts` and `standalone.ts` use for `ORCHESTRATOR_VERSION`.
 */
-const CLI_VERSION = "0.18.0";
+const CLI_VERSION = "0.19.0";
 /**
 * Root command whose option parsing first routes argv through
 * {@link routeRootArgs}: a leading `--version` prints the CLI version, and an

package/dist/dashboard/handler.d.ts

@@ -156,6 +156,8 @@ export declare class DashboardHandler {
     private enforcePolicy;
     /** dashboard.run.detail: the run's nested job/step tree. */
     handleRunDetail(msg: DashboardRunDetailRequest): Promise<void>;
+    /** Answer a run-detail read for a run this orchestrator does not hold. */
+    private sendRunDetailNotFound;
     /**
      * dashboard.run.structured: the user-plane twin of the orchestrator-admin
      * `/runs/:id/structured` endpoint, byte-identical because it reuses the

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -71,7 +71,7 @@ export interface WorkflowDispatchContext {
     fullLockFile: {
         workflows: readonly LockWorkflow[];
         lockfileHash?: string;
-        /** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
+        /** In-repo workspace sibling closure digest; part of the dep pointer key. */
         siblingsDigest?: string;
         source: {
             file: string;

package/dist/pipeline/global-eval-round.d.ts

@@ -193,14 +193,6 @@ export declare function narrowVerdict(raw: unknown, workflowName: string): Globa
  * best-effort post, so the check would vanish.
  */
 export declare const MAX_ROUND_REASON_CHARS = 4000;
-/**
- * Truncate `text` to at most `max` UTF-16 code units, marking that it was cut.
- *
- * - A `max` no larger than the marker returns the truncated marker, never a
- *   string longer than `max`.
- * - The cut backs off one unit rather than split a surrogate pair.
- */
-export declare function truncateReasonText(text: string, max: number): string;
 /**
  * One round that produced no verdicts after every attempt. Exactly one per
  * failed round, never one per candidate (the round exists to collapse N

package/dist/scaler/bare-metal-backend.d.ts

@@ -2,7 +2,8 @@
  * Bare-metal scaler backend: ephemeral agent processes via child_process.spawn.
  * On Linux and macOS each agent leads its own process group, which teardown
  * signals; on Windows teardown ends the agent's process tree with taskkill.
- * All agents are single-use: destroyed after job completion.
+ * An agent exits once it is idle past its idle window (a follow-up job that
+ * arrives within the window reuses it), and the backend destroys it on disconnect.
  */
 import { type ToolRequirement } from '@kici-dev/shared';
 import type { AgentTokenStore } from '../agent/token-store.js';

package/dist/scaler/container-hostconfig.d.ts

@@ -15,6 +15,13 @@ import type { EffectiveLimits } from './types.js';
  * its own docs and validation, and nothing yet says the constant is wrong.
  */
 export declare const AGENT_CONTAINER_PIDS_LIMIT = 4096;
+/**
+ * Group id of `kici-sudo` in the KiCI agent image (`packages/agent/Dockerfile`
+ * creates it). `/etc/sudoers.d/kici-sudo` grants that group passwordless sudo.
+ * The container scaler adds the group only to the single-job containers it
+ * starts from a pool's own image, so root never outlives one job.
+ */
+export declare const AGENT_SUDO_GROUP_GID = 1990;
 /**
  * Why this container is NOT capability-dropped, though the job containers the
  * agent starts are.
@@ -42,6 +49,8 @@ export interface AgentContainerHostConfigInput {
     binds?: string[];
     /** Extra `host:ip` entries (e.g. a private registry alias). */
     extraHosts?: string[];
+    /** Extra group ids for the container's process (`GroupAdd`). */
+    supplementaryGroups?: number[];
 }
 /**
  * Build the agent container's `HostConfig`.

package/dist/scaler/warm-pool.d.ts

@@ -19,7 +19,10 @@ export interface WarmPoolCallbacks {
     countAvailable: (labels: string[]) => number;
     /**
      * Agents this backend spawned that match the label set and have never run a
-     * job. `registeredAt` doubles as "idle since": scaler agents are single-use.
+     * job. `registeredAt` stands in for "idle since". That is exact for a
+     * container-backend agent, which exits after its one job. An agent of another
+     * backend can finish a job and wait out its idle window before it exits, so it
+     * can read as idle for longer than it has been.
      *
      * Scoped to the backend because the reaper destroys what it is given; a
      * matching static agent is ready capacity, not this pool's to tear down.