feat: machines are named <first>-<hostname>-<id>, and Integrations uses the window

Two things a board owes you, neither of which it was doing.

**A machine you can tell apart.** The portal sent the literal string "machine"
as the label for every registration, so the server's collision suffix did the
naming and a fleet came out as "machine", "machine · 2", "machine · 11" — names
that say nothing about whose machine it is or which one it is. The hostname was
being reported all along; it arrived at enrolment and was written to the record
and never used for anything a person reads.

Naming now happens where the facts are. Registration mints the uid and the
owner's first name and produces `sankara-pending-k3f9dq`; enrolment, which is
the one moment the hostname exists, rewrites it to
`sankara-sankaras-macbook-pro-k3f9dq`. Same uid on both sides, so a card that
gained a real name is recognisably the same card. The rules live in
shared/machine-name.mjs because the two ends of that handshake have to agree.

Machines that enrolled before any of this are the entire existing fleet, so
they are renamed the first time their owner loads the board — the only place
holding both the email and the recorded hostname. It is guarded three ways:
auto-generated names only, the caller's own rows only (the super admin sees
every account's), and only when the name would actually change.

A name a person typed is never touched, and renaming by hand opts a machine
out permanently.

**The right-hand third of the Integrations page.** `.mkt-page` set
`max-width: none` to opt out of the 1180px reading width, but `.adm-page--wide`
declares the same specificity later in the file and won outright, so a card
grid — the one layout here that genuinely wants the whole window — was capped
and left-aligned with a dead band beside it. Fixed with a compound selector.
Card chips now show the part of the name that differs, since every machine on
a board shares an owner prefix and a uid nobody reads.

install.sh takes TOKENHUD_HOST for a box whose real hostname is not the name
you think of it by, and says which name it is about to report.

Author: reddy-sh

amplify/functions/api/handler.ts

@@ -31,9 +31,12 @@
 // second copy of it into a secondary index, on every single heartbeat.
 
 import type { LambdaFunctionURLEvent, LambdaFunctionURLResult } from 'aws-lambda';
-import { randomUUID } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { gunzipSync, gzipSync } from 'node:zlib';
 
+import {
+    firstNameFrom, looksGenerated, machineName, shortUid,
+} from '../../../shared/machine-name.mjs';
 import { liveness, mergeEntries, profileOf } from '../../../shared/profile.mjs';
 import { cached, fail, json, preflight, type Cors } from './http';
 import { callerOf, type Caller } from './jwt';
@@ -92,6 +95,22 @@ function parseJson(
 const str = (v: unknown, max = 200) =>
   (typeof v === 'string' && v.length <= max ? v : '');
 
+/* A name nobody else on this board is using.
+ *
+ * The generated names carry six random characters precisely so this never
+ * fires, but a person renaming machines by hand can still collide, and the
+ * board's own rename endpoint refuses duplicates — so registration must not be
+ * able to create one behind its back. */
+function uniqueLabel(desired: string, taken: Set<string>): string {
+  if (!taken.has(desired)) return desired;
+  let n = 2;
+  while (taken.has(`${desired} · ${n}`)) n++;
+  return `${desired} · ${n}`;
+}
+
+/* Six characters of collision insurance, from the runtime's real CSPRNG. */
+const newUid = () => shortUid((n: number) => randomBytes(n));
+
 /* ── the public identity of an account ──────────────────────────────── */
 
 // The Cognito sub is an internal identifier and has no business appearing on a
@@ -173,13 +192,17 @@ async function register(
   const enrollTokenHash = str(req?.enrollTokenHash, 64);
   const pairingCode = str(req?.pairingCode, 7);
   const expiresAt = str(req?.enrollTokenExpiresAt, 40);
+  // The label is optional on purpose. At this point in the handshake nobody
+  // knows what this machine is called — the agent has not run yet — so a name
+  // supplied here can only be one a person typed. When they did not type one,
+  // this function names the machine itself and `claim` finishes the job once
+  // the agent reports its hostname.
   if (
-    !label ||
     !/^[0-9a-f]{64}$/.test(enrollTokenHash) ||
     !/^[A-Z2-9]{3}-[A-Z2-9]{3}$/.test(pairingCode) ||
     !Number.isFinite(Date.parse(expiresAt))
   ) {
-    return fail(400, 'a registration needs a label, a token hash, a pairing code and an expiry', cors);
+    return fail(400, 'a registration needs a token hash, a pairing code and an expiry', cors);
   }
   // A link that outlives the sitting it was minted in is a link somebody
   // pastes into a terminal a week later and cannot explain.
@@ -189,18 +212,30 @@ async function register(
   }
 
   const taken = new Set((await store.listMachines(caller.sub)).map((m) => m.label));
-  let name = label;
-  if (taken.has(name)) {
-    let n = 2;
-    while (taken.has(`${name} · ${n}`)) n++;
-    name = `${name} · ${n}`;
-  }
+
+  // `uid` and `ownerFirst` are minted here and never change, so the name this
+  // machine gets now and the name it gets when the agent enrols differ in
+  // exactly one part — the hostname. A card that gained a real name is
+  // recognisably the same card, which it would not be if the whole string
+  // were rebuilt from scratch.
+  const uid = newUid();
+  const ownerFirst = firstNameFrom(caller.email);
+  // A label a person typed is theirs and survives enrolment untouched. One
+  // that only looks generated — including the "machine · 11" shape this
+  // replaces — is treated as no label at all.
+  const chosen = label && !looksGenerated(label) ? label : '';
+  const labelAuto = !chosen;
+  const name = uniqueLabel(
+    chosen || machineName({ email: caller.email, uid, fallbackHost: 'pending' }),
+    taken,
+  );
 
   const id = randomUUID();
   const now = new Date().toISOString();
   await store.putMachine({
     pk: store.userPk(caller.sub), sk: store.machineSk(id),
     id, sub: caller.sub, label: name,
+    labelAuto, uid, ownerFirst,
     status: 'registered',
     pairingCode,
     enrollTokenHash,
@@ -247,9 +282,27 @@ async function claim(event: LambdaFunctionURLEvent): Promise<LambdaFunctionURLRe
   // One link binds to one machine; a retry from the same machine refreshes it.
   if (m.installId && m.installId !== installId) return fail(410, 'enrollment link already used');
 
+  // The hostname has just arrived, and this is the only moment it ever will —
+  // so this is where an auto-named machine stops being `sankara-pending-k3f9dq`
+  // and becomes `sankara-sankaras-macbook-pro-k3f9dq`. Rows written before
+  // this existed have no `labelAuto`, so their names are judged by shape,
+  // which is what rescues the "machine · 11" fleet on the next enrolment.
+  const auto = m.labelAuto ?? looksGenerated(m.label);
+  const uid = m.uid || newUid();
+  let label = m.label;
+  if (auto) {
+    const taken = new Set(
+      (await store.listMachines(m.sub)).filter((x) => x.id !== m.id).map((x) => x.label),
+    );
+    label = uniqueLabel(machineName({ first: m.ownerFirst, hostname: host, uid }), taken);
+  }
+
   await store.updateMachine(m.sub, m.id, {
     installId,
     hostname: host,
+    label,
+    labelAuto: auto,
+    uid,
     platform: str(req?.platform, 120),
     agentVersion: str(req?.agentVersion, 40),
     manifestDigest: str(req?.manifestDigest, 128),
@@ -407,13 +460,63 @@ function publicMachine(m: Record<string, any>) {
   };
 }
 
+/* Give a real name to machines that enrolled before names meant anything.
+ *
+ * The naming happens at registration and at enrolment, which does nothing for
+ * a machine that is already active — and the fleet this was written for is
+ * entirely already active, sitting on the board as "machine", "machine · 2",
+ * "machine · 11". Everything needed to fix them is here and nowhere else: the
+ * owner's email is on the caller, and the hostname was recorded when the agent
+ * enrolled. So the board renames them the first time their owner looks at it.
+ *
+ * Guarded three ways. Only auto-generated names are touched, so a name a
+ * person typed is never overwritten. Only the caller's own machines are
+ * touched, because the super admin sees every account's rows and must not
+ * stamp their own first name across all of them. And the write only happens
+ * when the name would actually change, so this costs nothing on every
+ * subsequent poll. */
+async function backfillNames(caller: Caller, rows: store.Machine[]): Promise<void> {
+  const mine = rows.filter((m) => m.sub === caller.sub);
+  const stale = mine.filter(
+    (m) => (m.labelAuto ?? looksGenerated(m.label)) && (m.hostname || m.label),
+  );
+  if (!stale.length) return;
+
+  const taken = new Set(mine.map((m) => m.label));
+  const first = firstNameFrom(caller.email);
+
+  for (const m of stale) {
+    const uid = m.uid || newUid();
+    // A machine that enrolled has a hostname; one still waiting to keeps the
+    // provisional shape until it does, rather than being named after nothing.
+    const desired = machineName({
+      first, hostname: m.hostname, uid, fallbackHost: m.hostname ? undefined : 'pending',
+    });
+    if (desired === m.label) continue;
+    taken.delete(m.label);
+    const label = uniqueLabel(desired, taken);
+    taken.add(label);
+    try {
+      await store.updateMachine(caller.sub, m.id, { label, labelAuto: true, uid, ownerFirst: first });
+      // The caller is about to be handed these rows, so update them in place
+      // rather than making the new name wait for the next poll.
+      m.label = label; m.labelAuto = true; m.uid = uid; m.ownerFirst = first;
+    } catch {
+      // A rename that loses a race is not worth failing a board render over —
+      // the next poll tries again.
+    }
+  }
+}
+
 async function overview(caller: Caller, event: LambdaFunctionURLEvent, cors: Cors) {
   const admin = isSuperAdmin(caller);
   const rows = admin
     ? await store.listAllMachines()
     : await store.listMachines(caller.sub);
   rows.sort((a, b) => ((a.createdAt ?? '') < (b.createdAt ?? '') ? 1 : -1));
 
+  await backfillNames(caller, rows);
+
   // `?live=0` asks for the rows without the readings — a much smaller answer,
   // and all the portal needs while it is only watching liveness.
   const wantLive = (event.queryStringParameters?.live ?? '1') !== '0';
@@ -479,7 +582,8 @@ async function machineAction(
     const taken = (await store.listMachines(ownerSub))
       .some((other) => other.id !== id && other.label === label);
     if (taken) return fail(409, 'another machine on this board already has that name', cors);
-    await store.updateMachine(ownerSub, id, { label });
+    // Naming a machine by hand opts it out of ever being renamed again.
+    await store.updateMachine(ownerSub, id, { label, labelAuto: false });
     return json(200, { ok: true, label }, cors);
   }
 

shared/machine-name.mjs

@@ -0,0 +1,141 @@
+/* How a machine gets its name.
+ *
+ * A board is only useful if you can tell one row from another, and the old
+ * default could not: the browser sent the literal string "machine" for every
+ * registration, so the server's collision suffix did the naming and a fleet
+ * came out as "machine", "machine · 2", "machine · 11". Those names say
+ * nothing about whose machine it is, which machine it is, or which of two
+ * identical laptops you are looking at.
+ *
+ * The shape is `<first>-<host>-<uid>`, and each part earns its place:
+ *
+ *   first  the owner's first name, from their sign-in email. On a shared or
+ *          team board this is the part that says whose laptop this is.
+ *   host   the machine's own hostname, slugged. This is the part a human
+ *          recognises — it is the same string they see in their shell prompt.
+ *   uid    six random characters. Two people really do own two machines both
+ *          called `mbp`, and a name that collides is a name that gets a " · 2"
+ *          bolted onto it, which is where this started.
+ *
+ * The pieces arrive at different times, which is the whole reason this module
+ * is shared rather than inlined. `first` and `uid` are known in the browser at
+ * registration; `host` is not known until the agent enrols and reports it. The
+ * name is therefore built twice — provisionally at registration, finally at
+ * enrolment — and both callers have to agree on the rules or the machine
+ * appears to rename itself for no reason.
+ */
+
+/* DynamoDB is happy with far more, but `str(req?.label, 120)` in the ingest
+   handler is the real ceiling and the rename endpoint enforces the same. */
+export const MAX_LABEL = 120;
+
+/* No vowels beyond `a`, no `0/O/1/I/L/U` — the same instinct as the pairing
+   alphabet. A name that gets read aloud over a desk should not turn on
+   whether that character was a one or an ell. */
+const UID_ALPHABET = 'abcdefghjkmnpqrstvwxyz23456789';
+const UID_LEN = 6;
+
+/* Lowercase, alphanumeric, single dashes, no leading or trailing dash. Applied
+   to every part so the joined name has exactly one kind of separator and the
+   whole thing survives a URL, a filename and a shell word unquoted. */
+function slug(s) {
+  return String(s ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/* The owner's first name, from the address they signed in with.
+ *
+ * `sankara.telukutla@gmail.com` and `sankara@reddy.sh` both give `sankara`.
+ * Plus-addressing is cut before the split so `sankara+work@…` does not become
+ * `sankara-work`. An address that yields nothing usable — a UUID alias, a
+ * digits-only local part — falls back rather than producing a name that is
+ * somehow worse than no name at all. */
+export function firstNameFrom(email, fallback = 'user') {
+  const local = String(email ?? '').split('@')[0].split('+')[0];
+  const first = slug(local).split('-').filter(Boolean)[0] ?? '';
+  // A purely numeric "first name" is an alias, not a person.
+  if (!first || /^[0-9]+$/.test(first)) return fallback;
+  return first;
+}
+
+/* The machine's own name, as a human would recognise it.
+ *
+ * Hostnames arrive dressed for a network, not for a list: `Sankaras-MacBook-
+ * Pro.local`, `web-01.prod.internal`. The first label is the part that
+ * identifies the machine and the rest identifies the network it happened to
+ * be on when it enrolled — which can change without the machine changing. */
+export function hostSlug(hostname, fallback = 'machine') {
+  const firstLabel = String(hostname ?? '').trim().split('.')[0];
+  return slug(firstLabel) || fallback;
+}
+
+/* Six characters of collision insurance.
+ *
+ * Takes an optional source of randomness so a caller with one already — the
+ * browser's crypto, the Lambda's — does not have to reach for Math.random,
+ * and so the tests can be deterministic. */
+export function shortUid(randomBytes) {
+  const bytes = randomBytes
+    ? randomBytes(UID_LEN)
+    : globalThis.crypto?.getRandomValues?.(new Uint8Array(UID_LEN));
+  if (!bytes) throw new Error('shortUid needs a source of randomness');
+  let out = '';
+  for (let i = 0; i < UID_LEN; i++) out += UID_ALPHABET[bytes[i] % UID_ALPHABET.length];
+  return out;
+}
+
+/* Assemble `<first>-<host>-<uid>`, within the length ceiling.
+ *
+ * When the whole thing is too long it is the host that gives way, never the
+ * uid: the uid is what makes the name unique, and a truncated uid is a name
+ * that can collide again. `first` is short by construction, so in practice
+ * this only ever bites a machine with a genuinely enormous hostname. */
+export function machineName({ email, first: given, hostname, uid, fallbackFirst, fallbackHost } = {}) {
+  // `first` wins over `email` because the two callers know different things.
+  // The browser and the register handler hold the signed-in address; the
+  // enrol handler does not — it is answering an agent, not a person — and
+  // reads back the first name that registration stamped on the machine.
+  const first = slug(given) || firstNameFrom(email, fallbackFirst ?? 'user');
+  const host = hostSlug(hostname, fallbackHost ?? 'machine');
+  const tail = uid ? `-${uid}` : '';
+  const room = MAX_LABEL - first.length - 1 - tail.length;
+  const clipped = host.length > room ? host.slice(0, Math.max(1, room)).replace(/-+$/, '') : host;
+  return `${first}-${clipped}${tail}`;
+}
+
+/* Is this name one we generated, rather than one a person typed?
+ *
+ * Only auto-generated names get rewritten when the hostname finally arrives.
+ * Somebody who took the trouble to call a machine "build box" should find it
+ * still called that after the agent enrols. The stored `labelAuto` flag is the
+ * authority; this is the fallback for rows written before the flag existed,
+ * including the "machine · 11" generation that prompted all of this. */
+export function looksGenerated(label) {
+  const s = String(label ?? '').trim();
+  if (!s) return true;
+  if (/^machine(\s·\s\d+)?$/.test(s)) return true;
+  return new RegExp(`^[a-z0-9]+-[a-z0-9-]+-[${UID_ALPHABET}]{${UID_LEN}}$`).test(s);
+}
+
+/* The part of a generated name that actually distinguishes one machine.
+ *
+ * Every machine on one board shares the same `<first>-` prefix and carries a
+ * uid that exists for the database's benefit rather than the reader's, so a
+ * list of them is a column of near-identical strings differing in the middle —
+ * the worst possible shape to scan. In a tight space, show the middle. The
+ * full name still belongs in a tooltip, and anywhere there is room for it.
+ *
+ * A name a person typed is returned untouched: they chose those words. */
+export function shortMachineName(label) {
+  const s = String(label ?? '').trim();
+  if (!looksGenerated(s)) return s;
+  const parts = s.split('-');
+  // <first>-<host…>-<uid>: drop the ends, keep everything between them.
+  if (parts.length >= 3) {
+    const middle = parts.slice(1, -1).join('-');
+    if (middle) return middle;
+  }
+  return s;
+}