@phnx-labs/agents-cli 1.19.2 → 1.20.0

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 } 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.
+        // In terminals that do not support OSC 8 the escape sequences are ignored and
+        // the label is displayed as plain text.
+        const link = (label, url) => url ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
+        const now = new Date();
+        const NAME_W = 24;
+        const AGENT_W = 10;
+        const REPO_W = 24;
+        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('-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/secrets.js

@@ -873,13 +873,12 @@ Examples:
         .option('--force', 'Overwrite existing 1Password items (used with --to-1password)')
         .action(async (bundleName, opts) => {
         try {
-            const { resolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
+            const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
-            const bundle = readBundle(resolvedBundleName);
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
-                const env = resolveBundleEnv(bundle, { caller: `1Password vault ${vault}` });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}` });
                 let created = 0;
                 let overwritten = 0;
                 let skipped = 0;
@@ -913,7 +912,7 @@ Examples:
                 console.error(chalk.red('export to a TTY requires --plaintext (prevents shoulder-surfing).'));
                 process.exit(1);
             }
-            const env = resolveBundleEnv(bundle, { caller: `export to shell` });
+            const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `export to shell` });
             const prefix = bundleToEnvPrefix(resolvedBundleName);
             for (const [k, v] of Object.entries(env)) {
                 const exportKey = isReservedEnvName(k) ? `${prefix}_${k}` : k;
@@ -939,10 +938,9 @@ Examples:
                 console.error(chalk.red('Usage: agents secrets exec <bundle> -- <command...>'));
                 process.exit(1);
             }
-            const { resolveBundleEnv } = await import('../lib/secrets/bundles.js');
-            const bundle = readBundle(bundleName);
+            const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
             const [cmd, ...args] = commandParts;
-            const secretEnv = resolveBundleEnv(bundle, { caller: `command ${cmd}` });
+            const { env: secretEnv } = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` });
             const { spawn } = await import('child_process');
             const proc = spawn(cmd, args, {
                 stdio: 'inherit',

package/dist/commands/sessions.d.ts

@@ -1,5 +1,33 @@
 import type { Command } from 'commander';
 import type { SessionMeta } from '../lib/session/types.js';
+import { type ActiveSession } from '../lib/session/active.js';
+/** Grouped + sorted view of active sessions for the --active renderer. */
+export interface ActiveSessionsLayout {
+    workspaces: Array<{
+        /** Internal grouping key — `__cloud__`, `__unknown__`, or the cwd. */
+        key: string;
+        /** Sessions in this workspace, both windowed and flat (preserves total count). */
+        total: number;
+        /** Terminals grouped by IDE window (sorted by oldest startedAtMs). */
+        windows: Array<{
+            windowId: string;
+            sessions: ActiveSession[];
+        }>;
+        /** Everything else in this workspace: cloud, teams, headless, terminals without a windowId. */
+        flat: ActiveSession[];
+    }>;
+}
+/**
+ * Group sessions by workspace, then split each workspace into IDE-window
+ * sub-groups + a flat bucket. Pure function — no I/O — so the renderer's
+ * grouping rules can be tested without mocking the session scanner.
+ *
+ * Sort order:
+ *   - workspaces: by session count descending, then key ascending
+ *   - windows within a workspace: by oldest startedAtMs ascending
+ *   - sessions within a window/flat bucket: input order preserved
+ */
+export declare function groupActiveSessions(sessions: ActiveSession[]): ActiveSessionsLayout;
 /**
  * Build the shell command that resumes a picked session.
  *

package/dist/commands/sessions.js

@@ -181,18 +181,45 @@ function buildSessionDescription(s) {
         return s.topic;
     return '';
 }
-/** Render the unified active-session view. */
-async function renderActiveSessions(asJson) {
-    const sessions = await getActiveSessions();
-    if (asJson) {
-        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
-        return;
-    }
-    if (sessions.length === 0) {
-        console.log(chalk.gray('No active agent sessions.'));
-        return;
-    }
-    // Group sessions by workspace (cwd), with cloud/undefined grouped separately
+/**
+ * Render a single agent-session row inside an already-printed group header.
+ * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
+ * window sub-group).
+ */
+function printActiveRow(s, indent) {
+    const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
+    const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
+    const statusCol = statusColor(s.status)(padRight(truncate(s.status, 7), 8));
+    const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
+    const desc = buildSessionDescription(s);
+    console.log(indent +
+        pidCol +
+        kindCol +
+        hostCol +
+        statusCol +
+        chalk.white(truncate(desc || '-', 50)));
+}
+/**
+ * Short label for an IDE window. The slice key in live-terminals.json is
+ * `${vscode.env.sessionId}-${ext-host pid}`; the trailing pid is the cheap
+ * stable disambiguator. We surface it as `ext-pid` so two windows on the
+ * same repo are visibly different.
+ */
+function shortWindowLabel(windowId) {
+    const m = windowId.match(/-(\d+)$/);
+    return m ? `ext-pid ${m[1]}` : `win ${windowId.slice(0, 8)}`;
+}
+/**
+ * Group sessions by workspace, then split each workspace into IDE-window
+ * sub-groups + a flat bucket. Pure function — no I/O — so the renderer's
+ * grouping rules can be tested without mocking the session scanner.
+ *
+ * Sort order:
+ *   - workspaces: by session count descending, then key ascending
+ *   - windows within a workspace: by oldest startedAtMs ascending
+ *   - sessions within a window/flat bucket: input order preserved
+ */
+export function groupActiveSessions(sessions) {
     const byWorkspace = new Map();
     for (const s of sessions) {
         const key = s.cwd ?? (s.context === 'cloud' ? '__cloud__' : '__unknown__');
@@ -200,7 +227,6 @@ async function renderActiveSessions(asJson) {
         list.push(s);
         byWorkspace.set(key, list);
     }
-    // Sort workspaces: most sessions first, then alphabetically
     const sortedKeys = Array.from(byWorkspace.keys()).sort((a, b) => {
         const aCount = byWorkspace.get(a).length;
         const bCount = byWorkspace.get(b).length;
@@ -208,33 +234,71 @@ async function renderActiveSessions(asJson) {
             return bCount - aCount;
         return a.localeCompare(b);
     });
-    let first = true;
-    for (const key of sortedKeys) {
+    const workspaces = sortedKeys.map((key) => {
         const group = byWorkspace.get(key);
+        const windowedSessions = [];
+        const flat = [];
+        for (const s of group) {
+            if (s.context === 'terminal' && s.windowId)
+                windowedSessions.push(s);
+            else
+                flat.push(s);
+        }
+        const byWindow = new Map();
+        for (const s of windowedSessions) {
+            const list = byWindow.get(s.windowId) || [];
+            list.push(s);
+            byWindow.set(s.windowId, list);
+        }
+        const windowKeys = Array.from(byWindow.keys()).sort((a, b) => {
+            const aStart = Math.min(...byWindow.get(a).map(s => s.startedAtMs ?? Infinity));
+            const bStart = Math.min(...byWindow.get(b).map(s => s.startedAtMs ?? Infinity));
+            return aStart - bStart;
+        });
+        return {
+            key,
+            total: group.length,
+            windows: windowKeys.map((wid) => ({ windowId: wid, sessions: byWindow.get(wid) })),
+            flat,
+        };
+    });
+    return { workspaces };
+}
+/** Render the unified active-session view. */
+async function renderActiveSessions(asJson) {
+    const sessions = await getActiveSessions();
+    if (asJson) {
+        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        return;
+    }
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No active agent sessions.'));
+        return;
+    }
+    const layout = groupActiveSessions(sessions);
+    let first = true;
+    for (const ws of layout.workspaces) {
         if (!first)
             console.log();
         first = false;
         // Print workspace header
-        const header = key === '__cloud__'
+        const header = ws.key === '__cloud__'
             ? chalk.magenta.bold('cloud')
-            : key === '__unknown__'
+            : ws.key === '__unknown__'
                 ? chalk.gray.bold('unknown')
-                : chalk.cyan.bold(shortCwd(key));
-        console.log(`${header} ${chalk.gray(`(${group.length})`)}`);
-        // Print each session in this workspace
-        for (const s of group) {
-            const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
-            const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
-            const statusCol = statusColor(s.status)(padRight(truncate(s.status, 7), 8));
-            const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
-            const desc = buildSessionDescription(s);
-            console.log('  ' +
-                pidCol +
-                kindCol +
-                hostCol +
-                statusCol +
-                chalk.white(truncate(desc || '-', 50)));
+                : chalk.cyan.bold(shortCwd(ws.key));
+        console.log(`${header} ${chalk.gray(`(${ws.total})`)}`);
+        for (const win of ws.windows) {
+            // Host is per-process, but every terminal in the same IDE window shares
+            // an ancestor — take the first non-empty host as the window's label.
+            const host = win.sessions.find((s) => s.host)?.host ?? 'terminal';
+            const winHeader = `${chalk.gray(host)} ${chalk.gray('·')} ${chalk.gray(shortWindowLabel(win.windowId))} ${chalk.gray(`(${win.sessions.length})`)}`;
+            console.log('  ' + winHeader);
+            for (const s of win.sessions)
+                printActiveRow(s, '    ');
         }
+        for (const s of ws.flat)
+            printActiveRow(s, '  ');
     }
     const runningCount = sessions.filter(s => s.status === 'running').length;
     const idleCount = sessions.filter(s => s.status === 'idle').length;
@@ -673,7 +737,8 @@ export function buildResumeCommand(session) {
         case 'openclaw':
         case 'rush':
         case 'hermes':
-            // Rush and Hermes sessions are captured artifacts, not resumable locally.
+        case 'grok':
+            // Grok (and some others) sessions are captured artifacts, not resumable the same way.
             return null;
     }
 }

package/dist/commands/setup.d.ts

@@ -9,6 +9,7 @@ import type { Command } from 'commander';
 export declare function runSetup(program: Command, options?: {
     force?: boolean;
     suppressFooter?: boolean;
+    systemRepo?: boolean;
 }): Promise<void>;
 /**
  * Ensure the system repo exists before running a command that needs it.

package/dist/commands/setup.js

@@ -68,38 +68,46 @@ export async function runSetup(program, options = {}) {
     for (const install of unmanaged) {
         sessionCounts[install.agentId] = countSessionFiles(install.agentId);
     }
+    const systemRepo = process.env.AGENTS_SYSTEM_REPO || DEFAULT_SYSTEM_REPO;
     console.log(chalk.bold('\nWelcome to agents-cli.'));
-    console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} into ~/.agents-system/.\n`));
-    ensureAgentsDir();
-    const spinner = ora('Cloning system repo...').start();
-    if (isGitRepo(agentsDir)) {
-        // --force on an existing repo: pull instead of re-clone
-        const result = await pullRepo(agentsDir);
-        if (!result.success) {
-            spinner.fail(`Pull failed: ${result.error}`);
-            console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
-            process.exit(1);
-        }
-        spinner.succeed(`Updated to ${result.commit}`);
+    if (options.systemRepo === false) {
+        ensureAgentsDir();
+        console.log(chalk.gray('Skipping system repo clone (--no-system-repo).'));
+        console.log(chalk.gray(`Populate ~/.agents-system/ yourself before running other commands that depend on it.\n`));
     }
     else {
-        // Check git is available
-        try {
-            const { execSync } = await import('child_process');
-            execSync('which git', { stdio: 'ignore' });
-        }
-        catch {
-            spinner.fail('git is not installed');
-            console.log(chalk.gray('Install git first: https://git-scm.com/downloads'));
-            process.exit(1);
+        console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(systemRepo)} into ~/.agents-system/.\n`));
+        ensureAgentsDir();
+        const spinner = ora('Cloning system repo...').start();
+        if (isGitRepo(agentsDir)) {
+            // --force on an existing repo: pull instead of re-clone
+            const result = await pullRepo(agentsDir);
+            if (!result.success) {
+                spinner.fail(`Pull failed: ${result.error}`);
+                console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
+                process.exit(1);
+            }
+            spinner.succeed(`Updated to ${result.commit}`);
         }
-        const result = await cloneIntoExisting(DEFAULT_SYSTEM_REPO, agentsDir);
-        if (!result.success) {
-            spinner.fail(`Clone failed: ${result.error}`);
-            console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
-            process.exit(1);
+        else {
+            // Check git is available
+            try {
+                const { execSync } = await import('child_process');
+                execSync('which git', { stdio: 'ignore' });
+            }
+            catch {
+                spinner.fail('git is not installed');
+                console.log(chalk.gray('Install git first: https://git-scm.com/downloads'));
+                process.exit(1);
+            }
+            const result = await cloneIntoExisting(systemRepo, agentsDir);
+            if (!result.success) {
+                spinner.fail(`Clone failed: ${result.error}`);
+                console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
+                process.exit(1);
+            }
+            spinner.succeed(`Cloned ${systemRepoSlug(systemRepo)} (${result.commit})`);
         }
-        spinner.succeed(`Cloned ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} (${result.commit})`);
     }
     // Offer to import existing unmanaged installations
     if (unmanaged.length > 0 && isInteractiveTerminal()) {
@@ -195,7 +203,8 @@ export function registerSetupCommand(program) {
     const setupCmd = program
         .command('setup')
         .description('First-time setup. Clones a config repo and installs agent CLIs.')
-        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)');
+        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)')
+        .option('--no-system-repo', 'Skip cloning the system repo (you must populate ~/.agents-system/ yourself)');
     setHelpSections(setupCmd, {
         examples: `
       # First-time setup (clones the system repo into ~/.agents-system/)

package/dist/commands/skills.js

@@ -394,17 +394,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents skills sync" is gone.'));
         console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune skills'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup skills'));
         process.exit(1);
     });
-    // `skills prune` moved to the top-level `agents prune` command.
+    // `skills prune` moved to the top-level `agents prune cleanup` command.
     skillsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents skills prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune skills   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup skills   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     skillsCmd

package/dist/commands/teams.js

@@ -21,6 +21,8 @@ const AGENT_NAMES = {
     gemini: 'Gemini',
     cursor: 'Cursor',
     opencode: 'OpenCode',
+    grok: 'Grok',
+    antigravity: 'Antigravity',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 const VALID_MODES = ['plan', 'edit', 'full'];
@@ -756,6 +758,11 @@ export function registerTeamsCommands(program) {
                 die(`Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
             }
         }
+        if (opts.worktree !== undefined) {
+            if (!opts.worktree || !/^[A-Za-z0-9_-]+$/.test(opts.worktree)) {
+                die(`Invalid worktree name '${opts.worktree}'. Use letters, numbers, '-', or '_'.`);
+            }
+        }
         const after = opts.after
             ? opts.after.split(',').map((s) => s.trim()).filter(Boolean)
             : [];
@@ -899,6 +906,12 @@ export function registerTeamsCommands(program) {
             console.log();
             if (staged) {
                 console.log(chalk.gray(`Start the ready teammates:  agents teams start ${team}`));
+                if (after.length > 0) {
+                    process.stderr.write(chalk.yellow(`\nWarning: this teammate has --after dependencies and will NEVER start on its own.\n` +
+                        `  A supervisor watch process is required to launch it when its deps complete.\n` +
+                        `  Run this in another terminal:\n` +
+                        `    agents teams start ${team} --watch\n`));
+                }
             }
             else {
                 console.log(chalk.gray(`Check in later:  agents teams status ${team}`));

package/dist/commands/versions.d.ts

@@ -1,10 +1,11 @@
 /**
  * Version management commands for installing, switching, and removing agent CLIs.
  *
- * Implements `agents add`, `agents remove`, `agents use`, and the deprecated
- * `agents list`. Handles npm-based installation, shim creation, config symlink
+ * Implements `agents add`, `agents prune`, `agents remove` (alias),
+ * `agents use`, and the deprecated `agents list`. Handles npm-based installation,
+ * shim creation, config symlink
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export declare function registerVersionsCommands(program: Command): void;