@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/commands/inspect.js

@@ -32,11 +32,16 @@ import { listHookEntriesFromDir } from '../lib/hooks.js';
 import { getResourceInventory } from '../lib/resource-inventory.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js';
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups, inspectPluginCapabilities, pluginCapabilityLabels } from '../lib/plugins.js';
+import { showResourceList } from './resource-view.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
+import { isInteractiveTerminal } from './utils.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 import { terminalWidth, truncateToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
+import { readJobFileResult, getJobRunsDir, readRunMeta, isOneShotRoutine, isPastOneShotRoutine, listJobs, } from '../lib/routines.js';
+import { routineDeviceIndex, currentRoutineDevice, routineEnabledOnThisDevice, } from '../lib/routine-activation.js';
+import { humanizeCron } from '../lib/routines-format.js';
 /** Resource kinds the inspect command can drill into. */
 const DRILLABLE_KINDS = [
     'commands',
@@ -47,15 +52,19 @@ const DRILLABLE_KINDS = [
     'plugins',
     'workflows',
     'subagents',
+    'routines',
 ];
 /**
  * Summary-view partition. SIMPLE kinds render as a one-line count + name preview;
- * RICH kinds (hooks/plugins/mcp) get their own expanded section showing each
- * item's key detail (events/predicates, bundle contents, transport/url). Together
- * they cover every DrillableKind.
+ * RICH kinds (hooks/plugins/mcp/routines) get their own expanded section showing
+ * each item's key detail (events/predicates, bundle contents, transport/url,
+ * schedule + where a routine actually fires). Together they cover every
+ * DrillableKind — the type below makes that claim load-bearing.
  */
 const SIMPLE_KINDS = ['commands', 'skills', 'rules', 'subagents', 'workflows'];
-const RICH_KINDS = ['hooks', 'plugins', 'mcp'];
+const RICH_KINDS = ['hooks', 'plugins', 'mcp', 'routines'];
+const _kindsPartitioned = true;
+void _kindsPartitioned;
 /**
  * Singular aliases for the plural drill-down flags. `--plugin code` reads as
  * "show the one plugin named code" — a required-value flag that always lands in
@@ -70,6 +79,7 @@ const SINGULAR_DRILL_ALIASES = {
     plugin: 'plugins',
     workflow: 'workflows',
     subagent: 'subagents',
+    routine: 'routines',
 };
 const CAPABILITY_NAMES = [
     'hooks', 'mcp', 'skills', 'commands', 'subagents', 'plugins', 'workflows', 'rules', 'allowlist',
@@ -262,6 +272,13 @@ function isDotAgentsRoot(dir) {
             return true;
     }
     for (const kind of DRILLABLE_KINDS) {
+        // `routines/` alone is NOT a marker. Shipping example routine YAML for
+        // `agents routines add` is a documented pattern (this repo's own
+        // apps/cli/routines/), and that directory is the ONLY kind dir there — so
+        // counting it would make `agents inspect apps/cli` resolve a source tree as
+        // a DotAgents repo. Same reasoning as the nested-`.agents/` case above.
+        if (kind === 'routines')
+            continue;
         if (safeStat(path.join(dir, kind))?.isDirectory())
             return true;
     }
@@ -271,9 +288,29 @@ export async function inspectRepo(repo, options) {
     const drill = pickDrillKind(options);
     const jsonHead = { repo: repo.label, root: repo.root };
     if (drill) {
-        const items = collectRepoKind(repo, drill.kind);
+        // Routines carry live state, and an unreadable device document silently
+        // removes that device from every `devices` cell — say so on this path too,
+        // not only in the overview.
+        let items;
+        if (drill.kind === 'routines') {
+            const provider = defaultRoutineLive();
+            items = collectRepoRoutines(repo, provider.live);
+            if (!options.json) {
+                for (const err of provider.errors) {
+                    console.error(chalk.yellow(`device config unreadable — ${err}`));
+                }
+            }
+        }
+        else {
+            items = collectRepoKind(repo, drill.kind);
+        }
         if (drill.query === true || drill.query === undefined) {
-            renderItemList(repo.label, jsonHead, drill.kind, items, options);
+            // A repo's hooks are wired by its OWN agents.yaml, not by whatever this
+            // machine has installed centrally — the same manifest the repo overview
+            // reads at collectRepoKind.
+            await renderItemList(repo.label, jsonHead, drill.kind, items, options, drill.kind === 'hooks'
+                ? hookManifestByScript(hookManifestFromFile(path.join(repo.root, 'agents.yaml')))
+                : undefined);
         }
         else {
             renderItemDetail(repo.label, jsonHead, drill.kind, String(drill.query), items, options);
@@ -314,8 +351,331 @@ export function collectRepoKind(repo, kind) {
         if (fs.existsSync(subrulesDir))
             return readResourceDir(subrulesDir, kind, repo.label);
     }
+    // Routines are YAML job definitions whose real state (does it fire, where, how
+    // did it last run) lives outside the file. Their directory also holds
+    // `<name>/home/` sandbox overlays, which a flat readdir would count as
+    // routines — on this author's box that turned 24 routines into 49.
+    if (kind === 'routines')
+        return collectRepoRoutines(repo);
     return readResourceDir(path.join(repo.root, kind), kind, repo.label);
 }
+const NO_LIVE_STATE = {
+    devices: [], materialized: false, thisDevice: '', enabledHere: null, lastStatus: null, lastAt: null,
+};
+/**
+ * Whether the routine actually runs on this machine.
+ *
+ * Exactly `applyDeviceActivation` (`lib/routines.ts`): this device's own
+ * allowlist answer wins when it exists, and the file's `enabled:` governs only
+ * while that answer is `null`. Measured at the same scope as the daemon's, so
+ * `agents inspect --routines` and `agents routines list` cannot disagree.
+ */
+function routineEnabledHere(config, live) {
+    return live.enabledHere === null ? config.enabled : live.enabledHere;
+}
+/**
+ * The last run we can read, without paying for the whole history.
+ *
+ * `getLatestRun` goes through `listRuns`, which parses EVERY meta.json under the
+ * routine — one firing every 3 minutes accumulates hundreds. Run ids are ISO-ish
+ * and sort lexicographically, so walking from the newest and stopping at the
+ * first readable record gives the same answer for a bounded number of reads.
+ */
+function latestRunOf(name, maxProbes = 20) {
+    let runIds;
+    try {
+        runIds = fs.readdirSync(getJobRunsDir(name), { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        return null;
+    }
+    for (const runId of runIds.slice(0, maxProbes)) {
+        const meta = readRunMeta(name, runId);
+        if (meta)
+            return meta;
+    }
+    return null;
+}
+/**
+ * Default live provider: one fleet index per collect, one bounded run read per
+ * routine, and this device's own activation answer per routine.
+ *
+ * Returns the collected `errors` alongside so the caller can surface an
+ * unreadable device document instead of letting the affected device silently
+ * vanish from every `devices` cell.
+ */
+function defaultRoutineLive() {
+    let index;
+    try {
+        index = routineDeviceIndex();
+    }
+    catch (err) {
+        return { live: () => NO_LIVE_STATE, errors: [err.message] };
+    }
+    const thisDevice = (() => { try {
+        return currentRoutineDevice();
+    }
+    catch {
+        return '';
+    } })();
+    const errors = [...index.errors];
+    // This device's own doc is read through readMeta, which THROWS on a corrupt
+    // one. Falling back to the file's `enabled:` silently would be the same
+    // silent-failure class the index's error collection just removed, so record it
+    // once — the answer is identical for every routine on this machine.
+    let ownDocError = null;
+    const enabledOnThisDevice = (name) => {
+        try {
+            return routineEnabledOnThisDevice(name);
+        }
+        catch (err) {
+            if (!ownDocError) {
+                ownDocError = `this device's own config is unreadable — ${err.message}`;
+                errors.push(ownDocError);
+            }
+            return null;
+        }
+    };
+    const live = (name) => {
+        const run = latestRunOf(name);
+        return {
+            devices: index.byRoutine.get(name) ?? [],
+            materialized: index.materialized,
+            thisDevice,
+            // The same call applyDeviceActivation makes — per-machine, not fleet-wide.
+            enabledHere: enabledOnThisDevice(name),
+            lastStatus: run?.status ?? null,
+            lastAt: run?.startedAt ?? null,
+        };
+    };
+    return { live, errors };
+}
+/** `2h` / `3d` / `just now` — compact enough for a 10-column cell. */
+export function compactAge(iso, now = new Date()) {
+    if (!iso)
+        return '';
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return '';
+    const mins = Math.floor((now.getTime() - then) / 60000);
+    if (mins < 1)
+        return 'now';
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.floor(hours / 24);
+    if (days < 365)
+        return `${days}d`;
+    return `${Math.floor(days / 365)}y`;
+}
+/** What makes this routine fire: a humanized cron, an event trigger, or nothing. */
+export function routineFireLabel(job, now = new Date()) {
+    const parts = [];
+    if (job.schedule)
+        parts.push(humanizeCron(job.schedule, job.timezone));
+    if (job.trigger) {
+        const t = job.trigger;
+        const event = manifestText(t.event) || manifestText(t.type) || 'event';
+        const qualifier = [manifestText(t.action), manifestText(t.label)].filter(Boolean).join(' ');
+        parts.push(qualifier ? `on ${event} (${qualifier})` : `on ${event}`);
+    }
+    if (parts.length === 0)
+        return 'no schedule or trigger';
+    if (isOneShotRoutine(job)) {
+        parts.push(isPastOneShotRoutine(job, now) ? '(one-shot, expired)' : '(one-shot)');
+    }
+    return parts.join(' · ');
+}
+/** What the routine actually executes. Exactly one of agent/workflow/command is set. */
+export function routineTargetLabel(job) {
+    const agent = manifestText(job.agent);
+    if (agent)
+        return `agent ${agent}`;
+    const workflow = manifestText(job.workflow);
+    if (workflow)
+        return `workflow ${workflow}`;
+    if (manifestText(job.command))
+        return 'command (shell)';
+    return 'nothing configured';
+}
+/**
+ * A routine's one-line intent.
+ *
+ * Routine YAML has no `description:` key, so the generic first-prose-line reader
+ * returns `name: growth-metrics` for one file and a real sentence for the next.
+ * Prefer the prompt's first sentence, then the file's leading comment block, then
+ * the first meaningful line of a shell command.
+ */
+export function routineDescription(job, raw) {
+    const prompt = job ? manifestText(job.prompt).trim() : '';
+    if (prompt)
+        return summaryLine(truncate(prompt.replace(/\s+/g, ' '), 400));
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        const comment = line.match(/^\s*#\s?(.+)$/);
+        if (!comment) {
+            if (line.trim())
+                break;
+            else
+                continue;
+        }
+        const text = comment[1].trim().replace(/^Routine:\s*/i, '');
+        // Skip the shebang-ish and install-instruction noise that opens many files.
+        if (!text || /^(yaml-language-server|Install:|Usage:)/i.test(text))
+            continue;
+        return summaryLine(text);
+    }
+    const command = job ? manifestText(job.command) : '';
+    for (const line of command.split('\n')) {
+        const text = line.trim();
+        if (!text || text.startsWith('#') || /^set\s+-/.test(text))
+            continue;
+        return truncate(text, 120);
+    }
+    return '';
+}
+/**
+ * Read every routine one DotAgents repo declares.
+ *
+ * Reads exactly `<root>/routines/`, never the layered `listJobs` — `collectRepoKind`
+ * is a single-root view, and returning `~/.agents` routines while inspecting a
+ * project repo would be a lie. `live` is injectable because `getUserAgentsDir()`
+ * and `getRunsDir()` have no env override, so tests cannot otherwise keep this
+ * off the developer's real fleet state.
+ */
+export function collectRepoRoutines(repo, live = defaultRoutineLive().live, now = new Date()) {
+    const dir = path.join(repo.root, 'routines');
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    const seen = new Map();
+    // Files only: `routines/<name>/home/` is a sandbox overlay HOME, not a routine.
+    //
+    // `.yml` before `.yaml` for the same basename, because that is the order
+    // `readJobFromDir` tries — so when both exist we describe the file the daemon
+    // actually loads. A plain alphabetical sort put `.yaml` first and reported the
+    // wrong schedule and command for a routine that fires from its sibling.
+    const files = entries
+        .filter(e => e.isFile() && /\.ya?ml$/.test(e.name) && !e.name.startsWith('.'))
+        .map(e => e.name)
+        .sort((a, b) => {
+        const an = a.replace(/\.ya?ml$/, ''), bn = b.replace(/\.ya?ml$/, '');
+        if (an !== bn)
+            return an.localeCompare(bn);
+        return (a.endsWith('.yml') ? 0 : 1) - (b.endsWith('.yml') ? 0 : 1);
+    });
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const { config, problem } = readJobFileResult(filePath);
+        const basename = file.replace(/\.ya?ml$/, '');
+        const name = config?.name || basename;
+        const existing = seen.get(name);
+        if (existing) {
+            // `writeJob` refuses to edit a routine with both extensions. Keep the item
+            // built from the file that loads, and flag the ambiguity on it — in `extra`
+            // for the panes AND in `json` so a --json consumer sees it too.
+            const collision = `both .yml and .yaml exist — ${file} is ignored; resolve before editing`;
+            existing.extra = [...(existing.extra ?? []), ['problem', collision]];
+            if (existing.json)
+                existing.json.problem = collision;
+            continue;
+        }
+        const raw = (() => { try {
+            return fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            return '';
+        } })();
+        const state = config ? live(name) : NO_LIVE_STATE;
+        const extra = [];
+        if (config) {
+            extra.push(['fires', routineFireLabel(config, now)]);
+            extra.push(['runs', routineTargetLabel(config)]);
+            extra.push(['devices', state.devices.length > 0
+                    ? state.devices.join(', ')
+                    : state.materialized ? 'no device — will not fire' : 'no device allowlist yet']);
+            extra.push(['last', state.lastStatus
+                    ? `${state.lastStatus}${state.lastAt ? ` · ${compactAge(state.lastAt, now)} ago` : ''}`
+                    : 'never run']);
+            extra.push(['enabled', routineEnabledHere(config, state)
+                    ? `yes${state.thisDevice ? ` (on ${state.thisDevice})` : ''}`
+                    : `no${state.thisDevice ? ` (on ${state.thisDevice})` : ''}`]);
+            const repoRef = manifestText(config.repo);
+            if (repoRef)
+                extra.push(['repo', repoRef]);
+            const tz = manifestText(config.timezone);
+            if (tz)
+                extra.push(['timezone', tz]);
+            if (config.catchup === false)
+                extra.push(['catchup', 'off — a missed fire is lost']);
+            const host = manifestText(config.host);
+            if (host)
+                extra.push(['host', host]);
+            const pinned = manifestList(config.devices);
+            if (pinned.length > 0)
+                extra.push(['pinned', pinned.join(', ')]);
+            if (name !== basename)
+                extra.push(['file', file]);
+        }
+        else if (problem) {
+            extra.push(['problem', problem]);
+        }
+        const item = {
+            name,
+            source: repo.label,
+            path: filePath,
+            linkTarget: filePath,
+            description: routineDescription(config, raw),
+            extra,
+            // Field names match `agents routines list --json` where they overlap, so
+            // one script can consume both. `devices` is what the YAML pins;
+            // `enabledDevices` is what the fleet actually allows — the diagnostic pair.
+            json: {
+                path: filePath,
+                schedule: config?.schedule ?? null,
+                scheduleHuman: config ? routineFireLabel(config, now) : null,
+                trigger: config?.trigger ?? null,
+                runs: config ? routineTargetLabel(config) : null,
+                agent: config?.agent ?? null,
+                workflow: config?.workflow ?? null,
+                command: config?.command ?? null,
+                timezone: config?.timezone ?? null,
+                repo: config?.repo ?? null,
+                // Effective on THIS machine, matching `agents routines list`.
+                enabled: config ? routineEnabledHere(config, state) : false,
+                // What the file itself declares, before device activation overrides it.
+                enabledInFile: config?.enabled ?? false,
+                catchup: config ? config.catchup !== false : null,
+                devices: config ? manifestList(config.devices) : [],
+                enabledDevices: state.devices,
+                activationMaterialized: state.materialized,
+                oneShot: config ? isOneShotRoutine(config) : false,
+                expired: config ? isPastOneShotRoutine(config, now) : false,
+                lastStatus: state.lastStatus,
+                lastRunAt: state.lastAt,
+                problem,
+            },
+        };
+        seen.set(name, item);
+        items.push(item);
+    }
+    return items.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Read one `extra` row back out — the renderers' only accessor. */
+function extraOf(item, key) {
+    return item.extra?.find(([k]) => k === key)?.[1] ?? '';
+}
 /**
  * Enumerate one directory of resources of `kind`, skipping dotfiles, build caches,
  * and directory docs. Shared so the rules `subrules/` branch and the default
@@ -391,6 +751,19 @@ export function pathSize(p) {
     }
     return { bytes, files };
 }
+/**
+ * Weigh only the entries actually listed, for a kind whose directory holds more
+ * than its resources (routines share theirs with sandbox overlay HOMEs).
+ */
+function itemsSize(items) {
+    let bytes = 0, files = 0;
+    for (const item of items) {
+        const sub = pathSize(item.path);
+        bytes += sub.bytes;
+        files += sub.files;
+    }
+    return { bytes, files };
+}
 /** Human byte size: "84 KB", "3.1 MB". */
 export function formatBytes(n) {
     if (n < 1024)
@@ -442,10 +815,24 @@ function renderRepoSummary(repo, options) {
     let totalBytes = 0, totalFiles = 0;
     let repoHookByScript = new Map();
     let repoMcpConfigs = new Map();
+    let routineActivationErrors = [];
     if (!options.brief) {
         for (const kind of DRILLABLE_KINDS) {
-            const items = collectRepoKind(repo, kind);
-            const size = pathSize(path.join(repo.root, kind));
+            // Routines share one live provider across the collect so the fleet index is
+            // read once, and so its errors survive to be reported below.
+            let items;
+            if (kind === 'routines') {
+                const provider = defaultRoutineLive();
+                routineActivationErrors = provider.errors;
+                items = collectRepoRoutines(repo, provider.live);
+            }
+            else {
+                items = collectRepoKind(repo, kind);
+            }
+            // `routines/` also holds `<name>/home/` sandbox overlays — often far larger
+            // than the definitions and not resources at all, so weigh the files listed
+            // rather than the directory tree.
+            const size = kind === 'routines' ? itemsSize(items) : pathSize(path.join(repo.root, kind));
             kindData[kind] = { items, size };
             totalBytes += size.bytes;
             totalFiles += size.files;
@@ -486,6 +873,12 @@ function renderRepoSummary(repo, options) {
                                 version: i.extra?.find(([k]) => k === 'version')?.[1],
                                 groups: Object.fromEntries((i.groups ?? []).map(g => [g.label, g.items.length])),
                             })) }];
+                if (kind === 'routines')
+                    return [kind, { ...base, items: items.map(i => ({
+                                name: i.name,
+                                description: i.description,
+                                ...(i.json ?? {}),
+                            })) }];
                 return [kind, base];
             })),
         }, null, 2));
@@ -529,18 +922,35 @@ function renderRepoSummary(repo, options) {
         }
     }
     if (!options.brief) {
-        console.log(`  ${'size'.padEnd(10)} ${formatBytes(totalBytes)} ${chalk.gray('·')} ${totalFiles} files`);
+        console.log(`  ${'size'.padEnd(10)} ${formatBytes(totalBytes)} ${chalk.gray('·')} ${totalFiles} ${totalFiles === 1 ? 'file' : 'files'}`);
         console.log('\n' + chalk.bold('Resources'));
         for (const kind of SIMPLE_KINDS) {
             const { items, size } = kindData[kind];
             const count = String(items.length).padStart(4);
             const sz = items.length > 0 ? formatBytes(size.bytes).padStart(8) : ''.padEnd(8);
-            const preview = items.length > 0 ? chalk.gray(truncate(previewNames(items, 4), 60)) : '';
-            console.log(`  ${kind.padEnd(10)} ${count}  ${sz}  ${preview}`.trimEnd());
+            // Width-aware, not a fixed 60: the old cap cut its own "…(+16)" tail off
+            // the rules row identically at 80, 100 and 160 columns.
+            const prefix = `  ${kind.padEnd(10)} ${count}  ${sz}  `;
+            const preview = items.length > 0
+                ? chalk.gray(truncateToWidth(previewNames(items, 4), Math.max(12, terminalWidth() - stringWidth(prefix))))
+                : '';
+            console.log(`${prefix}${preview}`.trimEnd());
         }
         printExpandedSection('Hooks', hookRows(kindData.hooks.items, repoHookByScript));
         printExpandedSection('Plugins', pluginRows(kindData.plugins.items));
         printExpandedSection('MCP', mcpRows(kindData.mcp.items, repoMcpConfigs));
+        printExpandedSection('Routines', routineRows(kindData.routines.items));
+        const dark = routineDarkWarning(kindData.routines.items);
+        if (dark) {
+            console.log('');
+            console.log(`  ${chalk.yellow('⚠')}  ${dark}`);
+            console.log(chalk.gray(`     Fix:  agents routines devices <name> --set <device>`));
+        }
+        // An unreadable device document silently removes that device from every
+        // `devices` cell, which reads as "not enabled there" — say so instead.
+        for (const err of routineActivationErrors) {
+            console.log(chalk.gray(`  device config unreadable — ${err}`));
+        }
     }
     console.log('');
     console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
@@ -685,6 +1095,7 @@ async function renderSummary(agent, version, versionHome, options) {
         printExpandedSection('Hook files', hookRows(itemsByKind.hooks, hookByScript));
         printExpandedSection('Plugins', pluginRows(itemsByKind.plugins));
         printExpandedSection('MCP', mcpRows(itemsByKind.mcp, mcpConfigs));
+        printExpandedSection('Routines', agentRoutineRows(itemsByKind.routines));
     }
     if (sessions) {
         console.log('\n' + chalk.bold('Sessions'));
@@ -698,15 +1109,22 @@ async function renderSummary(agent, version, versionHome, options) {
 // ─── List mode ───────────────────────────────────────────────────────────────
 async function renderList(agent, version, versionHome, kind, options) {
     const items = collectKind(agent, versionHome, kind);
-    renderItemList(`${agent}@${version}`, { agent, version }, kind, items, options);
+    await renderItemList(`${agent}@${version}`, { agent, version }, kind, items, options);
 }
-function renderItemList(header, jsonHead, kind, items, options) {
+async function renderItemList(header, jsonHead, kind, items, options, hookManifest) {
     if (options.json) {
         console.log(JSON.stringify({
             ...jsonHead,
             kind,
             count: items.length,
-            items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description, ...(i.groups ? { groups: i.groups } : {}) })),
+            items: items.map(i => ({
+                name: i.name,
+                source: i.source,
+                path: i.path,
+                description: i.description,
+                ...(i.groups ? { groups: i.groups } : {}),
+                ...(i.json ?? {}),
+            })),
         }, null, 2));
         return;
     }
@@ -716,29 +1134,129 @@ function renderItemList(header, jsonHead, kind, items, options) {
         console.log('');
         return;
     }
-    for (const item of items) {
-        const tag = chalk.gray(`[${item.source}]`.padEnd(10));
-        console.log(`  ${tag} ${termLink(chalk.cyan(item.name), item.linkTarget)}`);
-        if (item.description) {
-            const prefix = '             ';
-            console.log(prefix + chalk.gray(truncateToWidth(item.description, Math.max(1, terminalWidth() - stringWidth(prefix)))));
+    // Route through the shared resource view: an interactive picker with a live
+    // preview in a TTY, a plain aligned table when piped. This is the same
+    // renderer `agents skills list`, `agents commands` and four others already
+    // use — inspect was the last drill-down printing its own two-line-per-entry
+    // dump with a `[source]` tag repeated on every row.
+    //
+    // Sync targets are deliberately off: for a repo the resources ARE the source,
+    // so the column would read "no installed versions" for every row.
+    const sources = new Set(items.map(i => i.source));
+    // A hook has no prose description — it is a script. Leaving the column blank
+    // is honest but useless, so it carries what the Hooks view is actually for:
+    // the events that fire it. Same string the overview prints.
+    const hookEvents = kind !== 'hooks' ? null : (hookManifest ?? hookManifestByScript(loadCentralHookManifest()));
+    // A routine's byte size says nothing; whether it last ran, and where it is
+    // allowed to run, is the whole question. Devices needs the room, so it only
+    // takes a column on a wide terminal — below that it folds into the description
+    // rather than being dropped.
+    const isRoutines = kind === 'routines';
+    const routineDevicesColumn = isRoutines && terminalWidth() >= 100;
+    await showResourceList({
+        resourcePlural: kind,
+        resourceSingular: kind.replace(/s$/, ''),
+        extraLabel: isRoutines ? 'Last' : 'Size',
+        // Only carry a source column when the rows actually differ; a uniform
+        // `[.system]` on every row is 13 columns spent on one bit of information.
+        extra2Label: routineDevicesColumn ? 'Devices' : (isRoutines ? undefined : (sources.size > 1 ? 'Source' : undefined)),
+        showSync: false,
+        // inspect's names run long — hook scripts (`00-agent-verify-work-complete`
+        // and its `_test` sibling) and namespaced plugin entries (`/swarm:orchestrate`)
+        // both blow past the 22-char default and truncate to the same string.
+        //
+        // Gate on terminal width, NOT on "do any rows have a description": that
+        // proxy depended on which path built the items — the repo path hardcodes an
+        // empty description so it widened, while the agent path filled one from the
+        // script's shebang so it never did. Same command, two behaviours.
+        nameCap: terminalWidth() >= 120 ? 40 : undefined,
+        // Keep names clickable — the pre-picker list wrapped every name in an OSC-8
+        // link to its file, and losing that would be a silent capability regression.
+        linkFor: row => items.find(i => i.name === row.name)?.linkTarget,
+        emptyMessage: `  (none installed)`,
+        rows: items.map(item => ({
+            name: item.name,
+            description: (() => {
+                const hook = hookEvents?.get(item.name);
+                if (hook)
+                    return summarizeHook(hook);
+                if (isRoutines) {
+                    const problem = extraOf(item, 'problem');
+                    if (problem)
+                        return problem;
+                    // Compose at the row, leaving item.description pure prose for JSON.
+                    // Also makes "daily" and "zion" searchable in the picker's filter.
+                    return [
+                        extraOf(item, 'fires'),
+                        routineDevicesColumn ? '' : compactDeviceCell(extraOf(item, 'devices')),
+                        summaryLine(item.description),
+                    ].filter(Boolean).join(' · ');
+                }
+                return summaryLine(item.description);
+            })(),
+            extra: isRoutines ? routineLastCell(item) : itemSizeLabel(item.path),
+            extra2: routineDevicesColumn
+                ? compactDeviceCell(extraOf(item, 'devices')) || 'none'
+                : (isRoutines ? undefined : (sources.size > 1 ? item.source : undefined)),
+            targets: [],
+            // Pass the resolved manifest: the picker rebuilds this on every arrow
+            // key, so re-reading ~11 KB of YAML per keystroke is wasted work on top
+            // of being the wrong manifest for a repo target.
+            buildDetail: () => previewFor(kind, item, hookEvents ?? new Map()),
+        })),
+    });
+    // On a TTY the picker's preview pane carries each plugin's bundled skills and
+    // commands. Piped, there is no pane — and the pre-picker output printed those
+    // lines under every row, so a table alone would silently drop what a plugin
+    // actually ships from `agents inspect . --plugins | grep`.
+    if (!isInteractiveTerminal() && items.some(i => i.groups?.length)) {
+        for (const item of items) {
+            if (!item.groups?.length)
+                continue;
+            console.log('\n' + chalk.cyan(item.name));
+            const width = Math.max(...item.groups.map(g => g.label.length));
+            for (const g of item.groups) {
+                const colorFn = PLUGIN_GROUP_COLORS[g.label] ?? chalk.white;
+                // Wrapped, not truncated: routing these through a truncating helper is
+                // what once showed 4 of a 10-command plugin at 80 columns.
+                printWrappedJoined(`  ${chalk.gray(g.label.padEnd(width))}  `, g.items.map(s => colorFn(s)), ', ');
+            }
         }
-        if (item.groups)
-            printGroupRows(item.groups);
+        console.log('');
     }
-    console.log('');
 }
-/** Print a plugin's resource breakdown as aligned `label  items` rows under a list entry. */
-function printGroupRows(groups) {
-    if (groups.length === 0)
-        return;
-    const width = Math.max(...groups.map(g => g.label.length));
-    for (const g of groups) {
-        const colorFn = PLUGIN_GROUP_COLORS[g.label] ?? chalk.white;
-        const label = chalk.gray(g.label.padEnd(width));
-        const value = g.items.map((s) => colorFn(s)).join(chalk.gray(', '));
-        console.log(`             ${label}  ${value}`);
-    }
+/**
+ * The scannable half of a description: everything before the trigger clause, and
+ * only the first sentence of that. 15 of 20 skills in .system lead with their
+ * purpose and then append "Triggers on: …" — in a one-line row that boilerplate
+ * is what survives truncation, so the row says nothing. The full text still
+ * renders in the preview pane.
+ */
+export function summaryLine(description) {
+    if (!description)
+        return '';
+    const cutAtTrigger = description.split(/\s*(?:Triggers on|Use this skill when|Invoke when)\b/i)[0];
+    // A description that OPENS with the trigger clause splits to an empty head.
+    // Returning that would blank the row while --json still carried the text —
+    // showing less than we have is worse than showing boilerplate.
+    const trimmed = cutAtTrigger.trim() || description.trim();
+    // First sentence, but only when the split leaves something substantial —
+    // "e.g." and friends would otherwise chop a description to a fragment.
+    const firstSentence = trimmed.match(/^.*?[.!?](?=\s+[A-Z(`])/)?.[0];
+    const candidate = firstSentence && firstSentence.length >= 40 ? firstSentence : trimmed;
+    return candidate.replace(/\s+/g, ' ').trim();
+}
+/** Compact size for a list row: `18 KB` for a bundle, `413 B` for a single file. */
+function itemSizeLabel(p) {
+    if (!p)
+        return '';
+    const stat = safeStat(p);
+    if (!stat)
+        return '';
+    if (!stat.isDirectory())
+        return formatBytes(stat.size);
+    const { bytes } = pathSize(p);
+    return formatBytes(bytes);
 }
 // ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
 async function renderDetail(agent, version, versionHome, kind, query, options) {
@@ -868,6 +1386,13 @@ function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs, hookInvento
                     groups: Object.fromEntries((i.groups ?? []).map(g => [g.label, g.items.length])),
                 })) };
         }
+        else if (kind === 'routines') {
+            out[kind] = { ...base, items: items.map(i => ({
+                    name: i.name,
+                    source: i.source,
+                    ...Object.fromEntries(i.extra ?? []),
+                })) };
+        }
         else {
             out[kind] = { ...base, names: items.map(i => i.name) };
         }
@@ -900,8 +1425,54 @@ function collectKind(agent, versionHome, kind) {
             }));
         case 'plugins':
             return pluginItems();
+        case 'routines':
+            return agentRoutineItems(agent);
     }
 }
+/**
+ * The routines that dispatch this agent.
+ *
+ * Version-invariant, like the `rules`/`subagents` cases above which also ignore
+ * `versionHome`: a routine names an agent, never an agent@version. `listJobs()`
+ * with no cwd is deliberate — it is the daemon's own view (user + system), so an
+ * unsynced project routine that can never fire is not listed as if it could.
+ */
+function agentRoutineItems(agent) {
+    const { live } = defaultRoutineLive();
+    const now = new Date();
+    let jobs;
+    try {
+        jobs = listJobs();
+    }
+    catch {
+        return [];
+    }
+    return jobs
+        .filter(job => job.agent === agent)
+        .map(job => {
+        const state = live(job.name);
+        return {
+            name: job.name,
+            source: 'user',
+            path: '',
+            linkTarget: '',
+            description: routineDescription(job, ''),
+            extra: [
+                ['fires', routineFireLabel(job, now)],
+                // listJobs already applied device activation, so job.enabled is the
+                // effective answer here — no need to re-derive it.
+                ['enabled', job.enabled ? 'yes' : 'no'],
+                ['devices', state.devices.length > 0
+                        ? state.devices.join(', ')
+                        : state.materialized ? 'no device — will not fire' : 'no device allowlist yet'],
+                ['last', state.lastStatus
+                        ? `${state.lastStatus}${state.lastAt ? ` · ${compactAge(state.lastAt, now)} ago` : ''}`
+                        : 'never run'],
+            ],
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
 function pluginItems() {
     return discoverPlugins().map(p => pluginToItem(p, 'user'));
 }
@@ -985,7 +1556,13 @@ function entriesFromAgentResources(agent, versionHome, kind) {
         source: e.scope,
         path: e.path,
         linkTarget: linkTarget(e.path),
-        description: readDescription(e.path),
+        // A hook is a shell/Python script with no human description, so the prose
+        // fallback returned code: all 53 under an agent home read "!/usr/bin/env
+        // bash" (the `#` strip eating the shebang), and skipping that line only
+        // promoted `set -euo pipefail`. repoHookItems already hardcodes '' for the
+        // repo path; this makes the agent path agree instead of guessing. The
+        // Hooks view shows firing events in that column.
+        description: kind === 'hooks' ? '' : readDescription(e.path),
     }));
 }
 function skillsFromAgentResources(agent, versionHome) {
@@ -1021,6 +1598,96 @@ function buildDetail(item, kind) {
         out[k] = v;
     return out;
 }
+/**
+ * The preview pane for one row, refreshed as the selection moves.
+ *
+ * Adaptive on purpose — the sessions picker sets the precedent: a Cursor
+ * session shows Dirs/Repos/Artifacts, a Codex one shows a different set, and
+ * empty fields simply do not render. A hook's useful metadata (what fires it,
+ * whether it is wired) has nothing in common with a skill's (what invokes it,
+ * where it is synced), so each kind contributes its own rows and blanks drop out.
+ */
+export function previewFor(kind, item, hookManifest) {
+    const out = [];
+    const label = (k, v) => `  ${chalk.gray(k.padEnd(11))}${v}`;
+    out.push(chalk.bold.cyan(item.name) + '  ' + chalk.gray(`${kind.replace(/s$/, '')} · ${item.source}`));
+    if (item.description) {
+        out.push('');
+        for (const line of wrapJoined('  ', item.description.split(/\s+/), ' ', terminalWidth())) {
+            out.push(chalk.white(line));
+        }
+    }
+    const rows = [];
+    // A hook's identity is when it fires — the summary view has always shown this
+    // while the drill-down showed only a size.
+    if (kind === 'hooks') {
+        // Use the manifest the caller already resolved. Re-resolving the CENTRAL
+        // one here made the preview contradict its own row: a repo hook wired by
+        // that repo's agents.yaml showed `PreToolUse(Bash)` in the table and
+        // "not registered" in the pane below it, and the mirror case credited a
+        // central registration to the repo. No `?? loadCentralHookManifest()`
+        // fallback: it would be dead in production and would silently reinstate
+        // exactly that bug the next time a caller forgot the argument.
+        const hook = hookManifest.get(item.name);
+        if (hook) {
+            rows.push(['fires', chalk.yellow(summarizeHook(hook))]);
+            rows.push(['wired', chalk.green('yes') + chalk.gray(' · agents.yaml')]);
+        }
+        else {
+            rows.push(['wired', chalk.gray('no — on disk but not registered')]);
+        }
+    }
+    if (kind === 'skills' || kind === 'commands' || kind === 'subagents') {
+        const fm = readFrontmatter(item.path);
+        if (fm) {
+            const triggers = manifestList(fm.triggers).join(', ');
+            if (triggers)
+                rows.push(['triggers', triggers]);
+            const model = manifestText(fm.model);
+            if (model)
+                rows.push(['model', model]);
+            const tools = manifestList(fm.tools).join(', ');
+            if (tools)
+                rows.push(['tools', tools]);
+        }
+    }
+    if (item.extra)
+        rows.push(...item.extra);
+    const size = itemSizeDetail(item.path);
+    if (size)
+        rows.push(['size', size]);
+    if (item.path)
+        rows.push(['path', chalk.blue(item.path)]);
+    if (rows.length > 0) {
+        out.push('');
+        for (const [k, v] of rows)
+            out.push(label(k, v));
+    }
+    // A plugin's bundled resources, each on its own line rather than a comma run.
+    if (item.groups?.length) {
+        for (const g of item.groups) {
+            out.push('');
+            out.push('  ' + chalk.bold(`${g.label} (${g.items.length})`));
+            for (const entry of g.items.slice(0, 8))
+                out.push('    ' + chalk.green(entry));
+            if (g.items.length > 8)
+                out.push('    ' + chalk.gray(`…${g.items.length - 8} more`));
+        }
+    }
+    return out.join('\n');
+}
+/** `18 KB · 3 files` for a bundle, `413 B` for a single file. */
+function itemSizeDetail(p) {
+    if (!p)
+        return '';
+    const stat = safeStat(p);
+    if (!stat)
+        return '';
+    if (!stat.isDirectory())
+        return formatBytes(stat.size);
+    const { bytes, files } = pathSize(p);
+    return `${formatBytes(bytes)} · ${files} ${files === 1 ? 'file' : 'files'}`;
+}
 function buildDetailRows(item, kind) {
     const rows = [];
     if (item.path && kind !== 'mcp') {
@@ -1030,7 +1697,7 @@ function buildDetailRows(item, kind) {
         if (stat) {
             if (stat.isDirectory()) {
                 const { bytes, files } = pathSize(item.path);
-                rows.push(['size', `${formatBytes(bytes)} · ${files} files`]);
+                rows.push(['size', `${formatBytes(bytes)} · ${files} ${files === 1 ? 'file' : 'files'}`]);
             }
             else {
                 rows.push(['size', formatBytes(stat.size)]);
@@ -1065,9 +1732,13 @@ function buildDetailRows(item, kind) {
         if (item.groups)
             for (const g of item.groups)
                 rows.push([g.label, g.items.join(', ')]);
-        if (item.extra)
-            rows.push(...item.extra);
     }
+    // Every kind's scalar rows. previewFor already renders `extra` unconditionally,
+    // so gating it on plugins here made the detail view and its own preview pane
+    // disagree about the same item — and dropped a routine's schedule/status from
+    // `--routine <name> --json` entirely.
+    if (item.extra)
+        rows.push(...item.extra);
     return rows;
 }
 /** `system` → `sys`; everything else unchanged. Keeps the tag column narrow. */
@@ -1191,7 +1862,16 @@ export function hookManifestByScript(manifest) {
 }
 /** Build hook rows by enriching the installed hook items with manifest events/predicates. */
 function hookRows(items, byScript) {
-    return items.map(item => {
+    // The section shows only the first handful before a `…(+N)` tail, so order
+    // matters: wired hooks first. Alphabetically `00-…_test` sorts next to the
+    // hook it tests, so half the visible rows were test scaffolding with a blank
+    // event column while real registered hooks hid behind the tail.
+    const ordered = [...items].sort((a, b) => {
+        const aw = byScript.has(a.name) ? 0 : 1;
+        const bw = byScript.has(b.name) ? 0 : 1;
+        return aw !== bw ? aw - bw : a.name.localeCompare(b.name);
+    });
+    return ordered.map(item => {
         const hook = byScript.get(item.name);
         return {
             source: item.source,
@@ -1212,6 +1892,152 @@ function pluginRows(items) {
         return { source: item.source, name: item.name, detail, linkTarget: item.linkTarget };
     });
 }
+/** Statuses that mean the last run did not do its job. */
+const UNHEALTHY_RUN = new Set(['failed', 'timeout', 'missed', 'blocked']);
+/**
+ * Health tier for the section ordering. Lower sorts first.
+ *
+ * `printExpandedSection` shows only the first handful before a `…(+N)` tail, so
+ * for a repo with 24 routines the sort IS the section. Same reasoning as
+ * `hookRows` putting wired hooks first: a routine that fires nowhere is exactly
+ * what the reader opened this for, and must never hide behind the tail.
+ */
+export function routineHealthTier(item) {
+    if (extraOf(item, 'problem'))
+        return 0;
+    const fires = extraOf(item, 'fires');
+    if (fires.includes('expired'))
+        return 5;
+    const devices = extraOf(item, 'devices');
+    if (devices.startsWith('no device —'))
+        return 1;
+    if (extraOf(item, 'enabled').startsWith('no'))
+        return 2;
+    const last = extraOf(item, 'last').split(' ')[0];
+    if (UNHEALTHY_RUN.has(last))
+        return 3;
+    return 4;
+}
+/** Build routine rows: `daily at 9:00 AM   zion   completed · 2h ago`. Broken first. */
+function routineRows(items) {
+    const ordered = [...items].sort((a, b) => {
+        const at = routineHealthTier(a), bt = routineHealthTier(b);
+        return at !== bt ? at - bt : a.name.localeCompare(b.name);
+    });
+    const nameW = ordered.length > 0 ? Math.max(...ordered.slice(0, 6).map(r => r.name.length)) : 0;
+    // Budget the three cells against what printExpandedSection leaves after the
+    // `[source]` tag and the name column, so the status never truncates to `fai…`.
+    const budget = Math.max(30, terminalWidth() - nameW - 14);
+    const firesW = Math.min(21, Math.max(12, Math.floor(budget * 0.42)));
+    const devicesW = Math.min(14, Math.max(7, Math.floor(budget * 0.22)));
+    return ordered.map(item => {
+        const problem = extraOf(item, 'problem');
+        const fires = extraOf(item, 'fires');
+        // A routine with no `fires` never parsed — the problem IS the whole row. One
+        // that parsed but carries a problem (a duplicate-extension sibling) keeps its
+        // schedule and status, with the problem appended rather than replacing them.
+        if (problem && !fires) {
+            return { source: item.source, name: item.name, linkTarget: item.linkTarget, detail: chalk.red(problem) };
+        }
+        const devices = compactDeviceCell(extraOf(item, 'devices'));
+        const last = extraOf(item, 'last');
+        // Pad the PLAIN strings, then colour. Padding a chalk-wrapped string counts
+        // the escape codes as width and silently steals columns from the next cell.
+        // The trailing problem gets what the three sized cells leave, or it would
+        // blow the row past the terminal and break the alignment this budget exists
+        // to hold — a 147-column row at COLUMNS=100 in testing.
+        const problemW = Math.max(12, budget - firesW - devicesW - stringWidth(last) - 8);
+        const detail = [
+            chalk.gray(truncateToWidth(fires, firesW).padEnd(firesW)),
+            (devices === 'none ⚠' ? chalk.yellow : chalk.gray)(truncateToWidth(devices, devicesW).padEnd(devicesW)),
+            colorLast(last),
+            problem ? chalk.red(truncateToWidth(`  ⚠ ${problem}`, problemW)) : '',
+        ].join('  ').trimEnd();
+        return {
+            source: item.source,
+            name: item.name,
+            linkTarget: item.linkTarget,
+            detail,
+        };
+    });
+}
+/**
+ * Routine rows for an agent target: `daily at 9:00 AM   completed · 2h ago`.
+ * No devices column — an agent view is inherently about this machine.
+ */
+function agentRoutineRows(items) {
+    const ordered = [...items].sort((a, b) => {
+        const at = routineHealthTier(a), bt = routineHealthTier(b);
+        return at !== bt ? at - bt : a.name.localeCompare(b.name);
+    });
+    return ordered.map(item => ({
+        source: item.source,
+        name: item.name,
+        detail: `${extraOf(item, 'fires').padEnd(20)}  ${colorLast(extraOf(item, 'last'))}`,
+    }));
+}
+/**
+ * `ok 2h` / `fail 3d` / `never` — the Last column, clamped to the 10-wide cell.
+ *
+ * The picker path pads without truncating, so an 11-char `blocked 3d` would push
+ * the next column; the abbreviations cover only the two commonest statuses, so
+ * the clamp is what actually holds the invariant.
+ */
+function routineLastCell(item, width = 10) {
+    const last = extraOf(item, 'last');
+    if (!last || last === 'never run')
+        return 'never';
+    const [status, , age] = last.split(' ');
+    const word = status === 'completed' ? 'ok' : status === 'failed' ? 'fail' : status;
+    return truncateToWidth(age ? `${word} ${age}` : word, width);
+}
+/**
+ * Trim the long-form `devices` phrasing down to a cell.
+ *
+ * The extra row is written for the detail pane ("no device — will not fire");
+ * a 16-column cell needs the same fact in two words.
+ */
+function compactDeviceCell(devices) {
+    if (devices.startsWith('no device —'))
+        return 'none ⚠';
+    if (devices.startsWith('no device allowlist yet'))
+        return 'unset';
+    const list = devices.split(', ').filter(Boolean);
+    return list.length > 1 ? `${list[0]} +${list.length - 1}` : (list[0] ?? '');
+}
+function colorLast(last) {
+    if (!last || last === 'never run')
+        return chalk.gray('never run');
+    const word = last.split(' ')[0];
+    if (word === 'completed')
+        return chalk.green(last);
+    if (UNHEALTHY_RUN.has(word))
+        return chalk.red(last);
+    return chalk.gray(last);
+}
+/**
+ * The one-line warning under the Routines section, or null when it would mislead.
+ *
+ * Silent until some device has materialized a `routines:` list — before that,
+ * every routine is legitimately unpinned and "will not fire" would be noise.
+ */
+export function routineDarkWarning(items) {
+    const materialized = items.some(i => {
+        const d = extraOf(i, 'devices');
+        return d !== '' && !d.startsWith('no device allowlist yet');
+    });
+    if (!materialized)
+        return null;
+    const dark = items.filter(i => extraOf(i, 'devices').startsWith('no device —')).length;
+    if (dark === 0)
+        return null;
+    // The noun pluralizes on the total ("1 of 2 routines"), the verb on the count
+    // that is actually dark ("... is on no device's allowlist").
+    const noun = items.length === 1 ? 'routine' : 'routines';
+    const verb = dark === 1 ? 'is' : 'are';
+    const pronoun = dark === 1 ? 'it' : 'they';
+    return `${dark} of ${items.length} ${noun} ${verb} on no device's allowlist — ${pronoun} will not fire.`;
+}
 /** Build MCP rows by joining the installed mcp items with their full configs (transport/url/command). */
 function mcpRows(items, configs) {
     return items.map(item => {
@@ -1220,7 +2046,7 @@ function mcpRows(items, configs) {
     });
 }
 /** Read a repo/agents.yaml `hooks:` section into a name→ManifestHook map (best-effort). */
-function hookManifestFromFile(agentsYamlPath) {
+export function hookManifestFromFile(agentsYamlPath) {
     try {
         const meta = yaml.parse(fs.readFileSync(agentsYamlPath, 'utf-8'));
         return meta?.hooks ?? {};