@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/routine-readiness.js

@@ -1,14 +1,3 @@
-/**
- * Activation readiness for a routine, composed from the target-aware execution
- * context ({@link resolveJobExecutionContext}) plus the harness/target checks a
- * caller can perform on this box (agent installed). This is the gate `add`,
- * `edit`, `doctor`, and `resume` all run before activating a routine: ready →
- * active, any proven blocker → saved paused with a stable code + repair command.
- *
- * Structural context readiness is synchronous for the scheduler. Interactive
- * add/edit/doctor/resume additionally call the live variant below, which probes
- * authentication and Codex's native workspace-trust record before activation.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as TOML from 'smol-toml';
@@ -38,20 +27,8 @@ import { encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from '
 function fireBlockingAuthVerdict(verdict) {
     return verdict === 'revoked' || verdict === 'unconfigured';
 }
-/**
- * Fire-time auth preflight: read the daemon-warmed auth-health cache for the
- * exact (agent, version) a routine has resolved to run, and return an
- * `agent_auth_failed` blocker when that account is provably signed out — so the
- * daemon records a terminal `blocked` run (with the re-login repair) instead of
- * spawning a doomed run that 401s and burns a session (PHNX-3415).
- *
- * Cache-only (no network, no prompt — the daemon refreshes the cache
- * periodically and `fleet ping` writes it), and fails OPEN on a missing or
- * non-blocking verdict so a stale/absent probe never wedges a routine. It is
- * checked AFTER version rotation resolves the account (`launch.chain[0]`), so it
- * judges the identity the run will actually use, never a rotated-past dead pin.
- */
 export function fireTimeAuthReadiness(agent, version) {
+    // Fire-time auth is cache-only and fail-open unless the last verdict proves signed-out/revoked.
     const health = readAuthHealth(machineId(), agent, version);
     if (!health || !fireBlockingAuthVerdict(health.verdict))
         return null;
@@ -62,38 +39,23 @@ export function fireTimeAuthReadiness(agent, version) {
         repair: `agents run ${agent}@${version} -- login`,
     };
 }
-/**
- * Evaluate whether a routine is ready to activate on this box. `probeAgent`
- * defaults to "is a version of the routine's agent resolvable" via
- * {@link resolveVersion}; pass a stub in tests to exercise the availability path
- * without an installed harness.
- */
 export function evaluateActivationReadiness(config, deps = {}) {
     const strategy = resolveHostStrategy(config);
     const mode = strategy;
-    // Local placement inspects this box's filesystem; a remote/cloud target defers
-    // existence (its filesystem is unreachable here) and checks portability only.
     const context = resolveJobExecutionContext(config, {
         mode,
         probe: mode === 'local' ? undefined : null,
     });
-    // A pinned version on LOCAL placement must exist here — accepting a routine
-    // whose exact pin is absent just moves the failure to fire time (RUSH-2719).
-    // Remote host/fleet targets defer the check: their installs are unreachable
-    // from this box until the RUSH-2290 execution-context-on-target resolver.
     const pinnedLocally = mode === 'local' ? config.version : undefined;
     const probeAgent = deps.probeAgent ?? ((agent) => pinnedLocally
         ? isVersionInstalled(agent, pinnedLocally)
         : resolveVersion(agent) !== undefined);
     return evaluateRoutineReadiness(context, {
-        // Command routines have no agent to install; workflow routines dispatch
-        // through `agents run` (claude under the hood) and are checked at run time.
         agentInstalled: config.agent && !config.workflow && !config.command
             ? () => probeAgent(config.agent)
             : undefined,
     }, { agent: config.agent, version: pinnedLocally });
 }
-/** Parse the target HOME sentinel and the project catalog returned by one SSH call. */
 export function parseRemoteProjectSnapshot(stdout) {
     const lines = stdout.split(/\r?\n/);
     const homeLine = lines.shift();
@@ -115,7 +77,6 @@ export function parseRemoteProjectSnapshot(stdout) {
         return undefined;
     }
 }
-/** Build a target-native probe that creates and removes a file in the workspace. */
 export function buildRemoteWorkspaceProbe(cwd, windows) {
     if (windows) {
         return `powershell -NoProfile -EncodedCommand ${encodePowershell(`$d=${powershellQuote(cwd)}; if (-not (Test-Path -LiteralPath $d -PathType Container)) { exit 1 }; $p=Join-Path $d ([IO.Path]::GetRandomFileName()); try { New-Item -ItemType File -Path $p -ErrorAction Stop | Out-Null; Remove-Item -LiteralPath $p -Force -ErrorAction Stop; exit 0 } catch { exit 1 }`)}`;
@@ -123,7 +84,6 @@ export function buildRemoteWorkspaceProbe(cwd, windows) {
     const pattern = path.posix.join(cwd, '.agents-routine-readiness.XXXXXX');
     return `probe_path=$(mktemp ${shellQuote(pattern)}) && rm -f "$probe_path"`;
 }
-/** A successful probe must contain the exact requested postcondition, not merely exit zero. */
 export function probeOutputHasSentinel(stdout, sentinel) {
     const containsExact = (value) => {
         if (value === sentinel)
@@ -162,48 +122,19 @@ function codexWorkspaceTrusted(version, cwd) {
         return false;
     }
 }
-/**
- * Verdicts a routine's activation auth check accepts as usable. `no_evidence` is
- * here for robustness (a payload that still carries one), but a box that cannot
- * probe DROPS it in {@link probeLocalFleetAuth}, so the real path for those boxes
- * is the absent-row + launchability fallback in {@link decideRoutineAuthReadiness}
- * (PHNX-4116).
- */
 const ROUTINE_AUTH_ACCEPTED = new Set([
     'live', 'rate_limited', 'unverified', 'no_evidence',
 ]);
-/**
- * ONE decision the local ({@link evaluateActivationReadinessLive}) and host
- * ({@link evaluateHostActivationReadiness}) readiness paths share, so both reach
- * the SAME answer for the same box (PHNX-4116). `row` is that box's probe verdict
- * for the routine's agent — ABSENT when the box could not probe (a worker's
- * setup-token box, or a headed box that spent its hourly usage-endpoint budget,
- * both drop `no_evidence` in `probeLocalFleetAuth`). `launchable` is whether the
- * box holds a launchable signed-in credential, from the SAME
- * `collectRunCandidates`/`isLaunchableSignedIn` the run router uses — so a
- * token-backed routine on a box that cannot probe stays activatable, a box with
- * no credential at all fails `unconfigured`, and a server rejection (`revoked` —
- * the only present-but-not-accepted verdict these force-probed paths produce)
- * blocks regardless of a token on disk.
- */
 export function decideRoutineAuthReadiness(row, launchable) {
+    // Local and remote probes share absent-row semantics: launchability proves token-backed readiness.
     if (row && ROUTINE_AUTH_ACCEPTED.has(row.verdict))
         return { ok: true };
     if (!row)
         return launchable ? { ok: true } : { ok: false, reason: 'unconfigured' };
     return { ok: false, reason: row.verdict };
 }
-/**
- * Decide a host-placed routine's auth readiness from the REMOTE box's `devices
- * ping --local --json` payload (PHNX-4116). Pure over the payload TEXT so it is
- * unit-tested without SSH: it finds this agent's probe row (ABSENT when the box
- * dropped its `no_evidence` row) and reads the box's per-agent launchability the
- * ping now carries, then runs {@link decideRoutineAuthReadiness} — so a host box
- * that could not probe but holds a token is ready, exactly as the local path
- * decides for the same box. Returns null when the payload cannot be parsed; the
- * caller treats that as a probe failure, never as "no credential".
- */
 export function decideHostAuthFromPing(stdout, agent) {
+    // Unparseable output is a probe failure, never evidence that a credential is absent.
     let payload;
     try {
         payload = JSON.parse(stdout);
@@ -218,11 +149,6 @@ export function decideHostAuthFromPing(stdout, agent) {
     const row = verdict ? { verdict } : undefined;
     return decideRoutineAuthReadiness(row, launchable?.includes(agent) ?? false);
 }
-/**
- * Interactive setup/repair readiness. Unlike the scheduler's deterministic
- * structural gate, this completes a real local auth request and reads Codex's
- * native trust record before add/edit/resume can activate the definition.
- */
 export async function evaluateActivationReadinessLive(config) {
     const structural = evaluateActivationReadiness(config);
     if (!structural.ready)
@@ -236,9 +162,6 @@ export async function evaluateActivationReadinessLive(config) {
     if (!version)
         return structural;
     const context = resolveJobExecutionContext(config, { mode: 'local' });
-    // The probe row (absent when this box could not probe — a worker's setup-token
-    // box drops `no_evidence`) plus the run-router launchability, run through the
-    // ONE decision the host path also uses so both agree for the same box.
     const rows = await probeLocalFleetAuth({ agents: [config.agent] });
     const row = rows.find((candidate) => candidate.version === version);
     const { collectRunCandidates } = await import('./accounting/rotate.js');
@@ -252,7 +175,6 @@ export async function evaluateActivationReadinessLive(config) {
         authOk: () => authVerdict,
     }, { agent: config.agent });
 }
-/** Resolve and probe the actual SSH target used by a host-placed routine. */
 export async function evaluateHostActivationReadiness(config) {
     const host = await resolveHostRunTarget(config.host);
     const target = sshTargetFor(host);
@@ -296,6 +218,7 @@ export async function evaluateHostActivationReadiness(config) {
             } });
     }
     if (config.agent && !config.workflow && !config.command) {
+        // A failed live probe stays distinct from an absent auth row.
         if (config.agent === 'codex') {
             const args = ['run', 'codex', 'Reply with exactly ROUTINE_READY', '--mode', 'plan', '--timeout', '45s', '--json'];
             const command = windows
@@ -316,11 +239,6 @@ export async function evaluateHostActivationReadiness(config) {
                 ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`${POWERSHELL_PROGRESS_SILENCE}; & agents ${pingArgs.map(powershellQuote).join(' ')}`)}`
                 : `agents ${pingArgs.map(shellQuote).join(' ')}`;
             const probe = sshExec(target, command, { timeoutMs: 30_000, extraSshArgs: identity });
-            // A ping that could not run or parse is a probe FAILURE, never mistaken for
-            // "no credential": block with the failure so the operator sees it. A parsed
-            // payload runs the shared decision — an ABSENT row (the remote dropped its
-            // `no_evidence`) plus the launchability the ping now carries is ready,
-            // exactly as the local path decides for the same box (PHNX-4116).
             const decision = probe.code === 0 ? decideHostAuthFromPing(probe.stdout, config.agent) : null;
             if (!decision) {
                 return evaluateRoutineReadiness(unprobed, {

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

@@ -1,46 +1,6 @@
-/**
- * Pure display helpers for `agents routines list`.
- *
- * No external dependencies. All functions are pure (no I/O, no side effects).
- */
-/**
- * Convert a cron expression to a human-readable phrase.
- *
- * Handles the common patterns. For anything unrecognized, returns the raw
- * expression so the user still sees something useful. NEVER throws.
- */
 export declare function humanizeCron(expr: string, _tz?: string): string;
-/**
- * Convert a next-run Date into a human phrase relative to `now`.
- *
- * - null            → '-'
- * - same calendar day  → 'today 9:00 AM'
- * - next calendar day  → 'tomorrow 9:00 AM'
- * - within 7 days   → 'Mon 9:00 AM'
- * - further out      → 'Jun 15, 9:00 AM'
- */
 export declare function humanizeNextRun(date: Date | null, now: Date, tz?: string): string;
-/**
- * Maximum display length for a repo cell. Display strings longer than this
- * are truncated with an ellipsis so column alignment is preserved.
- * Consumers that render the column should use this constant as the column width.
- */
 export declare const REPO_DISPLAY_MAX = 24;
-/**
- * Parse a repo string into a display label and an optional hyperlink target.
- *
- * Rules:
- *   - null / undefined / empty / non-string → display '-', href null
- *   - 'owner/name' (one slash)              → display 'owner/name', href 'https://github.com/owner/name/pulls'
- *   - 'https://...' or 'http://...'         → display hostname+path, href the URL verbatim
- *   - anything else                         → display raw string, href null
- *
- * The display string is truncated to REPO_DISPLAY_MAX characters (with a
- * trailing '…') when it would otherwise exceed the column width. The href
- * is always the full untruncated URL so hyperlinks remain functional.
- *
- * NEVER throws — mirrors the contract of humanizeCron.
- */
 export declare function formatRepoLink(repo: unknown): {
     display: string;
     href: string | null;

package/dist/lib/routines-format.js

@@ -1,67 +1,44 @@
-/**
- * Pure display helpers for `agents routines list`.
- *
- * No external dependencies. All functions are pure (no I/O, no side effects).
- */
-// ---------------------------------------------------------------------------
-// humanizeCron
-// ---------------------------------------------------------------------------
 const DAY_NAMES = ['Sundays', 'Mondays', 'Tuesdays', 'Wednesdays', 'Thursdays', 'Fridays', 'Saturdays'];
-/**
- * Convert a cron expression to a human-readable phrase.
- *
- * Handles the common patterns. For anything unrecognized, returns the raw
- * expression so the user still sees something useful. NEVER throws.
- */
 export function humanizeCron(expr, _tz) {
     try {
         const parts = expr.trim().split(/\s+/);
         if (parts.length !== 5)
             return expr;
         const [minute, hour, dom, month, dow] = parts;
-        // every minute: * * * * *
         if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
             return 'every minute';
         }
-        // every N minutes: */N * * * *
         const everyMinMatch = minute.match(/^\*\/(\d+)$/);
         if (everyMinMatch && hour === '*' && dom === '*' && month === '*' && dow === '*') {
             const n = parseInt(everyMinMatch[1], 10);
             return `every ${n} minute${n === 1 ? '' : 's'}`;
         }
-        // every N hours: 0 */N * * *
         const everyHourMatch = hour.match(/^\*\/(\d+)$/);
         if (everyHourMatch && minute === '0' && dom === '*' && month === '*' && dow === '*') {
             const n = parseInt(everyHourMatch[1], 10);
             return `every ${n} hour${n === 1 ? '' : 's'}`;
         }
-        // Only proceed with time-of-day patterns when hour and minute are fixed integers
         const hourNum = /^\d+$/.test(hour) ? parseInt(hour, 10) : null;
         const minNum = /^\d+$/.test(minute) ? parseInt(minute, 10) : null;
         if (hourNum === null || minNum === null)
             return expr;
         const timeStr = formatTime12(hourNum, minNum);
-        // daily at HH:MM: M H * * *
         if (dom === '*' && month === '*' && dow === '*') {
             return `daily at ${timeStr}`;
         }
-        // weekdays: M H * * 1-5
         if (dom === '*' && month === '*' && dow === '1-5') {
             return `weekdays at ${timeStr}`;
         }
-        // specific day of week: M H * * D  (single digit 0-6)
         if (dom === '*' && month === '*' && /^\d$/.test(dow)) {
             const dayIdx = parseInt(dow, 10);
             if (dayIdx >= 0 && dayIdx <= 6) {
                 return `${DAY_NAMES[dayIdx]} at ${timeStr}`;
             }
         }
-        // specific day of month: M H D * *
         if (/^\d+$/.test(dom) && month === '*' && dow === '*') {
             const d = parseInt(dom, 10);
             return `monthly on day ${d} at ${timeStr}`;
         }
-        // every N hours with fixed minute: M */N * * *  (already handled above for M=0; catch M != 0)
         if (everyHourMatch && dom === '*' && month === '*' && dow === '*') {
             const n = parseInt(everyHourMatch[1], 10);
             return `every ${n} hour${n === 1 ? '' : 's'} at :${String(minNum).padStart(2, '0')}`;
@@ -72,34 +49,20 @@ export function humanizeCron(expr, _tz) {
         return expr;
     }
 }
-/** Format an hour (0-23) + minute (0-59) as "H:MM AM/PM". */
 function formatTime12(hour, minute) {
     const period = hour < 12 ? 'AM' : 'PM';
     const h = hour % 12 === 0 ? 12 : hour % 12;
     const m = String(minute).padStart(2, '0');
     return `${h}:${m} ${period}`;
 }
-// ---------------------------------------------------------------------------
-// humanizeNextRun
-// ---------------------------------------------------------------------------
 const WEEKDAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
 const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-/**
- * Convert a next-run Date into a human phrase relative to `now`.
- *
- * - null            → '-'
- * - same calendar day  → 'today 9:00 AM'
- * - next calendar day  → 'tomorrow 9:00 AM'
- * - within 7 days   → 'Mon 9:00 AM'
- * - further out      → 'Jun 15, 9:00 AM'
- */
 export function humanizeNextRun(date, now, tz) {
     if (!date)
         return '-';
     try {
         const locale = 'en-US';
         const tzOpts = tz ? { timeZone: tz } : {};
-        // Extract calendar date components for both dates using the same timezone.
         const toYMD = (d) => {
             const fmt = new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'numeric', day: 'numeric', ...tzOpts });
             const parts = fmt.formatToParts(d);
@@ -108,11 +71,9 @@ export function humanizeNextRun(date, now, tz) {
         };
         const nowYMD = toYMD(now);
         const dateYMD = toYMD(date);
-        // Diff in whole calendar days (ignoring time-of-day)
         const nowMidnight = Date.UTC(nowYMD.y, nowYMD.m - 1, nowYMD.day);
         const dateMidnight = Date.UTC(dateYMD.y, dateYMD.m - 1, dateYMD.day);
         const diffDays = Math.round((dateMidnight - nowMidnight) / 86400000);
-        // Time string for the date
         const timeFmt = new Intl.DateTimeFormat(locale, { hour: 'numeric', minute: '2-digit', hour12: true, ...tzOpts });
         const timeStr = timeFmt.format(date);
         if (diffDays === 0)
@@ -125,7 +86,6 @@ export function humanizeNextRun(date, now, tz) {
                 .find((p) => p.type === 'weekday')?.value;
             return `${weekdayIdx ?? WEEKDAY_NAMES[date.getDay()]} ${timeStr}`;
         }
-        // Further out: "Jun 15, 9:00 AM"
         const monthName = MONTH_NAMES[dateYMD.m - 1];
         return `${monthName} ${dateYMD.day}, ${timeStr}`;
     }
@@ -133,30 +93,7 @@ export function humanizeNextRun(date, now, tz) {
         return date.toLocaleString();
     }
 }
-// ---------------------------------------------------------------------------
-// formatRepoLink
-// ---------------------------------------------------------------------------
-/**
- * Maximum display length for a repo cell. Display strings longer than this
- * are truncated with an ellipsis so column alignment is preserved.
- * Consumers that render the column should use this constant as the column width.
- */
 export const REPO_DISPLAY_MAX = 24;
-/**
- * Parse a repo string into a display label and an optional hyperlink target.
- *
- * Rules:
- *   - null / undefined / empty / non-string → display '-', href null
- *   - 'owner/name' (one slash)              → display 'owner/name', href 'https://github.com/owner/name/pulls'
- *   - 'https://...' or 'http://...'         → display hostname+path, href the URL verbatim
- *   - anything else                         → display raw string, href null
- *
- * The display string is truncated to REPO_DISPLAY_MAX characters (with a
- * trailing '…') when it would otherwise exceed the column width. The href
- * is always the full untruncated URL so hyperlinks remain functional.
- *
- * NEVER throws — mirrors the contract of humanizeCron.
- */
 export function formatRepoLink(repo) {
     if (repo == null || typeof repo !== 'string' || repo.trim() === '') {
         return { display: '-', href: null };
@@ -164,7 +101,6 @@ export function formatRepoLink(repo) {
     const trimmed = repo.trim();
     let display;
     let href;
-    // Absolute URL
     if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
         try {
             const url = new URL(trimmed);
@@ -177,16 +113,13 @@ export function formatRepoLink(repo) {
         }
     }
     else if (/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(trimmed)) {
-        // GitHub shorthand: owner/name (exactly one slash, no scheme, no extra slashes)
         display = trimmed;
         href = `https://github.com/${trimmed}/pulls`;
     }
     else {
-        // Anything else: plain text, no link
         display = trimmed;
         href = null;
     }
-    // Truncate display to column width; href stays untruncated.
     if (display.length > REPO_DISPLAY_MAX) {
         display = display.slice(0, REPO_DISPLAY_MAX - 1) + '…';
     }

package/dist/lib/routines-placement.d.ts

@@ -1,14 +1,3 @@
-/**
- * Runtime placement resolution for routines: local / host / fleet / cloud.
- *
- * The scheduler only decides *whether* this machine may fire the job
- * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
- * body runs* once it has been fired, using `hostStrategy`.
- *
- * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
- * fire. Cross-device double-fire is prevented by requiring a `devices` firing
- * pin for fleet/host/cloud strategies (applied at add/sync time).
- */
 import type { JobConfig } from './scheduling/routines.js';
 import { type DevicePlatform } from './devices/registry.js';
 export type PlacementTarget = {
@@ -19,29 +8,7 @@ export type PlacementTarget = {
 } | {
     mode: 'cloud';
 };
-/**
- * Pick one online fleet device for `hostStrategy: fleet`.
- *
- * Preference order:
- * 1. This machine, if online and eligible (avoids needless SSH)
- * 2. First eligible online device by name (stable / deterministic)
- *
- * `config.devices` is the *firing* allowlist only (which daemon may fire the
- * job). It is intentionally NOT used as an execution pool filter — otherwise
- * the double-fire pin (`devices: [self]`) would collapse fleet placement to
- * always-local. Offline / no-address devices are never chosen.
- */
 export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>, platform?: DevicePlatform): string | null;
-/**
- * Resolve where a fired job's body should execute.
- * Throws a human-readable Error when placement cannot be satisfied.
- *
- * `host: 'auto'` under `hostStrategy: fleet` re-picks a healthy, signed-in,
- * unloaded device AT EACH FIRE via the same picker `agents run --device auto`
- * uses (`resolveDeviceAuto`), instead of `pickFleetDevice`'s
- * first-online-by-name order. The decision is deliberately not baked in at add
- * time — fleet health at fire time is the whole point (RUSH-2719).
- */
 export declare function resolvePlacementTarget(config: JobConfig, deps?: {
     resolveDeviceAuto?: (agent?: string) => Promise<{
         pickedDeviceKey: string;

package/dist/lib/routines-placement.js

@@ -1,30 +1,7 @@
-/**
- * Runtime placement resolution for routines: local / host / fleet / cloud.
- *
- * The scheduler only decides *whether* this machine may fire the job
- * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
- * body runs* once it has been fired, using `hostStrategy`.
- *
- * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
- * fire. Cross-device double-fire is prevented by requiring a `devices` firing
- * pin for fleet/host/cloud strategies (applied at add/sync time).
- */
 import { resolveHostStrategy } from './scheduling/routines.js';
 import { machineId, normalizeHost } from './machine-id.js';
 import { loadDevicesSync } from './devices/registry.js';
 import { planFleetTargets } from './devices/fleet.js';
-/**
- * Pick one online fleet device for `hostStrategy: fleet`.
- *
- * Preference order:
- * 1. This machine, if online and eligible (avoids needless SSH)
- * 2. First eligible online device by name (stable / deterministic)
- *
- * `config.devices` is the *firing* allowlist only (which daemon may fire the
- * job). It is intentionally NOT used as an execution pool filter — otherwise
- * the double-fire pin (`devices: [self]`) would collapse fleet placement to
- * always-local. Offline / no-address devices are never chosen.
- */
 export function pickFleetDevice(_config, platform) {
     let reg;
     try {
@@ -38,10 +15,6 @@ export function pickFleetDevice(_config, platform) {
         .filter((t) => !t.skip && (!platform || t.device.platform === platform))
         .map((t) => t.device.name);
     if (candidates.length === 0) {
-        // No registry / nothing online: fall back to self so a single-box fleet
-        // without a registry entry still runs locally. Only when no platform filter
-        // was requested — an unmet filter must fail loud so e.g. `fleet/linux` never
-        // silently lands on a macOS box.
         return platform ? null : machineId();
     }
     const self = machineId();
@@ -50,16 +23,6 @@ export function pickFleetDevice(_config, platform) {
         return selfMatch;
     return [...candidates].sort((a, b) => a.localeCompare(b))[0] ?? null;
 }
-/**
- * Resolve where a fired job's body should execute.
- * Throws a human-readable Error when placement cannot be satisfied.
- *
- * `host: 'auto'` under `hostStrategy: fleet` re-picks a healthy, signed-in,
- * unloaded device AT EACH FIRE via the same picker `agents run --device auto`
- * uses (`resolveDeviceAuto`), instead of `pickFleetDevice`'s
- * first-online-by-name order. The decision is deliberately not baked in at add
- * time — fleet health at fire time is the whole point (RUSH-2719).
- */
 export async function resolvePlacementTarget(config, deps = {}) {
     const strategy = resolveHostStrategy(config);
     switch (strategy) {
@@ -69,7 +32,6 @@ export async function resolvePlacementTarget(config, deps = {}) {
             if (!config.host || config.host.trim() === '') {
                 throw new Error(`Routine '${config.name}' has hostStrategy: host but no host: — set host: or --run-on`);
             }
-            // host: pointing at this machine is local execution (no SSH loop).
             if (normalizeHost(config.host) === machineId())
                 return { mode: 'local' };
             return { mode: 'host', host: config.host };
@@ -79,8 +41,6 @@ export async function resolvePlacementTarget(config, deps = {}) {
             if (config.host === 'auto') {
                 const resolveAuto = deps.resolveDeviceAuto
                     ?? (async (agent) => (await import('./smart-launch.js')).resolveDeviceAuto(agent));
-                // resolveDeviceAuto fails loud on an empty/unhealthy pool — surface its
-                // message (it names each excluded device) instead of a generic one.
                 const plan = await resolveAuto(config.agent);
                 picked = plan.pickedDeviceKey;
             }

package/dist/lib/routines-project.d.ts

@@ -1,25 +1,7 @@
-/**
- * Project routine discovery, source tracking, and user-layer sync.
- *
- * Project YAML under `<project>/.agents/routines/*.yml` never fires on its own
- * (a cloned repo must not auto-run agent prompts). A routine has exactly one
- * state — enabled or disabled — owned by this device's `meta.deviceRoutines`
- * list, never by the project YAML's own `enabled:` field. `agents routines
- * enable <name>` materialises the routine into `~/.agents/routines/` with
- * `source:` provenance (so the daemon, which loads only user + system layers,
- * can see it) and flips the device flag on — one action. `discoverProjectRoutines`
- * surfaces not-yet-materialised routines from the user's registered projects so
- * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
- * copies from their source YAML (also invoked on daemon SIGHUP).
- */
 import { type JobConfig } from './scheduling/routines.js';
-/** Expand `~/…` and resolve to an absolute path. */
 export declare function expandProjectPath(p: string): string;
-/** Store paths home-relative when under $HOME so they travel across machines. */
 export declare function displayProjectPath(abs: string): string;
-/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
 export declare function resolveProjectRoot(cwd?: string): string | null;
-/** List project routine YAML files (name + absolute path). */
 export declare function listProjectRoutineFiles(projectRoot: string): Array<{
     name: string;
     path: string;
@@ -37,67 +19,28 @@ interface SyncProjectResult {
         error: string;
     }>;
 }
-/**
- * Refresh one project's already-materialised routines from its source YAML.
- * - Overwrites user copies that already carry matching `source.projectPath`
- * - Never clobbers a hand-authored user routine (no source / different source)
- * - Removes user copies from this project whose YAML disappeared
- *
- * Sync NEVER touches the device enable flag: a routine's enabled/disabled state
- * is owned solely by `meta.deviceRoutines` (via `agents routines enable/disable`),
- * never by the project YAML's own `enabled:` field. That is what keeps a cloned
- * repo from auto-firing — refreshing a definition can never turn it on.
- */
 export declare function syncProjectRoutines(projectRoot: string): SyncProjectResult;
 export interface SyncAllResult {
     projects: SyncProjectResult[];
-    /** Project roots that were listed but missing on disk. */
     missing: string[];
 }
-/** Distinct project roots that already have at least one materialised routine. */
 export declare function materialisedProjectRoots(): string[];
-/**
- * Refresh every materialised project routine from its source YAML. The set of
- * roots is derived from what the user has already enabled/materialised (their
- * `source.projectPath`), not from any allowlist — enabling a routine is the only
- * thing that brings its project into the refresh set. Also runs on daemon SIGHUP.
- */
 export declare function syncAllProjectRoutines(opts?: {
     extraRoots?: string[];
 }): SyncAllResult;
-/** A project routine available to enable, not yet materialised on this device. */
 export interface DiscoveredProjectRoutine {
     name: string;
     projectRoot: string;
     file: string;
-    /** Display config for `list` (always disabled — enablement is a local act). */
     config: JobConfig;
 }
-/**
- * Project routines from registered projects that are NOT already materialised
- * in the user layer. These surface in `agents routines list` as disabled rows so
- * the single enabled/disabled model is visible, and `enable <name>` resolves a
- * name against them. A routine whose name already exists as a user/system
- * routine is omitted (that materialised copy is the live one).
- */
 export declare function discoverProjectRoutines(): DiscoveredProjectRoutine[];
-/**
- * Resolve a routine name to a project source for `enable <name>`: first the cwd
- * project, then registered projects. Returns null when the name matches no
- * project routine, or throws-by-return when it is ambiguous across projects.
- */
 export declare function findProjectRoutine(name: string, cwd?: string): {
     projectRoot: string;
     file: string;
 } | {
     ambiguous: string[];
 } | null;
-/**
- * Materialise one project routine into the user layer WITHOUT enabling it. The
- * caller (`agents routines enable`) flips the device flag separately, so a
- * materialise can never by itself make a routine fire. Returns the written
- * config, or an error string.
- */
 export declare function materialiseProjectRoutine(projectRoot: string, name: string): {
     job: JobConfig;
 } | {