@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/secrets.js

@@ -8,10 +8,12 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { registerSecretsSyncCommands } from './secrets-sync.js';
+import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -178,7 +180,6 @@ function humanAge(iso) {
 function renderBundleRow(b) {
     const entries = describeBundle(b);
     const keys = entries.length;
-    const sync = b.icloud_sync ? chalk.cyan('icloud') : '';
     const expiringCount = countExpiringSoon(b.meta);
     const expiring = expiringCount > 0 ? chalk.yellow(String(expiringCount)) : chalk.gray('-');
     // Timestamp distinction:
@@ -194,12 +195,11 @@ function renderBundleRow(b) {
         : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
     const head = `${chalk.cyan(b.name.padEnd(20))} ` +
         `${String(keys).padEnd(5)} ` +
-        `${padVisible(sync, 6)} ` +
         `${padVisible(expiring, 9)} ` +
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
         `${padVisible(used, 7)}`;
-    return b.description ? `${head} ${chalk.gray(b.description)}` : head.trimEnd();
+    return b.description ? `${head} ${chalk.gray(safePrint(b.description))}` : head.trimEnd();
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -220,6 +220,17 @@ function redact(value, reveal) {
         return '';
     return '*'.repeat(Math.min(value.length, 8));
 }
+/**
+ * Strip ASCII / C1 control bytes from a string before printing it to the
+ * terminal. Bundle descriptions, notes, and remote-supplied names can carry
+ * arbitrary text and a malicious value containing ANSI escape sequences (e.g.
+ * OSC 52 clipboard set, screen-clear, cursor moves) would otherwise be
+ * interpreted by the user's terminal. Allow tab and newline so multi-line
+ * notes still render; strip everything else in the C0/C1 ranges plus DEL.
+ */
+function safePrint(s) {
+    return s.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, '');
+}
 /**
  * Build a VarMeta patch from CLI flags. Validates each provided field. Returns
  * undefined if no meta flag was passed (so callers know to skip meta updates).
@@ -286,7 +297,7 @@ function renderMetaLine(meta, reveal) {
         parts.push(colored);
     }
     if (meta.note) {
-        let note = meta.note;
+        let note = safePrint(meta.note);
         if (!reveal && note.length > 80) {
             note = note.slice(0, 79) + '\u2026';
         }
@@ -314,7 +325,7 @@ function countExpiringSoon(meta) {
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain (iCloud-synced by default). Inject into agents via `agents run --secrets <name>`.');
+        .description('Named bundles of env variables backed by macOS Keychain (device-local, biometry-gated). Inject into agents via `agents run --secrets <name>`.');
     setHelpSections(cmd, {
         examples: `
       # Create a bundle
@@ -340,23 +351,22 @@ export function registerSecretsCommands(program) {
     `,
         notes: `
       Bundles are containers; secrets are the variables inside them. Keychain values
-      never touch disk in plaintext.
-
-      iCloud sync: new bundles use the iCloud-synced keychain by default so they
-      appear on other Macs (same iCloud account, iCloud Keychain enabled). Pass
-      --no-icloud-sync at create time to keep values device-local instead.
+      never touch disk in plaintext. Every item is device-local and gated by Touch ID
+      or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
       See also:
         agents secrets rotate <bundle> <key>           rotate value, preserve metadata
         agents secrets import <bundle> --from .env     bulk import from .env
         agents secrets import <bundle> --from-1password --vault <name>
         agents secrets generate [length]               generate a random password / PIN / hex
+        agents secrets migrate-acl                     upgrade legacy items to the biometry ACL
     `,
     });
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
-        { title: 'Utilities', names: ['exec', 'generate'] },
+        { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
+        { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
     ]);
     cmd
         .command('list')
@@ -369,7 +379,7 @@ export function registerSecretsCommands(program) {
             console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'SYNC'.padEnd(6)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
         for (const b of bundles) {
             console.log(renderBundleRow(b));
         }
@@ -387,11 +397,9 @@ export function registerSecretsCommands(program) {
             const entries = describeBundle(bundle);
             console.log(chalk.bold(bundle.name));
             if (bundle.description)
-                console.log(chalk.gray(bundle.description));
+                console.log(chalk.gray(safePrint(bundle.description)));
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
-            if (bundle.icloud_sync)
-                console.log(chalk.cyan('icloud_sync: true'));
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
@@ -408,19 +416,30 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
+            // Batch every keychain read into one helper call so --reveal pops
+            // Touch ID once for the whole bundle instead of once per key.
+            const revealedValues = new Map();
+            if (reveal) {
+                const items = entries
+                    .filter((e) => e.kind === 'keychain')
+                    .map((e) => secretsKeychainItem(bundle.name, e.detail));
+                try {
+                    const fetched = getKeychainTokens(items);
+                    for (const [item, value] of fetched)
+                        revealedValues.set(item, value);
+                }
+                catch {
+                    // Fall through to masked output on cancellation / batch failure.
+                }
+            }
             for (const e of entries) {
                 if (e.kind === 'keychain') {
                     const item = secretsKeychainItem(bundle.name, e.detail);
-                    const stored = hasKeychainToken(item, bundle.icloud_sync);
+                    const stored = hasKeychainToken(item);
                     const marker = stored ? chalk.green('stored') : chalk.red('missing');
                     let valueCol = `[keychain:${e.detail}] ${marker}`;
-                    if (reveal && stored) {
-                        try {
-                            valueCol = redact(getKeychainToken(item, bundle.icloud_sync), true);
-                        }
-                        catch {
-                            // fall through to masked
-                        }
+                    if (reveal && revealedValues.has(item)) {
+                        valueCol = redact(revealedValues.get(item), true);
                     }
                     console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${valueCol}`);
                 }
@@ -429,7 +448,7 @@ export function registerSecretsCommands(program) {
                     const literalValue = typeof raw === 'string'
                         ? raw
                         : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
-                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${literalValue}`);
+                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${redact(literalValue, reveal)}`);
                 }
                 else {
                     console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${e.detail}`);
@@ -451,7 +470,6 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--no-icloud-sync', 'Store keychain values device-local instead of syncing them via iCloud Keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
@@ -465,7 +483,6 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
-                icloud_sync: opts.icloudSync !== false,
                 vars: {},
             };
             writeBundle(bundle);
@@ -600,12 +617,11 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            setKeychainToken(item, secretValue, bundle.icloud_sync);
+            setKeychainToken(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
             writeBundle(bundle);
-            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in keychain (${item}).`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -665,8 +681,7 @@ Examples:
                 clearMeta: opts.clearMeta,
                 meta: metaPatch,
             });
-            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in ${where}.`));
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in keychain.`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -679,6 +694,7 @@ Examples:
         .command('remove [bundle] [key]')
         .description('Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.')
         .option('--keep-secret', 'Leave the keychain item in place after removing the ref from the bundle')
+        .option('-y, --yes', 'Skip the confirmation prompt when purging a keychain item')
         .action(async (bundleName, key, opts) => {
         try {
             const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
@@ -689,11 +705,28 @@ Examples:
                 process.exit(1);
             }
             const raw = bundle.vars[resolvedKey];
+            const willPurge = !opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:');
+            if (willPurge && !opts.yes) {
+                if (!isInteractiveTerminal()) {
+                    console.error(chalk.red(`Refusing to purge keychain item for ${resolvedBundleName}.${resolvedKey} non-interactively. ` +
+                        `Pass --yes to confirm or --keep-secret to retain the keychain entry.`));
+                    process.exit(1);
+                }
+                const { confirm } = await import('@inquirer/prompts');
+                const ok = await confirm({
+                    message: `Purge keychain item for ${resolvedBundleName}.${resolvedKey}? (use --keep-secret to retain)`,
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(chalk.gray('Aborted. Bundle metadata unchanged.'));
+                    return;
+                }
+            }
             delete bundle.vars[resolvedKey];
             writeBundle(bundle);
-            if (!opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:')) {
+            if (willPurge) {
                 const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
-                const removed = deleteKeychainToken(item, bundle.icloud_sync);
+                const removed = deleteKeychainToken(item);
                 if (removed) {
                     console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
                     return;
@@ -738,7 +771,7 @@ Examples:
             }
             if (!opts.keepSecrets) {
                 for (const { item } of keychainItemsForBundle(bundle)) {
-                    deleteKeychainToken(item, bundle.icloud_sync);
+                    deleteKeychainToken(item);
                 }
             }
             const existed = deleteBundle(resolvedName);
@@ -824,7 +857,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, envKey);
-                        setKeychainToken(item, value, bundle.icloud_sync);
+                        setKeychainToken(item, value);
                         bundle.vars[envKey] = keychainRef(envKey);
                     }
                     added++;
@@ -848,7 +881,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, key);
-                        setKeychainToken(item, value, bundle.icloud_sync);
+                        setKeychainToken(item, value);
                         bundle.vars[key] = keychainRef(key);
                     }
                     added++;
@@ -873,13 +906,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;
@@ -909,11 +941,11 @@ Examples:
                 console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
                 return;
             }
-            if (isInteractiveTerminal() && !opts.plaintext) {
-                console.error(chalk.red('export to a TTY requires --plaintext (prevents shoulder-surfing).'));
+            if (!opts.plaintext) {
+                console.error(chalk.red('export prints secrets in the clear and requires --plaintext (works for TTY and pipes alike).'));
                 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 +971,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',
@@ -1035,4 +1066,6 @@ Examples:
             console.log(password);
         }
     });
+    registerSecretsSyncCommands(cmd);
+    registerSecretsMigrateAclCommand(cmd);
 }

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/)