@ravefox/space 0.0.0-stage → 0.2.0

package/src/lib/inbox.js

@@ -0,0 +1,483 @@
+/**
+ * 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';
+import { capTimeoutMs, formatLimit } from './api.js';
+
+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));
+    }
+    // TASK-338: the same hard timeout as every other CAP request (api.js).
+    const timeoutMs = capTimeoutMs(method === 'GET' ? 'read' : 'write');
+    for (let attempt = 0; ; attempt += 1) {
+      let res;
+      let text;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        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) }),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        // eslint-disable-next-line no-await-in-loop
+        text = await res.text();
+      } catch (err) {
+        if (err?.name !== 'TimeoutError') throw err;
+        throw new InboxRequestError(`${method} ${path} got no answer in ${formatLimit(timeoutMs)}`, null);
+      }
+      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}`;

package/src/lib/instance-proxy.js

@@ -0,0 +1,76 @@
+/**
+ * A per-spawn relay to one declared Commonly instance origin, on a Unix
+ * socket, or on an ephemeral loopback TCP port when no socketPath is given
+ * (for a Seatbelt run whose only network is loopback).
+ */
+import { createServer, request as httpRequest } from 'http';
+import { request as httpsRequest } from 'https';
+import { chmod, unlink } from 'fs/promises';
+
+export const startInstanceProxy = async ({ instanceUrl, socketPath }) => {
+  const target = new URL(instanceUrl);
+  if (!['http:', 'https:'].includes(target.protocol)
+    || target.username || target.password || target.search || target.hash
+    || target.pathname !== '/') {
+    throw new Error('Space instance proxy requires a bare http(s) origin');
+  }
+  const transport = target.protocol === 'https:' ? httpsRequest : httpRequest;
+  const upstreams = new Set();
+  const server = createServer((incoming, outgoing) => {
+    const path = incoming.url || '';
+    if (!path.startsWith('/') || path.startsWith('//')
+      || incoming.method === 'CONNECT' || incoming.headers.upgrade) {
+      incoming.resume();
+      outgoing.writeHead(400).end();
+      return;
+    }
+    const headers = { ...incoming.headers, host: target.host };
+    delete headers.connection;
+    delete headers['proxy-authorization'];
+    delete headers['proxy-connection'];
+    const upstream = transport(target, {
+      method: incoming.method,
+      path,
+      headers,
+    }, (response) => {
+      outgoing.writeHead(response.statusCode || 502, response.headers);
+      response.pipe(outgoing);
+      response.on('error', () => outgoing.destroy());
+      response.on('close', () => {
+        if (!response.complete) outgoing.destroy();
+      });
+    });
+    upstreams.add(upstream);
+    upstream.on('close', () => upstreams.delete(upstream));
+    outgoing.on('close', () => upstream.destroy());
+    upstream.on('error', () => {
+      if (outgoing.destroyed) return;
+      if (!outgoing.headersSent) outgoing.writeHead(502);
+      outgoing.end();
+    });
+    incoming.pipe(upstream);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    const listening = () => {
+      server.removeListener('error', reject);
+      resolve();
+    };
+    if (socketPath) server.listen(socketPath, listening);
+    else server.listen(0, '127.0.0.1', listening);
+  });
+  if (socketPath) await chmod(socketPath, 0o600);
+  const port = socketPath ? null : server.address().port;
+  return {
+    socketPath: socketPath || null,
+    port,
+    url: port ? `http://127.0.0.1:${port}` : null,
+    close: async () => {
+      const closed = new Promise((resolve) => server.close(resolve));
+      for (const upstream of upstreams) upstream.destroy();
+      server.closeAllConnections();
+      await closed;
+      if (socketPath) await unlink(socketPath).catch((err) => { if (err.code !== 'ENOENT') throw err; });
+    },
+  };
+};

package/src/lib/machine-host.js

@@ -0,0 +1,29 @@
+/**
+ * TASK-784 (D164): what the daemon's computer runs, as the server stores it.
+ * Metadata only: Node's platform and arch names, the OS release's leading
+ * number, and this CLI's version. Nothing here may name the machine or the
+ * person (no hostname, path or user name); the server drops anything else.
+ */
+import { release as osRelease } from 'os';
+import { installedCliVersion } from './update-check.js';
+
+/**
+ * The leading number of an OS release string: Windows "10.0.22631" is 10,
+ * a Darwin kernel "25.4.0" is 25, Linux "6.5.0-1025-azure" is 6.
+ */
+export const osReleaseMajor = (release) => {
+  const match = /^(\d{1,4})(?:\D|$)/.exec(String(release ?? ''));
+  return match ? Number(match[1]) : null;
+};
+
+export const machineHostReport = ({
+  platform = process.platform,
+  release = osRelease(),
+  arch = process.arch,
+  cliVersion = installedCliVersion(),
+} = {}) => ({
+  platform,
+  osMajor: osReleaseMajor(release),
+  arch,
+  cliVersion: cliVersion || null,
+});