pi-kanban 0.3.1 → 2.0.0

package/lib/ask.js

@@ -0,0 +1,252 @@
+// The ask modal's server side: one open question per terminal or per session, from the extension's ask
+// tool. The tool's call waits on it, long-polling /wait until the board answers, the user skips, or the
+// agent is interrupted. Nothing is written to disk: a question outlives neither the board nor its asker.
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const express = require('express');
+const { httpError } = require('./http-error');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ASK_PATH = '/api/terminals/:terminalId/ask';
+// A session outside the board's terminal asks here; the modal opens over that session's view.
+const SESSION_ASK_PATH = '/api/sessions/:sessionId/ask';
+// The answer of a playground card is its whole state.
+const BODY_LIMIT = '256kb';
+const MAX_LABEL = 200;
+const SIZES = ['md', 'lg', 'full'];
+// $.http.fetch gives up after 30 s, so a wait answers pending before that.
+const WAIT_MAX_MS = 25_000;
+// An answer that lands between two polls waits this long for the next one.
+const DONE_TTL_MS = 60_000;
+
+function parseAsk(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return 'body must be a JSON object';
+  const { sessionId, title, file, size = 'lg' } = body;
+  if (typeof sessionId !== 'string' || !UUID_RE.test(sessionId)) return 'invalid sessionId';
+  if (typeof title !== 'string' || !title.trim() || title.length > MAX_LABEL) {
+    return `title must be a non-empty string of at most ${MAX_LABEL} characters`;
+  }
+  if (typeof file !== 'string' || !path.isAbsolute(file)) return 'file must be an absolute path';
+  if (!SIZES.includes(size)) return `size must be one of ${SIZES.join(', ')}`;
+  return { sessionId, title, file, size };
+}
+
+// A string is a reason the body is refused.
+function parseAnswer(body) {
+  const { status, data } = body || {};
+  if (status === 'dismissed') return { status };
+  if (status !== 'answered') return 'status must be answered or dismissed';
+  if (data === undefined) return 'an answer needs data';
+  return { status, data };
+}
+
+/**
+ * @param {object} [o]
+ * @param {() => number} [o.now]
+ */
+function createAskStore(o = {}) {
+  const now = o.now || Date.now;
+  const open = new Map();
+  const done = new Map();
+  const waiters = new Map();
+
+  function sweep() {
+    const t = now();
+    for (const [id, d] of done) if (t - d.at > DONE_TTL_MS) done.delete(id);
+  }
+
+  function settle(ask, result) {
+    open.delete(ask.owner);
+    done.set(ask.id, { result, at: now() });
+    for (const w of waiters.get(ask.id) || []) w(result);
+    waiters.delete(ask.id);
+  }
+
+  // `owner` is the terminal id or the session id the question belongs to.
+  // A new question ends the open one, so the board never holds two.
+  function ask(owner, { sessionId, title, file, size }) {
+    sweep();
+    const old = open.get(owner);
+    if (old) settle(old, { status: 'dismissed', reason: 'replaced' });
+    const entry = { id: crypto.randomUUID(), owner, sessionId, title, file, size, at: now() };
+    open.set(owner, entry);
+    return { entry, replaced: old?.id ?? null };
+  }
+
+  function current(owner) {
+    return open.get(owner) || null;
+  }
+
+  function end(owner, askId, result) {
+    const entry = open.get(owner);
+    if (!entry || entry.id !== askId) return false;
+    settle(entry, result);
+    return true;
+  }
+
+  // Resolves the result once, or pending after `ms`; an unknown id is gone.
+  function wait(askId, ms) {
+    const d = done.get(askId);
+    if (d) {
+      done.delete(askId);
+      return Promise.resolve(d.result);
+    }
+    if (![...open.values()].some((a) => a.id === askId)) return Promise.resolve({ status: 'gone' });
+    return new Promise((resolve) => {
+      const list = waiters.get(askId) || [];
+      const finish = (result) => {
+        clearTimeout(timer);
+        done.delete(askId);
+        resolve(result);
+      };
+      const timer = setTimeout(() => {
+        const left = (waiters.get(askId) || []).filter((w) => w !== finish);
+        if (left.length) waiters.set(askId, left);
+        else waiters.delete(askId);
+        resolve({ status: 'pending' });
+      }, ms);
+      timer.unref?.();
+      list.push(finish);
+      waiters.set(askId, list);
+    });
+  }
+
+  function prune(keep, reason) {
+    for (const [owner, entry] of open) if (!keep(owner)) settle(entry, { status: 'dismissed', reason });
+  }
+
+  return { ask, current, end, wait, prune };
+}
+
+function askBodyParser() {
+  return express.json({ limit: BODY_LIMIT });
+}
+
+/**
+ * The routes of a question asked from the board's terminal.
+ * @param {object} o
+ * @param {(token: string|undefined) => boolean} o.authorized  the terminal token
+ * @param {(terminalId: string) => boolean} o.hasTerminal  a live terminal has this id
+ */
+function terminalAskRoutes(o) {
+  return {
+    path: ASK_PATH,
+    param: 'terminalId',
+    refuse(req, terminalId) {
+      if (!o.authorized(req.get('x-terminal-token'))) return [401, 'invalid terminal token'];
+      if (!o.hasTerminal(terminalId)) return [404, 'no live terminal with that id'];
+      return null;
+    },
+  };
+}
+
+// No token: the asker is a pi process on this machine with no terminal token, and net-guard
+// already refuses a cross-site request.
+const SESSION_ASK_ROUTES = {
+  path: SESSION_ASK_PATH,
+  param: 'sessionId',
+  refuse(req, sessionId) {
+    if (!UUID_RE.test(sessionId)) return [400, 'invalid sessionId'];
+    if (req.body?.sessionId !== undefined && req.body.sessionId !== sessionId) return [400, 'sessionId does not match the URL'];
+    return null;
+  },
+};
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} o
+ * @param {ReturnType<typeof createAskStore>} o.store
+ * @param {string} o.path  the route base, with the owner as the `o.param` param
+ * @param {string} o.param
+ * @param {(req: import('express').Request, owner: string) => [number, string]|null} o.refuse  the status and error that refuse a request
+ * @param {(absPath: string) => Promise<{content: string|null, kind: string|null}>} o.readPreviewFile
+ * @param {(event: object) => void} o.broadcast
+ */
+function mountAskRoutes(app, o) {
+  const { store, path: base, param } = o;
+  const scope = (owner) => ({ [param]: owner });
+
+  function guard(req, res) {
+    const refused = o.refuse(req, req.params[param]);
+    return refused && res.status(refused[0]).json({ error: refused[1] });
+  }
+
+  async function readCard(file) {
+    let read;
+    try {
+      read = await o.readPreviewFile(file);
+    } catch (e) {
+      if (e.status === 404) throw httpError(400, `file not found: ${file}`);
+      throw e;
+    }
+    if (read.kind !== 'html') throw httpError(400, 'file must be an HTML file');
+    return read.content;
+  }
+
+  const route = (fn) => (req, res) => fn(req, res).catch((e) => {
+    if (res.headersSent) return;
+    if (!e.status) console.error(`Error in ${req.method} ${req.path}:`, e);
+    res.status(e.status || 500).json({ error: e.status ? e.message : 'Internal error' });
+  });
+
+  const closed = (owner, id, status) => o.broadcast({ type: 'ask:closed', ...scope(owner), id, status });
+
+  app.post(base, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const p = parseAsk(req.body);
+    if (typeof p === 'string') return res.status(400).json({ error: p });
+    await readCard(p.file);
+    const owner = req.params[param];
+    const { entry, replaced } = store.ask(owner, p);
+    if (replaced) closed(owner, replaced, 'dismissed');
+    o.broadcast({ type: 'ask:opened', sessionId: entry.sessionId, ...scope(owner), id: entry.id });
+    res.json({ id: entry.id });
+  }));
+
+  app.get(base, route(async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const entry = store.current(req.params[param]);
+    if (!entry) return res.json({ ask: null });
+    const { id, title, size, file, sessionId } = entry;
+    let content = null;
+    try {
+      content = await readCard(file);
+    } catch (e) {
+      if (!e.status) throw e;
+    }
+    res.json({ ask: { id, title, size, file, sessionId, content } });
+  }));
+
+  app.get(`${base}/:askId/wait`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const ms = Math.min(Math.max(Number(req.query.ms) || WAIT_MAX_MS, 0), WAIT_MAX_MS);
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(await store.wait(req.params.askId, ms));
+  }));
+
+  // The board answers or skips.
+  app.post(`${base}/:askId`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const result = parseAnswer(req.body);
+    if (typeof result === 'string') return res.status(400).json({ error: result });
+    const { [param]: owner, askId } = req.params;
+    if (!store.end(owner, askId, result)) return res.status(404).json({ error: 'no such question' });
+    closed(owner, askId, result.status);
+    res.status(204).end();
+  }));
+
+  // The tool call was interrupted.
+  app.delete(`${base}/:askId`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const { [param]: owner, askId } = req.params;
+    if (!store.end(owner, askId, { status: 'cancelled' })) return res.status(404).json({ error: 'no such question' });
+    closed(owner, askId, 'cancelled');
+    res.status(204).end();
+  }));
+}
+
+module.exports = {
+  createAskStore, mountAskRoutes, terminalAskRoutes, askBodyParser, parseAsk, parseAnswer,
+  ASK_PATH, SESSION_ASK_PATH, SESSION_ASK_ROUTES, WAIT_MAX_MS,
+};

package/lib/atomic-write.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const fs = require('node:fs').promises;
+const path = require('node:path');
+
+let seq = 0;
+
+// The board reads these files while pi writes them, so it must never see half a file.
+// On Windows a rename over a file another handle has open fails with EPERM or EBUSY until it closes.
+async function writeJsonAtomic(file, data) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${++seq}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2));
+    for (let attempt = 1; ; attempt++) {
+      try {
+        await fs.rename(tmp, file);
+        return;
+      } catch (e) {
+        if (attempt >= 10 || (e.code !== 'EPERM' && e.code !== 'EBUSY')) throw e;
+        await new Promise((r) => setTimeout(r, attempt * 10));
+      }
+    }
+  } catch (e) {
+    await fs.rm(tmp, { force: true });
+    throw e;
+  }
+}
+
+module.exports = { writeJsonAtomic };

package/lib/board-dir.js

@@ -0,0 +1,63 @@
+const crypto = require('node:crypto');
+const os = require('node:os');
+const path = require('node:path');
+const { getAgentDir, longPath } = require('./agent-dir');
+
+const DEFAULT_PI_AGENT_DIR = longPath(path.join(os.homedir(), '.pi', 'agent'));
+
+// --name <value> | --name=<value>; null when absent.
+function getArgValue(name) {
+  const argv = process.argv;
+  const idx = argv.findIndex((arg) => arg === `--${name}` || arg.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = argv[idx];
+  if (arg.includes('=')) return arg.split('=').slice(1).join('=');
+  return argv[idx + 1] || null;
+}
+
+function expandHome(dir) {
+  return dir.replace(/^~/, os.homedir());
+}
+
+// --dir | PI_DIR/agent | PI_CODING_AGENT_DIR | ~/.pi/agent
+function resolvePiAgentDir() {
+  const dir = getArgValue('dir');
+  return dir ? longPath(expandHome(dir)) : getAgentDir();
+}
+
+function boardDir(dir) {
+  return path.join(dir, 'kanban');
+}
+
+function isDefaultPiAgentDir(dir) {
+  return longPath(dir) === DEFAULT_PI_AGENT_DIR;
+}
+
+// localStorage is per browser origin, so every config dir served from the same port would
+// otherwise share last view, collapsed groups and sidebar layout. The default dir keeps the
+// bare keys; any other dir gets a prefix derived from its resolved path.
+function storageNamespace(dir) {
+  if (isDefaultPiAgentDir(dir)) return null;
+  return `cfg-${crypto.createHash('sha1').update(path.resolve(dir)).digest('hex').slice(0, 8)}`;
+}
+
+// Home-relative, forward-slash form for messages and shell commands.
+function displayPath(p) {
+  const home = os.homedir();
+  const rel = p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+  return rel.split(path.sep).join('/');
+}
+
+// The harness spells a project path into a temp/log dir name by replacing every
+// non-alphanumeric character with a dash, drive colon and separators included.
+function encodeProjectDirName(p) {
+  return p.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+// pi puts no session id in the environment, so the extension sets this for the commands a session runs.
+const SESSION_ID_ENV = 'PI_KANBAN_SESSION_ID';
+
+// Both vars come from the board terminal's ptyEnv, so only a session started there has them.
+const boardTerminalId = () => (process.env.PK_URL && process.env.PK_TERMINAL_ID) || null;
+
+module.exports = { getArgValue, resolvePiAgentDir, boardDir,isDefaultPiAgentDir, displayPath, storageNamespace, encodeProjectDirName, SESSION_ID_ENV, boardTerminalId };

package/lib/claude-settings.js

@@ -0,0 +1,21 @@
+const fs = require('node:fs');
+
+const fileCache = new Map();
+
+// Parsed Claude Code settings file, or null when it is missing or invalid. Re-read only
+// after its mtime changes.
+function readSettings(file) {
+  const mtime = fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? null;
+  const hit = fileCache.get(file);
+  if (hit && hit.mtime === mtime) return hit.data;
+  let data = null;
+  if (mtime !== null) {
+    try {
+      data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {}
+  }
+  fileCache.set(file, { mtime, data });
+  return data;
+}
+
+module.exports = { readSettings };

package/lib/companion-host.js

@@ -0,0 +1,142 @@
+'use strict';
+
+// Runs the optional companion dashboards (pi-cost, pi-inspect) as children of the board, so a pane
+// can show them. The embed contract the tools follow: `node <bin> --port <n> --host 127.0.0.1
+// --no-open` with PI_CODING_AGENT_DIR set, an explicit port binds exactly (taken: exit 1), and
+// GET /api/companion answers {name, version, session}, where session is a path with {id}.
+
+const fs = require('node:fs');
+const net = require('node:net');
+const path = require('node:path');
+const readline = require('node:readline');
+const { spawn: nodeSpawn } = require('node:child_process');
+const { writeJsonAtomic } = require('./atomic-write');
+const { isPidAlive: pidAlive } = require('./live-sessions');
+const { readSettings } = require('./claude-settings');
+const { companionStatus } = require('./companions');
+
+const START_TIMEOUT_MS = 15000;
+const PROBE_TIMEOUT_MS = 1500;
+const POLL_MS = 100;
+
+function binPath(dir) {
+  const pkg = readSettings(path.join(dir, 'package.json'));
+  const bin = typeof pkg?.bin === 'string' ? pkg.bin : (pkg?.bin?.[pkg.name] ?? Object.values(pkg?.bin || {})[0]);
+  return typeof bin === 'string' ? path.join(dir, bin) : null;
+}
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer().once('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// The record in <dir>/<id>.json keeps the last port, so a pane URL saved before a board restart
+// still works, and the pid, so a board that ended without stopping its child (kill -9) can adopt it.
+// Only global packages run: one child serves the sessions of every project, so no project's
+// .pi/settings.json picks it.
+function createCompanionHost({ agentDir, dir, spawn = nodeSpawn, isPidAlive = pidAlive, log = console, startTimeoutMs = START_TIMEOUT_MS }) {
+  const running = new Map();
+  const starting = new Map();
+  const ownedPids = new Set();
+  const recordFile = (id) => path.join(dir, `${id}.json`);
+
+  async function probe(c, port) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/companion`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      const info = res.ok ? await res.json() : null;
+      return info?.name === c.pkg ? info : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function pipeLog(c, child) {
+    for (const stream of [child.stdout, child.stderr]) {
+      if (stream) readline.createInterface({ input: stream }).on('line', (line) => log.log(`[${c.id}] ${line}`));
+    }
+  }
+
+  async function ready(c, child, port) {
+    const end = Date.now() + startTimeoutMs;
+    while (child.exitCode === null && child.signalCode === null && Date.now() < end) {
+      const info = await probe(c, port);
+      if (info) return info;
+      await wait(POLL_MS);
+    }
+    return null;
+  }
+
+  async function launch(c, preferredPort) {
+    const bin = c.dir && binPath(c.dir);
+    if (!bin || !fs.existsSync(bin)) return { error: `${c.pkg} is not in the global pi packages`, status: 404 };
+    for (const want of [preferredPort, 0]) {
+      const port = want || await freePort();
+      const child = spawn(process.execPath, [bin, '--port', String(port), '--host', '127.0.0.1', '--no-open'], {
+        cwd: c.dir,
+        env: { ...process.env, PI_CODING_AGENT_DIR: agentDir },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      ownedPids.add(child.pid);
+      child.once('exit', (code, signal) => {
+        ownedPids.delete(child.pid);
+        if (running.get(c.id)?.pid === child.pid) running.delete(c.id);
+        log.log(`[${c.id}] exited (${signal || code})`);
+      });
+      child.once('error', (e) => log.error(`[${c.id}] ${e.message}`));
+      pipeLog(c, child);
+      const info = await ready(c, child, port);
+      if (info) {
+        const entry = { pid: child.pid, port, session: info.session };
+        running.set(c.id, entry);
+        await writeJsonAtomic(recordFile(c.id), { pid: child.pid, port, boardPid: process.pid });
+        return entry;
+      }
+      child.kill();
+    }
+    return { error: `${c.pkg} did not start`, status: 502 };
+  }
+
+  async function open(c) {
+    const rec = readSettings(recordFile(c.id));
+    const info = rec?.port ? await probe(c, rec.port) : null;
+    if (!info) return launch(c, rec?.port);
+    // Another live board on this agent dir shares the child and stops it itself.
+    if (rec.boardPid === process.pid || !isPidAlive(rec.boardPid)) {
+      ownedPids.add(rec.pid);
+      await writeJsonAtomic(recordFile(c.id), { ...rec, boardPid: process.pid });
+    }
+    const entry = { pid: rec.pid, port: rec.port, session: info.session };
+    running.set(c.id, entry);
+    return entry;
+  }
+
+  async function start(id) {
+    const c = companionStatus({ agentDir }).find((r) => r.id === id && r.optional);
+    if (!c) return { error: 'unknown companion', status: 404 };
+    const live = running.get(id);
+    if (live && isPidAlive(live.pid)) return live;
+    if (!starting.has(id)) starting.set(id, open(c).finally(() => starting.delete(id)));
+    return starting.get(id);
+  }
+
+  const url = (entry, sessionId) => `http://127.0.0.1:${entry.port}${sessionId ? entry.session.replace('{id}', encodeURIComponent(sessionId)) : '/'}`;
+
+  // Sync, for process 'exit'. The child is node itself, not a shell, so killing its pid ends the tool.
+  function stop() {
+    for (const pid of ownedPids) try { process.kill(pid); } catch { /* already gone */ }
+    ownedPids.clear();
+    running.clear();
+  }
+
+  return { start, url, stop };
+}
+
+module.exports = { createCompanionHost };

package/lib/companions.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// The pi packages the board's features read from. pi loads a package listed under "packages" in
+// <agentDir>/settings.json (global) or <cwd>/.pi/settings.json (project); see pi's docs/packages.md.
+
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { readSettings } = require('./claude-settings');
+
+const COMPANIONS = [
+  { id: 'pi-kanban', pkg: 'pi-kanban', feature: 'Board skills: show, ask, panes, dispatch' },
+  { id: 'pi-subagents', pkg: 'pi-subagents', feature: 'Subagents' },
+  { id: 'rpiv-todo', pkg: '@juicesharp/rpiv-todo', feature: 'Todos' },
+  { id: 'pi-cost', pkg: 'pi-cost', feature: 'Cost pane', optional: true, verb: 'cost', shows: 'cost, tokens and models' },
+  { id: 'pi-inspect', pkg: 'pi-inspect', feature: 'Inspect pane', optional: true, verb: 'inspect', shows: 'the system prompt, tools, extensions, skills and context pi loaded' },
+].map((c) => ({ ...c, source: `npm:${c.pkg}` }));
+
+// The companions that open as a session pane, by their verb in `pi-kanban session` and `/kanban`.
+const PANE_COMPANIONS = COMPANIONS.filter((c) => c.verb);
+
+const LATEST_TTL_MS = 6 * 60 * 60 * 1000;
+const NPM_VIEW_TIMEOUT_MS = 30000;
+const GIT_SOURCE = /^(git:|https?:\/\/|ssh:\/\/|git@)/;
+
+// Mirrors pi's resolvePathFromBase (utils/paths.js normalizePath): trim, expand a leading ~, resolve.
+function localDir(source, baseDir) {
+  const s = source.trim();
+  const home = process.env.HOME || os.homedir();
+  if (s === '~') return home;
+  if (s.startsWith('~/') || (process.platform === 'win32' && s.startsWith('~\\'))) return path.join(home, s.slice(2));
+  return path.resolve(baseDir, s);
+}
+
+// npm and git sources carry the name; a local path names the package in its package.json.
+function packageName(source, baseDir) {
+  if (source.startsWith('npm:')) return source.slice(4).replace(/(.)@.*$/, '$1');
+  if (GIT_SOURCE.test(source)) {
+    return path.posix.basename(source.replace(/@[^/@]*$/, '').replace(/\.git$/, '').replace(/\/+$/, ''));
+  }
+  const dir = localDir(source, baseDir);
+  return readSettings(path.join(dir, 'package.json'))?.name || path.basename(dir);
+}
+
+function settingsPackages(file) {
+  const list = readSettings(file)?.packages;
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((p) => (typeof p === 'string' ? p : p?.source))
+    .filter((s) => typeof s === 'string' && s)
+    .map((source) => ({ source, base: path.dirname(file), name: packageName(source, path.dirname(file)) }));
+}
+
+// pi reads a local path in place. A git clone has no fixed folder the board can name.
+function packageFolder(at, pkg) {
+  if (at.source.startsWith('npm:')) return path.join(at.npmRoot, 'node_modules', pkg);
+  return GIT_SOURCE.test(at.source) ? null : localDir(at.source, at.base);
+}
+
+const installedVersion = (dir) => readSettings(path.join(dir, 'package.json'))?.version || null;
+
+function newerVersion(a, b) {
+  const parts = (v) => v.split(/[.+-]/).slice(0, 3).map(Number);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+}
+
+const latestVersions = new Map();
+
+// pi installs npm packages under <agentDir>/npm (global) or <cwd>/.pi/npm (project), and checks
+// an unpinned one for updates with `npm view <name> version` (DefaultPackageManager.checkForAvailableUpdates).
+function companionStatus({ agentDir, cwd }) {
+  const project = typeof cwd === 'string' && path.isAbsolute(cwd);
+  const packages = [
+    ...settingsPackages(path.join(agentDir, 'settings.json')).map((p) => ({ ...p, scope: 'global', npmRoot: path.join(agentDir, 'npm') })),
+    ...(project ? settingsPackages(path.join(cwd, '.pi', 'settings.json')).map((p) => ({ ...p, scope: 'project', npmRoot: path.join(cwd, '.pi', 'npm') })) : []),
+  ];
+  return COMPANIONS.map((c) => {
+    const at = packages.find((p) => p.name === c.pkg);
+    if (!at) return { ...c, scope: null, dir: null, version: null, latest: null, update: false };
+    const npm = at.source.startsWith('npm:');
+    const tracked = npm && !at.source.slice(4).includes('@', 1);
+    const dir = packageFolder(at, c.pkg);
+    const version = npm ? installedVersion(dir) : null;
+    const latest = (tracked && latestVersions.get(c.pkg)?.version) || null;
+    return { ...c, scope: at.scope, dir, version, latest, update: !!(version && latest && newerVersion(latest, version)), tracked };
+  });
+}
+
+// A missing package installs globally; an installed one updates where it is listed, and a project
+// package updates from its project's folder, where pi reads .pi/settings.json.
+function installPlan(id, { agentDir, cwd }) {
+  const c = companionStatus({ agentDir, cwd }).find((r) => r.id === id);
+  if (!c) return null;
+  return { piArgs: [c.scope ? 'update' : 'install', c.source], cwd: c.scope === 'project' ? cwd : null };
+}
+
+function offline() {
+  const v = process.env.PI_OFFLINE?.toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+function npmView(npmCommand, pkg) {
+  const [cmd, ...args] = Array.isArray(npmCommand) && npmCommand[0] ? npmCommand : ['npm'];
+  return new Promise((resolve) => {
+    // npm is npm.cmd on Windows, and Node runs a .cmd only through a shell. pkg is one of COMPANIONS.
+    execFile(cmd, [...args, 'view', pkg, 'version', '--json'], { timeout: NPM_VIEW_TIMEOUT_MS, shell: process.platform === 'win32', windowsHide: true }, (err, stdout) => {
+      try {
+        const v = err ? null : JSON.parse(stdout);
+        resolve(typeof v === 'string' ? v : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+
+// One npm call per package every LATEST_TTL_MS, run off the request. Resolves true when a latest
+// version changed, so the caller can tell the board.
+async function refreshLatest(rows, { agentDir, view = npmView, now = Date.now() }) {
+  if (offline()) return false;
+  const stale = rows.filter((r) => r.tracked && r.version && !(now - (latestVersions.get(r.pkg)?.at ?? -Infinity) < LATEST_TTL_MS));
+  if (!stale.length) return false;
+  for (const r of stale) latestVersions.set(r.pkg, { version: latestVersions.get(r.pkg)?.version ?? null, at: now });
+  const npmCommand = readSettings(path.join(agentDir, 'settings.json'))?.npmCommand;
+  const found = await Promise.all(stale.map(async (r) => {
+    const version = await view(npmCommand, r.pkg);
+    const before = latestVersions.get(r.pkg).version;
+    latestVersions.set(r.pkg, { version, at: now });
+    return version !== before;
+  }));
+  return found.some(Boolean);
+}
+
+module.exports = { COMPANIONS, PANE_COMPANIONS, companionStatus, installPlan, refreshLatest, packageName, newerVersion };