@commonlyai/cli 0.1.79 → 0.1.81

package/package.json

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

package/src/commands/inbox.js

@@ -0,0 +1,292 @@
+/**
+ * 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,
+  parseWindowMs,
+  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);
+    // Validated here with --kind, for the same reason: a typo must not cost a
+    // request, and a caller who asked for a window must not silently get another.
+    const windowMs = parseWindowMs(opts.window);
+    // 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}.`,
+      );
+    }
+    // The window: W behind the cursor's own stamp, not at it. A row stamped before
+    // the cursor can commit after the read that wrote it, and it is that read's
+    // `since` — not the row — that made it invisible; a read starting W earlier
+    // sees it. The ids already delivered inside the window are what keep the
+    // re-read from printing the old rows again (see lib/inbox.js).
+    const sinceMs = cursorIn ? cursorIn.ms - windowMs : null;
+    const since = sinceMs === null ? null : new Date(sinceMs).toISOString();
+
+    const {
+      baseUrl, request, account,
+    } = await connect(opts, { env, fetchImpl, sleep });
+
+    const { items, meta } = await fetchQueue(request, { podId: opts.pod, since });
+    const selected = filterItems(items, {
+      kind,
+      sinceMs,
+      // Everything already delivered inside the window. An item of the same id in
+      // the response is a re-delivery, not news; an item that merely shares its
+      // instant with one is news, which is why this dedupes by id and not by time.
+      seenIds: cursorIn ? cursorIn.ids : [],
+    });
+    const cursor = nextCursorFrom(selected, cursorIn, kind, windowMs);
+
+    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 ? `(nothing new; the window since ${since} was re-read)` : '(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 list --cursor-file ~/.commonly/inbox/c.cursor --window 300  # widen the re-read to 5m
+  $ commonly inbox ack <attentionItemId>
+  $ commonly inbox choose <decisionId> 2
+
+Cost: with no cursor, \`list\` reads the WHOLE queue, one request per 50 items —
+550 open items is 11 requests. /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.
+
+With \`--cursor-file\`, the read instead asks for \`createdAt >= cursor - W\`
+(\`--window\`, default 60s), so a watcher tick is ONE request. W is the margin
+over write-commit latency plus the writer's clock offset — a row is stamped before
+its write commits, so resuming exactly at the cursor would lose it. Rows already
+delivered inside W are dropped by id, which is the re-delivery the window is for.
+The counts printed in the header still describe the whole open set; only the rows
+inside the window are printed.
+
+\`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('--window <seconds>', 'Re-read this far behind the cursor, dropping ids already delivered (default 60; 0 = exact cursor)')
+    .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,472 @@
+/**
+ * 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 INSIDE A WINDOW that ends at
+ * it, 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 window is what makes the cursor safe, and the ids are not decoration. A row
+ * is stamped from the WRITER's clock at the moment of the write and becomes
+ * visible only when that write commits, so a row can carry a stamp before the
+ * cursor and appear after the read that wrote it — and it is not late, it is
+ * simply invisible to a reader who resumes at the cursor. Starting a read W
+ * behind the cursor (`--window`, default 60s) makes that row visible on the next
+ * tick; the ids already delivered inside that window are then dropped, so the
+ * re-read prints only what the caller has not seen. A bare `ms > since` cursor
+ * loses such a row silently and forever — the one failure this queue (576 open
+ * items, none ever read) cannot afford, which is why the recoverable direction
+ * (re-printing, deduped by `attentionItemId`) is always the one taken here. A
+ * legacy plain-timestamp cursor parses with an EMPTY set, which degrades toward
+ * re-printing rather than skipping.
+ *
+ * The window is NOT a guess about clock skew alone: W must exceed the write's
+ * commit latency PLUS the writer's clock offset, and a caller that sets it to 0
+ * gets the exact-cursor behaviour (resume at the cursor, dedupe only the ids
+ * stamped with it). The ids are pruned to the window on every write, so the
+ * cursor file stays the size of one window of deliveries instead of growing.
+ *
+ * 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,
+  };
+};
+
+/**
+ * `--window <seconds>`: how far behind the cursor a read starts. The default is
+ * the spec's 60s — the margin over in-cluster write latency and clock offset —
+ * and 0 restores the exact-cursor behaviour. Refused rather than clamped: a
+ * negative or unreadable window would silently change which rows a read can see,
+ * and that is the failure this whole module is built to avoid.
+ */
+export const DEFAULT_WINDOW_MS = 60 * 1000;
+
+export const parseWindowMs = (value, fallback = DEFAULT_WINDOW_MS) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const seconds = Number(String(value).trim());
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new InboxRefusal(`--window must be a number of seconds >= 0, not ${value}.`);
+  }
+  return Math.round(seconds * 1000);
+};
+
+/** 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 boundary — see the module header.
+ *
+ * `seenIds` is the set delivered inside the window and is dropped BY ID, whatever
+ * the item's timestamp: the window exists to re-serve those rows to the server
+ * call, and the id is the only thing that can say "the caller already saw this
+ * one". `sinceMs` is the window's own start and is inclusive, matching the
+ * route's bound, so a row stamped exactly at it still prints.
+ */
+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 (delivered.has(cursorKeyOf(item))) return false;
+    if (sinceMs === null) return true;
+    const ms = itemCreatedAtMs(item);
+    if (ms === null) return true;
+    return ms >= sinceMs;
+  });
+};
+
+/**
+ * Newest timestamp this query has covered — the previous cursor's stamp or the
+ * newest item printed, whichever is later — so the next call resumes from W behind
+ * it, plus every id delivered at or after that window's start, which is what the
+ * next read's window will re-serve and must therefore not print twice.
+ *
+ * The max is taken over the PRINTED items, not the server's `nextSince`, because
+ * `--kind` is filtered on this side: the server's window may hold rows of other
+ * kinds that this read will never print, and advancing the cursor onto them would
+ * move the high-water mark past a row of THIS kind that a later page has not
+ * delivered yet. When nothing printed, the cursor stays where it was — the
+ * fallback — so a quiet tick does not move the mark at all.
+ *
+ * The set is recomputed from the window plus the ids the previous cursor had not
+ * yet aged out of it, and both halves are load-bearing: this read's items are
+ * post-dedupe, so a row it dropped is absent from them and would be forgotten
+ * without the carry. The prune is what bounds the file at one window of
+ * deliveries instead of a list of everything ever printed.
+ */
+export const nextCursorFrom = (items, fallback = null, kind = null, windowMs = DEFAULT_WINDOW_MS) => {
+  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;
+  // A high-water mark: the newest item printed, or the cursor that came in,
+  // whichever is later. A row printed from inside the window is older than the
+  // mark that delimited that window, and letting it drag the mark back would move
+  // the next read's `since` back with it — reopening ground this query has already
+  // covered and moving the prune cutoff that bounds the id set.
+  const mark = fallback && Number.isFinite(fallback.ms) && fallback.ms > max ? fallback.ms : max;
+  const at = new Date(mark).toISOString();
+  const cutoff = mark - windowMs;
+  const inWindow = (items || []).filter((item) => {
+    const ms = itemCreatedAtMs(item);
+    return ms !== null && ms >= cutoff;
+  }).map(cursorKeyOf).filter(Boolean);
+  // The ids from the previous cursor are NOT dead weight, and dropping them is a
+  // measurable bug: `items` is what this read SELECTED, so a row delivered last
+  // tick has already been filtered out of it, and the set built from `items` alone
+  // would forget it — then the read after that would print it again, and the
+  // dedupe would alternate every tick. They are carried only while the previous
+  // cursor's own stamp is still inside this window; past that the next read's
+  // `since` is later than every one of them, the server can never re-serve them,
+  // and keeping them would grow the file for nothing.
+  const carried = fallback && Number.isFinite(fallback.ms) && fallback.ms >= cutoff
+    ? (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: mark, ids: [...new Set([...carried, ...inWindow])], 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, since } = {}) => {
+  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 } : {}),
+        // Only sent when there is a cursor: a first read is asking for everything
+        // the account has, and a bound there would silently hide its older half.
+        ...(since ? { since } : {}),
+      },
+    });
+    const batch = Array.isArray(page?.items) ? page.items : [];
+    items.push(...batch);
+    meta = page || {};
+    if (!meta.hasMore) break;
+    if (batch.length === 0) break;
+    // A bounded call reports the WHOLE open set in `count` and the window in
+    // `windowCount`, so stopping on `count` would page past the window's end.
+    const reported = since && Number.isInteger(meta.windowCount) ? meta.windowCount : meta.count;
+    if (Number.isInteger(reported) && items.length >= reported) 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}`;