@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/insights.js

@@ -1,40 +1,3 @@
-/**
- * Insights command — one observe verb for "how work looks".
- *
- * Two data paths under one name (do not re-split into peer top-level commands):
- *
- *   agents insights              HOW you work (transcript content: tools, friction,
- *                                rhythm, edits) — split by Claude account by default
- *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
- *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
- *   agents insights query        Raw usage.db rows
- *
- * Sibling observe verbs under this same group (different questions):
- *
- *   agents insights cost    what you spent ($ and duration)
- *   agents insights output  what shipped (burn vs PRs and commits)
- *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
- *   agents view             live quota headroom (per account, with auth state)
- *   agents sessions stats   which skills/slash-commands were explicitly invoked
- *
- * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
- * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
- * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
- *
- * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
- * command reads one account's directory, while `balanced` rotation sprays sessions
- * across every signed-in account. This reads the whole index and reports the accounts
- * apart — see lib/session/claude-accounts.ts for how a transcript is attributed.
- *
- * The deterministic report makes zero network calls. `--narrative` is opt-in and adds
- * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
- * `claude -p`.
- *
- * Former top-level `agents trends` is `agents insights mix` (one section:
- * `agents insights mix <recipe>`; `--list` names them).
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { execFile } from 'child_process';
@@ -43,10 +6,10 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { setHelpSections } from '../lib/help.js';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { querySessions, readSessionInsights, writeSessionInsights, clearSessionInsights, } from '../lib/session/db.js';
-import { parseSession } from '../lib/session/parse.js';
-import { computeInsightFacets, mergeFacets, newFacetAccumulator, detectOverlap, percentile, bucketGaps, topEntries, buildInsightActions, } from '../lib/session/insights.js';
+import { parseSession } from '@phnx-labs/sessions-cli/reader';
+import { computeInsightFacets, mergeFacets, newFacetAccumulator, detectOverlap, percentile, bucketGaps, topEntries, buildInsightActions, } from '@phnx-labs/sessions-cli/reader';
 import { formatUsd } from '../lib/pricing/index.js';
-import { formatDuration } from '../lib/session/render.js';
+import { formatDuration } from '@phnx-labs/sessions-cli/reader';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import { registerMixCommands } from '../lib/analytics/mix-commands.js';
 import { registerPerfSubcommand } from './perf.js';
@@ -74,15 +37,6 @@ function resolveGroup(by) {
     console.error(chalk.red('error: --by must be one of: account, agent, project, day'));
     process.exit(1);
 }
-/**
- * Sessions too short to say anything about how you work.
- *
- * Inspired by the filter `/insights` applies, but NOT identical and deliberately not
- * claimed to be: `/insights` counts USER messages, while `messageCount` on the index
- * counts both roles, so the same threshold is a weaker bar here. Matching it exactly
- * would mean parsing every session just to decide whether to parse it. The dropped
- * count is always reported, never silent.
- */
 function isSubstantive(m, minMessages) {
     if ((m.messageCount ?? 0) < minMessages)
         return false;
@@ -105,11 +59,6 @@ function groupLabelFor(m, dim, key) {
         return `${m.accountOrg} <${m.account}>`;
     return key;
 }
-/**
- * Load facets for every in-scope session, parsing only what the cache does not
- * already hold. A cold first run parses every transcript once; after that only files
- * whose (mtime, size) changed are re-read.
- */
 async function collectFacets(rows, onProgress) {
     let unreadable = 0;
     const cached = readSessionInsights(rows.map((r) => r.id));
@@ -120,25 +69,18 @@ async function collectFacets(rows, onProgress) {
     let done = 0;
     for (const row of stale) {
         try {
-            // Stat BEFORE reading, so the stamp we persist describes bytes no newer than the
-            // ones parsed: a rescan landing mid-read then reads as stale, not as a hit.
             const st = fs.statSync(row.filePath);
-            // includeInterrupts: the default event array is a versioned contract, so the
-            // marker is opt-in and this is the reader that opts in.
             const events = parseSession(row.filePath, row.agent, { includeInterrupts: true });
             const facets = computeInsightFacets(events);
             cached.set(row.id, facets);
             fresh.push({ id: row.id, fileMtimeMs: Math.floor(st.mtimeMs), fileSize: st.size, facets });
         }
         catch {
-            // Deleted or corrupt since it was indexed. Counted and reported below, never
-            // silently contributing zero.
             unreadable++;
         }
         done++;
         if (done % 25 === 0)
             onProgress(done, stale.length);
-        // Persist in batches so an interrupted cold run does not lose everything.
         if (fresh.length >= 200) {
             writeSessionInsights(fresh.splice(0, fresh.length));
         }
@@ -176,7 +118,6 @@ function buildGroups(rows, facetsById, dim) {
     }
     return [...byKey.values()].sort((a, b) => b.sessions - a.sessions || a.key.localeCompare(b.key));
 }
-/** A compact bar for a count relative to the row maximum. */
 function bar(count, max, width) {
     if (max <= 0)
         return '';
@@ -221,8 +162,6 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         console.log(out.join('\n'));
         return;
     }
-    // Per-group table — the headline, and the thing no sibling command produces.
-    // Includes silent-stall counts so harness/account laziness is visible without --json.
     out.push('');
     out.push(chalk.bold(`By ${dim}`));
     const labelW = Math.min(Math.max(...groups.map((g) => stringWidth(g.label)), 5), Math.max(16, terminalWidth() - 58));
@@ -244,17 +183,13 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             `${chalk.green(padToWidth(cost, 9))}  ${chalk.gray(padToWidth(dur, 8))}  ` +
             `${chalk.cyan(stalls.padStart(stallW))}  ${chalk.cyan(resumes)}`);
     }
-    // Everything below is the whole scope folded together; per-group detail is in --json.
     const all = newFacetAccumulator();
     for (const g of groups)
         mergeFacets(all, g.facets);
     renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
-    // The `Bash`/`exec` bar above says a shell ran; this says WHICH binary — git, gh,
-    // agents, find, ssh→git — so the tool mix is actionable rather than one lump.
     renderCounts('Shell commands', topEntries(all.bashCommands, 12), out);
     renderCounts('Languages', topEntries(all.languages, 6), out);
     renderCounts('Models', topEntries(all.models, 6), out);
-    // Friction — the section that earns the command.
     renderCounts('Silent stalls by model', topEntries(all.silentStallsByModel ?? {}, 8), out);
     const gaps = all.responseGaps;
     const silentStalls = Object.entries(all.frictionSignals)
@@ -267,8 +202,6 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         chalk.gray('   turns you cut short'));
     out.push(`  ${padToWidth('tool errors', 18)}  ${chalk.cyan(String(all.errorCount))}`);
     if (gaps.length > 0) {
-        // Same timestamps as silent stalls; this line is the distribution. Silent
-        // stalls (below) are the agent-attributed long gaps after the model stopped.
         out.push(`  ${padToWidth('gap until next msg', 18)}  ` +
             chalk.cyan(`p50 ${Math.round(percentile(gaps, 50))}s`) + chalk.gray(` · p90 ${Math.round(percentile(gaps, 90))}s`) +
             chalk.gray('   after assistant last spoke'));
@@ -287,14 +220,10 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
     }
     renderCounts('Friction / thrash', topEntries(all.frictionSignals, 10), out);
-    // Which shell binary was failing when a `failed tool loop: Bash` fired — makes the
-    // loop attributable (`git reconcile`, `find`, `gh`) instead of a bare tool name.
     renderCounts('Shell command failures', topEntries(all.bashCommandFailures, 8), out);
     renderCounts('Dissatisfaction / corrections', topEntries(all.correctionSignals, 10), out);
     renderCounts('Automatable repeats', topEntries(all.automationSignals, 10), out);
     renderCounts('Harness split', harnesses, out);
-    // Actions are built from frictionSignals/correctionSignals/automationSignals
-    // together (buildInsightActions).
     out.push('');
     out.push(chalk.bold('Actions'));
     if (actions.length === 0) {
@@ -306,21 +235,11 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`  ${padToWidth(action.priority, 7)} ${padToWidth(action.category, 11)} ` +
                 `${String(action.evidenceCount).padStart(8)}  ${padToWidth(action.sampleSessionIds.join(', '), 25)} ${action.action}`);
         }
-        // This report is aggregate by contract (SES-IF-4c); a sample id above drills into
-        // one session's timeline via the per-session surface, not a single-session mode here.
         out.push(chalk.gray('  drill into a sample session:  agents sessions trace <id>'));
     }
-    // Output
     out.push('');
     out.push(chalk.bold('What you changed'));
-    // Gate on whether anything was actually measured, not on whether an edit-shaped call
-    // was seen. Codex patches through `exec`, so it can log edit-class calls and still
-    // expose no line arguments to count — rendering that as "0 lines" would read as "wrote
-    // nothing" for a harness that wrote plenty.
     if (all.linesTouchedAfter > 0 || all.linesTouchedBefore > 0) {
-        // "touched", not "+/-": these are the before/after line counts of each edit, so an
-        // Edit with unchanged context lines counts them on both sides. Not a diffstat, and
-        // labelled so nobody reads it as one.
         out.push(`  ${chalk.cyan(String(all.linesTouchedAfter))} ${chalk.gray('lines written,')} ` +
             `${chalk.cyan(String(all.linesTouchedBefore))} ${chalk.gray('replaced')}  ` +
             chalk.gray('(lines touched, not a diff)'));
@@ -329,12 +248,6 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         out.push(`  ${chalk.gray('lines touched  —  not measurable for this harness (edits go through the shell)')}`);
     }
     out.push(`  ${chalk.gray(`${all.filesCreated} created, ${all.filesModified} modified, ${all.filesDeleted} deleted`)}`);
-    // Same not-measurable rule as the lines above. These are substring-matched from
-    // shell command TEXT, and not every harness exposes it — the codex parser populates
-    // `command` for `exec_command` but not plain `exec`, its dominant tool — so gate on
-    // whether we had anything to search rather than on seeing a shell-shaped tool call.
-    // When we did, the count is real, and still disagrees with `agents insights output`, which
-    // counts deduped SHAs from git log.
     if (all.shellCommandsSeen > 0) {
         out.push(`  ${chalk.gray(`${all.gitCommits} commits · ${all.gitPushes} pushes (seen in shell commands)`)}`);
     }
@@ -342,13 +255,10 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         out.push(`  ${chalk.gray('commits  —  not measurable for this harness')}`);
     }
     renderHours(all.messageHours, out);
-    // Concurrency — direct evidence that a single-account view would be wrong.
     if (meta.overlap.overlappingPairs > 0) {
         out.push('');
         out.push(chalk.bold('Parallel sessions'));
         out.push(`  ${chalk.cyan(String(meta.overlap.sessionsInvolved))} ${chalk.gray('sessions ran alongside another')}`);
-        // Pairs, not sessions — stated as pairs so the two numbers are not read as a
-        // subset of each other.
         const crossNote = meta.overlap.crossAccountPairs > 0
             ? `, ${meta.overlap.crossAccountPairs} of them across two different accounts`
             : '';
@@ -371,11 +281,6 @@ function renderReport(groups, dim, meta, actions, harnesses) {
     out.push(chalk.gray('  `agents insights --narrative` for a written read on what to change'));
     console.log(out.join('\n'));
 }
-/**
- * The opt-in coaching layer. Pipes the AGGREGATE through a headless `claude -p` — never
- * raw transcripts, unlike `/insights`, which ships session text to the API. Reuses
- * whatever account the shim resolves, so there is no API key handling here.
- */
 async function renderNarrative(payload) {
     const prompt = [
         'You are reading a developer\'s own coding-session telemetry, already aggregated.',
@@ -400,9 +305,6 @@ async function renderNarrative(payload) {
             timeout: 180_000,
             maxBuffer: 8 * 1024 * 1024,
         });
-        // stderr, always. Under --json stdout is a machine contract, and prose appended
-        // after the closing brace makes the payload unparseable; on a TTY stderr renders
-        // identically, so there is nothing to special-case.
         process.stderr.write('\n' + chalk.bold('Narrative') + '\n');
         process.stderr.write(stdout.trim().split('\n').map((l) => `  ${l}`).join('\n') + '\n');
     }
@@ -413,8 +315,6 @@ async function renderNarrative(payload) {
         console.error('');
         console.error(chalk.red(`✗ narrative unavailable: ${msg}`));
         console.error(chalk.gray('  The report above is complete; only the written section was skipped.'));
-        // A scripted caller asked for this section and did not get it. Say so in the exit
-        // code rather than reporting success for a partial result.
         process.exitCode = 1;
     }
 }
@@ -425,13 +325,8 @@ async function insightsAction(options) {
         console.error(chalk.red('error: --min-messages must be a non-negative integer'));
         process.exit(1);
     }
-    // `--all` is the spelling people reach for; `--since all` is what the window parser
-    // speaks. Accept both rather than failing on an unknown option, and let an explicit
-    // --since win so `--all --since 7d` is not silently contradictory.
     const since = options.since ?? (options.all ? 'all' : '30d');
     const sinceMs = since === 'all' ? undefined : parseTimeFilter(since);
-    // Refresh the index first, exactly as `agents insights cost` does, so a report never silently
-    // describes a stale picture of disk.
     await discoverSessions({ all: true, since: since === 'all' ? undefined : since, limit: 1 });
     if (options.refresh)
         clearSessionInsights();
@@ -486,8 +381,6 @@ async function insightsAction(options) {
             minMessages,
             by: dim,
             overlap,
-            // Built from frictionSignals/correctionSignals/automationSignals together
-            // (buildInsightActions) — same paid friction/correction data as above.
             actions,
             harnesses,
             groups: groups.map((g) => ({
@@ -502,7 +395,6 @@ async function insightsAction(options) {
                     responseGapP50: Math.round(percentile(g.facets.responseGaps, 50)),
                     responseGapP90: Math.round(percentile(g.facets.responseGaps, 90)),
                     responseGapBuckets: bucketGaps(g.facets.responseGaps),
-                    // The raw sample is large and uninteresting once bucketed.
                     responseGaps: undefined,
                 },
             })),
@@ -560,7 +452,6 @@ function configureInsightsCommand(cmd) {
             since: options.since ?? inherited.since,
         });
     });
-    // Cheap counter recipes (former top-level `agents trends`) — same parent, no peer verb.
     registerMixCommands(cmd);
     setHelpSections(cmd, {
         examples: `
@@ -609,9 +500,6 @@ export function registerInsightsCommand(program) {
     configureInsightsCommand(cmd);
     registerCostCommand(cmd);
     registerOutputCommand(cmd);
-    // Latency rollups (former top-level `agents perf` → `agents insights perf`,
-    // PHNX-3391). A sibling observe verb of cost/output, so it lives on the
-    // top-level insights group beside them, not under `sessions insights`.
     registerPerfSubcommand(cmd);
 }
 export function registerSessionsInsightsCommand(sessions) {

package/dist/commands/inspect.d.ts

@@ -1,43 +1,19 @@
-/**
- * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
- *
- * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
- * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
- * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
- * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
- * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
- * list one resource kind for either target form; passing a positional query to the
- * same flag fuzzy-searches for a single resource and prints its detail. Resource
- * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
- * AGENT.md / the file itself) so users can click straight to the source.
- */
 import { Command } from 'commander';
 import type { ManifestHook } from '../lib/types.js';
 import { type McpYamlConfig } from '../lib/mcp.js';
 import { type PluginResourceGroup } from '../lib/plugins/plugins.js';
 import { type JobConfig, type RunMeta } from '../lib/scheduling/routines.js';
-/** Resource kinds the inspect command can drill into. */
 declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents", "routines"];
 type DrillableKind = typeof DRILLABLE_KINDS[number];
-/** Wrap a separator-joined value list under `prefix`, preserving a hanging indent. */
 export declare function wrapJoined(prefix: string, items: string[], sep: string, width: number): string[];
 interface ResourceItem {
     name: string;
     source: string;
-    /** Absolute path to the resource entry (file or directory). */
     path: string;
-    /** Path the OSC-8 link should point at — marker file inside bundles, else `path`. */
     linkTarget: string;
-    /** One-line description (frontmatter `description:` or first non-frontmatter line). */
     description: string;
-    /** Scalar detail rows surfaced in detail mode (e.g. a plugin's version). */
     extra?: Array<[string, string]>;
-    /** For plugins: the resource categories (skills, commands, …) the bundle packages. */
     groups?: PluginResourceGroup[];
-    /**
-     * Machine-shaped fields for `--json`, when the display strings in `extra` would
-     * lose information a script needs (a routine's raw cron, its device arrays).
-     */
     json?: Record<string, unknown>;
 }
 export interface InspectOptions {
@@ -63,89 +39,39 @@ export interface InspectOptions {
 }
 export declare function registerInspectCommand(program: Command): void;
 export interface RepoTarget {
-    /** Display label: 'user' | 'system' | 'project', an extra-repo alias, or a path-derived name. */
     label: string;
-    /** Absolute path to the DotAgents root (the dir holding commands/, skills/, ...). */
     root: string;
 }
-/**
- * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
- * a registered extra-repo alias, or a filesystem path. Paths accept either a
- * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
- * Returns null when the target is none of these.
- */
 export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
 export declare function inspectRepo(repo: RepoTarget, options: InspectOptions): Promise<void>;
-/** List one resource kind from a single repo root — no layering, no overrides. */
 export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
-/** The live answers about one routine — what the YAML alone cannot say. */
 export interface RoutineLiveState {
-    /** Devices whose `routines:` allowlist names it. Empty means it fires nowhere. */
     devices: string[];
-    /** False until some device has materialized an allowlist at all. */
     materialized: boolean;
-    /** This machine's name, for reporting whether the routine is enabled here. */
     thisDevice: string;
-    /**
-     * THIS machine's activation answer, from `routineEnabledOnThisDevice` — the
-     * same call `applyDeviceActivation` makes. `null` means this device has not
-     * materialized its own allowlist, so the file's `enabled:` still governs.
-     *
-     * Deliberately separate from `materialized`, which is fleet-wide: a box whose
-     * own device doc has no `routines:` key while a synced peer's does is the
-     * normal state of a freshly-joined machine, and conflating the two reported
-     * `enabled: no` for routines the daemon was actively firing.
-     */
     enabledHere: boolean | null;
-    /** Last run's status, or null if it has never run on a device we can see. */
     lastStatus: RunMeta['status'] | null;
-    /** ISO timestamp of that run's start. */
     lastAt: string | null;
 }
-/** `2h` / `3d` / `just now` — compact enough for a 10-column cell. */
 export declare function compactAge(iso: string | null, now?: Date): string;
-/** What makes this routine fire: a humanized cron, an event trigger, or nothing. */
 export declare function routineFireLabel(job: JobConfig, now?: Date): string;
-/** What the routine actually executes. Exactly one of agent/workflow/command is set. */
 export declare function routineTargetLabel(job: JobConfig): string;
-/**
- * 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 declare function routineDescription(job: JobConfig | null, raw: string): string;
-/**
- * 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 declare function collectRepoRoutines(repo: RepoTarget, live?: (name: string) => RoutineLiveState, now?: Date): ResourceItem[];
-/** Recursive size + file count of a path; symlinks are not followed. */
 export declare function pathSize(p: string): {
     bytes: number;
     files: number;
 };
-/** Human byte size: "84 KB", "3.1 MB". */
 interface ManifestSummary {
-    /** `run.<agent>.strategy` pairs from agents.yaml. */
     strategies: Array<{
         agent: string;
         strategy: string;
     }>;
-    /** `agents.<agent>` version pins from agents.yaml, when present. */
     versions: Array<{
         agent: string;
         version: string;
     }>;
 }
-/** Parse the repo's own agents.yaml into the version pins + run strategies it declares. */
 export declare function repoManifestSummary(root: string): ManifestSummary | null;
 interface RepoGitInfo {
     branch: string;
@@ -161,55 +87,12 @@ interface RepoGitInfo {
     behind: number | null;
 }
 export declare function repoGitInfo(root: string): RepoGitInfo | null;
-/**
- * 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 declare function summaryLine(description: string): string;
-/**
- * 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 declare function previewFor(kind: DrillableKind, item: ResourceItem, hookManifest: Map<string, ManifestHook>): string;
-/**
- * Compact one-liner for a hook from its manifest entry: the firing events (with
- * the matcher/tool-name in parens), then a `·`-separated predicate summary, then
- * an optional cache tail. Plain text — the caller applies color.
- */
 export declare function summarizeHook(hook: ManifestHook): string;
-/** Compact one-liner for an MCP server: padded transport + the url (http) or command line (stdio). */
 export declare function summarizeMcp(cfg: McpYamlConfig): string;
-/**
- * Index a hook manifest by script basename (no extension). Installed hooks are
- * named after their script file (`04-capture-…`), while the manifest is keyed by
- * logical name (`capture-…`) with the filename in `script:` — so we join on the
- * script basename, not the manifest key.
- */
 export declare function hookManifestByScript(manifest: Record<string, ManifestHook>): Map<string, ManifestHook>;
-/**
- * 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 declare function routineHealthTier(item: ResourceItem): number;
-/**
- * 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 declare function routineDarkWarning(items: ResourceItem[]): string | null;
-/** Read a repo/agents.yaml `hooks:` section into a name→ManifestHook map (best-effort). */
 export declare function hookManifestFromFile(agentsYamlPath: string): Record<string, ManifestHook>;
 export {};