@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/routines.js

@@ -10,14 +10,14 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, } from '../lib/daemon.js';
 import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
 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 { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, isCanonicalRoutineSource, 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 { discoverProjectRoutines, findProjectRoutine, materialiseProjectRoutine, syncProjectRoutines, syncAllProjectRoutines, displayProjectPath, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -27,6 +27,8 @@ import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { runCatchup } from '../lib/catchup.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
+import { itemPicker } from '../lib/picker.js';
+import { Separator } from '@inquirer/core';
 import { setHelpSections } from '../lib/help.js';
 import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
@@ -409,12 +411,30 @@ export function buildRunsJson(runs) {
 }
 /** Build the exact structured routine rows shared by `routines list --json`
  * and the one-process AGI Menu snapshot. */
+/**
+ * Materialised routines plus project routines discoverable from registered
+ * projects, deduped by name. The discovered ones are always disabled (available
+ * to enable) — this is a DISPLAY-only merge, so `list` shows the full single
+ * enabled/disabled picture. Execution paths (`run`/`catchup`/`webhook`) keep
+ * using `listAllJobs` so an un-materialised project routine can never fire.
+ */
+function listJobsForDisplay(cwd) {
+    const jobs = listAllJobs(cwd);
+    const seen = new Set(jobs.map((j) => j.name));
+    for (const discovered of discoverProjectRoutines()) {
+        if (seen.has(discovered.name))
+            continue;
+        seen.add(discovered.name);
+        jobs.push(discovered.config);
+    }
+    return jobs;
+}
 export function buildRoutineListJson() {
     try {
         monitorRunningJobs();
     }
     catch { /* best-effort orphan reap */ }
-    const jobs = listAllJobs(process.cwd());
+    const jobs = listJobsForDisplay(process.cwd());
     if (jobs.length === 0)
         return [];
     const scheduler = new JobScheduler(async () => { });
@@ -521,6 +541,101 @@ async function pickJob(message, filter, alternatives = [], cwd) {
         throw err;
     }
 }
+/**
+ * Enable a routine on this device. If the name is not yet a user/system routine
+ * but names a project routine (in the current project or a registered one), it
+ * is materialised into the user layer first — one step, no separate opt-in. The
+ * device flag (`meta.deviceRoutines`) is the only thing that turns firing on, so
+ * a project YAML can never enable itself.
+ */
+async function enableRoutineAction(name) {
+    if (!name) {
+        name = await pickJob('Select routine to enable', (job) => !job.enabled, ['agents routines enable <name>']) ?? undefined;
+        if (!name) {
+            const available = discoverProjectRoutines();
+            if (available.length > 0) {
+                console.log(chalk.gray(`Project routines available to enable: ${available.map((r) => r.name).join(', ')}`));
+                console.log(chalk.gray('  Enable one by name: agents routines enable <name>'));
+            }
+            return;
+        }
+    }
+    try {
+        // Not a user/system routine yet? Resolve it as a project routine and
+        // materialise it before enabling.
+        if (!readJob(name)) {
+            const found = findProjectRoutine(name);
+            if (!found) {
+                console.log(chalk.red(`No routine named '${name}'.`));
+                const available = discoverProjectRoutines();
+                if (available.length > 0) {
+                    console.log(chalk.gray(`  Available project routines: ${available.map((r) => r.name).join(', ')}`));
+                }
+                process.exit(1);
+            }
+            if ('ambiguous' in found) {
+                console.log(chalk.red(`'${name}' is defined in more than one project: ${found.ambiguous.join(', ')}.`));
+                console.log(chalk.gray('  Enable it from inside the project you want, or rename one.'));
+                process.exit(1);
+            }
+            const mat = materialiseProjectRoutine(found.projectRoot, name);
+            if ('error' in mat) {
+                console.log(chalk.red(`Cannot enable '${name}': ${mat.error}`));
+                process.exit(1);
+            }
+            console.log(chalk.gray(`Materialised '${name}' from ${displayProjectPath(found.projectRoot)}`));
+        }
+        // Enabling re-runs readiness — it can never bypass a proven blocker. A
+        // blocked routine stays disabled.
+        const job = readJob(name);
+        if (job) {
+            const readiness = await evaluateActivationReadinessLive(job);
+            if (!readiness.ready) {
+                const r = readiness.readiness;
+                console.log(chalk.red(`Cannot enable '${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(`Routine '${name}' enabled`));
+        if (isDaemonRunning()) {
+            signalDaemonReload();
+            console.log(chalk.gray('Daemon reloaded'));
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(err.message));
+        process.exit(1);
+    }
+}
+/** Disable a routine on this device. Its definition stays; only firing stops. */
+async function disableRoutineAction(name) {
+    if (!name) {
+        name = await pickJob('Select routine to disable', (job) => job.enabled, ['agents routines disable <name>']) ?? undefined;
+        if (!name)
+            return;
+    }
+    try {
+        if (!readJob(name)) {
+            console.log(chalk.red(`No routine named '${name}'.`));
+            process.exit(1);
+        }
+        setJobEnabled(name, false);
+        console.log(chalk.green(`Routine '${name}' disabled`));
+        if (isDaemonRunning()) {
+            signalDaemonReload();
+            console.log(chalk.gray('Scheduler reloaded'));
+        }
+    }
+    catch (err) {
+        console.log(chalk.red(err.message));
+        process.exit(1);
+    }
+}
 /**
  * Parse a comma-separated devices string, normalize, deduplicate, and validate
  * each entry against the registered fleet. Exits nonzero on empty/whitespace
@@ -543,11 +658,258 @@ async function parseAndValidateDevices(raw) {
     }
     return names;
 }
+/**
+ * The static routines table. Shared verbatim by `agents routines list` and the
+ * non-interactive fall-through of the bare `agents routines` command, so both emit
+ * byte-identical `--json` and text output.
+ */
+function runRoutinesList(options) {
+    if (options.groupBy && options.groupBy !== 'device' && options.groupBy !== 'project') {
+        console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: project (default) or device`));
+        process.exit(1);
+    }
+    if (options.json) {
+        process.stdout.write(JSON.stringify(buildRoutineListJson()) + '\n');
+        return;
+    }
+    try {
+        monitorRunningJobs();
+    }
+    catch { /* best-effort orphan reap */ }
+    const jobs = listJobsForDisplay(process.cwd());
+    if (jobs.length === 0) {
+        console.log(chalk.gray('No jobs configured'));
+        console.log(chalk.gray('  Add a job: agents routines add <path-to-job.yml>'));
+        return;
+    }
+    const scheduler = new JobScheduler(async () => { });
+    scheduler.loadAll();
+    // Build a quick lookup: which jobs are currently overdue?
+    const overdueSet = new Set();
+    try {
+        for (const j of detectOverdueJobs())
+            overdueSet.add(j.name);
+    }
+    catch {
+        // Best-effort indicator; never block the list on detection errors.
+    }
+    console.log(chalk.bold('Scheduled Jobs\n'));
+    // OSC 8 hyperlink helper — renders as a clickable link in supporting terminals.
+    // Guarded on process.stdout.isTTY so that piped/redirected output never
+    // contains raw ESC ] 8 ;; ... BEL escape sequences.
+    const link = (label, url) => url && process.stdout.isTTY ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
+    const now = new Date();
+    if (options.flat) {
+        renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
+    }
+    else if (options.groupBy === 'device') {
+        let registry = {};
+        try {
+            registry = loadDevicesSync();
+        }
+        catch (err) {
+            console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
+        }
+        const groups = groupRoutineJobsByDevice(jobs, registry);
+        for (const group of groups) {
+            console.log(chalk.bold(`\n${group.title}`));
+            renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now, local: group.local });
+        }
+        if (groups.some((group) => !group.local)) {
+            console.log();
+            console.log(chalk.gray('  Last Status is per-device: rows under another device show "-" — read it there with: agents routines list --device <name>'));
+        }
+    }
+    else {
+        // Default: group by project
+        const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
+        const groups = groupRoutineJobsByProject(jobs, knownProjectNames);
+        for (const group of groups) {
+            console.log(chalk.bold(`\n${group.title}`));
+            renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+        }
+    }
+    if (overdueSet.size > 0) {
+        console.log();
+        console.log(chalk.yellow(`  ${overdueSet.size} routine(s) overdue — catch up with: agents routines catchup`));
+    }
+    scheduler.stopAll();
+    console.log();
+}
+/** True when a routine matches the browser's live filter query. */
+function routineMatchesQuery(job, q) {
+    const kind = job.command ? 'command' : job.workflow ? `wf:${job.workflow}` : job.agent ?? '';
+    return [job.name, kind, fireConditionLabel(job), (job.projects ?? []).join(' ')]
+        .join(' ')
+        .toLowerCase()
+        .includes(q);
+}
+/** One compact routine row for the browser list: name · kind · schedule · next · last. */
+function routineBrowserRow(job, scheduler, overdueSet, now) {
+    const kind = job.command ? 'command' : job.workflow ? `wf:${job.workflow}` : job.agent ?? '?';
+    const name = job.name.length > 24 ? job.name.slice(0, 23) + '…' : job.name.padEnd(24);
+    const enabled = job.enabled === false ? chalk.gray('paused') : chalk.green('on');
+    const latest = localLatestRun(job);
+    const last = latest
+        ? latest.status === 'completed'
+            ? chalk.green('ok')
+            : latest.status === 'failed' || latest.status === 'timeout'
+                ? chalk.red(latest.status)
+                : chalk.yellow(latest.status)
+        : chalk.gray('—');
+    const next = overdueSet.has(job.name)
+        ? chalk.yellow('overdue')
+        : chalk.gray(nextRunLabel(job, scheduler, now));
+    return `${chalk.bold(name)} ${chalk.cyan(kind.padEnd(12))} ${enabled.padEnd(6)} ${chalk.gray(scheduleLabel(job)).padEnd(24)} next ${next} · last ${last}`;
+}
+/**
+ * The four-block routine detail — Definition, Next fire, Recent runs, Stats — shown
+ * both live in the picker's preview pane and, in full, when a routine is selected.
+ */
+function buildRoutineDetail(job, scheduler, now) {
+    const lines = [];
+    // 1. Definition
+    lines.push(chalk.bold.underline('Definition'));
+    const kind = job.command
+        ? `command: ${job.command}`
+        : job.workflow
+            ? `workflow: ${job.workflow}`
+            : `agent: ${job.agent ?? '?'}`;
+    lines.push(`  ${kind}`);
+    lines.push(`  schedule: ${fireConditionLabel(job)}${isOneShotRoutine(job) ? ' (one-shot)' : ''}`);
+    const devices = devicesWithRoutineEnabled(job.name);
+    lines.push(`  devices: ${devices.length > 0 ? devices.join(', ') : chalk.gray('none (paused)')}`);
+    if (job.timezone)
+        lines.push(`  timezone: ${job.timezone}`);
+    if (job.repo)
+        lines.push(`  repo: ${job.repo}`);
+    if (job.prompt) {
+        const oneLine = job.prompt.replace(/\s+/g, ' ').trim();
+        lines.push(`  prompt: ${oneLine.length > 120 ? oneLine.slice(0, 119) + '…' : oneLine}`);
+    }
+    // 2. Next fire
+    lines.push('');
+    lines.push(chalk.bold.underline('Next fire'));
+    const nextDate = nextRunForDisplay(job, scheduler);
+    lines.push(`  ${nextRunLabel(job, scheduler, now)}${nextDate ? chalk.gray(`  (${nextDate.toISOString()})`) : ''}`);
+    // 3. Recent runs (most recent last, like `routines runs`)
+    lines.push('');
+    lines.push(chalk.bold.underline('Recent runs'));
+    const runs = listRuns(job.name).slice(-5);
+    if (runs.length === 0) {
+        lines.push(chalk.gray('  no runs yet'));
+    }
+    else {
+        for (const run of runs) {
+            const status = run.status === 'completed'
+                ? chalk.green(run.status)
+                : run.status === 'failed' || run.status === 'timeout'
+                    ? chalk.red(run.status)
+                    : chalk.yellow(run.status);
+            const dur = run.completedAt ? ` ${formatRunDuration(run.startedAt, run.completedAt)}` : '';
+            lines.push(`  ${run.startedAt}  ${status}${dur}`);
+        }
+    }
+    // 4. Stats
+    lines.push('');
+    lines.push(chalk.bold.underline('Stats'));
+    const stats = routineStats(job.name);
+    if (stats.count === 0) {
+        lines.push(chalk.gray('  no completed runs'));
+    }
+    else {
+        lines.push(`  runs ${stats.count} · failed ${stats.failed} · missed ${stats.missed}`);
+        lines.push(`  avg ${stats.avgMs}ms · p50 ${stats.p50}ms · p95 ${stats.p95}ms`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Interactive routines browser behind the bare `agents routines` command on a TTY.
+ * Reuses {@link itemPicker}, keeping the project/device group headers as inline
+ * dividers, with a live four-block detail pane and a full drill-in on select.
+ */
+async function runRoutinesBrowser(options) {
+    // Same --group-by validation as the static list, so a bad value fails the same
+    // way on a TTY as it does under --json / a pipe (rather than silently defaulting).
+    if (options.groupBy && options.groupBy !== 'device' && options.groupBy !== 'project') {
+        console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: project (default) or device`));
+        process.exit(1);
+    }
+    try {
+        monitorRunningJobs();
+    }
+    catch { /* best-effort orphan reap */ }
+    const jobs = listJobsForDisplay(process.cwd());
+    if (jobs.length === 0) {
+        console.log(chalk.gray('No jobs configured'));
+        console.log(chalk.gray('  Add a job: agents routines add <path-to-job.yml>'));
+        return;
+    }
+    const scheduler = new JobScheduler(async () => { });
+    scheduler.loadAll();
+    try {
+        const now = new Date();
+        const overdueSet = new Set();
+        try {
+            for (const j of detectOverdueJobs())
+                overdueSet.add(j.name);
+        }
+        catch { /* best-effort indicator */ }
+        // Group with the same headers the static list uses, so the picker's dividers
+        // read identically to `routines list`.
+        let groups;
+        if (options.groupBy === 'device') {
+            let registry = {};
+            try {
+                registry = loadDevicesSync();
+            }
+            catch { /* headers still render without state */ }
+            groups = groupRoutineJobsByDevice(jobs, registry);
+        }
+        else {
+            const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
+            groups = groupRoutineJobsByProject(jobs, knownProjectNames);
+        }
+        const filter = (query) => {
+            const q = query.trim().toLowerCase();
+            const rows = [];
+            for (const group of groups) {
+                const matched = q ? group.jobs.filter((j) => routineMatchesQuery(j, q)) : group.jobs;
+                if (matched.length === 0)
+                    continue;
+                rows.push(new Separator(chalk.bold(`── ${group.title} ──`)));
+                rows.push(...matched);
+            }
+            return rows;
+        };
+        const picked = await itemPicker({
+            message: 'Routines',
+            subtitle: chalk.gray('type to filter · ↑↓ navigate · space toggles detail · ⏎ open'),
+            items: filter(''),
+            filter,
+            labelFor: (job) => routineBrowserRow(job, scheduler, overdueSet, now),
+            buildPreview: (job) => buildRoutineDetail(job, scheduler, now),
+            shortIdFor: (job) => job.name,
+            pageSize: 15,
+            enterHint: 'open',
+            emptyMessage: 'No routines match.',
+        });
+        if (picked) {
+            // Drill-in: print the full, untruncated four-block detail for the selection.
+            console.log();
+            console.log(chalk.bold(picked.item.name));
+            console.log(buildRoutineDetail(picked.item, scheduler, now));
+        }
+    }
+    finally {
+        scheduler.stopAll();
+    }
+}
 /** Register the `agents routines` command tree. */
 export function registerRoutinesCommands(program) {
     const routinesCmd = program
         .command('routines')
-        .description('Schedule agents to run on a cron schedule or at a specific time. The scheduler auto-starts on first add.');
+        .description('Schedule agents to run on a cron schedule or at a specific time. The daemon starts at install/upgrade and on setup when daemon.enabled is not false; routines add also ensures it is running.');
     addHostOption(routinesCmd);
     setHelpSections(routinesCmd, {
         examples: `
@@ -564,9 +926,9 @@ export function registerRoutinesCommands(program) {
       agents routines add drain --schedule "0 3 * * *" --agent claude --placement fleet --prompt "Drain queue"
       agents routines add review --schedule "0 9 * * 1" --agent claude --placement cloud --prompt "Review open PRs"
 
-      # Opt a project's .agents/routines/*.yml into daemon firing (never auto)
-      agents routines enable-project --yes
-      agents routines sync
+      # Enable a routine (materialises a project routine on first enable)
+      agents routines enable security-sweep
+      agents routines disable security-sweep
 
       # List all routines and their next run times
       agents routines list
@@ -593,7 +955,8 @@ export function registerRoutinesCommands(program) {
         - what task to give the agent (the prompt)
         - execution constraints (mode, effort, timeout)
 
-      The background scheduler auto-starts the first time you add a routine.
+      The always-on agents daemon starts at install/upgrade and on setup (when
+      daemon.enabled is not false). Adding a routine also ensures it is running.
       Manage it with 'agents routines start|stop|status'.
 
       Version / credit failover (same semantics as 'agents run'):
@@ -611,6 +974,25 @@ export function registerRoutinesCommands(program) {
           run is skipped up front with a re-login hint.
     `,
     });
+    // Bare `agents routines`: a HIDDEN default subcommand carries the bare-command's
+    // own --json/--group-by/--flat. It must be a subcommand rather than options on the
+    // parent `routines`, because commander binds a same-named PARENT option first and
+    // would shadow the identical --json on every sibling (`add`/`run`/`runs`/`list`/…).
+    // On a TTY it opens the interactive browser; with --json, --flat, or in a
+    // non-interactive shell it prints the exact static `routines list` output.
+    routinesCmd
+        .command('browse', { isDefault: true, hidden: true })
+        .description('Interactive routines browser (the default for a bare `agents routines`)')
+        .option('--json', 'Emit machine-readable JSON instead of the browser (matches `routines list --json`)')
+        .option('--group-by <field>', 'Group by field: project (default) or device', 'project')
+        .option('--flat', 'Print the legacy flat table instead of the interactive browser')
+        .action(async (options) => {
+        if (options.json || options.flat || !isInteractiveTerminal()) {
+            runRoutinesList(options);
+            return;
+        }
+        await runRoutinesBrowser(options);
+    });
     routinesCmd
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
@@ -618,81 +1000,7 @@ export function registerRoutinesCommands(program) {
         .option('--group-by <field>', 'Group output by field: project (default) or device', 'project')
         .option('--flat', 'Print the legacy flat table instead of grouped sections')
         .action((options) => {
-        if (options.groupBy && options.groupBy !== 'device' && options.groupBy !== 'project') {
-            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: project (default) or device`));
-            process.exit(1);
-        }
-        if (options.json) {
-            process.stdout.write(JSON.stringify(buildRoutineListJson()) + '\n');
-            return;
-        }
-        try {
-            monitorRunningJobs();
-        }
-        catch { /* best-effort orphan reap */ }
-        const jobs = listAllJobs(process.cwd());
-        if (jobs.length === 0) {
-            if (options.json) {
-                process.stdout.write('[]\n');
-                return;
-            }
-            console.log(chalk.gray('No jobs configured'));
-            console.log(chalk.gray('  Add a job: agents routines add <path-to-job.yml>'));
-            return;
-        }
-        const scheduler = new JobScheduler(async () => { });
-        scheduler.loadAll();
-        // Build a quick lookup: which jobs are currently overdue?
-        const overdueSet = new Set();
-        try {
-            for (const j of detectOverdueJobs())
-                overdueSet.add(j.name);
-        }
-        catch {
-            // Best-effort indicator; never block the list on detection errors.
-        }
-        console.log(chalk.bold('Scheduled Jobs\n'));
-        // OSC 8 hyperlink helper — renders as a clickable link in supporting terminals.
-        // Guarded on process.stdout.isTTY so that piped/redirected output never
-        // contains raw ESC ] 8 ;; ... BEL escape sequences.
-        const link = (label, url) => url && process.stdout.isTTY ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
-        const now = new Date();
-        if (options.flat) {
-            renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
-        }
-        else if (options.groupBy === 'device') {
-            let registry = {};
-            try {
-                registry = loadDevicesSync();
-            }
-            catch (err) {
-                console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
-            }
-            const groups = groupRoutineJobsByDevice(jobs, registry);
-            for (const group of groups) {
-                console.log(chalk.bold(`\n${group.title}`));
-                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now, local: group.local });
-            }
-            if (groups.some((group) => !group.local)) {
-                console.log();
-                console.log(chalk.gray('  Last Status is per-device: rows under another device show "-" — read it there with: agents routines list --device <name>'));
-            }
-        }
-        else {
-            // Default: group by project
-            const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
-            const groups = groupRoutineJobsByProject(jobs, knownProjectNames);
-            for (const group of groups) {
-                console.log(chalk.bold(`\n${group.title}`));
-                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
-            }
-        }
-        if (overdueSet.size > 0) {
-            console.log();
-            console.log(chalk.yellow(`  ${overdueSet.size} routine(s) overdue — catch up with: agents routines catchup`));
-        }
-        scheduler.stopAll();
-        console.log();
+        runRoutinesList(options);
     });
     routinesCmd
         .command('add [nameOrPath]')
@@ -707,7 +1015,7 @@ export function registerRoutinesCommands(program) {
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
         .option('--devices <names>', 'Fleet allowlist (comma-separated): only listed devices schedule and fire this routine. Omit for unrestricted.')
-        .option('--run-on <name>', 'BODY placement: execute the job body on this machine over SSH (registered host, device, capability tag, or user@host). Sets hostStrategy=host. Same model as agents run --where device:<name> (docs/00-concepts.md#placement).')
+        .option('--run-on <name>', 'BODY placement: execute the job body on this machine over SSH (registered host, device, capability tag, or user@host). Sets hostStrategy=host. Same model as agents run --where device:<name> (docs/concepts.md#placement).')
         .option('--placement <strategy>', `BODY placement strategy: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Maps to the shared Placement model (local|device|fleet|cloud). Not the same as --host (which manages routines on a remote machine).`)
         .option('--run-cwd <dir>', 'Working directory on the --run-on host (--remote-cwd is taken by the remote-management passthrough)')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
@@ -887,6 +1195,10 @@ export function registerRoutinesCommands(program) {
                     console.log(chalk.gray(`  ${r.message}`));
                     if (r.repair)
                         console.log(chalk.gray(`  repair: ${r.repair}`));
+                    // Name the resume explicitly: a paused routine is otherwise a dead
+                    // end for an agent, which is how the release train sat unregistered
+                    // (RUSH-2517 / RUSH-2476).
+                    console.log(chalk.gray(`  then:   agents routines enable ${config.name}`));
                 }
             }
             if (options.json) {
@@ -956,17 +1268,38 @@ export function registerRoutinesCommands(program) {
                 config.runOnce = true;
                 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);
+            // `add <file>` must never rewrite the file the user pointed at. When the
+            // source already IS the canonical routine file — the normal case for a
+            // definition tracked in the git-backed `~/.agents` repo — writeJob would
+            // re-serialize it in place and drop every key the canonical form omits,
+            // including the legacy `devices:` pin, silently corrupting committed
+            // config (RUSH-2517). The definition is already where it belongs; only
+            // activation is left to do. A source from anywhere else is still copied
+            // in, which is the whole point of passing a path.
+            if (!isCanonicalRoutineSource(resolved, config.name))
+                writeJob(config);
             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);
+            // A `devices:` pin in a hand-authored definition is legacy input: since
+            // RUSH-2392's split (723182bb5) activation lives in each device's
+            // `agents.yaml`, and `add` only ever applies it to THIS box. Say so
+            // rather than let the routine read `Devices: all` on every peer.
+            if (config.devices && config.devices.length > 0 && !options.json) {
+                console.log(chalk.yellow(`'devices:' pins activation on this box only — it is not propagated to peers.`));
+                console.log(chalk.gray(`  pin the fleet with: agents routines devices ${config.name} --set ${config.devices.join(',')}`));
+            }
             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}`));
+                // Name the resume explicitly: a paused routine is otherwise a dead end
+                // for an agent, which is how the release train sat unregistered
+                // (RUSH-2517 / RUSH-2476).
+                console.log(chalk.gray(`  then:   agents routines enable ${config.name}`));
             }
             if (options.json) {
                 writeJson({
@@ -1070,6 +1403,8 @@ export function registerRoutinesCommands(program) {
         .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')
+        .option('--cwd <path>', 'Set the execution directory and save, without opening an editor')
+        .option('--project-anchor <name>', 'Set the execution project anchor and save, without opening an editor')
         .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to edit', undefined, ['agents routines edit <name>']) ?? undefined;
@@ -1077,6 +1412,40 @@ export function registerRoutinesCommands(program) {
                 return;
         }
         const existing = readJob(name);
+        // Headless context repair. Both readiness blockers print
+        // `agents routines edit <name> --project-anchor <name>  # or --cwd <path>`
+        // as their repair (routine-context.ts:215,334), but neither flag existed
+        // and the only edit surface opened $EDITOR — so an agent could never
+        // follow its own repair hint (RUSH-2517). Applying and saving directly is
+        // what makes that hint true.
+        if (options.cwd !== undefined || options.projectAnchor !== undefined) {
+            if (!existing) {
+                console.error(chalk.red(`Routine '${name}' not found. Create it first: agents routines add ${name} --schedule "..." --agent claude --prompt "..."`));
+                process.exit(1);
+            }
+            if (options.cwd !== undefined)
+                existing.cwd = options.cwd;
+            if (options.projectAnchor !== undefined)
+                existing.project = options.projectAnchor;
+            const errors = validateJob(existing);
+            if (errors.length > 0) {
+                console.error(chalk.red('Validation errors:'));
+                for (const err of errors)
+                    console.error(chalk.red(`  - ${err}`));
+                process.exit(1);
+            }
+            writeJob(existing);
+            const readiness = await evaluateActivationReadinessLive(existing);
+            console.log(chalk.green(`Routine '${name}' updated`));
+            if (!readiness.ready && readiness.readiness) {
+                console.log(chalk.yellow(`Still not ready: ${readiness.readiness.code}`));
+                console.log(chalk.gray(`  ${readiness.readiness.message}`));
+            }
+            else {
+                console.log(chalk.gray(`  enable it with: agents routines enable ${name}`));
+            }
+            return;
+        }
         if (existing && (options.stateTo !== undefined || options.stateFrom !== undefined)) {
             if (!existing.trigger || existing.trigger.type !== 'linear_event') {
                 console.error(chalk.red(`'${name}' does not have a Linear trigger; --state-to/--state-from only apply to linear triggers`));
@@ -1612,65 +1981,18 @@ export function registerRoutinesCommands(program) {
         }
     });
     routinesCmd
-        .command('resume [name]')
-        .description('Re-enable a paused routine so the daemon schedules it again')
+        .command('enable [name]')
+        .aliases(['resume'])
+        .description('Enable a routine so the daemon schedules it. Also materialises a project routine (from the current project or a registered one) on first enable — one step, no separate opt-in.')
         .action(async (name) => {
-        if (!name) {
-            // Only show paused jobs
-            name = await pickJob('Select job to resume', (job) => !job.enabled, ['agents routines resume <name>']) ?? undefined;
-            if (!name)
-                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()) {
-                signalDaemonReload();
-                console.log(chalk.gray('Daemon reloaded'));
-            }
-        }
-        catch (err) {
-            console.log(chalk.red(err.message));
-            process.exit(1);
-        }
+        await enableRoutineAction(name);
     });
     routinesCmd
-        .command('pause [name]')
-        .description('Temporarily disable a routine. Stops scheduling future runs; enable again with resume.')
+        .command('disable [name]')
+        .aliases(['pause'])
+        .description('Disable a routine. Stops scheduling future runs; turn it back on with: agents routines enable <name>.')
         .action(async (name) => {
-        if (!name) {
-            // Only show enabled jobs
-            name = await pickJob('Select job to pause', (job) => job.enabled, ['agents routines pause <name>']) ?? undefined;
-            if (!name)
-                return;
-        }
-        try {
-            setJobEnabled(name, false);
-            console.log(chalk.green(`Job '${name}' paused`));
-            if (isDaemonRunning()) {
-                signalDaemonReload();
-                console.log(chalk.gray('Scheduler reloaded'));
-            }
-        }
-        catch (err) {
-            console.log(chalk.red(err.message));
-            process.exit(1);
-        }
+        await disableRoutineAction(name);
     });
     // Device activation management for a single routine. Each mutation executes
     // on the target device so only that host writes devices/<hostname>/agents.yaml.
@@ -1874,122 +2196,13 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray('\n  Start the scheduler to begin firing routines: agents routines start'));
         }
     });
-    routinesCmd
-        .command('enable-project [path]')
-        .description('Opt a project\'s .agents/routines/*.yml into daemon firing. Requires explicit approval — project routines never auto-fire from a cloned repo. Materialises copies into ~/.agents/routines/ with source provenance.')
-        .option('--yes', 'Skip the interactive confirmation prompt')
-        .option('--json', 'Emit machine-readable JSON')
-        .action(async (projectPath, options) => {
-        const root = projectPath
-            ? path.resolve(projectPath)
-            : resolveProjectRoot(process.cwd());
-        if (!root) {
-            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
-            console.error(chalk.gray('Run from inside a project, or pass the project path: agents routines enable-project /path/to/repo'));
-            process.exit(1);
-        }
-        const files = listProjectRoutineFiles(root);
-        if (files.length === 0) {
-            console.error(chalk.red(`No routines found under ${path.join(root, '.agents', 'routines')}`));
-            process.exit(1);
-        }
-        if (!options.yes) {
-            if (!isInteractiveTerminal()) {
-                console.error(chalk.red('Refusing to enable project routines non-interactively without --yes.'));
-                console.error(chalk.gray(`Found ${files.length} routine(s) in ${displayProjectPath(root)}. Re-run with --yes to confirm.`));
-                process.exit(1);
-            }
-            try {
-                const { confirm } = await import('@inquirer/prompts');
-                const ok = await confirm({
-                    message: `Enable daemon firing for ${files.length} project routine(s) in ${displayProjectPath(root)}?`,
-                    default: false,
-                });
-                if (!ok) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-                throw err;
-            }
-        }
-        const newly = enableProjectRoutines(root);
-        const sync = syncProjectRoutines(root);
-        if (isDaemonRunning())
-            signalDaemonReload();
-        if (options.json) {
-            writeJson({
-                ok: true,
-                projectRoot: root,
-                newlyEnabled: newly,
-                synced: sync.synced,
-                skipped: sync.skipped,
-                removed: sync.removed,
-                errors: sync.errors,
-            });
-            return;
-        }
-        console.log(chalk.green(newly
-            ? `Enabled project routines for ${displayProjectPath(root)}`
-            : `Project routines already enabled for ${displayProjectPath(root)}`));
-        if (sync.synced.length > 0) {
-            console.log(chalk.gray(`  Synced: ${sync.synced.join(', ')}`));
-        }
-        for (const s of sync.skipped) {
-            console.log(chalk.yellow(`  Skipped ${s.name}: ${s.reason}`));
-        }
-        for (const e of sync.errors) {
-            console.log(chalk.red(`  Error ${e.name}: ${e.error}`));
-        }
-        console.log(chalk.gray('Daemon will fire these after reload. Re-sync later with: agents routines sync'));
-    });
-    routinesCmd
-        .command('disable-project [path]')
-        .description('Remove a project from the project-routines allowlist. Use --remove-synced to also delete the user-layer copies.')
-        .option('--remove-synced', 'Delete user-layer routines that were materialised from this project')
-        .option('--json', 'Emit machine-readable JSON')
-        .action(async (projectPath, options) => {
-        const root = projectPath
-            ? path.resolve(projectPath)
-            : resolveProjectRoot(process.cwd());
-        if (!root) {
-            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
-            process.exit(1);
-        }
-        const result = disableProjectRoutines(root, { removeSynced: options.removeSynced });
-        if (isDaemonRunning())
-            signalDaemonReload();
-        if (options.json) {
-            writeJson({ ok: true, projectRoot: root, ...result });
-            return;
-        }
-        if (!result.removed) {
-            console.log(chalk.gray(`Project ${displayProjectPath(root)} was not on the allowlist`));
-        }
-        else {
-            console.log(chalk.green(`Disabled project routines for ${displayProjectPath(root)}`));
-        }
-        if (result.deletedJobs.length > 0) {
-            console.log(chalk.gray(`  Removed user-layer copies: ${result.deletedJobs.join(', ')}`));
-        }
-    });
     routinesCmd
         .command('sync [path]')
-        .description('Refresh user-layer copies of opted-in project routines from their .agents/routines/*.yml sources. With no path, syncs every enabled project. Also runs automatically on daemon reload (SIGHUP).')
+        .description('Refresh materialised project routines from their .agents/routines/*.yml sources. Definition-only — never changes what is enabled. With no path, refreshes every project you have enabled a routine from. Also runs automatically on daemon reload (SIGHUP).')
         .option('--json', 'Emit machine-readable JSON')
         .action(async (projectPath, options) => {
         if (projectPath) {
             const root = path.resolve(projectPath);
-            const isEnabled = listEnabledProjectRoots().some((p) => p === root);
-            if (!isEnabled) {
-                console.error(chalk.red(`Project ${displayProjectPath(root)} is not enabled. Run: agents routines enable-project ${root}`));
-                process.exit(1);
-            }
             const sync = syncProjectRoutines(root);
             if (isDaemonRunning())
                 signalDaemonReload();
@@ -1997,6 +2210,11 @@ export function registerRoutinesCommands(program) {
                 writeJson({ ok: true, ...sync });
                 return;
             }
+            if (sync.synced.length === 0 && sync.skipped.length === 0 && sync.removed.length === 0 && sync.errors.length === 0) {
+                console.log(chalk.gray(`No enabled routines materialised from ${displayProjectPath(root)}.`));
+                console.log(chalk.gray('  Enable one with: agents routines enable <name>'));
+                return;
+            }
             printSyncResult(sync);
             return;
         }
@@ -2008,48 +2226,15 @@ export function registerRoutinesCommands(program) {
             return;
         }
         if (all.projects.length === 0 && all.missing.length === 0) {
-            console.log(chalk.gray('No project roots on the routines allowlist.'));
-            console.log(chalk.gray('  Enable one with: agents routines enable-project'));
+            console.log(chalk.gray('No project routines materialised yet.'));
+            console.log(chalk.gray('  Enable one with: agents routines enable <name>'));
             return;
         }
         for (const p of all.projects)
             printSyncResult(p);
         for (const m of all.missing) {
-            console.log(chalk.yellow(`Missing project root (still on allowlist): ${displayProjectPath(m)}`));
-        }
-    });
-    routinesCmd
-        .command('projects')
-        .description('List project roots opted into daemon-fired project routines')
-        .option('--json', 'Emit machine-readable JSON')
-        .action((options) => {
-        const roots = listEnabledProjectRoots();
-        if (options.json) {
-            writeJson(roots.map((r) => ({
-                path: r,
-                display: displayProjectPath(r),
-                routines: listProjectRoutineFiles(r).map((f) => f.name),
-            })));
-            return;
+            console.log(chalk.yellow(`Missing project root for a materialised routine: ${displayProjectPath(m)}`));
         }
-        if (roots.length === 0) {
-            console.log(chalk.gray('No projects enabled. Use: agents routines enable-project'));
-            // Offer a discovery hint for the current project.
-            const discovered = discoverProjectRoutinesAt(process.cwd());
-            if (discovered) {
-                console.log(chalk.gray(`  Found ${discovered.files.length} routine(s) in ${displayProjectPath(discovered.projectRoot)} — enable with: agents routines enable-project`));
-            }
-            return;
-        }
-        console.log(chalk.bold('Enabled project routines\n'));
-        for (const r of roots) {
-            const files = listProjectRoutineFiles(r);
-            console.log(`  ${chalk.cyan(displayProjectPath(r))}  ${chalk.gray(`(${files.length} routine${files.length === 1 ? '' : 's'})`)}`);
-            for (const f of files) {
-                console.log(chalk.gray(`    - ${f.name}`));
-            }
-        }
-        console.log();
     });
     routinesCmd
         .command('scheduler-logs')
@@ -2058,9 +2243,8 @@ export function registerRoutinesCommands(program) {
         .option('-f, --follow', 'Stream log output in real time (like tail -f)')
         .action(async (options) => {
         if (options.follow) {
-            const { getDaemonDir } = await import('../lib/state.js');
             const { followFile } = await import('../lib/log-follow.js');
-            const logPath = path.join(getDaemonDir(), 'logs.jsonl');
+            const logPath = getDaemonLogPath();
             const recent = readDaemonLog(parseInt(options.lines, 10));
             if (recent)
                 console.log(recent);