@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/prune.js

@@ -1,5 +1,5 @@
 /**
- * Top-level `agents prune` — destructive cleanup across the install.
+ * `agents prune cleanup` — destructive cleanup across the install.
  *
  * Cleanup targets:
  *   - Resource orphans: command/skill/hook files inside a version home that no
@@ -7,8 +7,9 @@
  *     into the version install).
  *   - Version duplicates: older installed versions of an agent that share an
  *     account with a newer installed version of the same agent.
- *   - Trash: soft-deleted resources in ~/.agents/.trash/ older than N days.
- *   - Sessions: session records in sessions.db older than N days.
+ *   - Trash/session targets are retained as no-op compatibility shims: version
+ *     homes and session history are durable and must not be hard-deleted by
+ *     agents-cli.
  *   - Runs: routine execution logs, keeping only the last N per job.
  *
  * Sync (additive: copy missing/changed files into version homes) is no longer
@@ -21,7 +22,6 @@
  * to widen orphan cleanup to every installed version.
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
@@ -34,7 +34,6 @@ import { resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { pruneDuplicates } from './view.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { getTrashDir } from '../lib/state.js';
-import { countSessionsOlderThan, deleteSessionsOlderThan } from '../lib/session/db.js';
 import { previewRunsPrune, pruneRuns, countAllRuns } from '../lib/routines.js';
 const RESOURCE_TYPES = ['commands', 'skills', 'hooks', 'plugins', 'subagents'];
 const STATE_TYPES = ['trash', 'sessions', 'runs'];
@@ -125,12 +124,6 @@ function parseTarget(arg) {
     console.log(chalk.gray(formatAgentError(arg)));
     process.exit(1);
 }
-function parseDays(value, defaultDays) {
-    const match = value.match(/^(\d+)d?$/);
-    if (match)
-        return parseInt(match[1], 10);
-    return defaultDays;
-}
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -140,137 +133,25 @@ function formatBytes(bytes) {
         return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
     return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
-function getDirSize(dirPath) {
-    if (!fs.existsSync(dirPath))
-        return 0;
-    let size = 0;
-    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = path.join(dirPath, entry.name);
-        if (entry.isDirectory()) {
-            size += getDirSize(fullPath);
-        }
-        else {
-            try {
-                size += fs.statSync(fullPath).size;
-            }
-            catch { /* ignore */ }
-        }
-    }
-    return size;
-}
 async function runTrashPrune(options) {
     const trashDir = getTrashDir();
     if (!fs.existsSync(trashDir)) {
         console.log(chalk.green('Trash is empty.'));
         return;
     }
-    const days = parseDays(options.olderThan || '30d', 30);
-    const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
-    const toPrune = [];
-    function scanDir(dir) {
-        if (!fs.existsSync(dir))
-            return;
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const fullPath = path.join(dir, entry.name);
-            try {
-                const stat = fs.statSync(fullPath);
-                if (stat.mtimeMs < cutoffMs) {
-                    toPrune.push({ path: fullPath, mtime: stat.mtimeMs, size: entry.isDirectory() ? getDirSize(fullPath) : stat.size });
-                }
-                else if (entry.isDirectory()) {
-                    scanDir(fullPath);
-                }
-            }
-            catch { /* skip inaccessible */ }
-        }
-    }
-    scanDir(trashDir);
-    if (toPrune.length === 0) {
-        console.log(chalk.green(`No trash entries older than ${days} days.`));
-        return;
-    }
-    const totalSize = toPrune.reduce((sum, e) => sum + e.size, 0);
-    console.log(chalk.bold(`Trash entries older than ${days} days\n`));
-    for (const entry of toPrune.slice(0, 20)) {
-        const age = Math.floor((Date.now() - entry.mtime) / (24 * 60 * 60 * 1000));
-        console.log(`  ${chalk.gray(`${age}d ago`)}  ${path.relative(trashDir, entry.path)}`);
-    }
-    if (toPrune.length > 20) {
-        console.log(chalk.gray(`  ... and ${toPrune.length - 20} more`));
-    }
-    console.log();
-    if (options.dryRun) {
-        console.log(chalk.gray(`${toPrune.length} entries (${formatBytes(totalSize)}). Run without --dry-run to delete.`));
-        return;
-    }
-    if (!options.yes) {
-        if (!isInteractiveTerminal()) {
-            console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-            process.exit(1);
-        }
-        let ok = false;
-        try {
-            ok = await confirm({ message: `Delete ${toPrune.length} entries (${formatBytes(totalSize)})?`, default: false });
-        }
-        catch (err) {
-            if (isPromptCancelled(err)) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-            throw err;
-        }
-        if (!ok) {
-            console.log(chalk.gray('Cancelled'));
-            return;
-        }
-    }
-    let deleted = 0;
-    for (const entry of toPrune) {
-        try {
-            fs.rmSync(entry.path, { recursive: true, force: true });
-            deleted++;
-        }
-        catch { /* ignore */ }
+    if (options.olderThan || options.yes || options.dryRun) {
+        console.log(chalk.gray('Trash expiry flags are accepted for compatibility but do not delete data.'));
     }
-    console.log(chalk.green(`Pruned ${deleted} trash entries (${formatBytes(totalSize)}).`));
+    console.log(chalk.yellow('Trash is durable. agents-cli does not hard-delete soft-deleted version data.'));
+    console.log(chalk.gray('Inspect recoverable versions with: agents trash list'));
+    console.log(chalk.gray(`Trash path: ${trashDir}`));
 }
 async function runSessionsPrune(options) {
-    const days = parseDays(options.olderThan || '90d', 90);
-    const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
-    const count = countSessionsOlderThan(cutoffMs);
-    if (count === 0) {
-        console.log(chalk.green(`No sessions older than ${days} days.`));
-        return;
+    if (options.olderThan || options.yes || options.dryRun) {
+        console.log(chalk.gray('Session prune flags are accepted for compatibility but do not delete data.'));
     }
-    console.log(chalk.bold(`Sessions older than ${days} days: ${count}\n`));
-    if (options.dryRun) {
-        console.log(chalk.gray(`${count} session(s). Run without --dry-run to delete.`));
-        return;
-    }
-    if (!options.yes) {
-        if (!isInteractiveTerminal()) {
-            console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-            process.exit(1);
-        }
-        let ok = false;
-        try {
-            ok = await confirm({ message: `Delete ${count} session records?`, default: false });
-        }
-        catch (err) {
-            if (isPromptCancelled(err)) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-            throw err;
-        }
-        if (!ok) {
-            console.log(chalk.gray('Cancelled'));
-            return;
-        }
-    }
-    const deleted = deleteSessionsOlderThan(cutoffMs);
-    console.log(chalk.green(`Pruned ${deleted} session records.`));
+    console.log(chalk.yellow('Session history is durable. agents-cli does not hard-delete session records.'));
+    console.log(chalk.gray('Browse sessions with: agents sessions'));
 }
 async function runRunsPrune(options) {
     const keep = options.keep ? parseInt(options.keep, 10) : 10;
@@ -380,13 +261,16 @@ async function runOrphanPrune(resourceTypes, options) {
     console.log(chalk.green(summary) + (failures > 0 ? chalk.red(`, ${failures} failed`) : '') + '.');
 }
 export function registerPruneCommand(program) {
-    program
-        .command('prune [target]')
-        .description('Remove orphan resources, old versions, trash, sessions, or routine runs')
+    const pruneCmd = program.commands.find((cmd) => cmd.name() === 'prune') ?? program
+        .command('prune <specs...>')
+        .description('Uninstall agent CLI versions. Moves version data to trash for recovery.');
+    pruneCmd
+        .command('cleanup [target]')
+        .description('Remove orphan resources, old versions, or routine runs')
         .option('--all', 'For orphan cleanup: sweep every installed version (default: current default version per agent)')
         .option('--dry-run', 'Show what would be removed without deleting (default for state targets)')
         .option('-y, --yes', 'Skip confirmation prompt')
-        .option('--older-than <days>', 'For trash/sessions: delete entries older than N days (default: 30d for trash, 90d for sessions)')
+        .option('--older-than <days>', 'Deprecated for trash/sessions; accepted but no data is deleted')
         .option('--keep <n>', 'For runs: keep the last N runs per job (default: 10)')
         .addHelpText('after', `
 Targets:
@@ -396,46 +280,40 @@ Targets:
   hooks      Orphan hook scripts only
   versions   Older duplicate version installs only
   <agent>    Older duplicate versions for one agent (e.g. 'claude')
-  trash      Soft-deleted resources older than --older-than days (default 30)
-  sessions   Session records in sessions.db older than --older-than days (default 90)
+  trash      No-op compatibility target; trash is durable
+  sessions   No-op compatibility target; session history is durable
   runs       Routine execution logs, keeping only --keep per job (default 10)
 
 Examples:
   # Full sweep: orphan resources + duplicate versions for current defaults
-  agents prune
+  agents prune cleanup
 
   # Preview what a full sweep would remove
-  agents prune --dry-run
+  agents prune cleanup --dry-run
 
   # Just orphan skills
-  agents prune skills
+  agents prune cleanup skills
 
   # Just version dedup
-  agents prune versions
+  agents prune cleanup versions
 
   # Deduplicate versions for one agent only
-  agents prune claude
+  agents prune cleanup claude
 
   # Sweep every installed version's orphans, not only the defaults
-  agents prune --all
-
-  # Preview trash entries older than 30 days
-  agents prune trash --dry-run
-
-  # Delete trash entries older than 60 days
-  agents prune trash --older-than 60 -y
+  agents prune cleanup --all
 
-  # Preview session cleanup (90+ days old)
-  agents prune sessions --dry-run
+  # Show the durable-trash notice
+  agents prune cleanup trash --dry-run
 
-  # Delete sessions older than 180 days
-  agents prune sessions --older-than 180 -y
+  # Show the durable-session notice
+  agents prune cleanup sessions --dry-run
 
   # Preview runs cleanup (keeping last 10)
-  agents prune runs --dry-run
+  agents prune cleanup runs --dry-run
 
   # Keep only the last 5 runs per job
-  agents prune runs --keep 5 -y
+  agents prune cleanup runs --keep 5 -y
 
 What's an orphan?
   A command, skill, or hook present inside a version home but missing from every
@@ -443,10 +321,11 @@ What's an orphan?
   repos). Usually leftovers from a resource that was deleted or moved but never
   reconciled into the version install.
 
-Soft-delete:
-  Version directories are NEVER hard-deleted. \`prune\` moves them to
-  ~/.agents/.trash/versions/<agent>/<version>/<timestamp>/. Use
-  \`agents prune trash\` to expire old trash entries.
+Durability:
+  Version directories are NEVER hard-deleted by agents-cli. Version prune and
+  cleanup move them to ~/.agents/.history/trash/versions/<agent>/<version>/<timestamp>/.
+  Session records are also durable; the sessions target remains only as a no-op
+  compatibility shim.
 `)
         .action(async (target, options) => {
         const parsed = parseTarget(target);

package/dist/commands/pull.js

@@ -13,11 +13,12 @@ import { getUserAgentsDir, ensureAgentsDir, getEnabledExtraRepos, } from '../lib
 import { isGitRepo, pullRepo, isSystemRepoOrigin, } from '../lib/git.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
+import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
+import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from '../lib/cli-resources.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
 import { setHelpSections } from '../lib/help.js';
-import { select } from '@inquirer/prompts';
+import { select, confirm } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
  * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
@@ -218,7 +219,7 @@ export function registerPullCommand(program) {
                 if (!defaultVer)
                     continue;
                 const actuallySynced = getActuallySyncedResources(agentId, defaultVer);
-                const newResources = getNewResources(available, actuallySynced);
+                const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
                 const hasAnySynced = actuallySynced.commands.length > 0 ||
                     actuallySynced.skills.length > 0 ||
                     actuallySynced.hooks.length > 0 ||
@@ -244,10 +245,10 @@ export function registerPullCommand(program) {
                         if (userSelection)
                             selection = userSelection;
                     }
-                    else if (hasNewResources(newResources, agentId)) {
+                    else if (hasNewResources(newResources, agentId, defaultVer)) {
                         // Has synced before, but NEW items available
                         console.log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
-                        const userSelection = await promptNewResourceSelection(agentId, newResources);
+                        const userSelection = await promptNewResourceSelection(agentId, newResources, defaultVer);
                         if (userSelection)
                             selection = userSelection;
                     }
@@ -366,6 +367,58 @@ export function registerPullCommand(program) {
                     console.log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
                 }
             }
+            // Report (and optionally install) any declared CLIs that are missing
+            // from the host. Skipped under -y so non-interactive pulls don't trigger
+            // package-manager prompts.
+            try {
+                const { statuses, errors } = listCliStatus(process.cwd());
+                for (const err of errors) {
+                    console.log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
+                }
+                const missing = statuses.filter((s) => !s.installed);
+                if (missing.length > 0) {
+                    console.log(chalk.bold('\nDeclared CLIs missing from this host:'));
+                    for (const s of missing) {
+                        const method = selectInstallMethod(s.manifest);
+                        const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+                        console.log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+                    }
+                    console.log('');
+                    if (!skipPrompts) {
+                        const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
+                        if (proceed) {
+                            for (const s of missing) {
+                                console.log(chalk.bold(`\n→ ${s.manifest.name}`));
+                                const result = installCli(s.manifest);
+                                if (result.error) {
+                                    console.log(chalk.red(`  ${result.error}`));
+                                    continue;
+                                }
+                                if (result.installed) {
+                                    console.log(chalk.green(`  installed`));
+                                    if (s.manifest.postInstall) {
+                                        console.log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                                    }
+                                }
+                                else {
+                                    console.log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
+                                }
+                            }
+                        }
+                        else {
+                            console.log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                        }
+                    }
+                    else {
+                        console.log(chalk.gray(`Run 'agents cli install' to install them.`));
+                    }
+                }
+            }
+            catch (err) {
+                if (!isPromptCancelled(err)) {
+                    console.log(chalk.yellow(`CLI install skipped: ${err.message}`));
+                }
+            }
             console.log(chalk.green('\nPull complete'));
         }
         catch (err) {

package/dist/commands/routines.js

@@ -11,11 +11,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonPid, readDaemonLog, } from '../lib/daemon.js';
+import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, } from '../lib/routines.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob } from '../lib/runner.js';
+import { executeJob, executeJobDetached } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
+import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 /** Start or reload the background scheduler so newly-added jobs fire on time. */
@@ -60,7 +62,7 @@ async function pickJob(message, filter, alternatives = []) {
             message,
             choices: jobs.map((job) => ({
                 value: job.name,
-                name: `${job.name} ${chalk.gray(`(${job.agent}, ${job.schedule})`)}`,
+                name: `${job.name} ${chalk.gray(`(${job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule})`)}`,
             })),
         });
     }
@@ -120,18 +122,57 @@ export function registerRoutinesCommands(program) {
         }
         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'));
-        const header = `  ${'Name'.padEnd(24)} ${'Agent'.padEnd(10)} ${'Schedule'.padEnd(20)} ${'Enabled'.padEnd(10)} ${'Next Run'.padEnd(24)} ${'Last Status'}`;
+        // 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();
+        const NAME_W = 24;
+        const AGENT_W = 10;
+        const REPO_W = REPO_DISPLAY_MAX;
+        const SCHED_W = 22;
+        const ENABLED_W = 10;
+        const NEXT_W = 22;
+        const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
         console.log(chalk.gray(header));
-        console.log(chalk.gray('  ' + '-'.repeat(110)));
+        console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
         for (const job of jobs) {
             const nextRun = scheduler.getNextRun(job.name);
-            const nextStr = nextRun ? nextRun.toLocaleString() : '-';
+            const nextStr = humanizeNextRun(nextRun ?? null, now, job.timezone);
+            const schedStr = humanizeCron(job.schedule, job.timezone);
             const latestRun = getLatestRun(job.name);
             const lastStatus = latestRun?.status || '-';
+            const repoInfo = formatRepoLink(job.repo);
+            const repoCell = link(repoInfo.display, repoInfo.href);
+            // Pad based on the display string, not the raw cell (which may include escape codes).
+            const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
             const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
-            const statusColor = lastStatus === 'completed' ? chalk.green : lastStatus === 'failed' ? chalk.red : lastStatus === 'timeout' ? chalk.yellow : chalk.gray;
-            console.log(`  ${chalk.cyan(job.name.padEnd(24))} ${job.agent.padEnd(10)} ${job.schedule.padEnd(20)} ${enabledStr.padEnd(10 + 10)} ${chalk.gray(nextStr.padEnd(24))} ${statusColor(lastStatus)}`);
+            // chalk adds escape codes; pad the raw word and let chalk wrap it.
+            const enabledWord = job.enabled ? 'yes' : 'no';
+            const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
+            const statusColor = lastStatus === 'completed' ? chalk.green
+                : lastStatus === 'failed' ? chalk.red
+                    : lastStatus === 'timeout' ? chalk.yellow
+                        : chalk.gray;
+            const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
+            const agentLabelPadded = job.workflow
+                ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
+                : (job.agent || '').padEnd(10);
+            console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+        }
+        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();
@@ -141,16 +182,17 @@ export function registerRoutinesCommands(program) {
         .description('Create a new routine from a YAML file or inline flags. Starts the scheduler automatically if it is not already running.')
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
         .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, gemini, cursor, or opencode')
+        .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
-        .option('-m, --mode <mode>', 'Execution mode: plan (read-only) or edit (can write files)', 'plan')
+        .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'plan')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto', 'auto')
-        .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 30m, 2h)', '30m')
+        .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('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
-        const hasInlineFlags = options.schedule || options.agent || options.prompt || options.at;
+        const hasInlineFlags = options.schedule || options.agent || options.workflow || options.prompt || options.at;
         if (hasInlineFlags) {
             // Inline mode: create job from flags
             if (!nameOrPath) {
@@ -158,6 +200,11 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.gray('Usage: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
                 process.exit(1);
             }
+            // Validate mutually exclusive --agent / --workflow
+            if (options.agent && options.workflow) {
+                console.log(chalk.red('--agent and --workflow are mutually exclusive; specify exactly one'));
+                process.exit(1);
+            }
             let schedule = options.schedule;
             let runOnce = false;
             // Handle --at for one-shot jobs
@@ -175,8 +222,8 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.red('Schedule is required (use --schedule or --at)'));
                 process.exit(1);
             }
-            if (!options.agent) {
-                console.log(chalk.red('Agent is required (use --agent)'));
+            if (!options.agent && !options.workflow) {
+                console.log(chalk.red('An agent or workflow is required (use --agent or --workflow)'));
                 process.exit(1);
             }
             if (!options.prompt) {
@@ -187,6 +234,7 @@ export function registerRoutinesCommands(program) {
                 name: nameOrPath,
                 schedule,
                 agent: options.agent,
+                ...(options.workflow ? { workflow: options.workflow } : {}),
                 mode: options.mode,
                 effort: options.effort,
                 timeout: options.timeout,
@@ -245,7 +293,7 @@ export function registerRoutinesCommands(program) {
             const config = {
                 mode: 'plan',
                 effort: 'auto',
-                timeout: '30m',
+                timeout: '10m',
                 enabled: true,
                 ...parsed,
             };
@@ -387,7 +435,8 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.red(`Job '${name}' not found`));
             process.exit(1);
         }
-        console.log(chalk.bold(`Running job '${name}' (agent: ${job.agent}, mode: ${job.mode})\n`));
+        const runLabel = job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
+        console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
         const spinner = ora('Executing...').start();
         try {
             const result = await executeJob(job);
@@ -413,6 +462,50 @@ export function registerRoutinesCommands(program) {
             process.exit(1);
         }
     });
+    routinesCmd
+        .command('catchup')
+        .description('Run any routines that missed their last scheduled fire (e.g. because your laptop was off). Detached — runs in the background under the scheduler.')
+        .option('--dry-run', 'List overdue routines without running them')
+        .action(async (options) => {
+        const overdue = detectOverdueJobs();
+        if (overdue.length === 0) {
+            console.log(chalk.gray('No overdue routines.'));
+            return;
+        }
+        console.log(chalk.bold(`${overdue.length} overdue routine(s):\n`));
+        for (const job of overdue) {
+            const last = job.lastRanAt ? job.lastRanAt.toLocaleString() : 'never';
+            console.log(`  ${chalk.cyan(job.name)} — missed ${chalk.gray(job.expectedAt.toLocaleString())}, last ran ${chalk.gray(last)}`);
+        }
+        if (options.dryRun) {
+            console.log(chalk.gray('\n(dry run — no jobs triggered)'));
+            return;
+        }
+        // Need the daemon alive so spawned jobs are monitored and meta.json is
+        // finalized. Start it if it isn't already running.
+        if (!isDaemonRunning()) {
+            const started = startDaemon();
+            if (started.pid) {
+                console.log(chalk.gray(`\nStarted scheduler (PID: ${started.pid}) so catchup runs are monitored.`));
+            }
+        }
+        console.log(chalk.bold('\nTriggering catchup runs...'));
+        for (const job of overdue) {
+            const config = readJob(job.name);
+            if (!config) {
+                console.log(`  ${job.name} → ${chalk.red('config not found')}`);
+                continue;
+            }
+            try {
+                const meta = await executeJobDetached(config);
+                console.log(`  ${job.name} → ${chalk.green('started')} (run: ${meta.runId}, PID: ${meta.pid ?? 'n/a'})`);
+            }
+            catch (err) {
+                console.log(`  ${job.name} → ${chalk.red('failed to start')}: ${err.message}`);
+            }
+        }
+        console.log(chalk.gray('\nTrack progress with: agents routines runs <name>'));
+    });
     routinesCmd
         .command('logs [name]')
         .description('Read stdout from the most recent execution. Use --run to see a specific past run.')

package/dist/commands/rules.js

@@ -7,11 +7,11 @@ import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverInstructionsFromRepo, discoverRuleFilesFromRepo, installInstructionsCentrally, uninstallInstructions, listInstalledInstructionsWithScope, instructionsExists, getInstructionsContent, listCentralRules, } from '../lib/rules/rules.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources, getActiveRulesPreset, setActiveRulesPreset } from '../lib/state.js';
 import { discoverRulesLayers } from '../lib/rules/compose.js';
 import * as yaml from 'yaml';
-import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, } from './utils.js';
+import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, } from './utils.js';
 /** Register the `agents rules` command tree (list, add, view, remove). */
 export function registerRulesCommands(program) {
     const rulesCmd = program
@@ -317,13 +317,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, ALL_AGENT_IDS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, ALL_AGENT_IDS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(ALL_AGENT_IDS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;

package/dist/commands/secrets-migrate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `agents secrets migrate-acl` — refresh existing keychain items so they pick
+ * up the new SecAccess ACL written by the signed Agents CLI.app helper.
+ *
+ * Items created before 1.19.2 (or by `security add-generic-password` directly)
+ * may carry the legacy "this-app-only" ACL that prompts the user for a
+ * password on every read. Re-writing them through the helper bakes in the
+ * empty trusted-app ACL that suppresses the prompt and lets the helper read
+ * them under LocalAuthentication instead.
+ *
+ * Sequence per item:
+ *   1. Read the current value (no auth prompt path — uses the unauthenticated
+ *      `security` CLI for non-sync items, helper `get` for sync items).
+ *   2. Append (item, value, sync) to an encrypted backup before any writes.
+ *   3. Delete + rewrite via the helper so macOS hands us a fresh ACL on the
+ *      new item.
+ *   4. Read back via the helper to verify the value round-trips.
+ *
+ * `--dry-run` (default) reports the planned actions. `--commit` performs the
+ * writes and produces the backup.
+ */
+import type { Command } from 'commander';
+/** Register `agents secrets migrate-acl` on the parent secrets Command. */
+export declare function registerSecretsMigrateAclCommand(secrets: Command): void;