@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/dist/commands/pull.js

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

package/dist/commands/routines.js

@@ -11,11 +11,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonPid, readDaemonLog, } from '../lib/daemon.js';
+import { humanizeCron, humanizeNextRun, formatRepoLink } 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);
+                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);
+            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,11 +938,10 @@ 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 secretEnv = resolveBundleEnv(bundle);
-            const { spawn } = await import('child_process');
+            const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
             const [cmd, ...args] = commandParts;
+            const { env: secretEnv } = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` });
+            const { spawn } = await import('child_process');
             const proc = spawn(cmd, args, {
                 stdio: 'inherit',
                 env: { ...process.env, ...secretEnv },

package/dist/commands/sessions.d.ts

@@ -1,16 +1,45 @@
 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.
  *
- * Cross-version handoff: when the session was created on a different version
- * than the one the shim will launch (activeVersion), the session file lives in
- * the other version's isolated home and `--resume <id>` would silently fail to
- * find it. Fall back to a fresh session seeded with `/continue <id>`, which is
- * wired (~/.claude/commands/continue.md) to read the prior transcript via
- * `agents sessions <id>` — that reader is version-agnostic.
+ * When the session's originating version is known, uses the version-pinned
+ * binary (e.g. `claude@2.1.138`) so the resume always runs in the same
+ * isolated HOME where the JSONL was written — regardless of which version is
+ * currently the default. Falls back to the bare shim when version is unknown.
+ *
+ * If the versioned binary is missing (version was removed), the ENOENT
+ * handler in handlePickedSession retries via buildFallbackCommand.
  */
-export declare function buildResumeCommand(session: SessionMeta, activeVersion?: string): string[] | null;
+export declare function buildResumeCommand(session: SessionMeta): string[] | null;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /** Register the `agents sessions` command with all its options and help text. */

package/dist/commands/sessions.js

@@ -22,7 +22,7 @@ import { parseSession } from '../lib/session/parse.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
-import { resolveVersion, resolveVersionAliasLoose } from '../lib/versions.js';
+import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.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;
@@ -613,18 +677,12 @@ async function handlePickedSession(picked) {
     const cwd = picked.session.cwd && fs.existsSync(picked.session.cwd)
         ? picked.session.cwd
         : process.cwd();
-    const activeVersion = resolveVersion(picked.session.agent, cwd) ?? undefined;
-    const resume = buildResumeCommand(picked.session, activeVersion);
+    const resume = buildResumeCommand(picked.session);
     if (!resume) {
         console.log(chalk.yellow(`Resume is not supported for ${picked.session.agent} sessions yet. Showing summary instead.`));
         await renderSession(picked.session, 'summary', {});
         return;
     }
-    if (picked.session.version && activeVersion && picked.session.version !== activeVersion) {
-        console.log(chalk.gray(`Cross-version handoff: session is ${picked.session.agent} ${picked.session.version}, ` +
-            `default is ${activeVersion}. Starting fresh and passing /continue so the new agent ` +
-            `reads the prior transcript via 'agents sessions'.`));
-    }
     console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
     await new Promise((resolve) => {
         const child = spawn(resume[0], resume.slice(1), {
@@ -633,6 +691,16 @@ async function handlePickedSession(picked) {
             shell: false,
         });
         child.on('error', (err) => {
+            if (err.code === 'ENOENT' && picked.session.version) {
+                const fallback = buildFallbackCommand(picked.session);
+                if (fallback) {
+                    console.log(chalk.gray(`Version ${picked.session.version} is not installed. Falling back to current version via /continue...`));
+                    const fb = spawn(fallback[0], fallback.slice(1), { cwd, stdio: 'inherit', shell: false });
+                    fb.on('error', (e) => { console.error(chalk.red(`Failed: ${e.message}`)); resolve(); });
+                    fb.on('close', () => resolve());
+                    return;
+                }
+            }
             console.error(chalk.red(`Failed to launch ${resume[0]}: ${err.message}`));
             if (err.code === 'ENOENT') {
                 console.error(chalk.gray(`Make sure '${resume[0]}' is on your PATH.`));
@@ -645,23 +713,23 @@ async function handlePickedSession(picked) {
 /**
  * Build the shell command that resumes a picked session.
  *
- * Cross-version handoff: when the session was created on a different version
- * than the one the shim will launch (activeVersion), the session file lives in
- * the other version's isolated home and `--resume <id>` would silently fail to
- * find it. Fall back to a fresh session seeded with `/continue <id>`, which is
- * wired (~/.claude/commands/continue.md) to read the prior transcript via
- * `agents sessions <id>` — that reader is version-agnostic.
+ * When the session's originating version is known, uses the version-pinned
+ * binary (e.g. `claude@2.1.138`) so the resume always runs in the same
+ * isolated HOME where the JSONL was written — regardless of which version is
+ * currently the default. Falls back to the bare shim when version is unknown.
+ *
+ * If the versioned binary is missing (version was removed), the ENOENT
+ * handler in handlePickedSession retries via buildFallbackCommand.
  */
-export function buildResumeCommand(session, activeVersion) {
-    const versionMismatch = !!(session.version && activeVersion && session.version !== activeVersion);
+export function buildResumeCommand(session) {
     switch (session.agent) {
         case 'claude':
-            if (versionMismatch)
-                return ['claude', `/continue ${session.id}`];
+            if (session.version)
+                return [`claude@${session.version}`, '--resume', session.id];
             return ['claude', '--resume', session.id];
         case 'codex':
-            if (versionMismatch)
-                return ['codex', `/continue ${session.id}`];
+            if (session.version)
+                return [`codex@${session.version}`, 'resume', session.id];
             return ['codex', 'resume', session.id];
         case 'opencode':
             return ['opencode', '--session', session.id];
@@ -669,10 +737,19 @@ export function buildResumeCommand(session, activeVersion) {
         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;
     }
 }
+/** Fallback resume command when the versioned binary is unavailable (ENOENT). */
+function buildFallbackCommand(session) {
+    switch (session.agent) {
+        case 'claude': return ['claude', `/continue ${session.id}`];
+        case 'codex': return ['codex', `/continue ${session.id}`];
+        default: return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Cloud session source (--cloud)
 // ---------------------------------------------------------------------------