@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/commands/projects.js

@@ -0,0 +1,358 @@
+/**
+ * `agents projects` — named, multi-repo projects and the progress
+ * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
+ * `lib/projects.ts`); this registers the command tree over them. Beta-gated on
+ * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ *
+ * The headline is `status`: instead of the vague per-agent activity line, it
+ * rolls every session up by project (matched on cwd) into one card — agents by
+ * lifecycle state, plan completion, open PRs, and tickets in flight.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { execFileSync, spawnSync } from 'child_process';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
+import { setHelpSections } from '../lib/help.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { parseOwnerRepoFromRemote } from '../lib/registry.js';
+import { toHomeRelative } from '../lib/project-root.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { factoryProjectsPath } from '../lib/auto-dispatch.js';
+import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
+import { rollupSessionsByProject, planPct, enrichProjectSignals, } from '../lib/project-status.js';
+/** `path:purpose` → a context anchor. Purpose may contain colons. */
+function parseContextFlag(raw) {
+    const i = raw.indexOf(':');
+    if (i === -1)
+        return { path: raw.trim(), purpose: '' };
+    return { path: raw.slice(0, i).trim(), purpose: raw.slice(i + 1).trim() };
+}
+/** Best-effort `owner/repo` from a repo's origin remote. */
+function originSlug(cwd) {
+    try {
+        const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8' }).trim();
+        return parseOwnerRepoFromRemote(url) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusBar(r) {
+    const parts = [];
+    const push = (n, label, color) => {
+        if (n && n > 0)
+            parts.push(color(`${n} ${label}`));
+    };
+    push(r.byStatus.running, 'running', chalk.green);
+    push(r.byStatus.idle, 'idle', chalk.gray);
+    push(r.byStatus.input_required, 'need-input', chalk.yellow);
+    push(r.byStatus.queued, 'queued', chalk.gray);
+    const shown = (r.byStatus.running ?? 0) + (r.byStatus.idle ?? 0) + (r.byStatus.input_required ?? 0) + (r.byStatus.queued ?? 0);
+    // Sessions in a non-live state (orphaned/crashed/unknown) count toward the
+    // headline — render the remainder so the bar never sums to less than it.
+    if (r.agents > shown)
+        parts.push(chalk.gray(`+${r.agents - shown} other`));
+    return parts.join(' · ') || chalk.gray('no live agents');
+}
+function renderCard(def, r, remote) {
+    const agents = r?.agents ?? 0;
+    const pct = r ? planPct(r.plan) : undefined;
+    const planStr = pct === undefined ? '' : `  ·  ${chalk.cyan(`${pct}% plan`)}`;
+    console.log(`${chalk.bold(def.name)}  ${chalk.dim('·')}  ${chalk.bold(`${agents} agents`)}${planStr}`);
+    if (def.description)
+        console.log(`  ${chalk.dim(def.description)}`);
+    console.log(`  ${chalk.dim('live')}     ${r ? statusBar(r) : chalk.gray('no live agents')}`);
+    const ships = [];
+    if (remote?.mergedPrs)
+        ships.push(chalk.green(`${remote.mergedPrs} merged (${remote.windowDays}d)`));
+    if (r?.openPrs.length)
+        ships.push(`${r.openPrs.length} open PR${r.openPrs.length === 1 ? '' : 's'}`);
+    if (r?.worktrees)
+        ships.push(`${r.worktrees} worktree${r.worktrees === 1 ? '' : 's'}`);
+    if (ships.length)
+        console.log(`  ${chalk.dim('ships')}    ${ships.join(' · ')}`);
+    if (r && r.tickets.length) {
+        console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
+    }
+    if (remote?.artifacts) {
+        const last = remote.lastArtifact ? `  ${chalk.dim(`· last: ${remote.lastArtifact}`)}` : '';
+        console.log(`  ${chalk.dim('proof')}    ${remote.artifacts} artifact${remote.artifacts === 1 ? '' : 's'} (${remote.windowDays}d)${last}`);
+    }
+    const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
+    if (repos.length)
+        console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
+    if (def.contexts?.length) {
+        console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
+    }
+    if (def.integrations?.length) {
+        console.log(`  ${chalk.dim('links')}    ${def.integrations.map((i) => i.label ?? i.kind).join(' · ')}`);
+    }
+    console.log('');
+}
+export function registerProjectsCommands(program) {
+    const enabled = isBetaEnabled('projects');
+    const projects = program
+        .command('projects', { hidden: !enabled })
+        .description('Named multi-repo projects with a progress rollup.');
+    setHelpSections(projects, {
+        examples: `
+      agents projects add rush --repo phnx-labs/rush --path apps/web
+      agents projects list
+      agents projects status              # progress card for every project
+      agents projects status rush --json  # one project, machine-readable
+      agents run --project rush           # land an agent in the project
+    `,
+        notes: `
+      Definitions are hand-editable YAML in ~/.agents/projects/ and sync across
+      machines with 'agents push/pull'. Enable with: agents beta enable projects.
+    `,
+    });
+    projects.hook('preAction', () => {
+        if (enabled)
+            return;
+        console.error(chalk.red('agents projects is in beta.'));
+        console.error(chalk.gray(betaEnableHint('projects')));
+        process.exit(1);
+    });
+    // ---- list ----
+    projects
+        .command('list')
+        .description('List defined projects with their root, repo, and live agent count.')
+        .option('--json', 'Machine-readable output')
+        .action(async (opts) => {
+        const defs = listProjectDefs();
+        if (opts.json) {
+            const roll = rollupSessionsByProject(defs, await getActiveSessions());
+            console.log(JSON.stringify(defs.map((d) => ({ ...d, agents: roll.get(d.name)?.agents ?? 0 })), null, 2));
+            return;
+        }
+        if (!defs.length) {
+            console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const roll = rollupSessionsByProject(defs, await getActiveSessions());
+        for (const d of defs) {
+            const agents = roll.get(d.name)?.agents ?? 0;
+            const repo = d.repo ?? d.repos?.[0]?.slug ?? '';
+            console.log(`  ${chalk.bold(d.name.padEnd(16))} ${chalk.dim((d.root ?? d.defaultPath ?? '').padEnd(32))} ${chalk.cyan(repo.padEnd(24))} ${agents} agents`);
+        }
+    });
+    // ---- add ----
+    projects
+        .command('add <name>')
+        .description('Define a project. Infers root and repo from the current git repo when not given.')
+        .option('--root <path>', 'Repo / monorepo root (defaults to the current git repo root)')
+        .option('--path <subdir>', 'Default cwd for agents (a monorepo subdir)')
+        .option('--repo <owner/repo>', 'Primary GitHub slug (defaults to the origin remote)')
+        .option('--context <path:purpose...>', 'A described starting point; repeatable')
+        .option('--linear <url-or-id>', 'Linear project URL or id')
+        .option('--force', 'Overwrite an existing definition')
+        .action(async (name, opts) => {
+        if (!isSafeProjectName(name)) {
+            console.error(chalk.red(`Invalid project name: "${name}" (letters, digits, ., _, - only)`));
+            process.exit(1);
+        }
+        if (loadProjectDef(name) && !opts.force) {
+            console.error(chalk.red(`Project "${name}" already exists. Use --force to overwrite, or 'agents projects edit ${name}'.`));
+            process.exit(1);
+        }
+        const cwd = process.cwd();
+        let root = opts.root;
+        if (!root) {
+            try {
+                root = toHomeRelative(await getMainRepoRoot(cwd));
+            }
+            catch {
+                console.error(chalk.red('Not inside a git repo — pass --root <path> explicitly.'));
+                process.exit(1);
+            }
+        }
+        const repo = opts.repo ?? originSlug(cwd);
+        const def = { name, root };
+        if (opts.path)
+            def.defaultPath = `${root.replace(/\/$/, '')}/${opts.path.replace(/^\//, '')}`;
+        if (repo)
+            def.repo = repo;
+        if (opts.context?.length)
+            def.contexts = opts.context.map(parseContextFlag);
+        if (opts.linear) {
+            def.linear = /^https?:/.test(opts.linear) ? { url: opts.linear } : { projectId: opts.linear };
+        }
+        const target = writeProjectDef(def);
+        console.log(chalk.green(`Defined project "${name}"`));
+        console.log(chalk.gray(`  ${target}`));
+        console.log(chalk.gray(`  root ${def.root}${def.repo ? `  ·  repo ${def.repo}` : ''}`));
+    });
+    // ---- show ----
+    projects
+        .command('show <name>')
+        .description('Show a project definition, resolved paths, repos, contexts, and links.')
+        .option('--json', 'Machine-readable output')
+        .action((name, opts) => {
+        const def = loadProjectDef(name);
+        if (!def) {
+            console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(def, null, 2));
+            return;
+        }
+        console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
+        if (def.root)
+            console.log(`  root         ${def.root}`);
+        if (def.defaultPath)
+            console.log(`  defaultPath  ${def.defaultPath}`);
+        const repos = [def.repo, ...(def.repos ?? []).map((r) => (r.subpath ? `${r.slug} (${r.subpath})` : r.slug))].filter(Boolean);
+        if (repos.length)
+            console.log(`  repos        ${repos.join(', ')}`);
+        for (const c of def.contexts ?? [])
+            console.log(`  context      ${chalk.cyan(c.path)} — ${c.purpose}`);
+        for (const i of def.integrations ?? [])
+            console.log(`  ${i.kind.padEnd(12)} ${i.url}${i.label ? chalk.dim(`  (${i.label})`) : ''}`);
+        if (def.linear?.url || def.linear?.projectId)
+            console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
+        for (const d of def.docs ?? [])
+            console.log(`  doc          ${d}`);
+        console.log(chalk.gray(`  ${projectDefPath(name)}`));
+    });
+    // ---- edit ----
+    projects
+        .command('edit <name>')
+        .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
+        .action((name) => {
+        const target = projectDefPath(name);
+        if (!fs.existsSync(target)) {
+            console.error(chalk.red(`No project named "${name}". Create it: agents projects add ${name}`));
+            process.exit(1);
+        }
+        const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
+        // $EDITOR commonly carries args ("code --wait") — split like monitors/routines do.
+        const parts = editor.split(/\s+/).filter(Boolean);
+        const res = spawnSync(parts[0], [...parts.slice(1), target], { stdio: 'inherit' });
+        process.exit(res.status ?? 0);
+    });
+    // ---- status ----
+    projects
+        .command('status [name]')
+        .description('Progress rollup: agents, plan %, merged/open PRs, tickets, and artifacts per project.')
+        .option('--json', 'Machine-readable output')
+        .option('--window <days>', 'Window for merged PRs and artifacts', '7')
+        .option('--no-remote', 'Skip the GitHub lookup (merged-PR count); faster, offline')
+        .action(async (name, opts) => {
+        const all = listProjectDefs();
+        // Named lookup goes through the strict single-def loader so a broken
+        // <name>.yaml surfaces its validation error instead of "No project named".
+        const defs = name ? [loadProjectDef(name)].filter((d) => d !== undefined) : all;
+        if (name && !defs.length) {
+            console.error(chalk.red(`No project named "${name}".`));
+            process.exit(1);
+        }
+        if (!defs.length) {
+            if (opts.json)
+                console.log('[]');
+            else
+                console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
+            return;
+        }
+        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
+        const nowMs = Date.now();
+        const roll = rollupSessionsByProject(all, await getActiveSessions());
+        // Enrich only the shown projects. --no-remote still reads the local artifact
+        // log but skips the gh call (def.repo left unused → mergedPrs stays 0).
+        const remote = new Map();
+        await Promise.all(defs.map(async (d) => {
+            remote.set(d.name, await enrichProjectSignals(d, windowDays, nowMs, { skipRemote: opts.remote === false }));
+        }));
+        if (opts.json) {
+            console.log(JSON.stringify(defs.map((d) => {
+                const r = roll.get(d.name);
+                const rem = remote.get(d.name);
+                return {
+                    name: d.name,
+                    agents: r?.agents ?? 0,
+                    byStatus: r?.byStatus ?? {},
+                    plan: r?.plan ?? { done: 0, total: 0 },
+                    planPct: r ? planPct(r.plan) ?? null : null,
+                    openPrs: r?.openPrs ?? [],
+                    mergedPrs: rem?.mergedPrs ?? 0,
+                    tickets: r?.tickets ?? [],
+                    worktrees: r?.worktrees ?? 0,
+                    artifacts: rem?.artifacts ?? 0,
+                    lastArtifact: rem?.lastArtifact ?? null,
+                    windowDays,
+                    repos: [d.repo, ...(d.repos ?? []).map((r2) => r2.slug)].filter(Boolean),
+                };
+            }), null, 2));
+            return;
+        }
+        for (const d of defs)
+            renderCard(d, roll.get(d.name), remote.get(d.name));
+    });
+    // ---- import ----
+    projects
+        .command('import')
+        .description('Absorb the Factory project registry (~/.agents/factory/projects.json) into YAML definitions.')
+        .requiredOption('--from-factory', 'Import from the Factory projects.json registry')
+        .option('--force', 'Overwrite existing definitions')
+        .action((opts) => {
+        const src = factoryProjectsPath();
+        let rawText;
+        try {
+            rawText = fs.readFileSync(src, 'utf8');
+        }
+        catch {
+            console.error(chalk.red(`No Factory registry at ${src}`));
+            process.exit(1);
+        }
+        let rows;
+        try {
+            rows = JSON.parse(rawText);
+        }
+        catch {
+            console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+            process.exit(1);
+        }
+        const list = Array.isArray(rows) ? rows : Array.isArray(rows.projects) ? rows.projects : [];
+        let created = 0;
+        let skipped = 0;
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const o = raw;
+            const name = typeof o.name === 'string' ? o.name : undefined;
+            if (!name || !isSafeProjectName(name)) {
+                skipped++;
+                continue;
+            }
+            if (loadProjectDef(name) && !opts.force) {
+                skipped++;
+                continue;
+            }
+            const def = { name };
+            if (typeof o.path === 'string')
+                def.root = toHomeRelative(o.path);
+            if (typeof o.repoSlug === 'string')
+                def.repo = o.repoSlug;
+            if (typeof o.linearProjectId === 'string')
+                def.linear = { projectId: o.linearProjectId };
+            writeProjectDef(def);
+            created++;
+        }
+        console.log(chalk.green(`Imported ${created} project${created === 1 ? '' : 's'}${skipped ? chalk.gray(` (${skipped} skipped)`) : ''}`));
+    });
+    // ---- rm ----
+    projects
+        .command('rm <name>')
+        .alias('remove')
+        .description('Delete a project definition. Never touches the repo.')
+        .action((name) => {
+        if (removeProjectDef(name)) {
+            console.log(chalk.green(`Removed project "${name}"`));
+        }
+        else {
+            console.error(chalk.red(`No project named "${name}".`));
+            process.exit(1);
+        }
+    });
+}

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';
@@ -242,7 +243,10 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = tru
         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))
@@ -544,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),
@@ -622,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')
@@ -734,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 } : {}),
             };
@@ -1109,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>'));
@@ -1270,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,11 +95,19 @@ 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. `hold` 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
@@ -97,6 +121,21 @@ export declare const NO_BUNDLES_HELD_LINE = "No bundles held. The next read of e
  * 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