sprag-cli 3.56.0 → 3.57.0

package/src/parser.js

@@ -1,9 +1,9 @@
 import { createReadStream, openSync, readSync, closeSync, fstatSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { join, isAbsolute } from 'node:path';
+import { join, isAbsolute, basename } from 'node:path';
 import { homedir } from 'node:os';
-import { loadCache, getCached, putCached, saveCache } from './session-cache.js';
+import { loadCache, getCached, putCached, saveCache, getCachedSince, putCachedSince } from './session-cache.js';
 import { resolveModelAlias, isGatewayModelId } from './model-alias.js';
 
 const CLAUDE_DIR = join(homedir(), '.claude', 'projects');
@@ -59,6 +59,12 @@ export async function parseSessionFile(filePath) {
     if (!msg?.usage || !msg.id) continue;
 
     const usage = msg.usage;
+    // "<synthetic>" marks a stub Claude Code wrote locally, such as an error or
+    // an interrupt notice. No API call was made and no token was billed, so it
+    // is not a request, and a transcript holding nothing else is not a session.
+    // Counted, they put hundreds of calls that never happened into the report.
+    if (msg.model === '<synthetic>' && !(usage.input_tokens || usage.output_tokens ||
+        usage.cache_creation_input_tokens || usage.cache_read_input_tokens)) continue;
     const cc = usage.cache_creation || {};
     const reqId = entry.requestId || msg.id;
 
@@ -87,7 +93,6 @@ export async function parseSessionFile(filePath) {
   }
 
   const reqs = [...requests.values()];
-  let maxContextPerRequest = 0;
   // Representative model: the one that handled the most requests, skipping
   // "<synthetic>" (Claude Code's local error-stub placeholder — no real API
   // call). Taking reqs[0] blindly let an error stub at session start
@@ -104,20 +109,7 @@ export async function parseSessionFile(filePath) {
     if (n > best) { best = n; model = m; }
   }
   if (best === 0 && reqs.length > 0) model = reqs[0].model || 'unknown';
-  const totals = reqs.reduce(
-    (acc, r) => {
-      acc.input += r.inputTokens;
-      acc.cacheCreation += r.cacheCreationTokens;
-      acc.cacheRead += r.cacheReadTokens;
-      acc.ephemeral5m += r.ephemeral5mTokens;
-      acc.ephemeral1h += r.ephemeral1hTokens;
-      acc.output += r.outputTokens;
-      const ctx = r.inputTokens + r.cacheCreationTokens + r.cacheReadTokens;
-      if (ctx > maxContextPerRequest) maxContextPerRequest = ctx;
-      return acc;
-    },
-    { input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 },
-  );
+  const { totals, maxContextPerRequest, modelTotals } = sumRequests(reqs);
 
   return {
     sessionId,
@@ -129,10 +121,48 @@ export async function parseSessionFile(filePath) {
     totals,
     maxContextPerRequest,
     model,
+    ...(modelTotals ? { modelTotals } : {}),
     gatewayObserved,
   };
 }
 
+const emptyTotals = () => ({ input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 });
+
+function addRequest(acc, r) {
+  acc.input += r.inputTokens;
+  acc.cacheCreation += r.cacheCreationTokens;
+  acc.cacheRead += r.cacheReadTokens;
+  acc.ephemeral5m += r.ephemeral5mTokens;
+  acc.ephemeral1h += r.ephemeral1hTokens;
+  acc.output += r.outputTokens;
+}
+
+/**
+ * Totals of a set of requests, plus the same totals split by model when more
+ * than one model spent tokens.
+ *
+ * `/model` switches model mid-session, and the session's one `model` field is
+ * only the model that answered most often. Pricing the whole session at that
+ * model's rate billed a Haiku stretch at the Fable rate, or the reverse. The
+ * split lets the cost side price each model's tokens at its own rate. It is
+ * left out for the usual single-model session, so those keep their old shape.
+ */
+function sumRequests(reqs) {
+  const totals = emptyTotals();
+  const byModel = new Map();
+  let maxContextPerRequest = 0;
+  for (const r of reqs) {
+    addRequest(totals, r);
+    const ctx = r.inputTokens + r.cacheCreationTokens + r.cacheReadTokens;
+    if (ctx > maxContextPerRequest) maxContextPerRequest = ctx;
+    if (ctx + r.outputTokens === 0) continue;
+    const key = r.model || 'unknown';
+    if (!byModel.has(key)) byModel.set(key, emptyTotals());
+    addRequest(byModel.get(key), r);
+  }
+  return { totals, maxContextPerRequest, modelTotals: byModel.size > 1 ? Object.fromEntries(byModel) : null };
+}
+
 /**
  * Find the most recent user-message timestamp in a session JSONL.
  * Used for statusline mode so the agent's own tool calls don't reset the TTL
@@ -284,6 +314,7 @@ export async function discoverSessionFiles(options = {}) {
       continue;
     }
 
+    const names = new Set(entries);
     for (const entry of entries) {
       if (!entry.endsWith('.jsonl')) continue;
       const fp = join(projPath, entry);
@@ -293,7 +324,15 @@ export async function discoverSessionFiles(options = {}) {
         if (s.mtimeMs >= cutoff) {
           // `size` pairs with `mtime` as the session-cache key — transcripts
           // are append-only, so the pair identifies a parse result exactly.
-          files.push({ path: fp, projectDir: projDir, mtime: s.mtimeMs, size: s.size });
+          const file = { path: fp, projectDir: projDir, mtime: s.mtimeMs, size: s.size };
+          // The listing already says whether the session has a folder of its
+          // own, so sessions without subagents cost no extra syscall.
+          const sessionDir = entry.slice(0, -'.jsonl'.length);
+          if (names.has(sessionDir)) {
+            const subagentFiles = await listSubagentFiles(join(projPath, sessionDir), projDir, cutoff);
+            if (subagentFiles.length) file.subagentFiles = subagentFiles;
+          }
+          files.push(file);
         }
       } catch {
         continue;
@@ -301,7 +340,51 @@ export async function discoverSessionFiles(options = {}) {
     }
   }
 
-  return files.sort((a, b) => a.mtime - b.mtime);
+  return dedupeSessionFiles(files).sort((a, b) => a.mtime - b.mtime);
+}
+
+/**
+ * Transcripts of the subagents a session spawned:
+ * `<session id>/subagents/agent-*.jsonl`. Their requests are billed like any
+ * other and appear nowhere in the session's own transcript.
+ */
+async function listSubagentFiles(sessionDir, projectDir, cutoff) {
+  const dir = join(sessionDir, 'subagents');
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.startsWith('agent-') || !entry.endsWith('.jsonl')) continue;
+    try {
+      const fp = join(dir, entry);
+      const s = await stat(fp);
+      if (s.mtimeMs >= cutoff) files.push({ path: fp, projectDir, mtime: s.mtimeMs, size: s.size });
+    } catch {
+      continue;
+    }
+  }
+  return files;
+}
+
+/**
+ * One file per transcript name. A project folder that was renamed or copied
+ * leaves the same `<session id>.jsonl` under two project directories, and
+ * every aggregate then counted that session twice. Transcripts are
+ * append-only, so the larger copy is the superset; the newer one breaks a tie
+ * and the first one found wins an exact tie.
+ */
+export function dedupeSessionFiles(files) {
+  const byName = new Map();
+  for (const f of files) {
+    const name = basename(f.path);
+    const kept = byName.get(name);
+    if (!kept || f.size > kept.size || (f.size === kept.size && f.mtime > kept.mtime)) byName.set(name, f);
+  }
+  return [...byName.values()];
 }
 
 /**
@@ -328,27 +411,14 @@ function spansCutoff(session, cutoffMs) {
  */
 function trimToCutoff(session, cutoffMs) {
   const reqs = (session.requests || []).filter((r) => r.ts == null || r.ts >= cutoffMs);
-  let maxContextPerRequest = 0;
   let firstTs = null;
   let lastTs = null;
-  const totals = reqs.reduce(
-    (acc, r) => {
-      acc.input += r.inputTokens;
-      acc.cacheCreation += r.cacheCreationTokens;
-      acc.cacheRead += r.cacheReadTokens;
-      acc.ephemeral5m += r.ephemeral5mTokens;
-      acc.ephemeral1h += r.ephemeral1hTokens;
-      acc.output += r.outputTokens;
-      const ctx = r.inputTokens + r.cacheCreationTokens + r.cacheReadTokens;
-      if (ctx > maxContextPerRequest) maxContextPerRequest = ctx;
-      if (r.ts != null) {
-        if (firstTs === null || r.ts < firstTs) firstTs = r.ts;
-        if (lastTs === null || r.ts > lastTs) lastTs = r.ts;
-      }
-      return acc;
-    },
-    { input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 },
-  );
+  for (const r of reqs) {
+    if (r.ts == null) continue;
+    if (firstTs === null || r.ts < firstTs) firstTs = r.ts;
+    if (lastTs === null || r.ts > lastTs) lastTs = r.ts;
+  }
+  const { totals, maxContextPerRequest, modelTotals } = sumRequests(reqs);
   return {
     sessionId: session.sessionId,
     filePath: session.filePath,
@@ -359,10 +429,19 @@ function trimToCutoff(session, cutoffMs) {
     totals,
     maxContextPerRequest,
     model: session.model,
+    ...(modelTotals ? { modelTotals } : {}),
     gatewayObserved: session.gatewayObserved,
   };
 }
 
+/** Attach the summary trimmed to `sinceMs` when the fully parsed session spans it. */
+function withSinceTrim(summary, full, sinceMs) {
+  if (sinceMs !== null && spansCutoff(full, sinceMs)) {
+    summary.sinceTrim = { since: sinceMs, session: trimToCutoff(full, sinceMs) };
+  }
+  return summary;
+}
+
 export async function parseAllSessions(options = {}) {
   const files = await discoverSessionFiles(options);
   const concurrency = 10;
@@ -378,31 +457,22 @@ export async function parseAllSessions(options = {}) {
   // stores the window-independent full parse.
   const days = options.days ?? 30;
   const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
+  // A second, fixed cutoff the caller will ask about next (sessionsSince). A
+  // file that has to be read here anyway is trimmed to it in the same pass.
+  const sinceMs = Number.isFinite(options.sinceMs) ? options.sinceMs : null;
 
   for (let i = 0; i < files.length; i += concurrency) {
     const batch = files.slice(i, i + concurrency);
     const parsed = await Promise.all(
       batch.map(async (f) => {
         try {
-          if (useCache) {
-            const hit = getCached(cache, f);
-            if (hit) {
-              if (!spansCutoff(hit, cutoffMs)) return hit;
-              // Boundary session from cache: the cached summary has no
-              // per-request data, so re-read the file to trim it.
-              const full = await parseSessionFile(f.path);
-              full.projectDir = f.projectDir;
-              return trimToCutoff(full, cutoffMs);
-            }
+          const summary = await parseOne(f);
+          const runs = await subagentRuns(f);
+          if (runs.length) summary.subagentRuns = runs;
+          if (summary.sinceTrim) {
+            const since = runs.filter((r) => r.endTime.getTime() >= sinceMs);
+            if (since.length) summary.sinceTrim.session.subagentRuns = since;
           }
-          const session = await parseSessionFile(f.path);
-          session.projectDir = f.projectDir;
-          if (useCache) {
-            putCached(cache, f, session);
-            misses++;
-          }
-          if (spansCutoff(session, cutoffMs)) return trimToCutoff(session, cutoffMs);
-          const { requests, ...summary } = session;
           return summary;
         } catch {
           return null;
@@ -415,4 +485,110 @@ export async function parseAllSessions(options = {}) {
   if (useCache && misses > 0) saveCache(cache);
 
   return results.filter((s) => s.requestCount > 0);
+
+  /**
+   * What a session's subagents spent, one entry per run with its own model so
+   * each is priced at its own rate. They ride on the session instead of being
+   * sessions themselves: the money counts, while the session count, context
+   * peaks and spike baselines keep describing conversations. A run is counted
+   * whole in the period it ended in; it lasts minutes, so it is not trimmed.
+   */
+  async function subagentRuns(f) {
+    const runs = [];
+    for (const a of f.subagentFiles || []) {
+      try {
+        let run = useCache ? getCached(cache, a) : null;
+        if (!run) {
+          run = await parseSessionFile(a.path);
+          if (useCache) {
+            putCached(cache, a, run);
+            misses++;
+          }
+        }
+        if (!run.requestCount || !run.endTime || run.endTime.getTime() < cutoffMs) continue;
+        runs.push({ model: run.model, totals: run.totals, requestCount: run.requestCount, endTime: run.endTime,
+          ...(run.modelTotals ? { modelTotals: run.modelTotals } : {}) });
+      } catch {
+        continue;
+      }
+    }
+    return runs;
+  }
+
+  async function parseOne(f) {
+    if (useCache) {
+      const hit = getCached(cache, f);
+      if (hit) {
+        if (!spansCutoff(hit, cutoffMs)) {
+          const since = sinceMs !== null && spansCutoff(hit, sinceMs) ? getCachedSince(cache, f, sinceMs) : null;
+          if (since) hit.sinceTrim = { since: sinceMs, session: since };
+          return hit;
+        }
+        // Boundary session from cache: the cached summary has no
+        // per-request data, so re-read the file to trim it.
+        const full = await parseSessionFile(f.path);
+        full.projectDir = f.projectDir;
+        return withSinceTrim(trimToCutoff(full, cutoffMs), full, sinceMs);
+      }
+    }
+    const session = await parseSessionFile(f.path);
+    session.projectDir = f.projectDir;
+    if (useCache) {
+      putCached(cache, f, session);
+      misses++;
+    }
+    const { requests, ...whole } = session;
+    const summary = spansCutoff(session, cutoffMs) ? trimToCutoff(session, cutoffMs) : whole;
+    withSinceTrim(summary, session, sinceMs);
+    if (useCache && summary.sinceTrim) putCachedSince(cache, f, sinceMs, summary.sinceTrim.session);
+    return summary;
+  }
+}
+
+/**
+ * The same sessions counted from `sinceMs` on: a session that started before
+ * it is re-aggregated from its per-request timestamps, and one that ended
+ * before it is dropped. A calendar-month total needs this, because a session
+ * left open across midnight on the 1st otherwise brings last month's requests
+ * with it.
+ *
+ * `sinceMs` is fixed for as long as the caller's period lasts, so the trimmed
+ * summary is cached next to the full one and the statusline re-reads a
+ * boundary transcript once, not on every refresh.
+ *
+ * @param {Array} sessions parseAllSessions result
+ * @param {number} sinceMs epoch ms
+ */
+export async function sessionsSince(sessions, sinceMs, { noCache = false } = {}) {
+  const out = [];
+  let cache = null;
+  let stored = 0;
+  for (const s of sessions || []) {
+    if (!s || !s.endTime || s.endTime.getTime() < sinceMs) continue;
+    if (!spansCutoff(s, sinceMs)) { out.push(s); continue; }
+    if (s.sinceTrim && s.sinceTrim.since === sinceMs) {
+      if (s.sinceTrim.session.requestCount > 0) out.push(s.sinceTrim.session);
+      continue;
+    }
+    try {
+      const st = await stat(s.filePath);
+      const file = { path: s.filePath, projectDir: s.projectDir, mtime: st.mtimeMs, size: st.size };
+      if (!noCache) cache = cache || loadCache();
+      let trimmed = noCache ? null : getCachedSince(cache, file, sinceMs);
+      if (!trimmed) {
+        const full = await parseSessionFile(s.filePath);
+        full.projectDir = s.projectDir;
+        trimmed = trimToCutoff(full, sinceMs);
+        if (!noCache && putCachedSince(cache, file, sinceMs, trimmed)) stored++;
+      }
+      const runs = (s.subagentRuns || []).filter((r) => r.endTime.getTime() >= sinceMs);
+      if (runs.length) trimmed.subagentRuns = runs;
+      if (trimmed.requestCount > 0) out.push(trimmed);
+    } catch {
+      // Unreadable now (deleted or rotated since the scan): leave it out rather
+      // than count its whole history into this period.
+    }
+  }
+  if (stored > 0) saveCache(cache);
+  return out;
 }

package/src/postinstall.js

@@ -0,0 +1,32 @@
+/**
+ * Whether the npm `postinstall` step should run `sprag install`.
+ *
+ * `install` writes hooks and a statusline into ~/.claude/settings.json, and
+ * those call the `sprag` binary by name. That is what someone who typed
+ * `npm i -g sprag-cli` asked for. The script ran for every other install too:
+ * a project that lists the package as a dependency, the `npx` cache, a CI job,
+ * `npm install` in a checkout of this repository. None of those put `sprag` on
+ * PATH, so the hooks they registered pointed at a command that is not there,
+ * and a CI runner had its home directory rewritten for nothing.
+ *
+ * So setup runs only where it was asked for:
+ *   - never in CI;
+ *   - with npm, only for a global install (npm says so in `npm_config_global`);
+ *   - with another package manager, as before: pnpm and bun do not run this
+ *     script unless the user allowed it, and neither they nor yarn report a
+ *     global install in a way worth guessing at.
+ * `SPRAG_POSTINSTALL=1` forces it and `SPRAG_POSTINSTALL=0` skips it.
+ */
+
+const truthy = (v) => typeof v === 'string' && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+
+export function postinstallDecision(env = process.env) {
+  if (env.SPRAG_POSTINSTALL === '1') return { run: true, reason: 'SPRAG_POSTINSTALL=1' };
+  if (env.SPRAG_POSTINSTALL === '0') return { run: false, reason: 'SPRAG_POSTINSTALL=0' };
+  if (truthy(env.CI)) return { run: false, reason: 'CI environment' };
+  const agent = String(env.npm_config_user_agent || '');
+  if (/^npm\//.test(agent) && env.npm_config_global !== 'true') {
+    return { run: false, reason: 'not a global install' };
+  }
+  return { run: true, reason: /^npm\//.test(agent) ? 'global install' : 'package manager does not report scope' };
+}

package/src/route-caps.js

@@ -0,0 +1,74 @@
+/**
+ * The caps of the delegation rule the current prompt matched, kept per session
+ * so the PreToolUse guard can state the same numbers the rule does.
+ *
+ * The prompt hook tells the main model "delegate, cap 6,100 output tokens" from
+ * the rule's calibrated budget. The guard then rewrote the Task prompt with its
+ * own fixed pair (8 calls / 1,500 tokens for haiku, 20 / 8,000 otherwise), so
+ * the subagent was held to a different limit than the one the main model had
+ * just been given. The guard sees only the Task call, not the user prompt that
+ * matched the rule, so the prompt hook leaves the matched caps here for it.
+ *
+ * One record per session, replaced by every prompt: a prompt that matches no
+ * rule clears it, so a cap never outlives the turn it was stated for.
+ *
+ * State: <stateDir>/route-caps.json
+ *   { sessions: { [session_id]: { ts, T2?: { calls, out }, T1?: { calls, out } } } }
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+import { writeStateFile } from './state-file.js';
+
+// A turn that is still delegating this long after its prompt is unusual; past
+// it the record is treated as left over from a session that ended mid-turn.
+const TTL_MS = 60 * 60 * 1000;
+const PRUNE_MS = 24 * 60 * 60 * 1000;
+
+export function routeCapsPath() {
+  return join(userDataDir(), 'route-caps.json');
+}
+
+function load() {
+  try {
+    const s = JSON.parse(readFileSync(routeCapsPath(), 'utf8'));
+    return s && s.sessions && typeof s.sessions === 'object' && !Array.isArray(s.sessions) ? s : { sessions: {} };
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+const validBudget = (b) => b && Number.isFinite(b.out) && b.out > 0;
+
+/**
+ * Record the caps this prompt's rule match carries, or clear the session's
+ * record when `caps` is null. Writes nothing when there is nothing to change.
+ */
+export function recordRouteCaps(sessionId, caps, now = Date.now()) {
+  if (typeof sessionId !== 'string' || sessionId === '') return false;
+  const state = load();
+  const next = {};
+  for (const tier of ['T2', 'T1']) {
+    if (validBudget(caps?.[tier])) next[tier] = { calls: caps[tier].calls ?? null, out: caps[tier].out };
+  }
+  const has = Object.keys(next).length > 0;
+  if (!has && !state.sessions[sessionId]) return false;
+  if (has) state.sessions[sessionId] = { ts: now, ...next };
+  else delete state.sessions[sessionId];
+  for (const [id, s] of Object.entries(state.sessions)) {
+    if (!s || !Number.isFinite(s.ts) || now - s.ts > PRUNE_MS) delete state.sessions[id];
+  }
+  writeStateFile(routeCapsPath(), JSON.stringify(state) + '\n');
+  return true;
+}
+
+/** The caps recorded for this session's current turn, or null. */
+export function routeCapsFor(sessionId, now = Date.now()) {
+  if (typeof sessionId !== 'string' || sessionId === '') return null;
+  const s = load().sessions[sessionId];
+  if (!s || !Number.isFinite(s.ts) || now - s.ts > TTL_MS) return null;
+  const out = {};
+  for (const tier of ['T2', 'T1']) if (validBudget(s[tier])) out[tier] = s[tier];
+  return Object.keys(out).length ? out : null;
+}

package/src/route-inject.js

@@ -26,7 +26,7 @@
  */
 
 import { categorize, ESCALATE_RE, EDIT_RE, worthDelegating } from './route-scan.js';
-import { loadModelRules, budgetCapPhrase } from './model-rules.js';
+import { loadModelRules, budgetCapPhrase, ruleBudget } from './model-rules.js';
 import { agentPhrase, agentPhraseEn } from './agents.js';
 import { userLanguage } from './config.js';
 import { aliasForRole, resolveModelAlias } from './model-alias.js';
@@ -77,19 +77,17 @@ export function sessionModelRank({ env = process.env, transcriptPath = null, sna
 }
 
 /**
+ * The rules a prompt matches, or null when the hint should stay quiet.
+ *
  * @param {string} text the prompt just submitted
  * @param {object} [opts]
  * @param {Array} [opts.rules] registered rules (defaults to the stored registry)
- * @param {string} [opts.lang] 'ko' | 'en'
- * @param {string} [opts.root] project root used to look for a subagent's .md.
- *   The hint names the agent when that file exists and only its model tier when
- *   it does not, so a caller that needs a predictable phrase pins this.
  * @param {number|null} [opts.sessionRank] price rank of the model reading the
  *   hint (see sessionModelRank). null means unknown, and an unknown session
  *   model filters nothing.
- * @returns {string|null} the line to inject, or null to stay quiet
+ * @returns {{cat: object, t2: object|undefined, t1: object|undefined}|null}
  */
-export function routeHint(text, { rules, lang = userLanguage(), root, sessionRank = null } = {}) {
+export function routeMatch(text, { rules, sessionRank = null } = {}) {
   const t = String(text || '').trim();
   if (t.length < MIN_LEN) return null;
   // Judgement and irreversible work stay on the top tier. This check comes
@@ -125,6 +123,32 @@ export function routeHint(text, { rules, lang = userLanguage(), root, sessionRan
 
   const t2 = usable.find((r) => r.tier === 'T2');
   const t1 = usable.find((r) => r.tier === 'T1');
+  return t2 || t1 ? { cat, t2, t1 } : null;
+}
+
+/** The budgets a match states, by tier: what the delegation guard repeats to the subagent. */
+export function matchCaps(match) {
+  if (!match) return null;
+  const caps = {};
+  if (match.t2) caps.T2 = ruleBudget(match.t2);
+  if (match.t1) caps.T1 = ruleBudget(match.t1);
+  return caps;
+}
+
+/**
+ * @param {string} text the prompt just submitted
+ * @param {object} [opts] as routeMatch, plus:
+ * @param {string} [opts.lang] 'ko' | 'en'
+ * @param {string} [opts.root] project root used to look for a subagent's .md.
+ *   The hint names the agent when that file exists and only its model tier when
+ *   it does not, so a caller that needs a predictable phrase pins this.
+ * @param {object|null} [opts.match] a routeMatch result the caller already has
+ * @returns {string|null} the line to inject, or null to stay quiet
+ */
+export function routeHint(text, { rules, lang = userLanguage(), root, sessionRank = null, match } = {}) {
+  const found = match === undefined ? routeMatch(text, { rules, sessionRank }) : match;
+  if (!found) return null;
+  const { cat, t2, t1 } = found;
   const ko = lang === 'ko';
   const label = ko ? (cat.label || cat.id) : (cat.labelEn || cat.label || cat.id);
   // `root` is threaded through to agentPhrase, which names the subagent only