@phnx-labs/agents-cli 1.22.33 → 1.22.34

package/dist/commands/inspect.js

@@ -27,11 +27,11 @@ import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/inde
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
-import { getAgentResources, listResources, } from '../lib/resources.js';
+import { getAgentResources, isDirectoryDoc, listResources, } from '../lib/resources.js';
 import { listHookEntriesFromDir } from '../lib/hooks.js';
 import { getResourceInventory } from '../lib/resource-inventory.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js';
-import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
+import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups, inspectPluginCapabilities, pluginCapabilityLabels } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
@@ -292,7 +292,36 @@ export function collectRepoKind(repo, kind) {
             .map(p => pluginToItem(p, repo.label))
             .sort((a, b) => a.name.localeCompare(b.name));
     }
-    const dir = path.join(repo.root, kind);
+    // Hooks live nested under event directories (`hooks/pre-tool-use/…`), and a
+    // script pairs with its data sidecar. repoHookItems already reads them that
+    // way for the summary view; a flat readdir here returned the event dirs
+    // themselves plus README/test scaffolding, so `--hooks` and the summary
+    // reported different counts for the same repo.
+    if (kind === 'hooks')
+        return repoHookItems(repo);
+    // A repo's `rules/` holds the COMPOSED output (AGENTS.md plus its CLAUDE.md /
+    // GEMINI.md symlinks) alongside a `subrules/` dir of the individually named
+    // fragments. The fragments are what `--rule <name>` resolves and what a reader
+    // means by "a rule"; the composed file is a build artifact. Without this,
+    // `subrules` listed as a single opaque leaf and every real rule was unreachable.
+    // Deliberately exclusive: once `subrules/` exists it is the sole home for
+    // rules (composeRules only ever resolves names under it — lib/rules/compose.ts),
+    // so loose top-level `.md` files are not listed. A repo mid-migration to the
+    // subrules convention would see those legacy files disappear from `--rules`;
+    // that is the correct signal, since composeRules would not load them either.
+    if (kind === 'rules') {
+        const subrulesDir = path.join(repo.root, kind, 'subrules');
+        if (fs.existsSync(subrulesDir))
+            return readResourceDir(subrulesDir, kind, repo.label);
+    }
+    return readResourceDir(path.join(repo.root, kind), kind, repo.label);
+}
+/**
+ * Enumerate one directory of resources of `kind`, skipping dotfiles, build caches,
+ * and directory docs. Shared so the rules `subrules/` branch and the default
+ * `<repo>/<kind>/` branch cannot drift apart.
+ */
+function readResourceDir(dir, kind, source) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -307,10 +336,16 @@ export function collectRepoKind(repo, kind) {
         // Build/tooling caches are never resources — they only inflate counts.
         if (entry.name === '__pycache__' || entry.name === 'node_modules')
             continue;
+        const name = entry.name.replace(/\.(md|yaml|yml|toml|json)$/, '');
+        // README/AGENTS/CLAUDE/GEMINI describe the directory, not resources of this
+        // kind. CLAUDE.md/GEMINI.md are symlinks to AGENTS.md, so a Dirent reports
+        // isFile() === false — use !isDirectory() to catch them (mirrors resources.ts).
+        if (!entry.isDirectory() && isDirectoryDoc(kind, name))
+            continue;
         const p = path.join(dir, entry.name);
         items.push({
-            name: entry.name.replace(/\.(md|yaml|yml|toml|json)$/, ''),
-            source: repo.label,
+            name,
+            source,
             path: p,
             linkTarget: linkTarget(p),
             description: readDescription(p),
@@ -406,7 +441,6 @@ function renderRepoSummary(repo, options) {
     const kindData = {};
     let totalBytes = 0, totalFiles = 0;
     let repoHookByScript = new Map();
-    let repoHookItemList = [];
     let repoMcpConfigs = new Map();
     if (!options.brief) {
         for (const kind of DRILLABLE_KINDS) {
@@ -417,7 +451,6 @@ function renderRepoSummary(repo, options) {
             totalFiles += size.files;
         }
         repoHookByScript = hookManifestByScript(hookManifestFromFile(path.join(repo.root, 'agents.yaml')));
-        repoHookItemList = repoHookItems(repo);
         repoMcpConfigs = new Map(discoverMcpConfigsFromRepo(repo.root).map(s => [s.name, s.config]));
     }
     if (options.json) {
@@ -430,8 +463,7 @@ function renderRepoSummary(repo, options) {
             size: options.brief ? null : { bytes: totalBytes, files: totalFiles },
             resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => {
                 const size = kindData[kind].size;
-                // Hooks use the grouped reader (clean names) instead of the raw readdir.
-                const items = kind === 'hooks' ? repoHookItemList : kindData[kind].items;
+                const items = kindData[kind].items;
                 const base = {
                     count: items.length,
                     bytes: size.bytes,
@@ -506,7 +538,7 @@ function renderRepoSummary(repo, options) {
             const preview = items.length > 0 ? chalk.gray(truncate(previewNames(items, 4), 60)) : '';
             console.log(`  ${kind.padEnd(10)} ${count}  ${sz}  ${preview}`.trimEnd());
         }
-        printExpandedSection('Hooks', hookRows(repoHookItemList, repoHookByScript));
+        printExpandedSection('Hooks', hookRows(kindData.hooks.items, repoHookByScript));
         printExpandedSection('Plugins', pluginRows(kindData.plugins.items));
         printExpandedSection('MCP', mcpRows(kindData.mcp.items, repoMcpConfigs));
     }
@@ -745,10 +777,23 @@ function renderItemDetail(header, jsonHead, kind, query, items, options) {
     const matchTag = best.matchKind === 'exact' ? 'exact' : best.matchKind === 'substring' ? 'substring' : `~${best.distance}`;
     console.log(`  ${chalk.green('✓')}  ${termLink(chalk.bold.cyan(best.item.name), best.item.linkTarget)}  ${chalk.gray(`[${matchTag}, ${best.item.source}]`)}`);
     if (best.item.description) {
-        console.log(`     ${chalk.gray(truncate(best.item.description, 100))}`);
+        // Wrap to the real terminal width. This used to be truncate(desc, 100): a
+        // character count blind to the window, so a long description lost its
+        // sentence at 80 columns AND wasted the space at 200.
+        for (const line of wrapJoined('     ', best.item.description.split(/\s+/), ' ', terminalWidth())) {
+            console.log(chalk.gray(line));
+        }
     }
     for (const [k, v] of buildDetailRows(best.item, kind)) {
-        console.log(`     ${chalk.gray(k.padEnd(10))} ${v}`);
+        // Wrap, never truncate. These values are `, `-joined lists (commands,
+        // skills, triggers, tools) and cutting them hides real entries — a 9-command
+        // plugin would show 4. Before the detail view wrapped at all, the terminal
+        // soft-wrapped these in full, so truncating here would lose information the
+        // old output had.
+        // String(v) is belt-and-braces: pluginToItem now coerces every manifest field
+        // through manifestText, so nothing non-string should reach here. Kept because
+        // this is the choke point every future row kind flows through.
+        printWrappedJoined(`     ${chalk.gray(k.padEnd(10))} `, String(v).split(', '), ', ');
     }
     if (others.length > 0) {
         console.log('\n' + chalk.gray('Other matches:'));
@@ -863,21 +908,75 @@ function pluginItems() {
 /**
  * Map a discovered plugin to a resource item, surfacing the manifest description
  * and the bundle's nested resources (skills, commands, hooks, ...) as detail rows.
+ *
+ * EVERY field read here comes from an uncontrolled `plugin.json`:
+ * `loadPluginManifest` casts parsed JSON straight to `PluginManifest` and
+ * validates only name/version (`lib/plugins.ts`), so the declared types are a
+ * hope, not a guarantee. A non-string reaching a renderer throws on `.split` /
+ * `.replace`, and `pluginToItem` runs while BUILDING THE LIST — so one malformed
+ * manifest anywhere takes down `inspect .`, `--plugins`, `--json`, and even a
+ * query for a different, valid plugin. Coerce every field through `manifestText`;
+ * never trust the annotation.
  */
 function pluginToItem(plugin, source) {
     const extra = [];
-    if (plugin.manifest.version)
-        extra.push(['version', plugin.manifest.version]);
+    const version = manifestText(plugin.manifest.version);
+    if (version)
+        extra.push(['version', version]);
+    // Which execution surfaces the bundle actually carries. Detection already
+    // exists for the plugin picker; the detail view simply never asked for it.
+    const surfaces = pluginCapabilityLabels(inspectPluginCapabilities(plugin.root));
+    if (surfaces.length > 0)
+        extra.push(['surfaces', surfaces.join(', ')]);
+    const author = plugin.manifest.author;
+    const authorLabel = manifestText(typeof author === 'object' && author !== null ? author.name : author);
+    if (authorLabel)
+        extra.push(['author', authorLabel]);
+    // `.length` is truthy for a bare string too, and a string has no `.join`.
+    const deps = plugin.manifest.dependencies;
+    const depsLabel = Array.isArray(deps)
+        ? deps.map(manifestText).filter(Boolean).join(', ')
+        : manifestText(deps);
+    if (depsLabel)
+        extra.push(['depends on', depsLabel]);
     return {
         name: plugin.name,
         source,
         path: plugin.root,
         linkTarget: linkTarget(plugin.root),
-        description: plugin.manifest.description ?? '',
+        // `?? ''` catches only null/undefined — a numeric or array description used
+        // to reach truncateToWidth/`.split` and kill the render for every plugin.
+        description: manifestText(plugin.manifest.description),
         extra,
         groups: pluginResourceGroups(plugin),
     };
 }
+/**
+ * Render one uncontrolled manifest value as display text. Objects and arrays
+ * carry no sensible one-line form, so they become '' (the row is then dropped)
+ * rather than `[object Object]`; everything else stringifies.
+ */
+function manifestText(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'object')
+        return '';
+    return String(v);
+}
+/**
+ * Render one uncontrolled value as a list of display strings. A scalar becomes a
+ * one-element list — the case `?? []` and `Array.isArray` both miss, and the one
+ * that threw on `.join`. Object entries drop out rather than becoming
+ * `[object Object]`.
+ */
+function manifestList(v) {
+    if (v === null || v === undefined)
+        return [];
+    if (Array.isArray(v))
+        return v.map(manifestText).filter(Boolean);
+    const single = manifestText(v);
+    return single ? [single] : [];
+}
 function entriesFromAgentResources(agent, versionHome, kind) {
     const res = getAgentResources(agent, { home: versionHome });
     const list = res[kind];
@@ -926,8 +1025,17 @@ function buildDetailRows(item, kind) {
     const rows = [];
     if (item.path && kind !== 'mcp') {
         const stat = safeStat(item.path);
-        if (stat)
-            rows.push(['size', stat.isDirectory() ? '(bundle)' : `${stat.size} bytes`]);
+        // A bundle reports its real recursive weight. `(bundle)` carried no
+        // information, and pathSize/formatBytes already back the summary view.
+        if (stat) {
+            if (stat.isDirectory()) {
+                const { bytes, files } = pathSize(item.path);
+                rows.push(['size', `${formatBytes(bytes)} · ${files} files`]);
+            }
+            else {
+                rows.push(['size', formatBytes(stat.size)]);
+            }
+        }
     }
     // Kind-specific fields
     if (kind === 'skills' || kind === 'commands' || kind === 'subagents') {
@@ -937,12 +1045,18 @@ function buildDetailRows(item, kind) {
             if (typeof fm.description === 'string' && fm.description.trim() !== item.description.trim()) {
                 rows.push(['description', truncate(fm.description, 120)]);
             }
-            if (Array.isArray(fm.triggers))
-                rows.push(['triggers', fm.triggers.join(', ')]);
-            if (typeof fm.model === 'string')
-                rows.push(['model', fm.model]);
-            if (Array.isArray(fm.tools))
-                rows.push(['tools', fm.tools.join(', ')]);
+            // Frontmatter is uncontrolled YAML too. These were type-guarded against a
+            // crash but still rendered `[object Object]` for an entry that is a map,
+            // and dropped a scalar `triggers: foo` entirely.
+            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]);
         }
     }
     // Plugin bundles surface their nested resources (skills, commands, …) plus
@@ -966,11 +1080,14 @@ function abbrevSource(s) {
  * an optional cache tail. Plain text — the caller applies color.
  */
 export function summarizeHook(hook) {
-    const events = (hook.events ?? []).join('/') || '(no event)';
-    let matcher = hook.matcher;
+    // `hook` is an unvalidated YAML cast from agents.yaml, so `??` is not enough:
+    // a scalar `events: PreToolUse` is neither null nor an array, and `.join` threw
+    // — taking down bare `agents inspect <repo>`, and via the central manifest
+    // `agents inspect <agent>` on every box. Same shape as the plugin.json bug.
+    const events = manifestList(hook.events).join('/') || '(no event)';
+    let matcher = manifestText(hook.matcher);
     if (!matcher && hook.matches?.tool_name) {
-        const tn = hook.matches.tool_name;
-        matcher = Array.isArray(tn) ? tn.join('|') : tn;
+        matcher = manifestList(hook.matches.tool_name).join('|');
     }
     const head = matcher ? `${events}(${matcher})` : events;
     const parts = [head];
@@ -987,21 +1104,26 @@ export function summarizeHook(hook) {
 function summarizeMatches(m) {
     if (!m)
         return '';
+    // Every predicate is raw YAML. `truncate` calls `.slice`, so a numeric
+    // `prompt_contains: 12345` threw here just like the events case above.
     const bits = [];
     if (m.git_dirty)
         bits.push('git_dirty');
-    if (m.prompt_contains)
-        bits.push(`prompt~"${truncate(m.prompt_contains, 24)}"`);
-    if (m.prompt_matches)
-        bits.push(`prompt=/${truncate(m.prompt_matches, 24)}/`);
-    if (m.tool_args_match)
-        bits.push(`args=/${truncate(m.tool_args_match, 20)}/`);
-    if (m.cwd_includes) {
-        const c = Array.isArray(m.cwd_includes) ? m.cwd_includes.join('|') : m.cwd_includes;
-        bits.push(`cwd~${truncate(c, 24)}`);
-    }
-    if (m.project_has)
-        bits.push(`has ${m.project_has}`);
+    const promptContains = manifestText(m.prompt_contains);
+    if (promptContains)
+        bits.push(`prompt~"${truncate(promptContains, 24)}"`);
+    const promptMatches = manifestText(m.prompt_matches);
+    if (promptMatches)
+        bits.push(`prompt=/${truncate(promptMatches, 24)}/`);
+    const argsMatch = manifestText(m.tool_args_match);
+    if (argsMatch)
+        bits.push(`args=/${truncate(argsMatch, 20)}/`);
+    const cwd = manifestList(m.cwd_includes).join('|');
+    if (cwd)
+        bits.push(`cwd~${truncate(cwd, 24)}`);
+    const projectHas = manifestText(m.project_has);
+    if (projectHas)
+        bits.push(`has ${projectHas}`);
     return bits.join(' · ');
 }
 /** Normalize a hook cache shorthand/object to a display ttl ("5m", "1h"); null when uncached. */
@@ -1010,7 +1132,10 @@ function hookCacheTtl(cache) {
         return null;
     if (typeof cache === 'string')
         return cache.replace(/-bg$/, '');
-    return String(cache.ttl);
+    // A bare `cache: 5` has no `.ttl`, and `cache: {ttl: {…}}` has a non-scalar
+    // one — String() on either rendered `(undefined cache)` / `([object Object]
+    // cache)`. No ttl to show means no cache tail.
+    return manifestText(cache.ttl) || null;
 }
 /** Compact one-liner for an MCP server: padded transport + the url (http) or command line (stdio). */
 export function summarizeMcp(cfg) {
@@ -1121,6 +1246,11 @@ function loadCentralHookManifest() {
  * data file collapsed into one entry, non-hook files like promptcuts.yaml or
  * README.md filtered out) rather than a naive readdir, so names are clean and
  * join cleanly against the manifest by script basename.
+ *
+ * `description` is intentionally blank: a hook is a script, and the only text a
+ * readdir-based reader could scrape from one is its shebang (the old flat path
+ * surfaced `!/usr/bin/env bash` as a description). The Hooks section shows firing
+ * events via summarizeHook instead, which is the useful signal.
  */
 function repoHookItems(repo) {
     return listHookEntriesFromDir(path.join(repo.root, 'hooks')).map(h => ({
@@ -1177,7 +1307,10 @@ function readDescription(p) {
     let filePath = p;
     try {
         if (fs.statSync(p).isDirectory()) {
-            for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md', 'README.md']) {
+            // `rule.md` is the directory form of a subrule (SUBRULE_RULE_FILE in
+            // lib/rules/compose.ts); without it the four dir-form subrules on disk
+            // drill in with a blank preview.
+            for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md', 'rule.md', 'README.md']) {
                 const c = path.join(p, marker);
                 if (fs.existsSync(c)) {
                     filePath = c;

package/dist/commands/message.d.ts

@@ -9,7 +9,12 @@
  *
  * Cross-host is handled one layer up: `--host <h>` routes the whole command over
  * ssh via `REMOTE_PASSTHROUGH` (see src/lib/hosts/passthrough.ts), so the box is
- * written on the host that actually owns the agent.
+ * written on the host that actually owns the agent. A caller who doesn't already
+ * know the host (a detached `agents run --device <h> --no-follow` dispatch) is
+ * still resolved automatically: a `target` matching no local/cloud session falls
+ * through to the `~/.agents/.cache/hosts/` records `agents hosts ps` reads
+ * (RUSH-2366 follow-up — see decideHostTaskRoute in lib/mailbox-target.ts), and
+ * the message is rerouted there.
  *
  * For local agents, the message is tied to the agent's current open feed block
  * (if any). The first answer to a block wins: a second concurrent answer is

package/dist/commands/message.js

@@ -7,7 +7,9 @@ import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { getAgentsInvocation } from '../lib/daemon.js';
-import { resolveMessageTarget, mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { resolveTaskRef } from '../lib/hosts/tasks.js';
+import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
+import { resolveMessageTarget, mailboxIdForActiveSession, decideHostTaskRoute, } from '../lib/mailbox-target.js';
 import { blockIdForSession, listBlocks, readBlock, recordAnswer, recordMessageReceipt, } from '../lib/feed.js';
 import { verifyOperatorIdentity } from '../lib/operator.js';
 import { resolveAnswerRoute, resumeArgv, } from '../lib/answer-router.js';
@@ -112,6 +114,40 @@ async function deliverViaResume(route, mailboxId) {
     console.log(chalk.green(`Resumed ${mailboxId} with answer. `) +
         chalk.dim(route.reason));
 }
+/**
+ * Reroute a message to a detached `agents run --device <host> --no-follow`
+ * dispatch (RUSH-2366 follow-up). `getActiveSessions()` never sees these: the
+ * live process is on the dispatch's host, not this machine, so the local
+ * session resolver in `resolveMessageTarget` reports "no running agent" even
+ * while `agents hosts ps` shows the same dispatch running with a live remote
+ * pid — the only recovery was kill-and-redispatch, losing all context.
+ *
+ * Re-spawns `agents message <remoteRef> <text> --host <host>` through
+ * `getAgentsInvocation`, so it re-enters via the SAME `--host` REMOTE_PASSTHROUGH
+ * choke point (`lib/hosts/passthrough.ts`) any explicit `--host` caller uses,
+ * and resolves against the remote box's own active sessions.
+ */
+async function deliverViaHostReroute(route, text, opts) {
+    const argv = ['message', route.remoteRef, text, '--host', route.host];
+    if (opts.from)
+        argv.push('--from', opts.from);
+    if (opts.as)
+        argv.push('--as', opts.as);
+    if (opts.surface)
+        argv.push('--surface', opts.surface);
+    if (opts.ttl)
+        argv.push('--ttl', opts.ttl);
+    const inv = getAgentsInvocation(argv);
+    const child = spawn(inv.command, inv.args, { stdio: 'inherit', env: process.env });
+    const code = await new Promise((resolve) => {
+        child.on('exit', (c) => resolve(c ?? 1));
+        child.on('error', () => resolve(1));
+    });
+    if (code !== 0) {
+        die(`Delivery to '${route.remoteRef}' on host '${route.host}' exited with code ${code}. ` +
+            `Tried: agents ${argv.join(' ')}`);
+    }
+}
 /**
  * `message` is the agent-control plane (RUSH-2123): the answer/keystroke/
  * injected input a running agent consumes, never a notification a human reads.
@@ -214,8 +250,29 @@ export function registerMessageCommand(program) {
                 die(`"${target}" matches ${res.candidates.length} running agents:\n${lines}\nRe-run with a full id.`);
                 return;
             }
-            case 'none':
-                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\`.`);
+            case 'none': {
+                // Not a local/cloud session — check whether it's a detached
+                // `--device ... --no-follow` dispatch, which `getActiveSessions()`
+                // never sees (its live process is on another host). Same records
+                // `agents hosts ps` reads, so the two commands never disagree.
+                // Heal first, exactly as `hosts stop`/`hosts ps` do: a detached
+                // dispatch record never self-updates, so a finished run is still
+                // stamped `status:'running'` on disk. Without this we'd route a dead
+                // task through an SSH reroute that can only fail, instead of
+                // reporting it finished here.
+                const onDisk = resolveTaskRef(target);
+                const hostRoute = decideHostTaskRoute(onDisk ? reconcileRunningTasks([onDisk])[0] : null, target);
+                if (hostRoute.kind === 'reroute') {
+                    await deliverViaHostReroute(hostRoute, text, opts);
+                    return;
+                }
+                if (hostRoute.kind === 'finished') {
+                    die(`Task '${target}' on host '${hostRoute.host}' already ${hostRoute.status}` +
+                        (hostRoute.exitCode !== undefined ? ` (exit ${hostRoute.exitCode})` : '') +
+                        `. Nothing to message. View its output: \`agents hosts logs ${target}\`.`);
+                }
+                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\` or \`agents hosts ps\`.`);
+            }
         }
     });
 }

package/dist/commands/sessions.d.ts

@@ -3,6 +3,7 @@ import { type ProjectDef } from '../lib/projects.js';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
+import { type RunMeta } from '../lib/routines.js';
 import { type PickedSession } from './sessions-picker.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
@@ -435,7 +436,60 @@ export interface RoutineChoice {
 }
 export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
 export declare function buildRoutineChoices(sessions: SessionMeta[], runOnlyNames?: string[]): RoutineChoice[];
+/**
+ * Resolve which routine the user is targeting for `--routine`. Returns `null` to
+ * ABORT the command (a bad `--routine <name>` printed an error, or the user
+ * cancelled the interactive pick). `{ name: null }` means "no routine was
+ * selected, don't filter" — the degenerate bare `--routine` piped to a
+ * non-interactive sink. `{ name }` is a chosen routine.
+ *
+ * The name universe is transcripts UNION every routine with a definition or a
+ * run record (`safeListJobsWithRuns`), so a command-only or never-ran routine —
+ * which produces no `SessionMeta` — still resolves and drills down.
+ */
+export declare function selectRoutineTarget(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<{
+    name: string | null;
+} | null>;
 export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
+/** How a run executed — decides whether an agent session is even expected. */
+export type RoutineExecutionKind = 'agent' | 'command' | 'workflow';
+export declare function executionKind(meta: RunMeta): RoutineExecutionKind;
+/** One canonical run record plus the indexed sessions linked to it by run id. */
+export interface RoutineRunEntry {
+    meta: RunMeta;
+    sessions: SessionMeta[];
+}
+export interface RoutineDrilldown {
+    name: string;
+    /** Canonical run records (newest first), each with its linked sessions. */
+    runs: RoutineRunEntry[];
+    /** Sessions whose `routineRunId` matches no local run record — e.g. archived
+     *  on another host whose run dir this box has not synced. Grouped by run id so
+     *  they are still shown, honestly separated from the canonical run history. */
+    orphanSessions: RoutineRunGroup[];
+    /** Count of canonical run records (any status, incl. missed/blocked/skipped). */
+    runRecordCount: number;
+    /** Count of linked indexed sessions across all runs (+ orphans). */
+    linkedSessionCount: number;
+    /** True when any run ran an agent or any session is linked — i.e. an agent
+     *  routine. False for a pure command routine, where no session is expected. */
+    isAgentRoutine: boolean;
+}
+/**
+ * Reconcile a routine's canonical run records (`listRuns`, local disk) with the
+ * indexed sessions for that routine (fleet-wide, keyed by `routineRunId`).
+ */
+export declare function buildRoutineDrilldown(name: string, sessions: SessionMeta[]): RoutineDrilldown;
+/**
+ * Render the routine drilldown: canonical run history first, each run linked to
+ * its indexed agent session(s). This is the run/session seam made visible — a
+ * command routine shows its runs and states plainly that no session is expected;
+ * an agent routine shows the same runs plus each run's session metadata.
+ */
+export declare function printRoutineDrilldown(drill: RoutineDrilldown, liveIndex?: Map<string, ActiveSession>, opts?: {
+    hiddenCount?: number;
+    hiddenUnmanaged?: number;
+}): void;
 /** 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. */
 export declare function renderSessionPreview(query: string, scope: {
@@ -527,10 +581,6 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
     groups: OverviewGroup[];
     projectCount: number;
 };
-export declare function printRoutineRunOverview(sessions: SessionMeta[], liveIndex: Map<string, ActiveSession> | undefined, opts?: {
-    hiddenCount?: number;
-    hiddenUnmanaged?: number;
-}): void;
 /**
  * Render a resolved session to stdout — the non-follow view behind
  * `agents logs <sessionId>`. Defaults to the concise `summary` digest (same as