@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/commands/routines.js

@@ -16,6 +16,7 @@ import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
 import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
+import { evaluateActivationReadinessLive } from '../lib/routine-readiness.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -724,6 +725,8 @@ export function registerRoutinesCommands(program) {
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .option('--project <name>', 'Associate with a named project (repeatable; use --all-projects for all)', collectProject, [])
         .option('--all-projects', 'Associate this routine with all defined projects (sets projects: ["*"])')
+        .option('--project-anchor <name>', 'Singular EXECUTION anchor: the named project whose base directory the run lands in (distinct from --project, which is grouping metadata). Rootless (Linear-imported) projects anchor a relative --cwd at the target home.')
+        .option('--cwd <path>', 'Portable execution directory. Relative values resolve under --project-anchor when usable, otherwise under the execution target $HOME. Supersedes --run-cwd/remoteCwd.')
         .option('--json', 'Emit machine-readable JSON with the created routine id and status')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
@@ -852,6 +855,8 @@ export function registerRoutinesCommands(program) {
                 ...(options.runOn ? { host: options.runOn } : {}),
                 ...(hostStrategy ? { hostStrategy } : {}),
                 ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
+                ...(options.projectAnchor ? { project: options.projectAnchor } : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
@@ -867,7 +872,23 @@ export function registerRoutinesCommands(program) {
                 process.exit(1);
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!devices || devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            // Readiness gate: a routine only activates when its execution context
+            // resolves and the harness is available. A proven blocker saves the
+            // definition PAUSED with a stable code + repair, so a broken routine can
+            // never fire (and storm) — the plan's save-paused contract.
+            const deviceMatch = !devices || devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready) {
+                const r = readiness.readiness;
+                if (!options.json) {
+                    console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                }
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -875,8 +896,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -933,7 +957,17 @@ export function registerRoutinesCommands(program) {
                 console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
             }
             writeJob(config);
-            setJobEnabled(config.name, config.enabled && (!config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()))));
+            const deviceMatch = !config.devices || config.devices.map(normalizeHost).includes(normalizeHost(machineId()));
+            const readiness = await evaluateActivationReadinessLive(config);
+            const activate = config.enabled && deviceMatch && readiness.ready;
+            setJobEnabled(config.name, activate);
+            if (config.enabled && deviceMatch && !readiness.ready && !options.json) {
+                const r = readiness.readiness;
+                console.log(chalk.yellow(`Saved paused — not ready to activate: ${r.code}`));
+                console.log(chalk.gray(`  ${r.message}`));
+                if (r.repair)
+                    console.log(chalk.gray(`  repair: ${r.repair}`));
+            }
             if (options.json) {
                 writeJson({
                     ok: true,
@@ -941,8 +975,11 @@ export function registerRoutinesCommands(program) {
                     job: config,
                     jobId: config.name,
                     name: config.name,
-                    status: 'added',
+                    status: activate ? 'added' : 'added_paused',
                     enabled: config.enabled,
+                    activated: activate,
+                    ready: readiness.ready,
+                    ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
                     schedule: config.schedule ?? null,
                     trigger: config.trigger ?? null,
                 });
@@ -1029,7 +1066,8 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('edit [name]')
-        .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
+        .description('Edit a prefilled routine transactionally; invalid YAML never replaces the live definition.')
+        .option('--yaml', 'Open the raw YAML in $EDITOR (the current edit surface)')
         .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
         .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
         .action(async (name, options) => {
@@ -1048,53 +1086,55 @@ export function registerRoutinesCommands(program) {
                 existing.trigger.stateTo = options.stateTo || undefined;
             if (options.stateFrom !== undefined)
                 existing.trigger.stateFrom = options.stateFrom || undefined;
-            writeJob(existing);
         }
         const jobPath = getJobPath(name);
-        if (!jobPath) {
-            // Job doesn't exist - create a new one
-            const cronDir = getRoutinesDir();
-            const newPath = safeJoin(cronDir, `${name}.yml`);
-            // Create template
-            const template = yaml.stringify({
+        const cronDir = getRoutinesDir();
+        fs.mkdirSync(cronDir, { recursive: true });
+        const targetPath = jobPath || safeJoin(cronDir, `${name}.yml`);
+        const editPath = safeJoin(cronDir, `.${name}.edit-${process.pid}.yml`);
+        const initial = existing
+            ? yaml.stringify(existing)
+            : yaml.stringify({
                 name,
                 schedule: '0 9 * * *',
                 agent: 'claude',
                 prompt: 'Your prompt here',
             });
-            fs.writeFileSync(newPath, template, 'utf-8');
-            console.log(chalk.gray(`Created new job file: ${newPath}`));
-        }
-        const targetPath = jobPath || path.join(getRoutinesDir(), `${name}.yml`);
+        fs.writeFileSync(editPath, initial, { encoding: 'utf-8', mode: 0o600 });
         const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const editorParts = editor.split(/\s+/).filter(Boolean);
         const editorBin = editorParts[0];
-        const editorArgs = [...editorParts.slice(1), targetPath];
+        const editorArgs = [...editorParts.slice(1), editPath];
         const { spawn: spawnSync } = await import('child_process');
         const child = spawnSync(editorBin, editorArgs, {
             stdio: 'inherit',
         });
-        child.on('close', (code) => {
-            if (code === 0) {
-                // Validate the edited file
-                const job = readJob(name);
-                if (job) {
-                    const errors = validateJob(job);
-                    if (errors.length > 0) {
-                        console.log(chalk.yellow('\nWarning: Job has validation errors:'));
-                        for (const err of errors) {
-                            console.log(chalk.yellow(`  - ${err}`));
-                        }
-                    }
-                    else {
-                        console.log(chalk.green(`\nJob '${name}' saved`));
-                        if (isDaemonRunning()) {
-                            signalDaemonReload();
-                            console.log(chalk.gray('Daemon reloaded'));
-                        }
-                    }
+        child.on('close', async (code) => {
+            if (code !== 0) {
+                fs.rmSync(editPath, { force: true });
+                return;
+            }
+            try {
+                const raw = fs.readFileSync(editPath, 'utf-8');
+                const job = yaml.parse(raw);
+                const errors = validateJob(job);
+                if (errors.length > 0)
+                    throw new Error(errors.join('\n'));
+                const readiness = await evaluateActivationReadinessLive(job);
+                fs.renameSync(editPath, targetPath);
+                if (!readiness.ready)
+                    setJobEnabled(job.name, false);
+                console.log(chalk.green(`\nJob '${name}' saved${readiness.ready ? '' : ' paused (not ready)'}`));
+                if (isDaemonRunning()) {
+                    signalDaemonReload();
+                    console.log(chalk.gray('Daemon reloaded'));
                 }
             }
+            catch (err) {
+                fs.rmSync(editPath, { force: true });
+                console.error(chalk.red(`\nRoutine not saved: ${err.message}`));
+                process.exitCode = 1;
+            }
         });
     });
     routinesCmd
@@ -1498,6 +1538,79 @@ export function registerRoutinesCommands(program) {
         console.log(chalk.gray(`Run: ${runId}\n`));
         console.log(fs.readFileSync(reportPath, 'utf-8'));
     });
+    routinesCmd
+        .command('doctor [name]')
+        .description('Check a routine\'s execution-context and harness readiness. Bare or --all checks every routine; --fix applies safe activation repairs (activate a now-ready paused routine; pause a broken active one).')
+        .option('--all', 'Check every routine (the default when no name is given)')
+        .option('--fix', 'Apply safe, deterministic activation repairs')
+        .option('--json', 'Machine-readable output')
+        .action(async (name, options) => {
+        const all = options.all || !name;
+        let targets;
+        if (all) {
+            targets = listAllJobs();
+        }
+        else {
+            const job = readJob(name);
+            if (!job) {
+                if (options.json) {
+                    writeJson({ ok: false, error: `routine '${name}' not found` });
+                    return;
+                }
+                console.error(chalk.red(`Routine '${name}' not found`));
+                process.exit(1);
+            }
+            targets = [job];
+        }
+        const thisDevice = normalizeHost(machineId());
+        const results = await Promise.all(targets.map(async (job) => {
+            const deviceMatch = !job.devices || job.devices.map(normalizeHost).includes(thisDevice);
+            const readiness = await evaluateActivationReadinessLive(job);
+            // `job.enabled` reflects THIS device's activation state (applyDeviceActivation).
+            let action;
+            if (options.fix && deviceMatch) {
+                if (readiness.ready && !job.enabled) {
+                    setJobEnabled(job.name, true);
+                    action = 'activated';
+                }
+                else if (!readiness.ready && job.enabled) {
+                    setJobEnabled(job.name, false);
+                    action = 'paused';
+                }
+            }
+            return {
+                name: job.name,
+                ready: readiness.ready,
+                active: job.enabled,
+                deviceScoped: deviceMatch,
+                ...(readiness.readiness ? { readiness: readiness.readiness } : {}),
+                ...(action ? { action } : {}),
+            };
+        }));
+        if (options.fix && results.some((r) => r.action) && isDaemonRunning()) {
+            signalDaemonReload();
+        }
+        if (options.json) {
+            writeJson({ ok: true, results });
+            return;
+        }
+        const blocked = results.filter((r) => !r.ready);
+        for (const r of results) {
+            if (r.ready) {
+                console.log(`${chalk.green('✓')} ${r.name}${r.action === 'activated' ? chalk.gray(' (activated)') : ''}`);
+            }
+            else {
+                const rd = r.readiness;
+                console.log(`${chalk.red('✗')} ${r.name} — ${chalk.yellow(rd.code)}${r.action === 'paused' ? chalk.gray(' (paused)') : ''}`);
+                console.log(chalk.gray(`    ${rd.message}`));
+                if (rd.repair)
+                    console.log(chalk.gray(`    repair: ${rd.repair}`));
+            }
+        }
+        if (blocked.length > 0 && !options.fix) {
+            console.log(chalk.gray(`\n${blocked.length} routine${blocked.length === 1 ? '' : 's'} blocked — re-run with --fix to pause them, or apply each repair above.`));
+        }
+    });
     routinesCmd
         .command('resume [name]')
         .description('Re-enable a paused routine so the daemon schedules it again')
@@ -1509,6 +1622,21 @@ export function registerRoutinesCommands(program) {
                 return;
         }
         try {
+            // Resume re-runs readiness — it can never bypass a proven blocker (the
+            // plan: "resume cannot bypass readiness"). A blocked routine stays paused.
+            const job = readJob(name);
+            if (job) {
+                const readiness = await evaluateActivationReadinessLive(job);
+                if (!readiness.ready) {
+                    const r = readiness.readiness;
+                    console.log(chalk.red(`Cannot resume '${name}' — not ready: ${r.code}`));
+                    console.log(chalk.gray(`  ${r.message}`));
+                    if (r.repair)
+                        console.log(chalk.gray(`  repair: ${r.repair}`));
+                    console.log(chalk.gray(`  fix it, then: agents routines doctor ${name} --fix`));
+                    process.exit(1);
+                }
+            }
             setJobEnabled(name, true);
             console.log(chalk.green(`Job '${name}' resumed`));
             if (isDaemonRunning()) {

package/dist/commands/sessions-browser.js

@@ -18,7 +18,7 @@ import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { AGENTS } from '../lib/agents.js';
-import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
+import { enrichTeamOrigins, safeTeamText, shouldShowTeamSessions } from '../lib/session/team-filter.js';
 import { listBookmarks, toggleBookmark } from '../lib/session/bookmarks.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
@@ -280,7 +280,7 @@ async function fetchRawPool(f, self, local, hosts, fixedFilters = false) {
             origin: f.routine ? 'routine' : undefined,
             skill: f.skill,
             plugin: f.plugin,
-            excludeTeamOrigin: !f.teams,
+            excludeTeamOrigin: !shouldShowTeamSessions(f),
             // A team filter reaches back past the usual browse window, so the pool it
             // draws from has to as well — otherwise the newest 500 rows decide which
             // teams exist.

package/dist/commands/sessions.d.ts

@@ -434,7 +434,7 @@ export interface RoutineChoice {
     latestRunSessionCount: number;
 }
 export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
-export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function buildRoutineChoices(sessions: SessionMeta[], runOnlyNames?: string[]): RoutineChoice[];
 export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */

package/dist/commands/sessions.js

@@ -33,7 +33,7 @@ import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/
 import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, getSessionById } from '../lib/session/db.js';
-import { filterTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
+import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
 import { formatRelativeTime, formatCompactAge, sessionAgeParts } from '../lib/session/relative-time.js';
@@ -43,6 +43,7 @@ import { sessionOwnerDevice, RESUME_PINNED_ENV } from '../lib/session/resume-own
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
+import { listJobs, listJobsWithRuns, listRuns } from '../lib/routines.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
@@ -1519,6 +1520,11 @@ export function hasNoBrowserDisqualifyingFlags(options, query) {
         !options.skill &&
         !options.plugin &&
         !options.sort &&
+        // --routine without a name owns a two-stage picker (routine -> run ->
+        // session), and a named routine owns the run-grouped overview. The generic
+        // browser can only flatten routine sessions into its ordinary row list, so
+        // routing this flag there silently bypasses both routine-specific views.
+        !options.routine &&
         !options.artifacts &&
         options.artifact === undefined &&
         // --cloud lists a provider's tasks, not the transcript index, and
@@ -1557,14 +1563,14 @@ export function buildRoutineRunGroups(sessions) {
     }))
         .sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : a.runId.localeCompare(b.runId)));
 }
-export function buildRoutineChoices(sessions) {
+export function buildRoutineChoices(sessions, runOnlyNames = []) {
     const byName = new Map();
     for (const session of sessions) {
         if (!session.routineName)
             continue;
         (byName.get(session.routineName) ?? byName.set(session.routineName, []).get(session.routineName)).push(session);
     }
-    return [...byName.entries()]
+    const choices = [...byName.entries()]
         .map(([name, rows]) => {
         const runs = buildRoutineRunGroups(rows);
         return {
@@ -1573,11 +1579,28 @@ export function buildRoutineChoices(sessions) {
             runCount: runs.length,
             latestRunSessionCount: runs[0].sessions.length,
         };
-    })
-        .sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
+    });
+    // Routines whose only attempts are pre-session (blocked/skipped/failed-before-
+    // spawn) have run records but no transcript. Surface them so the picker is
+    // built from definitions+runs, never only transcripts — otherwise a routine
+    // that has never produced a session reads as "No routines match" (the plan).
+    const seen = new Set(choices.map((c) => c.name));
+    for (const name of runOnlyNames) {
+        if (seen.has(name))
+            continue;
+        const runs = listRuns(name);
+        const latest = runs[runs.length - 1];
+        choices.push({
+            name,
+            lastRunAt: latest?.startedAt ?? '',
+            runCount: runs.length,
+            latestRunSessionCount: 0,
+        });
+    }
+    return choices.sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
 }
 async function selectRoutineName(sessions) {
-    const choices = buildRoutineChoices(sessions);
+    const choices = buildRoutineChoices(sessions, safeListJobsWithRuns());
     const picked = await itemPicker({
         message: 'Select a routine:',
         items: choices,
@@ -1590,7 +1613,8 @@ async function selectRoutineName(sessions) {
         labelFor: (choice) => {
             const runs = `${choice.runCount} run${choice.runCount === 1 ? '' : 's'}`;
             const sessions = `${choice.latestRunSessionCount} session${choice.latestRunSessionCount === 1 ? '' : 's'} in latest`;
-            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions} · ${formatRelativeTime(choice.lastRunAt)}`)}`;
+            const age = choice.lastRunAt ? ` · ${formatRelativeTime(choice.lastRunAt)}` : '';
+            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions}${age}`)}`;
         },
         shortIdFor: (choice) => choice.name,
         emptyMessage: 'No routines match.',
@@ -1598,8 +1622,22 @@ async function selectRoutineName(sessions) {
     });
     return picked?.item.name ?? null;
 }
+/** `listJobsWithRuns` but never throws into the sessions reader (best-effort). */
+function safeListJobsWithRuns() {
+    try {
+        return [...new Set([...listJobs().map((job) => job.name), ...listJobsWithRuns()])];
+    }
+    catch {
+        return [];
+    }
+}
 export async function filterSessionsByRoutine(sessions, routine, interactive) {
-    const routineNames = [...new Set(sessions.map((session) => session.routineName).filter((name) => !!name))].sort((a, b) => a.localeCompare(b));
+    // The name universe is transcripts UNION routines that have any run record —
+    // so a routine whose attempts never produced a session still resolves.
+    const routineNames = [...new Set([
+            ...sessions.map((session) => session.routineName).filter((name) => !!name),
+            ...safeListJobsWithRuns(),
+        ])].sort((a, b) => a.localeCompare(b));
     let selectedRoutine = null;
     if (typeof routine === 'string') {
         selectedRoutine = resolveRoutineName(routine, routineNames);
@@ -1616,9 +1654,10 @@ export async function filterSessionsByRoutine(sessions, routine, interactive) {
         if (!selectedRoutine)
             return null;
     }
-    return selectedRoutine
-        ? sessions.filter((session) => session.routineName === selectedRoutine)
-        : sessions;
+    if (!selectedRoutine)
+        return sessions;
+    const matched = sessions.filter((session) => session.routineName === selectedRoutine);
+    return matched;
 }
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
@@ -2259,6 +2298,11 @@ limitSource) {
     // silently returns nothing for any team older than that — so the flag widens its
     // own scope, the way --all does, unless the caller set an explicit --limit.
     const wantsWholeTeam = !!options.inTeam;
+    // A routine is not tied to the shell's cwd: its archived sessions retain the
+    // working directory in which the scheduled agent actually ran. Scope the
+    // routine catalog across directories so invoking it from ~/.agents/.system,
+    // a project repo, or $HOME yields the same routine history.
+    const wantsWholeRoutine = !!options.routine;
     // `--limit` has a commander default, so an untouched flag still arrives as a
     // string and truthiness can't tell it from a typed one. Commander records where
     // each value came from, which is the only signal that distinguishes an explicit
@@ -2267,7 +2311,7 @@ limitSource) {
     const userSetLimit = limitSource === 'cli' || limitSource === 'env';
     const limit = wantsOverview
         ? OVERVIEW_POOL_LIMIT
-        : parseInt(userSetLimit ? options.limit : wantsWholeTeam ? String(WHOLE_TEAM_POOL_LIMIT) : DEFAULT_LIMIT, 10);
+        : parseInt(userSetLimit ? options.limit : wantsWholeTeam || wantsWholeRoutine ? String(WHOLE_TEAM_POOL_LIMIT) : DEFAULT_LIMIT, 10);
     if (toolEvidenceMode && (!Number.isSafeInteger(limit) || limit < 1 || limit > TOOL_QUERY_MAX_RESULT_SESSIONS)) {
         console.error(chalk.red(`Tool search --limit must be from 1 to ${TOOL_QUERY_MAX_RESULT_SESSIONS}.`));
         process.exitCode = 1;
@@ -2277,7 +2321,7 @@ limitSource) {
     // --since still narrows. Non-overview keeps the prior interactive-30d default.
     const since = wantsOverview
         ? options.since
-        : (options.since ?? (isInteractive && !options.all && !wantsWholeTeam ? '30d' : undefined));
+        : (options.since ?? (isInteractive && !options.all && !wantsWholeTeam && !wantsWholeRoutine ? '30d' : undefined));
     const toolSpansDevices = toolEvidenceMode
         && (options.fleet || (options.host?.length ?? 0) > 0);
     const toolSortError = toolSearchFleetSortError(options.sort, toolSpansDevices);
@@ -2301,12 +2345,12 @@ limitSource) {
             // --in-team spans directories by construction: a team's teammates run in
             // their own worktrees, so scoping to the current cwd hides most of the
             // lineage the flag exists to show.
-            all: pathFilter ? undefined : options.all || wantsWholeTeam || toolSpansDevices,
+            all: pathFilter ? undefined : options.all || wantsWholeTeam || wantsWholeRoutine || toolSpansDevices,
             cwd: process.cwd(),
             // Default overview scopes to the current repo SUBTREE (prefix match), so a
             // monorepo shows its sub-projects grouped instead of collapsing to the one
             // exact-cwd project. `--all` clears the prefix and spans the whole index.
-            cwdPrefix: pathFilter ?? (wantsOverview && !options.all && !wantsWholeTeam && !toolSpansDevices ? process.cwd() : undefined),
+            cwdPrefix: pathFilter ?? (wantsOverview && !options.all && !wantsWholeTeam && !wantsWholeRoutine && !toolSpansDevices ? process.cwd() : undefined),
             project: options.project,
             since,
             until: options.until,
@@ -2339,7 +2383,7 @@ limitSource) {
             const readOptions = {
                 ...scope,
                 limit,
-                excludeTeamOrigin: !options.teams,
+                excludeTeamOrigin: !shouldShowTeamSessions(options),
                 onProgress: tracker.onProgress,
                 includeUnmanaged: options.unmanaged,
                 onHiddenUnmanaged: (n) => { hiddenUnmanaged = n; },
@@ -2356,7 +2400,7 @@ limitSource) {
         // meta.json in ~/.agents/teams/agents whose is_team_origin flag was
         // never set (legacy rows). Keep the in-memory pass so those are still
         // enriched/hidden.
-        const { visible: visibleSessions } = filterTeamSessions(sessions, !!options.teams);
+        const { visible: visibleSessions } = filterTeamSessions(sessions, shouldShowTeamSessions(options));
         sessions = visibleSessions;
         // --in-team spans both ends of the lineage, so it can't be one SQL predicate:
         // the orchestrator matches on the scan-derived `spawnedTeam` column, while a
@@ -2424,7 +2468,7 @@ limitSource) {
         }
         // Under --in-team the visible list is one team, so the whole-index team-origin
         // count would be a non-sequitur next to it.
-        const hiddenCount = options.teams || options.inTeam
+        const hiddenCount = shouldShowTeamSessions(options) || options.inTeam
             ? 0
             : countSessionsInScope({ ...scope, onlyTeamOrigin: true });
         // A typed routine scope must apply before smart ID routing. Otherwise an ID
@@ -4573,9 +4617,9 @@ export function registerSessionsCommands(program) {
       # teammate row [<team>/<handle>]. --in-team narrows to one team's lineage.
       agents sessions --in-team redesign --teams
 
-      # Show routine-run sessions and open one by routine run id
-      agents sessions --routine --all
-      agents sessions --routine nightly-review --all
+      # Pick a routine across every directory, then open one of its run sessions
+      agents sessions --routine
+      agents sessions --routine nightly-review
       agents sessions 2026-07-21T10-30-00-000Z
 
       # Export for analysis
@@ -4623,7 +4667,7 @@ export function registerSessionsCommands(program) {
       - --first and --last are mutually exclusive.
       - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.
       - --cloud sources from Rush Cloud captured runs instead of local disk.
-      - --routine [name] shows transcripts archived from routine runs. On a TTY, omit the name to pick a routine; a name accepts exact, substring, or unambiguous typo matches. --routines is an alias. Routine rows also resolve by run id.
+      - --routine [name] spans every directory and shows transcripts archived from routine runs. On a TTY, omit the name to pick a routine; a name accepts exact, substring, or unambiguous typo matches. --routines is an alias. Routine rows also resolve by run id.
       - Without --teams, team-spawned sessions are hidden by default.
     `,
     });

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerUpdateCommand(program: Command): void;