kronk-cli 0.6.1 → 0.8.0

package/src/subagent.js

@@ -2,6 +2,9 @@ import { def, TOOLS } from './tools.js';
 import { config } from './config.js';
 import { c, elapsed } from './ui.js';
 import { startRun } from './tasklog.js';
+import { livePane } from './pane.js';
+import { modelLimits as fetchModelLimits } from './client.js';
+import { resolveModel } from './resolve.js';
 
 /**
  * Sub-agents: one delegated task, one throwaway context.
@@ -66,6 +69,18 @@ export const AGENTS = {
 const agentList = () => Object.entries(AGENTS)
   .map(([name, a]) => `"${name}" — ${a.use}`).join('; ');
 
+/**
+ * The ids a task's `model` parameter may name, or null when nobody has said.
+ *
+ * Set once at boot, from `chatModels(await listModels())` in src/boot.js, by
+ * `setServedModels` below. A test that builds `runTask` by hand, as every
+ * test in test/subagent.test.js does, never calls that setter, so this stays
+ * null and the tool is offered exactly as it always was: no `model` property
+ * at all, because an enum with no members is not a real choice, it is a tool
+ * a model would call and then have no valid value to put in it.
+ */
+let servedModels = null;
+
 /**
  * The instruction the delegating model actually reads.
  *
@@ -73,16 +88,14 @@ const agentList = () => Object.entries(AGENTS)
  * the one place a small model reliably looks, so the whole protocol lives
  * here — what it is for, that the sub-agent starts blank, and that a vague
  * prompt is the failure mode.
+ *
+ * `model` is built from `servedModels` rather than written once: the whole
+ * point of the enum is that the delegating model can only ever name a real
+ * id, so the property has to be rebuilt whenever the served list changes,
+ * and left off entirely when there is no list to build it from.
  */
-export const TASK_TOOL = def('task',
-  'Delegate one self-contained piece of work to a sub-agent that runs in its own context. '
-  + 'Use it when getting the answer means reading or running a lot but the answer itself is '
-  + 'small — surveys, searches across many files, reproducing a failure. What the sub-agent '
-  + 'reads never enters this conversation; only its report does. The sub-agent cannot see this '
-  + 'conversation and cannot ask you anything, so the prompt must carry everything it needs and '
-  + 'must say exactly what to report back. It cannot delegate further. Prefer one well-scoped '
-  + 'task over several vague ones.',
-  {
+function buildTaskTool(models) {
+  const properties = {
     agent: {
       type: 'string',
       enum: Object.keys(AGENTS),
@@ -93,8 +106,50 @@ export const TASK_TOOL = def('task',
       description: 'The whole task, written for someone who knows nothing about this '
         + 'conversation: what to do, where to look, and exactly what to report back.',
     },
-  },
-  ['agent', 'prompt']);
+  };
+  if (models?.length) {
+    properties.model = {
+      type: 'string',
+      enum: models,
+      description: 'Which model to run this task on, when the default is not the right size '
+        + 'for it. A survey that reads a lot and concludes little wants a small, fast model; '
+        + 'reproducing a failure or making a change wants a large one. Omit it to use the '
+        + "session's own default. Naming a model that is not already loaded costs a real "
+        + 'load — seconds, not instant — so only ask for a different one when the task actually '
+        + 'needs it.',
+    };
+  }
+  return def('task',
+    'Delegate one self-contained piece of work to a sub-agent that runs in its own context. '
+    + 'Use it when getting the answer means reading or running a lot but the answer itself is '
+    + 'small — surveys, searches across many files, reproducing a failure. What the sub-agent '
+    + 'reads never enters this conversation; only its report does. The sub-agent cannot see this '
+    + 'conversation and cannot ask you anything, so the prompt must carry everything it needs and '
+    + 'must say exactly what to report back. It cannot delegate further. Prefer one well-scoped '
+    + 'task over several vague ones.',
+    properties,
+    ['agent', 'prompt']);
+}
+
+export let TASK_TOOL = buildTaskTool(servedModels);
+
+/**
+ * Tell src/subagent.js what Kronk is actually serving, so the task tool's
+ * `model` parameter can only ever name something real.
+ *
+ * Called once at boot with `chatModels(ids)` from src/boot.js — never the
+ * raw list from `listModels()`, so an embedding model, or a bare id sitting
+ * next to its own /AGENT profile, can never appear as something a delegated
+ * task is allowed to ask for. What it does keep is every chat model that has
+ * no profile of its own; src/boot.js has the argument for why that matters
+ * more here than it does when one default is being chosen. `null` (or an
+ * empty list) puts the tool back to its no-`model` shape, which is also its
+ * starting shape — nothing to degrade to, because nothing was ever added.
+ */
+export function setServedModels(ids) {
+  servedModels = Array.isArray(ids) && ids.length ? [...ids] : null;
+  TASK_TOOL = buildTaskTool(servedModels);
+}
 
 /**
  * The delegation tool, when it is allowed at all.
@@ -133,6 +188,14 @@ const nest = (line) => String(line).split('\n')
 /** How much of the prompt fits on the opening line. */
 const GIST = 60;
 
+/**
+ * The tail of a model id — enough of it to actually distinguish one on screen.
+ * A served id's own name is the second-to-last segment (`unsloth/Qwen3.6-…
+ * /AGENT`); the last segment alone is often just `AGENT` or `base`, which
+ * every profile of every model shares and which therefore says nothing.
+ */
+const short = (id) => String(id).split('/').slice(-2).join('/');
+
 /**
  * The line that says a run has started.
  *
@@ -140,11 +203,18 @@ const GIST = 60;
  * two of them in a row are indistinguishable in scrollback. The gist is the
  * prompt's first line, cut: enough to recognise which task this was, never
  * enough to be worth reading instead of the report.
+ *
+ * `model` is named here too, always, not only when it differs from the
+ * session's own — residency is the real cost of letting a task pick one
+ * (src/subagent.js's module comment on `setServedModels`), and "which model
+ * just cost you a cold load" is a question this line should answer without
+ * making anyone go read /agents first.
  */
-export function openLine(agent, prompt) {
+export function openLine(agent, prompt, model) {
   const first = String(prompt).split('\n')[0].trim();
   const gist = first.length > GIST ? `${first.slice(0, GIST - 1)}…` : first;
-  return `${c.grey('   ┌')} ${c.bold(agent)} ${c.grey(`· ${gist}`)}`;
+  const tag = model ? c.grey(` · ${short(model)}`) : '';
+  return `${c.grey('   ┌')} ${c.bold(agent)}${tag} ${c.grey(`· ${gist}`)}`;
 }
 
 /**
@@ -152,13 +222,17 @@ export function openLine(agent, prompt) {
  *
  * This is what makes `reportLines`' "…N more lines" actionable: the report on
  * screen is bounded, and now there is somewhere to go for the rest of it and
- * for everything the sub-agent read on the way.
+ * for everything the sub-agent read on the way. Once the pane erases itself it
+ * carries more than that — it is all that is left of the run on screen.
  */
-export function closeLine({ ms, steps, path, ok }) {
+export function closeLine({ ms, steps, n, ok }) {
   // A run that threw or was interrupted is the one worth reading, so the line
   // that points at its transcript must not read like a clean finish.
   const bits = [`${steps} step${steps === 1 ? '' : 's'}`, elapsed(ms), ...(ok ? [] : ['stopped'])];
-  if (path) bits.push(path);
+  // The command that reads the transcript, not the file it reads. The absolute
+  // path under the temp dir is long, mostly noise, and not a thing anyone would
+  // type; `/tasks 3` is both shorter and the answer to "how do I see it".
+  if (n) bits.push(`/tasks ${n} for the transcript`);
   const line = `   └ ${bits.join(' · ')}`;
   return ok ? c.grey(line) : c.yellow(line);
 }
@@ -191,6 +265,29 @@ function reportFrom(messages) {
   return text;
 }
 
+/**
+ * One model's window and output cap, looked up once per distinct id and kept
+ * for the rest of the session.
+ *
+ * Used to be a single field, `config.subagentLimits`, resolved once at boot
+ * for the one id `KRONK_SUBAGENT_MODEL` named. Now that a task can name a
+ * different model on every delegation, "once at boot for one id" is not
+ * enough — but "once per delegation" is worse: a survey and a build fix
+ * delegated back to back on the same small model would ask Kronk for the
+ * same profile twice for no reason. A `Map` keyed by id is the middle
+ * ground — paid once per model actually used, not once per model that exists
+ * and not once per task that runs.
+ */
+const limitsCache = new Map();
+
+/** Test-only: the cache is a session-lifetime optimisation, not a session. */
+export function resetLimitsCache() { limitsCache.clear(); }
+
+async function limitsFor(id, fetchLimits) {
+  if (!limitsCache.has(id)) limitsCache.set(id, await fetchLimits(id));
+  return limitsCache.get(id);
+}
+
 /**
  * Run one delegated task to completion and hand back only its report.
  *
@@ -201,6 +298,12 @@ function reportFrom(messages) {
  */
 export async function runTask(args, {
   run, model, signal, approve, grant, out = console.log, maxSteps = config.subagentSteps,
+  // Injected the same way `run` and `out` are, and for the same reason: the
+  // pane's behaviour is a screen behaviour, and a test has no screen.
+  pane: makePane = livePane,
+  // Real Kronk by default; a test hands in a stub so resolving a named
+  // model's limits never touches a network nobody promised would be there.
+  modelLimits: fetchLimits = fetchModelLimits,
 }) {
   const agent = args?.agent ?? 'explore';
   const prompt = String(args?.prompt ?? '').trim();
@@ -214,16 +317,52 @@ export async function runTask(args, {
     { role: 'user', content: prompt },
   ];
 
+  // The model this task actually runs on: what it asked for, else the
+  // session's configured default for delegation, else the session's own.
+  let taskModel = config.subagentModel ?? model;
+  const wanted = args?.model ? String(args.model).trim() : '';
+  // A note for the tool result, not a return in itself — a task that asked
+  // for a model that turns out not to be served still runs, on the fallback
+  // above, because there is nothing the delegating model can do to fix an id
+  // that came straight out of the enum it was offered. Failing the whole
+  // delegation over it would only cost a retry with the same bad value; a
+  // note it can read and carry forward is strictly more useful.
+  let modelNote = null;
+  if (wanted) {
+    if (servedModels) {
+      const resolved = resolveModel(wanted, servedModels);
+      if (resolved) taskModel = resolved;
+      else modelNote = `note: "${wanted}" is not being served right now — ran on ${short(taskModel)} instead.`;
+    } else {
+      // Nothing to check the name against — a unit test that built `runTask`
+      // by hand, or a session where `setServedModels` was never called. The
+      // id is trusted exactly as `model` and `config.subagentModel` already
+      // are in that situation: a plain string, handed to `run` unvalidated.
+      taskModel = wanted;
+    }
+  }
+
   // A sub-agent on another model gets that model's window and output cap, not
   // the session's. Compacting a 32k sub-agent at 85% of the main model's 131k
-  // means never compacting it at all.
-  const own = config.subagentModel ? config.subagentLimits : null;
+  // means never compacting it at all. The session's own model needs no
+  // lookup — config.contextWindow and config.maxTokens already are its
+  // limits, kept current by applyLimits whenever the session switches models.
+  const limits = taskModel === model ? null : await limitsFor(taskModel, fetchLimits);
 
   // Recorded from here, not from the first step: a run that dies in its first
   // model call still leaves a file saying which task was asked for.
-  const log = startRun({ agent, prompt, model: config.subagentModel ?? model });
+  const log = startRun({ agent, prompt, model: taskModel });
   const started = Date.now();
-  out(openLine(agent, prompt));
+
+  // On a terminal the run is drawn in a box that erases itself; on a pipe, a
+  // dumb terminal or an `--auto` run nobody is watching, `livePane` hands back
+  // an inert one and everything below takes exactly the path it took before
+  // the pane existed. The transcript is written either way, which is what
+  // makes erasing the box safe — see src/pane.js.
+  const pane = makePane({ agent, model: taskModel, maxSteps, signal });
+  if (pane.enabled) pane.open();
+  else out(openLine(agent, prompt, taskModel));
+  if (modelNote) out(c.yellow(`   ${modelNote}`));
 
   let steps = 0;
   let report;
@@ -232,12 +371,15 @@ export async function runTask(args, {
       messages,
       // A smaller model for the grunt work is the whole reason this is a knob:
       // the survey is reading and grepping, the synthesis is not.
-      model: config.subagentModel ?? model,
-      window: own ? own.contextWindow : config.contextWindow,
-      maxTokens: own?.maxTokens ?? config.maxTokens,
+      model: taskModel,
+      window: limits ? limits.configured : config.contextWindow,
+      maxTokens: limits?.maxTokens ?? config.maxTokens,
       signal,
-      approve,
-      grant,
+      // Wrapped, not replaced: delegation is still not a way to get a command
+      // past the user. The wrapper only wipes the box first, so the question is
+      // asked on a clear screen and nothing redraws over it while it waits.
+      approve: pane.shield(approve),
+      grant: pane.shield(grant),
       // No MCP: a local model already struggles past ~25 tools, and the
       // sub-agent's list is meant to be the short one.
       mcp: null,
@@ -250,23 +392,37 @@ export async function runTask(args, {
       // second stream interleaved with the caller's is unreadable. Tool calls
       // still show, indented, so the run is not a black box.
       stream: false,
-      out: (line) => out(nest(line)),
+      out: pane.enabled ? (line) => pane.line(line) : (line) => out(nest(line)),
+      // The pane is already the live view, and the spinner and the per-command
+      // live line both rewrite the current line with `\r` — which is the last
+      // row of the box. Two things redrawing the same row is the one way this
+      // can look broken, so below a pane there is only one of them.
+      quiet: pane.enabled,
       maxSteps,
       depth: 1,
       // Written as it goes rather than at the end. The runs worth reading are
       // the ones that were interrupted, threw, or ran out of steps, and none
       // of those reach the line below.
-      onStep: (msgs, n) => { steps = n; log?.step(msgs, n); },
+      onStep: (msgs, n) => { steps = n; pane.step(n); log?.step(msgs, n); },
     });
 
     report = reportFrom(done);
+    // The delegating model reads the tool result, not the scrollback, so the
+    // note about a model it asked for and did not get belongs in both —
+    // printed above when the run started, and carried in what it gets back.
+    if (modelNote) report = `${modelNote}\n\n${report}`;
+    // Before the report, so the box is gone by the time the answer lands in
+    // the scrollback it is keeping clean.
+    pane.close();
     reportLines(report).forEach((l) => out(l));
     return report;
   } finally {
     // In `finally` so an abort or a throw still closes the record and still
     // tells the user where the partial transcript is — that is the case the
-    // transcript exists for.
-    const path = log?.finish({ report, steps });
-    out(closeLine({ ms: Date.now() - started, steps, path, ok: report !== undefined }));
+    // transcript exists for. `close` is idempotent; the success path already
+    // called it above.
+    pane.close();
+    log?.finish({ report, steps });
+    out(closeLine({ ms: Date.now() - started, steps, n: log?.n, ok: report !== undefined }));
   }
 }

package/src/tasklog.js

@@ -203,6 +203,11 @@ const gist = (prompt, width) => {
  * never finished says so rather than reporting a duration it does not have:
  * "still running" and "died three steps in" are the two states where the
  * transcript is worth the most, and both would otherwise render as a blank.
+ *
+ * The model is named on every line, not only the ones that used a different
+ * one: a task can now pick its own (src/subagent.js), and a run that took a
+ * minute longer than the others is otherwise a mystery — this is the list
+ * where that gets explained, without opening the run in full.
  */
 export function runLines() {
   if (!config.taskLog) {
@@ -216,7 +221,8 @@ export function runLines() {
     const how = { done: took(r.ms), stopped: 'stopped', running: 'running' }[r.state] ?? took(r.ms);
     const state = `${r.steps} step${r.steps === 1 ? '' : 's'} \u00b7 ${how}`.padEnd(20);
     const dot = { done: c.green('\u25cf'), stopped: c.yellow('\u25cf'), running: c.blue('\u25cf') }[r.state] ?? c.grey('\u25cf');
-    return `  ${dot} ${c.bold(String(r.n).padStart(2))}  ${r.agent.padEnd(7)} ${c.grey(state)} ${c.grey(gist(r.prompt, 44))}`;
+    const model = r.model ? `${r.model.split('/').slice(-2).join('/')} \u00b7 ` : '';
+    return `  ${dot} ${c.bold(String(r.n).padStart(2))}  ${r.agent.padEnd(7)} ${c.grey(state)} ${c.grey(model)}${c.grey(gist(r.prompt, 40))}`;
   });
   lines.push(c.grey(`\n  /tasks <n> for one in full \u00b7 ${sessionDir()}`));
   return lines;

package/src/ui.js

@@ -24,12 +24,26 @@ export const c = {
   grey: wrap('grey'),
 };
 
-export const banner = (model, url) => `
-${c.cyan('  ██ kronk-cli')}  ${c.grey('· local agent, no network')}
-  ${c.grey('model')}  ${c.bold(model)}
-  ${c.grey('server')} ${url}
-  ${c.grey('/help for commands · Ctrl-C to interrupt · /exit to quit')}
-`;
+/** `{current, latest, hint}` when a newer release exists; `{current, hint}` when only the route is known (see src/update.js). */
+const fmtCliUpdate = (u) => (u.latest
+  ? `kronk-cli ${u.current} → ${u.latest} · run: ${u.hint}`
+  : `kronk-cli ${u.current} · ${u.hint}`);
+
+/**
+ * `update` is optional and, when there is nothing to report, this renders
+ * exactly what it always has — a session with no news prints no extra line.
+ * See src/update.js for how `update.cli` is decided; this function only lays
+ * it out.
+ */
+export const banner = (model, url, update) => [
+  '',
+  `${c.cyan('  ██ kronk-cli')}  ${c.grey('· local agent, no network')}`,
+  `  ${c.grey('model')}  ${c.bold(model)}`,
+  `  ${c.grey('server')} ${url}`,
+  ...(update?.cli ? [`  ${c.grey('update')}  ${fmtCliUpdate(update.cli)}`] : []),
+  `  ${c.grey('/help for commands · Ctrl-C to interrupt · /exit to quit')}`,
+  '',
+].join('\n');
 
 const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}k` : String(n));
 

package/src/update.js

@@ -0,0 +1,291 @@
+/**
+ * "A newer kronk-cli is available" — asked of the package manager that put
+ * this copy on disk, never of the network directly. `test/egress.test.js`
+ * forbids `fetch` to anything but the configured Kronk host and forbids a raw
+ * `node:http` import; this module respects both by going through `npm`,
+ * `brew` and `git` subprocesses the same way `src/setup.js` goes through
+ * `kronk` — a manager knows the version graph for the thing it manages, and
+ * asking it is the whole point of the issue this module exists for.
+ *
+ * It is a fifth entry in the `child_process` allowlist that test enforces,
+ * alongside `context.js`, `mcp.js`, `setup.js` and `tools.js`. It earns its
+ * own entry rather than borrowing one of theirs: `setup.js`'s door is
+ * `runKronk`, which only ever spawns the `kronk` binary, and reusing it here
+ * would mean either widening what that door lets through or lying about what
+ * command is actually running. `context.js` spawns `git` too, but only ever
+ * `-C <the user's project>` to describe *their* repository for the system
+ * prompt — pointing it at kronk-cli's own install directory to ask a
+ * different question would overload what that module is for. A dedicated
+ * module keeps each spawner's job legible from its name, which is what the
+ * allowlist is trying to preserve in the first place.
+ *
+ * Never on the path that blocks the prompt. `updateStatus` reads a small
+ * cache file synchronously (cheap, local, not a subprocess) and returns
+ * immediately; when that cache is missing or a day or more old it also kicks
+ * off `refreshCliUpdate` for next time, deliberately unawaited. A stale line
+ * shown instantly beats a fresh one that made the REPL wait for `npm view` to
+ * come back over whatever network the machine has today.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { config } from './config.js';
+import { VERSION } from './version.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run a manager and let go of it.
+ *
+ * `unref` is the whole reason this wrapper exists. `updateStatus` fires the
+ * refresh deliberately unawaited, and a live child keeps a handle on the event
+ * loop: without it, quitting the REPL in the first few seconds of a session
+ * prints "bye" and then sits there until `npm view` answers or the timeout
+ * kills it. A cache written for next time is never worth delaying this exit
+ * for — if the answer is lost because the process went away, the next session
+ * simply asks again.
+ */
+function exec(cmd, argv) {
+  const p = execFileAsync(cmd, argv, { timeout: CHECK_TIMEOUT_MS });
+  p.child?.unref?.();
+  return p;
+}
+
+/** A cold `npm view` or `brew outdated` over a slow link still has to give up. */
+const CHECK_TIMEOUT_MS = 4000;
+
+/** "At most once a day" from the issue, in milliseconds. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** What `packaging/install.sh` leaves behind. The only record that route has. */
+const RECEIPT = '.install-receipt.json';
+
+const HINTS = {
+  brew: 'brew upgrade kronk-cli',
+  npm: 'npm install -g kronk-cli@latest',
+  git: 'git pull',
+};
+
+// ---- install-route detection --------------------------------------------
+
+/**
+ * How far up from the running file to look for a `.git` before giving up on
+ * calling this a checkout. `src/index.js` is one level under the repository
+ * root in every layout this project ships or is developed in; the extra
+ * headroom is for a checkout nested a few directories deeper than that.
+ */
+const GIT_SEARCH_DEPTH = 6;
+
+function findGitRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < GIT_SEARCH_DEPTH; i++) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+const toPosix = (p) => p.split(sep).join('/');
+
+/**
+ * Where this running copy of kronk-cli came from, read off the path Node
+ * resolved for `src/index.js` rather than asked of any registry — the issue's
+ * own framing: "detect the route from where the running src/index.js
+ * resolves". Each package manager lays its files out in a shape distinctive
+ * enough to tell apart without guessing:
+ *
+ *   - Homebrew nests a formula's version under `Cellar/<name>/<version>`.
+ *   - npm's global install nests every package under `lib/node_modules`.
+ *   - `packaging/install.sh` has exactly one job — unpack straight into
+ *     `$PREFIX/lib/kronk-cli` — and that shape is otherwise unclaimed.
+ *   - A git checkout is the one route that carries its own `.git` upward
+ *     from wherever the file sits, so it is checked by content rather than by
+ *     path shape.
+ *
+ * Path shape alone is only suggestive, so the routes that can produce
+ * *evidence* are asked first, and the install script's receipt is evidence of
+ * exactly the same rank as a `.git` directory. That ordering is not a detail:
+ * `install.sh` defaults to `$PREFIX=$HOME/.local`, a great many people keep
+ * `$HOME` itself under version control for their dotfiles, and walking up
+ * from `~/.local/lib/kronk-cli/src` reaches `~/.git` well inside
+ * `GIT_SEARCH_DEPTH`. Asking for the `.git` first would tell every one of
+ * those people to run `git pull` to upgrade a tarball install — precisely the
+ * failure the issue means by "the hint must match how it was installed, or it
+ * is worse than nothing". With no receipt there is nothing to go on but the
+ * path, and then a `.git` ancestor is the better guess and wins.
+ *
+ * Returns null when none of the above matches — a shape this function was
+ * never taught, which is the honest answer, not a guess dressed as one.
+ */
+export function detectInstall(entryPath) {
+  const norm = toPosix(entryPath);
+  if (/\/Cellar\/kronk-cli\//.test(norm)) return { route: 'brew' };
+  if (/\/node_modules\/kronk-cli(\/|$)/.test(norm)) return { route: 'npm' };
+
+  const libDir = /\/lib\/kronk-cli\//.test(norm) ? dirname(dirname(entryPath)) : null;
+  if (libDir && existsSync(join(libDir, RECEIPT))) return { route: 'install-sh', dir: libDir };
+
+  const gitRoot = findGitRoot(dirname(entryPath));
+  if (gitRoot) return { route: 'git', dir: gitRoot };
+
+  if (libDir) return { route: 'install-sh', dir: libDir };
+  return null;
+}
+
+// ---- the cache ------------------------------------------------------------
+
+function readCache(path) {
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return typeof data?.checkedAt === 'number' ? data : null;
+  } catch {
+    // Missing, unreadable, or not JSON — treated exactly like "never checked",
+    // which is what it functionally is. A corrupt cache must never crash the
+    // one thing on the startup path that is supposed to be purely cosmetic.
+    return null;
+  }
+}
+
+function writeCache(path, data) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data), 'utf8');
+  } catch {
+    // The cache is a convenience, not the check itself — losing this write
+    // only means the next session asks again instead of reading an answer.
+  }
+}
+
+// ---- semver, just enough of it --------------------------------------------
+
+/** `a` and `b` as dotted numeric components; a leading `v` is not data. */
+function isNewer(current, latest) {
+  if (!latest) return false;
+  const a = current.replace(/^v/, '').split('.').map(Number);
+  const b = latest.replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (Number.isNaN(x) || Number.isNaN(y)) return false;   // an unparseable
+    if (y > x) return true;                                 // component is
+    if (y < x) return false;                                // "no opinion"
+  }
+  return false;
+}
+
+// ---- asking each manager ---------------------------------------------------
+
+async function npmLatest() {
+  try {
+    const { stdout } = await exec('npm', ['view', 'kronk-cli', 'version']);
+    const v = stdout.trim();
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+async function brewLatest() {
+  try {
+    const { stdout } = await exec('brew', ['outdated', '--json']);
+    const data = JSON.parse(stdout);
+    // Absent means "not outdated", which is not a failure — most days this
+    // is the answer, and it renders exactly like "nothing to report".
+    return data.formulae?.find((f) => f.name === 'kronk-cli')?.current_version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `git fetch --tags` is the one network call this module makes through a
+ * manager rather than being blocked outright — the issue asks for it by
+ * name ("though the fetch is a network call made through git and should
+ * follow the same off-switch as the rest"), which `refreshCliUpdate`'s
+ * `config.updateCheck` guard already covers before this is ever called.
+ */
+async function gitLatest(dir) {
+  try {
+    await exec('git', ['-C', dir, 'fetch', '--tags', '--quiet']);
+    const { stdout } = await exec('git', ['-C', dir, 'tag', '--sort=-v:refname']);
+    return stdout.split('\n').map((l) => l.trim()).find(Boolean) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function latestForRoute(route, dir) {
+  if (route === 'brew') return brewLatest();
+  if (route === 'npm') return npmLatest();
+  if (route === 'git') return gitLatest(dir);
+  return null;
+}
+
+/**
+ * The install script leaves no record of where a copy came from unless it
+ * chose to write one — see `packaging/install.sh`'s receipt. Its presence is
+ * the only thing this route can honestly report: not a version comparison
+ * (there is no registry to ask), just a nudge to re-run the same script,
+ * exactly as the issue specifies: "without claiming to know whether a newer
+ * release exists". No cache, no subprocess — a receipt is either sitting
+ * next to this install or it is not.
+ */
+function installScriptHint(install) {
+  if (!existsSync(join(install.dir, RECEIPT))) return null;
+  return { current: VERSION, hint: 're-run the install script' };
+}
+
+/**
+ * Ask the detected manager what the newest kronk-cli is, and cache the
+ * answer. Exported so a test can await it directly; `updateStatus` below
+ * fires it without awaiting, which is the shape the startup path actually
+ * uses.
+ */
+export async function refreshCliUpdate({ entryPath = process.argv[1], install, cacheFile = config.updateCacheFile } = {}) {
+  const found = install ?? detectInstall(entryPath);
+  const cache = { checkedAt: Date.now(), cli: null };
+  if (found && found.route !== 'install-sh') {
+    // A git tag is conventionally `v0.8.1`; npm and Homebrew both answer in
+    // bare `0.8.1`. Stripped here, once, so the banner's arrow reads as one
+    // version pointing at another and not at a spelling difference.
+    const latest = (await latestForRoute(found.route, found.dir))?.replace(/^v/, '') ?? null;
+    if (isNewer(VERSION, latest)) {
+      cache.cli = { current: VERSION, latest, hint: HINTS[found.route] };
+    }
+  }
+  writeCache(cacheFile, cache);
+  return cache.cli;
+}
+
+/**
+ * What the startup banner should say about kronk-cli's own version, decided
+ * without ever making the REPL wait for it.
+ *
+ * `KRONK_UPDATE_CHECK=false` (or the matching config key) turns the whole
+ * thing off: no cache read, no subprocess, ever — for anyone who wants a
+ * program that runs nothing it was not asked to run.
+ */
+export function updateStatus({
+  entryPath = process.argv[1], now = Date.now(), cacheFile = config.updateCacheFile,
+} = {}) {
+  if (!config.updateCheck) return null;
+
+  const install = detectInstall(entryPath);
+  if (!install) return null;
+
+  if (install.route === 'install-sh') {
+    const hint = installScriptHint(install);
+    return hint ? { cli: hint } : null;
+  }
+
+  const cache = readCache(cacheFile);
+  const stale = !cache || now - cache.checkedAt >= DAY_MS;
+  if (stale) {
+    // Next session's answer, not this one's wait.
+    refreshCliUpdate({ entryPath, install, cacheFile }).catch(() => {});
+  }
+  return cache?.cli ? { cli: cache.cli } : null;
+}