@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/sha256-asset.js

@@ -1,31 +1,11 @@
-/**
- * sha256 helpers for verifying downloaded release assets.
- *
- * These live in their own LEAF module — importing only `node:crypto` and
- * `node:fs` — on purpose. They used to sit in the computer subsystem's ssh-tunnel
- * module (since extracted, PHNX-4075), whose
- * own import graph reached `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
- * the in-repo secrets engine's own keychain-helper downloader, which imported
- * back into `helper-download.ts` while it was still evaluating — before
- * `EXPECTED_TEAM_ID` was bound, throwing `ReferenceError: Cannot access
- * 'EXPECTED_TEAM_ID' before initialization` for any entry point that reached
- * `helper-download.ts` first (RUSH-3113). The secrets engine that closed that
- * cycle is gone now (PHNX-3989 — the standalone `secrets` CLI downloads its own
- * helper), but the discipline that fixed it still holds: keep this module a
- * leaf, since `helper-download.ts` needs nothing beyond these two pure
- * functions and adding a local import here can reintroduce a cycle with
- * whatever imports it next.
- */
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
-/** Pull the digest out of a `<sha256>  <filename>` release asset. */
 export function parseSha256Asset(text) {
     const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
     if (!m)
         throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
     return m[1].toLowerCase();
 }
-/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
 export function sha256File(file) {
     return new Promise((resolve, reject) => {
         const hash = createHash('sha256');

package/dist/lib/share-runtime.d.ts

@@ -1,11 +1 @@
-/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
- *
- * Auto-injecting the share write token on every `agents run` is a background
- * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
- * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
- * always `agentOnly`: it resolves the token only from the injected env or an
- * already-held / no-ACL bundle, and silently returns undefined otherwise (the
- * agent can still publish via its own `artifacts share` credentials). For
- * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
- * share`) or make it no-ACL (`agents secrets policy share never`). */
 export declare function shareRuntimeEnv(): Record<string, string> | undefined;

package/dist/lib/share-runtime.js

@@ -1,45 +1,19 @@
-// Runtime share-token injection for spawned agents.
-//
-// The artifact share ENGINE moved to `@phnx-labs/artifacts-cli` (PHNX-3992);
-// agents-cli no longer publishes artifacts itself. What stays here is the thin
-// glue that lets a dispatched agent inherit the operator's BYO write token so
-// its own `artifacts share` can publish headlessly: `run`/`teams`/`cloud`
-// dispatch call `shareRuntimeEnv()` and forward the result into the agent env.
-// artifacts-cli honors the same `SHARE_WRITE_TOKEN` variable, so the injection
-// contract is unchanged by the extraction.
-//
-// The endpoint config still lives in `agents.yaml` under `share:` (Meta.share)
-// so a previously-provisioned BYO endpoint keeps syncing fleet-wide; the raw
-// write token lives in the keychain-backed `share` secrets bundle, never on disk.
 import { readMeta } from './state.js';
 import { bundleExistsSync as bundleExists, readAndResolveBundleEnvSync as readAndResolveBundleEnv, } from './secrets-client.js';
 const SHARE_BUNDLE = 'share';
 const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
 const SHARE_TOKEN_ENV_KEY = 'SHARE_WRITE_TOKEN';
-/** Trim; empty / whitespace-only strings are absent. */
 function nonempty(v) {
     const t = v?.trim();
     return t ? t : undefined;
 }
-/** Whether a BYO share endpoint is still configured in `agents.yaml`. */
 function hasShareEndpoint() {
     return !!nonempty(readMeta().share?.baseUrl);
 }
-/** The write token as injected ephemerally into fleet/cloud agents. */
 function readWriteTokenEnv(env = process.env) {
     const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
     return token ? token : null;
 }
-/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
- *
- * Auto-injecting the share write token on every `agents run` is a background
- * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
- * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
- * always `agentOnly`: it resolves the token only from the injected env or an
- * already-held / no-ACL bundle, and silently returns undefined otherwise (the
- * agent can still publish via its own `artifacts share` credentials). For
- * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
- * share`) or make it no-ACL (`agents secrets policy share never`). */
 export function shareRuntimeEnv() {
     if (!hasShareEndpoint())
         return undefined;
@@ -52,7 +26,7 @@ export function shareRuntimeEnv() {
         const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
             caller: 'share',
             keys: [SHARE_TOKEN_KEY],
-            agentOnly: true, // never raise a Touch ID sheet on an agent launch (SEC-13)
+            agentOnly: true,
         });
         const token = env[SHARE_TOKEN_KEY];
         return token ? { [SHARE_TOKEN_ENV_KEY]: token } : undefined;

package/dist/lib/shim-heal.d.ts

@@ -3,26 +3,11 @@ interface InteractiveShimHealResult {
     noticeLines: string[] | null;
     report: SelfHealReport;
 }
-/**
- * Heal the shim/shadow/PATH conditions silently, then return both the raw report
- * and the notice lines to print ONCE for whatever is left (a real-binary shadow we
- * won't move; a PATH entry that was just added / needs a reload).
- */
 export declare function runInteractiveShimHeal(): Promise<InteractiveShimHealResult>;
 type PathNoticeState = 'ok' | 'added' | 'reload';
-/**
- * A stable signature of the conditions worth surfacing: the sorted set of
- * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
- */
 export declare function computeShimNoticeSignature(input: {
     shadowNotes: string[];
     pathState: PathNoticeState;
 }): string;
-/**
- * Whether to surface the notice for the current condition. Returns false (stay
- * quiet) when the exact same signature was already surfaced, or when there's
- * nothing to say. On true it records the signature so the next shell with the same
- * state is suppressed. An empty signature clears the marker.
- */
 export declare function shouldSurfaceShimNotice(signature: string): boolean;
 export {};

package/dist/lib/shim-heal.js

@@ -1,21 +1,6 @@
-// Interactive shim-heal for the CLI startup path + the persistent notice-state that
-// replaces the old per-PPID sentinel.
-//
-// The actual repair (regenerating shims, adopting symlink launchers, adding the
-// shims dir to PATH) lives in the unified self-heal registry — this module just
-// drives the shim-relevant checks SILENTLY on a normal `agents` invocation and then
-// decides whether to print a one-time notice about anything left. The old flow
-// re-ran its whole detect-and-nag on every new terminal (its sentinel was keyed to
-// process.ppid); the persistent signature here means an unresolved condition is
-// surfaced once, not on every shell.
 import fs from 'node:fs';
 import path from 'node:path';
 import { getRuntimeStateDir } from './state.js';
-/**
- * Heal the shim/shadow/PATH conditions silently, then return both the raw report
- * and the notice lines to print ONCE for whatever is left (a real-binary shadow we
- * won't move; a PATH entry that was just added / needs a reload).
- */
 export async function runInteractiveShimHeal() {
     const { runSelfHeal } = await import('./self-heal/registry.js');
     const report = await runSelfHeal({ checks: ['shims', 'shadowing', 'path'], mode: 'safe' });
@@ -29,9 +14,9 @@ export async function runInteractiveShimHeal() {
             shadowNotes.push(...c.result.needsAttention);
         if (c.id === 'path') {
             for (const f of c.result.fixed)
-                pathAdded = f; // "added shims to PATH (~/.zshrc)"
+                pathAdded = f;
             for (const a of c.result.needsAttention)
-                pathReload = a; // "...not loaded — open a new terminal"
+                pathReload = a;
         }
     }
     const pathState = pathAdded ? 'added' : pathReload ? 'reload' : 'ok';
@@ -57,10 +42,6 @@ export async function runInteractiveShimHeal() {
 function noticeStatePath() {
     return path.join(getRuntimeStateDir(), 'shim-notice.json');
 }
-/**
- * A stable signature of the conditions worth surfacing: the sorted set of
- * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
- */
 export function computeShimNoticeSignature(input) {
     const shadows = [...input.shadowNotes].sort().join(',');
     const parts = [];
@@ -85,21 +66,14 @@ function writeLastNoticeSignature(signature) {
         fs.writeFileSync(noticeStatePath(), JSON.stringify({ signature }));
     }
     catch {
-        /* best-effort: never block a command on the marker */
     }
 }
-/**
- * Whether to surface the notice for the current condition. Returns false (stay
- * quiet) when the exact same signature was already surfaced, or when there's
- * nothing to say. On true it records the signature so the next shell with the same
- * state is suppressed. An empty signature clears the marker.
- */
 export function shouldSurfaceShimNotice(signature) {
     if (!signature) {
         try {
             fs.rmSync(noticeStatePath(), { force: true });
         }
-        catch { /* best-effort */ }
+        catch { }
         return false;
     }
     if (readLastNoticeSignature() === signature)

package/dist/lib/signin-badge.d.ts

@@ -3,84 +3,17 @@ import type { AuthVerdict } from './auth-health.js';
 import type { AgentId } from './types.js';
 export type AccountVerdict = Exclude<AuthVerdict, 'unconfigured' | 'error'> | 'missing' | 'per-device' | 'ready';
 export type AccountProvisioning = 'portable' | 'per-device';
-/**
- * The exact command that logs a given agent in — for warn banners and nudges.
- * Driven off the registry `cliCommand` with the per-agent subcommand overrides
- * (verified against the real CLIs): codex/grok/opencode run the finite login
- * subcommand `HARNESS_AUTH` wires (`loginSubcommand`), claude logs in from
- * inside its TUI via `/login`, and the remaining agents (kimi, gemini, …) start
- * their device/oauth flow on launch.
- */
 export declare function loginHint(agentId: AgentId): string;
-/**
- * Harnesses that log back in through a finite native subcommand runnable via
- * `agents run <agent>@<version> -- <args>`. Claude logs in from inside its TUI
- * (`/login`); cursor and the rest start their device/oauth flow on launch.
- */
 export declare const SUBCOMMAND_LOGIN_AGENTS: readonly AgentId[];
-/**
- * The finite native login subcommand (`login`, `login --device-auth`,
- * `auth login`) for a {@link SUBCOMMAND_LOGIN_AGENTS} harness, read from the one
- * `HARNESS_AUTH` row so every surface that spells it — the hint, the per-version
- * fix, `agents doctor` — agrees. Null for every other harness.
- */
 export declare function loginSubcommand(agent: AgentId): string | null;
-/**
- * Exact action shown beside a non-live account. Every emitted command exists
- * today — never a planned surface and never a hidden verb:
- * - Per-device harnesses (kimi/antigravity) repair on the box itself: run the
- *   harness there (`loginHint`) and complete its native login.
- * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
- *   A known account with no slot on a headed device is onboarded with
- *   `agents accounts add <harness> <name>`. A worker never runs an
- *   interactive login — the hint is `add.ts`'s worker refusal (add on the
- *   personal device; this box is provisioned from the durable credential).
- * - Unnamed legacy homes use the same version-targeted command shape as
- *   doctor, so the hint never logs a different/default home in by accident.
- * - `unverified` / `no_evidence` emit nothing: the probe could not confirm state
- *   (codex/grok have no probe endpoint; a worker's token lacks the usage scope),
- *   so there is nothing to repair.
- */
 export declare function fixFor(input: {
     agent: AgentId;
     verdict: AccountVerdict;
     name?: string | null;
     version?: string | null;
     provisioning?: AccountProvisioning;
-    /** When false, this named account has no slot on this device yet. */
     hasSlot?: boolean;
 }): string | null;
-/**
- * Whether `agents run` should probe login state before launching. True only for
- * a launch that actually opens the interactive TUI — where discovering a logged-out
- * account after the fact wastes time. Suppressed when there is no preamble surface
- * (`--json`/`--quiet`), when the check is explicitly disabled
- * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
- * signed-in account.
- *
- * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
- * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
- * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
- * Keying only off `hasPrompt` would silently skip the warning on exactly those
- * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
- * consulted directly.
- */
-/**
- * Is a Claude run on this box going to authenticate from an ambient
- * `CLAUDE_CODE_OAUTH_TOKEN` rather than a per-version login?
- *
- * `AccountInfo.signedIn` is `!!email` read from a version home's `.claude.json`
- * (agents.ts), so a version with no account written there reports signed-out —
- * even though Claude Code authenticates fine from the env token and the run
- * succeeds. Rendering that as "logged out" sends people hunting a login that is
- * not missing (a real fleet incident: every version on a box read as locked out
- * while all of them answered a live prompt).
- *
- * It is also the more useful warning: an ambient token is ONE account, so every
- * version on the box resolves to it and balanced rotation across them rotates
- * nothing. `env` is a parameter so the branch is testable without mutating the
- * process environment.
- */
 export declare function ambientClaudeToken(agentId: AgentId | string, env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldCheckLoginBeforeLaunch(o: {
     interactive?: boolean;
@@ -92,9 +25,4 @@ export declare function shouldCheckLoginBeforeLaunch(o: {
     authCheckDisabled?: boolean;
     rotated?: boolean;
 }): boolean;
-/**
- * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
- * account label is derivable (email, else an account id), it is appended in cyan;
- * opaque-credential agents with no email still read as signed in.
- */
 export declare function formatSignInBadge(info: Pick<AccountInfo, 'signedIn' | 'email' | 'accountId'> | null | undefined): string;

package/dist/lib/signin-badge.js

@@ -1,26 +1,8 @@
-/**
- * Shared login-state LOOK. One place decides how "signed in / logged out"
- * renders and what the login command is, so `agents doctor`, `agents view`, and
- * the `agents run` preflight banner all read identically.
- *
- * The signal is `AccountInfo.signedIn` from `getAccountInfo` (file-based, cheap,
- * no Keychain ACL prompt). It is advisory — opaque-credential agents (Kimi,
- * Antigravity) and keychain-bound Claude can false-negative — so callers that act
- * on it (the run preflight) WARN and continue; they never block.
- */
 import chalk from 'chalk';
 import { addWorkerRefusal } from './accounts/add.js';
 import { AGENTS } from './agents.js';
 import { HARNESS_AUTH } from './harness-auth-capabilities.js';
 import { CONFIG_ENV_ISOLATED_AGENTS } from './installations/shims.js';
-/**
- * The exact command that logs a given agent in — for warn banners and nudges.
- * Driven off the registry `cliCommand` with the per-agent subcommand overrides
- * (verified against the real CLIs): codex/grok/opencode run the finite login
- * subcommand `HARNESS_AUTH` wires (`loginSubcommand`), claude logs in from
- * inside its TUI via `/login`, and the remaining agents (kimi, gemini, …) start
- * their device/oauth flow on launch.
- */
 export function loginHint(agentId) {
     const cli = AGENTS[agentId]?.cliCommand ?? agentId;
     switch (agentId) {
@@ -30,50 +12,18 @@ export function loginHint(agentId) {
         case 'grok':
         case 'opencode':
             return `${cli} ${loginSubcommand(agentId)}`;
-        // Warp Agent CLI has no `login` subcommand: running `warp` opens a browser
-        // sign-in on launch (or set WARP_API_KEY / pass --api-key), so the default
-        // bare-`warp` hint is correct.
         default:
             return cli;
     }
 }
-/**
- * Harnesses that log back in through a finite native subcommand runnable via
- * `agents run <agent>@<version> -- <args>`. Claude logs in from inside its TUI
- * (`/login`); cursor and the rest start their device/oauth flow on launch.
- */
 export const SUBCOMMAND_LOGIN_AGENTS = ['codex', 'grok', 'opencode'];
-/**
- * The finite native login subcommand (`login`, `login --device-auth`,
- * `auth login`) for a {@link SUBCOMMAND_LOGIN_AGENTS} harness, read from the one
- * `HARNESS_AUTH` row so every surface that spells it — the hint, the per-version
- * fix, `agents doctor` — agrees. Null for every other harness.
- */
 export function loginSubcommand(agent) {
     if (!SUBCOMMAND_LOGIN_AGENTS.includes(agent))
         return null;
     return HARNESS_AUTH[agent].login.join(' ');
 }
-/**
- * Exact action shown beside a non-live account. Every emitted command exists
- * today — never a planned surface and never a hidden verb:
- * - Per-device harnesses (kimi/antigravity) repair on the box itself: run the
- *   harness there (`loginHint`) and complete its native login.
- * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
- *   A known account with no slot on a headed device is onboarded with
- *   `agents accounts add <harness> <name>`. A worker never runs an
- *   interactive login — the hint is `add.ts`'s worker refusal (add on the
- *   personal device; this box is provisioned from the durable credential).
- * - Unnamed legacy homes use the same version-targeted command shape as
- *   doctor, so the hint never logs a different/default home in by accident.
- * - `unverified` / `no_evidence` emit nothing: the probe could not confirm state
- *   (codex/grok have no probe endpoint; a worker's token lacks the usage scope),
- *   so there is nothing to repair.
- */
 export function fixFor(input) {
     const { agent, verdict } = input;
-    // `no_evidence` (credential present, nothing probed/run here yet) is benign like
-    // `unverified` — there is nothing to repair (PHNX-4116).
     if (verdict === 'live' || verdict === 'rate_limited' || verdict === 'unverified' || verdict === 'no_evidence' || verdict === 'ready')
         return null;
     if (input.provisioning === 'per-device' || verdict === 'per-device') {
@@ -97,37 +47,6 @@ export function fixFor(input) {
         return `agents run ${agent}@${version} -- ${sub}`;
     return `agents run ${agent}@${version}`;
 }
-/**
- * Whether `agents run` should probe login state before launching. True only for
- * a launch that actually opens the interactive TUI — where discovering a logged-out
- * account after the fact wastes time. Suppressed when there is no preamble surface
- * (`--json`/`--quiet`), when the check is explicitly disabled
- * (`--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`), or when a rotation already picked a
- * signed-in account.
- *
- * `forceInteractive` is load-bearing: a resume of a non-native-resume agent
- * (`agents run kimi --resume`, also grok/opencode/gemini) rewrites the prompt to
- * `/continue <id>` — so `hasPrompt` is true even though the run still opens the TUI.
- * Keying only off `hasPrompt` would silently skip the warning on exactly those
- * agents (the ones the feature is for), so the resume's `forceInteractive` flag is
- * consulted directly.
- */
-/**
- * Is a Claude run on this box going to authenticate from an ambient
- * `CLAUDE_CODE_OAUTH_TOKEN` rather than a per-version login?
- *
- * `AccountInfo.signedIn` is `!!email` read from a version home's `.claude.json`
- * (agents.ts), so a version with no account written there reports signed-out —
- * even though Claude Code authenticates fine from the env token and the run
- * succeeds. Rendering that as "logged out" sends people hunting a login that is
- * not missing (a real fleet incident: every version on a box read as locked out
- * while all of them answered a live prompt).
- *
- * It is also the more useful warning: an ambient token is ONE account, so every
- * version on the box resolves to it and balanced rotation across them rotates
- * nothing. `env` is a parameter so the branch is testable without mutating the
- * process environment.
- */
 export function ambientClaudeToken(agentId, env = process.env) {
     return agentId === 'claude' && (env.CLAUDE_CODE_OAUTH_TOKEN ?? '').trim().length > 0;
 }
@@ -136,11 +55,6 @@ export function shouldCheckLoginBeforeLaunch(o) {
         return false;
     return o.interactive === true || o.forceInteractive === true || (!o.hasPrompt && o.headless !== true);
 }
-/**
- * Colored `✓ signed in <account>` / `✗ logged out` badge. When signed in and an
- * account label is derivable (email, else an account id), it is appended in cyan;
- * opaque-credential agents with no email still read as signed in.
- */
 export function formatSignInBadge(info) {
     if (!info?.signedIn)
         return chalk.red('✗ logged out');

package/dist/lib/sink-format.d.ts

@@ -1,34 +1,2 @@
-/**
- * How loudly a destination can render a link — the one decision that shapes the
- * shared owner/broadcast `{message}` per channel (PHNX-3698).
- *
- *   - `mrkdwn` — Slack, which renders `<url|label>` as blue tappable text. The
- *     session crumb and every ticket key the prose NAMES become inline labeled
- *     links, so nothing rides a trailing naked-URL line.
- *   - `plain` — iMessage, the owner-scoped rush message, a spawned `command:`
- *     sink, desktop banners: none can render a labeled link and a dumped naked
- *     URL reads as noise, so the message stays the human sentence with no URLs.
- *
- * The default is `plain`; only Slack opts into `mrkdwn`.
- *
- * This lives in its own tiny module because both the feed broadcast fan-out
- * (`feed-broadcast.ts`) and the owner delivery fan-out (`notify.ts`) key on it,
- * and those two modules already import each other — a shared symbol here keeps
- * the format decision a single source of truth without a circular import.
- */
 export type SinkMessageFormat = 'plain' | 'mrkdwn';
-/**
- * Only Slack renders `<url|label>`, so it is the one format that gets labeled
- * links. iMessage / owner-scoped rush / command / desktop sinks stay `plain`
- * (they can't turn `claude/6fc1db18` blue, and dumping the raw URL is worse than
- * leaving the crumb unlinked — PHNX-3698).
- *
- * The argument is the **resolved provider name**, not a sink's declared channel:
- * an operator can point an arbitrary channel name at the Slack provider through
- * `notify.transports` (e.g. `eng-alerts -> slack`), and delivery keys off that
- * resolved provider (`lookupTransport`), so the format decision must too —
- * otherwise an aliased Slack sink would compose plain while delivering to Slack,
- * or a name remapped AWAY from Slack would emit `<url|label>` markup a non-Slack
- * transport shows literally.
- */
 export declare function sinkMessageFormat(provider: string | undefined): SinkMessageFormat;

package/dist/lib/sink-format.js

@@ -1,17 +1,3 @@
-/**
- * Only Slack renders `<url|label>`, so it is the one format that gets labeled
- * links. iMessage / owner-scoped rush / command / desktop sinks stay `plain`
- * (they can't turn `claude/6fc1db18` blue, and dumping the raw URL is worse than
- * leaving the crumb unlinked — PHNX-3698).
- *
- * The argument is the **resolved provider name**, not a sink's declared channel:
- * an operator can point an arbitrary channel name at the Slack provider through
- * `notify.transports` (e.g. `eng-alerts -> slack`), and delivery keys off that
- * resolved provider (`lookupTransport`), so the format decision must too —
- * otherwise an aliased Slack sink would compose plain while delivering to Slack,
- * or a name remapped AWAY from Slack would emit `<url|label>` markup a non-Slack
- * transport shows literally.
- */
 export function sinkMessageFormat(provider) {
     return provider?.trim().toLowerCase() === 'slack' ? 'mrkdwn' : 'plain';
 }

package/dist/lib/smart-launch.d.ts

@@ -1,10 +1,3 @@
-/**
- * Device placement for `--device auto`.
- *
- * Explicit auto placement probes live fleet health and harness readiness.
- * Historical affinity remains for generic host resolution callers.
- * Account selection is separate (`--strategy balanced` / rotate.ts).
- */
 import { type AffinityRow } from './session/db.js';
 import { type DevicePlacementSignal } from './teams/scheduler.js';
 import type { AgentType } from './teams/agents.js';
@@ -13,57 +6,24 @@ export interface WeightedCandidate {
     launches: number;
     weight: number;
 }
-/**
- * Convert affinity rows into positive weights: launches^α (floor 1 for any
- * row with launches > 0 so a single-use host still participates).
- */
 export declare function affinityWeights(rows: AffinityRow[], alpha?: number): WeightedCandidate[];
-/**
- * Weighted random sample. Returns null when candidates is empty.
- * Pure — inject `rng` for tests.
- */
 export declare function sampleWeighted(candidates: WeightedCandidate[], rng?: () => number): string | null;
-/**
- * Online device names from the local registry (+ local), narrowed to the
- * automatic-placement pool.
- *
- * The pool rule lives in `devices/pool.ts` and is an allowlist once any device
- * is marked `role=worker`: this is the single place both automatic-placement
- * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
- * marking workers moves every `--device auto` at once instead of one surface.
- *
- * It CAN return an empty list — a fleet where every marked worker is
- * offline, or where this box is the only candidate and is marked `personal`. That is a
- * real answer, and both callers fail loud on it rather than falling back to the
- * local machine (which would be the exact box the operator marked personal to
- * keep agents off).
- */
 export declare function listOnlineDeviceNames(localName?: string): string[];
 interface DeviceAffinityOptions {
     sinceDays?: number;
     alpha?: number;
-    /**
-     * Eligible hosts (normalized). Defaults to the automatic-placement pool
-     * (online devices + local, narrowed by device roles). An explicitly empty
-     * list falls back to local — the caller supplied it; an empty DEFAULT pool
-     * throws, because roles emptied it on purpose.
-     */
     eligibleHosts?: string[];
     localMachine?: string;
-    /** Injected affinity (tests). When omitted, reads sessions.db. */
     deviceAffinity?: AffinityRow[];
     rng?: () => number;
     project?: string;
 }
 export interface DeviceAffinityPlan {
-    /** null means run locally (do not pass --device). */
     host: string | null;
     deviceCandidates: WeightedCandidate[];
     pickedDeviceKey: string | null;
 }
-/** Live placement plan used by the explicit `--device auto` surface. */
 interface DeviceAutoPlan {
-    /** null means the local machine won the comparison. */
     host: string | null;
     candidates: Array<{
         key: string;
@@ -73,44 +33,16 @@ interface DeviceAutoPlan {
     }>;
     pickedDeviceKey: string;
 }
-/**
- * The error both automatic-placement resolvers raise when device roles leave no
- * candidate at all. Fail loud: the alternative — quietly running on the local
- * machine — puts the agent on the box the operator marked `personal`.
- */
 export declare function formatEmptyAutoPoolError(): string;
 export declare function formatNoHealthyDeviceError(pool: string[], signals: Map<string, DevicePlacementSignal>, agent?: string): string;
-/**
- * Pick the least-loaded healthy device that can run `agent` when the harness is
- * known. `run auto` omits the agent and treats any ready account on the device
- * as eligible. The local machine participates in the
- * same probe and must pass the same eligibility checks. An empty eligible pool
- * fails loud; automatic placement never silently becomes a local launch.
- */
 export declare function resolveDeviceAuto(agent?: string, opts?: {
     eligibleHosts?: string[];
     localMachine?: string;
-    /** Route only to devices with a row the interactive account picker can launch. */
     accountPicker?: boolean;
     probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
-    /**
-     * Preferred hosts (`auto-launch.preferred`) that get the ranking boost.
-     * Defaults to the stored fleet block resolved over the candidate pool;
-     * injectable so a test pins it without touching disk.
-     */
     preferred?: ReadonlySet<string>;
 }): Promise<DeviceAutoPlan>;
-/**
- * Resolve host for `--device auto`. Does NOT pick harness or accounts.
- *
- * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
- * `agents ssh auto`, the generic `--device auto` passthrough, and `matchHost`'s
- * `auto` sentinel honour device roles too. Throws when roles leave the pool
- * empty — a `null` host here means "run locally", which for a box marked
- * `personal` is the outcome the mark exists to prevent.
- */
 export declare function resolveDeviceAffinity(opts?: DeviceAffinityOptions): DeviceAffinityPlan;
-/** True when a host flag value means affinity pick. */
 export declare function isDeviceAuto(value: string | undefined | null): boolean;
 type DeviceAutoHostOptions = {
     host?: string;
@@ -121,20 +53,13 @@ type DeviceAutoHostOptions = {
     strategy?: string;
 };
 export type DeviceAutoApplyResult = {
-    /** True when automatic placement ran successfully. */
     attempted: boolean;
-    /** Present when affinity resolved without error. */
     banner?: {
         hostLabel: string;
         deviceHint: string;
         acctNote: string;
     };
 };
-/**
- * Apply `--device auto` onto run options.
- * Mutates `options` in place. Placement failures propagate without rewriting
- * `auto`, so callers fail loud instead of silently launching locally.
- */
 export declare function applyDeviceAutoToOptions(options: DeviceAutoHostOptions, deps?: {
     resolve?: (accountPicker: boolean) => DeviceAutoPlan | Promise<DeviceAutoPlan>;
     agent?: string;