@phnx-labs/agents-cli 1.22.31 → 1.22.32

package/dist/commands/routines.js

@@ -16,6 +16,7 @@ import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
 import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
+import { evaluateActivationReadinessLive } from '../lib/routine-readiness.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -724,6 +725,8 @@ export function registerRoutinesCommands(program) {
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .option('--project <name>', 'Associate with a named project (repeatable; use --all-projects for all)', collectProject, [])
         .option('--all-projects', 'Associate this routine with all defined projects (sets projects: ["*"])')
+        .option('--project-anchor <name>', 'Singular EXECUTION anchor: the named project whose base directory the run lands in (distinct from --project, which is grouping metadata). Rootless (Linear-imported) projects anchor a relative --cwd at the target home.')
+        .option('--cwd <path>', 'Portable execution directory. Relative values resolve under --project-anchor when usable, otherwise under the execution target $HOME. Supersedes --run-cwd/remoteCwd.')
         .option('--json', 'Emit machine-readable JSON with the created routine id and status')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
@@ -852,6 +855,8 @@ export function registerRoutinesCommands(program) {
                 ...(options.runOn ? { host: options.runOn } : {}),
                 ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
+                ...(options.projectAnchor ? { project: options.projectAnchor } : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
@@ -867,7 +872,23 @@ export function registerRoutinesCommands(program) {
                 process.exit(1);
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!devices || devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            // Readiness gate: a routine only activates when its execution context
+            // resolves and the harness is available. A proven blocker saves the
+            // definition PAUSED with a stable code + repair, so a broken routine can
+            // never fire (and storm) — the plan's save-paused contract.
+            const deviceMatch = !devices || devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready) {
+                const r = readiness.readiness;
+                if (!options.json) {
+                    console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                }
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -875,8 +896,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -933,7 +957,17 @@ export function registerRoutinesCommands(program) {
                 console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            const deviceMatch = !config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready && !options.json) {
+                const r = readiness.readiness;
+                console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                console.log(chalk.gray(`  ${r.message}`));
+                if (r.repair)
+                    console.log(chalk.gray(`  repair: ${r.repair}`));
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -941,8 +975,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -1029,7 +1066,8 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('edit [name]')
-        .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
+        .description('Edit a prefilled routine transactionally; invalid YAML never replaces the live definition.')
+        .option('--yaml', 'Open the raw YAML in $EDITOR (the current edit surface)')
         .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
         .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
         .action(async (name, options) => {
@@ -1048,53 +1086,55 @@ export function registerRoutinesCommands(program) {
                 existing.trigger.stateTo = options.stateTo || undefined;
             if (options.stateFrom !== undefined)
                 existing.trigger.stateFrom = options.stateFrom || undefined;
-            writeJob(existing);
         }
         const jobPath = getJobPath(name);
-        if (!jobPath) {
-            // Job doesn't exist - create a new one
-            const cronDir = getRoutinesDir();
-            const newPath = safeJoin(cronDir, `${name}.yml`);
-            // Create template
-            const template = yaml.stringify({
+        const cronDir = getRoutinesDir();
+        fs.mkdirSync(cronDir, { recursive: true });
+        const targetPath = jobPath || safeJoin(cronDir, `${name}.yml`);
+        const editPath = safeJoin(cronDir, `.${name}.edit-${process.pid}.yml`);
+        const initial = existing
+            ? yaml.stringify(existing)
+            : yaml.stringify({
                 name,
                 schedule: '0 9 * * *',
                 agent: 'claude',
                 prompt: 'Your prompt here',
             });
-            fs.writeFileSync(newPath, template, 'utf-8');
-            console.log(chalk.gray(`Created new job file: ${newPath}`));
-        }
-        const targetPath = jobPath || path.join(getRoutinesDir(), `${name}.yml`);
+        fs.writeFileSync(editPath, initial, { encoding: 'utf-8', mode: 0o600 });
         const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const editorParts = editor.split(/\s+/).filter(Boolean);
         const editorBin = editorParts[0];
-        const editorArgs = [...editorParts.slice(1), targetPath];
+        const editorArgs = [...editorParts.slice(1), editPath];
         const { spawn: spawnSync } = await import('child_process');
         const child = spawnSync(editorBin, editorArgs, {
             stdio: 'inherit',
         });
-        child.on('close', (code) => {
-            if (code === 0) {
-                // Validate the edited file
-                const job = readJob(name);
-                if (job) {
-                    const errors = validateJob(job);
-                    if (errors.length > 0) {
-                        console.log(chalk.yellow('\nWarning: Job has validation errors:'));
-                        for (const err of errors) {
-                            console.log(chalk.yellow(`  - ${err}`));
-                        }
-                    }
-                    else {
-                        console.log(chalk.green(`\nJob '${name}' saved`));
-                        if (isDaemonRunning()) {
-                            signalDaemonReload();
-                            console.log(chalk.gray('Daemon reloaded'));
-                        }
-                    }
+        child.on('close', async (code) => {
+            if (code !== 0) {
+                fs.rmSync(editPath, { force: true });
+                return;
+            }
+            try {
+                const raw = fs.readFileSync(editPath, 'utf-8');
+                const job = yaml.parse(raw);
+                const errors = validateJob(job);
+                if (errors.length > 0)
+                    throw new Error(errors.join('\n'));
+                const readiness = await evaluateActivationReadinessLive(job);
+                fs.renameSync(editPath, targetPath);
+                if (!readiness.ready)
+                    setJobEnabled(job.name, false);
+                console.log(chalk.green(`\nJob '${name}' saved${readiness.ready ? '' : ' paused (not ready)'}`));
+                if (isDaemonRunning()) {
+                    signalDaemonReload();
+                    console.log(chalk.gray('Daemon reloaded'));
                 }
             }
+            catch (err) {
+                fs.rmSync(editPath, { force: true });
+                console.error(chalk.red(`\nRoutine not saved: ${err.message}`));
+                process.exitCode = 1;
+            }
         });
     });
     routinesCmd
@@ -1498,6 +1538,79 @@ export function registerRoutinesCommands(program) {
         console.log(chalk.gray(`Run: ${runId}\n`));
         console.log(fs.readFileSync(reportPath, 'utf-8'));
     });
+    routinesCmd
+        .command('doctor [name]')
+        .description('Check a routine\'s execution-context and harness readiness. Bare or --all checks every routine; --fix applies safe activation repairs (activate a now-ready paused routine; pause a broken active one).')
+        .option('--all', 'Check every routine (the default when no name is given)')
+        .option('--fix', 'Apply safe, deterministic activation repairs')
+        .option('--json', 'Machine-readable output')
+        .action(async (name, options) => {
+        const all = options.all || !name;
+        let targets;
+        if (all) {
+            targets = listAllJobs();
+        }
+        else {
+            const job = readJob(name);
+            if (!job) {
+                if (options.json) {
+                    writeJson({ ok: false, error: `routine '${name}' not found` });
+                    return;
+                }
+                console.error(chalk.red(`Routine '${name}' not found`));
+                process.exit(1);
+            }
+            targets = [job];
+        }
+        const thisDevice = normalizeHost(machineId());
+        const results = await Promise.all(targets.map(async (job) => {
+            const deviceMatch = !job.devices || job.devices.map(normalizeHost).includes(thisDevice);
+            const readiness = await evaluateActivationReadinessLive(job);
+            // `job.enabled` reflects THIS device's activation state (applyDeviceActivation).
+            let action;
+            if (options.fix && deviceMatch) {
+                if (readiness.ready && !job.enabled) {
+                    setJobEnabled(job.name, true);
+                    action = 'activated';
+                }
+                else if (!readiness.ready && job.enabled) {
+                    setJobEnabled(job.name, false);
+                    action = 'paused';
+                }
+            }
+            return {
+                name: job.name,
+                ready: readiness.ready,
+                active: job.enabled,
+                deviceScoped: deviceMatch,
+                ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
+                ...(action ? { action } : {}),
+            };
+        }));
+        if (options.fix && results.some((r) => r.action) && isDaemonRunning()) {
+            signalDaemonReload();
+        }
+        if (options.json) {
+            writeJson({ ok: true, results });
+            return;
+        }
+        const blocked = results.filter((r) => !r.ready);
+        for (const r of results) {
+            if (r.ready) {
+                console.log(`${chalk.green('✓')} ${r.name}${r.action === 'activated' ? chalk.gray(' (activated)') : ''}`);
+            }
+            else {
+                const rd = r.readiness;
+                console.log(`${chalk.red('✗')} ${r.name} — ${chalk.yellow(rd.code)}${r.action === 'paused' ? chalk.gray(' (paused)') : ''}`);
+                console.log(chalk.gray(`    ${rd.message}`));
+                if (rd.repair)
+                    console.log(chalk.gray(`    repair: ${rd.repair}`));
+            }
+        }
+        if (blocked.length > 0 && !options.fix) {
+            console.log(chalk.gray(`\n${blocked.length} routine${blocked.length === 1 ? '' : 's'} blocked — re-run with --fix to pause them, or apply each repair above.`));
+        }
+    });
     routinesCmd
         .command('resume [name]')
         .description('Re-enable a paused routine so the daemon schedules it again')
@@ -1509,6 +1622,21 @@ export function registerRoutinesCommands(program) {
                 return;
         }
         try {
+            // Resume re-runs readiness — it can never bypass a proven blocker (the
+            // plan: "resume cannot bypass readiness"). A blocked routine stays paused.
+            const job = readJob(name);
+            if (job) {
+                const readiness = await evaluateActivationReadinessLive(job);
+                if (!readiness.ready) {
+                    const r = readiness.readiness;
+                    console.log(chalk.red(`Cannot resume '${name}' — not ready: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                    console.log(chalk.gray(`  fix it, then: agents routines doctor ${name} --fix`));
+                    process.exit(1);
+                }
+            }
             setJobEnabled(name, true);
             console.log(chalk.green(`Job '${name}' resumed`));
             if (isDaemonRunning()) {

package/dist/commands/sessions.d.ts

@@ -434,7 +434,7 @@ export interface RoutineChoice {
     latestRunSessionCount: number;
 }
 export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
-export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function buildRoutineChoices(sessions: SessionMeta[], runOnlyNames?: string[]): RoutineChoice[];
 export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */

package/dist/commands/sessions.js

@@ -43,6 +43,7 @@ import { sessionOwnerDevice, RESUME_PINNED_ENV } from '../lib/session/resume-own
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
+import { listJobs, listJobsWithRuns, listRuns } from '../lib/routines.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
@@ -1557,14 +1558,14 @@ export function buildRoutineRunGroups(sessions) {
     }))
         .sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : a.runId.localeCompare(b.runId)));
 }
-export function buildRoutineChoices(sessions) {
+export function buildRoutineChoices(sessions, runOnlyNames = []) {
     const byName = new Map();
     for (const session of sessions) {
         if (!session.routineName)
             continue;
         (byName.get(session.routineName) ?? byName.set(session.routineName, []).get(session.routineName)).push(session);
     }
-    return [...byName.entries()]
+    const choices = [...byName.entries()]
         .map(([name, rows]) => {
         const runs = buildRoutineRunGroups(rows);
         return {
@@ -1573,11 +1574,28 @@ export function buildRoutineChoices(sessions) {
             runCount: runs.length,
             latestRunSessionCount: runs[0].sessions.length,
         };
-    })
-        .sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
+    });
+    // Routines whose only attempts are pre-session (blocked/skipped/failed-before-
+    // spawn) have run records but no transcript. Surface them so the picker is
+    // built from definitions+runs, never only transcripts — otherwise a routine
+    // that has never produced a session reads as "No routines match" (the plan).
+    const seen = new Set(choices.map((c) => c.name));
+    for (const name of runOnlyNames) {
+        if (seen.has(name))
+            continue;
+        const runs = listRuns(name);
+        const latest = runs[runs.length - 1];
+        choices.push({
+            name,
+            lastRunAt: latest?.startedAt ?? '',
+            runCount: runs.length,
+            latestRunSessionCount: 0,
+        });
+    }
+    return choices.sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
 }
 async function selectRoutineName(sessions) {
-    const choices = buildRoutineChoices(sessions);
+    const choices = buildRoutineChoices(sessions, safeListJobsWithRuns());
     const picked = await itemPicker({
         message: 'Select a routine:',
         items: choices,
@@ -1590,7 +1608,8 @@ async function selectRoutineName(sessions) {
         labelFor: (choice) => {
             const runs = `${choice.runCount} run${choice.runCount === 1 ? '' : 's'}`;
             const sessions = `${choice.latestRunSessionCount} session${choice.latestRunSessionCount === 1 ? '' : 's'} in latest`;
-            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions} · ${formatRelativeTime(choice.lastRunAt)}`)}`;
+            const age = choice.lastRunAt ? ` · ${formatRelativeTime(choice.lastRunAt)}` : '';
+            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions}${age}`)}`;
         },
         shortIdFor: (choice) => choice.name,
         emptyMessage: 'No routines match.',
@@ -1598,8 +1617,22 @@ async function selectRoutineName(sessions) {
     });
     return picked?.item.name ?? null;
 }
+/** `listJobsWithRuns` but never throws into the sessions reader (best-effort). */
+function safeListJobsWithRuns() {
+    try {
+        return [...new Set([...listJobs().map((job) => job.name), ...listJobsWithRuns()])];
+    }
+    catch {
+        return [];
+    }
+}
 export async function filterSessionsByRoutine(sessions, routine, interactive) {
-    const routineNames = [...new Set(sessions.map((session) => session.routineName).filter((name) => !!name))].sort((a, b) => a.localeCompare(b));
+    // The name universe is transcripts UNION routines that have any run record —
+    // so a routine whose attempts never produced a session still resolves.
+    const routineNames = [...new Set([
+            ...sessions.map((session) => session.routineName).filter((name) => !!name),
+            ...safeListJobsWithRuns(),
+        ])].sort((a, b) => a.localeCompare(b));
     let selectedRoutine = null;
     if (typeof routine === 'string') {
         selectedRoutine = resolveRoutineName(routine, routineNames);
@@ -1616,9 +1649,10 @@ export async function filterSessionsByRoutine(sessions, routine, interactive) {
         if (!selectedRoutine)
             return null;
     }
-    return selectedRoutine
-        ? sessions.filter((session) => session.routineName === selectedRoutine)
-        : sessions;
+    if (!selectedRoutine)
+        return sessions;
+    const matched = sessions.filter((session) => session.routineName === selectedRoutine);
+    return matched;
 }
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -0,0 +1,148 @@
+import chalk from 'chalk';
+import { formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { describeInstallation, listInstallations, resolveInstallation, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+/**
+ * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
+ * label, or the release it currently carries — never a release to install; that
+ * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
+ * --to 2.0.71` read unambiguously.
+ */
+function parseTarget(raw) {
+    const at = raw.indexOf('@');
+    const name = at === -1 ? raw : raw.slice(0, at);
+    const selector = at === -1 ? undefined : raw.slice(at + 1).trim();
+    if (at !== -1 && !selector) {
+        throw new Error(`Missing installation in '${raw}'. Use <agent>@<installed-version>, or just <agent>.`);
+    }
+    const agent = resolveAgentName(name);
+    if (!agent)
+        throw new Error(formatAgentError(name));
+    return { agent, selector };
+}
+function serialize(installation) {
+    return {
+        id: installation.id,
+        agent: installation.agent,
+        label: installation.label,
+        releaseVersion: installation.releaseVersion,
+        createdAt: installation.createdAt,
+        updatedAt: installation.updatedAt,
+    };
+}
+function printOutcome(outcome, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            installation: serialize(outcome.installation),
+            strategy: outcome.strategy,
+            fromRelease: outcome.fromRelease,
+            toRelease: outcome.toRelease,
+            unchanged: outcome.unchanged,
+            alsoUpdated: outcome.alsoUpdated.map(serialize),
+        }, null, 2));
+        return;
+    }
+    const name = `${outcome.installation.agent}@${outcome.installation.label}`;
+    if (outcome.unchanged) {
+        console.log(chalk.gray(`${name} is already on release ${outcome.toRelease}.`));
+        return;
+    }
+    console.log(chalk.green(`Updated ${name}: release ${outcome.fromRelease} -> ${outcome.toRelease}`));
+    console.log(chalk.gray(`Its name is unchanged, so every default, project pin, and routine that names ${name} still resolves to it.`));
+    for (const other of outcome.alsoUpdated) {
+        console.log(chalk.gray(`  ${other.agent}@${other.label} shares the same binary and now also reports release ${other.releaseVersion}.`));
+    }
+}
+function printInstallations(agent, json) {
+    const installations = listInstallations(agent);
+    if (json) {
+        console.log(JSON.stringify(installations.map(serialize), null, 2));
+        return;
+    }
+    if (!installations.length) {
+        console.log(chalk.gray(`No managed ${agent} installations. Install one with: agents add ${agent}@latest`));
+        return;
+    }
+    console.log(chalk.bold(`${agent} installations\n`));
+    for (const installation of installations) {
+        console.log(`  ${chalk.cyan(installation.label)}  release ${installation.releaseVersion}  ${chalk.gray(installation.id)}`);
+    }
+}
+/**
+ * Surface a failure as one red line, not a stack trace. Everything this command
+ * can fail on — an unknown agent, an ambiguous selector, an unpinnable harness,
+ * a release that would not launch — is a message the user acts on, and a
+ * commander async action rejection otherwise reaches the user as a raw Node dump.
+ */
+function fail(err) {
+    console.error(chalk.red(err.message));
+    process.exitCode = 1;
+}
+export function registerUpdateCommand(program) {
+    const update = program
+        .command('update [target]')
+        .description('Move a frozen agent installation to a new release, keeping its name and every reference to it')
+        .option('--to <release>', 'Release to move to: latest (default), oldest, or an exact version')
+        .option('--account <label>', 'Disambiguate by signed-in account when several installations match')
+        .option('--json', 'Machine-readable result')
+        .action(async (target, options) => {
+        try {
+            if (!target) {
+                throw new Error('Which agent? Use: agents update <agent>[@<installed-version>]');
+            }
+            const { agent, selector } = parseTarget(target);
+            if (options.to && options.to !== 'latest' && !supportsPinnedUpdate(agent)) {
+                // Fail loud at the boundary rather than installing the current release
+                // and reporting it as the pin that was asked for.
+                throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
+            }
+            const installation = await resolveInstallation(agent, selector, { account: options.account });
+            const strategy = selectUpdateStrategy(agent);
+            if (!options.json && !strategy.transactional) {
+                console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
+                    + `a failure leaves whatever its installer wrote.`));
+            }
+            if (!options.json) {
+                console.log(chalk.gray(`Updating ${agent}@${describeInstallation(installation)} via the ${strategy.id} strategy...`));
+            }
+            const outcome = await updateInstallation(installation, {
+                to: options.to,
+                onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
+            });
+            printOutcome(outcome, !!options.json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    update
+        .command('list <agent>')
+        .description('Show every frozen installation of an agent and the release each carries')
+        .option('--json', 'Machine-readable listing')
+        // `--json` is declared on both `update` and `update list`, and commander
+        // binds a flag the parent also declares to the PARENT's option store — so
+        // reading this subcommand's own opts alone silently drops it. Merge them.
+        .action((rawAgent, _options, command) => {
+        try {
+            const agent = resolveAgentName(rawAgent);
+            if (!agent)
+                throw new Error(formatAgentError(rawAgent));
+            printInstallations(agent, !!command.optsWithGlobals().json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    setHelpSections(update, {
+        examples: `agents update list claude
+agents update claude@2.0.65
+agents update claude@2.0.65 --to 2.1.220
+agents update claude --account work
+agents update claude@2.0.65 --json`,
+        notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
+            + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
+            + 'The selector matches either the installation name or the release it currently carries — when two installations '
+            + 'share a release, name one or pass --account <label> (see: agents accounts). '
+            + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running.',
+    });
+}

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadUpdate, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -292,6 +292,7 @@ Quick start:
 Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add grok or agents add codex)
   import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
+  update <agent>[@version]        Move an installed agent to a new release, keeping its name (agents-cli itself is 'agents upgrade')
   prune <agent>[@version]         Uninstall a version
   remove <agent>[@version]        Alias for prune
   use <agent>@<version>           Set the default version
@@ -942,6 +943,7 @@ async function registerAllEagerCommands() {
     await reg(loadWorkflows);
     await reg(loadWorktree);
     await reg(loadVersions);
+    await reg(loadUpdate);
     await reg(loadImport);
     await reg(loadExport);
     await reg(loadPackages);

package/dist/lib/catchup.js

@@ -139,7 +139,10 @@ export async function runCatchup(opts = {}) {
             continue;
         }
         try {
-            const meta = await executeJobDetached(config);
+            // No `scheduledFor` here on purpose: the missed slot is already claimed by
+            // `claimMissedFire` above (its atomic mkdir IS the catch-up single-fire), so
+            // the late run gets a fresh id rather than colliding with the missed record.
+            const meta = await executeJobDetached(config, undefined, { kind: 'catchup' });
             outcomes.push({
                 name: entry.name,
                 expectedAt: entry.expectedAt,

package/dist/lib/daemon.d.ts

@@ -273,6 +273,23 @@ export interface DaemonStopResult {
     surviving: string[];
     detachedChildren: number[];
 }
+/**
+ * Live `__daemon-run` processes still registered in THIS state dir's instance
+ * registry, excluding `exclude`. State-dir-scoped by construction: the registry
+ * lives inside this daemon dir, so a daemon serving a DIFFERENT state dir (a test
+ * fixture with its own HOME, a separate install/home) registers elsewhere and is
+ * invisible here — it is never a stop/takeover target. POSIX-only (the registry
+ * and its `ps` liveness probe are); `[]` on Windows.
+ *
+ * Exported for `agents daemon status`/`doctor`/`services` (RUSH-2368): those
+ * commands previously flagged every `__daemon-run` on the box (a raw `ps` scan)
+ * as a "duplicate" of this daemon, which misreported test fixtures under their
+ * own HOME — and therefore their own state dir and registry — as strays to
+ * kill. This registry read is the same scope the reaper (`reapStrayDaemons`)
+ * and the stop postcondition (`stopDaemon`) already use, so the display and the
+ * reaper agree on what a duplicate is.
+ */
+export declare function findSurvivingStateDirDaemons(exclude: Set<number>): number[];
 /**
  * Stop the daemon and ASSERT its postcondition (SING-12, RUSH-2355), unloading it
  * from launchd/systemd if applicable.