@saadnvd1/agent-os 0.3.700 → 0.3.723

package/lib/peer/account.ts

@@ -19,6 +19,9 @@ import {
 } from "../connect/control-api";
 import { peerHostAllowed } from "./client";
 import { rawPublic } from "./keys";
+import { cleanMachineName } from "./name";
+import { reconcilePins, type AccountSays } from "./revoke";
+import { getSetting, putSetting } from "../settings-store";
 
 export interface AccountPeer {
   id: string;
@@ -37,9 +40,15 @@ export interface AccountView {
   /** When the list was last fetched, 0 if never. */
   fetchedAt: number;
   error: string | null;
+  /** Set when the service hasn't answered for a day: since when. */
+  uncheckedSince: number | null;
 }
 
 export const LIST_MAX_AGE_MS = 60_000;
+export const UNCHECKED_NOTICE_MS = 24 * 3_600_000;
+const OK_KEY = "peer.account_ok_at";
+// The last answer is written down at most this often (it survives restarts).
+const OK_SAVE_MS = 10 * 60_000;
 // Never more often than this, whoever asks.
 const MIN_GAP_MS = 5_000;
 
@@ -52,6 +61,8 @@ interface State {
   stale: boolean;
   error: string | null;
   inflight: Promise<void> | null;
+  okAt: number;
+  okSavedAt: number;
 }
 
 export type Fetcher = () => Promise<PeerList | null>;
@@ -70,6 +81,8 @@ const fresh = (): State => ({
   stale: false,
   error: null,
   inflight: null,
+  okAt: 0,
+  okSavedAt: 0,
 });
 
 const state = () => (g.__agentosPeerAccount ??= fresh());
@@ -97,6 +110,42 @@ export function rawFromSpki(pem: string): string | null {
   }
 }
 
+/** The service answered: links can be checked against it again. */
+export function noteAccountOk(now = Date.now()) {
+  const s = state();
+  s.okAt = now;
+  if (now - s.okSavedAt < OK_SAVE_MS) return;
+  s.okSavedAt = now;
+  try {
+    putSetting(OK_KEY, String(now));
+  } catch {
+    // Bookkeeping only.
+  }
+}
+
+/** When the service last answered; a first look starts the clock. */
+function lastOk(now: number): number {
+  const s = state();
+  if (s.okAt) return s.okAt;
+  let saved = NaN;
+  try {
+    saved = Number(getSetting(OK_KEY));
+  } catch {
+    // No database: count from now.
+  }
+  if (Number.isFinite(saved) && saved > 0) return (s.okAt = saved);
+  noteAccountOk(now);
+  return now;
+}
+
+function applyToPins(says: AccountSays) {
+  try {
+    reconcilePins(says);
+  } catch (err) {
+    console.error("peer revoke:", err);
+  }
+}
+
 function adopt(list: PeerList) {
   const s = state();
   const peers: AccountPeer[] = [];
@@ -107,7 +156,7 @@ function adopt(list: PeerList) {
     if (!signPub || !peerHostAllowed(m.hostname)) continue;
     peers.push({
       id: m.id,
-      name: m.name,
+      name: cleanMachineName(m.name),
       hostname: m.hostname,
       signPub,
       lastSeenAt: m.lastSeenAt,
@@ -120,6 +169,11 @@ function adopt(list: PeerList) {
   s.fetchedAt = Date.now();
   s.stale = false;
   s.error = null;
+  noteAccountOk(s.fetchedAt);
+  applyToPins({
+    linkMachines: s.entitlements?.linkMachines ?? null,
+    listed: new Map(peers.map((p) => [p.id, p.signPub])),
+  });
 }
 
 async function refresh(): Promise<void> {
@@ -161,15 +215,19 @@ export async function accountView(
       peers: [],
       fetchedAt: 0,
       error: null,
+      uncheckedSince: null,
     };
   const s = state();
   if (s.stale || Date.now() - s.fetchedAt > maxAgeMs) await refresh();
+  const now = Date.now();
+  const ok = lastOk(now);
   return {
     enrolled: true,
     entitlements: s.entitlements,
     peers: s.peers,
     fetchedAt: s.fetchedAt,
     error: s.error,
+    uncheckedSince: now - ok > UNCHECKED_NOTICE_MS ? ok : null,
   };
 }
 
@@ -187,12 +245,26 @@ export async function linkingAllowed(): Promise<boolean | null> {
   return entitlements ? entitlements.linkMachines : null;
 }
 
-/** What a heartbeat says: the plan now, and whether the list changed. */
+/**
+ * What a heartbeat says: the service is there, the plan now, and whether the
+ * list changed, which is fetched again at once so a machine removed from the
+ * account is suspended within a beat or so.
+ */
 export function noteHeartbeat(beat: Beat) {
   const s = state();
+  noteAccountOk();
+  const plan = beat.entitlements?.linkMachines;
+  const planChanged =
+    plan !== undefined && plan !== s.entitlements?.linkMachines;
   if (beat.entitlements) s.entitlements = beat.entitlements;
   if (beat.peersEtag && beat.peersEtag !== s.etag) {
     s.etag = beat.peersEtag;
     s.stale = true;
   }
+  // A downgrade suspends now. An upgrade waits for a fresh list, so a pin
+  // whose machine left the account meanwhile isn't resumed on the way.
+  if (planChanged && plan === false)
+    applyToPins({ linkMachines: false, listed: null });
+  else if (planChanged) s.stale = true;
+  if (s.stale && enrolled()) void refresh();
 }

package/lib/peer/allowlist.ts

@@ -67,7 +67,7 @@ export const PEER_ROUTES: readonly PeerRoute[] = [
   { method: "POST", pattern: "/api/peer/unlink" },
   { method: "GET", pattern: "/api/peer/ping" },
 
-  // The work registry's exchange (not built yet: 404 until it is).
+  // The work registry's exchange.
   { method: "POST", pattern: "/api/claims/exchange" },
 ];
 

package/lib/peer/client.ts

@@ -15,7 +15,8 @@ import {
   sealRequest,
 } from "./envelope";
 import { boxPublic, currentIdentity, signPublic, type Identity } from "./keys";
-import { notePinResult } from "./links";
+import { notePinResult, unlinkedByPeer } from "./links";
+import { UNLINKED_PROOF_HEADER, verifyUnlinked } from "./unlinked-proof";
 import type { HostLink } from "../hosts/remote-api";
 import { readCappedBytes } from "../hosts/read-capped-bytes";
 
@@ -67,12 +68,15 @@ export interface ClientDeps {
   identity: () => Identity | null;
   audit: (e: AuditEntry) => void;
   noteResult: (hostId: string, error: string | null) => void;
+  /** It proved it unlinked this machine: drop the pin here too. */
+  unlinked: (hostId: string, name: string) => void;
 }
 
 const realDeps: ClientDeps = {
   identity: () => currentIdentity(),
   audit: recordPeerCall,
   noteResult: notePinResult,
+  unlinked: unlinkedByPeer,
 };
 
 export async function peerCall(
@@ -155,6 +159,27 @@ export async function peerCall(
   }
   if (res.status !== 200) {
     const text = raw.subarray(0, 64).toString("utf8").trim();
+    if (
+      res.status === 403 &&
+      text === "unknown peer" &&
+      verifyUnlinked(
+        signPublic(peer.signPub),
+        {
+          from: peer.machineId,
+          to: identity.machineId,
+          nonce: sealed.nonce.toString("base64url"),
+        },
+        res.headers.get(UNLINKED_PROOF_HEADER)
+      )
+    ) {
+      audit("unknown_peer", 403, sealed.envelope.length);
+      deps.unlinked(link.hostId, link.hostName);
+      throw new PeerCallError(
+        `${link.hostName} unlinked this machine. Link it again in Machines.`,
+        true,
+        403
+      );
+    }
     const outcome = REFUSALS[text];
     if (outcome && res.status >= 400 && res.status < 500) {
       audit(outcome, res.status, sealed.envelope.length);

package/lib/peer/link-cli.ts

@@ -100,7 +100,9 @@ async function list(io: CliIo) {
     );
   for (const r of requests)
     io.out(
-      `\n${r.name} wants to link here: agent-os link accept <the code it shows>`
+      r.state === "accepted"
+        ? `\n${r.name} is linked here. To finish, type this code on ${r.name}: ${r.confirmCode ? showCode(r.confirmCode) : "(see the browser)"}`
+        : `\n${r.name} wants to link here: agent-os link accept <the code it shows>`
     );
   if (account.machines.some((m) => !m.linkState))
     io.out("\nLink one with: agent-os link <name>");
@@ -177,7 +179,12 @@ async function answer(io: CliIo, verb: "accept" | "decline", rest: string[]) {
     io,
     "/api/peers/pending"
   );
-  const req = pick(requests, from, (r) => r.machineId, "link request");
+  const req = pick(
+    requests.filter((r) => r.state !== "accepted"),
+    from,
+    (r) => r.machineId,
+    "link request"
+  );
   if (verb === "decline") {
     await call(io, `/api/peers/pending/${req.id}/decline`, { method: "POST" });
     io.out(`Declined ${req.name}.`);
@@ -210,10 +217,18 @@ async function unlink(io: CliIo, ref: string | undefined) {
     (h) => h.id,
     "linked machine"
   );
-  await call(io, `/api/hosts/${host.id}`, { method: "DELETE" });
+  const r = await call<{ told: boolean; removed: boolean }>(
+    io,
+    `/api/peers/${host.id}`,
+    { method: "DELETE" }
+  );
   io.out(
-    `Unlinked ${host.name} here. Remove this machine from its Machines too.`
+    r.told
+      ? `Unlinked ${host.name}, on both machines.`
+      : `Unlinked ${host.name} here. It couldn't be told now; its next call here is refused and it will show as unlinked.`
   );
+  if (!r.removed)
+    io.out(`It stays in Machines while it still has projects or sessions.`);
 }
 
 /** Runs one command; returns the exit code. */

package/lib/peer/links.ts

@@ -64,16 +64,18 @@ export const pinForHost = (hostId: string): PeerPin | null =>
 
 /** Pins a peer's keys to a Connect host. Pairing (S2) is the only caller. */
 export function savePin(pin: Omit<PeerPin, "state" | "suspendedReason">) {
-  getDb()
-    .prepare(
-      `INSERT INTO peer_links (host_id, machine_id, hostname, sign_pub, box_pub)
+  const db = getDb();
+  db.prepare(`DELETE FROM peer_unlinked WHERE machine_id = ?`).run(
+    pin.machineId
+  );
+  db.prepare(
+    `INSERT INTO peer_links (host_id, machine_id, hostname, sign_pub, box_pub)
        VALUES (?, ?, ?, ?, ?)
        ON CONFLICT(host_id) DO UPDATE SET machine_id = excluded.machine_id,
          hostname = excluded.hostname, sign_pub = excluded.sign_pub,
          box_pub = excluded.box_pub, state = 'active', suspended_reason = NULL,
          paired_at = datetime('now'), last_error = NULL`
-    )
-    .run(pin.hostId, pin.machineId, pin.hostname, pin.signPub, pin.boxPub);
+  ).run(pin.hostId, pin.machineId, pin.hostname, pin.signPub, pin.boxPub);
 }
 
 export function suspendPin(hostId: string, reason: string) {
@@ -84,6 +86,112 @@ export function suspendPin(hostId: string, reason: string) {
     .run(reason, hostId);
 }
 
+export function resumePin(hostId: string) {
+  getDb()
+    .prepare(
+      `UPDATE peer_links SET state = 'active', suspended_reason = NULL WHERE host_id = ?`
+    )
+    .run(hostId);
+}
+
+/** Every pin, for checking them against the account (revoke.ts). */
+export const allPins = (): PeerPin[] =>
+  (getDb().prepare(SELECT).all() as Row[]).map((r) => toPin(r)!);
+
+/** How long an unlinked machine is still answered "unknown peer", signed. */
+export const UNLINKED_KEEP_MS = 30 * 24 * 3_600_000;
+
+export interface Unlinked {
+  machineId: string;
+  hostId: string | null;
+  signPub: string;
+  /** The other machine unlinked it, rather than a person here. */
+  byPeer: boolean;
+  reason: string;
+  at: number;
+}
+
+interface UnlinkedRow {
+  machine_id: string;
+  host_id: string | null;
+  sign_pub: string;
+  by_peer: number;
+  reason: string;
+  at: number;
+}
+
+const toUnlinked = (r: UnlinkedRow | undefined): Unlinked | null =>
+  r
+    ? {
+        machineId: r.machine_id,
+        hostId: r.host_id,
+        signPub: r.sign_pub,
+        byPeer: r.by_peer === 1,
+        reason: r.reason,
+        at: r.at,
+      }
+    : null;
+
+/** A machine unlinked here within the last 30 days, by its Connect id. */
+export const unlinkedMachine = (
+  machineId: string,
+  now = Date.now()
+): Unlinked | null =>
+  toUnlinked(
+    getDb()
+      .prepare(`SELECT * FROM peer_unlinked WHERE machine_id = ? AND at > ?`)
+      .get(machineId, now - UNLINKED_KEEP_MS) as UnlinkedRow | undefined
+  );
+
+export const unlinkedHost = (hostId: string): Unlinked | null =>
+  toUnlinked(
+    getDb()
+      .prepare(
+        `SELECT * FROM peer_unlinked WHERE host_id = ? ORDER BY at DESC LIMIT 1`
+      )
+      .get(hostId) as UnlinkedRow | undefined
+  );
+
+export const hasRecentUnlinked = (now = Date.now()): boolean =>
+  getDb()
+    .prepare(`SELECT 1 FROM peer_unlinked WHERE at > ? LIMIT 1`)
+    .get(now - UNLINKED_KEEP_MS) !== undefined;
+
+/**
+ * Removes a pin, keeping its signing key as unlinked (see the migration).
+ * The host stays: it may still hold sessions, and it says who unlinked it.
+ */
+export function dropPin(
+  hostId: string,
+  o: { byPeer: boolean; reason: string },
+  now = Date.now()
+): PeerPin | null {
+  const pin = pinForHost(hostId);
+  if (!pin) return null;
+  const db = getDb();
+  db.transaction(() => {
+    db.prepare(`DELETE FROM peer_unlinked WHERE at <= ?`).run(
+      now - UNLINKED_KEEP_MS
+    );
+    db.prepare(
+      `INSERT INTO peer_unlinked (machine_id, host_id, sign_pub, by_peer, reason, at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(machine_id) DO UPDATE SET host_id = excluded.host_id,
+         sign_pub = excluded.sign_pub, by_peer = excluded.by_peer,
+         reason = excluded.reason, at = excluded.at`
+    ).run(
+      pin.machineId,
+      hostId,
+      pin.signPub,
+      o.byPeer ? 1 : 0,
+      o.reason.slice(0, 200),
+      now
+    );
+    db.prepare(`DELETE FROM peer_links WHERE host_id = ?`).run(hostId);
+  })();
+  return pin;
+}
+
 /** Last outcome of a call to that peer, for Machines. */
 export function notePinResult(hostId: string, error: string | null) {
   getDb()
@@ -94,3 +202,7 @@ export function notePinResult(hostId: string, error: string | null) {
     )
     .run(...(error ? [error.slice(0, 300), hostId] : [hostId]));
 }
+
+/** The other machine, `name`, unlinked this one: its signed call or refusal. */
+export const unlinkedByPeer = (hostId: string, name: string): boolean =>
+  dropPin(hostId, { byPeer: true, reason: `Unlinked by ${name}` }) !== null;

package/lib/peer/machines.ts

@@ -17,6 +17,7 @@ export interface AccountMachine {
   /** The Machines host it's linked as, when it is. */
   hostId: string | null;
   linkState: "active" | "suspended" | null;
+  suspendedReason: string | null;
 }
 
 export interface AccountMachines {
@@ -24,6 +25,8 @@ export interface AccountMachines {
   entitlements: Entitlements | null;
   fetchedAt: number;
   error: string | null;
+  /** Set when the service hasn't answered for a day: since when. */
+  uncheckedSince: number | null;
   machines: AccountMachine[];
 }
 
@@ -39,10 +42,16 @@ export async function accountMachines(
     (
       getDb()
         .prepare(
-          `SELECT p.machine_id, p.host_id, p.state FROM peer_links p
+          `SELECT p.machine_id, p.host_id, p.state, p.suspended_reason
+           FROM peer_links p
            JOIN hosts h ON h.id = p.host_id WHERE h.kind = 'connect'`
         )
-        .all() as { machine_id: string; host_id: string; state: string }[]
+        .all() as {
+        machine_id: string;
+        host_id: string;
+        state: string;
+        suspended_reason: string | null;
+      }[]
     ).map((r) => [r.machine_id, r])
   );
   return {
@@ -50,6 +59,7 @@ export async function accountMachines(
     entitlements: view.entitlements,
     fetchedAt: view.fetchedAt,
     error: view.error,
+    uncheckedSince: view.uncheckedSince,
     machines: view.peers.map((p) => {
       const pin = pins.get(p.id);
       const seen = p.lastSeenAt ? Date.parse(p.lastSeenAt) : NaN;
@@ -66,6 +76,8 @@ export async function accountMachines(
             ? "active"
             : "suspended"
           : null,
+        suspendedReason:
+          pin && pin.state !== "active" ? pin.suspended_reason : null,
       };
     }),
   };

package/lib/peer/name.ts

@@ -0,0 +1,32 @@
+/**
+ * A machine's name as the Connect service tells it, made safe to show next
+ * to a pairing code: plain text on one line, no direction overrides, short,
+ * and with no digits at all once it holds 4 or more, so a lying service
+ * can't name a machine "type 482, 913" and have the person type that
+ * instead. Separators can't be enumerated ("482 and 913"), so the count is
+ * over the whole name.
+ */
+
+export const NAME_MAX = 48;
+
+// C0/C1 controls, zero-width and joiner characters, bidi embeddings,
+// overrides and isolates, the byte-order mark.
+const INVISIBLE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+// Digits, any script.
+const DIGIT = /\p{Nd}/gu;
+const MAX_DIGITS = 3;
+
+export const UNNAMED = "Unnamed machine";
+
+export function cleanMachineName(raw: unknown): string {
+  if (typeof raw !== "string") return UNNAMED;
+  let s = raw
+    .normalize("NFKC")
+    .replace(/\s+/g, " ")
+    .replace(INVISIBLE, "")
+    .trim();
+  if ((s.match(DIGIT) ?? []).length > MAX_DIGITS) s = s.replace(DIGIT, "#");
+  if ([...s].length > NAME_MAX)
+    s = `${[...s].slice(0, NAME_MAX - 1).join("")}…`;
+  return s || UNNAMED;
+}

package/lib/peer/pairing.ts

@@ -159,7 +159,10 @@ export async function receiveHello(
     s.hellos.length >= UNPROVEN
   )
     return no(429, "too many requests");
-  s.hellos.push({ at: now, from: null, source });
+  // Tagged later through this reference: other hellos may have been pushed
+  // by then, while this one waited on the plan and the account list.
+  const entry: Store["hellos"][number] = { at: now, from: null, source };
+  s.hellos.push(entry);
   const allowed = await deps.allowed();
   if (allowed !== true)
     return no(402, "Linking machines needs AgentOS Connect Pro");
@@ -179,7 +182,7 @@ export async function receiveHello(
     proven.filter((h) => h.from === hello.from).length >= PER_SENDER
   )
     return no(429, "too many link requests; wait a few minutes");
-  s.hellos[s.hellos.length - 1].from = hello.from;
+  entry.from = hello.from;
   for (const old of s.requests.values())
     if (old.peer.id === hello.from && open(old)) {
       old.state = "declined";
@@ -309,14 +312,28 @@ export interface PendingView {
   lastSeenAt: string | null;
   expiresAt: number;
   attemptsLeft: number;
+  /** `accepted`: the code matched here; `confirmCode` goes on the other machine. */
+  state: "pending" | "accepted";
+  /** Only for a caller that could have accepted it (withCodes). */
+  confirmCode?: string;
 }
 
-/** Requests waiting for a person here to type the code. */
-export function pendingRequests(now = Date.now()): PendingView[] {
+/**
+ * Requests waiting for a person here to type the code, and accepted ones
+ * still within their 5 minutes, whose second code must survive a reload.
+ */
+export function pendingRequests(
+  now = Date.now(),
+  o: { withCodes?: boolean } = {}
+): PendingView[] {
   const s = store();
   sweep(s, now);
   return [...s.requests.values()]
-    .filter((r) => r.state === "pending")
+    .filter(
+      (r) =>
+        r.state === "pending" ||
+        (r.state === "accepted" && now - r.createdAt <= REQUEST_TTL_MS)
+    )
     .map((r) => ({
       id: r.id,
       machineId: r.peer.id,
@@ -324,6 +341,10 @@ export function pendingRequests(now = Date.now()): PendingView[] {
       lastSeenAt: r.peer.lastSeenAt,
       expiresAt: r.createdAt + REQUEST_TTL_MS,
       attemptsLeft: MAX_WRONG - r.wrong,
+      state: r.state === "accepted" ? "accepted" : "pending",
+      ...(o.withCodes &&
+        r.state === "accepted" &&
+        r.confirm && { confirmCode: r.confirm }),
     }));
 }
 
@@ -379,6 +400,14 @@ export async function acceptRequest(
       status: 402,
       error: "Linking machines needs AgentOS Connect Pro.",
     };
+  // It may have been declined, replaced, expired or accepted meanwhile.
+  sweep(s, deps.now());
+  if (r.state !== "pending" || s.requests.get(id) !== r)
+    return {
+      ok: false,
+      status: 404,
+      error: "That request has ended. Start again from the other machine.",
+    };
   let hostId: string;
   try {
     hostId = deps.pin({ ...r.peer, signPub: r.aSign, boxPub: r.aBox });

package/lib/peer/pin.ts

@@ -4,8 +4,9 @@
  * of a pin: a machine whose keys changed is unlinked first, by a person.
  */
 
-import { createConnectHost, listRemoteHosts } from "../hosts";
-import { pinForMachine, savePin } from "./links";
+import { createConnectHost, getHost, listRemoteHosts } from "../hosts";
+import { pinForMachine, savePin, unlinkedMachine } from "./links";
+import { cleanMachineName } from "./name";
 
 export interface Paired {
   id: string;
@@ -43,7 +44,13 @@ export function keysChanged(
 export function pinPeer(p: Paired): string {
   const pinned = pinForMachine(p.id);
   if (keysChanged(p.id, p)) throw new Error(KEY_CHANGED);
-  const hostId = pinned?.hostId ?? createConnectHost(freeName(p.name)).id;
+  // Linked again after an unlink: back on the host it had, if it's still here.
+  const was = unlinkedMachine(p.id)?.hostId;
+  const reuse = was && getHost(was)?.kind === "connect" ? was : null;
+  const hostId =
+    pinned?.hostId ??
+    reuse ??
+    createConnectHost(freeName(cleanMachineName(p.name))).id;
   savePin({
     hostId,
     machineId: p.id,

package/lib/peer/reasons.ts

@@ -0,0 +1,7 @@
+/** Why a Connect link is suspended (revoke.ts), shared with the UI. */
+
+import { CONNECT_SITE } from "../connect/view";
+
+export const REMOVED_FROM_ACCOUNT = "removed from your account";
+export const NEEDS_PRO = "Linking machines needs Pro";
+export const UPGRADE_URL = `${CONNECT_SITE}/settings/billing`;

package/lib/peer/revoke.ts

@@ -0,0 +1,75 @@
+/**
+ * Suspending links when the account says so, and lifting that when it says
+ * otherwise. A pin is never deleted here: a machine removed from the
+ * account by mistake comes back linked as soon as its key is listed again,
+ * with no new pairing. The account can only take trust away this way, never
+ * add it: a pin it didn't suspend is never touched, and a suspended pin is
+ * resumed only with the very key it was paired with.
+ */
+
+import { allPins, resumePin, suspendPin, type PeerPin } from "./links";
+import { NEEDS_PRO, REMOVED_FROM_ACCOUNT } from "./reasons";
+
+export { NEEDS_PRO, REMOVED_FROM_ACCOUNT };
+
+const OURS: ReadonlySet<string> = new Set([REMOVED_FROM_ACCOUNT, NEEDS_PRO]);
+
+export interface AccountSays {
+  /** The plan's answer; null when it hasn't said. */
+  linkMachines: boolean | null;
+  /** Each listed machine's signing key, or null when this isn't a fresh list. */
+  listed: Map<string, string> | null;
+}
+
+/** What this pin's state should be, or null to leave it as it is. */
+export function wanted(
+  pin: PeerPin,
+  says: AccountSays
+): { state: "active" } | { state: "suspended"; reason: string } | null {
+  if (pin.state === "suspended" && !OURS.has(pin.suspendedReason ?? ""))
+    return null;
+  if (says.linkMachines === false)
+    return { state: "suspended", reason: NEEDS_PRO };
+  const key = says.listed?.get(pin.machineId);
+  if (says.listed && key !== pin.signPub)
+    return { state: "suspended", reason: REMOVED_FROM_ACCOUNT };
+  if (pin.state === "active") return null;
+  const lifted =
+    pin.suspendedReason === NEEDS_PRO
+      ? says.linkMachines === true
+      : says.listed !== null && key === pin.signPub;
+  return lifted ? { state: "active" } : null;
+}
+
+export interface Changed {
+  hostId: string;
+  state: "active" | "suspended";
+  reason: string | null;
+}
+
+/** Applies what the account says to every pin; returns what changed. */
+export function reconcilePins(
+  says: AccountSays,
+  pins: PeerPin[] = allPins()
+): Changed[] {
+  const changed: Changed[] = [];
+  for (const pin of pins) {
+    const want = wanted(pin, says);
+    if (!want) continue;
+    if (want.state === "active") {
+      resumePin(pin.hostId);
+      changed.push({ hostId: pin.hostId, state: "active", reason: null });
+    } else if (
+      pin.state !== "suspended" ||
+      pin.suspendedReason !== want.reason
+    ) {
+      suspendPin(pin.hostId, want.reason);
+      changed.push({
+        hostId: pin.hostId,
+        state: "suspended",
+        reason: want.reason,
+      });
+    }
+  }
+  return changed;
+}