kronk-cli 0.6.1 → 0.8.0

package/src/rescue.js

@@ -0,0 +1,306 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { config, DEFAULT_MODEL, applyLimits } from './config.js';
+import { listModels, modelLimits } from './client.js';
+import { chatModels, pickDefault } from './boot.js';
+import { resolveModel } from './resolve.js';
+import { AGENTS, subagentTools, systemFor } from './subagent.js';
+import { runTurn } from './agent.js';
+import { projectContext } from './context.js';
+import {
+  ROOT, TERMINAL, createJob, readJob, recordStep, markRunning, markDone, markStopped,
+  markFailed, markInterrupted, toJson, collect, sweep, acquireLock, releaseLock,
+} from './rescueStore.js';
+
+/**
+ * `kronk-cli rescue` — the door the issue describes: a job an external
+ * agentic tool can submit to, follow up on, and collect from, without
+ * speaking a protocol or keeping a server up. `oneShot` in src/index.js is
+ * the same idea with the caller inside the process, blocking on the terminal;
+ * this is that same run, detached, reporting through a file instead of a
+ * screen.
+ *
+ * The one thing this file has that src/rescueStore.js deliberately does not:
+ * the ability to spawn a process. Submitting a job means starting a detached
+ * one and walking away from it — that is the whole point, the submitter must
+ * not wait — so it belongs in its own module, added once, deliberately, to
+ * the egress allowlist test/egress.test.js enforces.
+ */
+
+/** `done` 0 · `stopped` 1 · `interrupted` 2 · `failed` 3 — `wait`'s exit code. */
+export const EXIT_CODES = { done: 0, stopped: 1, interrupted: 2, failed: 3 };
+
+/** How often a waiting caller, or a queued worker, checks the record again. */
+const POLL_MS = 300;
+
+const CLI = new URL('./index.js', import.meta.url).pathname;
+
+const verbs = ['status', 'wait', 'result'];
+
+/**
+ * `rescue`'s own argv, one level below src/argv.js: which of the four shapes
+ * — submit, status, wait, result — the words after `rescue` describe.
+ *
+ * Bare words, exactly like `setup` reserves its own name in src/index.js: a
+ * caller who quotes the prompt (the form the README recommends, and the only
+ * form the `--role` example in the issue itself uses) always lands here as
+ * one word, so the common case never collides with a verb. What does collide
+ * is a two-word invocation whose first word is not one of the three verbs —
+ * read as an attempted `<verb> <id>` rather than a short prompt, because
+ * silently running the wrong job's status check is worse than refusing. A
+ * genuine two-word prompt still works; it just has to be quoted, or written
+ * as three words.
+ */
+export function parseRescueCommand(words) {
+  const rest = words.slice(1);
+  if (!rest.length) {
+    return { error: 'rescue needs a prompt, or one of: status <id>, wait <id>, result <id>' };
+  }
+  if (rest.length === 2 && !verbs.includes(rest[0])) {
+    return {
+      error: `unknown rescue verb: "${rest[0]}" — use status <id>, wait <id>, result <id>, `
+        + 'or quote the prompt',
+    };
+  }
+  if (verbs.includes(rest[0])) {
+    if (rest.length !== 2) return { error: `rescue ${rest[0]} takes exactly one job id` };
+    return { verb: rest[0], id: rest[1] };
+  }
+  return { verb: 'submit', prompt: rest.join(' ') };
+}
+
+/** `queued` · `running (step 7)` · `done` · `stopped` · `interrupted` · `failed`. */
+function humanState(record) {
+  if (record.state === 'running') return `running (step ${record.steps})`;
+  return record.state;
+}
+
+/**
+ * The only place this program starts a detached job. `stdio` points at a log
+ * file under the rescue root rather than the parent's own streams — nobody is
+ * attached to read them live, and `ignore` would throw away the one clue left
+ * if the worker dies before it can write its own record (a bad argv, a
+ * missing entry point) — and `unref()` is what actually lets the submitting
+ * process exit while the child keeps running; without it Node holds the
+ * parent open waiting on a child it was just asked to walk away from.
+ */
+function spawnWorker(id) {
+  let stdio = 'ignore';
+  try {
+    mkdirSync(ROOT(), { recursive: true, mode: 0o700 });
+    const fd = openSync(join(ROOT(), `${id}.log`), 'a', 0o600);
+    stdio = ['ignore', fd, fd];
+  } catch { /* the job still runs; only the crash-before-first-write case loses its clue */ }
+  const child = spawn(process.execPath, [CLI, 'rescue', '--rescue-worker', id], {
+    detached: true, stdio, cwd: process.cwd(), env: process.env,
+  });
+  child.unref();
+}
+
+async function submitCmd(prompt, args) {
+  const role = args.role ?? 'explore';
+  if (!AGENTS[role]) {
+    console.error(`\n  unknown role "${role}" — use one of: ${Object.keys(AGENTS).join(', ')}\n`);
+    return 2;
+  }
+  if (!prompt.trim()) {
+    console.error('\n  rescue needs a prompt saying what to do and what to report back\n');
+    return 2;
+  }
+
+  // Resolved here, the same way as #84 (src/resolve.js against
+  // chatModels(await listModels())), not deferred to the worker: a caller
+  // that named a model that does not exist should hear about it now, on the
+  // process it is still attached to, rather than have the job quietly run on
+  // something else or sit `failed` for a `wait` to discover later.
+  let model = null;
+  if (args.model) {
+    let ids;
+    try { ids = await listModels(); }
+    catch (e) {
+      console.error(`\n  cannot reach Kronk at ${config.baseUrl}\n  ${e.message}\n`);
+      return 1;
+    }
+    model = resolveModel(args.model, chatModels(ids));
+    if (!model) {
+      console.error(`\n  no model matching "${args.model}"\n`);
+      return 1;
+    }
+  }
+
+  const job = createJob({
+    role, prompt, model,
+    yes: args.yes, auto: args.auto,
+    // `JSON.stringify(Infinity)` is `null`, so the "unlimited" a bare
+    // `--steps off` produces (src/argv.js) cannot ride through the record
+    // file as the number it is on the way in — it needs a shape that
+    // survives being written and read back as JSON.
+    maxSteps: args.steps === null ? null : (Number.isFinite(args.steps) ? args.steps : 'unlimited'),
+  });
+  spawnWorker(job.id);
+
+  if (args.json) console.log(JSON.stringify(toJson(job)));
+  else console.log(job.id);
+  return 0;
+}
+
+function statusCmd(id, args) {
+  const record = readJob(id);
+  if (!record) { console.error(`\n  no rescue job ${id}\n`); return 1; }
+  if (args.json) console.log(JSON.stringify(toJson(record)));
+  else console.log(humanState(record));
+  return 0;
+}
+
+async function waitCmd(id, args) {
+  let record = readJob(id);
+  if (!record) { console.error(`\n  no rescue job ${id}\n`); return 1; }
+  while (!TERMINAL.has(record.state)) {
+    await sleep(POLL_MS);
+    record = readJob(id);
+    if (!record) { console.error(`\n  rescue job ${id} vanished while waiting\n`); return 1; }
+  }
+  collect(id);
+  if (args.json) console.log(JSON.stringify(toJson(record)));
+  else console.log(record.report ?? '');
+  return EXIT_CODES[record.state] ?? 1;
+}
+
+/** Not one of `wait`'s four codes on purpose — this is "ask again", not a finished job's state. */
+const NOT_READY = 4;
+
+function resultCmd(id, args) {
+  const record = readJob(id);
+  if (!record) { console.error(`\n  no rescue job ${id}\n`); return 1; }
+  if (!TERMINAL.has(record.state)) {
+    console.error(`\n  rescue job ${id} is ${humanState(record)} — not finished yet; `
+      + `use \`kronk-cli rescue wait ${id}\`\n`);
+    return NOT_READY;
+  }
+  collect(id);
+  if (args.json) console.log(JSON.stringify(toJson(record)));
+  else console.log(record.report ?? '');
+  return EXIT_CODES[record.state] ?? 1;
+}
+
+/**
+ * Run one job to completion inside the detached worker process. Everything
+ * below is `oneShot` in src/index.js with the terminal taken away: no
+ * banner, no streamed output, no readline — the record file is the only
+ * audience.
+ *
+ * `approve` and `grant` are the whole enforcement of the ground rule that
+ * matters most here: nobody is at the prompt, so without `--yes` / `--auto`
+ * on the original submit, both refuse outright. A rescue job is not a way to
+ * get a command approved that nobody was ever asked about.
+ */
+export async function runWorker(id) {
+  const job = readJob(id);
+  if (!job) return;
+
+  for (;;) {
+    if (acquireLock(id)) break;
+    await sleep(POLL_MS);
+    if (!readJob(id)) return;   // collected-and-swept, or otherwise gone, while we waited
+  }
+
+  // A stale lock this job's own runner is recovering from, or a duplicate
+  // worker started by mistake, both look the same from here: the record is
+  // not `queued` any more. Either way there is nothing left for this process
+  // to do.
+  const fresh = readJob(id);
+  if (!fresh || fresh.state !== 'queued') { releaseLock(id); return; }
+
+  const ac = new AbortController();
+  let interrupted = false;
+  const onSignal = () => { interrupted = true; ac.abort(); };
+  process.once('SIGTERM', onSignal);
+  process.once('SIGINT', onSignal);
+
+  let steps = 0;
+  try {
+    const ids = await listModels();
+    const model = job.model ?? (ids.includes(DEFAULT_MODEL) ? DEFAULT_MODEL : pickDefault(ids));
+    config.model = model;
+    applyLimits(await modelLimits(model));
+    markRunning(id, { pid: process.pid, model });
+
+    const ctx = await projectContext(process.cwd());
+    config.projectPrimer = ctx.text;
+
+    const messages = [
+      { role: 'system', content: systemFor(job.role) },
+      { role: 'user', content: job.prompt },
+    ];
+
+    const approve = async () => job.yes || job.auto;
+    const grant = async () => ((job.yes || job.auto) ? 'yes' : 'no');
+
+    const done = await runTurn({
+      messages,
+      model,
+      signal: ac.signal,
+      approve,
+      grant,
+      mcp: null,
+      auto: job.auto,
+      tools: subagentTools(job.role),
+      maxSteps: job.maxSteps === 'unlimited' ? Infinity : (job.maxSteps ?? config.subagentSteps),
+      plan: false,
+      stream: false,
+      out: () => {},
+      quiet: true,
+      // One, not zero. `runTurn` adds `taskTools(depth)` on top of whatever
+      // tool list it is given, and at depth 0 that is the `task` tool — so a
+      // rescue job would be handed a tool the role it was submitted under does
+      // not list, and the issue's "the same tool lists" would quietly not be
+      // true. It would also let a detached job nobody is watching start
+      // further runs of its own, each able to pull a different model into a
+      // pool that holds one. Depth 1 is also simply what this is: a delegated
+      // run, with the caller one level up and outside the process.
+      depth: 1,
+      onStep: (msgs, n) => { steps = n; recordStep(id, msgs, n); },
+    });
+
+    const last = [...done].reverse().find((m) => m.role === 'assistant');
+    const text = String(last?.content ?? '').trim();
+    // `runTurn` returns the same way whether it finished or ran out of steps,
+    // so the note it pushes as the last assistant message is the only signal
+    // there is. Matched on its shape rather than on one exact sentence: it
+    // has two spellings already, one per depth, and a caller reading `stopped`
+    // needs that state to be right far more than this needs to be clever.
+    if (text.startsWith('(stopped:')) {
+      // Said in terms of the job the caller submitted. `runTurn`'s own wording
+      // is written for a sub-agent with someone at a terminal above it, which
+      // is not who is reading this.
+      const cap = job.maxSteps === 'unlimited' ? 'step cap' : `step cap of ${job.maxSteps ?? config.subagentSteps}`;
+      markStopped(id, { report: `error: the job reached its ${cap} before finishing`, steps });
+    } else {
+      markDone(id, { report: text || 'error: the job finished without reporting anything', steps });
+    }
+  } catch (e) {
+    if (interrupted) markInterrupted(id, { steps });
+    else markFailed(id, { error: e.message, steps });
+  } finally {
+    process.removeListener('SIGTERM', onSignal);
+    process.removeListener('SIGINT', onSignal);
+    releaseLock(id);
+  }
+}
+
+/** Dispatched from src/index.js's main() exactly where `setup` is. */
+export async function runRescue(args) {
+  sweep();
+
+  if (args.rescueWorker) { await runWorker(args.rescueWorker); return 0; }
+
+  const parsed = parseRescueCommand(args.words);
+  if (parsed.error) { console.error(`\n  ${parsed.error}\n`); return 2; }
+
+  if (parsed.verb === 'submit') return submitCmd(parsed.prompt, args);
+  if (parsed.verb === 'status') return statusCmd(parsed.id, args);
+  if (parsed.verb === 'wait') return waitCmd(parsed.id, args);
+  return resultCmd(parsed.id, args);
+}

package/src/rescueStore.js

@@ -0,0 +1,277 @@
+import {
+  mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { config } from './config.js';
+
+/**
+ * The record store behind `kronk-cli rescue` — one JSON file per job, plus a
+ * single lock file that stands in for the one resident copy of the model
+ * Kronk's pool holds. Nothing here spawns anything; that is `src/rescue.js`'s
+ * job, and the split is deliberate — the state machine and the file layout
+ * are exactly the part of this feature a test can drive without a process to
+ * spawn, and keeping child_process out of this file keeps that true.
+ *
+ * A rescue record has to outlive the process that wrote it in a way a
+ * sub-agent transcript (src/tasklog.js) never had to: the submitter prints an
+ * id and exits on purpose, so `cleanup()` removing *its* session directory,
+ * or `sweep()` aging a session out after 24h, would delete the very answer a
+ * caller was told to come back for. The fix is not a special case in those
+ * two functions — it's a directory neither of them has ever heard of.
+ * `ROOT()` here is never `src/tasklog.js`'s `ROOT()`, so this store's own
+ * lifetime rule (below) is the only one that ever applies to it.
+ */
+
+export const ROOT = () => config.rescueDir ?? join(tmpdir(), 'kronk-cli-rescue');
+const LOCK = () => join(ROOT(), 'lock.json');
+
+/**
+ * Exactly the shape `newId()` produces, and the only shape a job id may have.
+ *
+ * A job id arrives from outside — `rescue status <id>` takes whatever was
+ * typed — and it is used to build a path. Without this it is used to build
+ * *any* path: `rescue result ../../something --json` would read that file and
+ * print it, and `collect()` would then write the record back over it, both
+ * outside the store entirely. That is a local CLI reading files its own
+ * operator can already read, so the ceiling on it is low — but a path built
+ * from unvalidated input is worth closing on its own terms, and the honest
+ * answer to an id that cannot exist is the one the callers already handle:
+ * there is no such job.
+ */
+const ID = /^[0-9a-z]+-[0-9a-z]+-[0-9a-f]{6}$/;
+
+export const isJobId = (id) => typeof id === 'string' && ID.test(id);
+
+const file = (id) => {
+  if (!isJobId(id)) throw new Error(`not a job id: ${id}`);
+  return join(ROOT(), `${id}.json`);
+};
+
+/**
+ * Kept until collected, then aged out — the lifetime the issue asks for.
+ * Anything still uncollected stays no matter how old, because "uncollected"
+ * means the one caller who could read the answer has not yet asked for it;
+ * removing it on a clock the caller never agreed to would be losing a job
+ * nobody failed to explain to them, and quietly. Once `collect()` has stamped
+ * `collectedAt`, the same 24h window `src/tasklog.js` uses applies — chosen
+ * for the same reason: the record worth keeping is one from the last session
+ * or two, not an accumulating archive.
+ */
+const KEEP_MS = 24 * 60 * 60 * 1000;
+
+/** How the state machine may end. `queued` and `running` are the only other states. */
+export const TERMINAL = new Set(['done', 'stopped', 'interrupted', 'failed']);
+
+/** 0700 / 0600 throughout — a rescue prompt and its transcript are the same material src/tasklog.js guards. */
+function ensureDir() {
+  mkdirSync(ROOT(), { recursive: true, mode: 0o700 });
+}
+
+/** Never throw into the caller: a full disk must not take the job down with it. */
+function flush(record) {
+  try {
+    ensureDir();
+    writeFileSync(file(record.id), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  } catch { /* the record is a convenience for whoever collects it, not the work itself */ }
+  return record;
+}
+
+/**
+ * `<timestamp>-<pid>-<random>`, all base36/hex so it reads cleanly on a
+ * command line with no quoting. Timestamp and pid alone repeat within the
+ * same submitting process inside the same millisecond — unlikely, but a job
+ * id colliding with an existing file would silently overwrite someone else's
+ * record — so six hex digits of randomness closes that off for the cost of a
+ * few extra characters.
+ */
+export function newId() {
+  return `${Date.now().toString(36)}-${process.pid.toString(36)}-${randomBytes(3).toString('hex')}`;
+}
+
+/** A job as first written: queued, nothing run yet. */
+export function createJob({ role, prompt, model = null, yes = false, auto = false, maxSteps = null }) {
+  const id = newId();
+  return flush({
+    id, role, prompt, model,
+    yes: Boolean(yes), auto: Boolean(auto), maxSteps,
+    state: 'queued',
+    pid: null,
+    steps: 0,
+    startedAt: null,
+    endedAt: null,
+    report: null,
+    messages: [],
+    collectedAt: null,
+  });
+}
+
+/**
+ * One job in full, or null. An id that is not a job id at all, one no file was
+ * ever written for, and one already swept away all look the same from here —
+ * deliberately: every caller's answer to all three is "there is no such job".
+ */
+export function readJob(id) {
+  if (!isJobId(id)) return null;
+  try { return JSON.parse(readFileSync(file(id), 'utf8')); }
+  catch { return null; }
+}
+
+function updateJob(id, patch) {
+  const record = readJob(id);
+  if (!record) return null;
+  Object.assign(record, patch);
+  return flush(record);
+}
+
+/** Written as the job goes, same reasoning as `Run.step` in src/tasklog.js. */
+export const recordStep = (id, messages, steps) => updateJob(id, { messages, steps });
+
+export const markRunning = (id, { pid, model }) =>
+  updateJob(id, { state: 'running', pid, model, startedAt: new Date().toISOString() });
+
+function finish(id, state, extra) {
+  return updateJob(id, { state, endedAt: new Date().toISOString(), ...extra });
+}
+
+export const markDone = (id, { report, steps }) => finish(id, 'done', { report, steps });
+export const markStopped = (id, { report, steps }) => finish(id, 'stopped', { report, steps });
+export const markFailed = (id, { error, steps }) =>
+  finish(id, 'failed', { report: `error: ${error}`, steps });
+export const markInterrupted = (id, { steps } = {}) =>
+  finish(id, 'interrupted', {
+    report: 'error: the job was interrupted before it finished',
+    ...(steps === undefined ? {} : { steps }),
+  });
+
+/**
+ * The `--json` shape, and exactly it: `{ id, state, role, model, steps, ms,
+ * report, transcript }`. `ms` is measured live for a running job (there is no
+ * `endedAt` yet) so `status --json` on a job mid-run reports how long it has
+ * been going, not zero.
+ */
+export function toJson(record) {
+  const ms = record.startedAt
+    ? Date.parse(record.endedAt ?? new Date().toISOString()) - Date.parse(record.startedAt)
+    : 0;
+  return {
+    id: record.id,
+    state: record.state,
+    role: record.role,
+    model: record.model,
+    steps: record.steps,
+    ms,
+    report: record.report,
+    transcript: record.messages,
+  };
+}
+
+/**
+ * Stamp the moment a terminal job was actually read back by `wait` or
+ * `result` — never by `status`, which is a peek, not a collection. Idempotent:
+ * the first caller to ask starts the clock, and asking again does not reset
+ * it, so two scripts polling the same id do not keep a finished job alive
+ * forever between them.
+ */
+export function collect(id) {
+  const record = readJob(id);
+  if (!record) return null;
+  if (TERMINAL.has(record.state) && !record.collectedAt) {
+    return updateJob(id, { collectedAt: new Date().toISOString() });
+  }
+  return record;
+}
+
+/** Collected records older than `KEEP_MS`; everything else is left alone. */
+export function sweep() {
+  let names;
+  try { names = readdirSync(ROOT()); } catch { return 0; }
+  let removed = 0;
+  for (const f of names) {
+    if (!f.endsWith('.json') || f === 'lock.json') continue;
+    const full = join(ROOT(), f);
+    try {
+      const record = JSON.parse(readFileSync(full, 'utf8'));
+      if (!record.collectedAt) continue;
+      if (Date.now() - Date.parse(record.collectedAt) < KEEP_MS) continue;
+      rmSync(full, { force: true });
+      removed += 1;
+    } catch { /* a record this cannot parse is not one it should guess about */ }
+  }
+  return removed;
+}
+
+/** Whether `pid` is a live process this machine still knows about. */
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; } // exists, owned by someone else — do not steal it
+}
+
+function readLock() {
+  try { return JSON.parse(readFileSync(LOCK(), 'utf8')); }
+  catch { return null; }
+}
+
+/**
+ * Claim the single slot the pool allows — see src/subagent.js's module
+ * comment for why there is only one. A plain exclusive create (`wx`) is the
+ * whole mechanism for the race: two runners asking for the same path can only
+ * ever have one winner, with no window in which both believe they hold it.
+ *
+ * The failure this still has to survive is not the race, it's the crash. A
+ * runner that dies holding the lock — killed, OOM, the machine rebooting —
+ * leaves the file behind with nobody left to remove it, and every caller
+ * after that would otherwise queue forever behind a process that no longer
+ * exists. So a lock file whose pid is not running is not treated as held: the
+ * job it belonged to never reached a terminal state on its own and never
+ * will, so that is recorded — `interrupted`, not left at `running` forever —
+ * before the file is cleared and the next claimant gets a turn.
+ *
+ * A lock that cannot be *parsed* is the same case, and it has to be handled
+ * as one rather than retried. A process killed between creating the file and
+ * finishing the write leaves a zero-byte `lock.json`: there is no pid in it to
+ * ask about, so treating "unreadable" as "try again" is an unyielding busy
+ * loop — the exclusive create keeps failing because the file is still there,
+ * and nothing in the loop ever removes it. In a detached worker nobody is
+ * watching, that is one core at 100% for as long as the machine is up, with
+ * every job after it queued behind a holder that was never alive. Unreadable
+ * means stale, for the same reason a dead pid does: there is no holder to
+ * respect.
+ *
+ * And the loop is bounded regardless. Every branch below either returns or
+ * removes the file it just failed to create, so the bound should be
+ * unreachable — which is exactly why it is cheap to have, and why a bug here
+ * costs a delayed job rather than a pinned CPU.
+ */
+const LOCK_TRIES = 50;
+
+export function acquireLock(id) {
+  ensureDir();
+  for (let attempt = 0; attempt < LOCK_TRIES; attempt += 1) {
+    try {
+      writeFileSync(LOCK(), JSON.stringify({ pid: process.pid, id }), { flag: 'wx', mode: 0o600 });
+      return true;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+    }
+    const holder = readLock();
+    if (holder && isAlive(holder.pid)) return false;   // genuinely running someone else's job
+    if (holder && holder.id !== id) {
+      const stuck = readJob(holder.id);
+      if (stuck && !TERMINAL.has(stuck.state)) markInterrupted(holder.id, { steps: stuck.steps });
+    }
+    try { unlinkSync(LOCK()); } catch { /* someone else already cleared it */ }
+  }
+  // Contended past all patience: not held by us, so the caller waits and asks
+  // again rather than proceeding as though it had the slot.
+  return false;
+}
+
+/** Release the lock, but only the copy this process actually holds. */
+export function releaseLock(id) {
+  const holder = readLock();
+  if (holder && holder.pid === process.pid && holder.id === id) {
+    try { unlinkSync(LOCK()); } catch { /* already gone */ }
+  }
+}

package/src/resolve.js

@@ -0,0 +1,27 @@
+/**
+ * Resolve a wanted model id against the ids Kronk is actually serving.
+ *
+ * This exact three-step fallback — exact id wins, else the closest substring,
+ * preferring an /AGENT profile — used to be written out three times: the main
+ * model pick and the sub-agent model pick in src/index.js's boot(), and
+ * `/model` in the REPL. None of the three needed a copy of their own; they
+ * needed this. Now a fourth site has the same problem — a delegated task
+ * naming a model by a short id — and it calls this instead of becoming a
+ * fourth copy.
+ *
+ * Exact match wins outright: a caller who already typed the whole id gets
+ * exactly that id, never a substring guess. Among the substring matches, an
+ * /AGENT profile wins over the bare id, because Kronk holds each as a
+ * separate resident copy in the pool — picking the wrong one silently loads
+ * a second one.
+ *
+ * Returns null rather than throwing. Every caller already has its own way of
+ * saying "nothing matched" — a console warning that falls back to a default,
+ * or a tool result a small local model can act on — and none of them is this
+ * function's business.
+ */
+export function resolveModel(want, ids) {
+  if (!want || !Array.isArray(ids) || !ids.length) return null;
+  const subs = ids.filter((id) => id.includes(want));
+  return ids.find((id) => id === want) ?? subs.find((id) => id.endsWith('/AGENT')) ?? subs[0] ?? null;
+}

package/src/setup.js

@@ -207,8 +207,13 @@ export function findOnPath(name, env = process.env) {
  *
  * `stream: true` hands the child our terminal, which is what a 21 GB pull wants;
  * otherwise its output is captured (up to CAPTURE_CAP) for parsing.
+ *
+ * `timeoutMs`, when given, kills the child after that long and still resolves
+ * (never rejects) with whatever was captured — the version check this exists
+ * for runs at startup and must come back on its own regardless of what the
+ * binary does, not hang the thing that asked.
  */
-export function runKronk(argv, { stream = false } = {}) {
+export function runKronk(argv, { stream = false, timeoutMs } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn('kronk', argv, {
       stdio: ['ignore', stream ? 'inherit' : 'pipe', stream ? 'inherit' : 'pipe'],
@@ -217,8 +222,16 @@ export function runKronk(argv, { stream = false } = {}) {
     const take = (d) => { if (output.length < CAPTURE_CAP) output += d; };
     child.stdout?.setEncoding('utf8').on('data', take);
     child.stderr?.setEncoding('utf8').on('data', take);
-    child.on('error', reject);
-    child.on('close', (code) => resolve({ code: code ?? 1, output }));
+
+    let timer;
+    if (timeoutMs) {
+      timer = setTimeout(() => child.kill(), timeoutMs);
+      timer.unref?.();
+    }
+    const settle = (fn) => (arg) => { clearTimeout(timer); fn(arg); };
+
+    child.on('error', settle(reject));
+    child.on('close', settle((code) => resolve({ code: code ?? 1, output })));
   });
 }