@phnx-labs/agents-cli 1.20.89 → 1.20.91

package/dist/commands/routines.js

@@ -19,9 +19,10 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, executeJobDetached, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
+import { executeJob, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
 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 { setHelpSections } from '../lib/help.js';
 import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
@@ -138,6 +139,21 @@ function deviceLabel(job, width) {
         : raw;
     return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
 }
+/**
+ * The last run THIS device can speak for.
+ *
+ * A run record is written by whichever daemon fired the routine, into that
+ * machine's own runs dir — records carry no device attribution, so a record
+ * found here only ever describes this device's history. When a routine is
+ * pinned away from this machine (`devices:` excludes it) any local record is a
+ * leftover from before the pin, and reporting it as the routine's status paints
+ * another device's healthy routine red. Report nothing instead; the local
+ * history stays readable via `agents routines runs <name>`, and the owning
+ * device's status via `agents routines list --device <name>`.
+ */
+export function localLatestRun(job) {
+    return jobRunsOnThisDevice(job) ? getLatestRun(job.name) : null;
+}
 export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     const groups = new Map();
     const add = (key, title, job) => {
@@ -146,7 +162,9 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
             existing.jobs.push(job);
             return;
         }
-        groups.set(key, { key, title, jobs: [job] });
+        // `device:` is the only group that describes a machine other than this one,
+        // so it is the only one whose rows this device cannot report a status for.
+        groups.set(key, { key, title, jobs: [job], local: !key.startsWith('device:') });
     };
     for (const job of jobs) {
         const strategy = resolveHostStrategy(job);
@@ -193,7 +211,7 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     };
     return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
 }
-function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = true }) {
     const NAME_W = 24;
     const AGENT_W = 10;
     const REPO_W = REPO_DISPLAY_MAX;
@@ -207,7 +225,7 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
     for (const job of jobs) {
         const nextStr = nextRunLabel(job, scheduler, now);
         const schedStr = scheduleLabel(job);
-        const latestRun = getLatestRun(job.name);
+        const latestRun = local ? localLatestRun(job) : null;
         const lastStatus = latestRun?.status || '-';
         const sourceRepo = job.source?.repo ?? job.repo;
         const sourceLabel = sourceRepo
@@ -225,7 +243,10 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
         const statusColor = lastStatus === 'completed' ? chalk.green
             : lastStatus === 'failed' ? chalk.red
                 : lastStatus === 'timeout' ? chalk.yellow
-                    : chalk.gray;
+                    // A miss is an infrastructure problem, not a task failure — the routine
+                    // never ran. Distinct from red so the two prompt different reactions.
+                    : lastStatus === 'missed' ? chalk.magenta
+                        : chalk.gray;
         const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
         const agentLabelPadded = job.command
             ? chalk.magenta('command'.padEnd(10))
@@ -509,7 +530,7 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const latestRun = getLatestRun(job.name);
+                const latestRun = localLatestRun(job);
                 return {
                     name: job.name,
                     agent: job.agent ?? null,
@@ -527,6 +548,7 @@ export function registerRoutinesCommands(program) {
                     sourceRepo: job.source?.repo ?? job.repo ?? null,
                     sourceBranch: job.source?.branch ?? null,
                     runOnce: Boolean(job.runOnce),
+                    catchup: job.catchup !== false,
                     oneShot: isOneShotRoutine(job),
                     expired: isPastOneShotRoutine(job, nowJson),
                     runsHere: jobRunsOnThisDevice(job),
@@ -562,9 +584,14 @@ export function registerRoutinesCommands(program) {
             catch (err) {
                 console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
             }
-            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+            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 });
+                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>'));
             }
         }
         if (overdueSet.size > 0) {
@@ -600,6 +627,7 @@ export function registerRoutinesCommands(program) {
         .option('--state-to <name>', 'Linear current-state filter for --on linear:<event> (e.g. Plan)')
         .option('--state-from <name>', 'Linear previous-state filter for --on linear:<event> (e.g. Triage)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
+        .option('--no-catchup', 'Do not run this routine late if its fire is missed (daemon down/asleep). The miss is still recorded. For routines whose value expires with their slot, e.g. a 9am brief.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .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('--json', 'Emit machine-readable JSON with the created routine id and status')
@@ -712,6 +740,7 @@ export function registerRoutinesCommands(program) {
                 ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
+                ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
                 ...(options.resume ? { resume: options.resume } : {}),
             };
@@ -1087,44 +1116,42 @@ export function registerRoutinesCommands(program) {
     });
     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')
+        .description('Run any routines that missed their last scheduled fire on demand. The daemon already does this every 5 minutes — use this to force a pass now. Detached: runs in the background under the scheduler.')
+        .option('--dry-run', 'Record the misses and list them without running anything')
         .action(async (options) => {
         const overdue = detectOverdueJobs();
         if (overdue.length === 0) {
-            console.log(chalk.gray('No overdue routines.'));
+            console.log(chalk.gray('No missed fires.'));
             return;
         }
-        console.log(chalk.bold(`${overdue.length} overdue routine(s):\n`));
+        console.log(chalk.bold(`${overdue.length} missed fire(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()) {
+        if (!options.dryRun && !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;
+        console.log(chalk.bold(options.dryRun ? '\nRecording misses...' : '\nTriggering catchup runs...'));
+        const outcomes = await runCatchup({ overdue, dryRun: options.dryRun });
+        for (const o of outcomes) {
+            if (o.result === 'ran') {
+                console.log(`  ${o.name} → ${chalk.green('started')} (run: ${o.runId})`);
             }
-            try {
-                const meta = await executeJobDetached(config);
-                console.log(`  ${job.name} → ${chalk.green('started')} (run: ${meta.runId}, PID: ${meta.pid ?? 'n/a'})`);
+            else if (o.result === 'recorded') {
+                const why = options.dryRun ? 'dry run' : 'catchup: false';
+                console.log(`  ${o.name} → ${chalk.yellow('recorded as missed')} (${why})`);
             }
-            catch (err) {
-                console.log(`  ${job.name} → ${chalk.red('failed to start')}: ${err.message}`);
+            else if (o.result === 'claimed-elsewhere') {
+                console.log(`  ${o.name} → ${chalk.gray('already claimed by the scheduler')}`);
+            }
+            else {
+                console.log(`  ${o.name} → ${chalk.red('failed to start')}: ${o.error}`);
             }
         }
         console.log(chalk.gray('\nTrack progress with: agents routines runs <name>'));
@@ -1248,8 +1275,9 @@ export function registerRoutinesCommands(program) {
         // is the concise view. Falls back to a bounded stdout tail when no report
         // was extracted (e.g. the run failed before finishing).
         const statusColor = run.status === 'completed' ? chalk.green
-            : run.status === 'failed' || run.status === 'timeout' ? chalk.red
-                : chalk.yellow;
+            : run.status === 'missed' ? chalk.magenta
+                : run.status === 'failed' || run.status === 'timeout' ? chalk.red
+                    : chalk.yellow;
         console.log(chalk.bold(name) + chalk.gray(`  run ${runId}`));
         console.log(statusColor(run.status) +
             chalk.gray(`  ${run.startedAt}`) +

package/dist/commands/secrets.d.ts

@@ -9,6 +9,7 @@ import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
+import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
@@ -51,6 +52,21 @@ export declare function buildRemoteUnlockArgs(names: string[], opts: {
     ttl?: string;
     durable?: boolean;
 }): string[];
+/**
+ * Build the remote `agents secrets list` argv for `list --host`. Every filter
+ * must be forwarded: `browseRemote` sends this argv verbatim, so a flag left out
+ * here is not an error — the remote just lists everything, and
+ * `secrets list --host zion --expired` reports every bundle on zion as expired.
+ * Silent and wrong beats loud and wrong only for the person who wrote the bug.
+ *
+ * Values pass through unparsed so the REMOTE validates them under its own rules,
+ * matching how `--ttl` is forwarded by buildRemoteUnlockArgs.
+ */
+export declare function buildRemoteListArgs(opts: SecretsListFilterOpts & {
+    json?: boolean;
+    sort?: string;
+    limit?: string;
+}, query?: string): string[];
 export { SSH_TARGET_RE, assertValidSshTarget };
 /**
  * Build the child environment for `agents secrets exec`. Strips
@@ -79,15 +95,47 @@ export declare function exportBundleToFile(env: Record<string, string>, filePath
  * Throws on a missing file, an invalid JSON envelope, or a wrong passphrase.
  */
 export declare function importBundleFromFile(filePath: string, passphrase: string): Record<string, string>;
-/** The POLICY column for `secrets list`: the prompt policy, plus a concise
- * state hint. `daily` shows `held Nh` when the secrets-agent is currently
- * caching the bundle; `always` and `never` show whether they prompt. `held`
+/** Compact span for a fixed duration: "45m" / "19h" / "2d". Shared by
+ * `compactRemaining` (a countdown) and the POLICY column's hold-window
+ * annotation (a fixed length) so the two can never round onto different unit
+ * thresholds and disagree about the same number of milliseconds. */
+export declare function compactDurationMs(ms: number): string;
+/** The POLICY column for `secrets list`. `hold` is a duration, not a mode — it
+ * means "prompt once, then stay silent for this long" — so the column states
+ * the window (`hold 7d`) rather than the bare tier name, and appends `· held Nd`
+ * while the secrets-agent is actually caching the bundle. `always` and `never`
+ * carry no window and gain nothing here. `holdMs` is the configured global hold
+ * (`secretsHoldMs()`), passed in rather than read so this stays pure; `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
-export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
+export declare function renderPolicyCol(b: SecretsBundle, holdMs: number, held?: Map<string, number>): string;
+/** The hold-window line at the top of `secrets status`. Names the `hold` policy
+ * the window belongs to — the rename in #1604 left this surface still saying
+ * "daily", the one name the CLI no longer accepts in its own help. Pure so the
+ * vocabulary is pinned by a test rather than re-drifting on the next rename. */
+export declare function renderHoldSummary(holdStr: string, configured: boolean): string;
+/** The empty-broker line under the hold summary. Named here, beside
+ * `renderHoldSummary`, for the same reason: it is the second line the rename
+ * left saying `daily`, and a test pins both. */
+export declare const NO_BUNDLES_HELD_LINE = "No bundles held. The next read of each hold-policy bundle will prompt once, then hold.";
 /** Human-readable hold window for `secrets status`. Sub-hour values render in
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
  * hours up to 2 days, whole days beyond. Pure — unit-tested. */
 export declare function formatHoldWindow(ms: number): string;
+/** A broker hold expiry, or null once it has lapsed. One definition of "held",
+ * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
+ * three can never disagree about the same bundle. */
+export declare function liveHold(expiresAt: number | undefined, now?: number): number | null;
+/**
+ * The EXPIRING cell. Counts keys needing attention — already expired plus due
+ * within 30 days — and colours by the worst of the two: red once anything has
+ * lapsed, yellow while everything is merely upcoming.
+ *
+ * Expired keys used to be invisible here. `countExpiringSoon` requires
+ * `d >= 0`, so a bundle whose token died last month rendered `-`, identical to
+ * one with no expiry at all; the only places it surfaced were `secrets view`
+ * and a hard abort at inject time, i.e. after it had already broken something.
+ */
+export declare function renderExpiringCol(b: SecretsBundle, now?: number): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the