@commonlyai/cli 0.1.79 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.79",
+  "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}`;