@commonlyai/cli 0.1.78 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/inbox.js

@@ -0,0 +1,275 @@
+/**
+ * commonly inbox <subcommand>
+ *
+ * list   — read ONE account's own attention queue, newest first, optionally only what is new
+ * ack    — acknowledge an item (takes the item's `attentionItemId`)
+ * choose — rule a decision card (takes the item's SOURCE id, i.e. the decision id)
+ *
+ * The account comes from `--token-file <path>` (or COMMONLY_TOKEN_FILE) and from
+ * nowhere else — see the header of ../lib/inbox.js for why that is a rule and
+ * not a preference. Every run prints the resolved account on its first line.
+ */
+
+import { resolveInstanceUrl } from '../lib/config.js';
+import {
+  InboxRefusal,
+  createInboxRequest,
+  countsLine,
+  fetchQueue,
+  filterItems,
+  formatAccountLine,
+  formatItemLine,
+  nextCursorFrom,
+  parseCursor,
+  readCursorFile,
+  readInboxToken,
+  resolveAccountLabel,
+  resolveTokenFilePath,
+  writeCursorFile,
+  INBOX_KINDS,
+  TOKEN_FILE_ENV,
+} from '../lib/inbox.js';
+
+export const INBOX_TOKEN_HELP = `Account token file (or ${TOKEN_FILE_ENV})`;
+
+const normalizeKind = (value) => {
+  if (value === undefined || value === null || value === '') return null;
+  const kind = String(value).trim().toLowerCase();
+  if (!INBOX_KINDS.includes(kind)) {
+    throw new InboxRefusal(`Unknown --kind ${value}. One of: ${INBOX_KINDS.join(', ')}.`);
+  }
+  return kind;
+};
+
+/**
+ * Resolve identity and build the request layer. Deliberately the only path to a
+ * request: every subcommand goes through it, so no subcommand can grow its own
+ * fallback to the saved login.
+ */
+const connect = async (opts, { env, fetchImpl, sleep }) => {
+  const tokenFile = resolveTokenFilePath(opts, env);
+  if (!tokenFile) {
+    throw new InboxRefusal(
+      `no token file. Pass --token-file <path> or set ${TOKEN_FILE_ENV}.\n`
+      + 'This command reads ONE account\'s own queue; it never falls back to the saved login, because on a\n'
+      + 'shared operator host that login belongs to someone else (Sam\'s queue is the wrong queue, silently).',
+    );
+  }
+  const token = readInboxToken(tokenFile);
+  const baseUrl = resolveInstanceUrl(opts.instance);
+  const request = createInboxRequest({
+    baseUrl, token, tokenFile, fetchImpl, sleep,
+  });
+  const user = await request('/api/auth/user');
+  return {
+    tokenFile, baseUrl, request, user, account: resolveAccountLabel(user),
+  };
+};
+
+const reportRefusal = (err, error) => {
+  error(`refusing: ${err.message}`);
+  return 1;
+};
+
+const reportFailure = (err, error) => {
+  error(`Failed: ${err.message}`);
+  return 1;
+};
+
+export const runInboxList = async (opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error, sleep = undefined,
+  } = deps;
+  try {
+    // Validated before the request: a typo in --kind must not cost a network
+    // round trip, and must not read a queue the caller did not ask for.
+    const kind = normalizeKind(opts.kind);
+    // Read and check the cursor BEFORE connecting: this is a local-file fact, and
+    // a misuse of the flags must not cost even the identity request that
+    // resolves the account.
+    const sinceRaw = opts.since !== undefined ? opts.since : readCursorFile(opts.cursorFile);
+    const cursorIn = parseCursor(sinceRaw);
+    // A resume cursor is valid only for the query that wrote it. Reading a
+    // kind-scoped cursor with a different filter — including no filter at all —
+    // would advance past items of other kinds that the earlier read never
+    // printed, and no later read could reach them. Only this direction is
+    // refused: a BROAD cursor read by a narrower query loses nothing, because
+    // that earlier read printed every kind.
+    if (cursorIn?.kind && cursorIn.kind !== kind) {
+      throw new InboxRefusal(
+        `the cursor file was written by a read with --kind ${cursorIn.kind}, and this read is `
+        + `${kind ? `--kind ${kind}` : 'not filtered by kind'}. A cursor records how far THAT query got, so this `
+        + `read would skip items of other kinds that one never printed. Keep one cursor file per kind, e.g. `
+        + `--kind ${cursorIn.kind} --cursor-file <path>.${cursorIn.kind}.`,
+      );
+    }
+    const sinceMs = cursorIn ? cursorIn.ms : null;
+    const since = cursorIn ? cursorIn.at : null;
+
+    const {
+      baseUrl, request, account,
+    } = await connect(opts, { env, fetchImpl, sleep });
+
+    const { items, meta } = await fetchQueue(request, { podId: opts.pod });
+    const selected = filterItems(items, {
+      kind,
+      sinceMs,
+      // The ids already delivered at the cursor's own millisecond. An item that
+      // shares that millisecond but is not among them arrived after the cursor
+      // was written, and is exactly the row a bare `ms > since` loses.
+      seenIds: cursorIn ? cursorIn.ids : [],
+    });
+    const cursor = nextCursorFrom(selected, cursorIn, kind);
+
+    if (opts.json) {
+      log(JSON.stringify({
+        account,
+        instance: baseUrl,
+        count: selected.length,
+        // The bare timestamp: a caller feeding this back through --since loses
+        // the boundary ids, which degrades to re-printing that millisecond
+        // rather than to skipping it.
+        cursor: cursor ? cursor.at : null,
+        countsByKind: meta?.countsByKind || {},
+        items: selected,
+      }, null, 2));
+    } else {
+      log(formatAccountLine({ account, baseUrl }));
+      const counts = countsLine(meta?.countsByKind);
+      log(`open: ${Number.isInteger(meta?.count) ? meta.count : items.length}${counts ? ` (${counts})` : ''}`);
+      if (selected.length === 0) {
+        log(since ? `(no items newer than ${since})` : '(queue is empty)');
+      }
+      for (const item of selected) log(formatItemLine(item));
+      log(`cursor: ${cursor ? cursor.at : ''}`);
+    }
+    writeCursorFile(opts.cursorFile, cursor);
+    return 0;
+  } catch (err) {
+    if (err instanceof InboxRefusal) return reportRefusal(err, error);
+    return reportFailure(err, error);
+  }
+};
+
+export const runInboxAck = async (itemId, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error, sleep = undefined,
+  } = deps;
+  try {
+    if (!itemId) throw new InboxRefusal('an item id is required: commonly inbox ack <attentionItemId>');
+    const {
+      baseUrl, request, account,
+    } = await connect(opts, { env, fetchImpl, sleep });
+    log(formatAccountLine({ account, baseUrl }));
+    const result = await request(`/api/activity/${encodeURIComponent(itemId)}/acknowledge`, {
+      method: 'POST',
+      body: {},
+    });
+    log(`acked ${itemId}${result?.success === false ? ` — server said: ${result.error || 'not acknowledged'}` : ''}`);
+    return 0;
+  } catch (err) {
+    if (err instanceof InboxRefusal) return reportRefusal(err, error);
+    if (err?.status === 400) {
+      error(`Failed: ${err.message}`);
+      error('Acknowledge takes the item\'s attentionItemId — the id printed as `item=…` by `commonly inbox list`'
+        + ' (the unlabelled source id is what `commonly inbox choose` takes).');
+      return 1;
+    }
+    return reportFailure(err, error);
+  }
+};
+
+export const runInboxChoose = async (decisionId, value, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error, sleep = undefined,
+  } = deps;
+  try {
+    if (!decisionId) throw new InboxRefusal('a decision id is required: commonly inbox choose <decisionId> <value>');
+    if (value === undefined) throw new InboxRefusal('a value is required: commonly inbox choose <decisionId> <value>');
+    const {
+      baseUrl, request, account,
+    } = await connect(opts, { env, fetchImpl, sleep });
+    log(formatAccountLine({ account, baseUrl }));
+    const result = await request(`/api/activity/decisions/${encodeURIComponent(decisionId)}/choose`, {
+      method: 'POST',
+      body: { value },
+    });
+    log(`chose ${decisionId} = ${value}`);
+    log(`-> ${JSON.stringify(result)}`);
+    return 0;
+  } catch (err) {
+    if (err instanceof InboxRefusal) return reportRefusal(err, error);
+    return reportFailure(err, error);
+  }
+};
+
+export const registerInbox = (program) => {
+  const inbox = program
+    .command('inbox')
+    .description("Read and act on ONE account's own attention queue");
+
+  inbox.addHelpText('after', `
+The account is read from a token file and from nowhere else:
+
+  $ commonly inbox list --token-file ~/.commonly/bin/connector-ops-token
+  $ COMMONLY_TOKEN_FILE=~/.commonly/bin/lily-token commonly inbox list
+
+There is no fallback to the saved login. On a host where \`commonly login\` was
+run once as somebody else, a fallback would print that person's queue while the
+operator believed they were reading their own. Every run therefore names the
+account it resolved on its first line.
+
+With neither --token-file nor COMMONLY_TOKEN_FILE set, the command refuses
+before it makes a request.
+
+Examples:
+  $ commonly inbox list --json | jq '.items[].title'
+  $ commonly inbox list --kind decision --pod <podId>
+  $ commonly inbox list --cursor-file ~/.commonly/inbox/connector-ops.cursor   # only what is new
+  $ commonly inbox ack <attentionItemId>
+  $ commonly inbox choose <decisionId> 2
+
+Cost: \`list\` reads the WHOLE queue, one request per 50 items — 550 open
+items is 11 requests — and /api/activity is limited to 60 a minute **keyed on
+the caller's IP**, so every session on one host (and the operator's browser)
+shares that budget. A 429 is backed off and retried twice on the server's own
+\`Retry-After\`, then reported. A cursor narrows what is PRINTED, not what is
+read: the route has no created-since filter yet, so \`--pod\` is the one scope
+that narrows the request itself.
+
+\`ack\` deliberately ships WITHOUT an \`--all\`: a burst of acks shares that same
+per-IP budget, so a paced loop is the caller's decision and a bulk
+\`ids[]\`-accepting route (one request) is the kernel-side answer.
+
+Ids: \`list\` prints both ids an item has. \`ack\` takes \`item=…\`
+(attentionItemId); \`choose\` takes the item's source id, which for a decision is
+the decision id. Agent runtime tokens (cm_agent_…) are out of scope — they get
+their attention as runtime events, not from this queue.
+`);
+
+  inbox
+    .command('list')
+    .description("List the account's open attention queue, newest first")
+    .option('--token-file <path>', INBOX_TOKEN_HELP)
+    .option('--since <cursor>', 'ISO-8601 timestamp; only items created after it')
+    .option('--cursor-file <path>', 'Read the cursor from this file and write the advanced cursor back')
+    .option('--kind <kind>', `Only this kind: ${INBOX_KINDS.join('|')}`)
+    .option('--pod <podId>', 'Only this pod')
+    .option('--json', 'Emit one JSON object (with the resolved account and the cursor)')
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (opts) => { process.exit(await runInboxList(opts)); });
+
+  inbox
+    .command('ack <itemId>')
+    .description('Acknowledge an attention item (the item= id from `list`)')
+    .option('--token-file <path>', INBOX_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (itemId, opts) => { process.exit(await runInboxAck(itemId, opts)); });
+
+  inbox
+    .command('choose <decisionId> <value>')
+    .description('Rule a decision card (the source= id from `list`)')
+    .option('--token-file <path>', INBOX_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (decisionId, value, opts) => { process.exit(await runInboxChoose(decisionId, value, opts)); });
+};

package/src/index.js

@@ -15,6 +15,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 import { registerLogin, registerWhoami } from './commands/login.js';
+import { registerInbox } from './commands/inbox.js';
 import { registerAgent } from './commands/agent.js';
 import { registerDaemon } from './commands/daemon.js';
 import { registerPod } from './commands/pod.js';
@@ -35,6 +36,10 @@ program
 registerLogin(program);
 registerWhoami(program);
 
+// An operator account's own attention queue (explicit token file, never the
+// saved login — see cli/src/lib/inbox.js)
+registerInbox(program);
+
 // Agent management
 registerAgent(program);
 
@@ -59,6 +64,7 @@ Quick start:
   $ commonly agent detach my-claude                    # clean uninstall
   $ commonly daemon register --name "My MacBook"
   $ commonly daemon status
+  $ commonly inbox list --token-file ~/.commonly/bin/ops-token   # an operator's own queue
 
 Custom Python agent:
   $ commonly agent init --language python --name research-bot --pod <podId>

package/src/lib/inbox.js

@@ -0,0 +1,398 @@
+/**
+ * Operator inbox — ONE account's attention queue, chosen explicitly.
+ *
+ * Why this exists: an operator account (connector-ops, lily-shen, gtm-ops) is a
+ * human-class recipient, so the kernel already materializes AttentionItems for
+ * it — mentions via `recordMentionedUsers`, decisions and handoffs via the
+ * `currentHumanMembers` fan-out. What was missing was a consumer. The queue is
+ * real: 576 open items for connector-ops on 2026-09-28, none of them ever read.
+ *
+ * THE IDENTITY RULE IS THE POINT OF THIS MODULE, not a detail in it. Every host
+ * helper built on the CLI's saved login read SAM's queue, because the saved
+ * login on a shared operator host is Sam's. So this command refuses to run
+ * without an explicit token file (`--token-file`, or `COMMONLY_TOKEN_FILE`) and
+ * never consults the saved login or `COMMONLY_TOKEN`. A reader can therefore
+ * trust the first line of every run: it names whose queue was read, resolved
+ * from `GET /api/auth/user` with that token.
+ *
+ * Two ids exist on a queue item and different commands consume them:
+ *   `attentionItemId` — what `POST /api/activity/:id/acknowledge` wants
+ *                       (`attentionItemService.acknowledgeAttention` matches
+ *                       `_id` and refuses a non-24-hex value)
+ *   `id`              — the SOURCE row: for a decision that is the decision id
+ *                       that `POST /api/activity/decisions/:id/choose` wants
+ * `list` prints both, labelled, so neither command has to be discovered by
+ * failing first.
+ *
+ * The cursor is a TIMESTAMP PLUS the ids delivered at exactly that timestamp,
+ * compared against `createdAt` — the only field on an item that never moves. The
+ * queue's ORDER moves as items are acknowledged (priority, then newest first),
+ * so an offset cursor would skip rows; `createdAt` cannot.
+ *
+ * The ids are not decoration. A bare `ms > since` cursor loses any row that
+ * shares its millisecond with the cursor and was inserted after the cursor was
+ * written: the next run compares `ms > since` (false), nothing prints it, and no
+ * later run can see it either, because the cursor never moves. That row is gone
+ * silently and forever — the one failure this queue (576 open items, none ever
+ * read) cannot afford. So the cursor carries the ids it already delivered at its
+ * own millisecond and re-prints only the ones it did not: `ms > sinceMs ||
+ * (ms === sinceMs && !delivered.has(id))`. A legacy plain-timestamp cursor parses
+ * with an EMPTY set, which degrades toward re-printing rather than skipping.
+ *
+ * THE GENERAL RULE, which both cursor bugs above are instances of: a resume
+ * cursor is valid only for the query that wrote it. `--kind` is a DIFFERENT
+ * query over a subset of the same queue, so a kind-filtered read advances the
+ * high-water mark past items of every other kind — items that read never printed,
+ * and that no later read can reach, because the mark has already moved beyond
+ * them. A cursor file therefore records the kind filter (`kind` in the JSON) and
+ * a read whose filter differs from the recorded one refuses before it makes a
+ * request, rather than silently skipping. One cursor file per kind is the
+ * remedy, and the message names it.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+
+export const INBOX_KINDS = ['mention', 'decision', 'handoff', 'approval'];
+export const TOKEN_FILE_ENV = 'COMMONLY_TOKEN_FILE';
+export const API_PAGE_LIMIT = 50;
+
+const TOKEN_FIELDS = ['token', 'runtimeToken', 'accessToken', 'access_token'];
+const DETAIL_CHARS = 160;
+
+/** A refusal the operator can fix by re-reading the message. Never a server fault. */
+export class InboxRefusal extends Error {}
+
+/** A server-side failure. `status` is the HTTP status. */
+export class InboxRequestError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'InboxRequestError';
+    this.status = status;
+  }
+}
+
+export const resolveTokenFilePath = (opts = {}, env = process.env) => {
+  const flag = typeof opts.tokenFile === 'string' ? opts.tokenFile.trim() : '';
+  if (flag) return flag;
+  const fromEnv = typeof env?.[TOKEN_FILE_ENV] === 'string' ? env[TOKEN_FILE_ENV].trim() : '';
+  return fromEnv || null;
+};
+
+/**
+ * Pull a token out of a file body. A raw token is the documented shape (that is
+ * what `~/.commonly/bin/<account>-token` holds today); JSON is tolerated because
+ * the CLI's own token files are JSON, and a caller that reaches for one should
+ * get a named answer rather than a confusing 401.
+ */
+export const extractToken = (raw) => {
+  const text = String(raw ?? '').trim();
+  if (!text) return null;
+  if (text.startsWith('{')) {
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return null;
+    }
+    for (const field of TOKEN_FIELDS) {
+      const value = parsed?.[field];
+      if (typeof value === 'string' && value.trim()) return value.trim();
+    }
+    return null;
+  }
+  return text.replace(/^Bearer\s+/i, '').trim() || null;
+};
+
+/**
+ * Read the operator's token. Every failure here is a refusal with the PATH in
+ * it — never the token, and never a hint to run `commonly login`, which would
+ * point the account back at the saved login this command exists to avoid.
+ */
+export const readInboxToken = (filePath) => {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new InboxRefusal(
+      `Cannot read the token file ${filePath} (${err?.code || err?.message}).`,
+    );
+  }
+  const token = extractToken(raw);
+  if (!token) {
+    throw new InboxRefusal(
+      `No token in ${filePath}. Expected a raw token, or JSON carrying one of: ${TOKEN_FIELDS.join(', ')}.`,
+    );
+  }
+  if (token.startsWith('cm_agent_')) {
+    throw new InboxRefusal(
+      `${filePath} holds an AGENT runtime token (cm_agent_…). This command reads a HUMAN account's own queue; `
+      + 'agent attention arrives as runtime events, not here. Pass that account\'s own token file.',
+    );
+  }
+  return token;
+};
+
+/** `--since` / a cursor file holds an ISO-8601 timestamp; null means "everything". */
+export const parseCursor = (value) => {
+  const text = value === undefined || value === null ? '' : String(value).trim();
+  if (!text) return null;
+  // Two accepted shapes. The JSON object is what `list` writes (a timestamp plus
+  // the ids delivered at it); a bare ISO timestamp is what an operator copies off
+  // the `cursor:` line, and what older versions wrote — it parses with an empty id
+  // set, so the boundary items re-print instead of disappearing.
+  let at = text;
+  let ids = [];
+  let kind = null;
+  if (text.startsWith('{')) {
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new InboxRefusal(`Not a cursor: ${text}`);
+    }
+    at = parsed?.at;
+    ids = Array.isArray(parsed?.ids) ? parsed.ids.filter((id) => typeof id === 'string' && id) : [];
+    // Which kind filter the read that wrote this cursor used, so the next read
+    // can tell whether it is asking the same question — see the rule at the top
+    // of this file. Absent on a bare timestamp and on a file written by an
+    // unfiltered read, which is the direction that cannot lose a row.
+    kind = typeof parsed?.kind === 'string' && parsed.kind ? parsed.kind : null;
+  }
+  const ms = Date.parse(String(at));
+  if (!Number.isFinite(ms)) {
+    throw new InboxRefusal(`Not an ISO-8601 timestamp: ${at}`);
+  }
+  return {
+    at: new Date(ms).toISOString(), ms, ids, kind,
+  };
+};
+
+/** A missing cursor file is "nothing seen yet", not an error. */
+export const readCursorFile = (filePath) => {
+  if (!filePath) return null;
+  try {
+    return readFileSync(filePath, 'utf8').trim() || null;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw new InboxRefusal(`Cannot read the cursor file ${filePath} (${err?.code || err?.message}).`);
+  }
+};
+
+/** The cursor as it goes on disk: `{"at":"<iso>","ids":[...]}` on one line. */
+export const formatCursor = (cursor) => {
+  if (!cursor) return null;
+  if (typeof cursor === 'string') return cursor;
+  const at = cursor.at || (Number.isFinite(cursor.ms) ? new Date(cursor.ms).toISOString() : null);
+  if (!at) return null;
+  const ids = Array.isArray(cursor.ids) ? cursor.ids : [];
+  // `kind` is written only when the read was scoped to one, so an unfiltered
+  // cursor keeps the exact shape it had before and neither gains nor loses
+  // meaning.
+  return JSON.stringify(cursor.kind ? { at, ids, kind: cursor.kind } : { at, ids });
+};
+
+/**
+ * Written temp-then-rename so a watcher reading this file mid-write sees either
+ * the previous cursor or the new one, never a half line. A failed write must not
+ * fail the run whose items were already printed, so the caller decides.
+ */
+export const writeCursorFile = (filePath, cursor) => {
+  const text = formatCursor(cursor);
+  if (!filePath || !text) return;
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, `${text}\n`, 'utf8');
+  renameSync(tmp, filePath);
+};
+
+export const itemCreatedAtMs = (item) => {
+  const ms = Date.parse(String(item?.createdAt ?? ''));
+  return Number.isFinite(ms) ? ms : null;
+};
+
+/** The identity an item is remembered by between runs: the id `ack` consumes. */
+export const cursorKeyOf = (item) => String(item?.attentionItemId || item?.id || '');
+
+/**
+ * An item with an unparseable `createdAt` is KEPT under a cursor: dropping it
+ * would lose the row silently, and re-printing is the recoverable error. The same
+ * argument decides the millisecond boundary — see the module header.
+ */
+export const filterItems = (items, { kind = null, sinceMs = null, seenIds = [] } = {}) => {
+  const delivered = seenIds instanceof Set ? seenIds : new Set(seenIds);
+  return (items || []).filter((item) => {
+    if (kind && item?.kind !== kind) return false;
+    if (sinceMs === null) return true;
+    const ms = itemCreatedAtMs(item);
+    if (ms === null) return true;
+    if (ms > sinceMs) return true;
+    return ms === sinceMs && !delivered.has(cursorKeyOf(item));
+  });
+};
+
+/**
+ * Newest timestamp delivered, so the next call resumes exactly where this one
+ * ended — plus the ids delivered AT that timestamp, which are what make the
+ * boundary safe to resume from. Those ids are carried forward only while the
+ * timestamp stays put; once it moves, they can never match again (the check needs
+ * `ms === sinceMs`) and carrying them would grow the file for nothing.
+ */
+export const nextCursorFrom = (items, fallback = null, kind = null) => {
+  let max = null;
+  for (const item of items || []) {
+    const ms = itemCreatedAtMs(item);
+    if (ms === null) continue;
+    if (max === null || ms > max) max = ms;
+  }
+  if (max === null) return fallback;
+  const at = new Date(max).toISOString();
+  const boundary = (items || []).filter((item) => itemCreatedAtMs(item) === max)
+    .map(cursorKeyOf).filter(Boolean);
+  const carried = fallback && fallback.ms === max ? (fallback.ids || []) : [];
+  // The kind is the CURRENT read's, never inherited: the cursor describes the
+  // query that just ran, and a mismatch with the file's own kind is what the
+  // command refuses on before it makes a request.
+  return {
+    at, ms: max, ids: [...new Set([...carried, ...boundary])], kind: kind || null,
+  };
+};
+
+const oneLine = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+export const formatItemLine = (item) => {
+  const id = String(item?.attentionItemId || item?.id || '?');
+  const source = String(item?.id || '');
+  const sourceLabel = source && source !== id ? ` source=${source}` : '';
+  const detail = oneLine(item?.title || item?.detail || '').slice(0, DETAIL_CHARS);
+  const pod = oneLine(item?.podName || item?.podId || '');
+  const actor = item?.actorName ? ` — ${oneLine(item.actorName)}` : '';
+  return `${String(item?.kind || '?').padEnd(8)} item=${id}${sourceLabel} [${pod}] ${detail}${actor}`;
+};
+
+export const countsLine = (countsByKind = {}) => {
+  const parts = Object.entries(countsByKind)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([kind, count]) => `${kind} ${count}`);
+  return parts.join(', ');
+};
+
+/**
+ * Never echo the token back, whatever the server decides to say — but only when
+ * there is something distinctive to remove. A needle that short shreds the
+ * message it is meant to clean: with a one-character token, "Attention item not
+ * found" loses every `t` and reads as a different error. Real tokens are JWTs or
+ * `cm_*` strings, so the floor is far below anything real and still above any
+ * string that could appear inside an ordinary sentence.
+ */
+export const MIN_SCRUB_CHARS = 16;
+
+export const createScrubber = (token) => {
+  const needle = typeof token === 'string' && token.length >= MIN_SCRUB_CHARS ? token : '';
+  return (value) => {
+    const text = String(value ?? '');
+    return needle ? text.split(needle).join('[redacted]') : text;
+  };
+};
+
+/**
+ * The `/api/activity` limiter answers 429 with `{code:'rate_limited'}` and
+ * `Retry-After` (it sets `standardHeaders`). A read that pages a 550-item queue
+ * is 11 requests against a limit of **60 a minute keyed on the caller's IP**
+ * (`backend/routes/activity.ts:43-53`) — shared by every session on one host,
+ * including the operator's browser — so a 429 is an ordinary busy signal here,
+ * not a fault. Back off and continue; fail only when the budget is still gone
+ * after the retries.
+ */
+export const MAX_RATE_LIMIT_RETRIES = 2;
+export const DEFAULT_BACKOFF_MS = 5_000;
+export const MAX_BACKOFF_MS = 60_000;
+
+export const retryDelayMs = (response, fallback = DEFAULT_BACKOFF_MS) => {
+  const header = Number(response?.headers?.get?.('retry-after'));
+  if (Number.isFinite(header) && header > 0) return Math.min(header * 1_000, MAX_BACKOFF_MS);
+  return fallback;
+};
+
+/**
+ * Minimal request layer, deliberately NOT `lib/api.js`'s `createClient`.
+ * That client answers a 401 with "run `commonly login`", which is the one
+ * instruction this command must never give: the token here comes from a file
+ * that `login` does not write. `fetchImpl` is injectable so the identity rule
+ * is testable without a server.
+ */
+export const createInboxRequest = ({
+  baseUrl, token, tokenFile, fetchImpl = fetch, sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+}) => {
+  const scrub = createScrubber(token);
+  return async (path, { method = 'GET', params = {}, body } = {}) => {
+    const url = new URL(`${baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+    for (let attempt = 0; ; attempt += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      const res = await fetchImpl(url.toString(), {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+          'User-Agent': 'commonly-cli/0.1',
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+      // eslint-disable-next-line no-await-in-loop
+      const text = await res.text();
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = { message: text };
+      }
+      if (res.ok) return parsed;
+      if (res.status === 429 && attempt < MAX_RATE_LIMIT_RETRIES) {
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(retryDelayMs(res));
+        continue;
+      }
+      const detail = parsed?.error || parsed?.message || parsed?.msg || parsed?.code || `HTTP ${res.status}`;
+      const hint = res.status === 401
+        ? ` — the token in ${tokenFile} was rejected. This command never uses the saved login.`
+        : res.status === 429
+          ? ' — the /api/activity rate limit (60 a minute, keyed on the caller IP, so every session on this host shares it). Wait and retry; one page per 50 items is already the minimum this read can make.'
+          : '';
+      throw new InboxRequestError(scrub(`${detail}${hint}`), res.status);
+    }
+  };
+};
+
+/**
+ * Page the queue through `hasMore`. Two independent stops, because a server
+ * that reports `hasMore: true` beside an empty page would otherwise spin
+ * forever, and one that lies about `count` would page past the end.
+ */
+export const fetchQueue = async (request, { podId } = {}) => {
+  const items = [];
+  let meta = {};
+  let offset = 0;
+  for (;;) {
+    // eslint-disable-next-line no-await-in-loop
+    const page = await request('/api/activity/decision-queue', {
+      params: { limit: API_PAGE_LIMIT, offset, ...(podId ? { podId } : {}) },
+    });
+    const batch = Array.isArray(page?.items) ? page.items : [];
+    items.push(...batch);
+    meta = page || {};
+    if (!meta.hasMore) break;
+    if (batch.length === 0) break;
+    if (Number.isInteger(meta.count) && items.length >= meta.count) break;
+    offset += batch.length;
+  }
+  return { items, meta };
+};
+
+export const resolveAccountLabel = (user) => String(
+  user?.username || user?.email || user?._id || 'unknown',
+);
+
+export const formatAccountLine = ({ account, baseUrl }) => `account: ${account} @ ${baseUrl}`;

package/src/lib/mcp-home.js

@@ -27,6 +27,15 @@
  * operator saying which build to run, and the npx cache already gives a pinned
  * spec its own dir.
  *
+ * The cold path is pinned too (TASK-174's second half). A spawn with no usable
+ * home still runs the declaration, but not with the shared `@latest` spec: the
+ * spec this spawn executes is the version the registry already answered with,
+ * read from the warm's own cache, so `@latest`'s one shared npx dir is not on
+ * the spawn path even once. The fallback is the declaration as written, and it
+ * is used exactly when nothing has ever resolved a version on this host — a
+ * fresh machine's first spawn, where `@latest` is also the only spec that could
+ * work — or when the cache is unreadable. Nothing here throws.
+ *
  * Every filesystem answer here is injected, because the two states that matter
  * (a home that has never been warmed, and a home whose pointed-at version dir was
  * deleted under it) cannot both be produced on one host.
@@ -39,7 +48,7 @@ import { homedir } from 'node:os';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
-import { MCP_PACKAGE, parseVersion } from './mcp-server-version.js';
+import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
 
 /** The env override, so tests (and an operator) can point the home elsewhere. */
 export const MCP_HOME_ENV = 'COMMONLY_MCP_HOME';
@@ -113,8 +122,34 @@ export const isUsableWarmHome = (home) => (
 export const resolveHomeDir = (home) => (isUsableWarmHome(home) ? home : mcpHomeDir());
 
 export const currentPointerPath = (home) => join(home, 'current');
-export const versionDirFor = (home, version) => join(home, version);
-export const packageDirFor = (home, version) => join(home, version, 'node_modules', MCP_PACKAGE);
+
+/**
+ * Where a version dir name that is not a triple lands: inside the home, and
+ * never a version (a version starts with a digit), so every read of it misses
+ * and the spawn falls back to its declaration. The alternative — building the
+ * path from whatever string arrived — is how `0.3.13/../../../../tmp/x` resolved
+ * outside the home, and #1970's `startsWith(pkgDir)` confinement is computed
+ * FROM that dir, so it would have confined to the wrong place (Vera, 74938).
+ */
+const UNUSABLE_VERSION_DIR = '.unusable-version';
+
+/**
+ * A version dir, built from the parsed triple — and only when the string given
+ * IS that triple.
+ *
+ * Refusing beats rebuilding here: this result is what the warm RENAMES into and
+ * what the pruner REMOVES, so silently rewriting `0.3.14-rc.1` to `0.3.14` would
+ * aim both at a different build. Normalising belongs at the producer of a
+ * version value (`resolveRegistryLatest`, `readCurrentVersion`,
+ * `readRegistryCache`, `pinShippedSpec`), where the choice is deliberate and
+ * visible; a producer that names something else gets a name no version can have.
+ */
+export const versionDirFor = (home, version) => {
+  const triple = exactVersion(version);
+  const name = triple && triple === String(version).trim() ? triple : UNUSABLE_VERSION_DIR;
+  return join(home, name);
+};
+export const packageDirFor = (home, version) => join(versionDirFor(home, version), 'node_modules', MCP_PACKAGE);
 export const lockPathFor = (home) => join(home, WARM_LOCK_NAME);
 
 /** `<home>/<version>/.inuse/` — one empty file per claiming pid. */
@@ -236,8 +271,8 @@ const defaultExists = (path) => {
 export const readCurrentVersion = (home, { readFile = defaultRead } = {}) => {
   const raw = readFile(currentPointerPath(home));
   if (typeof raw !== 'string') return null;
-  const version = raw.trim();
-  return parseVersion(version) ? version : null;
+  const version = exactVersion(raw.trim());
+  return version || null;
 };
 
 /**
@@ -282,6 +317,9 @@ const readBinInPackageDir = (pkgDir, {
 
 /** The bin of a version dir inside the seat's home. */
 export const readBinPath = (home, version, options = {}) => {
+  // Truthiness of `parseVersion` is truthiness of `exactVersion`; the check that
+  // matters here is `versionDirFor` refusing a name that is not a triple, so a
+  // reader naming `0.3.14-rc.1` gets nothing rather than 0.3.14's build.
   if (!parseVersion(version)) return null;
   return readBinInPackageDir(packageDirFor(home, version), options);
 };
@@ -317,7 +355,10 @@ export const newestInstalledVersion = (home, {
   readBin = (h, v) => readBinPath(h, v),
 } = {}) => {
   const versions = readDir(home)
-    .filter((name) => parseVersion(name))
+    // An exact triple, not a prefix match: a dir literally named `0.3.13-rc.1`
+    // is not `0.3.13`, and normalising the name would point this read at a dir
+    // the caller never mentioned.
+    .filter((name) => exactVersion(name) === name)
     .filter((name) => readBin(home, name))
     .sort((a, b) => {
       const [am, an, ap] = parseVersion(a);
@@ -332,6 +373,39 @@ const isUnpinnedShippedSpec = (spec) => (
   spec === MCP_PACKAGE || spec === `${MCP_PACKAGE}@latest`
 );
 
+/**
+ * The shipped command with its spec pinned to `version`, or the command
+ * unchanged when there is no version to pin to.
+ *
+ * Only slot 2 is touched, and only after `isShippedCommonlyMcpCommand` has
+ * proven the slot is the package spec — so `npx`, its `-y` and every other
+ * entry survive byte-for-byte, and a command that is not the shipped 3-arg form
+ * cannot be rewritten by construction. npx keys its cache dir by the spec
+ * string, which is the whole point: `@latest` is one dir every seat shares and a
+ * publish rewrites in place, while `@0.3.13` is a dir only this version ever
+ * uses.
+ */
+export const pinShippedSpec = (command, version) => {
+  // The triple, not the string: this spec is an argv entry we execute, so a
+  // version carrying a suffix must not reach it.
+  const safe = exactVersion(version);
+  if (!Array.isArray(command) || !safe) return command;
+  let changed = false;
+  const pinned = command.map((part, index) => {
+    // Slot 2 only. `isShippedCommonlyMcpCommand` already proves the package sits
+    // in slot 2 of a 3-arg command, so this bound is not reachable today — it is
+    // here so the function is safe to read on its own, and it is armed in the
+    // tests rather than argued from the shape check (Vera, 74940).
+    if (index !== 2 || !isUnpinnedShippedSpec(String(part))) return part;
+    changed = true;
+    return `${MCP_PACKAGE}@${safe}`;
+  });
+  // The same reference when nothing changed, so a caller can use identity as the
+  // "did this spawn's spec move" check — the convention the rest of this module
+  // already keeps (`ensureCommonlyMcpServer`, `withholdGrantBroker`).
+  return changed ? pinned : command;
+};
+
 /**
  * What a spawn should execute, and where that decision came from.
  *
@@ -370,7 +444,23 @@ export const planMcpSpawn = (command, {
       };
     }
   }
-  return { command, source: 'declared', version: null, reason: 'home-empty' };
+  // No usable home, so the declaration is what runs — and the one thing worth
+  // changing about it is the spec string. The cached registry answer is used
+  // rather than a fresh lookup because this function is synchronous and on the
+  // spawn's critical path, and the warm refreshes that same cache on the same
+  // TTL (`REGISTRY_TTL_MS`). A stale-but-real version still gives this run its
+  // own npx dir, which `@latest` does not, and a stale cache means the registry
+  // has been answering nothing for a while — the case where `@latest` is least
+  // usable. `pinned` is reported so the caller can log which spec it ran.
+  const cached = readRegistryCache(target, { readFile });
+  const pinned = cached ? pinShippedSpec(command, cached.version) : command;
+  return {
+    command: pinned,
+    source: 'declared',
+    version: null,
+    reason: 'home-empty',
+    pinned: cached ? cached.version : null,
+  };
 };
 
 /** The warm's cached registry answer, with its age. */
@@ -379,9 +469,9 @@ export const readRegistryCache = (home, { readFile = defaultRead } = {}) => {
   if (typeof raw !== 'string') return null;
   try {
     const parsed = JSON.parse(raw);
-    const version = parsed && typeof parsed.version === 'string' ? parsed.version : null;
+    const version = exactVersion(parsed && parsed.version);
     const checkedAt = parsed && Number.isFinite(parsed.checkedAt) ? parsed.checkedAt : null;
-    if (!parseVersion(version) || checkedAt === null) return null;
+    if (!version || checkedAt === null) return null;
     return { version, checkedAt };
   } catch {
     return null;

package/src/lib/mcp-server-version.js

@@ -23,6 +23,28 @@ export const parseVersion = (spec) => {
   return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
 };
 
+/**
+ * The version as a bare triple — or null when there is none to build.
+ *
+ * `parseVersion` is a PREFIX test, which is right for ordering two versions and
+ * wrong for building anything out of one: it accepts `0.3.13/../../../../tmp/x`,
+ * so a version read out of a file (`~/.commonly/mcp/.registry.json`, the
+ * `current` pointer) or out of `npm view` could become a path or an npm SPEC
+ * ARGUMENT that leaves the seat's home. Everything that turns a version into a
+ * STRING used outside this module's own comparisons goes through here instead,
+ * and the string it builds is the parsed triple, so no suffix can travel.
+ *
+ * The cost is deliberate and one-directional: a prerelease (`0.3.13-rc.1`)
+ * becomes `0.3.13` rather than falling back to `@latest` — the stable release of
+ * the same triple, which is a real published version, and strictly better than
+ * the shared `@latest` dir this whole change exists to get off. Anchoring the
+ * regex at the end instead would reject the prerelease and leave it unpinned.
+ */
+export const exactVersion = (spec) => {
+  const triple = parseVersion(spec);
+  return triple ? triple.join('.') : null;
+};
+
 /**
  * True when `version` is older than `target`; null when there is no version to
  * judge (an unpinned `@latest` tracks the published release, so it is never

package/src/lib/mcp-warm-child.mjs

@@ -34,7 +34,7 @@ import {
   WARM_RESULTS, currentPointerPath, isUsableWarmHome, liveInUsePids, lockPathFor,
   readBinInPrefix, versionDirFor,
 } from './mcp-home.js';
-import { MCP_PACKAGE, parseVersion } from './mcp-server-version.js';
+import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
 
 export const PROBE_API_URL_PLACEHOLDER = 'http://127.0.0.1:1';
 export const PROBE_TOKEN_PLACEHOLDER = 'cm_agent_warm_probe';
@@ -147,9 +147,9 @@ export const resolveRegistryLatest = async (home, {
   if (cached) {
     try {
       const parsed = JSON.parse(cached);
-      if (parsed && Number.isFinite(parsed.checkedAt) && now - parsed.checkedAt < ttlMs
-        && parseVersion(parsed.version)) {
-        return { version: parsed.version, source: 'cache' };
+      const cachedVersion = parsed ? exactVersion(parsed.version) : null;
+      if (cachedVersion && Number.isFinite(parsed.checkedAt) && now - parsed.checkedAt < ttlMs) {
+        return { version: cachedVersion, source: 'cache' };
       }
     } catch { /* unreadable cache is just a miss */ }
   }
@@ -164,18 +164,24 @@ export const resolveRegistryLatest = async (home, {
       version = raw.replace(/^"|"$/g, '');
     }
   }
-  if (version && parseVersion(version)) {
+  // This answer is both persisted and, downstream, an argv entry
+  // (`npm install <pkg>@<version>`) and a path (`<home>/<version>`, the temp
+  // prefix). Rebuild it as a triple here, at the one place it enters, so the
+  // rest of the warm can keep treating a version as a name.
+  const safe = exactVersion(version);
+  if (safe) {
     try {
-      writeFile(cachePath, JSON.stringify({ version, checkedAt: now }));
+      writeFile(cachePath, JSON.stringify({ version: safe, checkedAt: now }));
     } catch { /* a cache we cannot write is not a warm we should fail */ }
-    return { version, source: 'registry' };
+    return { version: safe, source: 'registry' };
   }
   // Registry down: the last known answer is better than none, and better than
   // moving the pointer backwards.
   if (cached) {
     try {
       const parsed = JSON.parse(cached);
-      if (parseVersion(parsed.version)) return { version: parsed.version, source: 'stale-cache' };
+      const stale = parsed ? exactVersion(parsed.version) : null;
+      if (stale) return { version: stale, source: 'stale-cache' };
     } catch { /* fall through */ }
   }
   return { version: null, source: 'unavailable' };
@@ -267,7 +273,10 @@ export const pruneVersionDirs = (home, current, {
   },
   livePids = (version) => liveInUsePids(home, version),
 } = {}) => {
-  const versions = readDir(home).filter((name) => parseVersion(name));
+  // Exact triples only, for the same reason `newestInstalledVersion` uses them:
+  // a dir named `0.3.13-rc.1` is not the dir `0.3.13`, and this loop REMOVES what
+  // it names.
+  const versions = readDir(home).filter((name) => exactVersion(name) === name);
   versions.sort((a, b) => {
     const [am, an, ap] = parseVersion(a);
     const [bm, bn, bp] = parseVersion(b);
@@ -309,8 +318,7 @@ export const warmMcpHome = async (home, {
   readCurrent = (h) => {
     const raw = readIfAny(currentPointerPath(h));
     if (typeof raw !== 'string') return null;
-    const trimmed = raw.trim();
-    return parseVersion(trimmed) ? trimmed : null;
+    return exactVersion(raw.trim()) || null;
   },
   keep = KEEP_VERSION_DIRS,
 } = {}) => {